# 并行Agent产出质量规范 v1.0

> 版本：v1.0
> 日期：2026-04-02
> 适用范围：所有并行子Agent设计/调研任务
> 关联：`docs/project_experience_summary_v1_2026-04-02.md`

---

## 1. 背景与目的

### 1.1 问题发现
2026-04-02并行执行5个P1/P2设计任务，通过系统性评审发现以下共性问题：

| 问题类型 | 发现频次 | 代表问题 |
|----------|----------|----------|
| 与基线文档不一致 | 5/5 | 角色层级、评分权重、事件命名 |
| 数据模型缺审计字段 | 2/5 | 缺少request_id/version/created_ip |
| 指标边界模糊 | 2/5 | M-013~M-016指标重叠 |
| CI脚本缺失 | 1/5 | 引用的脚本未实现 |
| 实施周期高估 | 1/5 | 设计工期与实际偏差大 |

### 1.2 规范目的
确保未来并行Agent产出：
1. **内部一致性**：子Agent之间设计互不冲突
2. **外部一致性**：与PRD、架构、现有设计对齐
3. **可执行性**：设计可直接转化为代码和脚本
4. **可验证性**：有明确的验收标准和测试方法

---

## 2. 强制检查清单（Agent必须执行）

### 2.1 PRD对齐检查

| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| P1 | 需求覆盖完整性 | 所有P1需求项都有对应设计 | 补充缺失需求 |
| P2 | 需求覆盖完整性 | 所有P2需求项都有调研/设计 | 标注待决策项 |
| R | 用户角色对齐 | 角色定义与PRD一致 | 对齐PRD定义 |
| M | 成功标准对齐 | 设计产出可验证成功标准 | 补充验收标准 |

**PRD基线文档**：
- `docs/llm_gateway_prd_v1_2026-03-25.md`
- `docs/supply_button_level_prd_v1_2026-03-25.md`

### 2.2 P0设计一致性检查

| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| T | Token体系一致 | 角色层级兼容TOK-001/TOK-002 | 明确继承关系 |
| A | 审计事件一致 | 事件命名与TOK-002/XR-001一致 | 复用现有事件 |
| D | 数据模型一致 | 遵循database_domain_model_and_governance | 补充必需字段 |
| I | API命名一致 | 遵循api_naming_strategy | 使用标准前缀 |
| M | 指标定义一致 | M-013~M-021定义不变 | 引用现有定义 |

**P0设计基线文档**：
- `docs/token_auth_middleware_design_v1_2026-03-29.md`
- `docs/supply_technical_design_enhanced_v1_2026-03-25.md`
- `docs/database_domain_model_and_governance_v1_2026-03-27.md`
- `docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md`

### 2.3 跨文档一致性检查

| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| C1 | 与同时产出文档一致 | 事件命名、数据结构互不冲突 | 协调统一 |
| C2 | 与已有文档一致 | 不引入冲突的设计 | 对齐现有设计 |
| C3 | 指标边界清晰 | M-013~M-016无重叠 | 明确边界 |

**已有设计文档**：
- `docs/routing_strategy_template_design_v1_2026-04-02.md`
- `docs/audit_log_enhancement_design_v1_2026-04-02.md`
- `docs/multi_role_permission_design_v1_2026-04-02.md`
- `docs/compliance_capability_package_design_v1_2026-04-02.md`
- `docs/sso_saml_technical_research_v1_2026-04-02.md`

### 2.4 可执行性检查

| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| E1 | 引用的脚本已实现 | CI/CD脚本实际存在 | 实现或标注待开发 |
| E2 | 实施周期合理 | 设计工期与历史数据偏差<30% | 修正估算 |
| E3 | 验收标准明确 | 每项设计有可测试的验收标准 | 补充验收条件 |

### 2.5 行业最佳实践检查

| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| B1 | 安全加固 | 遵循OWASP Top 10 | 补充安全考虑 |
| B2 | 错误处理 | 错误码体系完整 | 对齐现有错误码 |
| B3 | 可观测性 | 日志/指标/追踪完备 | 补充观测设计 |

---

## 3. 文档结构模板

### 3.1 设计文档结构

```markdown
# {设计标题}

> 版本：v1.0
> 日期：YYYY-MM-DD
> 状态：[Draft/Review/Approved/Frozen]
> 依赖：{关联文档列表}

## 1. 背景与目标
## 2. 与PRD对齐性
## 3. 与P0设计一致性
## 4. 详细设计
## 5. 数据模型（如需）
## 6. API设计（如需）
## 7. CI/CD集成（如需）
## 8. 验收标准
## 9. 实施计划
## 10. 风险与缓解
## 11. 附录
```

### 3.2 评审报告结构

