@xiaobuyu/nodesign 0.0.5 → 0.0.7

package/server/engine/agent/prompts/nodesign-prelude.md

@@ -2,7 +2,7 @@
 
 本文 append 在 SDK preset `claude_code` 之后，是平台事实与硬约束。设计怎么做由 skill 讲
 （deck 看 `deskskill-engine-mini`，站点看 `site-craft`，你自己判断何时 `Skill` 加载）。
-工具用法不在这里教：胖工具（生图 / tweaks / DirectEdit 细则 / 技术参考）在你第一次用到时由系统注入。
+工具用法不在这里教：胖工具（生图 / DirectEdit 细则 / 技术参考）在你第一次用到时由系统注入。
 
 ## 不是每次对话都是设计任务
 
@@ -84,10 +84,10 @@ cwd = 这个项目的工作区，所有路径默认相对 cwd。仓库路径你
 | `canvas.template.html` | deck 起手模板，Read 后改写（加载 skill 时自动拷进来）。站点**没有**模板，从骨架和风格名自己写 |
 | `notes/` | 便利贴（见下一节） |
 | `assets/` | 上传素材 + 生成图；`assets/references/` 是逛站采回来的（palette / fonts / css / skeleton / motion json + 截图，出处在同目录 `.meta/`）。**开工前先看有没有现成的，别重复去搜**；参考图挑关键的一张 Read 看一眼再下笔。每轮开头的状态块首轮列全、之后只报新增 |
-| `.claude/agent-memory/` | `memory.md` 用户偏好档（他说"记住…"就 Read 后 Edit 追加，别覆盖）· `brand/memory.md` 风格档案（锚定风格后写：色号 / 字体链 / 版式语言 / 动效预算）· `auto/` 系统自动记的，**不要碰** |
+| `记忆/` | **你的长期记忆**（系统提示里那套 memory 机制的家）。画布可见：用户看得到每一条，也可能改过 —— 他改的算数。风格定案（色号/字体/材质/艺术方向）随手记一条 `type: project` 记忆，别等收尾 |
+| `CLAUDE.md`（根上）| **项目档案**：指引 / 风格档案 / 用户习惯三节，每次会话全文进你的上下文。放定了就不常变的东西；硬约束改动要用户点头。生长中的事实写 `记忆/` 不写这里 |
 | `.claude/skills/` `.claude/agents/` | 项目级自定义 skill / 子代理 |
 | `exports/` | export_handoff 的落点 |
-| `.claude/CLAUDE.md` | 项目指引。用户点头才写，别自作主张 |
 | `.nd/<会话id>/` | 这次对话自己的暗档案（压缩历史）。系统写，你一般不用碰 |
 
 `curl -L -o` 只能写到 cwd 底下，写别处静默失败。
@@ -127,7 +127,6 @@ index.html 直接在工作区根上的「根站」仍被识别，但**新站一
 他看得到、翻得动、也能改 —— 这不是你的私人日志，是你们俩共用的白板边角。
 
 - 一个文件 = 一张贴；`\n---\n` 分面（翻页看）；每面首行 `# 标题`。
-- **设计决策**调 `record_decision`，它追加到 `notes/决策.md` 的新一面。
 - **讨论结论 / 参考素材消化 / 接力棒**（"下次从这继续"）直接 Write `notes/<slug>.md`。
   搜索/调研的发现里值得留的也落一张 —— 你的上下文迟早压缩，贴纸不会。
 - 别当垃圾桶：一张贴讲一件事，过时的删掉（文件删了贴就下墙）。每轮注入的清单
@@ -290,7 +289,7 @@ Edit/Write canvas 后系统会自动跑一致性校验（anchor 唯一 / layout-
 出一张按时刻拼好的胶片条，缓动/过冲/硬切一张图看完，数值级判断再上 `trace_motion`，`saveVideo: true` 出 webm 给用户过目）· `screenshot_url`
 （外部 URL 截图，找视觉参考用眼睛看）· `list_pages` · `read_page` ·
 `query_elements` · `get_computed_styles` · `navigate_to_page` · `highlight` ·
-`preview_deck` · `record_decision` · `get_pending_changes` / `clear_pending_changes`
+`preview_deck` · `get_pending_changes` / `clear_pending_changes`
 
 浏览器九件（常驻）：`browser_navigate` · `browser_read` · `browser_click` ·
 `browser_screenshot` · `browser_capture` · `browser_request_help` ·
@@ -340,7 +339,7 @@ batch**，一页一个回合太慢；逛到不确定的地方（要不要进、
 所以你打开的页面是"给人看的"，别把它停在一张错误页上就走。
 
 按需先 `ToolSearch("select:mcp__nodesign__<tool>")` 拉 schema：`generate_image` ·
-`remove_background` · `web_search` · `expose_tweaks` · `export_handoff` ·
+`remove_background` · `web_search` · `export_handoff` ·
 `pin_to_board` · `relate_on_board` ·
 `read_board` · `arrange_on_board` · `create_on_board` · `organize_board` · `deliver_files` ·
 `write_on_board` · `sketch_on_board` · `edit_sketch` · `finish_sketch` · `look_at_board` · `read_user_view` ·
@@ -358,12 +357,15 @@ noobai / noobai-eps / pony=danbooru 标签，anima=自然语言，krea2=12B 审
 限制，那是谁说了算的问题：别替他判断"好不好看"，别因为自己不喜欢就重滚。
 看的成本要克制：默认清晰度扫一眼够判崩坏，别每张都 `detail:'high'`。
 
