niceeval 0.1.0 → 0.1.2

package/src/runner/types.ts

@@ -0,0 +1,237 @@
+// runner 域类型:结果 / 汇总 / reporter 契约,eval / experiment / config 定义,
+// 以及调度器的编排类型(AgentRun / RunOptions / Attempt)。
+
+import type { Cleanup, LocalizedText, SourceArtifact } from "../shared/types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { Agent } from "../agents/types.ts";
+import type { Sandbox, SandboxOption } from "../sandbox/types.ts";
+import type { AssertionResult, DiffData, JudgeConfig, ResultOutcome } from "../scoring/types.ts";
+import type { TestContext } from "../context/types.ts";
+
+// ───────────────────────── 结果 / 报告 ─────────────────────────
+
+export interface ExperimentRunInfo {
+  id?: string;
+  flags?: Record<string, unknown>;
+  runs?: number;
+  earlyExit?: boolean;
+  sandbox?: string;
+  timeoutMs?: number;
+  budget?: number;
+}
+
+export interface EvalResult {
+  id: string;
+  description?: string;
+  experimentId?: string;
+  experiment?: ExperimentRunInfo;
+  agent: string;
+  model?: string;
+  outcome: ResultOutcome;
+  fingerprint?: string;
+  attempt: number;
+  /** 本 attempt 开始的墙钟时刻(ISO);view 按 eval 粒度展示「何时跑的」。 */
+  startedAt?: string;
+  durationMs: number;
+  assertions: AssertionResult[];
+  usage?: Usage;
+  estimatedCostUSD?: number;
+  error?: string;
+  skipReason?: string;
+  events?: StreamEvent[];
+  /** test 引用到的 eval 源码(按 loc 收集),供 view 渲染 github-diff 式代码视图。 */
+  sources?: SourceArtifact[];
+  o11y?: O11ySummary;
+  /** agent 经 OpenTelemetry 导出的运行追踪(有 tracing 能力且收到 span 时)。 */
+  trace?: TraceSpan[];
+  diff?: DiffData;
+  rawTranscript?: string;
+  // ── 拆分工件的引用(Artifacts 报告器写 summary.json 时填;view 按需懒加载)──
+  /** 本 attempt 工件目录(相对 run 根),下有 events/trace/o11y/diff.json。 */
+  artifactsDir?: string;
+  /** view 拼好的工件目录(相对 view 输入根,供前端 fetch);loadSummaries 注入。 */
+  artifactBase?: string;
+  /** 工件目录的绝对路径;loadSummaries 注入,供复制/展示用。 */
+  artifactAbsBase?: string;
+  hasTrace?: boolean;
+  hasEvents?: boolean;
+  hasSources?: boolean;
+}
+
+/** `summary.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
+export const RESULTS_FORMAT = "niceeval.results";
+/** 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本,缺失按 1。见 docs/results-format.md。 */
+export const RESULTS_SCHEMA_VERSION = 1;
+
+export interface RunSummary {
+  /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
+  format?: typeof RESULTS_FORMAT;
+  /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
+  schemaVersion?: number;
+  /** 写这份报告的 niceeval;version 唯一用途是拼 `npx niceeval@<version> view` 提示。 */
+  producer?: { name: "niceeval"; version?: string; commit?: string };
+  /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+  name?: LocalizedText;
+  agent: string;
+  model?: string;
+  startedAt: string;
+  completedAt: string;
+  passed: number;
+  /** 断言不通过的数量;不包含 errored。 */
+  failed: number;
+  skipped: number;
+  /** 环境、超时、adapter、agent runtime 等执行错误数量;与 failed 互斥。 */
+  errored: number;
+  durationMs: number;
+  usage?: Usage;
+  estimatedCostUSD?: number;
+  results: EvalResult[];
+  outputDir?: string;
+}
+
+/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
+export interface RunShape {
+  /** 去重后实际要跑的 eval 数(= evals.length)。 */
+  evals: number;
+  /** (agent, model, flags) 配置组合数;compare 多 agent 时 > 1。 */
+  configs: number;
+  /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
+  totalRuns: number;
+}
+
+export interface Reporter {
+  onEvent?(event: ReporterEvent): void | Promise<void>;
+  onRunStart?(evals: { id: string }[], agent: Agent, shape?: RunShape): void | Promise<void>;
+  onEvalComplete?(result: EvalResult): void | Promise<void>;
+  onRunComplete?(summary: RunSummary): void | Promise<void>;
+}
+
+export type ReporterEvent =
+  | { type: "run:start"; evals: { id: string }[]; agent: Agent; shape: RunShape }
+  | { type: "eval:start"; eval: { id: string }; agent: Agent; attempt: number; experimentId?: string }
+  | { type: "eval:complete"; result: EvalResult }
+  | { type: "run:earlyExit"; evalId: string; experimentId?: string }
+  | { type: "run:budgetExceeded"; budget: number; spent: number }
+  | { type: "run:saved"; summary: RunSummary }
+  | { type: "run:summary"; summary: RunSummary };
+
+// ───────────────────────── eval / experiment / config 定义 ─────────────────────────
+
+export interface EvalDef {
+  /** 路径推导,定义里禁止手写。 */
+  id?: string;
+  description?: string;
+  agent?: string;
+  tags?: string[];
+  judge?: JudgeConfig;
+  reporters?: Reporter[];
+  timeoutMs?: number;
+  metadata?: Record<string, unknown>;
+  /**
+   * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
+   * 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
+   * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨后端语义一致。
+   */
+  setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
+  test(t: TestContext): Promise<void> | void;
+}
+
+/** 内部:发现后带上 id 的 eval。 */
+export interface DiscoveredEval extends EvalDef {
+  id: string;
+  /** 定义文件所在目录(解析相对 workspace 用)。 */
+  baseDir: string;
+  /** 定义文件绝对路径,用于内容指纹缓存。 */
+  sourcePath: string;
+}
+
+export interface ExperimentDef {
+  id?: string;
+  description?: string;
+  agent: Agent;
+  /** 单个模型(agent 留空时实验决定);省略=用 agent 原生默认。跨模型对比写多个实验文件,别用数组。 */
+  model?: string;
+  flags?: Record<string, unknown>;
+  runs?: number;
+  earlyExit?: boolean;
+  evals?: "*" | string[] | ((id: string) => boolean);
+  timeoutMs?: number;
+  sandbox?: SandboxOption;
+  budget?: number;
+  maxConcurrency?: number;
+}
+
+export interface DiscoveredExperiment extends ExperimentDef {
+  id: string;
+  group: string;
+}
+
+export interface Config {
+  /**
+   * 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
+   * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
+   */
+  name?: LocalizedText;
+  sandbox?: SandboxOption;
+  workspace?: string;
+  judge?: JudgeConfig;
+  reporters?: Reporter[];
+  maxConcurrency?: number;
+  timeoutMs?: number;
+  /**
+   * OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL_OTLP_* 环境变量)。
+   * `port` 钉住接收端口(固定端口模式:长驻服务把 OTEL_EXPORTER_OTLP_ENDPOINT 一次性指到
+   * http://localhost:<port>/v1/traces,跑多少次 eval 都不用改)。省略 = 每次运行动态分配
+   * 临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
+   * 且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
+   * `host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
+   * "127.0.0.1";docker 沙箱型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
+   * 的远程接入,在这里覆盖。
+   */
+  telemetry?: { host?: string; port?: number };
+}
+
+// ───────────────────────── 调度编排 ─────────────────────────
+
+/** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
+export interface AgentRun {
+  agent: Agent;
+  model?: string;
+  flags: Record<string, unknown>;
+  runs: number;
+  earlyExit: boolean;
+  sandbox?: SandboxOption;
+  timeoutMs?: number;
+  budget?: number;
+  evalFilter: (id: string) => boolean;
+  experimentId?: string;
+  strict?: boolean;
+}
+
+export interface RunOptions {
+  config: Config;
+  evals: DiscoveredEval[];
+  agentRuns: AgentRun[];
+  reporters: Reporter[];
+  maxConcurrency: number;
+  signal?: AbortSignal;
+  /** TTY live display 的进度回调;设置后 attempt 的 log 消息路由到它而不是 stderr。 */
+  onProgress?: (evalId: string, who: string, msg: string) => void;
+  /** 上次运行的结果。outcome === "passed" 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
+  priorResults?: EvalResult[];
+  /**
+   * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
+   * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
+   */
+  otelPool?: import("../o11y/otlp/turn-otel.ts").OtelReceiverPool;
+}
+
+/** 调度器内部的一次尝试:eval × run × 第几轮。 */
+export interface Attempt {
+  evalDef: DiscoveredEval;
+  run: AgentRun;
+  attempt: number;
+  /** agent+model+evalId,用于早停。 */
+  key: string;
+  fingerprint: string;
+}

