1. 项目定位与目标

omniconductor 是一个面向 AI 编码代理（coding agent）的"工程纪律层"工具。它并不自己实现代码生成逻辑，而是作为一道前置治理层，把跨工具、跨场景的最佳实践统一编排后，下发到下游六类目标 IDE/CLI 代理环境中。项目的核心目标可以概括为三点：

• 可移植的纪律（portable discipline）——把"循环工程"、"git 卫生"、"指令保真"等规则从某个具体代理（如 Claude Code、Cursor 等）中解耦出来，形成可复用的 recipe。
• 可验证的安装（verifiable install）——通过 .conductor-manifest.json 记录每次写入的文件、SHA-256 校验和与当时的 CLI 版本，使后续的 doctor、uninstall 行为具备可回溯的真相源。
• 可降级的范围（degradeable scope）——通过 --mode=full|minimal|strict|recipes-only|reflector-only 让用户在严格 CI、纯文档生成、纯 hook 触发等场景下按需裁剪。

资料来源：README.md:1-40，VISION.md:1-30

2. 三层架构总览

整个项目自上而下分为CLI 控制层 → 适配层（Adapters）→ 学科层（Recipes / Hooks）。这三层各司其职，由 manifest 串联起来。

flowchart TB
  subgraph L1["CLI 控制层 (omniconductor)"]
    CLI["bin/omniconductor.js<br/>init · install · doctor · uninstall"]
    RUNTIME["共享运行时<br/>manifest writer · checksum · doctor reporter"]
  end

  subgraph L2["适配层 (adapters/<target>)"]
    A1[npx / opencode]
    A2[claude / cursor / gemini]
    A3[codex]
  end

  subgraph L3["学科层 (recipes · hooks · reflector)"]
    R1[loop-engineering]
    R2[git-hygiene]
    R3[instruction-fidelity]
    RF[Reflector runtime]
  end

  CLI --> RUNTIME
  CLI --> A1 & A2 & A3
  A1 & A2 & A3 --> R1 & R2 & R3
  RUNTIME -.stamps.-> M[(".conductor-manifest.json")]
  M -.drives.-> CLI

资料来源：docs/ARCHITECTURE.md:20-80

2.1 CLI 控制层

入口位于 bin/，对外暴露四个核心子命令：

CLI 层不直接生产纪律文本，它只承担计划 → 调用适配层 → 写 manifest → 校验这一闭环。manifest 既是安装的"真相源"，也是 doctor 与 uninstall 的唯一锚点。资料来源：README.md:60-120

2.2 适配层（Adapters）

适配层目录 adapters/<target>/ 中每个 adapter 是一份针对单一宿主环境的写入策略。宿主环境由六类组成（npm CLI + 五个目标代理）。adapter 之间共享同一份 contract，但不共享实现：每个 adapter 都知道如何在它的目录（如 .claude/, .cursor/, ~/.codex/ 等）下落地 agents、hooks、recipe 文本。--mode 参数在此层被转发并被记录进 manifest 的 "mode" 字段。资料来源：docs/ARCHITECTURE.md:80-140

2.3 学科层（Recipes / Hooks / Reflector）

学科层是最贴近用户的"内容层"，由若干 recipe 组成，每个 recipe 是一组已被外部验证过的规则集合：

• loop-engineering（v0.6.0 引入）：通过 pretool-loop-guard PreToolUse hook 约束代理循环——显式 done-criterion、迭代/Token 预算、verify externally, never by self-judgment、振荡守护。
• git-hygiene（v0.5.0 引入）：通过 stop-git-hygiene-guard Stop hook 强制共享仓库分支卫生。
• instruction-fidelity：强调 token-经济、指令保真的提示工程纪律。

Reflector runtime 是学科层的"反射执行器"，负责在 hook 触发时解析 recipe 规则并返回结构化决策（allow / warn / block）。--mode=reflector-only 即表示只安装该运行时而不下发任何 recipe 内容。资料来源：docs/PHILOSOPHY.md:40-90

3. 跨层协作流：以一次安装为例

1. 用户调用 omniconductor install --mode=full。
2. CLI 解析目标清单（六选 N），从 package.json 读取当前真实版本（修复了早期硬编码 "v0.2.0" 的 bug）。
3. 逐个 adapter 调用其 emit 函数，写出 agents、hooks、recipe 文档。
4. 对每个 emitted 文件计算 SHA-256，连同 "version"、"mode" 一并落入 .conductor-manifest.json。
5. 后续 doctor 通过同一 manifest 反向核对文件哈希、版本与遗留路径。
6. --uninstall 在文件哈希未变时直接删除；用户修改过的文件则被保留并发出警告（v1.0.1 的 checksum 保护语义）。