-harness 里的事用 `report_issue` 给维护者记一笔（进问题列表，不是给用户看的），
-分三类：bug（行为错了）、friction（能用但绕路，同一个坑绕了不止一次）、
-idea（没坏，但你干活时看出了更好的做法 —— 想法会被认真读，具体的会被做出来，
-别让它蒸发）。**这不是交差的替代品**：照常把活儿干完，顺手记一笔而已，别因为
-报了就少交东西。自己犯的错（路径写错、Edit 没匹配上）不算，重试一次就好的偶发
-抖动也不算，空泛的夸奖或"感觉能更好"也不算 —— 没有可实施内容的上报是噪音。
+**这套 harness 正处 beta 测试期，你就是它的一线测试员** —— harness 里的事用
+`report_issue` 给维护者记一笔（进问题列表，不是给用户看的），分三类：
+bug（行为错了）、friction（能用但绕路 —— 绕过一次就值得记，别等第二次）、
+idea（没坏，但你看出了更好的做法：该存在的工具、能合三步为一步的参数、
+以及**你自己摸出来的方法论** —— 某个套路/判断依据值得 harness 教给每个会话
+或做成自动化的，写下来）。每一条都会被认真读，具体的会被做出来；犹豫要不要
+报的时候，报。**这不是交差的替代品**：照常把活儿干完，顺手记一笔而已，别因为
+报了就少交东西。自己犯的错（路径写错、Edit 没匹配上）不算，空泛的夸奖或
+"感觉能更好"也不算 —— 没有可实施内容的上报是噪音。
 
 用户说"把这套风格留下来""以后还想这么做"时用 `crystallize_skill`：把这次探索的**判断
 依据**（为什么这个字号阶梯、他否掉了什么、这套气质在什么场合会失效）写成他自己的

package/server/engine/agent/prompts/tools/generate-image-cookbook.md

@@ -4,10 +4,9 @@
 > 注入，每 session 只注一次。SKILL.md 已含精简版核心要点，本文是深度参考。
 >
 > ⚠️ Gemini gateway 时代的参数段（imageSize / thinkingLevel / model 路由 flash-pro /
-> Image Search Grounding / PDF 文档输入 / NB2 model card 失败模式）**已整体移出本文**，
-> 存在同目录 `generate-image-cookbook.gemini-gateway.md`，不再注入。那些旋钮在当前
-> 后端上传了不报错也没效果，留在这里只会让你花心思拨一个不存在的开关。
-> `NODESIGN_IMAGE_PROVIDER=gateway` 重开时再把那份取回来。
+> Image Search Grounding / PDF 文档输入 / NB2 model card 失败模式）**已整体移出本文**
+> （那份存档 08-24 已删：全仓无引用的孤儿文件；要复活 gateway 从 git 历史里捞）。
+> 那些旋钮在当前后端上传了不报错也没效果，留在这里只会让你花心思拨一个不存在的开关。
 
 ## 前置 · 后端事实 —— 先读这节，它决定下面所有写法
 
@@ -344,6 +343,24 @@ Step 3: 给角色起名锚定（"Maya, character from Reference 1"）
 
 每次只改一处，改完再看，别一轮里改五件事。
 
+### G1. variationOf 模式 —— 系列图一致性用参数，别手写咒语
+
+上面那套 "Change only… Keep… unchanged" 的骨架，工具已经内置成结构化参数：
+
+```json
+{ "variationOf": "assets/generated/A1.png",
+  "change": "裙子换成薄荷绿短裙，长度到膝盖以上",
+  "preserve": ["pose","framing","face","hair","top","shoes"] }
+```
+
+- `variationOf` 就是编辑基底（自动成为第 1 张 reference），`change` 是唯一要动的那处，
+  `preserve` 是必须一致的方面（**省略 = 全保，最安全**）。工具会展开成完整骨架并
+  自动追加通用禁止项（不凭空加背带/发饰、缺席也要保持 —— 都是真实翻过车的）。
+- 何时用它而不是手写 § G 模板：**做系列**（换装矩阵、多页同角色、多帧同场景）。
+  组织成一棵树：先出一张锚图，之后每次调用只沿一个轴变一处。
+- 手写 prompt 仍然适合单次精修（改光线、删元素这类一次性编辑）。
+- 此模式下 `prompt` 可省略；传了就当补充说明附在骨架后。
+
 ## H. 连续帧的能力边界（实测，别重新踩）
 
 | 用法 | 结果 |
@@ -390,9 +407,9 @@ Step 3: 给角色起名锚定（"Maya, character from Reference 1"）
 
 ## J. 调完必做
 
-1. **`record_decision`** —— 把 prompt + role + path + 用户评价记进任务便利贴
-   （`notes/决策.md`）。重生时能查回，用户在画布上也看得到。
-   ⚠️ 入参是 `title`（必填）/ `rationale`（必填）/ `scope` / `alternatives`，**没有 `topic`**。
+1. **记进记忆** —— 定案的 anchor（prompt 骨架 + role + 产物路径 + 用户评价）写一条
+   `type: project` 记忆（`记忆/` 主题文件 + MEMORY.md 一行）。重生时能查回，
+   用户在画布上也看得到。
 2. **关键节点的反馈循环**：cover / 第一个 portrait / logo 嵌入这种会被当跨页种子的 anchor，
    生完在自然回话里邀请用户看一眼方向（生图的 image block 已自动渲染在 chat，他直接看得到）。
    种子早定早收益。

package/server/engine/agent/prompts/tools/site-reference.md

