agents-skills/ticket-management/SKILL.md

name, description

name	description
ticket-management	用 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 末尾 = 机读引用块（人读渲染不可见）

<!-- 机器可读 · 引用登记（正文已自包含，本段不参与人读）
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

# 自检：不联网、不需要令牌 —— 改完脚本先跑这条
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 / 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。❗旧口径已废止（早期只认等号形式，示例写成空格 ⇒ 参数错位，症状是 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 步）。