mingdao-harness 0.6.32 → 0.6.33

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # MingDao-Harness 架构设计
 
-> 版本口径：v0.6.30。本文档覆盖 `src/` 全部 **90** 个模块（`find src -name '*.js' | wc -l` = 90），
+> 版本口径：v0.6.30。本文档覆盖 `src/` 全部 **91** 个模块（`find src -name '*.js' | wc -l` = 91），
 > 按层给出每个模块的职责与它守住的那条不变量；判定以文件头注释与实际实现为准，不做推断性描述。
 >
 > 阅读顺序建议：§2 模块索引（查「某件事归谁管」）→ §3 数据流（看一次回合怎么走）→ §4 已知边界（看它**保证不了**什么）。
@@ -54,7 +54,7 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 
 ## 2. 模块索引
 
-以下逐文件列出 `src/` 全部 90 个模块。每条格式为「职责 —— 关键不变量/边界」。
+以下逐文件列出 `src/` 全部 91 个模块。每条格式为「职责 —— 关键不变量/边界」。
 
 ### 2.1 内核循环与上下文（6）
 
@@ -131,6 +131,8 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 - `web/constants.js` —— 前端与服务端共享常量：并发上限 8（`MAX_CONCURRENT`）、附件数与体积上限、单文件读取上限 —— 数值只在此定义，防客户端预检/服务端校验/工具读取三处漂移。
 - `web/attachments.js` —— 聊天附件构造（纯函数）：图片转 `data:` URL（仅视觉模型，单张 ≤5MB、最多 4 个），文本文件拼接进消息（≤200KB）—— 服务端按同一组常量校验。
 - `web/web-io.js` —— WebUI 的 io 适配器：把 Agent 的 io 事件翻译为 SSE 事件，权限确认/选择类交互经 `askHandler` 转发到浏览器模态框并等待 `POST /api/permission` 应答。
+- `web/viewmodel.js`（v0.7.0 §1.2）—— 前端的**纯计算层**：`sideNavLayout`（三档断点下的左栏形态）、`errCardParts`（错误卡文案分解）、`runStripView`（状态条六字段）、`traceRoundView`（轨迹一轮的视图模型）以及它们依赖的格式化助手。**不读 DOM、不读全局**，因此可以被 node 直测；`app.js` 只负责把结果渲染到 DOM。
+  为什么抽出来：此前 `app.js` 3252 行、可执行覆盖 0%，只靠源码正则守卫——UI 改动的"绿"等于"文本没变"。
 - `web/util.js` / `web/app.js` / `web/i18n.js` —— 前端：`util.js` 是零状态工具（选择器/转义/Markdown/格式化），`app.js` 是页面主脚本（消息渲染与轨迹、设置面板、自绘气泡与模态框），`i18n.js` 是零依赖 UI 文案表（zh/en 同键、默认跟随 `navigator.language`、`localStorage` 覆盖）—— 地址带 `?token=` 时记入 `sessionStorage` 并从地址栏移除，此后请求统一附加 `X-MingDao-Token`。
 
 ### 2.8 CLI 层（13）
@@ -172,7 +174,7 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 - `index.js` —— 库公共 API：导出 `@stable`（minor 内向后兼容）与 `@experimental` 两组能力，契约与示例见 DEVELOPER.md。
 
 模块计数核对：6 + 8 + 12 + 10 + 3 + 2 + 13 + 13 + 19 = **86** 个条目（含合并条目；`find src -name '*.js' | wc -l` = **90**），其中 §2.7 的
-`web/util.js` / `web/app.js` 一条覆盖 2 个文件，故条目覆盖 **90** 个 `src/**/*.js`（每版本以 `find` 实测为准），
+`web/util.js` / `web/app.js` 一条覆盖 2 个文件、`web/viewmodel.js` 单列，故条目覆盖 **91** 个 `src/**/*.js`（每版本以 `find` 实测为准），
 与 `find src -name '*.js' | wc -l` 的结果一致。
 
 ## 3. 数据流：一次 `runTurn` 的关键路径

package/docs/DEVELOPER.md

@@ -318,3 +318,96 @@ V8 块覆盖率（`isBlockCoverage`）的语义是：一条区间的计数只作
   降序取末 8 个 = 最小的 8 个文件，所以那行标题下的名单从来没和"最低覆盖"对应过）。
 - 基线是在本机 Node v24 / macOS 上实测生成的；CI 覆盖率腿跑 Linux + Node 20。V8 对同一份源码
   的块区间理论上一致，若 CI 实测略有出入，应按 CI 的实测值重建基线并在提交说明里写明原因。
