@ninkch/dsh-infinite-canvas 0.19.6 → 0.19.7

package/package.json

@@ -1,70 +1,82 @@
 {
-    "name": "@ninkch/dsh-infinite-canvas",
-    "version": "0.19.6",
-    "description": "Node-based short-drama studio for DeepSeek Harness: script → storyboard → assets → shots → voiced, subtitled final cut on an infinite canvas.",
-    "keywords": [
-        "dsh",
-        "deepseek-harness",
-        "plugin",
-        "infinite-canvas",
-        "storyboard",
-        "short-drama",
-        "ai-video",
-        "image-generation",
-        "video-generation",
-        "seedance",
-        "photocraft",
-        "filmcraft"
-    ],
-    "license": "Apache-2.0",
-    "author": "NINKCH",
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org/"
+  "name": "@ninkch/dsh-infinite-canvas",
+  "version": "0.19.7",
+  "description": "无限画布（Infinite Canvas）for DeepSeek Harness：节点式创作工作室（剧本/分镜/生成/成片），内置「媒体创作」预设模式（导演第一视角 + 引导工作坊）。Version-agnostic: reads the live catalog from the installed package at load time.",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "infinite-canvas",
+    "storyboard",
+    "short-drama",
+    "ai-video",
+    "image-generation",
+    "video-generation",
+    "seedance",
+    "photocraft",
+    "filmcraft"
+  ],
+  "license": "Apache-2.0",
+  "author": "NINKCH",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NINKCH/dsh-infinite_canvas.git"
+  },
+  "type": "module",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./assets/director/*.js": "./assets/director/*.js",
+    "./assets/canvas-director/*.js": "./assets/canvas-director/*.js",
+    "./skills": "./skills.js"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "icon.svg",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "assets/*/SKILL.md",
+    "assets/support/*",
+    "assets/director/*.js",
+    "assets/director/models/*.json",
+    "assets/director/clips/*.json",
+    "NOTICE",
+    "README.md",
+    "README.zh-CN.md",
+    "docs/*.md",
+    "docs/images/*",
+    "skill-pack.js",
+    "skill-pack-loader.js",
+    "index-core-skill-profile.js",
+    "assets/canvas-director/**",
+    "skills.js",
+    "skills/**"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
     },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/NINKCH/dsh-infinite_canvas.git"
-    },
-    "type": "module",
-    "icon": "./icon.svg",
-    "exports": {
-        ".": "./index.js",
-        "./client": "./client.js",
-        "./package.json": "./package.json",
-        "./locale/*.json": "./locale/*.json",
-        "./assets/director/*.js": "./assets/director/*.js",
-        "./assets/canvas-director/*.js": "./assets/canvas-director/*.js"
-    },
-    "files": [
-        "index.js",
-        "client.js",
-        "icon.svg",
-        "cordis.patch.yml",
-        "locale/*.json",
-        "assets/*/SKILL.md",
-        "assets/support/*",
-        "assets/director/*.js",
-        "assets/director/models/*.json",
-        "assets/director/clips/*.json",
-        "README.md",
-        "README.zh-CN.md",
-        "docs/*.md",
-        "docs/images/*",
-        "skill-pack.js",
-        "skill-pack-loader.js",
-        "index-core-skill-profile.js",
-        "assets/canvas-director/**"
-    ],
-    "dsh": {
-        "bundle": {
-            "patch": "./cordis.patch.yml"
-        },
-        "client": {
-            "platform": "web",
-            "immediately": true
-        }
-    },
-    "devDependencies": {
-        "fbx2gltf": "^0.9.7-p1"
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "devDependencies": {
+    "fbx2gltf": "^0.9.7-p1"
+  },
+  "peerDependencies": {
+    "@ninkch/dsh-artcraft": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@ninkch/dsh-artcraft": {
+      "optional": true
     }
+  }
 }

package/skill-pack-loader.js

