Clarify usage and contribution workflows

Author: wutianze

CONTRIBUTING.md

@@ -1,79 +1,149 @@
 # Contributing
 
-## 开发原则
+本指南主要面向共同维护和优化文档模板、OpenCode Skill 及其自动检查工具的开发者。使用现有工具生成某个模块文档，请直接阅读 [README.md](README.md) 的“为一个模块生成 Spec 文档”。
 
-- 实现事实以同 commit、同配置的 elaborated RTL 和 Chisel/Scala 为准。
-- 可选 spec 用于补充意图，不能覆盖源码证据。
-- 无法证实、来源冲突或疑似 RTL 缺陷必须登记为 `OPEN-*`。
-- 不修改 `third_party/XiangShan` 来迁就文档生成；需要兼容处理时修改本仓库工具。
-- `.cache/` 可删除，`evidence/` 必须随对应文档版本提交。
+## 维护对象
 
-## 新模块
+| 对象 | 路径 | 职责 |
+| --- | --- | --- |
+| 文档模板 | `templates/chip-design-document/chip_design_document_template_zh.md` | 定义交付文档的章节、字段、表格和标签 schema。 |
+| OpenCode Skill | `.opencode/skills/xiangshan-design-document/SKILL.md` | 指导 AI 如何取证、生成、判断版本和完成质量门禁。 |
+| 文档检查器 | `tools/validate_document.py` | 检查单个模块版本的结构和 evidence。 |
+| 仓库检查器 | `tools/validate_repository.py` | 检查跨模块链接、manifest 和模板约束。 |
+| RTL/图形工具 | `tools/generate_rtl.sh`、`extract_rtl_evidence.py`、`validate_mermaid.py` | 产生可复现 evidence。 |
+| 模板迭代记录 | `reports/template/Template_iteration_review.md` | 记录问题、决策、模板版本和回归结果。 |
 
-为 `<Module>` 增加文档时使用以下目录：
+模板规定“输出长什么样”，Skill 规定“AI 如何得到正确输出”，checker 负责“把关键规则变成强制门禁”。修改其中一个时，必须评估另外两个是否需要同步。
 
-```text
-inputs/<Module>/
-outputs/<Module>/
-reports/<Module>/
-evidence/<Module>/<version>/
+## 不可破坏的契约
+
+- 实现事实的证据优先级保持为：matching elaborated RTL > Chisel/Scala > 配置 > 可选 spec > 显式推断。
+- 无法证实、来源冲突或疑似 RTL 缺陷必须登记为 `OPEN-*`，不能写成 FACT。
+- I/O 必须区分 Chisel 声明与当前配置的 `Generated`/`Elided` Verilog 结果。
+- 顶层状态机章节不能混入 entry 生命周期或子模块 FSM。
+- `FG-API` 只能包含 Assume，`FG-COVERAGE` 只能包含 Cover。
+- 每个 FC 必须有自然语言、FC 表和至少一个独立 CK。
+- Mermaid 必须真实渲染，并以 source/SVG hash 防止使用过期证据。
+- 历史文档和 evidence 不得在普通迭代中被覆盖。
+- 不修改 XiangShan submodule 源码来迁就文档生成工具。
+
+## 模板版本
+
+模板顶部的 `模板结构版本` 与模块文档版本独立，使用 SemVer：
+
+| 增量 | 模板变化示例 |
+| --- | --- |
+| Major | 删除/重命名必选章节，改变 FG/FC/CK 解析结构，修改表格到旧生成器无法兼容。 |
+| Minor | 增加兼容字段、条件章节或新的可选/必选检查要求。 |
+| Patch | 增加 HTML 维护注释、修正文案或示例，不改变输出 schema。 |
+
+升级模板版本时必须：
+
+1. 更新模板顶部 `模板结构版本`。
+2. 更新模板“文档控制与依据”中的 `使用模板版本` 示例。
+3. 在 `Template_iteration_review.md` 说明问题、改动、兼容性和回归结果。
+4. 判断已有模块是否需要生成新文档版本；不要追溯修改历史版本记录的模板号。
+
+## Skill 修改原则
+
+Skill 必须说明可执行工作流，而不是重复模板全部正文。重点维护：
+
+- 触发场景、仓库路径和完整交付物。
+- 证据优先级与冲突处理。
+- preflight、RTL elaboration、缓存和 evidence 规则。
+- 文档 SemVer 选择及禁止覆盖历史。
+- Bundle/I/O、参数、FSM、FG/FC/CK 和 case 的提取方法。
+- Mermaid 安全写法与真实渲染要求。
+- 质量报告内容、checker 命令和完成标准。
+
+新增模板硬规则时，应同步回答：
+
+1. Skill 是否告诉 AI 如何满足它？
+2. checker 是否能自动发现违反规则的情况？
+3. quality report 是否记录了对应结果或未运行项？
+
+修改 Skill 后需要重启 OpenCode，再进行真实生成回归。
+
+## 开发流程
+
+### 1. 建立分支和基线
+
+```bash
+git switch -c <topic-branch>
+make init
+make preflight MODULE=Sbuffer CONFIG=DefaultConfig
+make lint MODULE=Sbuffer VERSION=v2.0.1
 ```
 
-输入 spec 可省略，设计文档、质量报告、版本历史和 evidence 不可省略。
+记录修改前的检查结果。不要把已有失败归因于本次改动。
 
-## 推荐流程
+### 2. 做最小一致修改
 
-1. 初始化并检查环境：
+- 先修改模板，明确是 schema 变化还是说明变化。
+- 再同步 Skill 的生成步骤和完成标准。
+- 能自动检查的新规则应加入 checker，避免只依赖提示词。
+- 跨平台逻辑必须同时考虑 Linux/macOS 和 x86-64/ARM64。
+- 不提交 `.cache/`、XiangShan build、凭据、私有路径或 IDE 状态。
 
-   ```bash
-   make init
-   make preflight MODULE=<Module> CONFIG=<Config>
-   ```
+### 3. 使用回归模块验证
 
-2. 检查 `outputs/<Module>/VERSION_HISTORY.md`，按 SemVer 选择未占用版本。
+Sbuffer 是当前模板和 Skill 的基准回归模块。至少执行：
 
-3. 创建 RTL evidence：
+```bash
+# 模板自身 Mermaid 示例
+rm -rf .cache/mermaid-check/template
+./tools/validate_mermaid.py \
+  --document templates/chip-design-document/chip_design_document_template_zh.md \
+  --output-dir .cache/mermaid-check/template
 
