# https://github.com/lee77840/omniconductor 项目说明书

生成时间：2026-07-20 05:09:06 UTC

## 目录

- [项目概览与三层架构](#page-overview)
- [安装路径、CLI 命令与模型路由向导](#page-install-cli)
- [核心框架：Recipes、Universal Rules、Roles、Hooks 与 Anti-patterns](#page-framework)
- [清单安全、卸载、Token 度量与故障排查](#page-ops)

<a id='page-overview'></a>

## 项目概览与三层架构

### 相关页面

相关主题：[安装路径、CLI 命令与模型路由向导](#page-install-cli), [核心框架：Recipes、Universal Rules、Roles、Hooks 与 Anti-patterns](#page-framework)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/lee77840/omniconductor/blob/main/README.md)
- [VISION.md](https://github.com/lee77840/omniconductor/blob/main/VISION.md)
- [AGENTS.md](https://github.com/lee77840/omniconductor/blob/main/AGENTS.md)
- [docs/ARCHITECTURE.md](https://github.com/lee77840/omniconductor/blob/main/docs/ARCHITECTURE.md)
- [docs/PHILOSOPHY.md](https://github.com/lee77840/omniconductor/blob/main/docs/PHILOSOPHY.md)
- [docs/COMPARISON.md](https://github.com/lee77840/omniconductor/blob/main/docs/COMPARISON.md)
- [package.json](https://github.com/lee77840/omniconductor/blob/main/package.json)
</details>

# 项目概览与三层架构

## 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 串联起来。

```mermaid
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/`，对外暴露四个核心子命令：

| 子命令 | 职责 | 关键产物 |
| --- | --- | --- |
| `init` | 首次安装模型向导，聚合 6 个 adapter | `.conductor/model-routing.json` |
| `install` | 物化纪律文件并写入 manifest | `.conductor-manifest.json` |
| `doctor <target>` | 只读健康检查（manifest 有效性 / 版本漂移 / 文件完整性 / 失效遗留路径 等 7 组） | 结构化报告 |
| `uninstall` | 基于 SHA-256 比对，安全回滚被改写的文件 | 受控文件删除 |

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 的核心契约。

---

<a id='page-install-cli'></a>

## 安装路径、CLI 命令与模型路由向导

### 相关页面

相关主题：[项目概览与三层架构](#page-overview), [清单安全、卸载、Token 度量与故障排查](#page-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [bin/omniconductor.js](https://github.com/lee77840/omniconductor/blob/main/bin/omniconductor.js)
- [bin/doctor.js](https://github.com/lee77840/omniconductor/blob/main/bin/doctor.js)
- [bin/model-routing.js](https://github.com/lee77840/omniconductor/blob/main/bin/model-routing.js)
- [bin/path-safety.js](https://github.com/lee77840/omniconductor/blob/main/bin/path-safety.js)
- [bin/claude-hookify.js](https://github.com/lee77840/omniconductor/blob/main/bin/claude-hookify.js)
- [package.json](https://github.com/lee77840/omniconductor/blob/main/package.json)
- [lib/adapters/*.js](https://github.com/lee77840/omniconductor/blob/main/lib/adapters)
- [lib/manifest.js](https://github.com/lee77840/omniconductor/blob/main/lib/manifest.js)
</details>

# 安装路径、CLI 命令与模型路由向导

omniconductor 是一个面向六种代理 CLI（npx、Claude、Cursor、Continue、Roo Code、Codex 等适配器）的统一安装与运行时协调器。本页聚焦三个紧密相关的子系统：**安装路径与 manifest 落盘位置**、**CLI 命令家族**（`init` / `doctor` / 模型路由），以及 **v1.1.0 引入的"一次性六工具模型路由向导"**。

## 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` 入口分发，目前公开的核心命令如下：

| 命令 | 作用 | 引入版本 |
|---|---|---|
| `omniconductor init [target]` | 在目标目录落盘 manifest 与各适配器产物 | 早期 |
| `omniconductor doctor <target>` | 只读健康检查，分 7 组（manifest 合法性、版本漂移、文件完整性、stale legacy 路径等） | v0.8.0 |
| 模型路由向导（`init` 内嵌） | 一次性为六工具配置 Tier 1/2/3 映射 | v1.1.0 |

`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` 提交进仓库，整套映射即可重建。

```mermaid
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]()

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

---

**小结**：路径安全 → manifest 契约 → CLI 命令族 → 路由向导，构成了 omniconductor 从"装进去"到"配得对"再到"看得见"的完整闭环。社区关注的核心——manifest 准确性、卸载安全性、路由可重现性——都通过这一分层得到了对应处理。

---

<a id='page-framework'></a>

## 核心框架：Recipes、Universal Rules、Roles、Hooks 与 Anti-patterns

### 相关页面

相关主题：[项目概览与三层架构](#page-overview), [清单安全、卸载、Token 度量与故障排查](#page-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [core/README.md](https://github.com/lee77840/omniconductor/blob/main/core/README.md)
- [core/universal-rules/README.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/README.md)
- [core/universal-rules/workflow.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/workflow.md)
- [core/universal-rules/quality-gates.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/quality-gates.md)
- [core/universal-rules/spec-as-you-go.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/spec-as-you-go.md)
- [core/universal-rules/operations.md](https://github.com/lee77840/omniconductor/blob/main/core/universal-rules/operations.md)
</details>

# 核心框架：Recipes、Universal Rules、Roles、Hooks 与 Anti-patterns

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 进一步划分为四个子文件，构成一个闭合的工作循环：

| 子文件 | 职责 | 关键约束 |
|---|---|---|
| `workflow.md` | 工作流阶段划分（计划→执行→验证→反思） | 必须显式声明阶段，禁止跨阶段短路 |
| `quality-gates.md` | 质量门禁 | 完成判定必须由外部信号给出，不可由模型自我判定 |
| `spec-as-you-go.md` | 边走边规范 | 每完成一个子目标立刻回写 spec，禁止集中补写 |
| `operations.md` | 操作纪律 | 包括 git-hygiene、循环工程（loop-engineering）等共享仓库与受控循环规则 |

资料来源：[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"等已知失败模式。

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

```mermaid
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，做到"默认安全、按需增强"。

---

<a id='page-ops'></a>

## 清单安全、卸载、Token 度量与故障排查

### 相关页面

相关主题：[安装路径、CLI 命令与模型路由向导](#page-install-cli), [核心框架：Recipes、Universal Rules、Roles、Hooks 与 Anti-patterns](#page-framework)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/manifest-safety.sh](https://github.com/lee77840/omniconductor/blob/main/tools/manifest-safety.sh)
- [tools/check-stale-tokens.sh](https://github.com/lee77840/omniconductor/blob/main/tools/check-stale-tokens.sh)
- [tools/check-framework-purity.sh](https://github.com/lee77840/omniconductor/blob/main/tools/check-framework-purity.sh)
- [tools/check-adapter-metadata.sh](https://github.com/lee77840/omniconductor/blob/main/tools/check-adapter-metadata.sh)
- [tools/measure-tokens.sh](https://github.com/lee77840/omniconductor/blob/main/tools/measure-tokens.sh)
- [tools/live-verify.sh](https://github.com/lee77840/omniconductor/blob/main/tools/live-verify.sh)
</details>

# 清单安全、卸载、Token 度量与故障排查

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 流水线用作"金丝雀"。

| 工具 | 类型 | 触发时机 | 主要防御目标 |
|---|---|---|---|
| `manifest-safety.sh` | 安装/卸载内置 | 每次 install & uninstall | 校验和漂移、误删用户文件 |
| `check-stale-tokens.sh` | CI | PR 与 release | 旧 token 漏改、版本号失同步 |
| `check-framework-purity.sh` | CI | PR | 适配器相互污染 |
| `check-adapter-metadata.sh` | CI | PR | 元数据与 manifest 不一致 |
| `measure-tokens.sh` | 手动/CI | 模式裁剪评估 | 误把重型规则塞进 minimal |
| `live-verify.sh` | 手动/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 校验器现在共享同一份"什么算合规"的判定表。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: lee77840/omniconductor; human_manual_source: deepwiki_human_wiki -->