Newshot agent-brain
不依赖特定笔记工具的第二大脑操作模型 + 多运行时代理配置/记忆版本管理。
agent-brain 是面向 AI 编码代理（Claude Code、OpenCode、Codex、Antigravity CLI）的个人操作模型。它为你提供：
- 一套第二大脑知识结构（日志、WIP、记忆、任务），该模型可构建在任意笔记文件夹之上——Obsidian 只是其中一种选择，并非必需。
- 受版本控制的运行时配置与记忆：你的 CLAUDE.md / AGENTS.md、记忆和运行时设置存放在由 git 跟踪的 brain 中，并通过符号链接接入各运行时（~/.claude、~/.config/opencode、…），因此你的代理配置和记忆可随你跨机器迁移。
- 由 brain skill 驱动的会话生命周期（每日笔记、会话笔记、整合）。
- 可选的 boyscout skill：工作时发现改进机会，然后将其转入明确的修复工作流或待办列表。
前置条件
- Python 3.x（运行时脚本仅使用标准库；完整受控测试门禁会使用 uv 安装其验证依赖）
- 至少安装一个受支持的代理运行时：Claude Code → ~/.claude/ OpenCode → ~/.config/opencode/ 共享代理目录 → ~/.agents/ Codex CLI → ~/.codex/（AGENTS.md 和 config.toml 持久化在私有 brain 的 _AGENTS/CODEX/ 下；brain skill 安装于 ~/.agents/skills/brain） Antigravity CLI → ~/.gemini/antigravity-cli/（仅 skill 集成）
- Claude Code → ~/.claude/
- OpenCode → ~/.config/opencode/
- 共享代理目录 → ~/.agents/
- Codex CLI → ~/.codex/（AGENTS.md 和 config.toml 持久化在私有 brain 的 _AGENTS/CODEX/ 下；brain skill 安装于 ~/.agents/skills/brain）
- Antigravity CLI → ~/.gemini/antigravity-cli/（仅 skill 集成）
安装
curl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh | bash
这会将 agent-brain 克隆到 ~/.local/share/agent-brain 并运行编排器，它会询问你的 brain 路径（Obsidian vault、笔记文件夹或新的空目录）。默认以 dry-run 模式运行。查看计划后，使用末尾打印的准确公开 apply 命令；它会保留所选的 brain、运行时过滤器和符号链接策略：
curl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh \
| bash -s -- --brain /path/to/brain --apply
如果 _COMMON 已存在
如果你的 brain 已经有一个指向不同模型的 _COMMON 符号链接（例如之前的设置），dry-run 会分别报告当前条目和期望的符号链接，包括损坏链接的原始目标。它还会检查由 home_setup 管理的每个模板符号链接，并报告过期目标。执行 --apply 时，安装器会将现有的 _COMMON 条目保留为 _COMMON.backup-<ts>，将 _COMMON 重新指向 agent-brain，并通过新的 _COMMON 重新链接过期的受管模板。常规模板文件保持不变。安装前创建的 Git 快照提供了额外的回滚锚点。
参数
| 参数 | 用途 |
|---|---|
| --brain <path> | brain 根路径（跳过交互式提示） |
| --apply | 执行（默认：dry-run） |
| --update | 在接入前对仓库执行 git pull --ff-only |
| --runtime claude,opencode,agents,codex,antigravity | 限制为逗号分隔
- runtime_manager——所有运行时配置：检测每个运行时，将本地配置摄取到 brain 中（Direction A），将 brain 配置植入本地（Direction B），处理冲突，链接 skills。
- runtime_health——针对每个已选运行时的只读应用后验证，使用与 runtime_manager 相同的映射矩阵。
运行时策略和私有配置属于私有 brain，而非此公共仓库。当 brain 包含 _AGENTS/SHARED/memory/ 时，Codex 会在 ~/.agents/brain-memory 处获得一个稳定指针；捆绑的查询工具会按需对小部分已索引笔记进行排序。Codex 自身生成的 ~/.codex/memories/ 目录保持为本地且独立。
Environment profiles
Environment profiles 提供了一种运行时中立契约，用于选择 issue tracker、仓库、项目约定以及可选的私有资源，而无需将这些值嵌入公共核心。Profiles 位于私有 brain 的 _AGENTS/SHARED/profiles/ 下；当 profiles 变化时，全局运行时符号链接保持稳定。
有关版本化 schema、选择算法、优先级、安全规则和脱敏示例，请参阅 docs/runtime-profiles.md。当 brain 中存在这些文件时，model/SCRIPTS/runtime_health.py 会加载并验证它们。使用 --profile <id> 进行显式选择，或使用 --cwd <path> 来执行项目规则选择。MCP/API 可用性被委托给活动运行时适配器；只读检查从不将已配置的 provider 名称视为实时访问的证明。
Skills 可以调用 skills/brain/scripts/profile_context.py，将通用能力解析为脱敏的 provider 上下文。--live 会检查 Codex MCP 注册表/认证边界，而调用方可传入确切的 --available-tool 名称以及 --tool-catalog-complete 来强制实施活动暴露。省略或不完整的 catalog 保持未验证状态。Claude 的实时发现会被拒绝，因为其官方 registry 命令可能会重写运行时设置。
运行时适配器可以使用 model/SCRIPTS/profile_overlays.py 投射独立的私有 profile 资源。适配器为每种选定的资源类型提供显式根目录；先进行 dry-run 的投射器会链接 brain 拥有的源、隔离冲突，并且可以安全地重复应用而无需重写运行时配置。
model/SCRIPTS/profile_secrets.py 会检查引用的 secret 名称而不返回其值。环境存在性、仅元数据的 macOS keychain 查找以及脱敏的运行时原生 catalog 共享相同的 fail-closed 状态契约。
Git 被用作回滚锚点：在任何变更之前都会创建本地快照提交或带注释的标签。快照消息是确定性的，且快照签名被禁用，因此无人值守的 bootstrap 运行永远不会打开编辑器或 GPG 提示。不会自动推送任何内容。
Skills
Agent-brain 附带多个 skills，但只有 operating skill 会被自动安装；其余为选择加入：
| Skill | Command | Installation | Purpose |
|---|---|---|---|
| brain | /brain (Codex: $brain ) | Automatic | 连接到 brain，管理会话生命周期、每日笔记、站会报告（ /brain daily ）以及标准化 |
| boyscout | /boyscout (Codex: $boyscout ) | Opt-in | 发现改进机会并将其路由到显式的修复工作流或待办列表 |
| explain-with-cards | /explain-with-cards (Codex: $explain-with-cards ) | Opt-in | 导师模式：通过小型卡片讲授会话主题，包含理解检查和持续学习计划 |
| step-by-step | /step-by-step (Codex: $step-by-step ) | Opt-in | 引导模式：将待处理的问题和任务转变为有序清单，并逐卡关闭 |
Skills 位于 brain 之外，并符号链接到仓库。Codex 和 OpenCode 共享 ~/.agents/skills/；Claude 使用 ~/.claude/skills/；Antigravity CLI 使用 ~/.gemini/antigravity-cli/skills/。旧版 Gemini CLI 路径不受管理。Skill 文件使用普通名称，不带 .common.md 后缀。
brain skill 的 session-open apply 是幂等的：它会创建或更新一条 session 笔记，按完整 session ID 为键恰好 upsert 一条每日恢复条目，保留手动编辑过的摘要，并检查最终生成的 session/daily 状态。活跃的 WIP 笔记可以用随附的只读工具 brain_check.py 对照 WIP/WIP.md 看板进行检查。
仅在需要时安装 opt-in skill（这里以用于 Codex 的 boyscout 为例）。先查看 dry-run；其他 opt-in skill 以相同方式安装，只是目录名不同：
bash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh boyscout ~/.agents
bash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh boyscout ~/.agents --apply
同一个安装器也接受仓库自有的 skill 目录，并能把它链接进所有检测到的 runtime：
bash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh /path/to/project/skills/confold
bash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh /path/to/project/skills/confold --apply
仓库布局
agent-brain/
├── bootstrap-zero.sh # curl 入口点（克隆仓库，分派给 orchestrator）
├── docs/ # 公开架构与带版本号的 profile schema
├── examples/profiles/ # 脱敏后的环境 profile 示例
├── model/ # 运行模型 —— brain 内部 _COMMON 符号链接指向的内容
│ ├── AGENTS.common.md # 共享 agent 指令
│ ├── BRAIN.common.md # brain 结构与约定
│ ├── RULES-*.common.md # 每日笔记、文件命名、链接、session、证据
│ ├── JOBS.common.md # 周期性维护例程
│ ├── TASK_TYPES/ # 常见任务类型的操作指南
│ ├── TEMPLATES/ # 每日笔记、WIP、issue、报告模板
│ └── SCRIPTS/
│ ├── brain_state.py # 状态机（共享）
│ ├── home_setup.py # 结构（清理、暂存、_COMMON、wrapper）
│ ├── runtime_catalog.py # runtime 配置主目录与 skill 目标位置
│ ├── runtime_manager.py # runtime 配置（Direction A/B、冲突、skill 链接）
│ ├── runtime_health.py # 针对所有受支持 runtime 的 apply 后检查
│ ├── profile_overlays.py # 可选的私有资源投影
│ ├── profile_secrets.py # 无值的 secret 引用预检
│ ├── runtime_install.sh # 底层符号链接辅助脚本（由 runtime_manager 调用）
│ └── skill_link.sh # 非默认 skill 的手动安装器
└── skills/
├── brain/ # session 生命周期、每日笔记、维护
│ ├── SKILL.md
│ ├── scripts/ # session_open.py, brain_check.py, find_home.py, ...
│ └── references/ # project-aware-loading, setup-and-attach, brain-maintenance, runtime-merge
└── boyscout/ # 改进点识别 + 待办管理
├── SKILL.md
├── scripts/ # backlog.py, doctor.py, fix-ceremony.sh
└── references/ # finding-schema、检测指南、工单后端、deep-mode、...
model/ 下的文件保留 .common.md 的命名约定，因为它们通过 _COMMON 存在于 brain 内部，必须对笔记类应用保持链接安全。skills/ 和仓库根目录使用普通命名。
测试
测试套件完全针对临时的 brain、home 和 Git 仓库运行。生命周期子集和聚焦子集仅依赖标准库；完整的受管控门禁使用 uv 提供 jsonschema、pydantic 和 pyyaml：
uv run --python 3.12 \
--with 'jsonschema>=4.25,<5' \
--with 'pydantic>=2.10,<3' \
--with 'pyyaml>=6.0.2,<7' \
python3 -m unittest discover -s tests -v
CI 在 macOS 和 Linux 上执行同一套件。profile 集成测试使用隔离的临时 HOME，验证 dry-run 安全性、冲突隔离以及双重 apply 的幂等性。
覆盖的契约、单项测试命令和 fixture 规则见 tests/README.md。
本地与 CI 门禁
规范的本地门禁是 todo19 QA-manifest 别名 complete-local-gate，仅通过 tests/support/evidence_cli.py run-todo 执行。它会运行当前 unittest 测试套件、不可变的 113-ID 基线重放、Python 编译、shell 语法检查、已提交差异的空白检查、工作树范围/空白检查、严格的 operating-model 检查器，以及零 __pycache__ 断言。
GitHub Actions 在 ubuntu-latest 和 macos-latest 上镜像严格的本地门禁。该工作流检出完整历史（fetch-depth: 0），从有效的 pull-request base、push base、固定的不可变基线或 root-commit fallback 中解析 MODEL_BASE，验证所选提交对象，然后在测试套件之前运行已提交范围门禁，并在编译/shell 检查之后运行工作树门禁。该工作流只是契约映射；private-brain 迁移仍是明确的用户工作，不会自动进行。