@xiaobuyu/nodesign 0.0.1

package/server/engine/agent/hooks/pre-injectors.js

@@ -0,0 +1,277 @@
+/**
+ * PreToolUse 首调注入族 —— 各工具的 reference 文档 / 起手提醒，agent 首次调
+ * 对应工具时才进 context（不放系统 prompt 恒驻，每 turn 拖累）。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * 共同模式：closure 里一个 alreadyInjected 布尔（或 per-kind Set），每 session
+ * 只注一次；permissionDecision='allow' 不阻塞工具。
+ */
+import path from 'node:path';
+import { toWorkspaceRel } from '../../../lib/workspace-path.js';
+import { kindOfPath, kindDef, KIND_DECK } from '../../../lib/artifact-target.js';
+import { loadToolPrompt } from './tool-prompts.js';
+
+/**
+ * PreToolUse(get_pending_changes) — 第一次调用时注入 DirectEdit 逐 kind
+ * 处理协议全文（字段结构 / pending-move 语义 / 邻居保护 / preDragLayout /
+ * constraint anchor 表）。prelude 常驻部分只留流程骨架 + 语义底线三条，
+ * ~90 行细则在 agent 真的要处理 pending changes 时才进 context。
+ */
+export function makePreToolUseGetPendingChangesProtocolInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const protocol = loadToolPrompt('direct-edit-protocol');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[DirectEdit 逐 kind 处理协议 — 首次注入]\n\n'
+        + protocol
+        + '\n\n本协议每 session 只注入一次，后续处理 pending changes 直接按它做。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(AskUserQuestion) — 第一次问用户时注入 NoDesign 的问法协议
+ * （何时用卡片 vs chat、schema、写选项的诀窍、preview 字段的两种形态与限制）。
+ * 常驻在 prelude 里是 1.2k tokens，但一次会话里可能一次都用不上。
+ */
+export function makePreToolUseAskUserQuestionProtocolInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const protocol = loadToolPrompt('ask-user-question-protocol');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[AskUserQuestion 协议 — 首次注入]\n\n'
+        + protocol
+        + '\n\n本协议每 session 只注入一次，后续问用户直接按它写。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(Write) — 第一次写 .html 时注入该形态的技术参考。
+ *
+ * 2026-07-28 加站点后按 kind 分流：以前是"任何 .html 都注入 hybrid deck 参考"，
+ * 于是 agent 写站点首页时会被塞一份讲 `data-page` / `__nd-deck-wrap` / babel 的
+ * 文档 —— 文不对题，还会诱导它往站点里塞 deck 专属结构。
+ *
+ * 两种形态各注一次（一个会话理论上只做一种，但试作阶段可能先摸另一种）。
+ */
+export function makePreToolUseHybridReferenceInjector({ workspaceRoot } = {}) {
+  const injected = new Set();
+  return async (input, _toolUseId, _options) => {
+    const fp = input?.tool_input?.file_path;
+    if (typeof fp !== 'string') return {};
+    const rel = workspaceRoot ? toWorkspaceRel(fp, workspaceRoot) : fp;
+    const kind = workspaceRoot ? await kindOfPath(workspaceRoot, rel) : KIND_DECK;
+    // 触发条件从「写 .html」改成「写的文件跟这个形态的入口同类型」（2026-08-01）。
+    // 写死 .html 的年代只有 deck 和 site，两者入口都是 html 所以恰好没错；非 html 入口的形态
+    // 的入口不是 .html，于是它的技术参考**永远不会被注入**，agent 一辈子不知道
+    // 目录结构该长什么样。扩展名从注册表的 entryFile 推，加形态不用再回来改。
+    const wantExt = path.extname(kindDef(kind)?.entryFile || '.html').toLowerCase();
+    if (path.extname(fp).toLowerCase() !== wantExt) return {};
+    if (injected.has(kind)) return {};
+    injected.add(kind);
+    // 技术参考按注册表分发（kinds/<kind>.referenceDoc）—— 新形态自带自己那份
+    const meta = kindDef(kind)?.referenceDoc || kindDef(KIND_DECK).referenceDoc;
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          `<system-reminder>\n[${meta.title} — 首次注入]\n\n`
+        + loadToolPrompt(meta.file)
+        + '\n\n本参考每 session 每形态只注入一次。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+// paint_still 首调注入本地生图手册：四模型选型 + noobai 标签流 + FLUX.2 官方
+// 提示词实践（BFL prompting guide 摘要）+ 装卸税排序纪律。
+export function makePreToolUsePaintStillCookbookInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const cookbook = loadToolPrompt('paint-still-cookbook');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[paint_still 本地生图手册 — 首次注入]\n\n'
+        + cookbook
+        + '\n\n本手册每 session 只注入一次，后续调用直接照用。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+// roll_film 首调注入 H3 提示词手册：三字段格式 + 多镜纪律（逐字角色块/同种子）
+// + 禁视觉检查。模式与 generate_image cookbook 完全同款。
+export function makePreToolUseRollFilmCookbookInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const cookbook = loadToolPrompt('roll-film-cookbook');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[roll_film H3 提示词手册 — 首次注入]\n\n'
+        + cookbook
+        + '\n\n本手册每 session 只注入一次，后续调用直接照用。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(generate_image) — 第一次调用时注 完整 cookbook（A-J 段）。
+ *
+ * 配套 SKILL.md 里的精简版 cookbook（5 元素公式 + 渲文字铁律 + 反例正例）保第一张
+ * 图质量底线；本 hook 注入完整深度内容，让第二张起 agent 拿出更稳的 prompt。
+ *
+ * 触发：本 session 第 1 次调 generate_image；后续不再注入（避免 spam）。
+ * 文件源：prompts/tools/generate-image-cookbook.md（模块加载时缓存）。
+ */
+export function makePreToolUseGenerateImageCookbookInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const cookbook = loadToolPrompt('generate-image-cookbook');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[generate_image 完整 cookbook — 首次注入]\n\n'
+        + cookbook
+        + '\n\n本 cookbook 每 session 只注入一次，已读完后续生图调用直接用即可。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(generate_image) — 第一次调用时提醒 agent 先 Read 目标页面。
+ *
+ * 设计原则 metadata-not-content：不预解析 canvas.html 注入页面 HTML，
+ * 而是提醒 agent 自己 Read。避免"被注入摘要后反而不主动读"的反模式。
+ *
+ * 触发：本 session（hook 工厂调用一次 → closure 一份 alreadyReminded）内
+ *      第 1 次调用 generate_image；后续不再注入。
+ *
+ * 不阻塞工具调用，permissionDecision='allow' 直接放行。
+ */
+export function makePreToolUseGenerateImageReadPageReminder() {
+  let alreadyReminded = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyReminded) return {};
+    alreadyReminded = true;
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[generate_image 目标页提醒]\n\n'
+        + '即将生成图片。如果还没看过目标页（deck 里对应的 <section data-page="N"> / 站点的那一页），建议先 Read 一下：\n'
+        + '  - 页面尺寸（多少行 / 多大留给图）\n'
+        + '  - 主色（design-tokens 里的 --bg / --accent / --hero）\n'
+        + '  - 已有视觉风格（hybrid 范式有无 React 组件 / 已有图片调性）\n\n'
+        + '多数情况下第一张图会被当 referenceImages 种子用于全 deck，看一眼能避免后续违和（暖色页塞冷调插图这类）。本提醒每 session 只触发一次。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(expose_tweaks) — 第一次调用时注 完整控件 schema 语法。
+ *
+ * SKILL.md 已有"何时暴露 / 暴露什么"哲学（5-8 个核心维度即可）；本 hook 注入完整
+ * 控件类型 / target_var vs target_class_on / target_scope / Tailwind 桥接 / 常坑
+ * 等参考语法，让 agent 写 controls JSON 时一次到位。
+ *
+ * 触发：本 session 第 1 次调 expose_tweaks；后续不再注入。
+ * 文件源：prompts/tools/tweaks-syntax.md（模块加载时缓存）。
+ */
+export function makePreToolUseExposeTweaksSyntaxInjector() {
+  let alreadyInjected = false;
+  return async (_input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    alreadyInjected = true;
+    const syntax = loadToolPrompt('tweaks-syntax');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[expose_tweaks 完整语法 — 首次注入]\n\n'
+        + syntax
+        + '\n\n本语法每 session 只注入一次。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(Agent) — subagent_type='vision-checker' 时首次注 派遣 prompt 模板。
+ *
+ * 注：跟 makePreToolUseAgentForceForegroundHandler 共存于同一 'Task|Agent' matcher
+ * 下，SDK 按数组顺序串行执行多个 hook。本 hook 仅在 subagent_type==='vision-checker'
+ * 命中时注 dispatch 模板（含全 deck 自检 / 有 plan 时按计划 critique / 单页评审 3 模板）。
+ *
+ * ⚠️ 2026-08-03 修：原来读的是 `input.subagent_type`，而 PreToolUse 的 hook input
+ * 形状是 `{ tool_name, tool_input, tool_use_id, ... }`（sdk.d.ts PreToolUseHookInput），
+ * 工具入参在 **tool_input** 里 —— 顶层那个字段永远是 undefined，条件永远不成立。
+ * 结果：历史上 6 次 vision-checker 派遣，模板一次都没注进去（jsonl 全量 grep 0 命中）。
+ * 同文件的 force-foreground handler 一直读的是 `input?.tool_input`，是对的，
+ * 这里当初抄漏了一层。
+ *
+ * 触发：本 session 第 1 次派 vision-checker；后续不再注入。
+ * 文件源：prompts/tools/vision-checker-dispatch.md（模块加载时缓存）。
+ */
+export function makePreToolUseTaskVisionCheckerDispatchInjector() {
+  let alreadyInjected = false;
+  return async (input, _toolUseId, _options) => {
+    if (alreadyInjected) return {};
+    if (input?.tool_input?.subagent_type !== 'vision-checker') return {};
+    alreadyInjected = true;
+    const dispatch = loadToolPrompt('vision-checker-dispatch');
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        additionalContext:
+          '<system-reminder>\n[vision-checker 派遣 prompt 模板 — 首次注入]\n\n'
+        + dispatch
+        + '\n\n本模板每 session 只注入一次。后续派遣按这套结构写 prompt 即可。\n'
+        + '</system-reminder>',
+      },
+    };
+  };
+}

package/server/engine/agent/hooks/pre-performance-log-guard.js

@@ -0,0 +1,78 @@
+/**
+ * pre-performance-log-guard —— 演出记录的隐私闸（2026-08-15，用户拍板）。
+ *
+ * RP 台词只走 chatai 通路（中转站），**不进设计会话**：agent 线的上下文进
+ * Anthropic，用户的演出原文不该去。此闸拦 agent 对演出文件夹里对话记录/摘要的
+ * Read / Grep —— 判定证据是同目录有 `编排.yaml`。写不拦：建场要种开场白
+ * （Write 对话.jsonl 是 skill 教的正路）。
+ *
+ * ⭐ **边界写死在这儿，别再自己脑补它有多严**：只拦「路径点名那个文件」这一种
+ * 读法。`Grep path=<演出文件夹>`、Bash `cat 戏/对话.jsonl` 都过得去。
+ * 2026-08-15 补过那两条（Grep 注排除 glob + Bash 命令闸），**用户看过连带面之后
+ * 决定撤回**：改 Grep 输入会影响所有 RP 项目的每一次搜索，Bash 串匹配会误伤
+ * `git add` / `cp` 这类正当命令，而拦住的只是"顺手"——本来就不防蓄意。
+ * 撤回时留下的真教训记在 [[nodesign-rp-mode]]：判据用正则抓 `编排.yaml` 里第一个
+ * `文件:` 会把系统层条目的设定文件（`文件: 设定/叙述者.md`）当成记录名 ——
+ * 所以下面这份解析是 YAML 解析、只认 `历史.文件`。
+ *
+ * 剩下两层不在这个文件里：
+ *   - 项目 `.gitignore` 里有 对话.jsonl / 摘要.json（workspace.js 的
+ *     DEFAULT_GITIGNORE），而 Grep 走 ripgrep 默认跳过被 gitignore 的文件；
+ *   - rp-craft skill 的隐私纪律章（让它压根不想去读）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import YAML from 'yaml';
+
+const FIXED = ['对话.jsonl', '摘要.json'];
+const CONFIG_FILE = '编排.yaml';
+
+/**
+ * 一个演出文件夹认哪几个记录文件名（固定两个 + `历史.文件` 自定义的记录名）。
+ *
+ * ⚠️ 必须**解析 YAML** 而不是正则抓第一个 `文件:` —— 系统层条目的
+ * `文件: 设定/叙述者.md` 排在 `历史.文件` 前面，正则版会把用户的设定文件
+ * 当成记录名（2026-08-15 在真配置上量出来的）。
+ * 半写完的 YAML 解析失败 → 只认固定两个名，不拦别的。
+ */
+async function namesOfPerformanceDir(dir) {
+  let raw;
+  try { raw = await fs.readFile(path.join(dir, CONFIG_FILE), 'utf8'); } catch { return null; }
+  const names = new Set(FIXED);
+  try {
+    const doc = YAML.parse(raw);
+    const rec = doc?.历史?.文件;
+    if (typeof rec === 'string' && rec.trim()) names.add(path.basename(rec.trim()));
+  } catch { /* 写了一半的 YAML：固定两个名照旧生效 */ }
+  return names;
+}
+
+/** @returns {Promise<null | string>} null=放行；string=拒绝理由 */
+export async function checkPerformanceLogRead(toolInput, workspaceRoot) {
+  const fp = toolInput?.file_path || toolInput?.path || '';
+  if (typeof fp !== 'string' || !fp) return null;
+  const abs = path.isAbsolute(fp) ? fp : path.resolve(workspaceRoot || '', fp);
+  const names = await namesOfPerformanceDir(path.dirname(abs));
+  if (!names) return null;                       // 同目录没有 编排.yaml → 不是演出文件夹
+  const base = path.basename(abs);
+  if (!names.has(base)) return null;
+  return `「${base}」是这场演出的对话记录——用户的演出原文是隐私，只走 chatai 通路，不进设计会话。`
+    + '要推进剧情改 状态/ 里的文件（尾部条目每轮现读）；用户想给你看某段戏会自己粘贴过来。';
+}
+
+export function makePreToolUsePerformanceLogGuard({ workspaceRoot }) {
+  return async (input) => {
+    try {
+      const reason = await checkPerformanceLogRead(input?.tool_input, workspaceRoot);
+      if (!reason) return {};
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: reason,
+        },
+      };
+    } catch { return {}; }                       // 闸自己出错不拦工具（fail-open）
+  };
+}

