@zhushanwen/subagent-core 0.2.0 → 0.4.0

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

@@ -41,3 +41,132 @@ export const ZCODE_KILL_GRACE_MS = 5_000;
 
 /** 错误信息里保留的 stdout 尾部长度（engine_run_failed 规格：够诊断、不刷屏）。 */
 export const ZCODE_ERROR_TAIL_CHARS = 2000;
+
+/**
+ * [R2] app-server 控制面请求默认超时（ms）。依据：旧 zsw 实现 REQUEST_TIMEOUT_MS=15s
+ * （60+ fake-server 用例 + 真机 e2e 验证值）；R5 probe 冒烟用独立更短预算，不走本值。
+ */
+export const ZCODE_APPSERVER_REQUEST_TIMEOUT_MS = 15_000;
+
+/**
+ * [R2] 连接崩溃错误信息附带的 stderr 尾部长度（字符）。设计 zcode-engine-appserver-
+ * resident.md §3.1 失败路径 2 / §3.3 错误规格表「进程意外退出」行：stderr 尾 400 字符。
+ */
+export const ZCODE_APPSERVER_STDERR_TAIL_CHARS = 400;
+
+/**
+ * [R2] stderr 滚动缓冲上限（字符）：只保最近内容供崩溃诊断。旧 zsw 实现同值 2048。
+ */
+export const ZCODE_APPSERVER_STDERR_TAIL_BUFFER_CHARS = 2048;
+
+/**
+ * [R3] 终态判定后 session/read 兜底拉取的超时（ms）。read 是全文权威来源（不变量 1
+ * 的双来源之二），失败不抛——降级收尾帧/delta 聚合。旧 zsw 实现 READ_TIMEOUT_MS=5000。
+ */
+export const ZCODE_APPSERVER_TURN_READ_TIMEOUT_MS = 5_000;
+
+/**
+ * [R3] 任务收尾 session/close 的控制面超时（ms，best-effort——失败只 warn 不抛）。
+ * 旧 zsw 实现 RELEASE_CLOSE_TIMEOUT_MS=1500（wave2 D2，同值同语义）。
+ */
+export const ZCODE_APPSERVER_TURN_CLOSE_TIMEOUT_MS = 1_500;
+
+/**
+ * [R3] 一轮终态等待的缺省预算（ms）。终态双保险（turn.terminal 权威 + 收尾帧宽松
+ * 匹配防洪堤）之后的最后一道：全漂移/进程假死时不挂死任务。R4 接线后任务级
+ * timeout / abort 链可显式传入更贴任务的值。
+ */
+export const ZCODE_APPSERVER_TURN_DEFAULT_TIMEOUT_MS = 300_000;
+
+// ============================================================
+// [R4] app-server 常驻 HOME（D7）/ abort 链（D3）/ 孤儿自愈（D6③）
+// ============================================================
+
+/**
+ * [R4 D7] 常驻 HOME 的池 key（固定名）。锚定不变量 poolDir == HOME == db 所在目录：
+ * HOME = resolvePoolDir(engineDataDir, 'zcode', 'home-appserver')，SQLite 落
+ * HOME/.zcode/cli/db/db.sqlite，journal 同落该池目录。锁被活宿主持有时派生
+ * `home-appserver-2`… 后缀目录，handle.poolKey 记实际目录名。
+ */
+export const ZCODE_APPSERVER_POOL_KEY = "home-appserver";
+
+/** [R4 D7] 目录锁文件名（HOME 内；O_EXCL 创建，内容 {pid}=持锁宿主进程 pid）。 */
+export const ZCODE_APPSERVER_LOCKFILE_NAME = "lockfile";
+
+/** [R4 D6③/D7] app-server 进程 pidfile 文件名（HOME 内；与 lockfile.pid 严格分离）。 */
+export const ZCODE_APPSERVER_PIDFILE_NAME = "appserver.pid";
+
+/** [R4 D7] 目录锁心跳间隔（ms）：仅刷新 lockfile mtime，不参与活持有否决。 */
+export const ZCODE_APPSERVER_LOCK_HEARTBEAT_MS = 30_000;
+
+/** [R4 D7] 派生目录后缀上限（home-appserver-2 … -N）——极端并发场景防无限循环。 */
+export const ZCODE_APPSERVER_MAX_DERIVED_HOMES = 8;
+
+/**
+ * [R4 D3] abort 链第一级：session/stop 的控制面超时（ms）。stop 失败/超时即落
+ * killChain（协议此时已不可信）。
+ */
+export const ZCODE_APPSERVER_STOP_TIMEOUT_MS = 3_000;
+
+/**
+ * [R4 D3] abort 链第二级：stop 送达后的终态确认 grace 窗口（ms）。窗口内终态
+ * 到达 → 不杀共享进程；超时 → killChain 连坐。
+ */
+export const ZCODE_APPSERVER_ABORT_GRACE_MS = 3_000;
+
+/** [R4 D6③] 孤儿回收的 SIGTERM→SIGKILL grace 窗口（ms）。 */
+export const ZCODE_APPSERVER_PIDFILE_GRACE_MS = 2_000;
+
+/**
+ * [R4/R5] 执行模式定向 env（appserver | spawn）。定向时不探不降；缺省走 app-server
+ * （R5 降级链在缺省路径插 probe 门控）。spawn 降级路径（D2 兜底）继续用
+ * home-<provider>-<model> 池。
+ */
+export const ZCODE_MODE_ENV_VAR = "XYZ_ZCODE_MODE";
+
+/**
+ * [R4] app-server 内部错误码中「模型配置缺失」的归类判据（A.3：-32603 内部错误族，
+ * 消息含 "Model config is missing"——错误规格表第 2 行：报 engine_credential_missing）。
+ */
+export const ZCODE_APPSERVER_ERR_MODEL_CONFIG_MISSING = -32603;
+
+// ============================================================
+// [R5] 降级链（D2）/ probe 冒烟（D8）
+// ============================================================
+
+/**
+ * [R5 D8] 协议冒烟探针的总预算（ms）：独立短命连接上 create 探针会话 → close →
+ * shutdown 的全部时间窗。不发模型请求（无 session/send）、不产生费用。超预算按
+ * 探针失败处理（错误规格表末行：结论 failed → 降级 spawn）。
+ */
+export const ZCODE_APPSERVER_PROBE_BUDGET_MS = 10_000;
+
+/**
+ * [R5 D2] 漂移类 RPC 错误码（错误规格表第 1 行：-32601 方法不存在 / -32602 参数
+ * 变形）。运行中命中任一 → 归档 protocol-drift：首任务降级 spawn 重跑一次 + 后续
+ * 任务直走 spawn（降级标志内存化，进程重启后重探重建）。-32004/-32010/-32603 不在
+ * 此列（任务失败上报 / 凭据缺失归类，均不降级）。
+ */
+const RPC_METHOD_NOT_FOUND = -32601;
+const RPC_INVALID_PARAMS = -32602;
+export const ZCODE_APPSERVER_DRIFT_RPC_CODES = [RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS] as const;
+
+/**
+ * [R5] app-server 内部错误码「会话忙」：send 时该会话已有轮在跑（busy 不排队不打断）。
+ * 单会话一任务是结构保证，运行中命中即 bug（错误文案引导上报 sessionId 与 state 流水）。
+ */
+export const ZCODE_APPSERVER_ERR_BUSY_SESSION = -32010;
+
+/**
+ * [R5 D8] 探针连接的 env 标记：探针用独立短命连接（不污染主连接），但 env 与主连接
+ * 同源（同一常驻 HOME）。此标记供 fake/诊断侧区分「探针进程」与「常驻进程」（测试
+ * 断言探针帧序、故障注入只命中探针或只命中主连接的判据）。
+ */
+export const ZCODE_APPSERVER_PROBE_CONN_ENV = "ZCODE_APPSERVER_PROBE_CONN";
+
+/**
+ * [R5] 崩溃收割确认的兜底窗口（ms）：killChain 在 `exit` 事件 resolve，而连接
+ * finalize（onClose → 在途 turn 崩溃收割）挂 `close` 事件——channel 退订前等 onClose
+ * 触发，本窗口兜底防 `close` 永不到达时 dispose/teardown 挂死。
+ */
+export const ZCODE_APPSERVER_HARVEST_GRACE_MS = 1_000;

