` |
### 其它
| 原能力 | HTML 等价 |
|--------|-----------|
| `#spec/能力交付` 标签 | `
`，不在正文堆标签 |
| 代码位置引用 | `
src/x.ts:88` |
| 表格、代码块、列表 | 原生 HTML，样式由 `rk-report.css` 统一 |
## 修订规范（核心）
**铁律：修改报告时永不静默改写。原文保留并标记，新内容标记新增。**
每轮修改：
1. 修订号 `+1`（r1 → r2），更新报告头 `修订` 字段
2. 在「修订历史」表**追加一行**，写清改了什么、为什么
3. 正文用语义标签标记，每个标记都带 `data-rev="{本轮修订号}"`
### 行内修订
```html
超时设为
30s
10s
```
### 块级修订
```html
删掉的整段旧方案。
新增的整段新方案。
```
**布局容器不要直接套语义类**：`.rk-kpis` 这类带 `display: grid` 的容器，不要把 `rk-added`/`rk-removed` 加在同一个元素上（`
`），语义类会覆盖容器的布局。要标记「新增了一组卡片」，用嵌套：
```html
```
共享样式对 `.rk-kpis.rk-added` 有兜底覆盖（恢复 grid、去块级装饰），但那是防误用，不是推荐写法。
### 表格行修订
```html
旧值
新值 |
```
**整行新增 / 删除**：改的是「新增一整行」或「删掉一整行」时，把 `rk-added` / `rk-removed` 加在 `
` 上（`data-rev` 同本轮修订号）。共享样式已对 `
` 单独覆盖：保持 `table-row` 布局、高亮落到单元格背景、不显示 `rN` 角标（第一列「修订」列已承载修订号）：
```html
| r2 | … | … |
| 旧行 | … | … |
```
**单元格内改值**：只改某行里的一个值，用上面 `
` 内的 `` / ``。不要给 `` 套 `rk-added`/`rk-removed` 后又在单元格里塞 ``/``——二选一。
### 三视图
`rk-report.js` 自动在 `.rk-revbar` 渲染切换按钮，无需手写：
| 视图 | 作用 |
|------|------|
| 全部修订 | 所有 `ins`/`del` 全部高亮，带 `rN` 角标——看全部演进 |
| 仅最新修订 | 只高亮最新一轮，旧修订降为正文——看本次改了什么 |
| 终稿 | 隐藏 `del`、`ins` 去高亮——当作干净最终版阅读 |
### 与 Decision Log 联动
`lead/team-context.md` 的 `Decision Log`（v2.6.0 起）记录**决策**（选项 / 结论 / 理由，编号 `D-001`），
报告修订历史记录**文本变更**（哪句改成了什么）。两者互补，必须能互相追溯：
- 修订源于一次实质取舍时，修订历史表的「原因」列写上决策编号，例如：`按 D-003 改用抽公共层方案`
- 纯笔误、措辞、补充说明等非决策性修改，「原因」列直接写清即可，不必编造决策编号
- 决策本身仍记在账本的 `Decision Log`，**不要**把决策过程正文复制进报告
```html
| r3 | 2026-06-26 | spec-writer |
缓存层从进程内改为 Redis |
按 D-003（多实例部署需共享缓存） |
```
## 突出重点的组件
```html
src/auth/token.ts:88
```
## 用户批注（人写，Agent 读）
用户可以直接在报告 HTML 里写批注，表达评审意见。这是**人写给 Agent** 的通道，与 Agent 自己的 `rk-cal` 区分开（橙色虚线框 + 「批注」角标）。
```html
这个方案没考虑离线场景，补一下。
这个方案没考虑离线场景，补一下。
exit 0 |
```
**Agent 侧义务**（详见 `.agents/rules/spec-workflow.md`「报告批注」）：接手报告前必须全文搜 `rk-note`，把每条登记进账本「问题闭环记录」（分类 `review`，状态 `pending`）。漏读批注等同于漏读用户指令。
批注是短期沟通载体，Agent 重写报告时会被覆盖，不需要长期保留——但账本里的登记必须留下。所以批注**不受修订规范约束**，写批注不必加 `data-rev`。
## 禁止事项
- 禁止 Obsidian 专有语法：`[[wikilink]]`、`> [!note]` Callout、`#tag`、Bases、Canvas
- 禁止在报告 HTML 里写 ` |