package/server/engine/agent/hooks/pre-starter-files.js

@@ -0,0 +1,61 @@
+/**
+ * skill 起手文件拷贝族（2026-08-14 可维护性行动：从 hooks.js 原样迁出）。
+ * 2026-07-27 工作台升级起，starter 拷贝从 session-loop init 挪到 hook：
+ * session 不再默认等于 deck 任务，非 deck 会话的 cwd 不再预置 deck 模板。
+ */
+import { ensureSkillStarterFiles, listSkillIds, listSkillStarterFiles } from '../skill.js';
+
+/**
+ * PreToolUse(Skill) — agent 加载 deskskill-engine-mini 时把 skill 起手文件
+ * （canvas.template.html 等）拷进 session cwd。
+ *
+ * ensureSkillStarterFiles 幂等 + fail-soft。
+ */
+export function makePreToolUseSkillStarterFilesCopier({ workspaceRoot }) {
+  const done = new Set();
+  return async (input, _toolUseId, _options) => {
+    if (!workspaceRoot) return {};
+    try {
+      // 认哪个 skill 从入参里读，不再硬编码 'deskskill-engine-mini' ——
+      // 硬编码的后果是新 skill（站点）的模板永远拷不出来，而且静默。
+      const raw = JSON.stringify(input?.tool_input || {});
+      for (const id of await listSkillIds()) {
+        if (done.has(id) || !raw.includes(id)) continue;
+        done.add(id);
+        const r = await ensureSkillStarterFiles(workspaceRoot, id);
+        if (r.copied.length > 0) {
+          console.log(`[hooks] starter files copied on Skill load (${id}): ${r.copied.join(', ')}`);
+        }
+      }
+    } catch (err) {
+      console.warn('[hooks] starter files copy on Skill load failed:', err.message);
+    }
+    return {};
+  };
+}
+
+/**
+ * PreToolUse(Bash) 兜底 —— agent 没走 Skill 加载、直接按 prelude 的
+ * "起手 cp canvas.template.html" 动手时，命令里出现模板名就现场补拷，
+ * 避免 cp 报 No such file。
+ */
+export function makePreToolUseBashStarterFilesFallback({ workspaceRoot }) {
+  const done = new Set();
+  return async (input, _toolUseId, _options) => {
+    if (!workspaceRoot) return {};
+    const command = String(input?.tool_input?.command || '');
+    if (!command.includes('.template.')) return {};   // 快速排除绝大多数命令
+    try {
+      for (const id of await listSkillIds()) {
+        if (done.has(id)) continue;
+        const names = await listSkillStarterFiles(id);
+        if (!names.some(n => command.includes(n))) continue;
+        done.add(id);
+        await ensureSkillStarterFiles(workspaceRoot, id);
+      }
+    } catch (err) {
+      console.warn('[hooks] starter files fallback copy failed:', err.message);
+    }
+    return {};
+  };
+}