@@ -113,6 +113,7 @@ export function packInventory(hereDir) {
       group: String(it.group || ''),
       oneliner: String(it.oneliner || ''),
       tier: String(it.tier || ''),
+      aliases: Array.isArray(it.aliases) ? it.aliases.map(String) : [],
       glyph: String(it.glyph || it.id || ''),
       file: String(it.file || ''),
       available: !!readCard(base, layer, it.file),

package/skill-pack.js

@@ -148,7 +148,7 @@ export function renderInventory(inv, profile, zh) {
       byGroup.get(g).push(it);
     }
     for (const [g, arr] of byGroup) {
-      lines.push((g ? g + '：' : '') + arr.map((x) => x.id + '=' + x.name + (x.available ? '' : '（缺文件）')).join('　'));
+      lines.push((g ? g + '：' : '') + arr.map((x) => x.id + '=' + x.name + ((x.aliases && x.aliases.length) ? '（' + x.aliases.join('/') + '）' : '') + (x.available ? '' : '（缺文件）')).join('　'));
     }
   }
   const mv = (inv && inv.moves) || [];

package/skills/director-workshop/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: director-workshop
+description: 导演工作坊——媒体创作模式的引导式创作流程。从"选导演"到"交付成片"，每一步给菜单、讲原理、一次只做一个决定。适用于：进入媒体创作模式、想拍短剧/视频但不知从哪下手、或说"带我做/引导我创作"时。
+whenToUse: 用户进入媒体创作模式、表达创作意图（拍片/短剧/视频/分镜）、或面对空白页不知如何开始时，先加载本技能再动手。
+---
+
+# 导演工作坊（Director Workshop）
+
+你现在是一位驻组导演，用户是你的监制兼学徒。你的职责不只是替他做，而是**带着他做**：每一步先给菜单、再讲一句"为什么"、让他做决定、你负责执行与专业兜底。
+
+> 本技能随「媒体创作」预设（@ninkch/dsh-infinite-canvas 内置）分发：装好包即自动注册，改本文件即改所有机器上的引导话术。
+>
+> **版本无关性**：本正文不写任何份数、名单或绝对路径——它们都会随上游插件版本或安装位置变化。菜单一律现场调 `canvas_list_skills` / `artcraft_recipes` 取。若本文件末尾附了《当期清单快照》，那是 skills.js 在你加载时实时读取上游清单生成的，以它为准；读不到时不附，忽略即可。
+
+## 铁律（全程有效）
+
+1. **一次只问一个问题**。用 ask_user_question 给 2–4 个选项，每个选项必须带一行说明（它意味着什么/适合什么）。永远允许用户自定义输入。
+2. **先菜单，后代劳**。只有用户说"你定/听你的"时才可以代选，且必须说明理由。**菜单必须是工具返回的当期清单**，不是记忆里的旧清单。
+3. **阶段小结**。每完成一个阶段，用 3–5 行汇报：✅ 已定（列决定）/ ⏭️ 下一步是什么，用户确认后才进下一阶段。
+4. **术语即教即用**。第一次出现专业词（ASL、景别、轴线、J-cut、LUFS…）时，用一句大白话解释。
+5. **决定即落盘**。每个创作决定立刻写进画布（canvas_update_bible 设定集 / canvas_skill_pack set:true 项目配置），不要只停留在对话里。
+6. **用户卡壳时降级**：给一个"最稳的默认组合"让他确认，而不是让他面对空白。
+7. **取到什么说什么（版本无关）**。本技能刻意不写死任何份数与名单——导演透镜、题材、规格、影调、编排链的集合都会随上游插件版本增长。凡是"现在有哪些 / 多少条 / 什么规格"的问题，一律现场调 `canvas_list_skills` / `artcraft_recipes` 取当期答案；工具没返回就说不确定并去调它，**绝不拿旧版本记忆充数**。本文件末尾可能附有一份由 skills.js 在加载时实时读取上游清单生成的《当期清单快照》，有就以它为准，没有忽略即可。
+
+## 阶段 0 · 启动仪式（每次新项目必做）
+
+**先自检，再问起点**（自检不通过就不要往下走）：
+
+1. 各调一次 `canvas_list_skills` 与 `artcraft_status`。
+2. 三档结论，如实说、不猜版本：
+   - 两者正常 → 继续启动仪式。
+   - `canvas_*` 缺失 → 告诉用户需要先安装 `@ninkch/dsh-infinite-canvas`（profile 级 bundle），然后停。**不要用文字假装建项目、不要用对话模拟分镜、不要凭空描述"已生成的画面"。**
+   - `artcraft_*` 缺失 → 剧本/分镜/生成照做，但走到阶段 7 必须停下来说明缺 `@ninkch/dsh-artcraft`，不得宣称已交付成片。
+
+然后问起点（三选一）：
+- **A 从零开始** —— 走完整流程（阶段 1 起）
+- **B 有个想法** —— 先听他用两三句话讲完，你复述成 logline 给他确认，跳到阶段 2
+- **C 已有剧本/画布项目** —— canvas_list_projects 查重后接管，从阶段 5 或 7 续做
+
+同时展示一张"全景地图"让他知道要经过哪几站：
+> 选导演 → 定题材规格影调 → 一句话故事 → 分场剧本 → 分镜 → 生成 → 后期成片 → 质检交付
+
+## 阶段 1 · 选导演（创作四件套第一件）
+
+1. **先取清单，不要凭记忆背名单**：调 `canvas_list_skills`（不传 projectId）。
+   画布插件的透镜集会随版本增长，本技能有意不在正文里写死份数与人名——你也不许替它记。
+2. **按返回值的 group 分组展示**：分组名（如华语 / 日韩 / 欧美）由插件给出，直接沿用，**不要自己重排或合并**。每人一行、用 `id=名字` 的形态，让用户可以直接报 id。
+3. **每人补一句风格签名 + 一句"适合拍什么"**：清单只有名字时，调 `canvas_skill_pack({ kind: 'prompt', lens: '<id>' })` 取该透镜切片开头再概括成人话。能一句话说清就别整份倒给用户；不要为了凑签名去编造参数。
+4. 用户选定后**立刻执行三件事**：
+   - `canvas_skill_pack(kind=script, lens=<id>, set:true)` 把透镜写进项目
+   - 加载 canvas-director 技能确认透镜完整参数
+   - 产出**《导演合作指南》**给用户（见下）
+
+### 《导演合作指南》模板（选完导演必给）
+
+> **和「<用户选定的导演>」合作拍戏，你会得到 / 他会要求：**
+> ① 他的眼睛 —— 构图与机位偏好（如：广角贴脸手持、前景遮挡、失焦呼吸）
+> ② 他的钟 —— 镜长与节奏（如：ASL 2–4 秒碎剪 + 突然 10 秒凝视；抽帧降格）
+> ③ 他的光与色 —— 色板、光比、质感（如：高饱和霓虹绿红、低调光、颗粒感）
+> ④ 他的声音 —— 对白/音乐/静默的使用（如：画外独白贯穿、音乐先于画面进）
+> ⑤ 五条拍摄军规 —— 翻译成可执行参数（分镜怎么写、FilmCraft Lumetri 怎么调、SoundCraft 怎么混）
+> ⑥ 禁区 —— 他绝不会做的事（如：不用大平光、不写解释性对白）
+>
+> 六节内容全部来自该透镜切片的实际内容（`canvas_skill_pack` 返回），不要套模板空话；切片里没写的节，就说"该透镜未给出这一项"，不补造。
+
+这份指南是后续每一阶段的"口味基准"：写剧本、拆分镜、调色、混音前都回看它。
+
+## 阶段 2 · 定题材 / 规格 / 影调（四件套其余三件）
+
+**清单同样现场取，不背**：`canvas_list_skills` 的返回里，题材（含叙事与行业两类）、规格、影调各有一节，每节带份数与 `id=名字`；按它给选项。
+
+每项先用一句话说清"它管什么"再给选项：
+- **题材**（管观众为什么上头）：叙事题材管压力机制与集尾钩子，行业题材管产品/服务类片子的证据与质感。份数以清单为准。
+- **类型规格**（管结构块与节奏）：决定结构块、ASL 下限与质量档；**画幅不归它管**（画幅在视频节点生成时选）。
+- **影调质感**（管画面成什么样）：决定成像底层与材质；默认跟随导演透镜。
+
+不要用记忆里的旧名单举例；清单里有哪些就给哪些，用户点名清单里没有的，去 `canvas_skill_pack` 确认后再答复。
+
+给一个"推荐组合"（导演×题材×规格×影调）并解释为什么搭，用户确认后 `canvas_skill_pack(..., set:true)` 一次写入。
+
+## 阶段 3 · 一句话故事（logline）
+
+用模板引导，缺哪项问哪项：
+> **【主角】**为了**【欲望】**，必须**【行动】**，但**【障碍】**，若失败则**【赌注】**；转折在于**【反转】**。
+
+确认后写入剧本节点的创作意图（idea），并给出分集/分段结构提案（短剧默认：前 3 秒钩子 → 每 30 秒一个反转 → 卡点结尾）。
+
+## 阶段 4 · 分场剧本（逐场引导）
+
+每场只问四件事，别贪多：
+1. 这场戏的**情绪目标**是什么？（让观众感到什么）
+2. **谁想要什么**，**谁在阻止**？
+3. 结尾的**钩子/转折**是什么？
+4. 这场多少秒？（用导演的钟算）
+
+用户答完 → 你按 canvas-craft 的四要素成稿 → `canvas_write_node` 写入 → 给他看，确认后下一场。每写完 3 场提醒一次："要不要先回头通读一遍再继续？"
+
+## 阶段 5 · 分镜（把文字翻译成镜头）
+
+先教"三连问"再拆镜：
+1. 这场让观众**感觉**什么？（决定景别：贴脸=近景/特写，命运感=大远景）
+2. 观众的**眼睛该看哪**？（决定机位角度与构图）
+3. 镜头**跟着谁动/为什么动**？（决定运动：跟拍/推拉/固定）
+
+每场给 2–3 个镜头方案让用户挑（如"方案A 手持贴脸 3 秒×6 切 / 方案B 一镜到底 18 秒缓推"），讲清各自的代价。拆镜用 type=storyboard 节点、connectFrom 连上游剧本；六要素（景别/机位/运动/画面/台词/时长）齐了才算过。加载 artcraft-shot-language 技能兜底专业判断。
+
+## 阶段 6 · 生成与验收
+
+- 触发生成（canvas_generate_node / canvas_run_node），后台跑，不忙轮询。
+- 出图/出片后**先自查再给用户**：一致性 warnings 逐条补设定集；抽帧看角色脸、场景、道具是否跑偏。
+- 给用户看时附"验收要点"：让他按 3 条具体的点看（如"看女主发色是否一致/看第 4 镜有没有穿帮"），而不是问"你觉得怎么样"。
+
+## 阶段 7 · 后期成片与交付
+
+1. `artcraft_status` / `artcraft_live` 探活 → 先 `artcraft_recipes(action=chains)` 看当期链清单，再取竖屏短剧成片链（当前 id 为 short-drama-episode；**以当期清单为准**，id 不在就用名称最接近的成片链）。
+2. **按返回的 steps 逐步执行**：每步的 `app` / `cmd` / `params` 以返回值为准，本技能不写死步骤数与顺序（链 id 与步骤都会随 ArtCraft 版本变化）。返回里带 `verify` 的，按它逐条验收。
+3. `artcraft_qc` 质检，PASS 前不宣称完成；只报事实与实测值，判定留给用户。
+4. 交付时给"三件套"：成片路径 + 质检报告摘要 + 下一集/多平台分发包（social-pack）提议。
+
+## 出口检查表（全部完成后自查）
+
+- [ ] 开工自检已做，缺失依赖已如实告知（未假装成功）
+- [ ] 四件套已 set 进项目配置，且四项都是从当期清单选的
+- [ ] 设定集含世界观/风格/全部出场角色场景道具
+- [ ] 每场剧本有钩子，分镜六要素齐全
+- [ ] 视频全部生成且一致性告警清零
+- [ ] 成片 QC PASS，响度/画幅/字幕安全区达标（以 artcraft_qc 实测为准）
+- [ ] 用户拿到了成片 + 报告 + 下一步建议

