dsh-drawai 0.4.1 → 0.4.3

package/lib/index.js

@@ -257,6 +257,26 @@ function messageOf(error) {
   return String(error)
 }
 
+// json 参数在工具 schema 里编译成 `{}`（没有类型约束），有的模型/宿主会把它当成字符串送进来，
+// 比如 frames 收到的是 "[0, 120]"。这里统一还原一次：看起来像 JSON 且解析成功就用解析结果，
+// 否则原样返回。不这么做的话，Array.isArray(字符串) 恒为假，参数会被静默忽略、退回默认值。
+function jsonValue(value) {
+  if (typeof value !== 'string') return value
+  const text = value.trim()
+  if (!text || !'[{"]-0123456789ntf'.includes(text[0])) return value
+  try { return JSON.parse(text) } catch { return value }
+}
+
+function jsonObject(value) {
+  const parsed = jsonValue(value)
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+}
+
+function jsonArray(value) {
+  const parsed = jsonValue(value)
+  return Array.isArray(parsed) ? parsed : []
+}
+
 function numberOr(value, fallback) {
   const n = Number(value)
   return Number.isFinite(n) ? n : fallback
@@ -2386,6 +2406,12 @@ function placeMissing(doc) {
 
 /** 画布写回端点：人工编辑唯一的落盘通道。 */
 export const SAVE_PATH = '/drawai/api/save'
+/**
+ * 只读诊断端点：把"这次到底注册了哪几个 host 工具"直接摆出来。
+ * 起因是 issue #8 —— 画布能用、apply 也确实跑过，但模型侧一个工具都没有；
+ * 现场只有一张截图，缺的正是这条数据（没注册 / 注册报错 / 注册完又被回收）。
+ */
+export const DIAGNOSTICS_PATH = '/drawai/api/diagnostics'
 /** 「打开」菜单最多下钻几个子目录 —— 不做全盘递归，避免撞上 node_modules 这类大目录。 */
 const MAX_SCAN_DIRS = 12
 /** 自定义请求头 —— 跨站表单设不了它，跨域 fetch 会被预检拦住（CSRF 围栏）。 */
@@ -2441,9 +2467,40 @@ export const inject = ['tools', 'fs', 'sessions', 'sandboxPolicy', 'webServer']
  * 它出现在会话的技能目录里，模型需要时按需取全文 —— 于是"怎么在这张画布上操作"这件事
  * 跟着插件走，而不是跟着这份仓库走。
  *
+ * **拆成两份**（drawai-canvas / drawai-video），因为这是两种任务、两套工具族：画布那份讲
+ * diagram_read / diagram_apply 的全部 op 与几何规则，视频那份讲十步制作流程与 motion_* 那组工具。
+ * 合成一份时正文近三万字，而技能目录里只显示 description 那一句 —— 用户说"做个宣传片"会先被
+ * "读写画布"这句挡住；分开后两条简介各自对口，画图的人也不必每次为视频流程付上下文。
+ * 视频那份自带一段"画布最小集"（见下），单独加载也不会写错 op；画布那份末尾指向视频技能。
+ *
  * 写成模板串但**不用反引号**（markdown 里要写示例，反引号会破坏模板串）：代码块用四空格缩进。
+ * 两份各自是独立模板串；`tools/build.mjs` 的反引号配平检查按整份文件数，照样管得住。
  */
-const SKILL_BODY = `# DrawAI 画布：怎么读、怎么改
+
+/** 技能 1/2：视频。位置保持原样（正文接在原来的地方），改动只剩标题与开头那段最小集。 */
+const SKILL_BODY_VIDEO = `# DrawAI 画布做视频：从问到出片
+
+这个技能只讲**怎么把一条片子做出来**。画布怎么读、怎么改（diagram_read / diagram_apply 的完整签名、
+折点与端点、图层与顺序、traceImage 位图矢量化）在技能 drawai-canvas 里 —— 视频流程真正用到的那几个 op
+下面列全了，不够用时再加载那个技能。
+
+## 画布最小集（视频只用到这些 op）
+
+    // 1) 先读回当前那张画布：用户说"这张"就别猜路径，不传 path 读一次
+    diagram_read()                       // → { path, absolute, nodes, edges, ... }，path 拿去给 apply
+    // 2) 一次写完：建节点、连卡、放分镜表；几何已经规划好就 layout:"none"
+    diagram_apply({ path, layout:"none", ops:[
+      {op:"addNode", label:"分镜表", shape:"text", x:40, y:40, w:520, h:360, as:"board"},
+      {op:"addNode", label:"主片", shape:"video", x:600, y:40, w:480, h:270, as:"film"},
+      {op:"addEdge", from:"shot-card", to:"film"}   // shot-card 是画布上已存在的镜头卡 id
+    ]})
+
+- **path 必填**：diagram_apply 永远要显式传 path；diagram_read 不传时返回当前聚焦的那张。
+- **from / to 必须是已存在的节点 id**（写错在写盘前就报错）；as 起的别名只在同一次 ops 数组里有效。
+- **建了镜头卡就必须连**：断连的卡既没进 assets、也不排期，motion_project create 会直接报错。
+- 连线用圆角折线，折点自己规划（points 只放中间转折，不放源/目标连接点），不要启用自动避障。
+- 挪位置用 move，改文字用 setLabel，换样式用 setStyle；改一组就传 ids:[...]。改接边用 setEdge，
+  不要 remove + addEdge 重画 —— 那会丢掉端点约束和折点。
 
 ## 视频节点与工作流编排
 
@@ -2500,12 +2557,19 @@ const SKILL_BODY = `# DrawAI 画布：怎么读、怎么改
 参考图：diagram_apply 连接图片节点后会把画布快照冻结进工程 assets/，场景里通过 props.assets 取用。视频参数（宽高/fps/duration）在 motion_project create 时写入节点；用户指定时长必须显式传 duration（支持 9.3 等小数秒），不能只写在 prompt 里。
 旧任务记录用 motion_task list/status/cancel/apply/focus/remove 管理，不要再指望它 start。多页或多个视频时明确指定 page/nodeId。
 不要把这条流程想成"提交一个任务等结果"：你是在一个普通工程里写代码、看图、渲染，每一步都由本次对话直接完成。
+`
+
+/** 技能 2/2：画布。正文从原来的位置原样接上，只多了标题下的一条"做视频去那边"。 */
+const SKILL_BODY_CANVAS = `# DrawAI 画布：怎么读、怎么改
 
 ## 一句话
 工作区里任何一个 .drawio 文件**就是**一张 DrawAI 画布 —— 它是 drawio 自己的 mxfile 格式。
 用户在 DSH 右栏画布面板里看到的、以及用 drawio 桌面版打开的，是同一份文件；
 没有"导入/导出"这一步，你直接读写这个文件就是读写那张画布。
 
+视频节点、镜头卡、分镜表也都是这张画布上的对象，但**做视频**（选卡、写分镜表、出样片与成片）
+是另一套流程：加载技能 drawai-video。这里只讲怎么读写它们。
+
 ## 两个工具怎么配合
 1. **diagram_read(path?, layer?, ids?)** —— 先读。返回节点（id/label/shape/style/**x·y·w·h 坐标尺寸**）、
    边（id/from/to/label/style/dash/arrow/折点/悬空端的自由点/标签位置 labelX·labelY）、
@@ -2741,8 +2805,12 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
 ## 想看效果图的时候（diagram_read 带 render:true）
 - 传 render:true 就是"让我看一眼这张画布"：正交路由、避让、圆角、文字断线这些
   **只有看图才知道**的东西，几何数据里没有（宿主也不算走线，那是画布算的）。
-- 渲染在画布那一半做，所以是两步：第一次返回 look.status="pending"（已请求），
-  **等几秒再调一次** diagram_read（render:true），图就作为图片内容块跟回来了。
+- 渲染在**浏览器那一半**做，所以只有用户在右侧栏**打开着这张画布**时才有人接活：
+  · 画布没打开（宿主知道你打开的是别的文件）→ look.status="not-open"，附原因，别重试；
+  · 打开了 → 第一次返回 look.status="pending"（已请求，带 waitedMs），**等几秒再调一次**
+    diagram_read（render:true），图就作为图片内容块跟回来了；
+  · 挂了请求却一直没人接（25 秒）→ look.status="timeout"，带已等待秒数 —— 这时别再
+    傻等，要么请用户先打开画布，要么直接用几何数据。
 - **不会在用户的工作区里生成任何文件**：图片存在宿主那边的附件库里（与用户上传图片同一套存储，
   在工作区之外），看完即取走 —— 要再看就再要一次（图不会被反复塞给你）。
 - **纯改图不需要它**：几何、样式、图层、纸张从普通 diagram_read 里就有。
@@ -2782,16 +2850,30 @@ HTML 标签按纯文本显示、图层结构原样保留（画布把它们叠在
 `
 
 /**
- * 技能目录里那一段（模型先看到简介，需要时才取全文）。
+ * 技能目录里那两条（模型先看到简介，需要时才取全文）。
  * 名字用 kebab-case —— DSH 的注册表按名字寻址并要求这个形状。
+ *
+ * description 是**唯一的检索入口**：会话的技能目录只渲染 name + description（whenToUse 不出现在
+ * 目录里），所以两边各写各的任务词，互不侵占 —— 这正是拆分的主要收益。
  */
-const SKILL_SUMMARY = {
-  name: 'drawai-canvas',
-  description:
-    '读写 DrawAI 画布（.drawio）：diagram_read 看现状、diagram_apply 结构化改图；做视频先问清风格与品牌素材（motion_assets gather 可整站自动收集素材/配色/字体/logo）、出过样片再开拍；支持图像复刻、视频分段复刻及 SVG 帧序列导出。',
-  whenToUse:
-    '用户让你画流程图/架构图/泳道图、复刻图片或视频、将视频转为 SVG 帧动画，或让你读/改某张 .drawio 画布，或问"这张图里有什么""画布上怎么操作"时。',
-}
+const SKILL_DEFINITIONS = [
+  {
+    name: 'drawai-canvas',
+    description:
+      '读写 DrawAI 画布（.drawio）：diagram_read 看现状、diagram_apply 结构化改图；支持图像复刻、视频分段复刻及 SVG 帧序列导出。',
+    whenToUse:
+      '用户让你画流程图/架构图/泳道图、复刻图片或视频、将视频转为 SVG 帧动画，或让你读/改某张 .drawio 画布，或问"这张图里有什么""画布上怎么操作"时。',
+    content: SKILL_BODY_CANVAS,
+  },
+  {
+    name: 'drawai-video',
+    description:
+      '用 DrawAI 画布做视频：定镜头卡与整片风格、写分镜表、生成工程、出样片与成片；含品牌素材收集、配音与踩点。',
+    whenToUse:
+      '用户让你做视频/宣传片/产品片/MG 动画、给已有视频改镜头或配音、把画布上的流程做成片子，或问"样片怎么出""镜头卡怎么连""配乐怎么踩点"时。',
+    content: SKILL_BODY_VIDEO,
+  },
+]
 
 /**
  * 列出工作区里的画布文档（非递归进子目录，最多扫 MAX_SCAN_DIRS 个）。
@@ -2853,7 +2935,7 @@ async function listCanvases(root, cwd, dir) {
   if (first.entries === null) notes.push('无法列出 ' + startAbs + '：' + first.error)
   else collect(first.entries, '')
   for (let d = 0; d < dirs.length; d += 1) {
-    const subAbs = toAbsolute(dirs[d], cwd)
+    const subAbs = toAbsolute(dirs[d], startAbs)
     const sub = await readDir(subAbs)
     if (sub.entries === null) {
       notes.push('无法列出 ' + subAbs + '：' + sub.error)
@@ -2868,6 +2950,102 @@ async function listCanvases(root, cwd, dir) {
 
 export function apply(ctx) {
   const documents = createDocumentCoordinator(), mediaSlots = createMediaWorkSlots(2), taskPatches = createTaskPatchJournal()
+
+  // ── host 工具注册的可观测化（issue #8）────────────────────────────────────
+  // 现场是"画布全好、apply 也执行了、模型侧一个工具都没有，而且哪儿都不报错"。
+  // 三种机制必须能被区分开，光凭"apply 进去了"证明不了什么：
+  //   ① apply 期间 tools 服务还没 ACTIVE —— 注册等于扔进空处；
+  //   ② 某个注册抛错，把同一段里后面的注册和收尾一起带走；
+  //   ③ 注册成功了，之后整个 effect scope 被回收 —— 只有"注册了 N 个"这条日志能反推。
+  // 所以每个工具逐项记名、逐项兜错，结果同时挂到 DIAGNOSTICS_PATH 上供远端取证。
+  const toolRegistrations = []
+  const pendingToolRegistrations = []
+  let pendingFlushRequested = false, toolReportLogged = false
+
+  /** 取工具登记表本身；取不到返回 undefined（不抛），调用方据此走挂起路径。 */
+  function toolsService() {
+    const usable = (value) => value !== null && value !== undefined && typeof value.register === 'function'
+    // 两条路都要试：真实 Cordis 走 service 解析（ctx.get），而宿主注入的 ctx 上
+    // tools 也可能是普通属性 —— 只看其中一条会把"可用"误判成"没就绪"。
+    try {
+      if (typeof ctx.get === 'function' && usable(ctx.get('tools'))) return ctx.get('tools')
+    } catch (error) {
+      // 解析本身失败（服务未 ACTIVE）不该中断：接着看直接属性。
+    }
+    try {
+      return usable(ctx.tools) ? ctx.tools : undefined
+    } catch (error) {
+      return undefined
+    }
+  }
+
+  function registerHostTool(tool) {
+    const named = tool !== null && tool !== undefined && typeof tool.name === 'string' && tool.name.length > 0
+    const entry = { name: named ? tool.name : '(unnamed)', ok: false, deferred: false, error: '', disposer: undefined }
+    toolRegistrations.push(entry)
+    const attempt = () => {
+      const tools = toolsService()
+      if (tools === undefined) return false
+      try {
+        const disposer = tools.register(tool)
+        entry.disposer = disposer
+        entry.ok = typeof disposer === 'function'
+        entry.error = entry.ok ? '' : 'register() 没有返回 disposer（tools 服务可能未 ACTIVE）'
+      } catch (error) {
+        entry.ok = false
+        entry.error = messageOf(error)
+      }
+      if (!entry.ok) console.error('[drawai] 工具注册失败 ' + entry.name + '：' + entry.error)
+      return true
+    }
+    if (!attempt()) {
+      // tools 还没就绪：挂起，等它 ACTIVE 再补注册。这里绝不能抛 —— 抛出去会把 apply
+      // 后半段（包括其余 17 个工具）一起带走，那正是 issue #8 里"全没了"的样子。
+      entry.deferred = true
+      pendingToolRegistrations.push({ entry: entry, attempt: attempt })
+      schedulePendingFlush()
+    }
+    return () => {
+      const index = pendingToolRegistrations.findIndex((item) => item.entry === entry)
+      if (index >= 0) pendingToolRegistrations.splice(index, 1)
+      if (typeof entry.disposer === 'function') entry.disposer()
+    }
+  }
+
+  /** 只申请一次；ctx.inject 的回调在 tools ACTIVE 后立刻跑（本来就 ACTIVE 就当场跑）。 */
+  function schedulePendingFlush() {
+    if (pendingFlushRequested) return
+    pendingFlushRequested = true
+    try {
+      ctx.inject(['tools'], () => {
+        for (const item of pendingToolRegistrations.splice(0)) item.attempt()
+        reportToolRegistrations(true)
+      })
+    } catch (error) {
+      console.error('[drawai] 等待 tools 服务就绪失败：' + messageOf(error))
+    }
+  }
+
+  function reportToolRegistrations(final) {
+    const registered = toolRegistrations.filter((item) => item.ok).map((item) => item.name)
+    const failed = toolRegistrations.filter((item) => !item.ok && !item.deferred)
+    const waiting = toolRegistrations.filter((item) => item.deferred).length
+    if (waiting > 0 && final !== true) {
+      console.error('[drawai] ' + registered.length + ' 个 host 工具已注册，' + waiting + ' 个等待 tools 服务就绪')
+      return
+    }
+    if (toolReportLogged) return
+    toolReportLogged = true
+    if (failed.length === 0) console.error('[drawai] 已注册 ' + registered.length + ' 个 host 工具：' + registered.join('、'))
+    else console.error('[drawai] host 工具注册 ' + registered.length + '/' + toolRegistrations.length + ' 成功，失败 ' + failed.length + ' 个：' + failed.map((item) => item.name + '（' + item.error + '）').join('；'))
+  }
+
+  // 注册成功、模型侧却看不见时，这条日志是"插件被卸载 / 上下文被回收"唯一的线索。
+  ctx.effect(() => () => {
+    const registered = toolRegistrations.filter((item) => item.ok).length
+    if (registered > 0) console.error('[drawai] 插件上下文释放：' + registered + ' 个已注册 host 工具随之注销')
+  })
+
   function sessionOf(sessionId) {
     try {
       if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
@@ -3053,7 +3231,9 @@ export function apply(ctx) {
         type: 'boolean',
         description:
           '**看一眼这张画布的渲染结果**（正交路由、避让、圆角、文字断线这些只有看图才知道的东西）。' +
-          '渲染在画布那一半做，所以第一次调用通常回 look.status="pending"（已请求，画布几秒内渲染完），**再调一次**就会带上图片块。' +
+          '渲染在浏览器那一半做，只有用户**在右侧栏打开着这张画布**时才有人接：没打开会回 look.status="not-open"（别重试）；' +
+          '打开了第一次调用回 look.status="pending"（已请求，带 waitedMs），**等几秒再调一次**就会带上图片块；' +
+          '挂着的请求 25 秒没人接就变成 look.status="timeout"（带已等待秒数），别傻等。' +
           '图片经附件通道直接进上下文 —— **不会在你的工作区里生成任何文件**。' +
           '只在确实需要"看"的时候用（判断重叠/压线/观感），纯粹改图不需要它。',
       },
@@ -3103,7 +3283,8 @@ export function apply(ctx) {
               error: { type: 'string' },
             },
           },
-          // 「看一眼」的状态（只有传了 render:true 才有）：pending / ready / unsupported / failed。
+          // 「看一眼」的状态（只有传了 render:true 才有）：
+          // pending / ready / unsupported / failed / not-open / timeout。
           // 图片本身不走 schema，而是走 render 的输出块（见下面的 render()）。
           look: {
             type: 'object',
@@ -3112,6 +3293,8 @@ export function apply(ctx) {
               status: { type: 'string', required: true },
               stale: { type: 'boolean' },
               error: { type: 'string' },
+              // 已经等了多久（毫秒）：pending 时是"已挂请求多久"，timeout 时是"没人接多久"。
+              waitedMs: { type: 'number' },
             },
           },
           // 这张图的附件引用（有图才有）。render() 用它拼出 `{type:'image', attachment}` 块。
@@ -3328,11 +3511,21 @@ export function apply(ctx) {
         if (value.look !== undefined && value.look !== null && typeof value.look.status === 'string') {
           const look = value.look
           if (look.status === 'pending') {
-            lines.push('  👁 已请求渲染这张画布：画布几秒内渲好，**再调一次 diagram_read（render:true）**就能看到图')
+            const waited = Number(look.waitedMs)
+            lines.push(
+              '  👁 已请求渲染这张画布' + (Number.isFinite(waited) && waited > 0 ? '（已等 ' + Math.round(waited / 1000) + ' 秒）' : '') +
+                '：画布几秒内渲好，**再调一次 diagram_read（render:true）**就能看到图',
+            )
           } else if (look.status === 'ready') {
             lines.push('  👁 渲染结果在图块里' + (look.stale === true ? '（**注意：这是你请求渲染时的样子，之后文件又被改过**）' : ''))
           } else if (look.status === 'unsupported') {
             lines.push('  👁 看不了图：' + String(look.error === undefined ? '这个部署没有可用的图片通道' : look.error))
+          } else if (look.status === 'not-open' || look.status === 'timeout') {
+            // 这两种都不是"渲坏了"，而是"根本没人在渲"：别让模型以为再等等就好了。
+            lines.push(
+              '  👁 ' + (look.status === 'not-open' ? '画布没打开，图不会渲出来：' : '渲染请求没人接（超时）：') +
+                String(look.error === undefined ? '请先在右侧栏打开这张画布' : look.error),
+            )
           } else {
             lines.push('  👁 渲染失败：' + String(look.error === undefined ? '未知原因' : look.error))
           }
@@ -3502,8 +3695,9 @@ export function apply(ctx) {
       const exportState = exportStateFor(sessionIdOf(exec), loaded.absolute)
       // 「看一眼」（render:true）：交图，或挂一个渲染请求。
       //
-      // 三道门依次过：附件服务在不在（图片的落脚处）→ 模型声明不声明图片输入 → 手上有没有渲好的图。
-      // 前两道过不去时**给一句人话**（而不是抛错）—— AI 还能照常读几何、改图，只是看不到图。
+      // 四道门依次过：附件服务在不在（图片的落脚处）→ 模型声明不声明图片输入 → 手上有没有渲好的图
+      // → 画布是不是真开着（渲染在浏览器里做，没打开就没人接请求）。
+      // 过不去时**给一句人话**（而不是抛错）—— AI 还能照常读几何、改图，只是看不到图。
       let lookState = undefined
       let imageValue = undefined
       if (args.render === true) {
@@ -3526,18 +3720,45 @@ export function apply(ctx) {
                 imageValue = taken.image
               }
             } else {
-              // 同一张画布已有请求就沿用（客户端按 requestId 去重，换 id 会让它再渲一遍）。
-              const existing = renderRequests.get(sessionIdOf(exec))
-              if (existing === undefined || existing.absolute !== loaded.absolute) {
-                // 换了画布：上一张渲好的图作废（否则会把 A 图的画面当 B 图交给模型）。
-                renderedImages.delete(sessionIdOf(exec))
-                renderRequests.set(sessionIdOf(exec), {
-                  requestId: 'r' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8),
-                  absolute: loaded.absolute,
-                  revision: doc.revision,
-                })
+              // 渲染在**浏览器**里做：只有用户正打开着这张画布时客户端才会接这个请求。
+              // 宿主知道用户看的是**别的**画布时就直接说清楚（not-open）—— 否则会挂一个
+              // 永远等不到回执的请求，模型只能反复重试（issue #12）。聚焦未知时仍按老规矩挂
+              // pending：刚打开的画布可能还没来得及上报，误判成"没开"会更让人困惑。
+              const focusedAbsolute = await focusedAbsoluteOf(sessionIdOf(exec))
+              if (focusedAbsolute !== undefined && samePath(focusedAbsolute, loaded.absolute) === false) {
+                lookState = {
+                  status: 'not-open',
+                  error:
+                    '看不了这张画布的渲染图：右侧栏现在打开的是 ' + focusedAbsolute +
+                    '，渲染请求没有画布接。先把这张画布打开再调一次；只要几何数据的话去掉 render:true。',
+                }
+              } else if (state !== undefined && state.status === 'timeout') {
+                lookState = {
+                  status: 'timeout',
+                  waitedMs: state.waitedMs,
+                  error:
+                    '渲染请求挂了 ' + Math.round(state.waitedMs / 1000) + ' 秒没人接：多半是右侧栏没打开这张画布（或画布与宿主的连接断了）。' +
+                    '先打开它再调一次；只想要几何数据的话去掉 render:true。',
+                }
+              } else {
+                // 同一张画布已有请求就沿用（客户端按 requestId 去重，换 id 会让它再渲一遍）。
+                const existing = renderRequests.get(sessionIdOf(exec))
+                if (existing === undefined || existing.absolute !== loaded.absolute) {
+                  // 换了画布：上一张渲好的图作废（否则会把 A 图的画面当 B 图交给模型）。
+                  renderedImages.delete(sessionIdOf(exec))
+                  renderRequests.set(sessionIdOf(exec), {
+                    requestId: 'r' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8),
+                    absolute: loaded.absolute,
+                    revision: doc.revision,
+                    // 请求挂上的时刻：UI 那半边一直不回执时，靠它算"已经等了多久"（见 renderStateFor 的超时）。
+                    at: Date.now(),
+                  })
+                }
+                lookState = {
+                  status: 'pending',
+                  waitedMs: state !== undefined && state.status === 'pending' ? state.waitedMs : 0,
+                }
               }
-              lookState = { status: 'pending' }
             }
           }
         }
@@ -4023,7 +4244,11 @@ export function apply(ctx) {
       // mode 回落到 'dagre-tb'，人手工摆好的版面被整张重排 —— 正是上面那个判断要防的事。
       // 教训：用整体赋值覆盖 meta 时，"没被显式处理"的字段会静默消失；新增 meta 字段时先看这里。
       const routingResult = documentRouter.update(routingBefore, doc)
-      if (routingResult.failed.length) notes.push('~ 自动避障暂无可用通道：' + routingResult.failed.join(', '))
+      if (routingResult.unavailable !== undefined) {
+        // 引擎整体不可用（最常见：从 git 装的包少了 lib/routing/vendor/*）时，写回照常进行，
+        // 只是这次没有自动路线。回执里必须说清楚，否则模型会以为"改完就是没走线"。
+        notes.push('~ 自动避障不可用（' + routingResult.unavailable + '）：这次保留现有折点，新画的边按直线写回')
+      } else if (routingResult.failed.length) notes.push('~ 自动避障暂无可用通道：' + routingResult.failed.join(', '))
       doc.meta = Object.assign({}, doc.meta, { layout: mode }, pinned ? { pinned: true } : {})
       const rendered = renderDocText(loaded.text, doc, { page: loaded.pageIndex, format: isNativeCanvasPath(loaded.absolute) ? 'drawai' : 'drawio' })
       doc.revision = rendered.revision
@@ -4143,6 +4368,14 @@ function sanitizeNewName(raw) {
   const renderedImages = new Map()
   /** 渲染结果的保鲜期：超过它就不再交付（要新的请重新请求一次，免得给模型看一张老图）。 */
   const RENDER_TTL_MS = 5 * 60 * 1000
+  /**
+   * 挂着的渲染请求多久没人接就算超时。
+   *
+   * 渲染在浏览器里做：用户没打开画布时这条请求**根本没人接**，而旧代码只会一直回 pending
+   * （issue #12：请求没有过期，模型分不清"正在渲"和"没人渲"）。25 秒足够大画布渲完，
+   * 超过它就该如实说"没人接"而不是让模型反复重试。
+   */
+  const RENDER_PENDING_TTL_MS = 25 * 1000
 
   /** 附件服务（可选依赖）：这个部署没装它就没法"看图"，但插件其余功能照旧。 */
   function attachmentsService() {
@@ -4196,13 +4429,21 @@ function sanitizeNewName(raw) {
   /**
    * 「看图」这条路当前的可用性 + 待交付的图。
    *
-   * 状态：`pending`（已请求，等画布渲染）/ `ready`（有图，这一次带回模型）/
+   * 状态：`pending`（已请求，等画布渲染，带 waitedMs）/ `ready`（有图，这一次带回模型）/
+   * `timeout`（挂了超过 RENDER_PENDING_TTL_MS 没人接，带 waitedMs —— 多半是画布没打开）/
    * `unsupported`（这个部署/模型看不了图，附一句为什么）/ `failed`（渲染回执说失败了）。
    */
   function renderStateFor(sessionId, absolute, revision) {
     if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
     const pending = renderRequests.get(sessionId)
-    if (pending !== undefined && pending.absolute === absolute) return { status: 'pending' }
+    if (pending !== undefined && samePath(pending.absolute, absolute)) {
+      const since = Number(pending.at)
+      const waitedMs = Number.isFinite(since) ? Math.max(0, Date.now() - since) : 0
+      // 不删这条请求：迟到一步的回执还要按 requestId 配回来（删了就永远配不上）。
+      // 只是不再说"pending"——模型至少知道"没人接"，而不是"正在渲"。
+      if (waitedMs > RENDER_PENDING_TTL_MS) return { status: 'timeout', waitedMs: waitedMs }
+      return { status: 'pending', waitedMs: waitedMs }
+    }
     const done = renderedImages.get(sessionId)
     if (done === undefined || done.absolute !== absolute) return undefined
     if (Date.now() - done.at > RENDER_TTL_MS) {
@@ -4351,6 +4592,33 @@ function sanitizeNewName(raw) {
     return focusedCanvas.get(sessionId)
   }
 
+  /** 两个绝对路径是不是同一个文件（Windows 大小写不敏感、斜杠两种都认）。 */
+  function samePath(a, b) {
+    if (a === b) return true
+    if (typeof a !== 'string' || typeof b !== 'string') return false
+    if (process.platform !== 'win32') return false
+    return a.replace(/\//g, '\\').toLowerCase() === b.replace(/\//g, '\\').toLowerCase()
+  }
+
+  /**
+   * 用户此刻打开的那张画布的**绝对路径**（归一后）；没上报过 / 解析不出来 → undefined。
+   *
+   * 只给「看图」的门禁用（diagram_read 的 render:true 分支）：渲染发生在浏览器里，只有**用户正打开着**
+   * 这张画布时客户端才接请求，否则请求永远挂着（issue #12）。聚焦路径是客户端上报的、
+   * 可能是相对工作区的，所以这里统一 resolve + processPath 成与 `loaded.absolute` 同一套形状。
+   */
+  async function focusedAbsoluteOf(sessionId) {
+    const raw = focusedPathFor(sessionId)
+    if (raw === undefined || raw.length === 0) return undefined
+    const root = workspaceRootOf(sessionId)
+    if (root === undefined) return undefined
+    try {
+      return ctx.fs.processPath(await ctx.fs.resolve(raw, { cwd: root }))
+    } catch (error) {
+      return undefined
+    }
+  }
+
   /** 用户画布当前页（0 起）；没上报过则 0。 */
   function focusedPageFor(sessionId) {
     if (typeof sessionId !== 'string' || sessionId.length === 0) return 0
@@ -4917,8 +5185,10 @@ function sanitizeNewName(raw) {
           sendJson(res, 400, { ok: false, error: 'resolve failed: ' + messageOf(error) })
           return
         }
+        // rootTarget 两个 try 都要用（包含校验 + 响应里的 root 字段），声明放到 if 块这一层。
+        let rootTarget
         try {
-          const rootTarget = await ctx.fs.resolve(root)
+          rootTarget = await ctx.fs.resolve(root)
           if (!ctx.fs.contains(rootTarget, dirTarget)) {
             sendJson(res, 403, { ok: false, error: '目录不在工作区内：' + absoluteHint(dirTarget, dir) })
             return
@@ -4932,15 +5202,18 @@ function sanitizeNewName(raw) {
           // 同时给出**绝对路径**：客户端按路径去重（同一个文件不该开出两个标签），
           // 而标签上的路径可能来自 tab 的资源地址（绝对），与列表里的相对路径不相等。
           // 让客户端用绝对路径当"身份"，就不会重复开标签。
+          // listed.files 里的相对路径是**相对 dir** 的，必须拼回 dir —— 拼到工作区根会指到
+          // 一个不存在的同名文件（issue #19：子目录里的画布「列得出、打不开」）。
+          const dirAbs = absoluteHint(dirTarget, dir)
           const abs = []
-          for (let i = 0; i < listed.files.length; i += 1) abs.push(toAbsolute(listed.files[i], root))
+          for (let i = 0; i < listed.files.length; i += 1) abs.push(toAbsolute(listed.files[i], dirAbs))
           sendJson(res, 200, {
             ok: true,
             files: listed.files,
             absolute: abs,
             notes: listed.notes,
-            root: absoluteHint(root, root),
-            dir: absoluteHint(dirTarget, dir),
+            root: absoluteHint(rootTarget, root),
+            dir: dirAbs,
           })
         } catch (error) {
           sendJson(res, 500, { ok: false, error: 'list failed: ' + messageOf(error) })
@@ -4956,7 +5229,7 @@ function sanitizeNewName(raw) {
           files: listed.files,
           absolute: abs,
           notes: listed.notes,
-          root: absoluteHint(root, root),
+          root: absoluteHint(await ctx.fs.resolve(root), root),
         })
       } catch (error) {
         sendJson(res, 500, { ok: false, error: 'list failed: ' + messageOf(error) })
@@ -6189,9 +6462,27 @@ function sanitizeNewName(raw) {
     sendJson(res, 200, { ok: true, revision: rendered.revision, path: absolute, dropped: rendered.dropped, ...(backgroundPatch ? { backgroundPatch } : {}) })
   }
 
+  /**
+   * 只读诊断：不碰画布、不改文件，只回答"这个进程里到底注册上了哪几个 host 工具"。
+   * issue #8 那种"画布能用、工具全没"的现场，把这个 URL 的 JSON 贴回来就够了。
+   */
+  function handleDiagnostics(_req, res) {
+    sendJson(res, 200, {
+      ok: true,
+      plugin: 'dsh-drawai',
+      toolsService: toolsService() !== undefined,
+      registered: toolRegistrations.filter((item) => item.ok).map((item) => item.name),
+      pending: toolRegistrations.filter((item) => item.deferred).map((item) => item.name),
+      failed: toolRegistrations.filter((item) => !item.ok && !item.deferred).map((item) => ({ name: item.name, error: item.error })),
+    })
+  }
+
+  // 诊断路由排在写回路由之前：自测按 routes[last] 取写回路由，这个顺序不能反过来。
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: DIAGNOSTICS_PATH, handler: handleDiagnostics }), 'drawai: ' + DIAGNOSTICS_PATH)
+
   ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: SAVE_PATH, handler: handleSave }), 'drawai: ' + SAVE_PATH)
 
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'shotcraft_search',
     description: '搜索 DrawAI 内置的 124 张 Shotcraft 镜头卡 / 150 个准确样式。按关键词（中英文卡名、样式、用途）和分类检索；返回唯一 demo、样片及可用于 diagram_apply 的节点参数。先搜索再添加 shape:shotcard 节点并连到视频节点，支持同时参考多卡。',
     parameters: { query: { type: 'string' }, category: { type: 'string' }, cardId: { type: 'string', description: '精确卡名，查看该卡所有样式；配合 styleKey 会直接返回这张卡的配方与 demo 源码' },
@@ -6218,7 +6509,7 @@ function sanitizeNewName(raw) {
         styles: matches.slice(offset, offset + limit).map((item) => ({ ...withPath(item), node: { op: 'addNode', shape: 'shotcard', cardId: item.cardId, styleKey: item.styleKey } })) }) }
     },
   })))
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'mg_style',
     description: 'DrawAI 内置的 14 种整片 MG 动效风格（mg-styles 库）：扁平矢量 / 线条动画 / 等轴 2.5D / 逐帧手绘 / 拼贴 / 液态 / 形变 / 包豪斯 / 80s 复古 / 玻璃拟态 / 综艺花字 / 粗描边贴纸科普 / 像素 / 赛博 HUD。上游那支 04-3d-render（C4D/Blender 质感的 CGI 软着陆）没有收录：画面是 Blender 离线渲的，插件里没有同等质感的等价物——用 CSS 滤镜凑出来的 CGI 只会更假，需要那种质感就外部渲好当素材回灌（motion_assets capture / 参考段）。这是「整片风格」（一种片子的整体视觉语言），与 shotcraft_search 的「单镜动效卡」互补、可同时用。action:"list" 列出全部；"search" 按关键词检索；"read" 读某个风格的施工包（可检验判据 + 色板 + 字体 + 节奏 + 效果配方 + 上游提示词 + Remotion 移植 brief）；"source" 读上游成片源码正文；**"frames" 从上游 demo 按 cue 时间点抽参考帧**——动态、转场、冲击、颗粒这些只有看帧才知道，写场景前先取。选中后 diagram_apply 加 shape:"mgstyle" 节点并连到视频节点，motion_project 会把风格写进工程主题与 STYLE.md。',
     parameters: { action: { type: 'string', enum: ['list', 'search', 'read', 'source', 'frames'], required: true },
@@ -6283,10 +6574,10 @@ function sanitizeNewName(raw) {
       throw new Error('未知 action：' + action)
     },
   })))
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name:'audio_asset',
     description:'为画布搜索和导入音频。search 从 Freesound 搜索；get 按 fs:数字 下载并创建音频节点；import 从当前工作区导入 mp3/wav/m4a/aac/ogg/flac/webm，32MB/10分钟以内；targetId 可自动连接视频。configure 修改音频节点的 audioRole(sfx/bgm/voice)、audioGainDb、audioTrimStart/End(秒，End=0至末尾)、audioAt(全片秒)、audioFadeIn/Out(秒)、audioLoop(字符串0/1)。inspect 返回素材来源、哈希和检测结果。音频需要连接到视频；motion_task settings.audioMode=auto让AI安排镜头声音，manual使用节点参数或audioPlan，off静音；remix只重混已有成片。没有真实试听不得宣称听感通过。',
