2026-03-31

CyberBrain：给 Coding Agent 的个人工作台

Author：Cunxi Gong

本文对应仓库：ansatzX/CyberBrain。

CyberBrain 不是“万能 Agent”，而是一套可检查、可维护的个人 Coding Agent 配置：明确宿主边界、按需加载技能、把重复流程沉淀为可复用资产。

先说结论

Agent = Model + Harness + Context + Workflow。

模型决定能力上限；Harness 决定工具、上下文、权限和交互如何组织；工作流决定一次任务是否可重复、可验证、可收尾。实际使用中，最常见的问题不是“没有更多 Agent”，而是：

用错误的上下文窗口或输出上限，导致过早压缩或请求失败；
把所有长指令、参考资料和流程预先塞进上下文；
让外部 Agent 直接写主工作树，却没有隔离、审查和测试；
留下已废弃的插件、重复 symlink 或没有所有者的本地配置。

CyberBrain 的目标是减少这些摩擦，而不是把每一种 CLI 或每一个 prompt 都收入仓库。

当前架构

CyberBrain 现在有两个一等宿主：

OpenAI Codex：通过本地 marketplace 插件、Codex 原生 skill 和显式 agent-role installer 工作；
Pi：通过本地 cyberbrain-pi package 提供 extensions、providers、slash modes 和共享 skills。

两者共享同一份 skill 源文件，但不互相模拟运行时 API。换句话说，Codex 的工具、插件清单和 agent TOML 留在 Codex 边界内；Pi 的 package、extension 和 slash mode 留在 pi/ 边界内。

当前发布的插件只有三个：

插件	作用
`awesome-agent-select`	Codex agent roles，以及 review、QA、API 文档、性能和工具类协作提示
`tachikoma`	调用外部 Coding Agent CLI 的技能
`brain`	上下文边界、证据、责任链与工作流审计技能

旧的 mac-eco 和 notifications 插件已经删除；仓库不再维护 Claude Code 专属包装或路径假设。

Skill：渐进披露，而不是上下文垃圾场

一个 skill 是一个包含 SKILL.md 的目录，可以有脚本、参考资料和资产：

my-skill/
├── SKILL.md          # 入口：名称、触发条件和简明工作流
├── scripts/          # 可执行辅助脚本
├── references/       # 需要时才读取的深入资料
└── assets/           # 模板或其他资源

Pi 和 Codex 都可以先发现 skill 的名称和描述；完整 SKILL.md、reference 或脚本只在任务确实匹配时才需要进入上下文。这种渐进披露比把所有 SOP 都放进 system prompt 更节省 token，也更容易维护。

但 skill 不是专业知识的替代品。它只能把已知流程、边界和检查项写清楚；是否选择正确的问题、数据、工具和验收标准，仍由使用者负责。

Tachikoma：外部 CLI 的受控协作

Tachikoma 目前只保留六个外部 CLI skills：

codex
gemini-cli
opencode
qwen
github-copilot-cli
kimi-code

它的用途不是把多个模型包装成“自动正确”的投票器，而是让不同 CLI 在清晰的边界内完成分析、评审或实现。

推荐实践：

先明确任务和验收条件：例如只做架构分析、只做 code review，还是允许修改文件。
默认只读：外部 CLI 分析或评审时使用 plan/read-only 模式。
写入必须隔离：需要让外部 CLI 改代码时，先创建新的 git worktree，再在 worktree 中授予写权限。
保留证据：记录完整 stdout/stderr 和独立 summary；退出码为 0 不等于结论正确。
由人或主 Agent 验证：检查 diff、运行相关测试、审查安全风险后再合并。

多模型可以提供不同视角，但不能替代问题定义、约束判断或最终责任。

Brain：把“看起来能跑”与“可以相信”分开

brain 插件提供的是思考和状态管理框架，而不是额外模型：

whole-object-responsibility：从对象、状态、控制链、失败路径到责任人，避免只看局部步骤；
state-machine：为有意义的选择、删除、转换和完成声明留下证据；
think-before-you-calculate：在训练、优化、搜索或仿真前先定义科学问题和解释边界；
agentic-search、epistemic-systems-audit、codex-compatible：分别处理检索溯源、证据审计和 Codex 运行边界。

核心原则很简单：

没有对象、边界、证据和失败路径，就不要把一次命令成功表述成系统成功。

Context：看真实工作窗口，不迷信宣传数字

上下文窗口通常是输入和输出共享的总窗口，并非“可无限使用的输入 token 数”。Harness 还会预留 system prompt、工具调用和输出空间，并在接近阈值时压缩历史。

因此模型 catalog 的宣传值不能直接当成运行时事实。CyberBrain 的 AIHubMix 集成会对 Codex 权威注册表中有记录的 GPT 模型采用其工作上下文窗口（例如 GPT-5.6 系列为 272K），而不是盲信聚合服务给出的 1.05M 或 400K 元数据。Pi 会在实际请求时再按剩余空间动态收紧输出上限。

实际策略应是：

优先选择与你的任务、工具调用和成本结构相匹配的模型；
把长资料拆为可按需读取的 skill/reference；
在接近上下文阈值前总结并压缩，而不是等请求失败；
用真实 token usage、请求错误和任务质量评估设置，而不是只看 model card。

安装

Codex

mkdir -p ~/soft
git clone https://github.com/ansatzX/CyberBrain.git ~/soft/CyberBrain
codex plugin marketplace add ~/soft/CyberBrain

在 Codex 中打开 /plugins，切到 CyberBrain marketplace 并安装需要的插件。

awesome-agent-select 的 agent roles 需要显式安装：

cd ~/soft/CyberBrain
bash tools/awesome-agent-select-codex-agents.sh install
bash tools/awesome-agent-select-codex-agents.sh doctor

Pi

cd ~/soft/CyberBrain
bash tools/manage-pi.sh install
bash tools/manage-pi.sh doctor

Pi installer 注册本地 package，并迁移它明确识别的旧 CyberBrain 文件；不会管理 API key、认证、会话、goals、缓存、主题、默认模型或用户模型偏好。

更新仓库后：

cd ~/soft/CyberBrain
git pull
bash tools/manage-pi.sh update
bash tools/manage-pi.sh doctor

manage-pi.sh 不会自行执行 git pull。这是刻意的边界：代码更新和本机配置迁移应当由用户清楚地分别控制。

一个可持续的日常流程

用自然语言说明目标、范围、约束与验收标准；
只在任务匹配时加载对应 skill；
简单任务直接完成，复杂任务先设计计划和状态检查点；
外部 CLI 只读优先，写入放入独立 worktree；
用测试、diff 和运行日志验证结果；
删除过期的插件、symlink 和重复配置，让可用能力保持少而清晰。

“多多益善”适合工具箱，不适合默认上下文。真正节省成本、提高成功率的方法，不是堆更多 Agent，而是让每个模型、工具、skill 和工作流都拥有明确的职责、输入边界和验收方式。