# Chip Doc Scorer

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

- Skill: `zhaixin244-wq/chip-doc-scorer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhaixin244-wq/chip-doc-scorer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaixin244-wq/chip-doc-scorer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaixin244-wq (https://skillmd.com/u/zhaixin244-wq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhaixin244-wq/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 总览

| 文档类型 | Rubric | 总分 | 维度数 | 对标清单 |
|----------|--------|------|--------|----------|
| **FS** | [FS Rubric](#fs-功能规格书-rubric100分) | 100 | 8+1 | quality-checklist-fs.md |
| **UA** | [UA Rubric](#ua-微架构文档-rubric100分) | 100 | 10+1 | quality-checklist-microarch.md |
| **RTL** | [RTL Rubric](#rtl-代码-rubric100分) | 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-10~13, IC-17, IC-20~22 |
| 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: 生成评分报告

#### 报告格式

```markdown
# {文档名} 评分报告

## 评分总览

| 项目 | 值 |
|------|-----|
| 文档类型 | 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} 分 |
```

#### 版本对比报告格式

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

## 总分变化

| 版本 | 总分 | 等级 | Δ |
|------|------|------|---|
| 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 格式

```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 不存在 | 新建并写表头行 |