@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/engine/agent/skill.js

@@ -1,204 +1,204 @@
-/**
- * skill.js — Skill 加载器（YAML frontmatter + Markdown body）
- *
- * 目录结构（2026-05-18 起，对齐 Claude Code plugin convention）：
- *   server/engine/plugins/nodesign/
- *     .claude-plugin/plugin.json       — plugin 元数据
- *     skills/<skill-id>/SKILL.md       — 各 skill
- *     skills/<skill-id>/<其他起手文件>
- *
- * SKILL.md 格式（YAML frontmatter + body）：
- *   ---
- *   name: deskskill-engine-mini
- *   version: 0.0.1
- *   description: 给 LLM 看的"什么时候用我"的描述
- *   ---
- *
- *   # System Prompt
- *
- *   你是一个 deck 设计 agent...（任意 markdown）
- *
- * 本模块职责：
- *   - 解析 SKILL.md 的 YAML frontmatter + body（loadSkill）
- *   - 把 skill 起手文件（canvas.template.html 等）拷进 session cwd（ensureSkillStarterFiles）
- *
- * 注：批量扫 plugin 下所有 skill 走 plugin-loader.js `listInstalledPluginsDetailed`，
- * 不在本模块（API 层 server/api/skills.js 用那个）。
- *
- * SDK 集成（在 session-loop.js）：
- *   - plugins: [{ type: 'local', path: PLUGIN_ROOT }]  → 让 SDK 识别本 plugin
- *   - skills: [<skill-id>]                              → 让 SDK 把 description 注入 system prompt
- *   - SKILL.md body 通过 SDK 内置 Skill 工具按需加载（不再走 systemPrompt.append 恒驻）
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/** Plugin 根目录（含 .claude-plugin/plugin.json + skills/）*/
-export const PLUGIN_ROOT = path.resolve(
-  process.env.NODESIGN_PLUGIN_DIR || path.join(__dirname, '../plugins/nodesign')
-);
-
-/** Skills 子目录（plugin convention：<plugin>/skills/<skill-id>/SKILL.md）*/
-export const SKILLS_ROOT = path.resolve(
-  process.env.NODESIGN_SKILLS_DIR || path.join(PLUGIN_ROOT, 'skills')
-);
-
-/**
- * 加载一个 skill。返回 { id, name, version, description, systemPrompt, raw }。
- * 找不到时抛 Error（code='SKILL_NOT_FOUND'）。
- */
-export async function loadSkill(skillId) {
-  if (!skillId || typeof skillId !== 'string') {
-    throw Object.assign(new Error('loadSkill: skillId required'), { code: 'INVALID_SKILL_ID' });
-  }
-
-  const skillDir = path.join(SKILLS_ROOT, skillId);
-  const skillFile = path.join(skillDir, 'SKILL.md');
-
-  let raw;
-  try {
-    raw = await fs.readFile(skillFile, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      throw Object.assign(
-        new Error(`skill not found: ${skillId} (expected at ${skillFile})`),
-        { code: 'SKILL_NOT_FOUND' }
-      );
-    }
-    throw err;
-  }
-
-  const { frontmatter, body } = parseFrontmatter(raw);
-
-  return {
-    id: skillId,
-    name: frontmatter.name || skillId,
-    version: frontmatter.version || '0.0.0',
-    description: frontmatter.description || '',
-    systemPrompt: body.trim(),
-    frontmatter,
-    raw,
-  };
-}
-
-/**
- * 把 skill 自带的工作区起手文件（目前主要是 canvas.template.html）拷贝
- * 进 session cwd，让 agent 能直接 `Read canvas.template.html` 而不必去
- * 仓库相对路径找（agent 看不到 server/engine/plugins/nodesign/skills/）。
- *
- * **拷贝不软链**：
- *   - 跨平台稳（Windows symlink 要 admin / Linux bwrap 不解析 symlink）
- *   - 防 agent 误 Edit 改源模板（影响其他 session）
- *   - session 是一次性沙盒，拷贝快照语义合理
- *
- * **幂等**：文件已存在就不覆盖（agent 改过的、或上次 session init 拷过的不动）。
- *
- * **起手文件是自动发现的**（2026-07-28 从硬编码 `['canvas.template.html']` 改来）：
- * skill 目录里凡是文件名带 `.template.` 的都算起手文件。加第二个 skill
- * （站点）时不必再回来改这里 —— 硬编码一个文件名意味着新 skill 的模板永远
- * 拷不出来，而且是静默的：agent 只会 `Read` 失败然后凭空写。
- *
- * @param {string} sessionRoot - sessions/<sid>/ 绝对路径
- * @param {string} skillId    - 同 loadSkill 的 skillId
- * @returns {Promise<{ copied: string[], skipped: string[] }>}
- */
-/** 内置 plugin 里现有的 skill id（目录名即 id） */
-export async function listSkillIds() {
-  try {
-    const entries = await fs.readdir(SKILLS_ROOT, { withFileTypes: true });
-    return entries.filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name);
-  } catch { return []; }
-}
-
-export async function listSkillStarterFiles(skillId) {
-  if (!skillId) return [];
-  try {
-    const entries = await fs.readdir(path.join(SKILLS_ROOT, skillId), { withFileTypes: true });
-    return entries
-      .filter(e => e.isFile() && e.name.includes('.template.'))
-      .map(e => e.name)
-      .sort();
-  } catch { return []; }
-}
-
-export async function ensureSkillStarterFiles(sessionRoot, skillId) {
-  const result = { copied: [], skipped: [] };
-  if (!sessionRoot || !skillId) return result;
-
-  const skillDir = path.join(SKILLS_ROOT, skillId);
-  const starterFiles = await listSkillStarterFiles(skillId);
-
-  for (const name of starterFiles) {
-    const src = path.join(skillDir, name);
-    const dst = path.join(sessionRoot, name);
-
-    let srcExists = false;
-    try {
-      await fs.access(src);
-      srcExists = true;
-    } catch { /* skill 没这个起手文件 */ }
-    if (!srcExists) continue;
-
-    let dstExists = false;
-    try {
-      await fs.access(dst);
-      dstExists = true;
-    } catch { /* dst 不存在，需要拷 */ }
-    if (dstExists) {
-      result.skipped.push(name);
-      continue;
-    }
-
-    try {
-      await fs.copyFile(src, dst);
-      result.copied.push(name);
-    } catch (err) {
-      console.warn(
-        `[skill] copy ${name} failed (${err.code || err.message}); `
-        + `agent will not have it in cwd`,
-      );
-    }
-  }
-
-  return result;
-}
-
-// ── frontmatter 解析（极简 YAML：只支持 key: value）──
-
-const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
-
-/**
- * 解析 SKILL.md 的 frontmatter + body。
- * 不支持嵌套 / 多行 / list — 只接受 `key: value` 形态。
- *
- * 没 frontmatter 的文件：返回 { frontmatter: {}, body: <整个文件> }
- */
-function parseFrontmatter(raw) {
-  const m = FRONTMATTER_RE.exec(raw);
-  if (!m) return { frontmatter: {}, body: raw };
-
-  const [, yamlText, body] = m;
-  const frontmatter = {};
-  for (const line of yamlText.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx < 1) continue;
-    const key = trimmed.slice(0, colonIdx).trim();
-    let value = trimmed.slice(colonIdx + 1).trim();
-    // 去掉成对引号
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    frontmatter[key] = value;
-  }
-  return { frontmatter, body: body || '' };
-}
-
-// 暴露供单测
-export { parseFrontmatter };
+/**
+ * skill.js — Skill 加载器（YAML frontmatter + Markdown body）
+ *
+ * 目录结构（2026-05-18 起，对齐 Claude Code plugin convention）：
+ *   server/engine/plugins/nodesign/
+ *     .claude-plugin/plugin.json       — plugin 元数据
+ *     skills/<skill-id>/SKILL.md       — 各 skill
+ *     skills/<skill-id>/<其他起手文件>
+ *
+ * SKILL.md 格式（YAML frontmatter + body）：
+ *   ---
+ *   name: deskskill-engine-mini
+ *   version: 0.0.1
+ *   description: 给 LLM 看的"什么时候用我"的描述
+ *   ---
+ *
+ *   # System Prompt
+ *
+ *   你是一个 deck 设计 agent...（任意 markdown）
+ *
+ * 本模块职责：
+ *   - 解析 SKILL.md 的 YAML frontmatter + body（loadSkill）
+ *   - 把 skill 起手文件（canvas.template.html 等）拷进 session cwd（ensureSkillStarterFiles）
+ *
+ * 注：批量扫 plugin 下所有 skill 走 plugin-loader.js `listInstalledPluginsDetailed`，
+ * 不在本模块（API 层 server/api/skills.js 用那个）。
+ *
+ * SDK 集成（在 session-loop.js）：
+ *   - plugins: [{ type: 'local', path: PLUGIN_ROOT }]  → 让 SDK 识别本 plugin
+ *   - skills: [<skill-id>]                              → 让 SDK 把 description 注入 system prompt
+ *   - SKILL.md body 通过 SDK 内置 Skill 工具按需加载（不再走 systemPrompt.append 恒驻）
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Plugin 根目录（含 .claude-plugin/plugin.json + skills/）*/
+export const PLUGIN_ROOT = path.resolve(
+  process.env.NODESIGN_PLUGIN_DIR || path.join(__dirname, '../plugins/nodesign')
+);
+
+/** Skills 子目录（plugin convention：<plugin>/skills/<skill-id>/SKILL.md）*/
+export const SKILLS_ROOT = path.resolve(
+  process.env.NODESIGN_SKILLS_DIR || path.join(PLUGIN_ROOT, 'skills')
+);
+
+/**
+ * 加载一个 skill。返回 { id, name, version, description, systemPrompt, raw }。
+ * 找不到时抛 Error（code='SKILL_NOT_FOUND'）。
+ */
+export async function loadSkill(skillId) {
+  if (!skillId || typeof skillId !== 'string') {
+    throw Object.assign(new Error('loadSkill: skillId required'), { code: 'INVALID_SKILL_ID' });
+  }
+
+  const skillDir = path.join(SKILLS_ROOT, skillId);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  let raw;
+  try {
+    raw = await fs.readFile(skillFile, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw Object.assign(
+        new Error(`skill not found: ${skillId} (expected at ${skillFile})`),
+        { code: 'SKILL_NOT_FOUND' }
+      );
+    }
+    throw err;
+  }
+
+  const { frontmatter, body } = parseFrontmatter(raw);
+
+  return {
+    id: skillId,
+    name: frontmatter.name || skillId,
+    version: frontmatter.version || '0.0.0',
+    description: frontmatter.description || '',
+    systemPrompt: body.trim(),
+    frontmatter,
+    raw,
+  };
+}
+
+/**
+ * 把 skill 自带的工作区起手文件（目前主要是 canvas.template.html）拷贝
+ * 进 session cwd，让 agent 能直接 `Read canvas.template.html` 而不必去
+ * 仓库相对路径找（agent 看不到 server/engine/plugins/nodesign/skills/）。
+ *
+ * **拷贝不软链**：
+ *   - 跨平台稳（Windows symlink 要 admin / Linux bwrap 不解析 symlink）
+ *   - 防 agent 误 Edit 改源模板（影响其他 session）
+ *   - session 是一次性沙盒，拷贝快照语义合理
+ *
+ * **幂等**：文件已存在就不覆盖（agent 改过的、或上次 session init 拷过的不动）。
+ *
+ * **起手文件是自动发现的**（2026-07-28 从硬编码 `['canvas.template.html']` 改来）：
+ * skill 目录里凡是文件名带 `.template.` 的都算起手文件。加第二个 skill
+ * （站点）时不必再回来改这里 —— 硬编码一个文件名意味着新 skill 的模板永远
+ * 拷不出来，而且是静默的：agent 只会 `Read` 失败然后凭空写。
+ *
+ * @param {string} sessionRoot - sessions/<sid>/ 绝对路径
+ * @param {string} skillId    - 同 loadSkill 的 skillId
+ * @returns {Promise<{ copied: string[], skipped: string[] }>}
+ */
+/** 内置 plugin 里现有的 skill id（目录名即 id） */
+export async function listSkillIds() {
+  try {
+    const entries = await fs.readdir(SKILLS_ROOT, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name);
+  } catch { return []; }
+}
+
+export async function listSkillStarterFiles(skillId) {
+  if (!skillId) return [];
+  try {
+    const entries = await fs.readdir(path.join(SKILLS_ROOT, skillId), { withFileTypes: true });
+    return entries
+      .filter(e => e.isFile() && e.name.includes('.template.'))
+      .map(e => e.name)
+      .sort();
+  } catch { return []; }
+}
+
+export async function ensureSkillStarterFiles(sessionRoot, skillId) {
+  const result = { copied: [], skipped: [] };
+  if (!sessionRoot || !skillId) return result;
+
+  const skillDir = path.join(SKILLS_ROOT, skillId);
+  const starterFiles = await listSkillStarterFiles(skillId);
+
+  for (const name of starterFiles) {
+    const src = path.join(skillDir, name);
+    const dst = path.join(sessionRoot, name);
+
+    let srcExists = false;
+    try {
+      await fs.access(src);
+      srcExists = true;
+    } catch { /* skill 没这个起手文件 */ }
+    if (!srcExists) continue;
+
+    let dstExists = false;
+    try {
+      await fs.access(dst);
+      dstExists = true;
+    } catch { /* dst 不存在，需要拷 */ }
+    if (dstExists) {
+      result.skipped.push(name);
+      continue;
+    }
+
+    try {
+      await fs.copyFile(src, dst);
+      result.copied.push(name);
+    } catch (err) {
+      console.warn(
+        `[skill] copy ${name} failed (${err.code || err.message}); `
+        + `agent will not have it in cwd`,
+      );
+    }
+  }
+
+  return result;
+}
+
+// ── frontmatter 解析（极简 YAML：只支持 key: value）──
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+
+/**
+ * 解析 SKILL.md 的 frontmatter + body。
+ * 不支持嵌套 / 多行 / list — 只接受 `key: value` 形态。
+ *
+ * 没 frontmatter 的文件：返回 { frontmatter: {}, body: <整个文件> }
+ */
+function parseFrontmatter(raw) {
+  const m = FRONTMATTER_RE.exec(raw);
+  if (!m) return { frontmatter: {}, body: raw };
+
+  const [, yamlText, body] = m;
+  const frontmatter = {};
+  for (const line of yamlText.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx < 1) continue;
+    const key = trimmed.slice(0, colonIdx).trim();
+    let value = trimmed.slice(colonIdx + 1).trim();
+    // 去掉成对引号
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body: body || '' };
+}
+
+// 暴露供单测
+export { parseFrontmatter };

