# 齐衡 QIHENG — 设计完整性控制平面

版本：`1.1.17`

[英文版](README.md) · [核心流程与术语](TERMINOLOGY.md) · [商用能力目录](CAPABILITIES.md) · [企业落地](ENTERPRISE.md) · [安全策略](SECURITY.md) · [支持策略](SUPPORT.md) · [品牌规范](BRAND.md) · [执行契约](INSTRUCTION.md) · [本体模型](docs/ONTOLOGY.md) · [常见问题](docs/FAQ.md) · [更新日志](CHANGELOG.md)

> **在璇玑玉衡，以齐七政。**
> *Zài xuán jī yù héng，yǐ qí qī zhèng。*

**以证据为衡，使设计、实现、验证与准入归于一致。**

齐衡的核心流程可以概括为：**输入设计规格，提取实现必须满足的设计要求，检查
设计与实现是否一致；发现缺口后执行最小修复，再用绑定当前候选版本的证据完成
验证闭环。** “设计要求、BDD 场景、实现位置、问题、验证、证据和质量门禁”等概念见
[核心流程与术语表](TERMINOLOGY.md)。

“齐衡”取意于《尚书·舜典》。“齐”表示校正、对齐，“衡”表示观测、衡量与
校准：以统一尺度观察研发交付体系，发现偏差后从最早受影响边界重新校准。
完整品牌口径见[品牌规范](BRAND.md)。

齐衡 QIHENG 是一套可移植的设计完整性控制平面，用于证明代码仍然符合
权威设计意图。它支持 Codex、Claude Code、OpenCode、MiMo Code、BitFun 和
兼容 Claude Code 文件协议的通用 Coding Agent，并可将 OpenSpec、设计文档、
接口契约、数据结构、产品需求或行为场景文件作为设计源。

## 它与普通多智能体流程的区别

- **可执行交付保障框架，而不是检查清单。** 候选版本身份凭证、类型化门禁图、依赖闭合、显式适用性和内容寻址证据共同计算交付就绪度。
- **共享本体，而不是互相隔离的智能体总结。** 需求、场景、实现单元、差距、修复、
  验证和证据进入同一张可追溯语义图。
- **受治理的修改。** 角色受限的动作和类型化补丁先进入 SHA-256 链式台账，
  再通过协调操作改变本体状态。
- **失败即关闭的证据。** 设计源、实现和验证证据都做内容寻址；文件变化或丢失会阻断通过结论。
- **验证因果性。** 绿色结果绑定本次实际消费的设计源与实现单元
  哈希，旧日志不能批准新代码。
- **可复核的最终结果。** 报告和最终证明文件将结论绑定到检查状态、操作记录、
  制品、不变量和残余风险。
- **领导视角与审计证据同源。** 高层交付保障驾驶舱直接从机器状态生成交付决定、保障覆盖率、设计交付数字主线、风险阻断项和可下钻证据编号。

因此，项目的差异不在智能体数量，而在设计、实现、验证和最终结论之间存在一条
受治理、可检查、可失效的证据链。

QIHENG 按证据职责组织角色，而不是追求智能体数量：

- **检查准备**：确认以哪份设计为准、有哪些设计要求、是否存在冲突以及影响哪些内容。
- **构建域**：检查、修复并验证有来源依据的一致性差距。
- **裁决域**：挑战高风险主张、审计证据新鲜度，并作出绑定候选版本的一致性与准入决定。

编排器依据当前风险选择最小适用评审组。没有独立假设、产物、下游消费者和决定权的新增智能体，不会增加可信度。

## 三分钟快速开始

需要 Node.js 20 或更高版本。

```text
npx dic-workflow-kit@1.1.17 install
```

为保持兼容，已发布的 npm 包名继续使用 `dic-workflow-kit` 和
`@tonyclaw/dic-workflow-kit`。全局安装后同时提供首选命令 `qiheng` 和兼容命令
`dic-workflow-kit`。

默认 `full` 能力包安装全部 21 个 Skills 和 19 个 SubAgents。企业可以先查看
机器可读产品物料表，再按场景安装自动补齐依赖的能力包：

```text
qiheng catalog
qiheng catalog --json
qiheng install --host coding-agent --pack design
```

`design` 会自动带上 `foundation`；能力包、职责、最小权限和商用验收基线见
[商用能力目录](CAPABILITIES.md)。

在目标仓库中重启编码智能体，然后使用产品总入口：

```text
使用 $qiheng 以审计模式处理当前规格或变更。
```

对应的命令行入口是 `qiheng start --root . --mode audit`。已知入口时增加
`--change <id>` 或 `--spec <path>`，之后使用 `qiheng status`、`qiheng next`
和 `qiheng resume`。总入口会复用既有编排器和 Harness，用户不再需要记住内部
组件名称。

优先查看 `reports/final-consistency-report.md`、`reports/FINAL_RESULT.json`
和 `reports/ontology-report.md`。终态只使用 `PASS`、`PARTIAL`、`BLOCKED`
或 `FAIL`；测试变绿本身不等于通过。

项目画像生成后，启动可执行交付保障框架：

```text
qiheng harness-init --root .
qiheng harness-check --root . --json
qiheng harness-report --root .
```

