@xiaobuyu/nodesign 0.0.5 → 0.0.7

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

@@ -31,18 +31,24 @@ 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:
+in. This goes to their issue list, not to the user.
+
+This harness is in BETA and you are one of its primary testers: the maintainer
+actively wants these reports and reads every one. When you hesitate between
+reporting and not reporting — report. 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).
+  return shape you had to fight, a workaround (one detour is enough to report;
+  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.
+  collapse three steps into one, a default that fights real usage, or a
+  METHODOLOGY you worked out on the job (a technique, a judgment rule, a
+  sequence that reliably works) that the harness should teach every session,
+  bake into a skill, or automate. Good ones get built — 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
@@ -50,7 +56,8 @@ 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
+- A one-off flake that a single retry fixed (the automatic layer counts those);
+  a flake that RECURS is friction — report it
 - 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

package/server/engine/mcp/tools/screenshot.js

@@ -19,7 +19,7 @@ import { can } from '../../../lib/kinds/index.js';
 import { screenshotDocx } from './screenshot-docx.js';
 import { SITE_DEVICE_W } from './helpers/perception-page.js';
 import { acquireArtifactPage, LIVE_PARAM_DESC } from './helpers/acquire-page.js';
-import { normalizeShot, detectPaintTransform, attachPageDiagnostics, runWaitFor, runBeforeShot } from './helpers/shot-pipeline.js';
+import { normalizeShot, detectPaintTransform, attachPageDiagnostics, runWaitFor, runBeforeShot, shotWithFallback, longPageSheet, clipShotWithFallback } from './helpers/shot-pipeline.js';
 import { recordMotion, pickNearestFrames, composeSheet, encodeWebm, motionCaptionLines } from './helpers/motion-lab.js';
 import { wheelScroll, elementMotionReport, elementMotionLines } from './helpers/motion-scroll.js';
 
@@ -428,6 +428,8 @@ Do NOT use this tool when:
         // （系统 fit script 包 frame + scroll-snap），locator.screenshot 自动
         // 拿目标 section 的 bbox，不需要再操作 DOM。
         let buf;
+        let shotDegraded = false;
+        let longPageNote = null;
         let captureMode;
         const targetSelector = selector
           || (pageIndex ? `section[data-page="${pageIndex}"]` : null);
@@ -476,13 +478,19 @@ Do NOT use this tool when:
           };
           clip.width = Math.max(1, Math.min(rect.width, rect.docW - clip.x));
           clip.height = Math.max(1, Math.min(rect.height, rect.docH - clip.y));
-          buf = await page.screenshot({ fullPage: true, clip, type: 'png' });
+          ({ buf, degraded: shotDegraded } = await clipShotWithFallback(page, { clip, selector: targetSelector }));
           captureMode = `selector="${targetSelector}"`;
         } else {
-          buf = await page.screenshot({ fullPage: fp, type: 'png' });
-          captureMode = isSite
-            ? `site ${device || 'desktop'} ${vp.width}px, fullPage=${fp}`
-            : `fullPage=${fp}`;
+          // 超长页 fullPage → 滚动联络表（阈值与理由见 shot-pipeline.longPageSheet）
+          const sheet = fp ? await longPageSheet(page).catch(() => null) : null;
+          if (sheet) {
+            buf = sheet.buf; captureMode = sheet.mode; longPageNote = sheet.note;
+          } else {
+            ({ buf, degraded: shotDegraded } = await shotWithFallback(page, { fullPage: fp, type: 'png' }));
+            captureMode = isSite
+              ? `site ${device || 'desktop'} ${vp.width}px, fullPage=${fp}`
+              : `fullPage=${fp}`;
+          }
         }
         // live 页的 DPR 是会话的（1），detail:'normal' 的 0.6 光栅在这里事后缩
         if (acq.live && rasterScale < 1) {
@@ -537,7 +545,9 @@ Do NOT use this tool when:
         const shot = await normalizeShot(buf);
 
         const captionParts = [
-          `Screenshot of ${target.relPath} (layout ${vp.width}x${vp.height} @${rasterScale}x raster, ${captureMode})`,
+          `Screenshot of ${target.relPath} (layout ${vp.width}x${vp.height} @${rasterScale}x raster, ${captureMode})`
+          + (shotDegraded ? '（常规截图等稳定帧超时——页面在持续动画（WebGL/rAF），已改抓当前帧：画面是真实的某一瞬间，动画中间态属正常）' : '')
+          + (longPageNote ? `（${longPageNote}）` : ''),
         ];
         // 加载通道写进 caption：agent 不用再靠"把 location.protocol 写进 DOM 再截一张"
         // 去反推自己被什么方式打开了（问题库 iss_msxk2oci_0v0v 就是这么查了四轮）

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

@@ -19,10 +19,11 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard, patchBoard, commitStaging, removeByTag, TEXT_FONTS } from '../../../projects/board-store.js';
 import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