package/src/execution/engine/engines/zcode/golden-sample.ts

@@ -1,15 +1,25 @@
 // src/execution/engine/engines/zcode/golden-sample.ts
 //
-// probe「干跑校验」的内嵌 golden 样本（D7：zcode 无官方契约，探针必须做已知样本
-// 回归——对 embed 样本跑 parser，格式漂移在入口拦截而非运行中静默挂死）。
+// golden 语料内嵌副本（双通道并存，R3 扩充）：
 //
-// 来源：2026-08-25 验收前置门真机实录（zcode 0.16.5），完整原文与采集元数据见
-// __tests__/__fixtures__/zcode-golden-spawn.json。为什么不直接读 fixture 文件：
-// probe 在生产运行（npm 包安装形态）也要可用，__tests__ 不在稳定交付面内——内嵌
-// 副本以代码为交付载体；两处不一致时以 fixture 为采集 SSOT、此处为运行时副本，
-// 更新样本需同步改两处（conformance golden 回放层会 diff 校验）。
+//   ① spawn 单 JSON（D7）：probe「干跑校验」的内嵌 golden 样本——zcode 无官方契约，
+//      探针必须做已知样本回归（对 embed 样本跑 parser，格式漂移在入口拦截而非运行中
+//      静默挂死）。来源：2026-08-25 验收前置门真机实录（zcode 0.16.5），完整原文与采集
+//      元数据见 __tests__/__fixtures__/zcode-golden-spawn.json。为什么不直接读 fixture
+//      文件：probe 在生产运行（npm 包安装形态）也要可用，__tests__ 不在稳定交付面内
+//      ——内嵌副本以代码为交付载体。spawn 降级路径（设计 D2 保留）持续消费本语料
+//      （zcode-engine probe 干跑 + conformance spawn 回归），故 R3 帧序列语料落地为
+//      并存新增而非删除替换——漂移防御的主力语料已切换到 ②（登记于 impl-plan 偏差表）。
+//
+//   ② app-server NDJSON 帧序列（R3，D8-②）：常驻通道的 golden 帧序列语料，四类样本
+//      （create 应答 / 推送流 / 终态帧 / read 应答，附录 A.2 任务生命周期帧序）。
+//      来源：按 A.2 协议权威 + 旧 zsw 实现真机抓包形态合成（非实录，fixture _meta
+//      如实标注）；真机冒烟后替换。双副本 diff 机制沿用 ① 的先例：fixture
+//      __tests__/__fixtures__/zcode-golden-appserver.json 是采集 SSOT，此处为运行时
+//      副本，更新样本需同步改两处（session-channel 测试 diff 校验；R6 conformance
+//      迁移后由 golden 回放层接管）。
 