候选文件与门禁证据采用有界并发哈希，并在单次核验中按路径去重。默认并发度为
`8`；资源受限或高性能构建机可通过 `QIHENG_IO_CONCURRENCY=1..32` 调整，
不影响候选版本和证据哈希语义。

Harness 会从依赖关系计算可运行批次。只读门禁以 `PARALLEL_READ` 批次并行暴露；
包含源码修复职责的批次以 `EXCLUSIVE_WRITE` 独占执行。`qiheng next --json`
同时返回 `executionMode`、`runnableGates` 和 `remainingBatches`。入口初始化、恢复、
门禁记录使用仓库级控制锁，避免多个进程覆盖同一份运行记录。

成功门禁会写入 `reports/.qiheng-cache/gates/`。缓存键绑定完整门禁定义、项目画像
和门禁实际使用的输入范围。只修改实现时，如果设计文件内容未变化，设计依据、跨规格和规格
门禁可跨 Candidate 复用，不再重新执行设计扫描；实现、测试与下游准入仍按依赖
失效。复用前会重新读取证据、重算 SHA-256 并核对 SubAgent 交接，任何设计源、
画像、证据或交接漂移均转为缓存未命中。跨 Candidate 复用结果明确记录
`reuseMode: UNCHANGED_INPUTS` 和原 Candidate 哈希。

`reports/harness-report.md` 是面向领导的高层交付保障驾驶舱：用一页高密度视图展示交付决定、候选版本身份凭证、保障覆盖率、设计交付数字主线、门禁矩阵和精确阻断项。

## 文档导航

| 文档 | 用途 |
| --- | --- |
| [核心流程与术语](TERMINOLOGY.md) | 一句话核心流程，以及设计要求、BDD 场景、实现位置、问题、验证、证据和质量门禁等常用术语 |
| [商用能力目录](CAPABILITIES.md) | 产品边界、能力包、组件职责、安装控制和验收基线 |
| [执行契约](INSTRUCTION.md) | 完整工作流、证据、交接和终态规则 |
| [内部数据模型](docs/ONTOLOGY.md) | 检查对象、关系、操作记录、质量门禁与最终证明文件 |
| [交付保障执行框架](docs/HARNESS.md) | 候选版本身份凭证、可执行门禁图、设计交付数字主线、证据记录和高层驾驶舱 |
| [常见问题](docs/FAQ.md) | 多智能体通信、知识挂载、行为驱动开发和产品问题 |
| [企业落地指南](ENTERPRISE.md) | 四层企业架构、生产准入清单、试点指标和九十天路线 |
| [安全策略](SECURITY.md) | 信任边界、漏洞报告、威胁模型和生产安全基线 |
| [支持策略](SUPPORT.md) | 支持层级、兼容范围、问题信息和升级边界 |
| [专有分发声明](NOTICE.md) | 公开分发与商业生产授权的边界 |
| [发布指南](docs/RELEASING.md) | 维护者使用的双 npm 包发布流程 |
| [更新日志](CHANGELOG.md) | 版本历史 |

## 企业采用

齐衡公共分发包适合功能了解和受控试点；企业生产使用还需要组织级身份、
权限、审批、密钥、不可变证据存储和正式商业协议。建议先阅读
[企业落地指南](ENTERPRISE.md)，并在发布前执行：

```text
npm run release:check
```

正式企业商用版本必须额外通过 `npm run commercial:check`。当前专有分发包
保持 `UNLICENSED`，该检查会有意阻断，直到法务确认正式商业许可并更新许可
元数据。技术发布成功不等于已经获得生产授权。

齐衡明确不重复建设企业身份、审批、签名、合规或不可变存储平台。仓库策略
要求的外部结论可以作为准入证据挂载，但企业系统仍是这些结论的权威来源。

## 通过 npm 安装

`dic-workflow-kit` 与 `@tonyclaw/dic-workflow-kit` 始终发布相同版本和相同
运行时载荷。npm 包完整包含 21 个技能和 19 个子智能体，并支持 Codex、
Claude Code、OpenCode、MiMo Code、BitFun，以及兼容 Claude Code 文件协议的
通用 Coding Agent。

Codex 仍是默认宿主，原命令保持兼容：

```text
npx dic-workflow-kit@1.1.17 install
```

安装到其他宿主时显式指定 `--host`：

```text
npx dic-workflow-kit@1.1.17 install --host claude-code
npx dic-workflow-kit@1.1.17 install --host opencode
npx dic-workflow-kit@1.1.17 install --host mimo-code
npx dic-workflow-kit@1.1.17 install --host bitfun
npx dic-workflow-kit@1.1.17 install --host coding-agent --dry-run
```

默认是用户级安装；若只希望当前仓库使用，则增加 `--scope project`：

```text
npx dic-workflow-kit@1.1.17 install --host claude-code --scope project
npx dic-workflow-kit@1.1.17 install --host opencode --scope project
npx dic-workflow-kit@1.1.17 install --host mimo-code --scope project
npx dic-workflow-kit@1.1.17 install --host bitfun --scope project
npx dic-workflow-kit@1.1.17 install --host coding-agent --scope project
```