-    parameters:{action:{type:'string',enum:['search','get','import','configure','inspect'],required:true},path:{type:'string'},page:{type:'number'},query:{type:'string'},limit:{type:'number'},id:{type:'string'},file:{type:'string'},nodeId:{type:'string'},targetId:{type:'string'},role:{type:'string',enum:['sfx','bgm','voice']},settings:{type:'json'},x:{type:'number'},y:{type:'number'}},
+    parameters:{action:{type:'string',enum:['search','get','import','configure','inspect'],required:true},path:{type:'string'},page:{type:'number'},query:{type:'string'},limit:{type:'number'},id:{type:'string'},file:{type:'string'},nodeId:{type:'string'},targetId:{type:'string'},role:{type:'string',enum:['sfx','bgm','voice']},settings:{type:'object',additionalProperties:false,properties:{audioRole:{type:'string',enum:['sfx','bgm','voice']},audioGainDb:{type:'number'},audioTrimStart:{type:'number'},audioTrimEnd:{type:'number'},audioAt:{type:'number'},audioFadeIn:{type:'number'},audioFadeOut:{type:'number'},audioLoop:{type:'string',enum:['0','1']}},description:'configure：要改的音频设置，键名就是节点 data 里的名字（audioRole / audioGainDb / audioTrimStart…）'},x:{type:'number'},y:{type:'number'}},
     output:{schema:{type:'object',additionalProperties:false,properties:{summary:{type:'string',required:true},details:{type:'string',required:true}}},render:(_args,value)=>[{type:'text',text:value.summary+'\n'+value.details}]},
     async execute(args,exec){
       const sessionId=sessionIdOf(exec),path=args.path||focusedPathFor(sessionId)
@@ -6330,8 +6621,8 @@ function sanitizeNewName(raw) {
       })
     }
   })))
