## 4.4 数据迁移一致性

### 4.4.1 迁移协议

数据迁移必须包含：

1. 事务边界。
2. 批次大小。
3. 校验和。
4. 断点。
5. 重放策略。
6. 回滚策略。
7. 隐私处理。

### 4.4.2 推荐流程

```text
备份 → 干跑 → 小批迁移 → 校验 → 全量迁移 → 二次校验 → 观察期 → 完成
```

### 4.4.3 校验项

| 校验 | 说明 |
|---|---|
| 行数 | 源/目标行数一致或可解释 |
| 主键 | 无重复 |
| 外键 | 引用完整 |
| 校验和 | 关键字段一致 |
| 空值 | 非空约束满足 |
| 枚举 | 值合法 |

### 4.4.4 禁止事项

1. 禁止无备份迁移。
2. 禁止不可回放的迁移脚本。
3. 禁止迁移中途静默改字段映射。
4. 禁止生产数据直接给普通 worker。

---

## 4.5 非 Token 成本账本

### 4.5.1 成本项

| 成本项 | 说明 |
|---|---|
| token | 模型调用 |
| tool_call | 工具调用次数 |
| ci_time | CI/测试时间 |
| cloud_resource | 容器/云资源 |
| human_review | 人工审批/评审 |
| waiting | 等待人工或环境的时间 |
| storage | 产物存储 |

### 4.5.2 记账事件

```json
{
  "cost_id": "uuid",
  "task_id": "string",
  "phase": "string",
  "module_id": "string | null",
  "cost_type": "token | tool_call | ci_time | cloud_resource | human_review | waiting | storage",
  "amount": 0,
  "unit": "string",
  "unit_price": 0,
  "total": 0,
  "timestamp": "ISO8601"
}
```

### 4.5.3 ROI 实测

结案实测 ROI 必须使用：

```text
实际人工节省收益 ÷ 实际总成本
```

实际总成本包括：

1. 实际 token。
2. 工具调用。
3. 云资源。
4. CI 时间。
5. 人工评审。
6. 等待成本。

不得继续使用立项预估分母。

---

## 4.6 产物 Manifest 与哈希

### 4.6.1 每个交付任务必须有 manifest

```json
{
  "task_id": "string",
  "created_at": "ISO8601",
  "process_doc_version": "string",
  "contract_version": "string",
  "artifacts": [
    {
      "path": "string",
      "sha256": "string",
      "kind": "code | doc | log | config | migration | rollback_plan",
      "source": "worker | ci | human",
      "required": true
    }
  ],
  "test_reports": ["uri"],
  "review_verdicts": ["uri"],
  "checkpoint_approvals": ["uri"]
}
```

### 4.6.2 校验规则

1. 摘要必须能从落盘文件重新计算哈希。
2. 领导只看摘要时，必须能追溯到完整产物。
3. 缺少必要产物不得进入 `delivered`。
4. manifest 必须归档。

---

## 4.7 取消、暂停与优先级

### 4.7.1 操作定义

| 操作 | 含义 |
|---|---|
| cancel | 终止任务，不再继续 |
| pause | 暂停任务，可恢复 |
| resume | 恢复任务 |
| preempt | 高优先级任务抢占资源 |

### 4.7.2 安全终止流程

1. 停止派发新任务。
2. 等待运行中工具调用进入安全点。
3. 保存现场。
4. 释放锁。
5. 写入终止原因。
6. 对已产生副作用检查回滚。

### 4.7.3 优先级规则

1. 生产事故修复优先。
2. 安全修复优先。
3. 已完成大半的任务不轻易抢占。
4. 抢占必须记录成本损失。
5. 抢占不得导致静默丢失产物。

---

## 4.8 行为契约 DSL 与生成边界

### 4.8.1 能力边界

契约自动生成适合：

1. 类型结构。
2. 字段必填性。
3. 枚举范围。
4. 基本请求/响应格式。
5. 简单数值范围。

不完全适合：

1. 幂等性。
2. 轮换语义。
3. 安全语义。
4. 状态机。
5. 跨服务事务。
6. 性能约束。
7. 复杂业务时序。

### 4.8.2 人工审核

以下行为契约必须人工审核：

1. 认证。
2. 授权。
3. 支付。
4. 数据迁移。
5. 回滚。
6. 审计。
7. 任何不可逆操作。

### 4.8.3 禁止事项

1. 禁止声称行为契约完全自动生成。
2. 禁止未审核的行为契约直接进入生产验收。
3. 禁止手写替代白测试而不记录豁免。

---

# 第五章 变更控制

## 5.1 验收清单变更控制

### 5.1.1 变更触发

以下情况可触发验收清单变更：

1. Phase 0 需求写错。
2. 发现遗漏验收项。
3. 契约变更。
4. 法规/安全要求变化。
5. 人工审批要求补充。

