@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/build-docx.js

@@ -0,0 +1,101 @@
+/**
+ * mcp/tools/build-docx.js — build_docx MCP tool（2026-08-17）
+ *
+ * 把 token 源文件构建成 .docx。
+ *
+ * ⭐**agent 拿到的是一条命令，不是一个构建系统。** 它写 JSON、调这个工具、
+ * 然后 screenshot 看结果 —— 不需要知道 OOXML、不需要跑 node、不需要碰沙盒
+ * 外的东西。（跟 h3box / publish_site 一个路子。）
+ *
+ * ⚠️ 构建完**不自动截图**：那会让每次构建都多花几秒和一张图的上下文。看不看
+ * 由 agent 自己决定 —— 但返回文案里会催它去看，因为「做完看一眼」这条纪律在
+ * docx 上比在网页上更要紧（没有 DOM 可查，眼睛是唯一的验收手段）。
+ */
+
+import path from 'node:path';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { buildFromSource, DocxSourceError } from '../../../lib/docx/build-from-source.js';
+import { formatLint } from '../../../lib/docx/text-lint.js';
+import { setActiveArtifact } from '../../../lib/artifact-target.js';
+import { safeResolveRead, safeResolveWrite } from '../../../lib/safe-path.js';
+import { Events } from '../../agent/events.js';
+
+const err = (text) => ({ content: [{ type: 'text', text }], isError: true });
+
+export function makeBuildDocxTool({ workspaceRoot, sessionId, ctx }) {
+  return tool(
+    'build_docx',
+    `Build a .docx from its token source file.
+
+The token JSON is the source of truth; the .docx is a build output. Always edit
+the JSON and rebuild — never hand-edit the .docx, or the next build silently
+throws your edit away.
+
+Source file shape:
+  {
+    "preset":  "公文",              // dictionary entry to start from (optional)
+    "tokens":  { ... },             // overrides on top of the preset
+    "content": [ {"t":"p","style":"Normal","text":"..."} ],
+    "header":  "...", "footer": "..."   // optional
+  }
+
+Built-in dictionary entries: 办公标准 (plain Office look) / 公文 (GB/T 9704-2012
+Chinese official document) / 学术论文 (Chinese academic). These are starting
+points, not a menu — override tokens freely, or skip preset and supply the full
+token table.
+
+Block types: {"t":"p"} paragraph, {"t":"table"}, {"t":"pageBreak"}.
+
+After building, LOOK AT IT with screenshot. A .docx has no DOM — rendering is
+the only way to verify layout, and "it built without errors" says nothing about
+whether it looks right.`,
+    {
+      source: z
+        .string()
+        .optional()
+        .describe("Token source file, workspace-relative. Defaults to '文档.json'."),
+      output: z
+        .string()
+        .optional()
+        .describe("Output .docx path, workspace-relative. Defaults to the source name with a .docx extension."),
+    },
+    async ({ source, output }) => {
+      const srcRel = (source || '文档.json').replace(/\\/g, '/');
+      const outRel = (output || srcRel.replace(/\.json$/i, '.docx')).replace(/\\/g, '/');
+      if (!/\.docx$/i.test(outRel)) return err(`输出得是 .docx，收到的是 ${outRel}`);
+
+      // ⚠️ 词法检查挡不住软链：工作区里一个指向外面的 `out.docx` 软链，会让这个
+      // 工具变成一个**绕过沙盒的任意写原语**（MCP 工具跑在 server 进程里，不在
+      // bwrap 内）。读写判据不同，见 lib/safe-path.js。
+      const srcAbs = await safeResolveRead(workspaceRoot, srcRel);
+      if (!srcAbs) return err('源路径跑出工作区了');
+      const outAbs = await safeResolveWrite(workspaceRoot, outRel);
+      if (!outAbs) return err('产物路径跑出工作区了（目标是软链也会被拒 —— 顺着它写会覆盖工作区外的文件）');
+
+      try {
+        const r = await buildFromSource(srcAbs, outAbs);
+        // 记成当前产物，这样后面 screenshot / 导出不传 path 也能找到它
+        setActiveArtifact(sessionId, outRel, 'docx');
+        // emit file_changed —— 让画布上的 docx 卡**当场**换新页图。MCP 工具写盘
+        // 不走 PostToolUse(Write|Edit) 那条直发（matcher 匹配不到 mcp__nodesign__*），
+        // 不发的话卡片停在旧页图，最多等 60 秒缓存自然过期（generate-image 同款补发）
+        try { ctx?.emit?.(Events.fileChanged(outRel, 'change')); } catch { /* fail-safe */ }
+        return {
+          content: [{
+            type: 'text',
+            text: `${outRel} 已构建 · ${(r.bytes / 1024).toFixed(1)}KB · ${r.blocks} 个块 · ${r.styles} 个样式`
+              + `${r.preset ? ` · 起点「${r.preset}」` : ''}\n`
+              // 字符/版式体检：符号惯例与全文一致性，schema 和渲染都照不到的那层
+              + (r.lint ? formatLint(r.lint) : ''),
+          }],
+        };
+      } catch (e) {
+        if (e instanceof DocxSourceError) {
+          return err(`${srcRel} 构建失败：${e.message}${e.detail ? `\n${e.detail}` : ''}`);
+        }
+        return err(`构建出错：${String(e.message || e).slice(0, 500)}`);
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/clear-pending-changes.js

@@ -0,0 +1,99 @@
+/**
+ * mcp/tools/clear-pending-changes.js — clear_pending_changes MCP tool
+ *
+ * 配 get_pending_changes 用：agent 处理完 pending 变更后清 buffer，
+ * 避免下次 turn 又看到同样的变更被反复处理。
+ *
+ * 不传 ids → 全清；传 ids → 只删指定。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeClearPendingChangesTool({ workspaceRoot, ctx }) {
+  return tool(
+    'clear_pending_changes',
+    `Clear processed items from the user's pending changes buffer.
+
+Call this after you've read pending changes via get_pending_changes and
+acted on them, so the same changes don't re-appear in the next turn.
+
+- Omit ids → clear all
+- Pass ids → clear only those specific items`,
+    {
+      ids: z
+        .array(z.string())
+        .optional()
+        .describe('Specific item ids to clear; omit to clear everything'),
+    },
+    async ({ ids }) => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot clear pending changes.' }],
+            isError: true,
+          };
+        }
+
+        const bufPath = path.join(workspaceRoot, 'pending-changes.json');
+        let buf = { items: [] };
+        try {
+          const raw = await fs.readFile(bufPath, 'utf8');
+          const parsed = JSON.parse(raw);
+          if (parsed && Array.isArray(parsed.items)) buf = parsed;
+        } catch (err) {
+          if (err.code !== 'ENOENT') throw err;
+        }
+
+        const beforeItems = buf.items;
+        let clearedItems;
+        if (Array.isArray(ids) && ids.length > 0) {
+          const set = new Set(ids);
+          clearedItems = beforeItems.filter(it => set.has(it.id));
+          buf.items = beforeItems.filter(it => !set.has(it.id));
+        } else {
+          clearedItems = beforeItems;
+          buf.items = [];
+        }
+        const removed = clearedItems.length;
+        // 带上被清的 id 列表，让前端可以同步移除 comments state 里对应的橙色 overlay。
+        // 前端 comments[].id 跟 pending-changes item.id 已统一（见 ProjectWorkspace
+        // handleAddComment + pending-changes.js POST accept body.id）。
+        const clearedIds = clearedItems.map(it => it.id);
+
+        await fs.writeFile(bufPath, JSON.stringify(buf, null, 2), 'utf8');
+
+        try {
+          ctx?.emit?.({
+            type: 'run.pending_changes_cleared',
+            clearedIds,
+            removed,
+            remaining: buf.items.length,
+          });
+        } catch { /* emit fail-safe */ }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Cleared ${removed} pending change(s); ${buf.items.length} remaining.`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `clear_pending_changes failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/create-on-board.js

@@ -0,0 +1,155 @@
+/**
+ * mcp/tools/create-on-board.js —— create_on_board（2026-08-14，agent 建元素批）
+ *
+ * 让 agent 落**用户级的画布原生物件**。v1 只开手写字（text）：便签是留档不是
+ * 聊天，agent 值得写下来的是"这一版为什么这么改"这类一句话，不是回复的搬运。
+ * 涂鸦不开 —— agent 画矢量笔迹没有意义，它要画图走生图。
+ *
+ * 设计对齐用户侧：
+ *   - near 锚定 = 用户"标注"的同构（落在锚右侧空白，关系线可选一步带上）——
+ *     一次调用 = 一段字 + 一条线，跟 keepAnnotation 落的东西一模一样
+ *   - 字体/字号走 board-store 同一份白名单（TEXT_FONTS）
+ *   - 尺寸估算抄前端 handleCreateText 同款公式（约 26 全角字/行）
+ *   - by:'agent' 出处，用户一眼分得出谁写的
+ *
+ * 护栏：每回合上限 4 条 —— 画布是版面不是弹幕区。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard, TEXT_FONTS } from '../../../projects/board-store.js';
+import { estimateSize } from '../../../lib/board-kind-sizes.js';
+import { normalizeCanvasId, layerOf } from '../../../lib/canvas-id.js';
+
+const MAX_PER_TURN = 4;
+const SIZE_PX = { sm: 13, md: 16, lg: 22, xl: 30 };
+
+let seq = 0;
+const nextTextId = () => `text:a${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+const nextBindingId = () => `b:a${Date.now().toString(36)}n${(seq++ % 1000).toString(36)}`;
+
+/** 前端 handleCreateText 同款身位估算（约 26 全角字/行，行高 1.6） */
+function textBox(t, sizeKey) {
+  const px = SIZE_PX[sizeKey] || 16;
+  const cols = Math.min(26, Math.max(6, t.length));
+  const lines = Math.ceil(t.length / cols) + (t.match(/\n/g)?.length || 0);
+  return { w: Math.round(cols * px * 1.05) + 12, h: Math.round(lines * px * 1.6) + 10 };
+}
+
+export function makeCreateOnBoardTool({ projectId, ctx }) {
+  const turnStamp = { turn: -1, count: 0 };
+  return tool(
+    'create_on_board',
+    `Write a handwritten note directly on the canvas — the same kind the user writes.
+
+Use it for remarks worth KEEPING on the board: why a version went this way, what
+to compare, a caption for a group. Not for conversation (that goes in your reply)
+and not for documents (write a .md instead). Hard cap: ${MAX_PER_TURN} notes per turn.
+
+- near: anchor it beside a thing (and usually pass relation to draw the line —
+  that is exactly the user's "annotation" gesture: a note + an annotates edge)
+- omit near: the note lands under the desktop's current content`,
+    {
+      text: z.string().min(1).max(200).describe('The note text (≤200 chars, one thought)'),
+      near: z.string().max(300).optional()
+        .describe('Canvas id to place the note next to (right side, auto-avoids overlap)'),
+      relation: z.object({
+        type: z.enum(['annotates', 'link']).describe('annotates = the note is ABOUT it; link = loosely related'),
+        to: z.string().min(1).max(300).describe('Canvas id the line connects to (usually = near)'),
+        label: z.string().max(60).optional().describe('Optional words on the line (link only usually)'),
+      }).optional().describe('Draw a relation line from the note in the same call'),
+      font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional()
+        .describe('Handwriting style (default pen — same as the user\'s default)'),
+      size: z.enum(['sm', 'md', 'lg', 'xl']).optional().describe('Text size (default md)'),
+    },
+    async ({ text, near: rawNear, relation, font, size }) => {
+      if (!projectId) {
+        return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      }
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+
+      const turn = ctx?.counters?.turns ?? -1;
+      if (turnStamp.turn !== turn) { turnStamp.turn = turn; turnStamp.count = 0; }
+      if (turnStamp.count >= MAX_PER_TURN) {
+        return err(`本回合便签额度用完（${MAX_PER_TURN} 条）—— 画布是版面不是弹幕区，要说的话说给用户听。`);
+      }
+
+      const t = String(text).trim();
+      if (!t) return err('空字不落板。');
+      const sizeKey = SIZE_PX[size] ? size : 'md';
+      const box = textBox(t, sizeKey);
+
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      let pos; let zone = '';
+      if (rawNear) {
+        const near = normalizeCanvasId(rawNear);
+        const anchorEntry = near ? board.objects?.[near] : null;
+        if (!anchorEntry || !Number.isFinite(anchorEntry.x)) {
+          return err(`锚点 ${rawNear} 还没有座位（read_board 里看不到就锚不上）。`);
+        }
+        zone = layerOf(near, anchorEntry, known);
+        const aSize = estimateSize(near, anchorEntry);
+        pos = { x: Math.round(anchorEntry.x + aSize.w + 24), y: Math.round(anchorEntry.y) };
+        // 撞卡往下让（同 arrange 的避让）
+        const obstacles = Object.entries(board.objects || {})
+          .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === zone)
+          .map(([id, e]) => ({ ...estimateSize(id, e), x: e.x, y: e.y }));
+        for (let g = 0; g < 40; g += 1) {
+          const blocker = obstacles.find(o =>
+            !(pos.x + box.w <= o.x || o.x + o.w <= pos.x || pos.y + box.h <= o.y || o.y + o.h <= pos.y));
+          if (!blocker) break;
+          pos.y = blocker.y + blocker.h + 16;
+        }
+      } else {
+        // 桌面根层内容最低边下面（跟新物件入座同一条起排线精神）
+        let bottom = 0;
+        for (const [id, e] of Object.entries(board.objects || {})) {
+          if (!Number.isFinite(e?.y) || layerOf(id, e, known) !== '') continue;
+          bottom = Math.max(bottom, e.y + estimateSize(id, e).h);
+        }
+        for (const zz of Object.values(board.zones || {})) {
+          if (Number.isFinite(zz?.y)) bottom = Math.max(bottom, zz.y + 150);
+        }
+        pos = { x: 10, y: Math.round(bottom) + 16 };
+      }
+
+      const textId = nextTextId();
+      const patch = {
+        objects: {
+          [textId]: {
+            x: pos.x, y: pos.y, z: 1, w: box.w, h: box.h,
+            kind: 'text',
+            data: { t, font: TEXT_FONTS.includes(font) ? font : 'pen', size: sizeKey, color: 'ink' },
+            zone, by: 'agent',
+          },
+        },
+      };
+      if (relation) {
+        const to = normalizeCanvasId(relation.to);
+        if (to && to !== textId) {
+          patch.bindings = {
+            [nextBindingId()]: {
+              type: relation.type, from: textId, to, by: 'agent',
+              ...(relation.label ? { label: relation.label } : {}),
+            },
+          };
+        }
+      }
+
+      const saved = await patchBoard(projectId, patch);
+      if (!saved.objects?.[textId]) return err('便签被 board 拒了（内容或字段不合法）。');
+      turnStamp.count += 1;
+      try {
+        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: '写了一条画布便签' });
+      } catch { /* fail-soft */ }
+      return {
+        content: [{
+          type: 'text',
+          text: `Note on board at (${pos.x},${pos.y})${relation ? ' with a line' : ''} (id: ${textId}).`
+            + ` ${MAX_PER_TURN - turnStamp.count} left this turn.`,
+        }],
+      };
+    },
+  );
+}