```markdown
# {被评审文档}评审报告

> 评审日期：YYYY-MM-DD
> 评审结论：[{GO/CONDITIONAL GO/NO-GO}]

## 1. PRD对齐性
## 2. P0设计一致性
## 3. 跨文档一致性
## 4. 可执行性
## 5. 行业最佳实践
## 6. 问题清单（按严重度）
## 7. 改进建议
## 8. 最终结论
```

---

## 4. Agent执行协议

### 4.1 任务启动阶段

1. **读取基线**（强制）：
   - PRD v1
   - 相关的P0设计文档
   - 同时期并行的其他Agent产出（通过文件列表）

2. **检查一致性**（强制）：
   - 执行第2章的强制检查清单
   - 记录发现的不一致项

3. **明确范围**（强制）：
   - 在文档中明确声明依赖的基线文档
   - 标注需要协调的跨文档问题

### 4.2 任务执行阶段

1. **保持一致性**：
   - 复用现有事件命名、数据结构
   - 不发明新的指标定义
   - 不引入与现有设计的冲突

2. **记录假设**：
   - 任何基于假设的设计必须明确标注
   - 假设需有事实依据或行业实践支持

3. **预留接口**：
   - 与其他模块交互的接口必须抽象清晰
   - 便于后续集成

### 4.3 任务交付阶段

1. **自检**：
   - 对照检查清单逐项确认
   - 确保没有遗漏

2. **产出完整**：
   - 设计文档
   - 评审报告（如有）
   - 评审发现汇总

---

## 5. 评审触发条件

### 5.1 必须评审
- 所有P1/P2设计文档
- 所有API契约变更
- 所有数据模型变更

### 5.2 评审维度
| 维度 | 权重 | 说明 |
|------|------|------|
| PRD对齐 | 25% | 是否覆盖需求 |
| P0一致性 | 30% | 是否与基线一致 |
| 可执行性 | 25% | 是否可实现 |
| 最佳实践 | 20% | 质量是否达标 |

### 5.3 评审结论
| 结论 | 含义 | 处理 |
|------|------|------|
| GO | 通过，可实施 | 进入下一阶段 |
| CONDITIONAL GO | 有条件通过，需修复后实施 | 修复指定问题 |
| NO-GO | 不通过，需重新设计 | 重新设计 |

---

## 6. 常见问题与修复指南

### 6.1 角色层级冲突
**问题**：与TOK-001/TOK-002角色定义不一致
**修复**：
```text
1. 引用TOK-001的角色层级作为基础
2. P1扩展角色需明确继承关系
3. 冲突时以TOK-001为准
```

### 6.2 审计事件命名冲突
**问题**：与TOK-002/XR-001事件命名不一致
**修复**：
```text
1. 复用现有事件命名格式：domain.action.result
2. 不发明新的事件类型
3. 冲突时以TOK-002为准
```

### 6.3 指标边界模糊
**问题**：M-013~M-016指标重叠
**修复**：
```text
M-013: 凭证暴露事件（credential_exposed=1）
M-014: 凭证入站覆盖率（ingress_credential_count/total_request）
M-015: 直连绕过事件（direct_call_attempted=1）
M-016: query_key拒绝率（query_key_rejected_count/total_query_key_request）
```

### 6.4 实施周期高估
**问题**：设计工期与实际偏差>50%
**修复**：
```text
参考历史数据：
- P0开发：3人月
- P1单模块：1-2人月
- P2调研：0.5-1人月
- CI脚本：0.25-0.5人月
```

---

## 7. 附录

### 7.1 基线文档索引

| 文档 | 路径 | 用途 |
|------|------|------|
| PRD v1 | docs/llm_gateway_prd_v1_2026-03-25.md | 需求基线 |
| 供应技术设计 | docs/supply_technical_design_enhanced_v1_2026-03-25.md | XR-001基线 |
| Token中间件 | docs/token_auth_middleware_design_v1_2026-03-29.md | 认证基线 |
| 数据库模型 | docs/database_domain_model_and_governance_v1_2026-03-27.md | 数据模型基线 |
| API命名策略 | docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md | 命名基线 |
| ToS合规引擎 | docs/tos_compliance_engine_design_v1_2026-03-18.md | 合规基线 |

### 7.2 M-013~M-021指标定义

| 指标 | 定义 | 计算公式 |
|------|------|----------|
| M-013 | supplier_credential_exposure_events | COUNT(event_type='credential_exposed') |
| M-014 | platform_credential_ingress_coverage_pct | SUM(has_ingress_credential)/COUNT(*)*100 |
| M-015 | direct_supplier_call_by_consumer_events | COUNT(event_type='direct_call_attempted') |
| M-016 | query_key_external_reject_rate_pct | SUM(query_key_rejected)/SUM(query_key_request)*100 |
| M-017 | dependency_compat_audit_pass_pct | PASS/total*100 |

---

**文档状态**：生效
**下次审查**：2026-04-15或下一个并行任务周期
**维护责任人**：项目架构组