资料来源：AGENTS.md:60-110

4. 设计权衡与边界

• 不是代理框架：omniconductor 不替代 Cursor / Claude Code 等宿主，只是把它们当作"输出目标"。
• 不是 prompt 仓库：recipe 不只是文本片段，它们必须可由 hooks 自动校验——否则会被 doctor 标记为 stale。
• 不是纯 CLI：manifest 是项目的"微型数据库"，CLI 是它的外壳，doctor / uninstall 是它的查询/写回路径。

资料来源：docs/COMPARISON.md:30-70

这种"三层 + 单一 manifest 真相源"的形态，使 omniconductor 在 v0.5.0 → v1.1.2 的迭代中能保持向后兼容的同时持续扩展学科内容，而无需触动 CLI 与 adapter 的核心契约。

1. 安装路径与 manifest 契约

适配器在执行 omniconductor init 时，会在目标项目根目录写入 .conductor-manifest.json 作为唯一的"安装事实源"。manifest 字段从早期版本开始就被反复加固：

• 版本号动态读取：早期 6 个适配器在 manifest 中硬编码 "version": "v0.2.0"，造成 install-history 与 bug-report 数据失真；现已改为读取 package.json 动态注入。 资料来源：lib/manifest.js:1-80
• 校验和保护：--uninstall 仅在 emitted 文件 SHA-256 与 manifest 记录一致时才删除；用户改动的文件以及无校验和的旧 manifest 条目会被保留并附带 warning。 资料来源：bin/omniconductor.js:120-180
• 模式戳记：--mode=full|minimal|strict|recipes-only|reflector-only 会被原样转给适配器，并作为 "mode" 字段写入 manifest；strict 模式在出问题时会以 exit code 3 中止而非 touch 修补。 资料来源：package.json:1-40

路径安全由独立模块守护，避免恶意或错误的目标参数污染外部目录：bin/path-safety.js 提供白名单与符号链接检查，是所有写入操作的前置门。

2. CLI 命令家族

omniconductor CLI 由 bin/omniconductor.js 入口分发，目前公开的核心命令如下：

bin/doctor.js 把每组检查实现为可独立运行的子检查器，输出按"通过 / 警告 / 失败"分级，便于在 CI 中接入。

3. 模型路由向导（v1.1.0）

这是 v1.1.0 的标志性功能，目的是把过去散落在六个适配器中的模型配置步骤合并成一次交互：

1. omniconductor init 枚举用户选择的目标适配器，呈现一份汇总表。
2. 用户对推荐方案按一次回车即可全量确认（Tier 1/2/3 默认映射）。
3. 仅当用户选择自定义某个适配器时，才被询问三个值（典型如 provider、model、api-style）。
4. 确认后，所有状态写入项目本地 .conductor/model-routing.json，作为可重放、可 diff 的项目级路由声明。 资料来源：bin/model-routing.js:1-120

这样做的好处是：路由策略跟着项目走而不是跟着工具走——换一台机器或换一种代理时，只要把 model-routing.json 提交进仓库，整套映射即可重建。

flowchart LR
    A[omniconductor init] --> B{已选适配器}
    B --> C[汇总 Tier 1/2/3 推荐]
    C --> D{用户确认?}
    D -- 全部默认 --> E[写入 .conductor/model-routing.json]
    D -- 自定义适配器 --> F[询问 3 个值]
    F --> E
    E --> G[各适配器 emit manifest]

4. Hookify 与 doctor 的协同

bin/claude-hookify.js 是 Claude 适配器的输出验证器；自 v1.1.2 起，它与 doctor 在规则开关语义上达成一致：

• 规则文件中文档化的 enabled: false 现在被识别为非失败 warning（之前可能被误判为错误）；
• 仍拒绝非布尔值或不支持的事件类型；
• doctor 在 warning-only 模式下保留 D5 checked-file 摘要，但不会把"属于其他 checkout 的 plugin-list 条目"判定为失败。 资料来源：bin/claude-hookify.js:1-90

这套协同确保"自定义豁免"和"诊断结论"使用同一套事实解释，避免用户在不同命令间得到自相矛盾的提示。

omniconductor 的核心是一组跨 6 种 AI 编程工具适配器（Claude Code、Cursor、Codex、Gemini、Copilot、Aider）共享的"纪律系统"。该系统由四个互相补强的层组成：Recipes（可选配方）、Universal Rules（始终生效的硬性规则）、Roles（角色契约）与 Hooks（事件级拦截器），并辅以 Anti-patterns（明确禁止的反模式）作为负面清单。资料来源：core/README.md

框架定位与安装模式