-  ctx.effect(() => ctx.tools.register(readTool))
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(readTool))
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_task',
     description: '画布视频节点的任务记录：list 列出任务、status 查某个任务、cancel 取消、focus 在面板定位、remove 移除记录。开始制作请走 motion_project → 改 scene-*.tsx → motion_preview → motion_render；成片回填节点用 motion_render apply。',
     parameters: {
@@ -6505,7 +6796,7 @@ function sanitizeNewName(raw) {
     }
   }
 
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_project',
     description: '视频工程：把画布里的一个视频节点落成磁盘上的小文件工程（timeline.json + scene-<n>.tsx + assets/ + theme.ts）。create 建工程并返回文件清单与分镜表，之后用 read/edit/write 直接改场景文件；open 重新读时间轴、文件清单和主题；theme 换配色（重写 theme.ts，场景里用它的常量就一起变）。这里不启动任何模型，也不渲染。按用户要求确定风格和素材；除非用户要求跳过，先制作 3–6 秒样片并回填到独立的样片视频节点，用户要求先审样时等待反馈。create 前镜头卡必须 addEdge 连到视频节点：连线同时是参考、镜头顺序和段长，画布上有断连的卡会直接报错。',
     parameters: {
@@ -6513,12 +6804,29 @@ function sanitizeNewName(raw) {
       path: { type: 'string', description: '画布路径，省略时使用当前画布' },
       nodeId: { type: 'string', required: true, description: '视频节点 id' },
       page: { type: 'number' },
-      spec: { type: 'json', description: '视频规格 {width,height,fps,duration}，省略时沿用节点设置' },
+      spec: {
+        type: 'object',
+        additionalProperties: true,
+        properties: { width: { type: 'number' }, height: { type: 'number' }, fps: { type: 'number' }, duration: { type: 'number' } },
+        description: '视频规格 {width,height,fps,duration}（像素与秒），省略时沿用节点设置',
+      },
       prompt: { type: 'string', description: '这条视频要什么，会写进 BRIEF.md' },
       segments: { type: 'number', description: '初始分几段，默认 4' },
-      storyboard: { type: 'json', description: '分镜表：[{intent:"这一镜要做什么", onScreen:"画面上出现什么", copy:"配字"}]，按镜头顺序；也可以给 ["一句话"] 简写。会写成 storyboard.md。' },
+      storyboard: {
+        type: 'array',
+        items: { type: 'json' },
+        description: '分镜表：[{intent:"这一镜要做什么", onScreen:"画面上出现什么", copy:"配字"}]，按镜头顺序；也可以给 ["一句话"] 简写。会写成 storyboard.md。',
+      },
       theme: { type: 'string', description: '配色主题名：vintage-kraft / deep-ocean / obsidian-violet / modern-light / midnight / solar-pop / coral-burst / color-play / paper-ink。给了就在工程里生成 theme.ts，场景用 {{PAPER, INK, DUST, STAMP}} 引用。' },
-      themeTokens: { type: 'json', description: '直接给一套色 {page,text,muted,accent,surface,field,border}（优先于 theme）。' },
+      themeTokens: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          page: { type: 'string' }, text: { type: 'string' }, muted: { type: 'string' }, accent: { type: 'string' },
+          surface: { type: 'string' }, field: { type: 'string' }, border: { type: 'string' },
+        },
+        description: '直接给一套色 {page,text,muted,accent,surface,field,border}（#RRGGBB，优先于 theme；也认 paper/card/ink 这些别名）。',
+      },
       style: { type: 'string', description: '整片风格 slug（mg_style list 里的 slug，如 09-bauhaus）。给了就用这个风格：色板当主题、节奏当规格缺省、施工说明与引擎契约写进 STYLE.md。也可以不传，改为在画布上连一个「整片风格」节点。' },
       allowUnlinkedCards: { type: 'boolean', description: 'create 时允许画布上存在没连线的镜头卡（当作灵感，不进 assets/timeline）。默认不允许：断连的卡会同时漏掉参考与排期，所以直接报错，让你补 addEdge。' },
     },