package/server/engine/mcp/tools/crystallize-skill.js

@@ -0,0 +1,168 @@
+/**
+ * mcp/tools/crystallize-skill.js — crystallize_skill MCP tool
+ *
+ * 把一次真实探索的**结论**固化成用户自己的 skill，并把作品收进个人橱窗。
+ *
+ * 为什么不是"存模板"：模板是把成品存下来，换个主题就崩——真正能复用的是判断依据
+ * （为什么这个字号阶梯、为什么这个场合压住动效、哪些默认做法在这个气质里必须反掉）。
+ * 所以这个工具收的是方法论，不是 HTML。产物写进用户级 plugin 根
+ * （~/.nodesign/plugins/<userId>/<name>/），下次开新会话在**这个用户的所有项目**里
+ * 都能用（plugin 发现是 startup-time，当前会话不生效）。
+ *
+ * 跟 record_decision 的分工：决策贴是**这一件作品**的过程档案，随任务走；
+ * 这里是跨项目复用的方法论，随用户走。一个是日志，一个是沉淀。
+ *
+ * 归属：写到**项目 owner** 的目录，不是"当前请求者"——同一个项目谁跑都该产出同一
+ * 套资产。owner 查不到就报错，不往共享根写（那是刚修掉的跨用户污染路径）。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { getProject } from '../../../projects/store.js';
+import { getUserPluginsRoot } from '../../agent/plugin-loader.js';
+import { installPluginToRoot } from '../../../lib/plugin-install.js';
+import { upsertEntry } from '../../../lib/showcase-store.js';
+import { getActiveArtifact } from '../../../lib/artifact-target.js';
+import { Events } from '../../agent/events.js';
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{2,39}$/;
+
+function composeSkillMd({ name, title, description, body }) {
+  return [
+    '---',
+    `name: ${name}`,
+    `description: ${description.replace(/\n+/g, ' ').trim()}`,
+    'version: 0.1.0',
+    '---',
+    '',
+    `# ${title.trim()}`,
+    '',
+    body.trim(),
+    '',
+  ].join('\n');
+}
+
+/**
+ * @param {object} deps
+ * @param {string} [deps.projectId]
+ * @param {string} [deps.sessionId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeCrystallizeSkillTool({ projectId, sessionId, ctx }) {
+  return tool(
+    'crystallize_skill',
+    `Distill a style/approach the user and you worked out together into a REUSABLE
+SKILL owned by this user, and put the finished work in their personal showcase.
+
+Call this ONLY when the user asks to keep a style, or explicitly confirms they
+want this approach reusable. Never call it unprompted — a skill the user did not
+ask for is clutter in every future session.
+
+What belongs in \`body\` is the METHODOLOGY, not the artifact:
+- The reasoning behind the choices (why this type scale, why this palette works
+  for this kind of room, why motion was held back here)
+- What the user rejected along the way and why — the negative space is the most
+  reusable part
+- The anti-default list for this style: what the obvious move would have been,
+  and why it was wrong here
+- Where this style BREAKS DOWN — occasions it does not suit. A skill that cannot
+  state its own boundary is a template wearing a methodology costume, and it will
+  produce bad work the first time it is applied off-target.
+
+Do NOT paste HTML/CSS of the finished piece. Concrete values (a specific hex, a
+specific scale) belong in only as illustrations of the reasoning.
+
+The skill lands in the user's personal plugin dir and becomes available in NEW
+sessions across all their projects (plugin discovery happens at session start,
+so it does not apply to the current session).`,
+    {
+      name: z.string()
+        .describe('Skill id, kebab-case, 3-40 chars (e.g. "quiet-editorial-deck"). Becomes the plugin/skill name.'),
+      title: z.string().min(2).max(80)
+        .describe('Human-readable name of the style (e.g. "安静的编辑气质 · 长文型 deck")'),
+      description: z.string().min(20).max(600)
+        .describe('Frontmatter description — the routing signal. MUST say when to use it AND when not to.'),
+      body: z.string().min(200)
+        .describe('The methodology in markdown: reasoning, rejected alternatives, anti-default list, and where the style breaks down.'),
+      showcaseTitle: z.string().max(80).optional()
+        .describe('Title for the showcase card. Defaults to the style title.'),
+      showcaseNote: z.string().max(400).optional()
+        .describe('One line for the showcase card: what occasion this piece was for.'),
+      artifactPath: z.string().optional()
+        .describe('Work to show on the card, relative to workspace (e.g. "canvas.html" or "稿件/主稿.html"). Defaults to the active artifact.'),
+      overwrite: z.boolean().optional()
+        .describe('Replace an existing skill of the same name. Ask the user before setting this.'),
+    },
+    async ({ name, title, description, body, showcaseTitle, showcaseNote, artifactPath, overwrite }) => {
+      const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+      try {
+        if (!NAME_RE.test(String(name || ''))) {
+          return fail(`Invalid skill name "${name}" — use kebab-case, 3-40 chars, e.g. "quiet-editorial-deck".`);
+        }
+        if (!projectId) return fail('No project bound; cannot resolve who owns this skill.');
+        const ownerId = getProject(projectId)?.ownerId || null;
+        const root = getUserPluginsRoot(ownerId);
+        if (!root) {
+          return fail('This project has no owner on record, so there is no personal skill library to write to.');
+        }
+
+        const md = composeSkillMd({ name, title, description, body });
+        const result = await installPluginToRoot(Buffer.from(md, 'utf8'), root, { force: !!overwrite });
+        if (result.status === 409) {
+          return fail(`A skill named "${name}" already exists in this user's library `
+            + `(${result.body.existing?.description || 'no description'}). `
+            + 'Ask the user whether to replace it, then call again with overwrite: true.');
+        }
+        if (result.status >= 400) {
+          const errs = (result.body.errors || []).join('; ') || result.body.error;
+          return fail(`Skill rejected by validator: ${errs}`);
+        }
+
+        // 橱窗条目：作品 + 它沉淀出来的 skill
+        // 橱窗条目指向的是**产物的相对路径**。扁平化前还要顺带记一个 taskId
+        // （产物住在哪个任务文件夹里），任务层没了之后这个字段永远是 null ——
+        // 留着列是因为 showcase 表里有存量数据，读的时候还认它。
+        const rel = String(artifactPath || getActiveArtifact(sessionId)?.path || '').replace(/\\/g, '/');
+        const artifactRel = rel || null;
+        let entry = null;
+        try {
+          entry = upsertEntry({
+            userId: ownerId,
+            projectId,
+            taskId: null,
+            artifactRel,
+            skillName: name,
+            title: (showcaseTitle || title).trim(),
+            note: showcaseNote?.trim() || null,
+          });
+        } catch (err) {
+          console.warn('[crystallize_skill] showcase entry failed:', err.message);
+        }
+
+        try {
+          ctx?.emit?.({
+            type: 'run.skill_crystallized',
+            skillName: name,
+            title: title.trim(),
+            showcaseId: entry?.id || null,
+          });
+        } catch { /* emit fail-safe */ }
+
+        const warn = (result.body.warnings || []).length
+          ? ` Warnings: ${result.body.warnings.join('; ')}.` : '';
+        return {
+          content: [{
+            type: 'text',
+            text: `Skill "${name}" saved to the user's personal library`
+              + `${artifactRel ? ` and the work added to their showcase` : ''}.`
+              + ` It becomes available in NEW sessions (not this one).${warn}`
+              + ` Tell the user plainly what you captured and what boundary you wrote,`
+              + ` so they can correct it while it is fresh.`,
+          }],
+        };
+      } catch (err) {
+        return fail(`crystallize_skill failed: ${err?.message || String(err)}`);
+      }
+    },
+  );
+}