| 宿主 | 用户级目录 | 项目级目录 |
| --- | --- | --- |
| Codex | `~/.agents/plugins/plugins/dic-workflow-kit`，并注册插件市场 | 当前插件安装器不提供项目级模式 |
| Claude Code | `~/.claude/{skills,agents}` | `.claude/{skills,agents}` |
| OpenCode | `~/.config/opencode/{skills,agents}` | `.opencode/{skills,agents}` |
| MiMo Code | 平台配置根目录下的 `mimocode/{skills,agents}` | `.mimocode/{skills,agents}` |
| BitFun | 平台原生的 BitFun 数据/配置目录 | `.bitfun/{skills,agents}` |
| 通用 Coding Agent | 自动探测常见 CodeAgent 目录，默认 `~/.codeagent/{skills,agents}` | 自动探测 `.codeagent`、`.code-agent`、`.coding-agent` |

Windows 上 MiMo Code 的用户级根目录为 `%LOCALAPPDATA%\mimocode`；适用时也会读取 `MIMOCODE_HOME` 和 `XDG_CONFIG_HOME`。BitFun 的用户级技能安装到平台数据目录下的 `BitFun/skills`，子智能体安装到 BitFun 配置根目录下的 `bitfun/agents`；项目级安装统一使用 `.bitfun`。通用 Coding Agent 复用 Claude Code 的 Skill 与 Subagent 元数据约定，并依次识别 `CODING_AGENT_HOME`、`CODE_AGENT_HOME`、`CODEAGENT_HOME` 和常见目录。若发现多个候选目录，安装器会拒绝猜测并要求显式指定。安装器以仓库中的 `agents/` 为唯一来源，并按宿主转换子智能体元数据，避免维护多套重复内容。

对于 BitFun，安装器会生成其原生自定义智能体结构。只有
`code-repairer` 可以修改源码；`profile-builder` 与 `validation-runner`
可写入职责范围内的画像或验证产物。需要核验证据的门禁角色按职责获得命令执行能力。

也可以先全局安装命令行工具：

```text
npm install --global @tonyclaw/dic-workflow-kit@1.1.17
qiheng install --host opencode
```

也可以直接从仓库安装同一个命令行工具：

```text
npm install --global git+ssh://git@gitcode.com/TonyClaw/DICWorkflowKit.git
qiheng install
```

使用 `--dry-run` 预演目标目录，使用 `--install-root <path>` 指定宿主根目录；若目标产品将两类资源分开存放，还可分别使用 `--skills-root <path>` 和 `--agents-root <path>`。Codex 仍兼容 `--marketplace-root <path>`。首次创建技能或智能体目录后，请重启或重新加载对应编码智能体会话。

目录不明确时，建议先执行：

```text
npx dic-workflow-kit@1.1.17 install --host coding-agent --dry-run
```

确认 CodeAgent 的配置根目录后，执行：

```text
npx dic-workflow-kit@1.1.17 install --host coding-agent --install-root <CodeAgent配置根目录>
```

### Coding Agent 实际安装内容

`--install-root` 指定的是齐衡在目标 Coding Agent 中的安装根目录，不是项目源码目录，
也不是 npm 的全局安装目录。未显式指定时，用户级安装默认使用
`~/.codeagent`，项目级安装默认使用 `<项目目录>/.codeagent`；如果安装器发现已有
`.code-agent` 或 `.coding-agent`，则使用已存在的唯一候选目录。

默认结构如下：

```text
<Coding Agent root>/
├─ .dic-workflow-kit-install.json   # 版本、目标目录、受管文件与 SHA-256
├─ skills/                          # 21 个可复用方法，包含产品总入口
└─ agents/                          # 19 个可调度子智能体
```

`skills/` 安装仓库中完整的 Skill 目录及其配套资源：

```text
knowledge-bdd                    quality-evidence-audit
knowledge-change-impact          quality-repository-gate
knowledge-openspec               quality-review-orchestrator
knowledge-repair-distill         quality-spec-review
qiheng
quality-adversarial-challenge    quality-sr-ar-review
quality-ci-gate                  workflow-core
quality-code-review              workflow-harness
quality-consistency-gate         workflow-intake
quality-cross-spec-consistency   workflow-profile
quality-dt-review                workflow-repair
```

`agents/` 安装以下子智能体，并将其元数据转换为 Claude Code 兼容格式：

```text
adversarial-challenger.md        impact-analyst.md
architecture-reviewer.md         impl-inspector.md
ci-gatekeeper.md                 profile-builder.md
code-quality-reviewer.md         repair-planner.md
code-repairer.md                 repository-gatekeeper.md
contract-oracle.md               semantic-conflict-auditor.md
evidence-auditor.md              spec-quality-reviewer.md
final-reviewer.md                spec-reader.md
flow-auditor.md                  test-quality-reviewer.md
                                 validation-runner.md
```

Skill 回答“如何执行”，Subagent 负责“由谁判断和交付”，安装根目录中的清单负责
完整性检查与安全卸载。如果目标产品将两类资源分开存放，可以分别指定：

```text
qiheng install --host coding-agent \
  --install-root <齐衡状态目录> \
  --skills-root <目标技能目录> \
  --agents-root <目标智能体目录>
```

此时安装根目录主要保存安装清单，Skill 和 Subagent 分别写入显式目录。后续运行
`doctor` 或 `uninstall` 时应传入相同的三个目录参数。

### 安装后第一眼理解流程

交互式安装成功后，终端会直接显示 QIHENG 的核心流程图，包括候选版本冻结、
检查—修复—验证反馈环、专业质量保障、一致性签署以及
`READY_FOR_ADMISSION → 仓库准入 → READY` 两阶段闭环。使用 `--json`
时不会混入流程图，自动化输出仍保持纯 JSON。