### 5.1.2 变更流程

```text
提出变更 → 影响分析 → 人工审批 → 版本号递增 → 重新覆盖性 diff → 重验受影响模块
```

### 5.1.3 影响分析必须包含

1. 哪些 brief 受影响。
2. 哪些模块需要重验。
3. 哪些契约条目受影响。
4. 预算是否变化。
5. 是否需要重新 Checkpoint ①。

### 5.1.4 禁止事项

1. 禁止执行中静默追加验收项。
2. 禁止删除验收项不留审计。
3. 禁止已派发 brief 自动继承新验收清单。
4. 禁止变更验收清单不递增版本。

---

# 第六章 规则单一事实源与插件硬拦截

本章对应框架级第 4 项的工程落地：  
将可执行硬规则收敛为版本化规则文件，并通过插件层执行 `approve / modify / block`。

## 6.1 单一事实源目标

以下规则必须逐步从文档、prompt、代码三处重复，收敛到一个机器可读规则源：

1. `max_workers`
2. `max_tool_calls_per_worker`
3. `token_fuse_ratio`
4. `brief_rewrite_auto_limit`
5. `brief_rewrite_total_limit`
6. `environment_retry_backoff`
7. `checkpoint_timeout_actions`
8. `forbidden_commands`
9. `high_risk_domains`
10. `budget_borrow_limit_ratio`

## 6.2 rules.json 最小结构

```json
{
  "version": "rules@2026-xx-xx",
  "hard_limits": {
    "max_workers": 3,
    "max_tool_calls_per_worker": 15,
    "token_fuse_ratio": 1.2,
    "brief_rewrite_auto_limit": 1,
    "brief_rewrite_total_limit": 2,
    "budget_borrow_limit_ratio": 0.5
  },
  "retry": {
    "environment_backoff_seconds": [1, 4, 16],
    "jitter": true,
    "total_retry_limit_seconds": 300,
    "retryable_error_whitelist": ["ETIMEDOUT", "ECONNRESET", "SERVICE_UNAVAILABLE"]
  },
  "security": {
    "forbidden_commands": ["rm -rf /", "curl | sh"],
    "high_risk_domains": ["auth", "payment", "permission", "data_migration", "prod_config"]
  },
  "checkpoints": {
    "sla_high_risk_hours": 4,
    "sla_normal_hours": 24,
    "timeout_high_risk_action": "reject_and_hold",
    "timeout_normal_action": "hold_safe_state"
  }
}
```

## 6.3 插件动作定义

| 动作 | 含义 |
|---|---|
| approve | 放行 |
| modify | 修改参数或命令后放行 |
| block | 阻断 |

### 6.3.1 返回结构

```json
{
  "action": "approve | modify | block",
  "message": "string",
  "modified_payload": {},
  "rule_id": "string",
  "rules_version": "string"
}
```

## 6.4 Fail-Closed 规则

插件必须默认失败关闭。

```text
插件异常 → block
规则文件缺失 → block
规则文件解析失败 → block
无法确认规则版本 → block
```

禁止：

```text
插件异常 → approve
```

## 6.5 启用与热更

| 对象 | 规则 |
|---|---|
| 插件启用 | 首次启用需重启进程 |
| 插件禁用 | 需重启或明确热禁用接口 |
| rules.json | 可热更 |
| 规则缓存 | 必须加锁 |
| 规则版本 | 每次拦截必须记录 |

推荐实现：

1. 每次工具调用现读 `rules.json`。
2. 若使用缓存，必须使用读写锁。
3. 文件变更后必须刷新缓存或版本号。

## 6.6 并发安全

1. 工具并行运行时，插件会并发触发。
2. 共享规则缓存必须加读写锁。
3. 禁止在并发下写坏缓存。
4. 禁止读取半写入状态的规则文件。

## 6.7 覆盖边界

| 层 | 拦截方式 |
|---|---|
| 工具调用 | `pre_tool_call` |
| 模型输出 | `pre_verify` 或等价校验 |
| 文件写入 | 文件系统权限 + 写入白名单 |
| 预算 | Code 层预算计数器 |
| 状态迁移 | 状态机校验 |

## 6.8 插件回归用例

每次修改规则插件后必须运行回归用例。

### 6.8.1 用例环境

1. 临时 `HOME`。
2. 隔离配置目录。
3. 测试插件。
4. 测试规则文件。
5. 断言脚本。

### 6.8.2 最小断言

| 用例 | 断言 |
|---|---|
| block | 命中禁词时工具不执行，返回拦截错误 |
| modify | 原始命令被替换，实际执行修改后命令 |
| approve | 正常命令放行 |
| fail_closed | 插件异常时返回 block |
| hot_reload | 修改规则后无需重启即可生效 |
| concurrency | 并发调用下规则不串、不漏 |
| no_plugin | 无插件时门控跳过，不影响正常执行 |

