@downcity/agent 1.1.86 → 1.1.92

package/bin/types/plugin/ImagePlugin.d.ts

@@ -78,6 +78,69 @@ export interface ImagePluginInput {
  * ImagePlugin 生成结果。
  */
 export type ImagePluginResult = UIMessage;
+/**
+ * ImagePlugin 图片任务状态。
+ */
+export type ImagePluginJobStatus = "queued" | "running" | "succeeded" | "failed";
+/**
+ * ImagePlugin 图片任务创建结果。
+ */
+export interface ImagePluginJobCreateResult {
+    /** 图片任务唯一 ID。 */
+    job_id: string;
+    /** 当前任务状态。 */
+    status: ImagePluginJobStatus;
+    /** 查询任务状态的路径或 URL。 */
+    status_path?: string;
+    /** 读取任务结果的路径或 URL。 */
+    result_path?: string;
+    /** 人类可读状态说明。 */
+    message?: string;
+    /** 建议下次轮询前等待的毫秒数。 */
+    poll_after_ms?: number;
+    /** 任务创建时间。 */
+    created_at?: string;
+    /** 任务更新时间。 */
+    updated_at?: string;
+}
+/**
+ * ImagePlugin 图片任务状态查询结果。
+ */
+export interface ImagePluginJobStatusResult {
+    /** 图片任务唯一 ID。 */
+    job_id: string;
+    /** 当前任务状态。 */
+    status: ImagePluginJobStatus;
+    /** 人类可读状态说明。 */
+    message?: string;
+    /** 失败时的错误信息。 */
+    error?: string;
+    /** 建议下次轮询前等待的毫秒数。 */
+    poll_after_ms?: number;
+    /** 任务创建时间。 */
+    created_at?: string;
+    /** 任务更新时间。 */
+    updated_at?: string;
+}
+/**
+ * ImagePlugin 图片任务结果查询结果。
+ */
+export interface ImagePluginJobResult {
+    /** 图片任务唯一 ID。 */
+    job_id: string;
+    /** 当前任务状态。 */
+    status: ImagePluginJobStatus;
+    /** 成功时的图片结果。 */
+    result?: ImagePluginResult;
+    /** 失败时的错误信息。 */
+    error?: string;
+    /** 人类可读状态说明。 */
+    message?: string;
+    /** 任务创建时间。 */
+    created_at?: string;
+    /** 任务更新时间。 */
+    updated_at?: string;
+}
 /**
  * ImagePlugin 构造参数。
  */
@@ -88,7 +151,21 @@ export interface ImagePluginOptions {
     title?: string;
     /** Plugin 用途说明。 */
     description?: string;
-    /** 图片生成函数，通常传入 `(input) => city.ai.image(input)`。 */
-    image: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+    /** 可选：图片生成函数；未传 `create/status/result` 时用于本地后台任务兼容。 */
+    image?: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+    /** 可选：创建图片生成任务，通常传入 `(input) => city.ai.imageJobCreate(input)`。 */
+    create?: (input: ImagePluginInput) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
+    /** 可选：查询图片生成任务状态，通常传入 `(input) => city.ai.imageJobStatus(input)`。 */
+    status?: (input: {
+        job_id: string;
+    }) => Promise<ImagePluginJobStatusResult> | ImagePluginJobStatusResult;
+    /** 可选：读取图片生成任务结果，通常传入 `(input) => city.ai.imageJobResult(input)`。 */
+    result?: (input: {
+        job_id: string;
+    }) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
+    /** 兼容 `generate` 动作等待任务完成的最长毫秒数。 */
+    wait_timeout_ms?: number;
+    /** 兼容 `generate` 动作每次轮询间隔毫秒数。 */
+    poll_interval_ms?: number;
 }
 //# sourceMappingURL=ImagePlugin.d.ts.map

package/bin/types/plugin/ImagePlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImagePlugin.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/ImagePlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kBAAkB;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,gBAAgB;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY;IACZ,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,oBAAoB;IACpB,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC,cAAc;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC9B,qCAAqC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,EAAE,GAAG,SAAS,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,KAAK,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;CACpF"}
+{"version":3,"file":"ImagePlugin.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/ImagePlugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.86",
+  "version": "1.1.92",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -29,7 +29,7 @@
     "node-cron": "^4.2.1",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@downcity/type": "0.1.23"
+    "@downcity/type": "0.1.27"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/scripts/assistant-file-resource.test.mjs

@@ -0,0 +1,91 @@
+/**
+ * @file 验证 assistant file part 会把 data URL 资源落盘为 file:// URL。
+ *
+ * 关键点（中文）
+ * - 历史消息不应长期保存图片 base64。
+ * - 送模型前可以从 file:// 临时 hydrate 回 data URL。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { materializeAssistantFileParts } from "../bin/executor/messages/AssistantFileResource.js";
+import { hydrateFileUrlPartsForModel } from "../bin/executor/messages/SessionAttachmentMapper.js";
+
+test("materializeAssistantFileParts stores data URL images under .downcity/resources", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-assistant-resource-"),
+  );
+  const bytes = Buffer.from("png-bytes-for-test", "utf8");
+  const data_url = `data:image/png;base64,${bytes.toString("base64")}`;
+
+  const parts = await materializeAssistantFileParts({
+    projectRoot: project_root,
+    parts: [
+      {
+        type: "file",
+        mediaType: "image/png",
+        filename: "image-1.png",
+        url: data_url,
+      },
+    ],
+  });
+
+  assert.equal(parts.length, 1);
+  assert.equal(parts[0].type, "file");
+  assert.equal(parts[0].mediaType, "image/png");
+  assert.equal(parts[0].filename, "image-1.png");
+  assert.match(parts[0].url, /^file:\/\//);
+  assert.equal(parts[0].url.includes("base64"), false);
+
+  const resource_path = fileURLToPath(parts[0].url);
+  assert.equal(
+    path.dirname(resource_path),
+    path.join(project_root, ".downcity", "resources"),
+  );
+  assert.deepEqual(await fs.readFile(resource_path), bytes);
+});
+
+test("hydrateFileUrlPartsForModel converts persisted file URLs back to data URLs in memory", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-assistant-hydrate-"),
+  );
+  const bytes = Buffer.from("hydrate-bytes-for-test", "utf8");
+  const materialized = await materializeAssistantFileParts({
+    projectRoot: project_root,
+    parts: [
+      {
+        type: "file",
+        mediaType: "image/png",
+        filename: "image-1.png",
+        url: `data:image/png;base64,${bytes.toString("base64")}`,
+      },
+    ],
+  });
+
+  const messages = await hydrateFileUrlPartsForModel([
+    {
+      id: "a:test:1",
+      role: "assistant",
+      metadata: {
+        v: 1,
+        ts: Date.now(),
+        sessionId: "session_test",
+      },
+      parts: materialized,
+    },
+  ]);
+
+  const hydrated_part = messages[0]?.parts[0];
+  assert.equal(hydrated_part?.type, "file");
+  assert.equal(hydrated_part?.mediaType, "image/png");
+  assert.equal(
+    hydrated_part?.url,
+    `data:image/png;base64,${bytes.toString("base64")}`,
+  );
+  assert.match(materialized[0].url, /^file:\/\//);
+});

package/scripts/image-plugin-job.test.mjs

@@ -0,0 +1,155 @@
+/**
+ * @file 验证 ImagePlugin 的可观察图片任务协议。
+ *
+ * 关键点（中文）
+ * - `create` 应快速返回 job_id，而不是同步等待图片完成。
+ * - `status/result` 可查询同一个任务，成功后 result 返回 UIMessage。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { ImagePlugin } from "../bin/index.js";
+
+function create_image_message() {
+  return {
+    id: "msg_image_test",
+    role: "assistant",
+    parts: [
+      {
+        type: "file",
+        mediaType: "image/png",
+        filename: "image.png",
+        url: "data:image/png;base64,cG5n",
+      },
+    ],
+  };
+}
+
+test("ImagePlugin create/status/result exposes async image jobs", async () => {
+  let finish_image;
+  const image_promise = new Promise((resolve) => {
+    finish_image = () => resolve(create_image_message());
+  });
+  const plugin = new ImagePlugin({
+    image: async () => image_promise,
+    poll_interval_ms: 1,
+    wait_timeout_ms: 100,
+  });
+
+  const created = await plugin.actions.create.execute({
+    context: {},
+    payload: { prompt: "draw" },
+    pluginName: "image",
+    actionName: "create",
+  });
+
+  assert.equal(created.success, true);
+  assert.equal(created.data.status, "running");
+  assert.match(created.data.job_id, /^img_/);
+
+  const before = await plugin.actions.status.execute({
+    context: {},
+    payload: { job_id: created.data.job_id },
+    pluginName: "image",
+    actionName: "status",
+  });
+
+  assert.equal(before.success, true);
+  assert.equal(before.data.status, "running");
+
+  finish_image();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  const after = await plugin.actions.status.execute({
+    context: {},
+    payload: { job_id: created.data.job_id },
+    pluginName: "image",
+    actionName: "status",
+  });
+
+  assert.equal(after.success, true);
+  assert.equal(after.data.status, "succeeded");
+  assert.equal("result" in after.data, false);
+
+  const result = await plugin.actions.result.execute({
+    context: {},
+    payload: { job_id: created.data.job_id },
+    pluginName: "image",
+    actionName: "result",
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.data.role, "assistant");
+  assert.equal(result.data.parts[0].type, "file");
+});
+
+test("ImagePlugin accepts custom job API without synchronous image function", async () => {
+  const message = create_image_message();
+  const plugin = new ImagePlugin({
+    create: () => ({
+      job_id: "img_custom",
+      status: "running",
+      poll_after_ms: 1,
+    }),
+    status: () => ({
+      job_id: "img_custom",
+      status: "succeeded",
+    }),
+    result: () => ({
+      job_id: "img_custom",
+      status: "succeeded",
+      result: message,
+    }),
+  });
+
+  const created = await plugin.actions.create.execute({
+    context: {},
+    payload: { prompt: "draw" },
+    pluginName: "image",
+    actionName: "create",
+  });
+
+  assert.equal(created.success, true);
+  assert.equal(created.data.job_id, "img_custom");
+
+  const result = await plugin.actions.result.execute({
+    context: {},
+    payload: { job_id: "img_custom" },
+    pluginName: "image",
+    actionName: "result",
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.data.parts[0].type, "file");
+});
+
+test("ImagePlugin strips accidental result data from custom status responses", async () => {
+  const plugin = new ImagePlugin({
+    create: () => ({
+      job_id: "img_status_result",
+      status: "succeeded",
+    }),
+    status: () => ({
+      job_id: "img_status_result",
+      status: "succeeded",
+      result: create_image_message(),
+    }),
+    result: () => ({
+      job_id: "img_status_result",
+      status: "succeeded",
+      result: create_image_message(),
+    }),
+  });
+
+  const status = await plugin.actions.status.execute({
+    context: {},
+    payload: { job_id: "img_status_result" },
+    pluginName: "image",
+    actionName: "status",
+  });
+
+  assert.equal(status.success, true);
+  assert.equal(status.data.status, "succeeded");
+  assert.equal("result" in status.data, false);
+});

package/scripts/linux-bubblewrap-sandbox.test.mjs

@@ -0,0 +1,142 @@
+/**
+ * @file 验证 Linux bubblewrap sandbox 参数生成。
+ *
+ * 关键点（中文）
+ * - 测试编译后的 bin 输出，避免测试文件进入 package 源码导出面。
+ * - 不启动真实 `bwrap`，只锁住路径挂载、网络开关与 shell 调用参数。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { buildLinuxBubblewrapArgs } from "../bin/sandbox/LinuxBubblewrapSandbox.js";
+
+async function createSandboxFixture() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-bwrap-"));
+  const projectRoot = path.join(root, "project");
+  const writablePath = path.join(projectRoot, ".downcity");
+  const shellDir = path.join(writablePath, "shell", "sh_test");
+  const shellHomeDir = path.join(shellDir, "sandbox", "home");
+  const shellTmpDir = path.join(shellDir, "sandbox", "tmp");
+
+  await fs.mkdir(shellHomeDir, { recursive: true });
+  await fs.mkdir(shellTmpDir, { recursive: true });
+
+  return {
+    root,
+    projectRoot,
+    writablePath,
+    shellDir,
+    shellHomeDir,
+    shellTmpDir,
+  };
+}
+
+function createParams(fixture, overrides = {}) {
+  return {
+    shellId: "sh_test",
+    shellDir: fixture.shellDir,
+    cmd: "printf hello",
+    cwd: fixture.projectRoot,
+    actualCwd: fixture.projectRoot,
+    shellPath: "/bin/sh",
+    login: true,
+    baseEnv: {
+      PATH: "/usr/bin:/bin",
+      LANG: "C.UTF-8",
+      DC_SESSION_ID: "session_test",
+    },
+    config: {
+      backend: "linux-bubblewrap",
+      rootPath: fixture.projectRoot,
+      envAllowlist: ["PATH", "LANG"],
+      writablePaths: [fixture.writablePath],
+      networkMode: "off",
+    },
+    shellHomeDir: fixture.shellHomeDir,
+    shellTmpDir: fixture.shellTmpDir,
+    ...overrides,
+  };
+}
+
+function hasArg(args, value) {
+  return args.includes(value);
+}
+
+function hasOptionPair(args, option, sourcePath, targetPath = sourcePath) {
+  for (let index = 0; index < args.length - 2; index += 1) {
+    if (
+      args[index] === option &&
+      args[index + 1] === sourcePath &&
+      args[index + 2] === targetPath
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function hasOptionValue(args, option, value) {
+  for (let index = 0; index < args.length - 1; index += 1) {
+    if (args[index] === option && args[index + 1] === value) {
+      return true;
+    }
+  }
+  return false;
+}
+
+test("Linux bubblewrap args isolate network and overlay writable project paths", async () => {
+  const fixture = await createSandboxFixture();
+  try {
+    const args = buildLinuxBubblewrapArgs(createParams(fixture));
+
+    assert.equal(hasArg(args, "--die-with-parent"), true);
+    assert.equal(hasArg(args, "--unshare-pid"), true);
+    assert.equal(hasArg(args, "--unshare-net"), true);
+    assert.equal(hasOptionPair(args, "--ro-bind", fixture.projectRoot), true);
+    assert.equal(hasOptionPair(args, "--bind", fixture.writablePath), true);
+    assert.equal(hasOptionPair(args, "--bind", fixture.projectRoot), false);
+    assert.equal(hasOptionValue(args, "--dir", fixture.writablePath), false);
+    assert.deepEqual(args.slice(-5), [
+      "--chdir",
+      fixture.projectRoot,
+      "/bin/sh",
+      "-lc",
+      "printf hello",
+    ]);
+  } finally {
+    await fs.rm(fixture.root, { recursive: true, force: true });
+  }
+});
+
+test("Linux bubblewrap args keep root writable when sandbox writablePaths includes root", async () => {
+  const fixture = await createSandboxFixture();
+  try {
+    const args = buildLinuxBubblewrapArgs(createParams(fixture, {
+      config: {
+        backend: "linux-bubblewrap",
+        rootPath: fixture.projectRoot,
+        envAllowlist: ["PATH"],
+        writablePaths: [fixture.projectRoot],
+        networkMode: "full",
+      },
+      login: false,
+    }));
+
+    assert.equal(hasArg(args, "--unshare-net"), false);
+    assert.equal(hasOptionPair(args, "--bind", fixture.projectRoot), true);
+    assert.equal(hasOptionPair(args, "--ro-bind", fixture.projectRoot), false);
+    assert.deepEqual(args.slice(-5), [
+      "--chdir",
+      fixture.projectRoot,
+      "/bin/sh",
+      "-c",
+      "printf hello",
+    ]);
+  } finally {
+    await fs.rm(fixture.root, { recursive: true, force: true });
+  }
+});

package/scripts/shell-sandbox-preflight.test.mjs

@@ -0,0 +1,88 @@
+/**
+ * @file 验证 shell sandbox 启动前依赖诊断。
+ *
+ * 关键点（中文）
+ * - 测试编译后的 bin 输出，避免测试文件进入 package 源码导出面。
+ * - 通过注入探针模拟 Linux 依赖状态，不要求当前测试机安装 bwrap。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  checkShellSandboxPreflightWithProbe,
+} from "../bin/sandbox/SandboxPreflight.js";
+
+async function withPlatform(platform, callback) {
+  const previous = Object.getOwnPropertyDescriptor(process, "platform");
+  Object.defineProperty(process, "platform", {
+    configurable: true,
+    value: platform,
+  });
+  try {
+    return await callback();
+  } finally {
+    if (previous) {
+      Object.defineProperty(process, "platform", previous);
+    }
+  }
+}
+
+function createProbe(params) {
+  return {
+    commandExists: async (command) => params.commands?.has(command) === true,
+    readProcInt: async (filePath) => params.proc?.get(filePath) ?? null,
+  };
+}
+
+test("Linux shell sandbox preflight reports missing bwrap and disabled userns", async () => {
+  await withPlatform("linux", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(),
+      proc: new Map([
+        ["/proc/sys/kernel/unprivileged_userns_clone", 0],
+        ["/proc/sys/user/max_user_namespaces", 0],
+      ]),
+    }));
+
+    assert.equal(result.ok, false);
+    assert.equal(result.backend, "linux-bubblewrap");
+    assert.deepEqual(
+      result.issues.map((issue) => issue.code),
+      ["missing-command", "userns-disabled"],
+    );
+    assert.match(result.issues[0].message, /bubblewrap/);
+    assert.match(result.issues[1].message, /user namespaces/);
+  });
+});
+
+test("Linux shell sandbox preflight accepts bwrap with enabled userns", async () => {
+  await withPlatform("linux", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(["bwrap"]),
+      proc: new Map([
+        ["/proc/sys/kernel/unprivileged_userns_clone", 1],
+        ["/proc/sys/user/max_user_namespaces", 1024],
+      ]),
+    }));
+
+    assert.equal(result.ok, true);
+    assert.equal(result.backend, "linux-bubblewrap");
+    assert.deepEqual(result.issues, []);
+  });
+});
+
+test("Unsupported platforms fail shell sandbox preflight", async () => {
+  await withPlatform("win32", async () => {
+    const result = await checkShellSandboxPreflightWithProbe(createProbe({
+      commands: new Set(),
+      proc: new Map(),
+    }));
+
+    assert.equal(result.ok, false);
+    assert.deepEqual(
+      result.issues.map((issue) => issue.code),
+      ["unsupported-platform"],
+    );
+  });
+});

package/src/config/AgentInitializer.ts

@@ -27,6 +27,7 @@ import {
   getDowncityProfileOtherPath,
   getDowncityProfilePrimaryPath,
   getDowncityPublicDirPath,
+  getDowncityResourcesDirPath,
   getDowncitySchemaPath,
   getDowncityTasksDirPath,
   getSoulMdPath,
@@ -229,6 +230,7 @@ export async function initializeAgentProject(
     getDowncityDataDirPath(projectRoot),
     getDowncityAgentsRootDirPath(projectRoot),
     getDowncityPublicDirPath(projectRoot),
+    getDowncityResourcesDirPath(projectRoot),
     getDowncityConfigDirPath(projectRoot),
     path.join(projectRoot, ".agents", "skills"),
     path.join(getDowncityDirPath(projectRoot), "schema"),

package/src/config/Paths.ts

@@ -331,6 +331,17 @@ export function getDowncityPublicDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "public");
 }
 
+/**
+ * 返回项目资源目录路径。
+ *
+ * 关键点（中文）
+ * - 该目录用于存放会话历史引用的二进制资源，例如图片生成结果。
+ * - `messages.jsonl` 只保存 `file://` 绝对 URL，避免把大段 base64 长期写入历史。
+ */
+export function getDowncityResourcesDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "resources");
+}
+
 /**
  * 返回项目任务目录路径。
  *

package/src/executor/Executor.ts

@@ -375,6 +375,9 @@ export class Executor implements SessionExecutor {
   ): SessionRunContext {
     return {
       sessionId: String(input?.sessionId || this.sessionId).trim(),
+      ...(typeof input?.projectRoot === "string" && input.projectRoot.trim()
+        ? { projectRoot: input.projectRoot.trim() }
+        : {}),
       ...(typeof input?.onStepCallback === "function"
         ? { onStepCallback: input.onStepCallback }
         : {}),