Chip Doc Scorer

Chip Doc Scorer — 芯片架构文档多维度评分器

核心理念：量化评估 → 定位短板 → 生成报告 → 指导改进 → 复评验证 适用文档类型：FS 功能规格书 / UA 微架构文档 / RTL 代码 集成方法论：doc-quality-feedback-loop.md + risk-driven-methodology.md + cross-agent-consistency.md

设计哲学

1. 文档类型自适应 — 根据文档类型自动选择对应评分 Rubric
2. 双重评估 — 脚本可查项（自动化）+ LLM 审查项（语义分析）
3. 量化可追溯 — 每个维度有明确的评分标准和扣分依据
4. 对标规范 — 评分标准对齐项目质量检查清单（QC/MC/IC）
5. 结果可比较 — 支持版本间对比，量化改进效果
6. 风险感知 — 高风险维度权重自动提升，评审资源分配更精准
7. 闭环改进 — 评分→改进→复评，最多 3 轮迭代直到达标

评分 Rubric 总览

"+1" 为跨文档一致性维度，仅在上下游文档存在时启用。

FS 功能规格书 Rubric（100分）

评分维度

评分规则

• 每个维度按 1-10 分打分，乘以权重系数（权重/10）得到维度得分
• 总分 = Σ(维度分 × 权重/10)，满分 100
• 扣分必须附具体理由（引用 QC 编号和文档章节）
• 风险加权：维度涉及 Critical/High 风险 REQ 时，权重 ×1.5

评分等级

UA 微架构文档 Rubric（100分）

评分维度

评分等级

RTL 代码 Rubric（100分）

评分维度

评分等级

执行流程

Phase 0: 文档识别 + 风险评估

1. 读取目标文档全文
2. 识别文档类型（FS / UA / RTL）
   - FS: 包含"功能规格书"、§4 功能描述、§7 寄存器定义
   - UA: 包含"微架构规格书"、§5 微架构设计、§5.3 状态机
   - RTL: 包含 module/endmodule、always/assign 等 Verilog 结构
3. 加载对应 Rubric
4. 执行风险评估（参照 risk-driven-methodology.md）：
   - 识别文档涉及的 REQ 风险等级
   - 评估设计复杂度
   - 根据风险/复杂度调整评分权重（Critical/High 风险维度权重 ×1.5）
5. 确认评分范围（单文档 / 批量 / 版本对比 / 闭环改进）

Phase 1: 逐维度评分

for each 维度 in 对应 Rubric:

  # 脚本可查项（如适用）
  1. 执行自动化检查：
     - 提取表格数据，检查数值一致性
     - 检查信号名/端口名匹配
     - 验证文件存在性
     - 运行 lint/综合工具（RTL 时）

  # LLM 审查项
  2. 按评分标准逐条检查：
     - 对照 QC/MC/IC 清单项
     - 检查文档章节内容完整性
     - 评估语义一致性和设计合理性

  # 风险加权
  3. 如维度涉及高风险 REQ，权重 ×1.5

  # 打分
  4. 给出 1-10 分（附扣分理由，引用具体章节和 QC 编号）

Phase 2: 跨文档一致性检查

如存在上下游文档，执行一致性检查：

FS 评分时：
  - 检查 PR→FS 需求覆盖率
  - 检查 FS 端口定义是否与 PR 一致

UA 评分时：
  - 检查 FS→UA 端口/参数一致性
  - 检查 FS 需求在 UA RTM 中的覆盖率

RTL 评分时：
  - 检查 UA→RTL 端口/FSM/FIFO 一致性
  - 检查 RTL 是否忠实实现 UA 设计

一致性检查结果纳入 F9/U11/R11 维度评分：
  - 一致性 ≥ 95% → 满分
  - 一致性 90~94% → 扣 2 分
  - 一致性 < 90% → 扣 5 分

Phase 3: 生成评分报告

报告格式

# {文档名} 评分报告

## 评分总览

| 项目 | 值 |
|------|-----|
| 文档类型 | FS / UA / RTL |
| 文档版本 | v{X.Y} |
| 评分日期 | YYYY-MM-DD |
| 风险等级 | Low / Medium / High / Critical |
| **总分** | **{N}/100** |
| **等级** | **{S/A/B/C/D}** |

## 维度评分

| # | 维度 | 得分 | 满分 | 风险加权 | 扣分原因 |
|---|------|------|------|----------|----------|
| 1 | {维度名} | {N} | 10 | ×1.5 | {扣分理由，引用 QC 编号} |
| ... | ... | ... | ... | ... | ... |
| **合计** | | **{N}** | **100** | | |

## 跨文档一致性

| 检查维度 | 源文档 | 目标文档 | 一致性 | 差异项数 |
|----------|--------|----------|--------|----------|
| 端口一致性 | FS §6.2 | UA §4.1 | {N}% | {N} |
| 参数一致性 | FS §8 | UA §9 | {N}% | {N} |

## 雷达图（文本表示）

{维度1}: ████████░░ 8/10
{维度2}: ██████░░░░ 6/10
{维度3}: ██████████ 10/10
...

## 短板分析（Top 3）

1. **{维度名}** ({N}/10)：{具体问题描述}
   - 影响：{对后续阶段的影响}
   - 改进措施：{具体可执行措施，引用 QC 编号}
   - 预期提升：+{N} 分

