@zhushanwen/pi-exec-skills 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-exec-skills",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Shared skill acquisition library for Pi extensions — disk-scanning discovery over pi's four skill roots (settings overrides + plan-exec frontmatter marker + name dedup) and the pi-registry execution gate (resolveSkills). Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
@@ -35,6 +35,6 @@
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }

package/src/__tests__/exec-skills.test.ts

@@ -326,9 +326,9 @@ describe("isEnabledByOverrides（overrides 三级优先级，pi 同构）", () =
   });
 
   // globToRegExp 未测分支（minimatch 子集重实现，与 pi 求值的偏差域）：? 单字符 /
-  // [...] 字符类（含取反）/ 未闭合 ] 字面量 / 正则元字符转义——经公开入口锁语义，
+  // [...] 字符类（含取反）/ 未结束 ] 字面量 / 正则元字符转义——经公开入口锁语义，
   // 任一分支回归即红（false = 禁用命中，true = 默认启用未命中）。
-  it("? / 字符类 / 取反 / 未闭合 ] / 元字符转义分支", () => {
+  it("? / 字符类 / 取反 / 未结束 ] / 元字符转义分支", () => {
     const baseDir = join(world.root, "base");
     const filePath = join(baseDir, "skills", "demo", "SKILL.md");
     // ? = 单字符且不跨 /：dem? 命中 o；demo? 差一字符不命中；skills?demo 不跨 / 不命中
@@ -341,7 +341,7 @@ describe("isEnabledByOverrides（overrides 三级优先级，pi 同构）", () =
     // 取反类：[!a-z] 排除小写字母 → d 不命中；[!0-9] 排除数字 → d 命中
     expect(isEnabledByOverrides(filePath, ["!skills/[!a-z]emo/SKILL.md"], baseDir)).toBe(true);
     expect(isEnabledByOverrides(filePath, ["!skills/[!0-9]emo/SKILL.md"], baseDir)).toBe(false);
-    // 未闭合 ]：[ 按字面量处理（不吞后续段），demo 目录无 [ → 不命中
+    // 未结束 ]：[ 按字面量处理（不吞后续段），demo 目录无 [ → 不命中
     expect(isEnabledByOverrides(filePath, ["!skills/demo[/SKILL.md"], baseDir)).toBe(true);
     // 字符类单字：dem[o] 命中（dem 后是 o）；dem[w] 不命中（dem 后非 w）
     expect(isEnabledByOverrides(filePath, ["!skills/dem[o]/SKILL.md"], baseDir)).toBe(false);
@@ -371,7 +371,7 @@ describe("pi 实装对拍（loadSkillsFromDir 语义锚）", () => {
    * - beta：无 frontmatter name → 目录名 fallback（⑥）
    * - no-desc：无 description → ③ 必填门排除
    * - nested/deep/gamma：递归遍历
-   * - loose.md：根级散 .md（loadSkillsFromDir 收集，⑦登记面内）
+   * - loose.md：根级散 .md（loadSkillsFromDir 收集，⑦登记清单内）
    * - ignored/：.gitignore 排除（①）
    * - node_modules 与 .hidden：loader 内建排除
    */
@@ -396,7 +396,7 @@ describe("pi 实装对拍（loadSkillsFromDir 语义锚）", () => {
     const { root, agentDir } = makeAnchorRoot();
     try {
       const piResult = loadSkillsFromDir({ dir: join(agentDir, "skills"), source: "anchor" });
-      // pi 实装语义快照——pi bump 改单根规则时此处红灯（守卫边界 = 单根规则漂移）
+      // pi 实装语义快照——pi bump 改单根规则时此处红灯（检查边界 = 单根规则漂移）
       expect(piResult.skills.map((s) => s.name).sort()).toEqual(["beta", "custom-alpha", "gamma", "loose"]);
       expect(piResult.skills.some((s) => s.name === "no-desc")).toBe(false); // ③ description 必填门
       expect(piResult.skills.some((s) => s.filePath.includes("ignored"))).toBe(false); // ① gitignore
@@ -430,7 +430,7 @@ describe("pi 实装对拍（loadSkillsFromDir 语义锚）", () => {
     }
   });
 
-  it("散 .md 形态：skillEntryPath = 文件路径本身（指引路径不悬空，⑦登记面内）", () => {
+  it("散 .md 形态：skillEntryPath = 文件路径本身（指引路径不悬空，⑦登记清单内）", () => {
     const { root, agentDir } = makeAnchorRoot();
     try {
       const detected = detectExecSkills({

package/src/__tests__/resolve-skills.test.ts

@@ -7,7 +7,7 @@ import { normalizeSkillName, resolveSkills } from "../resolve-skills.js";
 /**
  * fake skill 命令条目（SlashCommandInfo 形态：source === 'skill' + sourceInfo.path）。
  * name 带 pi 命名空间前缀（`skill:<name>`）——真实 pi.getCommands() 枚举 skill 类
- * 命令即此形态，归一化比对的靶子。
+ * 命令即此形态，归一化比对的检查目标。
  */
 const SKILL_COMMANDS = [
   { name: "skill:tech-design", source: "skill", sourceInfo: { path: "/skills/tech-design/SKILL.md" } },
@@ -36,7 +36,7 @@ describe("normalizeSkillName（skill: 命名空间前缀剥离）", () => {
 
 describe("resolveSkills（执行门禁：pi 注册表枚举比对，双向剥 skill: 前缀归一）", () => {
   it("resolves prefixed enum entries from bare-name input (short name in resolved)", () => {
-    // 无前缀输入命中带前缀枚举（输入面：用户用自然技能名）
+    // 无前缀输入命中带前缀枚举（输入范围：用户用自然技能名）
     const resolution = resolveSkills(makePi(), ["tech-design", "code review"]);
     expect(resolution.ok).toBe(true);
     if (resolution.ok) {

package/src/exec-skills.ts

@@ -14,11 +14,11 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 const logger = getLogger("pi-exec-skills");
 
 /**
- * 技能目录扫描共享能力（ADR-0074 落地包）：项目内一切「发现可执行 skill」的磁盘
+ * 技能目录扫描共享能力（ADR-0096 落地包）：项目内一切「发现可执行 skill」的磁盘
  * 扫描单源，禁止各扩展自扫目录或直用 pi 注册表快照形成第二实现（pi 的
  * getCommands 返回 resource loader 启动加载集——reload 才刷新的滞后快照）。
  *
- * 与 ./resolve-skills.js 的两段消费语义闭环（ADR-0074）：
+ * 与 ./resolve-skills.js 的两段消费语义闭环（ADR-0096）：
  * - 本模块 = 「发现」：自研扫描直读磁盘，技能安装即时可见；用于向用户提议
  *   （表单列出可用执行方式）。
  * - resolve-skills = 「执行门禁」：注入前经 pi 注册表确认 pi 实际认得该技能。
@@ -26,7 +26,7 @@ const logger = getLogger("pi-exec-skills");
  * 检测语义 = 「向用户提议的执行 skill」，以 pi 本体加载集为基线做意图/信任对齐：
  * - 单根枚举复用 pi 公开导出 loadSkillsFromDir——单根内横切规则（ignore / description
  *   必填门 / name 派生 / 递归遍历 / symlink / node_modules / 隐藏文件）随 pi 升级
- *   自动同步，零漂移面（对照表①③⑥⑦ 的 SKILL.md 目录形态侧）；
+ *   自动同步，零漂移风险（对照表①③⑥⑦ 的 SKILL.md 目录形态侧）；
  * - 跨根组装自实现（pi 的四根拼装逻辑未导出，对照表②④⑤）：根序四枚按 pi 本体
  *   `package-manager.js addAutoDiscoveredResources`——`.pi/skills` → 祖先链
  *   `.agents/skills`（近→远，git root 级含）→ `<agentDir>/skills` → `~/.agents/skills`
@@ -45,7 +45,7 @@ const logger = getLogger("pi-exec-skills");
  * plan-exec skill，出现时补第五根）。
  *
  * 降级规格（检测失败最坏后果 = skill 选项空集，绝不允许炸消费方的核心交互闭环；
- * pi 对坏 skill 也只产 diagnostics 不中断加载）：每根 existsSync 守卫 + 整根
+ * pi 对坏 skill 也只产 diagnostics 不中断加载）：每根 existsSync 检查 + 整根
  * try/catch（EACCES 等任何 fs 错 → 跳过该根 + warn）；单 skill frontmatter 读/解析
  * 失败 → 跳过该项 + warn；settings 读取/解析失败 → 视为无 overrides。
  */

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @zhushanwen/pi-exec-skills 公共出口（ADR-0074 落地包）。
+ * @zhushanwen/pi-exec-skills 公共出口（ADR-0096 落地包）。
  *
  * 两段消费语义闭环：exec-skills = 发现（目录扫描，技能热装即时可见）；
  * resolve-skills = 执行门禁（pi 注册表确认 pi 实际认得）。禁止各扩展自扫

package/src/resolve-skills.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 /**
- * 技能执行门禁共享能力（ADR-0074 落地包）：steer/注入前的「pi 实际认得」确认，
+ * 技能执行门禁共享能力（ADR-0096 落地包）：steer/注入前的「pi 实际认得」确认，
  * 走 pi 注册表（pi.getCommands）。与同包 exec-skills 模块构成两段消费语义闭环——
  * 扫描（发现，自研直读磁盘，技能热装即时可见）≠ 本模块（执行门禁，pi 注册表
  * 是执行权威）；pi 不认得的技能只提示不注入。
@@ -25,7 +25,7 @@ export interface SkillRef { // oe-exempt:20261001:framework:exec-skills 共享
 /**
  * 技能名归一：剥掉 pi 命令命名空间前导 `skill:` 前缀，得到自然技能名。
  * pi.getCommands() 枚举 skill 类命令时 name 带 `skill:` 前缀（如 `skill:tech-design`），
- * 这是 pi 的实现细节，不得泄漏到输入面——slash `--skills` 与消费方工具的 skills 参数
+ * 这是 pi 的实现细节，不得泄漏到输入范围——slash `--skills` 与消费方工具的 skills 参数
  * 都用自然技能名。枚举侧与输入侧双向剥前缀后比对，兼容两种形态。
  */
 export function normalizeSkillName(name: string): string {
@@ -41,7 +41,7 @@ export function normalizeSkillName(name: string): string {
  * available + 空 missing——available 正是调用方报错文案的恢复动作输入（错误 →
  * 可用清单 → 重试闭环），missing 空让报错器走「没有给技能名」分支。自 plan 包
  * enter.ts 迁入（plan-mode-audit-remediation 批次 4②b）：该分支是 slash 空
- * `--skills` 报错复用单源的活契约，非死防御；既有调用方先判非空才调的，行为不受影响。
+ * `--skills` 报错复用单源的活契约，非永不命中的防御机制；既有调用方先判非空才调的，行为不受影响。
  */
 export function resolveSkills(pi: ExtensionAPI, requested: string[]): SkillResolution {
   const skillCommands = pi.getCommands().filter((c) => c.source === "skill");