@yxzpro/agent-acta 2.14.4

package/parsers/zcode.mjs

@@ -0,0 +1,356 @@
+// ---------------- zcode 解析器（~/.zcode/cli/db/db.sqlite，WAL 模式的 SQLite 库） ----------------
+// 从 agent-acta-server.mjs 拆出（纯搬家，逻辑零改动）。导出 scanZcode / zcodeScanErr / zcodeIdBase。
+//
+// 表结构与关联（本机实测，见 LOGFORMATS.md 的 zcode 一节）：
+//   session(id, parent_id, directory, title, task_type, time_created/updated/archived)
+//   message(id, session_id, sequence, time_created, data JSON)   —— data.role = user/assistant，
+//         data.time.{created,completed}、data.tokens、data.error、data.modelID/providerID
+//   part(id, message_id, session_id, sequence, data JSON)        —— data.type = text / reasoning /
+//         tool / step-start / step-finish / timeline / …；tool part 的出入参在 data.state.{input,output}
+//   session_input(payload JSON)                                   —— 用户输入的兜底：payload.text
+//         或 payload.conversationInputIntent.text，promoted_message_id 关联到 user message
+//   tool_usage / model_usage / turn_usage                         —— 逐次工具/模型/轮的真实指标
+//         （起止时间、duration_ms、token、status、error），靠 turn_id / tool_call_id / user_message_id
+//         关联回 message 与 part
+//
+// 切轮：一个 role=user 的 message 开一轮（与 claude/cursor 同口径），turn_usage.user_message_id
+// 正好也是这个键，两边天然对齐。turn_usage 缺行（老版本/中断）时回退到「按消息分组 + model_usage 求和」。
+// 首个 user 之前的 assistant 消息（实测存在：会话头一条 assistant）挂进一个「序章」轮，不丢。
+//
+// 增量：SQLite 没有字节偏移语义，且 WAL 模式下新数据先落在 db.sqlite-wal（库文件本身的 mtime 不动），
+// 所以签名 = db 文件与 wal 文件的 {mtime,size} 四元组，变了才整份重解析 —— 与 gemini 同一路数。
+// 库很小（本机 <1MB），整份重读比维护水位线可靠；zcode 因此不进 OFF_KINDS，也就无需 PARSER_REV。
+//
+// 只读纪律：DatabaseSync 一律 {readOnly:true} 打开，查完即关；任何一步失败（库被锁、损坏、表缺失）
+// 都保留上一轮的解析结果并记下原因（诊断页可见），绝不对库做任何写操作。
+import fs from 'node:fs';
+import { files, entries, srcs, removedIds, sorted, addEntry, toolNameCounts, modelName, toText, sqliteMod } from './shared.mjs';
+
+// node:sqlite 加载器在 shared.mjs（cursor / zcode / discovery 的嗅探共用同一份实例）。
+// zcode 这里只需要「拿不拿得到模块」：拿到就能扫，拿不到在 zcodeScanErr 里说明原因。
+
+// 每个 agent 最近一次 zcode 扫描的失败原因（诊断页「已接入 · 0 条」时展示；成功则清除）
+export const zcodeScanErr = new Map();
+
+// part.data 的安全解析：损坏 JSON 不能拖垮整个会话（需求「兼容和容错」），坏了就以原文进 others
+function zcodeJson(raw) { try { return JSON.parse(raw); } catch { return null; } }
+
+function zcodeTurn(sid, key, ts) {
+  return {
+    sid, key, time: ts || 0, lastTs: ts || 0, endTs: 0,
+    tin: 0, tout: 0, tcache: 0, ctxUsed: 0,
+    models: [], callList: [], tools: [], byCall: new Map(),
+    user: '', texts: [], events: [], others: [],
+    err: false, errMsg: '', steps: 0,
+  };
+}
+
+// 非文本 part 的处理：工具进 tools[]，有信息量的状态事件压缩后进 others[]，纯占位的不留。
+// 未知类型**不静默丢弃**（需求）：整个 JSON 截到 2000 字进 others，详情面板「其他事件」里可看。
+function zcodePart(turn, msg, part) {
+  const d = zcodeJson(part.data);
+  const t = part.time_created || msg?.time_created || 0;
+  if (!d) {
+    turn.others.push({ type: '(损坏的 JSON)', t, json: String(part.data || '').slice(0, 2000) });
+    return;
+  }
+  const type = typeof d.type === 'string' ? d.type : '(无 type)';
+  if (type === 'text') {
+    const s = toText(d.text);
+    if (!s) return;
+    if (msg?.role === 'user') { if (!turn.user) turn.user = s; }
+    else if (msg?.role === 'assistant') turn.texts.push(s);
+    else {
+      // system 或更晚出现的角色：不进「AI 输出」冒充助手正文，留结构化锚点 + sys 事件
+      turn.others.push({ type: (msg?.role || '未知角色') + ' 文本', t, json: JSON.stringify(s.slice(0, 2000)) });
+      turn.events.push({ k: 'sys', t: t || turn.time, len: s.length });
+    }
+    return;
+  }
+  if (type === 'tool') {
+    const st = d.state || {};
+    const tool = {
+      name: d.tool || '?', tid: d.callID || null, ct: t,
+      input: st.input != null ? st.input : '', output: st.output != null ? st.output : '',
+      error: st.status && st.status !== 'completed' ? String(st.error || st.status) : null,
+      dur: 0,
+    };
+    turn.tools.push(tool);
+    if (tool.tid) turn.byCall.set(tool.tid, tool);
+    return;
+  }
+  if (type === 'step-start') { turn.steps++; turn.events.push({ k: 'step', t: t || turn.time, n: turn.steps, ph: 'start' }); return; }
+  if (type === 'step-finish') {
+    // step-finish 带这一步的 token 账：model_usage 缺行时它就是调用级的兜底来源
+    const tk = d.tokens || {};
+    turn.others.push({ type, t, json: JSON.stringify({ reason: d.reason, tokens: tk }).slice(0, 2000) });
+    turn._stepTokens = tk; // 调用级 token 兜底（见 scanZcode 的 calls 回填）
+    return;
+  }
+  if (type === 'reasoning') {
+    // 推理正文可能是整段思考，且 metadata 里常带签名junk —— 只留长度锚点（同 dsh 对 sys 的处理）
+    turn.others.push({ type, t, json: JSON.stringify({ len: toText(d.text).length }) });
+    return;
+  }
+  // timeline / 未知类型：保留结构化 JSON（截断），在详情「其他事件」里可查
+  turn.others.push({ type, t, json: JSON.stringify(d).slice(0, 2000) });
+}
+
+export function scanZcode(agent, dbPath) {
+  const key = dbPath;
+  let dst, wst = null;
+  try { dst = fs.statSync(dbPath); } catch { zcodeScanErr.set(agent, '数据库不存在：' + dbPath); return; }
+  try { wst = fs.statSync(dbPath + '-wal'); } catch {}  // WAL 可能已被 checkpoint 掉，没有是正常的
+  const sig = dst.mtimeMs + '|' + dst.size + '|' + (wst ? wst.mtimeMs + '|' + wst.size : '-');
+  const prev = files.get(key);
+  if (prev && prev.data.sig === sig) {
+    // 库没变就不重解析 —— 但条目可能被 LRU 淘汰过（同 dsh 的处理：按最后一轮补回）
+    const last = prev.data?.turns?.[prev.data.turns.length - 1];
+    if (last && !entries.has(zcodeIdBase(key) + last.sid.replace(/#/g, '~') + '#' + last.key)) emitZcodeTurns(agent, key, prev.data, null);
+    return;
+  }
+
+  const mod = sqliteMod();
+  if (!mod) { zcodeScanErr.set(agent, '当前 Node 没有 node:sqlite（需要 22.5+）'); return; }
+  let db = null;
+  try {
+    db = new mod.DatabaseSync(dbPath, { readOnly: true });
+    // 每张表单独容错：库在、但某张表缺失/损坏时，其余表照常解析，不让整库变白
+    const qAll = (sql) => { try { return db.prepare(sql).all(); } catch { return null; } };
+    const sessions = qAll('SELECT id, parent_id, directory, path, title, task_type, time_created, time_updated, time_archived FROM session ORDER BY time_created');
+    if (!sessions) throw new Error('读不到 session 表（schema 不兼容或被锁定）');
+    const messages = qAll('SELECT id, session_id, sequence, time_created, time_updated, data FROM message ORDER BY session_id, sequence') || [];
+    const parts = qAll('SELECT id, message_id, session_id, sequence, time_created, data FROM part ORDER BY session_id, sequence') || [];
+    const inputs = qAll('SELECT id, session_id, kind, status, payload, promoted_message_id, time_created FROM session_input') || [];
+    const toolUs = qAll('SELECT session_id, turn_id, tool_call_id, tool_name, status, started_at, completed_at, duration_ms, exit_code, error_message, stdout_bytes, stderr_bytes FROM tool_usage') || [];
+    const modelUs = qAll('SELECT session_id, turn_id, parent_user_message_id, assistant_message_id, provider_id, model_id, status, started_at, first_token_at, completed_at, duration_ms, time_to_first_token_ms, finish_reason, tool_call_count, input_tokens, output_tokens, reasoning_tokens, cache_creation_input_tokens, cache_read_input_tokens, error_type, error_message FROM model_usage') || [];
+    const turnUs = qAll('SELECT session_id, turn_id, user_message_id, status, started_at, completed_at, duration_ms, time_to_first_token_ms, input_tokens, output_tokens, reasoning_tokens, cache_creation_input_tokens, cache_read_input_tokens, tool_call_count, error_type, error_code FROM turn_usage') || [];
+
+    const sessById = new Map(sessions.map(s => [s.id, s]));
+    // sequence 排序的防御：真库的 sequence 是 INTEGER，但万一哪个版本写成别的（或错列），
+    // 退回 time_created 也得保证「同一会话内按真实先后」——切轮正确性全靠这个顺序
+    const seqOf = r => (typeof r.sequence === 'number' ? r.sequence : (r.time_created || 0));
+    messages.sort((a, b) => (a.session_id < b.session_id ? -1 : a.session_id > b.session_id ? 1 : seqOf(a) - seqOf(b)));
+    parts.sort((a, b) => (a.session_id < b.session_id ? -1 : a.session_id > b.session_id ? 1 : seqOf(a) - seqOf(b)));
+    // ---- 消息与其 part 归组 ----
+    const msgById = new Map();
+    const partsByMsg = new Map();
+    for (const p of parts) {
+      if (!partsByMsg.has(p.message_id)) partsByMsg.set(p.message_id, []);
+      partsByMsg.get(p.message_id).push(p);
+    }
+    const inputByMsg = new Map();
+    for (const si of inputs) {
+      const d = zcodeJson(si.payload);
+      const text = toText(d?.text ?? d?.conversationInputIntent?.text);
+      if (text && si.promoted_message_id && !inputByMsg.has(si.promoted_message_id)) inputByMsg.set(si.promoted_message_id, text);
+    }
+
+    // ---- 按会话切轮：role=user 开一轮，其后的 assistant 归这一轮 ----
+    const turns = [];
+    const turnByMsg = new Map();   // 任意 message id（user 或 assistant）→ 它所属的轮
+    const turnByUserMsg = new Map();
+    for (const s of sessions) {
+      const sMsgs = messages.filter(m => m.session_id === s.id);
+      // 会话级信息拍平进每一轮：emit / 详情不再回查 session 表
+      const proj = s.directory || s.path || '(未知项目)';
+      const title = (s.title || '').trim();
+      const name = (s.parent_id ? '⤷ ' : '') + title;   // parent_id 非空 = 子 agent 会话
+      let cur = null;
+      for (const m of sMsgs) {
+        const d = zcodeJson(m.data) || {};
+        const role = typeof d.role === 'string' ? d.role : '';
+        const ts = typeof d.time?.created === 'number' ? d.time.created : (m.time_created || 0);
+        const msg = { id: m.id, role, ts, d };
+        msgById.set(m.id, msg);
+        if (role === 'user' || !cur) {
+          // 首个 user 之前的消息（会话头的 assistant 序章）也开一轮，key 用消息 id 兜底
+          cur = zcodeTurn(s.id, role === 'user' ? m.id : ('pre#' + m.id), ts);
+          cur.ord = turns.length;
+          cur.project = proj;
+          cur.name = name || null;
+          // I16 子 agent 拓扑：`session.parent_id` 非空 = 这一坨轮次属于**子 agent 会话**。
+          // 源头给的显式外键（子会话 id 指向父会话 id），不需要按时间区间猜父子。
+          // 之前只用它给标题加了个「⤷ 」前缀，父子关系本身没往条目上落，聚合层也就无从成树。
+          cur.parentId = s.parent_id || null;
+          turns.push(cur);
+          if (role === 'user') turnByUserMsg.set(m.id, cur);
+          // 时间线锚点：这一轮的用户输入时刻（dsh 的 user/message 事件同义）
+          if (role === 'user') cur.events.push({ k: 'user', t: ts || 0 });
+        }
+        turnByMsg.set(m.id, cur);
+        if (ts) { if (!cur.time || ts < cur.time) cur.time = ts; cur.lastTs = Math.max(cur.lastTs, ts); }
+        if (d.time?.completed) cur.endTs = Math.max(cur.endTs, d.time.completed);
+        // message 级错误（模型调用失败整条挂在 assistant message 上）
+        if (d.error && !cur.errMsg) cur.errMsg = toText(d.error?.data?.message || d.error?.message || d.error?.name || '');
+        // 该消息的 parts 归进当前轮
+        for (const p of partsByMsg.get(m.id) || []) zcodePart(cur, msg, p);
+        // 用户输入兜底：user message 没有 text part 时，从 session_input 补
+        if (role === 'user' && !cur.user && inputByMsg.has(m.id)) cur.user = inputByMsg.get(m.id);
+      }
+    }
+
+    // ---- 用量表回填（turn_id / message id 三条路都试，配不上的按时间落） ----
+    const turnByTurnId = new Map();
+    for (const tu of turnUs) {
+      const t = turnByUserMsg.get(tu.user_message_id);
+      if (t && tu.turn_id) turnByTurnId.set(tu.session_id + '|' + tu.turn_id, t);
+    }
+    const findTurn = (sid, turnId, msgIds, ts) => {
+      if (turnId && turnByTurnId.has(sid + '|' + turnId)) return turnByTurnId.get(sid + '|' + turnId);
+      for (const mid of msgIds || []) if (mid && turnByMsg.has(mid)) return turnByMsg.get(mid);
+      // 时间兜底：落到「包含这个时刻」的轮（轮与轮之间按 user 消息切，时间必然单调）
+      if (ts) {
+        let best = null;
+        for (const t of turns) {
+          if (t.sid !== sid || !t.time || ts < t.time) continue;
+          if (!best || t.time > best.time) best = t;
+        }
+        if (best) return best;
+      }
+      return null;
+    };
+
+    for (const tu of turnUs) {
+      const t = findTurn(tu.session_id, null, [tu.user_message_id], tu.started_at);
+      if (!t) continue;
+      if (tu.turn_id) turnByTurnId.set(tu.session_id + '|' + tu.turn_id, t);
+      // 轮级账以 turn_usage 为准（它是源头自己算的聚合）；字段为 null 时不覆盖已有值
+      t._tu = tu;
+      if (tu.started_at) t.time = t.time ? Math.min(t.time, tu.started_at) : tu.started_at;
+      if (tu.completed_at) { t.endTs = Math.max(t.endTs, tu.completed_at); t.lastTs = Math.max(t.lastTs, tu.completed_at); }
+      if (tu.status && tu.status !== 'completed') { t.err = true; if (!t.errMsg && tu.error_type) t.errMsg = tu.error_type; }
+    }
+    for (const mu of modelUs) {
+      const t = findTurn(mu.session_id, mu.turn_id, [mu.parent_user_message_id, mu.assistant_message_id], mu.started_at);
+      if (!t) continue;
+      const mdl = modelName(mu.model_id);
+      const cache = (mu.cache_read_input_tokens || 0) + (mu.cache_creation_input_tokens || 0);
+      const failed = mu.status && mu.status !== 'completed';
+      const call = {
+        model: mdl || '(未知模型)',
+        tin: mu.input_tokens || 0, tout: (mu.output_tokens || 0) + (mu.reasoning_tokens || 0), tcache: cache,
+        dur: mu.duration_ms || (mu.started_at && mu.completed_at ? Math.max(0, mu.completed_at - mu.started_at) : 0),
+      };
+      if (failed) call.error = mu.error_message || mu.error_type || String(mu.status);
+      // 这次调用自己产出的正文：assistant_message_id 直接指到那条 message，它的 text parts 就是
+      const amsg = mu.assistant_message_id ? msgById.get(mu.assistant_message_id) : null;
+      if (amsg) {
+        const pts = (partsByMsg.get(mu.assistant_message_id) || [])
+          .map(p => zcodeJson(p.data)).filter(d => d && d.type === 'text').map(d => toText(d.text)).filter(Boolean);
+        if (pts.length) call.text = pts.join('\n');
+      }
+      t.callList.push(call);
+      if (mdl && !t.models.includes(mdl)) t.models.push(mdl);
+      const ctxNow = (mu.input_tokens || 0) + cache;
+      if (ctxNow > 0) t.ctxUsed = ctxNow;   // 轮内最后一次胜出（与 claude/kimi 同口径，非累加）
+      if (mu.started_at) { if (!t.time || mu.started_at < t.time) t.time = mu.started_at; }
+      if (mu.completed_at) { t.lastTs = Math.max(t.lastTs, mu.completed_at); t.endTs = Math.max(t.endTs, mu.completed_at); }
+      // 逐事件时间线（与 dsh 同一 schema）：ttft = 首 token − 发起，dur = 流式解码段
+      t.events.push({
+        k: 'llm', t: mu.started_at || t.time,
+        ttft: mu.first_token_at && mu.started_at ? Math.max(0, mu.first_token_at - mu.started_at) : (mu.time_to_first_token_ms || 0),
+        dur: mu.first_token_at && mu.completed_at ? Math.max(0, mu.completed_at - mu.first_token_at) : call.dur,
+        model: mdl || '', tin: call.tin, tout: call.tout, tcache: cache,
+        err: !!failed, blocks: call.text ? ['text'] : [],
+      });
+      if (failed && !t.errMsg && call.error) t.errMsg = toText(call.error);
+    }
+    for (const tu of toolUs) {
+      const t = findTurn(tu.session_id, tu.turn_id, null, tu.started_at);
+      if (!t) continue;
+      // 指标挂回 part 层面的工具（tool_call_id ↔ callID）；配不上 part 的以「纯指标」工具补一条
+      let tool = tu.tool_call_id ? t.byCall.get(tu.tool_call_id) : null;
+      if (!tool) {
+        tool = { name: tu.tool_name || '?', tid: tu.tool_call_id || null, ct: tu.started_at || 0, input: '', output: '', error: null, dur: 0 };
+        t.tools.push(tool);
+        if (tool.tid) t.byCall.set(tool.tid, tool);
+      }
+      const failed = tu.status && tu.status !== 'completed';
+      tool.dur = tu.duration_ms || (tu.started_at && tu.completed_at ? Math.max(0, tu.completed_at - tu.started_at) : 0);
+      if (failed && !tool.error) tool.error = toText(tu.error_message || tu.error_type || (tu.exit_code ? 'exit ' + tu.exit_code : tu.status));
+      const i = t.tools.indexOf(tool);
+      t.events.push({ k: 'call', t: tu.started_at || t.time, name: tool.name, tid: tool.tid, i });
+      t.events.push({ k: 'result', t: tu.completed_at || (tu.started_at || t.time), tid: tool.tid, i, dur: tool.dur, error: !!failed });
+      if (failed) t.err = true;
+    }
+
+    // ---- 收尾：轮级字段定稿 ----
+    for (const t of turns) {
+      const tu = t._tu;
+      if (tu) {
+        t.tin = tu.input_tokens || 0;
+        t.tout = (tu.output_tokens || 0) + (tu.reasoning_tokens || 0);
+        t.tcache = (tu.cache_read_input_tokens || 0) + (tu.cache_creation_input_tokens || 0);
+      } else {
+        // turn_usage 缺行：回退到逐次调用求和
+        for (const c of t.callList) { t.tin += c.tin; t.tout += c.tout; t.tcache += c.tcache; }
+      }
+      if (!t.callList.length && t._stepTokens) {
+        // 连 model_usage 也没有：step-finish 的 token 账兜底一次调用（宁可少算不造假，标 1 次）
+        const tk = t._stepTokens;
+        t.callList.push({ model: t.models[0] || '(未知模型)', tin: tk.input || 0, tout: (tk.output || 0) + (tk.reasoning || 0), tcache: (tk.cache?.read || 0) + (tk.cache?.write || 0), dur: 0 });
+      }
+      // 状态：turn_usage 说错了才算错；没有 turn_usage 时「有调用且全败」才算错（与 dsh 同思路）
+      if (!t.err && !tu && t.callList.length && t.callList.every(c => c.error)) t.err = true;
+      if (t.err && !t.errMsg) t.errMsg = (t.callList.find(c => c.error) || {}).error || '';
+      t.user = t.user.slice(0, 3000);
+      const body = t.texts.join('\n\n---\n\n');
+      t.preview = (t.user || body || t.errMsg || '').replace(/\s+/g, ' ').slice(0, 300);
+      // 事件按真实时刻排序；end 事件放在最后（turn_usage 的 completed_at 或最后一条消息时刻）
+      t.events.push({ k: 'end', t: t.endTs || t.lastTs || t.time, reason: t.err ? 'error' : 'completed' });
+      t.events.sort((a, b) => (a.t - b.t) || 0);
+      delete t._tu; delete t._stepTokens;
+    }
+
+    // 全空的轮不灌条目：真库里存在「序章 assistant 消息」（首个 user 之前、无 part 无调用）与
+    // 打开了但没说话的轮 —— 它们会以 preview 空、calls 0、tools 0 的卡片出现在列表里，纯噪音。
+    // 「只有推理/步态/时间线标记」也算空（实测：每个会话的序章 assistant 消息只挂一个
+    // timeline=model_change part，留着就是一张全空卡片）；但带未知类型 part 的轮必须留着
+    // （未知内容不能静默丢弃）。
+    const KEEP_NOISY = new Set(['reasoning', 'step-finish', 'timeline']);
+    const liveTurns = turns.filter(t =>
+      t.user || t.texts.length || t.callList.length || t.tools.length || t.errMsg ||
+      t.others.some(o => !KEEP_NOISY.has(o.type)));
+    const data = { sig, turns: liveTurns, rev: (prev?.data?.rev || 0) + 1 };
+    files.set(key, { agent, kind: 'zcode', m: dst.mtimeMs, s: dst.size, off: 0, data });
+    zcodeScanErr.delete(agent);
+    emitZcodeTurns(agent, key, data, prev?.data);
+  } catch (e) {
+    // 库被锁/损坏/schema 变了：保留旧数据，原因写到诊断页，绝不让一个库拖垮整轮扫描
+    console.error('[zcode]', e.message);
+    zcodeScanErr.set(agent, e.message);
+  } finally {
+    try { db && db.close(); } catch {}
+  }
+}
+
+export function zcodeIdBase(key) { return 'z#' + key.replace(/[\\/:]/g, '~') + '#'; }
+
+function emitZcodeTurns(agent, key, data, prevData) {
+  const idBase = zcodeIdBase(key);
+  const ids = new Set();
+  data.turns.forEach((t, i) => {
+    const id = idBase + t.sid.replace(/#/g, '~') + '#' + t.key;
+    ids.add(id);
+    addEntry(id, {
+      agent, project: t.project, session: t.sid,
+      time: t.time, dur: Math.max(0, (t.endTs || t.lastTs) - t.time), status: t.err ? 'error' : 'ok',
+      tin: t.tin, tout: t.tout, tcache: t.tcache, total: t.tin + t.tout + t.tcache,
+      ctx: 0, ctxUsed: t.ctxUsed || null,   // zcode 源头没有窗口容量字段：只显示占用，不画进度条
+      rounds: t.callList.length, tools: t.tools.length, calls: t.callList.length,
+      models: t.models, preview: t.preview, name: t.name || null,
+      // I16：子会话谱系（parent_id → 父会话 id；根会话不落 depth 这个键）。源头显式外键，直接透传。
+      parent: t.parentId || undefined, depth: t.parentId ? 1 : undefined,
+      finished: !!t.finished || i < data.turns.length - 1, aborted: !!t.aborted,
+      toolNames: toolNameCounts(t.tools),
+    }, { file: key, turn: i, kind: 'zcode' });
+  });
+  // 库重写/会话被删时旧条目要撤掉（同 dsh / gemini）
+  for (const old of prevData?.ids || []) {
+    if (ids.has(old)) continue;
+    entries.delete(old); srcs.delete(old); removedIds.push(old);
+  }
+  data.ids = [...ids];
+  sorted.cache = null;
+}

package/plugin/client.js

@@ -0,0 +1,51 @@
+// AgentActa 的 DSH 客户端垫片（I11 批 3）。手写纯 ESM-free 的 .js：宿主把插件 client 原样拼成普通 <script>，
+// react 由浏览器的模块表提供，所以这里没有 JSX、也没有构建步骤（实测见 DSH-PLUGIN-PLAN.md §8.4/§8.6）。
+// __ModuleLoader__.load 的 id 必须等于包名，且同一个 id 只能注册一次（重复注册宿主会抛）。
+window.__ModuleLoader__.load({
+  id: '@yxzpro/agent-acta',
+  factory(require) {
+    const React = require('react');
+    const h = React.createElement;
+
+    const PANEL_ID = 'agent-acta';
+    // 面板入口：由服务端**同源递出**面板 HTML（宿主前端在 dsh-app://app，只代理 /api/*，
+    // 而 iframe 302 到 http 口是跨源、实测被拦成空白 —— 见 DSH-PLUGIN-PLAN.md §8.6 第七轮）。
+    // 页面里的 /page/、/vendor/ 引用由服务端递送时翻译成 /api/agent-acta/asset?p=…，浏览器侧一行都不用改。
+    const PAGE_URL = '/api/agent-acta/entry';
+
+    // 没有 icon 这个注册参数 —— 注册的组件本身就是侧栏那颗图标，宿主按 { size, active } 喂它。
+    function PanelIcon({ size, active }) {
+      const s = size || 18;
+      return h('svg', {
+        width: s, height: s, viewBox: '0 0 24 24', 'aria-hidden': true,
+        style: { display: 'block', opacity: active ? 1 : 0.6 },
+      },
+        h('circle', { cx: 12, cy: 12, r: 9, fill: 'none', stroke: 'currentColor', strokeWidth: 1.6 }),
+        h('path', { d: 'M7.5 13.5h2.2l1.4-4 1.9 6.4 1.4-2.4h2.1', fill: 'none', stroke: active ? 'currentColor' : 'currentColor', strokeWidth: 1.6, 'stroke-linejoin': 'round', 'stroke-linecap': 'round' }));
+    }
+
+    function Panel() {
+      return h('iframe', {
+        // 面板 HTML 必须从 /api 递出：宿主前端在 dsh-app://app 下只把 /api/* 代理到 webServer，
+        // 走 /page/ 之类路径会被当成宿主自己的静态资源（§8.6 实测）。同源之后 SSE 也照用。
+        title: 'AgentActa',
+        src: PAGE_URL,
+        style: { width: '100%', height: '100%', border: 0, display: 'block' },
+      });
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        // 任一步失败都只降级成 console.error：slot API 变了不该把宿主一起拖崩。
+        try {
+          ctx.slots.inject('sidebar.panellist', () => ctx.slots.register(
+            { name: 'sidebar.panellist', id: PANEL_ID, order: 900, label: 'AgentActa' }, PanelIcon));
+        } catch (e) { console.error('[agent-acta] 侧栏入口注册失败：', e && e.message); }
+        try {
+          ctx.slots.inject('main', () => ctx.slots.register({ name: 'main', key: PANEL_ID }, Panel));
+        } catch (e) { console.error('[agent-acta] 面板注册失败：', e && e.message); }
+      },
+    };
+  },
+});

package/plugin/cordis.patch.yml

@@ -0,0 +1,5 @@
+# AgentActa 插件的 bundle patch（I11 批 4 的另一半）：宿主按这份把自己插进 bundle 层。
+# patch 行的 id 是短名、name 是包名，两者不是一回事 —— 浏览器模块 id 用的是包名（见 plugin/client.js 的 load({id})）。
+- insert:
+    - id: agent-acta-panel
+      name: '@yxzpro/agent-acta'

package/plugin/plugin.mjs

@@ -0,0 +1,220 @@
+// AgentActa 的 DSH 插件壳（I11 批 2）。
+//
+// 形状是「URL 转接 + 逐条注册」，不是第二套服务：所有 handler 一律转给 core 的 handle(req,res)，
+// 静态文件也走 core 原有的 routePageFile / routeVendor（那套 path.resolve + 前缀校验防逃逸只有一份）。
+// 装配层的生命周期（扫描 / 落索引 / SSE 心跳 / 归档轮）由 start({mode:'hosted'}) 开，
+// 但**不监听端口、不写 pid、不挂空闲自停、不退出宿主进程** —— 见 core/service.mjs 的 MODE 三态。
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  ROUTES, PAGE_DIR, ROOT, PORT, VERSION, BUILD,
+  handle, start, stop,
+} from '../core/service.mjs';
+
+// 插件声明名 = 包名（cordis 按这个键装配；09-30 因为 npm 上 `agentacta` 已被别人的同名项目占了，
+// 包名换成作用域名 `@yxzpro/agent-acta` —— 产品名、CLI 命令 `agentacta`、面板 key 与 URL 都不跟着改）。
+export const name = '@yxzpro/agent-acta';
+export const inject = ['webServer'];
+
+// 宿主里不该存在的四条：退进程 / 起 Electron 壳 / 弹 UAC 抓密钥 / 悬浮球壳。
+// 它们在 core 的路由表里照旧存在（CLI 要用），只是不给宿主注册。
+// 导出是给守卫对的：test/cli-behavior-guard.mjs 断言「插件实际注册的集合 ≡ ROUTES − DENY + EXTRA」。
+// 不导出的话，「插件悄悄少挂一条 API」这条红线只守住了 core 那半边。
+//
+// '/' 也必须让出去：宿主 webServer 的兜底位（dsh-host-frontend-static）在上面挂的是
+// authorizeIndex —— 壳启动时拿 GET /?token=… 换 303 + set-cookie 才算认证过。
+// exact 路由优先于兜底位，插件一旦把 '/' 挂成 exact，这一问就由面板 HTML 200 应答（无 cookie），
+// 壳直接判「Desktop Host authentication failed」⇒ DSH 每次开机都起不来（2026-09-30 实测）。
+export const HOSTED_DENY = ['/', '/api/shutdown', '/api/client', '/api/trae/capture-key', '/widget'];
+// 面板的唯一入口路径：两支（A 说明页 / hosted 递面板 HTML）都挂在这一条上，
+// client.js 的 iframe src 就是它 —— 两支换路不换路径，才不会出现「图标点了但 404」。
+export const ENTRY_PATH = '/api/agent-acta/entry';
+// 静态资产的中转路径：`?p=page/x.js`。宿主前端在 `dsh-app://app` 下**只把 /api/* 代理到 webServer**，
+// 所以面板里那些 `/page/…`、`/vendor/…` 引用在浏览器侧一律 404（curl 打宿主 http 口却是 200，别被骗）。
+// 只能把它们收进 /api 命名空间，见下面的 rewriteRefs。
+export const ASSET_PATH = '/api/agent-acta/asset';
+export const HOSTED_EXTRA = [ENTRY_PATH, ASSET_PATH];
+
+// 双载体探测在测试里要能换掉（守卫不能依赖「用户有没有开着 14570」这种环境状态）。
+let cliProbe = probeCliService;
+export function setCliProbe(fn) { cliProbe = typeof fn === 'function' ? fn : probeCliService; }
+
+// 暂定 A（PLAN §8.8）：老 CLI 服务在跑时**不另起一份扫描器**，面板如实说明并给出退出办法。
+// 选 B（代理转发）时换掉这一支即可 —— 所以它是个开关，不是一处重构。
+function probeCliService() {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: '127.0.0.1', port: PORT, timeout: 600 });
+    s.on('connect', () => {
+      s.write('GET /api/version HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n');
+      let buf = '';
+      s.on('data', (d) => { buf += d; });
+      s.on('end', () => {
+        const m = buf.match(/\{[\s\S]*\}/);
+        try { const j = m ? JSON.parse(m[0]) : null; resolve(j && j.ok ? j : null); } catch { resolve(null); }
+      });
+      s.on('error', () => resolve(null));
+    });
+    s.on('timeout', () => { s.destroy(); resolve(null); });
+    s.on('error', () => resolve(null));
+  });
+}
+
+// 静态资源白名单：启动时递归列目录，而不是抄一份常量表 ——
+// 抄来的清单会随页面加组件/图标而过期（vendor/svg 下 54 个图标正是先前漏掉的那批）。
+function staticFiles() {
+  const out = [];
+  for (const dir of [PAGE_DIR, path.join(ROOT, 'vendor')]) {
+    if (!fs.existsSync(dir)) continue;
+    const walk = (d, pre) => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (e.name.startsWith('.')) continue;
+        const abs = path.join(d, e.name);
+        if (e.isDirectory()) walk(abs, pre + e.name + '/');
+        else out.push(pre + e.name);
+      }
+    };
+    const base = path.basename(dir);
+    walk(dir, '/' + base + '/');
+  }
+  return out;
+}
+
+// 插件到底该往宿主注册哪些路由 —— **纯函数**，不 start、不起扫描、不碰数据目录。
+// 守卫要的就是这一份：拿 apply() 去数注册条式意味着在测试里真起一个 hosted 服务，
+// 那会在用户的机器上多出第二个索引写者（2026-09-29 我这么试过一次，2 秒，事后无法归因）。
+export function hostedRouteSpecs() {
+  const deny = new Set(HOSTED_DENY);
+  const specs = ROUTES.filter(r => !deny.has(r.path)).map(r => ({ kind: 'exact', path: r.path }));
+  for (const p of staticFiles()) specs.push({ kind: 'exact', path: p });
+  for (const p of HOSTED_EXTRA) specs.push({ kind: 'exact', path: p });
+  return specs;
+}
+
+// 面板引用改写：只认「紧跟引号的那个 /page/ 或 /vendor/」，换成资产路由的形式。
+// 收窄到引号后面这一处有两个理由：① 注释和报错文案里的 `/page/` 不是 URL，跟着改会让人以为是新路径；
+// ② 运行时拼出来的图标（`'/vendor/svg/' + name`，page/shared.js:234）也是引号开头，所以这一条规则同时覆盖静态标签和动态拼接。
+// 已核过 vendor/ 内部没有任何绝对引用（Element Plus 的 url() 全是 data:/#fragment），改写不会漏掉二跳引用。
+const ASSET_URL = ASSET_PATH + '?p=';
+const REWRITEABLE = /^text\/(html|javascript|css)/;
+export function rewriteRefs(text) {
+  return text.replace(/(["'])\/(page|vendor)\//g, '$1' + ASSET_URL + '$2/');
+}
+
+// 借 core 的手把文件发出去，插件只在中间加一层「URL 前缀翻译」：
+// 防穿越、MIME、no-store、`__AGENT_LOG_BUILD__` / `__AGENT_LOG_SHARED__` 注入全都还是那一份实现
+//（顶注那条纪律 —— 装配层不另起一套服务）。
+function deliver(req, res, urlPath) {
+  const cap = { statusCode: 200, headers: {}, body: null };
+  const push = (chunk) => {
+    if (chunk == null) return;
+    cap.body = Buffer.concat([cap.body || Buffer.alloc(0), Buffer.from(chunk)]);
+  };
+  const shim = {
+    get statusCode() { return cap.statusCode; },
+    set statusCode(v) { cap.statusCode = v; },
+    setHeader(k, v) { cap.headers[String(k).toLowerCase()] = v; },
+    getHeader(k) { return cap.headers[String(k).toLowerCase()]; },
+    hasHeader(k) { return String(k).toLowerCase() in cap.headers; },
+    write: push,
+    end(chunk) {
+      push(chunk);
+      const type = String(cap.headers['content-type'] || '');
+      let out = cap.body || Buffer.alloc(0);
+      if (cap.statusCode === 200 && REWRITEABLE.test(type)) out = Buffer.from(rewriteRefs(out.toString('utf8')), 'utf8');
+      res.statusCode = cap.statusCode;
+      for (const [k, v] of Object.entries(cap.headers)) { try { res.setHeader(k, v); } catch {} }
+      res.end(out);
+    },
+  };
+  // 那三条目标路由（'/'、/page/*、/vendor/*）都是同步 readFileSync + 同步 end，所以改 req.url、调用、再改回来是安全的；
+  // 若哪天它们改成异步流式输出，这里要换成复制一个 req。
+  const orig = req.url;
+  req.url = urlPath;
+  try { handle(req, shim); }
+  catch (e) { res.statusCode = 500; res.end('agent-acta: 递送失败 ' + (e && e.message)); }
+  finally { req.url = orig; }
+}
+
+// ?p= 只收裸相对路径（page/x.js、vendor/svg/y.svg）。带前导斜杠、带 .. 的一律不收 ——
+// core 里那套 resolve + 前缀比对仍作第二层，这两层不是重复：那层防文件穿越，这层防「把资产路由当成任意路径的口子」。
+const ASSET_REL = /^(?:page|vendor)\/[\w.-]+(?:\/[\w.-]+)*$/;
+export function assetTarget(req) {
+  let p = '';
+  try { p = new URL(req.url, 'http://agent-acta.local').searchParams.get('p') || ''; } catch { return null; }
+  if (!ASSET_REL.test(p) || p.includes('..')) return null;
+  return '/' + p;
+}
+
+const NOTICE = (cli) => `<!doctype html><html lang="zh-CN"><meta charset="utf-8">
+<title>AgentActa</title><style>body{font:14px/1.7 ui-monospace,Consolas,monospace;background:#12161d;color:#dfe6ef;padding:22px;max-width:46rem}
+code{background:#ffffff14;padding:2px 6px;border-radius:4px}</style>
+<body><h3>AgentActa 面板没起来 —— 命令行那版服务正在跑</h3>
+<p>端口 <code>127.0.0.1:${PORT}</code> 上有一个 AgentActa 服务（版本 <code>${cli && cli.version}</code> / 指纹 <code>${cli && cli.build}</code>）。
+它和插件是同一套数据目录，两个扫描器同时跑会互相抢着写索引与归档，所以插件这次<b>没有起自己的服务</b>。</p>
+<p>想看面板：直接开 <a href="http://127.0.0.1:${PORT}/">http://127.0.0.1:${PORT}/</a>（就是它）；
+想让插件接手：先跑 <code>agentacta --stop</code>，再重开这个面板。</p></body></html>`;
+
+export function apply(ctx) {
+  let web = null;
+  const registered = [];
+
+  const reg = (kind, p, h) => {
+    try {
+      web.effect(() => {
+        const off = web.webServer.register({ kind, path: p, handler: h });
+        registered.push(p);
+        return () => { try { if (typeof off === 'function') off(); } catch (e) { /* 卸载不该拖垮宿主 */ } };
+      });
+    } catch (e) {
+      console.error('[agent-acta] 路由注册失败 ' + p + '：' + (e && e.message));
+    }
+  };
+
+  // 把 inject 的 promise 交回去：宿主（和测试）要能 await 到「注册真的挂完」，
+  // 否则 apply() 只是「发起」了装配 —— 测试里就会看见注册表还是空的、断言空跑。
+  return ctx.inject(['webServer'], async (webCtx) => {
+    web = webCtx;
+    const cli = await cliProbe();
+
+    if (cli) {
+      // A 分支：不起 hosted、不挂业务路由，只留一条说明页。
+      reg('exact', ENTRY_PATH, (req, res) => {
+        res.statusCode = 200;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.end(NOTICE(cli));
+      });
+      webCtx.logger?.info?.('[agent-acta] 检测到命令行服务在跑，插件只提供说明页');
+      return;
+    }
+
+    await start({ mode: 'hosted', listen: false });
+
+    const passthrough = (req, res) => handle(req, res);
+
+    // EXTRA 那几条有自己的 handler，不能让 passthrough 先占位：core 没这些路由，passthrough 会答 404；
+    // 而重复的 (kind,path) 在宿主里是 throw + **先注册的那条赢** ⇒ 真 handler 永远挂不上（302 那次就是这么坏的）。
+    const extraHandlers = {
+      [ENTRY_PATH]: (req, res) => deliver(req, res, '/'),
+      [ASSET_PATH]: (req, res) => {
+        const target = assetTarget(req);
+        if (!target) { res.statusCode = 400; res.setHeader('content-type', 'text/plain; charset=utf-8'); res.end('agent-acta: 资产请求的 p 参数不在白名单（要形如 page/x.js）'); return; }
+        deliver(req, res, target);
+      },
+    };
+
+    for (const s of hostedRouteSpecs()) {
+      if (extraHandlers[s.path]) continue;
+      reg(s.kind, s.path, passthrough);
+    }
+    for (const p of HOSTED_EXTRA) reg('exact', p, extraHandlers[p]);
+
+    // 面板入口不再 302 到宿主 http 口：iframe 从 dsh-app:// 跳 http://127.0.0.1 是跨源，实测被拦（空白），
+    // 而且那口上的 /page/、/vendor/ 在 iframe 里本来也到不了。改成由 ENTRY_PATH 自己把 HTML 递出来，
+    // 页面里的静态引用由 rewriteRefs 翻译成 ASSET_PATH —— 全程同源、单源。
+    webCtx.logger?.info?.('[agent-acta] hosted 就绪 v' + VERSION + ' (' + BUILD + ')，路由 ' + registered.length + ' 条，入口 ' + ENTRY_PATH);
+
+    web.effect(() => () => stop('DSH 插件卸载'));
+  });
+}