package/server/engine/agent/hooks/pre-workspace-scope-guard.js

@@ -0,0 +1,78 @@
+/**
+ * pre-workspace-scope-guard —— 结构化工具的项目边界闸（2026-08-15）
+ *
+ * 沙盒（bwrap）只管 Bash。Read / Grep / Glob / Write / Edit 是 SDK 进程内工具，
+ * 不进 bwrap —— 2026-08-15 探针实测：沙盒开着，Read 照样能读别的项目的工作区，
+ * Write 照样能往 cwd 外落文件。凭据那部分由 permissions.deny 盖住了
+ * （runtime/platform.js），**但"别人的项目"盖不住**：deny 规则没有"除了自己这个"
+ * 的写法（deny 压过 allow），而项目是动态新建的。
+ *
+ * 两条判据，读写不一样严：
+ *   - **写**（Write/Edit/NotebookEdit）：只准落在自己的工作区或临时目录。
+ *     写东西到别处没有任何正当理由 —— 产物都在工作区里。
+ *   - **读**（Read/Grep/Glob）：只拦数据根内部的越界。仓库、plugin/skill 目录、
+ *     /tmp 照读不误 —— 那是干活要用的（skill 附件就在仓库里）。
+ *
+ * 边界（故意窄，别自己脑补更严）：
+ *   - 凭据不归它管（那是 platform.protectedPathRules 的活，两边别互相假设）。
+ *   - 自己出错就放行（fail-open）—— 闸崩了不该把整个会话堵死。
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+const TARGET_FIELDS = ['file_path', 'path', 'notebook_path'];
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+
+function insideDir(abs, dir) {
+  return abs === dir || abs.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep);
+}
+
+/** 临时目录（沙盒会把 TMPDIR 指到自己那份，两个都认） */
+function tempDirs() {
+  return [process.env.TMPDIR, os.tmpdir(), '/tmp'].filter(Boolean).map(d => path.resolve(d));
+}
+
+/**
+ * @returns {null | string} null=放行；string=拒绝理由
+ */
+export function checkWorkspaceScope(toolInput, { workspaceRoot, dataRoot, toolName } = {}) {
+  if (!workspaceRoot) return null;
+  const ws = path.resolve(workspaceRoot);
+  const isWrite = WRITE_TOOLS.has(toolName);
+  if (!isWrite && !dataRoot) return null;
+  const root = dataRoot ? path.resolve(dataRoot) : null;
+  for (const field of TARGET_FIELDS) {
+    const v = toolInput?.[field];
+    if (typeof v !== 'string' || !v) continue;
+    const abs = path.resolve(ws, v);          // 相对路径按工作区解析
+    if (insideDir(abs, ws)) continue;         // 自己的工作区，放行
+    if (isWrite) {
+      if (tempDirs().some(d => insideDir(abs, d))) continue;   // 临时文件随便写
+      return `${toolName} 只能落在你自己的工作区里（${ws}），或者临时目录。`
+        + '产物、草稿、附件全都归工作区管；往外写一律拒绝。';
+    }
+    if (!root || !insideDir(abs, root)) continue;   // 数据根之外的读不归这道闸管
+    return '这个路径在别的项目的工作区里，不是你这个项目的东西。'
+      + `你的工作区是 ${ws} —— 用相对路径就好，越过它去读写别人的项目一律拒绝。`;
+  }
+  return null;
+}
+
+export function makePreToolUseWorkspaceScopeGuard({ workspaceRoot, dataRoot }) {
+  return async (input) => {
+    try {
+      const reason = checkWorkspaceScope(input?.tool_input, {
+        workspaceRoot, dataRoot, toolName: input?.tool_name,
+      });
+      if (!reason) return {};
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: reason,
+        },
+      };
+    } catch { return {}; }                    // 闸自己出错不拦工具（fail-open）
+  };
+}

