@zhushanwen/subagent-core 0.2.0

package/src/execution/engine/engines/zcode/reader.ts

@@ -0,0 +1,381 @@
+// src/execution/engine/engines/zcode/reader.ts
+//
+// ZcodeEngine reader（P3）：sqlite 只读读取 session/message/part 三级 JOIN →
+// SessionView（设计 D6 read 降级链第①级）。
+//
+// 双端复用约束（设计 §3.3.7）：本模块是唯一允许被 xyz-agent runtime import 的引擎
+// 模块——必须保持无状态纯函数、无 spawn/进程依赖、不 import 同包 launcher/
+// preparer/parser（依赖仅 node 内置 + 中立类型 + 纯常量）。runtime 侧经 workspace
+// 依赖引入（P5 打包登记 tsup noExternal）。
+//
+// 依赖选型：node:sqlite（零依赖）。依据：仓根 engines node>=22.19.0，node:sqlite
+// 自 22.13 起免 flag 可用（本机 v24.11.1 实测通过）；better-sqlite3 是原生模块，
+// 会引入 electron rebuild / pi 进程 ABI 匹配两重打包负担（项目关键规则 12②）。
+// 防御：动态 import——不支持的环境（老 node）抛结构化错误供调用方降级②③级，
+// 不炸模块加载。
+//
+// 表结构（2026-08-25 实测 0.16.5，16 表 WAL）：
+//   session(id, ..., time_created, ...) / message(id, session_id, sequence, data)
+//   / part(id, message_id, session_id, sequence, data)
+//   message.data: {role: 'user'|'assistant', ...}；part.data: {type: 'text'|'reasoning'|
+//   'tool'|'step-start'|'step-finish', ...}（tool 的 state 是 JSON 字符串）。
+//   schema_migration 表存在——CLI 升级迁移表结构，漂移由结构化错误暴露（降级链兜底）。
+
+import * as fs from "node:fs";
+
+// 相对 import 用 .js 形态（本文件是双端复用模块，runtime tsconfig 无
+// allowImportingTsExtensions——.ts 形态会 TS5097；jiti 2.7 / vite / esbuild 均支持
+// .js→.ts 解析，pi 直载不受影响）。
+import type { AgentUsage, AgentUsageTotal, ToolCall } from "../../../types.js";
+import type { ReplayedTurn, SessionView } from "../../types.js";
+import { ZCODE_ENGINE_ID } from "./constants.js";
+
+// ============================================================
+// 结构化错误（供调用方降级②③级——不静默）
+// ============================================================
+
+export type ZcodeReaderErrorCode = "engine_session_read_failed";
+
+export class ZcodeReaderError extends Error {
+  readonly code: ZcodeReaderErrorCode;
+  /** 原始失败细节（缺文件/表漂移/运行时不支持）。 */
+  readonly detail: string;
+
+  constructor(detail: string, hint?: string) {
+    super(
+      `[engine_session_read_failed] zcode 原生 session 读取失败：${detail}。` +
+        (hint ?? "调用方应降级到第②级（宿主 event journal）或第③级（outcome-only）。"),
+    );
+    this.name = "ZcodeReaderError";
+    this.code = "engine_session_read_failed";
+    this.detail = detail;
+  }
+}
+
+// ============================================================
+// 行数据 guard（sqlite 驱动返回 unknown，禁 any）
+// ============================================================
+
+interface MessageRow {
+  id: string;
+  data: string;
+}
+
+interface PartRow {
+  data: string;
+}
+
+interface ParsedMessage {
+  role?: unknown;
+}
+
+interface ParsedPart {
+  type?: unknown;
+  text?: unknown;
+  tool?: unknown;
+  state?: unknown;
+  cost?: unknown;
+  tokens?: unknown;
+}
+
+/** sqlite 驱动的最小消费面（node:sqlite DatabaseSync 结构子集，测试可注入）。 */
+type SqliteDb = {
+  prepare: (sql: string) => { get: (...a: unknown[]) => unknown; all: (...a: unknown[]) => unknown[] };
+};
+
+function parseJsonField(raw: string, ctx: string): Record<string, unknown> | undefined {
+  try {
+    const v: unknown = JSON.parse(raw);
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+  } catch (err) {
+    throw new ZcodeReaderError(
+      `${ctx} 行 data 不是合法 JSON（${err instanceof Error ? err.message : String(err)}）`,
+      "db 内容损坏或版本不兼容——调用方应降级到第②级（宿主 event journal）。",
+    );
+  }
+}
+
+function finiteOr(v: unknown, fallback: number): number {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/** step-finish tokens 形状 {total, input, output, reasoning, cache:{read, write}} → AgentUsage。 */
+function usageFromStepFinish(part: ParsedPart): AgentUsage | undefined {
+  const tokens = part.tokens;
+  if (typeof tokens !== "object" || tokens === null) return undefined;
+  const t = tokens as Record<string, unknown>;
+  const cache = typeof t.cache === "object" && t.cache !== null ? (t.cache as Record<string, unknown>) : {};
+  if (t.input === undefined && t.output === undefined) return undefined;
+  return {
+    input: finiteOr(t.input, 0),
+    output: finiteOr(t.output, 0),
+    cacheRead: finiteOr(cache.read, 0),
+    cacheWrite: finiteOr(cache.write, 0),
+  };
+}
+
+/** tool part 的 state（JSON 字符串）→ 中立 ToolCall。 */
+function toolFromPart(part: ParsedPart): ToolCall {
+  const toolName = typeof part.tool === "string" ? part.tool : "unknown";
+  let state: Record<string, unknown> | undefined;
+  if (typeof part.state === "string") {
+    try {
+      const v: unknown = JSON.parse(part.state);
+      state = typeof v === "object" && v !== null ? (v as Record<string, unknown>) : undefined;
+    } catch {
+      state = undefined;
+    }
+  }
+  const status = typeof state?.status === "string" ? state.status : "unknown";
+  const output = state?.output;
+  return {
+    toolName,
+    ...(state?.input !== undefined ? { args: state.input } : {}),
+    // 输出形态（实测）：string（内容）或 object（结构化）——分别映射到 pi ToolCallResult
+    // 的 content[] / details，不发明第二形状
+    ...(typeof output === "string" ? { result: { content: [output] } } : {}),
+    ...(typeof output === "object" && output !== null ? { result: { details: output } } : {}),
+    ...(status !== "completed" ? { isError: true } : {}),
+  };
+}
+
+// ============================================================
+// SessionView 派生（turn = assistant 消息内 step-start…step-finish 段）
+// ============================================================
+
+interface TurnAcc {
+  text: string;
+  thinking: string;
+  toolCalls: ToolCall[];
+  usageDelta?: AgentUsage;
+}
+
+class TotalsAcc {
+  input = 0;
+  output = 0;
+  cacheRead = 0;
+  cacheWrite = 0;
+  cost = 0;
+  has = false;
+
+  add(u: AgentUsage): void {
+    this.has = true;
+    this.input += u.input;
+    this.output += u.output;
+    this.cacheRead += u.cacheRead;
+    this.cacheWrite += u.cacheWrite;
+    this.cost += u.cost ?? 0;
+  }
+
+  toTotal(): AgentUsageTotal | undefined {
+    if (!this.has) return undefined;
+    return {
+      input: this.input,
+      output: this.output,
+      cacheRead: this.cacheRead,
+      cacheWrite: this.cacheWrite,
+      cost: this.cost,
+      total: this.input + this.output + this.cacheRead + this.cacheWrite,
+    };
+  }
+}
+
+function closeTurn(acc: TurnAcc | null, turns: ReplayedTurn[], totals: TotalsAcc): void {
+  if (acc === null) return;
+  turns.push({ text: acc.text, thinking: acc.thinking, toolCalls: acc.toolCalls, closed: true });
+  if (acc.usageDelta !== undefined) totals.add(acc.usageDelta);
+}
+
+function rowToMessageRow(v: unknown): MessageRow {
+  if (typeof v === "object" && v !== null && "id" in v && "data" in v) {
+    const r = v as { id: unknown; data: unknown };
+    if (typeof r.id === "string" && typeof r.data === "string") return { id: r.id, data: r.data };
+  }
+  throw new ZcodeReaderError("message 行形状异常（id/data 列缺失或类型漂移）");
+}
+
+function rowToPartRow(v: unknown): PartRow {
+  if (typeof v === "object" && v !== null && "data" in v) {
+    const r = v as { data: unknown };
+    if (typeof r.data === "string") return { data: r.data };
+  }
+  throw new ZcodeReaderError("part 行形状异常（data 列缺失或类型漂移）");
+}
+
+function resolveSessionId(db: SqliteDb, sessionId: string | undefined): string {
+  if (sessionId !== undefined) {
+    const hit = db.prepare("SELECT id FROM session WHERE id = ?").get(sessionId);
+    if (hit === undefined) {
+      throw new ZcodeReaderError(
+        `session 不存在：${sessionId}`,
+        "sessionId 可能来自已清理的池——降级到 outcome-only。",
+      );
+    }
+    return sessionId;
+  }
+  const latest = db
+    .prepare("SELECT id FROM session ORDER BY time_created DESC LIMIT 1")
+    .get() as { id?: unknown } | undefined;
+  if (latest === undefined || typeof latest.id !== "string") {
+    throw new ZcodeReaderError("db 内无任何 session 行");
+  }
+  return latest.id;
+}
+
+/** part JOIN 查询按 message_id 分组（mid 列缺失的行跳过——形状防御）。 */
+function loadGroupedParts(db: SqliteDb, sessionId: string): Map<string, PartRow[]> {
+  // part.sequence 是 message 内局部序（实测：user part 0 / assistant parts 0..n）——
+  // JOIN message 按 (message.sequence, part.sequence) 还原时序，再按 message_id 分组
+  const grouped = new Map<string, PartRow[]>();
+  for (const raw of db
+    .prepare(
+      "SELECT part.message_id AS mid, part.data AS data FROM part " +
+        "JOIN message ON part.message_id = message.id " +
+        "WHERE part.session_id = ? ORDER BY message.sequence, part.sequence",
+    )
+    .all(sessionId)) {
+    if (typeof raw !== "object" || raw === null || !("mid" in raw)) continue;
+    const mid = String((raw as { mid: unknown }).mid);
+    const arr = grouped.get(mid) ?? [];
+    arr.push(rowToPartRow(raw));
+    grouped.set(mid, arr);
+  }
+  return grouped;
+}
+
+/** 首段直入、后续段 "\n" 拼接（text / reasoning 共用；text 字段缺失按空串）。 */
+function appendPartText(current: string, part: ParsedPart): string {
+  return current === "" ? String(part.text ?? "") : current + "\n" + String(part.text ?? "");
+}
+
+/**
+ * 单个 part 归入当前 turn（无 turn 则开），返回归入后的累积器（step-finish 闭合后为
+ * null）。step-start 等边界标记：开 turn 交给首个内容 part（空 step-start 段不产空 turn）。
+ */
+function applyPartToTurn(
+  part: ParsedPart,
+  acc: TurnAcc | null,
+  turns: ReplayedTurn[],
+  totals: TotalsAcc,
+): TurnAcc | null {
+  switch (part.type) {
+    case "text":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.text = appendPartText(acc.text, part);
+      return acc;
+    case "reasoning":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.thinking = appendPartText(acc.thinking, part);
+      return acc;
+    case "tool":
+      acc = acc ?? { text: "", thinking: "", toolCalls: [] };
+      acc.toolCalls.push(toolFromPart(part));
+      return acc;
+    case "step-finish": {
+      const u = usageFromStepFinish(part);
+      const cost = finiteOr(part.cost, 0);
+      if (acc === null) acc = { text: "", thinking: "", toolCalls: [] };
+      if (u !== undefined) acc.usageDelta = cost > 0 ? { ...u, cost } : u;
+      closeTurn(acc, turns, totals);
+      return null;
+    }
+    default:
+      return acc;
+  }
+}
+
+/** assistant 消息流 → turns（usage 累计进 totals）。 */
+function collectTurns(messages: MessageRow[], grouped: Map<string, PartRow[]>, totals: TotalsAcc): ReplayedTurn[] {
+  const turns: ReplayedTurn[] = [];
+  for (const msg of messages) {
+    const parsedMsg = parseJsonField(msg.data, "message") as ParsedMessage | undefined;
+    // SessionView.turns 是 assistant 视角（pi Turn 同构）——user 消息（任务 prompt）不进 turns
+    if (parsedMsg?.role !== "assistant") continue;
+    let acc: TurnAcc | null = null;
+    for (const partRow of grouped.get(msg.id) ?? []) {
+      const part = parseJsonField(partRow.data, "part") as ParsedPart | undefined;
+      if (part === undefined) continue;
+      acc = applyPartToTurn(part, acc, turns, totals);
+    }
+    // 消息结束仍无 step-finish（被杀/截断）：已有内容则闭合
+    closeTurn(acc, turns, totals);
+  }
+  return turns;
+}
+
+function buildView(db: SqliteDb, sessionId: string): SessionView {
+  const messages = db
+    .prepare("SELECT id, data FROM message WHERE session_id = ? ORDER BY sequence")
+    .all(sessionId)
+    .map(rowToMessageRow);
+
+  const totals = new TotalsAcc();
+  const turns = collectTurns(messages, loadGroupedParts(db, sessionId), totals);
+
+  const usageTotal = totals.toTotal();
+  return {
+    engineId: ZCODE_ENGINE_ID,
+    sessionId,
+    ...(usageTotal !== undefined ? { usage: usageTotal } : {}),
+    turns,
+    source: "native",
+  };
+}
+
+// ============================================================
+// 主入口
+// ============================================================
+
+/**
+ * 读取 zcode session 的引擎中立视图（read 第①级）。
+ *
+ * @param dbPath    db.sqlite 绝对路径（引擎 read() 由 handle 解析后传入）
+ * @param sessionId 目标 session；缺省取池内最新（time_created DESC 首行）
+ * @throws ZcodeReaderError db 缺失/表漂移/node:sqlite 不可用/session 不存在——
+ *         结构化错误供调用方走降级链②③级
+ */
+export async function readZcodeSessionView(dbPath: string, sessionId?: string): Promise<SessionView> {
+  if (!fs.existsSync(dbPath)) {
+    throw new ZcodeReaderError(`db 文件不存在：${dbPath}`);
+  }
+  // [HISTORICAL] 动态 import 必须经变量间接：esbuild CJS 输出会把字面量
+  // import("node:sqlite") 规约成裸名 import("sqlite")（external 化 node builtin 时的
+  // 前缀剥离），而 Node 动态 import 裸名不走内置模块 fallback → ERR_MODULE_NOT_FOUND
+  // → xyz-agent runtime bundle（tsup CJS）下①级恒降级（2026-08-25 P5 实测）。非字面量
+  // specifier esbuild 无法静态分析，保留原样输出，node: 前缀运行时正确解析。
+  const sqliteModuleId = "node:sqlite";
+  const sqliteMod = (await import(sqliteModuleId).catch(() => undefined)) as
+    | { DatabaseSync?: unknown }
+    | undefined;
+  const DatabaseSyncCtor = sqliteMod?.DatabaseSync;
+  if (typeof DatabaseSyncCtor !== "function") {
+    throw new ZcodeReaderError(
+      "当前 node 运行时不支持 node:sqlite（需 >=22.13）",
+      "升级 node 或改用第②级（宿主 event journal）读取。",
+    );
+  }
+  type DatabaseSyncLike = new (path: string, opts: { readOnly: boolean }) => SqliteDb & { close(): void };
+  const open = DatabaseSyncCtor as DatabaseSyncLike;
+
+  let db: InstanceType<DatabaseSyncLike> | undefined;
+  try {
+    db = new open(dbPath, { readOnly: true });
+    return buildView(db, resolveSessionId(db, sessionId));
+  } catch (err) {
+    if (err instanceof ZcodeReaderError) throw err;
+    throw new ZcodeReaderError(
+      `sqlite 查询失败（${err instanceof Error ? err.message : String(err)}）`,
+      "疑似表结构漂移（zcode schema_migration 升级）——调用方应降级到第②级；" +
+        "并把新 schema 样本补录进 golden 库后更新 reader。",
+    );
+  } finally {
+    try {
+      db?.close();
+    } catch (err) {
+      // 只读连接 close 失败（WAL 并发读常见）不影响读取结果——吞掉继续；
+      // reader 保持零依赖（双端复用约束），不留 void err 以外的语句
+      void err;
+    }
+  }
+}

package/src/execution/engine/engines/zcode/registration.ts

@@ -0,0 +1,37 @@
+// src/execution/engine/engines/zcode/registration.ts
+//
+// zcode 引擎注册入口（P3 接线）。与 pi/registration.ts 同构：zcode-engine.ts 保持零
+// 注册副作用，注册是组合根（src/index.ts）的职责——依赖方向 registry ← registration
+// ← zcode-engine 单向，无循环。
+//
+// engineDataDir 通道：默认走公共 data-dir SSOT（common/data-dir.ts——env
+// XYZ_AGENT_DATA_DIR（xyz-agent 宿主注入）→ piAgentDir 回退 + warn，透传链证据见该
+// 文件头）。组合根可显式传 getter 覆盖（测试 / 宿主 DI）。
+
+import { getEngineDataDir } from "../../common/data-dir.ts";
+import { registerEngine } from "../../registry.ts";
+import { ZCODE_ENGINE_ID } from "./constants.ts";
+import { ZcodeEngine } from "./zcode-engine.ts";
+import type { ZcodeEngineDeps } from "./zcode-engine.ts";
+
+export { ZCODE_ADAPTER_VERSION, ZCODE_ENGINE_ID } from "./constants.ts";
+export { ZcodeEngine } from "./zcode-engine.ts";
+export type { ZcodeEngineDeps } from "./zcode-engine.ts";
+
+/** 构造 ZcodeEngine（DI 工厂——测试/宿主注入 deps）。 */
+export function createZcodeEngine(deps: ZcodeEngineDeps): ZcodeEngine {
+  return new ZcodeEngine(deps);
+}
+
+/**
+ * 把 'zcode' 引擎登记进 registry（幂等——组合根可能多次执行，registerEngine 覆盖
+ * 语义）。工厂惰性：登记不触发任何文件/进程探测，首次 getEngine 才建实例。
+ */
+export function registerZcodeEngine(engineDataDir: () => string = getEngineDataDir): void {
+  registerEngine(ZCODE_ENGINE_ID, () =>
+    createZcodeEngine({
+      engineDataDir,
+      ...(process.env["XYZ_ZCODE_CLI"] !== undefined ? { cliPath: process.env["XYZ_ZCODE_CLI"] } : {}),
+    }),
+  );
+}