生成可离线浏览、打印和分享的高密度 HTML 泳道图：

```text
npx dic-workflow-kit@1.1.17 guide
```

全局安装命令行工具后可以简写为 `qiheng guide`。默认写入当前项目的
`.qiheng/guide/index.html`。也可以指定位置：

```text
npx dic-workflow-kit@1.1.17 guide --output docs/qiheng-flow.html
```

终端图和 HTML 图由同一份流程定义生成，确保阶段、角色、证据与终态不会出现
两套描述。

### 检查、升级与卸载

每次成功安装都会写入 `.dic-workflow-kit-install.json`，记录包版本、宿主目录、受管理文件及其 SHA-256。使用 `doctor` 检查是否存在文件缺失或被修改：

```text
qiheng doctor --host bitfun --scope project
qiheng doctor --host opencode
```

只移除当前安装清单管理的文件：

```text
qiheng uninstall --host bitfun --scope project
```

安装器不会默认覆盖未受管理或已被本地修改的文件；卸载器也不会默认删除已修改的受管理文件。安装、升级与卸载使用跨进程锁和磁盘持久事务；进程异常退出后，下一次生命周期操作会隔离陈旧锁、校验备份哈希并恢复未完成事务。请先检查报告中的路径，仅在确认这些修改可以丢弃时使用 `--force`。`--force` 不会关闭真实路径边界检查。`install`、`doctor` 和 `uninstall` 都支持 `--json`，可供持续集成或自动化脚本消费。

## 用户如何使用

### 1. 在项目根目录启动编码智能体

安装完成后，进入需要检查的代码仓库，重新启动 Codex、Claude Code、OpenCode、MiMo Code 或 BitFun。第一次安装新的技能或智能体目录时，已有会话可能无法立即发现它们。

```text
cd /path/to/your-project
```

### 2. 用自然语言启动工作流

下面这条总入口提示词适用于全部受支持宿主：

```text
使用 $qiheng 以交付模式处理当前规格或变更。
告诉我当前阶段、下一门禁、下一 Skill/Agent、阻塞项和证据。
```

`$qiheng` 是公开总入口；`quality-review-orchestrator` 是内部门禁编排器，
`workflow-harness` 是唯一执行状态权威。

如果只希望审计、不允许修改代码：

```text
使用 QIHENG 审计当前项目，但不要修改任何文件。
输出设计要求、实现问题、证据位置、修复建议和剩余风险。
```

如果希望检查并修复：

```text
使用 QIHENG 检查并修复当前项目。
仅修复能够追溯到权威设计源的缺口；每次修改后执行相关验证，
验证失败时停止扩散修改并记录阻塞原因。
```

### 3. 检查一个 OpenSpec 变更

明确给出变更编号，可以减少搜索范围并避免把历史变更当成当前事实：

```text
使用 QIHENG 检查 OpenSpec 变更
2026-06-09-add-ts-local-skill-source。
以该变更的提案、设计、任务和增量规格为入口，
同时核对当前稳定规格、实现和测试，输出设计要求矩阵、实现缺口和验证结论。
```

如果变更已归档，工作流会将归档内容作为历史上下文，并以当前已经提升的稳定规格为权威基线。

### 4. 必要时显式调用内部技能

只有诊断或定向执行时才需要显式调用内部技能：

```text
/workflow-core
```

也可以在提示词中直接写出需要使用的技能：

```text
使用 workflow-core、workflow-intake、workflow-profile 和
knowledge-openspec 检查当前 OpenSpec 变更。
```

不需要手工逐个启动 19 个子智能体。主智能体应按照证据依赖关系选择角色，并保证每个委派都输出被下游消费的标准交接。

### 5. 查看结果

默认应重点查看：

| 文件 | 用途 |
| --- | --- |
| `reports/qiheng-entry.json` | 产品总入口意图：模式和仓库/规格/变更指针，不保存第二套门禁状态 |
| `reports/qiheng-entry.md` | 面向人的当前阶段和下一动作视图 |
| `reports/intake-evidence.json` | 项目画像归一化之前发现的原始仓库事实 |
| `reports/project-profile.json` | 项目结构、设计源、保护路径和验证命令 |
| `reports/handoffs/` | 门禁消费的标准 `dic.agent-handoff.v1` 子智能体交接 |
| `reports/contract-obligations.md` | 人可读的设计要求及其来源 |
| `reports/implementation-gaps.md` | 已确认的实现缺口 |
| `reports/repair-plan.md` | 带来源锚点和停止条件的修复计划 |
| `reports/quality/` | 适用性计划、门禁运行历史、失效原因和候选版本绑定决定 |
| `reports/final-consistency-report.md` | 最终一致性结论与残余风险 |
| `reports/FINAL_RESULT.json` | 机器可读的最终状态 |
| `logs/trace/` | 入口识别、委派、修改和验证证据 |

设计一致性终态只使用 `PASS`、`PARTIAL`、`BLOCKED` 或 `FAIL`，并与专项质量状态和
仓库准入状态分开读取。设计一致性通过表示证据链成立，不只是“测试刚好通过”，
也不代表候选版本自动获得准入。

### 常见问题