package/server/engine/agent/hooks/site-validate.js

@@ -0,0 +1,94 @@
+/**
+ * hooks/site-validate.js — 站点页面的两条硬规则 lint（2026-08-21）
+ *
+ * 起手模板（site.template.html / style.template.css）08-21 删了：它把"别把预览弄坏"
+ * 的硬规则和"站长什么样"的默认审美捆在一个文件里，后者同化了一半的成品（11/28 个
+ * 站保留着模板骨架）。硬规则不能靠"注释写在模板顶上、agent 记得 Read"传播 ——
+ * 契约要配 lint。这里就是那两条：
+ *
+ *   1. `<meta name="viewport">` 缺失 → 手机端按 980px 虚拟视口渲染，媒体查询
+ *      看着"没生效"
+ *   2. 根路径 `href="/x"` / `src="/x"` → 预览走 `/api/projects/<id>/artifact-file/…`
+ *      前缀，根路径跳出前缀直接 404（发布到独立域名后反而正常，所以本地更容易漏）
+ *
+ * 实测（08-21，27 个站）两条违反都是 0 —— 模型本来就守。lint 的意义是把"本来就守"
+ * 变成"守不守都查得到"，弱模型/长会话漂移时兜底。只报不改，跟 canvas-validate 同款。
+ *
+ * 只看**子目录里的 .html**（站点住自己的文件夹）；工作区根上的 .html 是 deck，
+ * 不归这里（deck 有自己的 canvas-validate）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MAX_BYTES = 2 * 1024 * 1024;
+
+const strip = (html) => String(html)
+  .replace(/<!--[\s\S]*?-->/g, '')
+  .replace(/<script[\s\S]*?<\/script>/gi, '')
+  .replace(/<style[\s\S]*?<\/style>/gi, '');
+
+/**
+ * 纯函数：html 文本 → 问题列表（空数组 = 干净）。
+ * @returns {Array<{title:string, detail:string}>}
+ */
+export function lintSiteHtml(html) {
+  const src = strip(html);
+  const issues = [];
+  if (!/<meta\s[^>]*name\s*=\s*["']viewport["']/i.test(src)) {
+    issues.push({
+      title: '缺 <meta name="viewport">',
+      detail: '没有它手机端按 980px 虚拟视口渲染，媒体查询看着"没生效"。加 <meta name="viewport" content="width=device-width, initial-scale=1">。',
+    });
+  }
+  // 根路径：href="/x" 或 src="/x"，排除协议相对 "//cdn…"；"/" 单独一个也算（回首页应写 index.html）
+  const roots = [...src.matchAll(/\b(?:href|src|action)\s*=\s*["'](\/(?!\/)[^"']*)["']/gi)].map(m => m[1]);
+  if (roots.length) {
+    const uniq = [...new Set(roots)].slice(0, 5);
+    issues.push({
+      title: `根路径链接 ${roots.length} 处（${uniq.join(' ')}${roots.length > uniq.length ? ' …' : ''}）`,
+      detail: '预览和导出都走 artifact-file/<路径> 前缀，根路径会跳出前缀直接 404。站内一律相对路径：about.html / assets/x.png / ../assets/generated/x.png。',
+    });
+  }
+  return issues;
+}
+
+/** 相对工作区的 .html，且在子目录里（站点页）—— deck 在根上，不归这里 */
+export function isSitePagePath(workspaceRoot, fp) {
+  if (!fp || !/\.html?$/i.test(fp)) return false;
+  const rel = path.relative(workspaceRoot, path.resolve(workspaceRoot, fp)).split(path.sep).join('/');
+  if (!rel || rel.startsWith('..') || !rel.includes('/')) return false;
+  if (/^(exports|node_modules|_drafts|\.)/.test(rel)) return false;   // _drafts/ 是独立单页，不是站点页
+  return true;
+}
+
+export function makePostToolUseSiteValidationHandler({ workspaceRoot }) {
+  return async (input) => {
+    try {
+      const fp = input?.tool_input?.file_path;
+      if (!workspaceRoot || !isSitePagePath(workspaceRoot, fp)) return {};
+      const abs = path.resolve(workspaceRoot, fp);
+      let html;
+      try {
+        const st = await fs.stat(abs);
+        if (st.size > MAX_BYTES) return {};
+        html = await fs.readFile(abs, 'utf8');
+      } catch (err) {
+        if (err.code === 'ENOENT') return {};
+        throw err;
+      }
+      if (html.includes('__nd-deck-wrap')) return {};   // 收进文件夹的 deck，不是站点页
+      const issues = lintSiteHtml(html);
+      if (!issues.length) return {};
+      const body = issues.map((i, idx) => `${idx + 1}. ${i.title}\n   ${i.detail}`).join('\n\n');
+      return {
+        systemMessage:
+          `<system-reminder>\n[site-validate] 你刚改完 ${fp}，系统检测到 ${issues.length} 项会让预览出错的硬规则违反：\n\n`
+          + body
+          + '\n\n有意为之就忽略；否则下一轮先修这几处再继续。\n</system-reminder>',
+      };
+    } catch (err) {
+      console.warn('[hooks/site-validate] threw:', err.message);
+      return {};
+    }
+  };
+}

package/server/engine/agent/hooks/tool-prompts.js

@@ -0,0 +1,31 @@
+/**
+ * 工具 prompt lazy 注入文件加载（首调即缓存）。仿 agents/index.js loadPrompt 模式。
+ *
+ * 用途：cookbook / tweaks-syntax / vision-checker-dispatch 这些 reference 文档
+ * 不放系统 prompt 恒驻（每 turn 拖累），改由 PreToolUse hook 在 agent 首次调对应工具时
+ * 通过 additionalContext 注入。文件存 prompts/tools/*.md，模块加载时一次性读完缓存到 map。
+ *
+ * fail-soft：缺失 / 读失败返回 stub 字符串，hook 注入也不至于崩；console.warn 让部署
+ * 日志能立刻发现。
+ */
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// prompts/ 住在 agent/ 层（本模块在 agent/hooks/ 下一层，要往上跳一级）
+const PROMPTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'prompts', 'tools');
+
+const TOOL_PROMPT_CACHE = {};
+export function loadToolPrompt(name) {
+  if (TOOL_PROMPT_CACHE[name] !== undefined) return TOOL_PROMPT_CACHE[name];
+  const file = path.join(PROMPTS_DIR, `${name}.md`);
+  try {
+    TOOL_PROMPT_CACHE[name] = fsSync.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.warn(`[hooks] failed to load tool prompt ${name}.md (${err.message}); using stub`);
+    TOOL_PROMPT_CACHE[name] =
+      `(tool prompt ${name}.md not found at ${file}. PreToolUse hook will skip lazy injection — `
+      + `agent fallbacks to whatever guidance lives in SKILL.md core.)`;
+  }
+  return TOOL_PROMPT_CACHE[name];
+}