-   ```bash
-   make evidence MODULE=<Module> CONFIG=<Config> VERSION=<version>
-   ```
+# 最新已交付模块文档
+make lint MODULE=Sbuffer VERSION=v2.0.1
+git diff --check
+```
 
-4. 使用 `xiangshan-design-document` Skill 生成同版本设计文档、质量报告和版本历史。
+若改动会影响生成结果，应使用新文档版本完整重生成 Sbuffer，而不是改写旧版本。确认：
 
-5. 实际渲染 Mermaid 并运行完整检查：
+- 设计文档、质量报告、VERSION_HISTORY 和 evidence 版本一致。
+- RTL commit/config/hash 未变化时，质量报告明确说明。
+- FG/FC/CK 的新增、删除或语义变化符合所选文档版本。
+- 所有 Mermaid SVG 可渲染且 source hash 最新。
+- XiangShan submodule 保持 clean。
 
-   ```bash
-   make render MODULE=<Module> VERSION=<version>
-   make lint MODULE=<Module> VERSION=<version>
-   ```
+### 4. 更新迭代记录
 
-## 版本规则
+在 `reports/template/Template_iteration_review.md` 记录：
 
-| 增量 | 使用条件 |
-| --- | --- |
-| Major | DUT 范围或文档 schema 出现不兼容变化。 |
-| Minor | 接口、参数、状态、功能、FC/CK 或支持配置发生语义变化。 |
-| Patch | 证据、OPEN 项、措辞、链接、图形或格式变化，行为契约不变。 |
+- 原问题和可复现方式。
+- 模板、Skill、工具分别如何处理。
+- 模板版本及兼容性判断。
+- 使用了哪些回归模块和命令。
+- 尚未覆盖的风险。
+
+## Pull Request 要求
 
-模板结构版本与模块文档版本独立。生成文档必须记录所使用的模板版本。
+PR 应聚焦一个模板或 Skill 问题，并说明：
 
-历史版本不可覆盖。`--replace-evidence` 只能用于修复客观错误，并必须在新质量报告中记录原因。
+- 修改动机及失败示例。
+- 模板版本变化及 SemVer 理由。
+- 模板、Skill、checker 是否同步；未同步时说明原因。
+- 对已有文档和 UCAgent 解析的兼容性影响。
+- Linux/macOS 相关影响。
+- 回归命令和实际结果。
+- 是否生成了新的模块回归文档/evidence。
 
-## Pull Request 检查
+使用仓库 PR 模板，并确保：
 
-- 说明受影响模块、文档版本、XiangShan commit 和配置。
-- 说明 spec 与源码的冲突及新增/关闭的 `OPEN-*`。
-- 提交设计文档、同版本质量报告、版本历史、RTL manifest/ports 和 Mermaid evidence。
-- 确认 XiangShan submodule clean；若更新 gitlink，解释升级原因和影响。
-- 执行 `git diff --check` 和对应版本的 `make lint`。
-- 不提交 `.cache/`、submodule build、凭据、私有路径或本地 IDE 配置。
+- `git diff --check` 通过。
+- 模板 Mermaid 示例实际渲染成功。
+- `make lint MODULE=Sbuffer VERSION=<regression-version>` 通过。
+- 敏感信息、缓存和 submodule build 未进入提交。
 
 ## 提交信息
 
-使用简洁的祈使句，说明实际变化，例如：
+使用简洁的祈使句描述维护动作，例如：
 
 ```text