@@ -21,12 +21,22 @@
 
 （旧项目里工作区根上直接放 index.html 的「根站」仍被识别和支持，但**新站一律入夹**。）
 
-**构建型站点**（Astro / 11ty / 自写 build 脚本）：源随便组织，构建产物落
-`dist/`（或 `out/` `build/` `_site/`，有 index.html 的那个自动被认作**产物根**；
-也可在 `.nd-project.json` 加 `"root": "<目录>"` 显式指定）。预览、截图、`list_pages`、
+**构建型站点**（Vite / React / Vue / Astro / 11ty / 自写 build 脚本）：源随便组织，
+构建产物落 `dist/`（或 `out/` `build/` `_site/` `public/`，有 index.html 的那个自动
+被认作**产物根**）。现代工程源码里的 `index.html`（引 `/src/main.tsx` 那种 dev 入口）
+**不会**被误当产物 —— 构建完系统自动优先 dist。`.nd-project.json` 的 `"root": "<目录>"`
+可显式指定产物根：**放站点文件夹里，路径相对该文件夹**（如 `观察日志/.nd-project.json`
+写 `{"root":"dist"}`）；根站的放工作区根。预览、截图、`list_pages`、
 导出、发布看的**全是产物根** —— 改完源必须重新构建，否则用户看到的还是旧的。
