chip-doc-scorer

name	chip-doc-scorer
description	芯片架构文档多维度评分器。对 FS 功能规格书、UA 微架构文档、RTL 代码进行 10 维度量化评分（总分100），集成跨文档一致性检查、风险加权评分、自动改进建议生成和评分→改进→复评闭环。支持单文档评分、批量评分、版本对比、闭环改进。触发词：'文档评分','文档打分','FS评分','UA评分','RTL评分','代码评分','架构评分','质量评分','doc score','文档质量检查','评分报告','评分改进','文档质量闭环'.

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 总览

文档类型	Rubric	总分	维度数	对标清单
FS	FS Rubric	100	8+1	quality-checklist-fs.md
UA	UA Rubric	100	10+1	quality-checklist-microarch.md
RTL	RTL Rubric	100	10+1	quality-checklist-impl.md

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

---

FS 功能规格书 Rubric（100分）

评分维度

#	维度	权重	评分标准	对标 QC
F1	需求覆盖	15	RTM 覆盖率 ≥90%=满分，每降 5% 扣 2 分；REQ 编号缺失/未追溯扣分	QC-05, QC-21
F2	接口完整性	15	§6 信号均有 §5.x.2 对应端口；无悬空信号；位宽参数化；接口时序明确	QC-01, QC-10, QC-13, QC-20
F3	PPA 量化度	10	§8 所有指标有数值或"待综合验证"标注；子模块分配合计 ≤ 顶层；有约束类型	QC-03, QC-11, QC-14
F4	功能描述质量	15	§4 数据流表完整（输入→处理→输出）；控制流有仲裁/流控/超时描述；工作模式有状态转移图	QC-06, QC-16
F5	寄存器定义	10	§7 地址无重叠；位域覆盖所有 bit；访问类型正确；复位值明确	QC-02, QC-12
F6	异常处理	10	§5.x.4 + §6.4 异常表非空；每个异常有触发条件、行为、恢复方式、相关信号	QC-06
F7	图表规范	10	D2/Wavedrom 格式正确；PNG 文件存在；图文描述一致；每张图有说明文字	QC-09, QC-18, QC-23~27
F8	文档规范	15	版本号/修订历史一致；约束与假设非空；缩略语完整；子模块编号连续；时钟/复位已明确	QC-04, QC-07, QC-08, QC-15, QC-17, QC-19, QC-22
F9	跨文档一致性	10	PR→FS 需求覆盖率 ≥95%；端口定义与 PR 一致	cross-agent-consistency

评分规则

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

评分等级

等级	分数区间	含义	建议
S	90-100	优秀	可直接进入 UA 阶段
A	80-89	良好	小幅修改后可进入 UA
B	70-79	合格	需修复明显缺陷后重新评分
C	60-69	不合格	需返回 FS 设计阶段补充
D	<60	严重不足	需重新编写 FS

---

UA 微架构文档 Rubric（100分）

评分维度

#	维度	权重	评分标准	对标 MC
U1	数据通路	15	§5.1 信号链完整（输入→各阶段→输出）；每阶段有信号名/位宽/组合时序属性；关键路径有延迟预估	MC-01
U2	控制逻辑	10	§5.2 控制信号有产生源和驱动逻辑；流控机制有背压路径描述；valid/ready 依赖无组合环路	MC-03, MC-04
U3	状态机	10	§5.3 编码方式已声明；有 default 分支；可从非法状态恢复；无死锁；状态转移条件完整	MC-05, MC-05b, MC-05c
U4	FIFO/缓冲	10	§5.5 深度有流控模型计算依据（R_prod/R_cons/B_max/D_fb）；满/空判断使用多 1 位指针法	MC-06, MC-07
U5	IP/CBB 集成	5	§5.6 实例化参数与 IP 文档一致；配置初始化序列完整；接口适配逻辑明确	MC-08, MC-09
U6	时序分析	10	§6 有 SDC 约束建议；关键路径有 Tslack 公式和计算结果；Tslack > 0 或标注优化方案	MC-02, MC-10
U7	PPA 预估	10	§8 逻辑面积有 gate 数估算；功耗有计算依据；子模块分配合计 ≤ FS 预算	MC-11, MC-12
U8	RTL 指导	10	§9 高风险项已标注关注点；反合理化清单 ≥4 项；文件结构和参数化指导明确	MC-13, MC-14
U9	图表规范	10	D2/Wavedrom 格式正确；PNG 文件存在；图文描述一致；每张图有说明文字	MC-18, MC-19, MC-20, MC-21
U10	文档规范	10	RTM 覆盖率 ≥95%；版本号一致；顶层模块零逻辑；寄存器模块纯配置	MC-15, MC-16, MC-17
U11	跨文档一致性	10	FS→UA 端口/参数/需求一致性 ≥95%	cross-agent-consistency

