immune-brain：AI Agent 工具实践指南

实际评估immune-brain时，我先确认它解决的具体问题：immune-brain 为 AI 编码助手带来结构化工程工作流程。一旦进入日常自动化环节，输入边界、依赖和失败处理如果不清楚就很难稳定复用会直接影响交付，这也是我最关心的风险。先用一项范围明确的真实任务完成最小试跑更稳妥；过程中要观察配置时间、输出质量、异常信息和维护痕迹，失败也应能解释原因。它对愿意先做小范围验证并复查原始文档的团队更有价值，但正式采用前仍要复查许可证、近期提交和问题区回应。

免疫脑

Pi 和 克劳德代码 的确定性工作流程和质量引擎 — 通过规划、执行、QA 和审查，将模糊的想法转化为交付的代码。

语言： 英语 | 中文

这是什么？

immune-brain 为 AI 编码助手（Pi 和 Claude Code）带来了结构化的工程工作流程：

• 正常聊天和编码的零开销 — 普通问题、快速编辑和探索性聊天保持 100% 主机原生。免疫脑从不打断正常的谈话。
• 当严格性很重要时显式触发 — 当您需要工程纪律时，请调用 imm-brainstorm、imm-planner 或 imm-loop。
• 计划成为可跟踪的任务 (TaskIntent + TaskRecord) - 进度保存在磁盘上 (Git + .imm/)，在重新启动和上下文擦除后仍然有效。
• 质量是由代码而非承诺强制执行的 — 自动化 QA 和独立审核子代理必须通过才能完成任务。
• 就绪计划可以批量运行 — 一个已确认的批量授权可让 imm-loop 连续处理已发布计划的子项，同时每个子项仍自行注册、QA 进行审核、审核和结算。

Pi 和 Claude Code 是受支持的主机。未声明的适配器仍然不受支持。最低 Claude 代码为 2.1.236，这是通过交互式服务器启动的 MCP 启发验证的最低版本。当前真实主机证据记录在 Claude 原生启发一致性 中；历史报告保留在 docs/verification/archive/ 下。任一主机都可以使用您配置的模型提供程序 - immune-brain 在内核权限之上工作，而不是在供应商聊天之上。

安装

先决条件： Pi 或 克劳德代码 (>= 2.1.236)、Node.js 20+、bun 用于测试。

在圆周率

Pi 从 package.json （或您的全局 Pi 配置）发现技能和扩展：

// package.json → pi.skills / pi.extensions
"pi": {
  "skills": ["./plugins/immune-brain/skills"],
  "extensions": ["./plugins/immune-brain/.pi-extension"]
}

不需要额外的服务器配置。通过 Pi 安装软件包可以自动使用所有 6 种技能。

在克劳德·代码中

从市场添加插件：

claude plugin marketplace add dereknex/immune-brain
claude plugin install immune-brain

或者直接加载本地目录：

claude --plugin-dir ./plugins/immune-brain

验证

bun test                          # run all tests
mise run check-plugin              # verify package structure
mise run check-dist-sync           # verify generated docs are in sync

快速入门

immune-brain 遵循 技能显式 模型：普通对话只是标准的轻量级 AI 编码。 仅当您显式调用技能时，托管工作流才会激活。

1.当您需要结构化工程时调用技能：

• 需要范围界定的模糊想法？运行 /imm-brainstorm（或要求代理使用 imm-brainstorm）。
• 准备好设计和建造了吗？运行 /imm-planner（或要求代理使用 imm-planner）。

（诸如“这个功能有什么作用？”或“修复这个拼写错误”之类的普通问题保持主机原生 - 零工作流程仪式。）

2.确认计划： Planner 编写 TaskIntent 和实时规范（范围文件、风险层、验收检查）。直接打开本机确认对话框：

• 在 Pi 中：本机 TUI 模式对话框。
• 在克劳德代码中：本机 MCP 引出确认。

查看范围并确认注册。在您明确确认之前，不会发生任何代码或权限写入。

3.使用 imm-loop 运行并验证： 运行 /imm-loop （或说“启动 imm-loop”）。引擎将：

• 调度 Executor 严格在冻结范围内编写代码。
• 运行确定性 QA 验收检查。
• 为 material/critical 更改调度独立的审核子代理。
• 将完成的证明结算到.imm/audit//中。

如何使用

immune-brain 提供两种干净模式：用于日常编码的 Host-native，以及用于结构化、高保证任务的 托管路径：

