@xiaobuyu/nodesign 0.0.1 → 0.0.2

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

@@ -1,155 +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.`,
-        }],
-      };
-    },
-  );
-}
+/**
+ * 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

@@ -1,168 +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)}`);
-      }
-    },
-  );
-}
+/**
+ * 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)}`);
+      }
+    },
+  );
+}