package/src/sandbox/checkpoint.ts

@@ -4,36 +4,38 @@
 //   uploadFile   — 向沙箱写任意路径的原始字节 ← Buffer
 //
 // 原理:
-//   capture: tar czf /tmp/__fe_cp__.tar.gz <paths>  →  downloadFile → Buffer
-//   restore: uploadFile → /tmp/__fe_rs__.tar.gz  →  tar xzf -C /
+//   capture: tar czf /tmp/__fe_cp_<uuid>.tar.gz <paths>  →  downloadFile → Buffer
+//   restore: uploadFile → /tmp/__fe_rs_<uuid>.tar.gz  →  tar xzf -C /
 //
 // tar / binary file I/O 在所有 Linux sandbox(Docker、Vercel、e2b、Modal…)里都支持,
 // 这段代码对任意 backend 的 Sandbox 实现无改动即可使用。
 
+import { randomUUID } from "node:crypto";
 import type { Sandbox } from "../types.ts";
+import { shellQuote } from "./shell.ts";
 import { t } from "../i18n/index.ts";
 
-const CP_TMP = "/tmp/__fe_cp__.tar.gz";
-const RS_TMP = "/tmp/__fe_rs__.tar.gz";
+// 临时 tar 名带随机后缀:同一沙箱被复用 / 并发做 checkpoint 时,固定名会互相覆盖。
+function tmpTarPath(tag: string): string {
+  return `/tmp/__fe_${tag}_${randomUUID()}.tar.gz`;
+}
 
 /** 把 paths 列出的目录打成 gzip tar,返回 Buffer。 */
 export async function createCheckpoint(sb: Sandbox, paths: string[]): Promise<Buffer> {
+  const tmp = tmpTarPath("cp");
   const quoted = paths.map(shellQuote).join(" ");
   // --ignore-failed-read:跳过不存在的路径(如 .cache/uv 可能未建);true 保证 exit 0。
-  await sb.runShell(`tar czf ${CP_TMP} --ignore-failed-read ${quoted} 2>/dev/null; true`);
-  const buf = await sb.downloadFile(CP_TMP);
-  await sb.runShell(`rm -f ${CP_TMP}`);
+  await sb.runShell(`tar czf ${tmp} --ignore-failed-read ${quoted} 2>/dev/null; true`);
+  const buf = await sb.downloadFile(tmp);
+  await sb.runShell(`rm -f ${tmp}`);
   if (!buf || buf.length === 0) throw new Error(t("checkpoint.emptyTar", { paths: paths.join(", ") }));
   return buf;
 }
 
 /** 把 createCheckpoint 返回的 Buffer 还原到沙箱根目录。 */
 export async function restoreCheckpoint(sb: Sandbox, data: Buffer): Promise<void> {
-  await sb.uploadFile(RS_TMP, data);
+  const tmp = tmpTarPath("rs");
+  await sb.uploadFile(tmp, data);
   // -C / 解压到根目录,覆盖同路径文件;rm 用 ; 保证无论成败都清理临时文件。
-  await sb.runShell(`tar xzf ${RS_TMP} -C / 2>/dev/null; rm -f ${RS_TMP}`);
-}
-
-function shellQuote(s: string): string {
-  return `'${s.replace(/'/g, "'\\''")}'`;
+  await sb.runShell(`tar xzf ${tmp} -C / 2>/dev/null; rm -f ${tmp}`);
 }

