@xiaobuyu/nodesign 0.0.1

package/server/engine/agent/session-model.js

@@ -0,0 +1,164 @@
+/**
+ * server/engine/agent/session-model.js — 会话跑在哪个模型上，这里是唯一答案
+ *
+ * 在此之前这个事实有 5 个读法和 3 个写法，各不相同：
+ *
+ *   读：session-loop 内联一条 `cfg.model || env || 'kimi-k2.6'`（真正生效的那条）；
+ *       turn.js 又抄了一遍同样的链算 prevEffective；canvas.js 的 readSessionConfig
+ *       只读文件不带 env 兜底；sessions.js 问 `querySession.ctx?.appModel` —— 而
+ *       activeQuerySessions 的 ctx 字段**从注册起就是 null，没有任何地方填过**，
+ *       那一支永远走不到；前端干脆只信自己的 localStorage。
+ *   写：turn.js 的 body.model（写文件 + 空闲时重启 query）；canvas.js 的
+ *       PATCH /config（任意字段透传，写了文件但不重启 query，跑着的会话不认账）；
+ *       POST /runs/:runId/model 调 SDK setModel（只改运行时，不落文件，下次 resume 变回去）。
+ *
+ * 同一个事实有五份算法，就一定会有对不上的时候 —— 比如按钮上写着 Sonnet、
+ * 会话实际跑 Opus，或者选了「默认」什么也没发生。
+ *
+ * 优先级（跟 session-loop 原来那条完全一致，只是搬到了一处）：
+ *   调用方显式指定  >  session-config.json 的 model  >  NODESIGN_MODEL  >  兜底常量
+ *
+ * 「覆盖」(override) 指 session-config.json 里那一项。清掉它 = 回到全局默认，
+ * 这是「默认」那个选项该做的事 —— 以前它什么也不做。
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+import { getQuerySession, closeQuerySession } from '../runs/active-runs.js';
+
+const CONFIG_NAME = 'session-config.json';
+
+/**
+ * NODESIGN_MODEL 没配时的兜底。原值是 kimi 网关时代的 'kimi-k2.6'，08-21 深夜 kimi 行从模型表删除后
+ * 改成订阅默认行（一个不在表里的名字会被 resolveModelRoute 当订阅模型，兜底必须是真名）；
+ * 正常部署 .env 里一定有 NODESIGN_MODEL，走不到这里。
+ */
+const LEGACY_FALLBACK_MODEL = 'claude-sonnet-5[1m]';
+
+/** 全局默认模型（不含会话覆盖）。每次现读 env —— 进程内改 env 也能生效 */
+export function defaultModel() {
+  return process.env.NODESIGN_MODEL || LEGACY_FALLBACK_MODEL;
+}
+
+// ── config 文件的读改写串行化 ──
+// turn.js（发消息时）和模型接口（用户点 picker 时）可能同时改同一个文件，
+// 各自 read-modify-write 会互相吃掉对方的字段。按路径排队。
+/** @type {Map<string, Promise<any>>} */
+const configLocks = new Map();
+
+function withConfigLock(sessionRoot, fn) {
+  const key = path.resolve(sessionRoot);
+  const prev = configLocks.get(key) || Promise.resolve();
+  const next = prev.then(fn, fn);
+  // 链上留的是"完成信号"，不是结果，避免上一个的异常传染下一个
+  configLocks.set(key, next.then(() => {}, () => {}));
+  return next;
+}
+
+/**
+ * ⚠️ 参数是**会话私档目录**（`<工作区>/.nd/<sid>/`），不是工作区根。
+ *
+ * 2026-08-07 扁平化之前两者是同一个目录（一个会话一个沙盒），所以这里叫
+ * `sessionRoot` 也没错。现在工作区是全项目共用的 —— 传工作区根进来的话，
+ * 一个项目里所有会话会共用一份 session-config.json，**在一条会话里换模型，
+ * 另一条会话跟着变**。调用方一律传 getSessionMetaDir(pid, sid)。
+ */
+function configPath(sessionMetaDir) {
+  // 传错了要当场炸，不能默默共用一份配置。这个错误的表现是"在一条会话里换了
+  // 模型，另一条会话也变了"——没人会把它跟一个路径参数联系起来，静默半年都可能。
+  if (!/[/\\]\.nd[/\\][0-9a-f-]{36}$/i.test(path.resolve(sessionMetaDir))) {
+    throw new Error(
+      `[session-model] 需要会话私档目录（<工作区>/.nd/<sid>/），拿到的是 ${sessionMetaDir}。`
+      + '用 getSessionMetaDir(pid, sid)，别传工作区根。',
+    );
+  }
+  return path.join(sessionMetaDir, CONFIG_NAME);
+}
+
+/** 读整份 config（文件不存在 / 坏了 → {}）。不带任何默认字段填充 */
+export async function readSessionConfigFile(sessionRoot) {
+  try {
+    const raw = await fs.readFile(configPath(sessionRoot), 'utf8');
+    const cfg = JSON.parse(raw);
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return {};
+    return cfg;
+  } catch {
+    return {};
+  }
+}
+
+/** 会话自己的模型覆盖；没设过返回 null */
+export async function readSessionModelOverride(sessionRoot) {
+  const cfg = await readSessionConfigFile(sessionRoot);
+  return typeof cfg.model === 'string' && cfg.model.trim() ? cfg.model.trim() : null;
+}
+
+/**
+ * 这个会话实际会跑的模型。
+ * @returns {Promise<{ model: string, override: string|null, fallback: string }>}
+ *   override = 用户在这个会话里选过的；null 表示跟随全局默认
+ */
+export async function resolveSessionModel(sessionRoot) {
+  const override = await readSessionModelOverride(sessionRoot);
+  const fallback = defaultModel();
+  return { model: override || fallback, override, fallback };
+}
+
+/**
+ * 写 / 清会话的模型覆盖。
+ *
+ * @param {string} sessionRoot
+ * @param {string|null} model  字符串 = 设成它；null = **清掉覆盖**，回到全局默认
+ * @returns {Promise<{ model: string, override: string|null, changed: boolean, previous: string }>}
+ *   changed 指"实际生效的模型变了没有" —— 调用方据此决定要不要重启空闲 query。
+ *   把覆盖设成跟全局默认一样的值不算变（跑着的会话本来就是那个模型）。
+ */
+export async function writeSessionModelOverride(sessionRoot, model) {
+  const wanted = typeof model === 'string' && model.trim() ? model.trim() : null;
+  return withConfigLock(sessionRoot, async () => {
+    const cfg = await readSessionConfigFile(sessionRoot);
+    const fallback = defaultModel();
+    const previous = (typeof cfg.model === 'string' && cfg.model.trim()) ? cfg.model.trim() : fallback;
+    const next = { ...cfg, updatedAt: new Date().toISOString() };
+    if (wanted) next.model = wanted;
+    else delete next.model;          // 清覆盖 = 删字段，不是写 null
+    const effective = wanted || fallback;
+    if (previous !== effective || (cfg.model || null) !== wanted) {
+      await fs.writeFile(configPath(sessionRoot), JSON.stringify(next, null, 2), 'utf8');
+    }
+    return { model: effective, override: wanted, changed: previous !== effective, previous };
+  });
+}
+
+/**
+ * 改模型的**完整**动作：写配置 + 让已经跑着的会话认账。
+ *
+ * 这两步必须绑在一起。以前 PATCH /config 只写文件不碰 query，配置说 Opus、
+ * 跑着的进程还是 Sonnet，要等下次 resume 才对上，中间这段时间界面和事实分家。
+ *
+ * 空闲时才关 query：turn 正在跑就只落配置，等这一轮结束后自然重启（前端 picker
+ * 在运行中是禁用的，这里是兜底）。closeQuerySession 之后下一条消息走
+ * startNewRunSession，从同一份 jsonl 以新模型 resume —— 对话内容无损，上下文
+ * 窗口 / spoofing alias / thinking 配置全按新模型重算。
+ *
+ * @param {string} sessionId
+ * @param {string} sessionRoot
+ * @param {string|null} model  null = 清掉覆盖
+ * @param {string} reason      日志用
+ */
+export async function applySessionModel(sessionId, sessionRoot, model, reason = 'api') {
+  const result = await writeSessionModelOverride(sessionRoot, model);
+  let restarted = false;
+  if (result.changed) {
+    const qs = getQuerySession(sessionId);
+    if (qs && !qs.currentRunId) {
+      closeQuerySession(sessionId, 'model_change');
+      restarted = true;
+    }
+    console.info(
+      `[session-model] sid=${sessionId.slice(0, 8)} ${result.previous} → ${result.model}`
+      + ` (${reason}${restarted ? ', query restarted' : ', applies on next resume'})`,
+    );
+  }
+  return { ...result, restarted };
+}