- **找不到技能或子智能体**：重启编码智能体，并使用 `--dry-run` 检查安装目标。
- **检查安装完整性**：使用与安装时相同的宿主、安装范围和根目录参数运行 `doctor`。
- **安装提示冲突**：先检查报告中的文件，保存或重命名用户内容后再考虑 `--force`。
- **卸载拒绝删除修改文件**：可以保留当前安装；只有备份修改后才应使用 `--force`。
- **只想当前仓库使用**：Claude Code、OpenCode、MiMo Code、BitFun 安装时增加项目范围参数 `--scope project`。
- **项目没有 OpenSpec**：仍可使用设计文档、接口说明、数据结构、项目说明或产品需求作为权威设计源。
- **缺少验证工具**：记录缺失的命令和环境原因，最终状态应为 `BLOCKED` 或 `PARTIAL`，不要伪造成功。
- **测试通过是否等于一致**：不等于。还必须确认需求、分支、状态迁移、副作用及集成流程符合设计。

维护者请参考[双 npm 包发布指南](docs/RELEASING.md)。

## 为什么需要它

编码智能体很擅长修改代码，但容易围绕局部报错、公开样例或最近一次失败进行优化。对于设计先行的项目，更重要的问题是：

> 当前实现是否仍然满足已确认的设计契约？

QIHENG 将这个问题转换为一条可重复执行的证据链：

1. 定位权威设计源。
2. 生成项目画像。
3. 建立设计要求与实现区域的映射。
4. 审计流程与实现缺口。
5. 规划有来源依据的小修复。
6. 使用项目声明的命令验证。
7. 记录证据、变更文件、残余风险和最终产物。

## 目录结构

| 路径 | 作用 |
| --- | --- |
| `INSTRUCTION.md` | 通用执行契约，定义设计—实现一致性工作流。 |
| `skills/` | 工作流控制技能和可插拔知识包。 |
| `agents/` | 按阶段工作的子智能体，负责生产和消费证据。 |
| `adapters/` | OpenSpec、BDD、通用仓库和受支持编码智能体的适配层。 |
| `runtime/` | 检查状态计算、操作记录、完整性检查、报告和最终证明文件的源码实现。 |
| `schemas/` | 项目信息、检查状态、操作、交接、最终证明文件和最终结果的数据结构约束。 |
| `scripts/` | 仅依赖 Python 标准库的辅助脚本。 |
| `docs/` | 本体参考、常见问题、发布指南和当前产品演示文稿。 |
| `examples/` | 不同项目形态的使用示例。 |

## 能力启用规则

通用的是选择机制，不是固定运行全部能力。QIHENG 先根据设计源、仓库结构、变更范围和风险生成项目画像，再决定加载哪些技能和子智能体；未命中的能力不加载、不执行，也不占用上下文。

| 属性 | 含义 | 启用原则 |
| --- | --- | --- |
| **必需** | 设计—实现一致性主流程的基础能力 | 每个项目都执行，形成可追溯的最小闭环。 |
| **按需** | 面向特定项目结构、工具或风险的专项能力 | 项目画像命中适用条件时才加载；例如未触及架构、接口、数据、依赖或领域边界时，不启用架构专项检查。 |
| **触发** | 面向变化、问题或异常事件的响应能力 | 发生输入变化、发现不一致、验证失败或出现高风险争议时启用，完成处理后只重跑受影响门禁。 |

## 技能：按首次介入点索引

下表只是索引，不是一条必须串行执行的流水线。技能按最早介入点排列；其输入或候选版本发生变化时，原决定会失效。

