@downcity/agent 1.1.86 → 1.1.91

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/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 }
         : {}),

package/src/executor/messages/AssistantFileResource.ts

@@ -0,0 +1,155 @@
+/**
+ * AssistantFileResource：assistant file part 的本地资源落盘工具。
+ *
+ * 关键点（中文）
+ * - 只处理运行期产生的 assistant file part，不参与 user 附件注入。
+ * - 将 `data:*;base64,...` 写入 `.downcity/resources`，历史中只保留 `file://` 绝对 URL。
+ * - 资源文件按内容 hash 命名，天然去重并避免重复写入大文件。
+ */
+
+import crypto from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import fs from "fs-extra";
+import type { FileUIPart } from "ai";
+import { getDowncityResourcesDirPath } from "@/config/Paths.js";
+
+type ParsedDataUrl = {
+  /**
+   * data URL 声明的媒体类型。
+   */
+  media_type: string;
+  /**
+   * data URL 解码后的二进制内容。
+   */
+  bytes: Buffer;
+};
+
+/**
+ * assistant file part 资源落盘参数。
+ */
+export interface MaterializeAssistantFilePartsParams {
+  /**
+   * 当前项目根目录。
+   *
+   * 关键点（中文）
+   * - 正常 session run 会显式传入 projectRoot。
+   * - 旧入口未传时回退到 `process.cwd()`，保证行为可用。
+   */
+  projectRoot?: string;
+
+  /**
+   * 待处理的 assistant file parts。
+   */
+  parts: FileUIPart[];
+}
+
+function resolve_project_root(projectRoot: string | undefined): string {
+  const raw = String(projectRoot || "").trim();
+  return path.resolve(raw || process.cwd());
+}
+
+function parse_data_url(url: string): ParsedDataUrl | null {
+  const raw = String(url || "").trim();
+  if (!raw.startsWith("data:")) return null;
+  const comma_index = raw.indexOf(",");
+  if (comma_index < 0) return null;
+
+  const header = raw.slice(5, comma_index);
+  const body = raw.slice(comma_index + 1);
+  const header_parts = header.split(";").filter(Boolean);
+  const media_type =
+    header_parts.find((item) => item.includes("/")) || "application/octet-stream";
+  const is_base64 = header_parts.some((item) => item.toLowerCase() === "base64");
+
+  try {
+    const bytes = is_base64
+      ? Buffer.from(body, "base64")
+      : Buffer.from(decodeURIComponent(body), "utf8");
+    if (bytes.length === 0) return null;
+    return {
+      media_type,
+      bytes,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extension_from_media_type(mediaType: string): string {
+  const value = String(mediaType || "").toLowerCase();
+  if (value === "image/png") return ".png";
+  if (value === "image/jpeg" || value === "image/jpg") return ".jpg";
+  if (value === "image/webp") return ".webp";
+  if (value === "image/gif") return ".gif";
+  if (value === "application/pdf") return ".pdf";
+  return ".bin";
+}
+
+function extension_from_filename(filename: string | undefined): string {
+  const ext = path.extname(String(filename || "").trim()).toLowerCase();
+  if (!ext || ext.length > 12) return "";
+  return /^[.][a-z0-9]+$/u.test(ext) ? ext : "";
+}
+
+async function write_resource_file(params: {
+  projectRoot: string;
+  mediaType: string;
+  filename?: string;
+  bytes: Buffer;
+}): Promise<string> {
+  const hash = crypto.createHash("sha256").update(params.bytes).digest("hex");
+  const ext =
+    extension_from_filename(params.filename) ||
+    extension_from_media_type(params.mediaType);
+  const file_name = `${hash}${ext}`;
+  const resources_dir = getDowncityResourcesDirPath(params.projectRoot);
+  const file_path = path.join(resources_dir, file_name);
+
+  await fs.ensureDir(resources_dir);
+  try {
+    await fs.writeFile(file_path, params.bytes, { flag: "wx" });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "EEXIST") throw error;
+  }
+
+  return file_path;
+}
+
+/**
+ * 将 assistant file part 中的 data URL 资源落盘为 `file://` 绝对 URL。
+ */
+export async function materializeAssistantFileParts(
+  params: MaterializeAssistantFilePartsParams,
+): Promise<FileUIPart[]> {
+  const parts = Array.isArray(params.parts) ? params.parts : [];
+  if (parts.length === 0) return [];
+
+  const project_root = resolve_project_root(params.projectRoot);
+  const out: FileUIPart[] = [];
+
+  for (const part of parts) {
+    const parsed = parse_data_url(String(part.url || ""));
+    if (!parsed) {
+      out.push(part);
+      continue;
+    }
+
+    const media_type = String(part.mediaType || parsed.media_type || "").trim();
+    const file_path = await write_resource_file({
+      projectRoot: project_root,
+      mediaType: media_type || parsed.media_type,
+      filename: typeof part.filename === "string" ? part.filename : undefined,
+      bytes: parsed.bytes,
+    });
+
+    out.push({
+      ...part,
+      mediaType: media_type || parsed.media_type,
+      url: pathToFileURL(file_path).href,
+    });
+  }
+
+  return out;
+}

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -9,6 +9,7 @@
 
 import fs from "fs-extra";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   isFileUIPart,
   isTextUIPart,
@@ -61,6 +62,64 @@ function buildDataUrl(mediaType: string, buffer: Buffer): string {
   return `data:${safeType};base64,${base64}`;
 }
 
+async function hydrateFileUrlPart(part: FileUIPart): Promise<FileUIPart> {
+  const url = String(part.url || "").trim();
+  if (!url.startsWith("file://")) return part;
+  try {
+    const absPath = fileURLToPath(url);
+    const buffer = await fs.readFile(absPath);
+    const mediaType =
+      String(part.mediaType || "").trim() ||
+      guessAttachmentMediaTypeFromPath(absPath) ||
+      "application/octet-stream";
+    return {
+      ...part,
+      mediaType,
+      url: buildDataUrl(mediaType, buffer),
+    };
+  } catch {
+    return part;
+  }
+}
+
+/**
+ * 将历史中的 `file://` file part 临时转换为模型可消费的 data URL。
+ *
+ * 关键点（中文）
+ * - 该函数只修改本轮内存消息，不回写历史。
+ * - 持久化层继续保留轻量 `file://` 绝对 URL，避免 JSONL 存储 base64。
+ */
+export async function hydrateFileUrlPartsForModel(
+  messages: SessionMessageV1[],
+): Promise<SessionMessageV1[]> {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+
+  const out: SessionMessageV1[] = [];
+  for (const message of messages) {
+    const parts = Array.isArray(message?.parts) ? message.parts : [];
+    if (!parts.some((part) => isFileUIPart(part as FileUIPart))) {
+      out.push(message);
+      continue;
+    }
+
+    const nextParts: SessionMessageV1["parts"] = [];
+    let changed = false;
+    for (const part of parts) {
+      if (!isFileUIPart(part as FileUIPart)) {
+        nextParts.push(part);
+        continue;
+      }
+      const nextPart = await hydrateFileUrlPart(part as FileUIPart);
+      if (nextPart !== part) changed = true;
+      nextParts.push(nextPart as SessionMessageV1["parts"][number]);
+    }
+
+    out.push(changed ? { ...message, parts: nextParts } : message);
+  }
+
+  return out;
+}
+
 /**
  * 在 user 消息上注入 FileUIPart，以便多模态模型直接消费本地附件。
  */

package/src/executor/messages/SessionMessageCodec.ts

@@ -15,7 +15,10 @@ import {
   type ToolSet,
 } from "ai";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
-import { injectFilePartsFromAttachments } from "@executor/messages/SessionAttachmentMapper.js";
+import {
+  hydrateFileUrlPartsForModel,
+  injectFilePartsFromAttachments,
+} from "@executor/messages/SessionAttachmentMapper.js";
 
 /**
  * 过滤回调返回值中的 user 文本消息。
@@ -76,8 +79,11 @@ export async function toModelMessages(
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
   const enrichedMessages = await injectFilePartsFromAttachments(messages);
 
-  // 第二步（中文）：转换前先剔除 UI 层 id 字段，仅保留模型需要的数据结构。
-  const input = enrichedMessages.map((message) => {
+  // 第二步（中文）：把历史里的 file:// 资源在内存中 hydrate 成模型可消费的 data URL。
+  const hydratedMessages = await hydrateFileUrlPartsForModel(enrichedMessages);
+
+  // 第三步（中文）：转换前先剔除 UI 层 id 字段，仅保留模型需要的数据结构。
+  const input = hydratedMessages.map((message) => {
     // 解构去掉 id。
     const { id: _id, ...rest } = message;
 

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -14,7 +14,11 @@ import type {
   PluginCallInput,
   PluginCallToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
-import { enqueueAssistantFileParts } from "@executor/SessionRunScope.js";
+import { materializeAssistantFileParts } from "@executor/messages/AssistantFileResource.js";
+import {
+  enqueueAssistantFileParts,
+  getSessionRunContext,
+} from "@executor/SessionRunScope.js";
 
 let plugin_tool_runtime: PluginPort | null = null;
 
@@ -131,9 +135,16 @@ export async function invokePluginCallTool(
       action,
       payload,
     });
-    const file_parts = result.success
+    const raw_file_parts = result.success
       ? extract_assistant_file_parts(result.data)
       : [];
+    const file_parts =
+      raw_file_parts.length > 0
+        ? await materializeAssistantFileParts({
+            projectRoot: getSessionRunContext()?.projectRoot,
+            parts: raw_file_parts,
+          })
+        : [];
     if (file_parts.length > 0) {
       enqueueAssistantFileParts(file_parts);
     }

package/src/index.ts

@@ -229,6 +229,10 @@ export type {
   ImagePluginContent,
   ImagePluginFileContent,
   ImagePluginInput,
+  ImagePluginJobCreateResult,
+  ImagePluginJobResult,
+  ImagePluginJobStatus,
+  ImagePluginJobStatusResult,
   ImagePluginMessage,
   ImagePluginOptions,
   ImagePluginResult,