BTCU Harness

Balanced Ternary Cognitive Unit Harness — 基于平衡三进制认知单元的智能体认知驾驭架构

什么是 BTCU Harness？

BTCU Harness 是一个以三态集合 {-1, 0, +1} 为最小认知基元，以 3^9 = 19683 离散认知空间为核心，面向大语言模型（LLM）与智能体（Agent）的认知驾驭架构。

它不替代大模型，而是作为大模型与 Agent 之间的结构化认知层，逐步实现从"高频调用大模型"到"内部认知自主"的演进。

核心特性

• 三态认知基元：阴(-1)、空(0)、阳(+1)，公理 -1+1=0
• 19683 状态空间：九维三元向量，每个状态有唯一整数编号
• 涌现式语义：不预设状态含义，全靠 Agent 实践积累
• 三阶段成长：school -> internalize -> graduate，成本从 C proportional to N_call 降至 C proportional to N_unknown
• NLP 自我层：Dilts 8 层身份模型作为认知吸引子
• 第三选择：二元冲突时生成 5 策略候选，四维评分
• 认知气候：极性趋势、探索阶段、气候区域、认知漂移
• 持久化：JSON 存储完整认知状态，支持 save/load 往返
• CLI 工具：命令行操作认知空间
• 性能优化：LRU 缓存、批量操作、邻域预计算

快速上手

安装

pip install btcu-harness

# 可选依赖
pip install btcu-harness[llm]    # OpenAI API 支持
pip install btcu-harness[mongo]  # MongoDB 存储
pip install btcu-harness[dev]    # 开发工具
pip install btcu-harness[all]    # 全部

5 分钟入门

from btcu_harness.agent import BTCUAgent
from btcu_harness.core.state import CognitiveState
from btcu_harness.llm.bridge import LLMBridge

# 1. 创建 LLM 桥接（callback 模式或 API 模式）
bridge = LLMBridge(callback=my_llm_function)
# 或：bridge = LLMBridge(api_key="sk-...", model="gpt-4o-mini")

# 2. 创建 Agent
agent = BTCUAgent(growth_stage="school")

# 3. 初始化项目（定义九维）
agent.init_project(
    domain="custom",
    dim_labels=[
        "技术深度", "用户体验", "创新性", "可维护性",
        "社区影响", "商业价值", "学习成长", "风险评估", "长期愿景",
    ],
    llm_bridge=bridge,
)

# 4. 设置使命（身份锚点）
agent.set_self_level(
    name="mission",
    description="Be a helpful cognitive companion",
    state=CognitiveState.from_values([1, 1, 1, 0, 1, 0, 1, -1, 1]),
    weight=1.0,
    stability=0.95,
)

# 5. 处理认知输入
response = agent.process("Should we focus on deep innovation?")
print(f"State: #{response.current_state.index}")
print(f"Self alignment: {response.self_alignment:.1%}")

# 6. 记录结果（触发自我强化）
agent.record_outcome(
    state=response.current_state,
    outcome_positive=True,
)

# 7. 保存认知状态
agent.save()

CLI 使用

# 初始化项目
btcu init --domain agent --mission "My AI assistant"

# 投影输入
btcu project "Should we prioritize innovation?"

# 查看状态
btcu status

# 发现认知节气
btcu seasons

# 生成气候报告
btcu climate

# 探索状态空间
btcu explore --index 9841
btcu explore --values "1,0,-1,1,0,0,-1,1,-1"

# 保存/加载
btcu save
btcu load

架构总览

btcu_harness/
|-- core/              # 核心层：Trit, CognitiveState, CognitiveSpace
|-- memory/            # 记忆层：ecology, trajectory, climate, state/transition memory
|-- mapping/           # 映射层：dimension_adapter, projector, pattern_learner
|-- decision/          # 决策层：pathfinder, third_choice
|-- self_layer/        # NLP 自我层：Dilts 8 层模型
|-- llm/               # LLM 协同层：bridge (OpenAI 兼容)
|-- storage/           # 持久化层：JSON (未来 MongoDB)
|-- agent.py           # 主 Agent：11 步认知流水线
|-- cli.py             # CLI 入口
|-- config.py          # 配置 (环境变量)
|-- performance.py     # 性能优化：LRU 缓存、批量操作
|-- logging_config.py  # 日志系统

认知流水线（11 步）

核心概念

三态基元

公理：-1 + 1 = 0（对立交互归空）

19683 状态空间

九维三元向量的全组合：3^9 = 19683 个离散状态，每个有唯一编号 0-19682。

三阶段成长

文档

测试

# 运行全部测试
pytest tests/ -v

# 带覆盖率
pytest tests/ --cov=btcu_harness --cov-report=term-missing

# 仅集成测试
pytest tests/test_integration.py -v

当前：96 项测试全部通过，覆盖：三态运算、状态编码、空间拓扑、记忆生态、决策路径、第三选择、认知气候、性能缓存、CLI、错误处理、端到端流水线。

配置

通过环境变量或 .env 文件配置：

# LLM
BTCU_LLM_API_BASE=https://api.openai.com/v1
BTCU_LLM_API_KEY=your-key-here
BTCU_LLM_MODEL=gpt-4o-mini

# MongoDB (未来)
BTCU_MONGO_URI=mongodb://localhost:27017
BTCU_MONGO_DB=btcu_harness

# 认知空间
BTCU_NUM_DIMENSIONS=9
BTCU_GROWTH_STAGE=school

许可证

MIT License

引用

@software{btcu_harness,
  title={BTCU Harness: Balanced Ternary Cognitive Unit Architecture},
  author={BTCU Harness Contributors},
  year={2026},
  url={https://github.com/q1z2q3-debug/btcu-harness}
}