SethGammon/Citadel 是什么？

Citadel 是一个面向 Claude Code 和 OpenAI Codex 的开源操作层，提供持久项目记忆、意图路由、安全钩子和成本遥测。本文基于其 README 与仓库信息，分析它的安装方式、运行机制、适用场景与边界。

SethGammon/Citadel 可以商用吗？

可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。

SethGammon/Citadel 还在维护吗？

在维护。仓库最近一次提交在 2 天前。

SethGammon/Citadel 是用什么编程语言写的？

主要是 JavaScript（依据 GitHub 的语言统计）。

Citadel 评测：Claude Code 与 Codex 的操作层，安装与使用指南

Q: SethGammon/Citadel 还在维护吗？

在维护。仓库最近一次提交在 2 天前。

秒懂

它是什么？: Citadel 是一个面向 Claude Code 和 OpenAI Codex 的开源操作层，提供持久项目记忆、意图路由、安全钩子和成本遥测。本文基于其 README 与仓库信息，分析它的安装方式、运行机制、适用场景与边界。
适合谁用？: Citadel 适合那些需要跨会话保持项目上下文、经常并行运行多个代理、或对变更安全有较高要求的团队。它不适合只做一次性小改动、或者不想引入额外状态层的个人开发者。
能商用吗？: 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
还在维护吗？: 在维护。仓库最近一次提交在 2 天前。
用什么语言写的？: 主要是 JavaScript（依据 GitHub 的语言统计）。

以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。

开源项目深度解析

Hysen Labs 编辑部 · 2026年8月8日 · SethGammon/Citadel

它解决什么问题：代理的失忆与失控

Claude Code 和 OpenAI Codex 这类编码代理擅长处理单次请求，但一旦会话结束，它们就失去了上下文。每次新会话都要重新解释项目结构、已有决策和进行中的工作。对于多步骤任务，代理可能选错工作流，或者在执行高风险变更时没有足够的检查。Citadel 试图解决这三个问题：它提供仓库本地的持久状态，让信息跨会话存活；它通过一个统一的 /do 入口路由请求到正确的工作流；它用审批边界和显式验证来约束多步骤操作。这个项目面向的是那些让代理承担持续开发任务的工程师，而不是只需要一次性补丁的人。

核心机制：五个状态构成的运行循环

Citadel 的操作循环由五个公开状态组成：Request、Run、Evidence、Needs You、Resume。你通过 /do 描述期望的结果，这进入 Request 状态。然后选定的工作流在运行时、仓库和审批边界内执行，这是 Run。执行过程中，检查和产物会报告 passed、failed、blocked 或 unknown，形成 Evidence。如果遇到需要你批准的冲突，或者缺少必要证据，Citadel 会停在 Needs You 状态，而不是自作主张继续。最后，Resume 状态利用仓库本地状态告诉你在新会话中下一步该做什么。这个状态机是 Citadel 的核心设计，它把代理从无状态的工具变成了有记忆的参与者。

安装方式：插件市场与高保证离线路径

Citadel 不通过 npm 发布，而是通过编码代理内置的插件市场安装。对于 Codex，你需要在仓库中运行 codex plugin marketplace add SethGammon/Citadel --ref v1.3.5，然后 codex plugin add citadel@citadel-local。对于 Claude Code，对应命令是 claude plugin marketplace add SethGammon/Citadel@v1.3.5 --scope local 和 claude plugin install citadel@citadel-local --scope local。README 特别强调，必须使用明确的版本标签，不要用浮动的 main 分支。它还提供了一套手动离线安装流程：下载 vX.Y.Z 的 tarball、manifest 和 sha256 文件，校验哈希，然后通过 node scripts/adopt.js 生成并应用计划。这个流程要求将计划文件保存在目标仓库之外，否则会导致 TARGET_DRIFT 错误。

命令解析：精确匹配与语义分类的取舍

Citadel 的 /do 命令处理方式值得注意。它首先尝试精确匹配整个规范化请求，比如 /do test 对应 package.json 中的 test 脚本。如果无法精确匹配，较大的请求会收集候选方案，然后由运行时进行语义分类。这里有一个明确的限制：/do preview 命令只做候选预检，不会检查活动状态，也不会运行 LLM 分类器，因此它的结果不可执行，selected 和 command 字段都是 null。这意味着 preview 只是一个预览，不能作为执行依据。这种设计避免了代理在不确定的情况下贸然行动，但也意味着用户需要理解精确匹配与语义分类之间的差距，否则可能对 preview 的结果产生误解。

安全与信任边界：谁拥有什么

Citadel 的 README 明确划分了信任边界：平台（即 Claude Code 或 Codex）负责插件获取和可执行代码的信任，而 Citadel 只负责有界的项目状态和恢复。这意味着 Citadel 不会修改共享配置、沙箱设置或用户级权限，除非你明确要求。安装脚本 adopt.js 会生成一个计划文件，应用时需要一个确认令牌。这种设计将风险隔离在项目本地，但同时也意味着 Citadel 无法保护你免受代理本身的安全漏洞影响。它提供的安全钩子是审批边界，而不是沙箱。如果你需要强隔离，Citadel 不是替代品，它只是增加了一层审计和暂停机制。

适用场景与明确边界

README 用表格列出了 Citadel 最有用的场景：重复设置和丢失上下文、工作流选择不明确、风险或多步骤变更、多个代理或分支并行、跨会话中断的工作。对于这些情况，Citadel 增加了仓库本地的决策记录、统一的 /do 入口、审批边界和持久状态。但文档也直说：对于短期的单次编辑，你的编码代理可能已经足够，Citadel 不会取代 CLAUDE.md、AGENTS.md、分支保护或人工审查。这是一个诚实的边界。如果你只是偶尔用代理改个 bug，Citadel 带来的状态管理和安装成本可能不值得。

替代方案与维护成本

最直接的替代方案是依赖编码代理原生的记忆机制，比如 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 文件。这些文件是静态的，需要你手动维护，而 Citadel 是动态地记录决策和发现。另一种做法是使用外部工具如 git 分支来管理并行工作，但 Citadel 提供了隔离的工作树和所有权管理，这超出了简单分支的能力。维护成本方面，Citadel 需要你保持 Node.js 22+ 的环境，并且每次升级都要通过插件市场重新安装。由于它没有 npm 包，回滚需要依赖 INSTALL.md 中的卸载步骤。MIT 许可证允许自由修改，但如果你 fork 了项目，你需要自己跟进上游的发布。

编辑结论

Citadel 适合那些需要跨会话保持项目上下文、经常并行运行多个代理、或对变更安全有较高要求的团队。它不适合只做一次性小改动、或者不想引入额外状态层的个人开发者。在采纳前，你需要验证三件事：确认你的 Node.js 版本满足 22+，检查你的编码代理是否支持插件市场（Claude Code 或 Codex），并仔细阅读 INSTALL.md 中的回滚与卸载步骤，确保在出问题时能干净退出。Citadel 的 MIT 许可证允许自由使用和修改，但它的核心价值在于项目本地状态，这既是优势也是负担，你必须有意识地管理它。

官方来源

社区笔记