package/server/engine/agent/skill.js

@@ -0,0 +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 };

package/server/engine/agent/system-prompts.js

@@ -0,0 +1,86 @@
+/**
+ * engine/agent/system-prompts.js — 系统提示词的加载与渲染（2026-08-19 从
+ * agent-shared.js 拆出）。
+ *
+ * 拆的理由是行数棘轮："想给胖文件加功能，先拆出去一块再写"。而这一块本来就是
+ * agent-shared 里最不像它的东西 —— 那个文件其余部分是 SDK 消息翻译层和 options
+ * 默认值，跟"提示词长什么样"零耦合。放一起的唯一原因是历史。
+ *
+ * 这里的东西只有一个消费方（session-loop 组装 SDK options 时），但它决定了线上
+ * 每一次对话的系统提示词，改错不会报错、只会让模型行为悄悄变一档 —— 所以两份
+ * markdown 的加载都带兜底日志，底线段的切换带加载期断言。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// NoDesign agent 通用 prelude —— append 在 SDK preset 'claude_code' 之后、
+// SKILL.md 之前。教 Claude Code 工具用法 + NoDesign 工作台共性约束（assets
+// 必看 / 信息不足先问 / git 不自管）。所有 NoDesign agent 共用，跟具体 skill
+// 解耦。模块级 readFileSync 一次性读入，避免每次 turn 重读。
+export const NODESIGN_PRELUDE = (() => {
+  try {
+    // CRLF 归一：Windows git autocrlf 会把 md checkout 成 CRLF，下面 POLICY_BLOCK 按 `\n` 切块
+    // （.gitattributes 已钉 LF，这里是第二道保险，老 checkout 不重拉也能起）
+    return fs.readFileSync(path.join(__dirname, 'prompts/nodesign-prelude.md'), 'utf8').replace(/\r\n?/g, '\n').trim();
+  } catch (err) {
+    console.warn('[system-prompts] failed to load nodesign-prelude.md:', err.message);
+    return '';
+  }
+})();
+
+// 成人段与外审档联动（2026-08-08）：一个旋钮同时管 GPT 外审和提示词口径，
+// 两边永远一致。off=明文允许（站主/获批账号）、loose=原默认、strict=收敛。
+const ADULT_POLICY = {
+  off: '**成人内容明确允许，不用迂回。** 露骨的性与亲密描写照常写、写到位，不留白、不淡化、\n不换成暗示手法带过，前后也不加提醒和免责声明。用户没要求收敛就不要自己收敛，写完接着干活。\n**写实风格照做** —— 照片级真实感的虚构人物不是真人，画得像不构成任何问题，生图同理。\n不做的只有两种：涉及未成年人；把可指认的现实个人（点名的公众人物、用户给的真人照片）\n放进这类内容。除此之外不要自己发明别的边界。',
+  loose: '成人向的亲密情节可以写，涉及未成年人是上面那条绝对红线，真实存在的个人也不写。',
+  strict: '露骨的成人内容在这个账号档位下不写——涉及时收敛处理、用留白带过。',
+};
+
+/**
+ * 「底线」那一节在 prelude 里有**两份并排写着**的版本，标记块框起来：
+ * `nd:policy:full`（对外开放平台的完整产物政策）和 `nd:policy:min`。渲染时留一份、
+ * 删一份，两个标记本身永远不进模型上下文。
+ *
+ * 为什么用显式标记而不是按标题正则切：靠 `## 底线` 到下一个 `##` 去猜边界的话，
+ * 以后谁在这节里加个三级标题，剥离就会剥掉半截 —— 而且不会报错，只会让线上某条
+ * 路径的提示词悄悄少一段。标记块是写死的边界，配下面的加载期断言，切错当场炸。
+ */
+const POLICY_BLOCK = /<!-- nd:policy:(full|min):start -->\n([\s\S]*?)<!-- nd:policy:\1:end -->\n/g;
+
+// 加载期断言：两份都必须在。少一份说明有人编辑 prelude 时把标记删了，那时候
+// 正则会静默退化成"一份都不删"（uncensored 路径拿到完整底线）或"整节消失"。
+{
+  const found = [...NODESIGN_PRELUDE.matchAll(POLICY_BLOCK)].map((m) => m[1]);
+  for (const want of ['full', 'min']) {
+    if (NODESIGN_PRELUDE && !found.includes(want)) {
+      throw new Error(`[system-prompts] nodesign-prelude.md 缺少 nd:policy:${want} 标记块 —— 提示词渲染会静默走错版本`);
+    }
+  }
+}
+
+/**
+ * 渲染 prelude。
+ *
+ * @param {'off'|'loose'|'strict'} level 成人段档位（moderation.levelFor 算出来的）
+ * @param {{uncensored?: boolean}} opts
+ *   `uncensored: true` 时留 `nd:policy:min` 那份 —— 本地无审查权重走这条
+ *   （model-context 表里的 `uncensored` 位，今天只有 qwen3.8-27b）。
+ *
+ *   这不是"把成人档位调到最宽"：off 档改的只是成人段一句话，整节产物政策照旧在。
+ *   min 版是**整节换掉**，站主 08-19 拍板 —— 那节的前提是"对外开放、产物能一键挂
+ *   到站主域名下"，而这条路跑在自己租的盒子上、只对获批账号开、产物不外发，
+ *   前提不成立。留下的一条不随档位变，也不随谁在用变。
+ *
+ *   ⚠️ 默认 false。调用方拿不到模型名时落**完整**那份，绝不落 min。
+ */
+export function renderPrelude(level = 'loose', opts = {}) {
+  const keep = opts.uncensored === true ? 'min' : 'full';
+  return NODESIGN_PRELUDE
+    .replace(POLICY_BLOCK, (_all, which, body) => (which === keep ? body : ''))
+    .replace('{{ADULT_POLICY}}', ADULT_POLICY[level] || ADULT_POLICY.loose)
+    .trim();
+}

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

