@migor/cli 0.10.6 → 0.10.8

package/CHANGELOG.md

@@ -5,6 +5,89 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.10.8] - 2026-11-12
+
+### 变更
+
+调试面板展开态的**第二档**：字符串里套着的 JSON 也铺开。无破坏性变更、无迁移动作。
+两包同步 0.10.7 → 0.10.8；`@migor/agentia` 此次仍只有版本常量变化（`src/` 未动）。
+
+- **上一档解决的是「容器长什么样」，但真实 payload 里最常见的那一层不是容器**：工具把结构
+  `JSON.stringify` 后塞回文本字段（`tool.output.content`、MCP 的 text block、SSE 的 `data:`、
+  `content[0].text`）。这些值的类型是字符串 ⇒ 走纯文本老路 ⇒ 展开后是一串 `{\"a\":1`
+  的反斜杠汤，比 0.10.7 之前那个「一坨」更劝退。
+- **现在这类字符串也按容器铺开**，但**如实标出它原本是字符串**：行内打 `str→json` 标记，
+  根级头部写 `string · 232 字符 → object · 3 项`。只写解析后的规模，读者会以为工具真返回了对象。
+- **判据是首尾字符，不是「`JSON.parse` 成功」**：`"123"` / `"null"` / `"true"` 都能 parse，
+  把它们显示成数字 / 空值 / 布尔就是**改写工具返回的事实**。trim 后首尾须是 `{`…`}` 或
+  `[`…`]`，不吻合连 parse 都不试（普通文本占绝大多数，负路径不付反序列化成本）；超 100k 字符
+  不解析。
+- **只解析一层**：进了「解析出来的子树」就不再往下解析。一层套一层是真实现象，逐层展开会把
+  10KB 放大成十万个节点。
+- **表格里的格子不解析**：同构表已经放弃逐层展开，格子里放不下嵌套块。
+- 字符串根上点「复制」拿到的是**原始字符串**（能直接喂 `jq`），不是重排后的 JSON。
+
+### 新增：字符串里的 JSON 也铺开（2026-11-12 ref-trace-json-string）
+
+- **判据同源**：新导出 `hasStructuredBody(v)` 与块内共用同一份 `jsonInString`；`view.js` 用它
+  取代原先的 `typeof v === 'object'` ⇒「挂不挂块」与「块里画什么」不会分叉。
+  `createFullView` 与 `hasStructuredBody` 都进公共导出（bundle 导出面必须与 `src/index.js`
+  逐字一致，有 `test/bundle.test.js` 守着）。
+- **宿主侧无需改动**：本次没有新增静态件 —— `full-view.js` / `view.js` / `index.js` 都已在
+  CLI inspector 的 STATIC 白名单里，`dist/inspector` 随构建更新即可。
+- **验证**：trace-view 测试 75 → 90（+15）；反向验证 6 条各自咬住（摘标记 ⇒ 7 条红；
+  去「只解析一层」⇒ 嵌套用例红；接线退回「只认容器」⇒ 字符串出参挂块用例红；去 100k 上限 ⇒
+  超长用例红；去首尾先筛 ⇒ parse 计数与谓词两条红；头部只写解析后类型 ⇒ 头部用例红）。
+  另记一条**等价变异**的教训：第一版里「parse 结果再判类型」那段代码永远走不到（首尾判据
+  已经挡住标量字符串），任何用例都咬不住，已删除 —— 留着只会让下一个人以为那里有守卫。
+  决策见 `docs/spec.md` §10 2026-11-12 ref-trace-json-string，守卫登记见 `docs/guards.md` §1。
+
+## [0.10.7] - 2026-11-12
+
+### 变更
+
+本版只改**调试面板的展开呈现**，无破坏性变更、无迁移动作。两包同步 0.10.6 → 0.10.7；
+`@migor/agentia` 此次只有版本常量变化（`src/` 一行未动），实际改动全在调试面板与
+`agentia view` 的产物面。
+
+- **展开态不再是一大坨 JSON**：`tool.input` / `tool.output` 是对象或数组时，展开行下方追加
+  一个**结构化正文块** —— 缩进、四类值着色、头部写类型与规模（`object · 6 项`）。
+  此前唯一的展开方式是把整串 JSON 折行，20 个键在 400px 宽的右栏里就是十几行连续的
+  `{"a":"b","c":{"d":`：页面不报错、无溢出、构建与 e2e 全绿，只是人读不了 ——
+  而「展开看工具到底收到/返回了什么」正是这块面板的主用途。
+- **逐层折叠**：容器默认只铺两层，更深的折成 `▸ watch: { object · 2 项 }`，点一下铺开。
+  折叠状态由调用方持有，所以**实时 run 里刚折起的容器不会被下一条事件弹开**。
+- **同构数组成表**：元素键集完全相等、且各列都是标量时铺成表（`targets[*].file` 这种表头），
+  3 行 `{name, score}` 从 9 行重复键名压到 1 行表头 + 3 行数据。判据刻意从严 ——
+  表格里没法逐层展开，判错一次就是**静默丢列**，所以任一条件不满足就回落树形。
+- **键路径可复制**：悬停键名出 `⧉`，点一下写入 `results[0].name`。没有剪贴板实现时
+  点击不生效、也不显示「已复制」—— 不把没做到的事显示成做到了。
+- **三处宿主同时生效**：CLI 的 `agentia dev` 面板、`agentia view` 生成的单文件 HTML、
+  官网 Playground 共用这份渲染器。
+- 字符串形态的展开（`tool.output` 的文本正文、官网模拟回放）**照旧**走原来的纯文本换行 ——
+  那一档有两个 CSS 不变量守着，刻意保留两档并存，不做统一。
+
+### 新增：展开态结构化渲染（2026-11-11 ref-trace-full-view）
+
+- **新件 `packages/trace-view/src/full-view.js`**：入参任意值、出参一个元素，与树的构建与
+  状态机无关（零依赖、纯 DOM 构造、无内部状态）。默认铺两层（`OPEN_DEPTH = 2`）。
+- **数据侧递原值**：`fromTrace.eventFull` 对 `tool.input` / `tool.output` 返回**原值**而非
+  `JSON.stringify` 结果 —— 此前在数据层就序列化了，渲染器根本看不到对象，结构化无从发生。
+  `rawArg` 保留（`.tr-io` 的正文与既有展开断言都靠它）。
+- **原文仍然在场**：结构化时给行打 `tr-structured`，CSS 只是隐藏 `.tr-io`，它依旧持有
+  `JSON.stringify` 原文 ⇒ 既有 9 条展开断言一条都不用改，用户选中复制也照旧。
+  改的是**画法**，不是数据。
+- **截断必须说出来**：单值超 240 字符写「还有 N 字符」，一层超 40 项写「还有 N 项未展开」，
+  嵌套超 6 层压平但仍标出「它是个容器」。静默截断比糊成一坨更坏 —— 它会让人以为工具
+  就返回了这么点东西。循环引用不抛（调试面板不该因一条坏数据白屏）。
+- **CLI 侧**：`inspector-routes.ts` 的 STATIC 白名单加 `full-view.js`（漏登记的后果是浏览器
+  404、面板整块求值失败），`packages/cli/test/structure.test.mjs` 的 W5 守着这条。
+- **验证**：trace-view 测试 +19（渲染件 15、接线 4），跑真 `createTraceView` + `playTrace`；
+  反向验证 5 条（不传 `fold` ⇒ 折叠跨重建用例红；摘掉「键数相等」判定 ⇒ 成表边界红；
+  摘掉挂块那一行 ⇒ 两处接线红；`eventFull` 退回 `JSON.stringify` ⇒ 结构化用例红；
+  `copyInto` 写 `title` 而非路径 ⇒ 复制用例红）。决策与判据见 `docs/spec.md` §10
+  2026-11-11 ref-trace-full-view，守卫登记见 `docs/guards.md` §1。
+
 ## [0.10.6] - 2026-11-09
 
 ### 变更