package/server/engine/agent/task-events.js

@@ -1,78 +1,78 @@
-/**
- * task-events.js — SDK 统一任务消息族（task_*）的收口翻译（2026-08-18，
- * 从 agent-shared.js handleSystemMessage 拆出）
- *
- * SDK 0.3.x 起「任务」统一化：task_* 消息不再只代表 Task 子代理 —— 后台
- * Bash（task_type 'local_bash'）、Workflow（'local_workflow'）等也走同一条。
- * 我们 run.task.* 事件的语义是「子代理」，在这个咽喉点收口：只放真子代理
- * 过去，其余不进事件流。不收口的话每条 bash 命令都会在前端顶着「子代理」
- * 的名头出现（舞台便利贴/在场徽记/侧栏状态位全线噪音，2026-08-18 事故）。
- */
-
-import { Events } from './events.js';
-import { recordTaskNotification } from './hooks/post-subagent-report.js';
-
-/**
- * 这条 task_* 消息说的是不是真子代理（Task 工具）。靠 subagent_type /
- * task_type 区分；skip_transcript 是 SDK 标的 ambient/housekeeping 任务，
- * 按 SDK 约定对用户隐藏。
- */
-export function isSubagentTask(msg) {
-  if (msg.skip_transcript) return false;
-  return !!msg.subagent_type || msg.task_type === 'local_agent';
-}
-
-/**
- * 本轮已放行的子代理 task_id —— task_progress / task_notification 不带
- * subagent_type，靠它过滤非子代理任务。挂在 ctx 上惰性建：task_* 消息
- * 不带 parent_tool_use_id，进来的恒是真 ctx（不是子代理的派生 ctx），
- * own property 不会写丢。
- */
-function subagentTaskIds(ctx) {
-  if (!ctx._subagentTaskIds) ctx._subagentTaskIds = new Set();
-  return ctx._subagentTaskIds;
-}
-
-/** handleSystemMessage 的 task_* 四兄弟统一入口 */
-export function handleTaskMessage(ctx, msg) {
-  switch (msg.subtype) {
-    case 'task_started':
-      if (!isSubagentTask(msg)) return;
-      subagentTaskIds(ctx).add(msg.task_id);
-      ctx.emit(Events.taskStarted(
-        msg.task_id, msg.description, msg.subagent_type, msg.task_type, msg.prompt, msg.tool_use_id,
-      ));
-      return;
-
-    case 'task_progress':
-      // agentProgressSummaries: true 时每 ~30s 一次："正在调整字号节奏" 之类
-      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
-      ctx.emit(Events.taskProgress(
-        msg.task_id, msg.description, msg.summary, msg.last_tool_name, msg.usage, msg.tool_use_id,
-      ));
-      return;
-
-    case 'task_updated':
-      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
-      ctx.emit(Events.taskUpdated(msg.task_id, msg.patch, msg.tool_use_id));
-      return;
-
-    case 'task_notification':
-      // 收尾用量记账不分任务类型（进 metadata 可观测，不进主 token 列 ——
-      // 防止与 result.usage 双重计数，详见 context.absorbSubagentUsage）：
-      // 将来若接 workflow 之类带真用量的本地任务，账也不能漏。
-      ctx.absorbSubagentUsage?.(msg.usage);
-      // 报告丢失的兜底也在闸**前**：把 output_file 记下来，PostToolUse(Agent)
-      // 的 handler 在报告看起来是空的时候把转录路径递给主 agent（见
-      // hooks/post-subagent-report.js）。它按 tool_use_id 查、只被 Agent 工具
-      // 问到，多记非子代理任务无害；安全网不该依赖过滤闸的状态（存储有界 200 条）。
-      recordTaskNotification(msg);
-      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
-      ctx.emit(Events.taskNotification(
-        msg.task_id, msg.status, msg.summary, msg.usage, msg.tool_use_id,
-      ));
-      return;
-
-    default:
-  }
-}
+/**
+ * task-events.js — SDK 统一任务消息族（task_*）的收口翻译（2026-08-18，
+ * 从 agent-shared.js handleSystemMessage 拆出）
+ *
+ * SDK 0.3.x 起「任务」统一化：task_* 消息不再只代表 Task 子代理 —— 后台
+ * Bash（task_type 'local_bash'）、Workflow（'local_workflow'）等也走同一条。
+ * 我们 run.task.* 事件的语义是「子代理」，在这个咽喉点收口：只放真子代理
+ * 过去，其余不进事件流。不收口的话每条 bash 命令都会在前端顶着「子代理」
+ * 的名头出现（舞台便利贴/在场徽记/侧栏状态位全线噪音，2026-08-18 事故）。
+ */
+
+import { Events } from './events.js';
+import { recordTaskNotification } from './hooks/post-subagent-report.js';
+
+/**
+ * 这条 task_* 消息说的是不是真子代理（Task 工具）。靠 subagent_type /
+ * task_type 区分；skip_transcript 是 SDK 标的 ambient/housekeeping 任务，
+ * 按 SDK 约定对用户隐藏。
+ */
+export function isSubagentTask(msg) {
+  if (msg.skip_transcript) return false;
+  return !!msg.subagent_type || msg.task_type === 'local_agent';
+}
+
+/**
+ * 本轮已放行的子代理 task_id —— task_progress / task_notification 不带
+ * subagent_type，靠它过滤非子代理任务。挂在 ctx 上惰性建：task_* 消息
+ * 不带 parent_tool_use_id，进来的恒是真 ctx（不是子代理的派生 ctx），
+ * own property 不会写丢。
+ */
+function subagentTaskIds(ctx) {
+  if (!ctx._subagentTaskIds) ctx._subagentTaskIds = new Set();
+  return ctx._subagentTaskIds;
+}
+
+/** handleSystemMessage 的 task_* 四兄弟统一入口 */
+export function handleTaskMessage(ctx, msg) {
+  switch (msg.subtype) {
+    case 'task_started':
+      if (!isSubagentTask(msg)) return;
+      subagentTaskIds(ctx).add(msg.task_id);
+      ctx.emit(Events.taskStarted(
+        msg.task_id, msg.description, msg.subagent_type, msg.task_type, msg.prompt, msg.tool_use_id,
+      ));
+      return;
+
+    case 'task_progress':
+      // agentProgressSummaries: true 时每 ~30s 一次："正在调整字号节奏" 之类
+      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
+      ctx.emit(Events.taskProgress(
+        msg.task_id, msg.description, msg.summary, msg.last_tool_name, msg.usage, msg.tool_use_id,
+      ));
+      return;
+
+    case 'task_updated':
+      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
+      ctx.emit(Events.taskUpdated(msg.task_id, msg.patch, msg.tool_use_id));
+      return;
+
+    case 'task_notification':
+      // 收尾用量记账不分任务类型（进 metadata 可观测，不进主 token 列 ——
+      // 防止与 result.usage 双重计数，详见 context.absorbSubagentUsage）：
+      // 将来若接 workflow 之类带真用量的本地任务，账也不能漏。
+      ctx.absorbSubagentUsage?.(msg.usage);
+      // 报告丢失的兜底也在闸**前**：把 output_file 记下来，PostToolUse(Agent)
+      // 的 handler 在报告看起来是空的时候把转录路径递给主 agent（见
+      // hooks/post-subagent-report.js）。它按 tool_use_id 查、只被 Agent 工具
+      // 问到，多记非子代理任务无害；安全网不该依赖过滤闸的状态（存储有界 200 条）。
+      recordTaskNotification(msg);
+      if (!subagentTaskIds(ctx).has(msg.task_id)) return;
+      ctx.emit(Events.taskNotification(
+        msg.task_id, msg.status, msg.summary, msg.usage, msg.tool_use_id,
+      ));
+      return;
+
+    default:
+  }
+}