@@ -0,0 +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:
+  }
+}

package/server/engine/agents/ds-extractor.md

@@ -0,0 +1,132 @@
+# ds-extractor
+
+You are a design system extractor. Given a finished `canvas.html`, you
+read the markup + inline styles + computed style intent, and emit a
+**Design System** JSON document that captures color, typography, spacing,
+shadow, radius — plus recurring composition idioms.
+
+## Your one job
+
+When invoked, you:
+
+1. **Read `canvas.html`** (the only mandatory file). If `spec.json`
+   exists, also read it for design intent context — but the canvas is
+   the source of truth.
+2. **Identify the actual visual rules** by looking at the markup and
+   styles. Don't invent tokens that aren't present; don't omit ones
+   that are clearly used.
+3. **Output one single JSON document** matching the schema below. No
+   commentary, no markdown — just the JSON.
+
+You do NOT modify any file. You do NOT take screenshots (this is a
+structural / textual analysis, not a visual one — `vision-checker` is
+the agent for visual review).
+
+## Output schema
+
+The JSON you output MUST conform to this JSON Schema:
+
+```json
+{
+  "type": "object",
+  "required": ["meta", "colors", "typography", "spacing", "radius", "shadow"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["extractedAt", "sourceArtifact"],
+      "properties": {
+        "extractedAt": "ISO 8601 timestamp",
+        "sourceArtifact": "relative path to the canvas (usually 'canvas.html')",
+        "summary": "one-sentence vibe description"
+      }
+    },
+    "colors": {
+      "primary":    "hex (e.g., '#3366FF')",
+      "secondary":  "hex (optional)",
+      "accent":     "hex (optional)",
+      "text":       { "default": "hex", "100..900": "hex (only steps actually used)" },
+      "background": { "default": "hex", "100..900": "hex (only steps actually used)" },
+      "border":     { "default": "hex" },
+      "status":     { "success": "hex", "warning": "hex", "error": "hex", "info": "hex" }
+    },
+    "typography": {
+      "families": { "sans": "...", "serif": "...", "mono": "..." },
+      "scale": {
+        "h1":   { "fontSize": <number px>, "lineHeight": <number|string>, "weight": <100-900>, "letterSpacing": "..." },
+        "h2":   { ... },
+        "h3":   { ... },
+        "h4":   { ... },
+        "body": { ... },
+        "small": { ... },
+        "caption": { ... }
+      }
+    },
+    "spacing": { "xs": <number>, "sm": <number>, "md": <number>, "lg": <number>, "xl": <number>, "xxl": <number>, "page": <number> },
+    "radius":  { "sm": <number>, "md": <number>, "lg": <number>, "pill": <number> },
+    "shadow":  { "sm": "<css-shadow-string>", "md": "...", "lg": "..." },
+    "idioms":  ["string list — composition patterns repeated ≥2 times in the canvas"]
+  }
+}
+```
+
+The full schema is at `agents/schemas/design-system.json` if you need
+to verify a field shape.
+
+## Extraction guidelines
+
+### Colors
+- Walk every `style="color: ..."`, `background: ...`, `border: ...`,
+  CSS-var references in `<style>` blocks.
+- Group by semantic role (text vs background vs border vs status).
+- If you see a tonal scale (multiple shades of the same hue used for
+  hierarchy), populate the `100..900` keys. Skip steps that aren't used.
+- If a color appears once and looks accidental, omit it. Keep the
+  exported palette tight.
+
+### Typography
+- Read `font-family` declarations to fill `families.sans/serif/mono`.
+- For each used heading level + body / small / caption, find the
+  `font-size` and `line-height` in px (convert em / rem / pt to px
+  using base 16px if needed).
+- Capture `font-weight` if it deviates from default 400.
+
+### Spacing
+- Look at margins / paddings / gaps. Identify the underlying rhythm
+  (commonly 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64).
+- Map to xs / sm / md / lg / xl / xxl based on which step the most
+  common values fall on.
+- `page` = outermost padding (e.g., section wrapper padding).
+
+### Radius
+- `border-radius` values used. Map to sm / md / lg / pill.
+
+### Shadow
+- Each unique `box-shadow` declaration becomes one of sm / md / lg.
+- Output as the literal CSS string (e.g., `"0 2px 4px rgba(0,0,0,0.06)"`).
+
+### Idioms
+- Recurring composition: "stat row = 3-column grid with 24px gap", "every
+  section starts with 1px border-top", "headings are followed by a 4px
+  underline accent". List as plain English strings.
+- ≥ 2 occurrences to count as an idiom (one-off layouts don't qualify).
+
+## Output format
+
+When done, emit ONE message containing ONLY the JSON document. No
+preamble, no postscript, no markdown fences. Just `{...}`.
+
+If `canvas.html` doesn't exist, output:
+
+```json
+{ "error": "canvas.html not found in workspace" }
+```
+
+If extraction fails partially, fill what you have and add a `meta.summary`
+note like "could not extract typography — no <style> tag found".
+
+## Constraints
+
+- Single Read of canvas.html (and optionally spec.json) — don't poll.
+- No screenshots. No tool calls beyond Read.
+- Strict JSON output (parsable by `JSON.parse`).
+- Don't invent tokens — be honest about what's actually in the canvas.