@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/engine/mcp/tools/export-handoff.js

@@ -1,133 +1,133 @@
-/**
- * mcp/tools/export-handoff.js — export_handoff MCP tool
- *
- * agent 觉得设计到了交付时机时主动调，把 canvas.html / spec.json /
- * assets / chat-history / README 打包成 handoff.zip。
- *
- * 复用 server/api/exports.js 的 buildHandoffZip pipeline，agent 端和
- * 用户按钮路径输出一致。
- *
- * 输出位置：写到 workspace/exports/handoff-<ts>.zip。agent 不能直接给
- * 用户文件，所以告诉用户路径，用户从前端 UI 看到 / 下载。
- *
- * 调用约定（agent 端）：
- *   mcp__nodesign__export_handoff
- *     notes?: string  可选记录"为什么这个时机交付"
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { buildHandoffZip } from '../../../api/exports.js';
-import { getProject, listRunsForProject } from '../../../projects/store.js';
-import { resolveCanvasTarget, CANVAS_PATH_DESC } from '../../../lib/artifact-target.js';
-
-/**
- * @param {object} deps
- * @param {string} deps.workspaceRoot
- * @param {string} [deps.projectId]
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makeExportHandoffTool({ workspaceRoot, sharedRoot, projectId, sessionId, ctx }) {
-  return tool(
-    'export_handoff',
-    `Build a handoff zip: the artifact's source, the assets it actually
-references, and a README that says what it is, how to run it, and — for a
-mock-data app — which backend endpoints the recipient needs to implement.
-
-Use this when the work is done and the user wants to take it away. The point of
-this package is that **someone else can pick the project up and keep building**;
-it is not the "give me a pretty file to look at" path (that's the export menu's
-PDF / single-page HTML).
-
-The zip is written to workspace/exports/handoff-<timestamp>.zip. After building,
-tell the user the path so they can download it via the UI.
-
-Use this tool when:
-- The artifact meets the brief and you've verified it (e.g., via screenshot_canvas)
-- The user says "give me the files" / "package it up" / "I want to host this myself"
-
-Do NOT use this tool when:
-- The work is still in iteration
-- The artifact doesn't exist yet (nothing has been written)`,
-    {
-      notes: z
-        .string()
-        .optional()
-        .describe('Optional notes about why exporting now (gets logged but not in the zip)'),
-      path: z.string().optional().describe(CANVAS_PATH_DESC),
-    },
-    async ({ notes, path: relPath }) => {
-      try {
-        let projectMeta = null;
-        let runs = [];
-        if (projectId) {
-          try {
-            projectMeta = getProject(projectId);
-            runs = listRunsForProject(projectId);
-          } catch { /* DB not available 或 project 已删 */ }
-        }
-
-        // 2026-07-28：这里以前少传了 sharedRoot（签名是 (sessionRoot, sharedRoot, opts)），
-        // opts 被当成 sharedRoot —— 导出的 zip 里 assets 全空、元数据全 unknown。
-        const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
-        if (!target.ok) return { content: [{ type: 'text', text: target.message }], isError: true };
-        const buf = await buildHandoffZip(workspaceRoot, sharedRoot || workspaceRoot, {
-          projectId: projectMeta?.id || projectId || 'unknown',
-          projectName: projectMeta?.name || 'design',
-          skillId: projectMeta?.skillId,
-          sessionId,
-          runs,
-          deckPath: target.relPath,
-        });
-
-        const exportDir = path.join(workspaceRoot, 'exports');
-        await fs.mkdir(exportDir, { recursive: true });
-        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-        // 名字不能再叫 relPath：它会遮蔽入参 relPath，而上面 resolveCanvasTarget
-        // 已经读过那个入参 —— 同一个块里先读后声明 = TDZ，整个工具每次调用必炸
-        const zipRel = `exports/handoff-${stamp}.zip`;
-        const absPath = path.join(workspaceRoot, zipRel);
-        await fs.writeFile(absPath, buf);
-
-        try {
-          ctx?.emit?.({
-            type: 'run.export_built',
-            format: 'handoff',
-            path: zipRel,
-            sizeBytes: buf.length,
-            notes: notes || null,
-          });
-          // 打完包直接进用户的下载列表，不用他再去导出菜单里翻（2026-07-28）
-          ctx?.emit?.({
-            type: 'run.download_ready',
-            url: `/api/projects/${encodeURIComponent(projectId || '')}`
-              + `/sessions/${encodeURIComponent(sessionId || '')}`
-              + `/exports/file/${encodeURIComponent(path.basename(zipRel))}`,
-            filename: path.basename(zipRel),
-            sizeBytes: buf.length,
-            count: 1,
-            note: notes || '工程交付包',
-          });
-        } catch { /* emit fail-safe */ }
-
-        return {
-          content: [{
-            type: 'text',
-            text: `Handoff zip built: ${zipRel} (${(buf.length / 1024).toFixed(1)} KB), deck = ${target.relPath}. `
-              + `Tell the user the package is ready — they can download it from the UI's export menu.`,
-          }],
-        };
-      } catch (err) {
-        return {
-          content: [{
-            type: 'text',
-            text: `Export handoff failed: ${err?.message || String(err)}`,
-          }],
-          isError: true,
-        };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/export-handoff.js — export_handoff MCP tool
+ *
+ * agent 觉得设计到了交付时机时主动调，把 canvas.html / spec.json /
+ * assets / chat-history / README 打包成 handoff.zip。
+ *
+ * 复用 server/api/exports.js 的 buildHandoffZip pipeline，agent 端和
+ * 用户按钮路径输出一致。
+ *
+ * 输出位置：写到 workspace/exports/handoff-<ts>.zip。agent 不能直接给
+ * 用户文件，所以告诉用户路径，用户从前端 UI 看到 / 下载。
+ *
+ * 调用约定（agent 端）：
+ *   mcp__nodesign__export_handoff
+ *     notes?: string  可选记录"为什么这个时机交付"
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { buildHandoffZip } from '../../../api/exports.js';
+import { getProject, listRunsForProject } from '../../../projects/store.js';
+import { resolveCanvasTarget, CANVAS_PATH_DESC } from '../../../lib/artifact-target.js';
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {string} [deps.projectId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeExportHandoffTool({ workspaceRoot, sharedRoot, projectId, sessionId, ctx }) {
+  return tool(
+    'export_handoff',
+    `Build a handoff zip: the artifact's source, the assets it actually
+references, and a README that says what it is, how to run it, and — for a
+mock-data app — which backend endpoints the recipient needs to implement.
+
+Use this when the work is done and the user wants to take it away. The point of
+this package is that **someone else can pick the project up and keep building**;
+it is not the "give me a pretty file to look at" path (that's the export menu's
+PDF / single-page HTML).
+
+The zip is written to workspace/exports/handoff-<timestamp>.zip. After building,
+tell the user the path so they can download it via the UI.
+
+Use this tool when:
+- The artifact meets the brief and you've verified it (e.g., via screenshot_canvas)
+- The user says "give me the files" / "package it up" / "I want to host this myself"
+
+Do NOT use this tool when:
+- The work is still in iteration
+- The artifact doesn't exist yet (nothing has been written)`,
+    {
+      notes: z
+        .string()
+        .optional()
+        .describe('Optional notes about why exporting now (gets logged but not in the zip)'),
+      path: z.string().optional().describe(CANVAS_PATH_DESC),
+    },
+    async ({ notes, path: relPath }) => {
+      try {
+        let projectMeta = null;
+        let runs = [];
+        if (projectId) {
+          try {
+            projectMeta = getProject(projectId);
+            runs = listRunsForProject(projectId);
+          } catch { /* DB not available 或 project 已删 */ }
+        }
+
+        // 2026-07-28：这里以前少传了 sharedRoot（签名是 (sessionRoot, sharedRoot, opts)），
+        // opts 被当成 sharedRoot —— 导出的 zip 里 assets 全空、元数据全 unknown。
+        const target = await resolveCanvasTarget(workspaceRoot, relPath, sessionId);
+        if (!target.ok) return { content: [{ type: 'text', text: target.message }], isError: true };
+        const buf = await buildHandoffZip(workspaceRoot, sharedRoot || workspaceRoot, {
+          projectId: projectMeta?.id || projectId || 'unknown',
+          projectName: projectMeta?.name || 'design',
+          skillId: projectMeta?.skillId,
+          sessionId,
+          runs,
+          deckPath: target.relPath,
+        });
+
+        const exportDir = path.join(workspaceRoot, 'exports');
+        await fs.mkdir(exportDir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        // 名字不能再叫 relPath：它会遮蔽入参 relPath，而上面 resolveCanvasTarget
+        // 已经读过那个入参 —— 同一个块里先读后声明 = TDZ，整个工具每次调用必炸
+        const zipRel = `exports/handoff-${stamp}.zip`;
+        const absPath = path.join(workspaceRoot, zipRel);
+        await fs.writeFile(absPath, buf);
+
+        try {
+          ctx?.emit?.({
+            type: 'run.export_built',
+            format: 'handoff',
+            path: zipRel,
+            sizeBytes: buf.length,
+            notes: notes || null,
+          });
+          // 打完包直接进用户的下载列表，不用他再去导出菜单里翻（2026-07-28）
+          ctx?.emit?.({
+            type: 'run.download_ready',
+            url: `/api/projects/${encodeURIComponent(projectId || '')}`
+              + `/sessions/${encodeURIComponent(sessionId || '')}`
+              + `/exports/file/${encodeURIComponent(path.basename(zipRel))}`,
+            filename: path.basename(zipRel),
+            sizeBytes: buf.length,
+            count: 1,
+            note: notes || '工程交付包',
+          });
+        } catch { /* emit fail-safe */ }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Handoff zip built: ${zipRel} (${(buf.length / 1024).toFixed(1)} KB), deck = ${target.relPath}. `
+              + `Tell the user the package is ready — they can download it from the UI's export menu.`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Export handoff failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/expose-tweaks.js

@@ -1,149 +1,149 @@
-/**
- * mcp/tools/expose-tweaks.js — expose_tweaks MCP tool
- *
- * agent 看完 deck 内容后，把这份 deck 专属的"可调参数控制台"暴露成 schema，
- * 写到 spec.json 的 spec.tweaks 字段。前端 TweaksPanel 读 schema 渲染
- * sliders / color picker / segmented，拖动直接改 iframe :root CSS variable
- * 实时预览（不落盘）；用户点 Apply 触发新 chat run，让 agent 把当前数值固化
- * 进 canvas.html 的 :root。
- *
- * spec.json 结构：
- *   spec.tweaks = {
- *     version: 1,
- *     controls: [{ id, type, label, target_var?, target_class_on?, ... }],
- *     updatedAt, updatedBy: 'agent',
- *   }
- *
- * 触发时机（详见 SKILL.md "Tweaks 暴露协议"）：
- *   - 写完 deck 主动暴露 5-8 个核心可调参数
- *   - 用户问"哪些可以调"时
- *   - 用户在前端点了 Apply 时把 inline style 固化进 :root（这种 case agent
- *     除了写 canvas.html 还应该 expose_tweaks 更新 default 值）
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { mutateSpecJson } from '../../../projects/workspace.js';
-
-const ControlSchema = z.object({
-  id: z.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, 'id must be kebab/snake case'),
-  type: z.enum(['slider', 'color', 'segmented', 'toggle', 'select']),
-  label: z.string().min(1).max(80),
-  description: z.string().max(200).optional(),
-  target_var: z
-    .string()
-    .regex(/^--[a-zA-Z0-9-]+$/, 'target_var must be a CSS custom property starting with --')
-    .optional(),
-  target_class_on: z.string().optional(),
-  // A6.2：CSS selector 限定 control 影响范围。不传默认 ":root"（全局）。
-  // 例：'section[data-page="1"]' / '[data-layout="hero-split"]'（layout 名由 agent
-  // 按隐喻自由命名）。配合 SKILL.md HTML 规范的"per-page scoped override"教学
-  // （让"封面字号"slider 不牵连内页字号）。前端 TweaksPanel 应用时
-  // doc.querySelector(scope) 找元素在它身上 setProperty 而不是 :root。
-  target_scope: z
-    .string()
-    .max(120)
-    .optional()
-    .describe('CSS selector for scope (e.g. \'section[data-page="1"]\'); default ":root" applies globally. Use to limit one control to one page / one layout type.'),
-  min: z.number().optional(),
-  max: z.number().optional(),
-  step: z.number().optional(),
-  default: z.union([z.string(), z.number(), z.boolean()]),
-  unit: z.string().max(8).optional().describe('Suffix appended to numeric value, e.g. "px", "%"'),
-  options: z.array(z.object({
-    label: z.string(),
-    value: z.union([z.string(), z.number()]),
-  })).optional(),
-});
-
-/**
- * @param {object} deps
- * @param {string} deps.workspaceRoot
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makeExposeTweaksTool({ workspaceRoot, ctx }) {
-  return tool(
-    'expose_tweaks',
-    `Expose a "tweaks schema" for the current deck — a list of UI controls
-(slider, color picker, segmented control, toggle, select) that the user can
-drag in the frontend to live-tweak the design without going through chat.
-
-Each control points at a CSS custom property (target_var, must start with --)
-or a class to toggle on root (target_class_on). Frontend renders the controls,
-binds onChange to set CSS variable on iframe :root for instant preview.
-
-Use this tool when:
-- You finished writing/editing canvas.html and want to expose 5-8 most
-  valuable tunables (hero font size, accent color, layout density, etc.)
-- The user asks "what can I adjust"
-- After the user clicks Apply on the frontend Tweaks panel — re-expose with
-  updated default values matching what was just baked into :root
-
-The schema is merged into spec.json's spec.tweaks field. Pass replace=true
-to wipe existing controls; default false merges by id.
-
-Frontend will refresh once it sees run.tweaks_exposed event.`,
-    {
-      controls: z.array(ControlSchema).min(1).max(20).describe('Tweak controls to expose'),
-      replace: z
-        .boolean()
-        .optional()
-        .describe('If true, replace all existing controls; default false merges by id'),
-    },
-    async ({ controls, replace }) => {
-      try {
-        if (!workspaceRoot) {
-          return {
-            content: [{ type: 'text', text: 'No workspace bound; cannot expose tweaks.' }],
-            isError: true,
-          };
-        }
-
-        // 串行 read-modify-write 防 spec.json 三路并发覆盖（详见 workspace.js mutateSpecJson）
-        let merged;
-        await mutateSpecJson(workspaceRoot, (spec) => {
-          const existing = (spec.tweaks && Array.isArray(spec.tweaks.controls))
-            ? spec.tweaks.controls
-            : [];
-          if (replace) {
-            merged = controls;
-          } else {
-            const byId = new Map(existing.map(c => [c.id, c]));
-            for (const c of controls) byId.set(c.id, c);
-            merged = [...byId.values()];
-          }
-          spec.tweaks = {
-            version: 1,
-            controls: merged,
-            updatedAt: new Date().toISOString(),
-            updatedBy: 'agent',
-          };
-        });
-
-        try {
-          ctx?.emit?.({
-            type: 'run.tweaks_exposed',
-            count: merged.length,
-            added: controls.length,
-            replaced: !!replace,
-          });
-        } catch { /* emit fail-safe */ }
-
-        return {
-          content: [{
-            type: 'text',
-            text: `Exposed ${controls.length} tweak control(s); spec.tweaks now has ${merged.length} total.`,
-          }],
-        };
-      } catch (err) {
-        return {
-          content: [{
-            type: 'text',
-            text: `expose_tweaks failed: ${err?.message || String(err)}`,
-          }],
-          isError: true,
-        };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/expose-tweaks.js — expose_tweaks MCP tool
+ *
+ * agent 看完 deck 内容后，把这份 deck 专属的"可调参数控制台"暴露成 schema，
+ * 写到 spec.json 的 spec.tweaks 字段。前端 TweaksPanel 读 schema 渲染
+ * sliders / color picker / segmented，拖动直接改 iframe :root CSS variable
+ * 实时预览（不落盘）；用户点 Apply 触发新 chat run，让 agent 把当前数值固化
+ * 进 canvas.html 的 :root。
+ *
+ * spec.json 结构：
+ *   spec.tweaks = {
+ *     version: 1,
+ *     controls: [{ id, type, label, target_var?, target_class_on?, ... }],
+ *     updatedAt, updatedBy: 'agent',
+ *   }
+ *
+ * 触发时机（详见 SKILL.md "Tweaks 暴露协议"）：
+ *   - 写完 deck 主动暴露 5-8 个核心可调参数
+ *   - 用户问"哪些可以调"时
+ *   - 用户在前端点了 Apply 时把 inline style 固化进 :root（这种 case agent
+ *     除了写 canvas.html 还应该 expose_tweaks 更新 default 值）
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { mutateSpecJson } from '../../../projects/workspace.js';
+
+const ControlSchema = z.object({
+  id: z.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, 'id must be kebab/snake case'),
+  type: z.enum(['slider', 'color', 'segmented', 'toggle', 'select']),
+  label: z.string().min(1).max(80),
+  description: z.string().max(200).optional(),
+  target_var: z
+    .string()
+    .regex(/^--[a-zA-Z0-9-]+$/, 'target_var must be a CSS custom property starting with --')
+    .optional(),
+  target_class_on: z.string().optional(),
+  // A6.2：CSS selector 限定 control 影响范围。不传默认 ":root"（全局）。
+  // 例：'section[data-page="1"]' / '[data-layout="hero-split"]'（layout 名由 agent
+  // 按隐喻自由命名）。配合 SKILL.md HTML 规范的"per-page scoped override"教学
+  // （让"封面字号"slider 不牵连内页字号）。前端 TweaksPanel 应用时
+  // doc.querySelector(scope) 找元素在它身上 setProperty 而不是 :root。
+  target_scope: z
+    .string()
+    .max(120)
+    .optional()
+    .describe('CSS selector for scope (e.g. \'section[data-page="1"]\'); default ":root" applies globally. Use to limit one control to one page / one layout type.'),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  step: z.number().optional(),
+  default: z.union([z.string(), z.number(), z.boolean()]),
+  unit: z.string().max(8).optional().describe('Suffix appended to numeric value, e.g. "px", "%"'),
+  options: z.array(z.object({
+    label: z.string(),
+    value: z.union([z.string(), z.number()]),
+  })).optional(),
+});
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeExposeTweaksTool({ workspaceRoot, ctx }) {
+  return tool(
+    'expose_tweaks',
+    `Expose a "tweaks schema" for the current deck — a list of UI controls
+(slider, color picker, segmented control, toggle, select) that the user can
+drag in the frontend to live-tweak the design without going through chat.
+
+Each control points at a CSS custom property (target_var, must start with --)
+or a class to toggle on root (target_class_on). Frontend renders the controls,
+binds onChange to set CSS variable on iframe :root for instant preview.
+
+Use this tool when:
+- You finished writing/editing canvas.html and want to expose 5-8 most
+  valuable tunables (hero font size, accent color, layout density, etc.)
+- The user asks "what can I adjust"
+- After the user clicks Apply on the frontend Tweaks panel — re-expose with
+  updated default values matching what was just baked into :root
+
+The schema is merged into spec.json's spec.tweaks field. Pass replace=true
+to wipe existing controls; default false merges by id.
+
+Frontend will refresh once it sees run.tweaks_exposed event.`,
+    {
+      controls: z.array(ControlSchema).min(1).max(20).describe('Tweak controls to expose'),
+      replace: z
+        .boolean()
+        .optional()
+        .describe('If true, replace all existing controls; default false merges by id'),
+    },
+    async ({ controls, replace }) => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot expose tweaks.' }],
+            isError: true,
+          };
+        }
+
+        // 串行 read-modify-write 防 spec.json 三路并发覆盖（详见 workspace.js mutateSpecJson）
+        let merged;
+        await mutateSpecJson(workspaceRoot, (spec) => {
+          const existing = (spec.tweaks && Array.isArray(spec.tweaks.controls))
+            ? spec.tweaks.controls
+            : [];
+          if (replace) {
+            merged = controls;
+          } else {
+            const byId = new Map(existing.map(c => [c.id, c]));
+            for (const c of controls) byId.set(c.id, c);
+            merged = [...byId.values()];
+          }
+          spec.tweaks = {
+            version: 1,
+            controls: merged,
+            updatedAt: new Date().toISOString(),
+            updatedBy: 'agent',
+          };
+        });
+
+        try {
+          ctx?.emit?.({
+            type: 'run.tweaks_exposed',
+            count: merged.length,
+            added: controls.length,
+            replaced: !!replace,
+          });
+        } catch { /* emit fail-safe */ }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Exposed ${controls.length} tweak control(s); spec.tweaks now has ${merged.length} total.`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `expose_tweaks failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}