+构建必须用绝对路径或 `(cd <站点文件夹> && npm run build)` 子 shell 跑，**build 完
+`ls` 确认产物真的落在了站点文件夹里的 dist/**（cwd 漂了会把 dist 建到别处）。
 `node_modules` / 构建缓存系统永远不扫，不用进 .ndignore。
 
+WebGL/Three.js（含 R3F）的一个静默坑：渲染器属性（如剖切要的
+`localClippingEnabled`）传给 `<Canvas gl={{…}}>` 构造参数会被**静默忽略**（无报错
+无效果），要在 `onCreated={({gl}) => { gl.localClippingEnabled = true }}` 里设；
+`clippingPlanes` 裁掉的是法线**负**侧，"看起来没剖"先怀疑法线方向。
+
 手写起手：`mkdir 观察日志`，然后 Write `观察日志/index.html`（文件夹名换成真站名；
 没有起手模板，骨架从需求推、样式从风格名推）。**唯一硬要求是产物根上有 `index.html`**；
 样式文件怎么拆怎么叫你定，按站的体量来。

package/server/engine/agent/session-loop.js

@@ -54,6 +54,7 @@ import {
 import { loadInstalledPlugins } from './plugin-loader.js';
 import { createHooks } from './hooks.js';
 import { buildIsolationOptions, prepareAgentDirs, sandboxShimEnv } from './isolation.js';
+import { MEMORY_EXTRA_GUIDELINES, mergeAgentSettings } from './memory-config.js';
 import { createNodesignMcpServer } from '../mcp/index.js';
 import { assertInitContract } from './init-contract.js';
 import { createAgents, resolveDefaultFastModel } from '../agents/index.js';
@@ -329,8 +330,21 @@ export async function runSession({
   // npm 缓存 + 沙盒可写 tmp（$TMPDIR / pip 缓存）：细节与教训见 isolation.js
   const agentDirs = await prepareAgentDirs({ dataRoot: PROJECTS_DATA_ROOT, projectId, sessionId });
 
+  // ⛔ 服务器自己的运行姿态不许漏进 agent 环境（08-24 案）：
+  //   - NODE_ENV=production（pm2 注的）会让 agent 沙盒里的 npm install 静默跳过
+  //     devDependencies —— 返回 0 还报 "up to date"，vite/typescript 根本没装上，
+  //     构建道当场断。npm_config_production / npm_config_omit 是同一开关的旁路。
+  //   - PWD 是 pm2 进程的 cwd（仓库根）；spawn({cwd}) 不更新它，bash 会自校正但
+  //     python/node/构建工具读 $PWD 拿到的就是错目录 ——"cwd 被重置到父目录"的
+  //     另一半病根。下面显式钉成 cwdRoot。
+  const {
+    NODE_ENV: _dropNodeEnv, npm_config_production: _dropNpmProd,
+    npm_config_omit: _dropNpmOmit, OLDPWD: _dropOldpwd,
+    ...inheritedEnv
+  } = process.env;
   const sdkEnv = {
-    ...process.env,
+    ...inheritedEnv,
+    PWD: cwdRoot,
     ANTHROPIC_BASE_URL: baseUrlForBinary,
     // 订阅模型：apiKeyForBinary = process.env 原值（通常 undefined）——binary 见到
     // ANTHROPIC_API_KEY 会弃用 ~/.claude 订阅 OAuth，所以订阅路绝不能注入。
@@ -341,6 +355,8 @@ export async function runSession({
     // auto-memory 强制开启分支（binary gate：DISABLE 置 falsy 值 = force on，
     // 绕过 CLAUDE_CODE_SIMPLE 等后置门；前置门 U$/zl 若拦住则此招无效 → 走自建 B 计划）
     CLAUDE_CODE_DISABLE_AUTO_MEMORY: '0',
+    // 记忆指导追加段（保留 SDK 原合同只追加产品口径，理由见 memory-config.js）
+    CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES: MEMORY_EXTRA_GUIDELINES,
     // 工具搜索：非 alwaysLoad 的 MCP 工具延迟加载（省 ~25-30k 常驻 schema tokens），
     // agent 用 ToolSearch 按需取。白名单见 mcp/index.js ALWAYS_LOAD_TOOLS
     ENABLE_TOOL_SEARCH: 'true',
@@ -530,22 +546,6 @@ export async function runSession({
     persistSession: true,
     settingSources: ['project'],
 
-    // skipWebFetchPreflight 来自 runtime/platform.js（gateway key 模式永远关）
-    // 详细因果链见 platform.js 的 skipWebFetchPreflight 注释
-    settings: {
-      skipWebFetchPreflight: platform.skipWebFetchPreflight,
-      // 项目 memory（2026-07-28 正式启用）：骑 SDK 原生 auto-memory ——
-      // 二级索引（MEMORY.md 常驻 + 主题文件按需召回）、召回监督器
-      // （run.memory_recall 前端已渲染）、auto-dream 后台固化全由 SDK 包办。
-      // ⚠️ 目录必须显式指到项目共享区：默认按 cwd 派生，而 cwd 是会话级的，
-      // 不指定则每个会话一座记忆孤岛；指定后全项目所有会话共享一套。
-      ...(sharedRoot ? {
-        autoMemoryEnabled: true,
-        // 落在 .claude/agent-memory/auto —— 跟前端记忆卡读的是同一棵树
-        // （2026-07-28 修：之前指到 shared/agent-memory/auto，SDK 记了前端也看不到）
-        autoMemoryDirectory: path.join(sharedRoot, '.claude', 'agent-memory', 'auto'),
-      } : {}),
-    },
 
     includePartialMessages: STREAMING_ENABLED,
     // 子代理时间轴（2026-07-28）：转发子代理完整对话（text/thinking 也带
@@ -582,7 +582,18 @@ export async function runSession({
 
     // 隔离两道闸（sandbox 管 Bash，permissions.deny 管 Read/Write 这类进程内工具）
     // 全在 agent/isolation.js 里，改之前读那份文件头上的四条实测教训。
-    ...buildIsolationOptions({ cwdRoot, sharedRoot, ...agentDirs, dataRoot: PROJECTS_DATA_ROOT, env: sdkEnv }),
+    // ⛔ settings 必须与 isolationOptions.settings 深合并 —— 08-15 起两处 settings
+    // 静默互吞八天（autoMemory*/skipWebFetchPreflight 全丢）。合并+出口断言在
+    // memory-config.js 的 mergeAgentSettings。
+    ...(() => {
+      const isolation = buildIsolationOptions({ cwdRoot, sharedRoot, ...agentDirs, dataRoot: PROJECTS_DATA_ROOT, env: sdkEnv });
+      return {
+        ...isolation,
+        settings: mergeAgentSettings(isolation.settings, {
+          skipWebFetchPreflight: platform.skipWebFetchPreflight, sharedRoot,
+        }),
+      };
+    })(),
 
     toolConfig: {
       askUserQuestion: { previewFormat: 'html' },

package/server/engine/agents/explorer.md

@@ -44,7 +44,7 @@
 - `Read` / `Glob` / `Grep` —— 看本地 `./assets/` 里的素材 / `./spec.json` 决策档案
 - `TodoWrite` —— 3 步以上研究列计划
 
-**工具集外的工具**（用了也无效，且打破子代理边界）：Write / Edit / Bash / screenshot_canvas / export / record_decision /
+**工具集外的工具**（用了也无效，且打破子代理边界）：Write / Edit / Bash / screenshot_canvas / export /
 AskUserQuestion —— 你的产物是信息不是修改，跟用户对话由主 agent 负责。研究就是研究。
 
 ---

package/server/engine/agents/index.js

@@ -137,7 +137,7 @@ export function createAgents({ mainModel, sdkModel, fastModel } = {}) {
     //   - TodoWrite（多步研究列计划）
     // 不给：Write/Edit（不写代码）/ Bash（不要 shell shenanigans）/
     //       AskUserQuestion（子代理不直接跟用户说话）/ screenshot/export/
-    //       record_decision（不是它的角色）/ Task（不允许嵌套子代理）
+    //       Task（不允许嵌套子代理）
     // ⏸ explorer 研究员（2026-08-14 用户暂时停用："有点没用"）。定义与
     // prompt（explorer.md）原样保留，恢复 = 取消注释 + prelude 补回子代理
     // 清单那两行。停用期间搜索/读外链由主 agent 直接用 web_search / WebFetch。

package/server/engine/mcp/index.js

@@ -10,7 +10,7 @@
  *   反馈层（用户在 canvas 上的直接编辑 + 评论 buffer）：
  *     get_pending_changes / clear_pending_changes
  *   产物层（NoDesign 差异化能力）：
- *     expose_tweaks / export_handoff / record_decision
+ *     export_handoff …（expose_tweaks 08-24 暂退役待升级；record_decision 08-24 拆除，记忆体系接棒）
  *   研究层：
  *     web_search（4 provider，CJK auto baidu）
  *
@@ -33,7 +33,6 @@ import { withCapabilityGate } from './capability-gate.js';
 import { makeScreenshotCanvasTool } from './tools/screenshot.js';
 import { makeScreenshotUrlTool } from './tools/screenshot-url.js';
 import { makeExportHandoffTool } from './tools/export-handoff.js';
-import { makeRecordDecisionTool } from './tools/record-decision.js';
 import { makeWebSearchTool } from './tools/web-search.js';
 import { withTierGate } from './tools/tier-gate.js';   // 档位闸包装器（auth/tier.js；按项目 owner）
 import { makeReadPageTool } from './tools/read-page.js';
@@ -55,7 +54,7 @@ import { makeNavigateToPageTool } from './tools/navigate-to-page.js';
 import { makeHighlightTool } from './tools/highlight.js';
 import { makePreviewDeckTool } from './tools/preview-deck.js';
 import { makeBuildDocxTool } from './tools/build-docx.js';
-import { makeExposeTweaksTool } from './tools/expose-tweaks.js';
+// expose-tweaks 08-24 暂退役（能力不足待升级再加回）：本体与前端 TweaksPanel 留档休眠，不注册
 import { makeGetPendingChangesTool } from './tools/get-pending-changes.js';
 import { makeClearPendingChangesTool } from './tools/clear-pending-changes.js';
 import { makeGenerateImageTool } from './tools/generate-image.js';
@@ -103,7 +102,7 @@ import { makeLookupTagsTool } from './tools/lookup-tags.js';
 const ALWAYS_LOAD_TOOLS = new Set([
   'screenshot_canvas', 'read_page', 'list_pages', 'query_elements',
   'get_computed_styles', 'navigate_to_page', 'highlight', 'preview_deck',
-  'record_decision', 'get_pending_changes', 'clear_pending_changes',
+  'get_pending_changes', 'clear_pending_changes',
   // screenshot_url 常驻：explorer 显式 tools 列表没有 ToolSearch，defer 了它就
   // 永远拉不到 schema；schema 本身很小（4 字段），常驻成本可忽略
   'screenshot_url',
@@ -182,9 +181,6 @@ export function createNodesignMcpServer({ workspaceRoot, sharedRoot, projectId,
       // C10 export_handoff — 复用 exports.js 的 buildHandoffZip，写到 workspace/exports/
       makeExportHandoffTool({ workspaceRoot, sharedRoot, projectId, sessionId, ctx }),
 
-      // C11 record_decision — 写入 spec.json decisions[] 设计意图档案
-      makeRecordDecisionTool({ workspaceRoot, sessionId, ctx }),
-
       // crystallize_skill — 把探索出来的方法论固化成用户自己的 skill + 作品进橱窗
       // （2026-07-30）。用户明确要求才调；写的是判断依据不是成品 HTML。
       makeCrystallizeSkillTool({ projectId, sessionId, ctx }),
@@ -284,9 +280,6 @@ export function createNodesignMcpServer({ workspaceRoot, sharedRoot, projectId,
       makeGetPendingChangesTool({ workspaceRoot, ctx }),
       makeClearPendingChangesTool({ workspaceRoot, ctx }),
 
-      // Tweaks 协议：agent 暴露 deck 专属可调参数 schema → 前端按 schema 渲染控件
-      makeExposeTweaksTool({ workspaceRoot, ctx }),
-
       // 图片生成（gemini-3.1-flash-image-preview / Nano Banana 2，via NoDesk passthrough）
       // 落档优先 sharedRoot/assets/generated/，fallback workspaceRoot/assets/generated/。
       // 跨 session 共享靠 sessions/<sid>/assets softlink → shared/assets。
@@ -304,7 +297,7 @@ export function createNodesignMcpServer({ workspaceRoot, sharedRoot, projectId,
       // 关系线（2026-08-07）：agent 把「这版改自那版」「这两个是对照」这类
       // **只有它知道**的关系画到画布上。画布知道每个产物是什么，但不知道它们
       // 之间是什么关系 —— 那是北极星（排出有版面感的布局）真正缺的那一块。
-      makeRelateOnBoardTool({ projectId, ctx }),
+      makeRelateOnBoardTool({ sharedRoot, projectId, ctx }),
       // agent 摆位四件（2026-08-14）：看版面 / 语义摆位·立主角 / 落手写便签 / 归纳收纳
       makeReadBoardTool({ projectId }),
       makeArrangeOnBoardTool({ projectId, ctx }),

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

@@ -90,7 +90,9 @@ drag things afterwards — their move wins, do not fight it.`,
       if (subjectEntry) {
         const subjectLayer = layerOf(subject, subjectEntry, known);
         if (subjectLayer !== anchorLayer) {
-          return err(`不同层（${subjectLayer || '根'} vs ${anchorLayer || '根'}）：先 mv 文件到同一个文件夹，画布跟着走。`);
+          return err(`不同层（${subjectLayer || '根'} vs ${anchorLayer || '根'}）：摆位只在同一层内有意义。`
+            + '要摆到一起：先把文件放进同一个文件夹（assets/ 里的素材用 cp 复制过去 —— 母版别挪走）；'
+            + '只是想表达"相关"，用 relate_on_board 连一条线更合适。');
         }
       }
 

package/server/engine/mcp/tools/browse-computer.js

@@ -179,7 +179,8 @@ async function zoomShot(page, region, frame, lead) {
   }
   const [x0, y0, x1, y1] = region.map(Math.round);
   if (x0 < 0 || y0 < 0 || x1 > frame.w || y1 > frame.h || x1 - x0 < 8 || y1 - y0 < 8) {
-    return asText(`Error: zoom region [${region.join(', ')}] must lie inside the ${frame.w}×${frame.h} screenshot and be at least 8×8.`, true);
+    return asText(`Error: zoom region [${region.join(', ')}] must lie inside the ${frame.w}×${frame.h} LIVE VIEWPORT and be at least 8×8. `
+      + 'zoom takes viewport pixels — coordinates from a fullPage screenshot are in page space and do NOT work here; scroll the target into view first, or subtract the scroll offset.', true);
   }
   const clip = { x: toPage(x0, frame), y: toPage(y0, frame), width: toPage(x1 - x0, frame), height: toPage(y1 - y0, frame) };
   const buf = await page.screenshot({ type: 'png', clip });

package/server/engine/mcp/tools/browse-find-batch.js

@@ -104,6 +104,7 @@ export function makeBatchTool({ name, description, tools, batchable, finalShot }
       const out = [];
       const n = actions.length;
       let failedAt = -1;
+      let failText = '';
       let lastHadImage = false;
       for (let i = 0; i < n; i += 1) {
         const { name: toolName, input } = actions[i];
@@ -112,14 +113,16 @@ export function makeBatchTool({ name, description, tools, batchable, finalShot }
         const def = byName.get(toolName);
         if (!def) {
           failedAt = i;
-          out.push({ type: 'text', text: `${label}: Error: "${toolName}" is not batchable here (use one of ${names.join(', ')}).` });
+          failText = `"${toolName}" is not batchable here (use one of ${names.join(', ')}).`;
+          out.push({ type: 'text', text: `${label}: Error: ${failText}` });
           continue;
         }
         const parsed = z.object(def.inputSchema).safeParse(input || {});
         if (!parsed.success) {
           failedAt = i;
           const why = parsed.error.issues.map(is => `${is.path.join('.') || '(root)'}: ${is.message}`).join('; ');
-          out.push({ type: 'text', text: `${label}: Error: invalid input — ${why}` });
+          failText = `invalid input — ${why}`;
+          out.push({ type: 'text', text: `${label}: Error: ${failText}` });
           continue;
         }
         let r;
@@ -135,7 +138,21 @@ export function makeBatchTool({ name, description, tools, batchable, finalShot }
           if (b.type === 'text' && !prefixed) { out.push({ type: 'text', text: `${label}: ${b.text}` }); prefixed = true; }
           else out.push(b);
         }
-        if (r?.isError) failedAt = i;
+        if (r?.isError) {
+          failedAt = i;
+          failText = blocks.find(b => b.type === 'text')?.text || '(no error text)';
+        }
+      }
+      // 失败时把错误行提到最前面：下游（记账层截 120/500 字符、模型扫返回）都先看到
+      // 真正的报错，而不是前面成功步骤的输出。同时钉死"别整批重跑"——前面的步骤
+      // （click/type 这类非幂等动作）已经执行过了。
+      if (failedAt >= 0) {
+        const step = actions[failedAt];
+        out.unshift({
+          type: 'text',
+          text: `FAILED at step ${failedAt + 1}/${n} (${step.name}${step.input?.action ? ` ${step.input.action}` : ''}): ${String(failText).split('\n')[0]}\n`
+            + `Steps 1-${failedAt} already ran — do NOT re-run the whole batch; continue from the failed step.`,
+        });
       }
       if (finalShot && screenshotAfter !== false && !lastHadImage) {
         const shotDef = byName.get(finalShot.name);

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

@@ -121,7 +121,7 @@ and reopens on the next call — the profile survives, so you stay logged in.
 The user has a browser card on their desktop and can watch, or take over.`,
     {
       url: z.string().min(4).describe('Absolute http(s) URL.'),
-      waitUntil: z.enum(['domcontentloaded', 'load', 'networkidle']).optional()
+      waitUntil: z.enum(['commit', 'domcontentloaded', 'load', 'networkidle']).optional()
         .describe("How long to wait. Default 'domcontentloaded' — fastest and enough to read; measured on this machine, 'networkidle' costs an extra 1.6-4s per page, so do not reach for it by reflex. Use it only when a JS-built page comes back empty."),
       digest: z.boolean().optional()
         .describe('Include the page digest (default true). Set false only when you are navigating purely to screenshot and do not want the text.'),
@@ -175,9 +175,31 @@ The user has a browser card on their desktop and can watch, or take over.`,
             ].filter(Boolean).join('\n'), true);
           }
           if (navErr) {
+            // 超时 ≠ 全失败：commit 之后页面往往已有内容。半张页面也交回去 ——
+            // agent 拿到骨架就能决定继续还是换站（08-19 上报：原建议「试
+            // waitUntil:"load"」是往错方向推 —— load 比 domcontentloaded 严，
+            // 连 DOMContentLoaded 都没到换 load 只会更慢地再失败一次）
+            const timedOut = /Timeout/i.test(navErr);
+            let landedUrl = null;
+            try { const u = page.url(); if (timedOut && u !== before && /^https?:/.test(u)) landedUrl = u; } catch { /* */ }
+            if (landedUrl) {
+              let lines = [];
+              try {
+                const data = await collectPage(page);
+                if (!data.missing) lines = formatPage(data, { compact: true });
+              } catch { /* 半张页面读不出摘要也照样交回 */ }
+              try { ctx?.emit?.({ type: 'run.browser_opened', url: landedUrl, ts: new Date().toISOString() }); } catch { /* */ }
+              return asText([
+                `⚠️ 等待超时（${navErr}），但页面已部分加载 —— 当前状态如下，够用就继续（read/screenshot 都可），不够就换站：`,
+                ...lines,
+                gate,
+              ].filter(Boolean).join('\n'));
+            }
             return asText([
               `导航失败：${navErr}`,
-              '如果是超时：站点可能慢或者在挡自动化访问；试 waitUntil:"load"，或者换一个参考站。',
+              timedOut
+                ? '超时多半是广告/追踪脚本卡死或站点反自动化，不是"等得不够久"。别换 waitUntil:"load"（更严只会更慢地失败）；可试 waitUntil:"commit"（一有响应就接手，配 read/screenshot 看拿到多少），或者直接换一个参考站。'
+                : '站点可能在挡自动化访问；换一个参考站。',
               gate,
             ].filter(Boolean).join('\n'), true);
           }

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

@@ -9,7 +9,7 @@
  * （~/.nodesign/plugins/<userId>/<name>/），下次开新会话在**这个用户的所有项目**里
  * 都能用（plugin 发现是 startup-time，当前会话不生效）。
  *
- * 跟 record_decision 的分工：决策贴是**这一件作品**的过程档案，随任务走；
+ * 跟长期记忆（记忆/ + 根 CLAUDE.md）的分工：记忆记的是**这个项目/这位用户**的持续状态，随项目走；
  * 这里是跨项目复用的方法论，随用户走。一个是日志，一个是沉淀。
  *
  * 归属：写到**项目 owner** 的目录，不是"当前请求者"——同一个项目谁跑都该产出同一

package/server/engine/mcp/tools/generate-image.js

@@ -41,7 +41,6 @@
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { spawn } from 'node:child_process';
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { Events } from '../../agent/events.js';
 import { z } from 'zod';
@@ -49,6 +48,9 @@ import sharp from 'sharp';
 import {
   THUMBNAIL_MAX_DIM, THUMBNAIL_QUALITY, writeWebpSibling,   // 预热由 writeWebpSibling 顺带做
 } from '../../../lib/image-variant.js';
+import {
+  buildCodexBridgePrompt, runCodexImageGen, buildVariationPrompt, PRESERVE_KEYS,
+} from './helpers/codex-imagegen.js';
 
 // Thumbnail 配置（env 可调）。**原图不动**——保留 Gemini 输出的全分辨率（通常
 // 1080×1920+ PNG，6-8MB）让用户最终交付不损失质量。仅生成低清 thumbnail 给
@@ -136,71 +138,9 @@ const DEFAULT_DMXAPI_BASE = 'https://www.dmxapi.cn';
 const DEFAULT_CHANNEL = 'DMX';
 
 // ── codex 生图桥（2026-07-27：NoDesk 网关退役，codex 成为默认 provider）──
-// 骑 codex CLI 订阅（零 API 费）：spawn `codex exec` 让它调自带图像生成工具，
-// 图直接落到我们指定的绝对路径。实测单张 ~45-60s，参考图走 -i 附件（同样实测
-// 风格参照有效）。桥接 prompt 必须写死"逐字传递零改写"——codex agent 默认会
-// 按自己的 Augmentation rules 润色 prompt。
+// 桥的 prompt 组装 + 子进程执行 + 变体模式骨架都在 helpers/codex-imagegen.js
+// （2026-08-24 迁出）。这里只留 provider 分流开关。
 const IMAGE_PROVIDER = () => (process.env.NODESIGN_IMAGE_PROVIDER || 'codex').toLowerCase();
-const CODEX_BIN = process.env.NODESIGN_CODEX_BIN || 'codex';
-const CODEX_IMAGE_TIMEOUT_MS = Number(process.env.NODESIGN_CODEX_IMAGE_TIMEOUT_MS) || 240_000;
-
-function buildCodexBridgePrompt({ prompt, aspectRatio, absOut, refCount }) {
-  return [
-    '你是图像生成管道的执行端，只做下面几件事，不做任何多余动作：',
-    '1. 调用你的图像生成工具生成一张图。<image-prompt> 标签内的内容必须逐字作为生成 prompt，禁止改写、增删、翻译或润色。',
-    `2. 输出比例：${aspectRatio}。优先用工具的比例/尺寸参数；工具没有对应参数时，作为补充说明传给工具，但不修改 <image-prompt> 原文。`,
-    refCount > 0
-      ? `3. 本消息附带 ${refCount} 张参考图，把它们作为图像生成的参考输入（风格 / 主体一致性参照）。`
-      : '3. 本次无参考图。',
-    `4. 生成后把图片文件复制到精确路径 ${absOut}（目录已存在）。`,
-    '5. 最后只回复该绝对路径。',
-    '<image-prompt>',
-    prompt,
-    '</image-prompt>',
-  ].join('\n');
-}
-
-/**
- * 跑一次 codex exec 生图，以目标文件落盘为成功标准（codex 的文本回复不可信），
- * 失败自动重试一次。abort signal / 超时都 SIGKILL 子进程。
- */
-async function runCodexImageGen({ bridgePrompt, refPaths, cwd, signal, expectFile, timeoutMs = CODEX_IMAGE_TIMEOUT_MS }) {
-  const args = ['exec', '--skip-git-repo-check', '-s', 'workspace-write', '-C', cwd, bridgePrompt];
-  for (const p of refPaths) args.push('-i', p);
-
-  const runOnce = () => new Promise((resolve, reject) => {
-    const child = spawn(CODEX_BIN, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
-    let stderrTail = '';
-    child.stdout.on('data', () => { /* 排空防背压 */ });
-    child.stderr.on('data', (d) => { stderrTail = (stderrTail + d.toString()).slice(-2000); });
-    const killTimer = setTimeout(() => {
-      try { child.kill('SIGKILL'); } catch { /* */ }
-      reject(new Error(`codex exec timeout after ${Math.round(timeoutMs / 1000)}s`));
-    }, timeoutMs);
-    const onAbort = () => { try { child.kill('SIGKILL'); } catch { /* */ } };
-    signal?.addEventListener?.('abort', onAbort, { once: true });
-    child.on('error', (err) => { clearTimeout(killTimer); reject(err); });
-    child.on('close', (code) => {
-      clearTimeout(killTimer);
-      signal?.removeEventListener?.('abort', onAbort);
-      if (signal?.aborted) return reject(new Error('aborted'));
-      if (code !== 0) return reject(new Error(`codex exec exited ${code}: ${stderrTail.slice(-300) || 'no stderr'}`));
-      resolve();
-    });
-  });
-
-  for (let attempt = 1; attempt <= 2; attempt++) {
-    try {
-      await runOnce();
-      const st = await fs.stat(expectFile).catch(() => null);
-      if (st && st.size > 0) return;
-      throw new Error(`codex finished but target file missing/empty: ${expectFile}`);
-    } catch (err) {
-      if (attempt === 2 || signal?.aborted) throw err;
-      console.warn(`[generate-image] codex attempt ${attempt} failed (${err.message}), retrying once`);
-    }
-  }
-}
 
 const PASSTHROUGH_PATH = '/default/passthrough';
 // model id 在 callGateway 时动态拼，因为支持 flash / pro 路由
@@ -413,6 +353,15 @@ REFERENCES:
   conversation. To iterate on a previous image, pass it back in referenceImages
   and restate the invariants every round.
 
+VARIATION MODE (series consistency — outfit swaps, one-detail edits):
+  Instead of hand-writing "change only X, keep Y" prompts, pass
+  variationOf (path of the base image) + change (the ONE thing to alter)
+  + optional preserve (which aspects must stay identical; default all).
+  The tool expands these into a battle-tested skeleton incl. standard
+  prohibitions (no invented straps/ornaments, absences preserved). Build
+  series as a tree: one anchor, then vary one axis per call. In this mode
+  prompt is optional (used as extra notes).
+
 WHEN TO USE:
   - You're building a deck / landing / report and want real imagery
   - You need a backdrop that pure CSS gradient can't achieve
@@ -424,15 +373,29 @@ WHEN NOT TO USE:
   - Data charts — use Recharts/ECharts/Mermaid via React mount
   - Simple inline icons (≤5 per page) — use lucide-react inline SVG
 
-ALWAYS pair generation with mcp__nodesign__record_decision so the prompt + role
-land on the shared decision sticky (notes/decisions). Its params are title +
-rationale (both required), scope, alternatives — there is no "topic" param.`,
+After a generation that settles style direction, record the settled anchor as a
+memory (记忆/, type: project) so later sessions inherit it.`,
     {
       prompt: z
         .string()
         .min(4)
         .max(3500)
-        .describe('Natural-language scene description. Describe, don\'t list keywords.'),
+        .optional()
+        .describe('Natural-language scene description. Describe, don\'t list keywords. Required unless variationOf is set (then it is appended as extra notes).'),
+      variationOf: z
+        .string()
+        .optional()
+        .describe('VARIATION MODE: workspace-relative path of the base image to reproduce with ONE change. Becomes the first reference image (edit target).'),
+      change: z
+        .string()
+        .min(4)
+        .max(500)
+        .optional()
+        .describe('VARIATION MODE: the single thing to alter, e.g. "裙子换成薄荷绿短裙，长度到膝盖以上". Required with variationOf.'),
+      preserve: z
+        .array(z.enum(PRESERVE_KEYS))
+        .optional()
+        .describe('VARIATION MODE: aspects that must stay identical. Omit = all of them (safest).'),
       aspectRatio: z
         .enum(ASPECT_RATIOS)
         .optional()
@@ -476,6 +439,9 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
     },
     async ({
       prompt,
+      variationOf,
+      change,
+      preserve,
       aspectRatio = '16:9',
       imageSize = '1K',
       referenceImages,
@@ -496,6 +462,19 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
           isError: true,
         };
       }
+      // 变体模式归一化：variationOf 只是 referenceImages[0] 的语义化别名，
+      // prompt 换成固定骨架 —— 下游（ref 解析 / -i 附件 / gateway inline）零改动。
+      const isVariation = Boolean(variationOf);
+      if (isVariation && !change) {
+        return { content: [{ type: 'text', text: 'generate_image failed: variationOf requires `change` (the ONE thing to alter).' }], isError: true };
+      }
+      if (!isVariation && !prompt) {
+        return { content: [{ type: 'text', text: 'generate_image failed: `prompt` is required (or use variationOf + change).' }], isError: true };
+      }
+      if (isVariation) {
+        prompt = buildVariationPrompt({ change, preserve, extra: prompt });
+        referenceImages = [variationOf, ...(referenceImages || [])];
+      }
       // 1. provider 分流（2026-07-27：NoDesk 网关退役，默认 codex 订阅生图；
       //    gateway 分支保留给显式 NODESIGN_IMAGE_PROVIDER=gateway 的场景）
       const provider = IMAGE_PROVIDER();
@@ -550,7 +529,7 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
         fileName = `${finalName}.png`;
         absOut = path.join(outDir, fileName);
         const bridgePrompt = buildCodexBridgePrompt({
-          prompt, aspectRatio, absOut, refCount: resolvedRefs.length,
+          prompt, aspectRatio, absOut, refCount: resolvedRefs.length, variation: isVariation,
         });
         try {
           await runCodexImageGen({
@@ -706,6 +685,7 @@ rationale (both required), scope, alternatives — there is no "topic" param.`,
           provider,
           model: provider === 'codex' ? 'codex' : model,
           referenceImageCount: resolvedRefs.length,
+          variationOf: variationOf || null,   // 变体血缘：产物墙 / 引用层能顺出系列树
           sessionId: ctx?.sessionId || null,
           runId: ctx?.runId || null,
           ts: new Date().toISOString(),