@downcity/agent 1.1.160 → 1.1.162

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

@@ -1,9 +1,9 @@
 /**
- * @file 验证 assistant file part 会把资源落盘为 resources:// URL。
+ * @file 验证 assistant file part 会把资源落盘为 Agent 根目录相对路径。
  *
  * 关键点（中文）
  * - 历史消息不应长期保存图片 base64。
- * - 送模型前可以从 resources:// 临时 hydrate 回 data URL。
+ * - 送模型前可以从 Agent 根目录相对路径临时 hydrate 回 data URL。
  */
 
 import test from "node:test";
@@ -15,10 +15,13 @@ import http from "node:http";
 import { pathToFileURL } from "node:url";
 
 import { materializeAssistantFileParts } from "../bin/executor/messages/AssistantFileResource.js";
-import { hydrateFileUrlPartsForModel } from "../bin/executor/messages/SessionAttachmentMapper.js";
+import {
+  hydrateFileUrlPartsForModel,
+  injectFilePartsFromAttachments,
+} from "../bin/executor/messages/SessionAttachmentMapper.js";
 
-function resource_path_from_url(project_root, url) {
-  return path.join(project_root, String(url || "").replace(/^resources:\/\//, ""));
+function resource_path_from_relative_path(project_root, relative_path) {
+  return path.join(project_root, String(relative_path || ""));
 }
 
 test("materializeAssistantFileParts stores data URL images under .downcity/resources", async () => {
@@ -44,10 +47,10 @@ test("materializeAssistantFileParts stores data URL images under .downcity/resou
   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, /^resources:\/\/\.downcity\/resources\//);
+  assert.match(parts[0].url, /^\.downcity\/resources\//);
   assert.equal(parts[0].url.includes("base64"), false);
 
-  const resource_path = resource_path_from_url(project_root, parts[0].url);
+  const resource_path = resource_path_from_relative_path(project_root, parts[0].url);
   assert.equal(
     path.dirname(resource_path),
     path.join(project_root, ".downcity", "resources"),
@@ -84,10 +87,10 @@ test("materializeAssistantFileParts downloads remote file URLs into resources",
       ],
     });
 
-    assert.match(parts[0].url, /^resources:\/\/\.downcity\/resources\//);
+    assert.match(parts[0].url, /^\.downcity\/resources\//);
     assert.equal(parts[0].url.startsWith("http://"), false);
     assert.deepEqual(
-      await fs.readFile(resource_path_from_url(project_root, parts[0].url)),
+      await fs.readFile(resource_path_from_relative_path(project_root, parts[0].url)),
       bytes,
     );
   } finally {
@@ -97,7 +100,33 @@ test("materializeAssistantFileParts downloads remote file URLs into resources",
   }
 });
 
-test("hydrateFileUrlPartsForModel converts resources URLs back to data URLs in memory", async () => {
+test("materializeAssistantFileParts resolves relative local file URLs from agent project root", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-assistant-relative-resource-"),
+  );
+  const bytes = Buffer.from("relative-local-png-bytes", "utf8");
+  await fs.writeFile(path.join(project_root, "input.png"), bytes);
+
+  const parts = await materializeAssistantFileParts({
+    projectRoot: project_root,
+    parts: [
+      {
+        type: "file",
+        mediaType: "image/png",
+        filename: "input.png",
+        url: "./input.png",
+      },
+    ],
+  });
+
+  assert.match(parts[0].url, /^\.downcity\/resources\//);
+  assert.deepEqual(
+    await fs.readFile(resource_path_from_relative_path(project_root, parts[0].url)),
+    bytes,
+  );
+});
+
+test("hydrateFileUrlPartsForModel converts relative resource paths back to data URLs in memory", async () => {
   const project_root = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-assistant-hydrate-"),
   );
@@ -137,7 +166,7 @@ test("hydrateFileUrlPartsForModel converts resources URLs back to data URLs in m
     hydrated_part?.url,
     `data:image/png;base64,${bytes.toString("base64")}`,
   );
-  assert.match(materialized[0].url, /^resources:\/\/\.downcity\/resources\//);
+  assert.match(materialized[0].url, /^\.downcity\/resources\//);
 });
 
 test("hydrateFileUrlPartsForModel keeps old file URLs compatible", async () => {
@@ -178,3 +207,40 @@ test("hydrateFileUrlPartsForModel keeps old file URLs compatible", async () => {
     `data:image/png;base64,${bytes.toString("base64")}`,
   );
 });
+
+test("injectFilePartsFromAttachments resolves relative file tags from agent project root", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-attachment-relative-"),
+  );
+  const bytes = Buffer.from("attachment-relative-png-bytes", "utf8");
+  await fs.writeFile(path.join(project_root, "input.png"), bytes);
+
+  const messages = await injectFilePartsFromAttachments(
+    [
+      {
+        id: "u:test:attachment",
+        role: "user",
+        metadata: {
+          v: 1,
+          ts: Date.now(),
+          sessionId: "session_test",
+        },
+        parts: [
+          {
+            type: "text",
+            text: '<file type="photo">./input.png</file>',
+          },
+        ],
+      },
+    ],
+    project_root,
+  );
+
+  const injected_part = messages[0]?.parts[1];
+  assert.equal(injected_part?.type, "file");
+  assert.equal(injected_part?.mediaType, "image/png");
+  assert.equal(
+    injected_part?.url,
+    `data:image/png;base64,${bytes.toString("base64")}`,
+  );
+});

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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 插件只暴露 image_create / image_result 两个任务 action。
- * - image_result 只读取一次当前状态，不在 plugin 层等待终态。
+ * - image_result 默认只读取一次当前状态；传 until_done=true 时会在 plugin 层等待终态。
  * - 成功图片仍以 UIMessage 返回，后续由 plugin bridge 落盘 file parts。
  */
 
@@ -132,6 +132,7 @@ test("ImagePlugin exposes action metadata through plugin registry", async () =>
   assert.equal(metadata.actions[0].name, "image_create");
   assert.equal(metadata.actions[0].has_input_schema, true);
   assert.match(metadata.actions[0].description, /Create an async image job/);
+  assert.match(metadata.actions[0].description, /explicit user confirmation/);
   assert.equal(metadata.actions[0].examples[0].payload.prompt.includes("rainy city"), true);
 });
 

package/scripts/plugin-tool-bridge.test.mjs

@@ -2,8 +2,8 @@
  * @file 验证 plugin tool bridge 会把生成文件摘要为可打开路径。
  *
  * 关键点（中文）
- * - assistant message 仍然使用 `resources://` URL，避免历史暴露本机路径。
- * - tool result 额外返回本机绝对路径，便于模型与用户明确知道文件位置。
+ * - assistant message 使用 Agent 根目录相对路径，避免历史暴露本机路径。
+ * - tool result 同时返回相对路径与本机绝对路径，便于模型与用户明确知道文件位置。
  */
 
 import test from "node:test";
@@ -78,7 +78,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
   assert.equal(result.success, true);
   assert.equal(result.assistant_file_count, 1);
   assert.equal(result.files?.length, 1);
-  assert.match(result.files[0].url, /^resources:\/\/\.downcity\/resources\//);
+  assert.match(result.files[0].relative_path, /^\.downcity\/resources\//);
   assert.equal(path.isAbsolute(result.files[0].path), true);
   assert.equal(
     path.dirname(result.files[0].path),
@@ -89,7 +89,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
 
   const pending_parts = run_context.pendingAssistantFileParts;
   assert.equal(pending_parts.length, 1);
-  assert.equal(pending_parts[0].url, result.files[0].url);
+  assert.equal(pending_parts[0].url, result.files[0].relative_path);
 });
 
 test("invokePluginReadTool returns plugin action metadata", async () => {

package/src/config/Paths.ts

@@ -336,7 +336,7 @@ export function getDowncityPublicDirPath(cwd: string): string {
  *
  * 关键点（中文）
  * - 该目录用于存放会话历史引用的二进制资源，例如图片生成结果。
- * - `messages.jsonl` 只保存 `resources://` 相对 URL，避免暴露本机绝对路径或长期保存 base64。
+ * - `messages.jsonl` 只保存 Agent 根目录相对路径，避免暴露本机绝对路径或长期保存 base64。
  */
 export function getDowncityResourcesDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "resources");

package/src/executor/core-engine/CoreEngineMessageState.ts

@@ -34,7 +34,7 @@ export class CoreEngineMessageState {
   private readonly tools: Record<string, Tool>;
 
   /**
-   * 当前项目根目录，用于解析历史中的 `resources://` file part。
+   * 当前项目根目录，用于解析历史中的相对路径 file part。
    */
   private readonly projectRoot?: string;
 

package/src/executor/messages/AssistantFileResource.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 只处理运行期产生的 assistant file part，不参与 user 附件注入。
  * - 将 data URL、远程 URL 与本地文件统一写入 `.downcity/resources`。
- * - 历史中只保留 `resources://<project-relative-path>`，避免暴露本机绝对路径。
+ * - 历史中只保留基于 Agent 项目根目录的相对路径，避免暴露本机绝对路径。
  * - 资源文件按内容 hash 命名，天然去重并避免重复写入大文件。
  */
 
@@ -34,8 +34,8 @@ export interface MaterializeAssistantFilePartsParams {
    * 当前项目根目录。
    *
    * 关键点（中文）
-   * - 正常 session run 会显式传入 projectRoot。
-   * - 旧入口未传时回退到 `process.cwd()`，保证行为可用。
+   * - 正常 session run 必须显式传入 projectRoot。
+   * - 旧入口未传时仅为兼容回退到 `process.cwd()`。
    */
   projectRoot?: string;
 
@@ -102,12 +102,58 @@ function filename_from_url(raw_url: string): string | undefined {
   }
 }
 
-function to_resources_url(projectRoot: string, filePath: string): string {
+/**
+ * 将项目内文件路径转换为基于 Agent 根目录的相对路径。
+ */
+export function toAgentRelativePath(params: {
+  /**
+   * 当前 Agent 项目根目录。
+   */
+  projectRoot: string;
+  /**
+   * 项目内文件绝对路径。
+   */
+  filePath: string;
+}): string {
+  const project_root = resolve_project_root(params.projectRoot);
   const relative = path
-    .relative(projectRoot, filePath)
+    .relative(project_root, params.filePath)
     .split(path.sep)
     .join("/");
-  return `resources://${relative}`;
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Assistant resource path is outside agent root: ${params.filePath}`);
+  }
+  return relative;
+}
+
+/**
+ * 将相对路径解析为 Agent 项目内绝对路径。
+ *
+ * 关键点（中文）
+ * - 相对路径统一基于 Agent 项目根目录解析。
+ * - 绝对路径原样归一化后返回。
+ * - 越界路径返回空字符串，由调用方决定是否忽略。
+ */
+export function resolveAgentFilePath(params: {
+  /**
+   * 当前 Agent 项目根目录。
+   */
+  projectRoot: string;
+  /**
+   * 待解析的相对路径或绝对路径。
+   */
+  filePath: string;
+}): string {
+  const raw = String(params.filePath || "").trim();
+  if (!raw) return "";
+  const project_root = resolve_project_root(params.projectRoot);
+  const file_path = path.isAbsolute(raw)
+    ? path.resolve(raw)
+    : path.resolve(project_root, raw);
+  if (path.isAbsolute(raw)) return file_path;
+  const rel = path.relative(project_root, file_path);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return "";
+  return file_path;
 }
 
 async function write_resource_file(params: {
@@ -258,8 +304,6 @@ async function materialize_file_part(params: {
   if (!raw_url) {
     throw new Error("Assistant file part url is required");
   }
-  if (raw_url.startsWith("resources://")) return params.part;
-
   const parsed_data_url = parse_data_url(raw_url);
   if (parsed_data_url) {
     const media_type =
@@ -275,7 +319,10 @@ async function materialize_file_part(params: {
     return {
       ...params.part,
       mediaType: media_type,
-      url: to_resources_url(params.projectRoot, file_path),
+      url: toAgentRelativePath({
+        projectRoot: params.projectRoot,
+        filePath: file_path,
+      }),
     };
   }
 
@@ -297,7 +344,10 @@ async function materialize_file_part(params: {
       return {
         ...params.part,
         mediaType: media_type,
-        url: to_resources_url(params.projectRoot, file_path),
+        url: toAgentRelativePath({
+          projectRoot: params.projectRoot,
+          filePath: file_path,
+        }),
       };
     } catch (error) {
       // 关键点（中文）：远程下载失败时保留原始 URL，不让整张图导致 action 失败。
@@ -325,12 +375,15 @@ async function materialize_file_part(params: {
   return {
     ...params.part,
     mediaType: media_type,
-    url: to_resources_url(params.projectRoot, file_path),
+    url: toAgentRelativePath({
+      projectRoot: params.projectRoot,
+      filePath: file_path,
+    }),
   };
 }
 
 /**
- * 将 assistant file part 中的资源统一落盘为 `resources://` 相对 URL。
+ * 将 assistant file part 中的资源统一落盘为 Agent 根目录相对路径。
  */
 export async function materializeAssistantFileParts(
   params: MaterializeAssistantFilePartsParams,

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -5,7 +5,7 @@
  * - 兼容 Telegram / Feishu / TUI 等统一的 `<file>` 协议入口。
  * - 仅在本轮执行的内存消息上追加 file parts，不修改持久化历史。
  * - 当前只为图片与 PDF 注入 file part，保持多模态模型可直接消费。
- * - 历史中的 `resources://` 与旧版 `file://` 会在喂给模型前临时 hydrate。
+ * - 历史中的相对路径与旧版 `file://` 会在喂给模型前临时 hydrate。
  */
 
 import fs from "fs-extra";
@@ -63,18 +63,17 @@ function buildDataUrl(mediaType: string, buffer: Buffer): string {
   return `data:${safeType};base64,${base64}`;
 }
 
-function resolveResourcesUrlPath(
+function resolveHydratableFilePath(
   projectRoot: string | undefined,
-  rawUrl: string,
+  rawPath: string,
 ): string | null {
-  const prefix = "resources://";
-  const raw = String(rawUrl || "").trim();
-  if (!raw.startsWith(prefix)) return null;
-  const relative = raw.slice(prefix.length).replace(/^\/+/, "");
-  if (!relative) return null;
+  const raw = String(rawPath || "").trim();
+  if (!raw || raw.startsWith("data:") || /^https?:\/\//i.test(raw)) return null;
+  if (raw.startsWith("file://")) return fileURLToPath(raw);
+  if (path.isAbsolute(raw)) return path.resolve(raw);
 
   const root = path.resolve(String(projectRoot || "").trim() || process.cwd());
-  const absPath = path.resolve(root, relative);
+  const absPath = path.resolve(root, raw);
   const rel = path.relative(root, absPath);
   if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
   return absPath;
@@ -85,14 +84,13 @@ async function hydrateFileUrlPart(
   projectRoot?: string,
 ): Promise<FileUIPart> {
   const url = String(part.url || "").trim();
-  const resourcesPath = resolveResourcesUrlPath(projectRoot, url);
-  if (!url.startsWith("file://") && !resourcesPath) return part;
+  const filePath = resolveHydratableFilePath(projectRoot, url);
+  if (!filePath) return part;
   try {
-    const absPath = resourcesPath || fileURLToPath(url);
-    const buffer = await fs.readFile(absPath);
+    const buffer = await fs.readFile(filePath);
     const mediaType =
       String(part.mediaType || "").trim() ||
-      guessAttachmentMediaTypeFromPath(absPath) ||
+      guessAttachmentMediaTypeFromPath(filePath) ||
       "application/octet-stream";
     return {
       ...part,
@@ -109,7 +107,7 @@ async function hydrateFileUrlPart(
  *
  * 关键点（中文）
  * - 该函数只修改本轮内存消息，不回写历史。
- * - 新历史保留 `resources://` 相对 URL，旧历史的 `file://` 仍继续兼容。
+ * - 新历史保留 Agent 根目录相对路径，旧历史的 `file://` 仍继续兼容。
  */
 export async function hydrateFileUrlPartsForModel(
   messages: SessionMessageV1[],
@@ -148,10 +146,11 @@ export async function hydrateFileUrlPartsForModel(
  */
 export async function injectFilePartsFromAttachments(
   messages: SessionMessageV1[],
+  projectRoot?: string,
 ): Promise<SessionMessageV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
-  const cwd = process.cwd();
+  const root = path.resolve(String(projectRoot || "").trim() || process.cwd());
   const out: SessionMessageV1[] = [];
 
   for (const message of messages) {
@@ -203,7 +202,7 @@ export async function injectFilePartsFromAttachments(
 
       const absPath = path.isAbsolute(attachment.path)
         ? attachment.path
-        : path.resolve(cwd, attachment.path);
+        : path.resolve(root, attachment.path);
       try {
         const exists = await fs.pathExists(absPath);
         if (!exists) continue;

package/src/executor/messages/SessionMessageCodec.ts

@@ -78,7 +78,10 @@ export async function toModelMessages(
   if (!Array.isArray(messages) || messages.length === 0) return [];
 
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
-  const enrichedMessages = await injectFilePartsFromAttachments(messages);
+  const enrichedMessages = await injectFilePartsFromAttachments(
+    messages,
+    projectRoot,
+  );
 
   // 第二步（中文）：把历史里的资源 URL 在内存中 hydrate 成模型可消费的 data URL。
   const hydratedMessages = await hydrateFileUrlPartsForModel(

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

@@ -18,7 +18,10 @@ import type {
   PluginReadInput,
   PluginReadToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
-import { materializeAssistantFileParts } from "@executor/messages/AssistantFileResource.js";
+import {
+  materializeAssistantFileParts,
+  resolveAgentFilePath,
+} from "@executor/messages/AssistantFileResource.js";
 import {
   enqueueAssistantFileParts,
   getSessionRunContext,
@@ -81,25 +84,6 @@ function resolve_project_root(project_root: string | undefined): string {
   return path.resolve(raw || process.cwd());
 }
 
-/**
- * 将 `resources://` URL 转成本机绝对路径。
- */
-function resolve_resources_file_path(
-  project_root: string,
-  raw_url: string,
-): string {
-  const prefix = "resources://";
-  const raw = String(raw_url || "").trim();
-  if (!raw.startsWith(prefix)) return "";
-  const relative = raw.slice(prefix.length).replace(/^\/+/, "");
-  if (!relative) return "";
-
-  const file_path = path.resolve(project_root, relative);
-  const rel = path.relative(project_root, file_path);
-  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return "";
-  return file_path;
-}
-
 /**
  * 构建返回给模型和用户可见的文件摘要。
  */
@@ -107,13 +91,19 @@ function summarize_materialized_files(
   parts: FileUIPart[],
   project_root: string,
 ): PluginCallToolFileResult[] {
-  return parts.map((part, index) => ({
-    index,
-    media_type: part.mediaType,
-    filename: typeof part.filename === "string" ? part.filename : "",
-    url: String(part.url || ""),
-    path: resolve_resources_file_path(project_root, String(part.url || "")),
-  }));
+  return parts.map((part, index) => {
+    const relative_path = String(part.url || "");
+    return {
+      index,
+      media_type: part.mediaType,
+      filename: typeof part.filename === "string" ? part.filename : "",
+      relative_path,
+      path: resolveAgentFilePath({
+        projectRoot: project_root,
+        filePath: relative_path,
+      }),
+    };
+  });
 }
 
 /**

package/src/executor/tools/plugin/types/PluginTool.ts

@@ -40,9 +40,9 @@ export interface PluginCallToolFileResult {
   media_type: string;
   /** 原始文件名；若上游未提供则为空字符串。 */
   filename: string;
-  /** 持久化到历史消息中的资源 URL，通常为 `resources://.downcity/resources/...`。 */
-  url: string;
-  /** 当前机器可直接打开的绝对文件路径。 */
+  /** 基于 Agent 项目根目录的相对路径，例如 `.downcity/resources/xxx.png`。 */
+  relative_path: string;
+  /** 当前机器可直接打开的绝对文件路径，按 Agent 项目根目录解析。 */
   path: string;
 }