package/src/sandbox/docker-stream.ts

@@ -0,0 +1,87 @@
+// Docker exec 流的 demux 与 tar 打包/解包 helper——从 docker.ts 拆出的纯工具层,
+// 不含任何容器编排逻辑,便于独立测试与复用。
+
+import * as tar from "tar-stream";
+
+/**
+ * Docker exec 复用流(8 字节头 + 载荷)的增量解析器。
+ * 头:[stream_type(1B), 0, 0, 0, size(4B 大端)];stream_type:1=stdout,2=stderr。
+ *
+ * 关键:一帧可能被 Node 的可读流切到【多个 data 事件】里(尤其大输出,如 cat 一个
+ * ~100KB 的文件),帧头 / 载荷都可能跨 chunk。所以必须跨 data 累积一个 leftover,
+ * 只消费「已到齐的完整帧」,残帧留到下个 data —— 否则会在 chunk 边界丢字节 / 串帧,
+ * 表现为 transcript 里随机损坏的行(曾导致 bub tape 的 tool_result/tool_call 被吞)。
+ */
+export function createExecDemuxer(): {
+  push(chunk: Buffer): void;
+  stdout(): string;
+  stderr(): string;
+} {
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  let buffer: Buffer = Buffer.alloc(0); // 跨 data 累积的残帧;注解为 Buffer 以容纳 concat 的 ArrayBufferLike
+
+  return {
+    push(chunk: Buffer): void {
+      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+      while (buffer.length >= 8) {
+        const streamType = buffer[0];
+        const size = buffer.readUInt32BE(4);
+        if (buffer.length < 8 + size) break; // 载荷未到齐 → 等下个 chunk
+        const payload = buffer.subarray(8, 8 + size);
+        if (streamType === 2) stderrChunks.push(payload);
+        else stdoutChunks.push(payload); // 1 / 0 / 未知 → 归 stdout
+        buffer = buffer.subarray(8 + size);
+      }
+    },
+    stdout(): string {
+      return Buffer.concat(stdoutChunks).toString("utf-8");
+    },
+    stderr(): string {
+      return Buffer.concat(stderrChunks).toString("utf-8");
+    },
+  };
+}
+
+/** Readable stream → Buffer。 */
+export async function readableToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    stream.on("data", (chunk: Buffer | string) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+
+/** 从单文件 tar 包里提取第一个 entry 的内容。 */
+export async function extractFileFromTar(tarBuf: Buffer): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const extract = tar.extract();
+    let found = false;
+    extract.on("entry", (header, stream, next) => {
+      if (!found) {
+        found = true;
+        const chunks: Buffer[] = [];
+        stream.on("data", (c: Buffer) => chunks.push(c));
+        stream.on("end", () => { resolve(Buffer.concat(chunks)); next(); });
+        stream.on("error", reject);
+      } else {
+        stream.resume();
+        next();
+      }
+    });
+    extract.on("finish", () => { if (!found) reject(new Error("tar: no entries found")); });
+    extract.on("error", reject);
+    extract.end(tarBuf);
+  });
+}
+
+/** 把若干文件打成 tar 流(putArchive 用)。 */
+export function packFilesToTar(entries: readonly { name: string; content: Buffer }[]): tar.Pack {
+  const pack = tar.pack();
+  for (const entry of entries) {
+    pack.entry({ name: entry.name }, entry.content);
+  }
+  pack.finalize();
+  return pack;
+}

