@downcity/agent 1.1.101 → 1.1.105

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

@@ -33,6 +33,11 @@ export class CoreEngineMessageState {
    */
   private readonly tools: Record<string, Tool>;
 
+  /**
+   * 当前项目根目录，用于解析历史中的 `resources://` file part。
+   */
+  private readonly projectRoot?: string;
+
   private constructor(params: {
     /**
      * 当前运行时 session 语义消息。
@@ -46,10 +51,15 @@ export class CoreEngineMessageState {
      * 当前轮可用工具集合。
      */
     tools: Record<string, Tool>;
+    /**
+     * 当前项目根目录。
+     */
+    projectRoot?: string;
   }) {
     this.sessionMessages = params.sessionMessages;
     this.currentModelMessages = params.modelMessages;
     this.tools = params.tools;
+    this.projectRoot = params.projectRoot;
   }
 
   /**
@@ -64,14 +74,23 @@ export class CoreEngineMessageState {
      * 当前轮可用工具集合。
      */
     tools: Record<string, Tool>;
+    /**
+     * 当前项目根目录。
+     */
+    projectRoot?: string;
   }): Promise<CoreEngineMessageState> {
     const sessionMessages = Array.isArray(params.messages)
       ? [...params.messages]
       : [];
     return new CoreEngineMessageState({
       sessionMessages,
-      modelMessages: await toModelMessages(sessionMessages, params.tools),
+      modelMessages: await toModelMessages(
+        sessionMessages,
+        params.tools,
+        params.projectRoot,
+      ),
       tools: params.tools,
+      projectRoot: params.projectRoot,
     });
   }
 