| 顺序 | 技能 | 属性 | 类型 | 介入阶段 | 主要作用 |
| --- | --- | --- | --- | --- | --- |
| 00 | `qiheng` | **必需** | 产品总入口 | 用户请求到交付终态 | 启动、查询和续跑全流程，并把编排和状态委托给既有控制面。 |
| 01 | `quality-review-orchestrator` | **必需** | 质量控制 | 导入规格到提交前准入 | 维护适用性计划、门禁依赖、失效与重跑，并保留不同层次的交付结论。 |
| 02 | `workflow-core` | **必需** | 工作流机制 | 设计一致性全流程 | 定义事实源优先级、本体、证据规则、交接、终态和产物契约。 |
| 03 | `workflow-harness` | **必需** | 可执行控制平面 | 项目画像生成后到仓库准入 | 冻结候选版本、生成门禁拓扑、记录证据化决定、传播失效并计算交付就绪度。 |
| 04 | `workflow-intake` | **必需** | 工作流方法 | 子智能体启动前 | 识别设计源、实现目录、测试目录、保护路径、验证命令和适配器线索。 |
| 05 | `workflow-profile` | **必需** | 工作流方法 | 子智能体启动前 | 将入口识别证据规范化为所有下游角色共同消费的项目画像。 |
| 06 | `knowledge-openspec` | **按需** | 知识包 | 读取设计源时；检测到 OpenSpec 才加载 | 理解提案、设计、规格、场景、任务、活动变更和已归档能力。 |
| 07 | `knowledge-bdd` | **按需** | 知识包 | 存在 `.feature` 或需要行为覆盖时 | 解释已挂载的行为场景契约，或从已确认设计中生成受来源约束的“前提—行为—结果”场景。 |
| 08 | `knowledge-change-impact` | **触发** | 工作流方法 | 输入变化、证据过期或修复后 | 追踪语义影响，只使真正依赖的证据和门禁失效。 |
| 09 | `quality-cross-spec-consistency` | **按需** | 设计质量检查 | 存在多个相关规格或基线时 | 检查直接相关的基线和设计文件是否存在规则冲突。 |
| 10 | `quality-spec-review` | **按需** | 设计质量门 | 需要独立规格质量检查时 | 检查规格完整性、一致性、可测试性、可追溯性和无依据声明；规格变化后重跑。 |
| 11 | `quality-sr-ar-review` | **按需** | 架构质量门 | 需求、架构或领域边界变化时 | 检查需求到设计覆盖、归属、接口、数据/状态、质量属性和可实现性。 |
| 12 | `quality-ci-gate` | **按需** | 交付质量门 | 项目存在持续集成或交付检查时 | 定义必跑门禁、耗时与不稳定测试策略、证据留存并核验候选版本。 |
| 13 | `workflow-repair` | **触发** | 工作流方法 | 发现设计与实现不一致时 | 控制有来源的一致性检查、最小修复、验证和收敛。 |
| 14 | `knowledge-repair-distill` | **触发** | 知识包 | 修复反复、验证失败或模型跑偏时 | 提供缺口分类、收敛策略、模型引导提示和验证门槛。 |
| 15 | `quality-code-review` | **按需** | 实现质量门 | 代码发生变化或实现风险较高时 | 审查契约影响、架构、安全、性能、可靠性和可维护性。 |
| 16 | `quality-dt-review` | **按需** | 测试质量门 | 需要检查测试覆盖、断言或缺陷发现能力时 | 检查需求/风险覆盖、负向路径、断言强度、确定性和变异敏感度。 |
| 17 | `quality-adversarial-challenge` | **触发** | 独立挑战门 | 高风险或通过结论存在争议时 | 按风险选择最小挑战集，并记录可复现反例。 |
| 18 | `quality-evidence-audit` | **按需** | 证据完整性门 | 需要严格审计或可复现交付时 | 验证主张是否当前、可复现、内容寻址且绑定候选版本。 |
| 19 | `quality-consistency-gate` | **必需** | 设计一致性终态门 | 证据就绪后；仓库准入前 | 独立签署候选版本的设计、实现、测试和证据一致性终态。 |
| 20 | `quality-repository-gate` | **按需** | 提交前准入门 | 需要决定提交、合并或发布时 | 决定准入、带后续事项准入或拒绝，并将完整门禁闭合到 `READY`。 |

技能合计：**7 个必需、10 个按需、4 个触发，共 21 个**。

## 子智能体：设计一致性循环中的职责顺序

这些子智能体实现开发完成后的设计—实现一致性循环。这里的依赖顺序不代表外围质量门
只执行一次，也不要求无依赖的工作全部串行。

| 步骤 | 子智能体 | 属性 | 阶段 | 消费的输入 | 主要产物 |
| --- | --- | --- | --- | --- | --- |
| 01 | `profile-builder` | **必需** | 项目画像确认 | 入口识别证据和仓库结构 | `reports/project-profile.json`、权威范围和语义候选 |
| 02 | `spec-reader` | **必需** | 事实源读取 | 项目画像和权威设计源 | 带文件锚点的需求摘要、保护路径和未决问题 |
| 03 | `semantic-conflict-auditor` | **按需** | 跨规格质询 | 多个相关规格、基线和权威根 | 成对引用的冲突与细化结论；不修改文件 |
| 04 | `contract-oracle` | **必需** | 设计要求确认 | 已确认需求、场景和冲突结论 | 有来源依据的设计要求清单 |
| 05 | `spec-quality-reviewer` | **按需** | 规格质量 | 需要独立质量检查的规格和来源锚点 | 独立的完整性、一致性和可测试性决定 |
| 06 | `architecture-reviewer` | **按需** | 架构质量 | 发生变化的架构、接口、数据、依赖或领域边界 | 独立的架构可实现性决定 |
| 07 | `impact-analyst` | **触发** | 变更影响分析 | 发生变化的设计、实现或测试及其依赖 | 失效决策与最小安全重跑计划 |
| 08 | `flow-auditor` | **按需** | 流程完整性审计 | 涉及状态机、生命周期、异步或跨系统流程的设计要求 | 生命周期、状态迁移、分支、副作用和集成流程审计 |
| 09 | `impl-inspector` | **必需** | 实现检查 | 已确认设计要求和适用的专项审计结果 | 实现缺口报告；不修改代码 |
| 10 | `repair-planner` | **触发** | 修复规划 | 已发现的不一致、保护路径和验证命令 | 包含来源锚点、停止条件和回退路径的小修复片段 |
| 11 | `code-repairer` | **触发** | 代码修复 | 已批准的修复片段 | 最小代码变更、变更文件证据和修复说明 |
| 12 | `code-quality-reviewer` | **按需** | 代码质量 | 代码变更或较高实现风险 | 独立的正确性、安全和可维护性决定 |
| 13 | `validation-runner` | **必需** | 验证执行 | 项目声明的命令和变更后实现 | `logs/trace/validation/` 下的内容寻址日志 |
| 14 | `test-quality-reviewer` | **按需** | 测试质量 | 存在测试或测试风险变化 | 独立的测试覆盖和强度决定 |
| 15 | `adversarial-challenger` | **触发** | 独立挑战 | 高风险或存在争议的通过结论、策略和证据 | 可证伪挑战与可复现反例；不修改文件 |
| 16 | `ci-gatekeeper` | **按需** | 交付门禁 | 项目存在持续集成或交付检查 | 持续集成计划与冻结候选版本核验决定 |
| 17 | `evidence-auditor` | **按需** | 证据完整性 | 严格审计或可复现交付所需的主张、证据和内容哈希 | 主张—证据矩阵及过期或无依据主张 |
| 18 | `final-reviewer` | **必需** | 设计一致性检查 | 当前证据、冲突、影响计划、验证结果和最终产物 | 与待检查版本绑定的一致性结论和最终证明文件；不决定是否允许提交 |
| 19 | `repository-gatekeeper` | **按需** | 提交门禁 | 需要决定提交、合并或发布的候选版本 | 允许提交、附带后续事项提交或拒绝提交 |