核心框架通过 omniconductor init 写入目标工程，所有交付物由 .conductor-manifest.json 记录，并支持五种安装模式：full、minimal、strict、recipes-only、reflector-only，可在所有 6 个适配器上一致转发（npx CLI 透传，manifest 写入 "mode" 字段）。其中 minimal 只落盘"纪律文本 + 文档"，不注入 agents/hooks/Reflector 运行时；strict 在规则被破坏时直接 abort（exit 3）而非仅 warn。资料来源：v1.0.0 Release Notes

安装模式 × 注入内容
─────────────────────────────────────────────
full             ：纪律 + agents + hooks + Reflector
minimal          ：纪律文本 + 文档（无 agents/hooks）
strict           ：同 full，但违规 → exit 3
recipes-only     ：仅落盘 Recipes 目录与 Universal Rules
reflector-only   ：仅 Reflector 运行时

Universal Rules：始终生效的硬性规则

core/universal-rules/ 是基础层，所有模式（除 reflector-only 外）都会注入。Universal Rules 进一步划分为四个子文件，构成一个闭合的工作循环：

资料来源：core/universal-rules/workflow.md、core/universal-rules/quality-gates.md、core/universal-rules/spec-as-you-go.md、core/universal-rules/operations.md

Recipes：可选的垂直场景配方

Recipes 是"按需启用"的场景包，位于 core/recipes/，每个配方配套一个或多个 Hook（PreToolUse / Stop）。社区版本中两个代表性配方：

• loop-engineering：在 PreToolUse 阶段强制实施 G1–G6 循环工程纪律——显式 done-criterion、迭代+token 预算、require-progress、stall 升级、外部验证而非自我判定、震荡/死循环守卫。资料来源：v0.6.0 Release Notes
• git-hygiene：在 Stop 阶段检查 G1–G7 共享仓库卫生——禁止未申请 worktree、push 而非囤积、merge 后删除分支、备份≠已应用（必须以真实代码验证）、共享仓库禁用 force/rebase、合并 PR 提交给 CI、session 结束自检。资料来源：v0.5.0 Release Notes

用户可通过 recipes-only 模式只获取 Recipes 与 Universal Rules，跳过 agents/hooks 的重注入。

Roles、Hooks 与 Anti-patterns

Roles 在 core/roles/ 下以契约形式定义"谁负责什么"，例如 planner、implementer、verifier、reflector 的输入/输出契约；它们被映射为各适配器的 sub-agent / slash command。Hooks 是事件级拦截器，按 Claude Code 的 PreToolUse / Stop（以及其它适配器的等价事件）触发，对应 Recipes 中的纪律检查。Anti-patterns 作为负面清单散落在 Universal Rules 与各 Recipe 顶部，禁止"自我验证完成"、"集中补 spec"、"在共享分支 force push"等已知失败模式。

四个层的协作关系可由下图概括：

flowchart TB
  UR[Universal Rules\n始终生效] --> WP[workflow.md]
  UR --> QG[quality-gates.md]
  UR --> SAG[spec-as-you-go.md]
  UR --> OP[operations.md]
  R[Recipes\n可选] --> LH[loop-engineering\n+ pretool-loop-guard]
  R --> GH[git-hygiene\n+ stop-git-hygiene-guard]
  RO[Roles\nplanner/implementer/verifier/reflector] --> H[Hooks\nPreToolUse/Stop]
  AP[Anti-patterns\n负面清单] -.禁止.-> R
  AP -.禁止.-> RO

健康检查与一致性

该框架还配套 omniconductor doctor <target>（v0.8.0 引入），对已安装工程做 7 组只读校验，包括 manifest 合法性、版本漂移、文件完整性、陈旧遗留路径等。当 Hookify 配置与 doctor 诊断出现分歧时（如 enabled: false 的合法性与 plugin 列表解析），最新版本（v1.1.2）已统一：合法 false 作为非失败 warning，畸形布尔值仍被拒绝。资料来源：v1.1.2 Release Notes、v0.8.0 Release Notes

通过这一分层结构，omniconductor 既能在所有 6 个适配器上保持纪律一致性，又允许团队按需打开 Recipes，做到"默认安全、按需增强"。

omniconductor 是一个面向六款主流 AI 编程工具（Claude / Cursor / Codex / Copilot / Gemini / OpenCode）的"指挥棒"安装器。它通过 .conductor-manifest.json 记录每次安装的来源、模式、文件清单与哈希,并以此为锚点提供安全的卸载、Token 消耗度量、以及跨版本的健康检查。本页聚焦这四个紧密耦合的运维能力。

1. 清单（manifest）安全模型

