@xiaobuyu/nodesign 0.0.1 → 0.0.3

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

@@ -1,110 +1,112 @@
-/**
- * mcp/tools/relate-on-board.js — relate_on_board MCP tool（2026-08-07）
- *
- * 让 agent 在画布上**画出产物之间的关系**。
- *
- * ## 为什么这个工具重要
- *
- * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
- * 位置在回答「它和旁边那张什么关系」—— 而系统此前只知道每个产物的尺寸和
- * mtime。**关系数据不到位，再好的布局算法也只能排出「错落有致的网格」。**
- *
- * 关键洞察是：**关系不需要推断，agent 手里本来就有**。它知道 proto-暖调 和
- * proto-冷调 是同一拍的两个试作、知道哪张图是哪次批注的结果、知道这版改自那版。
- * 这些信息现在全在会话里，一落到画布就只剩文件名。这个工具就是那条落差。
- *
- * 线不存坐标：端点是物件 id 或工作区 id，端点一移动线自己跟着走。
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { patchBoard } from '../../../projects/board-store.js';
-import { BINDING_TYPES, BINDING_TYPE_IDS } from '../../../lib/binding-types.js';
-
-/** 词汇表渲染成工具描述里的一段表，免得两处各写各的 */
-const VOCAB = BINDING_TYPE_IDS
-  .map(id => `- ${id} (${BINDING_TYPES[id].label})${BINDING_TYPES[id].directed ? '' : ' — undirected'}`)
-  .join('\n');
-
-let seq = 0;
-const nextId = () => `b:a${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
-
-export function makeRelateOnBoardTool({ projectId, ctx }) {
-  return tool(
-    'relate_on_board',
-    `Draw a relationship line between two things on the workbench canvas.
-
-The canvas knows *what* each artifact is, but not *how they relate*. You are
-the only one who knows that — you made them. Recording it lets the user see
-lineage at a glance, and lets layout put related things near each other.
-
-Relationship types:
-${VOCAB}
-
-Endpoints are canvas ids — a kind prefix plus the workspace-relative path,
-exactly as the file sits on disk:
-- a file: 'assets/generated/x.webp', 'notes/灵感.md'
-- a deck: 'deck:海报/proto-暖调.html'
-- a site: 'site:伊蕾娜手账研究站'
-- a folder: just its path, '海报' or '海报/初稿'
-
-Use it right after you produce something that relates to earlier work:
-- made v2 of a poster → derives-from, from the new one to the old one
-- produced two variants to compare → contrast between them
-- storyboard panels in order → flow, each to the next
-- used a reference image in a deck → ref, from the deck to the image
-
-Do NOT use it for "these are all in the same folder" — that is what the
-folder already says. Only record relationships that are not obvious from
-where the files live.`,
-    {
-      type: z.enum(BINDING_TYPE_IDS).describe('Relationship kind (see list above)'),
-      from: z.string().min(1).max(300).describe('Source canvas id — see forms above'),
-      to: z.string().min(1).max(300).describe('Target canvas id — see forms above'),
-      label: z.string().max(60).optional()
-        .describe('Optional short words on the line. Omit to use the default for the type.'),
-    },
-    async ({ type, from, to, label }) => {
-      if (!projectId) {
-        return { content: [{ type: 'text', text: 'No project bound; cannot draw relationships.' }], isError: true };
-      }
-      if (from === to) {
-        return {
-          content: [{ type: 'text', text: 'from and to are the same thing — a relationship needs two ends.' }],
-          isError: true,
-        };
-      }
-      const id = nextId();
-      // by:'agent' 不只是记录出处 —— 用户画的线 agent 不该擅自删，反过来也一样
-      const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}) };
-      const board = await patchBoard(projectId, { bindings: { [id]: binding } });
-
-      // 服务端会丢掉非法的线（未知 type / 自环）。**丢了要说**，否则 agent 以为
-      // 画上了，用户看不到，两边都不知道发生了什么。
-      if (!board.bindings?.[id]) {
-        return {
-          content: [{ type: 'text', text: `Relationship rejected by the board (bad type or endpoints): ${type} ${from} -> ${to}` }],
-          isError: true,
-        };
-      }
-
-      // 广播：前端整份重拉。**sessionId 必须显式给 null** —— ctx 会把自己的
-      // sessionId 补进事件，那样只有当前会话的连接收得到，别的 tab 看不见。
-      try {
-        ctx?.emit?.({
-          type: 'board.updated',
-          sessionId: null,
-          summary: `已画一条「${BINDING_TYPES[type].label}」关系`,
-        });
-      } catch { /* emit fail-safe：广播失败不该让工具报错，线已经落盘了 */ }
-
-      const arrow = BINDING_TYPES[type].directed ? '->' : '<->';
-      return {
-        content: [{
-          type: 'text',
-          text: `Drew ${type} (${BINDING_TYPES[type].label}): ${from} ${arrow} ${to}`,
-        }],
-      };
-    },
-  );
-}
+/**
+ * mcp/tools/relate-on-board.js — relate_on_board MCP tool（2026-08-07）
+ *
+ * 让 agent 在画布上**画出产物之间的关系**。
+ *
+ * ## 为什么这个工具重要
+ *
+ * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
+ * 位置在回答「它和旁边那张什么关系」—— 而系统此前只知道每个产物的尺寸和
+ * mtime。**关系数据不到位，再好的布局算法也只能排出「错落有致的网格」。**
+ *
+ * 关键洞察是：**关系不需要推断，agent 手里本来就有**。它知道 proto-暖调 和
+ * proto-冷调 是同一拍的两个试作、知道哪张图是哪次批注的结果、知道这版改自那版。
+ * 这些信息现在全在会话里，一落到画布就只剩文件名。这个工具就是那条落差。
+ *
+ * 线不存坐标：端点是物件 id 或工作区 id，端点一移动线自己跟着走。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { patchBoard } from '../../../projects/board-store.js';
+import { BINDING_TYPES, BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
+
+/** 词汇表渲染成工具描述里的一段表，免得两处各写各的 */
+const VOCAB = BINDING_TYPE_IDS
+  .map(id => `- ${id} (${BINDING_TYPES[id].label})${BINDING_TYPES[id].directed ? '' : ' — undirected'}`)
+  .join('\n');
+
+let seq = 0;
+const nextId = () => `b:a${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+export function makeRelateOnBoardTool({ projectId, ctx }) {
+  return tool(
+    'relate_on_board',
+    `Draw a relationship line between two things on the workbench canvas.
+
+The canvas knows *what* each artifact is, but not *how they relate*. You are
+the only one who knows that — you made them. Recording it lets the user see
+lineage at a glance, and lets layout put related things near each other.
+
+Relationship types:
+${VOCAB}
+
+Endpoints are canvas ids — a kind prefix plus the workspace-relative path,
+exactly as the file sits on disk:
+- a file: 'assets/generated/x.webp', 'notes/灵感.md'
+- a deck: 'deck:海报/proto-暖调.html'
+- a site: 'site:伊蕾娜手账研究站'
+- a folder: just its path, '海报' or '海报/初稿'
+
+Use it right after you produce something that relates to earlier work:
+- made v2 of a poster → derives-from, from the new one to the old one
+- produced two variants to compare → contrast between them
+- storyboard panels in order → flow, each to the next
+- used a reference image in a deck → ref, from the deck to the image
+
+Do NOT use it for "these are all in the same folder" — that is what the
+folder already says. Only record relationships that are not obvious from
+where the files live.`,
+    {
+      type: z.enum(BINDING_TYPE_IDS).describe('Relationship kind (see list above)'),
+      from: z.string().min(1).max(300).describe('Source canvas id — see forms above'),
+      to: z.string().min(1).max(300).describe('Target canvas id — see forms above'),
+      label: z.string().max(60).optional()
+        .describe('Optional short words on the line. Omit to use the default for the type.'),
+      material: z.enum(BINDING_MATERIALS).optional()
+        .describe('How the line is drawn (orthogonal to type): ink = quiet archive line (default); pencil = hand-drawn; yarn = detective red string with pins, for hypotheses/evidence while reasoning. The whole canvas is a detective board — use yarn when the relation is still being argued, ink when it is settled.'),
+    },
+    async ({ type, from, to, label, material }) => {
+      if (!projectId) {
+        return { content: [{ type: 'text', text: 'No project bound; cannot draw relationships.' }], isError: true };
+      }
+      if (from === to) {
+        return {
+          content: [{ type: 'text', text: 'from and to are the same thing — a relationship needs two ends.' }],
+          isError: true,
+        };
+      }
+      const id = nextId();
+      // by:'agent' 不只是记录出处 —— 用户画的线 agent 不该擅自删，反过来也一样
+      const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}), ...(material && material !== 'ink' ? { material } : {}) };
+      const board = await patchBoard(projectId, { bindings: { [id]: binding } });
+
+      // 服务端会丢掉非法的线（未知 type / 自环）。**丢了要说**，否则 agent 以为
+      // 画上了，用户看不到，两边都不知道发生了什么。
+      if (!board.bindings?.[id]) {
+        return {
+          content: [{ type: 'text', text: `Relationship rejected by the board (bad type or endpoints): ${type} ${from} -> ${to}` }],
+          isError: true,
+        };
+      }
+
+      // 广播：前端整份重拉。**sessionId 必须显式给 null** —— ctx 会把自己的
+      // sessionId 补进事件，那样只有当前会话的连接收得到，别的 tab 看不见。
+      try {
+        ctx?.emit?.({
+          type: 'board.updated',
+          sessionId: null,
+          summary: `已画一条「${BINDING_TYPES[type].label}」关系`,
+        });
+      } catch { /* emit fail-safe：广播失败不该让工具报错，线已经落盘了 */ }
+
+      const arrow = BINDING_TYPES[type].directed ? '->' : '<->';
+      return {
+        content: [{
+          type: 'text',
+          text: `Drew ${type} (${BINDING_TYPES[type].label}): ${from} ${arrow} ${to}`,
+        }],
+      };
+    },
+  );
+}

