lijiaoqiao/docs/parallel_agent_output_quality_standards_v1_2026-04-02.md

并行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 设计文档结构

# {设计标题}

> 版本：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 评审报告结构

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

> 评审日期：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角色定义不一致 修复：

1. 引用TOK-001的角色层级作为基础
2. P1扩展角色需明确继承关系
3. 冲突时以TOK-001为准

6.2 审计事件命名冲突

问题：与TOK-002/XR-001事件命名不一致 修复：

1. 复用现有事件命名格式：domain.action.result
2. 不发明新的事件类型
3. 冲突时以TOK-002为准

6.3 指标边界模糊

问题：M-013~M-016指标重叠 修复：

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% 修复：

参考历史数据：
- 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或下一个并行任务周期 维护责任人：项目架构组