cardbuddy 0.10.0 → 0.11.0

package/dist/server-core/ai-chat.js

@@ -0,0 +1,3710 @@
+/**
+ * AI 开发助手后端：流式调用任意 OpenAI 兼容 LLM，工具调度复用 mcp/tools.mjs。
+ *
+ * 设计：
+ *   - 不依赖 AI SDK（v7 对 reasoning_content 等扩展字段兼容差，直接丢弃导致无输出），
+ *     用原生 fetch + ReadableStream 手写 OpenAI chat/completions 流式客户端。
+ *   - 模型配置（baseUrl / apiKey / model）读取优先级：
+ *     真实环境变量 > .env.cb.local（个人覆盖，不入库）> .env.cb（共享默认）。
+ *     密钥不回传前端（只回 hasKey + 掩码），保存时写入 .env.cb.local，避免密钥进版本库。
+ *   - 工具调度复用 mcp/tools.mjs 的 TOOLS + dispatch；另加本地工具
+ *     skill_read（skills/ 文档按需读）/ card_grep + card_patch（大卡最小改）/ fs_read + fs_list（仓库与挂载目录）
+ *     / skill_exec（跑 skills 下各技能的 scripts 脚本，设计稿前处理管线的唯一执行手段）/ shell_exec（需显式开启）。
+ *   - 挂载目录进上下文时，服务端顺手跑 card_route_input 做「建卡输入路由」机械判定（Workflow 0 前置），
+ *     并附浅层清单：模型不必再自己试错形态，省下的步数用于真正的建卡动作。
+ *   - system prompt 为精简协议 + 参考索引；模型用 skill_read 工具按需取
+ *     skills/dsl-card-generator/references 下的文档（避免整份 skill 十万字进上下文放大空转思考）。
+ *   - 客户端断开（前端「停止」按钮 / 关页）即中止 LLM 请求与工具循环，不再白跑。
+ *   - 对话记录按卡片落盘 .cache/ai-chats/<cardId>.json（.cache/ 不入库），切卡 / 重开可续。
+ *   - 本地文件挂载：不上传，只解析绝对路径 + 元信息；图片预览由本机读盘直出。
+ *
+ * 端点（均只放行可信来源：回环 / 局域网 / 本机网卡地址，避免公网页面跨源读本机文件）：
+ *   GET/POST  /__ai/config            读取（脱敏；?reveal=1 回明文供设置面板回显）/ 保存模型配置
+ *   POST      /__ai/ping              连通性自测（设置面板「测试连接」）
+ *   POST      /__ai/chat              SSE 流式对话
+ *   GET/POST/DELETE /__ai/history     按 cardId 读 / 存 / 清对话记录
+ *   POST      /__ai/fs/pick           调起系统选择器，返回绝对路径
+ *   GET       /__ai/fs/stat           路径元信息（文件 / 文件夹摘要）
+ *   GET       /__ai/fs/raw            本地图片直出（仅预览用）
+ *   POST      /__ai/fs/locate         拖拽落点的绝对路径反查（浏览器拿不到 path）
+ *   POST      /__ai/fs/stash          剪贴板截图落盘为本机路径（同样只存本地 .cache/）
+ *   POST      /__ai/approve           对话内审批回落（skill_exec / shell_exec 的「允许 / 本回合不再询问 / 拒绝」）
+ *
+ * /__ai/chat SSE 事件：
+ *   data: {"type":"reasoning-delta","text":"..."}
+ *   data: {"type":"text-delta","text":"..."}
+ *   data: {"type":"tool-call","toolCallId":"...","toolName":"card_write","args":{...}}
+ *   data: {"type":"tool-call-start","toolCallId":"...","toolName":"..."}   工具名先到、参数还在流
+ *   data: {"type":"tool-result","toolCallId":"...","toolName":"...","result":"..."}
+ *   data: {"type":"approval-request","approvalId":"...","toolName":"skill_exec","command":"python3 skills/...","args":{...}}
+ *   data: {"type":"approval-decided","approvalId":"...","ok":true,"scope":"once|turn"}
+ *   data: {"type":"approval-auto","toolName":"skill_exec","command":"node skills/..."}   免确认策略命中：没弹审批，直接执行
+ *   data: {"type":"notice","message":"..."}                                  横幅提示（重复调用警告 / 上下文折叠 / 收敛催促）
+ *   data: {"type":"context-usage","used":12345,"total":96000,"window":65536}   每轮上下文占用（输入框圆环）
+ *   data: {"type":"turn-ended","reason":"loop|timeout|steps","message":"..."} 熔断收尾原因（前端落进对话记录，持久可见）
+ *   data: {"type":"error","message":"..."}
+ *   data: {"type":"aborted"}
+ *   data: {"type":"done"}
+ */
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import { execFile, spawn, spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = path.resolve(__dirname, '..', '..')
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills')
+
+/** 单卡片最多保留的消息条数，超出从头部裁剪（避免历史无限增长撑爆上下文与磁盘） */
+const MAX_HISTORY_MESSAGES = 200
+
+// ---- 工具定义（延迟加载） ----
+let _toolsCache = null
+let _dispatchRef = null
+
+async function loadTools() {
+  if (_toolsCache) return { tools: _toolsCache, dispatch: _dispatchRef }
+  const toolsModule = await import('../../mcp/tools.mjs')
+  const { TOOLS, dispatch } = toolsModule
+  // OpenAI tools 格式
+  const openaiTools = TOOLS.map((t) => ({
+    type: 'function',
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.inputSchema || { type: 'object', properties: {} },
+    },
+  }))
+  _toolsCache = openaiTools
+  _dispatchRef = dispatch
+  return { tools: openaiTools, dispatch }
+}
+
+// ---- System prompt：精简协议 + 按需参考索引 ----
+
+const SKILL_REFS_DIR = path.join(SKILLS_DIR, 'dsl-card-generator', 'references')
+/** 参考索引的一句话说明：够模型选对文件即可，全文不进上下文 */
+const SKILL_REF_HINTS = {
+  'rules.md': '卡片生成铁律（card_write 前必读：结构 / 绑定 / 样式红线）',
+  'expression_engine.md': '$ 表达式绑定引擎：语法与金额 / 文本格式化表达式（「文本用表达式实现」首选）',
+  'amount_formatting.md': '金额千分位 / 货币符号格式化约定与示例',
+  'dsl_structure.md': 'schema 骨架：组件树 / 插槽 / 样式 / v-show 字段结构',
+  'component_specs.md': '可渲染组件的属性、事件、插槽与样式默认值规范',
+  'component_rules.md': '组件使用规则与常见禁忌',
+  'event_patterns.md': '事件脚本范式：this.state 直读、globalSet / postMessage 透传',
+  'field_naming.md': '变量命名规范与中文名映射',
+  'field_name_dict.json': '高频变量名字典（JSON）',
+  'card_to_summary.md': '从 schema 解释建卡逻辑的要点',
+  'quickref.md': '速查卡：组件 / 表达式 / 样式 / 工作流一页纸（拿不准先看这个）',
+  'recipes.md': '通用开发范式库：Canvas 标题头 / 列表 / 金额 / 弹窗等组合配方（建卡先套最接近的范式）',
+  'spec_to_schema_patterns.md': 'spec 标注 → schema 的映射范式（设计稿建卡照抄字段形状）',
+  'card_index.json': '全卡索引（组件 / 范式标签 / 名称）：找最相似的已有卡当范本',
+  'card_templates.json': '卡片模板库：card_scaffold 的 from 模板来源',
+  'generation_pitfalls.md': '生成高频坑位清单（IR / schema 写完自查一遍）',
+  'previewer_contract.md': '预览器渲染契约：绝对布局 AbsoluteLayout 等字段形状的唯一权威说明',
+  'ir-format.md': '紧凑 IR 字段契约（大卡建新卡时省 token 的中间表示）',
+  'ui_fidelity_rules.md': '保真规则：间距 / 字号 / 行高 / 媒体降级等还原度纪律',
+  'image_to_card.md': '设计稿 → 卡片的读图与语义块划分规则',
+  'slices_convention.md': '切图资产落点与引用约定（Image 节点用哪张图）',
+}
+/** 跨 skill 的固定入口：路径相对 skills/，与动态列出的 references 一起进「按需参考索引」 */
+const SKILL_DOC_ENTRIES = [
+  { path: 'dsl-card-generator/SKILL.md', hint: '建卡工作流总纲（Workflow 0 输入路由 / A 读图生成 / A.5 弹窗分流 / B 改卡）' },
+  { path: 'sketch-spec-to-card/SKILL.md', hint: 'MeaXure 导出 → 要素包管线：产物结构、画板分类、卡片边界判定' },
+  { path: 'sketch-spec-to-card/references/spec-schema.md', hint: 'spec.json 字段契约（cards / elements / rect / slices 怎么读）' },
+]
+let _systemPromptCache = null
+
+/**
+ * 系统提示词只放「工作协议 + 参考索引」。
+ * 此前整份注入两份 SKILL.md + rules.md（约 125KB / 数万 token），上下文臃肿会显著放大
+ * 推理模型的空转思考（实测单轮 reasoning 4 分钟不收敛、界面一直「思考中」）。
+ */
+function buildSystemPrompt({ shellAllowed = false, vision = false, autoApprove = DEFAULT_AUTO_APPROVE } = {}) {
+  const cacheKey = `${shellAllowed ? 'shell' : 'base'}${vision ? '+vision' : ''}+aa:${autoApprove}`
+  if (_systemPromptCache && _systemPromptCache.key === cacheKey) return _systemPromptCache.text
+  // 免确认策略要如实写进协议：模型若以为「每次都要用户点确认」，会主动停下来等批准 / 把命令甩给用户
+  const skillAuto = autoApproves(autoApprove, 'skill_exec')
+  const shellAuto = autoApproves(autoApprove, 'shell_exec')
+  const lines = []
+  for (const entry of SKILL_DOC_ENTRIES) {
+    const abs = path.join(SKILLS_DIR, entry.path)
+    let size = 0
+    try {
+      size = fs.statSync(abs).size
+    } catch {
+      continue
+    }
+    lines.push(`- ${entry.path}（${Math.max(1, Math.round(size / 1024))}KB）：${entry.hint}`)
+  }
+  try {
+    for (const name of fs.readdirSync(SKILL_REFS_DIR)) {
+      let st
+      try {
+        st = fs.statSync(path.join(SKILL_REFS_DIR, name))
+      } catch {
+        continue
+      }
+      if (!st.isFile()) continue
+      lines.push(`- ${name}（${Math.max(1, Math.round(st.size / 1024))}KB）：${SKILL_REF_HINTS[name] || '特定主题参考'}`)
+    }
+    // 范式片段是子目录，不列出来模型根本不知道存在（曾经为此反推 expand_ir 源码猜字段形状）
+    const snippets = fs
+      .readdirSync(path.join(SKILL_REFS_DIR, 'recipe_snippets'))
+      .filter((f) => f.endsWith('.json'))
+      .sort()
+    if (snippets.length) {
+      lines.push(
+        `- recipe_snippets/（按主题的现成范式片段，skill_read path=dsl-card-generator/references/recipe_snippets/<文件名> 取用）：${snippets.join(' / ')}`,
+      )
+    }
+  } catch {
+    /* references 目录缺失时只保留协议 */
+  }
+  const _text = `你是 CardBuddy 编辑器内置的卡片编辑助手：帮用户读取、修改、生成低代码卡片 schema.json。
+工作协议：
+1. 先用 card_read / card_node_models 了解卡片现状；修改保持最小 diff，不要重写无关节点。
+2. 写之前按需 skill_read 参考文档（path = 下面索引里的文件名）：常规修改只读最相关的 1-2 个文件——表达式 / 格式化问题先读 expression_engine.md；card_write 前读 rules.md；不要一次读全部。
+2b. 大卡（card_read 回喂被截断者）修改流程：card_grep 定位 JSON 路径 → card_patch 按路径最小写；严禁 card_write 整包重写大卡。小卡可直接 card_write。
+2c. **从零建卡（尤其设计稿建卡）不要在工具参数里吐整份 schema**：光参数就上万 token，会被单次输出上限截断，整轮白跑。正路是——先 skill_read ir-format.md 看字段契约 → fs_write 把紧凑 IR 写到 .cache/ai-scratch/<id>.ir.json（比 schema 小 4-5 倍）→ skill_exec 跑 skills/dsl-card-generator/scripts/expand_ir.mjs，args=["--ir",".cache/ai-scratch/<id>.ir.json","--out","src/cards/<id>/"]（自带 autofix + 真 validate，报错会原样回传）→ 报错就修。**IR 全文只写这一次**：之后所有调整都用 iterate.mjs 的 --set 点路径原子微调（一轮可带多条）；整份重写 IR 一次要 40-110s 纯输出浪费，只有结构级推翻才允许重写。
+2e. **flex / 尺寸红线（validate 与 lint 直接拦，别试错）**：枚举值 kebab-case（flex-start / flex-end / space-between；写 flexEnd 即 validate ERROR）；Column / Row 默认 gap=4，不需要间距就显式 gap:"0"；justifyContent:space-between 的 Row 必须 rect.width:"100%"（lint R19）；Row 父级里的 Row / AbsoluteLayout 子节点默认 width:100%，会互相把对方挤出画布——定宽子簇要显式 rect.width，且并列子节点至少一个 flexShrink:"1"（lint R35）。
+2d. **先抄范式，再动手写**：建卡 / 大改布局前按序取范式——① skill_read recipes.md 或 spec_to_schema_patterns.md 找最接近的组合配方；② 布局与自绘的字段形状（绝对布局 AbsoluteLayout、Canvas 自绘、列表展开收起、金额格式化、弹窗配对等）直接 skill_read recipe_snippets/ 下对应片段或 previewer_contract.md 照抄；③ 需要整卡范本时查 card_index.json，按组件 / 范式标签 / 名称找最相似的已有卡，card_read 或 fs_read 它的关键片段照着写。**禁止反推脚本源码（rg 翻 expand_ir.mjs 之类）或凭记忆猜字段形状**；范式里确实没有才允许自己设计，并在正文里说明为什么没有套用范式。
+3. 改变量类型时要同步处理引用它的地方（绑定表达式 / mock 数据）；金额字段配格式化表达式生成展示文本。
+4. 改完用人话说明：改了什么、为什么、需要用户确认什么。
+5. 信息足够后立即收敛：直接调用工具落盘或回复方案；同一内容不要重复读取。**思考里不要逐字草拟 schema / IR / 长 JSON，也不要复述卡片数据**——那会同时吃掉思考与输出额度，想清结构就立刻调工具把内容写出去。
+6. 读文件用 fs_read（仓库内任意文本文件 / 挂载附件），列目录用 fs_list —— fs_read 只能读文件，对目录一定报错，别拿它试目录；被中止过的轮次按上下文里的中止标记从中断处继续，不要从零重做。
+7. 跑技能脚本用 skill_exec（script 传 skills/<skill>/scripts/<脚本>，args 传参数数组）：设计稿前处理管线与 spec_audit / crop_slices / expand_ir / iterate / check_fidelity 等建卡脚本都靠它。${skillAuto ? '本仓库已设「技能脚本免确认」：调用即执行（审计写 .cache/ai-audit.log），不要停下来等用户批准，也不要因为怕要授权而改用 shell_exec 绕路、或把命令甩给用户自己跑。' : '每次调用会先请用户确认（用户可选「本回合不再询问」），被拒就把命令原样写给用户自行运行。'}${shellAllowed ? `\n8. 技能脚本之外的本地命令（npm / node / git / rg / cd 等）用 shell_exec：经真实 shell 执行，管道 |、链接 && / ;、重定向、引号与循环 / 条件 / 子shell 都可用（其中真正执行的每个外部命令需在白名单），不必再为元字符把命令拆开；复制文件用 fs_copy。${shellAuto ? '本仓库已设「本地命令免确认」：调用即执行。' : '每次调用都会弹给用户确认，被拒返回错误。'}cwd 已是仓库根、技能脚本自己按仓库根推算落点，不要写 cd；白名单不含 sips / convert / magick / python3 —— 图像裁剪派生一律 crop_slices.mjs，Python 脚本一律 skill_exec，别去试系统图像命令。` : ''}
+
+## 设计稿建卡协议（Stage Machine：逐阶段推进，上一阶段产物齐了才进下一阶段；用户挂载设计稿目录 / 图片并要求建卡时严格执行，不要自由发挥）
+S0 路由：输入形态已由服务端机械判定，写在「用户挂载的本地文件」段（kind / preprocess / next）：照它执行，不要再调 card_route_input；该段缺失才自己调 card_route_input({ path })。
+S1 要素包：kind=meaxure-export（Sketch MeaXure 标注导出）必须先有 sketch-spec-to-card 要素包，禁止直接读 preview/ 整图建卡。
+   - fs_read 判定里给出的 manifest（通常 UI/manifest.json）找目标画板条目：status=generated ⇒ 产物已在；status=pending ⇒ 先看 preprocess.alsoFound（同一导出的其它产物目录，平铺与按稿分片常并存），有就直接用；确实都没有才补跑：
+     ① skill_exec script=skills/sketch-spec-to-card/scripts/parse_meaxure.py，args=["--src","<导出目录>","--list"] 拿画板序号与名称；
+     ② args=["--src","<导出目录>","--out","UI","--draft","<稿名>","--indices","<n>","--build"] 只产该画板（多个逗号；按名称子串用 "--only","<子串>"）；
+     ③ script=skills/sketch-spec-to-card/scripts/cluster_states.py，args=["--out","UI/<稿名>"]。
+   - 要素包落点记作 <bundle>：传了 --draft 在 UI/<稿名>/<画板名>/，否则 UI/<画板名>/；以 parse_meaxure.py 打印的落盘路径为准。仓库可能两种布局并存，manifest 说的画板在 UI/ 下找不到就用 fs_list UI 找同名目录，别急着判定产物缺失。
+S2 审计（一步代替反复探索）：skill_exec script=skills/dsl-card-generator/scripts/spec_audit.mjs，args=["--spec","<bundle>/spec.json","--card","N","--slices-dir","<bundle>/slices","--project-slices","src/slices","--design","<bundle>/card-N.png","--save",".cache/ai-scratch/<id>.audit.json"]。
+   它交叉审计 spec + 聚焦截图 + 切图目录，给出：bands（水平行与行内元素序）、gaps（padLeft / padRight / padTop / padBottom / rowGaps）、texts（文案 / 字号 / 字重 / 颜色 / 行高 / 对齐）、shapes（装饰条）、slices（存在性 / 复用 / 是否烘焙背景与标签文字）、colors（背景采样点）、missing（缺哪张切图 + 建议裁剪矩形）。
+   它交叉审计 spec + 聚焦截图 + 切图目录，另给 bgGradientHint（顶部渐变带的起止色/跨度 + IR 正确写法）与 slices[].crops（reused-differs 时「矩形 → 该用哪张 _alt 图」的映射，exists=true 直接引用、false 才需裁）。
+   IR 的几何与样式一律照抄审计值；**禁止 fs_read spec.json**（几百 KB 只会拿到截断片段，重复读纯浪费步数），禁止反复 fs_list 摸索结构。要看层级树才跑 spec_tree.mjs。
+   **审计 JSON 只认落盘文件**：--save 已把整份审计写到 .cache/ai-scratch/<id>.audit.json，下游脚本（crop_slices --from-audit）一律引用该文件。**禁止用 fs_write 手抄 / 节选审计内容**——实测手抄的 156 字节「摘要」让 crop_slices 裁出错名错位的切图，还自造了违反命名约定的新切片。
+S3 补切图：S2 的 missing 非空 ⇒ skill_exec script=skills/dsl-card-generator/scripts/crop_slices.mjs，args=["--design","<bundle>/card-N.png","--card-width","<卡宽>","--out","src/slices","--from-audit",".cache/ai-scratch/<id>.audit.json"]，从聚焦截图派生缺失切图（审计已落盘，直接引用）。切图唯一落点 src/slices/ 扁平命名，IR 里 Image.value 用 /slices/<名>。
+   只缺一两张时用 --crop <名>@x,y,w,h（可多条），x/y/w/h 直接抄审计 missing[].crop 的**卡片本地 1x 坐标**，脚本自己按 design 宽 ÷ 卡宽换算像素。**禁止用 sips / convert / magick 等系统图像命令裁图**：它们不在 shell 白名单，且要手算缩放比与裁剪偏移，实测必错。
+   切图用法看 slices[].baked：label=true ⇒ 切图已含标签文字，tile 用单个 Image（96×84 之类照 rect 抄）；label=false ⇒ 需要 Image + Text 组合；verdict=reused-differs ⇒ 同一张切图被标到内容不同的多个位置，除第一个外必须用审计 slices[].crops 给出的 _alt 名（exists=true 直接引用，exists=false 由 crop_slices 派生）——**禁止自造新名字**（实测自造 icon_xx_左/右 让同一设计内容在 src/slices 下出现三套名字）。
+S4 写 IR（全文只写这一次）：fs_write .cache/ai-scratch/<id>.ir.json。结构照 bands 一条一段；gaps.rowGaps 映射成 flex.gap / padding（paddingType:"1" + 四边值）；texts 逐条转 Text（fontSize / fontWeight / color / lineHeight 全抄，**lineHeight 必写**，否则渲染器按 1.5 倍字号撑高、整卡累计漂移几个像素）；标题 + 底部装饰条照抄 recipe_snippets/title-underline-overlay.json（AbsoluteLayout + position.top，禁负 margin）。
+   **类型开关铁律（渲染器静默丢弃类缺陷的唯一防线）**：margin / padding 组写单边值（marginTop 等）必须同组写 marginType:"1" / paddingType:"1"（expand_ir 会自动补；手写 schema 漏了会被 lint 报 r44-*-no-type）；背景三选一：纯色 backgroundType:"01"+backgroundColor、图片 "02"+backgroundImage、渐变 "03"+backgroundGradient。审计给了 bgGradientHint 就照抄它的 ir 字段；**禁止自造 gradientColor / gradientDirection，禁止把 linear-gradient(...) 塞进 backgroundColor**——这三者都会静默失效（实测模型连试 3 轮全无效后放弃并编造理由）。
+   落点卡默认 = 当前正在编辑的卡片 ID（见「当前卡片上下文」）：IR 的 id 与 iterate 的 --out 一律 src/cards/<当前卡片ID>/，即覆盖当前卡 / 空卡是默认行为；只有用户明说「新建一张」才自拟 ID。当前卡已有内容时，动手前一句正文说明将覆盖、原内容留 .history 快照可回滚。
+S4.5 变量抽取（真实卡片不是截图：这步漏了，产物就是 dictionary / data.json 全空的死图）：先 skill_read ir-format.md 的「2b. 变量绑定」看契约，再决定哪些文本绑变量——
+   下限 = S2 审计的 bindHints[]（amount / percent / date / masked / count / level），再按语义补正则认不出的动态值（用户名 / 客户层级 / 卡片名称 / 状态词）；静态标签（区块标题 / 按钮 / 说明文字）才写字面量。
+   - 动态值：Text 主值用 v:"$key"（条件文案写表达式如 "$showAll ? '收起' : '查看更多'"，金额展示照 recipe_snippets/money-format.json，别把「¥7,000.00」拆成字面量）。
+   - IR 顶层**显式写 dictionary.inputParams**：{key,name,type,defaultValue,desc,rule:{type:"",options:{}},children:[]}，defaultValue 一律取设计稿字面量——expand_ir 用它生成 data.json，渲染即设计稿文案，S5 像素闭环才不受绑定影响。
+   - 重复行 / tile 组（审计 listCandidates[]、或用户明说要列表）：数组变量 + listScope 插槽，子树内 $item.xxx / $_index；范式照 recipe_snippets/list-expand-collapse.json 或 src/cards/account 的 account_details。结构确实不规则时允许保持静态，但要在正文说明理由。
+   - 命名语义化（memberLevel / totalAmount / assetRows），禁 text1 / val2；写完在正文列一句绑定清单（key → 设计稿文案）。
+S5 收敛循环（唯一门禁 = iterate.mjs 报告里的 gate 字段：内部已跑 autofix + 真 validate + lint + preflight + render + 并集像素对比，别再单独跑 validate_schema.py）：
+   skill_exec script=skills/dsl-card-generator/scripts/iterate.mjs，args=["--ir",".cache/ai-scratch/<id>.ir.json","--out","src/cards/<落点卡>/","--design","<bundle>/card-N.png","--width","<卡宽>","--spec","<bundle>/spec.json"]。
+   修 IR 一律 --set 点路径原子微调（数字段=数组下标，一轮可多条；中段不存在会响亮报错，按报错改路径），例：--set children.0.s.flex={"gap":"0"}。
+   **收敛 = 报告 gate.passed === true**（validate/lint/preflight 零 error ∧ match ≥ 95 ∧ heightDelta=0 ∧ widthDelta=0 ∧ |contentOffset1x| ≤ 2）。gate 是脚本判的，正文只能引用它的 verdict / failed，不得自行宣布达标。像素对比按并集画布算，删内容 / 高度塌缩只会降分，不可能凑分。
+   报告还带：contentOffset1x + contentOffsetHint（内容整体平移时先修对齐，别逐行调间距）、lint.warningDetails、preflight.details、renderImage（渲染原图路径）、diffImageNote（并排图顶部色条是工具标题栏，不是卡片内容）、stalled（连续多轮 match 与热区不变）。
+   **stalled 出现 ⇒ 停止 --set 盲调，照 stalled.hint 换证据链**：跑 diff_bands.mjs（args=["--id","<落点卡>","--design","<bundle>/card-N.png","--render","<报告 renderImage>"]）拿逐带 dy/dh 与分区主色，再对照 references/generation_pitfalls.md 的「类型开关+值 / 静默丢弃」清单。实测事故：match 卡 73% 连调 6 轮无效，根因是 6 处 margin 漏 marginType，diff_bands 一轮就能指认。
+   match 不升反降、heightDelta 非 0、或 hotspots 集中在原本已有内容的区域 ⇒ 说明在删内容凑分：回退该轮 --set 换思路。diffImage 每轮重写（报告里的路径），只给用户预览。
+   **取证禁令**：禁止用 shell_exec 写 node -e pngjs 像素脚本（行扫描 / 取色 / 自算 diff）——diff_bands.mjs、报告 hotspots、contentOffset1x、审计 colors/bgGradientHint 已经覆盖全部取证需求，实测手写脚本 4 次全是浪费步数；禁止 fs_read 任何图片；禁止在 S5 之前调 card_screenshot（渲染还没意义）；禁止把 src/cards/<卡>/<卡>.png 当渲染图（那是设计稿归档，渲染原图是报告里的 renderImage）。
+   每轮用一两句正文汇报：gate.verdict / match% / heightDelta / 这轮修了什么，不要闷头连调。
+S6 收尾门禁：① skill_exec script=skills/dsl-card-generator/scripts/check_fidelity.mjs，args=["--spec","<bundle>/spec.json","--schema","src/cards/<落点卡>/schema.json","--card","N"]，按它报的文本缺失 / 字号偏差 / 颜色偏差修到无 ERROR；② skill_exec script=skills/dsl-card-generator/scripts/iterate.mjs，args=["--gate","--out","src/cards/<落点卡>/"] 拿机器判定（读最近一轮落盘报告，schema 在报告之后被改过会直接判 FAIL）。
+   正文汇报必须**逐字引用 --gate 的 verdict 与 failed 列表** + 落点卡 + 补了哪些切图 + 回滚方式。gate 未过禁止写「门禁全绿 / 已完成 / 验收通过」，必须列出未达标项、原因与下一步；禁止把未达标归因于「测量噪声 / 工具合成产物」——pixelDiff 只用渲染原图与设计原图，合成图色条不参与计算（见 diffImageNote）。
+   绑定对齐：check_fidelity 会按 data.json / defaultValue 把 $ 绑定解析回文案再对齐——报 missing-text 而该文本已绑定 ⇒ 是 mock 与设计稿不一致，改 defaultValue / data.json，**不是拆回字面量**。收尾自查：bindHints 每一项要么已绑定、要么正文说明为何保持字面量。
+${vision ? '你有视觉能力：S5 里 match 不达标可直接读注入的并排对比图定位差异（哪一行 / 哪个颜色 / 哪段间距）再 --set；数值指标仍是收敛判据，图只用于定位。' : '当前模型无视觉：不要声称看过图；S2 的审计值 + S5 的数值指标就是你的眼睛，所有尺寸颜色文案取审计值，缺时按 references/ui_fidelity_rules.md 降级规则处理，禁止凭空估数值。'}
+步数不设硬顶（除非用户在设置里配了上限），但有四道闸：①连续多轮「同工具 + 同参数」会被判定原地打转并强制收尾 ②单轮墙钟到点会强制收尾 ③每 24 步会收到一次收敛提醒 ④单轮上下文超预算时**早期工具结果会被折叠成摘要**并标注「已折叠」——看到折叠标记就用工具重读，不要拿摘要当结论。所以别把额度当免费：S2 / S3 / S5 各尽量一次调用解决；同类信息只读一次；收到重复调用警告就立刻换证据链（diff_bands.mjs / generation_pitfalls.md），不要把同一条调用原样再发一次；被中止过的轮次按上下文里的中止标记从中断处继续，不要从零重做。
+
+## 按需参考索引（skill_read）
+${lines.join('\n')}`
+  _systemPromptCache = { key: cacheKey, text: _text }
+  return _text
+}
+
+/** skill_read：模型按需取参考文档，替代把整份 skill 塞进 system prompt */
+const SKILL_READ_TOOL = {
+  type: 'function',
+  function: {
+    name: 'skill_read',
+    description: '读取系统提示词「按需参考索引」中列出的建卡参考文档（文件名），返回正文（超长截断）。只在需要时读，不要全读。',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string', description: '索引中的文件名，如 expression_engine.md' } },
+      required: ['path'],
+    },
+  },
+}
+const SKILL_READ_MAX = 30000
+
+/** 大卡定位/最小写工具：card_read 只回喂 12KB、card_write 要整包替换，
+ *  400KB 级卡片上二者都不可行（模型只能空转）。card_grep 给 JSON 路径，card_patch 按路径最小写。 */
+const CARD_GREP_TOOL = {
+  type: 'function',
+  function: {
+    name: 'card_grep',
+    description: '在卡片 schema/data 里按关键字搜键名与字符串值，返回匹配处的 JSON 点路径 + 片段（大卡定位修改点首选；card_read 的回喂有截断，看不到全卡）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '卡片 id' },
+        pattern: { type: 'string', description: '关键字，如变量名 externalText（大小写不敏感）' },
+        target: { type: 'string', enum: ['schema', 'data'], description: '默认 schema' },
+      },
+      required: ['id', 'pattern'],
+    },
+  },
+}
+const CARD_PATCH_TOOL = {
+  type: 'function',
+  function: {
+    name: 'card_patch',
+    description: '按 JSON 点路径（数组用数字段）对卡片 schema/data 做最小修改并写回；大卡必用本工具，禁止用 card_write 整包重写。路径必须先用 card_grep 拿真实路径——schema 的节点树是 view.components[].slots[].components[]（不是 view.children）。路径中段不存在会直接报错（不再静默新建分支），确要新建传 create:true。仓库根下走 card_write 管线（带历史快照与校验）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '卡片 id' },
+        patches: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string', description: 'JSON 点路径（card_grep 返回值可直接用）' },
+              value: { description: '新值（任意 JSON）' },
+            },
+            required: ['path', 'value'],
+          },
+        },
+        deletes: { type: 'array', items: { type: 'string' }, description: '要删除的 JSON 点路径' },
+        target: { type: 'string', enum: ['schema', 'data'], description: '默认 schema' },
+        create: { type: 'boolean', description: '路径中段不存在时是否新建分支（默认 false = 响亮报错）' },
+      },
+      required: ['id', 'patches'],
+    },
+  },
+}
+const GREP_MAX_HITS = 40
+
+function cardGrep(root, { id, pattern, target = 'schema' }) {
+  const file = path.join(root, 'src', 'cards', String(id || ''), target === 'data' ? 'data.json' : 'schema.json')
+  const doc = JSON.parse(fs.readFileSync(file, 'utf8'))
+  const needle = String(pattern || '').toLowerCase()
+  if (!needle) throw new Error('缺少 pattern')
+  const hits = []
+  const walk = (node, p) => {
+    if (hits.length >= GREP_MAX_HITS) return
+    if (Array.isArray(node)) {
+      node.forEach((v, i) => walk(v, `${p}.${i}`))
+      return
+    }
+    if (node && typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        const cp = p ? `${p}.${k}` : k
+        if (k.toLowerCase().includes(needle)) {
+          hits.push({ path: cp, kind: 'key', snippet: typeof v === 'string' ? v.slice(0, 120) : typeof v })
+        } else if (typeof v === 'string' && v.toLowerCase().includes(needle)) {
+          hits.push({ path: cp, kind: 'value', snippet: v.slice(0, 120) })
+        }
+        if (hits.length >= GREP_MAX_HITS) return
+        walk(v, cp)
+      }
+      return
+    }
+  }
+  walk(doc, '')
+  return { id, target, pattern, hits, truncated: hits.length >= GREP_MAX_HITS }
+}
+
+function applyByPath(doc, p, setter, { create = false } = {}) {
+  const segs = String(p).split('.').filter(Boolean)
+  if (!segs.length) throw new Error(`非法路径：${p}`)
+  let cur = doc
+  for (let i = 0; i < segs.length - 1; i++) {
+    const k = segs[i]
+    const next = Array.isArray(cur) ? cur[Number(k)] : cur[k]
+    if (next == null || typeof next !== 'object') {
+      // 历史事故：静默 auto-create 让猜错的路径（如 view.children.…）往 schema 里塞垃圾分支，
+      // 补丁「成功」但目标节点纹丝不动。现在响亮报错，逼模型回 card_grep 拿真实路径。
+      if (!create) {
+        throw new Error(
+          `路径中段不存在：${segs.slice(0, i + 1).join('.')}（完整路径 ${p}）。schema 节点树是 view.components[].slots[].components[]，先 card_grep 定位再 patch；确要新建分支传 create:true`,
+        )
+      }
+      cur[k] = /^\d+$/.test(segs[i + 1]) ? [] : {}
+    }
+    cur = Array.isArray(cur) ? cur[Number(k)] : cur[k]
+  }
+  setter(cur, segs[segs.length - 1])
+}
+
+async function cardPatch(root, args, dispatch) {
+  const { id, patches = [], deletes = [], target = 'schema' } = args || {}
+  if (!Array.isArray(patches) || !patches.length) throw new Error('缺少 patches')
+  const file = path.join(root, 'src', 'cards', String(id || ''), target === 'data' ? 'data.json' : 'schema.json')
+  const doc = JSON.parse(fs.readFileSync(file, 'utf8'))
+  const create = args.create === true
+  for (const pt of patches) applyByPath(doc, pt.path, (obj, k) => (obj[k] = pt.value), { create })
+  for (const d of deletes) applyByPath(doc, d, (obj, k) => delete obj[k], { create })
+  // 仓库根：走 card_write 管线（历史快照 + validate/render_status）；其它根（测试/自定义）直接落盘
+  if (path.resolve(root) === REPO_ROOT && dispatch) {
+    const res = await dispatch('card_write', { id, [target]: doc })
+    return { ok: true, via: 'card_write', patches: patches.length, deletes: deletes.length, write: res }
+  }
+  fs.writeFileSync(file, JSON.stringify(doc, null, 2) + '\n', 'utf8')
+  return { ok: true, via: 'disk', patches: patches.length, deletes: deletes.length, file }
+}
+
+
+/** 仓库内任意文件只读：补齐 card_read / skill_read 覆盖不到的 AGENTS.md、docs、tools 等 */
+const FS_READ_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fs_read',
+    description: '读取仓库根（或用户挂载目录）内的任意文本文件，返回正文（超长截断）。读卡片优先 card_read / card_grep；读参考文档优先 skill_read；本工具用于其余仓库文件与挂载附件。',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '相对仓库根的路径或绝对路径（挂载目录内）' },
+        maxChars: { type: 'number', description: '返回上限，默认 20000 字符' },
+      },
+      required: ['path'],
+    },
+  },
+}
+
+/**
+ * 本地命令执行（默认注册；是否逐次确认由 AI_AUTO_APPROVE 决定，默认 all=免确认；AI_ALLOW_SHELL=0 可整体关闭）。
+ * 描述里的白名单实时取自 SHELL_ALLOW_BIN —— 硬编码一份清单注定和实现漂移（曾经漏了 cd，
+ * 模型照着旧清单写命令反被自己的工具描述误导）。
+ */
+function shellTool(auto = false) {
+  return {
+    type: 'function',
+    function: {
+      name: 'shell_exec',
+      description: `在仓库根经真实 shell（/bin/sh -c）执行一条本地命令并返回输出（60s 超时）。cwd 已是仓库根，命令里不要写 cd（要切目录用脚本自己的 --src / --out 参数）。支持管道 |、链接 && / ;、重定向、引号与循环 / 条件 / 子shell / $( ) 等 shell 语法；其中真正执行的每个外部命令（含管道各段与替换体内部）必须在白名单（${[...SHELL_ALLOW_BIN].join(' / ')}）。复制文件用 fs_copy，不要试 cp / mv。白名单**不含**图像处理命令（sips / convert / magick：裁切图用 skill_exec 跑 crop_slices.mjs）与解释器（python / python3：Python 脚本用 skill_exec）。${auto ? '本仓库已设为免确认：调用即执行，不要停下来等用户批准。' : '每次调用都会先弹给用户确认，被拒会返回错误。'}用于跑测试、构建、git 等结构化卡片工具覆盖不了的操作。`,
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: '命令与参数，如：node tools/version-bump.mjs --check "fix(x): y"' },
+        },
+        required: ['command'],
+      },
+    },
+  }
+}
+
+/**
+ * skill_exec：跑 skills/ 下的技能脚本（node / python3）。
+ *
+ * 为什么必须有它：设计稿建卡的上游管线（sketch-spec-to-card 的 parse_meaxure.py / cluster_states.py）
+ * 是 Python，而 shell_exec 默认不注册、白名单里也没有 python —— 网页助手此前**根本无法**执行
+ * 「先 sketch-spec-to-card 前处理、再 dsl-card-generator 生成」这条链路，只能干读 preview/ 整图。
+ * 与 shell_exec 的区别：script 必须是 skills/<skill>/scripts/ 下的 .mjs/.js/.py（路径形状硬校验），
+ * 参数以数组传入、不经 shell 解析，cwd 固定仓库根 —— 风险面小得多；默认策略（AI_AUTO_APPROVE=all）
+ * 让它免确认执行，建卡流水线才不必每步都等用户点「允许」；shell_exec 默认仍逐次审批。
+ */
+function skillExecTool(auto = false) {
+  return {
+    type: 'function',
+    function: {
+      name: 'skill_exec',
+      description: `执行 skills/<skill>/scripts/ 下的技能脚本（.mjs/.js 用 node、.py 用 python3），cwd=仓库根，返回 exit code + stdout/stderr（默认 180s 超时）。设计稿建卡必用：sketch-spec-to-card 的 parse_meaxure.py（--list 列画板 / --indices 选画板 / --build 出要素包）与 cluster_states.py；dsl-card-generator 的 spec_audit.mjs（一步审计带出 bands/gaps/texts/slices/missing）、crop_slices.mjs（从聚焦截图派生缺失切图：--from-audit 或 --crop 名@x,y,w,h）、spec_tree.mjs（spec.json 压缩成层级树）、expand_ir.mjs（IR 展开成 schema，自带 autofix + validate）、iterate.mjs（--set 点路径微调 + 渲染 + 并集像素对比 + preflight + gate 机器门禁的唯一入口；--gate 单独判收敛）、diff_bands.mjs（渲染 vs 设计的逐带 dy/dh / 内容底边 / 分区主色，凡「看起来不一致」先跑它拿证据，支持 --render 复用渲染原图）、preflight.mjs（Pre-flight Checklist 的机械化 10 条）、render_card.mjs（离线渲染原图）、describe_card.mjs / extract_subtree.mjs（反向读存量卡 / 抽子树范式，替代手写 node -e 遍历 schema）、check_fidelity.mjs（还原度门禁）等。${auto ? '本仓库已设为免确认：调用即执行，按协议连跑到底，不要停下来等用户批准，也不要因为怕要授权而改用 shell_exec。' : '每次调用先请用户确认（用户可选「本回合不再询问」）。'}`,
+      parameters: {
+        type: 'object',
+        properties: {
+          script: { type: 'string', description: '仓库根相对路径，如 skills/sketch-spec-to-card/scripts/parse_meaxure.py' },
+          args: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '参数数组，如 ["--src","/path/含空格 也作为一项","--list"]；不要自己加引号，也不要拼成一整条命令字符串',
+          },
+          timeoutMs: { type: 'number', description: '超时毫秒，默认 180000，最大 600000' },
+        },
+        required: ['script'],
+      },
+    },
+  }
+}
+
+/** 脚本路径形状：只认 skills/<skill>/scripts/ 下的 .mjs/.cjs/.js/.py，杜绝拿它当通用命令执行器 */
+const SKILL_SCRIPT_RE = /^skills\/[^/]+\/scripts\/[^/].*\.(mjs|cjs|js|py)$/
+const SKILL_EXEC_MAX_ARGS = 60
+const SKILL_EXEC_DEFAULT_TIMEOUT = 180000
+const SKILL_EXEC_MAX_TIMEOUT = 600000
+let _pythonBin = ''
+
+/** Python 解释器：尊重 DSL_CARD_PYTHON，否则探测 python3 / python（管线脚本只用标准库，无需装依赖） */
+function pythonBin() {
+  if (process.env.DSL_CARD_PYTHON) return process.env.DSL_CARD_PYTHON
+  if (_pythonBin) return _pythonBin
+  for (const bin of ['python3', 'python']) {
+    try {
+      if (spawnSync(bin, ['--version'], { stdio: 'ignore' }).status === 0) {
+        _pythonBin = bin
+        return _pythonBin
+      }
+    } catch {
+      /* 换下一个候选 */
+    }
+  }
+  _pythonBin = 'python3'
+  return _pythonBin
+}
+
+function resolveSkillScript(root, script) {
+  const rel = String(script || '').trim().replace(/\\/g, '/').replace(/^\.\//, '')
+  if (!rel) throw new Error('缺少 script')
+  if (!SKILL_SCRIPT_RE.test(rel)) {
+    throw new Error(`只能执行 skills/<skill>/scripts/ 下的 .mjs / .js / .py 脚本（收到：${rel}）；其余命令用 shell_exec`)
+  }
+  const abs = path.resolve(root, rel)
+  if (!abs.startsWith(path.join(root, 'skills') + path.sep)) throw new Error('非法路径：脚本必须在仓库 skills/ 目录内')
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`脚本不存在：${rel}`)
+  return { rel, abs, bin: path.extname(abs).toLowerCase() === '.py' ? pythonBin() : 'node' }
+}
+
+function normalizeSkillArgs(args) {
+  const list = Array.isArray(args) ? args : args === undefined || args === null || args === '' ? [] : [args]
+  if (list.length > SKILL_EXEC_MAX_ARGS) throw new Error(`参数过多（上限 ${SKILL_EXEC_MAX_ARGS}）`)
+  return list.map((a) => {
+    if (typeof a === 'number' || typeof a === 'boolean') return String(a)
+    if (typeof a !== 'string') throw new Error('args 必须是字符串数组')
+    if (/[\r\n\0]/.test(a)) throw new Error('args 含非法控制字符（换行 / NUL）')
+    return a
+  })
+}
+
+/**
+ * 命令白名单：只放读多写少、可预期的入口（含常用只读过滤器，管道才有意义）；真正的安全闸是审批策略。
+ * cd 在白名单里：它自己不执行任何东西，而模型很爱写 `cd <仓库根> && node …`（训练语料习惯），
+ * 拦掉只会换来一轮无谓的重试；`cd x && rm -rf y` 依旧被 rm 那一段挡住，逐段校验没有被削弱。
+ */
+const SHELL_ALLOW_BIN = new Set([
+  'npm', 'node', 'npx', 'git', 'rg', 'grep', 'cat', 'ls', 'pwd', 'cd', 'find',
+  'head', 'tail', 'wc', 'sort', 'uniq', 'cut', 'tr', 'sed', 'awk', 'jq', 'diff', 'echo', 'mkdir',
+])
+
+/**
+ * 白名单外的高频误用 → 指回范式工具。
+ * 报错文本是模型唯一的路标：只说「不在白名单」它下一轮会换个同类命令再撞一次
+ * （实测：裁切图被拒后仍想用 sips / convert 硬来，而正路是 crop_slices.mjs）。
+ */
+const SHELL_BIN_HINTS = {
+  sips: '图像裁剪 / 缩放 / 转格式一律用 skill_exec skills/dsl-card-generator/scripts/crop_slices.mjs（--crop <名>@x,y,w,h 传卡片本地 1x 坐标，或 --from-audit <审计JSON>），它自己按 design 宽 ÷ 卡宽换算像素；渲染截图由 iterate.mjs 产出',
+  convert: '同上：图像处理走 skill_exec crop_slices.mjs，不要用 ImageMagick',
+  magick: '同上：图像处理走 skill_exec crop_slices.mjs，不要用 ImageMagick',
+  identify: '图片尺寸 / 切图信息看 spec_audit.mjs 的审计 JSON（slices[].px、missing[].crop），不要自己跑图像命令',
+  ffmpeg: '本工具链不处理音视频',
+  python: 'Python 脚本用 skill_exec（script=skills/<skill>/scripts/x.py，args 传参数数组）：白名单不含解释器',
+  python3: 'Python 脚本用 skill_exec（script=skills/<skill>/scripts/x.py，args 传参数数组）：白名单不含解释器',
+  rm: '不要删文件：覆盖写用 fs_write，卡片改动用 card_patch / card_write，历史版本由 .history 快照保管',
+  mv: '移动 = fs_copy 复制到新落点；删旧文件不支持（留给用户或 .history 快照）',
+  cp: '复制文件用 fs_copy 工具（from / to 两个路径参数，二进制安全、自动建父目录）；改写文本内容才用 fs_write（仅草稿区）',
+  dir: 'Windows 下用 ls 列目录（Git Bash 自带）；或直接用自己的领域知识判断文件位置',
+  mkdir: '目录由写入工具自动创建（fs_write / fs_copy / crop_slices.mjs --out），不需要手动 mkdir',
+  touch: '写空文件用 fs_write（content 传空串，仅草稿区）；仓库内落占位文件用 fs_copy',
+  curl: '助手不联网：网关调用由后端代理，不要自己发 HTTP 请求',
+  wget: '助手不联网：网关调用由后端代理，不要自己发 HTTP 请求',
+  open: '不要打开 GUI 程序：产物路径写进正文回复，用户自己点开',
+}
+
+/** 替换体在「扁平段」里的占位符：整块替换体已单独收集校验，段内定位命令词时不该再看它内部 */
+const SUBST_PLACEHOLDER = '\u0000sub\u0000'
+
+/**
+ * sh 结构走查：一趟扫出「引号 / 转义 / 替换体嵌套」三态下的分段与替换体，静态闸的几个口径共用它。
+ * 返回：
+ * - flatSegs：顶层按 ; && || | 与换行的分段，且每个替换体整块折叠成占位符 ——
+ *   替换体 / 子shell 内部的分隔符是它的参数、不切段；折叠后才不会把 `M=$(find vendor x | head -1)`
+ *   赋值体里的 vendor 当段首命令拦掉（实测误拒源）
+ * - subs：所有替换体 / 子shell 正文（含嵌套、含双引号内的），quoted 标记供报错话术区分
+ *
+ * sh 语义三条（旧实现三处各漏一条，实测各自造成一次误拒或一次白名单绕过）：
+ * 1. 反斜杠转义：单引号内 \ 是字面量，其余场景 \ 吃掉下一个字符 —— `grep "\"a\"|b"` 的引号是闭合的
+ * 2. 双引号不阻止展开：`"$(cmd)"` 与引号内反引号照跑，必须当替换体收走（漏了就是绕过）
+ * 3. 替换体 / 子shell 内部的 ; | && 不是顶层分隔符
+ */
+function scanShellText(text) {
+  const s = String(text)
+  const flatSegs = []
+  const subs = []
+  let cur = ''
+  let flat = ''
+  let quote = ''
+  /** 替换体栈：{ closer, buf, quoted, savedQuote }；非空即处于替换体 / 子shell 内部 */
+  const frames = []
+  /** 写进原文（cur 供 & / 重定向判定 + 所有未闭合替换体正文）：开合符属于外层正文，不属于替换体自身 */
+  const verb = (str) => {
+    cur += str
+    for (const f of frames) f.buf += str
+  }
+  /** 写进原文与扁平两份（扁平只收顶层：替换体内部在扁平段里已整块折叠成占位符） */
+  const lit = (str) => {
+    verb(str)
+    if (!frames.length) flat += str
+  }
+  const splitTop = () => {
+    flatSegs.push(flat)
+    cur = ''
+    flat = ''
+  }
+
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    // ① 转义：单引号内 \ 才是字面量，其余场景 \ 吃掉下一个字符（\" \\ \$ \; \| \( 一律按字面走）
+    if (ch === '\\' && quote !== "'") {
+      const next = s[i + 1]
+      if (next === undefined) {
+        lit(ch)
+        continue
+      }
+      lit(ch + next)
+      i++
+      continue
+    }
+    // ② 引号内：只有「双引号里的 $( 与反引号」是特殊结构，其余字符原样
+    if (quote) {
+      if (ch === quote) {
+        quote = ''
+        lit(ch)
+        continue
+      }
+      if (quote !== '"' || !(ch === '`' || s.startsWith('$(', i))) {
+        lit(ch)
+        continue
+      }
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+      lit(ch)
+      continue
+    }
+    const frame = frames.length ? frames[frames.length - 1] : null
+    // ③ 替换体 / 子shell 开合（引号外，或双引号内命中 ②）
+    if (frame && ch === frame.closer) {
+      subs.push({ text: frame.buf, quoted: frame.quoted })
+      frames.pop()
+      quote = frame.savedQuote // 出替换体：恢复外层引号状态（"$(…)" 的收尾双引号还要靠它配对）
+      verb(ch)
+      continue
+    }
+    const dollar = s.startsWith('$(', i)
+    const back = ch === '`'
+    const paren = !quote && ch === '('
+    if (dollar || back || paren) {
+      const first = !frames.length
+      verb(dollar ? '$(' : ch)
+      // 进替换体：外层引号状态挂起（sh 里 "$(…)" 的替换体按新上下文重新解析，
+      // 外层双引号不跟着进去 —— 否则替换体里的 ) 会被当普通字符，整条命令误报「未闭合」）
+      frames.push({ closer: back ? '`' : ')', buf: '', quoted: Boolean(quote), savedQuote: quote })
+      quote = ''
+      if (dollar) i++
+      if (first) flat += SUBST_PLACEHOLDER
+      continue
+    }
+    // ④ 顶层分隔符与后台 &（替换体内部不切段）
+    if (!frames.length && !quote) {
+      const two = s.slice(i, i + 2)
+      if (two === '&&' || two === '||') {
+        splitTop()
+        i++
+        continue
+      }
+      if (ch === ';' || ch === '|' || ch === '\n') {
+        splitTop()
+        continue
+      }
+      if (ch === '&') {
+        // 2>&1 / >&2 / <&3 里的 & 是重定向语法不是后台：前一个字符是 > / < 时原样保留
+        const head = cur.trimEnd()
+        if (head.endsWith('>') || head.endsWith('<')) {
+          lit(ch)
+          continue
+        }
+        if (s[i + 1] === '>') {
+          throw new Error('不支持 &> 写法（bash 专属）：请改成 > file 2>&1')
+        }
+        throw new Error('不支持后台运行（单独的 &）：去掉 & 同步执行，或把长任务交给 dev server')
+      }
+    }
+    lit(ch)
+  }
+  if (quote) throw new Error('命令引号未闭合：请补全或去掉引号')
+  if (frames.length) throw new Error('命令替换 / 子shell 未闭合：$( 与 ( 要有配对的 )，反引号要成对')
+  flatSegs.push(flat)
+  return { flatSegs: flatSegs.map((x) => x.trim()).filter(Boolean), subs }
+}
+
+/** 顶层分段的扁平版：替换体折叠成占位符，供 segmentCommandWord 定位段首真正执行的外部命令 */
+function shellFlatSegments(command) {
+  return scanShellText(command).flatSegs
+}
+
+/**
+ * shell 语法词：控制结构与纯内置词。静态闸要查的是「真正被执行的外部命令」，
+ * 这些词自己不启动外部进程，不能当段首命令拦——否则 `for f in *.png; do node crop.mjs "$f"; done`
+ * 会在 for / do / done 段连撞三次，模型每撞一次换一种写法再撞（实测复发源）。
+ */
+const SHELL_SYNTAX_WORDS = new Set([
+  'for', 'in', 'do', 'done', 'while', 'until', 'if', 'then', 'elif', 'else', 'fi',
+  'case', 'esac', 'select', 'function', 'time', '{', '}', '(', ')', '!',
+  'export', 'local', 'readonly', 'declare', 'typeset', 'set', 'unset', 'shift',
+  'source', '.', 'return', 'break', 'continue', 'true', 'false', ':',
+])
+
+/** 这些词之后本段其余部分全是「条件 / 列表 / 内置参数」，不再出现命令词；$( ) 替换仍由全局扫描兜住 */
+const SHELL_TAIL_WORDS = new Set(['in', 'test', '[', '[[', 'read', 'printf'])
+
+/**
+ * 取一个分段里「真正被执行的外部命令」：跳过语法词、for 循环变量、赋值前缀、重定向及其目标。
+ * 入参应是扁平段（shellFlatSegments 的产物：替换体已折叠成占位符），
+ * `case` 后第一个词是主语、`for` 后第一个词是循环变量，都跳过。整段无外部命令返回 null
+ * （纯语法 / 纯赋值 / 纯注释段不该触发白名单）。
+ */
+function segmentCommandWord(seg) {
+  // 也接受原文段：含替换体先折叠，否则赋值体里的词会被当成段首命令（M=$(find vendor x) → 无外部命令）
+  const flat = seg.includes('$(') || seg.includes('`') ? shellFlatSegments(seg)[0] || '' : seg
+  const toks = tokenizeCommand(flat)
+  let skipNext = false
+  let tail = false
+  for (let i = 0; i < toks.length; i++) {
+    if (tail) return null
+    let t = toks[i]
+    if (skipNext) {
+      skipNext = false
+      continue
+    }
+    // 子shell 左括号可能粘在命令词上：(node x) → (node
+    t = t.replace(/^\(+/, '').replace(/\)+$/, '')
+    if (!t) continue
+    // 替换体占位符不是命令词：整块替换体由 subs 那组单独过闸
+    if (t.startsWith(SUBST_PLACEHOLDER)) return null // 段首就是替换体：真正跑什么由替换结果决定，静态闸不猜
+    if (t.includes(SUBST_PLACEHOLDER)) continue // 赋值 / 参数里带替换体：M=$(…)、--out=$(…)
+    // TAIL 先判：in / [ / test 等同时是语法词，但语义是「本段其余全是列表 / 条件参数」
+    if (SHELL_TAIL_WORDS.has(t)) {
+      tail = true
+      continue
+    }
+    if (SHELL_SYNTAX_WORDS.has(t)) {
+      if (t === 'for' || t === 'case') skipNext = true
+      continue
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) continue // VAR=value 前缀（含整段纯赋值）
+    if (/^[A-Za-z_][A-Za-z0-9_]*\(\)$/.test(t)) continue // 函数定义 f()
+    if (/^[0-9]*(>>|>|<)/.test(t)) {
+      if (/^[0-9]*(>>|>|<)$/.test(t)) i++ // 独立重定向运算符：下一个 token 是目标
+      continue
+    }
+    return t
+  }
+  return null
+}
+
+/**
+ * 提取命令替换 / 子shell 体：$( ... )、`...`、( ... )（引号 / 转义感知、支持嵌套）。
+ * 替换体内的命令同样要过白名单——`echo $(rm -rf x)` 不能靠段首检查漏过去；
+ * 双引号内的 `"$(rm -rf x)"` 同理（sh 里双引号不阻止展开，旧实现漏了这条 = 白名单可绕）。
+ */
+function shellSubCommands(command) {
+  return scanShellText(command).subs.map((sub) => sub.text)
+}
+
+/**
+ * 白名单静态闸：查「每个真正被执行的外部命令」而非「每段第一个词」。
+ * 循环 / 条件 / 子shell / $( ) 等 shell 语法都可用，但语法之内跑的外部命令（含管道各段、
+ * 替换体内部）逐个过白名单，ls; rm -rf x 依旧在 rm 处被拦。
+ */
+function assertShellAllowlist(command) {
+  const top = scanShellText(command)
+  // 顶层用扁平段（替换体折叠成占位符，别把赋值体里的词当段首命令）；每个替换体再走一遍同样的闸
+  const segGroups = [
+    { segs: top.flatSegs, quotedSub: false },
+    ...top.subs.map((sub) => ({ segs: scanShellText(sub.text).flatSegs, quotedSub: sub.quoted })),
+  ]
+  for (const group of segGroups) {
+    for (const seg of group.segs) {
+      const head = segmentCommandWord(seg)
+      if (!head) continue
+      // 整段是 shell 注释（# 开头）：/bin/sh 会忽略它，静态闸不该把它当命令拦
+      // （模型爱在多条命令之间插 `# 步骤说明` 注释行，此前每插一行就撞一次白名单）
+      if (head.startsWith('#')) continue
+      if (/^[<>]/.test(head)) {
+        throw new Error(`不支持以重定向开头的片段：${seg.slice(0, 60)}（把 > / < 放到命令后面）`)
+      }
+      if (!SHELL_ALLOW_BIN.has(head)) {
+        const hint = SHELL_BIN_HINTS[head]
+        throw new Error(
+          `命令不在白名单：${head}（允许：${[...SHELL_ALLOW_BIN].join(' / ')}）。循环 / 条件 / 子shell / $( ) 等 shell 语法都支持，` +
+            `但其中真正执行的每个外部命令（含管道各段与替换体内部）都必须在白名单内` +
+            (hint ? `\n正路：${hint}` : '') +
+            (group.quotedSub
+              ? '\n（它写在双引号里：双引号内的 $( ) 与反引号会被 shell 真实执行，所以同样过闸；只想写字面文本请转义或改用单引号）'
+              : '') +
+            '\n（cwd 已是仓库根，命令里不需要 cd；换正路重试，不要把同一条命令原样再发一次）',
+        )
+      }
+    }
+  }
+}
+const SHELL_MAX_OUT = 200000
+
+/** 子进程输出回收：合并 stdout/stderr，超时杀进程，输出限量回喂 */
+function captureChild(child, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let out = ''
+    let killed = false
+    const timer = setTimeout(() => {
+      killed = true
+      child.kill('SIGKILL')
+    }, timeoutMs)
+    const onChunk = (c) => {
+      if (out.length < SHELL_MAX_OUT) out += c.toString('utf8')
+    }
+    child.stdout.on('data', onChunk)
+    child.stderr.on('data', onChunk)
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      reject(new Error(`启动失败：${e.message}`))
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      const truncated = out.length >= SHELL_MAX_OUT ? '\n…（输出过长已截断）' : ''
+      resolve(`exit=${code}${killed ? '（超时已杀）' : ''}\n${out.slice(0, 20000)}${truncated}`)
+    })
+  })
+}
+
+const SPAWN_ENV = { FORCE_COLOR: '0', NO_COLOR: '1' }
+
+/** 通用子进程执行（不经 shell）：skill_exec 等「二进制 + 参数数组」场景 */
+function spawnCapture(root, bin, argv, timeoutMs = 60000, extraEnv = {}) {
+  const child = spawn(bin, argv, { cwd: root, shell: false, env: { ...process.env, ...SPAWN_ENV, ...extraEnv } })
+  return captureChild(child, timeoutMs)
+}
+
+function findGitBash() {
+  try {
+    const pf = process.env.ProgramFiles || "C:\\Program Files"
+    const base = path.join(pf, "Git", "usr", "bin")
+    const exe = path.join(base, "bash.exe")
+    if (fs.existsSync(exe)) return { exe, usrBin: base }
+  } catch { /* ignore */ }
+  const alts = [
+    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+    "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe",
+    path.join(process.env.LOCALAPPDATA || "", "Programs", "Git", "usr", "bin", "bash.exe"),
+  ]
+  for (const p of alts) { if (fs.existsSync(p)) return { exe: p, usrBin: path.dirname(p) } }
+  return null
+}
+
+/** 经真实 shell 执行（posix = /bin/sh -c）：管道 / 链接 / 重定向 / 引号都按 shell 语义来 */
+function spawnShell(root, command, timeoutMs = 60000, extraEnv = {}) {
+  const isWin = process.platform === "win32"
+  const bash = isWin ? findGitBash() : null
+  const env = { ...process.env, ...SPAWN_ENV, ...extraEnv }
+  if (bash) {
+    env.PATH = bash.usrBin + ";" + (process.env.PATH || "")
+    const child = spawn(bash.exe, ["-c", command], { cwd: root, shell: false, env })
+    return captureChild(child, timeoutMs)
+  }
+  const child = spawn(command, { cwd: root, shell: true, env })
+  return captureChild(child, timeoutMs)
+}
+
+/**
+ * 空白分词但识别单 / 双引号与反斜杠转义（引号成对剥掉、\x 取字面 x）：
+ * 朴素 split 会让 `cat "a b.png"` 的路径带上字面引号而 ENOENT；
+ * 不认转义则会把 `grep -nE "\"a\"|b" f` 判成引号未闭合（sh 里它合法，实测误拒源）。
+ */
+function tokenizeCommand(command) {
+  const s = String(command)
+  const out = []
+  let cur = ''
+  let quote = ''
+  let open = false
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    // 单引号内 \ 是字面量，其余场景 \ 吃掉下一个字符
+    if (ch === '\\' && quote !== "'") {
+      const next = s[i + 1]
+      cur += next === undefined ? ch : next
+      if (next !== undefined) i++
+      open = true
+      continue
+    }
+    if (quote) {
+      if (ch === quote) quote = ''
+      else cur += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      open = true
+      continue
+    }
+    if (/\s/.test(ch)) {
+      if (open || cur) {
+        out.push(cur)
+        cur = ''
+        open = false
+      }
+      continue
+    }
+    cur += ch
+    open = true
+  }
+  if (quote) throw new Error('命令引号未闭合：请补全或去掉引号')
+  if (open || cur) out.push(cur)
+  return out
+}
+
+function execShell(root, command, timeoutMs = 60000) {
+  const cmd = String(command || '').trim()
+  if (!cmd) throw new Error('命令为空')
+  // 静态闸只查「每段首个命令」：引号里的分号 / 管道符是参数不是元字符，不再误伤 node -e "…;…"
+  assertShellAllowlist(cmd)
+  return spawnShell(root, cmd, timeoutMs)
+}
+
+/** 路径闸：解析成绝对路径并确认落在「仓库根 / 本次挂载目录」内，越界即拒（杜绝任意路径读盘） */
+function resolveInsideRoots(root, raw, extraRoots = [], verb = '读') {
+  const s = String(raw || '').trim()
+  if (!s) throw new Error('缺少 path')
+  const abs = path.resolve(path.isAbsolute(s) ? s : path.join(root, s))
+  const roots = [root, ...extraRoots.filter(Boolean)]
+  if (!roots.some((r) => abs === r || abs.startsWith(r + path.sep))) {
+    throw new Error(`只能${verb}仓库根或本次挂载目录内的路径`)
+  }
+  return abs
+}
+
+/** 只读文件：限定仓库根 + 用户挂载目录；目录 / 图片给「换哪个工具」的可操作提示，不浪费步数 */
+function fsRead(root, { path: p, maxChars = 20000 }, extraRoots = []) {
+  const abs = resolveInsideRoots(root, p, extraRoots)
+  if (!fs.existsSync(abs)) throw new Error(`路径不存在：${p}`)
+  const st = fs.statSync(abs)
+  if (st.isDirectory()) throw new Error(`这是目录不是文件：${p}（列目录内容请用 fs_list）`)
+  if (IMAGE_EXT.has(path.extname(abs).toLowerCase())) {
+    return `图片文件：${abs}（${Math.round(st.size / 1024)}KB）。图像不会注入模型上下文（当前网关不支持多模态），已在对话面板中给用户预览；需要它的信息请读同目录的 spec.json / spec.md / prompt.md 标注。`
+  }
+  if (st.size > 4 * 1024 * 1024) throw new Error('文件大于 4MB：请改用 card_grep 定位或分段读取')
+  const text = fs.readFileSync(abs, 'utf8')
+  const cap = Number(maxChars) > 0 ? Number(maxChars) : 20000
+  return text.length <= cap ? text : `${text.slice(0, cap)}\n…（已截断，省略 ${text.length - cap} 字符）`
+}
+
+/**
+ * fs_write：只写 .cache/ai-scratch/ 草稿区。
+ *
+ * 为什么需要：设计稿建卡若让模型一次性吐整份 schema.json，光参数就要上万 token，
+ * 实测会被 max_tokens 截断（工具参数 JSON 半截 → 解析失败 → 整轮白跑）。
+ * 正路是模型写「紧凑 IR」（比 schema 小 4-5 倍）到草稿区，再由 expand_ir.mjs 展开成
+ * schema.json + data.json（自带 autofix / validate / lint）。草稿区在 .cache/ 下，不入库。
+ */
+const FS_WRITE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fs_write',
+    description:
+      '把 UTF-8 文本写入仓库草稿区 .cache/ai-scratch/（不入库）。主要用途：写「紧凑 IR」JSON（字段契约见 skill_read ir-format.md），再用 skill_exec 跑 skills/dsl-card-generator/scripts/expand_ir.mjs --ir <草稿路径> --out src/cards/<id>/ 展开成完整 schema（自带 autofix+validate+lint）。只能写草稿区；改卡片内容用 card_write / card_patch。',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: '草稿文件名，如 riskAssessTip.ir.json' },
+        content: { type: 'string', description: '文件内容（文本）' },
+      },
+      required: ['name', 'content'],
+    },
+  },
+}
+
+const SCRATCH_RELPATH = path.join('.cache', 'ai-scratch')
+const FS_WRITE_MAX_BYTES = 2 * 1024 * 1024
+
+function fsWrite(root, { name, content = '' }) {
+  const rel = String(name || '').trim().replace(/^[/\\]+/, '')
+  if (!rel) throw new Error('缺少 name')
+  const scratch = path.join(root, SCRATCH_RELPATH)
+  const abs = path.resolve(scratch, rel)
+  if (abs !== scratch && !abs.startsWith(scratch + path.sep)) {
+    throw new Error('非法文件名：只能写 .cache/ai-scratch/ 草稿区内的路径')
+  }
+  const text = String(content ?? '')
+  const bytes = Buffer.byteLength(text, 'utf8')
+  if (bytes > FS_WRITE_MAX_BYTES) throw new Error('内容超过 2MB 上限')
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  fs.writeFileSync(abs, text, 'utf8')
+  const relRepo = path.relative(root, abs)
+  const slicesNote = text.includes('/slices/') ? '；IR 引用 /slices/ 切图时加 --slices-dir <要素包>/slices，免拷贝' : ''
+  return `已写入 ${relRepo}（${bytes} 字节）。下一步可用 skill_exec 跑 expand_ir.mjs --ir ${relRepo} --out src/cards/<id>/` + slicesNote
+}
+
+/**
+ * fs_copy：服务端单文件复制（二进制安全）。补「cp 不在白名单、而 fs_write 只写草稿区」的缺口——
+ * 此前 cp 被拒后的提示把模型指去 fs_read + fs_write，但 fs_write 只能写 .cache/ai-scratch/，
+ * 复制到 src/slices/ 等仓库落点必然再撞墙，于是 cp → fs_write → cp 原地打转（实测复发源）。
+ * 源允许仓库根 + 本次挂载目录（与 fs_read 同口径），目的限仓库根内且禁入保护目录。
+ */
+const FS_COPY_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fs_copy',
+    description:
+      '在仓库根 / 挂载目录内复制单个文件（二进制安全，自动创建目的父目录）：from 为源路径（仓库相对或绝对，挂载目录内亦可），to 为目的路径（仓库相对，含文件名，如 src/slices/x.png、.cache/ai-scratch/x.json）。文件复制 / 搬落点一律用本工具（shell 白名单不含 cp / mv）；改写文本内容用 fs_write（仅草稿区），卡片内容用 card_write / card_patch。',
+    parameters: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: '源文件路径（仓库相对或绝对；挂载目录内亦可）' },
+        to: { type: 'string', description: '目的文件路径（仓库相对，含文件名）' },
+      },
+      required: ['from', 'to'],
+    },
+  },
+}
+
+const FS_COPY_FORBID_SEG = new Set(['.git', 'node_modules', '.history'])
+
+function fsCopy(root, { from, to }, extraRoots = []) {
+  const src = resolveInsideRoots(root, from, extraRoots, '读')
+  if (!fs.existsSync(src)) throw new Error(`源不存在：${from}`)
+  if (fs.statSync(src).isDirectory()) {
+    throw new Error(`fs_copy 只复制单个文件：${from} 是目录（批量切图裁切用 skill_exec crop_slices.mjs）`)
+  }
+  const relTo = String(to || '').trim().replace(/^[/\\]+/, '')
+  if (!relTo) throw new Error('缺少 to')
+  const dst = path.resolve(root, relTo)
+  if (dst !== root && !dst.startsWith(root + path.sep)) throw new Error('非法目的：只能复制到仓库根内')
+  const relSegs = path.relative(root, dst).split(path.sep)
+  if (relSegs.some((seg) => FS_COPY_FORBID_SEG.has(seg))) {
+    throw new Error(`目的落在保护目录（${relSegs.find((seg) => FS_COPY_FORBID_SEG.has(seg))}）：拒绝`)
+  }
+  if (fs.existsSync(dst) && fs.statSync(dst).isDirectory()) {
+    throw new Error(`目的是目录：${to}（请给含扩展名的文件名）`)
+  }
+  fs.mkdirSync(path.dirname(dst), { recursive: true })
+  fs.copyFileSync(src, dst)
+  return `已复制 ${path.relative(root, src) || from} → ${relTo}（${fs.statSync(dst).size} 字节）`
+}
+
+/** fs_list：列目录（fs_read 读不了目录，模型此前会反复撞墙浪费步数） */
+const FS_LIST_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fs_list',
+    description: '列出目录内容（仓库根或用户挂载目录内）：文件夹带 / 后缀、图片带 [img] 标记、文件带体积。要看目录里有什么就用本工具，不要用 fs_read（它只读文件）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '相对仓库根的路径或绝对路径（挂载目录内）' },
+        depth: { type: 'number', description: '递归深度，默认 1，最大 3' },
+        max: { type: 'number', description: '最多返回条目数，默认 120，最大 600' },
+      },
+      required: ['path'],
+    },
+  },
+}
+
+const FS_LIST_HARD_MAX = 600
+const FS_LIST_SKIP = new Set(['.git', 'node_modules', '.DS_Store', '__pycache__', '.cache'])
+
+/**
+ * 列目录为紧凑文本清单（文件夹在前、同名按字典序），带体积与图片标记。
+ * 同时被 /__ai/chat 复用：把挂载目录的浅层清单直接写进上下文，省掉模型自己摸索的步数。
+ */
+function fsList(root, { path: p, depth = 1, max = 120 }, extraRoots = []) {
+  const abs = resolveInsideRoots(root, p, extraRoots, '列')
+  if (!fs.existsSync(abs)) throw new Error(`路径不存在：${p}`)
+  if (!fs.statSync(abs).isDirectory()) throw new Error(`这不是目录：${p}（读文件内容请用 fs_read）`)
+  const maxDepth = Math.min(3, Math.max(1, Number(depth) || 1))
+  const cap = Math.min(FS_LIST_HARD_MAX, Math.max(1, Number(max) || 120))
+  const lines = []
+  let dirs = 0
+  let files = 0
+  let images = 0
+  const walk = (dir, level) => {
+    if (level > maxDepth || lines.length >= cap) return
+    let list
+    try {
+      list = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    list.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name, 'zh'))
+    for (const ent of list) {
+      if (lines.length >= cap) return
+      if (FS_LIST_SKIP.has(ent.name)) continue
+      const full = path.join(dir, ent.name)
+      const rel = path.relative(abs, full)
+      if (ent.isDirectory()) {
+        dirs++
+        lines.push(`${rel}/`)
+        walk(full, level + 1)
+        continue
+      }
+      let size = 0
+      try {
+        size = fs.statSync(full).size
+      } catch {
+        /* 读不到体积就按 0 显示 */
+      }
+      files++
+      const isImg = IMAGE_EXT.has(path.extname(ent.name).toLowerCase())
+      if (isImg) images++
+      lines.push(`${rel}${isImg ? ' [img]' : ''} (${size >= 1024 ? `${Math.round(size / 1024)}KB` : `${size}B`})`)
+    }
+  }
+  walk(abs, 1)
+  const head = `${abs} — 目录 ${dirs} 个 / 文件 ${files} 个（图片 ${images} 张）${lines.length >= cap ? `，已到上限 ${cap} 条（可加大 max 或 depth）` : ''}`
+  return `${head}\n${lines.join('\n')}`
+}
+
+/** 单条附件在上下文里的清单条数上限：够判形态即可，别把几百个文件名塞进 prompt */
+const ATTACH_LIST_MAX = 40
+const ATTACH_BRIEF_MAX = 6000
+
+/**
+ * 挂载附件的服务端摘要：目录浅层清单 + 「建卡输入路由」机械判定结果。
+ *
+ * 路由判定（card_route_input，离线 ~70ms）提前跑掉是本次修复的关键之一：
+ * 判定结果里已经写明 kind / preprocess.needed / next 命令，模型照抄即可，
+ * 不用再自己试错「这是不是 MeaXure 导出」「要不要先跑 sketch-spec-to-card」。
+ */
+async function describeAttachments(root, attachments, dispatch, extraRoots = []) {
+  const blocks = []
+  /** 命中设计稿形态（MeaXure 导出 / 要素包 / 单张设计稿）⇒ 本轮是多阶段建卡管线，需要更多步数额度 */
+  let designFlow = false
+  for (const a of attachments || []) {
+    const target = String(a?.path || '').trim()
+    if (!target) continue
+    const kind = a.isDir ? '文件夹' : a.isImage ? '图片' : '文件'
+    const lines = [`- ${kind}：${target}${a.note ? `（${a.note}）` : ''}`]
+    if (a.isDir) {
+      try {
+        const listing = fsList(root, { path: target, depth: 1, max: ATTACH_LIST_MAX }, extraRoots)
+        listing.split('\n').forEach((l, i) => lines.push(i === 0 ? `  清单：${l}` : `  ${l}`))
+      } catch (e) {
+        lines.push(`  清单读取失败：${String((e && e.message) || e)}`)
+      }
+    }
+    if (a.isDir || a.isImage) {
+      try {
+        const routed = await dispatch('card_route_input', { path: target })
+        const r = typeof routed === 'string' ? JSON.parse(routed) : routed || {}
+        if (r.error) {
+          lines.push(`  建卡输入路由：判定失败（${r.error}${r.message ? `：${r.message}` : ''}）—— 需要建卡时先向用户确认输入形态`)
+        } else if (r.kind) {
+          if (['meaxure-export', 'ui-bundle', 'image'].includes(r.kind)) designFlow = true
+          const parts = [`kind=${r.kind}（置信度 ${r.confidence || '?'}）`, r.workflow ? `workflow=${r.workflow}` : '']
+          if (r.preprocess) parts.push(`preprocess=${JSON.stringify(r.preprocess)}`)
+          if (Array.isArray(r.next) && r.next.length) parts.push(`next=${JSON.stringify(r.next)}`)
+          lines.push(`  建卡输入路由（服务端已机械判定，勿重复调 card_route_input）：${parts.filter(Boolean).join('；')}`)
+          if (r.note) lines.push(`  路由说明：${r.note}`)
+        }
+      } catch {
+        /* 判定器不可用不阻断对话：模型仍可自行调 card_route_input */
+      }
+    }
+    blocks.push(lines.join('\n'))
+  }
+  const text = blocks.join('\n')
+  return {
+    designFlow,
+    text: text.length <= ATTACH_BRIEF_MAX ? text : `${text.slice(0, ATTACH_BRIEF_MAX)}\n…（附件摘要过长已截断）`,
+  }
+}
+
+/** 执行审计：谁在什么时候让 AI 跑了什么（allow / deny / auto=本回合已授权 / auto-policy=设置里免确认），落 .cache/ 不入库 */
+function auditShell(root, command, ok, mode = '') {
+  try {
+    const dir = path.join(root, '.cache')
+    fs.mkdirSync(dir, { recursive: true })
+    const tag = mode ? mode : ok ? 'allow' : 'deny'
+    fs.appendFileSync(
+      path.join(dir, 'ai-audit.log'),
+      `${new Date().toISOString()}\t${tag}\t${String(command).replace(/[\r\n\t]/g, ' ')}\n`,
+      'utf8',
+    )
+  } catch {
+    /* 审计失败不阻断执行 */
+  }
+}
+
+/**
+ * 高危执行的审批闸：SSE 发 approval-request → 用户在对话里点「允许 / 本回合不再询问 / 拒绝」→ 回落继续。
+ * 「本回合不再询问」（scope=turn）很关键：设计稿管线要连跑 parse → cluster → spec_tree → check_fidelity
+ * 好几步，逐次点确认体验极差；授权范围只限当前这一轮请求，下一轮重新问。
+ * auto=true（设置里的免确认策略命中）时整段跳过：不弹审批、不挂起流，只补一条 approval-auto 让对话看得见。
+ */
+async function runGuarded(root, res, { toolName, command, approved, auto = false }, run) {
+  const label = String(command || '').trim()
+  if (auto) {
+    auditShell(root, label, true, 'auto-policy')
+    sseWrite(res, { type: 'approval-auto', toolName, command: label })
+    return run()
+  }
+  if (approved.has(toolName)) {
+    auditShell(root, label, true, 'auto')
+    return run()
+  }
+  const approvalId = `ap_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`
+  const decision = await waitForApproval(res, { approvalId, toolName, command: label, args: { command: label } })
+  sseWrite(res, { type: 'approval-decided', approvalId, ok: decision.ok, scope: decision.scope })
+  if (!decision.ok) {
+    auditShell(root, label, false)
+    throw new Error(decision.reason || '用户拒绝了这次执行：请把命令原样写给用户自行运行，或改用结构化卡片工具')
+  }
+  if (decision.scope === 'turn') approved.add(toolName)
+  auditShell(root, label, true)
+  return run()
+}
+
+async function runShellExec(root, args, res, approved) {
+  const cfg = readAiConfig(root)
+  if (!cfg.shellAllowed) {
+    throw new Error('未开启本地命令执行：请先在 AI 开发助手设置里打开「允许执行本地命令」开关（技能脚本走 skill_exec，不受此开关影响）')
+  }
+  const cmd = String(args.command || '').trim()
+  if (!cmd) throw new Error('命令为空')
+  // 静态闸前置到审批之前：白名单外的命令根本没资格执行，不该拿它去打扰用户点「允许」；
+  // 更要紧的是模型能**立刻**拿到「正路」提示改走范式脚本，而不是等批准后再撞一次同样的墙。
+  // 审计记 blocked（区别于用户主动 deny），execShell 内的同一道闸保留作纵深防御。
+  try {
+    assertShellAllowlist(cmd)
+  } catch (e) {
+    auditShell(root, cmd, false, 'blocked')
+    throw e
+  }
+  return runGuarded(
+    root,
+    res,
+    {
+      toolName: 'shell_exec',
+      command: cmd,
+      approved,
+      auto: autoApproves(cfg.autoApprove, 'shell_exec'),
+    },
+    () => execShell(root, cmd),
+  )
+}
+
+/** 技能脚本执行：路径形状校验 → 解释器解析 → 审批（或按策略免确认）→ 跑（cwd=仓库根，脚本自己按仓库根推算落点） */
+async function runSkillExec(root, args, res, approved) {
+  const script = resolveSkillScript(root, args.script)
+  const argv = normalizeSkillArgs(args.args)
+  const timeoutMs = Math.min(
+    SKILL_EXEC_MAX_TIMEOUT,
+    Math.max(5000, Number(args.timeoutMs) > 0 ? Number(args.timeoutMs) : SKILL_EXEC_DEFAULT_TIMEOUT),
+  )
+  const label = `${script.bin} ${script.rel}${argv.length ? ` ${argv.join(' ')}` : ''}`
+  const cfg = readAiConfig(root)
+  return runGuarded(
+    root,
+    res,
+    {
+      toolName: 'skill_exec',
+      command: label,
+      approved,
+      auto: autoApproves(cfg.autoApprove, 'skill_exec'),
+    },
+    () =>
+      spawnCapture(root, script.bin, [script.abs, ...argv], timeoutMs, {
+        PYTHONIOENCODING: 'utf-8',
+        PYTHONUNBUFFERED: '1',
+      }),
+  )
+}
+
+// ---- 对话内审批：未命中免确认策略的高危执行（默认是 shell_exec）每次调用都要用户点确认 ----
+
+/** approvalId -> { resolve, timer }：SSE 发 approval-request，等 POST /__ai/approve 回落 */
+const pendingApprovals = new Map()
+
+/** 审批等待上限：技能脚本管线可能连跑多步，用户走神也不能让整轮挂死 */
+const APPROVAL_TIMEOUT_MS = 300000
+
+function waitForApproval(res, { approvalId, toolName, args, command = '' }, timeoutMs = APPROVAL_TIMEOUT_MS) {
+  sseWrite(res, { type: 'approval-request', approvalId, toolName, command, args })
+  return new Promise((resolve) => {
+    const entry = { resolve, timer: 0 }
+    entry.timer = setTimeout(() => {
+      if (pendingApprovals.get(approvalId) === entry) pendingApprovals.delete(approvalId)
+      resolve({ ok: false, reason: `超过 ${Math.round(timeoutMs / 1000)} 秒未确认，按拒绝处理` })
+    }, timeoutMs)
+    pendingApprovals.set(approvalId, entry)
+  })
+}
+
+function settleApproval(approvalId, ok, scope = 'once') {
+  const entry = pendingApprovals.get(String(approvalId || ''))
+  if (!entry) return false
+  pendingApprovals.delete(String(approvalId))
+  clearTimeout(entry.timer)
+  entry.resolve({ ok: Boolean(ok), scope: scope === 'turn' ? 'turn' : 'once' })
+  return true
+}
+
+const SKILL_DOC_EXT = new Set(['.md', '.json', '.txt', '.csv'])
+
+/**
+ * skill_read：按需取技能文档。
+ *   - 裸文件名（rules.md）→ 兼容老用法，落在 dsl-card-generator/references/；
+ *   - 带 / 的相对路径（sketch-spec-to-card/SKILL.md、dsl-card-generator/references/ir-format.md）→ 按 skills/ 解析。
+ * 只放行文档类扩展名且必须在 skills/ 内：SKILL.md 是工作流权威，此前读不到，模型只能靠猜。
+ */
+function skillRead(root, args) {
+  const name = String(args?.path || '').trim().replace(/^\.?\/+/u, '')
+  if (!name) throw new Error('缺少 path')
+  const refsDir = path.join(root, 'skills', 'dsl-card-generator', 'references')
+  const rel = name.includes('/') ? name.replace(/^skills\//, '') : path.join('dsl-card-generator', 'references', name)
+  const full = path.resolve(path.join(root, 'skills'), rel)
+  const skillsRoot = path.join(root, 'skills')
+  if (!full.startsWith(skillsRoot + path.sep)) throw new Error('非法路径：只能读 skills/ 目录内的文档')
+  if (!SKILL_DOC_EXT.has(path.extname(full).toLowerCase())) throw new Error('只能读文档（.md / .json / .txt / .csv）；跑脚本用 skill_exec')
+  if (!fs.existsSync(full) || !fs.statSync(full).isFile()) {
+    // 测试根等场景下 skills/ 可能不存在：退回模块加载时的仓库 references 目录
+    const fallback = path.resolve(fs.existsSync(refsDir) ? refsDir : SKILL_REFS_DIR, name)
+    if (!name.includes('/') && fallback.startsWith(SKILL_REFS_DIR + path.sep) && fs.existsSync(fallback)) {
+      const text = fs.readFileSync(fallback, 'utf8')
+      return text.length <= SKILL_READ_MAX ? text : `${text.slice(0, SKILL_READ_MAX)}\n…（已截断，省略 ${text.length - SKILL_READ_MAX} 字符）`
+    }
+    throw new Error(`文档不存在：skills/${rel}`)
+  }
+  const text = fs.readFileSync(full, 'utf8')
+  if (text.length <= SKILL_READ_MAX) return text
+  return `${text.slice(0, SKILL_READ_MAX)}\n…（已截断，省略 ${text.length - SKILL_READ_MAX} 字符）`
+}
+
+// ---- 配置读取 / 写入 ----
+
+/** 极简 .env 解析（与 tools/finmall-env.mjs 同规则，避免 server-core 反向依赖 tools/） */
+function parseEnvFile(file) {
+  const out = {}
+  try {
+    if (!fs.existsSync(file)) return out
+    for (const raw of fs.readFileSync(file, 'utf8').split('\n')) {
+      const line = raw.trim()
+      if (!line || line.startsWith('#')) continue
+      const i = line.indexOf('=')
+      if (i < 0) continue
+      const key = line.slice(0, i).trim()
+      let val = line.slice(i + 1).trim()
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1)
+      }
+      out[key] = val
+    }
+  } catch {
+    /* 读取失败按空配置处理 */
+  }
+  return out
+}
+
+/**
+ * 单轮（一次用户提问）预算策略：**步数默认不设硬顶**。
+ * 早先的 24 / 32 / 40 步硬顶是纯负担——设计稿建卡一轮要 spec_audit → crop_slices → expand_ir →
+ * iterate × N → check_fidelity 十几到几十次调用，到顶就把用户变成「继续」按钮，而步数多本身
+ * 并不代表模型在空转。真正要拦的是三种失控，各配一道精准熔断：
+ *   ① 原地打转：连续 LOOP_BREAK_REPEATS 轮「同工具 + 同参数」⇒ 判定卡死，跳过执行并收尾汇报
+ *   ② 墙钟失控：单轮总时长超过 turnTimeoutMs ⇒ 收尾汇报（上下文不丢，回复「继续」接着做）
+ *   ③ 迟迟不收敛：每 SOFT_NUDGE_EVERY 步注入一次收敛提醒（只提醒，不打断）
+ * 想控成本仍可设 AI_MAX_STEPS / 设置面板「单轮步数上限」> 0 启用旧硬顶行为。
+ */
+const DEFAULT_TURN_TIMEOUT_MS = 60 * 60 * 1000
+/** 连续多少轮完全相同的工具调用即判定死循环（第 2 轮先警告，第 3 轮熔断） */
+const LOOP_BREAK_REPEATS = 3
+
+/** 时长人话：分钟为主，亚分钟（测试里常把墙钟压到几十毫秒）回落秒，别显示「0 分钟」 */
+function fmtDuration(ms) {
+  const n = Number(ms) > 0 ? Number(ms) : 0
+  return n >= 60000 ? `${Math.round(n / 60000)} 分钟` : `${Math.max(1, Math.round(n / 1000))} 秒`
+}
+/** 每多少步注入一次「该收敛了」的软提醒（0 = 关闭） */
+const SOFT_NUDGE_EVERY = 24
+
+/**
+ * 免确认执行策略（AI_AUTO_APPROVE）：
+ *   none  = 每次执行都弹审批（旧行为）
+ *   skill = skill_exec 免确认、shell_exec 仍逐次确认（默认）
+ *   all   = 两者都免确认
+ * 默认 all（技能脚本 + 本地命令都免确认）的理由：建卡 / 改卡一轮要连跑 spec_audit → crop_slices →
+ * expand_ir → iterate × N → check_fidelity 十几次，逐次点「允许」会把流水线打断成手工活（用户明确要求默认免确认）；
+ * 真正的安全闸不是审批弹窗，而是「skill_exec 路径形状硬校验 + shell_exec 命令白名单 + 全量审计」：
+ * 每次执行照样写 .cache/ai-audit.log（tag=auto-policy），SSE 也会发 approval-auto 让对话里看得见命令原文。
+ * 需要收紧时在设置面板或 AI_AUTO_APPROVE 改回 skill / none。
+ */
+const DEFAULT_AUTO_APPROVE = 'all'
+const AUTO_APPROVE_MODES = new Set(['none', 'skill', 'all'])
+
+/** 宽松归一：开关值可能是 0/1/on/off/skill/all，认不出的回落默认（默认值本身可被调用方覆盖） */
+function normalizeAutoApprove(value, fallback = DEFAULT_AUTO_APPROVE) {
+  const s = String(value ?? '').trim().toLowerCase()
+  if (!s) return fallback
+  if (['0', 'off', 'false', 'no', 'none', 'ask'].includes(s)) return 'none'
+  if (['1', 'on', 'true', 'yes', 'all'].includes(s)) return 'all'
+  return AUTO_APPROVE_MODES.has(s) ? s : fallback
+}
+
+/** 该策略下这个工具是否免确认 */
+function autoApproves(mode, toolName) {
+  if (mode === 'all') return true
+  if (mode === 'skill') return toolName === 'skill_exec'
+  return false
+}
+
+/**
+ * 当前生效的 AI 配置：真实环境变量 > .env.cb.local（个人覆盖）> .env.cb（共享默认）。
+ *
+ * 坑点：cardbuddy CLI 启动时会 dotenv 载入 .env / .env.cb / .env.cb.local，把 AI_* 写进 process.env；
+ * 若简单让 process.env 最高优先，个人覆盖层 .env.cb.local 就永远失效，且启动后改磁盘文件也不生效。
+ * 因此 cli.js 会把「dotenv 实际注入的值」登记到 globalThis.__cardbuddyDotenvInjected；
+ * 这里只承认与「注入值 / 共享文件」都不同的环境变量为真实覆盖（CI / 命令行导出），其余一律实时读文件。
+ */
+function readAiConfig(root = REPO_ROOT) {
+  const shared = parseEnvFile(path.join(root, '.env.cb'))
+  const local = parseEnvFile(path.join(root, '.env.cb.local'))
+  const injected = globalThis.__cardbuddyDotenvInjected || {}
+  const pick = (key) => {
+    const fromProcess = process.env[key]
+    // 与 dotenv 启动注入值 / 共享文件同值 ⇒ 不是真实覆盖：以文件实时读取为准（磁盘改动立即生效）；
+    // 三者都不同才承认是命令行 / CI 导出的真实环境变量。
+    const isRealOverride = fromProcess !== undefined && fromProcess !== injected[key] && fromProcess !== shared[key]
+    return String(isRealOverride ? fromProcess : (local[key] || shared[key] || ''))
+  }
+  return {
+    baseUrl: pick('AI_BASE_URL'),
+    apiKey: pick('AI_API_KEY'),
+    model: pick('AI_MODEL'),
+    // 本地命令执行开关（默认开）：shell_exec 工具默认注册；是否逐次确认由 AI_AUTO_APPROVE 决定（默认 all=免确认）。
+    // 显式 AI_ALLOW_SHELL=0 才关闭（本工具只监听 127.0.0.1，且命令过白名单 + 全量审计）
+    shellAllowed: pick('AI_ALLOW_SHELL') !== '0',
+    // 单次输出上限（0 = 用默认值）：推理模型的思考也算 completion，太小会被截断
+    maxTokens: Number(pick('AI_MAX_TOKENS')) > 0 ? Number(pick('AI_MAX_TOKENS')) : 0,
+    // 深度思考开关（默认开）：关掉可显著提速，但仅在 vLLM / SGLang 系网关生效
+    thinking: pick('AI_THINKING') !== '0',
+    // 多模态视觉开关（默认关）：开启后先探测网关是否真支持图像，不支持自动降级数值闭环
+    vision: pick('AI_VISION') === '1',
+    // 免确认执行策略（默认 all）：建卡管线连跑十几次脚本 / 命令，不该每次都等用户点「允许」
+    autoApprove: normalizeAutoApprove(pick('AI_AUTO_APPROVE')),
+    // 单轮工具调用步数硬顶（0 = 不限，默认）：>0 时到顶收尾汇报并提示「继续」，上下文不丢
+    maxSteps: Number(pick('AI_MAX_STEPS')) > 0 ? Number(pick('AI_MAX_STEPS')) : 0,
+    // 单轮墙钟上限（毫秒）：不限步数后唯一能兜住「无限跑下去」的闸门，到点收尾汇报而非无声挂着
+    turnTimeoutMs: Number(pick('AI_TURN_TIMEOUT_MS')) > 0 ? Number(pick('AI_TURN_TIMEOUT_MS')) : DEFAULT_TURN_TIMEOUT_MS,
+  }
+}
+
+/** 密钥脱敏：只暴露「是否已配置 + 尾 4 位」，前端无需也不应拿到明文 */
+function maskKey(key) {
+  if (!key) return ''
+  if (key.length <= 8) return '*'.repeat(key.length)
+  return `${'*'.repeat(Math.min(8, key.length - 4))}${key.slice(-4)}`
+}
+
+/**
+ * 保存 AI 配置到 .env.cb.local（个人覆盖层，.gitignore 已忽略，密钥不入库）。
+ * 只写传入且非 undefined 的键；apiKey 传空串表示清除本地覆盖。
+ * 未传的键**保持原值原样重写**：早先的实现会把没传的键从个人覆盖层删掉，
+ * 于是「手写 env 只改一项」或「局部 POST」会连带清掉别的配置（与本文档相悖，实测 AI_ALLOW_SHELL 被抹掉）。
+ */
+function writeAiConfigLocal(
+  root = REPO_ROOT,
+  { baseUrl, apiKey, model, allowShell, maxTokens, thinking, vision, autoApprove, maxSteps } = {},
+) {
+  const envPath = path.join(root, '.env.cb.local')
+  const lines = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8').split('\n') : []
+  const KEYS = [
+    'AI_BASE_URL',
+    'AI_API_KEY',
+    'AI_MODEL',
+    'AI_ALLOW_SHELL',
+    'AI_MAX_TOKENS',
+    'AI_THINKING',
+    'AI_VISION',
+    'AI_AUTO_APPROVE',
+    'AI_MAX_STEPS',
+  ]
+  const incoming = {
+    AI_BASE_URL: baseUrl,
+    AI_API_KEY: apiKey,
+    AI_MODEL: model,
+    AI_ALLOW_SHELL: allowShell === undefined ? undefined : allowShell ? '1' : '0',
+    // 传空串 / 0 = 清除本地覆盖，回到内置默认
+    AI_MAX_TOKENS: maxTokens === undefined ? undefined : String(Number(maxTokens) > 0 ? Number(maxTokens) : ''),
+    AI_THINKING: thinking === undefined ? undefined : thinking ? '1' : '0',
+    AI_VISION: vision === undefined ? undefined : vision ? '1' : '0',
+    AI_AUTO_APPROVE: autoApprove === undefined ? undefined : normalizeAutoApprove(autoApprove),
+    AI_MAX_STEPS: maxSteps === undefined ? undefined : String(Number(maxSteps) > 0 ? Number(maxSteps) : ''),
+  }
+
+  // 文件里已有的受管键值：incoming 为 undefined 时按原值重写，实现「只改传入的键」
+  const existing = {}
+  for (const l of lines) {
+    const t = l.trim()
+    if (!t || t.startsWith('#')) continue
+    const i = t.indexOf('=')
+    if (i < 0) continue
+    const k = t.slice(0, i).trim()
+    if (KEYS.includes(k)) existing[k] = t.slice(i + 1).trim()
+  }
+
+  const kept = lines.filter((l) => {
+    const t = l.trim()
+    if (!t || t.startsWith('#')) return true
+    const i = t.indexOf('=')
+    if (i < 0) return true
+    return !KEYS.includes(t.slice(0, i).trim())
+  })
+  while (kept.length && !kept[kept.length - 1].trim()) kept.pop()
+
+  const block = []
+  if (!kept.some((l) => l.startsWith('# AI 开发助手'))) {
+    block.push('# AI 开发助手模型配置（CardBuddy 设置面板写入；本文件为个人覆盖层，勿提交）')
+  }
+  for (const k of KEYS) {
+    // 未传（undefined）= 沿用文件里的原值：只改用户真正动过的那几项
+    const value = incoming[k] !== undefined ? incoming[k] : existing[k]
+    if (value !== undefined) block.push(`${k}=${String(value ?? '')}`)
+  }
+
+  const out = [...kept, ...(kept.length ? [''] : []), ...block]
+  fs.writeFileSync(envPath, out.join('\n') + '\n', 'utf8')
+
+  // 清掉 dotenv 从 .env.cb 灌进来的旧值：readAiConfig 以「与共享文件同值 = 非真实覆盖」判定，
+  // 留着会让刚写入 .local 的值被误判为环境变量覆盖（清空即回落 .local，语义正确）
+  for (const k of KEYS) {
+    if (incoming[k] !== undefined) delete process.env[k]
+  }
+}
+
+// ---- 请求体 / 响应辅助 ----
+
+function readBody(req, limitBytes = 8 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    req.on('data', (chunk) => {
+      data += chunk
+      if (data.length > limitBytes) {
+        reject(new Error('body too large'))
+        req.destroy()
+      }
+    })
+    req.on('end', () => {
+      try {
+        resolve(data ? JSON.parse(data) : {})
+      } catch (e) {
+        reject(e)
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/** RFC1918 / 链路本地：局域网页面（vite Network 地址、同网设备）属可信来源 */
+const PRIVATE_HOST_RE = /^(10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){2}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|169\.254(\.\d{1,3}){2})$/
+let _ownHosts = null
+/** 本机所有网卡地址：用它们打开编辑器（含 VPN/utun 地址）也算可信来源 */
+function ownHosts() {
+  if (_ownHosts) return _ownHosts
+  const set = new Set()
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const i of list || []) set.add(String(i.address).toLowerCase())
+  }
+  _ownHosts = set
+  return set
+}
+/**
+ * 可信来源判定：回环 / 局域网私有地址 / 本机网卡地址 才允许跨源读取；
+ * 公网页面（含嵌入 iframe 的第三方站点）一律不放行。
+ * 局域网必须放行：用 vite 的 Network 地址（或经其代理）打开编辑器是文档内的正常用法。
+ */
+function trustedOrigin(req) {
+  const origin = req.headers.origin || ''
+  if (!origin) return null // 同源 / 非浏览器请求：由调用方决定是否放行
+  try {
+    const host = new URL(origin).hostname.toLowerCase().replace(/^\[|\]$/g, '')
+    if (host === 'localhost' || host.startsWith('127.') || host === '::1') return origin
+    if (PRIVATE_HOST_RE.test(host)) return origin
+    if (ownHosts().has(host)) return origin
+  } catch {
+    /* 非法 origin 视作不可信 */
+  }
+  return null
+}
+
+function sendJson(req, res, code, payload) {
+  res.statusCode = code
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  const origin = trustedOrigin(req)
+  if (origin) res.setHeader('Access-Control-Allow-Origin', origin)
+  res.end(JSON.stringify(payload))
+}
+
+function sseWrite(res, obj) {
+  if (res.writableEnded || res.destroyed) return
+  res.write(`data: ${JSON.stringify(obj)}\n\n`)
+}
+
+// ---- 对话记录落盘 ----
+
+function safeCardId(cardId) {
+  const id = String(cardId || '').trim()
+  if (!id) return ''
+  // 只允许文件名安全字符，杜绝 ../ 路径穿越
+  return id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120)
+}
+
+function historyFile(chatDir, cardId) {
+  const id = safeCardId(cardId)
+  return id ? path.join(chatDir, `${id}.json`) : ''
+}
+
+function readHistory(chatDir, cardId) {
+  const file = historyFile(chatDir, cardId)
+  if (!file || !fs.existsSync(file)) return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return {
+      cardId: String(raw.cardId || cardId || ''),
+      messages: Array.isArray(raw.messages) ? raw.messages : [],
+      updatedAt: Number(raw.updatedAt || 0),
+    }
+  } catch {
+    return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
+  }
+}
+
+function writeHistory(chatDir, cardId, messages) {
+  const file = historyFile(chatDir, cardId)
+  if (!file) return { ok: false, error: 'missing-card-id' }
+  fs.mkdirSync(chatDir, { recursive: true })
+  const list = Array.isArray(messages) ? messages.slice(-MAX_HISTORY_MESSAGES) : []
+  const payload = { cardId: safeCardId(cardId), messages: list, updatedAt: Date.now() }
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(payload), 'utf8')
+  fs.renameSync(tmp, file)
+  return { ok: true, count: list.length, updatedAt: payload.updatedAt }
+}
+
+function deleteHistory(chatDir, cardId) {
+  const file = historyFile(chatDir, cardId)
+  if (!file) return { ok: false, error: 'missing-card-id' }
+  try {
+    if (fs.existsSync(file)) fs.unlinkSync(file)
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e) }
+  }
+  return { ok: true }
+}
+
+/** 历史卡片清单（面板「最近对话」用，按更新时间倒序） */
+function listHistories(chatDir, limit = 30) {
+  try {
+    if (!fs.existsSync(chatDir)) return []
+    return fs
+      .readdirSync(chatDir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => {
+        try {
+          const raw = JSON.parse(fs.readFileSync(path.join(chatDir, f), 'utf8'))
+          const messages = Array.isArray(raw.messages) ? raw.messages : []
+          return {
+            cardId: String(raw.cardId || f.replace(/\.json$/, '')),
+            updatedAt: Number(raw.updatedAt || 0),
+            count: messages.length,
+            preview: String(messages.find((m) => m.role === 'user')?.content || '').slice(0, 60),
+          }
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, limit)
+  } catch {
+    return []
+  }
+}
+
+// ---- 本地文件挂载（只读，不上传） ----
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg', '.avif', '.ico'])
+const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.svg': 'image/svg+xml',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+}
+/** 预览直出的图片体积上限（超过则前端退化为占位图标） */
+const RAW_MAX_BYTES = 12 * 1024 * 1024
+
+/** 用户最近选过 / 拖过的目录，作为拖拽路径反查的优先根 */
+const recentRoots = []
+
+function rememberRoot(p) {
+  try {
+    const dir = fs.statSync(p).isDirectory() ? p : path.dirname(p)
+    const idx = recentRoots.indexOf(dir)
+    if (idx >= 0) recentRoots.splice(idx, 1)
+    recentRoots.unshift(dir)
+    if (recentRoots.length > 12) recentRoots.pop()
+  } catch {
+    /* 路径已失效则忽略 */
+  }
+}
+
+function expandHome(p) {
+  const s = String(p || '').trim()
+  if (!s) return ''
+  if (s === '~') return os.homedir()
+  if (s.startsWith('~/')) return path.join(os.homedir(), s.slice(2))
+  return s
+}
+
+function describePath(target) {
+  const abs = path.resolve(expandHome(target))
+  let st
+  try {
+    st = fs.statSync(abs)
+  } catch {
+    return { path: abs, exists: false }
+  }
+  const ext = path.extname(abs).toLowerCase()
+  const info = {
+    path: abs,
+    exists: true,
+    name: path.basename(abs) || abs,
+    isDir: st.isDirectory(),
+    size: st.size,
+    mtime: st.mtimeMs,
+    ext,
+    isImage: !st.isDirectory() && IMAGE_EXT.has(ext),
+  }
+  if (info.isDir) {
+    // 文件夹：给 AI 一份「浅层清单」摘要，避免它盲目递归
+    const entries = []
+    let count = 0
+    try {
+      const walk = (dir, depth) => {
+        if (depth > 2 || count > 400) return
+        let list
+        try {
+          list = fs.readdirSync(dir, { withFileTypes: true })
+        } catch {
+          return
+        }
+        for (const ent of list) {
+          if (count > 400) return
+          if (ent.name === '.git' || ent.name === 'node_modules' || ent.name === '.DS_Store') continue
+          const rel = path.relative(abs, path.join(dir, ent.name))
+          count++
+          if (ent.isDirectory()) {
+            entries.push(`${rel}/`)
+            walk(path.join(dir, ent.name), depth + 1)
+          } else {
+            entries.push(rel)
+          }
+        }
+      }
+      walk(abs, 0)
+    } catch {
+      /* 无权限目录忽略 */
+    }
+    info.entries = entries
+    info.entryCount = count
+    info.truncated = count > 400
+  }
+  rememberRoot(abs)
+  return info
+}
+
+/**
+ * 拖拽落点反查绝对路径。
+ * 浏览器出于安全不给 File.path，这里两条路走：
+ *   1) 直拼：用 webkitRelativePath（如 `设计稿/index.html`）拼上「最近选过的目录 / 其父目录 /
+ *      Desktop / Downloads / Documents / 项目根」，命中且大小一致即采用（绝大多数拖拽走这条，零扫描）；
+ *   2) 兜底 BFS：按「文件名 + 大小」逐个根目录浅层优先搜索，命中即返回（根列表本身按可能性排序）；
+ *      异步分片扫描（每 400 条让出一次事件循环），未命中时也不会把本机服务卡住。
+ * 搜索根先剪掉「被其它根包含」的子根：否则同一文件会在父 / 子根各命中一次，被误判成重名歧义而返回空。
+ * 同一个根里出现多个同名同尺寸文件才算歧义，此时不猜。
+ */
+async function locateDropped({ name, relPath = '', size = -1 }) {
+  const fileName = String(name || '').trim()
+  if (!fileName) return null
+  const wantSize = Number(size) >= 0 ? Number(size) : -1
+  const tail = String(relPath || '').split('/').filter(Boolean)
+  const SKIP = new Set(['node_modules', '.git', '.cache', 'dist', '.codex-tmp', '.local', '.history', 'UI', 'demo', 'release'])
+  const home = os.homedir()
+
+  const sizeMatches = (p) => {
+    if (wantSize < 0) return true
+    try {
+      return fs.statSync(p).size === wantSize
+    } catch {
+      return false
+    }
+  }
+
+  const realOf = (p) => {
+    try {
+      return fs.realpathSync(p)
+    } catch {
+      return p
+    }
+  }
+
+  const roots = []
+  const pushRoot = (r) => {
+    if (!r) return
+    const abs = path.resolve(r)
+    if (!roots.includes(abs)) roots.push(abs)
+  }
+  for (const r of recentRoots) {
+    pushRoot(r)
+    pushRoot(path.dirname(r))
+  }
+  pushRoot(path.join(home, 'Desktop'))
+  pushRoot(path.join(home, 'Downloads'))
+  pushRoot(path.join(home, 'Documents'))
+  pushRoot(REPO_ROOT)
+  pushRoot(path.dirname(REPO_ROOT))
+  pushRoot(home)
+
+  // 只保留「最外层」的根用于扫描（recentRoots 常同时含某目录与其父目录）
+  const reals = roots.map(realOf)
+  const scanRoots = roots.filter((r, i) => {
+    const real = reals[i]
+    return !reals.some((other, j) => j !== i && other !== real && real.startsWith(other + path.sep))
+  })
+
+  // 1) 直拼相对路径
+  if (tail.length) {
+    for (const root of roots) {
+      const cand = path.join(root, ...tail)
+      try {
+        const st = fs.statSync(cand)
+        if (st.isDirectory() || sizeMatches(cand)) return cand
+      } catch {
+        /* 该根下没有这个相对路径，换下一个 */
+      }
+    }
+  }
+
+  // 2) 逐根浅层优先 BFS（同一层全部展开后再下钻，拖入的目录通常在浅层）
+  const MAX_VISIT = 20000
+  const MAX_DEPTH = 4
+  let visited = 0
+  for (const scanRoot of scanRoots) {
+    if (visited >= MAX_VISIT) break
+    try {
+      if (!fs.statSync(scanRoot).isDirectory()) continue
+    } catch {
+      continue /* 根不存在则跳过 */
+    }
+    const queue = [{ dir: scanRoot, depth: 0 }]
+    /** realpath → 展示路径：同一文件经不同符号链接命中只算一次 */
+    const hits = new Map()
+    while (queue.length && visited < MAX_VISIT && hits.size < 2) {
+      const { dir, depth } = queue.shift()
+      if (depth > MAX_DEPTH) continue
+      let list
+      try {
+        list = fs.readdirSync(dir, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      const subdirs = []
+      for (const ent of list) {
+        visited++
+        if (visited > MAX_VISIT) break
+        // 兜底扫描可能遍历上万条目：定期让出事件循环，别把 dev server 卡住
+        if (visited % 400 === 0) await new Promise((r) => setImmediate(r))
+        if (SKIP.has(ent.name) || ent.name === '.DS_Store') continue
+        const full = path.join(dir, ent.name)
+        if (ent.isDirectory()) {
+          // 拖入文件夹：同名目录直接命中（无需比大小）
+          if (tail.length && ent.name === tail[0] && depth < MAX_DEPTH) {
+            try {
+              if (fs.statSync(full).isDirectory()) return full
+            } catch {
+              /* 忽略不可读目录 */
+            }
+          }
+          subdirs.push({ dir: full, depth: depth + 1 })
+        } else if (ent.name === fileName && sizeMatches(full)) {
+          const real = realOf(full)
+          if (!hits.has(real)) hits.set(real, full)
+        }
+      }
+      queue.push(...subdirs)
+    }
+    if (hits.size === 1) return hits.values().next().value
+    if (hits.size > 1) return null /* 同根下重名同尺寸：不猜 */
+  }
+  return null
+}
+
+/** 系统选择器（macOS 用 osascript；其它平台返回明确提示，前端仍可拖拽 / 粘路径） */
+function pickPaths({ kind = 'file', multiple = true }) {
+  if (process.platform !== 'darwin') {
+    throw Object.assign(new Error('当前系统不支持原生选择器，请改用拖拽或粘贴绝对路径'), { code: 'unsupported' })
+  }
+  const label = kind === 'folder' ? '选择文件夹' : kind === 'image' ? '选择图片' : '选择文件'
+  const what = kind === 'folder' ? 'folder' : 'file'
+  const ofType = kind === 'image' ? ' of type {"public.image"}' : ''
+  const multi = multiple ? ' with multiple selections allowed' : ''
+  const script = multiple
+    ? `set theItems to choose ${what} with prompt "${label}"${ofType}${multi}\nset outText to ""\nrepeat with i in theItems\n  set outText to outText & POSIX path of i & "\\n"\nend repeat\nreturn outText`
+    : `return POSIX path of (choose ${what} with prompt "${label}"${ofType})`
+
+  return new Promise((resolve, reject) => {
+    execFile('osascript', ['-e', script], { encoding: 'utf8', timeout: 10 * 60 * 1000 }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = String(stderr || err.message || '')
+        if (/User canceled|用户取消| (-128)/i.test(msg + String(err.code ?? ''))) {
+          return resolve({ cancelled: true, paths: [] })
+        }
+        const e = new Error(`系统选择器调用失败：${msg.slice(0, 200)}`)
+        e.code = 'picker-failed'
+        return reject(e)
+      }
+      const paths = String(stdout || '')
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      resolve({ cancelled: false, paths })
+    })
+  })
+}
+
+// ---- LLM 流式客户端 ----
+
+/**
+ * 调用 LLM（OpenAI 兼容），流式返回。
+ * @param {{ baseUrl:string, apiKey:string, model:string, messages:any[], tools?:any[], maxTokens?:number, signal?:AbortSignal }} opts
+ * @returns {AsyncGenerator<{type: string, [k: string]: any}>}
+ */
+/**
+ * 关闭深度思考的请求体扩展（vLLM / SGLang 系网关的 chat_template 透传）。
+ * 实测本仓网关：带 thinking 时一句话也要 900+ 字思考、建卡时思考 3 万字仍不产出；
+ * 关掉后首字节更快、直接出工具调用。非该类网关会忽略或拒绝本字段——拒绝时自动去掉重试。
+ */
+const NO_THINKING_BODY = { chat_template_kwargs: { enable_thinking: false } }
+
+/** 400 详情判定①：明确指向 max_tokens 过大 / 超范围（减半能救）：
+    DashScope 系「Range of max_tokens should be [1, N]」、vLLM 系「max_tokens must be <= max_model_len - prompt_tokens」 */
+const MAX_TOKENS_400_RE = /max_tokens[^\n]{0,160}(range|exceed|too (?:large|big)|must be|should be|limit|<=)|range of max_tokens/i
+/** 400 详情判定②：prompt / 上下文超窗（减半救不了，交给调用方裁剪重试） */
+const CONTEXT_400_RE = /(context|prompt|input)[^\n]{0,160}(length|long|exceed|limit|too (?:large|big|many))|maximum context/i
+
+/**
+ * 瞬时网关错误（超时 / 限流 / 5xx）：这类错误重试一次往往就过，整轮直接报错收尾代价太大——
+ * 实测一轮建卡跑了 72 次工具调用后被 nginx 504 一刀切，用户只看到一坨 HTML。
+ */
+const TRANSIENT_STATUS = new Set([408, 425, 429, 500, 502, 503, 504, 506, 507, 509, 520, 521, 522, 523, 524])
+
+/** 重试间隔（毫秒，逐个对应一次重试）：AI_GATEWAY_RETRY_MS 可覆盖，弱网调参与单测提速用 */
+function transientRetryDelays() {
+  const list = String(process.env.AI_GATEWAY_RETRY_MS || '1000,4000')
+    .split(',')
+    .map((x) => Number(x.trim()))
+    .filter((x) => Number.isFinite(x) && x >= 0)
+  return list.length ? list : [1000, 4000]
+}
+
+const nap = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * 把网关错误摘成一句话：错误页多是 HTML（nginx 504 / 502），原样甩给用户或回喂给模型都是噪音。
+ * 保留 `LLM <status>` 前缀——轮循环靠它识别 400 上下文溢出。
+ */
+function llmHttpError(status, body) {
+  const raw = String(body ?? '')
+  const isHtml = /<\s*(html|head|body|br|center|hr|div|p|title)\b/i.test(raw)
+  // HTML 错误页优先取 <title>：整页去标签会把 title 与 h1 拼成重复句（nginx 504 实测）
+  const title = raw.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim() || ''
+  const brief = raw
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-zA-Z#0-9]+;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300)
+  const gist = (isHtml ? title || brief : raw.slice(0, 500)).trim()
+  return new Error(isHtml ? `LLM ${status}：网关返回 HTML 错误页（无模型输出）${gist ? ` — ${gist}` : ''}` : `LLM ${status}: ${gist}`)
+}
+
+async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4096, signal, extraBody }) {
+  const url = baseUrl.replace(/\/$/, '') + '/chat/completions'
+  const buildBody = (extra, maxTok = maxTokens) => {
+    const body = { model, messages, stream: true, max_tokens: maxTok, ...(extra || {}) }
+    if (tools?.length) {
+      body.tools = tools
+      body.tool_choice = 'auto'
+    }
+    return body
+  }
+  const post = (extra, maxTok) =>
+    fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify(buildBody(extra, maxTok)),
+      signal,
+    })
+
+  // 生成器里没法从普通函数 yield：重试提示先攒着，拿到响应后统一吐给前端
+  const pendingNotices = []
+  /** 只在「一个字节都还没吐出去」前重试：流一旦开始就不能重来（前端已渲染半截正文） */
+  const postRetry = async (extra, maxTok) => {
+    const delays = transientRetryDelays()
+    let lastErr = null
+    for (let attempt = 0; ; attempt++) {
+      if (signal?.aborted) throw new Error('请求已中止')
+      const retryable = attempt < delays.length
+      try {
+        const resp = await post(extra, maxTok)
+        if (resp.ok || !TRANSIENT_STATUS.has(resp.status) || !retryable) return resp
+        const wait = delays[attempt]
+        pendingNotices.push(
+          `网关返回 HTTP ${resp.status}（瞬时错误）：${wait / 1000} 秒后自动重试本步（第 ${attempt + 1}/${delays.length} 次），任务不中断`,
+        )
+        await nap(wait)
+      } catch (e) {
+        if (signal?.aborted) throw e
+        lastErr = e
+        if (!retryable) break
+        const wait = delays[attempt]
+        pendingNotices.push(`网关连接失败（${String(e?.message || e).slice(0, 80)}）：${wait / 1000} 秒后自动重试本步`)
+        await nap(wait)
+      }
+    }
+    const err = new Error(`LLM 网络错误：${String(lastErr?.message || lastErr).slice(0, 200)}`)
+    err.code = 'network-error'
+    throw err
+  }
+
+  let curExtra = extraBody
+  let resp = await postRetry(curExtra)
+  for (const text of pendingNotices.splice(0)) yield { type: 'notice', text }
+  const hasExtra = Boolean(extraBody && Object.keys(extraBody).length)
+  if (!resp.ok && hasExtra) {
+    // 网关不认扩展字段（非 vLLM/SGLang 系）：去掉后原样重试一次，别让整轮直接失败
+    const detail = await resp.text().catch(() => '')
+    curExtra = undefined
+    resp = await postRetry(curExtra)
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '')
+      throw llmHttpError(resp.status, text)
+    }
+    yield {
+      type: 'notice',
+      text: `当前网关不支持「关闭深度思考」参数（HTTP ${resp.status} 已回退）：${detail.slice(0, 120)}`,
+    }
+  }
+
+  // max_tokens 超网关硬上限 / 窗口：自动减半重试（最多 2 次），避免手填过大或探测值过时时整轮直接失败。
+  // 分类收紧：只有详情明确指向 max_tokens 才减半；prompt 超窗类 400 减半无意义，
+  // 打 context-overflow 标记抛出，由轮循环走「压缩上下文重试」分支
+  let effMax = maxTokens
+  for (let i = 0; i < 2 && !resp.ok && resp.status === 400; i++) {
+    const detail = await resp.text().catch(() => '')
+    if (!MAX_TOKENS_400_RE.test(detail)) {
+      const err = llmHttpError(400, detail)
+      if (CONTEXT_400_RE.test(detail)) err.code = 'context-overflow'
+      throw err
+    }
+    const prev = effMax
+    effMax = Math.max(2048, Math.floor(effMax / 2))
+    resp = await postRetry(curExtra, effMax)
+    for (const text of pendingNotices.splice(0)) yield { type: 'notice', text }
+    yield { type: 'notice', text: `单次输出上限 ${prev} 被网关拒绝（HTTP 400）：已自动减半为 ${effMax} 重试` }
+  }
+
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => '')
+    throw llmHttpError(resp.status, text)
+  }
+  // 减半后的值被网关接受 = 「网关接受的单次输出上限」的证据：回写 capCache（**不是窗口缓存**）。
+  // 窗口与输出上限是两回事：本网关实测 max_tokens 硬上限 131072、/models 又无窗口字段，
+  // 把接受值当窗口会污染圆环分母与单轮上下文预算
+  if (effMax < maxTokens) {
+    const sig = maxTokensSig({ baseUrl, apiKey, model })
+    const known = capCache.get(sig)
+    if (!known || known.cap > effMax) capCache.set(sig, { cap: effMax, source: 'halved' })
+  }
+  if (!resp.body) throw new Error('LLM 返回空 body')
+
+  const decoder = new TextDecoder()
+  const reader = resp.body.getReader()
+  let buffer = ''
+  let toolCallsAccum = null
+
+  const flushToolCalls = () => {
+    if (!toolCallsAccum) return null
+    const finalized = Object.values(toolCallsAccum).map(({ announced, ...tc }) => ({
+      ...tc,
+      function: { ...tc.function, arguments: tc.function.arguments || '{}' },
+    }))
+    toolCallsAccum = null
+    return { type: 'tool-calls', toolCalls: finalized }
+  }
+
+  try {
+    while (true) {
+      if (signal?.aborted) return
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+
+      const lines = buffer.split('\n')
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        const trimmed = line.trim()
+        if (!trimmed.startsWith('data:')) continue
+        const payload = trimmed.slice(5).trim()
+        if (payload === '[DONE]') {
+          const evt = flushToolCalls()
+          if (evt) yield evt
+          return
+        }
+        let chunk
+        try {
+          chunk = JSON.parse(payload)
+        } catch {
+          continue
+        }
+        const choice = chunk.choices?.[0]
+        if (!choice) continue // usage chunk 等
+        const delta = choice.delta || {}
+        // reasoning 字段各家命名不一：reasoning_content（DeepSeek/智谱）/ reasoning（部分网关）
+        const reasoning = delta.reasoning_content ?? delta.reasoning ?? ''
+        if (reasoning) yield { type: 'reasoning-delta', text: reasoning }
+        if (delta.content) yield { type: 'text-delta', text: delta.content }
+        if (delta.tool_calls) {
+          if (!toolCallsAccum) toolCallsAccum = {}
+          for (const tc of delta.tool_calls) {
+            const idx = tc.index ?? 0
+            if (!toolCallsAccum[idx]) {
+              toolCallsAccum[idx] = { id: tc.id || '', type: 'function', function: { name: '', arguments: '' } }
+            }
+            if (tc.id && !toolCallsAccum[idx].id) toolCallsAccum[idx].id = tc.id
+            if (tc.function?.name) toolCallsAccum[idx].function.name += tc.function.name
+            if (tc.function?.arguments) toolCallsAccum[idx].function.arguments += tc.function.arguments
+            // 工具名一到就先冒泡：参数（card_patch 的 JSON 可能很长）还在流式拼装时，
+            // 前端就能立刻显示「正在调用 xxx」，而不是等整轮结束才有反馈（Codex 同款体感）
+            if (tc.function?.name && !toolCallsAccum[idx].announced) {
+              toolCallsAccum[idx].announced = true
+              yield {
+                type: 'tool-call-start',
+                index: idx,
+                toolCallId: toolCallsAccum[idx].id,
+                toolName: toolCallsAccum[idx].function.name,
+              }
+            }
+          }
+        }
+        if (choice.finish_reason) {
+          // 'length' = 被 max_tokens 截断：工具参数会是半截 JSON，必须显式告诉用户而不是静默失败
+          yield { type: 'finish', reason: choice.finish_reason }
+        }
+        if (choice.finish_reason === 'tool_calls') {
+          const evt = flushToolCalls()
+          if (evt) yield evt
+        }
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock?.()
+    } catch {
+      /* 已中止时忽略 */
+    }
+  }
+
+  // 流末尾残留（无 [DONE] 的网关）兜底解析
+  const remaining = buffer.trim()
+  if (remaining.startsWith('data:')) {
+    const payload = remaining.slice(5).trim()
+    if (payload && payload !== '[DONE]') {
+      try {
+        const delta = JSON.parse(payload).choices?.[0]?.delta || {}
+        if (delta.content) yield { type: 'text-delta', text: delta.content }
+      } catch {
+        /* 忽略 */
+      }
+    }
+  }
+  const tail = flushToolCalls()
+  if (tail) yield tail
+}
+
+/** 工具结果里内联图片的体积上限（超出只留摘要，避免把上下文塞爆） */
+const TOOL_IMAGE_MAX_BYTES = 2 * 1024 * 1024
+
+/**
+ * 拆出工具结果中的 base64 图片（card_screenshot 等）：
+ * 图片对「文本模型」毫无价值却极占上下文，故从回传 LLM 的文本里剔除，只留给前端做预览。
+ * @param {any} result dispatch 返回值
+ * @returns {{ text: string, image?: { mime: string, base64: string } }}
+ */
+function splitToolResult(result) {
+  const raw = typeof result === 'string' ? result : JSON.stringify(result)
+  if (!raw || raw.indexOf('base64') < 0) return { text: raw }
+  let parsed
+  try {
+    parsed = typeof result === 'string' ? JSON.parse(result) : result
+  } catch {
+    return { text: raw }
+  }
+  if (!parsed || typeof parsed !== 'object') return { text: raw }
+  const b64 = typeof parsed.base64 === 'string' ? parsed.base64 : ''
+  if (!b64) return { text: raw }
+  const mime = typeof parsed.mime === 'string' ? parsed.mime : 'image/png'
+  const image = b64.length <= TOOL_IMAGE_MAX_BYTES ? { mime, base64: b64 } : undefined
+  const summary = { ...parsed }
+  delete summary.base64
+  summary.note = image ? '截图已生成，图像已在对话面板中预览（未注入文本上下文）' : '截图过大，已省略图像数据'
+  return { text: JSON.stringify(summary), image }
+}
+
+// ---- 多模态视觉通路（开关开启 → 先探测网关；不支持自动降级数值闭环）----
+/** 注入上限：单轮最多注入几张图（图 token 很贵，推理模型尤其） */
+const VISION_INJECT_MAX = 2
+/** 单图注入体积上限（超出且降采样后仍超 → 放弃注入） */
+const VISION_MAX_BYTES = 900 * 1024
+/** 降采样长边上限 */
+const VISION_MAX_EDGE = 1024
+/** 32×32 灰底 PNG（95B）：探测用最小载荷。
+    曾用 1×1 透明图，实测有网关拒收小图（「height:1 or width:1 must be larger than 10」）→
+    带图请求 400 被误判成「模型不支持视觉」，32×32 满足常见最小边长限制且体积可忽略 */
+const TINY_PNG_B64 = 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAJklEQVR42u3NMQ0AAAwDoEqv9KrYsQQMkB6LQCAQCAQCgUAg+BIMLd4AWwUPN68AAAAASUVORK5CYII='
+const visionProbeCache = new Map()
+
+/** usage 里的输入 token 数：兼容 OpenAI 系 prompt_tokens 与部分网关的 input_tokens */
+function promptTokensOf(j) {
+  const u = j && j.usage
+  if (!u) return NaN
+  const n = Number(u.prompt_tokens ?? u.input_tokens)
+  return Number.isFinite(n) ? n : NaN
+}
+
+/**
+ * 探测网关是否真的把图像算进上下文：同一句 prompt 带 / 不带小图各发一次（max_tokens=1），
+ * 比较 usage.prompt_tokens——实测不支持的网关会静默忽略 image_url（token 数不变）。
+ * 带图请求被拒（尺寸 / 格式 / 模态限制）与「无 usage 可比」都记原因：降级照旧，但提示要说清为什么，
+ * 不能把网关拒收探针图误报成「模型不支持多模态」。结果按 baseUrl|model|key 尾缀缓存；保存设置会清缓存重探。
+ */
+async function probeVisionSupport({ baseUrl, apiKey, model }) {
+  const sig = `${baseUrl}|${model}|${String(apiKey || '').slice(-8)}`
+  if (visionProbeCache.has(sig)) return visionProbeCache.get(sig)
+  let out = { ok: false, reason: '' }
+  try {
+    const url = `${String(baseUrl).replace(/\/+$/, '')}/chat/completions`
+    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` }
+    const mk = (withImg) => ({
+      model,
+      stream: false,
+      max_tokens: 1,
+      messages: [
+        {
+          role: 'user',
+          content: withImg
+            ? [{ type: 'text', text: 'ping' }, { type: 'image_url', image_url: { url: `data:image/png;base64,${TINY_PNG_B64}` } }]
+            : 'ping',
+        },
+      ],
+    })
+    const call = async (body) => {
+      const r = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) })
+      const text = await r.text().catch(() => '')
+      let json = null
+      try {
+        json = JSON.parse(text)
+      } catch {
+        /* 非 JSON 响应：只留状态码与原文片段 */
+      }
+      return { ok: r.ok, status: r.status, json, text }
+    }
+    const [plain, withImage] = await Promise.all([call(mk(false)), call(mk(true))])
+    if (!plain.ok) {
+      out = { ok: false, reason: `纯文本探针请求被拒（HTTP ${plain.status}）` }
+    } else if (!withImage.ok) {
+      out = { ok: false, reason: `网关拒绝图像请求（HTTP ${withImage.status}：${(withImage.text || '').slice(0, 100)}）` }
+    } else {
+      const a = promptTokensOf(plain.json)
+      const b = promptTokensOf(withImage.json)
+      if (!Number.isFinite(a) || !Number.isFinite(b)) out = { ok: false, reason: '网关未回 usage.prompt_tokens，无法验证图像是否入上下文' }
+      else if (b > a) out = { ok: true, reason: '' }
+      else out = { ok: false, reason: '带图与不带图 prompt_tokens 无变化（网关静默忽略图像）' }
+    }
+  } catch (e) {
+    out = { ok: false, reason: String((e && e.message) || e).slice(0, 100) }
+  }
+  visionProbeCache.set(sig, out)
+  return out
+}
+
+/** 单次输出上限探测候选（降序）：二分式极小请求，第一个不 400 的即近似模型窗口 */
+const MAXTOKENS_CANDIDATES = [262144, 131072, 65536, 32768, 16384, 8192]
+/** 首轮最多等这么久拿探测结果；超时不取消探测，先用默认值开跑，结果留给后续轮次 */
+const MAXTOKENS_PROBE_WAIT_MS = 2000
+/** 网关上下文窗口缓存：仅 /v1/models 元数据写入（单轮上下文预算、输入框圆环分母的唯一来源） */
+const windowCache = new Map()
+/** 网关接受的单次输出上限缓存：二分试探与减半回写写入（自动封顶、手填夹取的依据） */
+const capCache = new Map()
+const maxTokensProbeInflight = new Map()
+/** 元数据读不到过的配置：聊天路径不再每轮重复 GET /models（「探测」按钮会清掉重测） */
+const maxTokensMetaMiss = new Set()
+
+/** 探测缓存键：同一网关 + 模型 + 密钥共用一份认知 */
+function maxTokensSig({ baseUrl, apiKey, model }) {
+  return `${baseUrl}|${model}|${String(apiKey || '').slice(-8)}`
+}
+
+/** 某配置的当前认知快照：{ cap: 接受的输出上限, window: 上下文窗口, source } */
+function probeSnapshot(sig) {
+  const cap = capCache.get(sig)
+  const win = windowCache.get(sig)
+  return { cap: cap?.cap || 0, window: win?.window || 0, source: cap?.source || win?.source || '' }
+}
+
+/**
+ * 自动获取「网关窗口」与「接受的单次输出上限」，两级手段、两份缓存：
+ * ① 读 /v1/models 元数据里的窗口字段（vLLM max_model_len、OpenRouter context_length 等）——免费、毫秒级，写 windowCache；
+ * ② binary=true 时再用极小请求降序试探，第一个不 400 的候选是**网关接受的输出上限**（≠ 窗口，
+ *    实测有网关窗口 262144 但 max_tokens 硬上限 131072）——**会产生一次真实计费补全**，
+ *    所以只由设置面板「探测」按钮触发，聊天路径绝不做（避免首轮偷偷发付费请求 / 与对话抢并发），写 capCache。
+ * 并发去重；普通用户无需手填：留空即自动。
+ */
+function probeMaxTokensSupport(cfg, { binary = true } = {}) {
+  const sig = maxTokensSig(cfg)
+  const metaKnown = windowCache.has(sig) || maxTokensMetaMiss.has(sig)
+  const capKnown = capCache.has(sig)
+  if (metaKnown && (!binary || capKnown)) return Promise.resolve(probeSnapshot(sig))
+  const key = `${sig}|${binary ? 'b' : 'm'}`
+  if (maxTokensProbeInflight.has(key)) return maxTokensProbeInflight.get(key)
+  const pending = runMaxTokensProbe(cfg, { binary }).finally(() => maxTokensProbeInflight.delete(key))
+  maxTokensProbeInflight.set(key, pending)
+  return pending
+}
+
+/** 最多等 ms 拿结果：超时返回 null（探测继续在后台跑并写缓存），避免首轮像卡住 */
+function settleWithin(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), ms)
+    if (typeof timer.unref === 'function') timer.unref()
+    promise.then(resolve, () => resolve(null)).finally(() => clearTimeout(timer))
+  })
+}
+
+async function runMaxTokensProbe({ baseUrl, apiKey, model }, { binary = true } = {}) {
+  const sig = maxTokensSig({ baseUrl, apiKey, model })
+  const base = String(baseUrl).replace(/\/+$/, '')
+  const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` }
+  let source = ''
+  try {
+    if (maxTokensMetaMiss.has(sig)) throw new Error('meta-miss')
+    const r = await fetch(`${base}/models`, { headers })
+    if (r.ok) {
+      const j = await r.json().catch(() => null)
+      const list = Array.isArray(j && j.data) ? j.data : []
+      const hit = list.find((m) => m && (m.id === model || m.model === model)) || list[0]
+      const meta =
+        hit &&
+        (hit.max_model_len ||
+          hit.context_length ||
+          hit.max_context_len ||
+          hit.max_tokens ||
+          (hit.model_info && hit.model_info.context_length))
+      const n = Number(meta)
+      if (hit && Number.isFinite(n) && n > 0) {
+        windowCache.set(sig, { window: Math.floor(n), source: 'models-meta' })
+        source = 'models-meta'
+      }
+    }
+  } catch {
+    /* 元数据不可用 → 记住，聊天路径下次不再白跑一趟 */
+    maxTokensMetaMiss.add(sig)
+  }
+  if (binary && !capCache.has(sig)) {
+    for (const cand of MAXTOKENS_CANDIDATES) {
+      try {
+        const r = await fetch(`${base}/chat/completions`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({ model, stream: false, max_tokens: cand, messages: [{ role: 'user', content: 'ping' }] }),
+        })
+        if (r.ok) {
+          capCache.set(sig, { cap: cand, source: 'probe' })
+          source = source || 'probe'
+          break
+        }
+        if (r.status !== 400) break // 非 400 的错误（鉴权 / 限流）不该继续试探
+        await r.text().catch(() => '')
+      } catch {
+        break
+      }
+    }
+  }
+  // 只缓存有效结果：探测失败不能把「不知道」写死，否则「探测」按钮之外再也拿不到窗口 / 上限
+  return { ...probeSnapshot(sig), source: source || probeSnapshot(sig).source }
+}
+
+/**
+ * 自动模式封顶：探测到的是「上下文窗口」，而 max_tokens 是「单次输出预算」。把整段窗口当输出
+ * 预算既没必要（建卡一轮 32k 绰绰有余），又容易被 vLLM 系网关 400（prompt + max_tokens > 窗口）。
+ */
+const AUTO_MAX_TOKENS_CEILING = 32768
+
+/** 留空（自动）时该用多大：min(接受的输出上限 || 窗口, 封顶)；都没探测到就用默认值 */
+function autoMaxTokens(cap, window) {
+  const n = Number(cap) > 0 ? Number(cap) : Number(window) > 0 ? Number(window) : 0
+  return n > 0 ? Math.min(n, AUTO_MAX_TOKENS_CEILING) : DEFAULT_MAX_TOKENS
+}
+
+/** 留空（自动）时的实际单次输出上限：探测缓存 → 默认值；已配置则以配置为准（轮级再按已知上限夹取） */
+function effectiveMaxTokens(cfg) {
+  if (Number(cfg.maxTokens) > 0) return Number(cfg.maxTokens)
+  const snap = probeSnapshot(maxTokensSig(cfg))
+  return autoMaxTokens(snap.cap, snap.window)
+}
+
+function dataUrlPart(buf, mime) {
+  return { type: 'image_url', image_url: { url: `data:${mime};base64,${buf.toString('base64')}` } }
+}
+
+/** PNG 超限时最近邻降采样到长边 ≤ VISION_MAX_EDGE（pngjs 缺失 / 解码失败 → 原图或放弃） */
+async function bufToVisionPart(buf, mime) {
+  let out = buf
+  if (mime === 'image/png' && out.length > VISION_MAX_BYTES) {
+    try {
+      const { PNG } = await import('pngjs')
+      const img = PNG.sync.read(out)
+      const long = Math.max(img.width, img.height)
+      if (long > VISION_MAX_EDGE) {
+        const scale = VISION_MAX_EDGE / long
+        const w = Math.max(1, Math.round(img.width * scale))
+        const h = Math.max(1, Math.round(img.height * scale))
+        const dst = new PNG({ width: w, height: h })
+        for (let y = 0; y < h; y++) {
+          for (let x = 0; x < w; x++) {
+            const sx = Math.min(img.width - 1, Math.floor(x / scale))
+            const sy = Math.min(img.height - 1, Math.floor(y / scale))
+            const si = (sy * img.width + sx) << 2
+            const di = (y * w + x) << 2
+            dst.data[di] = img.data[si]
+            dst.data[di + 1] = img.data[si + 1]
+            dst.data[di + 2] = img.data[si + 2]
+            dst.data[di + 3] = img.data[si + 3]
+          }
+        }
+        out = PNG.sync.write(dst)
+      }
+    } catch {
+      /* 解码失败保留原图，超 cap 则下面放弃 */
+    }
+  }
+  if (out.length > VISION_MAX_BYTES) return null
+  return dataUrlPart(out, mime)
+}
+
+async function fileToVisionPart(abs) {
+  try {
+    const buf = fs.readFileSync(abs)
+    if (!buf.length || buf.length > RAW_MAX_BYTES) return null
+    const mime = IMAGE_MIME[path.extname(abs).toLowerCase()] || 'image/png'
+    return await bufToVisionPart(buf, mime)
+  } catch {
+    return null
+  }
+}
+
+function safeParseArgs(str) {
+  if (!str || typeof str !== 'string') return {}
+  try {
+    return JSON.parse(str)
+  } catch {
+    return { _raw: str }
+  }
+}
+
+/** 键序无关的稳定序列化：死循环签名靠它，避免「同参数不同书写顺序」逃过检测 */
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+      .join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+/** 一轮工具调用的指纹：同工具 + 同参数（键序无关）⇒ 指纹相同 */
+function toolRoundSignature(toolCalls) {
+  return toolCalls.map((tc) => `${tc?.function?.name || '?'}${stableStringify(safeParseArgs(tc?.function?.arguments))}`).join('|')
+}
+
+// ---- 上下文预算与压缩 ----
+
+/** 输入上下文默认预算（token 粗估）：够装下几万字节卡片片段 + 十几轮对话，又不至于拖慢推理 */
+const DEFAULT_CONTEXT_TOKENS = 48000
+
+/**
+ * 单轮（一次提问内）上下文预算：步数不设硬顶后，工具结果会在轮内一路累积（每条最多 12000 字符），
+ * 几十轮就能把网关窗口顶爆 —— 而 prompt 超窗是直接 400，整轮白跑。超预算时折叠**早期**的超长工具
+ * 结果与注入图像（只缩内容、不删消息，assistant.tool_calls ↔ role:tool 的配对始终合法）。
+ * 探测到网关窗口时按 min(窗口 × 0.7, 本默认值) 收紧，给输出与思考留余量。
+ */
+const DEFAULT_TURN_CONTEXT_TOKENS = 96000
+
+/** 注入图像在预算里的计价（长边 ≤1024 降采样后大致这个量级；无法精确算，取固定成本足够触发折叠） */
+const IMAGE_TOKEN_COST = 1024
+
+/** 折叠时每条工具结果保留的头部字符数：够看清「调了什么、结论是什么」，细节让模型重新调工具拿 */
+const TRIM_STUB_CHARS = 400
+
+/** 最近多少条消息保持原文（含最新一轮的 assistant/tool 配对），不参与折叠 */
+const TRIM_KEEP_RECENT = 10
+
+/** 单次输出上限默认值：需容纳「推理模型的思考 + 一次工具调用的完整参数」 */
+const DEFAULT_MAX_TOKENS = 24576
+
+/** 粗估 token：CJK ≈ 1 token/字，其余 ≈ 0.3 token/字符，每条消息再加 4 token 结构开销 */
+function estTokens(text) {
+  const s = String(text ?? '')
+  let cjk = 0
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if ((c >= 0x3400 && c <= 0x9fff) || (c >= 0xf900 && c <= 0xfaff) || (c >= 0xff00 && c <= 0xffef)) cjk++
+  }
+  return Math.ceil(cjk + (s.length - cjk) * 0.3) + 4
+}
+
+function msgTokens(m) {
+  let t = estTokens(m.content)
+  for (const tc of m.toolCalls || []) {
+    t += estTokens(JSON.stringify(tc.args ?? {}))
+    t += estTokens(typeof tc.result === 'string' ? tc.result : JSON.stringify(tc.result ?? ''))
+  }
+  return t
+}
+
+const oneLine = (text, max) => {
+  const line = String(text || '').replace(/\s+/g, ' ').trim()
+  return line.length > max ? `${line.slice(0, max)}…` : line || '（无正文）'
+}
+
+/**
+ * 多轮对话的上下文压缩：以「轮」（user 开头到下一个 user 之前）为粒度，
+ * 从后往前保留原文直到预算用尽，更早的轮次折叠成一条 system 摘要。
+ * 按轮折叠保证 assistant.tool_calls 与 role:tool 永远成对保留/成对丢弃，上下文始终合法。
+ * @returns {{messages:any[], droppedTurns:number, keptTokens:number}}
+ */
+function compactContext(messages, budgetTokens) {
+  const list = Array.isArray(messages) ? messages : []
+  const turns = []
+  for (const m of list) {
+    if (m.role === 'user' || !turns.length) turns.push([m])
+    else turns[turns.length - 1].push(m)
+  }
+  let used = 0
+  let keepFrom = turns.length
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const t = turns[i].reduce((a, m) => a + msgTokens(m), 0)
+    // 最后一轮无论如何保留（当前任务），其余超预算即止
+    if (used + t > budgetTokens && i < turns.length - 1) break
+    used += t
+    keepFrom = i
+  }
+  if (keepFrom <= 0) return { messages: list, droppedTurns: 0, keptTokens: used }
+  const dropped = turns.slice(0, keepFrom)
+  const lines = []
+  for (const turn of dropped) {
+    for (const m of turn) {
+      if (m.role === 'user') {
+        lines.push(`- 用户：${oneLine(m.content, 90)}`)
+      } else {
+        const tools = (m.toolCalls || []).map((tc) => tc.toolName).filter(Boolean).join('、')
+        lines.push(`- 助手${tools ? `（调用 ${tools}）` : ''}：${oneLine(m.content, 90)}${m.status === 'aborted' ? '［被中止］' : ''}`)
+      }
+    }
+  }
+  const digest = {
+    role: 'system',
+    content:
+      `[早期对话压缩摘要：共 ${dropped.length} 轮，不再保留原文；其中的工具结果已丢弃，` +
+      `需要细节请用 card_read / card_grep / fs_read 等工具重新读取，不要凭摘要猜测现状]\n${lines.join('\n')}`,
+  }
+  return { messages: [digest, ...turns.slice(keepFrom).flat()], droppedTurns: dropped.length, keptTokens: used }
+}
+
+/** OpenAI 形态消息的 token 粗估（content 可能是多模态数组：文本按字数、图像按固定成本） */
+function openAiMsgTokens(m) {
+  const c = m?.content
+  if (typeof c === 'string') return estTokens(c)
+  if (Array.isArray(c)) {
+    let t = 4
+    for (const part of c) {
+      if (part?.type === 'text') t += estTokens(part.text)
+      else if (part?.type === 'image_url') t += IMAGE_TOKEN_COST
+    }
+    return t
+  }
+  let t = 4
+  for (const tc of m?.tool_calls || []) t += estTokens(tc?.function?.arguments)
+  return t
+}
+
+/**
+ * 单轮内上下文裁剪：超预算时从**最早**的消息开始折叠，直到落回预算内。
+ * 只改 content、绝不删消息 —— tool_calls 与 role:'tool' 的配对一旦被破坏，网关会直接 400。
+ * @returns {{messages:any[], trimmed:number, tokens:number, before:number}}
+ */
+function trimTurnContext(messages, { budgetTokens = DEFAULT_TURN_CONTEXT_TOKENS, keepRecent = TRIM_KEEP_RECENT, stubChars = TRIM_STUB_CHARS } = {}) {
+  const list = Array.isArray(messages) ? messages.slice() : []
+  const before = list.reduce((a, m) => a + openAiMsgTokens(m), 0)
+  let total = before
+  if (!(budgetTokens > 0) || total <= budgetTokens) return { messages: list, trimmed: 0, tokens: total, before }
+  // index 0 是系统提示，永远保留；最近 keepRecent 条也保持原文（当前工作记忆）
+  const floor = Math.max(1, list.length - keepRecent)
+  let trimmed = 0
+  // ① 折叠早期超长工具结果：留下头部 + 明确的「重新调用可取全文」指引
+  for (let i = 1; i < floor && total > budgetTokens; i++) {
+    const m = list[i]
+    if (m?.role !== 'tool' || typeof m.content !== 'string' || m.content.length <= stubChars * 2) continue
+    const prev = openAiMsgTokens(m)
+    list[i] = {
+      ...m,
+      content: `${m.content.slice(0, stubChars)}…\n[工具结果已折叠以腾出单轮上下文预算；需要完整内容请重新调用该工具，不要凭这段摘要猜结论]`,
+    }
+    total -= prev - openAiMsgTokens(list[i])
+    trimmed++
+  }
+  // ② 仍超预算：丢掉早期注入图像（图 token 很贵），保留其文字说明
+  for (let i = 1; i < floor && total > budgetTokens; i++) {
+    const m = list[i]
+    if (m?.role !== 'user' || !Array.isArray(m.content) || !m.content.some((part) => part?.type === 'image_url')) continue
+    const prev = openAiMsgTokens(m)
+    const texts = m.content.filter((part) => part?.type === 'text').map((part) => part.text)
+    list[i] = { ...m, content: `${texts.join(' ')}\n[图像已折叠以腾出单轮上下文预算；需要看图请重新跑一次渲染 / 对比工具]` }
+    total -= prev - openAiMsgTokens(list[i])
+    trimmed++
+  }
+  return { messages: list, trimmed, tokens: total, before }
+}
+
+/** 深度压缩后最近多少条保持原文（含进行中的 assistant/tool 配对与最新证据） */
+const DEEP_KEEP_RECENT = 8
+
+/**
+ * 单轮深度压缩：折叠工具结果仍超预算（或网关已报上下文 400）时的第二道闸。
+ * 以「assistant(tool_calls) + 紧随的全部 role:tool 结果」为整组从最早开始丢弃，换成一条 system 摘要——
+ * 整组丢弃保证 tool_calls ↔ tool 配对协议始终合法；系统提示、本轮首条 user（任务本体）与
+ * 最近 DEEP_KEEP_RECENT 条永远保留，压缩后模型仍知道「这轮在做什么、刚做到哪」，循环继续不中断任务。
+ * @returns {{messages:any[], droppedGroups:number, tokens:number, before:number}}
+ */
+function deepCompactTurn(messages, budgetTokens, keepRecent = DEEP_KEEP_RECENT, force = false) {
+  const list = Array.isArray(messages) ? messages.slice() : []
+  const before = list.reduce((a, m) => a + openAiMsgTokens(m), 0)
+  if (list.length <= keepRecent + 2) return { messages: list, droppedGroups: 0, tokens: before, before }
+  const floor = list.length - keepRecent
+  const groups = []
+  for (let i = 2; i < floor; i++) {
+    const m = list[i]
+    if (m?.role !== 'assistant' || !Array.isArray(m.tool_calls) || !m.tool_calls.length) continue
+    let j = i + 1
+    while (j < floor && list[j]?.role === 'tool') j++
+    // 只丢「tool_calls 与 tool 结果齐全」的整组：丢半组会留下悬空 tool_calls，网关直接 400
+    if (j - (i + 1) === m.tool_calls.length) groups.push([i, j])
+    i = j - 1
+  }
+  let total = before
+  let dropped = 0
+  const lines = []
+  const removed = new Set()
+  for (const [a, b] of groups) {
+    if (total <= budgetTokens) break
+    const names = list[a].tool_calls.map((tc) => tc?.function?.name || '?').join('+')
+    const stub = String(list[a + 1]?.content || '').replace(/\s+/g, ' ').slice(0, 80)
+    lines.push(`- 丢弃调用 ${names}：结果头部「${stub}」`)
+    for (let k = a; k < b; k++) {
+      total -= openAiMsgTokens(list[k])
+      removed.add(k)
+    }
+    dropped++
+  }
+  if (!dropped) return { messages: list, droppedGroups: 0, tokens: total, before }
+  // 全丢也到不了预算（如系统提示本身就超）：主动路径不空丢（留给折叠与网关 400 自愈），
+  // force（网关已报溢出）才照丢——能减一点是一点
+  if (total > budgetTokens && !force) return { messages: list, droppedGroups: 0, tokens: total, before }
+  const digest = {
+    role: 'system',
+    content:
+      `[单轮上下文深度压缩：已丢弃最早 ${dropped} 组工具调用及其结果，仅留下面摘要；` +
+      `需要细节请重新调用对应工具取，不要凭摘要猜测现状]\n${lines.join('\n')}`,
+  }
+  const kept = list.filter((_, i) => !removed.has(i))
+  const out = [kept[0], kept[1], digest, ...kept.slice(2)]
+  return { messages: out, droppedGroups: dropped, tokens: total + openAiMsgTokens(digest), before }
+}
+
+/**
+ * 把前端持久化的消息（含 reasoning / toolCalls）还原成 OpenAI messages。
+ * 关键：assistant 的 tool_calls 必须紧跟对应的 role:'tool' 结果，否则续聊时上下文非法。
+ */
+function toOpenAiMessages(messages) {
+  const out = []
+  for (const m of messages || []) {
+    if (m.role === 'user') {
+      out.push({ role: 'user', content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '') })
+      continue
+    }
+    if (m.role === 'assistant') {
+      const calls = Array.isArray(m.toolCalls) ? m.toolCalls : []
+      const msg = { role: 'assistant', content: m.content || (calls.length ? null : '') }
+      if (calls.length) {
+        msg.tool_calls = calls.map((tc, i) => ({
+          id: tc.toolCallId || tc.id || `call_${i}`,
+          type: 'function',
+          function: { name: tc.toolName || tc.name, arguments: JSON.stringify(tc.args ?? {}) },
+        }))
+      }
+      out.push(msg)
+      for (const tc of calls) {
+        const result = tc.error ? `Error: ${tc.error}` : typeof tc.result === 'string' ? tc.result : JSON.stringify(tc.result ?? '')
+        out.push({ role: 'tool', tool_call_id: tc.toolCallId || tc.id || `call_${calls.indexOf(tc)}`, content: result.slice(0, 12000) })
+      }
+      continue
+    }
+    if (m.role === 'system') out.push({ role: 'system', content: String(m.content || '') })
+  }
+  return out
+}
+
+/**
+ * 创建 AI 开发助手中间件。
+ * @param {{ root?: string }} [opts]
+ */
+export function createAiChatMiddleware(opts = {}) {
+  const root = opts.root ? path.resolve(opts.root) : REPO_ROOT
+  /** 对话记录落盘目录（.cache/ 已在 .gitignore）：随 root 走，测试可用临时根隔离 */
+  const chatDir = path.join(root, '.cache', 'ai-chats')
+
+  return async (req, res, next) => {
+    const rawUrl = req.url || ''
+    const qIdx = rawUrl.indexOf('?')
+    const pathname = qIdx >= 0 ? rawUrl.slice(0, qIdx) : rawUrl
+    if (!pathname.startsWith('/__ai/')) return next()
+    const query = new URLSearchParams(qIdx >= 0 ? rawUrl.slice(qIdx + 1) : '')
+
+    // 只放行可信来源（回环 / 局域网 / 本机网卡地址）的跨源请求；公网页面（含嵌入 iframe 的第三方站点）一律 403
+    const origin = req.headers.origin
+    if (origin && !trustedOrigin(req)) {
+      return sendJson(req, res, 403, { error: 'origin-not-allowed' })
+    }
+
+    if (req.method === 'OPTIONS') {
+      res.statusCode = 204
+      const allow = trustedOrigin(req)
+      if (allow) {
+        res.setHeader('Access-Control-Allow-Origin', allow)
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, x-dev-token')
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS')
+      }
+      return res.end()
+    }
+
+    // ---------- 模型配置 ----------
+    if (pathname === '/__ai/config') {
+      if (req.method === 'GET') {
+        const cfg = readAiConfig(root)
+        const out = {
+          baseUrl: cfg.baseUrl,
+          model: cfg.model,
+          hasKey: Boolean(cfg.apiKey),
+          apiKeyMasked: maskKey(cfg.apiKey),
+          shellEnabled: Boolean(cfg.shellAllowed),
+          // 免确认策略（none / skill / all）：面板拆成「技能脚本免确认」「本地命令免确认」两个开关
+          autoApprove: cfg.autoApprove,
+          // maxTokens = 本轮实际会用的值；maxTokensAuto = 用户没填（面板据此留空 + 显示自动值）
+          maxTokens: effectiveMaxTokens(cfg),
+          maxTokensAuto: !(cfg.maxTokens > 0),
+          maxTokensCap: capCache.get(maxTokensSig(cfg))?.cap || 0,
+          maxTokensWindow: windowCache.get(maxTokensSig(cfg))?.window || 0,
+          thinking: cfg.thinking !== false,
+          vision: cfg.vision === true,
+          // 0 = 不限步数（默认）；>0 = 用户自设硬顶。面板据此留空并显示「不限 + 熔断器」说明
+          maxSteps: cfg.maxSteps,
+          turnTimeoutMs: cfg.turnTimeoutMs,
+        }
+        // 设置面板要「回显」已存密钥：仅 ?reveal=1 回明文（本系列端点只放行可信来源）
+        if (query.get('reveal') === '1') out.apiKey = cfg.apiKey
+        return sendJson(req, res, 200, out)
+      }
+      if (req.method === 'POST') {
+        let body
+        try {
+          body = await readBody(req)
+        } catch {
+          return sendJson(req, res, 400, { error: 'invalid-body' })
+        }
+        try {
+          // apiKey 为空串 = 清除本地覆盖；未传（undefined）= 保持不变
+          // 设置变更（换网关 / 换模型 / 换密钥 / 动视觉开关）→ 视觉探测结论作废，下轮重探
+          visionProbeCache.clear()
+          writeAiConfigLocal(root, {
+            baseUrl: body.baseUrl,
+            apiKey: body.apiKey === '' ? '' : body.apiKey,
+            model: body.model,
+            allowShell: body.allowShell === undefined ? undefined : Boolean(body.allowShell),
+            maxTokens: body.maxTokens === undefined ? undefined : body.maxTokens,
+            thinking: body.thinking === undefined ? undefined : Boolean(body.thinking),
+            vision: body.vision === undefined ? undefined : Boolean(body.vision),
+            autoApprove: body.autoApprove === undefined ? undefined : normalizeAutoApprove(body.autoApprove),
+            maxSteps: body.maxSteps === undefined ? undefined : body.maxSteps,
+          })
+          const cfg = readAiConfig(root)
+          return sendJson(req, res, 200, {
+            ok: true,
+            baseUrl: cfg.baseUrl,
+            model: cfg.model,
+            hasKey: Boolean(cfg.apiKey),
+            apiKeyMasked: maskKey(cfg.apiKey),
+            shellEnabled: Boolean(cfg.shellAllowed),
+            autoApprove: cfg.autoApprove,
+            maxTokens: effectiveMaxTokens(cfg),
+            maxTokensAuto: !(cfg.maxTokens > 0),
+            maxTokensCap: capCache.get(maxTokensSig(cfg))?.cap || 0,
+          maxTokensWindow: windowCache.get(maxTokensSig(cfg))?.window || 0,
+            thinking: cfg.thinking !== false,
+            vision: cfg.vision === true,
+            maxSteps: cfg.maxSteps,
+            turnTimeoutMs: cfg.turnTimeoutMs,
+          })
+        } catch (e) {
+          return sendJson(req, res, 500, { error: 'write-failed', message: String((e && e.message) || e) })
+        }
+      }
+      return sendJson(req, res, 405, { error: 'method-not-allowed' })
+    }
+
+    // ---------- 单次输出上限探测（设置面板「探测」按钮）----------
+    if (pathname === '/__ai/probe-maxtokens') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      const cfg = readAiConfig(root)
+      if (!cfg.baseUrl || !cfg.apiKey || !cfg.model) {
+        return sendJson(req, res, 400, { error: 'missing-config', message: '请先填写 Base URL / API Key / 模型名' })
+      }
+      capCache.delete(maxTokensSig(cfg))
+      windowCache.delete(maxTokensSig(cfg))
+      maxTokensMetaMiss.delete(maxTokensSig(cfg))
+      const probed = await probeMaxTokensSupport(cfg)
+      // maxTokens = 留空时后端真正会用的值（封顶后）；window = 上下文窗口（仅元数据）；cap = 接受的单次输出上限（试探 / 减半）
+      return sendJson(req, res, 200, {
+        ok: true,
+        maxTokens: autoMaxTokens(probed.cap, probed.window),
+        window: probed.window,
+        cap: probed.cap,
+        ceiling: AUTO_MAX_TOKENS_CEILING,
+        source: probed.source || 'fallback',
+      })
+    }
+
+    // ---------- 连通性自测（设置面板「测试连接」）----------
+    if (pathname === '/__ai/ping') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 64 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      const cfg = readAiConfig(root)
+      const baseUrl = String(body.baseUrl || cfg.baseUrl || '')
+      const model = String(body.model || cfg.model || '')
+      // 前端不持有明文 key：留空即用服务端已配置值
+      const apiKey = String(body.apiKey || cfg.apiKey || '')
+      if (!baseUrl || !apiKey || !model) {
+        return sendJson(req, res, 400, { error: 'missing-config', message: '请先填写 Base URL / API Key / 模型名' })
+      }
+      const started = Date.now()
+      const ctl = new AbortController()
+      const timer = setTimeout(() => ctl.abort(), 20000)
+      try {
+        const resp = await fetch(baseUrl.replace(/\/$/, '') + '/chat/completions', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+          body: JSON.stringify({ model, messages: [{ role: 'user', content: 'ping' }], max_tokens: 8, stream: false }),
+          signal: ctl.signal,
+        })
+        const latencyMs = Date.now() - started
+        if (!resp.ok) {
+          const text = await resp.text().catch(() => '')
+          return sendJson(req, res, 200, { ok: false, status: resp.status, latencyMs, message: text.slice(0, 300) })
+        }
+        const json = await resp.json().catch(() => ({}))
+        return sendJson(req, res, 200, {
+          ok: true,
+          latencyMs,
+          model: json.model || model,
+          reply: String(json.choices?.[0]?.message?.content || '').slice(0, 80),
+        })
+      } catch (e) {
+        return sendJson(req, res, 200, { ok: false, latencyMs: Date.now() - started, message: String((e && e.message) || e).slice(0, 300) })
+      } finally {
+        clearTimeout(timer)
+      }
+    }
+
+    // ---------- 对话记录 ----------
+    if (pathname === '/__ai/history') {
+      const cardId = query.get('cardId') || ''
+      if (req.method === 'GET') {
+        if (query.get('list') === '1') return sendJson(req, res, 200, { items: listHistories(chatDir) })
+        if (!safeCardId(cardId)) return sendJson(req, res, 400, { error: 'missing-card-id' })
+        return sendJson(req, res, 200, readHistory(chatDir, cardId))
+      }
+      if (req.method === 'POST') {
+        let body
+        try {
+          body = await readBody(req)
+        } catch {
+          return sendJson(req, res, 400, { error: 'invalid-body' })
+        }
+        const id = body.cardId || cardId
+        if (!safeCardId(id)) return sendJson(req, res, 400, { error: 'missing-card-id' })
+        try {
+          return sendJson(req, res, 200, writeHistory(chatDir, id, body.messages))
+        } catch (e) {
+          return sendJson(req, res, 500, { error: 'write-failed', message: String((e && e.message) || e) })
+        }
+      }
+      if (req.method === 'DELETE') {
+        let cardIds = [cardId]
+        if (req.method === 'DELETE' && !cardId) {
+          try {
+            const body = await readBody(req, 1024 * 1024)
+            if (Array.isArray(body.cardIds)) cardIds = body.cardIds
+          } catch {
+            /* 无 body 时按单卡处理 */
+          }
+        }
+        const failed = []
+        for (const id of cardIds) {
+          const r = deleteHistory(chatDir, id)
+          if (!r.ok) failed.push({ cardId: id, error: r.error })
+        }
+        return sendJson(req, res, failed.length ? 207 : 200, { ok: !failed.length, failed })
+      }
+      return sendJson(req, res, 405, { error: 'method-not-allowed' })
+    }
+
+    // ---------- 本地文件挂载 ----------
+    if (pathname === '/__ai/fs/pick') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 64 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      try {
+        const picked = await pickPaths({ kind: body.kind || 'file', multiple: body.multiple !== false })
+        const items = (picked.paths || []).map((p) => describePath(p)).filter((i) => i.exists)
+        return sendJson(req, res, 200, { cancelled: Boolean(picked.cancelled), items })
+      } catch (e) {
+        const code = e?.code === 'unsupported' ? 501 : 500
+        return sendJson(req, res, code, { error: 'pick-failed', message: String((e && e.message) || e) })
+      }
+    }
+
+    if (pathname === '/__ai/fs/stat') {
+      if (req.method !== 'GET') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      const target = query.get('path') || ''
+      if (!target) return sendJson(req, res, 400, { error: 'missing-path' })
+      const info = describePath(target)
+      if (!info.exists) return sendJson(req, res, 404, { error: 'not-found', path: info.path })
+      return sendJson(req, res, 200, info)
+    }
+
+    if (pathname === '/__ai/fs/raw') {
+      if (req.method !== 'GET') {
+        res.statusCode = 405
+        return res.end()
+      }
+      const target = query.get('path') || ''
+      const abs = path.resolve(expandHome(target))
+      const ext = path.extname(abs).toLowerCase()
+      if (!target || !IMAGE_EXT.has(ext)) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+        return res.end('unsupported-media')
+      }
+      let st
+      try {
+        st = fs.statSync(abs)
+      } catch {
+        res.statusCode = 404
+        return res.end('not-found')
+      }
+      if (!st.isFile() || st.size > RAW_MAX_BYTES) {
+        res.statusCode = 413
+        return res.end('too-large')
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', IMAGE_MIME[ext] || 'application/octet-stream')
+      res.setHeader('Content-Length', String(st.size))
+      res.setHeader('Cache-Control', 'no-store')
+      const allow = trustedOrigin(req)
+      if (allow) res.setHeader('Access-Control-Allow-Origin', allow)
+      fs.createReadStream(abs).pipe(res)
+      return
+    }
+
+    if (pathname === '/__ai/fs/stash') {
+      // 剪贴板粘贴的截图没有本机路径：落到 .cache/ai-attachments/ 后按「本地文件」同等对待
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 24 * 1024 * 1024)
+      } catch {
+        return sendJson(req, res, 413, { error: 'too-large' })
+      }
+      const dataUrl = String(body.dataUrl || '')
+      const m = dataUrl.match(/^data:(image\/[a-z0-9.+-]+);base64,([\s\S]+)$/i)
+      if (!m) return sendJson(req, res, 400, { error: 'invalid-image' })
+      const ext = (m[1].split('/')[1] || 'png').replace('svg+xml', 'svg').toLowerCase()
+      if (!IMAGE_EXT.has(`.${ext}`)) return sendJson(req, res, 400, { error: 'unsupported-media' })
+      try {
+        const buf = Buffer.from(m[2], 'base64')
+        if (!buf.length) return sendJson(req, res, 400, { error: 'empty-image' })
+        if (buf.length > RAW_MAX_BYTES) return sendJson(req, res, 413, { error: 'too-large' })
+        const dir = path.join(root, '.cache', 'ai-attachments')
+        fs.mkdirSync(dir, { recursive: true })
+        const file = path.join(dir, `paste-${Date.now()}.${ext}`)
+        fs.writeFileSync(file, buf)
+        return sendJson(req, res, 200, describePath(file))
+      } catch (e) {
+        return sendJson(req, res, 500, { error: 'stash-failed', message: String((e && e.message) || e) })
+      }
+    }
+
+    if (pathname === '/__ai/fs/locate') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 256 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      const found = await locateDropped({
+        name: body.name,
+        relPath: body.relPath || '',
+        size: Number.isFinite(Number(body.size)) ? Number(body.size) : -1,
+      })
+      if (!found) return sendJson(req, res, 404, { error: 'not-located' })
+      const info = describePath(found)
+      return sendJson(req, res, 200, info)
+    }
+
+    // ---------- 对话内审批回落 ----------
+    if (pathname === '/__ai/approve') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 64 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      const settled = settleApproval(body.approvalId, body.ok !== false, body.scope === 'turn' ? 'turn' : 'once')
+      return sendJson(req, res, settled ? 200 : 404, { ok: settled, error: settled ? undefined : 'approval-not-found' })
+    }
+
+    // ---------- 流式对话 ----------
+    if (pathname !== '/__ai/chat') return sendJson(req, res, 404, { error: 'unknown-endpoint' })
+    if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+
+    let body
+    try {
+      body = await readBody(req)
+    } catch {
+      return sendJson(req, res, 400, { error: 'invalid-body' })
+    }
+
+    const { messages = [], config = {}, cardContext, attachments = [] } = body
+    const defaults = readAiConfig(root)
+    const baseUrl = config.baseUrl || defaults.baseUrl
+    const apiKey = config.apiKey || defaults.apiKey
+    const model = config.model || defaults.model
+    // 单次输出上限：推理模型的 reasoning 也算 completion，8192 实测不够建一张卡（思考 2 万字就把
+    // 额度吃光，工具参数还没开始吐就被截断）。留空 = 自动：min(网关窗口, 32768)；窗口只读免费的
+    // /v1/models 元数据（最多等 2s，超时先用默认值开跑，结果留给后续轮次），读不到就用默认 24576；
+    // 真被网关 400 拒绝还有减半重试兜底并回写窗口认知 —— 普通用户全程不用管这一项。
+    const maxTokensAuto = !(Number(config.maxTokens) > 0) && !(defaults.maxTokens > 0)
+    // 窗口认知与 maxTokens 是否「自动」无关：/v1/models 元数据免费、带缓存、最多等 2s，始终取一次——
+    // 单轮上下文预算与输入框圆环的分母都靠它；手填了 max_tokens 也不该失去窗口认知
+    const probed =
+      (await settleWithin(probeMaxTokensSupport({ baseUrl, apiKey, model }, { binary: false }), MAXTOKENS_PROBE_WAIT_MS)) || null
+    const finalConfig = {
+      baseUrl,
+      apiKey,
+      model,
+      maxTokens: maxTokensAuto
+        ? autoMaxTokens(probed?.cap || 0, probed?.window || 0)
+        : Number(config.maxTokens) || defaults.maxTokens,
+      // 单轮步数硬顶（0 = 不限）：本轮请求 > 设置/环境变量；此前这里合并完却在循环里读原始 config，
+      // 导致 AI_MAX_STEPS 形同虚设，现已统一走 finalConfig
+      maxSteps: Number(config.maxSteps) > 0 ? Number(config.maxSteps) : defaults.maxSteps,
+      // 单轮墙钟上限（毫秒）：不限步数后的失控兜底
+      turnTimeoutMs: Number(config.turnTimeoutMs) > 0 ? Number(config.turnTimeoutMs) : defaults.turnTimeoutMs,
+    }
+
+    // 手填值按「网关接受的单次输出上限」主动夹取：与其等网关 400 再减半（白白失败一次请求），
+    // 不如开跑前就夹好并在对话里说明；上限未知（没试探 / 没减半过）时仍保留减半兜底
+    let clampNotice = ''
+    const knownCap = capCache.get(maxTokensSig(finalConfig))?.cap || 0
+    if (!maxTokensAuto && knownCap > 0 && finalConfig.maxTokens > knownCap) {
+      clampNotice = `手填单次输出上限 ${finalConfig.maxTokens} 超过网关接受上限 ${knownCap}：本轮已夹取为 ${knownCap}（设置里留空即走自动）`
+      finalConfig.maxTokens = knownCap
+    }
+
+    if (!finalConfig.baseUrl || !finalConfig.apiKey || !finalConfig.model) {
+      return sendJson(req, res, 400, {
+        error: 'missing-config',
+        message: '未配置 AI 模型：请在设置面板填写 Base URL / API Key / 模型名（保存在 .env.cb.local）',
+      })
+    }
+
+    // 多模态视觉：开关开启 → 先探测网关是否真支持图像（带缓存）；不支持自动降级并在对话里提示一次
+    const visionWanted = config.vision === undefined ? defaults.vision === true : Boolean(config.vision)
+    const visionProbe = visionWanted ? await probeVisionSupport(finalConfig) : { ok: false, reason: '' }
+    const visionOn = visionProbe.ok
+
+    let tools, dispatch, systemPrompt
+    try {
+      ;({ tools, dispatch } = await loadTools())
+      systemPrompt = buildSystemPrompt({
+        shellAllowed: Boolean(defaults.shellAllowed),
+        vision: visionOn,
+        autoApprove: defaults.autoApprove,
+      })
+    } catch (e) {
+      return sendJson(req, res, 500, { error: 'tools-load-failed', message: String((e && e.message) || e) })
+    }
+    // skill_exec 常驻注册：它只能跑 skills/*/scripts/ 下的脚本（路径形状硬校验、参数不经 shell），
+    // 是「设计稿 → sketch-spec-to-card 前处理 → dsl-card-generator 生成」链路唯一的执行手段；
+    // 默认策略下免确认，一轮建卡十几次脚本调用才不会被打断成手工点「允许」
+    tools = [
+      ...tools,
+      SKILL_READ_TOOL,
+      CARD_GREP_TOOL,
+      CARD_PATCH_TOOL,
+      FS_READ_TOOL,
+      FS_LIST_TOOL,
+      FS_WRITE_TOOL,
+      FS_COPY_TOOL,
+      skillExecTool(autoApproves(defaults.autoApprove, 'skill_exec')),
+    ]
+    // shell 是高危能力：默认不注册；开启后是否逐次确认看策略（默认 all 之外仍逐次问）
+    if (defaults.shellAllowed) tools = [...tools, shellTool(autoApproves(defaults.autoApprove, 'shell_exec'))]
+    /** 本轮已获「不再询问」授权的工具名（scope=turn）：管线连跑多步时不必逐步点确认 */
+    const approvedTools = new Set()
+
+    let contextPrompt = systemPrompt
+    // 只注入「当前卡片 ID」：此前额外塞 8KB schema 摘要，与模型自己 card_read 的全文重复，
+    // 实测推理模型会在思考里反复背诵这份摘要而空转不收敛
+    if (cardContext?.id) {
+      contextPrompt += `\n\n## 当前卡片上下文\n\n用户正在编辑卡片 ID: ${cardContext.id}；现状以 card_read / card_node_models 的结果为准，不要凭记忆猜测。`
+    }
+    /** 本轮是否「设计稿建卡」流程（由附件路由判定得出，用于思考熔断催促时附加 IR 路线指引） */
+    let designFlow = false
+    // 用户挂载的目录（或文件所在目录）纳入 fs_read / fs_list 白名单：挂载即授权只读
+    const mountedRoots = attachments
+      .map((a) => (a.isDir ? String(a.path || '') : path.dirname(String(a.path || ''))))
+      .filter(Boolean)
+    if (attachments.length) {
+      // 目录浅层清单 + 建卡输入路由（Workflow 0）在服务端先跑掉再进上下文：
+      // 实测让模型自己摸索时，12 步工具额度里 4 步浪费在「fs_read 一个目录」上，最后超限零产出
+      const brief = await describeAttachments(root, attachments, dispatch, mountedRoots)
+      designFlow = brief.designFlow
+      contextPrompt += `\n\n## 用户挂载的本地文件（仅本机路径，未上传；需要内容时用工具自行读取）\n\n${brief.text}`
+    }
+
+    res.statusCode = 200
+    res.setHeader('Content-Type', 'text/event-stream; charset=utf-8')
+    res.setHeader('Cache-Control', 'no-cache, no-transform')
+    res.setHeader('Connection', 'keep-alive')
+    res.setHeader('X-Accel-Buffering', 'no')
+    const allow = trustedOrigin(req)
+    if (allow) res.setHeader('Access-Control-Allow-Origin', allow)
+    res.flushHeaders?.()
+
+    // 前端「停止」= abort fetch = 连接关闭：立刻中止 LLM 请求与工具循环
+    const abortCtl = new AbortController()
+    let aborted = false
+    const onClose = () => {
+      if (aborted) return
+      aborted = true
+      abortCtl.abort()
+    }
+    req.on('close', onClose)
+    req.on('aborted', onClose)
+    res.on('close', onClose)
+
+    // 上下文预算：多轮对话 + 大工具结果超限时，把早期轮次折叠成摘要（按轮折叠，
+    // 保证 assistant.tool_calls 与 tool 结果成对保留），并给前端一条 notice 说明
+    const contextBudget = Number(config.contextTokens) > 0 ? Number(config.contextTokens) : DEFAULT_CONTEXT_TOKENS
+    const compacted = compactContext(messages, contextBudget)
+    if (compacted.droppedTurns) {
+      sseWrite(res, {
+        type: 'notice',
+        message: `对话较长：早期 ${compacted.droppedTurns} 轮已压缩为摘要（最近轮次保留原文），需要细节时 AI 会用工具重读`,
+      })
+    }
+    if (visionWanted && !visionOn) {
+      sseWrite(res, {
+        type: 'notice',
+        message: `已开启多模态视觉，但本轮用不了图像，降级为数值闭环（pixelDiff.match）。原因：${visionProbe.reason || '探测失败'}`,
+      })
+    }
+    const fullMessages = [{ role: 'system', content: contextPrompt }, ...toOpenAiMessages(compacted.messages)]
+    // 视觉注入点①：用户挂载的图片随本轮 user 消息进上下文（落盘历史不含 base64，重开不重复注入）
+    if (visionOn && attachments.length) {
+      const parts = []
+      for (const a of attachments) {
+        if (a.isDir) continue
+        const ap = String(a.path || '')
+        if (!IMAGE_EXT.has(path.extname(ap).toLowerCase())) continue
+        const part = await fileToVisionPart(path.isAbsolute(ap) ? ap : path.join(root, ap))
+        if (part) parts.push({ caption: `用户挂载图片：${a.name || path.basename(ap)}`, part })
+        if (parts.length >= VISION_INJECT_MAX) break
+      }
+      if (parts.length) {
+        for (let i = fullMessages.length - 1; i >= 0; i--) {
+          if (fullMessages[i].role === 'user') {
+            const text = typeof fullMessages[i].content === 'string' ? fullMessages[i].content : JSON.stringify(fullMessages[i].content ?? '')
+            fullMessages[i] = {
+              role: 'user',
+              content: [{ type: 'text', text }, ...parts.flatMap((v) => [{ type: 'text', text: `[图] ${v.caption}` }, v.part])],
+            }
+            break
+          }
+        }
+      }
+    }
+
+    // 单轮预算：步数默认不限（设计稿建卡是多阶段管线，列画板 → 前处理 → cluster → spec_tree →
+    // scaffold → 填组件 → iterate × N → fidelity，几十次调用很正常），失控交给三道熔断；
+    // 只有用户显式配了 AI_MAX_STEPS / 面板「单轮步数上限」> 0 才恢复旧硬顶
+    const HARD_STEPS = Number(finalConfig.maxSteps) > 0 ? Number(finalConfig.maxSteps) : 0
+    const turnTimeoutMs = Number(finalConfig.turnTimeoutMs) > 0 ? Number(finalConfig.turnTimeoutMs) : DEFAULT_TURN_TIMEOUT_MS
+    // 单轮上下文预算：探测到网关窗口就按 70% 收紧（给输出 + 思考留余量），否则用默认值
+    const knownWindow = probed?.window || windowCache.get(maxTokensSig(finalConfig))?.window || 0
+    const turnContextBudget =
+      Number(config.turnContextTokens) > 0
+        ? Number(config.turnContextTokens)
+        : knownWindow > 0
+          ? Math.max(8000, Math.min(DEFAULT_TURN_CONTEXT_TOKENS, Math.floor(knownWindow * 0.7)))
+          : DEFAULT_TURN_CONTEXT_TOKENS
+    // 单轮「纯思考」预算：推理网关空转时（只吐 reasoning、迟迟不产出）中止上游并催促重试。
+    // 90s 对设计稿建卡太紧——实测前处理管线跑完、正要建卡时连续思考 90s+ 就被熔断，整轮白跑；
+    // 调到 240s（仍可 config.reasoningTimeoutMs 覆盖），另用 stallTimeoutMs 兜「网关彻底静默」。
+    const reasoningTimeoutMs = Number(config.reasoningTimeoutMs) > 0 ? Number(config.reasoningTimeoutMs) : 240000
+    // 网关静默判定：一个增量都不来才算挂起（与「正在思考」区分开），避免大上下文首 token 慢被误杀
+    const stallTimeoutMs = Number(config.stallTimeoutMs) > 0 ? Number(config.stallTimeoutMs) : 120000
+    let step = 0
+    /** 本轮开始时刻：墙钟熔断的基准 */
+    const turnStartedAt = Date.now()
+    /** 预算耗尽原因（null = 模型自己收尾）：'steps'（用户设了硬顶）/ 'timeout'（墙钟）/ 'loop'（原地打转） */
+    let budgetReason = null
+    /** 上一轮工具调用指纹与「连续相同」计数：死循环熔断的依据 */
+    let lastRoundSig = ''
+    let repeatRounds = 0
+    /** 熔断时展示给用户的调用名（比整串指纹可读） */
+    let loopToolNames = ''
+    /** 墙钟用到 80% 时的一次性收敛提醒（不打断流程） */
+    let timeNudged = false
+    /** 单轮上下文裁剪是否已提示过（每轮都可能裁，提示只发一次免得刷屏） */
+    let trimNoticed = false
+    /** 单轮深度压缩是否已提示过（同 trimNoticed，免刷屏） */
+    let deepNoticed = false
+    /** 网关报上下文溢出后的「压缩 + 重试」次数：最多 2 次，仍超才报错收尾 */
+    let contextRetries = 0
+    /** 网关静默空回复（无正文 / 无工具 / 无 finish 标记）的重试次数：最多 1 次 */
+    let emptyRetries = 0
+    /** 熔断收尾的人话原因：随 turn-ended 事件落进对话记录，重开面板仍看得见「这轮为什么停」 */
+    let budgetWhy = ''
+    let currentMessages = fullMessages
+    /** 本轮工具产出的待注入图像（截图 / 并排对比图）：下一次 callLLM 前打包成一条 user 消息 */
+    const visionQueue = []
+    /** 思考熔断后是否已催促重试过一次：重试仍超时才报错，给推理网关一次收敛机会 */
+    let thinkingNudged = false
+    /** 重试轮关闭深度思考：实测推理模型会在思考里逐字拼完整 IR / schema，两轮 240s 都产不出工具调用 */
+    let retryNoThinking = false
+    /** 深度思考总开关（设置为关时每轮都走 NO_THINKING_BODY） */
+    const thinkingEnabled = config.thinking === undefined ? defaults.thinking !== false : Boolean(config.thinking)
+
+    try {
+      while (HARD_STEPS === 0 || step < HARD_STEPS) {
+        if (aborted) break
+        step++
+
+        // 熔断②墙钟：不限步数后，唯一能兜住「无限跑下去」的闸门（到点收尾汇报，上下文不丢）
+        const elapsedMs = Date.now() - turnStartedAt
+        if (elapsedMs > turnTimeoutMs) {
+          budgetReason = 'timeout'
+          break
+        }
+        if (!timeNudged && elapsedMs > turnTimeoutMs * 0.8) {
+          timeNudged = true
+          sseWrite(res, {
+            type: 'notice',
+            message: `本轮已跑 ${fmtDuration(elapsedMs)}（墙钟上限 ${fmtDuration(turnTimeoutMs)}）：已要求模型优先落盘 / 给结论`,
+          })
+          currentMessages.push({
+            role: 'user',
+            content: `[系统提醒] 本轮墙钟预算只剩 20%（上限 ${fmtDuration(turnTimeoutMs)}）：立即收敛——优先 card_write / card_patch 落盘或给出正文结论与下一步，不要再读资料、不要开新战线。`,
+          })
+        }
+        // 熔断③软提醒：每 SOFT_NUDGE_EVERY 步催一次收敛，但**不打断**（步数多不等于空转）
+        if (SOFT_NUDGE_EVERY > 0 && step % SOFT_NUDGE_EVERY === 0) {
+          sseWrite(res, {
+            type: 'notice',
+            message: `本轮已用 ${step} 步工具调用（步数不设硬顶）：提醒模型收敛，别在同类信息上重复取数`,
+          })
+          currentMessages.push({
+            role: 'user',
+            content: `[系统提醒] 本轮已进行 ${step} 步工具调用（不设硬顶，但别空转）：自查是否已拿到足够证据——能落盘就 card_write / card_patch / iterate.mjs 落盘并推进到下一门禁；同类信息只读一次，不要重复读同一份资料、不要重跑同一条命令。`,
+          })
+        }
+
+        // 熔断④上下文：步数不限后工具结果会一路累积，撑爆网关窗口 = 整轮 400 报废。
+        // 每轮发请求前先按预算折叠早期工具结果 / 注入图像（最近 TRIM_KEEP_RECENT 条保持原文）
+        const turnTrim = trimTurnContext(currentMessages, { budgetTokens: turnContextBudget })
+        // 输入框圆环的数据源：本轮**实际送进网关**的上下文量（裁剪后），有窗口认知时前端按窗口画环
+        sseWrite(res, { type: 'context-usage', used: turnTrim.tokens, total: turnContextBudget, window: knownWindow })
+        if (clampNotice) sseWrite(res, { type: 'notice', message: clampNotice })
+        if (turnTrim.trimmed) {
+          currentMessages = turnTrim.messages
+          if (!trimNoticed) {
+            trimNoticed = true
+            sseWrite(res, {
+              type: 'notice',
+              message: `单轮上下文接近预算（约 ${turnTrim.before} token，上限 ${turnContextBudget}）：已折叠 ${turnTrim.trimmed} 条早期工具结果 / 图像，最近 ${TRIM_KEEP_RECENT} 条保持原文`,
+            })
+          }
+        }
+        // 深度压缩：折叠工具结果后仍超预算 ⇒ 整组丢弃最早的工具调用并留摘要。
+        // 任务消息与最近工作记忆保留原文，压缩完循环照常继续（用户要求：主动压缩且不断任务）
+        const estNow = currentMessages.reduce((a, m) => a + openAiMsgTokens(m), 0)
+        if (estNow > turnContextBudget) {
+          const deep = deepCompactTurn(currentMessages, turnContextBudget)
+          if (deep.droppedGroups) {
+            currentMessages = deep.messages
+            if (!deepNoticed) {
+              deepNoticed = true
+              sseWrite(res, {
+                type: 'notice',
+                message: `单轮上下文约 ${deep.before} token 超预算 ${turnContextBudget}：已深度压缩最早 ${deep.droppedGroups} 组工具调用为摘要（任务与最近 ${DEEP_KEEP_RECENT} 条保持原文），任务继续`,
+              })
+            }
+          }
+        }
+
+        let assistantContent = ''
+        let assistantToolCalls = null
+        let roundProgressAt = Date.now()
+        let lastDeltaAt = Date.now()
+        let roundTimedOut = false
+        let roundStalled = false
+        let finishReason = ''
+
+        // 轮级 AbortController：思考熔断 / 静默看门狗只杀当前轮；客户端断开经 AbortSignal.any 一并生效
+        const roundCtl = new AbortController()
+        // 巡检间隔跟随阈值缩放（500ms~5s）：既不误杀首 token 慢的大上下文请求，也能尽快发现真静默
+        const watchdog = setInterval(() => {
+          if (aborted || roundTimedOut || roundStalled) return
+          if (Date.now() - lastDeltaAt > stallTimeoutMs) {
+            roundStalled = true
+            roundCtl.abort()
+          }
+        }, Math.min(5000, Math.max(500, Math.floor(stallTimeoutMs / 4))))
+        const gen = callLLM({
+          baseUrl: finalConfig.baseUrl,
+          apiKey: finalConfig.apiKey,
+          model: finalConfig.model,
+          messages: currentMessages,
+          tools,
+          maxTokens: finalConfig.maxTokens,
+          // 用户关了深度思考 ⇒ 每轮都关；否则正常带思考，只有熔断重试那一轮强制关（见下）
+          extraBody: retryNoThinking || !thinkingEnabled ? NO_THINKING_BODY : undefined,
+          signal: AbortSignal.any([abortCtl.signal, roundCtl.signal]),
+        })
+
+        // 看门狗必须在任何退出路径上都清掉：残留 setInterval 会让进程（与测试）无法退出
+        try {
+          for await (const evt of gen) {
+            if (aborted) break
+            lastDeltaAt = Date.now()
+            switch (evt.type) {
+              case 'reasoning-delta':
+                if (Date.now() - roundProgressAt > reasoningTimeoutMs) {
+                  roundTimedOut = true
+                  roundCtl.abort()
+                  break
+                }
+                sseWrite(res, { type: 'reasoning-delta', text: evt.text })
+                break
+              case 'text-delta':
+                roundProgressAt = Date.now()
+                assistantContent += evt.text
+                sseWrite(res, { type: 'text-delta', text: evt.text })
+                break
+              case 'tool-call-start':
+                roundProgressAt = Date.now()
+                sseWrite(res, {
+                  type: 'tool-call-start',
+                  toolName: evt.toolName,
+                  toolCallId: evt.toolCallId || '',
+                  index: evt.index,
+                })
+                break
+              case 'finish':
+                if (evt.reason) finishReason = evt.reason
+                break
+              case 'notice':
+                sseWrite(res, { type: 'notice', message: evt.text })
+                break
+              case 'tool-calls':
+                roundProgressAt = Date.now()
+                assistantToolCalls = evt.toolCalls
+                for (const tc of evt.toolCalls) {
+                  sseWrite(res, {
+                    type: 'tool-call',
+                    toolName: tc.function.name,
+                    args: safeParseArgs(tc.function.arguments),
+                    toolCallId: tc.id,
+                  })
+                }
+                break
+            }
+            if (roundTimedOut || roundStalled) break
+          }
+        } catch (e) {
+          // 熔断 / 看门狗主动 abort 时，上游生成器会抛 AbortError：这不是「用户中止」，
+          // 吞掉后交给下面的 roundStalled / roundTimedOut 分支给出准确原因
+          if (roundStalled || roundTimedOut) {
+            /* 吞掉，走下面分支 */
+          } else if (
+            contextRetries < 2 &&
+            (e?.code === 'context-overflow' ||
+              (/LLM 400/.test(String(e && e.message)) && /context|length|token/i.test(String(e && e.message))))
+          ) {
+            // 网关报上下文溢出：callLLM 已按详情分类（减半救不了的才带 context-overflow 标记抛出），
+            // 说明是**输入**超窗。压缩后重试同一步（此刻尚未追加 assistant 消息，无悬空 tool_calls），任务不中断
+            contextRetries++
+            const tight = Math.max(4000, Math.floor(turnContextBudget * 0.6))
+            const deep = deepCompactTurn(currentMessages, tight, Math.max(4, DEEP_KEEP_RECENT - 2), true)
+            currentMessages = deep.droppedGroups
+              ? deep.messages
+              : trimTurnContext(currentMessages, { budgetTokens: tight, keepRecent: 4, stubChars: 200 }).messages
+            sseWrite(res, {
+              type: 'notice',
+              message: `网关报上下文溢出（HTTP 400）：已${deep.droppedGroups ? `深度压缩 ${deep.droppedGroups} 组早期工具调用` : '加强折叠早期工具结果'}后自动重试本步，任务不中断`,
+            })
+            continue
+          } else {
+            throw e
+          }
+        } finally {
+          clearInterval(watchdog)
+        }
+
+        if (finishReason === 'length') {
+          // 输出被截断：本轮的正文 / 工具参数都不可信，别拿去执行（半截 JSON 会得到莫名其妙的报错）
+          sseWrite(res, {
+            type: 'error',
+            message: `本轮输出被单次输出上限（max_tokens=${finalConfig.maxTokens}）截断，结果不可用。请在设置里调高「单次输出上限」，或要求 AI 走紧凑 IR 路线（fs_write 写 .cache/ai-scratch/*.ir.json → expand_ir.mjs 展开），不要一次性输出整份 schema`,
+          })
+          break
+        }
+
+        if (roundStalled) {
+          sseWrite(res, {
+            type: 'error',
+            message: `上游 ${Math.round(stallTimeoutMs / 1000)} 秒没有返回任何数据（网关静默），已中止本轮：请重试或检查模型服务`,
+          })
+          break
+        }
+
+        if (roundTimedOut) {
+          if (!thinkingNudged) {
+            // 第一次熔断：不报错，插入催促 + **关掉深度思考**再给一轮机会。
+            // 只催促不关思考实测无效：模型继续用思考逐字草拟 schema，第二轮同样超时，整轮 10 分钟零产出。
+            thinkingNudged = true
+            retryNoThinking = true
+            sseWrite(res, {
+              type: 'notice',
+              message: `本轮思考超过 ${Math.round(reasoningTimeoutMs / 1000)} 秒仍无产出：已关闭深度思考并催促模型直接落盘，重试一次`,
+            })
+            currentMessages = [
+              ...currentMessages,
+              {
+                role: 'user',
+                content: `[系统催促] 思考预算已用完：立即停止分析，本轮**必须**以一次工具调用收尾（fs_write 写 IR / card_write / card_patch / card_scaffold），或直接用正文回复结论；不要再读取任何资料、不要复述卡片数据、不要在脑子里逐字草拟 JSON。${designFlow ? '建卡走 IR 路线：fs_write 把紧凑 IR 写到 .cache/ai-scratch/<id>.ir.json，再用 skill_exec 跑 expand_ir.mjs 展开，一次调用就能落盘整卡；落盘后仍须跑完 check_fidelity + iterate.mjs 像素自循环（数值指标，1-2 轮即可）才允许收尾。' : ''}`,
+              },
+            ]
+            continue
+          }
+          sseWrite(res, {
+            type: 'error',
+            message: `两轮思考均超过 ${Math.round(reasoningTimeoutMs / 1000)} 秒仍无产出，已停止。可重试、简化需求或拆成更小步骤`,
+          })
+          break
+        }
+        if (aborted) break
+        // 网关静默空回复：无正文、无工具调用、连 finish 标记都没有——多是上游连接中途被切 / 空流。
+        // 静默 break 会让前端只看到一句「已终止生成」而不知原因（体感就是「卡住后突然死掉」）：
+        // 先明示并自动重试一次；重试仍空才报错收尾
+        if (!assistantToolCalls?.length && !assistantContent && !finishReason && !roundStalled && !roundTimedOut) {
+          if (emptyRetries < 1) {
+            emptyRetries++
+            sseWrite(res, {
+              type: 'notice',
+              message: '网关返回空响应（无正文、无结束标记，连接可能被切断）：自动重试本步一次',
+            })
+            continue
+          }
+          sseWrite(res, {
+            type: 'error',
+            message: '网关连续两次返回空响应（无正文、无结束标记）：本轮已停止。可重试，或检查模型服务 / 网络',
+          })
+          break
+        }
+        if (!assistantToolCalls?.length) break
+
+        // 熔断①原地打转：同工具 + 同参数连续重复（实测最烧钱的失控形态，如反复 fs_read 同一份 spec.json、
+        // 反复跑同一条 iterate --set）。第 2 轮先警告，第 3 轮不再执行、直接收尾汇报。
+        const roundSig = toolRoundSignature(assistantToolCalls)
+        if (roundSig === lastRoundSig) repeatRounds++
+        else {
+          lastRoundSig = roundSig
+          repeatRounds = 1
+        }
+        loopToolNames = [...new Set(assistantToolCalls.map((tc) => tc?.function?.name || '?'))].join(' + ')
+        if (repeatRounds >= LOOP_BREAK_REPEATS) {
+          budgetReason = 'loop'
+          // 协议要求每个 tool_call 都有对应的 tool 结果：回填「已跳过」再收尾，别留下悬空 tool_calls
+          currentMessages = [
+            ...currentMessages,
+            { role: 'assistant', content: assistantContent || null, tool_calls: assistantToolCalls },
+          ]
+          for (const tc of assistantToolCalls) {
+            sseWrite(res, {
+              type: 'tool-result',
+              toolName: tc.function.name,
+              toolCallId: tc.id,
+              error: `已跳过：连续 ${repeatRounds} 轮完全相同的调用（同工具同参数），触发死循环熔断`,
+            })
+            currentMessages.push({
+              role: 'tool',
+              tool_call_id: tc.id,
+              content: `Error: 已跳过——这是连续第 ${repeatRounds} 次完全相同的调用（同工具 + 同参数），说明当前思路拿不到新信息，本轮到此为止。`,
+            })
+          }
+          break
+        }
+
+        currentMessages = [
+          ...currentMessages,
+          { role: 'assistant', content: assistantContent || null, tool_calls: assistantToolCalls },
+        ]
+
+        for (const tc of assistantToolCalls) {
+          if (aborted) break
+          const toolName = tc.function.name
+          const parsedArgs = safeParseArgs(tc.function.arguments)
+          try {
+            let result
+            switch (toolName) {
+              case 'skill_read':
+                result = skillRead(root, parsedArgs)
+                break
+              case 'card_grep':
+                result = cardGrep(root, parsedArgs)
+                break
+              case 'card_patch':
+                result = await cardPatch(root, parsedArgs, dispatch)
+                break
+              case 'fs_read':
+                result = fsRead(root, parsedArgs, mountedRoots)
+                break
+              case 'fs_list':
+                result = fsList(root, parsedArgs, mountedRoots)
+                break
+              case 'fs_write':
+                result = fsWrite(root, parsedArgs)
+                break
+              case 'fs_copy':
+                result = fsCopy(root, parsedArgs, mountedRoots)
+                break
+              case 'skill_exec':
+                result = await runSkillExec(root, parsedArgs, res, approvedTools)
+                break
+              case 'shell_exec':
+                result = await runShellExec(root, parsedArgs, res, approvedTools)
+                break
+              default:
+                result = await dispatch(toolName, parsedArgs)
+            }
+            const { text, image } = splitToolResult(result)
+            sseWrite(res, {
+              type: 'tool-result',
+              toolName,
+              toolCallId: tc.id,
+              result: text.slice(0, 4000),
+              truncated: text.length > 4000,
+              image,
+            })
+            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: text.slice(0, 12000) })
+            // 视觉注入点②：工具产出的图像先入队，循环末尾打包注入（文本模型下 image 恒为 undefined，零开销）
+            if (visionOn && image) {
+              visionQueue.push({ caption: `${toolName} 产出的渲染截图`, part: dataUrlPart(Buffer.from(image.base64, 'base64'), image.mime) })
+            }
+            if (visionOn && toolName === 'skill_exec') {
+              const dm = text.match(/"diffImage"\s*:\s*"([^"]+)"/)
+              if (dm) {
+                const part = await fileToVisionPart(path.isAbsolute(dm[1]) ? dm[1] : path.join(root, dm[1]))
+                if (part) visionQueue.push({ caption: '设计稿 vs 渲染并排对比（左=设计，右=渲染）', part })
+              }
+            }
+          } catch (e) {
+            const errMsg = String(e?.message || e)
+            sseWrite(res, { type: 'tool-result', toolName, toolCallId: tc.id, error: errMsg })
+            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: `Error: ${errMsg}` })
+          }
+        }
+
+        // 视觉注入点②收尾：把本轮工具产出的图像打包成一条 user 消息回喂（数值指标仍是收敛判据）
+        if (visionOn && visionQueue.length) {
+          const batch = visionQueue.splice(0, VISION_INJECT_MAX)
+          currentMessages.push({
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: '[视觉] 以下图像为上面工具调用的渲染结果 / 对比图，可直接读图定位差异；收敛判据仍是 pixelDiff.match 与 check_fidelity。',
+              },
+              ...batch.flatMap((v) => [{ type: 'text', text: v.caption }, v.part]),
+            ],
+          })
+        }
+
+        // 连续第 2 轮相同调用：先给一次明确的「换证据链」警告（第 3 轮才熔断），多数模型这一句就能纠偏
+        if (!aborted && repeatRounds >= 2) {
+          sseWrite(res, {
+            type: 'notice',
+            message: `连续第 ${repeatRounds} 轮完全相同的工具调用（${loopToolNames}）：已要求换证据链，再重复将熔断收尾`,
+          })
+          currentMessages.push({
+            role: 'user',
+            content: `[系统提醒] 你已连续 ${repeatRounds} 轮发起**完全相同**的工具调用（${loopToolNames}，参数一字不差），结果不会变。立刻换证据链：改参数 / 换工具（如 diff_bands.mjs 取逐带 dy、references/generation_pitfalls.md 查静默丢弃清单），或直接落盘 card_write / card_patch。再重复一次本轮就会被熔断收尾。`,
+          })
+        }
+
+        // 用户设了硬顶且额度快用尽：提前催收敛，别等超限才发现整轮没产出
+        if (!aborted && HARD_STEPS > 0 && step === HARD_STEPS - 2) {
+          sseWrite(res, { type: 'notice', message: `本轮工具额度只剩 2 步：已要求模型优先落盘 / 给结论` })
+          currentMessages.push({
+            role: 'user',
+            content: `[系统提醒] 本轮工具调用额度只剩 2 步：立即收敛——优先 card_write / card_patch 落盘或给出正文结论与下一步，不要再读资料。`,
+          })
+        }
+      }
+
+      // while 条件自然退出 = 用户自设的步数硬顶到顶（不限步数时不会走到这里）
+      if (!budgetReason && !aborted && HARD_STEPS > 0 && step >= HARD_STEPS) budgetReason = 'steps'
+
+      if (aborted) {
+        sseWrite(res, { type: 'aborted' })
+      } else if (budgetReason) {
+        // 预算耗尽不再「报错 + 零正文」：不带工具再问一次，逼出进度汇总与下一步
+        const why =
+          budgetReason === 'loop'
+            ? `检测到连续 ${LOOP_BREAK_REPEATS} 轮完全相同的工具调用（${loopToolNames}），判定为原地打转`
+            : budgetReason === 'timeout'
+              ? `本轮时长已达墙钟上限 ${fmtDuration(turnTimeoutMs)}（共用 ${step} 步工具调用）`
+              : `已达单轮工具调用上限（${HARD_STEPS} 步）`
+        budgetWhy = why
+        sseWrite(res, {
+          type: 'notice',
+          message: `${why}：正在汇总进度与下一步，回复「继续」可接着做`,
+        })
+        try {
+          const wrap = callLLM({
+            baseUrl: finalConfig.baseUrl,
+            apiKey: finalConfig.apiKey,
+            model: finalConfig.model,
+            messages: [
+              ...currentMessages,
+              {
+                role: 'user',
+                content: `[系统提醒] ${why}，本轮工具调用已被停止，不要再调用任何工具。用 6 行以内中文汇报：①已经做完什么（含跑过的脚本与产物路径）②卡在哪${
+                  budgetReason === 'loop'
+                    ? '（为什么重复同一条调用拿不到新信息、下一步该换哪条证据链）'
+                    : ''
+                } ③用户下一步该说什么（例如「继续」${budgetReason === 'loop' ? '，或直接给出新思路' : ''}）。`,
+              },
+            ],
+            maxTokens: 2048,
+            extraBody: NO_THINKING_BODY,
+            signal: abortCtl.signal,
+          })
+          for await (const evt of wrap) {
+            if (aborted) break
+            if (evt.type === 'text-delta') sseWrite(res, { type: 'text-delta', text: evt.text })
+            else if (evt.type === 'reasoning-delta') sseWrite(res, { type: 'reasoning-delta', text: evt.text })
+          }
+        } catch (e) {
+          sseWrite(res, {
+            type: 'error',
+            message: `${why}，收尾汇总也失败：${String((e && e.message) || e)}`,
+          })
+        }
+      }
+      // 熔断 / 硬顶收尾都补一条持久事件：notice 横幅 6 秒就没了，对话记录里要留得住「为什么停」
+      if (!aborted && budgetWhy) sseWrite(res, { type: 'turn-ended', reason: budgetReason, message: budgetWhy })
+      sseWrite(res, { type: 'done' })
+    } catch (e) {
+      if (!aborted) {
+        console.error('[ai-chat] failed:', e)
+        const msg = String((e && e.message) || e)
+        sseWrite(res, { type: 'error', message: /aborted/i.test(msg) ? '请求已中止' : msg })
+      }
+      sseWrite(res, { type: 'done' })
+    } finally {
+      req.off('close', onClose)
+      req.off('aborted', onClose)
+      res.off('close', onClose)
+      if (!res.writableEnded) res.end()
+    }
+  }
+}
+
+// 单测入口（tools/tests/ai-chat-shell-gate.test.mjs）：网关与压缩是纯函数，直接断言
+export {
+  assertShellAllowlist,
+  segmentCommandWord,
+  shellSubCommands,
+  trimTurnContext,
+  deepCompactTurn,
+  compactContext,
+}
+
+export default createAiChatMiddleware