feat(ticket-management)!: 「任务全貌」四段 → 五段，新增必备段「经验教训」
用户 2026-09-24 指出漏了一个要点：**经验教训**也应是**重点结构**的一部分。 【改动】 - SKILL §8.1：正文骨架加第 ⑤ 段 `## 经验教训`（**必备**，排在 `效果对比` 之后）—— 必须是**可复用结论**（对象 + 动作 / 判据）；**尚未定性写「暂无（原因）」**， **不许留空壳，也不许写「加强测试」这类套话**。 - §8.2 闸门 B：**四问 → 五问**（新增「它给出『下次怎么避免 / 怎么做』的可复用结论吗？」）。 - §8.3 整洁性自检：加「经验教训须是可复用结论、非套话；未定性须显式写『暂无（原因）』」。 - §3.2 骨架 / §8.0 定全貌 / §8.1 标题 / §5 assess 表 / §7 分工注 / §8.3 有效性 —— 措辞全部同步。 - `bin/ticket.mjs`：`SECTIONS` 加第 5 段（词表 `经验教训` / `教训` / `复盘`）；`assess` 表头改「五段」； **必备段缺失提示按段区分**（教训 ⇒ 指「暂无（原因）」；提案 ⇒ 指「结论即提案 / 无需处置」）； `selftest` 20 → **21**。 - `templates/issue.md` 加 `## 经验教训`；README 技能行改「五段任务全貌」。 - （顺带更正）README 里「本机已按此接好 ticket-management」**与实测不符**（本机无该 junction）⇒ 去掉机器特有断言 —— 可复用文档不写本地状态。 【验证 · E1 · 本机】 - `node --check` 通过；`selftest` **21/21**；`grep 四段|四问` ⇒ **0 残留**。 - `assess 158`（真跑）⇒ 五段中**恰好第 ⑤ 段未识别**（正是用户指出的缺口，`#158` 待补经验教训）； 顺序 OK · 空壳 无。 - 合成「五段齐」正文 ⇒ 五段全 ✓ · 顺序 OK · 空壳 无。
This commit is contained in:
+21
-16
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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。
|
||||
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 工单管理）
|
||||
@@ -17,7 +17,7 @@ description: 用 Gitea 工单库做「人读 + 机读」双面管理，并**始
|
||||
|
||||
> **动工单（新建或更新）前必过两条前置闸门** —— 它们是本技能的**第一动作**，不能事后补：
|
||||
> - **闸门 A · 先评结构**（§8.0）：先出**落点表**（本轮每条信息落在**正文哪一段 / 评论 / 外部**），再落笔。**没有落点表，不许改工单。**
|
||||
> - **闸门 B · 只记要点**（§8.2）：每条候选信息过**四问** —— **改变不了「任务全貌」的，一律不进工单**（工单不是日志）。
|
||||
> - **闸门 B · 只记要点**（§8.2）：每条候选信息过**五问** —— **改变不了「任务全貌」的，一律不进工单**（工单不是日志）。
|
||||
>
|
||||
> **改完必过第三条**：**§8.3 自检 + `verify`（§7）全过**，才算改完（见规则 4）。
|
||||
|
||||
@@ -47,15 +47,16 @@ description: 用 Gitea 工单库做「人读 + 机读」双面管理，并**始
|
||||
- 枚举建议：`闸门`=可开工|等口径|等取证|等部署 · `优先级`=立即|本迭代|排队 · `类型`=安全|数据|性能|可用|债务 · `端`=后端|前端|小程序|运维 · `环境`=正式服|测服 · `证据`=E1|E2|需生产取证。
|
||||
- 若标题出现闸门段，**必须与 `闸门=` 一致**。
|
||||
|
||||
### 3.2 正文其余（人读）= 「任务全貌」四段
|
||||
### 3.2 正文其余（人读）= 「任务全貌」五段
|
||||
|
||||
## 问题背景 现象 · 影响面 · 根因（含证据锚点）· 复现
|
||||
## 处置提案 打算怎么做 / 已选路线 / 为什么；执行窗口与风险；回退
|
||||
## 处置结果 实际做了什么 · 当前状态 ← 未发生就整段不写
|
||||
## 效果对比 改前 vs 改后：指标 + 口径 + 时点 ← 未测就整段不写
|
||||
（可选补段）## 验收判据 / ## 反证条件 / ## 遗留
|
||||
## 经验教训 下次怎么避免 / 怎么做（可复用） ← 必备；未定性写「暂无（原因）」
|
||||
（其他小节）## 验收判据 / ## 反证条件 / ## 遗留 / ## 取证记录
|
||||
|
||||
- **段序固定**（背景 → 提案 → 结果 → 效果）；**未发生的段不写空壳**（宁缺不空）；**判据 / 反证 / 遗留**放四段之后。
|
||||
- **段序固定**（背景 → 提案 → 结果 → 效果 → 教训）；**未发生的段不写空壳**（宁缺不空）；**判据 / 反证 / 遗留 / 取证记录**放五段之后。
|
||||
- 证据锚点 = 仓库相对路径:行 + permalink（§4）。**取舍与粒度见 §8.1 / §8.2。**
|
||||
|
||||
### 3.3 末尾 = 机读引用块（人读渲染不可见）
|
||||
@@ -108,7 +109,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
| `labels` / `milestones` / `list` | 读（标签 id 是创建时唯一可传的形式） | `read:issue` |
|
||||
| `verify <n>` | **校验**（只读）：见 §7 七项断言（含标签非空） | `read:issue` |
|
||||
| `selftest` | **自检**（不联网、不需要令牌）：解析器两种写法 + §7 七项断言正反 + §8 结构判定 | 无 |
|
||||
| `assess <n>` / `assess --body-file=f` | **结构评估**（只读）：四段现状 / 缺段 / 空壳段 + 评论清单 ⇒ §8.0 落点表底稿 | `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` |
|
||||
@@ -138,7 +139,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
6. 正文若含 `<!--` ⇒ 该注释块必须含 `ref-owner:`。
|
||||
7. **必须带标签**（`labels` 非空）—— 与建单的 `--label` 必传配套（2026-09-23 加）。
|
||||
|
||||
> `verify` 管**有效性**（标题 / 首行 / 闸门 / 自包含 / 引用块 / 标签）；**四段结构的体检在 `assess`**（§8.0）—— 两者分工，不要混用。
|
||||
> `verify` 管**有效性**（标题 / 首行 / 闸门 / 自包含 / 引用块 / 标签）；**五段结构的体检在 `assess`**（§8.0）—— 两者分工，不要混用。
|
||||
|
||||
## 8 工单结构纪律（**先评结构 · rebase 模型** · 2026-09-24 立 · 与 §1 闸门 A/B、规则 1b/1c 配套）
|
||||
|
||||
@@ -149,7 +150,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
### 8.0 先评结构：动工单前的五步（**闸门 A**）
|
||||
|
||||
1. **列候选**：把本轮所有产出（结论 / 证据 / 动作 / 命令 / 读数）逐条列成清单，**先不分正文评论**。
|
||||
2. **定全貌**：对每条问「它改的是四段里的哪一段？」（§8.1）—— 一段都落不上的，交 §8.2 淘汰。
|
||||
2. **定全貌**：对每条问「它改的是五段里的哪一段？」（§8.1）—— 一段都落不上的，交 §8.2 淘汰。
|
||||
3. **出落点表**（落到临时文件或贴进对话即可，不必提交）：
|
||||
|
||||
| 候选信息 | 落点 | 理由 |
|
||||
@@ -162,11 +163,11 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
4. **落笔**：正文按 §8.1 的**固定顺序**写；评论只写第 3 步判定为「可执行」的整块。
|
||||
5. **自检**：跑 §8.3 + `verify`（§7）。**没过就不算改完。**
|
||||
|
||||
**机器底稿**：`node bin/ticket.mjs assess <n> --repo=…`（或 `assess --body-file=…`）打印**四段现状 / 缺哪段 / 空壳段 / 评论清单** —— 它只报结构，**判断仍由你（agent）下**。
|
||||
**机器底稿**：`node bin/ticket.mjs assess <n> --repo=…`（或 `assess --body-file=…`）打印**五段现状 / 缺哪段 / 空壳段 / 评论清单** —— 它只报结构，**判断仍由你（agent）下**。
|
||||
|
||||
### 8.1 结构性要求（正文骨架 = 「任务全貌」四段）
|
||||
### 8.1 结构性要求（正文骨架 = 「任务全貌」五段）
|
||||
|
||||
1. **正文按固定顺序承载四段，取舍取决于「发生了没有」**：
|
||||
1. **正文按固定顺序承载五段，取舍取决于「发生了没有」**：
|
||||
|
||||
| 段 | 回答的问题 | 典型小标题 |
|
||||
|---|---|---|
|
||||
@@ -174,11 +175,13 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
| **② 处置提案**（必备） | 打算怎么做 / 已选哪条路线 / 为什么 | `## 方案` `## 机制` `## 两条修复路线` `## 结论` |
|
||||
| **③ 处置结果**（按事实） | 实际做了什么 · 当前状态（已执行 / 挂起 / 未动） | `## 执行回执` `## 当前状态` `## 处置结果` |
|
||||
| **④ 效果对比**（按事实） | 改前 vs 改后：**指标 + 口径 + 时点**同表对照 | `## 效果对比` `## 生产基线 T0` `## T0 / T1 对照` |
|
||||
| **⑤ 经验教训**（必备） | **下次怎么避免 / 怎么做** —— 可复用到别的单 | `## 经验教训` `## 教训` `## 复盘` |
|
||||
|
||||
- ③④ **只在真的做了 / 真的测了之后**才写；**未发生就整段不写**（不留空壳 —— 空壳等于噪音）。
|
||||
- **⑤ 经验教训是必备段**：必须是**可复用的结论** —— 写清「**对象 + 动作 / 判据**」；确实尚未定性就写「**暂无（原因）**」，**不许留空壳，也不许写「加强测试」这类套话**。
|
||||
- **同一段可以有多个并列小节**：用 `## <段名> · <子题>`（实测：`## 效果对比 · 生产基线 T0` + `## 效果对比 · T1/T2 判据与实测`）—— `assess` 会**合并计为一节**。
|
||||
- **没有「提案」时不要硬造**：`## 结论`（**结论即提案**）可替代；若结论是「**无需处置**」或「**与 #n 不是同一根因**」，就在正文**显式写一段结论声明**。
|
||||
- **其他已识别小节**（不计入四段）：`## 验收判据` · `## 反证条件` · `## 遗留` · `## 取证记录`。
|
||||
- **其他已识别小节**（不计入五段）：`## 验收判据` · `## 反证条件` · `## 遗留` · `## 取证记录`。
|
||||
- 正文必须**自包含**（§1 规则 3）—— 只读正文就能回答：**现在什么状态 / 要做什么 / 怎么验收 / 效果如何**。
|
||||
2. **评论只保留「必须可执行物」**：可执行 SQL / 命令 / 待跑清单。**其余过程性评论一律删除**（不是「标注过时后留着」）。
|
||||
⚠ **可执行物不得因「正文已列名字」而删**（2026-09-24 实测事故）：DDL / SQL 这类东西，**判定可删的唯一判据是「其全文已被正文或另一条评论完整承载」**；只列了对象名（如索引名清单）**不等于**承载了可执行语句 —— 一旦删除，工单就**没法照着做**了。
|
||||
@@ -189,7 +192,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
5. **删除前必须备份**：删评论前先 `comments <n> --dump=<文件>` **全量导出**（含 `comment id` 与全文），并在交付说明里给路径 —— **删除 ≠ 丢失**。
|
||||
6. **一次工单一条线程**：同一问题的新证据**追加到正文**，不要为每条证据新开评论；跨单内容**只在一处详写**，其余用 `#n` 交叉引用。
|
||||
|
||||
### 8.2 只记要点：四问闸门（**闸门 B**）
|
||||
### 8.2 只记要点：五问闸门（**闸门 B**）
|
||||
|
||||
> **判据只有一句**：**这条信息改变「任务全貌」的答案吗？** 改不了 ⇒ **不进工单**。
|
||||
|
||||
@@ -198,8 +201,9 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
2. **处置提案**：它改变「打算怎么做 / 为什么选它」吗？
|
||||
3. **处置结果**：它改变「实际做了什么 / 现在什么状态」吗？
|
||||
4. **效果对比**：它给出「前后对照的指标 / 口径 / 时点」吗？
|
||||
5. **经验教训**：它给出「**下次怎么避免 / 怎么做**」的**可复用**结论吗？
|
||||
|
||||
**四问全否 ⇒ 不进工单**（改放外部记录；需要时只在末尾引用块留指针）。**典型排除物**：
|
||||
**五问全否 ⇒ 不进工单**（改放外部记录；需要时只在末尾引用块留指针）。**典型排除物**：
|
||||
- 逐次取证的**读数流水**（进底册 / 分析文档；正文只留**结论 + 现行读数**）；
|
||||
- 被取代的**旧版清单 / 旧数字 / 已撤回表述**（**删**；确需防误用的，正文只留一句「**已废止，正确值 X**」）；
|
||||
- **探索与试错过程**（试过哪些路、哪条走不通）；
|
||||
@@ -211,12 +215,13 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径]
|
||||
|
||||
**有效性**（结构还在不在）：
|
||||
- [ ] `node bin/ticket.mjs verify <n> --repo=…` **7/7 全过**（§7）；
|
||||
- [ ] `assess` 报告：**必备两段在**（背景 / 提案），出现者**按序**，**无空壳段**；
|
||||
- [ ] `assess` 报告：**必备段在**（背景 / 提案 / 经验教训），出现者**按序**，**无空壳段**；
|
||||
- [ ] 标题主域 = 首行 `域=` 的 L1；标题闸门 = 首行 `闸门=`；
|
||||
- [ ] **只读正文**能独立回答：现在什么状态 / 要做什么 / 怎么验收 / 效果如何。
|
||||
|
||||
**整洁性**（有没有垃圾）：
|
||||
- [ ] 四段**顺序正确**，**没有空壳段**（标题下没内容 ⇒ 删）；
|
||||
- [ ] 五段**顺序正确**，**没有空壳段**（标题下没内容 ⇒ 删）；
|
||||
- [ ] 「**经验教训**」是**可复用结论**（有对象 + 动作 / 判据），不是套话；尚未定性则已显式写「暂无（原因）」；
|
||||
- [ ] 正文**没有**「旧版 / 已废止」并列堆叠 —— 旧值已删，或压成一句「已废止，正确值 X」；
|
||||
- [ ] 标题 / 正文 / 评论里的**数量与范围一致**（「23 条」不能只改一处）；
|
||||
- [ ] 评论**只剩可执行物**，且**可执行物完整可跑**（是全文，不是对象名）；工具标 `[? 非可执行]` 的**逐条核过**；
|
||||
|
||||
Reference in New Issue
Block a user