nx-kv 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.5.0] - 2026-10-08
+
+### Added
+
+- **skill 命令补齐为完整多 skill 形态（严格按脚手架 B04）**：
+  - `nx-kv skill list`：列出包内可装 skill（nx-kv / kv-sessiontask）、默认安装项与可装 group；
+  - `nx-kv skill groups`：列出 groups.json 的 group → 其包含的 skill；
+  - `nx-kv skill install [name] [--to <dir>] [--force]`：显式装某个 skill；
+  - `nx-kv skill install --group=<key> [--to <dir>] [--force]`：一键装整组（`<name>` 与
+    `--group` 互斥，同时给报 INVALID_INPUT）；
+  - `nx-kv skill get [name] [ref] [--to <dir>]` / `--group=<key>`：输出 skill 全文（prefix +
+    sentinel + 正文 + install 状态），供外部 agent 一键拿全上下文。
+  - 新增 `assets/groups.json`（默认 group key = nx-kv）；缺失/损坏时降级为目录扫描，
+    schema 错显式报错，不静默。
+  - HTTP 新增 `GET /api/bundled/groups`、`GET /api/bundled/content`。
+- 新增单测 `bundled-multiskill.test.mjs`（20 项断言：三种 install、默认标记、降级、
+  schema 错、幂等、部分冲突聚合、get 整组）；全套 50 项全绿。
+
 ## [0.4.1] - 2026-10-08
 
 ### Added

package/README.md

@@ -166,7 +166,10 @@ assets/kv-sessiontask/   内置 skill：对话内实时任务接力
 ```bash
 nx-kv skill install      # 装到 ~/.claude/skills/nx-kv（KV 清单操作手册）
 nx-kv skill install kv-sessiontask   # 实时任务接力：最后一步阻塞等用户喂任务
-nx-kv skill list         # 列出 nx-kv / kv-sessiontask
+nx-kv skill list         # 列出可装 skill、默认安装项与可装 group
+nx-kv skill groups       # 列出 group → 包含哪些 skill
+nx-kv skill install --group=<key>    # 一键装整组（与 <name> 二选一）
+nx-kv skill get [name] [ref]         # 输出 skill 全文，外部 agent 一键拿上下文
 ```
 
 装好后 agent 就能按 skill 里的 SOP 领任务、读主题上下文、完成后回填结果；

