Citadel 是 Claude Code + OpenAI Codex 的开源操作系统层，它通过/do统一入口把一次任务拆成请求（Request）→ 执行（Run）→ 证据（Evidence）→ 需要你（Needs You）→ 恢复（Resume）五个公开状态。本文用一篇入门指南，带你完整看懂 Citadel 操作循环：为什么普通 Agent 会"半途失忆"、五状态各自在做什么、以及每一步留下的可检查证据。

为什么需要"操作循环"？

普通编码 Agent 的问题不在于"不会干活"，而在于干完活后没有留下可验证的痕迹：

• 换个会话，之前做了什么、做到哪一步，全部要靠重新解释；
• "做完了"只是一个口头声明，没有命令输出或产物可以对照；
• 遇到冲突、越权、缺失信息时，Agent 可能擅自继续，而不是停下来等你决策。

Citadel 的回答是：把每次工作都收敛成一个有界的操作循环——声明触发条件、预算、验证器、停止条件，状态落在仓库本地（.planning/），让下一次会话可以从证据继续，而不是从聊天记录猜起。

官方把"证明"定义为：不是 Agent 能描述功能，而是后来的会话能检查发生了什么、并从证据继续（见 docs/OPERATING_LOOP_PROOF.md）。

/do 五状态全解析：一张表看懂核心工作流

Citadel 的操作循环只有五个公开状态，全部围绕/do展开（定义见 README.md）：

📌 状态一：Request —— 一句话进入，无需背命令

你不需要记住/review、/scaffold、/triage等几十个技能名，直接描述结果即可：

/do review README.md /do generate tests for the changed files /do next

/do内部是一个统一意图路由器：先做精确命令匹配，再看激活状态（有没有进行中的 campaign / fleet），再做技能关键词候选匹配，最后用 LLM 做复杂度分类（范围、复杂度、是否需要持久化、是否可并行）。分类完成后会宣布路由决策，例如"Routing to /review because …"，保证过程透明。

如果你已经知道目标，还可以显式指定路由，但它依然要经过激活与安全边界检查：

/do --route /test-gen -- generate tests for the changed files

路由细节完整定义在 skills/do/SKILL.md，包括 Tier 0 精确匹配表、Tier 3 六维分类模型（SCOPE / COMPLEXITY / INTENT 等）和降级保护（比如输入太短就不会被升级成大规模 campaign）。

⚙️ 状态二：Run —— 在有界的边界内执行

进入 Run 后，工作流在运行时权限、仓库范围、审批边界内行动。Citadel 的克制原则是"比例性检查"：

• 单个文件的修改不会被派给并行 agent 编队；
• 多会话级任务不会被丢给一次性技能；
• 高风险命令仍走原有工具审批，不会被自动放行。

如果任务是"重复直到通过"型（比如 lint 修到绿），会路由到 skills/loop/SKILL.md 的有界循环：必须显式提供验证器和最大尝试次数，绝不静默超出声明的尝试上限。循环契约字段（触发器、预算、验证器、重试、停止条件、状态路径）统一规范在 docs/LOOP_CONTRACT.md 中。

🔍 状态三：Evidence —— 证据只有四种结论

这是 Citadel 最核心的设计：证据结论只有passed、failed、blocked、unknown四种，缺失的证据不会被"晋升"为成功。

• 验证命令来自项目本身（比如npm run test），而不是凭空猜测；
• 报告必须写清文件、命令与结果，别的会话可以逐条对照；
• 运行不了、查不到的能力如实报unavailable，而不是假装支持。

官方对"好的证据"的定义很朴素：无聊且可检查——真实仓库、原样展示命令、报告指出文件与结论。反过来，"截图配声明"是弱证据。

信任边界提醒：独立验证器才是结果证据。自报"完成"的 adapter 在声明了命令验证器时不足以判 pass（见 docs/OPERATION_CONTROL.md 的 Trust boundary 一节）。

⚠️ 状态四：Needs You —— 停下，并说清缺什么

遇到审批、冲突或证据缺失时，Citadel 不做"猜一个继续"，而是精确停止，告诉你下一步缺哪个具体输入：是某个审批、某个冲突解决，还是某份缺失证据。这一状态配合/do next（操作控制台）使用体验最好——它会先展示当前状态、下一步动作、风险边界和验证方案，让你在批准之前先看到 Citadel 的想法。

🔄 状态五：Resume —— 新会话从状态而非聊天继续

会话结束后，.planning/下的仓库本地状态会记录：当前在哪个工作流、停在哪、下一条最有用的命令是什么。新会话里只需：

/do next

它会基于仓库状态恢复下一个动作（campaign 继续、fleet 续跑，或明确回答"No active campaign or fleet session found. Nothing to continue."）。这就是五状态闭环的最后一环：没有状态迁移，就没有真正的跨会话持久性。

新手上手：三步跑通第一个操作循环

1. 克隆仓库（只读参考亦可）：

   git clone https://gitcode.com/gh_mirrors/citadel13/Citadel

2. 初始化：安装后在目标项目里执行/do setup --express，Citadel 会在当前仓库落.planning/状态目录；
3. 跑循环：按 docs/OPERATING_LOOP_PROOF.md 的最小公开演示序列走一遍：

/do setup --express /do next /do review README.md for first-time developer friction /do identify the project's safest verification command and run it /cost

最后打开.planning/operating-proof/latest.md检查产物——你能看到每一步的命令与结论，这就是"从请求到证据"的完整闭环。

延伸阅读：关键文档与模块路径

总结

一句话记住 Citadel 操作循环：请求进、证据出，中间每一步都有名字、有边界、有状态文件。

• Request 让你用自然语言进入，不用背命令；
• Run 保证执行不越界、不失控；
• Evidence 只给四种诚实结论，缺证据不算成功；
• Needs You 把决策权还给人，且说清楚缺什么；
• Resume 让下一个会话从状态继续，而不是从头解释。

这套五状态工作流就是 Citadel 作为"操作层"的全部承诺——把 AI 编码 Agent 从"聊天工具"变成可检查、可恢复、可审计的工程系统。