@@ -119,7 +138,11 @@ export class CoreEngineMessageState {
     messages: SessionMessageV1[],
   ): Promise<ModelMessage[]> {
     this.sessionMessages = [...this.sessionMessages, ...messages];
-    const modelMessages = await toModelMessages(messages, this.tools);
+    const modelMessages = await toModelMessages(
+      messages,
+      this.tools,
+      this.projectRoot,
+    );
     if (modelMessages.length > 0) {
       this.currentModelMessages = [...this.currentModelMessages, ...modelMessages];
       return modelMessages;
@@ -127,6 +150,7 @@ export class CoreEngineMessageState {
     this.currentModelMessages = await toModelMessages(
       this.sessionMessages,
       this.tools,
+      this.projectRoot,
     );
     return [];
   }

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

@@ -154,6 +154,7 @@ export class CoreEngineRunner {
       const message_state = await CoreEngineMessageState.create({
         messages: input.execute_input.messages,
         tools,
+        projectRoot: input.run_context.projectRoot,
       });
 
       const append_merged_user_messages = (messages: SessionMessageV1[]) =>

package/src/executor/messages/AssistantFileResource.ts

@@ -3,13 +3,14 @@
  *
  * 关键点（中文）
  * - 只处理运行期产生的 assistant file part，不参与 user 附件注入。
- * - 将 `data:*;base64,...` 写入 `.downcity/resources`，历史中只保留 `file://` 绝对 URL。
+ * - 将 data URL、远程 URL 与本地文件统一写入 `.downcity/resources`。
+ * - 历史中只保留 `resources://<project-relative-path>`，避免暴露本机绝对路径。
  * - 资源文件按内容 hash 命名，天然去重并避免重复写入大文件。
  */
 
 import crypto from "node:crypto";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import fs from "fs-extra";
 import type { FileUIPart } from "ai";
 import { getDowncityResourcesDirPath } from "@/config/Paths.js";
@@ -92,6 +93,23 @@ function extension_from_filename(filename: string | undefined): string {
   return /^[.][a-z0-9]+$/u.test(ext) ? ext : "";
 }
 
+function filename_from_url(raw_url: string): string | undefined {
+  try {
+    const parsed = new URL(raw_url);
+    return path.basename(decodeURIComponent(parsed.pathname)) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function to_resources_url(projectRoot: string, filePath: string): string {
+  const relative = path
+    .relative(projectRoot, filePath)
+    .split(path.sep)
+    .join("/");
+  return `resources://${relative}`;
+}
+
 async function write_resource_file(params: {
   projectRoot: string;
   mediaType: string;
@@ -117,8 +135,97 @@ async function write_resource_file(params: {
   return file_path;
 }
 
+async function read_remote_resource(raw_url: string): Promise<{
+  mediaType?: string;
+  filename?: string;
+  bytes: Buffer;
+}> {
+  const response = await fetch(raw_url);
+  if (!response.ok) {
+    throw new Error(`Failed to download assistant file resource: ${response.status}`);
+  }
+  const array_buffer = await response.arrayBuffer();
+  const bytes = Buffer.from(array_buffer);
+  if (bytes.length === 0) {
+    throw new Error("Downloaded assistant file resource is empty");
+  }
+  return {
+    mediaType: response.headers.get("content-type")?.split(";")[0]?.trim(),
+    filename: filename_from_url(raw_url),
+    bytes,
+  };
+}
+
+async function read_local_resource(
+  projectRoot: string,
+  raw_url: string,
+): Promise<{
+  mediaType?: string;
+  filename?: string;
+  bytes: Buffer;
+}> {
+  const raw = String(raw_url || "").trim();
+  const file_path = raw.startsWith("file://")
+    ? fileURLToPath(raw)
+    : path.isAbsolute(raw)
+      ? raw
+      : path.resolve(projectRoot, raw);
+  const bytes = await fs.readFile(file_path);
+  if (bytes.length === 0) {
+    throw new Error(`Assistant file resource is empty: ${file_path}`);
+  }
+  return {
+    filename: path.basename(file_path),
+    bytes,
+  };
+}
+
+async function materialize_file_part(params: {
+  projectRoot: string;
+  part: FileUIPart;
+}): Promise<FileUIPart> {
+  const raw_url = String(params.part.url || "").trim();
+  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);
+  const source = parsed_data_url
+    ? {
+        mediaType: parsed_data_url.media_type,
+        filename:
+          typeof params.part.filename === "string"
+            ? params.part.filename
+            : undefined,
+        bytes: parsed_data_url.bytes,
+      }
+    : raw_url.startsWith("http://") || raw_url.startsWith("https://")
+      ? await read_remote_resource(raw_url)
+      : await read_local_resource(params.projectRoot, raw_url);
+
+  const media_type =
+    String(params.part.mediaType || source.mediaType || "").trim() ||
+    "application/octet-stream";
+  const file_path = await write_resource_file({
+    projectRoot: params.projectRoot,
+    mediaType: media_type,
+    filename:
+      typeof params.part.filename === "string"
+        ? params.part.filename
+        : source.filename,
+    bytes: source.bytes,
+  });
+
+  return {
+    ...params.part,
+    mediaType: media_type,
+    url: to_resources_url(params.projectRoot, file_path),
+  };
+}
+
 /**
- * 将 assistant file part 中的 data URL 资源落盘为 `file://` 绝对 URL。
+ * 将 assistant file part 中的资源统一落盘为 `resources://` 相对 URL。
  */
 export async function materializeAssistantFileParts(
   params: MaterializeAssistantFilePartsParams,
@@ -130,25 +237,7 @@ export async function materializeAssistantFileParts(
   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,
-    });
+    out.push(await materialize_file_part({ projectRoot: project_root, part }));
   }
 
   return out;

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -5,6 +5,7 @@
  * - 兼容 Telegram / Feishu / TUI 等统一的 `<file>` 协议入口。
  * - 仅在本轮执行的内存消息上追加 file parts，不修改持久化历史。
  * - 当前只为图片与 PDF 注入 file part，保持多模态模型可直接消费。
+ * - 历史中的 `resources://` 与旧版 `file://` 会在喂给模型前临时 hydrate。
  */
 
 import fs from "fs-extra";
@@ -62,11 +63,32 @@ function buildDataUrl(mediaType: string, buffer: Buffer): string {
   return `data:${safeType};base64,${base64}`;
 }
 
-async function hydrateFileUrlPart(part: FileUIPart): Promise<FileUIPart> {
+function resolveResourcesUrlPath(
+  projectRoot: string | undefined,
+  rawUrl: 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 root = path.resolve(String(projectRoot || "").trim() || process.cwd());
+  const absPath = path.resolve(root, relative);
+  const rel = path.relative(root, absPath);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return absPath;
+}
+
+async function hydrateFileUrlPart(
+  part: FileUIPart,
+  projectRoot?: string,
+): Promise<FileUIPart> {
   const url = String(part.url || "").trim();
-  if (!url.startsWith("file://")) return part;
+  const resourcesPath = resolveResourcesUrlPath(projectRoot, url);
+  if (!url.startsWith("file://") && !resourcesPath) return part;
   try {
-    const absPath = fileURLToPath(url);
+    const absPath = resourcesPath || fileURLToPath(url);
     const buffer = await fs.readFile(absPath);
     const mediaType =
       String(part.mediaType || "").trim() ||
@@ -83,14 +105,15 @@ async function hydrateFileUrlPart(part: FileUIPart): Promise<FileUIPart> {
 }
 
 /**
- * 将历史中的 `file://` file part 临时转换为模型可消费的 data URL。
+ * 将历史中的资源 file part 临时转换为模型可消费的 data URL。
  *
  * 关键点（中文）
  * - 该函数只修改本轮内存消息，不回写历史。
- * - 持久化层继续保留轻量 `file://` 绝对 URL，避免 JSONL 存储 base64。
+ * - 新历史保留 `resources://` 相对 URL，旧历史的 `file://` 仍继续兼容。
  */
 export async function hydrateFileUrlPartsForModel(
   messages: SessionMessageV1[],
+  projectRoot?: string,
 ): Promise<SessionMessageV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
@@ -109,7 +132,7 @@ export async function hydrateFileUrlPartsForModel(
         nextParts.push(part);
         continue;
       }
-      const nextPart = await hydrateFileUrlPart(part as FileUIPart);
+      const nextPart = await hydrateFileUrlPart(part as FileUIPart, projectRoot);
       if (nextPart !== part) changed = true;
       nextParts.push(nextPart as SessionMessageV1["parts"][number]);
     }

package/src/executor/messages/SessionMessageCodec.ts

@@ -72,6 +72,7 @@ export function pickMergedUserMessages(
 export async function toModelMessages(
   messages: SessionMessageV1[],
   tools: Record<string, Tool>,
+  projectRoot?: string,
 ): Promise<ModelMessage[]> {
   // 空输入快速返回，避免调用转换器的额外开销。
   if (!Array.isArray(messages) || messages.length === 0) return [];
@@ -79,8 +80,11 @@ export async function toModelMessages(
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
   const enrichedMessages = await injectFilePartsFromAttachments(messages);
 
-  // 第二步（中文）：把历史里的 file:// 资源在内存中 hydrate 成模型可消费的 data URL。
-  const hydratedMessages = await hydrateFileUrlPartsForModel(enrichedMessages);
+  // 第二步（中文）：把历史里的资源 URL 在内存中 hydrate 成模型可消费的 data URL。
+  const hydratedMessages = await hydrateFileUrlPartsForModel(
+    enrichedMessages,
+    projectRoot,
+  );
 
   // 第三步（中文）：转换前先剔除 UI 层 id 字段，仅保留模型需要的数据结构。
   const input = hydratedMessages.map((message) => {

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

@@ -2,14 +2,14 @@
  * Plugin tool 运行时桥接。
  *
  * 关键点（中文）
- * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 PluginPort 调用 action。
+ * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 AgentPlugins 调用 action。
  * - 如果 action 返回 AI SDK UIMessage，则抽取 file parts 并入最终 assistant 消息。
  * - 返回给模型的 tool result 只保留短摘要，避免 data URL 等大内容污染上下文。
  */
 
 import type { FileUIPart } from "ai";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   PluginCallInput,
   PluginCallToolResult,
@@ -20,19 +20,19 @@ import {
   getSessionRunContext,
 } from "@executor/SessionRunScope.js";
 
-let plugin_tool_runtime: PluginPort | null = null;
+let plugin_tool_runtime: AgentPlugins | null = null;
 
 /**
  * 注入 plugin tool 运行时。
  */
-export function setPluginToolRuntime(next: PluginPort): void {
+export function setPluginToolRuntime(next: AgentPlugins): void {
   plugin_tool_runtime = next;
 }
 
 /**
  * 读取已注入的 plugin tool 运行时。
  */
-function require_plugin_tool_runtime(): PluginPort {
+function require_plugin_tool_runtime(): AgentPlugins {
   if (plugin_tool_runtime) return plugin_tool_runtime;
   throw new Error(
     "Plugin tool runtime is not initialized. Ensure agent assembly completed before using plugin_call.",

package/src/index.ts

@@ -69,7 +69,6 @@ export type {
 
 // Plugin 作者 API
 export { BasePlugin } from "./plugin/core/BasePlugin.js";
-export { ImagePlugin } from "./plugin/core/ImagePlugin.js";
 
 // Session 与即时执行集成
 export { Executor } from "./executor/Executor.js";
@@ -225,15 +224,6 @@ export type {
 } from "./types/runtime/http/InlineInstant.js";
 
 // Plugin 作者与控制面类型
-export type {
-  ImagePluginContent,
-  ImagePluginFileContent,
-  ImagePluginInput,
-  ImagePluginMessage,
-  ImagePluginOptions,
-  ImagePluginTextContent,
-} from "./types/plugin/ImagePlugin.js";
-
 export type {
   Plugin,
   PluginAction,
@@ -249,7 +239,7 @@ export type {
   PluginHooks,
   PluginHttpDefinition,
   PluginPipelineHook,
-  PluginPort,
+  AgentPlugins,
   PluginResolveHook,
   PluginHttpRegistration,
   PluginActionInvokeParams,

package/src/plugin/core/BasePlugin.ts

@@ -8,7 +8,6 @@
  */
 
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   Plugin,
   PluginActions,
@@ -38,15 +37,6 @@ export abstract class BasePlugin implements Plugin {
     chain: Promise.resolve(),
   };
 
-  /**
-   * 当前 plugin 所属的 agent 宿主。
-   */
-  protected agent: AgentRuntime | null;
-
-  constructor(agent: AgentRuntime | null = null) {
-    this.agent = agent;
-  }
-
   /**
    * 当前 plugin 名称。
    */
@@ -114,21 +104,4 @@ export abstract class BasePlugin implements Plugin {
    */
   system?(context: AgentContext): Promise<string> | string;
 
-  /**
-   * 绑定当前 plugin 所属的 agent 宿主。
-   */
-  bindAgent(agent: AgentRuntime | null): this {
-    this.agent = agent;
-    return this;
-  }
-
-  /**
-   * 读取绑定的 agent 宿主。
-   */
-  protected requireAgent(): AgentRuntime {
-    if (this.agent) return this.agent;
-    throw new Error(
-      `Plugin "${this.name}" is not bound to an agent instance.`,
-    );
-  }
 }

package/src/plugin/core/Manager.ts

@@ -9,8 +9,6 @@ export type {
 } from "@/plugin/types/Plugin.js";
 export {
   controlPluginState,
-  getPluginRootCommandNames,
-  getStaticPlugins,
   isPluginRunning,
   listPluginStates,
   startAllPlugins,

package/src/plugin/core/PluginRegistry.ts

@@ -12,6 +12,7 @@ import type { HookRegistry } from "@/plugin/core/HookRegistry.js";
 import type {
   Plugin,
   PluginActionResult,
+  AgentPlugins,
   PluginAvailability,
   PluginView,
 } from "@/plugin/types/Plugin.js";
@@ -23,7 +24,7 @@ type ContextResolver = () => AgentContext;
 /**
  * PluginRegistry：plugin 注册与调度实现。
  */
-export class PluginRegistry {
+export class PluginRegistry implements AgentPlugins {
   private readonly contextResolver: ContextResolver;
 
   private readonly hookRegistry: HookRegistry;

package/src/plugin/core/PluginStateController.ts

@@ -5,7 +5,6 @@
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
-  Plugin,
   PluginLifecycle,
   PluginState,
   PluginStateControlAction,
@@ -132,20 +131,6 @@ export function markPluginCommand(
   record.updatedAt = nowMs();
 }
 
-/**
- * 返回静态主动型 plugin 定义清单。
- */
-export function getStaticPlugins(): Plugin[] {
-  return [];
-}
-
-/**
- * 返回主动型 plugin 根命令名清单。
- */
-export function getPluginRootCommandNames(): string[] {
-  return [];
-}
-
 /**
  * 列出全部主动型 plugin 状态快照。
  */

package/src/plugin/types/Plugin.ts

@@ -37,7 +37,7 @@ export type {
   PluginGuardHook,
   PluginHooks,
   PluginPipelineHook,
-  PluginPort,
+  AgentPlugins,
   PluginResolveHook,
   PluginResolves,
   PluginView,

package/src/types/config/DowncityConfig.ts

@@ -107,24 +107,6 @@ export interface DowncityChatPluginConfig {
   channels?: DowncityChatPluginChannelsConfig;
 }
 
-/**
- * skill 插件配置。
- */
-export interface DowncitySkillPluginConfig {
-  /**
-   * 当前插件是否启用。
-   */
-  enabled?: boolean;
-  /**
-   * 技能目录列表。
-   */
-  paths?: string[];
-  /**
-   * 是否允许读取项目外部技能目录。
-   */
-  allowExternalPaths?: boolean;
-}
-
 /**
  * downcity.json 中的插件配置映射。
  */
@@ -133,17 +115,12 @@ export interface DowncityPluginConfigMap {
    * chat 插件配置。
    */
   chat?: DowncityChatPluginConfig;
-  /**
-   * skill 插件配置。
-   */
-  skill?: DowncitySkillPluginConfig;
   /**
    * 其他插件配置。
    */
   [pluginName: string]:
     | JsonObject
     | DowncityChatPluginConfig
-    | DowncitySkillPluginConfig
     | undefined;
 }
 
@@ -171,7 +148,7 @@ export interface DowncityConfig {
    *
    * 关键点（中文）
    * - 所有可配置能力统一收敛到 `plugins`，不再保留独立 `services` 域。
-   * - plugin 私有配置（例如 `plugins.skill.paths`、`plugins.chat.channels`）也放在这里。
+   * - 需要持久化到项目文件的 plugin 配置（例如 `plugins.chat.channels`）放在这里。
    * - key 为 plugin 名称，value 为对应插件的结构化配置对象。
    * - 当前阶段允许各 plugin 自定义字段，但必须保持 JSON 可序列化。
    */

package/src/types/plugin/PluginRuntime.ts

@@ -52,9 +52,9 @@ export interface PluginAvailability {
 }
 
 /**
- * Plugin 调用端口。
+ * 当前 Agent 可用的 plugin 调用面。
  */
-export interface PluginPort {
+export interface AgentPlugins {
   /** 列出全部已注册 plugin。 */
   list(): PluginView[];
   /** 检查指定 plugin 可用性。 */

package/src/types/runtime/agent/AgentContext.ts

@@ -19,7 +19,7 @@ import type {
 } from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   SessionMetadataV1,
   SessionMessageV1,
@@ -261,7 +261,7 @@ export interface AgentContext {
   /**
    * Plugin 调用入口。
    */
-  plugins: PluginPort;
+  plugins: AgentPlugins;
 }
 
 /**