package/server/engine/agent/hooks/turn-state-memory.js

@@ -0,0 +1,56 @@
+/**
+ * hooks/turn-state-memory.js — 每轮状态注入的"上一轮记忆"（2026-08-21）
+ *
+ * UserPromptSubmit 每轮把工作区状态（素材 / 产物 / 便利贴 / 关系线 / 决策 / tweaks）
+ * 注给模型。以前每轮全量，30 轮下来上下文里是十几份几乎一样的块（实测 540~1300
+ * token/轮）。现在**首轮全量、之后只报变化**：每节算一个指纹存在这里，下一轮对照。
+ *
+ * 键按 sessionId（一次对话一份记忆）。两种情况要清掉让下一轮重新全量：
+ *   - 上下文压缩之后（PostCompact）：旧的那份已经被摘要吞了，"同上轮"没有所指
+ *   - 进程重启：Map 本来就空
+ * 上限 300 个会话，LRU 淘汰 —— 会话结束不另外清（多数会话没几轮，留着也就几百字节）。
+ */
+
+const MAX_SESSIONS = 300;
+/** sessionId → { sections: Map<key, {hash:string, items:string[]|null}>, turns: number } */
+const memory = new Map();
+
+/** djb2：够用的短指纹，不引 crypto */
+export function fingerprint(text) {
+  let h = 5381;
+  const s = String(text);
+  for (let i = 0; i < s.length; i += 1) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+export function getTurnMemory(sessionId) {
+  if (!sessionId) return null;
+  const m = memory.get(sessionId);
+  if (m) { memory.delete(sessionId); memory.set(sessionId, m); }   // LRU 触碰
+  return m || null;
+}
+
+export function setTurnMemory(sessionId, sections) {
+  if (!sessionId) return;
+  const prev = memory.get(sessionId);
+  memory.delete(sessionId);
+  memory.set(sessionId, { sections, turns: (prev?.turns || 0) + 1 });
+  while (memory.size > MAX_SESSIONS) memory.delete(memory.keys().next().value);
+}
+
+/** 压缩后 / 想强制下一轮全量时调 */
+export function resetTurnMemory(sessionId) {
+  if (sessionId) memory.delete(sessionId);
+}
+
+/** 两个清单的差 → { added, removed }（给素材 / 便利贴这种按项报变化的节用） */
+export function diffItems(prevItems, nextItems) {
+  const prev = new Set(prevItems || []);
+  const next = new Set(nextItems || []);
+  return {
+    added: [...next].filter(x => !prev.has(x)),
+    removed: [...prev].filter(x => !next.has(x)),
+  };
+}
+
+export const _memory = memory;   // 测试用