# 齐衡核心流程与术语表

## 一句话理解齐衡

**输入设计规格，提取必须实现的要求，检查代码是否与设计一致；发现缺口后执行最小修复，并用可复现证据证明修复有效。**

齐衡的核心不是“启动很多智能体”，也不是泛化的代码评审，而是建立一条可追溯闭环：

```text
设计规格输入
  → 确定设计依据
  → 提取设计要求
  → 查找实现位置
  → 检查设计与实现一致性
  → 发现并分类问题
  → 按最小范围修复
  → 运行验证并保存证据
  → 只重新检查受影响内容
  → 形成一致性结论
```

## 核心术语

| 术语 | 通俗解释 | 在齐衡中的作用 |
| --- | --- | --- |
| **设计规格** | 描述系统应该做什么、不能做什么以及如何验收的输入材料 | 齐衡的流程入口，可以是 OpenSpec、需求文档、设计文档、接口契约、数据模式或行为场景 |
| **设计依据** | 检查时应当采用的设计材料 | 发生冲突时用于判断以哪份设计为准，代码和测试不能自动取代设计 |
| **需求** | 设计规格中需要满足的目标或规则 | 形成从设计到实现和验证的追溯起点 |
| **场景** | 在特定前置条件下触发行为并产生可观察结果的用例 | 把抽象需求变成可以检查和验证的行为边界 |
| **设计要求** | 从设计规格中提取、实现必须满足的具体要求 | 是一致性检查的最小判断单位，例如“重复请求不得重复扣款” |
| **BDD 场景** | 用 Given/When/Then 描述系统行为的场景 | 适用于行为类设计要求，不代表接口、数据、架构、安全或性能等全部要求 |
| **实现位置** | 满足某项设计要求的代码、配置或数据结构 | 用于回答“这条设计要求在哪里实现” |
| **对应关系** | 设计要求与实现位置之间的关联 | 防止要求没有实现，也防止代码行为没有设计依据 |
| **一致性检查** | 对照设计要求检查当前实现是否完整、正确且没有超出设计 | 识别未实现、实现不完整、实现错误和超出设计等问题 |
| **问题** | 设计要求与当前实现之间经过证据确认的差异 | 用于安排后续修复；没有设计依据的猜测不能直接算作问题 |
| **修复任务** | 范围明确的一次修复工作 | 限制修改路径和影响范围，明确开始条件、停止条件、回退与验证方式 |
| **代码修改** | 已获授权、可以实际执行的修改 | 将“修复建议”和“已经修改”区分开，避免角色越权 |
| **验证** | 对当前设计和实现执行的构建、测试、检查或可复现实验 | 判断修复是否满足对应设计要求，而不只是命令是否返回成功 |
| **证据** | 带路径、内容哈希、命令、环境和候选版本身份的验证产物 | 让结论可以被复核，防止旧日志批准新代码 |
| **待检查版本** | 本轮接受检查的代码和设计文件 | 所有检查结果和证据都对应这个版本；文件变化后要判断哪些结果需要重跑 |
| **影响范围** | 设计、代码、测试或规则变化后需要重新检查的内容 | 只重跑真正受影响的检查，避免每次修复后重新扫描全部设计 |
| **质量门禁** | 在特定阶段必须通过的检查 | 控制规格、实现、一致性、证据和提交条件，缺少必要检查时不能放行 |
| **结果已过期** | 检查所依据的文件已经变化，原结果不能证明当前状态 | 内部标记为 `STALE`，必须按影响范围重新检查 |
| **项目信息** | 从仓库中识别出的设计位置、代码位置、命令和保护路径 | 让齐衡适配不同项目，而不是与某个项目写死绑定 |
| **检查记录** | 保存设计要求、实现位置、问题、验证、证据和结论的结构化数据 | 供各角色共享检查状态，避免只靠聊天摘要传递信息 |
| **最终证明** | 将最终结论与准确版本及证据绑定的结果文件 | 证明结论针对哪一版内容，并且可以复核 |
| **提交门禁** | 在一致性和质量检查完成后，决定能否提交、合并或发布 | 一致性检查通过，不代表其他质量条件也已满足 |

## 为什么要提取“设计要求”

提取设计要求不是额外创造需求，而是把设计规格中的内容拆成可以逐项检查的要求。

BDD 场景只适用于能够用前置条件、操作和预期结果描述的行为要求。接口、数据、架构、安全和性能要求仍然是设计要求，但不必强行转换为 BDD 场景。

例如设计规格写明：

> 同一支付请求重复提交时，不得重复扣款，并返回第一次处理结果。

齐衡会将其拆成至少三项设计要求：

1. 系统必须识别同一请求；
2. 重复请求不得再次产生扣款副作用；
3. 重复请求必须返回第一次处理的结果。

随后逐项寻找实现单元和验证证据。缺少任一映射，都不能仅凭“测试通过”宣布设计与实现一致。

## 三个容易混淆的边界

### 一致性不等于代码质量

一致性回答“实现是否符合设计”。代码质量还要回答安全、性能、可靠性、可维护性等问题。两类结论分别保存。

### 验证结果不等于证据充分

命令退出码为零，只证明命令执行成功。只有当验证覆盖具体设计要求，并对应当前设计、实现和待检查版本时，结果才构成充分证据。

### 修复不等于重新全量检查

修复后先做变更影响分析。设计规格未变化而只有实现变化时，设计扫描结果可以复用，只重跑实现、测试以及依赖它们的下游门禁。