2. ...

## 改进任务列表

| 任务 ID | 优先级 | 维度 | 改进措施 | 预期提升 | 状态 |
|---------|--------|------|----------|----------|------|
| IMP-001 | P0 | {维度} | {措施} | +{N} 分 | 待执行 |
| IMP-002 | P1 | {维度} | {措施} | +{N} 分 | 待执行 |

## 一致性修复建议

| 不一致项 | 源值 | 目标值 | 修复建议 |
|----------|------|--------|----------|
| {信号名} | {FS 值} | {UA 值} | 将 UA 修改为 {FS 值} |

## 优势项

1. **{维度名}** ({N}/10)：{做得好的方面}

## 改进建议优先级

| 优先级 | 维度 | 改进项 | 预期提升 |
|--------|------|--------|----------|
| P0 | {维度} | {具体改进} | +{N} 分 |
| P1 | {维度} | {具体改进} | +{N} 分 |
| P2 | {维度} | {具体改进} | +{N} 分 |

版本对比报告格式

# {文档名} 版本对比评分

## 总分变化

| 版本 | 总分 | 等级 | Δ |
|------|------|------|---|
| v{old} | {N} | {等级} | - |
| v{new} | {N} | {等级} | {+/-N} |

## 维度变化

| # | 维度 | v{old} | v{new} | Δ | 变化说明 |
|---|------|--------|--------|---|----------|
| 1 | {维度} | {N} | {N} | {+/-N} | {说明} |
| ... | ... | ... | ... | ... | ... |

## 改进效果评估

- 显著提升（Δ ≥ 2）：{维度列表}
- 略有提升（Δ = 1）：{维度列表}
- 无变化（Δ = 0）：{维度列表}
- 退步（Δ < 0）：{维度列表} ⚠️

## 建议

{基于对比结果的下一步建议}

Phase 4: 改进闭环

评分完成后，如用户要求改进：

1. 按优先级执行改进任务列表
2. 修改文档
3. 自动触发复评
4. 对比改进前后评分：
   - 总分提升 ≥ 5 → 显著改进
   - 总分提升 1~4 → 略有改进
   - 总分无变化 → 改进无效，分析原因
5. 如未达标（< 80 分），继续迭代（最多 3 轮）
6. 输出最终评分报告 + 改进效果对比

Phase 5: 结果持久化

1. 评分报告保存到文档同级目录：
   - FS:  ds/doc/fs/{module}_score_report_v{X}.md
   - UA:  ds/doc/ua/{module}_score_report_v{X}.md
   - RTL: ds/rtl/{module}_score_report_v{X}.md

2. 评分记录追加到 results.tsv（如存在）
3. 如为版本对比，生成 diff 报告

results.tsv 格式

timestamp	document	type	version	score	rank	F1	F2	F3	F4	F5	F6	F7	F8	F9	R11	note
2026-04-30T10:00	data_adpt_FS	FS	v1.0	72	B	8	7	6	7	8	5	7	8	-	-	初始评分
2026-04-30T11:00	data_adpt_FS	FS	v1.1	85	A	9	8	8	8	9	7	8	8	7	-	修复接口和异常

文件位置：与 SKILL.md 同目录下的 results.tsv。

使用方式

单文档评分

用户："帮我评分这个 FS 文档" / "对 data_adpt_FS_v1.0.md 打分"
→ Phase 0-3 完整流程
→ 输出评分报告 + 改进建议

批量评分

用户："评分所有 FS 文档" / "对 ds/doc/fs/ 下所有文档打分"
→ 扫描目录，逐个执行 Phase 0-3
→ 输出汇总表格（按分数排序）

版本对比

用户："对比 FS v1.0 和 v1.1 的评分变化"
→ 分别评分两个版本
→ 生成版本对比报告

评分 + 改进闭环

用户："评分并改进这个 UA 文档" / "帮我把评分提到 80 分以上"
→ Phase 0-3 评分
→ Phase 4 改进闭环（最多 3 轮）
→ 输出最终报告 + 改进效果对比

跨文档一致性检查

用户："检查 FS 和 UA 的一致性"
→ Phase 2 跨文档一致性检查
→ 输出一致性报告 + 修复建议

仅评分不生成报告

用户："快速评分一下" / "给个分数就行"
→ Phase 0-1 评分，输出简要分数表，不生成完整报告

与质量检查清单的关系

本 Skill 的评分标准对齐项目质量检查清单，但不替代：

使用建议：

• 质量检查清单用于交付前逐条门禁检查（Pass/Fail）
• 本 Skill 用于阶段性质量评估和版本对比（量化分数）
• 两者互补，不互斥

与相关方法论的关系

约束规则

1. 评分必须有据 — 每个扣分必须引用具体章节和 QC/MC/IC 编号
2. 不修改被评文档 — 本 Skill 只评分，不自动修复（修复由对应 Agent 执行）
3. 脚本可查优先 — 能自动化检查的项不依赖 LLM 主观判断
4. 对标规范 — 评分标准必须对齐项目编码规范和质量清单
5. 结果可复现 — 相同文档相同版本，评分结果应一致
6. 闭环有界 — 改进迭代最多 3 轮，超限暂停人工介入
7. 一致性以 FS 为准 — 跨文档不一致时，FS 为 single source

异常处理