@ninkch/dsh-artcraft 0.2.10 → 0.3.1

package/index.js

@@ -8,12 +8,18 @@
  *
  * 两种形态：
  *   1) Agent Tools（对话内直接驱动）:
- *        artcraft_status  —— 检查 12 个家族 CLI 是否可用、配置目录、控制通道配置
- *        artcraft_cli     —— 运行 12 个家族 CLI 任意命令（cwd / 文件参数由调用方给绝对路径）
+ *        artcraft_status  —— 检查 13 个家族 CLI 是否可用、配置目录、控制通道配置
+ *        artcraft_cli     —— 运行 13 个家族 CLI 任意命令（cwd / 文件参数由调用方给绝对路径）
  *        artcraft_control —— 向运行中的 FilmCraft/EffectCraft/VectorCraft/LightCraft JSON 控制通道发一条命令
  *        artcraft_fs      —— 桥接文件操作（list/stat/readtext/write/mkdir，绝对路径）
  *        artcraft_update  —— 插件自身更新（检查/应用）
- *        artcraft_apps    —— 12 个家族应用的自动化能力目录（子命令/控制端口/MCP/仓库）
+ *        artcraft_apps    —— 13 个家族应用的自动化能力目录（子命令/控制端口/MCP/仓库）
+ *        artcraft_qc      —— 交付质检（家族探针 + 平台规格核对，返回 PASS/WARN/FAIL/MANUAL）
+ *        artcraft_live    —— 控制通道活性探测（哪些 App 正开着，可直接边看边调）
+ *
+ * 技能包（独立插件行 @ninkch/dsh-artcraft/skills，见 skills.js）：artcraft-ops / artcraft-shot-language /
+ * artcraft-edit-rhythm / artcraft-color-light / artcraft-sound-design / artcraft-motion-vfx /
+ * artcraft-delivery-qc —— 教 agent 怎么调得顺、何时用哪种效果、镜头语言怎么设计。
  *   2) HTTP API（同源 /artcraft/api/*，供无限画布等前端调用，无 CORS 问题）:
  *        GET  /artcraft/api/status     环境自检
  *        GET  /artcraft/api/fs         list / stat / readtext
@@ -23,10 +29,13 @@
  *        POST /artcraft/api/job        启动长任务（渲染/导出/批处理）
  *        POST /artcraft/api/job/cancel 取消任务
  *        POST /artcraft/api/control    控制通道同步调用（engine.execute / ui.*）
- *        GET  /artcraft/api/apps       家族能力目录（list / ?id= 单个）
+ *        GET  /artcraft/api/apps       家族能力目录（list / ?id= 单个，含命令族统计）
+ *        GET  /artcraft/api/qc         交付质检（?path= 产物[&platform=][&kind=]）
+ *        GET  /artcraft/api/skills     内置技能包清单
+ *        GET  /artcraft/api/live       控制通道活性（?ports=app:port,… 追加）
  *
  * 安全约定：
- *   - 子进程只允许 12 个白名单键（家族 CLI），具体可执行文件由 artcraft.config.json 指定；
+ *   - 子进程只允许 13 个白名单键（家族 CLI），具体可执行文件由 artcraft.config.json 指定；
  *   - 控制通道只连 127.0.0.1，与 ArtCraft 官方协议一致（App 需以 --control 启动；
  *     已知默认端口：filmcraft 9876 / effectcraft 9877 / vectorcraft 7979 / lightcraft 7980；
  *     PhotoCraft 控制通道为令牌鉴权模式、PdfCraft 为文件式（--control FILE），均不代理；
@@ -46,12 +55,12 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 const NAME = 'artcraft';
-const VERSION = '0.2.10';
+const VERSION = '0.3.1';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 const BINS = [
   'photocraft', 'vectorcraft', 'filmcraft', 'lightcraft', 'pdfcraft', 'effectcraft',
-  'designcraft', 'wordcraft', 'deckcraft', 'gridcraft', 'cadcraft', 'soundcraft',
+  'designcraft', 'wordcraft', 'deckcraft', 'gridcraft', 'cadcraft', 'soundcraft', 'figcraft',
 ];
 const PKG_NAME = '@ninkch/dsh-artcraft';
 const DEFAULT_PORTS = { filmcraft: 9876, effectcraft: 9877, vectorcraft: 7979, lightcraft: 7980 };
@@ -78,6 +87,7 @@ const DEFAULT_CONFIG = {
     gridcraft: 'gridcraft-cli',
     cadcraft: 'cadcraft-cli',
     soundcraft: 'soundcraft-cli',
+    figcraft: 'figcraft-cli',
   },
   control: { ...DEFAULT_PORTS },
 };
@@ -86,7 +96,7 @@ const APP_DISPLAY = {
   photocraft: 'PhotoCraft', vectorcraft: 'VectorCraft', filmcraft: 'FilmCraft',
   lightcraft: 'LightCraft', pdfcraft: 'PdfCraft', effectcraft: 'EffectCraft',
   designcraft: 'DesignCraft', wordcraft: 'WordCraft', deckcraft: 'DeckCraft',
-  gridcraft: 'GridCraft', cadcraft: 'CADCraft', soundcraft: 'SoundCraft',
+  gridcraft: 'GridCraft', cadcraft: 'CADCraft', soundcraft: 'SoundCraft', figcraft: 'FigCraft',
 };
 
 /* ============================ 配置 ============================ */