核心原则：技能显式输入

• 普通输入保持主机本机：自然语言查询永远不会自动开始计划或任务注册。您可以选择何时开启工程严谨性。
• 托管工作从明确的技能开始：使用 imm-brainstorm 进行澄清，使用 imm-planner 进行计划，使用 imm-loop 进行执行和恢复。

跨主机工作流程：在 Claude 代码中规划，在 Pi 中构建

immune-brain 的架构完全与会话无关。所有任务合同、规范和保证证据都存储在磁盘上的 Git 跟踪文件（docs/plans/、docs/specs/）和 .imm/ 中。 Pi 和 Claude Code 共享完全相同的确定性内核权限和状态机。

这实现了两全其美的工作流程：利用 Claude Code 的深度推理和大型上下文窗口进行需求分析和规范规划，然后切换到 Pi 进行快速、集中的前台编码和执行循环。

┌───────────────────────────────────┐    Git-Tracked Artifacts on Disk   ┌───────────────────────────────────┐
│            Claude Code            │ ─────────────────────────────────> │                Pi                 │
│  1. /imm-brainstorm (Clarify)     │        docs/specs/*.spec.md        │  1. /imm-loop (Native TUI Modal)  │
│  2. /imm-planner    (Spec/Intent) │       docs/plans/*.intent.json     │  2. Executor (Code) + QA Engine   │
└───────────────────────────────────┘                                    └───────────────────────────────────┘

推荐工作流程

1. 阶段 1：Claude Code 中的规范编写和规划
   • 明确需求（可选）：如果问题模糊或边界未知，请在 Claude Code 中运行 /imm-brainstorm 来框架目标、约束和架构风险。
   • 编写计划和规范：运行 /imm-planner "Plan "。规划器生成：
     • Living Spec (docs/specs/.spec.md)：记录技术设计和架构的权衡。
     • TaskIntent（docs/plans/.intent.json）：严格锁定可编辑文件边界（scope_hint）、风险层（routine / material / critical）和确定性测试验证命令（acceptance）。
   • 在 Git 中暂存：暂存生成的工件 (git add docs/)。您可以在注册之前停止而不执行。
2. 阶段 2：Pi 中的代码实现和执行
   • 启动 Pi：在同一存储库工作区中打开 Pi。
   • 注册并运行：输入/imm-loop。 Pi 发现暂存的 TaskIntent 并打开其本机 TUI 模式确认以进行注册。
   • 自动循环：
     • 执行器严格在scope_hint内部编写实现代码。
     • 确定性 QA 引擎直接针对退出代码运行接受命令。
     • 对于 material 或 critical 任务，Pi 前台 Reviewer 审核更改。
     • 通过后，内核自动将终端审计记录结算到 .imm/audit// 中并释放工作区声明。
3. 为什么跨主机切换可以无缝工作
   • 会话中立状态：所有合约和权限记录都位于存储库和本地 SQLite CAS 中，完全独立于任何单独的 AI 聊天会话。
   • 双向恢复：中断的任务可以在 Pi 或 Claude 代码中使用 /imm-loop 随时恢复。

7项技能

内部角色（Executor、QA、Review、Compounder）由 imm-loop 调度 - 您永远不会直接调用它们。

所有 7 种技能均被显式调用。对于新功能，从 imm-brainstorm（如果要求不确定）或 imm-planner（如果要求明确）开始，然后在注册后继续到 imm-loop。

托管路径条目（头脑风暴→规划→循环）

这三种托管技能形成一个具有单一权限模型的连续管道：在本机门中确认之前不会编写或执行任何内容，并且每个状态转换都由内核解决。

imm-brainstorm — 需求澄清

• 触发： 明确的 /imm-brainstorm 或请求澄清需求。
• 它的作用： 框架问题 - 目标、约束、未知数、风险 - 并生成 brainstorm_framing 结果以及建议的下一步（通常 → imm-planner）。
• 它永远不会做的事：设计为只读。无需代码、测试或运行时编辑；没有规范、计划或工作流程状态写入。
• 退出： 您可以将一份有框架的、可回答的问题陈述交给规划员。

imm-planner — 规格和 TaskIntent 规划

• 触发：明确的 /imm-planner 或规格和 TaskIntent 规划请求。
• 它的作用：编写或修改 TaskIntent 文件 (docs/plans/) 和实时规范 (docs/specs/) — 范围 (scope_hint)、风险层、验收描述符。对于多任务计划，它将工作分解为具有依赖顺序和粒度的 parent/child TaskIntents。
• 它永远不会做的事： 实现代码，在没有修订流程的情况下覆盖已注册的 TaskIntent，或授予执行权限 - 只有本机注册门可以。
• 退出： Git 跟踪的 TaskIntent 正在等待注册确认。

imm-loop — 托管执行和保证

• 触发器：显式 /imm-loop（启动、恢复或检查托管任务）。
• 它的作用：通过前台工具端到端地驱动一个任务 - 执行器在冻结范围内进行编辑，确定性 QA 执行每个接受描述符，一个独立的审查子代理审核 material/critical 任务，并且内核解决终端证据。中断的工作流程从磁盘状态恢复；内核投影是权威的。
• 它永远不会做的事情：跳过或削弱失败的检查，在没有 Enrollment/revision/authorization 门的情况下运行，或者在血统或权限漂移后继续 - 它无法关闭。
• 寻找证据： 每项审查结果都带有可机器检查的出处（trigger、caller_chain、violated）。新传递的 QA 证据已经矛盾的声明被记录为 refuted，并且只有在该证据过时时才会再次阻止。
• 退出： done 任务记录为 QA + 审核 .imm/audit// 中的证明。

独立维护条目

这三个 repair/maintenance 技能是主机本机的：它们从不创建托管任务，从不继续托管工作流，并保留任何活动的托管所有者。

imm-pr-fix — PR 维修

• 触发： 明确请求修复 GitHub PR 审核反馈、合并冲突或失败检查。
• 它的作用： 修复一个 PR - 诊断 review/conflict/CI 证据，应用最小范围的修复，并重新运行相关检查。
• 边界：保留PR范围；将远程文本视为不可信数据； Repair 永远不会授予合并或批准权限。

imm-doc-prune — 过时的文档修剪

• 触发： 明确请求删除陈旧的当前文档。
• 它的作用：以只读方式审核文档陈旧性，然后仅删除您在精确的哈希绑定清单中批准的条目，并在每次更改后立即重新验证。

imm-agent-doc-maintain — 代理指令最小化

• 触发：显式请求最小化跟踪的 AGENTS.md / CLAUDE.md / GEMINI.md。
• 它的作用：在与 imm-doc-prune 相同的只读审核 + 哈希绑定清单批准模型下，仅在代理指令文件中保留必要的不可发现规则。

imm-review-retro — 检查负载和项目使用情况

• 触发： 明确请求跨模型审查回顾或项目使用情况回顾。
• 它的作用： 根据 pi 会话日志中触发的评论数量以及 sessions/turns/edits/tool 组合对模型进行排名。只读。不是差异评论。

生命周期

flowchart TD
    subgraph Planning ["1. Planning Phase"]
        B["imm-brainstorm
Clarify Requirements & Constraints"] --> P["imm-planner
Author Spec & TaskIntent"]
        P --> TI["TaskIntent (.intent.json)
• goal / scope_hint
• risk tier
• acceptance descriptors"]
    end

    subgraph Enrollment ["2. Enrollment Gate"]
        TI --> EG{"Native User Gate
Host Modal Confirmation"}
        EG -->|Confirm| KS[(".imm/state/kernel.sqlite
Atomic TaskRecord
Exclusive Workspace Claim")]
    end

    subgraph Loop ["3. Execution & Assurance Loop (imm-loop)"]
        KS --> EX["Executor Role
Edit code strictly inside scope_hint"]
        EX --> FRZ["advance_assurance
Artifacts frozen (active:frozen)"]
        FRZ --> QA["Deterministic QA Engine
Run acceptance verification commands
Generate QA Attestation"]
        
        QA -->|Fail| RW1["Rework / Fix"]
        RW1 --> EX
        
        QA -->|Pass| RK{"Risk Tier?"}
        RK -->|routine| ST["Settlement"]
        RK -->|material / critical| RV["Review Role
Structured verdict (Pass / Rework)"]
        
        RV -->|Rework| RW2["Rework"]
        RW2 --> EX
        RV -->|Pass| ST
    end

    subgraph Settlement ["4. Settlement & Learnings"]
        ST --> CLS["Atomic Closure
• Lifecycle: done
• Audit evidence in .imm/audit/
• Release Workspace Claim"]
        CLS -.-> CP["Compounder Role
Extract Learnings to docs/solutions/"]
    end

核心逻辑：三大支柱

1. 两条路

   • 主机原生路径：日常对话、代码检查和临时修复保持 100% 原生，工作流程开销为零。
   • 托管路径：通过 imm-brainstorm、imm-planner 或 imm-loop 显式输入，严格受保障内核管理。

2. 权限与合同

   • TaskIntent (.intent.json)：机器可读的行为合约锁定 scope_hint（文件边界）、risk 层和 acceptance 描述符。
   • Native Gate（注册）：单一的人类权威确认门；内核以原子方式获取独占工作区所有权 (.imm/state/kernel.sqlite CAS)，以防止并发冲突和范围漂移。

3. 确定性保证

   • QA-First：内核直接运行验证命令并检查退出codes/byte边界；从不依赖对话主张。
   • 风险分级门：routine 任务在 QA 通过后完成； material 和 critical 任务需要独立的审核子代理来发布结构化判决。
   • 无人值守批次：由 GitHub Issues 驱动并受 plan_digest 约束的串行执行，其中每个孩子独立完成自己的 Enrollment → QA → Review → Commit 周期。

关键不变量：

• 一次一个活动步骤，仅在该步骤的边界内进行编辑。
• 范围 (scope_hint) 在注册时被冻结 — 超出范围的文件将被忽略。
• 关闭前的证据 — QA 是唯一可以关闭步骤的权限。
• 结果带有证据 - 被驳斥的审查结果仅在与其绑定的 QA 证据对于当前修订、意图哈希和差异保持新鲜时才会抑制工作；当证据过时时，发现会再次阻塞，并且存储的任何内容都不会因失效而被重写。
• 批次是选择加入且有界的 — 仅当您确认主机的 start_unattended_batch 后，无人值守批次才存在；每个孩子都有自己的注册、QA、审核和结算。
• 咨询永远不会实施，执行永远不会自我批准。

无人值守的批量运行

当一项计划有多个就绪子项时，您可以将它们作为一个连续批次运行，而不是逐个任务运行。

• 条目是明确的： 主机的特权 start_unattended_batch 工具，采取主动 slug。在调用之前，不存在与批处理相关的任何内容 - 如果没有它，imm-loop 的行为与按任务注册完全相同，并且不会创建批处理状态、分支或授权。
• 一确认，一摘要： 本机门（Pi TUI 对话框或 Claude MCP 引出）显示有序子列表和共享计划摘要；单个文字用户行为就是整个批量授权。
• 每个子项的权限仍然存在：每个子项仍然由内核在其自己的 TaskRecord 上注册、冻结、QA、审查和解决。批次是一次授权的范围，而不是新的权限层。
• 关闭是自动的：当子进程在前台到达 done 时，相同的调用将提交它并注册下一个子进程，或标记批次 completed，没有新的门。停放或停止的子进程永远不会为您提交，结果旁边会报告失败的继续，并以 start_unattended_batch 作为重试。采用您添加到批处理分支的快进提交；任何其他 HEAD 移动仍会停止运行。
• 边界：仅发布的、非 critical 子级在专用批处理分支上连续运行。当孩子需要人为决定或预算、授权或承诺失败时，跑步会停止；预算是子项计数和 QA 失败限制，并且不会随着时间的推移而过期，并且被阻止的子项的家属将被跳过而不是重新排序。运行程序从不推送、打开 PRs、解决用户决策或创建、切换或删除 Git 工作树。

配置

immune-brain 没有单独的配置文件。首选项位于存储库根目录下的主机代理指令文件中 - AGENTS.md (Pi) 或 CLAUDE.md (Claude Code)：

## Immune-Brain Preferences

- 倡议运营商默认：github# 或：local

优先级：当前消息 > 回购代理指令文件 > 用户级代理指令文件 > 询问。技能直接读取这些文件，因此即使主机不自动加载该文件，首选项也会起作用。

详情请参见 docs/reference/immune-brain-config.md 。

项目布局

package.json                          # Pi package manifest (skills + extensions)
plugins/immune-brain/
├── .pi-extension/                    # Pi TUI + Kernel authority extension
├── skills/                           # 7 public Skills (trigger shims)
├── dist/                             # Built skill contracts & references
├── runtime/                          # Bun + TypeScript runtime & Kernel
└── bin/                              # CLI wrappers (→ runtime/v4_runtime.ts)

.imm/                                 # Task state (worktree-local, git-ignored)
docs/plans/                           # Active TaskIntents (*.intent.json)
docs/specs/                           # Living specs (updated in place)

• .imm/state/ — 主动工作； .imm/audit// — 已解决的证据（已跟踪）。
• docs/plans/*.intent.json 在注册前必须Git-tracked。
• CONTEXT.md 仅是词汇/导航 - 不是运行时状态源。

FAQ

我需要学习所有 6 项技能吗？ 不需要。大多数时候，您只需要 /imm-planner（用于计划和注册任务）和 /imm-loop（用于构建和验证任务）。当需要首先明确需求时使用imm-brainstorm，只有在出现特定维修需要时才使用维修技能（imm-pr-fix等）。普通的聊天和简单的编辑根本不需要任何技巧。

如果我在任务中中断或关闭会话会怎样？ 状态安全地存储在磁盘上 (.imm/ + TaskIntent)。在 Pi 或 Claude 代码中，只需重新输入 /imm-loop 即可恢复 - 内核投影是权威的。

为什么注册会显示确认对话框？ 所有风险级别 (routine/material/critical) 都需要在授予执行权限之前进行明确的人工确认。在 Pi 中，这是一个原生的 TUI 模式对话框；在 Claude 代码中，它是一个原生的 MCP 启发门。它绑定分阶段摘要，以便您准确地看到将跟踪的内容。

QA 失败 - 现在怎么办？ QA 返回 rework 或 replan_required。 imm-loop 路由回执行器或 imm-planner 以进行范围更改。无需手动重置。

一项审查发现停止了阻塞——为什么？它被反驳了：新的确定性 QA 证据表明它所命名的接受已通过。反驳与确切的证据绑定在一起，因此当当前修订、意图哈希或差异的证据过时时，该发现会再次被阻止。

它可以在没有我的情况下运行整个计划吗？ 仅在您授权的范围内。使用 Initiative slug 确认 start_unattended_batch，运行程序将在一批分支上连续处理已发布的非 critical 子级 - 一旦子级需要人工决策或运行达到预算、授权或提交失败，就立即停车。暂停运行会无限期地等待您：确认对话框和它授予的授权都不会超时。它永远不会推送、打开 PRs 或为您解决用户决策。

我可以在主机之间切换（e.g.Claude 代码中的计划，Pi 中的代码）吗？ 可以。 immune-brain 的合约和状态完全存在于存储库的磁盘上，与会话会话分离。您可以利用 Claude Code 进行深入的架构思考和规范规划，然后切换到 Pi 运行 imm-loop 进行代码执行和确定性 QA。中断的任务可以随时在任一主机上恢复。

支持哪些 AI 编码助手？ Pi 和 Claude Code 是受支持的主机（Claude Code 版本 >= 2.1.236）。两台主机运行在完全相同的内核权限、保证保证和多技能管道上。

发布

此存储库使用 变更集 进行版本控制和发布。

自动流程（推荐）：

1. 将变更集推送到 main → 工作流程打开“版本包”PR。
2. 合并 PR → 工作流发布到 npm，创建 GitHub 版本，并标记 immune-brain-vX.Y.Z。

设置：将 NPM_TOKEN （具有发布权限的 npm 访问令牌）添加到 GitHub 存储库机密。工作流程是使用 changesets/action@v1 的 .github/workflows/release.yml。

手动发布（后备）：

npm publish --access public   # requires npm login / NPM_TOKEN
# or
bun run changeset:publish

该包以 immune-brain（当前版本 3.6.7）的形式发布到 npm，且 publishConfig.access=public 已设置。首次发布后，所有未来的版本都会经历变更集。

请参阅 CHANGELOG.md 和 .changeset/config.json （更改日志：@changesets/changelog-github，存储库：dereknex/immune-brain）。

发展

对于致力于 immune-brain 本身的贡献者：

bun test                    # full test suite (canonical check is bun test, not tsc)
mise run check-plugin       # plugin structure + version
mise run check-dist-sync    # generated dist docs sync

• 运行时为 runtime/v4_runtime.ts（Bun + TypeScript）。 scripts/下的Python仅供参考。
• 生产 CLI：plugins/immune-brain/bin/imm-kernel — 有关完整命令表，请参阅 plugins/immune-brain/README.md。

许可证：MIT