+
+## 八、变异覆盖盲区检查（v0.7.0 §1.2）
+
+> 变异验证回答的是「**改坏了的代码会不会被抓到**」；它不回答「从没被改过的模块安不安全」。
+> 2026-11 的自审实测：633→669 条变异里 4 个文件占了 285 条，而 90 个模块里 43 个**一条变异都没有**。
+> 分数高只说明「改过的都测了」，盲区模块在报告里是**沉默**的——这一节把沉默变成可复跑的清单。
+
+### 8.1 三件套：行为套件 → 变异批次 → 盲区检查
+
+给一个「有真实逻辑但 0 条变异」的模块补覆盖，顺序不能颠倒：
+
+1. **先建行为套件**（`test/<模块>-<主题>.js`）。没有套件就没有可抓的变异。
+   - 调**真实函数**看结果，不做源码文本匹配；
+   - 用本机临时目录（`fs.mkdtempSync(path.join(os.tmpdir(), ...))`）+ 桩服务端，不连网；
+   - 每条断言带稳定前缀（如 `E1：`、`P7：`、`W13：`），后面写变异批次要用它当关键词。
+2. **再写变异批次**（`test/mutate/batchNN-<主题>.mjs`，参照 `batch72`/`73`/`74`）。
+   - 只改 `src/**` 里**最容易写错**的那一行：整键替换 vs 合并、mtime 丢失、围栏少一层 realpath、
+     软链不判、能力声明不校验、错误被吞……；
+   - 每条都在套件上**真跑一遍**，必须红；
+   - `expect` 填**失败输出里真实出现的关键词**（断言原文的一部分）。
+     本仓在这上面踩过两次：一次是 `expect` 写了同一断言组里另一条分支的文案；一次是
+     `'工具名非法'` 同时出现在 `registerTool` 的兜底报错里，变异把 Pack 层主动告警删掉后
+     **仍然命中**、看起来"抓到了"。所以 `expect` 要尽量长、尽量是**你删掉的那条路径**独有的话。
+3. **跑一遍盲区检查**（下节），确认这个模块从清单里消失。
+
+### 8.2 盲区检查：`scripts/mutation-coverage.mjs`
+
+```bash
+node scripts/mutation-coverage.mjs                 # 只报告（退出 0）
+node scripts/mutation-coverage.mjs --fail-over 0   # 盲区数 > 0 即失败（CI 卡新增盲区）
+node scripts/mutation-coverage.mjs --fail-over 13  # 只允许存量 13 个（存量基线，逐步下调）
+node scripts/mutation-coverage.mjs --min-lines 150  # 调整"有真实逻辑"的代码行门槛
+node scripts/mutation-coverage.mjs --json          # 机器可读
+```
+
+口径（简单、可解释）：
+
+- **代码行** = 去掉空行与纯注释行后的行数（逐字符识别 `//`、`/* */`；字符串里的 `//` 不算注释）。
+- **变异条数** = 该文件在全部 `test/mutate/batch*.mjs` 的 `file:` 字段里出现的次数（只统计 `src/**`）。
+- **盲区** = 代码行 > `--min-lines`（默认 150）且变异条数 = 0。
+
+`--fail-over N` 的语义：**盲区模块数 > N 时非零退出**；不带该参数绝不失败（只报告）。
+CI 想"只卡新增盲区"就用当前存量数当基线（例如 `--fail-over 13`），想"一个都不能有"就用 0。
+本任务**未**把它接进 `.github/workflows/ci.yml`（不在允许改动范围）——接线时注意：直接上
+`--fail-over 0` 会让今天的存量盲区全部变红，应先按存量收敛。
+
+### 8.3 当前盲区清单（2026-11-04，v0.6.32 / HEAD b5cd199 + 本任务三批变异）
+
+`node scripts/mutation-coverage.mjs` 的实跑输出（如实抄录；数字随后续批次变化，**以脚本输出为准**）：
+
+```text
+变异覆盖盲区检查（阈值：代码行 > 150 且 0 条变异）
+  src 模块：91 个；src/** 变异条目：630 条；盲区模块：13 个
+
+  模块（按代码行降序）：
+  模块                        代码行  变异
+  src/ui.js                    600     0
+  src/mcp.js                   303     0
+  src/tokenizer.js             302     0
+  src/commands/sync.js         288     0
+  src/update.js                244     0
+  src/web/viewmodel.js         243     0
+  src/web/i18n.js              225     0
+  src/commands/skill.js        218     0
+  src/web/util.js              198     0
+  src/commands/update.js       187     0
+  src/commands/schedule.js     181     0
+  src/skill-registry.js        171     0
+  src/compact.js               154     0
+
+  合计：13 个模块、3314 行代码没有可抓的变异。
+```
+
+本任务补掉的三处（此前均 0 条）：
+
+| 模块 | 行为套件 | 变异批次 | 条数 |
+| --- | --- | --- | --- |
+| `src/sync.js` 状态增量 / 冲突 / 边界 | `test/sync-state.js`（16 项） | `test/mutate/batch72-sync-state.mjs` | 10 |
+| `src/packs.js` manifest / 版本 / 能力声明 / 信任门 | `test/packs-capabilities.js`（16 项） | `test/mutate/batch73-packs.mjs` | 10 |
+| `src/workspace.js` 注册表 / 归一 / 跨进程锁 | `test/workspace-fence.js`（15 项） | `test/mutate/batch74-workspace.mjs` | 11 |
+
+> 模块边界如实说明：`src/workspace.js` 本身**不含**路径围栏（`withinRoot`），围栏真实实现于
+> `src/tools/fs-tools.js` 与 `src/web/routes/domains/workspace.js`。`batch74` 的 11 条里有 8 条打在
+> `src/workspace.js`，2 条打在前者的 `withinRoot`，2 条打在后者（允许根 / realpath 两层围栏）。
+> 另外 `src/sync.js` 在本任务前已有 1 条（`batch70` ⑦），并非严格 0 条。
+
+### 8.4 边界
+
+- 本任务的三个新套件**没有**接进 `test/run-all.mjs` 与 CI（不在允许改动范围）。要接的话，
+  在 `SUITES` 里加 `['sync-state', 'node', ['test/sync-state.js']]` 等三行即可；
+  三个套件都是零外部依赖、只用本机临时目录。
+- 盲区检查只回答"有没有变异"，不回答"变异质量"——`--fail-over` 只能挡住新增盲区，
+  挡不住"给一个 600 行模块写 1 条无关变异"这种凑数。质量仍靠 review 与 `expect` 关键词约束。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.32",
+  "version": "0.6.33",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/web/app.js

@@ -1,5 +1,6 @@
 import { $, esc, highlight, renderMarkdown, scrollBottom, expandableBody, resultText, truncText, textBody, fmtDur, fmtTok, fmtT } from './util.js';
 import { MAX_ATTACHMENTS, MAX_IMAGE_BYTES, MAX_TEXT_BYTES } from './constants.js';
+import { sideNavBreakpoint, sideNavLayout, errCardParts, runStripView, permissionSourceLabel, toolStepView, toolTimelineSummary, toolTimelineVisibility, traceRoundView } from './viewmodel.js';
 
 // 访问令牌（P1-3）：地址带 ?token= 时记入 sessionStorage 并从地址栏移除（防截图/历史外泄），
 // 之后所有同源请求统一附加 X-MingDao-Token 头；无令牌时行为与旧版一致。
@@ -349,18 +350,8 @@ function toggleRecentSessions() {
   writeRecentCollapsed(storage, recentCollapsed);
   syncRecentCollapsed(recentCollapsed);
 }