package/skills.js

@@ -0,0 +1,342 @@
+/**
+ * @ninkch/dsh-infinite-canvas — 技能提供者（媒体创作预设随本包分发）
+ *
+ * 模式沿用 @ninkch/dsh-artcraft/skills：`inject: ['skills']` 是硬依赖，
+ * 单独成行，即使某环境没有 skills 服务也只影响本行，不拖垮预设其余部分。
+ *
+ * 技能来源：包内 skills/<name>/SKILL.md（YAML frontmatter: name + description）。
+ * rank 600 与内置技能同级 —— 项目级（100/200）与用户级（400/500）技能可覆盖同名技能。
+ * 随包分发：装好本包 = 导演工作坊引导技能自动就位，无需手工拷贝到 ~/.dsh/skills。
+ *
+ * ── 版本无关性（v1.2.0 起）───────────────────────────────────────────────
+ * 预设正文不写透镜/题材/规格/影调/编排链的份数与名单：它们会随
+ * @ninkch/dsh-infinite-canvas 与 @ninkch/dsh-artcraft 的版本增长。
+ * 本文件在**加载技能时**用 require.resolve 定位这两个已安装的包，实时读取
+ *
+ *   <canvas>/assets/canvas-director/manifest.json   → lenses/genres/industries/forms/looks/moves
+ *   <artcraft>/recipes/recipes.json                 → chains/recipes
+ *
+ * 并把当期清单作为附录拼在技能正文末尾。读不到（包未装、版本过旧、路径异常）时
+ * **静默省略，绝不抛错**——技能本体永远可用。
+ */
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = path.join(HERE, 'skills');
+const PROVIDER = 'media-studio';
+const RANK = 600;
+
+const CANVAS_PKG = '@ninkch/dsh-infinite-canvas';
+const ARTCRAFT_PKG = '@ninkch/dsh-artcraft';
+
+/** 附录默认上限（字符）。技能正文约 2.6k，DSH 工具结果修剪阈值 8192，
+ * 故附录留到 5000 以内，保证"正文+附录"整体不被修剪截断。 */
+const DEFAULT_SNAPSHOT_MAX = 5000;
+
+const CANVAS_LAYERS = [
+  ['lenses', '导演透镜'],
+  ['genres', '叙事题材'],
+  ['industries', '行业题材'],
+  ['forms', '规格'],
+  ['looks', '影调质感'],
+];
+
+/** Cordis 插件名 */
+export const name = 'media-studio-skills';
+/** 需要技能服务 */
+export const inject = ['skills'];
+
+/** 解析 SKILL.md 的 YAML frontmatter（只取扁平的 name/description 标量，够用且不引入依赖） */
+function parseSkill(raw) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw);
+  if (!m) return null;
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.+)$/.exec(line);
+    if (!kv) continue;
+    let v = kv[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    meta[kv[1]] = v;
+  }
+  if (!meta.name || !meta.description) return null;
+  return { name: meta.name, description: meta.description, content: raw.slice(m[0].length).trim() };
+}
+
+/** 扫描包内技能目录，产出候选清单 */
+async function loadCatalog() {
+  const out = [];
+  let entries = [];
+  try {
+    entries = await fs.readdir(SKILLS_DIR, { withFileTypes: true });
+  } catch {
+    return out; // 无 skills/ 目录 → 空目录（不报错）
+  }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const file = path.join(SKILLS_DIR, ent.name, 'SKILL.md');
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      const parsed = parseSkill(raw);
+      if (!parsed) continue;
+      out.push({
+        name: parsed.name,
+        description: parsed.description,
+        invocation: { modelInvocable: true, userInvocable: true },
+        provider: PROVIDER,
+        source: 'bundled',
+        rank: RANK,
+        resourceBase: { kind: 'directory', path: path.dirname(file) },
+        locator: file,
+      });
+    } catch { /* 单个技能读取失败不影响其余 */ }
+  }
+  return out;
+}
+
+// ── 上游清单快照 ────────────────────────────────────────────────────────────
+
+/** require.resolve 的解析锚点：包自身 → 往上逐级找 node_modules（覆盖 profile/开发目录两种安装形态）。 */
+function resolveAnchors() {
+  const anchors = [path.join(HERE, 'package.json')];
+  let dir = HERE;
+  for (let i = 0; i < 6; i += 1) {
+    dir = path.dirname(dir);
+    if (!dir || dir === path.dirname(dir)) break;
+    anchors.push(path.join(dir, 'package.json'));
+  }
+  return anchors;
+}
+
+/**
+ * 定位已安装的上游包目录；失败返回 null（不抛错）。
+ *
+ * 覆盖三种安装形态：
+ *   A. 预设与上游同在 profile 的 node_modules（npm 安装）—— 锚点向上 6 级必命中；
+ *   B. 预设为 link:（本地开发）、上游也在同一工作区 —— 向上查找同样覆盖；
+ *   C. 预设 npm 安装、上游为 link: 指到别处 —— 上面的锚点走不出去，
+ *      再从 DSH 标准目录（环境变量 DSH_HOME 或主目录下的 .dsh，及其每个
+ *      profile 的 node_modules）兜底。
+ * 目录一律来自运行时环境，不写死任何机器路径。
+ */
+function resolvePkgDir(pkgName) {
+  const spec = `${pkgName}/package.json`;
+  for (const anchor of resolveAnchors()) {
+    try {
+      return path.dirname(createRequire(anchor).resolve(spec));
+    } catch { /* 换下一个锚点 */ }
+  }
+  // C 形态兜底：扫描 DSH 标准目录下的 profile node_modules（同步、一次性、量级为个位数）
+  try {
+    const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+    const profiles = path.join(home, 'profiles');
+    for (const name of fsSync.readdirSync(profiles)) {
+      const nm = path.join(profiles, name, 'node_modules');
+      const direct = path.join(nm, ...pkgName.split('/'));
+      try {
+        if (fsSync.statSync(path.join(direct, 'package.json')).isFile()) return direct;
+      } catch { /* 该 profile 没有此包 */ }
+    }
+  } catch { /* 无 DSH 目录或不可读 */ }
+  return null;
+}
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function readVersion(pkgDir) {
+  const pkg = pkgDir ? await readJson(path.join(pkgDir, 'package.json')) : null;
+  return (pkg && typeof pkg.version === 'string') ? pkg.version : '';
+}
+
+function toList(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+/** `id=名字`，或仅 `id`。 */
+function renderItems(list, withName) {
+  return list
+    .map((x) => {
+      const id = x && x.id != null ? String(x.id) : '';
+      if (!id) return '';
+      if (!withName) return id;
+      const nm = x && x.name != null ? String(x.name) : '';
+      return nm ? `${id}=${nm}` : id;
+    })
+    .filter(Boolean)
+    .join('　');
+}
+
+function groupBy(list) {
+  const by = new Map();
+  for (const it of list) {
+    const g = (it && it.group != null) ? String(it.group) : '';
+    if (!by.has(g)) by.set(g, []);
+    by.get(g).push(it);
+  }
+  return by;
+}
+
+/**
+ * 画布清单块。
+ * level 0 = 分组 + id=名字；1 = 每层 id 列表；2 = 只报份数。
+ */
+function renderCanvas(manifest, level) {
+  const out = [];
+  for (const [key, label] of CANVAS_LAYERS) {
+    const list = toList(manifest[key]);
+    if (!list.length) continue;
+    if (level === 0) {
+      out.push(`- ${label}（${list.length}）`);
+      for (const [g, arr] of groupBy(list)) {
+        out.push(`  · ${g ? `${g}：` : ''}${renderItems(arr, true)}`);
+      }
+    } else if (level === 1) {
+      out.push(`- ${label}（${list.length}）：${renderItems(list, false)}`);
+    } else {
+      out.push(`- ${label}（${list.length}）`);
+    }
+  }
+  const moves = toList(manifest.moves);
+  if (moves.length) {
+    out.push(level === 2
+      ? `- 运镜与节奏（${moves.length}）`
+      : `- 运镜与节奏（${moves.length}）：${renderItems(moves, level === 0)}`);
+  }
+  return out.join('\n');
+}
+
+/** ArtCraft 编排链块。level 0 = id=标题；1 = 仅 id；2 = 只报份数。 */
+function renderArtcraft(recipes, level) {
+  const chains = toList(recipes.chains);
+  const formula = toList(recipes.recipes);
+  const out = [];
+  if (chains.length) {
+    out.push(`- 编排链（${chains.length}）`);
+    if (level === 2) {
+      /* 只报份数 */
+    } else {
+      out.push(`  · ${renderItems(chains, level === 0)}`);
+    }
+  }
+  if (formula.length) {
+    out.push(level === 2
+      ? `- 配方（${formula.length}）`
+      : `- 配方（${formula.length}）：${renderItems(formula, false)}`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * 组装快照附录。分级降级：画布给全量中文名（选导演必需）→ 画布仅 id →
+ * 全层只报份数；仍超限则截断。ArtCraft 链始终只给 id（标题可由
+ * artcraft_recipes 现场取，不值得占快照预算）。任何一步失败都返回 ''。
+ */
+async function buildSnapshot(maxChars) {
+  // 画布 manifest 与本文件同包（assets/canvas-director/manifest.json），优先自定位；
+  // resolvePkgDir 仅作为异常兜底（例如安装形态导致的路径重排）。
+  const canvasDir = fsSync.existsSync(path.join(HERE, 'assets', 'canvas-director', 'manifest.json'))
+    ? HERE
+    : resolvePkgDir(CANVAS_PKG);
+  const artDir = resolvePkgDir(ARTCRAFT_PKG);
+  if (!canvasDir && !artDir) return '';
+
+  const [canvasVersion, artVersion] = await Promise.all([
+    readVersion(canvasDir),
+    readVersion(artDir),
+  ]);
+
+  const manifest = canvasDir
+    ? await readJson(path.join(canvasDir, 'assets', 'canvas-director', 'manifest.json'))
+    : null;
+  const recipes = artDir
+    ? await readJson(path.join(artDir, 'recipes', 'recipes.json'))
+    : null;
+
+  if (!manifest && !recipes) return '';
+
+  const head = [
+    '',
+    '',
+    '---',
+    '',
+    '## 当期清单快照（加载时自动生成，勿手改）',
+    '',
+    '> 本段由 `@ninkch/dsh-infinite-canvas/skills` 在本技能加载时，实时读取**这台机器上已安装**的包生成。',
+    '> 它只代表当前机器与当前版本；与你的工具返回值冲突时，**一律以工具返回值（`canvas_list_skills` / `artcraft_recipes`）为准**。',
+    '',
+  ].join('\n');
+
+  const build = (canvasLevel, artLevel) => {
+    const parts = [head];
+    if (manifest) {
+      const block = renderCanvas(manifest, canvasLevel);
+      if (block) {
+        parts.push(`### ${CANVAS_PKG}${canvasVersion ? ` v${canvasVersion}` : ''}`);
+        parts.push(block);
+      }
+    }
+    if (recipes) {
+      const block = renderArtcraft(recipes, artLevel);
+      if (block) {
+        parts.push('');
+        parts.push(`### ${ARTCRAFT_PKG}${artVersion ? ` v${artVersion}` : ''}`);
+        parts.push(block);
+      }
+    }
+    // 两段都没渲染出内容 → 无意义附录，返回空串让调用方跳过
+    return parts.length > 1 ? parts.join('\n').replace(/\n{3,}/g, '\n\n') : '';
+  };
+
+  // 画布中文名优先；画布降级到 1/2 时，ArtCraft 也跟着降。
+  for (const [cl, al] of [[0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]) {
+    const text = build(cl, al);
+    if (text.length <= maxChars) {
+      return cl === 2
+        ? `${text}\n\n（篇幅所限，仅报份数；具体名单请调 canvas_list_skills / artcraft_recipes。）`
+        : text;
+    }
+  }
+
+  return '';
+}
+
+export function apply(ctx, config = {}) {
+  const cfg = (config && typeof config === 'object') ? config : {};
+  const includeSnapshot = cfg.includeLiveSnapshot !== false;
+  const maxChars = Number.isFinite(cfg.snapshotMaxChars) && cfg.snapshotMaxChars > 0
+    ? Math.floor(cfg.snapshotMaxChars)
+    : DEFAULT_SNAPSHOT_MAX;
+
+  const provider = {
+    name: PROVIDER,
+    list: () => loadCatalog(),
+    async get(candidate, options) {
+      const { rank: _rank, locator, ...summary } = candidate;
+      const raw = await fs.readFile(locator, { encoding: 'utf8', signal: options?.signal });
+      const parsed = parseSkill(raw);
+      let content = parsed ? parsed.content : raw;
+
+      // 附加当期上游清单（失败静默降级，绝不影响技能本体）
+      if (includeSnapshot && !options?.signal?.aborted) {
+        try {
+          const snapshot = await buildSnapshot(maxChars);
+          if (snapshot) content = `${content}${snapshot}`;
+        } catch { /* 快照是增强，不是必需 */ }
+      }
+
+      // 每次加载都重读文件：改技能正文无需版本号或缓存失效
+      return { summary, content };
+    },
+  };
+  ctx.skills.registerProvider(() => provider);
+}