-Add ICache design document v1.0.0
-Fix Mermaid rendering validation
-Update XiangShan submodule baseline
+Clarify formal harness guidance
+Add Mermaid rendering validation
+Update template I/O mapping schema
 ```

README.md

@@ -18,9 +18,11 @@
 
 当前输出适合作为设计评审、验证计划和属性生成的输入。在 UCAgent checker、SVA 编译以及 formal prove/cover 回归完成前，文档不应标记为 `Frozen`。
 
-## 快速开始
+## 为一个模块生成 Spec 文档
 
-### 1. 克隆并初始化
+这里的 “Spec 文档” 指 `outputs/<Module>/` 下按照模板生成的设计与功能检测点文档。推荐由 OpenCode 加载项目 Skill 后完成源码分析、版本选择、RTL evidence、正文、质量报告和检查，不需要使用者手工拼接各个工具命令。
+
+### 第 1 步：克隆并初始化项目
 
 ```bash
 git clone --recurse-submodules git@github.com:XS-MLVP/spec_generator.git
@@ -33,27 +35,148 @@ cd spec_generator
 make init
 ```
 
-### 2. 检查环境
+所有 OpenCode 和 `make` 命令都应从仓库根目录 `spec_generator/` 执行。
+
+### 第 2 步：确定模块和配置
+
+至少准备以下信息：
+
+| 信息 | 是否必需 | 示例 |
+| --- | --- | --- |
+| 文档模块名 | 必需 | `Sbuffer`、`ICache` |
+| Chisel 顶层 class | 建议提供 | `Sbuffer` |
+| XiangShan 配置 | 必需 | `DefaultConfig` |
+| 已有 spec | 可选 | `inputs/Sbuffer/Sbuffer_spec.md` |
+
+模块名区分大小写，并用于创建 `inputs/<Module>`、`outputs/<Module>`、`reports/<Module>` 和 `evidence/<Module>`。若功能名可能对应多个 Chisel class，应在请求中明确 DUT 顶层 class。
+
+配置决定参数、功能开关和最终 Verilog 端口。没有项目特定要求时使用 `DefaultConfig`；不能把其他配置生成的 RTL evidence 复用到当前文档。
+
+### 第 3 步：放置可选输入 Spec
+
+已有需求说明、旧设计文档或 AI 生成的草稿可以放入：
+
+```text
+inputs/<Module>/
+```
+
+例如：
+
+```text
+inputs/ICache/ICache_spec.md
+inputs/ICache/ICache_ecc_spec.md
+```
+
+没有 spec 也可以生成。Skill 会把 spec 作为设计意图参考，并以 Chisel/Scala 和 elaborated RTL 核验实现事实；冲突内容会进入质量报告或登记为 `OPEN-*`。
+
+### 第 4 步：运行环境预检
+
+```bash
+make preflight MODULE=<Module> CONFIG=<Config>
+```
+
+Sbuffer 示例：
 
 ```bash
 make preflight MODULE=Sbuffer CONFIG=DefaultConfig
 ```
 
-工具支持 Linux x86-64/ARM64 和 macOS Intel/Apple Silicon。缺少的 JDK、Mill、Node.js、Mermaid CLI 和 headless browser 会下载到 `.cache/`；非 Linux x86-64 主机会构建固定 commit 的 native Espresso。详细依赖见 [environment/README.md](environment/README.md)。
+看到 `Summary: 0 error(s)` 后再开始生成。工具支持 Linux x86-64/ARM64 和 macOS Intel/Apple Silicon。缺少的 JDK、Mill、Node.js、Mermaid CLI 和 headless browser 会下载到 `.cache/`；非 Linux x86-64 主机会构建固定 commit 的 native Espresso。详细依赖见 [environment/README.md](environment/README.md)。
+
+### 第 5 步：从仓库根目录启动 OpenCode
+
+确保已安装 [OpenCode](https://opencode.ai/docs/)，然后从仓库根目录启动，使其发现 `.opencode/skills/`：
+
+```bash
+opencode
+```
+
+启动后使用下面的请求模板：
+
+```text
+请使用 xiangshan-design-document Skill 为 <Module> 生成设计与功能检测点文档。
+DUT Chisel 顶层 class：<ClassName>
+XiangShan 配置：<Config>
+可选 spec：inputs/<Module>/（如不存在则只使用源码）
+请根据 VERSION_HISTORY.md 选择下一个合法版本，生成设计文档、质量报告、
+RTL/端口 evidence 和 Mermaid 渲染 evidence，并运行严格 checker 与 make lint。
+```
+
+Sbuffer 示例：
+
+```text
+请使用 xiangshan-design-document Skill 为 Sbuffer 生成下一版设计与功能检测点文档。
+DUT Chisel 顶层 class：Sbuffer
+XiangShan 配置：DefaultConfig
+可选 spec：inputs/Sbuffer/
+请生成全部版本化产物并运行严格 checker 与 make lint。
+```
+
+如果刚修改或首次加入 `.opencode/skills/`，请重启 OpenCode 后再生成；Skill 在会话启动时加载，不会热更新。
 
-### 3. 生成新版本
+### 第 6 步：检查生成产物
 
-先按 SemVer 选择未占用版本。以下以 `v2.0.2` 为例：
+一次完整生成应新增同一版本的以下内容：
+
+```text
+outputs/<Module>/<Module>_design_document_zh_vX.Y.Z.md
+outputs/<Module>/VERSION_HISTORY.md
+reports/<Module>/<Module>_document_quality_review_vX.Y.Z.md
+evidence/<Module>/vX.Y.Z/manifest.json
+evidence/<Module>/vX.Y.Z/ports.csv
+evidence/<Module>/vX.Y.Z/diagrams/manifest.json
+evidence/<Module>/vX.Y.Z/diagrams/*.svg
+```
+
+设计文档、质量报告、history 和 evidence 的版本必须完全一致。`manifest.json` 应记录 XiangShan commit、配置、生成状态、工具版本、RTL SHA-256 和端口数量。
+
+### 第 7 步：独立运行验收
+
+即使 AI 已报告检查通过，也建议使用者重新运行：
+
+```bash
+make lint MODULE=<Module> VERSION=vX.Y.Z
+```
+
+该命令会真实重渲染 Mermaid，而不只是检查代码块语法。验收完成后重点阅读质量报告中的：
+
+- spec 被确认、修正或拒绝的内容。
+- `OPEN-IO-*`、`OPEN-PARAM-*`、`OPEN-BEHAV-*` 和 `OPEN-VERIFY-*`。
+- 未运行的 UCAgent、SVA 或 formal 检查。
+- RTL 生成是否为 `success`；若为 `partial`，是否明确说明失败发生在目标模块 RTL 输出之后。
+
+### 可选：手工预生成 Evidence
+
+通常让 Skill 自动执行即可。需要提前预热耗时的 RTL 缓存时，可先运行：
+
+```bash
+make evidence MODULE=<Module> CONFIG=<Config> VERSION=vX.Y.Z
+```
+
+该版本必须尚未存在。evidence 创建后，再让 OpenCode 使用完全相同的模块、配置和版本生成正文。历史 evidence 默认禁止覆盖。
+
+### 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| `Chisel class not found` | 核对 class 大小写和当前 XiangShan commit，必要时在请求中给出 Scala 路径。 |
+| 配置不存在 | 在 `third_party/XiangShan/src/main/scala/top/Configs.scala` 中确认配置 class。 |
+| 首次 RTL 生成较慢 | 属正常情况；同 commit/config/tool fingerprint 的后续模块会复用 split-RTL 缓存。 |
+| evidence 已存在 | 选择新的文档版本；不要用 `--replace-evidence` 覆盖历史。 |
+| Mermaid 无法显示 | 运行 `make render`/`make lint`；检查版本目录中的 SVG 和 diagram manifest。 |
+| 文档仍有 `OPEN-*` | 根据质量报告补充缺失源码、配置、RTL 或设计确认，不要猜测关闭。 |
+
+## 快速命令示例
+
+以下命令展示 Sbuffer 下一 Patch 版本的完整手工检查顺序。正文仍应由 Skill 生成：
 
 ```bash
 make evidence MODULE=Sbuffer CONFIG=DefaultConfig VERSION=v2.0.2
-# 使用 Skill 生成 outputs/、reports/ 和 VERSION_HISTORY.md
+# 在 OpenCode 中使用 Skill 生成 outputs/、reports/ 和 VERSION_HISTORY.md
 make render MODULE=Sbuffer VERSION=v2.0.2
 make lint MODULE=Sbuffer VERSION=v2.0.2
 ```
 
-在 OpenCode 中可直接要求：“使用 `xiangshan-design-document` Skill 为 Sbuffer 生成新版本文档”。修改 `.opencode/skills/` 后需要重启 OpenCode 才会加载新定义。
-
 ## 生成流程
 
 ```text