diff --git a/README.md b/README.md index ea5740f..f847747 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # agents-skills -> 可复用的 **agent 技能库**（执行方法，不含项目结论）。每个技能一个**顶层目录** + `SKILL.md`，因此本仓**可以直接作为技能根**（如 junction 到 `<项目>/.dsh/skills` 后由 DSH 发现）。 +> 可复用的 **agent 技能库**（执行方法，不含项目结论）。每个技能一个**顶层目录** + `SKILL.md`，按 DSH 的发现规则逐个接到技能根下即可（见「使用」）。 ## 技能清单 | 技能 | 覆盖 | 主要文件 | |---|---|---| -| `ticket-management` | Gitea 工单的「人读 + 机读」双面管理，且**始终维护结构有效性与整洁性**：**动工单前先评结构**（四段任务全貌 = 问题背景 / 处置提案 / 处置结果 / 效果对比 → 出「落点表」）· **只记要点**（改不了全貌的不进工单）· 标题【问题域】（闸门并入同一括号）· 正文首行机读 · 正文自包含 · 来源只进末尾机读引用块 · `verify`（有效性）+ `assess`（结构体检） | `SKILL.md` · `bin/ticket.mjs` · `templates/issue.md` | +| `ticket-management` | Gitea 工单的「人读 + 机读」双面管理，并**始终维护结构有效性与整洁性**：**动工单前先评结构**（四段任务全貌 = 问题背景 / 处置提案 / 处置结果 / 效果对比 → 出「落点表」）· **只记要点**（改不了全貌的不进工单）· 标题问题域前缀 · 正文首行机读 · 正文自包含 · 来源只进末尾机读引用块 · `verify`（有效性）+ `assess`（结构体检）+ 离线 `selftest` | `SKILL.md` · `bin/ticket.mjs` · `templates/issue.md` | ## 约定 @@ -16,11 +16,30 @@ 4. **工具要能自检**：脚本必须能在自己的仓里跑通一条最小用例。 5. **令牌不落盘**：脚本从 `GITEA_TOKEN` 或 `--token-file` 读，**绝不把令牌写进仓库、URL 或提交**。 -## 使用（把本仓接到项目） +## 使用（把本仓接到 DSH） + +DSH 的技能发现**只有一层**：技能根下的 `/SKILL.md` 或平铺 `.md`，**不认**嵌套的 `**/SKILL.md`。所以要把**每个技能目录**接到技能根下，不能把本仓整体 junction 成 `<技能根>/agents-skills`（那层里没有 `SKILL.md`，会发现不到）。 + +技能根与优先级（同名时 rank 小者胜）： + +| rank | 来源 | 路径 | +|---|---|---| +| 100 | 项目 | `<项目根>/.dsh/skills` | +| 200 | 项目 | `<项目根>/.agents/skills` | +| 400 | 用户 | `~/.dsh/skills`（即 `$DSH_HOME/skills`） | ```powershell -# 方式一：作为技能根之一（Windows 目录 junction） -New-Item -ItemType Junction -Path '<项目>/.dsh/skills/agents-skills' -Target '<本仓路径>' -# 方式二：只取一个技能 -Copy-Item -Recurse '<本仓>/ticket-management' '<项目>/.dsh/skills/' +# 方式一：用户级 —— 所有项目都可见（推荐；本机已按此接好 ticket-management） +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.dsh\skills" +New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\skills\ticket-management" -Target '<本仓>\ticket-management' + +# 方式二：项目级 —— 只在该项目可见 +New-Item -ItemType Junction -Path '<项目>/.dsh/skills/ticket-management' -Target '<本仓>\ticket-management' + +# 方式三：拷一份 —— 与本仓脱钩，之后改动不再同步 +Copy-Item -Recurse '<本仓>\ticket-management' '<技能根>\' ``` + +junction 指向本仓 ⇒ 在这里改 `SKILL.md`，DSH 的下一次目录扫描即生效：**正文编辑不用重启，也不用重新链接**。技能名取自 frontmatter 的 `name`；技能根下的新增 / 改名 / 删除由 DSH 的目录监视自动发现。 + +> 进阶：也可让本仓**整体**充当一个技能根（`@deepseek-ai/dsh-skill-filesystem` 的 `customSkillDirs`，rank 300），但要在部署侧给该插件配目录；默认预设不带这行配置。 \ No newline at end of file diff --git a/ticket-management/SKILL.md b/ticket-management/SKILL.md index 8695adb..973bcd9 100644 --- a/ticket-management/SKILL.md +++ b/ticket-management/SKILL.md @@ -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。适用于：建单、更新工单正文或评论、整理精简既有工单、校验工单是否合规、用 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 工单管理） @@ -84,7 +84,11 @@ refs: ## 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 @@ -103,6 +107,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径] |---|---|---| | `labels` / `milestones` / `list` | 读（标签 id 是创建时唯一可传的形式） | `read:issue` | | `verify ` | **校验**（只读）：见 §7 七项断言（含标签非空） | `read:issue` | +| `selftest` | **自检**（不联网、不需要令牌）：解析器两种写法 + §7 七项断言正反 + §8 结构判定 | 无 | | `assess ` / `assess --body-file=f` | **结构评估**（只读）：四段现状 / 缺段 / 空壳段 + 评论清单 ⇒ §8.0 落点表底稿 | `read:issue` | | `create` | 建单（**先按标题查重**；**`--label` 必传**，缺失 / id 不存在 ⇒ 拒建） | `write:issue` | | `update ` | 改正文（**标题与正文同一次 PATCH**，§8.1 第 4 条）；过自检，不过 ⇒ 拒改 | `write:issue` | @@ -116,6 +121,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径] - **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`。 @@ -216,7 +222,7 @@ node bin/ticket.mjs rename 142 --repo=xbc/xbc --domain=平台 [--gate=等口径] ## 9 本工具实测补充（2026-09-24） -- **`--repo` 必须用等号形式**：`--repo=xbc/xbc`。写成空格形式（`--repo xbc/xbc`）时，`xbc/xbc` 会被当成**单号**去请求 ⇒ 报 `读取失败 status=404` 且后面紧跟一行 `#xbc/xbc 读取失败` —— 这是**参数错位**，不是权限问题。 +- **`--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`。 diff --git a/ticket-management/bin/ticket.mjs b/ticket-management/bin/ticket.mjs index 8455c0f..5e3ab78 100644 --- a/ticket-management/bin/ticket.mjs +++ b/ticket-management/bin/ticket.mjs @@ -21,11 +21,18 @@ const SECTIONS = [ ]; const OPTIONAL_SECTIONS = ["验收判据", "反证条件", "遗留"]; +// 取值型选项：`--repo=o/r` 与 `--repo o/r` 两种写法都收（等价；布尔开关不吃后一个参数） +const VALUE_OPTS = ["repo", "title", "body-file", "label", "milestone", "token-file", "host", "state", "limit", "domain", "gate", "dump"]; function parseArgs(argv) { const pos = [], opt = {}; - for (const a of argv) { - if (a.startsWith("--")) { const i = a.indexOf("="); if (i < 0) opt[a.slice(2)] = true; else opt[a.slice(2, i)] = a.slice(i + 1); } - else pos.push(a); + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + if (!a.startsWith("--")) { pos.push(a); continue; } + const j = a.indexOf("="); + if (j >= 0) { opt[a.slice(2, j)] = a.slice(j + 1); continue; } + const k = a.slice(2), next = argv[i + 1]; + if (VALUE_OPTS.indexOf(k) >= 0 && next !== undefined && !next.startsWith("--")) { opt[k] = next; i++; } + else opt[k] = true; } return { pos: pos, opt: opt }; } @@ -138,6 +145,42 @@ function printStructure(body) { console.log(" 空壳段：" + (st.empty.length ? "✗ " + st.empty.join(" · ") + "（删掉或补齐）" : "无")); console.log(" 可选段：" + (st.optional.length ? st.optional.join(" · ") : "无")); } +// 自检（不联网、不需要令牌）：node bin/ticket.mjs selftest +function cmdSelftest() { + let pass = 0, fail = 0; + const t = function (name, ok) { if (ok) { pass++; console.log(" PASS " + name); } else { fail++; console.log(" FAIL " + name); } }; + // —— 解析器：两种写法等价 · 布尔开关不吃后一个参数 —— + const p1 = parseArgs(["list", "--repo", "xbc/xbc", "--state=open"]); + t("空格写法 --repo xbc/xbc", p1.opt.repo === "xbc/xbc" && p1.pos[0] === "list" && p1.opt.state === "open"); + const p2 = parseArgs(["verify", "142", "--repo=xbc/xbc"]); + t("等号写法 --repo=xbc/xbc", p2.opt.repo === "xbc/xbc" && p2.pos[1] === "142"); + const p3 = parseArgs(["create", "--repo=xbc/xbc", "--dry-run"]); + t("布尔开关不吃后面的参数", p3.opt["dry-run"] === true && p3.opt.repo === "xbc/xbc"); + const p4 = parseArgs(["comments", "158", "--dump", "_bak.md"]); + t("新增取值型选项同规则（--dump）", p4.opt.dump === "_bak.md" && p4.pos[1] === "158"); + // —— §7 七项断言：合规样例 + 反例 —— + const ok = checksOf("【报表-等口径】报表未按经营模式分列", "域=报表-统计-模式分列 | 闸门=等口径 | 优先级=本迭代 | 类型=数据 | 模式=改造 | 端=后端 | 环境=测服 | 证据=E1" + NL + NL + "正文"); + t("合规样例 6/6", ok.every(function (c) { return c[1]; })); + const b1 = checksOf("【报表】报表未按经营模式分列", "域=报表-统计-模式分列 | 闸门=可开工 | 优先级=本迭代" + NL + NL + "见 codes/foo.go"); + t("标题无闸门 + 首行 闸门=可开工 ⇒ 断言 4 通过", b1[3][1] === true); + t("人读部分含禁用前缀 ⇒ 断言 5 失败", b1[4][1] === false); + const b2 = checksOf("【报表-等口径】x", "域=报表-统计-模式分列 | 闸门=可开工"); + t("标题带闸门但首行 闸门=可开工 ⇒ 断言 4 失败", b2[3][1] === false); + const b3 = checksOf("【报表】x", "域=报表-统计-模式分列" + NL + NL + "