@@ -489,6 +499,306 @@ async function statusInfo(cfg, meta) {
   };
 }
 
+/* ============================ 交付质检（确定性规则） ============================ */
+
+/**
+ * 质检原则：只报事实，不下判断（判定交给调用方/agent）。
+ * 每条 check 给 level(ok|warn|fail|manual) + 实测值 + 建议命令。
+ */
+const QC_KINDS = [
+  { kind: 'video', bin: 'filmcraft', re: /\.(mp4|mov|mkv|webm|avi|m4v|mxf)$/i, args: (p) => ['probe', p] },
+  { kind: 'audio', bin: 'soundcraft', re: /\.(wav|aif|aiff|mp3|m4a|flac|aac|ogg)$/i, args: (p) => ['info', p] },
+  { kind: 'image', bin: 'photocraft', re: /\.(png|jpe?g|tiff?|webp|bmp|gif|pcraft|psd|exr)$/i, args: (p) => ['info', p, '--compact'] },
+  { kind: 'pdf', bin: 'pdfcraft', re: /\.pdf$/i, args: (p) => ['info', p] },
+  { kind: 'doc', bin: 'wordcraft', re: /\.(docx|doc|odt|rtf)$/i, args: (p) => ['info', p] },
+  { kind: 'sheet', bin: 'gridcraft', re: /\.(xlsx|xls|csv|tsv|ods)$/i, args: (p) => ['info', p, '--json'] },
+  { kind: 'deck', bin: 'deckcraft', re: /\.(pptx|ppt|odp|deckcraft)$/i, args: (p) => ['info', p] },
+  { kind: 'fig', bin: 'figcraft', re: /\.(figcraft|fig)$/i, args: (p) => ['info', p, '--json'] },
+  { kind: 'cad', bin: 'cadcraft', re: /\.(dxf|dwg)$/i, args: (p) => ['info', p] },
+  { kind: 'design', bin: 'designcraft', re: /\.(indd|idml|icml|designcraft)$/i, args: null },
+];
+
+const PLATFORM_SPECS = {
+  bilibili: { label: 'B 站/横屏', width: 1920, height: 1080, fps: [24, 25, 30, 50, 60], loudness: -14, tp: -1 },
+  youtube: { label: 'YouTube/横屏', width: 1920, height: 1080, fps: [24, 25, 30, 50, 60], loudness: -14, tp: -1 },
+  douyin: { label: '抖音/竖屏', width: 1080, height: 1920, fps: [30, 60], loudness: -14, tp: -1 },
+  reels: { label: 'Reels/竖屏', width: 1080, height: 1920, fps: [30, 60], loudness: -14, tp: -1 },
+  shorts: { label: 'Shorts/竖屏', width: 1080, height: 1920, fps: [30, 60], loudness: -14, tp: -1 },
+  wechat: { label: '视频号/竖屏', width: 1080, height: 1920, fps: [30], loudness: -14, tp: -1 },
+  broadcast: { label: '广播 EBU R128', width: 1920, height: 1080, fps: [25, 50, 29.97, 59.94], loudness: -23, tp: -2 },
+  podcast: { label: '播客（纯音频）', audioOnly: true, loudness: -16, tp: -1.5 },
+};
+
+/** 从 CLI 输出里尽力抽出 JSON（前面可能有日志行） */
+function extractJson(text) {
+  const t = String(text ?? '');
+  const start = t.search(/[[{]/);
+  if (start < 0) return null;
+  for (let end = t.length; end > start; end--) {
+    const slice = t.slice(start, end).trim();
+    if (!slice || (slice[0] === '{' && !slice.endsWith('}')) || (slice[0] === '[' && !slice.endsWith(']'))) continue;
+    try { return JSON.parse(slice); } catch { /* 继续缩短 */ }
+  }
+  return null;
+}
+
+function qcKindFor(file) {
+  for (const k of QC_KINDS) if (k.re.test(file)) return k;
+  return null;
+}
+
+function num(v) { const n = Number(v); return Number.isFinite(n) ? n : null; }
+
+/** 深挖对象树，找第一个匹配键（不同成员的字段命名不统一） */
+function dig(obj, keys, depth = 0) {
+  if (!obj || typeof obj !== 'object' || depth > 4) return null;
+  for (const k of keys) if (obj[k] !== undefined && obj[k] !== null) return obj[k];
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === 'object') { const r = dig(v, keys, depth + 1); if (r !== null) return r; }
+  }
+  return null;
+}
+
+async function runQc(cfg, { path: rawPath, platform, kind: wantKind, live: wantLive = true } = {}) {
+  const file = resolveCallerPath(rawPath);
+  const st = await fs.stat(file).catch(() => null);
+  if (!st || !st.isFile()) throw new Error('文件不存在或不是常规文件: ' + file);
+  const k = wantKind ? QC_KINDS.find((x) => x.kind === wantKind) : qcKindFor(file);
+  if (!k) throw new Error('无法识别文件类型（可用 kind 显式指定: ' + QC_KINDS.map((x) => x.kind).join('|') + '）');
+
+  const spec = platform ? PLATFORM_SPECS[String(platform).toLowerCase()] : null;
+  if (platform && !spec) throw new Error('未知 platform: ' + platform + '（可用: ' + Object.keys(PLATFORM_SPECS).join('|') + '）');
+
+  const checks = [];
+  const add = (id, level, detail, fix) => checks.push({ id, level, detail, ...(fix ? { fix } : {}) });
+
+  // 通用：文件体量
+  st.size > 0 ? add('file.size', 'ok', `${(st.size / 1048576).toFixed(2)} MB`) : add('file.size', 'fail', '文件为空');
+
+  // 成员探针
+  let probe = null; let raw = ''; let bin = null; let exe = null; let probeOk = false;
+  if (k.args) {
+    try {
+      exe = await resolveBin(cfg, k.bin);
+      bin = k.bin;
+      const r = await runProcess(exe, k.args(file), { timeoutMs: 120000 });
+      raw = (r.stdout || '') + (r.stderr ? '\n' + r.stderr : '');
+      probe = extractJson(r.stdout) ?? extractJson(raw);
+      probeOk = r.ok && !!probe;
+      probeOk ? add('probe', 'ok', `${k.bin} ${k.args(file)[0]} 成功`)
+        : add('probe', probe ? 'warn' : 'fail', probe ? '探针有输出但退出码非 0' : `探针失败：${(r.stderr || '').split('\n')[0] || '无输出'}`, `artcraft_cli { bin:"${k.bin}", args:${JSON.stringify(k.args(file))} }`);
+    } catch (e) {
+      add('probe', 'fail', `无法执行 ${k.bin}: ${String(e?.message ?? e)}`, `artcraft_status 检查 bins.${k.bin} 路径`);
+    }
+  } else {
+    add('probe', 'manual', `${k.bin} 无 info 子命令，需打开工程检查`, `artcraft_cli { bin:"${k.bin}", args:["commands","--json"] }`);
+  }
+
+  // 按类型核对
+  if (probe && k.kind === 'video') {
+    const w = num(dig(probe, ['width', 'videoWidth']));
+    const h = num(dig(probe, ['height', 'videoHeight']));
+    const fps = num(dig(probe, ['fps', 'frameRate', 'frame_rate']));
+    const dur = num(dig(probe, ['seconds', 'duration', 'durationSeconds']));
+    const audioStreams = dig(probe, ['audioStreams', 'audio_streams', 'audioTracks']);
+    if (w && h) add('video.resolution', 'ok', `${w}×${h}`); else add('video.resolution', 'manual', '未能从探针读到分辨率');
+    if (fps) add('video.fps', 'ok', `${fps} fps`);
+    if (dur) add('video.duration', 'ok', `${dur.toFixed(2)} s`);
+    const hasAudio = Array.isArray(audioStreams) ? audioStreams.length > 0 : audioStreams !== null ? true : null;
+    if (hasAudio === false) add('video.audio', 'warn', '未检测到音轨', '确认是否需要静音交付');
+    else if (hasAudio === true) add('video.audio', 'ok', '存在音轨');
+    if (spec) {
+      if (spec.audioOnly) add('platform.match', 'warn', `${spec.label} 需要纯音频交付，当前是视频`);
+      if (w && h && (spec.width !== w || spec.height !== h)) {
+        add('platform.resolution', 'warn', `${w}×${h} ≠ 目标 ${spec.width}×${spec.height}`, `按目标画幅重排或改用对应平台导出预设`);
+      } else if (w && h) add('platform.resolution', 'ok', `符合 ${spec.label}`);
+      if (fps && spec.fps && !spec.fps.includes(fps)) add('platform.fps', 'warn', `${fps} fps 不在推荐 ${spec.fps.join('/')}`);
+    }
+    add('loudness', 'manual', '文件响度需在应用内测量', `soundcraft bounce 返回 lufs/true_peak_db；或用 FilmCraft essentialSound.inspect + autoMatch { target: ${spec?.loudness ?? -14} }`);
+  }
+
+  if (probe && k.kind === 'audio') {
+    const sr = num(dig(probe, ['sample_rate', 'sampleRate']));
+    const ch = num(dig(probe, ['channels']));
+    const sec = num(dig(probe, ['seconds', 'duration']));
+    const fmt = dig(probe, ['sample_format', 'sampleFormat', 'format']);
+    if (sr) add('audio.sampleRate', sr >= 44100 ? 'ok' : (sr >= 32000 ? 'warn' : 'fail'), `${sr} Hz`, sr < 44100 ? '交付建议 ≥ 44.1 kHz' : undefined);
+    if (ch) add('audio.channels', 'ok', `${ch} ch`);
+    if (sec) add('audio.duration', 'ok', `${sec.toFixed(2)} s`);
+    if (fmt) add('audio.format', 'ok', String(fmt));
+    add('loudness', 'manual', '需在应用内测量或 bounce 时读取', `soundcraft run --in <session> --bounce <out> 的返回含 lufs/true_peak_db；目标 ${spec?.loudness ?? -14} LUFS`);
+  }
+
+  if (probe && k.kind === 'image') {
+    const w = num(dig(probe, ['width'])); const h = num(dig(probe, ['height'])); const depth = num(dig(probe, ['depth']));
+    if (w && h) add('image.size', 'ok', `${w}×${h}`);
+    if (depth) add('image.depth', 'ok', `${depth} bit/通道`);
+    if (spec && !spec.audioOnly && w && h && (spec.width !== w || spec.height !== h)) {
+      add('platform.resolution', 'warn', `${w}×${h} ≠ 目标 ${spec.width}×${spec.height}`, '按目标画幅导出');
+    }
+  }
+
+  if (probe && (k.kind === 'pdf' || k.kind === 'doc' || k.kind === 'deck' || k.kind === 'sheet')) {
+    const pages = num(dig(probe, ['pages', 'pageCount', 'page_count']));
+    const enc = dig(probe, ['encrypted']);
+    const sheets = dig(probe, ['sheets']);
+    if (pages) add('doc.pages', 'ok', `${pages} 页`);
+    if (enc === true) add('doc.encrypted', 'warn', '文档已加密', '确认交付对象可打开；必要时 pdfcraft protect.remove');
+    if (Array.isArray(sheets)) {
+      add('sheet.count', 'ok', `${sheets.length} 个工作表`);
+      const used = sheets.map((s) => s?.usedRange).filter(Boolean);
+      used.length ? add('sheet.usedRange', 'ok', used.slice(0, 3).join(' / ')) : add('sheet.usedRange', 'warn', '工作表未见已用区域', '确认数据是否已写入');
+      const charts = sheets.reduce((n, s) => n + (Array.isArray(s?.charts) ? s.charts.length : 0), 0);
+      add('sheet.charts', charts > 0 ? 'ok' : 'warn', `${charts} 个图表`);
+    }
+    if (k.kind === 'pdf') {
+      add('doc.a11y', 'manual', '无障碍需在 PdfCraft 内跑检查', `artcraft_cli { bin:"pdfcraft", args:["run","a11y.check","path=<file>"] }（或 a11y.report 出报告）`);
+      add('doc.print', 'manual', '印刷尺寸/出血需测量', `artcraft_cli { bin:"pdfcraft", args:["run","measure.info"] }`);
+    }
+    if (k.kind === 'doc') {
+      add('doc.a11y', 'manual', 'Word 侧无障碍需在应用内检查', 'artcraft_cli { bin:"wordcraft", args:["run","--cmd","file.accessibility"] }');
+      const comments = num(dig(probe, ['comments']));
+      if (comments !== null) add('doc.comments', comments === 0 ? 'ok' : 'warn', `${comments} 条批注`, comments ? '交付前清点批注（review.changes）' : undefined);
+    }
+    if (k.kind === 'deck') add('deck.review', 'manual', '动画/转场与备注需在应用内核对', 'artcraft_cli { bin:"deckcraft", args:["commands","animation"] }');
+  }
+
+  // 运行中 App 的实测信号（QC v2）：示波器 / 声音体检 / 字幕长度 / 合成能力
+  let liveInfo = null;
+  const appChecks = [];
+  if (wantLive) {
+    try {
+      liveInfo = await probeLiveApps(cfg);
+      const liveApps = new Set(liveInfo.apps.filter((a) => a.live).map((a) => a.app));
+      checks.push({
+        id: 'app.live',
+        level: liveInfo.live ? 'ok' : 'manual',
+        detail: liveInfo.live ? `控制通道可达：${[...liveApps].join(' / ')}` : '无运行中的控制通道（无头 CLI 已足够；需信号级实测时以 --control 启动 App）',
+      });
+      const brief = (v) => { const s = JSON.stringify(v ?? null); return s && s.length > 360 ? s.slice(0, 360) + '…' : s; };
+      if (liveApps.has('filmcraft')) {
+        const port = cfg.control.filmcraft;
+        try {
+          const sc = await controlCall(port, 'scopes.read', { scopes: ['waveform', 'vectorscopeYuv', 'histogram'] }, { timeoutMs: 4000 });
+          appChecks.push({ app: 'filmcraft', method: 'scopes.read', result: brief(sc) });
+          checks.push({ id: 'app.scopes', level: 'ok', detail: '已取 FilmCraft 示波器读数（详见 appChecks）' });
+        } catch (e) { checks.push({ id: 'app.scopes', level: 'manual', detail: '示波器读取失败：' + String(e?.message ?? e).slice(0, 120) }); }
+        try {
+          const es = await controlCall(port, 'essentialSound.inspect', {}, { timeoutMs: 4000 });
+          appChecks.push({ app: 'filmcraft', method: 'essentialSound.inspect', result: brief(es) });
+          checks.push({ id: 'app.audio', level: 'ok', detail: '已取 Essential Sound 体检（详见 appChecks）' });
+        } catch (e) { checks.push({ id: 'app.audio', level: 'manual', detail: '声音体检失败：' + String(e?.message ?? e).slice(0, 120) }); }
+        try {
+          const caps = await controlCall(port, 'captions.list', {}, { timeoutMs: 4000 });
+          const arr = Array.isArray(caps) ? caps : (caps?.captions ?? []);
+          const texts = arr.map((c) => String(c?.text ?? '')).filter(Boolean);
+          const tooLong = texts.filter((t) => t.length > 20);
+          checks.push({
+            id: 'app.captions',
+            level: texts.length === 0 ? 'manual' : (tooLong.length ? 'warn' : 'ok'),
+            detail: texts.length === 0 ? '当前序列未见字幕条目' : `${texts.length} 条字幕${tooLong.length ? `，其中 ${tooLong.length} 条超过 20 字（竖屏建议 ≤15 字，横屏 ≤20）` : '，长度合规'}`,
+            ...(tooLong.length ? { fix: 'captions.split / captions.setText 拆分或精简；并确认字幕在安全区内' } : {}),
+          });
+        } catch (e) { checks.push({ id: 'app.captions', level: 'manual', detail: '字幕清点失败：' + String(e?.message ?? e).slice(0, 120) }); }
+      }
+      if (liveApps.has('effectcraft')) {
+        try {
+          const caps = await controlCall(cfg.control.effectcraft, 'app.capabilities', {}, { timeoutMs: 4000 });
+          appChecks.push({ app: 'effectcraft', method: 'app.capabilities', result: brief(caps) });
+          checks.push({ id: 'app.effectcraft', level: 'ok', detail: '已取 EffectCraft 能力表（命令数/效果数，详见 appChecks）' });
+        } catch (e) { checks.push({ id: 'app.effectcraft', level: 'manual', detail: '能力表读取失败：' + String(e?.message ?? e).slice(0, 120) }); }
+      }
+    } catch (e) {
+      checks.push({ id: 'app.live', level: 'manual', detail: '活性探测失败：' + String(e?.message ?? e).slice(0, 120) });
+    }
+  }
+
+  const fails = checks.filter((c) => c.level === 'fail').length;
+  const warns = checks.filter((c) => c.level === 'warn').length;
+  const manuals = checks.filter((c) => c.level === 'manual').length;
+  return {
+    path: file,
+    kind: k.kind,
+    bin,
+    exe,
+    platform: spec ? { id: String(platform).toLowerCase(), ...spec } : null,
+    verdict: fails ? 'fail' : warns ? 'warn' : manuals ? 'pass-with-manual-checks' : 'pass',
+    counts: { fail: fails, warn: warns, manual: manuals, ok: checks.filter((c) => c.level === 'ok').length },
+    checks,
+    appChecks,
+    live: liveInfo ? { live: liveInfo.live, apps: liveInfo.apps.map((a) => ({ app: a.app, port: a.port, live: a.live })) } : null,
+    probe,
+    rawTail: raw ? raw.slice(-1200) : null,
+  };
+}
+
+/* ============================ 控制通道活性探测 ============================ */
+
+/**
+ * 探测哪些家族 App 正在运行（控制通道可达 = 该 App 以 --control 启动且工程已打开）。
+ * 活性证据用一次 engine.commands 调用，顺带拿到该应用当前可用命令数（parity 视角的"活着"）。
+ */
+async function probeLiveApps(cfg, extraPorts = []) {
+  const targets = [];
+  for (const [app, port] of Object.entries(cfg.control || {})) targets.push({ app, port: Number(port) });
+  for (const ap of extraPorts) {
+    const p = Number(ap?.port ?? ap);
+    if (Number.isInteger(p) && p > 0 && p < 65536) targets.push({ app: ap?.app ?? null, port: p });
+  }
+  const seen = new Set();
+  const apps = [];
+  for (const t of targets) {
+    if (seen.has(t.port)) continue;
+    seen.add(t.port);
+    const started = Date.now();
+    try {
+      const result = await controlCall(t.port, 'engine.commands', {}, { timeoutMs: 2500 });
+      const list = Array.isArray(result) ? result : (result?.commands ?? result?.result ?? null);
+      apps.push({
+        app: t.app,
+        port: t.port,
+        live: true,
+        ms: Date.now() - started,
+        commands: Array.isArray(list) ? list.length : null,
+      });
+    } catch (e) {
+      apps.push({ app: t.app, port: t.port, live: false, ms: Date.now() - started, error: String(e?.message ?? e).slice(0, 160) });
+    }
+  }
+  return { live: apps.filter((a) => a.live).length, total: apps.length, apps, note: apps.some((a) => a.live) ? '控制通道可达：可直接用 artcraft_control 边看边调' : '未发现运行中的控制通道（App 需以 --control 启动）' };
+}
+
+/* ============================ 技能包清单 ============================ */
+
+/** 扫描包内技能目录（供 /api/skills 与界面展示；技能实际加载由 skills.js 的提供者负责） */
+async function listBundledSkills() {
+  const dir = path.join(HERE, 'skills');
+  const out = [];
+  let entries = [];
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return { skills: [] }; }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const file = path.join(dir, ent.name, 'SKILL.md');
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+      const meta = {};
+      if (fm) for (const line of fm[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.+)$/.exec(line);
+        if (kv) meta[kv[1]] = kv[2].trim();
+      }
+      const refs = [];
+      try {
+        for (const r of await fs.readdir(path.join(dir, ent.name, 'references'), { withFileTypes: true })) {
+          if (r.isFile()) refs.push(r.name);
+        }
+      } catch { /* 无 references 目录 */ }
+      out.push({ dir: ent.name, name: meta.name ?? ent.name, description: meta.description ?? '', references: refs, bytes: raw.length });
+    } catch { /* 跳过不可读 */ }
+  }
+  return { count: out.length, skills: out.sort((a, b) => a.dir.localeCompare(b.dir)) };
+}
+
 /* ============================ HTTP 基础设施 ============================ */
 
 function sendJson(res, code, obj) {
@@ -735,13 +1045,15 @@ export function apply(ctx) {
   ctx.effect(() => {
     const disposers = [];
     const attempt = (def) => {
+      // 44.0.0 起注册器强制要求 output（缺了整工具拒注册，见 RELEASING.md 教训与 issue #1）：
+      // 兜底 output 必须随 shape 一起传入，两个命名约定都要带。
       const output = def.output ?? {
         schema: { type: 'object', additionalProperties: true },
         render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
       };
       for (const shape of [
-        { name: def.name, description: def.description, parameters: def.schema, execute: def.execute },
-        { name: def.name, description: def.description, inputSchema: def.schema, handler: def.execute },
+        { name: def.name, description: def.description, parameters: def.schema, execute: def.execute, output },
+        { name: def.name, description: def.description, inputSchema: def.schema, handler: def.execute, output },
       ]) {
         try {
           const d = ctx.tools.register(shape);
@@ -757,7 +1069,7 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_status',
-      description: '检查 ArtCraft 家族 12 个 CLI 是否可用，报告配置目录、控制通道端口与任务状态。本插件只是桥接，产物路径由调用方决定。',
+      description: '检查 ArtCraft 家族 13 个 CLI 是否可用，报告配置目录、控制通道端口与任务状态。本插件只是桥接，产物路径由调用方决定。',
       schema: { type: 'object', properties: {}, additionalProperties: false },
       async execute() {
         const cfg = await loadConfig();
@@ -767,7 +1079,7 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_cli',
-      description: '运行 ArtCraft 家族 CLI 的任意子命令（photocraft-cli / wordcraft-cli / soundcraft-cli 等 12 个，bin 参数的 enum 即完整清单）。长渲染请改用 HTTP POST /artcraft/api/job 后台执行。',
+      description: '运行 ArtCraft 家族 CLI 的任意子命令（photocraft-cli / wordcraft-cli / figcraft-cli 等 13 个，bin 参数的 enum 即完整清单）。长渲染请改用 HTTP POST /artcraft/api/job 后台执行。',
       schema: {
         type: 'object',
         properties: {
@@ -919,12 +1231,12 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_recipes',
-      description: '内置专家处理方案库：ArtCraft 家族的专业工作流配方（短剧海报、分镜批量调色、横转竖、响度标准化、SRT 字幕烧录、动态片头、多平台分发包、先探测后验证纪律）。action=list 列出全部；action=get + id 取单个配方的专业原则、执行步骤与验证清单。',
+      description: '内置专家处理方案库（v2）：8 套专业配方（短剧海报、分镜批量调色、横转竖、响度标准化、字幕生成与烧录、动态片头、多平台分发包、先探测后验证纪律）+ 14 条「任务 → 技能 → 命令链」编排模板（竖屏短剧成片、剧本到分镜、RAW 批量冲洗、拉片分析、音频后期、合成镜头、设计系统交付、文档交付、批量横转竖、封面缩略图、多语言字幕、素材清理修复、社交分发包、长素材切片）。action=list 列配方；action=get + id 取配方详情；action=chains 列编排链；action=chain + id 取完整命令链。配方中的 skills 字段指名应先读的技能包。',
       schema: {
         type: 'object',
         properties: {
-          action: { type: 'string', enum: ['list', 'get'] },
-          id: { type: 'string', description: 'action=get 时的配方 id' },
+          action: { type: 'string', enum: ['list', 'get', 'chains', 'chain'] },
+          id: { type: 'string', description: 'action=get / chain 时的 id' },
         },
         required: ['action'],
         additionalProperties: false,
@@ -932,22 +1244,37 @@ export function apply(ctx) {
       async execute(args) {
         const recipesPath = path.join(HERE, 'recipes', 'recipes.json');
         const catalog = JSON.parse(await fs.readFile(recipesPath, 'utf8'));
-        if (String(args.action) === 'get') {
+        const action = String(args.action);
+        const chains = Array.isArray(catalog.chains) ? catalog.chains : [];
+        if (action === 'get') {
           const r = catalog.recipes.find((x) => x.id === String(args.id ?? ''));
           if (!r) throw new Error('配方不存在: ' + args.id + '（可用: ' + catalog.recipes.map((x) => x.id).join(', ') + '）');
           return r;
         }
+        if (action === 'chain') {
+          const c = chains.find((x) => x.id === String(args.id ?? ''));
+          if (!c) throw new Error('编排链不存在: ' + args.id + '（可用: ' + chains.map((x) => x.id).join(', ') + '）');
+          return c;
+        }
+        if (action === 'chains') {
+          return {
+            version: catalog.version,
+            chains: chains.map((c) => ({ id: c.id, title: c.title, skills: c.skills, when: c.when, steps: c.steps?.length ?? 0 })),
+            hint: 'action=chain + id 取完整命令链（每步 app + cmd + 说明 + 验证项）',
+          };
+        }
         return {
           version: catalog.version,
-          recipes: catalog.recipes.map((r) => ({ id: r.id, title: r.title, apps: r.apps, goal: r.goal })),
-          hint: 'action=get + id 取完整配方（专业原则 + 执行步骤 + 验证清单）',
+          recipes: catalog.recipes.map((r) => ({ id: r.id, title: r.title, apps: r.apps, skills: r.skills, goal: r.goal })),
+          chains: chains.map((c) => ({ id: c.id, title: c.title, skills: c.skills })),
+          hint: 'action=get + id 取配方（原则 + 步骤 + 验证）；action=chain + id 取编排链；技能包见 artcraft-ops 等 7 个技能',
         };
       },
     });
 
     attempt({
       name: 'artcraft_apps',
-      description: 'ArtCraft 家族 12 应用的自动化能力目录：每个应用的定位、对标软件、CLI 子命令用法、控制通道端口、MCP 可用性与仓库/文档链接。action=list 列出全部；action=get + id 取单个应用的完整能力卡。要拿某应用的实时命令注册表，用 artcraft_cli 跑该应用的 commands 子命令。',
+      description: 'ArtCraft 家族 13 应用的自动化能力目录：每个应用的定位、对标软件、CLI 子命令用法、控制通道端口、MCP 可用性与仓库/文档链接，另含各成员实测命令族统计。action=list 列出全部；action=get + id 取单个应用的完整能力卡。要拿某应用的实时命令注册表，用 artcraft_cli 跑该应用的 commands 子命令。',
       schema: {
         type: 'object',
         properties: {
@@ -974,6 +1301,71 @@ export function apply(ctx) {
       },
     });
 
+    attempt({
+      name: 'artcraft_qc',
+      description: '交付质检（确定性规则）：对产物跑家族探针并按平台规格核对，返回 PASS/WARN/FAIL/MANUAL 清单与修复命令。支持 video/audio/image/pdf/doc/sheet/deck/fig/cad。用法：path=产物绝对路径；platform 可选（bilibili|youtube|douyin|reels|shorts|wechat|broadcast|podcast）核对画幅/帧率/响度目标；kind 可选，强制指定类型；live 默认 true——若检测到运行中的 App，会额外取示波器读数（filmcraft scopes.read）、Essential Sound 体检、字幕长度与 EffectCraft 能力表（结果在 appChecks）。只报事实与实测值，判定留给调用方。',
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, v) => {
+          if (!v || !Array.isArray(v.checks)) return [{ type: 'text', text: JSON.stringify(v, null, 2) }];
+          const lines = [`QC ${String(v.verdict || '').toUpperCase()}  ${v.path ?? ''}`,
+            `kind=${v.kind ?? '?'}  bin=${v.bin ?? '-'}  platform=${v.platform?.id ?? '-'}  计数=${JSON.stringify(v.counts ?? {})}`];
+          for (const c of v.checks) {
+            lines.push(`[${String(c.level).toUpperCase().padEnd(6)}] ${c.id}: ${c.detail}`);
+            if (c.fix) lines.push(`        fix: ${c.fix}`);
+          }
+          if (Array.isArray(v.appChecks) && v.appChecks.length) {
+            lines.push('appChecks: ' + JSON.stringify(v.appChecks));
+          }
+          return [{ type: 'text', text: lines.join('\n') }];
+        },
+      },
+      schema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '待检产物绝对路径（或 ~/ 展开）' },
+          platform: { type: 'string', enum: Object.keys(PLATFORM_SPECS), description: '可选：目标平台，用于规格核对' },
+          kind: { type: 'string', enum: QC_KINDS.map((k) => k.kind), description: '可选：强制指定文件类型' },
+          live: { type: 'boolean', description: '可选：是否探测运行中的 App 做信号级检查（默认 true）' },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      },
+      async execute(args) {
+        const cfg = await loadConfig();
+        return runQc(cfg, { path: args.path, platform: args.platform, kind: args.kind, live: args.live !== false });
+      },
+    });
+
+    attempt({
+      name: 'artcraft_live',
+      description: '探测哪些 ArtCraft App 正在运行（控制通道活性）：对已知端口逐个调用 engine.commands 作为活性证据，返回 live 列表、耗时与当前可用命令数。用于"边看边调"前的准备——确认目标 App 已以 --control 启动。可用 ports 追加自定义端口（如 [{app:"designcraft",port:8000}]）。',
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, v) => {
+          if (!v || !Array.isArray(v.apps)) return [{ type: 'text', text: JSON.stringify(v, null, 2) }];
+          const lines = [`LIVE ${v.live}/${v.total}  ${v.note ?? ''}`];
+          for (const a of v.apps) {
+            lines.push(a.live
+              ? `[LIVE ] ${String(a.app).padEnd(13)} :${a.port}  ${a.commands ?? '?'} cmds, ${a.ms}ms`
+              : `[—    ] ${String(a.app).padEnd(13)} :${a.port}  ${(a.error || '').slice(0, 90)}`);
+          }
+          return [{ type: 'text', text: lines.join('\n') }];
+        },
+      },
+      schema: {
+        type: 'object',
+        properties: {
+          ports: { type: 'array', items: { type: 'object' }, description: '可选：追加探测的端口，元素形如 {app:"x", port:8000} 或直接端口号' },
+        },
+        additionalProperties: false,
+      },
+      async execute(args) {
+        const cfg = await loadConfig();
+        return probeLiveApps(cfg, Array.isArray(args?.ports) ? args.ports : []);
+      },
+    });
+
     return () => {
       for (const d of disposers) { try { d(); } catch { /* ignore */ } }
     };
@@ -1165,9 +1557,49 @@ export function apply(ctx) {
           version: catalog.version,
           controlProtocol: catalog.controlProtocol,
           apps: catalog.apps.map((a) => ({ id: a.id, name: a.name, tagline: a.tagline, ref: a.ref, cli: a.cli, control: a.control, mcp: a.mcp, stage: a.stage })),
+          capabilityStats: catalog.capabilityStats ?? null,
         });
       }),
 
+      makeRoute(`/${NAME}/api/live`, async (req, res) => {
+        if (req.method !== 'GET') throw new Error('仅支持 GET');
+        const cfg = await loadConfig();
+        const url = new URL(req.url, 'http://x');
+        const extra = String(url.searchParams.get('ports') ?? '')
+          .split(',').map((s) => s.trim()).filter(Boolean)
+          .map((s) => { const [app, port] = s.split(':'); return port ? { app, port } : { port: app }; });
+        sendJson(res, 200, await probeLiveApps(cfg, extra));
+      }),
+
+      makeRoute(`/${NAME}/api/skills`, async (req, res) => {
+        if (req.method !== 'GET') throw new Error('仅支持 GET');
+        sendJson(res, 200, await listBundledSkills());
+      }),
+
+      makeRoute(`/${NAME}/api/qc`, async (req, res) => {
+        const cfg = await loadConfig();
+        const url = new URL(req.url, 'http://x');
+        if (req.method === 'GET') {
+          sendJson(res, 200, await runQc(cfg, {
+            path: url.searchParams.get('path') ?? url.searchParams.get('rel'),
+            platform: url.searchParams.get('platform') ?? undefined,
+            kind: url.searchParams.get('kind') ?? undefined,
+            live: url.searchParams.get('live') !== '0' && url.searchParams.get('live') !== 'false',
+          }));
+          return;
+        }
+        if (req.method === 'POST') {
+          const body = await readJson(req);
+          sendJson(res, 200, await runQc(cfg, {
+            path: body.path ?? body.rel ?? url.searchParams.get('path'),
+            platform: body.platform,
+            kind: body.kind,
+          }));
+          return;
+        }
+        throw new Error('仅支持 GET/POST');
+      }),
+
       makeRoute(`/${NAME}/api/control`, async (req, res) => {
         if (req.method !== 'POST') throw new Error('仅支持 POST');
         const cfg = await loadConfig();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ninkch/dsh-artcraft",
-  "version": "0.2.10",
+  "version": "0.3.1",
   "type": "module",
-  "description": "Drive the open-source ArtCraft studio suite (12 family apps: PhotoCraft, VectorCraft, FilmCraft, LightCraft, PdfCraft, EffectCraft, DesignCraft, WordCraft, DeckCraft, GridCraft, CADCraft, SoundCraft) from DeepSeek Harness: agent tools, a same-origin HTTP API, and plugins-page status with self-update.",
+  "description": "Drive the open-source ArtCraft studio suite (13 family apps: PhotoCraft, VectorCraft, FilmCraft, LightCraft, PdfCraft, EffectCraft, DesignCraft, WordCraft, DeckCraft, GridCraft, CADCraft, SoundCraft, FigCraft) from DeepSeek Harness: agent tools, a same-origin HTTP API, a bundled craft skill pack, and plugins-page status with self-update.",
   "keywords": [
     "deepseek-harness",
     "dsh-plugin",
@@ -10,6 +10,7 @@
     "photocraft",
     "filmcraft",
     "effectcraft",
+    "skills",
     "automation",
     "ai-agents"
   ],
@@ -28,11 +29,14 @@
   "exports": {
     ".": "./index.js",
     "./client": "./client.js",
+    "./skills": "./skills.js",
     "./package.json": "./package.json"
   },
   "files": [
     "index.js",
     "client.js",
+    "skills.js",
+    "skills",
     "cordis.patch.yml",
     "artcraft.config.json.example",
     "apps",