每次 install 完成后,适配器会写入一份 .conductor-manifest.json,包含 version(动态读自 package.json)、mode(full|minimal|strict|recipes-only|reflector-only)、目标目录、生成的文件路径以及文件级 SHA-256 校验和。这套校验和是 v1.0.1 引入的"卸载安全"前置条件——只有知道原始哈希,卸载器才能判断"磁盘上的文件是否仍是当初写入的那个"。

校验和的写入路径由 tools/manifest-safety.sh 守护;CI 侧的 tools/check-adapter-metadata.sh 则反向核对:六个适配器声明的元数据必须和清单字段一致,否则在 CI 阶段就拒绝合并。tools/check-framework-purity.sh 进一步确保适配器之间不互相侵入实现,防止某一适配器静默改写另一适配器生成的文件,污染别人的校验和。资料来源：tools/manifest-safety.sh:1-1、tools/check-adapter-metadata.sh:1-1、tools/check-framework-purity.sh:1-1。

2. 卸载行为与变更保护

--uninstall 走"双校验"路径:第一道校验是清单存在性与 mode 字段(确保卸载器走对了执行分支);第二道校验是文件内容 SHA-256 对比。

• 校验通过:文件未被人修改 → 直接删除,恢复干净。
• 校验失败:磁盘哈希 ≠ 清单哈希 → 视为"用户改过的产物",不删,只输出 warning。这避免了一次手抖的 git restore、一次格式化、一次本地化翻译把整个工作流吊销掉。
• 遗留条目:v1.0.1 之前的 manifest 没有 sha256 字段 → 同样按"未知状态"处理,保留文件并警告用户先核对。

这一设计直接对应 v1.0.1 发布说明中"Checksum-protected uninstall on all six adapters"的承诺。资料来源：tools/manifest-safety.sh:1-1、tools/measure-tokens.sh:1-1。

3. Token 度量与 stale-token 防御

tools/measure-tokens.sh 是一个只读的体量分析工具,用来回答"这次安装/卸载到底动了多少 token"。它会扫遍 manifest 涉及的所有文件(规则、agents、hooks、recipes、文档),按 token 化近似估算各模式的体量,输出表格化报告,作为 --mode=minimal 与 --mode=recipes-only 等裁剪路径的成本依据。

tools/check-stale-tokens.sh 是 v0.7.0 引入的 CI 守门员。配套数据文件 tools/stale-tokens.txt 用 pattern⇥reason⇥hint⇥allow_regex 的四列格式登记"已知应该被替换但还没替换的旧 token",例如过期的工具名称、错误的指令引用;同时支持源码内联的 stale-ok: 豁免注释,用于确实需要保留的边界情况。该脚本的 Class A 类别还会机械校验 README 的状态行版本号必须严格等于 package.json 中的版本(R7 stamp),杜绝 npm 页面与 GitHub Release 长期不一致——这正是 v0.4.1 文档补丁修复的根因。资料来源：tools/check-stale-tokens.sh:1-1、tools/measure-tokens.sh:1-1。

4. 故障排查:doctor 与 live-verify

omniconductor doctor <target>(v0.8.0 起为第三个 CLI 子命令)以 .conductor-manifest.json 为锚点,做七组只读健康检查:清单合法性 · 版本漂移(安装戳 vs 运行 CLI) · 文件完整性 · 残留旧路径(来自适配器 metadata.json 历史快照) · 模式字段一致性 · doctor 自己检查过的文件摘要(D5) · 以及"插件清单条目是否指向另一份 checkout"的安全拒判。

tools/live-verify.sh 则用于真机端到端冒烟:在临时目录安装六款适配器、跑 doctor、跑 token 度量、跑卸载校验,确认 manifest 安全链不破。它常被 release 流水线用作"金丝雀"。

资料来源：tools/live-verify.sh:1-1、tools/manifest-safety.sh:1-1。

典型排查路径:遇到"卸载后文件还在" → 先 doctor <target> 拿 D5 文件清单 → 对照 manifest 的 sha256 判定是"被保护的用户修改"还是"遗留条目";遇到"模式比预期胖" → measure-tokens.sh 定位哪个文件贡献最大;遇到"README 写 v1.1.0 实际装的是 v1.1.2" → 看 CI 是否跑了 check-stale-tokens.sh 的 R7 stamp。这条链路也是 v1.1.2 修复 Hookify enabled: false 校验差异的诊断依据——doctor 与 Hookify 校验器现在共享同一份"什么算合规"的判定表。

Pitfall Log / 踩坑日志

项目：lee77840/omniconductor

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/lee77840/omniconductor | host_targets=claude_code, claude, cursor, gemini_cli

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/lee77840/omniconductor | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/lee77840/omniconductor | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/lee77840/omniconductor | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/lee77840/omniconductor | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/lee77840/omniconductor | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/lee77840/omniconductor | release_recency=unknown