子智能体合计：**6 个必需、9 个按需、4 个触发，共 19 个**。

## 默认门禁生命周期

```text
导入规格
-> 入口识别 + 项目画像
-> 跨规格一致性检查
-> 规格评审
-> [影响架构或实现设计时执行系统需求与架构评审]
-> 持续集成门禁 [规划]

推进实现
-> 按已确认设计要求开发
-> [按风险触发专项质量门]*

设计一致性循环
-> 检查设计—实现差异
-> [规划修复 -> 实施修复 -> 验证]*
-> 影响分析与受影响证据失效
-> [使受影响证据失效并重跑相关门禁]*

提交前
-> [存在实质性失败假设时执行对抗挑战]
-> 持续集成门禁 [核验并冻结候选版本]
-> 证据审计 [候选版本绑定的主张新鲜度]
-> 最终一致性检查 [设计一致性 + 最终证明文件]
-> 执行框架 [准入前就绪]
-> 仓库准入门 [准入 / 带后续事项准入 / 拒绝]
-> 执行框架 [完整就绪]
```

`*` 表示按风险执行零次或多次。这是带反馈回路的门禁图，不是固定执行一次的智能体
链。跳过门禁必须记录不适用理由。规格、架构、实现、测试、测试夹具、流水线、
策略或候选版本发生变化时，依赖它的决定立即失效，并从最早受影响边界重跑。

必须分别保留设计一致性状态 `consistencyStatus`、专项质量状态 `qualityStatus` 和仓库
准入状态 `admissionStatus`。设计一致性通过只证明设计—实现一致，不代表所有质量域均通过，
也不直接等于仓库准入。适用性计划、门禁运行历史、失效原因和评审决策
应保存在 `reports/quality/` 下。

## 本体驱动的一致性

QIHENG 将一次运行建模为可移植的语义图，而不是互相独立的智能体总结。
`reports/ontology-snapshot.json` 保存类型化对象（设计源、需求、场景、实现单元、
缺口、修复动作、验证和证据）以及它们之间的明确关系。

每个对象都有稳定编号、生命周期和来源证据。智能体通过
`schemas/ontology-action.schema.json` 定义的受控动作改变状态。最终审查者根据
图上的不变量计算通过结论：有效设计要求必须有来源，需求必须有实现处置，设计要求必须有
当前验证证据，并且不能存在未关闭的阻断缺口。

本体默认以文件保存，不依赖图数据库，因此可跨 Codex、Claude Code、OpenCode、
MiMo Code 和 BitFun 使用；后续可以增加 SQLite 或图服务索引而不改变语义契约。

发布后的单文件命令行工具已内置动作校验和审计能力，但不会发布运行时源码。
这些本体命令要求工作流已经生成 `reports/ontology-snapshot.json`、
`reports/project-profile.json`；台账操作还需要
`reports/ontology-actions.jsonl`。它们负责完整性与证据校验，不替代最初由智能体
完成的入口识别：

```text
qiheng ontology-check --root . --status PASS
qiheng action-check --root . --action reports/actions/repair.json
qiheng action-record --root . --action reports/actions/repair.json
qiheng ontology-reconcile --root .
qiheng ontology-ledger-check --root . --json
qiheng ontology-evidence-check --root . --json
qiheng ontology-validation-check --root . --json
qiheng ontology-implementation-check --root . --json
qiheng ontology-query --root . --query impact --id <object-id>
qiheng ontology-drift --root .
qiheng ontology-plan --root . --json
qiheng ontology-explain --root . --id <object-id> --json
qiheng ontology-report --root . --status PASS
qiheng ontology-attest --root . --status PASS --summary "已验证"
qiheng ontology-attestation-check --root .
```

`action-record` 将带 SHA-256 的不可变记录追加到
`reports/ontology-actions.jsonl`，并拒绝越权角色、无效目标、缺失证据、
保护路径重叠和动作编号冲突。

新记录采用第二版台账：包含序号、前一记录哈希、基准快照修订、动作
哈希和整条记录哈希，可检测重排、插入、修改和过期状态落账，同时兼容连续的
第一版历史前缀。使用 `ontology-ledger-check` 查看链头和整文件哈希。

完成态动作必须携带声明式 `ontologyPatch`。每种动作只能增加被允许的对象、
关系和生命周期迁移。`ontology-reconcile` 会校验台账哈希、跳过已经应用的
动作、重放剩余补丁、重新计算不变量，并且只在候选状态完整有效时替换快照。