@@ -6532,10 +6840,15 @@ function sanitizeNewName(raw) {
         const node = loaded.doc.nodes.find((item) => item.id === args.nodeId)
         if (!node) throw new Error('找不到视频节点 ' + args.nodeId)
         const dir = projectDirOf(node, scope)
+        // json 参数有可能是字符串（见 jsonValue 注释），先统一还原，后面只读这几个局部量。
+        const specArg = jsonObject(args.spec)
+        const styleArg = jsonValue(args.style)
+        const storyboardArg = jsonValue(args.storyboard)
+        const themeTokensArg = jsonValue(args.themeTokens)
         if (args.action === 'theme') {
           if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读')
           if (!existsSync(dir)) throw new Error('工程还没建：先 action:"create"')
-          const resolved = resolveTheme(args.themeTokens || args.theme)
+          const resolved = resolveTheme(themeTokensArg || args.theme)
           if (!resolved) throw new Error('请给 theme（主题名）或 themeTokens（一套色）。可选主题：' + listThemes().map((item) => item.name).join('、'))
           const written = writeTheme(dir, resolved)
           return { summary: '已换主题：' + written.name, details: JSON.stringify({ dir, theme: written, themes: listThemes() }) }
@@ -6547,10 +6860,10 @@ function sanitizeNewName(raw) {
         }
         if (!isMotionNode(node)) throw new Error('请选择空视频或绘制视频节点')
         const before = { data: JSON.parse(JSON.stringify(node.data)), style: node.style }
-        const style = args.style ? resolveMgStyle(mgStyleCatalog, args.style) : mgStyleOf(loaded.doc, node.id)
+        const style = styleArg ? resolveMgStyle(mgStyleCatalog, styleArg) : mgStyleOf(loaded.doc, node.id)
         const kit = style ? mgStyleKit({ slug: style.slug }) : null
         // 规格优先级：风格节奏（最弱）< 节点上存的 < 这次显式给的
-        const spec = readSpec({ ...rhythmSpec(style?.rhythm), ...(node.data.motion || {}), ...(args.spec || {}) })
+        const spec = readSpec({ ...rhythmSpec(style?.rhythm), ...(node.data.motion || {}), ...specArg })
         const errors = validateSpec(spec)
         if (errors.length) throw new Error('视频规格不合法：' + errors.join('；'))
         const cards = shotCardsOf(loaded.doc, node.id)
@@ -6566,14 +6879,14 @@ function sanitizeNewName(raw) {
         // 这也是"分镜被拆成八条文本节点"能被发现的地方 —— readCanvasSpec 会把它们列出来。
         const canvasSpec = readCanvasSpec(loaded.doc, { fps: spec.fps })
         const storyboardInput = args.storyboard !== undefined
-          ? args.storyboard
+          ? storyboardArg
           : canvasSpec.storyboard.length > 0 ? canvasSpec.storyboard : undefined
         // 显式给了时长就以时长为总长：卡片之间按相对时长等比拉伸，不再被卡片总和改短。
-        const durationGiven = Number(args.spec?.duration) > 0
+        const durationGiven = Number(specArg.duration) > 0
         // 建工程要往 assets/fonts 里拷字体：先确保素材包在（首次会下载一次）。
         await ensureMotionAssets('建视频工程')
         const created = createProject(dir, { spec, prompt: args.prompt ?? node.data.motion?.prompt, segments: args.segments, cards, storyboard: storyboardInput,
-          theme: args.themeTokens || args.theme, style: kit, fitFrames: durationGiven ? spec.totalFrames : 0 })
+          theme: themeTokensArg || args.theme, style: kit, fitFrames: durationGiven ? spec.totalFrames : 0 })
         registerProject(dir)
         const seconds = created.timeline.durationInFrames / created.timeline.fps
         node.data.motion = { ...(node.data.motion || {}), mode: spec.mode, width: created.timeline.width, height: created.timeline.height, fps: created.timeline.fps, duration: Math.round(seconds * 100) / 100,
@@ -6624,7 +6937,7 @@ function sanitizeNewName(raw) {
   // 以前这三块只活在对话里（或 storyboard.md 里），于是"分镜表"在画布上就变成
   // **一镜一个文本节点**——八镜八条，谁也不觉得那是一张表，motion_project 也读不到。
   // 这里给一个工具：建（scaffold）、读（read）、验（validate）。
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_spec',
     description: '画布上的视频规格三块，用**一个节点**写清楚：\n【分镜表】一张 Markdown 六列表（镜头 | 帧区间 | 镜头卡 | 这一镜要做什么 | 屏幕上出现什么 | 文案 / 声音），每一镜一行——**不要一镜建一个节点**；\n【风格】一行一个键（page #F7F3EA / serif "Noto Serif SC" / materials: kraft）；\n【旁白】`## shot-N` 分节，一句一行。\naction:"scaffold" 返回把缺的块摆到视频附近空位的 diagram_apply ops（已有一张【分镜表】就不再建第二张）；"read" 读回来；"validate" 逐条报错（分镜被拆成多条、帧数之和对不上节点时长、镜号不连号…）。motion_project create 不给 storyboard 时会直接读这张表。',
     parameters: {
@@ -6632,10 +6945,21 @@ function sanitizeNewName(raw) {
       path: { type: 'string', description: '画布路径，省略时使用当前画布' },
       nodeId: { type: 'string', description: '视频节点 id（规格块的锚点）' },
       page: { type: 'number' },
-      storyboard: { type: 'json', description: '分镜行 [{intent,onScreen,copy,card,durationFrames}]，或一段 markdown 表；省略时 scaffold 只出表头' },
-      style: { type: 'json', description: '风格：一段文本，或 {palette,fonts,materials}' },
+      storyboard: {
+        oneOf: [{ type: 'array', items: { type: 'json' } }, { type: 'string' }],
+        description: '分镜行 [{intent,onScreen,copy,card,durationFrames}]，或一段 markdown 表；省略时 scaffold 只出表头',
+      },
+      style: {
+        oneOf: [{ type: 'string' }, { type: 'object', additionalProperties: true }],
+        description: '风格：一段文本，或 {palette,fonts,materials}',
+      },
       narration: { type: 'string', description: '旁白脚本（## shot-N 分节，一句一行）' },
-      spec: { type: 'json', description: '视频规格 {width,height,fps,duration}，省略时读节点上的' },
+      spec: {
+        type: 'object',
+        additionalProperties: true,
+        properties: { width: { type: 'number' }, height: { type: 'number' }, fps: { type: 'number' }, duration: { type: 'number' } },
+        description: '视频规格 {width,height,fps,duration}（像素与秒），省略时读节点上的',
+      },
     },
     output: { schema: { type: 'object', additionalProperties: false, properties: { summary: { type: 'string', required: true }, details: { type: 'string', required: true } } },
       render: (_args, value) => [{ type: 'text', text: value.summary + '\n' + value.details }] },
@@ -6644,10 +6968,10 @@ function sanitizeNewName(raw) {
       const loaded = await loadDoc(scope.path, scope.sessionId, args.page)
       const node = args.nodeId ? loaded.doc.nodes.find((item) => item.id === args.nodeId) : loaded.doc.nodes.find(isMotionNode)
       if (!node) throw new Error('找不到视频节点' + (args.nodeId ? ' ' + args.nodeId : ''))
-      const spec = readSpec({ ...(node.data?.motion || {}), ...(args.spec || {}) })
+      const spec = readSpec({ ...(node.data?.motion || {}), ...jsonObject(args.spec) })
       if (args.action === 'scaffold') {
         if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读')
-        const built = scaffoldOps(loaded.doc, { videoNode: node, storyboard: args.storyboard, style: args.style,
+        const built = scaffoldOps(loaded.doc, { videoNode: node, storyboard: jsonValue(args.storyboard), style: jsonValue(args.style),
           narration: args.narration, fps: spec.fps, totalFrames: spec.totalFrames })
         if (built.ops.length === 0) {
           return { summary: '规格块已经齐了（' + built.already.join('、') + '），不必再建',
@@ -6681,14 +7005,22 @@ function sanitizeNewName(raw) {
     },
   })))
 
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_preview',
     description: '渲染工程里的几帧并**直接返回拼图**（同一轮就能看见画面）。第一次调用要打包（约 10–30 秒），之后同一份源码复用缓存只要几秒。frames 是绝对帧号，例如 [0,60,120,180]；省略时取每段的中点（最多 6 帧），定调阶段只写 scene-0 时用它看一张定妆帧。**要看画质（锯齿、色带、字重）就传 crop：只出 1:1 原尺寸局部**，拼图是缩过的，缩过的图看不出这些毛病。',
     parameters: {
       path: { type: 'string' }, page: { type: 'number' }, nodeId: { type: 'string', required: true },
-      frames: { type: 'json', description: '绝对帧号数组，最多 9 帧；省略 = 每段中点' },
+      frames: { type: 'array', items: { type: 'number' }, description: '绝对帧号数组，最多 9 帧；省略 = 每段中点' },
       cols: { type: 'number', description: '拼图列数，默认 3' },
-      crop: { type: 'json', description: '只出局部：{x,y,w,h} 或 {cx,cy,w,h}，像素。传了就按 1:1 原尺寸返回（不缩放），用来判断 AA / 色带 / 字体' },
+      crop: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          x: { type: 'number' }, y: { type: 'number' }, w: { type: 'number' }, h: { type: 'number' },
+          cx: { type: 'number' }, cy: { type: 'number' },
+        },
+        description: '只出局部：{x,y,w,h} 或 {cx,cy,w,h}，像素。传了就按 1:1 原尺寸返回（不缩放），用来判断 AA / 色带 / 字体',
+      },
     },
     output: { schema: { type: 'object', additionalProperties: false, properties: {
       summary: { type: 'string', required: true },
@@ -6704,12 +7036,13 @@ function sanitizeNewName(raw) {
       const node = loaded.doc.nodes.find((item) => item.id === args.nodeId)
       if (!node) throw new Error('找不到视频节点 ' + args.nodeId)
       const dir = projectDirOf(node, scope)
-      const requested = Array.isArray(args.frames) ? args.frames.map(Number).filter((n) => Number.isFinite(n)).slice(0, 9) : []
+      const requestedFrames = jsonArray(args.frames)
+      const requested = requestedFrames.length ? requestedFrames.map(Number).filter((n) => Number.isFinite(n)).slice(0, 9) : []
       const frames = requested.length ? requested : (() => {
         const timeline = readTimeline(dir)
         return timeline.shots.slice(0, 6).map((shot) => shot.startFrame + Math.floor(shot.durationFrames * 0.6))
       })()
-      const preview = await previewProject(dir, { frames, cols: args.cols, crop: args.crop, attachments: ctx.get?.('attachments') })
+      const preview = await previewProject(dir, { frames, cols: args.cols, crop: jsonValue(args.crop), attachments: ctx.get?.('attachments') })
       const payload = { summary: '已渲染 ' + frames.length + ' 帧并拼图' + (preview.crop ? '（1:1 局部 ' + preview.crop.w + '×' + preview.crop.h + '）' : ''), details: JSON.stringify({ frames: preview.frames, sheet: preview.sheet, crop: preview.crop }) }
       const ref = preview.attachment
       if (ref && typeof ref.attachmentId === 'string') {
@@ -6725,15 +7058,15 @@ function sanitizeNewName(raw) {
     },
   })))
 
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_render',
     description: '渲染工程。start 立即返回 jobId（后台跑，不要等）；**start 前会按 STYLE.md 的引擎契约扫工程源码，three / webgl2 风格缺真引擎会直接拒绝渲染**（样片也拦；确实要换实现先在 STYLE.md 写「偏离：引擎 …」）；range 渲的是**样片**（写 .out/pilot.mp4，任务 kind=pilot），不传就是整片（.out/film.mp4）；status 查进度；list 列最近任务；cancel 取消；apply 把渲好的片子回填到视频节点——**nodeId 决定回填到哪个节点**（样片回填到另建的「样片」节点，成片回填到主视频节点），不给 jobId 时主视频节点取整片、样片节点取样片。frames 只渲染指定帧。',
     parameters: {
       action: { type: 'string', enum: ['start', 'status', 'list', 'cancel', 'apply'], required: true },
       path: { type: 'string' }, page: { type: 'number' }, nodeId: { type: 'string', description: 'start：从哪个视频节点对应的工程渲；apply：回填到哪个节点（省略时：主视频节点回填整片、另建的样片节点回填样片）' }, jobId: { type: 'string' },
       source: { type: 'string', enum: ['film', 'pilot'], description: 'apply 时回填哪一种：film=整片（主视频节点）、pilot=样片（样片节点）' },
-      frames: { type: 'json', description: '只渲染这些帧' },
-      range: { type: 'json', description: '帧区间 [from,to]：渲样片（写 pilot.mp4）' },
+      frames: { type: 'array', items: { type: 'number' }, description: '只渲染这些帧' },
+      range: { type: 'array', items: { type: 'number' }, description: '帧区间 [from,to]：渲样片（写 pilot.mp4）' },
     },
     output: { schema: { type: 'object', additionalProperties: false, properties: { summary: { type: 'string', required: true }, details: { type: 'string', required: true } } },
       render: (_args, value) => [{ type: 'text', text: value.summary + '\n' + value.details }] },
@@ -6824,8 +7157,10 @@ function sanitizeNewName(raw) {
         })
       }
       if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读')
-      const operation = Array.isArray(args.frames) && args.frames.length ? 'still' : 'full'
-      const ranged = Array.isArray(args.range) && args.range.length === 2
+      const renderFrames = jsonArray(args.frames)
+      const renderRange = jsonArray(args.range)
+      const operation = renderFrames.length ? 'still' : 'full'
+      const ranged = renderRange.length === 2
       // 样片的输出必须跟整片分开：以前 range 渲染也写 film.mp4，下一次 apply 就会把 4 秒样片当整片塞进主节点。
       const kind = operation === 'still' ? 'still' : ranged ? 'pilot' : 'film'
       const outputName = kind === 'still' ? 'still.mp4' : kind === 'pilot' ? 'pilot.mp4' : 'film.mp4'
@@ -6847,7 +7182,7 @@ function sanitizeNewName(raw) {
       const qualityGate = kind === 'still' ? null : assertQualityEvidence(dir, styleForGate)
       const gateWarnings = [engineGate?.warning, ...(qualityGate?.warnings || [])].filter(Boolean)
       const job = motionJobs.create({ kind, dir, nodeId: node.id })
-      const handle = renderProject(dir, { operation, frames: args.frames, frameRange: ranged ? args.range : undefined,
+      const handle = renderProject(dir, { operation, frames: renderFrames.length ? renderFrames : undefined, frameRange: ranged ? renderRange : undefined,
         output: outputPath(dir, outputName),
         onProgress: (message) => motionJobs.progress(job, message.phase, message.progress, message.message) })
       motionJobs.attach(job, handle)
@@ -6863,7 +7198,7 @@ function sanitizeNewName(raw) {
   })))
 
   // 帧检：把"片子有没有毛病"变成一张带帧号的清单，而不是靠眼睛。
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_qa',
     description: '成片帧检：不靠眼睛，靠像素和响度。inspect 立刻检一遍（默认检工程里的 .out/film.mp4，也可以指定 file）：帧数对不对、有没有黑场、有没有静止太久、有没有单帧闪烁、有没有空白帧、画面有没有顶到边、音轨有没有削波。report 读上次的结果。每条问题都带帧号和镜头号，能直接回去改对应场景。',
     parameters: {
@@ -6902,7 +7237,7 @@ function sanitizeNewName(raw) {
   })))
 
   // 剪映导出：把成片拆成"还能继续剪"的素材包。
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_export',
     description: '把工程导出成剪映可继续剪的素材包：逐镜头无声音轨 clips/、原音轨 audio/（BGM 与音效分开）、shots.json / audio.json / README.md，有字幕数据时再给 subtitles.srt，draft:true 另写一份 draft_content.json 草稿。run 导出，list 看导出过哪些。镜头按时间轴精确切（重编码，不靠关键帧），cut 点不会偏。',
     parameters: {
@@ -6910,7 +7245,15 @@ function sanitizeNewName(raw) {
       path: { type: 'string' }, nodeId: { type: 'string' }, page: { type: 'number' },
       name: { type: 'string', description: '导出目录名，默认 jianying' },
       draft: { type: 'boolean', description: '另写一份 draft_content.json（剪映草稿结构，未在剪映里实测过）' },
-      subtitles: { type: 'json', description: '字幕数组 [{startFrame,endFrame,text}]；工程 timeline 里有 subtitles 就不用传' },
+      subtitles: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: true,
+          properties: { startFrame: { type: 'number' }, endFrame: { type: 'number' }, text: { type: 'string' } },
+        },
+        description: '字幕数组 [{startFrame,endFrame,text}]；工程 timeline 里有 subtitles 就不用传',
+      },
       file: { type: 'string', description: '当成片对照的 mp4，默认 .out/film.mp4' },
     },
     output: { schema: { type: 'object', additionalProperties: false, properties: { summary: { type: 'string', required: true }, details: { type: 'string', required: true } } },
@@ -6928,7 +7271,7 @@ function sanitizeNewName(raw) {
       if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读')
       const timeline = readTimeline(dir)
       const result = await exportPackage({ dir, timeline, name: args.name || 'jianying', draft: Boolean(args.draft),
-        subtitles: args.subtitles, film: args.file ? workspacePath(scope, isAbsolute(args.file) ? args.file : joinPath(dir, args.file)) : undefined })
+        subtitles: jsonValue(args.subtitles), film: args.file ? workspacePath(scope, isAbsolute(args.file) ? args.file : joinPath(dir, args.file)) : undefined })
       return { summary: '已导出 ' + result.shots.length + ' 镜 / ' + result.stems.length + ' 条音轨到 ' + result.folder
         + (result.subtitles ? '（含字幕 ' + result.subtitles + ' 条）' : '')
         + (result.missing.length ? '，缺 ' + result.missing.length + ' 个音频文件' : ''),
@@ -6956,7 +7299,7 @@ function sanitizeNewName(raw) {
   }
 
   //   motion_assets   真素材进工程（原字节 + 尺寸 + 色板），场景用 staticFile 取
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_assets',
     description: '视频工程素材：list 查看工程素材；library 按 query（如 纸张、颗粒、钢琴）或 category 搜索插件自带纹理及乐器采样；use 用 assetId 按需导入，返回 file，图片用 staticFile(file)，音频须另用 motion_audio add 上时间轴。素材库是可选来源，用户自带素材优先，采样是单音而非完整配乐；使用前查看许可。gather 按站点收集品牌素材、配色与字体，collect 扫单页；capture 收本地素材；fetch 下载原图；crop 裁切；page 截网页；palette 读色板。',
     parameters: {
@@ -7049,7 +7392,7 @@ function sanitizeNewName(raw) {
   })))
 
   //   motion_sfx      音效采购：Freesound 搜索/下载与素材索引
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_sfx',
     description: '音效采购（Freesound）。search 按英文关键词搜，返回时长与作者；get 按 id 下载 HQ mp3 预览到 <工程>/assets/sfx/，量峰值与有效区间，维护一份 assets/audio-manifest.json；list 看已下载的音效。下载完用 motion_audio {action:"add", file:"sfx/xxx.mp3", role:"sfx"} 挂到轴上。',
     parameters: {
@@ -7060,7 +7403,7 @@ function sanitizeNewName(raw) {
       minDuration: { type: 'number', description: 'search：最短秒数，默认 0' },
       maxDuration: { type: 'number', description: 'search：最长秒数' },
       limit: { type: 'number', description: 'search：最多返回几条，默认 8' },
-      ids: { type: 'json', description: 'get：音效 id 数组，例如 ["fs:12345"]' },
+      ids: { type: 'array', items: { type: 'string' }, description: 'get：音效 id 数组，例如 ["fs:12345"]' },
     },
     output: { schema: { type: 'object', additionalProperties: false, properties: { summary: { type: 'string', required: true }, details: { type: 'string', required: true } } },
       render: (_args, value) => [{ type: 'text', text: value.summary + '\n' + value.details }] },
@@ -7076,7 +7419,7 @@ function sanitizeNewName(raw) {
           details: JSON.stringify({ ...found, next: '挑一条再 motion_sfx {action:"get", ids:["fs:xxxx"]}；想先听可以按 pageUrl 打开' }) }
       }
       if (policyFor(scope.sessionId)?.mode === 'read-only') throw new Error('当前会话为只读')
