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

版本：1.1.17

英文版 · 核心流程与术语 · 商用能力目录 · 企业落地 · 安全策略 · 支持策略 · 品牌规范 · 执行契约 · 本体模型 · 常见问题 · 更新日志

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

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

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

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

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

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

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

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

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

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

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

三分钟快速开始

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

npx [email protected] install

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

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

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

design 会自动带上 foundation；能力包、职责、最小权限和商用验收基线见 商用能力目录。

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

使用 $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；测试变绿本身不等于通过。

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

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

文档导航

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

企业采用

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

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 仍是默认宿主，原命令保持兼容：

npx [email protected] install

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

npx [email protected] install --host claude-code
npx [email protected] install --host opencode
npx [email protected] install --host mimo-code
npx [email protected] install --host bitfun
npx [email protected] install --host coding-agent --dry-run

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

npx [email protected] install --host claude-code --scope project
npx [email protected] install --host opencode --scope project
npx [email protected] install --host mimo-code --scope project
npx [email protected] install --host bitfun --scope project
npx [email protected] 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 可写入职责范围内的画像或验证产物。需要核验证据的门禁角色按职责获得命令执行能力。

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

npm install --global @tonyclaw/[email protected]
qiheng install --host opencode

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

npm install --global git+ssh://[email protected]/TonyClaw/DICWorkflowKit.git
qiheng install

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

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

npx [email protected] install --host coding-agent --dry-run

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

npx [email protected] install --host coding-agent --install-root <CodeAgent配置根目录>

Coding Agent 实际安装内容

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

默认结构如下：

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

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

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 兼容格式：

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 负责“由谁判断和交付”，安装根目录中的清单负责 完整性检查与安全卸载。如果目标产品将两类资源分开存放，可以分别指定：

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

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

安装后第一眼理解流程

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

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

npx [email protected] guide

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

npx [email protected] guide --output docs/qiheng-flow.html

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

检查、升级与卸载

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

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

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

qiheng uninstall --host bitfun --scope project

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

用户如何使用

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

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

cd /path/to/your-project

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

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

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

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

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

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

如果希望检查并修复：

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

3. 检查一个 OpenSpec 变更

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

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

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

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

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

/workflow-core

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

使用 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 包发布指南。

为什么需要它

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

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

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 个。

默认门禁生命周期

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

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

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

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

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

必须分别保留设计一致性状态 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。它们负责完整性与证据校验，不替代最初由智能体 完成的入口识别：

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 | 活跃变更中的增量需求。 | | 已归档规格 | 历史上下文，不能覆盖当前有效规格。 |

默认输出契约

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 与行为驱动开发入口识别、本体治理动作、内容寻址验证、防篡改台账、自动报告 和最终证明文件。后续扩展应保持这些接口约定，并继续增强适配器、存储后端和 持续集成外部信任锚。