`ontology-query` 提供四类查询：未覆盖设计要求、开放差距、无证据验证，以及从指定
对象出发的有限深度影响链。

`ontology-evidence-check` 会验证当前验证所需的每个证据是否指向
项目内真实文件，以及当前字节是否匹配记录的 SHA-256。只有生命周期有效且
`properties.status: PASS` 的验证对象才能通过 `VERIFIED_BY` 满足通过条件。

`ontology-validation-check` 用来堵住“旧绿灯日志批准新代码”的漏洞。每个
验证对象必须记录 `executedAt`，并通过 `{ objectId, contentHash }` 绑定本次
运行实际消费的设计源与实现单元。输入缺失或哈希过期会阻断
通过结论，并使原最终证明文件失效。

`ontology-implementation-check` 会将每个必需实现单元与项目内文件及
记录的 SHA-256 比较。既有代码通过 `ObserveImplementation` 记录；
`ApplyRepair` 只表示获批修复实际创建或修改的实现。

`ontology-drift` 会将设计源当前内容与快照中的 SHA-256 来源记录进行比较；
变更或丢失的设计源返回非零状态，其对象 ID 可以直接用于影响链查询。

`ontology-plan` 将设计源、实现文件、证据漂移和影响链组合成最小重跑计划。
设计变化从入口识别与契约映射重跑，实现漂移从实现检查与验证重跑，
仅证据漂移则只重跑验证与最终评审。

生成或重放后的快照包含规范化 `snapshotRevision`。直接修改语义状态会导致修订
哈希失效；协调操作也会拒绝覆盖执行期间已经发生变化的快照。设计源漂移已经
接入通过门禁，因此旧的绿色验证证据不能批准已经变化的设计。

`ontology-explain` 会返回对象属性、来源、直接关系和有限深度证据链，便于说明
某个结论来自哪一行设计、对应哪个实现、差距、修复、验证和证据。

`ontology-report` 直接从快照生成高信息密度文档视图。
`ontology-attest` 生成内容寻址的终态证明，将结论绑定到快照修订、动作台账
哈希、设计源哈希、证据制品哈希、实现单元哈希和门禁结果；
`ontology-attestation-check` 会重新计算这些绑定，因此设计源、实现文件、
证据文件、台账、快照或证明被改动后都会失败关闭。
应将输出的 `contentHash` 保存到持续集成或发布元数据，并通过
`--expected-hash` 进行外部锚定；仅在同一文件内保存哈希只能证明完整性，
不能证明真实性。

## 行为驱动开发作为本体入口

源码辅助工具会识别常见的功能、行为、规格和测试目录中的 `.feature` 文件，
并支持英文及常见中文行为场景关键字：

- 功能映射为需求。
- 场景和场景大纲映射为场景对象。
- 背景步骤继承到每个场景。
- 示例表、标签、行号和来源哈希完整保留。
- `DERIVED_FROM` 连接设计源，`REFINES` 连接功能需求。

场景被解析不代表验证通过；仍需通过 `RunValidation` 和 `AttachEvidence` 挂载
当前执行证据。

显式选择某个 OpenSpec 变更时，只挂载被该变更引用的行为场景文件；
其他检测到的文件保持可发现，但不会静默扩大变更的设计要求范围。

## OpenSpec 适配重点

| OpenSpec 文件 | 使用方式 |
| --- | --- |
| `openspec/specs/**/spec.md` | 当前稳定能力要求和场景。 |
| `openspec/changes/**/proposal.md` | 变更意图。 |
| `openspec/changes/**/design.md` | 技术设计和约束。 |
| `openspec/changes/**/tasks.md` | 实现任务和完成证据。 |
| `openspec/changes/**/specs/**/spec.md` | 活跃变更中的增量需求。 |
| 已归档规格 | 历史上下文，不能覆盖当前有效规格。 |

## 默认输出契约

```text
reports/project-profile.json
reports/contract-obligations.json
reports/contract-obligations.md
reports/ontology-snapshot.json
reports/ontology-actions.jsonl
reports/ontology-report.md
reports/ontology-attestation.json
reports/implementation-gaps.md
reports/repair-plan.md
reports/final-consistency-report.md
reports/FINAL_RESULT.json
result/output.md
logs/trace/
```

适配器可以针对规格格式或编码智能体宿主扩展契约，但不改变核心
Skills/SubAgents 的职责边界。

## 平台无关要求

- 不硬编码本机绝对路径。
- 不假设 Windows、Linux、macOS、PowerShell、Bash 或 `cmd`。
- 从 `INSTRUCTION.md`、项目画像或适配器配置解析路径。
- Python 辅助工具只依赖标准库。
- `git`、`mvn`、`npm`、`pnpm`、`pytest`、`openspec` 等外部工具仅在验证需要时从目标环境 `PATH` 解析。
- 工具缺失属于环境证据，不等同于设计失败。

## 当前状态

QIHENG 已经是一套正式发布的跨宿主工作流包，具备安全安装生命周期、
OpenSpec 与行为驱动开发入口识别、本体治理动作、内容寻址验证、防篡改台账、自动报告
和最终证明文件。后续扩展应保持这些接口约定，并继续增强适配器、存储后端和
持续集成外部信任锚。