@@ -4426,7 +4509,9 @@ toolkit 142 / runtime 55 / engine 403 / container 10 / store 55 —— 全绿。
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.6...HEAD
+[Unreleased]: https://github.com/migoric/agentia/compare/v0.10.8...HEAD
+[0.10.8]: https://github.com/migoric/agentia/releases/tag/v0.10.8
+[0.10.7]: https://github.com/migoric/agentia/releases/tag/v0.10.7
 [0.10.6]: https://github.com/migoric/agentia/releases/tag/v0.10.6
 [0.10.5]: https://github.com/migoric/agentia/releases/tag/v0.10.5
 [0.10.4]: https://github.com/migoric/agentia/releases/tag/v0.10.4

package/dist/inspector/fromTrace.js

@@ -14,7 +14,7 @@
  *   3. usage 只由 llm.turn 累计（capability span 的 usage 是子 span 聚合，计入会双算）。
  */
 
-import { fmtArg, rawArg, capabilityTypeOf, CAP_ICO } from './view.js';
+import { fmtArg, capabilityTypeOf, CAP_ICO } from './view.js';
 
 /** 从 span.attributes 认能力类型（框架用 `setAttribute(capabilityId, 'subagent', name)` 记类型） */
 function spanType(s) {
@@ -68,15 +68,24 @@ function eventText(ev) {
 }
 
 /**
- * 事件全文（展开态用）。
+ * 事件全文（展开态用）—— **给原值，不预先序列化**。
  *
- * 只有 `tool.input` 需要单独取：`fmtArg` 把入参摘要**砍到 4 个键 / 每值 21 字符 / 整串 62 字符**，
- * 直接拿摘要当全文就是「假展开」—— 点开看到的还是那 62 个字符。出参与其他事件本身就是原文
- * （`eventText` 原样返回 content），无需二次处理。
- * 原文口径统一在 view.js 的 `rawArg`：官网 playground 的模拟回放也要用它，两处一处定义。
+ * 2026-11-11 起 `full` 的类型本身携带语义：字符串 ⇒ 渲染器走 `.tr-io` 的纯文本换行；
+ * 对象/数组 ⇒ 交给 `full-view.js` 铺成带缩进的结构化块。所以这里必须把**原值**递下去 ——
+ * 若仍在这里 `rawArg` 成字符串，「一大坨 JSON」那条路就永远回不来了（渲染器只能看到字符串）。
+ *
+ * 口径：
+ * - `tool.input` → 入参原值（`fmtArg` 的摘要砍到 4 键 / 每值 21 字符 / 整串 62 字符，
+ *   拿摘要当全文就是「假展开」）；
+ * - `tool.output` → `content` 原值：字符串就是纯文本（含图片块时会是非字符串，正好结构化）；
+ * - 其余事件 → `eventText` 的字符串（它们的体本来就是给人看的一小段说明）。
  */
 function eventFull(ev) {
-  if (ev.name === 'tool.input') return rawArg(ev.body?.input);
+  if (ev.name === 'tool.input') return ev.body?.input ?? '';
+  if (ev.name === 'tool.output') {
+    const c = ev.body?.content;
+    return c == null ? '' : c;
+  }
   return eventText(ev);
 }
 

package/dist/inspector/full-view.js

@@ -0,0 +1,449 @@
+/* 展开态的**结构化正文** —— 把「一大坨 JSON」拆成可折叠、可成表、可复制路径的块。
+ *
+ * ## 为什么需要它
+ *
+ * 展开此前只有一条路：把 `rawArg(v)`（= `JSON.stringify(v)`，**无缩进**）整串塞进
+ * `.tr-io` 再靠 CSS 换行。一个 20 键的工具入参在 400px 宽的右栏里会折成十几行连续的
+ * `{"a":"b","c":{"d":` —— 页面不报错、无溢出、构建全绿，只是**人读不了**。工具出参更糟：
+ * 它是 `content` 的原始序列化，长文本与图片块混在一起，一行到底。
+ *
+ * 缩进只是第一档。第二档（2026-11-11 晚，本文件的现状）解决缩进解决不了的三件事：
+ *
+ * 1. **静态文本没有"收起"**：深度 6 全铺开，一个出参就能把整棵树顶到屏幕外。现在容器
+ *    默认只铺两层（`OPEN_DEPTH`），其余折成 `{ object · 4 项 }`，点一下展开。折叠状态由
+ *    调用方传入（`opts.fold`）—— 渲染是全量重建，状态放本文件里活不过下一条事件。
+ * 2. **同构对象数组在浪费行**：`[{name,score},{...},{...}]` 每个元素重复一遍键名，3 行数据
+ *    吃掉 9 行。同构且各列都是标量时改成表格，表头一行、数据一行。
+ * 3. **路径拿不到**：想引用 `results[0].name` 只能用手数层级。每个键悬停出一个 `⧉`，
+ *    点一下把路径写进剪贴板（表头写的是 `results[*].name`，因为它是一整列）。
+ * 4. **字符串里套着的 JSON 读不了**（2026-11-12）：MCP 的 text block、SSE 的 `data:`、把结果
+ *    序列化后又塞回 `content` 的工具 —— 这些值的类型是**字符串**，此前只显示成一串
+ *    `{\"a\":1` 的反斜杠汤，比无缩进的 JSON 更难读。现在首尾是 `{`…`}` / `[`…`]` 且解析成功的
+ *    字符串按容器铺开，并在行里打 `str→json` 标记 —— 不标出来，读者会以为工具真的返回了对象。
+ *
+ * ## 边界（都是「不这么做就会坏」的地方，不是口味）
+ *
+ * - **只在 `full` 不是字符串时接手**：字符串正文（工具返回的纯文本、官网模拟回放）
+ *   继续走 `.tr-io` + `.tr-open` 的老路 —— 那条路有 `test/style.test.js` 的两个不变量守着
+ *   （最小宽度、caret 常显），换成本件就会让那两个守卫失去落点。两档并存是刻意的。
+ * - **不改 `.tr-io` 的文本**：本件只是**追加**一个兄弟块，`.tr-io` 仍持有原文（展开时由
+ *   CSS 隐藏）。既有断言（`textContent === JSON.stringify(...)`）因此逐字保留 ——
+ *   展开的正文依旧是"原文"，只是多了一层可读的呈现。
+ * - **截断必须说出来**：长字符串与超大集合会截断，但截断处标明「还有 N 字符 / N 项」。
+ *   静默截断会让人以为工具就返回了这么点东西 —— 比糊成一坨更坏。表格单元格同样走
+ *   `primitive()`，所以这条在表里也成立（不做「表格例外」）。
+ * - **循环引用不抛**：手写的 trace 可能有环（`rawArg` 对它会回落 `[object Object]`），
+ *   这里同样只回落、不抛错：调试面板不该因为一条坏数据整棵树白屏。
+ * - **折叠状态必须外部持有**：`opts.fold` 是调用方的 Map（`view.js` 按事件键存一份）。
+ *   本文件只读写它、不 new 一份长期状态 —— 否则「点开一个容器，下一条事件到达时它自己合上」
+ *   会原样复现（这正是 `view.js` 的 `expanded` 集合存在的原因）。
+ * - **表格化只在"真的同构"时发生**：元素必须全是普通对象、键集完全一致、列数 1..6、
+ *   每列都是标量。任一不满足就回落树形 —— 表格里没法逐层展开，判错一次就是**丢数据**。
+ * - **字符串里的 JSON 只解析一层，且必须标出来**：判据是**首尾字符**（`{`…`}` / `[`…`]`），
+ *   不是「`JSON.parse` 成功」—— `"123"` / `"null"` / `"true"` 都能 parse 成功，显示成
+ *   数字/空值/布尔就是**改写工具返回的事实**。解析结果内部的字符串**不再二次解析**：
+ *   一层套一层是业务里的真实现象（SSE data 里再套 JSON），逐层展开会让 10KB 变成十万个节点。
+ *   表格单元格也不解析 —— 同构表已经放弃了逐层展开，单元格里放不下嵌套块。
+ *
+ * 零依赖、纯 DOM 构造（只用 createElement / appendChild / textContent / className /
+ * dataset / innerHTML=''），与 view.js 共用同一套 DOM stub 跑测试。
+ */
+
+/** 单个字符串值最多显示多少字符（超过就说出来，不静默截断） */
+const MAX_STR = 240;
+/** 一层里最多铺开多少项（再多就没法看了，留着类型与计数） */
+const MAX_ITEMS = 40;
+/** 嵌套深度上限：再深就整体序列化成一行，避免缩进把宽度吃光 */
+const MAX_DEPTH = 6;
+/** 默认展开到第几层（容器自身深度 < 它 ⇒ 默认铺开）。两层 = 根 + 一层子节点 */
+const OPEN_DEPTH = 2;
+/** 表格最多几列：再多横向就没法看了，回落树形 */
+const MAX_COLS = 6;
+/** 多长的字符串才值得尝试从里面解析 JSON。再长的话，parse 与随后的渲染成本都不值得 */
+const MAX_JSON_STR = 100_000;
+
+function fvEl(tag, cls, text) {
+  const node = document.createElement(tag);
+  if (cls) node.className = cls;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+/** 安全序列化：循环引用 / BigInt / 自定义 toJSON 抛错都回落成一句人话，绝不冒泡 */
+function safeStringify(v) {
+  try {
+    const s = JSON.stringify(v, null, 2);
+    return s === undefined ? String(v) : s;
+  } catch {
+    return '[无法序列化 —— 可能是循环引用]';
+  }
+}
+
+/** 该值是否值得走结构化视图（字符串交给 .tr-io 的老路） */
+function isStructured(v) {
+  return v !== null && typeof v === 'object';
+}
+
+/**
+ * 有没有「结构化正文」可铺 —— 容器，或者**装着 JSON 的字符串**。
+ *
+ * 后者是业务里的常态：`tool.output` 的 `content` 常常就是 `JSON.stringify(...)` 的结果
+ * （工具把结构序列化后塞回文本字段，MCP 的 text block 更是如此）。此前这种值是字符串 ⇒
+ * 走纯文本老路 ⇒ 展开后是一串 `{\"a\":1` 的反斜杠汤。判据与 `jsonInString` 完全同一套，
+ * 所以「挂不挂块」与「块里画什么」不会跑偏。
+ */
+export function hasStructuredBody(v) {
+  return isStructured(v) || jsonInString(v) !== null;
+}
+
+/** 普通对象（排除数组与 null）—— 表格化与"容器"判定都只要这一种 */
+function isPlainObject(v) {
+  return isStructured(v) && !Array.isArray(v);
+}
+
+/** 容器规模：数组算元素数，对象算键数 */
+function sizeOf(v) {
+  return Array.isArray(v) ? v.length : Object.keys(v).length;
+}
+
+/** 头部那句类型说明：`object · 6 项` / `array · 12 项` / `string · 4,096 字符` */
+function typeLabelOf(v) {
+  if (Array.isArray(v)) return `array · ${v.length} 项`;
+  if (isStructured(v)) return `object · ${Object.keys(v).length} 项`;
+  if (typeof v === 'string') return `string · ${v.length} 字符`;
+  return typeof v;
+}
+
+/** 基本类型的着色类与展示文本 */
+function primitive(v) {
+  if (v === null) return { cls: 'tr-full-null', text: 'null' };
+  if (v === undefined) return { cls: 'tr-full-null', text: 'undefined' };
+  const t = typeof v;
+  if (t === 'string') {
+    const clipped = v.length > MAX_STR ? v.slice(0, MAX_STR) : v;
+    const rest = v.length > MAX_STR ? `… 还有 ${v.length - MAX_STR} 字符` : '';
+    return { cls: 'tr-full-str', text: JSON.stringify(clipped) + rest };
+  }
+  if (t === 'number') return { cls: 'tr-full-num', text: String(v) };
+  if (t === 'boolean') return { cls: 'tr-full-bool', text: String(v) };
+  return { cls: 'tr-full-null', text: String(v) };
+}
+
+/** 深层容器压成单行时的表示：保留"它是个容器"这个事实，不伪装成标量 */
+function oneLine(v) {
+  const kind = Array.isArray(v) ? 'array' : 'object';
+  const s = safeStringify(v).replace(/\s+/g, ' ');
+  const clipped = s.length > MAX_STR ? s.slice(0, MAX_STR) + '…' : s;
+  return `<${kind} · ${sizeOf(v)} 项> ${clipped}`;
+}
+
+/**
+ * 「字符串里套着 JSON」：返回解析出来的容器，其余（普通文本、标量字符串、坏 JSON）一律 `null`。
+ *
+ * 判据是**首尾字符**而不是「parse 成功」，这一条是这段代码的全部要害：`"123"`、`"null"`、
+ * `"true"` 都能被 `JSON.parse` 吃下去，但把它们显示成数字/空值/布尔，等于把工具返回的
+ * 字符串改写成另一种类型 —— 调试面板的第一职责是如实。所以先看 trim 后的首尾一个字符，
+ * 不吻合就连 parse 都不试（普通文本占绝大多数，省掉无谓的反序列化）。
+ * 截断过的 JSON（尾部被切掉）在这里自然失败，回落成原样字符串。
+ */
+function jsonInString(v) {
+  if (typeof v !== 'string' || v.length < 2 || v.length > MAX_JSON_STR) return null;
+  const t = v.trim();
+  if (t.length < 2) return null;
+  const head = t[0];
+  const tail = t[t.length - 1];
+  if (!((head === '{' && tail === '}') || (head === '[' && tail === ']'))) return null;
+  try {
+    // 首尾判据已经保证了这里解析出来的必然是对象或数组（`{`…`}` / `[`…`]`），
+    // 所以不再重复判类型 —— 那会是一条永远走不到的防御分支（变异测试实测盖不住）。
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+
+/** 「这个字符串里装着 JSON」的标记。**必须显眼**：不标出来，读者会以为工具真的返回了对象。
+ *  title 顺带交代两件容易误会的事 —— 原文还在（`.tr-io` 与块内原值），路径需先 parse 这一层。 */
+function jsonBadge() {
+  const b = fvEl('span', 'tr-full-json', 'str→json');
+  b.title = '这个值是字符串，内容是 JSON（已按对象展示；内部路径需先 JSON.parse 这一层）';
+  return b;
+}
+
+/** 子键的 JSON 路径：对象用 `.key`，数组用 `[i]`。根是空串，所以 `[0]` 不会变成 `.[0]` */
+function pathOf(parent, key, isArr) {
+  return isArr ? `${parent}[${key}]` : parent ? `${parent}.${key}` : key;
+}
+
+/** 剪贴板：没有实现时**什么都不做**，绝不把没做到的事显示成「已复制」 */
+function copyInto(btn, text, done) {
+  const clip = globalThis.navigator?.clipboard;
+  if (!clip || typeof clip.writeText !== 'function') return;
+  Promise.resolve(clip.writeText(text)).then(
+    () => {
+      btn.textContent = done;
+    },
+    () => {
+      btn.textContent = '复制失败';
+    },
+  );
+}
+
+/** 正在选文本时不要收起/展开 —— 鼠标拖选到行外松手会补一次 click，否则选完就自己合上了 */
+function hasSelection() {
+  try {
+    return String(globalThis.getSelection?.() ?? '') !== '';
+  } catch {
+    return false;
+  }
+}
+
+/** 悬停才露出的 `⧉`：点它复制路径，**不**触发所在容器的折叠 */
+function pathBtn(path) {
+  const btn = fvEl('span', 'tr-full-path', '⧉');
+  btn.title = '复制路径 ' + path;
+  btn.addEventListener('click', (e) => {
+    // 真实 DOM 里会冒泡到容器行的折叠处理；stub 的 click() 传的是空对象，故双保险
+    if (e && typeof e.stopPropagation === 'function') e.stopPropagation();
+    copyInto(btn, path, '已复制');
+  });
+  return btn;
+}
+
+/**
+ * 这一层要不要铺开。显式折叠/展开优先（`fold` 里有记录），否则按深度给默认值。
+ * @param {Map<string, boolean>} fold 路径 → 是否展开
+ */
+function isOpen(fold, path, depth) {
+  return fold.has(path) ? fold.get(path) === true : depth < OPEN_DEPTH;
+}
+
+/**
+ * 同构对象数组 → 列名；不是"真同构"就返回 null（调用方回落树形）。
+ *
+ * 判据全部是「表格会丢东西」的地方，松一条就丢一类数据：元素必须是普通对象、
+ * 键集**完全一致**（缺键/多键都回落）、列数 1..6、每列都是标量（表格里没法逐层展开）。
+ */
+function tableColsOf(arr) {
+  if (!Array.isArray(arr) || arr.length < 2 || arr.length > MAX_ITEMS) return null;
+  if (!isPlainObject(arr[0])) return null;
+  const cols = Object.keys(arr[0]);
+  if (cols.length === 0 || cols.length > MAX_COLS) return null;
+  for (const item of arr) {
+    if (!isPlainObject(item)) return null;
+    if (Object.keys(item).length !== cols.length) return null;
+    for (const c of cols) {
+      if (!Object.hasOwn(item, c)) return null;
+      if (isStructured(item[c])) return null;
+    }
+  }
+  return cols;
+}
+
+/**
+ * 同构数组铺成表格。缩进用 `data-depth`（值为 0 时不写）—— CSS 靠属性选择器补左外边距，
+ * 因为列数是动态的、行数也是动态的，没有一个能写死的 inline style 可靠活在 stub 里。
+ */
+function renderTable(ctx, arr, cols, depth, path) {
+  const table = fvEl('table', 'tr-full-table');
+  if (depth > 0) table.dataset.depth = String(depth);
+
+  const thead = fvEl('thead');
+  const headRow = fvEl('tr');
+  for (const c of cols) {
+    const th = fvEl('th');
+    th.appendChild(fvEl('span', 'tr-full-col', c));
+    // 列的路径带 `[*]`：复制出去能直接用于过滤/取值，而不是某一行的那一份
+    th.appendChild(pathBtn(pathOf(path + '[*]', c, false)));
+    headRow.appendChild(th);
+  }
+  thead.appendChild(headRow);
+  table.appendChild(thead);
+
+  const tbody = fvEl('tbody');
+  for (const item of arr) {
+    const tr = fvEl('tr');
+    for (const c of cols) {
+      const td = fvEl('td');
+      const p = primitive(item[c]); // 表里同样截断并说出剩余（不做「表格例外」）
+      td.appendChild(fvEl('span', p.cls, p.text));
+      tr.appendChild(td);
+    }
+    tbody.appendChild(tr);
+  }
+  table.appendChild(tbody);
+  ctx.body.appendChild(table);
+}
+
+/** 缩进空格的落点：0 层不占位（否则每条顶级键都白带两个空格） */
+function indentOf(depth) {
+  return depth > 0 ? fvEl('span', 'tr-full-indent', '  '.repeat(depth)) : null;
+}
+
+/** 折叠箭头的槽位。叶子行也占一格（传空串），否则同层键名会在「有箭头」与「没箭头」之间
+ *  左右跳 10px —— 一列键名对齐是这类面板最基本的可读性，不能靠行首参差来区分有没有子项。 */
+function caretSlot(glyph) {
+  return fvEl('span', 'tr-full-caret', glyph);
+}
+
+/** 一行 = 缩进 + 箭头槽位（+ 稍后追加的键名/值）。所有行都从同一个入口起头，
+ *  这样才能保证「同一层的键名在同一条竖线上」—— 逐处手写就迟早漏一处。 */
+function startRow(depth, caret) {
+  const row = fvEl('div', 'tr-full-line');
+  const indent = indentOf(depth);
+  if (indent) row.appendChild(indent);
+  row.appendChild(caretSlot(caret));
+  return row;
+}
+
+/**
+ * 把一个值铺进 `ctx.body`。
+ * @param {{body: Element, fold: Map<string, boolean>, repaint: () => void}} ctx
+ * @param {any} v         值
+ * @param {number} depth  当前缩进层级（根为 0）
+ * @param {string} path   当前值的 JSON 路径（根为空串）
+ * @param {boolean} [allowParse] 还允许不允从字符串里解析 JSON（进了「解析出来的子树」就为 false）
+ */
+function renderInto(ctx, v, depth, path, allowParse = true) {
+  const box = ctx.body;
+
+  if (!isStructured(v)) {
+    const p = primitive(v);
+    const row = startRow(depth, '');
+    row.appendChild(fvEl('span', p.cls, p.text));
+    box.appendChild(row);
+    return;
+  }
+
+  const isArr = Array.isArray(v);
+  const cols = isArr ? tableColsOf(v) : null;
+  if (cols) {
+    renderTable(ctx, v, cols, depth, path);
+    return;
+  }
+
+  const keys = isArr ? v.map((_, i) => String(i)) : Object.keys(v);
+  const show = keys.slice(0, MAX_ITEMS);
+
+  for (const k of show) {
+    const child = isArr ? v[Number(k)] : v[k];
+    const keyText = isArr ? `[${k}]` : `${k}:`;
+    const childPath = pathOf(path, k, isArr);
+    // 字符串里套着的 JSON（`content: "{\"rows\":[...]}"`）⇒ 按容器铺。`allowParse` 只在
+    // 「刚从一个字符串里解析出来」的那棵子树上为 false —— 一层套一层会放大成十万个节点。
+    const parsed = allowParse ? jsonInString(child) : null;
+    const val = parsed ?? child;
+    const fromJson = parsed !== null;
+    // 「能否折叠」只看三件事：是容器、非空、没到深度上限 —— 与下面几个分支同一套判据。
+    // 先算出来是为了让箭头槽位在起行时就有正确字形（叶子行留空格位，键名才会对齐）。
+    const foldable = isStructured(val) && sizeOf(val) > 0 && depth < MAX_DEPTH;
+    const open = foldable && isOpen(ctx.fold, childPath, depth);
+    const row = startRow(depth, foldable ? (open ? '▾' : '▸') : '');
+
+    // 叶子：同一行里写完（缩进 + 键名 + 路径 + 值）
+    if (!isStructured(val)) {
+      const p = primitive(child);
+      row.appendChild(fvEl('span', 'tr-full-key', keyText));
+      row.appendChild(pathBtn(childPath));
+      row.appendChild(fvEl('span', p.cls, ' ' + p.text));
+      box.appendChild(row);
+      continue;
+    }
+
+    // 深度用尽 ⇒ 整体压成一行（并标明它是个容器），避免缩进吃掉全部宽度
+    if (depth >= MAX_DEPTH) {
+      row.appendChild(fvEl('span', 'tr-full-key', keyText));
+      if (fromJson) row.appendChild(jsonBadge());
+      row.appendChild(fvEl('span', 'tr-full-null', ' ' + oneLine(val)));
+      box.appendChild(row);
+      continue;
+    }
+
+    // 空容器：留一对括号，别让它看起来像"展开失败"（`"{}"` / `"[]"` 这类字符串也走这里）
+    if (sizeOf(val) === 0) {
+      row.appendChild(fvEl('span', 'tr-full-key', keyText));
+      if (fromJson) row.appendChild(jsonBadge());
+      row.appendChild(fvEl('span', 'tr-full-null', Array.isArray(val) ? ' []' : ' {}'));
+      box.appendChild(row);
+      continue;
+    }
+
+    row.appendChild(fvEl('span', 'tr-full-key', keyText));
+    row.appendChild(pathBtn(childPath));
+    if (fromJson) row.appendChild(jsonBadge());
+    if (!open) {
+      const kind = Array.isArray(val) ? 'array' : 'object';
+      row.appendChild(fvEl('span', 'tr-full-hint', ` { ${kind} · ${sizeOf(val)} 项 }`));
+    } else if (Array.isArray(val) && tableColsOf(val)) {
+      // 成表时行内不铺子项，只在键名后标一句规模 —— 否则 `▾ targets:` 后面直接跟着表格，
+      // 看不出这是个数组、也看不出表格是不是全部内容（是不是被截断了）
+      row.appendChild(fvEl('span', 'tr-full-hint', ` array · ${val.length} 项`));
+    }
+    row.dataset.fold = childPath;
+    row.addEventListener('click', (e) => {
+      if (e && typeof e.stopPropagation === 'function') e.stopPropagation();
+      if (hasSelection()) return;
+      ctx.fold.set(childPath, !open);
+      ctx.repaint();
+    });
+    box.appendChild(row);
+
+    if (open) renderInto(ctx, val, depth + 1, childPath, fromJson ? false : allowParse);
+  }
+
+  if (keys.length > show.length) {
+    const row = startRow(depth, '');
+    row.appendChild(fvEl('span', 'tr-full-null', `… 还有 ${keys.length - show.length} 项未展开`));
+    box.appendChild(row);
+  }
+}
+
+/**
+ * 建一个结构化正文块。
+ * @param {any} value  `ev.full` 的**原值**（不是序列化后的字符串）
+ * @param {{fold?: Map<string, boolean>}} [opts]
+ *   `fold` 是**调用方持有**的折叠状态（路径 → 是否展开）。省略时本块自建一份，
+ *   此时折叠状态活不过下一次「全量重建」—— 只对一次性渲染（测试、静态快照）够用。
+ * @returns {Element}  `.tr-full` 块；调用方负责 append 到展开行之后
+ */
+export function createFullView(value, opts = {}) {
+  const fold = opts.fold instanceof Map ? opts.fold : new Map();
+
+  // 根是字符串 ⇒ 只有「里面装着 JSON」才会进来（调用方用 hasStructuredBody 先筛过）。
+  // 头部同时写出**两件事**：它原本是字符串（字符数）、解析后是什么规模 —— 只写后者，
+  // 读者会以为工具真的返回了对象。
+  const parsedRoot = jsonInString(value);
+  const root = parsedRoot ?? value;
+  const fromJson = parsedRoot !== null;
+
+  const box = fvEl('div', 'tr-full');
+  box.dataset.kind = Array.isArray(root) ? 'array' : 'object';
+
+  const head = fvEl('div', 'tr-full-head');
+  const label = typeLabelOf(root);
+  head.appendChild(
+    fvEl('span', 'tr-full-type', fromJson ? `string · ${value.length} 字符 → ${label}` : label),
+  );
+  if (fromJson) head.appendChild(jsonBadge());
+  const copy = fvEl('span', 'tr-full-copy', '复制');
+  copy.dataset.copy = '1';
+  // 字符串根复制的是**原文**（拿到手能直接喂 jq）；容器根复制的是缩进后的 JSON
+  copy.addEventListener('click', () =>
+    copyInto(copy, fromJson ? String(value) : safeStringify(root), '已复制'),
+  );
+  head.appendChild(copy);
+  box.appendChild(head);
+
+  const body = fvEl('div', 'tr-full-body');
+  const ctx = { body, fold, repaint: null };
+  // 只重画正文（不动头部）：折叠不需要重建整棵树，滚动位置与头部反馈都留着
+  ctx.repaint = () => {
+    body.innerHTML = '';
+    // 根若是从字符串解析来的，它的子树不再二次解析（只解析一层，防嵌套放大）
+    renderInto(ctx, root, 0, '', !fromJson);
+  };
+  ctx.repaint();
+
+  box.appendChild(body);
+  return box;
+}

package/dist/inspector/index.js

@@ -12,3 +12,9 @@ export {
 } from './view.js';
 export { playTrace } from './fromTrace.js';
 export { summarizeTrace, renderSummary } from './summary.js';
+/* 结构化正文块（2026-11-11）：`full` 是容器时，渲染器会给展开行挂上这个块；
+ * 2026-11-12 起「装着 JSON 的字符串」也走这条路（`hasStructuredBody` 是同一个判据，
+ * 宿主自己判断要不要挂块时用得上）。单独导出是因为它是**纯函数式的 DOM 构造**
+ * （入参 → 元素），宿主可以拿它渲染任意值 —— 而 bundle 的导出面必须与这里逐字一致
+ * （`test/bundle.test.js`），所以内部件不进公共面、这两件必须进。 */
+export { createFullView, hasStructuredBody } from './full-view.js';