package/assets/groups.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "$comment": "group 名 → skill 名列表的别名表。当前 group 名 ≡ skill 名（一对一）；skills 是数组，为「一个 group 含多个 skill」预留。路径恒由 assets/<skills[i]>/ 推导——本文件只做聚合，不是第二条事实源。",
+  "groups": {
+    "nx-kv": {
+      "skills": ["nx-kv"],
+      "summary": "KV 清单管理中枢主 skill（默认 install 装的就是这个）：todo / group / 工作空间"
+    },
+    "kv-sessiontask": {
+      "skills": ["kv-sessiontask"],
+      "summary": "本机实时人机接力（sessiontask）——agent 阻塞 wait，用户在网页回填"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "nx-kv — KV 清单管理中枢 + 对话内实时任务接力：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 领取任务与阻塞接收用户输入",
   "type": "module",
   "bin": {

package/src/modules/bundled/index.js

@@ -1,6 +1,63 @@
-// 内置 skill 包模块：把随包发布的 nx-kv 说明装到用户的 skills 目录。
-// 没有面板视图——安装入口在 Skill 页，列出/安装都通过 action 暴露。
+// 内置 skill 包模块：把随包发布的 skill 说明装到用户的 skills 目录。
+// 没有面板视图——列出/安装/取全文都通过 action 暴露（CLI 与 HTTP 同源）。
+//
+// 多 skill（见脚手架 B04）：`assets/` 下可以有多个 skill，由 `assets/groups.json`
+// 归组；`skill install --group <key>` 一键装一组。groups.json 只是**便捷别名表**，
+// 缺失/损坏时降级为「每个 assets/<x> 各成一组」——事实源永远只有 `assets/<x>/SKILL.md`。
 import * as service from './service.js';
+import { badInput } from '../../core/errors.js';
+
+// <name> 与 --group 互斥：二者语义等价，报错比替用户猜意图友好（B04 §CLI 形状）
+function exclusive(ctx, cmd) {
+  if (ctx.group !== undefined && ctx.group !== null && ctx.group !== '' && ctx.name) {
+    throw badInput(`${cmd} 的 <name> 与 --group 只能给一个`);
+  }
+}
+
+const GROUP_FLAG = { type: 'string', hint: 'groups.json 里的组名（与 <name> 互斥）' };
+
+// `skill list` 的人读渲染（B04 §skill list 的输出）
+function renderList(d) {
+  const def = d.defaultGroup ? (d.groupSkills[d.defaultGroup] || []) : [];
+  const w = Math.max(0, ...d.skills.map((s) => s.length));
+  const lines = ['可装的 skill:'];
+  for (const s of d.skills) {
+    lines.push(def.includes(s) ? `  * ${s.padEnd(w)}  （默认 install）` : `  * ${s}`);
+  }
+  lines.push('可装的 group:');
+  for (const g of d.groups) {
+    lines.push(d.summaries[g] ? `  * ${g.padEnd(w)}  ${d.summaries[g]}` : `  * ${g}`);
+  }
+  if (d.source === 'assets-dirs') {
+    lines.push('', '（assets/groups.json 缺失或损坏，已降级为目录扫描：每个内置 skill 各成一组）');
+  }
+  return lines.join('\n');
+}
+
+// get 的三段拼接（顺序固定）：prefix 在最前告诉 agent 文件位置与「复制到自己可访问路径」；
+// sentinel 让 agent 知道正文从哪行开始，不把引导语一起带进下游上下文。
+// --json 不走这里（机器协议，不含 prefix）。
+function renderContent(d) {
+  const i = d.install;
+  const inst = i.status === 'conflict'
+    ? `冲突: ${i.path}（${i.count} 个文件不同）—— 需要覆盖时用 nx-kv skill install --force`
+    : i.skipped
+      ? `已是最新: ${i.path}（无差异）`
+      : i.replaced
+        ? `已替换: ${i.path}`
+        : `已安装: ${i.path}`;
+  return [
+    `# === ${d.skillName} skill context ===`,
+    `# 以下内容来自 nx-kv skill \`${d.skillName}\` 的 ${d.ref}。`,
+    '# 建议：把 sentinel 之后的正文完整复制到你自己可访问的路径，再按其内容操作。',
+    '# --- begin skill content (do not modify this line) ---',
+    '',
+    d.content.replace(/\s*$/, ''),
+    '',
+    '-- install 状态 --',
+    inst,
+  ].join('\n');
+}
 
 export default {
   id: 'bundled',
@@ -11,34 +68,78 @@ export default {
   actions: [
     {
       id: 'bundled.list',
-      // 第二条是历史别名：`skill install --list` 早于 `bundled list` 存在，
+      // `skill list` 是 B04 的强制命令面（列出**包内**可装的 skill）。
+      // 后两条是历史别名：`skill install --list` 早于 `bundled list` 存在，
       // 命令路径里带 flag，因此匹配是按 token 前缀而非「非 flag 前缀」。
-      cli: [['bundled', 'list'], ['skill', 'install', '--list']],
+      cli: [['skill', 'list'], ['skill', 'install', '--list'], ['bundled', 'list']],
       http: ['GET', '/api/bundled'],
-      summary: '列出包内自带 skill（含文件数与描述）',
-      // 两端返回结构刻意不同：HTTP 供面板顺带拿到默认安装目录；
-      // CLI 的 --json 保持纯数组的历史形状，不破坏已在消费它的 agent。
+      summary: '列出包内自带 skill（含文件数与描述）+ 默认装哪个 + 有哪些 group',
+      // 两端返回结构刻意不同：HTTP 供面板顺带拿到默认安装目录与每个 skill 的文件数；
+      // CLI 的 --json 走 B04 的形状（skills 是**名字数组** + defaultGroup/groups/source）。
       run: async (_ctx, meta) => {
-        const skills = await service.listBundledSkills();
-        return meta.transport === 'http'
-          ? { defaultDir: service.DEFAULT_SKILLS_DIR, skills }
-          : skills;
+        const info = await service.groupsInfo();
+        if (meta.transport !== 'http') return info;
+        const details = await service.listBundledSkills();
+        // 展开顺序要紧：info.skills 是**名字数组**，details 是**对象数组**
+        // （{name,dir,files,description}）。先铺 info、再压 details，否则
+        // skills 会被覆盖回字符串数组 —— 面板与 smoke 读 skills[].name 全变 undefined。
+        return {
+          ...info,
+          defaultDir: service.DEFAULT_SKILLS_DIR,
+          // smoke 与面板都在读 skills[].name —— HTTP 侧保持这个形状
+          skills: details,
+          details,
+        };
+      },
+      render: renderList,
+    },
+    {
+      id: 'bundled.groups',
+      cli: [['skill', 'groups'], ['bundled', 'groups']],
+      http: ['GET', '/api/bundled/groups'],
+      summary: '列出可装的 group（groups.json 的组名 → 它包含哪些 skill）',
+      run: () => service.groupsInfo(),
+      render: (d) => {
+        const head = `可装的 group（来源: ${d.source}${d.defaultGroup ? ` · 默认组: ${d.defaultGroup}` : ''}）:`;
+        const lines = [head];
+        for (const g of d.groups) {
+          lines.push(`  ${g}${d.summaries[g] ? '  —— ' + d.summaries[g] : ''}`);
+          lines.push(`      skills: ${(d.groupSkills[g] || []).join(', ')}`);
+        }
+        if (!d.groups.length) lines.push('  （无）');
+        return lines.join('\n');
       },
-      render: (l) =>
-        l.length
-          ? l.map((s) => `${s.name.padEnd(14)} ${s.files} 个文件  ${s.description.slice(0, 50)}`).join('\n')
-          : '（包内无内置 skill）',
     },
     {
       id: 'bundled.install',
       cli: ['skill', 'install'],
       http: ['POST', '/api/bundled/install'],
-      summary: '安装内置 skill 到 skills 目录（默认 nx-kv → ~/.claude/skills）',
+      summary: '安装内置 skill 到 skills 目录（默认 nx-kv → ~/.claude/skills；--group <key> 一键装一组）',
       args: [{ name: 'name', required: false }],
-      flags: { to: { type: 'string' }, force: { type: 'boolean' } },
-      run: (ctx) =>
-        service.installBundledSkill({ name: ctx.name || 'nx-kv', to: ctx.to, force: ctx.force }),
+      flags: { group: GROUP_FLAG, to: { type: 'string' }, force: { type: 'boolean' } },
+      run: (ctx) => {
+        exclusive(ctx, 'skill install');
+        return service.installBundledSkill({
+          name: ctx.name || service.DEFAULT_SKILL_NAME,
+          group: ctx.group,
+          to: ctx.to,
+          force: ctx.force,
+        });
+      },
       render: (d) => {
+        // 聚合形状用**显式 group 字段**判别，不做形状嗅探（B04 §实现要点）
+        if (d.group) {
+          const done = d.skills.filter((r) => r.status === 'ok').length;
+          const lines = [`group ${d.group}: ${done}/${d.skills.length} 已就绪`];
+          for (const r of d.skills) {
+            const what = r.status === 'conflict'
+              ? `冲突（${r.count} 个文件不同）→ 用 --force 覆盖`
+              : r.skipped ? '已是最新'
+                : `${r.replaced ? '已更新' : '已安装'}（${r.files} 个文件）-> ${r.path}`;
+            lines.push(`  ${r.name.padEnd(16)} ${what}`);
+          }
+          return lines.join('\n');
+        }
         if (d.status === 'conflict') {
           const files = d.files.map((f) => `  ${f.file}  ${f.side}`).join('\n');
           return `目标已存在且内容不同（${d.count} 个文件）: ${d.path}\n${files}\n用 --force 覆盖，或先删除目标目录`;
@@ -47,5 +148,22 @@ export default {
         return `${d.replaced ? '已更新' : '已安装'} ${d.name}（${d.files} 个文件）-> ${d.path}`;
       },
     },
+    {
+      // A03 §一/§三：get 与 install 是互补能力——install 让本机 agent 学得会用，
+      // get 让**不读 ~/.claude/skills 的外部 agent**一键拿全上下文。缺一即单边能力打折。
+      id: 'bundled.get',
+      cli: ['skill', 'get'],
+      http: ['GET', '/api/bundled/content'],
+      summary: '输出内置 skill 全文（prefix + sentinel + 正文 + install 状态），并顺手装到本机',
+      args: [{ name: 'name', required: false }, { name: 'ref', required: false }],
+      flags: { group: GROUP_FLAG, to: { type: 'string' } },
+      run: (ctx) => {
+        exclusive(ctx, 'skill get');
+        return service.bundledSkillContent({ name: ctx.name, group: ctx.group, ref: ctx.ref, to: ctx.to });
+      },
+      render: (d) => (d.group
+        ? d.skills.map(renderContent).join('\n\n' + '─'.repeat(60) + '\n\n')
+        : renderContent(d)),
+    },
   ],
 };

package/src/modules/bundled/service.js

@@ -1,5 +1,9 @@
 // 内置 skill 包：随 nx-kv 一起发布的 assets/<name>/（SKILL.md + references/…）
 // 负责列出与安装到用户/项目的 skills 目录，供 agent 一键获得 nx-kv 的使用说明。
+//
+// 多 skill（见脚手架 B04）：`assets/` 下可以有多个 skill，由 `assets/groups.json`
+// 归组；`skill install --group <key>` 一键装一组。groups.json 只是**便捷别名表**，
+// 缺失/损坏时降级为「每个 assets/<x> 各成一组」——事实源永远只有 `assets/<x>/SKILL.md`。
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -7,14 +11,23 @@ import fsp from 'node:fs/promises';
 import { diffTrees } from '../../core/fstree.js';
 import { parseFrontmatter } from '../../core/frontmatter.js';
 import { assertSafeName } from '../../core/paths.js';
-import { notFound } from '../../core/errors.js';
+import { notFound, badInput } from '../../core/errors.js';
 
 // assets/ 在包根，src/modules/bundled/ 的上三级
-const ASSETS_DIR = fileURLToPath(new URL('../../../assets/', import.meta.url));
+const DEFAULT_ASSETS_DIR = fileURLToPath(new URL('../../../assets/', import.meta.url));
+
+// assets 根。NX_KV_ASSETS 可覆盖，且**在调用时读、不在模块加载时快照**——
+// 测试要拿一棵伪资产树验 groups.json 的降级 / schema 错误，绝不能真去改仓库里的 assets/。
+function assetsRoot() {
+  return process.env.NX_KV_ASSETS ? resolve(process.env.NX_KV_ASSETS) : DEFAULT_ASSETS_DIR;
+}
 
 // 默认安装到 Claude Code 的用户级 skills 目录
 export const DEFAULT_SKILLS_DIR = join(homedir(), '.claude', 'skills');
 
+// 内置主 skill 的规范名 = 包名（A03 §二：用户不必记两个名字）。
+export const DEFAULT_SKILL_NAME = 'nx-kv';
+
 async function pathExists(p) {
   try {
     await fsp.access(p);
@@ -24,19 +37,121 @@ async function pathExists(p) {
   }
 }
 
+// ─── B04：多 skill 的分组（assets/groups.json） ──────────────────────
+//
+// 事实源只有一个：`assets/<name>/SKILL.md`。`groups.json` 只是「便捷别名表」——
+// 它缺失或损坏时降级成「每个 assets/<x> 各成一组」，用户照样能装，只是没了 --group。
+// 但 **schema 错**必须显式报错：那是作者/打包事故，静默吞掉只会让排查抓瞎。
+
+const GROUPS_REL = 'groups.json';
+
+// 包内实际存在的 skill：靠 assets/<x>/SKILL.md 判定
+async function assetSkillDirs() {
+  const entries = await fsp.readdir(assetsRoot(), { withFileTypes: true }).catch(() => []);
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (await pathExists(join(assetsRoot(), e.name, 'SKILL.md'))) out.push(e.name);
+  }
+  return out.sort();
+}
+
+function degradeGroups(names) {
+  const groups = {};
+  for (const n of names) {
+    groups[n] = { skills: [n], summary: '（groups.json 缺失或损坏，按目录扫描兜底）' };
+  }
+  return groups;
+}
+
+export async function loadGroups() {
+  const raw = await fsp.readFile(join(assetsRoot(), GROUPS_REL), 'utf8').catch(() => null);
+  if (raw === null) return { groups: degradeGroups(await assetSkillDirs()), source: 'assets-dirs' };
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    process.stderr.write('[nx-kv] assets/groups.json 不是合法 JSON，已降级为目录扫描\n');
+    return { groups: degradeGroups(await assetSkillDirs()), source: 'assets-dirs' };
+  }
+
+  const g = parsed && parsed.groups;
+  if (!g || typeof g !== 'object' || Array.isArray(g)) {
+    throw badInput('assets/groups.json 缺少 groups 对象（schema 错）');
+  }
+  const groups = {};
+  for (const [key, val] of Object.entries(g)) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(key)) throw badInput(`assets/groups.json 的 group 名非法: ${key}`);
+    if (!val || !Array.isArray(val.skills) || !val.skills.length) {
+      throw badInput(`assets/groups.json 的 group "${key}" 缺少非空 skills 数组（schema 错）`);
+    }
+    for (const s of val.skills) assertSafeName(s, 'group 里的 skill 名');
+    // 同一组里重复的 skill 名去重，避免重复三态与重复计数
+    groups[key] = { skills: [...new Set(val.skills)], summary: String(val.summary || '') };
+  }
+  if (!Object.keys(groups).length) throw badInput('assets/groups.json 里没有任何 group（schema 错）');
+  return { groups, source: 'manifest' };
+}
+
+// 默认 group 名 = 包名（B04「默认 install 的约定」）。
+// 全局安装时 cwd 是用户目录，读 cwd 永远匹配不上，故优先读**本包自己的** package.json；
+// 读不到就 null（不崩）。
+let pkgNameCache;
+async function packageName() {
+  if (pkgNameCache !== undefined) return pkgNameCache;
+  const own = fileURLToPath(new URL('../../../package.json', import.meta.url));
+  for (const p of [own, join(process.cwd(), 'package.json')]) {
+    try {
+      const name = JSON.parse(await fsp.readFile(p, 'utf8')).name;
+      if (name) { pkgNameCache = String(name); return pkgNameCache; }
+    } catch { /* 换下一个 */ }
+  }
+  pkgNameCache = null;
+  return pkgNameCache;
+}
+
+async function resolveGroup(key) {
+  const k = String(key ?? '').trim();
+  if (!k) {
+    throw badInput('--group 需要一个值（可用: ' + (Object.keys((await loadGroups()).groups).join(', ') || '(无)') + '）');
+  }
+  if (k.startsWith('-')) throw badInput(`--group 的值不能以 - 开头: ${k}`);
+  const { groups } = await loadGroups();
+  const g = groups[k];
+  if (!g) throw badInput(`未知 group: ${k}（可用: ${Object.keys(groups).join(', ') || '(无)'}）`);
+  return g;
+}
+
+// `skill list` 的数据：可装的 skill + 默认装哪个 + 有哪些 group + 数据来源
+export async function groupsInfo() {
+  const { groups, source } = await loadGroups();
+  const ids = Object.keys(groups);
+  const def = await packageName();
+  return {
+    skills: await assetSkillDirs(),
+    // 标记只认「与包名同名」的那一项；无匹配就不显示标记（不崩）
+    defaultGroup: def && groups[def] ? def : null,
+    groups: ids,
+    summaries: Object.fromEntries(ids.map((id) => [id, groups[id].summary])),
+    groupSkills: Object.fromEntries(ids.map((id) => [id, groups[id].skills])),
+    source,
+  };
+}
+
 export function assetsDir() {
-  return ASSETS_DIR;
+  return assetsRoot();
 }
 
 // 列出包内自带的所有 skill（含文件数与描述）
 export async function listBundledSkills() {
   const out = [];
-  const entries = await fsp.readdir(ASSETS_DIR, { withFileTypes: true }).catch(() => []);
+  const entries = await fsp.readdir(assetsRoot(), { withFileTypes: true }).catch(() => []);
   for (const e of entries) {
     if (!e.isDirectory()) continue;
-    const dir = join(ASSETS_DIR, e.name);
+    const dir = join(assetsRoot(), e.name);
     // 用不存在的路径当哨兵，diffTrees 会把包内文件全列为 only-central，等于列出文件清单
-    const files = await diffTrees(dir, join(dir, '__nx_rh_missing__'));
+    const files = await diffTrees(dir, join(dir, '__nx_kv_missing__'));
     if (!files.length) continue;
 
     // 描述解析复用 core/frontmatter.js —— 这里原本抄了一份简化正则，
@@ -48,14 +163,13 @@ export async function listBundledSkills() {
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-// 安装内置 skill 到目标 skills 目录（默认 ~/.claude/skills）
-// 返回 { status: 'ok' | 'conflict', ... }——已存在且内容不同是**业务结果**，
-// 需要用户决定是否覆盖，不是错误。
-export async function installBundledSkill({ name = 'nx-kv', to, force } = {}) {
-  name = assertSafeName(name);
-  const src = join(ASSETS_DIR, name);
+// 安装**一个**内置 skill。返回值形状与历史逐字节兼容，只多一个 `group` 字段
+// （B04 §实现要点：判别单/多 skill 必须用显式 `group` 字段，不做形状嗅探）。
+async function installOne(name, { to, force } = {}) {
+  name = assertSafeName(String(name || '').trim());
+  const src = join(assetsRoot(), name);
   if (!(await pathExists(join(src, 'SKILL.md')))) {
-    const available = (await listBundledSkills()).map((s) => s.name).join(', ') || '(无)';
+    const available = (await assetSkillDirs()).join(', ') || '(无)';
     throw notFound(`未找到内置 skill: ${name}（可用: ${available}）`);
   }
 
@@ -64,17 +178,105 @@ export async function installBundledSkill({ name = 'nx-kv', to, force } = {}) {
   const files = await diffTrees(src, dst); // side: only-central=新增, both-differ=不同, only-project=多余
 
   if (!files.length) {
-    return { status: 'ok', skipped: true, name, path: dst, files: 0 };
+    return { status: 'ok', skipped: true, name, path: dst, files: 0, group: null };
   }
 
   const exists = await pathExists(dst);
   if (exists && !force) {
-    return { status: 'conflict', name, path: dst, files, count: files.length };
+    return { status: 'conflict', name, path: dst, files, count: files.length, group: null };
   }
 
   if (exists) await fsp.rm(dst, { recursive: true, force: true });
   await fsp.mkdir(targetRoot, { recursive: true });
   await fsp.cp(src, dst, { recursive: true, dereference: true, force: true });
 
-  return { status: 'ok', installed: !exists, replaced: exists, name, path: dst, files: files.length };
+  return { status: 'ok', installed: !exists, replaced: exists, name, path: dst, files: files.length, group: null };
+}
+
+// 安装内置 skill 到目标 skills 目录（默认 nx-kv → ~/.claude/skills）。
+// 返回 { status: 'ok' | 'conflict', ... }——已存在且内容不同是**业务结果**，
+// 需要用户决定是否覆盖，不是错误。
+//
+// `group` 给定时装该组的**全部** skill，返回聚合形状 { status, group, skills:[…] }；
+// 不给则装单个，形状与历史一致。两者的判别靠显式 `group` 字段。
+export async function installBundledSkill({ name = DEFAULT_SKILL_NAME, group, to, force } = {}) {
+  if (group !== undefined && group !== null && group !== '') {
+    const g = await resolveGroup(group);
+    const skills = [];
+    for (const s of g.skills) skills.push(await installOne(s, { to, force }));
+    return {
+      // 有一个冲突就是 conflict：调用方要么加 --force 要么逐个处理
+      status: skills.every((r) => r.status === 'ok') ? 'ok' : 'conflict',
+      group: String(group).trim(),
+      skills,
+    };
+  }
+  return installOne(name, { to, force });
+}
+
+// ─── skill get：把内置 skill 全文交给外部 agent（A03 §三） ───────────
+// install 解决「本骨架的 agent 学得会用」，get 解决「外部 agent 一键拿全上下文」——
+// 两者互补，不是二选一。get 永远给文档：目标端 conflict 也照常输出，
+// 冲突信息放在 install 字段里让调用方自己决定要不要 --force。
+
+// ref 解析（A03 §三）：缺省 → SKILL.md；裸名 → references/<名>.md 再 <名>.md；
+// 带分隔符 → 相对 assets/<name>/；含 .. 或绝对路径一律拒绝。
+async function listRefs(dir) {
+  const out = [];
+  const entries = await fsp.readdir(join(dir, 'references'), { withFileTypes: true }).catch(() => []);
+  for (const e of entries) if (e.isFile() && e.name.endsWith('.md')) out.push(e.name.slice(0, -3));
+  return out.join(', ') || '(无)';
+}
+
+async function contentOne(name, { ref, to } = {}) {
+  name = assertSafeName(String(name || '').trim());
+  const dir = join(assetsRoot(), name);
+  if (!(await pathExists(join(dir, 'SKILL.md')))) {
+    const available = (await assetSkillDirs()).join(', ') || '(无)';
+    throw notFound(`未找到内置 skill: ${name}（可用: ${available}）`);
+  }
+
+  let rel;
+  const raw = String(ref || '').trim();
+  if (!raw) {
+    rel = 'SKILL.md';
+  } else {
+    if (raw.split(/[\\/]+/).includes('..')) throw badInput(`ref 路径不允许包含 '..': ${raw}`);
+    if (/^([a-zA-Z]:|[\\/])/.test(raw)) throw badInput('ref 越界（必须是相对路径）: ' + raw);
+    if (/[\\/]/.test(raw) || raw.startsWith('./')) {
+      rel = raw.replace(/^\.\//, '');
+    } else {
+      const bare = raw.endsWith('.md') ? raw : raw + '.md';
+      const inRefs = join('references', bare);
+      if (await pathExists(join(dir, inRefs))) rel = inRefs;
+      else if (await pathExists(join(dir, bare))) rel = bare;
+      else throw badInput(`未找到 ref: ${raw}（可用: ${await listRefs(dir)}）`);
+    }
+  }
+
+  const content = await fsp.readFile(join(dir, rel), 'utf8').catch(() => null);
+  if (content === null) throw notFound(`skill ${name} 里没有文件: ${rel}`);
+
+  // get 的语义是「读」不是「修」：conflict 照常返回文档，不提供 --force
+  const install = await installOne(name, { to });
+  return {
+    skillName: name,
+    // 机器契约字段统一正斜杠，Windows 上不出现反斜杠
+    ref: rel.split('\\').join('/'),
+    content,
+    contentBytes: Buffer.byteLength(content, 'utf8'),
+    install,
+  };
+}
+
+// `group` 给定时把该组**每个** skill 的全文都取回来，返回 { group, skills:[…] }；
+// 不给则单个。判别同样用显式 `group` 字段。
+export async function bundledSkillContent({ name = DEFAULT_SKILL_NAME, group, ref, to } = {}) {
+  if (group !== undefined && group !== null && group !== '') {
+    const g = await resolveGroup(group);
+    const skills = [];
+    for (const s of g.skills) skills.push(await contentOne(s, { ref, to }));
+    return { group: String(group).trim(), skills };
+  }
+  return contentOne(name, { ref, to });
 }