xuxiang
feeafbd70d
复核回执 R-20260924-103820-a8f2（现状梳理）逐条实跑核对后落地。 【采纳】 - 词表按 #157/#159 真实小节名补齐：`结论`（结论即提案）→ 提案 · `生产实测` → 背景 · `基线` → 效果； `取证记录` 进「其他已识别小节」（原报「未归类」是误报）。 - 去掉「更正 / 补充」特例 ⇒ 顺序改按主叙事**如实**判定（复核指出 `## 影响面（实测更正）` 被错列成「后置小节」）；提示语写明「确为更正小节后置时可保留，由人判断」。 - 缺「提案」的措辞给出路：提示「若『结论即提案』或结论为『无需处置』，请显式写一段声明」。 - 评论清单加 `[可执行]` / `[? 非可执行]` 列（启发式：代码围栏或 SQL 关键字）⇒ 「评论只应剩必须可执行物」由人肉核变为机器提示 + 人核；SKILL §8.1/§8.3 同步。 - `selftest` 13 → **20** 条（补 结论即提案 / 基线归效果 / 取证记录 / 可执行物三态 / 方案明细不被「实测」抢走）。 【自查中自己踩的坑（已修 + 加回归用例）】 - 首版把裸词 `实测` 加进背景词表 ⇒ `## 方案明细（…实测代价）` 被抢归「问题背景」，`#158` 误报「顺序 ⚠」。 改为 `生产实测`，并加 selftest 锁死该回归。 【不采纳（附理由）】 - 「`闸门=不处置` 作为提案的替代」：闸门是断言 4 的受控词表（等口径 / 等取证 / 等部署）， 新增取值属口径变更且会使「不能开工」语义漂移 ⇒ 改用「`## 结论` 可替代提案 + 正文显式声明」， **不动闸门词表**；确要加取值请用户拍板。 【验证 · E1 · 本机】 - `node --check` 通过；`selftest` **20/20**；`verify 157 158 159` = **21/21**。 - `assess`：#158 四段全 ✓ · 顺序 OK · 空壳 无 · 两条评论均判 `[可执行]`； #157 四段（结果 / 效果未发生 ⇒ 不长空壳）· 顺序 OK； #159 ⇒ **顺序 ⚠**（`影响面` 落在 `机制` 之后）—— 如实判定，前移或按更正小节保留由属主定。
233 lines
22 KiB
Markdown
233 lines
22 KiB
Markdown
---
|
||
name: ticket-management
|
||
description: 用 Gitea 工单库做「人读 + 机读」双面管理，并**始终维护工单的结构有效性与整洁性**。**动工单（新建或更新）前先做结构评估**：把本轮信息按「问题背景 / 处置提案 / 处置结果 / 效果对比」四段**任务全貌**出「落点表」，再过「只记要点」四问闸门（改不了全貌的不进工单）；正文 = 现行唯一权威叙事，评论只留必须可执行物，外部来源只进末尾机读引用块。含 bin/ticket.mjs 的 labels/milestones/list/verify/assess/create/update/comments/comment-add/comment-del/rename，以及不联网、不需要令牌的 selftest 自检。适用于：建单、更新工单正文或评论、整理精简既有工单、校验工单是否合规、用 API 读写 Gitea issue。
|
||
---
|
||
|
||
# ticket-management（Gitea 工单管理）
|
||
|
||
> **定位**：执行方法（怎么做），不含项目结论。
|
||
> **一句话**：**动工单前先评结构 · 只把改变「任务全貌」的要点写进去 · 正文是唯一权威叙事 · 每次改完都自检「有效性 + 整洁性」**。
|
||
|
||
## 0 什么时候用 / 不用
|
||
|
||
**用**：新建工单；**更新**工单（标题 / 正文 / 评论）；整理或精简既有工单；校验工单是否合规；用 API 读标签 / 里程碑 / 工单。
|
||
**不用**：拿工单做排期与资源计划（那是项目管理）；把工作区内部知识库路径写进工单（见 §1 规则 3）。
|
||
|
||
## 1 硬规则（不合规就不建单 / 不改单）
|
||
|
||
> **动工单（新建或更新）前必过两条前置闸门** —— 它们是本技能的**第一动作**，不能事后补：
|
||
> - **闸门 A · 先评结构**（§8.0）：先出**落点表**（本轮每条信息落在**正文哪一段 / 评论 / 外部**），再落笔。**没有落点表，不许改工单。**
|
||
> - **闸门 B · 只记要点**（§8.2）：每条候选信息过**四问** —— **改变不了「任务全貌」的，一律不进工单**（工单不是日志）。
|
||
>
|
||
> **改完必过第三条**：**§8.3 自检 + `verify`（§7）全过**，才算改完（见规则 4）。
|
||
|
||
1. **标签零新增 · 且建单必传** —— 只用仓库既有标签；**不得**为分类新建标签（标签是给人扫的稀缺资源，词表一膨胀人就不再用了）；**建单 `--label=<id>` 为必传参数**，缺失或 id 无效 ⇒ 工具**拒建**（实测 `#156`/`#157` 因未传而裸建无标签，用户 2026-09-23 纠正）。
|
||
1b. **问题与解决方案一律落工单 · 但落点只有一个**（用户 2026-09-23 交办，**2026-09-24 修订**）：凡与**问题**或**解决方案**相关的产出（现象 / 根因 / 证据 / 方案与选项 / 执行窗口与风险 / 回退 / 验收），都必须**有工单落点**；但**落点 = 该单的「问题正文」**（见 §8 结构纪律），**不是评论流水**。文档可以详写，工单只写**现行叙事 + 证据指针**（指针进末尾引用块），且单号与外部记录号互指。
|
||
1c. **工单 = 干净时间线（rebase 模型 · 2026-09-24 立 · 用户交办）**：「工单能溯源」指的是**类似 git 的 `rebase`**——**不是** `merge`，**不是**把每个变更都堆上去。要求：**该删删、该合并合并**，只留能读懂的**问题 → 行动 → 现状 → 判据**。**执行细则见 §8。**
|
||
2. **标题 = `【问题域】`**（当前**不能开工**时，把闸门**并进同一个括号**写成 `【域-闸门】`，分隔符是**半角连字符 `-`**；**不要写两个括号**）—— 闸门**只在「当前不能开工」时**出现；能开工就不加（默认即常态，零打扰）。
|
||
3. **正文自包含** —— 人读部分**不得**出现工作区 / 本地路径（`codes/`、`分析/`、`C:\…`、`/home/…`）或内部分析编号；源码引用一律 **仓库相对路径 + 该 ref 的 permalink**。
|
||
4. **结构有效性与整洁性是可交付条件** —— 每次编辑后**必须**跑 §8.3 自检与 `verify`（§7）并**全过**；**结构坏了就不算改完**（宁可先不改）。
|
||
|
||
## 2 标题规范
|
||
|
||
- **前缀（必填，单括号、`-` 分隔）**：`【订单】` `【库存】` `【结算】` `【商品】` `【报表】` `【平台】` `【其他】`；带闸门时**合并成一个括号**：`【域-闸门】`（例 `【报表-等口径】`）—— 分隔符用**半角连字符 `-`**；**不要写两个括号**（`【报表】【等口径】` 已废止）。
|
||
- 词表**可按项目替换**，但**改动须登记**；新域先用 `【其他】`，**同域攒够 3 条再立**新前缀。
|
||
- **闸门（可选）**：`-等口径` `-等取证` `-等部署` —— **仅当「不能开工」**；可开工 ⇒ 括号里只有域。
|
||
- **准入三问**（新增任何段都要过）：① 列表页会按它筛 / 排吗？② 能否从正文推出（能推就别重复占位）？③ 生命周期里会变几次（反复变 = 每次都要改标题）？
|
||
- 按此三问：**问题域、闸门**通过；**优先级**（churn 大）· **端** · **环境** · **版本** · **客户 / 店铺**（敏感）· **批次**（用 milestone）全部不通过。
|
||
|
||
## 3 正文规范
|
||
|
||
### 3.1 首行 = 机读行（也是人读的第一行）
|
||
|
||
域=L1-L2-L3 | 闸门=… | 优先级=… | 类型=… | 模式=… | 端=… | 环境=… | 证据=…
|
||
|
||
- **字段顺序固定**；分隔符 = 空格 + 竖线 + 空格。
|
||
- **`域` 的 L1 必须等于标题主前缀**（机器可校验）；`域` 三段逐级更细、**用半角连字符 `-` 分隔**（`域=L1-L2-L3`，如 `域=报表-统计-模式分列`）：**L1 受控**（= 标题词表）· **L2 受控小词表** · **L3 自由**（表 / 文件 / 函数 / 接口）。
|
||
- 枚举建议：`闸门`=可开工|等口径|等取证|等部署 · `优先级`=立即|本迭代|排队 · `类型`=安全|数据|性能|可用|债务 · `端`=后端|前端|小程序|运维 · `环境`=正式服|测服 · `证据`=E1|E2|需生产取证。
|
||
- 若标题出现闸门段，**必须与 `闸门=` 一致**。
|
||
|
||
### 3.2 正文其余（人读）= 「任务全貌」四段
|
||
|
||
## 问题背景 现象 · 影响面 · 根因（含证据锚点）· 复现
|
||
## 处置提案 打算怎么做 / 已选路线 / 为什么；执行窗口与风险；回退
|
||
## 处置结果 实际做了什么 · 当前状态 ← 未发生就整段不写
|
||
## 效果对比 改前 vs 改后：指标 + 口径 + 时点 ← 未测就整段不写
|
||
（可选补段）## 验收判据 / ## 反证条件 / ## 遗留
|
||
|
||
- **段序固定**（背景 → 提案 → 结果 → 效果）；**未发生的段不写空壳**（宁缺不空）；**判据 / 反证 / 遗留**放四段之后。
|
||
- 证据锚点 = 仓库相对路径:行 + permalink（§4）。**取舍与粒度见 §8.1 / §8.2。**
|
||
|
||
### 3.3 末尾 = 机读引用块（人读渲染不可见）
|
||
|
||
```html
|
||
<!-- 机器可读 · 引用登记（正文已自包含，本段不参与人读）
|
||
ref-owner: <引用对象的拥有者，例如：某分析工作区 / 某会议纪要库>
|
||
refs:
|
||
- <外部编号或文件>
|
||
-->
|
||
```
|
||
|
||
- **必须**写明 `ref-owner`（**引用对象的拥有者**）—— 读者据此知道该去哪儿找、以及**它不在这条工单所在的仓里**。
|
||
- **没有外部引用就整段不要**；也不要把内部编号写进人读部分。
|
||
|
||
## 4 路径口径
|
||
|
||
| | 写法 |
|
||
|---|---|
|
||
| ✅ 源码（本仓） | `path/to/file.go:105` + `https://<host>/<owner>/<repo>/src/commit/<sha>/<path>#L105` |
|
||
| ✅ 依赖 / 框架（**另一个仓**） | 另标仓：`https://<host>/<owner>/<repo>/src/tag/<tag>/<path>#L829` |
|
||
| ⛔ 禁用 | 本地物化前缀（`codes/` · `vendor/` 副本）、工作区路径（`分析/`）、内部分析编号 |
|
||
|
||
⚠ **行号必须按所引 ref 复核** —— 本地克隆常落后远端（实测：本地 `f5b74b2` 落后远端 `main` `c210c293`）。做法：用 API 取该 ref 的文件内容，再在内容里定位行号。
|
||
|
||
## 5 工具 `bin/ticket.mjs`
|
||
|
||
```bash
|
||
# 自检：不联网、不需要令牌 —— 改完脚本先跑这条
|
||
node bin/ticket.mjs selftest
|
||
|
||
# 令牌：GITEA_TOKEN 环境变量，或 --token-file=<含 key=value 的文件>（不落盘、不回显）
|
||
# 取值型选项两种写法等价：--repo=xbc/xbc 与 --repo xbc/xbc
|
||
node bin/ticket.mjs labels --repo=xbc/xbc
|
||
node bin/ticket.mjs milestones --repo=xbc/xbc
|
||
node bin/ticket.mjs list --repo=xbc/xbc --state=open
|
||
node bin/ticket.mjs verify 142 --repo=xbc/xbc # 七项断言
|
||
node bin/ticket.mjs assess 142 --repo=xbc/xbc # 结构评估（落点表底稿）
|
||
node bin/ticket.mjs assess --body-file=body.md # 只评正文（无需令牌）
|
||
node bin/ticket.mjs create --repo=xbc/xbc --title='【平台】…' --body-file=body.md --label=77 [--dry-run]
|
||
node bin/ticket.mjs update 142 --repo=xbc/xbc --body-file=body.md [--title='【平台】…'] [--dry-run]
|
||
node bin/ticket.mjs comments 142 --repo=xbc/xbc [--dump=_备份.md] # 清单 / 删前备份
|
||
node bin/ticket.mjs comment-add 142 --repo=xbc/xbc --body-file=cmt.md [--dry-run]
|
||
node bin/ticket.mjs comment-del 12345 --repo=xbc/xbc [--yes] # 不带 --yes 只预览
|
||
node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径] [--dry-run]
|
||
```
|
||
|
||
| 子命令 | 作用 | 需要 scope |
|
||
|---|---|---|
|
||
| `labels` / `milestones` / `list` | 读（标签 id 是创建时唯一可传的形式） | `read:issue` |
|
||
| `verify <n>` | **校验**（只读）：见 §7 七项断言（含标签非空） | `read:issue` |
|
||
| `selftest` | **自检**（不联网、不需要令牌）：解析器两种写法 + §7 七项断言正反 + §8 结构判定 | 无 |
|
||
| `assess <n>` / `assess --body-file=f` | **结构评估**（只读）：四段现状 / 缺段 / 空壳段 + 评论清单 ⇒ §8.0 落点表底稿 | `read:issue` |
|
||
| `create` | 建单（**先按标题查重**；**`--label` 必传**，缺失 / id 不存在 ⇒ 拒建） | `write:issue` |
|
||
| `update <n>` | 改正文（**标题与正文同一次 PATCH**，§8.1 第 4 条）；过自检，不过 ⇒ 拒改 | `write:issue` |
|
||
| `comments <n>` | 评论清单（id / 字数 / 首行）；`--dump=f` = 全量备份（**删前必做**） | `read:issue` |
|
||
| `comment-add <n>` | 加评论（只放**必须可执行物**，§8.1 第 2 条） | `write:issue` |
|
||
| `comment-del <id>` | 删评论（**默认只预览**；`--yes` 才删 ⇒ 与 `--dump` 备份配套） | `write:issue` |
|
||
| `rename <n>` | 规范化标题（重建前缀，描述不动） | `write:issue` |
|
||
|
||
## 6 常见坑（实测）
|
||
|
||
- **HTTP 分块解码**：`let d = ''; res.on('data', c => d += c)` 会把**跨块的多字节字符**打成 `U+FFFD`（中文标签名就被打坏过）⇒ 必须 `res.setEncoding('utf8')`，或用 `fetch` 的 `text()`。
|
||
- **建单前必须查重**：按标题查，否则会重复建单。
|
||
- **标签传 id**：`POST /issues` 的 `labels` 是**标签 id 数组**，不是名字。
|
||
- **参数写法的坑（已修 · 留档）**：早先 `parseArgs` 只认 `--repo=o/r`，而文档示例写的是 `--repo o/r` ⇒ `xbc/xbc` 被当成位置参数、`repo` 变成布尔 `true`，请求打到 `/repos/true/…`，报出来的是 **403「缺 read 权限」/ 405「方法不允许」—— 全是假故障**，白排查三轮。现在**取值型选项两种写法都收**；改完脚本一律先跑 `selftest` 兜底。
|
||
- **批量改首行时必须保持 ` | ` 形态**（空格 + 竖线 + 空格）：把 `域=…` 换成新值时若顺手吃掉它后面的空格，`闸门=` 会与 `域` 黏成一段 ⇒ **断言 4 全线 FAIL**（实测 14/14 中招，工具拦住了）。
|
||
- **改标题与正文**：都是 `PATCH /repos/{owner}/{repo}/issues/{n}`；**要同一次提交**（用 `update`，见 §8.1 第 4 条）。
|
||
- **令牌 scope**：只读 `read:issue,read:repository` 建不了单（403，报错会写 required scope）；建 / 改需 `write:issue`；`GET /user` 另需 `read:user`。
|
||
- **里程碑可能已被当「状态桶」用**（如「记录工单 / 领取工单 / 完结工单」）⇒ 不要再用它承载闸门，否则两套状态打架；用前先 `milestones` 看语义与 `due_on`。
|
||
- **没有看板时**（`/projects` 返回 404）不要设计「用看板列承载闸门」的流程。
|
||
|
||
## 7 `verify` 的七项断言（可交机器）
|
||
|
||
1. 标题以 `【…】` 开头，且内文 ∈ 问题域词表；
|
||
2. 正文第一行存在且含 `域=`；
|
||
3. **标题主域 = 首行 `域=` 的 L1**（`域` 内以 `-` 分层）；
|
||
4. 标题 `-` 后的闸门 ∈ 词表 **且** 等于首行 `闸门=`；**可开工时标题不得带 `-闸门`**（多写即 FAIL）；
|
||
5. 人读部分（第一个 `<!--` 之前）**不含**工作区路径与内部分析编号 —— 判据用**具体前缀**（`codes/` · `分析/数据/` · `分析/D-`…`分析/F-` · `分析/_tmp` · `分析/_archive` · `86 §` · `80 · V` · 盘符路径）；⚠ **不要用裸 `分析/`**（会误伤中文词组，如「进货分析/商品维度」）；
|
||
6. 正文若含 `<!--` ⇒ 该注释块必须含 `ref-owner:`。
|
||
7. **必须带标签**（`labels` 非空）—— 与建单的 `--label` 必传配套（2026-09-23 加）。
|
||
|
||
> `verify` 管**有效性**（标题 / 首行 / 闸门 / 自包含 / 引用块 / 标签）；**四段结构的体检在 `assess`**（§8.0）—— 两者分工，不要混用。
|
||
|
||
## 8 工单结构纪律（**先评结构 · rebase 模型** · 2026-09-24 立 · 与 §1 闸门 A/B、规则 1b/1c 配套）
|
||
|
||
> **一句话**：**动笔前先定「哪句话放哪儿」；正文 = 现行唯一权威叙事；评论 = 只放必须可执行的东西；过程流水进外部记录，工单里只留指针。**
|
||
|
||
**为什么**：评论流水会把「现行结论」淹掉 —— 旧版清单、已撤回的表述、被更正的数字与现行内容混在一起，读者**分不清主次**，甚至会**照旧版执行**。
|
||
|
||
### 8.0 先评结构：动工单前的五步（**闸门 A**）
|
||
|
||
1. **列候选**：把本轮所有产出（结论 / 证据 / 动作 / 命令 / 读数）逐条列成清单，**先不分正文评论**。
|
||
2. **定全貌**：对每条问「它改的是四段里的哪一段？」（§8.1）—— 一段都落不上的，交 §8.2 淘汰。
|
||
3. **出落点表**（落到临时文件或贴进对话即可，不必提交）：
|
||
|
||
| 候选信息 | 落点 | 理由 |
|
||
|---|---|---|
|
||
| … | 正文「处置结果」 | 改变了「做没做 / 做成什么样」 |
|
||
| … | 正文「效果对比」 | 前后读数 + 口径 + 时点 |
|
||
| … | 评论（可执行） | 必须能照着跑 |
|
||
| … | 外部记录 + 末尾指针 | 逐次取证流水 / 推导过程 |
|
||
|
||
4. **落笔**：正文按 §8.1 的**固定顺序**写；评论只写第 3 步判定为「可执行」的整块。
|
||
5. **自检**：跑 §8.3 + `verify`（§7）。**没过就不算改完。**
|
||
|
||
**机器底稿**：`node bin/ticket.mjs assess <n> --repo=…`（或 `assess --body-file=…`）打印**四段现状 / 缺哪段 / 空壳段 / 评论清单** —— 它只报结构，**判断仍由你（agent）下**。
|
||
|
||
### 8.1 结构性要求（正文骨架 = 「任务全貌」四段）
|
||
|
||
1. **正文按固定顺序承载四段，取舍取决于「发生了没有」**：
|
||
|
||
| 段 | 回答的问题 | 典型小标题 |
|
||
|---|---|---|
|
||
| **① 问题背景**（必备） | 谁 / 什么场景 / 什么问题 · 影响面 · 根因（含证据 / 生产实测） | `## 现象` `## 根因` `## 影响面` `## 生产实测阶梯` |
|
||
| **② 处置提案**（必备） | 打算怎么做 / 已选哪条路线 / 为什么 | `## 方案` `## 机制` `## 两条修复路线` `## 结论` |
|
||
| **③ 处置结果**（按事实） | 实际做了什么 · 当前状态（已执行 / 挂起 / 未动） | `## 执行回执` `## 当前状态` `## 处置结果` |
|
||
| **④ 效果对比**（按事实） | 改前 vs 改后：**指标 + 口径 + 时点**同表对照 | `## 效果对比` `## 生产基线 T0` `## T0 / T1 对照` |
|
||
|
||
- ③④ **只在真的做了 / 真的测了之后**才写；**未发生就整段不写**（不留空壳 —— 空壳等于噪音）。
|
||
- **同一段可以有多个并列小节**：用 `## <段名> · <子题>`（实测：`## 效果对比 · 生产基线 T0` + `## 效果对比 · T1/T2 判据与实测`）—— `assess` 会**合并计为一节**。
|
||
- **没有「提案」时不要硬造**：`## 结论`（**结论即提案**）可替代；若结论是「**无需处置**」或「**与 #n 不是同一根因**」，就在正文**显式写一段结论声明**。
|
||
- **其他已识别小节**（不计入四段）：`## 验收判据` · `## 反证条件` · `## 遗留` · `## 取证记录`。
|
||
- 正文必须**自包含**（§1 规则 3）—— 只读正文就能回答：**现在什么状态 / 要做什么 / 怎么验收 / 效果如何**。
|
||
2. **评论只保留「必须可执行物」**：可执行 SQL / 命令 / 待跑清单。**其余过程性评论一律删除**（不是「标注过时后留着」）。
|
||
⚠ **可执行物不得因「正文已列名字」而删**（2026-09-24 实测事故）：DDL / SQL 这类东西，**判定可删的唯一判据是「其全文已被正文或另一条评论完整承载」**；只列了对象名（如索引名清单）**不等于**承载了可执行语句 —— 一旦删除，工单就**没法照着做**了。
|
||
**工具辅助**：`assess` / `comments` 会给每条评论标 `[可执行]` / `[? 非可执行]`（**启发式**：含代码围栏或 SQL 关键字）—— 只作提示，**仍需人核**。
|
||
⚠ **工单里的 SQL 必须逐条原样**（2026-09-24 实测事故）：**禁止**对语句做「拼接 / 去尾 / 换分隔符」式字符串变换（实测把 `, ALGORITHM=INPLACE, LOCK=NONE;` 换成逗号 ⇒ 18 条语句连成一段**无分号的废码**）；**回退脚本不得留占位符**（列序 / 唯一性要填实）—— 否则「可执行物」实际**不可执行**。**投递前必须实跑验证**（结构影子库零数据逐条执行，正反向都要过）。
|
||
3. **过程流水与逐条取证进外部记录**（分析文档 / 台账底册），工单里**只在末尾引用块登记**（§3.3）；人读部分**不得**出现外部路径与编号。
|
||
4. **口径更新必须同步正文与标题**：凡结论/数量/清单发生变化（如「24 条」→「23 条」、「删 5」→「删 4」），必须**同一次**改掉**标题 + 正文 + 摘要评论**（`update` 支持标题与正文同提交）；**旧口径若仍在被引用（如执行清单），必须显式标注「已废止」并写明正确值**。
|
||
5. **删除前必须备份**：删评论前先 `comments <n> --dump=<文件>` **全量导出**（含 `comment id` 与全文），并在交付说明里给路径 —— **删除 ≠ 丢失**。
|
||
6. **一次工单一条线程**：同一问题的新证据**追加到正文**，不要为每条证据新开评论；跨单内容**只在一处详写**，其余用 `#n` 交叉引用。
|
||
|
||
### 8.2 只记要点：四问闸门（**闸门 B**）
|
||
|
||
> **判据只有一句**：**这条信息改变「任务全貌」的答案吗？** 改不了 ⇒ **不进工单**。
|
||
|
||
逐条问：
|
||
1. **问题背景**：它让人更清楚「谁 / 什么场景 / 为什么坏」吗？
|
||
2. **处置提案**：它改变「打算怎么做 / 为什么选它」吗？
|
||
3. **处置结果**：它改变「实际做了什么 / 现在什么状态」吗？
|
||
4. **效果对比**：它给出「前后对照的指标 / 口径 / 时点」吗？
|
||
|
||
**四问全否 ⇒ 不进工单**（改放外部记录；需要时只在末尾引用块留指针）。**典型排除物**：
|
||
- 逐次取证的**读数流水**（进底册 / 分析文档；正文只留**结论 + 现行读数**）；
|
||
- 被取代的**旧版清单 / 旧数字 / 已撤回表述**（**删**；确需防误用的，正文只留一句「**已废止，正确值 X**」）；
|
||
- **探索与试错过程**（试过哪些路、哪条走不通）；
|
||
- **与工单无关的旁证**（相邻话题 ⇒ 用 `#n` 交叉引用，不复制）。
|
||
|
||
⚠ **要点 ≠ 短**：结论、**可执行物**、判据与反证条件都属于**要点**，必须**完整**（如「删 22 条」的**全文清单**）。「不事无巨细」约束的是**过程流水**，**不是结论的完整性** —— 把可执行物删成「见某文档」是**另一类破坏**（§8.1 第 2 条两条实测事故）。
|
||
|
||
### 8.3 结构有效性与整洁性自检（**每次编辑后必跑 · 规则 4**）
|
||
|
||
**有效性**（结构还在不在）：
|
||
- [ ] `node bin/ticket.mjs verify <n> --repo=…` **7/7 全过**（§7）；
|
||
- [ ] `assess` 报告：**必备两段在**（背景 / 提案），出现者**按序**，**无空壳段**；
|
||
- [ ] 标题主域 = 首行 `域=` 的 L1；标题闸门 = 首行 `闸门=`；
|
||
- [ ] **只读正文**能独立回答：现在什么状态 / 要做什么 / 怎么验收 / 效果如何。
|
||
|
||
**整洁性**（有没有垃圾）：
|
||
- [ ] 四段**顺序正确**，**没有空壳段**（标题下没内容 ⇒ 删）；
|
||
- [ ] 正文**没有**「旧版 / 已废止」并列堆叠 —— 旧值已删，或压成一句「已废止，正确值 X」；
|
||
- [ ] 标题 / 正文 / 评论里的**数量与范围一致**（「23 条」不能只改一处）；
|
||
- [ ] 评论**只剩可执行物**，且**可执行物完整可跑**（是全文，不是对象名）；工具标 `[? 非可执行]` 的**逐条核过**；
|
||
- [ ] 同一条信息**没有两处详写**（一处详写，其余 `#n` 交叉引用）；
|
||
- [ ] 首行机读行仍是 ` | ` 形态、字段顺序未被打乱。
|
||
|
||
## 9 本工具实测补充（2026-09-24）
|
||
|
||
- **`--repo` 两种写法都可以**：`--repo=xbc/xbc` 与 `--repo xbc/xbc`。❗**旧口径已废止**（早期只认等号形式，示例写成空格 ⇒ 参数错位，症状是 403 / 405 / 404 的**假故障**）；**改完脚本先跑 `selftest`**。
|
||
- **令牌**：`GITEA_TOKEN` 环境变量，或 `--token-file=<含 `token`/`accessToken` 的 key=value 文件>`（按行匹配 `/token/i`）。缺令牌时报错但**错误信息可能表现为 404**（私有仓隐藏权限差异）⇒ 先查令牌再怀疑工单。`assess --body-file` **只评正文，不需要令牌**。
|
||
- **评论的增删改已收进工具**：`comments`（清单 / `--dump` 备份）· `comment-add` · `comment-del`（**默认只预览**，`--yes` 才删）。底层仍是 `POST /issues/{n}/comments` · `PATCH /issues/comments/{id}` · `DELETE /issues/comments/{id}`（204）。
|
||
- **改工单正文用 `update`**：它把**标题与正文在同一次 PATCH 提交**（§8.1 第 4 条的机器保证）；只想改标题用 `rename`。
|
||
- **`assess` 的界限**：它是**只读结构体检**，报告「缺哪段 / 哪段空壳 / 评论几条」，**不替你判断内容对不对**；落点表仍要人来填（§8.0 第 3 步）。
|