agents-skills/ticket-management/SKILL.md

---
name: ticket-management
description: 用 Gitea 工单库做「人读 + 机读」双面管理，并**始终维护工单的结构有效性与整洁性**。**动工单（新建或更新）前先做结构评估**：把本轮信息按「问题背景 / 处置提案 / 处置结果 / 效果对比」四段**任务全貌**出「落点表」，再过「只记要点」四问闸门（改不了全貌的不进工单）；正文 = 现行唯一权威叙事，评论只留必须可执行物，外部来源只进末尾机读引用块。含 bin/ticket.mjs 的 labels/milestones/list/verify/assess/create/update/comments/comment-add/comment-del/rename。适用于：建单、更新工单正文或评论、整理精简既有工单、校验工单是否合规、用 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
# 令牌：GITEA_TOKEN 环境变量，或 --token-file=<含 key=value 的文件>（不落盘、不回显）
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` |
| `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 数组**，不是名字。
- **批量改首行时必须保持 ` | ` 形态**（空格 + 竖线 + 空格）：把 `域=…` 换成新值时若顺手吃掉它后面的空格，`闸门=` 会与 `域` 黏成一段 ⇒ **断言 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 / T1 对照` |

   - ③④ **只在真的做了 / 真的测了之后**才写；**未发生就整段不写**（不留空壳 —— 空壳等于噪音）。
   - **可选补段**（一律放四段之后）：`## 验收判据` · `## 反证条件` · `## 遗留`。
   - 正文必须**自包含**（§1 规则 3）—— 只读正文就能回答：**现在什么状态 / 要做什么 / 怎么验收 / 效果如何**。
2. **评论只保留「必须可执行物」**：可执行 SQL / 命令 / 待跑清单。**其余过程性评论一律删除**（不是「标注过时后留着」）。
   ⚠ **可执行物不得因「正文已列名字」而删**（2026-09-24 实测事故）：DDL / 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`）时，`xbc/xbc` 会被当成**单号**去请求 ⇒ 报 `读取失败 status=404` 且后面紧跟一行 `#xbc/xbc 读取失败` —— 这是**参数错位**，不是权限问题。
- **令牌**：`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 步）。