-import { layerOf, normalizeCanvasId } from '../../../lib/canvas-id.js';
+import { layerOf, normalizeCanvasId, tagEnvelope } from '../../../lib/canvas-id.js';
 import { BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
 import { UNIT, SKETCH_FIT, SKETCH_MAX, textBox, shapePath, layoutNodes, bboxOf, findSpot, fitFor } from '../../../lib/sketch-layout.js';
 import { getViewpoint } from '../../../projects/viewpoint-store.js';
+import { Events } from '../../agent/events.js';
 
 const MAX_NODES = 40;
 const MAX_SHAPES = 30;
@@ -248,9 +249,16 @@ Per sketch: ≤${MAX_NODES} nodes, ${MAX_SHAPES} shapes, ${MAX_EDGES} edges (spl
       if (args.near) {
         const nid = normalizeCanvasId(args.near);
         const e = nid ? board.objects?.[nid] : null;
-        if (!e || !Number.isFinite(e.x)) return err(`锚点 ${args.near} 还没有座位（read_board 里看不到就锚不上）。`);
-        zone = layerOf(nid, e, known);
-        anchor = { x: e.x, y: e.y, ...estimateSizeOn(after, nid, e) };
+        if (e && Number.isFinite(e.x)) {
+          zone = layerOf(nid, e, known);
+          anchor = { x: e.x, y: e.y, ...estimateSizeOn(after, nid, e) };
+        } else {
+          // near 也认 tag（08-23 案，同 write_on_board）
+          const env = tagEnvelope(board, args.near, (id2, e2) => estimateSizeOn(after, id2, e2));
+          if (!env) return err(`锚点 ${args.near} 还没有座位，也不是板上任何 tag（read_board 里看不到就锚不上）。`);
+          zone = layerOf(env.anchorId, board.objects[env.anchorId], known);
+          anchor = { x: env.x, y: env.y, w: env.w, h: env.h };
+        }
       }
       const obstacles = [];
       let contentBottom = 0;
@@ -293,7 +301,7 @@ Per sketch: ≤${MAX_NODES} nodes, ${MAX_SHAPES} shapes, ${MAX_EDGES} edges (spl
       try {
         ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `画了一张草图 #${tag}` });
         // 镜头提示（前端只在黑板模式跟随；不是劫持，是"黑板是主窗口"的约定）
-        ctx?.emit?.({ type: 'board.focus', sessionId: null, tag, rect: world, layer: zone });
+        ctx?.emit?.(Events.boardFocus(world, { tag, layer: zone }));
       } catch { /* fail-soft */ }
       const lines = [
         `Sketch #${tag} landed${staging ? ' as STAGING (半透明)' : ''}: ${Object.keys(objects).length - shapes.length} nodes, ${shapes.length} shapes, ${Object.keys(bindings).length} lines; layout ${tpl}; at world (${world.x},${world.y}) ${world.w}x${world.h}${anchor ? ` (${spot.side} of ${args.near})` : ' (below current content)'}.`,

package/server/engine/mcp/tools/web-search.js

@@ -393,6 +393,7 @@ Suggested flow for image-led pages:
         //    - 普通模式：tavily/exa/baidu/zhipu auto-route by language（CJK→baidu, EN→tavily）
         //    - include_images：zhipu 不支持图，从候选中剔除；其余按语言 auto-route
         let providerId;
+        let providerNote = '';
         if (include_images) {
           if (provider === 'zhipu') {
             return {
@@ -418,15 +419,13 @@ Suggested flow for image-led pages:
               };
             }
           } else {
+            // 点名的 provider 没配 key：换配了的顶上别硬失败（结果>供应商身份，iss_mt5z4s8j）
             providerId = provider;
             if (!getKey(providerId)) {
-              return {
-                content: [{
-                  type: 'text',
-                  text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set in .env.`,
-                }],
-                isError: true,
-              };
+              const alt = ((looksChinese(query) ? PRIORITY_CJK : PRIORITY_NON_CJK).filter(id => id !== 'zhipu')).find(id => getKey(id)) || null;
+              if (!alt) return { content: [{ type: 'text', text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set, and no other image-capable provider configured.` }], isError: true };
+              providerNote = `（provider "${provider}" 没配 key，已换用 ${alt}）`;
+              providerId = alt;
             }
           }
         } else {
@@ -443,13 +442,10 @@ Suggested flow for image-led pages:
             };
           }
           if (!getKey(providerId)) {
-            return {
-              content: [{
-                type: 'text',
-                text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set in .env.`,
-              }],
-              isError: true,
-            };
+            const alt = autoSelectProvider(query);   // 只挑配了 key 的
+            if (!alt || !getKey(alt)) return { content: [{ type: 'text', text: `web_search failed: ${PROVIDERS[providerId].keyEnv} not set, and no other provider configured.` }], isError: true };
+            providerNote = `（provider "${providerId}" 没配 key，已换用 ${alt}）`;
+            providerId = alt;
           }
         }
 
@@ -518,7 +514,7 @@ Suggested flow for image-led pages:
         // count 张 + base64 体积。已在上一步通过 count 截断控量。
         const out = [{
           type: 'text',
-          text: formatMarkdown(query, providerId, hits, { images: downloadedImages }),
+          text: `${providerNote ? `${providerNote}\n` : ''}${formatMarkdown(query, providerId, hits, { images: downloadedImages })}`,
         }];
         for (const img of downloadedImages) {
           if (img.base64) {

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

@@ -17,10 +17,11 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard, patchBoard } from '../../../projects/board-store.js';
 import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
-import { layerOf, normalizeCanvasId } from '../../../lib/canvas-id.js';
+import { layerOf, normalizeCanvasId, tagEnvelope } from '../../../lib/canvas-id.js';
 import { textBox, findSpot, SKETCH_FIT } from '../../../lib/sketch-layout.js';
 import { getViewpoint } from '../../../projects/viewpoint-store.js';
 import { renderChalk, chalkFileName, writeChalkFile, CHALK_DIR } from '../../../lib/chalk.js';
+import { Events } from '../../agent/events.js';
 
 let seq = 0;
 const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
@@ -91,10 +92,17 @@ Keep the chat reply short — a line pointing at the board is enough.`,
       } else if (near) {
         const nid = normalizeCanvasId(near);
         const e = nid ? board.objects?.[nid] : null;
-        if (!e || !Number.isFinite(e.x)) return err(`锚点 ${near} 还没有座位（read_board 里看不到就锚不上）。`);
-        anchorId = nid; zone = layerOf(nid, e, known);
-        const as = estimateSizeOn(board, nid, e);
-        pos = avoid({ x: e.x + as.w + 24, y: e.y }, obstaclesOf(zone), box.w, box.h);
+        if (e && Number.isFinite(e.x)) {
+          anchorId = nid; zone = layerOf(nid, e, known);
+          const as = estimateSizeOn(board, nid, e);
+          pos = avoid({ x: e.x + as.w + 24, y: e.y }, obstaclesOf(zone), box.w, box.h);
+        } else {
+          // near 也认 tag（08-23 案）：落到那片东西的包络右侧，锚线连最右那个
+          const env = tagEnvelope(board, near, (id2, e2) => estimateSizeOn(board, id2, e2));
+          if (!env) return err(`锚点 ${near} 还没有座位，也不是板上任何 tag（read_board 里看不到就锚不上）。`);
+          anchorId = env.anchorId; zone = layerOf(env.anchorId, board.objects[env.anchorId], known);
+          pos = avoid({ x: env.x + env.w + 24, y: env.y }, obstaclesOf(zone), box.w, box.h);
+        }
       } else {
         const obstacles = obstaclesOf('');
         let bottom = 0; for (const o of obstacles) bottom = Math.max(bottom, o.y + o.h);
@@ -118,7 +126,8 @@ Keep the chat reply short — a line pointing at the board is enough.`,
       const rect = { x: Math.round(pos.x), y: Math.round(pos.y), w: box.w, h: box.h };
       try {
         ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: parentId ? '回了一条板书' : '写了一条板书' });
-        ctx?.emit?.({ type: 'board.focus', sessionId: null, tag: tag || null, rect, layer: zone, soft: true, chalk: rel });
+        // chalk 字段进精灵追踪链（08-24）：形状钉在 Events.boardFocus，别再内联对象
+        ctx?.emit?.(Events.boardFocus(rect, { tag: tag || null, layer: zone, soft: true, chalk: rel }));
       } catch { /* */ }
       const big = box.h > SKETCH_FIT.h * 0.6;
       return { content: [{ type: 'text', text:

package/server/engine/plugins/nodesign/skills/deskskill-engine-mini/SKILL.md

@@ -116,10 +116,9 @@ IP、角色、真人、某个具体产品型号、小众品牌 —— 那种情
 用户点头之后，把这一份固化下来，它就是后面所有页的基准：
 
 - `<style id="design-tokens">` 的 `:root` 整组写死（色号、字号、字体链）
-- `record_decision` 落锚：`title` **名字打头**（`风格锚 = 拼贴`），取值写进 `rationale`
-  （"纸纹底 + 微旋转 + 白边 + 手写体标注 + 一点樱桃红"）。⚠️ 入参是 title / rationale
-  （都必填）/ scope / alternatives，**没有 `topic`**
-- 风格锚定之后顺手更新 `agent-memory/brand/memory.md`（风格档案），参照图留在
+- 落锚进长期记忆：写一条 `type: project` 记忆（名字打头，如「风格锚 = 拼贴」，
+  取值写进正文："纸纹底 + 微旋转 + 白边 + 手写体标注 + 一点樱桃红"）；项目级
+  定案还该进根 `CLAUDE.md` 的「风格档案」节（用户点头后）。参照图留在
   `assets/references/` 别删 —— 后面几页跑偏时靠它回锚
 
 锚说不出名字，说明还没定下来，回去再试一轮。

package/server/engine/plugins/nodesign/skills/docx-craft/SKILL.md

@@ -38,6 +38,13 @@ docx 的版式谱系跟网页不是一套，常用的这些：
 | 简历 / 投递 | **单页履历体** | 窄边距、姓名区大字号、条目左对齐悬挂缩进、零装饰 |
 | 手册 / 说明书 | **技术文档体** | 编号标题、等宽代码块、表格密排 |
 
+⚠️ 公文体的坑（实测反馈，08-21 案）：严格国标的三级标题**同缩进、纯换字体**
+（黑/楷/仿宋），而预览的替身字体会吃掉楷体与仿宋的对比度 —— 三级在预览里几乎
+不可辨，用户大概率抱怨"层级看不出来"。两条路先问一句：a) 严格国标（对方单位
+真按 9704 收文时用）；b) **层级强化变体**（用户没点名国标就默认它）——
+Heading1 加 `spacing.beforePt: 8`、Heading2 加 `indent.leftChars: 200` + `bold: true`，
+层级立刻一眼可辨且不破坏 exact 行距的页数稳定性。
+
 内置词典条目有三个（`build_docx` 的 `preset`）：`办公标准` / `公文` / `学术论文`。
 **它们是起点不是菜单** —— 上表其余的用 preset 起手再覆写 tokens，或者干脆不写
 preset 给完整 token 表。自造词作废（"科技感文档"不是版式名），但凡是真实存在、
@@ -60,7 +67,9 @@ preset 给完整 token 表。自造词作废（"科技感文档"不是版式名
 新旧并排），⛔ 别覆盖旧版 —— 版本是给用户看的，不是给你腾地方的。
 
 起手文件 `文档.template.json` 已经拷进工作区了 —— 照着它改，别从空白开始。
-**字段全集 Read `references/token-schema.md`** —— 键名、值域、单位、块的形状、
+**字段全集 Read `references/token-schema.md`**（⚠️ 相对**本 SKILL 文件所在目录**，
+不相对工作区 —— 用加载本 skill 时给出的 SKILL.md 路径拼出绝对路径去 Read，
+别在工作区里找、更别 find / 全盘扫）—— 键名、值域、单位、块的形状、
 常见错法对照全在那里，别靠猜，也别去读引擎源码。
 
 **schema 是闭合的**：写了没登记过的字段名，`build_docx` 直接报错。这是故意的 ——

package/server/engine/plugins/nodesign/skills/docx-craft/references/token-schema.md

@@ -262,6 +262,22 @@
 写成 `"para": {...}` **会被拒**（2026-08-18 起 content 和页眉页脚都过闭合校验）。
 在那之前它是"不报错也不生效"——最难发现的一类错，起手模板自己教错过一次。
 
+⭐ **对象型键（`spacing` / `indent` / `borders`）与样式里的同名键是属性级深合并**，
+跟 tokens 对 preset 的合并规则一致：引擎只把你写的属性写进这一段的 pPr，
+没写的属性照常从样式继承（OOXML 的属性级联就是这个粒度；2026-08-24 真渲染
+实测证实——样式 `line:10/lineRule:"exact"` 的段，块级只写 `beforePt:30`，
+行距不掉）：
+
+```jsonc
+{ "t": "p", "style": "要点", "spacing": { "beforePt": 3 } }
+// ✅ 只多 3pt 段前距；样式里的 line/lineRule 原样保留，不必重抄
+```
+
+唯一的例外是 `indent`：`firstLine*` 和 `hanging*` 互斥（见上），而深合并抹不掉
+从样式继承来的属性——所以"样式带首行缩进的段想改成悬挂"**不要**靠块级开小灶
+（继承的 firstLine 还在，两个属性并存后哪个生效随渲染器），正路是给这类段落
+单独立一个不带首行缩进的样式。
+
 ### `{"t": "table"}` 表格
 
 ```jsonc

package/server/engine/plugins/nodesign/skills/site-craft/SKILL.md

@@ -125,10 +125,10 @@ IP、角色、真人、某个具体产品型号、小众品牌 —— 那种情
   2-4 个带小样的候选，不是一张风格大全。摊开菜单就退回模板思维了。
 
 他已经点了名字（"我要拼贴风"）的，跳过前两步直接进试作；直接甩了参考图的，
-读图读出那是什么风格、跟他确认一下名字，再进试作。名字定下来之后调 `record_decision` 落锚：`title` 名字打头
-（`风格锚 = 拼贴`），取值写进 `rationale`；⚠️ 入参是 title / rationale（都必填）/
-scope / alternatives，**没有 `topic`**。参照图留在 `assets/references/` 别删 ——
-铺到第五页跑偏时靠它回锚。
+读图读出那是什么风格、跟他确认一下名字，再进试作。名字定下来之后落锚进长期
+记忆（一条 `type: project` 记忆，名字打头如「风格锚 = 拼贴」，取值写进正文）；
+项目级定案经用户点头后进根 `CLAUDE.md` 的「风格档案」节。参照图留在
+`assets/references/` 别删 —— 铺到第五页跑偏时靠它回锚。
 
 ### 翻译词典 —— 你的词汇量，不是给用户的菜单
 

package/server/index.js

@@ -33,7 +33,6 @@ import turnRouter from './api/turn.js';
 import exportsRouter from './api/exports.js';
 import sessionsRouter from './api/sessions.js';
 import instructionRouter from './api/instruction.js';
-import memoryRouter from './api/memory.js';
 import boardRouter from './api/board.js';
 import pendingChangesRouter from './api/pending-changes.js';
 import browseRouter from './api/browse.js';
@@ -118,7 +117,6 @@ app.use('/api/projects', turnRouter);
 app.use('/api/projects', exportsRouter);
 app.use('/api/projects', sessionsRouter);
 app.use('/api/projects', instructionRouter);
-app.use('/api/projects', memoryRouter);
 app.use('/api/projects', boardRouter);
 app.use('/api/projects', pendingChangesRouter);  // C4: 用户直接编辑 + 评论 buffer
 app.use('/api/projects', browseRouter);          // 刷新后拿回浏览器窗/求助状态

package/server/lib/artifact-target.js

@@ -95,7 +95,10 @@ export function clearActiveArtifact(sessionId) {
 }
 
 function normalizeRel(p) {
-  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+  // 尾部 ?query / #hash 一并剥掉：agent 常把预览 URL 原样拿来当 path
+  //（'dist/index.html?t=18&panel=0' 落 not found，08-24 清账两案）。
+  // 磁盘文件名里合法出现 ? # 的场景在这套产物约定里不存在。
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '').replace(/[?#].*$/, '');
 }
 
 async function exists(p) {
@@ -108,13 +111,9 @@ function insideWorkspace(workspaceRoot, absPath) {
   return absPath === root || absPath.startsWith(root + path.sep);
 }
 
-/**
- * 站点的页面清单（相对产物根）。
- */
-export async function listSitePages(workspaceRoot) {
-  const m = await KINDS[KIND_SITE].manifest(workspaceRoot, null);
-  return m.pages;
-}
+// （listSitePages 2026-08-24 拆除：调用 KINDS.site.manifest 这个不存在的方法，
+//  一调必 TypeError，全仓无调用方 —— 死代码假装公开 API。页面清单读
+//  taskManifest().artifacts[].pages。）
 
 /**
  * 推断某个 html 路径的产物形态。
@@ -209,11 +208,28 @@ export async function resolveArtifactTarget(workspaceRoot, relPath, sessionId) {
     const hit = await tryPath(relPath);
     if (hit) { setActiveArtifact(sessionId, hit.relPath, hit.kind); return hit; }
     const abs = path.resolve(workspaceRoot, relPath);
+    if (!insideWorkspace(workspaceRoot, abs)) return { ok: false, message: 'path escapes workspace' };
+    // 回退：agent 常拿**产物根相对**或**源目录相对**路径来喂（'index.html'、
+    // 'dist/index.html'），而这里收的是工作区相对（'jet-engine/dist/index.html'）。
+    // 没命中时按各站点实例的 root / srcRoot 补前缀再试一轮，省一次注定失败的
+    // 往返（08-24 案：三个工具三种写法全 not found）。
+    const m = await taskManifest(workspaceRoot);
+    const rel = normalizeRel(relPath);
+    const prefixes = new Set();
+    for (const a of (m?.artifacts || [])) {
+      if (a.kind !== KIND_SITE || a.single) continue;
+      if (a.root) prefixes.add(a.root);
+      if (a.srcRoot && a.srcRoot !== a.root) prefixes.add(a.srcRoot);
+    }
+    for (const pre of prefixes) {
+      const hit2 = await tryPath(`${pre}/${rel}`);
+      if (hit2) { setActiveArtifact(sessionId, hit2.relPath, hit2.kind); return hit2; }
+    }
+    const candidates = (m?.artifacts || []).map(a => a.entryRel).filter(Boolean);
     return {
       ok: false,
-      message: insideWorkspace(workspaceRoot, abs)
-        ? `${relPath} not found. Write it first, or check the path.`
-        : 'path escapes workspace',
+      message: `${relPath} not found. Write it first, or check the path (workspace-relative).`
+        + (candidates.length ? `\nExisting artifact entries:\n${candidates.map(c => `- ${c}`).join('\n')}` : ''),
     };
   }
 
@@ -272,9 +288,10 @@ export function requireBrowsable(target) {
 
 /** 给各工具复用的 path 参数描述（保持措辞一致） */
 export const ARTIFACT_PATH_DESC =
-  'Relative path of the artifact entry (deck: "canvas.html", site: "index.html" '
-  + 'or its built output like "dist/index.html", word: "文档.docx"). '
-  + 'Omit to use the artifact you are currently working on.';
+  'WORKSPACE-relative path of the artifact entry (deck: "canvas.html", '
+  + 'root site: "index.html" or "dist/index.html", site in a folder: full path '
+  + 'like "my-site/dist/index.html", word: "文档.docx"). All artifact tools share '
+  + 'this one convention. Omit to use the artifact you are currently working on.';
 
 // ── 兼容层：老名字继续可用，内部全部走上面的实现 ────────────────────────────
 export const CANVAS_PATH_DESC = ARTIFACT_PATH_DESC;

package/server/lib/board-kind-sizes.js

@@ -19,7 +19,6 @@ export const ARTIFACT_PREVIEW_H = { deck: 360, site: 400, docx: 420, browse: 360
 // file 是 224x32 的细条卡（parity 测试上岗第一天就逮住我猜成 160x120 ——
 // 那是涂鸦的默认身位。别猜，抄表）
 export const KIND_SIZES = {
-  doc: { w: 200, h: 96 },
   image: { w: 200, h: 176 },
   video: { w: 240, h: 160 },
   note: { w: 200, h: 148 },
@@ -44,7 +43,6 @@ export function estimateSize(id, entry) {
     return { w: entry.w, h: entry.h };
   }
   const s = String(id || '');
-  if (s.startsWith('doc:')) return KIND_SIZES.doc;
   // 浏览器卡是**单例**，id 就是 'browse'（没有路径可挂 —— 它背后不是文件）。
   // 不给这条分支的话它会掉到最后的 file 兜底（224×32 的细条），agent 摆位时
   // 就会拿一个错的矩形去算"挨着谁摆、会不会压到谁"。
@@ -58,7 +56,8 @@ export function estimateSize(id, entry) {
   }
   if (IMG_EXT.test(s)) return KIND_SIZES.image;
   if (VIDEO_EXT.test(s)) return KIND_SIZES.video;
-  if (/\.(md|txt)$/i.test(s)) return KIND_SIZES.note;
+  // 文本类文件卡带内容预览（08-24：md/json 等升级出预览体），身位=note
+  if (/\.(md|markdown|txt|json|csv|ya?ml)$/i.test(s)) return KIND_SIZES.note;
   return KIND_SIZES.file;
 }
 

package/server/lib/canvas-id.js

@@ -10,21 +10,46 @@
 export function normalizeCanvasId(raw) {
   let id = String(raw || '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
   if (!id || id.includes('..')) return null;
-  if (id.endsWith('agent-memory/brand/memory.md')) return 'doc:brand';
-  if (id.endsWith('agent-memory/memory.md')) return 'doc:_root';
+  // （doc:brand / doc:_root 映射 2026-08-24 拆除：项目文档并进根 CLAUDE.md，
+  //   记忆住 记忆/，都是普通画布文件，没有特殊 id 了）
   if (!/^(deck|site|doc|text|scribble):/.test(id) && /\.html?$/i.test(id)) return `deck:${id}`;
   return id;
 }
 
+/**
+ * 一个 tag 下所有座位的包络（08-23 案：near 只认节点 id 不认 tag，可 tag 本来
+ * 就是"一片东西的名字"——刚用 tag 画完草图，把 tag 传给 near 是自然写法）。
+ * 返回 { x, y, w, h, anchorId, ids } 或 null；anchorId = 最右那个（贴右侧摆用）。
+ * sizeOf(id, entry) 由调用方给（estimateSizeOn 绑着 board，不在这层 import）。
+ */
+export function tagEnvelope(board, tag, sizeOf) {
+  const hits = Object.entries(board?.objects || {})
+    .filter(([, e]) => e?.tag === tag && Number.isFinite(e?.x));
+  if (!hits.length) return null;
+  let x1 = Infinity; let y1 = Infinity; let x2 = -Infinity; let y2 = -Infinity;
+  let anchorId = null; let rightEdge = -Infinity;
+  for (const [id, e] of hits) {
+    const s = sizeOf(id, e) || { w: 0, h: 0 };
+    x1 = Math.min(x1, e.x); y1 = Math.min(y1, e.y);
+    x2 = Math.max(x2, e.x + s.w); y2 = Math.max(y2, e.y + s.h);
+    if (e.x + s.w > rightEdge) { rightEdge = e.x + s.w; anchorId = id; }
+  }
+  return { x: x1, y: y1, w: x2 - x1, h: y2 - y1, anchorId, ids: hits.map(([id]) => id) };
+}
+
 /**
  * 它住在哪一层（服务端近似版）：显式 zone 字段优先，其次沿路径往上找第一个
  * 已知文件夹。已知集 = board.zones 的 key —— 比前端少了"服务端扫出来的任务
  * 目录"这一路，没摆过的深层目录会归到根。read_board 的输出里写明这是近似。
  */
 export function layerOf(id, entry, knownFolders) {
-  if (entry && typeof entry.zone === 'string') return entry.zone;
+  // 显式 zone 只认**真实存在的层**（'' 或 zones 里有的文件夹）。历史上
+  // pin_to_board 往 zone 里写过 'assets/generated' 这类前端根本不当层渲染的
+  // 路径（iss_mt5t487g：pin 上来的图被判在"assets 层"，arrange 跟根层的草图
+  // 节点一比就拒）——错标签直接落回按路径推，存量脏数据顺带自愈。
+  if (entry && typeof entry.zone === 'string'
+    && (entry.zone === '' || knownFolders?.has?.(entry.zone))) return entry.zone;
   const s = String(id);
-  if (s.startsWith('doc:')) return '';
   const c = s.indexOf(':');
   const p = (c > 0 && /^[a-z]+$/.test(s.slice(0, c))) ? s.slice(c + 1) : s;
   let d = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '';

package/server/lib/export-collect.js

@@ -145,7 +145,9 @@ export async function collectCard({ workspaceRoot, cardId }) {
     const m = await taskManifest(workspaceRoot).catch(() => null);
     const rootSite = (m?.artifacts || []).find(a => a.kind === 'site' && !a.single && !a.srcRoot);
     for (const pg of (rootSite?.pages || [])) {
-      const pRel = String(pg).replace(/\\/g, '/');
+      // ⚠️ pages 是**产物根相对**（构建型根站 root='dist' 时是 'index.html' 不是
+      // 'dist/index.html'）——对着工作区根解析会抓到源文件或落空（08-24 对齐）
+      const pRel = (rootSite.root ? `${rootSite.root}/` : '') + String(pg).replace(/\\/g, '/');
       const pAbs = await safeResolve(workspaceRoot, pRel);
       if (!pAbs) continue;
       try { if ((await fs.stat(pAbs)).isFile()) files.push({ abs: pAbs, rel: pRel }); } catch { /* 页面刚被删 */ }

package/server/lib/issues-store.js

@@ -59,7 +59,9 @@ db.exec(`
  */
 export function signatureOf(text) {
   const norm = String(text || '')
-    .replace(/[/~][\w.\-/@ 一-鿿]+/g, '<path>')   // 路径
+    // 字符类里不能有空格：不然一个孤立的 "/" 会贪婪吞掉后面一整串词（08-24 案，
+    // artifact_find 输出里的 "→ https://…" 之后的文字被不定长吃掉，指纹漂移不聚合）
+    .replace(/[/~][\w.\-/@一-鿿]+/g, '<path>')    // 路径
     .replace(/\b[0-9a-f]{8,}\b/gi, '<hash>')      // id / hash
     .replace(/\d+/g, 'N')                          // 行号、字节数、耗时
     .replace(/\s+/g, ' ')

package/server/lib/kinds/docx.js

@@ -264,16 +264,23 @@ export default {
   async describe(taskDir, artifact) {
     const label = `word ${artifact.entryRel}`;
     const src = artifact.sourceFile;
+    // 文件夹里的**全部**成员都要点名（08-19 案：目录里 v3/v4 两份，清单只报
+    // 默认那份，agent 对着过时的 v3 干了一整轮 —— 注入的清单让人默认它是全的，
+    // 半份状态比没状态更误导）
+    const others = (artifact.members || [])
+      .map(m => m.file)
+      .filter(f => f && f !== artifact.entryRel);
+    const memberNote = others.length ? ` · 同夹还有：${others.join(' / ')}` : '';
     try {
       const stat = await fs.stat(path.join(taskDir, artifact.entryRel));
       const kb = (stat.size / 1024).toFixed(0);
       return src
-        ? `${label} · ${kb}KB · 源 ${src}（改源重建，别直接改 .docx）`
-        : `${label} · ${kb}KB · 外来文档，没有 token 源`;
+        ? `${label} · ${kb}KB · 源 ${src}（改源重建，别直接改 .docx）${memberNote}`
+        : `${label} · ${kb}KB · 外来文档，没有 token 源${memberNote}`;
     } catch {
       return src
-        ? `${label} · 还没构建（源 ${src} 已就位）`
-        : `${label} · 入口读不到`;
+        ? `${label} · 还没构建（源 ${src} 已就位）${memberNote}`
+        : `${label} · 入口读不到${memberNote}`;
     }
   },
 

package/server/lib/kinds/index.js

@@ -30,7 +30,9 @@ import docx from './docx.js';
 
 export const KINDS = Object.freeze({ [deck.id]: deck, [site.id]: site, [docx.id]: docx });
 
-export { RESERVED_DIRS, isReservedFile } from '../task-scan.js';
+import { readTaskMarker } from '../task-scan.js';
+
+export { RESERVED_DIRS, isReservedFile, readTaskMarker } from '../task-scan.js';
 
 export function kindDef(kind) {
   return KINDS[kind] || null;
@@ -57,21 +59,9 @@ export function can(kind, cap) {
   return !!KINDS[kind]?.capabilities?.includes(cap);
 }
 
-/**
- * 读产物标记（`.nd-project.json`）。没有 / 读不动 → null。
- *
- * 2026-08-07 从 `.nd-task.json` 改名。旧文件里有两个字段：`sessionId`（这个
- * 任务属于哪次对话 —— 正是要废的那条绑定，迁移时直接删）和 `root`（构建型
- * 站点显式声明产物根，agent 刚写完源还没 build 的窗口期靠它认出"站已经在了"）。
- * 后者还有用，所以标记本身留着，只是不再承载归属。
- */
-export async function readTaskMarker(root) {
-  try {
-    const raw = await fs.readFile(path.join(root, '.nd-project.json'), 'utf8');
-    const parsed = JSON.parse(raw);
-    return (parsed && typeof parsed === 'object') ? parsed : null;
-  } catch { return null; }
-}
+// readTaskMarker 本体 2026-08-24 迁去 task-scan.js（site.js 要按子目录读 marker，
+// 住这里会循环 import）。上面 re-export 保住老调用方。历史注释一并搬走：
+// `.nd-project.json` 2026-08-07 从 `.nd-task.json` 改名，只剩 `root` 字段有用。
 
 /**
  * 任务的完整 manifest —— 服务端唯一的解析器，前端、感知工具、导出都吃这份。