### 6.8.3 回归通过标准

```text
所有断言通过，且日志中可看到规则版本与动作。
```

---

# 第七章 工程验收清单

## 7.1 状态机验收

- [ ] 所有状态枚举已落库。
- [ ] 所有状态迁移都有日志。
- [ ] 非法状态迁移会被拒绝。
- [ ] 重启后可恢复到稳定检查点。
- [ ] 不会重复执行非幂等副作用。

## 7.2 锁与并发验收

- [ ] 文件锁可物理互斥。
- [ ] 资源锁覆盖数据库/端口/环境。
- [ ] 锁超时可回收。
- [ ] 崩溃后锁不会永久泄漏。
- [ ] 强制解锁有审计。

## 7.3 预算验收

- [ ] 单任务超 120% 会进入 `paused_for_budget`。
- [ ] 全局池耗尽会进入 `circuit_broken`。
- [ ] 借调不超过 50%。
- [ ] 借调事件进入 Checkpoint 汇报队列。
- [ ] 非 token 成本可归集。

## 7.4 验收流程验收

- [ ] Reviewer verdict 可机器比对。
- [ ] 空报告规则按“未执行检查”判定。
- [ ] 高危阻断项不走子集容忍。
- [ ] 双 Reviewer 独立隔离。
- [ ] Checkpoint 有 SLA 和超时动作。

## 7.5 安全验收

- [ ] 高危域禁止默认妥协。
- [ ] 技术债有 owner、期限、阻断规则。
- [ ] 密钥不进日志。
- [ ] 高风险操作有审批。
- [ ] 外部依赖有许可与安全记录。

## 7.6 插件硬拦截验收

- [ ] `rules.json` 版本可追踪。
- [ ] 插件支持 `approve / modify / block`。
- [ ] 插件异常时 fail-closed。
- [ ] 规则热更可用。
- [ ] 并发调用安全。
- [ ] 回归用例全部通过。

---

# 附录 A：最小状态迁移审计表

```sql
CREATE TABLE state_transitions (
  id INTEGER PRIMARY KEY,
  entity_type TEXT NOT NULL,
  entity_id TEXT NOT NULL,
  from_state TEXT NOT NULL,
  to_state TEXT NOT NULL,
  reason_code TEXT NOT NULL,
  actor TEXT NOT NULL,
  evidence_uri TEXT,
  created_at TEXT NOT NULL
);
```

# 附录 B：最小锁表

```sql
CREATE TABLE locks (
  lock_key TEXT PRIMARY KEY,
  lock_type TEXT NOT NULL,
  lock_mode TEXT NOT NULL,
  owner_id TEXT NOT NULL,
  task_id TEXT NOT NULL,
  acquired_at TEXT NOT NULL,
  lease_expires_at TEXT NOT NULL,
  state TEXT NOT NULL
);
```

# 附录 C：最小成本账本表

```sql
CREATE TABLE cost_ledger (
  cost_id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  phase TEXT,
  module_id TEXT,
  cost_type TEXT NOT NULL,
  amount REAL NOT NULL,
  unit TEXT NOT NULL,
  unit_price REAL,
  total REAL,
  created_at TEXT NOT NULL
);
```

# 附录 D：插件伪代码

```python
def pre_tool_call(tool_name, payload, context):
    try:
        rules = load_rules_with_lock()

        if rules.is_forbidden(tool_name, payload):
            return {
                "action": "block",
                "message": "blocked by rules",
                "rule_id": rules.matched_rule_id,
                "rules_version": rules.version
            }

        if rules.should_rewrite(tool_name, payload):
            new_payload = rules.rewrite(payload)
            return {
                "action": "modify",
                "modified_payload": new_payload,
                "rule_id": rules.matched_rule_id,
                "rules_version": rules.version
            }

        return {
            "action": "approve",
            "rules_version": rules.version
        }

    except Exception as e:
        return {
            "action": "block",
            "message": f"plugin failure: fail-closed: {e}",
            "rules_version": "unknown"
        }
```

# 附录 E：回归用例骨架

```text
1. 创建临时 HOME
2. 写入测试插件
3. 写入测试 rules.json
4. 启动隔离环境
5. 断言 block 用例
6. 断言 modify 用例
7. 断言 approve 用例
8. 断言插件异常时 fail-closed
9. 断言规则热更生效
10. 断言并发调用无串规则
11. 输出测试报告
```

---

## 结尾说明

本手册 v0.1 覆盖：

1. C 组 28 项工程缺口。
2. 框架级第 4 项“单一事实源 + 插件硬拦截”的落地方案。
3. 流程文档中所有“由 Code 层执行”的硬边界所需的最小工程规格。

本手册不改变流程文档的业务规则。  
后续如果流程文档升级到新版本，本手册必须同步进行回归验证。