-      const result = await getSfx(dir, args.ids)
+      const result = await getSfx(dir, jsonArray(args.ids))
       const ok = result.results.filter((item) => item.ok)
       const bad = result.results.filter((item) => !item.ok)
       return { summary: '下载 ' + ok.length + ' 条' + (bad.length ? '，失败 ' + bad.length + ' 条' : ''),
@@ -7091,7 +7434,7 @@ function sanitizeNewName(raw) {
   })))
 
   //   motion_audio    音频轴：加/删/列音轨，量节拍，把切镜和目标音钉到拍子上
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_audio',
     description: '音频轴工具。list 列出时间轴上的音轨；add 把一条音频放到指定秒（默认写进 <工程>/assets/，素材没进工程会自动捕获）；remove 按 cueId 删；analyze 量 BPM/网格/重音（返回 bpm、grid 残差、hits 三分类、peakLag）；apply 写 beats.json 并把切点吸到拍子上，给 cueId 时改把这条音轨钉到拍子（自动扣掉音源峰值滞后与输出偏移）。bpm 为 null 说明量不出稳定网格——不要硬对。',
     parameters: {
@@ -7223,13 +7566,37 @@ function sanitizeNewName(raw) {
     },
   })))
 
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_sync',
     description: '音乐拍点→切镜/动作→音效峰值统一绑定。bind 替换绑定表并分析音乐；list 查看解析结果；clear 解除绑定、保留当前排期。anchors:[{id,type:"cut"|"action",shotId,beat?:0起拍号,at?:源音乐秒,name?:动作名,visual?:{metric:"change"|"brightness",roi:{x,y,w,h}},sfx?:[{cueId,peakSeconds:素材源峰值秒}]}]。beat/at 二选一；动作场景接收 anchors，使用 anchors.<name> 本镜局部帧写关键帧。动作验收要选 ROI/metric，切镜默认测帧差。绑定后 motion_audio_verify 对照成片。音乐需要非循环音轨，音乐 from/trimStart 参与换算。',
     parameters: {
       action: {type:'string',enum:['bind','list','clear'],required:true},
       nodeId: {type:'string',required:true}, path:{type:'string'},page:{type:'number'},
-      musicCueId:{type:'string'},anchors:{type:'json'},
+      musicCueId:{type:'string'},
+      anchors:{
+        type:'array',
+        items:{
+          type:'object',
+          additionalProperties:true,
+          properties:{
+            id:{type:'string'},
+            type:{type:'string',enum:['cut','action']},
+            shotId:{type:'string'},
+            beat:{type:'number'},
+            at:{type:'number'},
+            name:{type:'string'},
+            visual:{
+              type:'object',
+              additionalProperties:true,
+              properties:{
+                metric:{type:'string',enum:['change','brightness']},
+                roi:{type:'object',additionalProperties:false,properties:{x:{type:'number'},y:{type:'number'},w:{type:'number'},h:{type:'number'}}},
+              },
+            },
+            sfx:{type:'array',items:{type:'object',additionalProperties:true,properties:{cueId:{type:'string'},peakSeconds:{type:'number'}}}},
+          },
+        },
+      },
       outputOffsetSeconds:{type:'number',description:'具体渲染管线实测音轨延迟（秒），默认0；验收报告给出多点测得的偏移参考'},
       toleranceFrames:{type:'number',description:'音画及音效误差容差，默认2帧，最大3帧'},
     },