评分等级

等级	分数区间	含义	建议
S	90-100	优秀	可直接进入 RTL 实现阶段
A	80-89	良好	小幅修改后可进入 RTL
B	70-79	合格	需修复缺陷后重新评分
C	60-69	不合格	需返回微架构设计阶段补充
D	<60	严重不足	需重新设计微架构

---

RTL 代码 Rubric（100分）

评分维度

#	维度	权重	评分标准	对标 IC
R1	命名规范	10	信号名准确反映功能；小写下划线；参数大写；低有效 _n 结尾；无单字母/关键字/tmp	coding-style §2
R2	复位策略	10	异步复位同步释放；所有寄存器有明确复位值；复位分支列出所有寄存器	IC-01, coding-style §5
R3	组合逻辑防护	15	always @(*) 输出赋默认值；if 补 else；case 有 default；无 latch	IC-02, IC-04, IC-15
R4	状态机规范	10	localparam 定义状态；两段式；编码方式正确（≤16 独热/ >16 二进制）；非法状态回收	coding-style §7
R5	握手协议	10	valid 不依赖 ready；valid 拉高后保持稳定；数据稳定性；ready 优先依赖下游	IC-14, IC-28, IC-29
R6	FIFO 设计	5	指针多 1 位；深度为 2 的幂；满/空判断正确	IC-18
R7	DFT 友好性	10	无异步置位；无门控时钟（用 ICG）；无组合反馈环；ICG 有 scan_en 端口	IC-05
R8	SVA 断言	5	在 ifdef ASSERT_ON 内；握手/数据/复位断言覆盖；命名规范	IC-08
R9	代码风格	10	缩进 4 空格；时序 <= 组合 = 不混用；常量显式位宽；generate 有标签；注释覆盖率 >30%	IC-03, IC-06, IC-07, IC-1013, IC-17, IC-2022
R10	工具验证	15	Verilator lint 通过（0 Error）；Yosys 综合通过；无 Warning（或已标注抑制理由）	强制门禁
R11	跨文档一致性	10	UA→RTL 端口/FSM/FIFO 一致性 ≥95%	cross-agent-consistency

评分等级

等级	分数区间	含义	建议
S	90-100	优秀	可进入综合/集成阶段
A	80-89	良好	修复 Warning 后可进入综合
B	70-79	合格	需修复明显编码问题
C	60-69	不合格	需对照编码规范重构
D	<60	严重不足	需重新编写 RTL

---

执行流程

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 的评分标准对齐项目质量检查清单，但不替代：

质量清单	本 Skill 对应	区别
quality-checklist-fs.md	FS Rubric (F1-F9)	清单是 Pass/Fail 二值；本 Skill 是 1-10 连续评分
quality-checklist-microarch.md	UA Rubric (U1-U11)	清单逐条检查；本 Skill 按维度聚合打分
quality-checklist-impl.md	RTL Rubric (R1-R11)	清单含自动化脚本指引；本 Skill 侧重综合评估

使用建议：

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

---

与相关方法论的关系

方法论	本 Skill 集成方式
doc-quality-feedback-loop.md	Phase 4 的改进闭环流程
risk-driven-methodology.md	Phase 0 的风险评估 + Phase 1 的风险加权
cross-agent-consistency.md	Phase 2 的跨文档一致性检查
quality-checklist-fs/microarch/impl.md	Phase 1 的评分标准对标

---

约束规则

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

---

异常处理

场景	处理方式
文档类型无法识别	提示用户指定类型，或尝试从内容推断
文档章节缺失	该维度记 0 分，标注"章节缺失"
图表文件不存在	图表规范维度扣分，标注"文件缺失"
lint/综合工具不可用	RTL 工具验证维度退化为人工检查，标注 dry_run
文档过长（>5000 行）	分章节评分，最后汇总
上下游文档不存在	跳过一致性检查，标注 [CONSISTENCY-SKIPPED]
风险评估数据不足	使用默认权重，标注 [RISK-DEFAULT]
改进 3 轮仍未达标	暂停，输出残留问题清单，等待人工介入
results.tsv 不存在	新建并写表头行