-/** 实录 stdout 原文（单 JSON：sessionId/traceId/turnId/response/usage/eventCount/projection）。 */
+/** [①spawn] 实录 stdout 原文（单 JSON：sessionId/traceId/turnId/response/usage/eventCount/projection）。 */
 export const ZCODE_GOLDEN_STDOUT = `{
   "sessionId": "sess_35852a0f-1302-4e20-9e48-87f47527abe3",
   "traceId": "9fffaebd-749e-468b-af3f-2a89e3347785",
@@ -37,3 +47,39 @@ export const ZCODE_GOLDEN_STDOUT = `{
   }
 }
 `;
+
+// ============================================================
+// [②app-server] NDJSON 帧序列语料（R3，附录 A.2 帧序逐字）
+// ============================================================
+
+/** 四类样本的结构（与 zcode-golden-appserver.json 的 frames 字段一一对应）。 */
+export interface AppServerGoldenFrames {
+  /** ① session/create 应答帧（NDJSON 单行；projection.sessionId 恒 "unknown" 勿用）。 */
+  createResponse: string;
+  /** ④ 推送流帧（NDJSON 逐行：state.updated / stream.chunk 无文本 / session/event delta 有文本）。 */
+  pushStream: string[];
+  /** ⑤ 终态帧（NDJSON 逐行：v4 telemetry turn.terminal 权威 + session/event 收尾帧全文/usage）。 */
+  terminal: string[];
+  /** ⑥ session/read 应答帧（NDJSON 单行：messages[].parts[]，text 全文 + step-finish tokens）。 */
+  readResponse: string;
+}
+
+/** [②app-server] golden 帧序列内嵌副本（采集 SSOT = zcode-golden-appserver.json，双副本 diff 防漂移）。 */
+export const ZCODE_APPSERVER_GOLDEN: AppServerGoldenFrames = {
+  createResponse:
+    '{"session":{"sessionId":"sess_golden_r3_01"},"projection":{"sessionId":"unknown","status":"idle","turnCount":0,"totalTokenCount":0,"contextUsed":0,"contextWindow":1000000}}',
+  pushStream: [
+    '{"method":"state.updated","params":{"sessionId":"sess_golden_r3_01","patch":{"status":"running"},"reason":"prompt_started"}}',
+    '{"method":"v4/telemetry/event","params":{"kind":"stream.chunk","channel":"text","chunkLength":6,"firstChunk":true,"assistantMessageId":"msg_golden_r3_01"}}',
+    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"你好","assistantMessageId":"msg_golden_r3_01"}}}',
+    '{"method":"v4/telemetry/event","params":{"kind":"stream.chunk","channel":"text","chunkLength":1,"firstChunk":false,"assistantMessageId":"msg_golden_r3_01"}}',
+    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"，","assistantMessageId":"msg_golden_r3_01"}}}',
+    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"delta":"任务完成","assistantMessageId":"msg_golden_r3_01"}}}',
+  ],
+  terminal: [
+    '{"method":"v4/telemetry/event","params":{"kind":"turn.terminal","status":"success"}}',
+    '{"method":"session/event","params":{"sessionId":"sess_golden_r3_01","payload":{"response":"你好，任务完成","usage":{"inputTokens":12599,"outputTokens":17}}}}',
+  ],
+  readResponse:
+    '{"messages":[{"info":{"role":"user"},"parts":[{"type":"text","text":"做点什么"}]},{"info":{"role":"assistant"},"parts":[{"type":"text","text":"你好"},{"type":"text","text":"，任务完成"},{"type":"step-finish","tokens":{"input":12599,"output":17,"reasoning":0,"cache":512,"total":12616}}]}]}',
+};

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

@@ -16,12 +16,16 @@
 // 同一 HOME 但模型不同时，config.json 的 model.main 会出现「后写覆盖先写」的串池——
 // zsub 的 per-model HOME 池正是防这个；本引擎以 provider+model 为隔离粒度，agent 维度
 // 的池化留给宿主 refs.json（W3 对齐点）。
+//
+// [R4 D7] app-server 常驻 HOME 语义（锁/派生/pidfile 孤儿回收/allProviders 引导/
+// 凭据内容 hash 刷新）拆至同目录 appserver-home.ts——单一关注点分立。
 
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
 import { resolvePoolDir } from "../../paths.ts";
+import { writeAtomicFileSync } from "../../../../shared/atomic-write.ts";
 import {
   ZCODE_FALLBACK_DEFAULT_MODEL,
   ZCODE_POOL_CONFIG_SUFFIX,
@@ -67,16 +71,16 @@ interface SourceConfig {
 }
 
 /** unknown 的 Record 窄化 guard（替代 as 全可选断言——taste/no-unsafe-cast）。 */
-function isRecord(v: unknown): v is Record<string, unknown> {
+export function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
 /** provider 条目一律按 ZcodeProviderEntry 消费（索引签名形态，无需逐键校验）。 */
-function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
+export function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
   return isRecord(v);
 }
 
-function readSourceConfig(absPath: string): SourceConfig {
+export function readSourceConfig(absPath: string): SourceConfig {
   const empty: SourceConfig = { providers: new Map(), mtimeMs: 0 };
   let raw: string;
   try {
@@ -119,7 +123,12 @@ function providerOf(ref: string): string {
   return ref.slice(0, ref.lastIndexOf("/"));
 }
 
-function hasApiKey(entry: ZcodeProviderEntry): boolean {
+/** [R4] 规范化全名 provider/model → create 参数的 per-session model 拆分（A.2 ① strict 对象）。 */
+export function splitZcodeModelRef(modelRef: string): { providerId: string; modelId: string } {
+  return { providerId: providerOf(modelRef), modelId: modelShort(modelRef) };
+}
+
+export function hasApiKey(entry: ZcodeProviderEntry): boolean {
   const key = entry.options?.apiKey;
   return typeof key === "string" && key !== "";
 }
@@ -129,12 +138,16 @@ export interface ZcodeSourcePaths {
   v2ConfigPath?: string;
 }
 
-function defaultV2ConfigPath(): string {
+export function defaultV2ConfigPath(): string {
   return path.join(os.homedir(), ...ZCODE_V2_CONFIG_PATH_SUFFIX);
 }
 
-/** 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。 */
-const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
+/**
+ * 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。
+ * 导出（sink 设计 U1 模型切分四件之一）：barrel re-export 供第三宿主模型路由消费，
+ * 实现体内聚本文件不挪。
+ */
+export const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
 
 /**
  * 短名模型（如 "GLM-5.3"）的默认 provider 决策。让位条件（对齐点⑦）：显式默认引擎
@@ -297,7 +310,7 @@ function homeNeedsBootstrap(configPath: string, sourceMtimeMs: number): boolean
 }
 
 /** 池 config.json 缩进（人读友好——与 zsub 产出的文件形态一致）。 */
-const CONFIG_INDENT_SPACES = 2;
+export const CONFIG_INDENT_SPACES = 2;
 
 /**
  * 引导隔离 HOME 的 provider 配置（spawn 前调用）。
@@ -342,22 +355,12 @@ export function prepareZcodeHome(opts: {
   const hitSourceMtime = v2.mtimeMs;
   let wroteConfig = false;
   if (homeNeedsBootstrap(configPath, hitSourceMtime)) {
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
     const payload = JSON.stringify({ model: { main: modelRef }, provider: { [provider]: entry } }, null, CONFIG_INDENT_SPACES);
-    const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, payload, "utf8");
-      fs.renameSync(tmp, configPath);
-    } finally {
-      // rename 成功后 tmp 已不存在；失败时清残留，避免污染 HOME 目录
-      try {
-        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
-      } catch (err) {
-        // rename 失败路径的残留清理是 best-effort——记录后继续（tmp 文件不参与读取）
-        void err;
-      }
-    }
+    // tmp+rename 原子写（shared/atomic-write 统一原语，U6b 迁移——rename 失败时
+    // 原语清残留 tmp，避免污染 HOME 目录；tmp 文件不参与读取，best-effort 语义不变）
+    writeAtomicFileSync(configPath, payload);
     wroteConfig = true;
   }
   return { modelRef, poolKey, homeDir, configPath, wroteConfig };
 }
+