package/server/engine/mcp/tools/report-issue.js

@@ -1,115 +1,115 @@
-/**
- * mcp/tools/report-issue.js — report_issue MCP tool
- * （2026-08-02 由 report_friction 扩容改名：加 kind 轴，bug / friction / idea）
- *
- * agent 主动给维护者写信：harness 的故障（bug）、能用但绕路的摩擦（friction）、
- * 干活时冒出来的改进想法（idea）。三类走同一张 issues 表同一套指纹聚合。
- *
- * 跟自动层（PostToolUseFailure → issues 表 source='auto'）的分工：
- *   自动层记"发生了什么"——某工具失败 N 次，不依赖 agent 自觉，但指不出修法。
- *   这一层补"为什么难受、期望怎样"——一条 "screenshot 超时 12 次" 没有信息量，
- *   一条 "截长站点页时我只想要首屏，但只能 fullPage 然后自己裁" 才指向修法。
- *
- * 措辞戒律（继承自 report_friction，扩 idea 后同样适用）：
- *   - 压住"遇到困难就上报"的倾向：上报**不是**绕路的替代品，照常把活儿干完。
- *   - idea 通道要具体到可实施——"工具链很棒" 这种话没有收件人，不收。
- *   - 同类按指纹聚合累加，不是刷一万条重复。
- */
-
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { recordIssue, signatureOf } from '../../../lib/issues-store.js';
-import { getProject } from '../../../projects/store.js';
-
-/**
- * @param {object} deps
- * @param {string} [deps.projectId]
- * @param {string} [deps.sessionId]
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makeReportIssueTool({ projectId, sessionId, ctx }) {
-  return tool(
-    'report_issue',
-    `Write to the maintainer of this HARNESS — the tools and environment you work
-in. This goes to their issue list, not to the user. Three kinds:
-
-- "bug": something in the harness behaved WRONGLY — a tool crashed on valid
-  input, returned corrupt output, or contradicted its own description.
-- "friction": it worked, but the path was painful — a missing parameter, a
-  return shape you had to fight, a workaround you have now done more than once
-  (the workaround IS the report).
-- "idea": nothing is broken, but while working you saw something the harness
-  could do better or do at all — a tool that should exist, a flag that would
-  collapse three steps into one, a default that fights real usage. The
-  maintainer reads every one of these and good ones get built — if a concrete
-  improvement occurred to you, report it rather than let it evaporate.
-
-This is NOT a substitute for doing the work. Finish the task the way you would
-have anyway — route around the problem, deliver the result — and log this on
-the side. Never report and then hand back less than you could have.
-
-Do NOT report:
-- Your own mistakes (wrong path, malformed edit) — not harness issues
-- One-off flakes that a retry fixed
-- Anything about the design work itself (that belongs in the conversation)
-- Praise or vague sentiment ("the tools are great", "X could be better
-  somehow") — a report with no actionable content is noise
-
-Be concrete. "screenshot is slow" is useless. "screenshot_canvas on a 6000px
-site page takes ~14s and returns an image too large to read, so I crop by hand
-every time; a viewportOnly flag would remove the whole detour" is actionable.`,
-    {
-      kind: z.enum(['bug', 'friction', 'idea'])
-        .describe('bug = behaved wrongly · friction = worked but painful · idea = improvement worth building'),
-      summary: z.string().min(8).max(200)
-        .describe('One line. bug/friction: what is wrong, concrete. idea: the improvement itself, not "improve X".'),
-      detail: z.string().min(20).max(3000)
-        .describe('What you were doing and what happened (bug/friction: include the workaround you used; idea: the real situation that made you want this).'),
-      // 选填（2026-08-18）：以前是必填，agent 不传就被 zod 打回 —— **信箱把上报挡在
-      // 门外**，库里有 4 次这样的失败。能提当然好，提不出来也别丢掉这条上报。
-      expectation: z.string().min(10).max(1500).optional()
-        .describe('If you can name it: bug → the correct behaviour; friction → what would remove the detour; idea → what it looks like once built and what it unlocks. Leave it out rather than padding it.'),
-      toolName: z.string().max(80).optional()
-        .describe('The tool involved, if it is about one (e.g. "mcp__nodesign__screenshot_canvas").'),
-    },
-    async ({ kind, summary, detail, expectation, toolName }) => {
-      try {
-        const rec = recordIssue({
-          source: 'agent',
-          kind,
-          toolName: toolName || null,
-          summary,
-          detail,
-          expectation,
-          projectId,
-          sessionId,
-          userId: projectId ? getProject(projectId)?.ownerId : null,
-          // 按"摘要 + 工具"归一化：同一个抱怨反复出现是累加计数，不是刷屏
-          signature: signatureOf(`${toolName || ''}|${summary}`),
-        });
-        if (!rec) {
-          return {
-            content: [{ type: 'text', text: 'Could not write the report (logged server-side). Carry on with the task.' }],
-            isError: true,
-          };
-        }
-        try {
-          ctx?.emit?.({ type: 'run.friction_reported', kind, summary, toolName: toolName || null, count: rec.count });
-        } catch { /* emit fail-safe */ }
-        return {
-          content: [{
-            type: 'text',
-            text: rec.count > 1
-              ? `Logged (this is the ${rec.count}th time this one has come up). Now carry on and finish the task.`
-              : 'Logged. Now carry on and finish the task.',
-          }],
-        };
-      } catch (err) {
-        return {
-          content: [{ type: 'text', text: `report_issue failed: ${err?.message || String(err)}` }],
-          isError: true,
-        };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/report-issue.js — report_issue MCP tool
+ * （2026-08-02 由 report_friction 扩容改名：加 kind 轴，bug / friction / idea）
+ *
+ * agent 主动给维护者写信：harness 的故障（bug）、能用但绕路的摩擦（friction）、
+ * 干活时冒出来的改进想法（idea）。三类走同一张 issues 表同一套指纹聚合。
+ *
+ * 跟自动层（PostToolUseFailure → issues 表 source='auto'）的分工：
+ *   自动层记"发生了什么"——某工具失败 N 次，不依赖 agent 自觉，但指不出修法。
+ *   这一层补"为什么难受、期望怎样"——一条 "screenshot 超时 12 次" 没有信息量，
+ *   一条 "截长站点页时我只想要首屏，但只能 fullPage 然后自己裁" 才指向修法。
+ *
+ * 措辞戒律（继承自 report_friction，扩 idea 后同样适用）：
+ *   - 压住"遇到困难就上报"的倾向：上报**不是**绕路的替代品，照常把活儿干完。
+ *   - idea 通道要具体到可实施——"工具链很棒" 这种话没有收件人，不收。
+ *   - 同类按指纹聚合累加，不是刷一万条重复。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { recordIssue, signatureOf } from '../../../lib/issues-store.js';
+import { getProject } from '../../../projects/store.js';
+
+/**
+ * @param {object} deps
+ * @param {string} [deps.projectId]
+ * @param {string} [deps.sessionId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeReportIssueTool({ projectId, sessionId, ctx }) {
+  return tool(
+    'report_issue',
+    `Write to the maintainer of this HARNESS — the tools and environment you work
+in. This goes to their issue list, not to the user. Three kinds:
+
+- "bug": something in the harness behaved WRONGLY — a tool crashed on valid
+  input, returned corrupt output, or contradicted its own description.
+- "friction": it worked, but the path was painful — a missing parameter, a
+  return shape you had to fight, a workaround you have now done more than once
+  (the workaround IS the report).
+- "idea": nothing is broken, but while working you saw something the harness
+  could do better or do at all — a tool that should exist, a flag that would
+  collapse three steps into one, a default that fights real usage. The
+  maintainer reads every one of these and good ones get built — if a concrete
+  improvement occurred to you, report it rather than let it evaporate.
+
+This is NOT a substitute for doing the work. Finish the task the way you would
+have anyway — route around the problem, deliver the result — and log this on
+the side. Never report and then hand back less than you could have.
+
+Do NOT report:
+- Your own mistakes (wrong path, malformed edit) — not harness issues
+- One-off flakes that a retry fixed
+- Anything about the design work itself (that belongs in the conversation)
+- Praise or vague sentiment ("the tools are great", "X could be better
+  somehow") — a report with no actionable content is noise
+
+Be concrete. "screenshot is slow" is useless. "screenshot_canvas on a 6000px
+site page takes ~14s and returns an image too large to read, so I crop by hand
+every time; a viewportOnly flag would remove the whole detour" is actionable.`,
+    {
+      kind: z.enum(['bug', 'friction', 'idea'])
+        .describe('bug = behaved wrongly · friction = worked but painful · idea = improvement worth building'),
+      summary: z.string().min(8).max(200)
+        .describe('One line. bug/friction: what is wrong, concrete. idea: the improvement itself, not "improve X".'),
+      detail: z.string().min(20).max(3000)
+        .describe('What you were doing and what happened (bug/friction: include the workaround you used; idea: the real situation that made you want this).'),
+      // 选填（2026-08-18）：以前是必填，agent 不传就被 zod 打回 —— **信箱把上报挡在
+      // 门外**，库里有 4 次这样的失败。能提当然好，提不出来也别丢掉这条上报。
+      expectation: z.string().min(10).max(1500).optional()
+        .describe('If you can name it: bug → the correct behaviour; friction → what would remove the detour; idea → what it looks like once built and what it unlocks. Leave it out rather than padding it.'),
+      toolName: z.string().max(80).optional()
+        .describe('The tool involved, if it is about one (e.g. "mcp__nodesign__screenshot_canvas").'),
+    },
+    async ({ kind, summary, detail, expectation, toolName }) => {
+      try {
+        const rec = recordIssue({
+          source: 'agent',
+          kind,
+          toolName: toolName || null,
+          summary,
+          detail,
+          expectation,
+          projectId,
+          sessionId,
+          userId: projectId ? getProject(projectId)?.ownerId : null,
+          // 按"摘要 + 工具"归一化：同一个抱怨反复出现是累加计数，不是刷屏
+          signature: signatureOf(`${toolName || ''}|${summary}`),
+        });
+        if (!rec) {
+          return {
+            content: [{ type: 'text', text: 'Could not write the report (logged server-side). Carry on with the task.' }],
+            isError: true,
+          };
+        }
+        try {
+          ctx?.emit?.({ type: 'run.friction_reported', kind, summary, toolName: toolName || null, count: rec.count });
+        } catch { /* emit fail-safe */ }
+        return {
+          content: [{
+            type: 'text',
+            text: rec.count > 1
+              ? `Logged (this is the ${rec.count}th time this one has come up). Now carry on and finish the task.`
+              : 'Logged. Now carry on and finish the task.',
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `report_issue failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}