@@ -7249,7 +7616,7 @@ function sanitizeNewName(raw) {
         const analysis=await analyzeBeats(assetPath(dir,cue.file))
         const tolerance=args.toleranceFrames??2
         if(!Number.isFinite(tolerance)||tolerance<0||tolerance>3)throw new Error('toleranceFrames 必须在0–3内')
-        timeline.sync={version:1,musicCueId:cue.id,analysis,analysisSourceHash:filmHash(assetPath(dir,cue.file)),anchors:args.anchors,outputOffsetSeconds:args.outputOffsetSeconds??0,toleranceFrames:tolerance}
+        timeline.sync={version:1,musicCueId:cue.id,analysis,analysisSourceHash:filmHash(assetPath(dir,cue.file)),anchors:jsonArray(args.anchors),outputOffsetSeconds:args.outputOffsetSeconds??0,toleranceFrames:tolerance}
         timeline=resolveSync(timeline)
       }
       writeTimeline(dir,timeline)
@@ -7258,7 +7625,7 @@ function sanitizeNewName(raw) {
   })))
 
   //   motion_audio verify    渲后回测：成片里的声音到底偏了多少帧
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_audio_verify',
     description: '音画对照验收：按 motion_sync 锚点，从成片匹配源音乐和音效波形、测切镜或动作ROI的实际变化帧，逐项报告音画及音效误差。无证据标 unverified，超容差 fail。报告写入 .out/qa/sync/report.json。',
     parameters: {
@@ -7288,7 +7655,7 @@ function sanitizeNewName(raw) {
   //     为什么时长由旁白说了算：旁白是"内容的长度"，画面是"内容的形状"。
   //     先按字速估、合成后用真实时长再重排一次，镜头跟着句子走 —— 反过来做
   //     （先定死镜头再塞旁白）只能靠变速或砍句，两个都难看。
-  ctx.effect(() => ctx.tools.register(defineTool({
+  ctx.effect(() => registerHostTool(defineTool({
     name: 'motion_voice',
     description: '旁白（TTS）：把 voice.script.md（## shot-N 分节、一句一行）变成 voice 音轨 + 字幕，并让镜头时长跟着句子走。action=list 看现状/音色；plan 只估算与重排（不合成，先看排期是否合理）；say 真合成（edge-tts，拿不到就退 SAPI）+ 用真实时长重排；align 已有音频只按真实时长重排。合成结果按台词哈希缓存，改一句只重合成一句。字幕写进 timeline.subtitles，导出 SRT / 剪映字幕轨零改动。',
     parameters: {
@@ -7368,7 +7735,7 @@ function sanitizeNewName(raw) {
     },
   })))
 
-  ctx.effect(() => ctx.tools.register({ ...applyTool, execute: async (args, exec) => {
+  ctx.effect(() => registerHostTool({ ...applyTool, execute: async (args, exec) => {
     const sessionId = sessionIdOf(exec)
     const path = typeof args.path === 'string' && args.path ? args.path : focusedPathFor(sessionId) || DEFAULT_PATH
     const target = await resolveTarget(path, sessionId)
@@ -7378,24 +7745,34 @@ function sanitizeNewName(raw) {
     })
   } }))
 
-  // 把"怎么用这张画布"注册成**内嵌技能**（见 SKILL_BODY 的注释）：
+  // 注册段收尾：一行汇总（成功几个、失败哪几个）。远端出问题时先看这条，
+  // 再看 DIAGNOSTICS_PATH 的 JSON —— 两者对不上就说明注册完又被回收了。
+  reportToolRegistrations()
+
+  // 把"怎么用这张画布"注册成**内嵌技能**（见 SKILL_DEFINITIONS 的注释）：
   // 换了电脑、只装了插件（没有源码/README/tools）时，模型依然知道该怎么操作。
   //
   // `skills` 是**可选**依赖：没装 skill 注册表的部署里照样能用（工具描述本身已经够启动），
   // 所以走 ctx.get 而不是写进 inject —— 缺它不该让整个插件停在等待态。
   const skills = typeof ctx.get === 'function' ? ctx.get('skills') : undefined
   if (skills !== undefined && skills !== null && typeof skills.register === 'function') {
-    ctx.effect(() =>
-      skills.register({
-        name: SKILL_SUMMARY.name,
-        description: SKILL_SUMMARY.description,
-        whenToUse: SKILL_SUMMARY.whenToUse,
-        // `source: 'runtime'` 不能省：注册时只校验 name/description/invocation，
-        // 但**取全文**时注册表会再跑一次 validateDefinition，那里要求 source 是字符串
-        // （少了它，目录里看得见、一 load 就抛 "source must be a string"）。
-        source: 'runtime',
-        content: SKILL_BODY,
-      }),
-    )
+    ctx.effect(() => {
+      const disposers = SKILL_DEFINITIONS.map((definition) =>
+        skills.register({
+          name: definition.name,
+          description: definition.description,
+          whenToUse: definition.whenToUse,
+          // `source: 'runtime'` 不能省：注册时只校验 name/description/invocation，
+          // 但**取全文**时注册表会再跑一次 validateDefinition，那里要求 source 是字符串
+          // （少了它，目录里看得见、一 load 就抛 "source must be a string"）。
+          source: 'runtime',
+          content: definition.content,
+        }),
+      )
+      // 两条注册各返回一个 disposer；合成一个交回 Cordis，卸载时一并撤掉。
+      return () => {
+        for (const dispose of disposers) if (typeof dispose === 'function') dispose()
+      }
+    })
   }
 }