-/** 左栏三档断点：≥1180 展开(240) / 900–1180 自动折叠(48) / <900 抽屉。右栏收起点见 layoutClassesFor（<1100）。 */
-function sideNavBreakpoint(width) {
-  const w = Number(width) || 0;
-  if (w >= 1180) return 'wide';
-  if (w >= 900) return 'mid';
-  return 'drawer';
-}
-function sideNavLayout(width, pref) {
-  const mode = sideNavBreakpoint(width);
-  const collapsed = mode === 'mid' || (mode === 'wide' && !!pref);
-  return { mode, collapsed, width: mode === 'drawer' ? 0 : (collapsed ? 48 : 240), drawer: mode === 'drawer' };
-}
+// 左栏三档断点/布局是纯计算，已搬到 viewmodel.js（sideNavBreakpoint / sideNavLayout）；
+// 这里只消费结果，类名映射（sideNavClassNames）仍留在 DOM 层。
 function sideNavClassNames(layout) {
   const out = [];
   if (layout.mode === 'wide') out.push('side-wide');
@@ -555,17 +546,7 @@ function renderTodos(todos,msg){
 // —— 错误卡：三段式（纯函数；smoke §148 直接 eval 这段做行为断言） ——
 // 上游原文保留换行（<pre> + white-space:pre-wrap），默认折叠只显示首行摘要；
 // 处置建议独立成一行（.err-hint，white-space:pre-line），与原文明分；长错误可一键复制。
-function errCardParts(text){
-  const rawText=String(text||'').replace(/\r\n?/g,'\n');
-  const lines=rawText.split('\n');
-  let hintIdx=-1;
-  for(let i=0;i<lines.length;i++){ if(/^\s*(?:💡|提示[:：]|处置建议[:：])/.test(lines[i])){ hintIdx=i; break; } }
-  const hint=hintIdx>=0?lines[hintIdx].trim():'';
-  const raw=(hintIdx>=0?lines.slice(0,hintIdx):lines).join('\n').trim()||rawText.trim();
-  const head=(lines[0]||'').trim();
-  const tag=/上游|upstream/i.test(rawText)?'上游':/超时|timeout/i.test(rawText)?'内核':'错误';
-  return {head,hint,raw,tag};
-}
+// 三段式的纯计算已搬到 viewmodel.js（errCardParts）；errCardHtml 只做字符串拼装。
 function errCardHtml(text){
   const p=errCardParts(text);
   const summary=p.head.length>120?p.head.slice(0,120)+'…':p.head;
@@ -984,56 +965,10 @@ async function stopTurnFromButton(){
 }
 
 // —— 输入框上方工作状态条（P0-1 起由下面的 #runStrip 常驻状态条取代；保留本行作为既有守卫的定位锚点）
-// —— 运行状态条：字段口径（纯函数；smoke §148 直接 eval 这段做行为断言） ——
+// —— 运行状态条：字段口径（纯函数；已搬到 viewmodel.js，smoke 直测 runStripView） ——
 // 阶段只有五档（等首帧 / 解码中 / 执行工具 / 已中止 / 空闲）——服务端的 phase 文案更细
 // （发请求（等首帧）/ 解码中（收到增量）/ 执行工具 bash / 排队等待本地端点…），这里收敛成用户能一眼读懂的五档。
-function normalizeRunPhase(rawPhase, isGenerating, aborted){
-  if(aborted) return '已中止';
-  if(!isGenerating) return '空闲';
-  const p=String(rawPhase||'');
-  if(/已中止|已停止|aborted|stalled/.test(p)) return '已中止';
-  if(/解码/.test(p)) return '解码中';
-  if(/执行工具|等待权限确认|待发请求|子\s?Agent|工具/.test(p)) return '执行工具';
-  return '等首帧';
-}
-function fmtRunTtft(ms){ return ms==null || !Number.isFinite(Number(ms)) ? '—' : (Number(ms)/1000).toFixed(1)+'s'; }
-function fmtRunTps(v){ return v==null || !Number.isFinite(Number(v)) ? '—' : Number(v).toFixed(1); }
-function fmtRunTools(n){ const k=Math.max(0,Math.round(Number(n)||0)); return k===0 ? '0 次工具调用' : k+' 次工具调用'; }
-function fmtRunCost(cost){ const m=String(cost||'').match(/≈¥[0-9.]+/); return m ? m[0] : ''; }
-function fmtRunCtx(st){
-  const total=Number(st.contextTotal)||0;
-  const used=Math.max(0,Math.round(Number(st.contextUsed)||0));
-  if(!total && !used) return '—';
-  // 生成中没有实时 used tokens（内核 budget 只在 done 算）：用「上一轮 used + 本轮字符估算」，
-  // 必须标 ≈；done 带回 budget 后才是精确值（去掉 ≈）。
-  const approx=st.contextApprox !== false;
-  return (approx?'≈ ':'')+fmtTok(used)+' / '+(total?fmtTok(total):'?')+' tokens';
-}
-function runStripView(st, isGenerating){
-  return {
-    phase: normalizeRunPhase(st.rawPhase, isGenerating !== false, st.aborted),
-    ttft: fmtRunTtft(st.ttftMs),
-    tps: fmtRunTps(st.tokensPerSec),
-    ctx: fmtRunCtx(st),
-    tools: fmtRunTools(st.toolCalls),
-    cost: fmtRunCost(st.cost) || '—',
-  };
-}
-/** 把一条 progress 事件并进运行状态（桩 SSE 与真实 SSE 走同一条路径）。 */
-function applyRunProgress(st, ev, baseUsed){
-  st.rawPhase=String(ev.phase||'');
-  st.phase=normalizeRunPhase(st.rawPhase, true, false);
-  if(ev.ttftMs!=null) st.ttftMs=Number(ev.ttftMs)||0;
-  st.tokensPerSec=ev.tokensPerSec!=null ? Number(ev.tokensPerSec) : null;
-  st.toolCalls=Number(ev.toolCalls)||0;
-  st.contentChars=Number(ev.contentChars)||0;
-  st.contextApprox=true;
-  st.contextUsed=Math.max(0, Number(baseUsed)||0) + Math.round(st.contentChars/1.5);
-  return st;
-}
-function permissionSourceLabel(source){
-  return ({explicit:'显式选择',preset:'预设',config:'config 默认',cli:'命令行',default:'内置默认'})[String(source||'')] || '未知';
-}
+// runStripView / applyRunProgress / permissionSourceLabel 及六个 fmtRun* 全部在 viewmodel.js。
 
 // —— 状态条渲染（**唯一**刷新出口；合并原 #workStatus / 顶部活动条 / 消息内气泡三处） ——
 function renderWorkStatus(){
@@ -1075,116 +1010,7 @@ function renderWorkStatus(){
 // 会话设置文案。DOM 渲染在下面各自的小节里，只消费这些结果。
 // ============================================================================
 
-// —— 工具时间线：同一轮多个调用聚合成一张卡（默认前 3 步 + 失败步，整卡可折叠） ——
-const TOOL_TL_DEFAULT_VISIBLE = 3;
-const TOOL_OUTPUT_PREVIEW = 900;
-/** 工具参数的**一行**摘要（完整参数在展开区里用 JSON 显示）。 */
-function toolArgsSummary(name, args) {
-  const a = args || {};
-  if (name === 'bash') return String(a.command || '');
-  if (name === 'task') return String(a.question || a.prompt || a.description || '');
-  return String(a.path || a.pattern || a.name || a.query || a.url || a.file || '');
-}
-/** 工具结果的一行摘要（不是正文；正文在展开区）。 */
-function toolResultSummary(ev) {
-  if (!ev || ev.result === undefined) return '执行中…';
-  const r = ev.result || {};
-  if (r.ok === false) return r.error ? String(r.error).split('\n')[0] : '失败';
-  if (ev.name === 'bash') return r.timedOut ? '超时' : 'exit ' + (r.exitCode != null ? r.exitCode : 0);
-  if (ev.name === 'skill') {
-    const m = String(r.output || '').match(/^description:\s*(.+)$/m);
-    return m ? m[1].slice(0, 100) : '已加载技能';
-  }
-  if (ev.name === 'write') return r.bytes != null ? r.bytes + ' 字节' : '已写入';
-  if (ev.name === 'edit') return '已修改';
-  if (ev.name === 'read') return r.lines != null ? r.lines + ' 行' : '读取完成';
-  if (ev.name === 'todo') return '更新任务清单';
-  const out = String(r.output || r.stdout || r.stderr || '');
-  return out.split('\n')[0].slice(0, 120);
-}
-/** 工具输出的完整文本（展开区用）。 */
-function toolOutputText(ev) {
-  const r = (ev && ev.result) || {};
-  if (ev && ev.name === 'skill') return String(r.output || '');
-  if (r.diff) {
-    const before = String(r.diff.before || '').split('\n');
-    const after = String(r.diff.after || '').split('\n');
-    const n = Math.max(before.length, after.length);
-    const out = [];
-    for (let i = 0; i < n; i++) {
-      if (before[i] === after[i]) out.push(' ' + (before[i] || ''));
-      else {
-        if (before[i] !== undefined) out.push('- ' + before[i]);
-        if (after[i] !== undefined) out.push('+ ' + after[i]);
-      }
-    }
-    return out.join('\n');
-  }
-  if (ev && ev.name === 'bash') return [r.stdout, r.stderr].filter(Boolean).join('\n') || ('exit ' + (r.exitCode != null ? r.exitCode : 0));
-  if (r.output != null) return String(r.output);
-  if (r.error != null) return String(r.error);
-  return ev && ev.result !== undefined ? JSON.stringify(r, null, 2) : '';
-}
-/** 长输出折叠判据：给出完整文本、预览、行数与字节数（用户要知道被折了多少）。 */
-function toolOutputStats(text, limit) {
-  const full = String(text == null ? '' : text);
-  const max = Number(limit) || TOOL_OUTPUT_PREVIEW;
-  const lines = full === '' ? 0 : full.split('\n').length;
-  let bytes = full.length;
-  try { bytes = new TextEncoder().encode(full).length; } catch { bytes = full.length; }
-  const truncated = full.length > max || lines > 40;
-  const preview = !truncated ? full : (full.length > max ? full.slice(0, max) : full.split('\n').slice(0, 40).join('\n'));
-  return { full, preview, lines, bytes, truncated };
-}
-/** 单步视图（失败高亮类名 / 状态图标 / 一行摘要 / 完整参数与输出）。 */
-function toolStepView(ev, done) {
-  const isDone = done !== undefined ? Boolean(done) : ev.result !== undefined || ev.denied;
-  const failed = Boolean(ev.denied) || (ev.result !== undefined && ev.result && ev.result.ok === false);
-  const out = toolOutputStats(toolOutputText(ev));
-  return {
-    seq: ev.seq,
-    name: String(ev.name || 'tool'),
-    args: toolArgsSummary(ev.name, ev.args),
-    argsJson: JSON.stringify(ev.args || {}, null, 2),
-    durationMs: ev.durationMs != null ? Number(ev.durationMs) : null,
-    dur: ev.durationMs != null ? fmtToolDur(ev.durationMs) : (isDone ? '—' : '执行中…'),
-    done: isDone,
-    failed,
-    stIcon: !isDone ? '…' : failed ? '✖' : '✓',
-    stCls: !isDone ? '' : failed ? 'bad' : 'ok',
-    result: ev.denied ? String(ev.denied || '未授权') : toolResultSummary(ev),
-    output: out,
-    liClass: 'tl-step' + (failed ? ' fail' : ''),
-  };
-}
-function fmtToolDur(ms) {
-  const n = Number(ms) || 0;
-  return n < 1000 ? n + 'ms' : (n / 1000).toFixed(1) + 's';
-}
-/** 时间线汇总：步数 / 失败数 / 总耗时 / 头行文案。 */
-function toolTimelineSummary(items) {
-  const list = items || [];
-  const failed = list.filter((s) => s.failed).length;
-  const totalMs = list.reduce((a, s) => a + (Number(s.durationMs) || 0), 0);
-  const detail = list.length + ' 步' + (failed ? ' · ' + failed + ' 个失败' : '');
-  return {
-    count: list.length,
-    failed,
-    totalMs,
-    countText: detail,
-    sumText: totalMs ? fmtToolDur(totalMs) : '',
-  };
-}
-/** 默认可见步：前 3 步 + 所有失败步（失败步免展开可见）。 */
-function toolTimelineVisibility(items, expanded) {
-  const list = items || [];
-  if (expanded) return list.map((_, i) => i);
-  const keep = new Set();
-  for (let i = 0; i < Math.min(TOOL_TL_DEFAULT_VISIBLE, list.length); i++) keep.add(i);
-  list.forEach((s, i) => { if (s.failed) keep.add(i); });
-  return [...keep].sort((a, b) => a - b);
-}
-
+// —— 工具时间线 / 轨迹视图（纯函数；已搬到 viewmodel.js，smoke 直测 toolStepView / traceRoundView） ——
 // —— 右侧「本轮运行」：六项字段与状态条同源（都从 runStripView 派生） ——
 function runPanelView(st, isGenerating) {
   const base = runStripView(st, isGenerating);
@@ -1350,71 +1176,7 @@ function applyThemePreference(pref, deps) {
 // —— 轨迹 / 子 Agent 视图（v0.6.21 §3.73；smoke §151 直接 eval 这段做行为断言） ——
 // 唯一统计口径：对话流每轮那一行摘要与右栏「轨迹」都走 traceRoundView / traceSummaryText，
 // 由 traceRoundForMsg 统一装配。**不允许**两处各算一套（§151 断言两处都调用同一函数）。
-function fmtTraceDur(ms) {
-  const total = Math.max(0, Math.round((Number(ms) || 0) / 1000));
-  if (total < 60) return total + 's';
-  const m = Math.floor(total / 60);
-  const s = total % 60;
-  if (m < 60) return m + 'm' + (s ? s + 's' : '');
-  const h = Math.floor(m / 60);
-  const rm = m % 60;
-  return h + 'h' + (rm ? rm + 'm' : '');
-}
-/** 子代理一行的视图：名称 · 轮次 · 工具次数 · 最后进展 · 状态（缺失字段如实显示 —，不编造）。 */
-function subagentRowView(sub) {
-  const s = sub || {};
-  const toolCalls = s.toolCalls == null || !Number.isFinite(Number(s.toolCalls)) ? null : Math.max(0, Math.round(Number(s.toolCalls)));
-  const modelRounds = s.modelRounds == null || !Number.isFinite(Number(s.modelRounds)) ? null : Math.max(0, Math.round(Number(s.modelRounds)));
-  const ago = s.lastProgressAgoMs == null || !Number.isFinite(Number(s.lastProgressAgoMs)) ? null : Math.max(0, Math.round(Number(s.lastProgressAgoMs)));
-  const running = Boolean(s.running);
-  const failed = !running && (s.status === 'failed' || Boolean(s.result && s.result.ok === false));
-  const status = running ? 'running' : failed ? 'failed' : 'done';
-  const round = Math.max(0, Math.round(Number(s.round) || 0));
-  return {
-    key: 'sub:' + String(s.seq == null ? '?' : s.seq),
-    seq: s.seq,
-    round,
-    roundText: round ? '第 ' + round + ' 轮' : '—',
-    name: String(s.label || s.description || s.question || '子代理').slice(0, 80),
-    question: String(s.question || ''),
-    toolCalls,
-    toolText: toolCalls == null ? '工具次数 —' : toolCalls + ' 次工具',
-    modelRounds,
-    roundsText: modelRounds == null ? '自身轮次 —' : modelRounds + ' 轮',
-    progress: ago == null ? '最后进展 —' : '最后进展 ' + (ago < 1000 ? '<1s' : Math.round(ago / 1000) + 's') + ' 前',
-    status,
-    statusText: running ? '运行中' : failed ? '失败' : '完成',
-    statusCls: running ? 'run' : failed ? 'bad' : 'ok',
-    running,
-    durationMs: s.durationMs == null ? null : Number(s.durationMs),
-    result: s.result,
-  };
-}
-/** 一轮的完整视图（工具步 + 子代理 + 摘要文案）；对话流与右栏消费同一个对象。 */
-function traceRoundView(round) {
-  const r = round || {};
-  const now = Number(r.now) || Date.now();
-  const tools = (r.tools || []).map((t) => toolStepView(t, t.done));
-  const subs = (r.subs || []).map(subagentRowView);
-  const started = Number(r.startedAt) || 0;
-  const ended = r.endedAt != null ? Number(r.endedAt) : now;
-  const durationMs = started ? Math.max(0, ended - started) : 0;
-  const durationText = started ? fmtTraceDur(durationMs) : '';
-  const parts = ['本轮 ' + tools.length + ' 次工具调用'];
-  if (subs.length) parts.push(subs.length + ' 个子代理');
-  if (durationText) parts.push(durationText);
-  return {
-    round: Math.max(0, Math.round(Number(r.round) || 0)),
-    tools,
-    subs,
-    toolCount: tools.length,
-    subCount: subs.length,
-    failed: tools.filter((t) => t.failed).length,
-    durationMs,
-    durationText,
-    summary: parts.join(' · '),
-  };
-}
+// fmtTraceDur / subagentRowView / traceRoundView 已搬到 viewmodel.js；下面只保留数据装配与文案读取。
 function traceSummaryText(view) { return String((view && view.summary) || ''); }
 /** 每轮的数据装配：只读 msg._traj 与传入的 sessionSubs/pending，不读 runState、不另算。 */
 function traceRoundData(msg, subs, pending, now) {

package/src/web/routes/api.js

@@ -32,7 +32,7 @@ export function createApiDispatch(deps) {
     // 访问控制（P1-3/P1-4）：token 校验覆盖数据与操作接口；壳页面与 PWA 静态资源公开
     // （壳不含任何数据，SPA 需要先加载才能读取 ?token=）；Host 白名单覆盖一切请求
     const isStaticAsset =
-      p === '/' || p === '/index.html' || p === '/app.js' || p === '/util.js' || p === '/constants.js' || p === '/favicon.ico' || p === '/icon.svg' || p === '/icon-192.png' || p === '/icon-512.png' || p === '/manifest.webmanifest' || p === '/sw.js';
+      p === '/' || p === '/index.html' || p === '/app.js' || p === '/util.js' || p === '/constants.js' || p === '/viewmodel.js' || p === '/favicon.ico' || p === '/icon.svg' || p === '/icon-192.png' || p === '/icon-512.png' || p === '/manifest.webmanifest' || p === '/sw.js';
     if (authEnabled && !isStaticAsset && !tokenMatches(requestToken(req, url))) {
       return json(res, 401, { error: '未授权：缺少或无效的访问令牌（地址需带 ?token=…，或请求头携带 X-MingDao-Token）' });
     }
@@ -90,7 +90,8 @@ export function createApiDispatch(deps) {
     // —— 静态壳资源（公开；不经过域分发） ——
     // 质检 Q2/S5：SPA 外部 JS——从磁盘读取（与 index.html 同目录）。
     // v0.2.8 C2：app.js 拆分为 ES Modules（app.js / util.js / constants.js），统一从此处伺服。
-    const WEB_JS_FILES = new Set(['app.js', 'util.js', 'constants.js']);
+    // v0.7.0 §1.2：viewmodel.js（纯视图模型）与 app.js 同目录、同源伺服（不新增接口，只加白名单）。
+    const WEB_JS_FILES = new Set(['app.js', 'util.js', 'constants.js', 'viewmodel.js']);
     if (method === 'GET' && WEB_JS_FILES.has(p.slice(1))) {
       try {
         const js = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', p.slice(1)), 'utf8');

package/src/web/viewmodel.js

@@ -0,0 +1,447 @@
+// 前端纯视图模型（v0.7.0 §1.2）：从 app.js 搬出的可直测计算层。
+//
+// 设计约束（与 smoke §148/§149/§151/§158 的行为断言一致）：
+//   · 不读 DOM、不读窗口尺寸、不读 localStorage、不读写任何模块级可变状态；
+//   · 只依赖入参（以及 util.js 的纯格式化函数），同样的输入永远得到同样的输出；
+//   · 输出字段名就是 app.js 渲染层消费的字段名——改名会当场打破 smoke 的形状断言。
+//
+// 本文件只做"纯计算"，DOM 接线仍在 app.js。test/viewmodel.js 用 node 直跑，
+// 并把搬家前的原实现当作"参照实现"逐组对拍，证明这次搬家没有改变行为。
+
+// 本模块刻意不 import util.js：util.js 依赖 document，属于浏览器层；tsconfig.full 的
+// exclude 不阻断"被 import 的文件"进入类型检查。这里只复制一个纯格式化函数并逐值对拍。
+/**
+ * tokens 数量缩写（与 util.js 的 fmtTok 逐字节一致；test/viewmodel.js 对数）。
+ *
+ * @param {number} n
+ * @returns {string}
+ */
+function fmtTok(n) {
+  if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B';
+  if (n >= 1e6) return (n / 1e6).toFixed(0) + 'M';
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+  return String(n);
+}
+
+/**
+ * 左栏三档断点：≥1180 展开(240) / 900–1180 自动折叠(48) / <900 抽屉。
+ * 右栏收起点见 app.js 的 layoutClassesFor（<1100）。
+ *
+ * @param {number|string} width 视口宽度；非数字/缺省按 0 处理
+ * @returns {'wide'|'mid'|'drawer'}
+ */
+export function sideNavBreakpoint(width) {
+  const w = Number(width) || 0;
+  if (w >= 1180) return 'wide';
+  if (w >= 900) return 'mid';
+  return 'drawer';
+}
+
+/**
+ * 左栏布局：把断点与用户折叠偏好收敛成渲染层直接消费的对象。
+ *
+ * @param {number|string} width 视口宽度
+ * @param {boolean} pref 用户是否手动折叠（只对 wide 档生效）
+ * @returns {{mode: 'wide'|'mid'|'drawer', collapsed: boolean, width: number, drawer: boolean}}
+ */
+export function sideNavLayout(width, pref) {
+  const mode = sideNavBreakpoint(width);
+  const collapsed = mode === 'mid' || (mode === 'wide' && !!pref);
+  return { mode, collapsed, width: mode === 'drawer' ? 0 : (collapsed ? 48 : 240), drawer: mode === 'drawer' };
+}
+
+/**
+ * 错误卡三段式的纯计算：原文 / 处置建议 / 归属标签 / 首行摘要。
+ * 换行统一为 \n；处置建议行（💡 / 提示：/ 处置建议：）从原文中剥离；
+ * 原文为空时退回整段 trim 后的文本，head 始终取第一行。
+ *
+ * @param {unknown} text 上游错误原文
+ * @returns {{head: string, hint: string, raw: string, tag: '上游'|'内核'|'错误'}}
+ */
+export function errCardParts(text) {
+  const rawText = String(text || '').replace(/\r\n?/g, '\n');
+  const lines = rawText.split('\n');
+  let hintIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(?:💡|提示[:：]|处置建议[:：])/.test(lines[i])) { hintIdx = i; break; }
+  }
+  const hint = hintIdx >= 0 ? lines[hintIdx].trim() : '';
+  const raw = (hintIdx >= 0 ? lines.slice(0, hintIdx) : lines).join('\n').trim() || rawText.trim();
+  const head = (lines[0] || '').trim();
+  const tag = /上游|upstream/i.test(rawText) ? '上游' : /超时|timeout/i.test(rawText) ? '内核' : '错误';
+  return { head, hint, raw, tag };
+}
+
+/**
+ * 运行阶段收敛成五档（等首帧 / 解码中 / 执行工具 / 已中止 / 空闲）。
+ *
+ * @param {unknown} rawPhase 服务端 phase 文案
+ * @param {boolean} isGenerating 是否生成中
+ * @param {boolean|undefined} aborted 是否已中止
+ * @returns {'等首帧'|'解码中'|'执行工具'|'已中止'|'空闲'}
+ */
+export function normalizeRunPhase(rawPhase, isGenerating, aborted) {
+  if (aborted) return '已中止';
+  if (!isGenerating) return '空闲';
+  const p = String(rawPhase || '');
+  if (/已中止|已停止|aborted|stalled/.test(p)) return '已中止';
+  if (/解码/.test(p)) return '解码中';
+  if (/执行工具|等待权限确认|待发请求|子\s?Agent|工具/.test(p)) return '执行工具';
+  return '等首帧';
+}
+
+/**
+ * 首帧耗时文案：非法/缺省显示 —。
+ *
+ * @param {unknown} ms 毫秒
+ * @returns {string}
+ */
+export function fmtRunTtft(ms) {
+  return ms == null || !Number.isFinite(Number(ms)) ? '—' : (Number(ms) / 1000).toFixed(1) + 's';
+}
+
+/**
+ * 吞吐文案：非法/缺省显示 —。
+ *
+ * @param {unknown} v tokens/s
+ * @returns {string}
+ */
+export function fmtRunTps(v) {
+  return v == null || !Number.isFinite(Number(v)) ? '—' : Number(v).toFixed(1);
+}
+
+/**
+ * 工具调用次数文案：0 也必须显式写出来。
+ *
+ * @param {unknown} n
+ * @returns {string}
+ */
+export function fmtRunTools(n) {
+  const k = Math.max(0, Math.round(Number(n) || 0));
+  return k === 0 ? '0 次工具调用' : k + ' 次工具调用';
+}
+
+/**
+ * 费用只取 ≈¥ 金额部分（缓存命中/价格表提示不进一行状态条）。
+ *
+ * @param {unknown} cost
+ * @returns {string} 无金额时返回空串
+ */
+export function fmtRunCost(cost) {
+  const m = String(cost || '').match(/≈¥[0-9.]+/);
+  return m ? m[0] : '';
+}
+
+/**
+ * 上下文占用文案：无数据 —；生成中用 ≈ 标明估算；done 带回精确 budget 时不带 ≈。
+ *
+ * @param {{contextTotal?: unknown, contextUsed?: unknown, contextApprox?: boolean}} st
+ * @returns {string}
+ */
+export function fmtRunCtx(st) {
+  const total = Number(st.contextTotal) || 0;
+  const used = Math.max(0, Math.round(Number(st.contextUsed) || 0));
+  if (!total && !used) return '—';
+  const approx = st.contextApprox !== false;
+  return (approx ? '≈ ' : '') + fmtTok(used) + ' / ' + (total ? fmtTok(total) : '?') + ' tokens';
+}
+
+/**
+ * 常驻运行状态条的六字段视图（状态条与右栏「本轮运行」同源）。
+ *
+ * @param {{rawPhase?: unknown, aborted?: boolean, ttftMs?: unknown, tokensPerSec?: unknown,
+ *          toolCalls?: unknown, contextTotal?: unknown, contextUsed?: unknown,
+ *          contextApprox?: boolean, cost?: unknown}} st
+ * @param {boolean} [isGenerating]
+ * @returns {{phase: string, ttft: string, tps: string, ctx: string, tools: string, cost: string}}
+ */
+export function runStripView(st, isGenerating) {
+  return {
+    phase: normalizeRunPhase(st.rawPhase, isGenerating !== false, st.aborted),
+    ttft: fmtRunTtft(st.ttftMs),
+    tps: fmtRunTps(st.tokensPerSec),
+    ctx: fmtRunCtx(st),
+    tools: fmtRunTools(st.toolCalls),
+    cost: fmtRunCost(st.cost) || '—',
+  };
+}
+
+/**
+ * 把一条 progress 事件并进运行状态（桩 SSE 与真实 SSE 走同一条路径）。
+ * 只改传入的 st（调用方持有的状态对象），不读 DOM/全局。
+ *
+ * @param {Record<string, any>} st
+ * @param {{phase?: unknown, ttftMs?: unknown, tokensPerSec?: unknown, toolCalls?: unknown, contentChars?: unknown}} ev
+ * @param {unknown} baseUsed 上一轮已知 used tokens
+ * @returns {Record<string, any>} 同一个 st
+ */
+export function applyRunProgress(st, ev, baseUsed) {
+  st.rawPhase = String(ev.phase || '');
+  st.phase = normalizeRunPhase(st.rawPhase, true, false);
+  if (ev.ttftMs != null) st.ttftMs = Number(ev.ttftMs) || 0;
+  st.tokensPerSec = ev.tokensPerSec != null ? Number(ev.tokensPerSec) : null;
+  st.toolCalls = Number(ev.toolCalls) || 0;
+  st.contentChars = Number(ev.contentChars) || 0;
+  st.contextApprox = true;
+  st.contextUsed = Math.max(0, Number(baseUsed) || 0) + Math.round(st.contentChars / 1.5);
+  return st;
+}
+
+/**
+ * 权限来源的人读标签。
+ *
+ * @param {unknown} source explicit / preset / config / cli / default
+ * @returns {string}
+ */
+export function permissionSourceLabel(source) {
+  return ({ explicit: '显式选择', preset: '预设', config: 'config 默认', cli: '命令行', default: '内置默认' })[String(source || '')] || '未知';
+}
+
+// —— 工具时间线：同一轮多个调用聚合成一张卡（默认前 3 步 + 失败步，整卡可折叠） ——
+const TOOL_TL_DEFAULT_VISIBLE = 3;
+const TOOL_OUTPUT_PREVIEW = 900;
+
+/**
+ * 工具参数的一行摘要（完整参数在展开区里用 JSON 显示）。
+ *
+ * @param {unknown} name 工具名
+ * @param {Record<string, any>} [args]
+ * @returns {string}
+ */
+export function toolArgsSummary(name, args) {
+  const a = args || {};
+  if (name === 'bash') return String(a.command || '');
+  if (name === 'task') return String(a.question || a.prompt || a.description || '');
+  return String(a.path || a.pattern || a.name || a.query || a.url || a.file || '');
+}
+
+/**
+ * 工具结果的一行摘要（不是正文；正文在展开区）。
+ *
+ * @param {any} ev 工具事件
+ * @returns {string}
+ */
+export function toolResultSummary(ev) {
+  if (!ev || ev.result === undefined) return '执行中…';
+  const r = ev.result || {};
+  if (r.ok === false) return r.error ? String(r.error).split('\n')[0] : '失败';
+  if (ev.name === 'bash') return r.timedOut ? '超时' : 'exit ' + (r.exitCode != null ? r.exitCode : 0);
+  if (ev.name === 'skill') {
+    const m = String(r.output || '').match(/^description:\s*(.+)$/m);
+    return m ? m[1].slice(0, 100) : '已加载技能';
+  }
+  if (ev.name === 'write') return r.bytes != null ? r.bytes + ' 字节' : '已写入';
+  if (ev.name === 'edit') return '已修改';
+  if (ev.name === 'read') return r.lines != null ? r.lines + ' 行' : '读取完成';
+  if (ev.name === 'todo') return '更新任务清单';
+  const out = String(r.output || r.stdout || r.stderr || '');
+  return out.split('\n')[0].slice(0, 120);
+}
+
+/**
+ * 工具输出的完整文本（展开区用）。
+ *
+ * @param {any} ev 工具事件
+ * @returns {string}
+ */
+export function toolOutputText(ev) {
+  const r = (ev && ev.result) || {};
+  if (ev && ev.name === 'skill') return String(r.output || '');
+  if (r.diff) {
+    const before = String(r.diff.before || '').split('\n');
+    const after = String(r.diff.after || '').split('\n');
+    const n = Math.max(before.length, after.length);
+    const out = [];
+    for (let i = 0; i < n; i++) {
+      if (before[i] === after[i]) out.push(' ' + (before[i] || ''));
+      else {
+        if (before[i] !== undefined) out.push('- ' + before[i]);
+        if (after[i] !== undefined) out.push('+ ' + after[i]);
+      }
+    }
+    return out.join('\n');
+  }
+  if (ev && ev.name === 'bash') return [r.stdout, r.stderr].filter(Boolean).join('\n') || ('exit ' + (r.exitCode != null ? r.exitCode : 0));
+  if (r.output != null) return String(r.output);
+  if (r.error != null) return String(r.error);
+  return ev && ev.result !== undefined ? JSON.stringify(r, null, 2) : '';
+}
+
+/**
+ * 长输出折叠判据：给出完整文本、预览、行数与字节数（用户要知道被折了多少）。
+ *
+ * @param {unknown} text
+ * @param {unknown} [limit]
+ * @returns {{full: string, preview: string, lines: number, bytes: number, truncated: boolean}}
+ */
+export function toolOutputStats(text, limit) {
+  const full = String(text == null ? '' : text);
+  const max = Number(limit) || TOOL_OUTPUT_PREVIEW;
+  const lines = full === '' ? 0 : full.split('\n').length;
+  let bytes = full.length;
+  try { bytes = new TextEncoder().encode(full).length; } catch { bytes = full.length; }
+  const truncated = full.length > max || lines > 40;
+  const preview = !truncated ? full : (full.length > max ? full.slice(0, max) : full.split('\n').slice(0, 40).join('\n'));
+  return { full, preview, lines, bytes, truncated };
+}
+
+/**
+ * 单步视图（失败高亮类名 / 状态图标 / 一行摘要 / 完整参数与输出）。
+ *
+ * @param {any} ev 工具事件
+ * @param {boolean} [done] 覆盖完成判据
+ * @returns {Record<string, any>}
+ */
+export function toolStepView(ev, done) {
+  const isDone = done !== undefined ? Boolean(done) : ev.result !== undefined || ev.denied;
+  const failed = Boolean(ev.denied) || (ev.result !== undefined && ev.result && ev.result.ok === false);
+  const out = toolOutputStats(toolOutputText(ev));
+  return {
+    seq: ev.seq,
+    name: String(ev.name || 'tool'),
+    args: toolArgsSummary(ev.name, ev.args),
+    argsJson: JSON.stringify(ev.args || {}, null, 2),
+    durationMs: ev.durationMs != null ? Number(ev.durationMs) : null,
+    dur: ev.durationMs != null ? fmtToolDur(ev.durationMs) : (isDone ? '—' : '执行中…'),
+    done: isDone,
+    failed,
+    stIcon: !isDone ? '…' : failed ? '✖' : '✓',
+    stCls: !isDone ? '' : failed ? 'bad' : 'ok',
+    result: ev.denied ? String(ev.denied || '未授权') : toolResultSummary(ev),
+    output: out,
+    liClass: 'tl-step' + (failed ? ' fail' : ''),
+  };
+}
+
+/**
+ * 工具耗时文案：<1s 用 ms，其余保留一位小数秒。
+ *
+ * @param {unknown} ms
+ * @returns {string}
+ */
+export function fmtToolDur(ms) {
+  const n = Number(ms) || 0;
+  return n < 1000 ? n + 'ms' : (n / 1000).toFixed(1) + 's';
+}
+
+/**
+ * 时间线汇总：步数 / 失败数 / 总耗时 / 头行文案。
+ *
+ * @param {Array<{failed?: boolean, durationMs?: unknown}>} [items]
+ * @returns {{count: number, failed: number, totalMs: number, countText: string, sumText: string}}
+ */
+export function toolTimelineSummary(items) {
+  const list = items || [];
+  const failed = list.filter((s) => s.failed).length;
+  const totalMs = list.reduce((a, s) => a + (Number(s.durationMs) || 0), 0);
+  const detail = list.length + ' 步' + (failed ? ' · ' + failed + ' 个失败' : '');
+  return {
+    count: list.length,
+    failed,
+    totalMs,
+    countText: detail,
+    sumText: totalMs ? fmtToolDur(totalMs) : '',
+  };
+}
+
+/**
+ * 默认可见步：前 3 步 + 所有失败步（失败步免展开可见）。
+ *
+ * @param {Array<{failed?: boolean}>} [items]
+ * @param {boolean} [expanded]
+ * @returns {number[]}
+ */
+export function toolTimelineVisibility(items, expanded) {
+  const list = items || [];
+  if (expanded) return list.map((_, i) => i);
+  const keep = new Set();
+  for (let i = 0; i < Math.min(TOOL_TL_DEFAULT_VISIBLE, list.length); i++) keep.add(i);
+  list.forEach((s, i) => { if (s.failed) keep.add(i); });
+  return [...keep].sort((a, b) => a - b);
+}
+
+/**
+ * 轨迹耗时文案：<60s 用秒；<60m 用 m/s；否则 h/m。
+ *
+ * @param {unknown} ms
+ * @returns {string}
+ */
+export function fmtTraceDur(ms) {
+  const total = Math.max(0, Math.round((Number(ms) || 0) / 1000));
+  if (total < 60) return total + 's';
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  if (m < 60) return m + 'm' + (s ? s + 's' : '');
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return h + 'h' + (rm ? rm + 'm' : '');
+}
+
+/**
+ * 子代理一行的视图：名称 · 轮次 · 工具次数 · 最后进展 · 状态（缺失字段如实显示 —，不编造）。
+ *
+ * @param {any} sub 子代理快照
+ * @returns {Record<string, any>}
+ */
+export function subagentRowView(sub) {
+  const s = sub || {};
+  const toolCalls = s.toolCalls == null || !Number.isFinite(Number(s.toolCalls)) ? null : Math.max(0, Math.round(Number(s.toolCalls)));
+  const modelRounds = s.modelRounds == null || !Number.isFinite(Number(s.modelRounds)) ? null : Math.max(0, Math.round(Number(s.modelRounds)));
+  const ago = s.lastProgressAgoMs == null || !Number.isFinite(Number(s.lastProgressAgoMs)) ? null : Math.max(0, Math.round(Number(s.lastProgressAgoMs)));
+  const running = Boolean(s.running);
+  const failed = !running && (s.status === 'failed' || Boolean(s.result && s.result.ok === false));
+  const status = running ? 'running' : failed ? 'failed' : 'done';
+  const round = Math.max(0, Math.round(Number(s.round) || 0));
+  return {
+    key: 'sub:' + String(s.seq == null ? '?' : s.seq),
+    seq: s.seq,
+    round,
+    roundText: round ? '第 ' + round + ' 轮' : '—',
+    name: String(s.label || s.description || s.question || '子代理').slice(0, 80),
+    question: String(s.question || ''),
+    toolCalls,
+    toolText: toolCalls == null ? '工具次数 —' : toolCalls + ' 次工具',
+    modelRounds,
+    roundsText: modelRounds == null ? '自身轮次 —' : modelRounds + ' 轮',
+    progress: ago == null ? '最后进展 —' : '最后进展 ' + (ago < 1000 ? '<1s' : Math.round(ago / 1000) + 's') + ' 前',
+    status,
+    statusText: running ? '运行中' : failed ? '失败' : '完成',
+    statusCls: running ? 'run' : failed ? 'bad' : 'ok',
+    running,
+    durationMs: s.durationMs == null ? null : Number(s.durationMs),
+    result: s.result,
+  };
+}
+
+/**
+ * 一轮的完整视图（工具步 + 子代理 + 摘要文案）；对话流与右栏消费同一个对象。
+ *
+ * @param {{now?: unknown, round?: unknown, startedAt?: unknown, endedAt?: unknown,
+ *          tools?: any[], subs?: any[]}} [round]
+ * @returns {{round: number, tools: any[], subs: any[], toolCount: number, subCount: number,
+ *           failed: number, durationMs: number, durationText: string, summary: string}}
+ */
+export function traceRoundView(round) {
+  const r = round || {};
+  const now = Number(r.now) || Date.now();
+  const tools = (r.tools || []).map((t) => toolStepView(t, t.done));
+  const subs = (r.subs || []).map(subagentRowView);
+  const started = Number(r.startedAt) || 0;
+  const ended = r.endedAt != null ? Number(r.endedAt) : now;
+  const durationMs = started ? Math.max(0, ended - started) : 0;
+  const durationText = started ? fmtTraceDur(durationMs) : '';
+  const parts = ['本轮 ' + tools.length + ' 次工具调用'];
+  if (subs.length) parts.push(subs.length + ' 个子代理');
+  if (durationText) parts.push(durationText);
+  return {
+    round: Math.max(0, Math.round(Number(r.round) || 0)),
+    tools,
+    subs,
+    toolCount: tools.length,
+    subCount: subs.length,
+    failed: tools.filter((t) => t.failed).length,
+    durationMs,
+    durationText,
+    summary: parts.join(' · '),
+  };
+}