package/src/sandbox/docker.ts

@@ -2,11 +2,8 @@
 // 改编自 agent-eval 的 docker-sandbox.ts,签名对齐 ../types.ts 的 Sandbox 契约
 //(runShell/runCommand 的 opts 一律是选项对象,不再用位置参数)。
 
-import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, dirname, join, relative, sep } from "node:path";
-import { Readable } from "node:stream";
+import { basename, dirname } from "node:path";
 import Docker from "dockerode";
-import * as tar from "tar-stream";
 import type {
   Sandbox,
   CommandResult,
@@ -17,11 +14,17 @@ import type {
   ReadSourceFilesOptions,
 } from "../types.ts";
 import { makeSourceFiles } from "./source-files.ts";
+import {
+  DEFAULT_IGNORE_DIRS,
+  DEFAULT_IGNORE_FILES,
+  DEFAULT_SOURCE_EXTENSIONS,
+  collectLocalFiles,
+} from "./local-files.ts";
+import { buildFindScript, shellQuote } from "./shell.ts";
+import { createExecDemuxer, extractFileFromTar, packFilesToTar, readableToBuffer } from "./docker-stream.ts";
+import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
 
-const DEFAULT_SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
-const DEFAULT_IGNORE_DIRS = [".git", ".next", "node_modules", "dist", "build", "coverage"];
-const DEFAULT_IGNORE_FILES = ["EVAL.ts", "PROMPT.md"];
 // 行首哨兵:源码文件几乎不可能出现这一串,用来切分单次 shell 输出里的多份文件。
 const SOURCE_FILE_MARKER = "::FE-SRC-7b3f9c::";
 
@@ -47,11 +50,6 @@ const CONTAINER_WORKDIR = "/home/sandbox/workspace";
 // 容器「主日志」文件:PID1 tail 它 → `docker logs` 实时显示;agent 命令的 stream 输出 tee 进来。
 const CONTAINER_LOG = "/tmp/niceeval-agent.log";
 
-/** 单引号包裹 + 转义,把一个参数安全嵌进 shell 命令串。 */
-function shellQuote(s: string): string {
-  return `'${s.replace(/'/g, "'\\''")}'`;
-}
-
 // 命令默认以非 root 的 node 用户跑:安全 + 兼容(如 Claude Code 在 root 下拒绝
 // --dangerously-skip-permissions)。node:*-slim 镜像自带 UID/GID 1000 的 node 用户。
 // 需要 root 的命令(setup 装系统依赖)走 runCommand 的 `{ root: true }`;此默认非 root + 按需提
@@ -67,39 +65,6 @@ const NPM_GLOBAL_DIR = "/home/node/.npm-global";
 // 命令执行时注入的 PATH:把 npm 全局 bin 放最前。
 const SANDBOX_PATH = `${NPM_GLOBAL_DIR}/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`;
 
-/** Readable stream → Buffer。 */
-async function readableToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    stream.on("data", (chunk: Buffer | string) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-/** 从单文件 tar 包里提取第一个 entry 的内容。 */
-async function extractFileFromTar(tarBuf: Buffer): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    const extract = tar.extract();
-    let found = false;
-    extract.on("entry", (header, stream, next) => {
-      if (!found) {
-        found = true;
-        const chunks: Buffer[] = [];
-        stream.on("data", (c: Buffer) => chunks.push(c));
-        stream.on("end", () => { resolve(Buffer.concat(chunks)); next(); });
-        stream.on("error", reject);
-      } else {
-        stream.resume();
-        next();
-      }
-    });
-    extract.on("finish", () => { if (!found) reject(new Error("tar: no entries found")); });
-    extract.on("error", reject);
-    extract.end(tarBuf);
-  });
-}
-
 /** 创建 Docker 沙箱的选项。 */
 export interface DockerSandboxOptions {
   /** 单条命令超时(毫秒)。 */
@@ -115,6 +80,7 @@ export interface DockerSandboxOptions {
  * 实现 ../types.ts 的 Sandbox 接口。
  */
 export class DockerSandbox implements Sandbox {
+  readonly workdir = CONTAINER_WORKDIR;
   readonly otlpHost = "host.docker.internal";
   private docker: Docker;
   private container: Docker.Container | null = null;
@@ -269,7 +235,7 @@ export class DockerSandbox implements Sandbox {
 
     return this.execCommand(cmd, args, {
       env,
-      cwd: opts.cwd,
+      cwd: resolveSandboxPath(this.workdir, opts.cwd),
       user: isRoot ? ROOT_USER : SANDBOX_USER,
     });
   }
@@ -282,7 +248,7 @@ export class DockerSandbox implements Sandbox {
   ): Promise<CommandResult> {
     return this.execCommand(cmd, args, {
       env: opts.env,
-      cwd: opts.cwd,
+      cwd: resolveSandboxPath(this.workdir, opts.cwd),
       user: ROOT_USER,
     });
   }
@@ -311,7 +277,7 @@ export class DockerSandbox implements Sandbox {
       Cmd: fullCmd,
       AttachStdout: true,
       AttachStderr: true,
-      WorkingDir: opts.cwd ?? CONTAINER_WORKDIR,
+      WorkingDir: resolveSandboxPath(this.workdir, opts.cwd),
       Env: env,
       User: opts.user,
     });
@@ -319,29 +285,11 @@ export class DockerSandbox implements Sandbox {
     const stream = await exec.start({ hijack: true, stdin: false });
 
     return new Promise<CommandResult>((resolve, reject) => {
-      // Docker 把 stdout/stderr 复用在同一条流里(8 字节头 + 载荷),需手动 demux。
-      // 头:[stream_type(1B), 0, 0, 0, size(4B 大端)];stream_type:1=stdout,2=stderr。
-      //
-      // 关键:一帧可能被 Node 的可读流切到【多个 data 事件】里(尤其大输出,如 cat 一个
-      // ~100KB 的文件),帧头 / 载荷都可能跨 chunk。所以必须跨 data 累积一个 leftover,
-      // 只消费「已到齐的完整帧」,残帧留到下个 data —— 否则会在 chunk 边界丢字节 / 串帧,
-      // 表现为 transcript 里随机损坏的行(曾导致 bub tape 的 tool_result/tool_call 被吞)。
-      const stdoutChunks: Buffer[] = [];
-      const stderrChunks: Buffer[] = [];
-      let buffer: Buffer = Buffer.alloc(0); // 跨 data 累积的残帧;注解为 Buffer 以容纳 concat 的 ArrayBufferLike
-
-      stream.on("data", (chunk: Buffer) => {
-        buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
-        while (buffer.length >= 8) {
-          const streamType = buffer[0];
-          const size = buffer.readUInt32BE(4);
-          if (buffer.length < 8 + size) break; // 载荷未到齐 → 等下个 data
-          const payload = buffer.subarray(8, 8 + size);
-          if (streamType === 2) stderrChunks.push(payload);
-          else stdoutChunks.push(payload); // 1 / 0 / 未知 → 归 stdout
-          buffer = buffer.subarray(8 + size);
-        }
-      });
+      // Docker 把 stdout/stderr 复用在同一条流里(8 字节头 + 载荷),需手动 demux;
+      // 跨 chunk 的帧累积逻辑见 docker-stream.ts 的 createExecDemuxer。
+      const demuxer = createExecDemuxer();
+
+      stream.on("data", (chunk: Buffer) => demuxer.push(chunk));
 
       // 超时:杀流并 reject。
       const timeoutId = setTimeout(() => {
@@ -351,8 +299,8 @@ export class DockerSandbox implements Sandbox {
 
       stream.on("end", async () => {
         clearTimeout(timeoutId);
-        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
-        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+        const stdout = demuxer.stdout();
+        const stderr = demuxer.stderr();
 
         try {
           const inspection = await exec.inspect();
@@ -391,16 +339,17 @@ export class DockerSandbox implements Sandbox {
 
   /** 读容器里的文件。 */
   async readFile(path: string): Promise<string> {
-    const result = await this.runCommand("cat", [path]);
+    const absPath = resolveSandboxPath(this.workdir, path);
+    const result = await this.runCommand("cat", [absPath]);
     if (result.exitCode !== 0) {
-      throw new Error(t("docker.readFileFailed", { path, stderr: result.stderr }));
+      throw new Error(t("docker.readFileFailed", { path: absPath, stderr: result.stderr }));
     }
     return result.stdout;
   }
 
   /** 判断容器里某文件是否存在。 */
   async fileExists(path: string): Promise<boolean> {
-    const result = await this.runCommand("test", ["-f", path]);
+    const result = await this.runCommand("test", ["-f", resolveSandboxPath(this.workdir, path)]);
     return result.exitCode === 0;
   }
 
@@ -413,10 +362,8 @@ export class DockerSandbox implements Sandbox {
     const ignoreDirs = opts.ignoreDirs ?? DEFAULT_IGNORE_DIRS;
     const ignoreFiles = new Set(opts.ignoreFiles ?? DEFAULT_IGNORE_FILES);
 
-    const dirPrune = ignoreDirs.map((d) => `-name '${d}'`).join(" -o ");
-    const nameTests = extensions.map((e) => `-name '*.${e}'`).join(" -o ");
     const script =
-      `find . \\( -type d \\( ${dirPrune} \\) \\) -prune -o -type f \\( ${nameTests} \\) -print | ` +
+      `${buildFindScript({ extensions, ignoreDirs })} | ` +
       `while IFS= read -r f; do printf '%s%s\\n' '${SOURCE_FILE_MARKER}' "$f"; cat "$f"; printf '\\n'; done`;
     const result = await this.runShell(script);
 
@@ -445,7 +392,7 @@ export class DockerSandbox implements Sandbox {
   }
 
   /** 用 tar 归档把文件灌进容器。 */
-  async uploadFiles(files: SandboxFile[], targetDir = CONTAINER_WORKDIR): Promise<void> {
+  async uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void> {
     if (!this.container) {
       throw new Error(t("docker.containerNotInitialized"));
     }
@@ -455,27 +402,25 @@ export class DockerSandbox implements Sandbox {
     }
 
     // 打 tar 包。
-    const pack = tar.pack();
-
-    for (const file of files) {
-      const content =
-        typeof file.content === "string" ? Buffer.from(file.content, "utf-8") : file.content;
+    const pack = packFilesToTar(
+      files.map((file) => ({
+        name: file.path,
+        content: typeof file.content === "string" ? Buffer.from(file.content, "utf-8") : file.content,
+      })),
+    );
 
-      pack.entry({ name: file.path }, content);
-    }
+    const targetPath = resolveSandboxPath(this.workdir, targetDir);
 
-    pack.finalize();
-
-    await this.runCommandAsRoot("mkdir", ["-p", targetDir]);
+    await this.runCommandAsRoot("mkdir", ["-p", targetPath]);
 
     // putArchive 以 root 身份解包到目标目录。
-    await this.container.putArchive(pack, { path: targetDir });
+    await this.container.putArchive(pack, { path: targetPath });
 
     // 修正属主:putArchive 上传成 root,改回 node 用户,agent 才能编辑。
-    await this.chownToSandboxUser(targetDir);
+    await this.chownToSandboxUser(targetPath);
   }
 
-  async uploadDirectory(localDir: string, targetDir: string, opts: { ignore?: string[] } = {}): Promise<void> {
+  async uploadDirectory(localDir: string, targetDir?: string, opts: { ignore?: string[] } = {}): Promise<void> {
     const files = await collectLocalFiles(localDir, opts.ignore);
     await this.uploadFiles(files, targetDir);
   }
@@ -486,7 +431,7 @@ export class DockerSandbox implements Sandbox {
    */
   async downloadFile(path: string): Promise<Buffer> {
     if (!this.container) throw new Error(t("docker.containerNotInitialized"));
-    const stream = await (this.container as Docker.Container).getArchive({ path });
+    const stream = await (this.container as Docker.Container).getArchive({ path: resolveSandboxPath(this.workdir, path) });
     const tarBuf = await readableToBuffer(stream as NodeJS.ReadableStream);
     return extractFileFromTar(tarBuf);
   }
@@ -497,10 +442,9 @@ export class DockerSandbox implements Sandbox {
    */
   async uploadFile(destPath: string, content: Buffer): Promise<void> {
     if (!this.container) throw new Error(t("docker.containerNotInitialized"));
-    const pack = tar.pack();
-    pack.entry({ name: basename(destPath) }, content);
-    pack.finalize();
-    await (this.container as Docker.Container).putArchive(pack, { path: dirname(destPath) });
+    const absPath = resolveSandboxPath(this.workdir, destPath);
+    const pack = packFilesToTar([{ name: basename(absPath), content }]);
+    await (this.container as Docker.Container).putArchive(pack, { path: dirname(absPath) });
   }
 
   /** 停止并清理容器(AutoRemove 负责销毁)。 */
@@ -515,25 +459,3 @@ export class DockerSandbox implements Sandbox {
     }
   }
 }
-
-async function collectLocalFiles(localDir: string, ignore: readonly string[] = []): Promise<SandboxFile[]> {
-  const ignored = new Set(ignore);
-  const out: SandboxFile[] = [];
-  async function walk(dir: string): Promise<void> {
-    for (const entry of await readdir(dir)) {
-      if (ignored.has(entry)) continue;
-      const abs = join(dir, entry);
-      const st = await stat(abs);
-      if (st.isDirectory()) {
-        await walk(abs);
-      } else if (st.isFile()) {
-        out.push({
-          path: relative(localDir, abs).split(sep).join("/"),
-          content: await readFile(abs),
-        });
-      }
-    }
-  }
-  await walk(localDir);
-  return out;
-}