@downcity/plugins 1.0.254 → 1.0.280

package/src/image/ImagePlugin.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 对 Agent 暴露 `image_create` / `image_result` 两步式任务 action。
- * - City / provider 的图片能力通过 image_create / image_result 任务函数注入。
+ * - 图片 AI 从运行时 Context 的 Embassy 能力读取；Workspace 文件能力由运行时 Context 提供。
  * - 成功结果中的远程图片会写入 Workspace，并同时保留本地引用与在线来源地址。
  */
 
@@ -19,6 +19,7 @@ import type {
 } from "@downcity/agent";
 import type {
   ImagePluginInput,
+  ImageAiService,
   ImagePluginJobCreateResult,
   ImagePluginJobResult,
   ImagePluginJobResultInput,
@@ -51,6 +52,17 @@ const DEFAULT_IMAGE_WAIT_MS = 60_000;
 const DEFAULT_IMAGE_POLL_MS = 1_500;
 const MAX_IMAGE_WAIT_MS = 10 * 60_000;
 
+/** 从 City 注入的 Embassy 获取图片 AI 服务。 */
+function require_image_ai(context: PluginContext): ImageAiService {
+  const service = context.embassy?.user.ai;
+  if (!service) throw new Error("ImagePlugin requires a City Embassy user AI service");
+  return {
+    catalog: async () => await service.catalog(),
+    image_create: async (input) => await service.image_create(input as never),
+    image_result: async (input) => await service.image_result(input as never),
+  };
+}
+
 /**
  * 判断任务状态是否已到达终态。
  */
@@ -386,15 +398,15 @@ function normalize_image_result_payload(
 }
 
 /**
- * 校验 image 函数返回的 UIMessage。
+ * 校验 image 函数返回的 Downcity Session 消息。
  *
- * 本函数只校验 provider / City 返回的 UIMessage 结构；
+ * 本函数只校验 provider / City 返回的 Session 消息结构；
  * 远程资源下载由 action 成功分支中的 ImageResultStorage 统一处理。
  */
 function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   const record = to_record(result);
   if (!record || !Array.isArray(record.parts)) {
-    throw new TypeError("ImagePlugin image provider must return an AI SDK UIMessage");
+    throw new TypeError("ImagePlugin image provider must return a Downcity Session message");
   }
   for (const part of record.parts) {
     const part_record = to_record(part);
@@ -504,9 +516,6 @@ export class ImagePlugin extends BasePlugin {
    */
   readonly description: string;
 
-  private readonly image_create: NonNullable<ImagePluginOptions["image_create"]>;
-  private readonly image_result: NonNullable<ImagePluginOptions["image_result"]>;
-  private readonly list_models?: ImagePluginOptions["list_models"];
   private readonly default_model?: ImagePluginDefaultModel;
 
   constructor(options: ImagePluginOptions) {
@@ -515,20 +524,11 @@ export class ImagePlugin extends BasePlugin {
     if (!name) {
       throw new Error("ImagePlugin requires a non-empty name");
     }
-    if (typeof options.image_create !== "function") {
-      throw new Error("ImagePlugin requires an image_create function");
-    }
-    if (typeof options.image_result !== "function") {
-      throw new Error("ImagePlugin requires an image_result function");
-    }
     this.name = name;
     this.title = String(options.title || DEFAULT_IMAGE_PLUGIN_TITLE).trim();
     this.description = String(
       options.description || DEFAULT_IMAGE_PLUGIN_DESCRIPTION,
     ).trim();
-    this.image_create = options.image_create;
-    this.image_result = options.image_result;
-    this.list_models = options.list_models;
     this.default_model = normalize_default_image_model(options.default_model);
   }
 
@@ -578,8 +578,9 @@ export class ImagePlugin extends BasePlugin {
    */
   private async read_image_result(
     input: ImagePluginJobResultInput,
+    context: PluginContext,
   ): Promise<ImagePluginJobResult> {
-    const first = await this.fetch_job_once(input.job_id);
+    const first = await this.fetch_job_once(input.job_id, context);
     if (!input.until_done) return first;
     if (is_terminal_status(first.status)) return first;
 
@@ -599,7 +600,7 @@ export class ImagePlugin extends BasePlugin {
       const sleep_ms = Math.min(wait_ms, remaining);
       if (sleep_ms === 0) break;
       await delay_ms(sleep_ms);
-      current = await this.fetch_job_once(input.job_id);
+      current = await this.fetch_job_once(input.job_id, context);
       if (is_terminal_status(current.status)) return current;
     }
     return current;
@@ -608,8 +609,11 @@ export class ImagePlugin extends BasePlugin {
   /**
    * 拉取一次任务状态并校验。
    */
-  private async fetch_job_once(job_id: string): Promise<ImagePluginJobResult> {
-    const current = await this.image_result({ job_id });
+  private async fetch_job_once(
+    job_id: string,
+    context: PluginContext,
+  ): Promise<ImagePluginJobResult> {
+    const current = await require_image_ai(context).image_result({ job_id }) as unknown as ImagePluginJobResult;
     validate_job_result(current);
     if (current.status === "succeeded" && current.result) {
       normalize_image_result(current.result);
@@ -624,16 +628,9 @@ export class ImagePlugin extends BasePlugin {
     models: create_action({
       description: "List image-capable models available to ImagePlugin.",
       input_schema: z.object({}).passthrough(),
-      execute: async () => {
+      execute: async ({ context }) => {
         try {
-          if (!this.list_models) {
-            return {
-              success: false,
-              error: "ImagePlugin list_models is not configured",
-              message: "ImagePlugin list_models is not configured",
-            };
-          }
-          const models = await this.list_models();
+          const models = await require_image_ai(context).catalog().then((catalog) => catalog.all()) as unknown as ImagePluginModel[];
           const result = normalize_image_models(models);
           return {
             success: true,
@@ -729,7 +726,7 @@ export class ImagePlugin extends BasePlugin {
             await normalize_image_create_input(context, normalized_payload),
             this.default_model,
           );
-          const created = await this.image_create(normalized_input);
+          const created = await require_image_ai(context).image_create(normalized_input as unknown as JsonObject) as unknown as ImagePluginJobCreateResult;
           validate_created_job(created);
           return {
             success: true,
@@ -792,10 +789,10 @@ export class ImagePlugin extends BasePlugin {
           },
         },
       ],
-      execute: async ({ context, execution_context, input }) => {
+      execute: async ({ context, execution, input }) => {
         try {
           const normalized_input = normalize_image_result_payload(input);
-          const current = await this.read_image_result(normalized_input);
+          const current = await this.read_image_result(normalized_input, context);
           if (current.status === "failed") {
             return {
               success: false,
@@ -809,7 +806,7 @@ export class ImagePlugin extends BasePlugin {
                 context,
                 job_id: current.job_id,
                 result: current.result,
-                abort_signal: execution_context?.abort_signal,
+                abort_signal: execution.abort_signal,
               })
             : undefined;
           const output = localized

package/src/image/runtime/ImageResultStorage.ts

@@ -2,8 +2,8 @@
  * ImagePlugin 生成结果本地化。
  *
  * 关键点（中文）
- * - City / provider 返回的远程图片先落到当前 Workspace，再交给 Agent Session。
- * - File Part 的 `url` 使用稳定的本地相对路径，原始在线地址写入 provider metadata。
+ * - City / provider 返回的远程图片先落到当前 Agent private runtime directory 私有目录，再交给 Agent Session。
+ * - File Part 的 `url` 使用稳定的本地绝对路径。
  * - 单张图片下载失败时保留远程地址，并返回可观察错误，不丢弃已经生成成功的结果。
  */
 
@@ -12,6 +12,7 @@ import type {
   ImagePluginResultStorageInput,
   ImagePluginResultStorageResult,
 } from "@/image/types/ImagePlugin.js";
+import type { SessionAssistantResultPart } from "@downcity/agent";
 
 const HTTP_URL_RE = /^https?:\/\//i;
 const MAX_IMAGE_RESULT_BYTES = 50 * 1024 * 1024;
@@ -25,12 +26,6 @@ const MEDIA_TYPE_EXTENSIONS: Record<string, string> = {
   "image/webp": ".webp",
 };
 
-/** 判断未知值是否为普通对象。 */
-function to_record(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value as Record<string, unknown>;
-}
-
 /** 把外部标识压缩为单个安全路径片段。 */
 function to_safe_segment(value: string, fallback: string): string {
   const normalized = String(value || "")
@@ -64,27 +59,6 @@ function resolve_extension(input: {
   return extension_from_url(input.source_url) || ".bin";
 }
 
-/** 给 File Part 合并 Downcity 来源元数据。 */
-function with_source_metadata(
-  part: Record<string, unknown>,
-  source_url: string,
-  localization_error?: string,
-): Record<string, unknown> {
-  const provider_metadata = to_record(part.providerMetadata) ?? {};
-  const downcity_metadata = to_record(provider_metadata.downcity) ?? {};
-  return {
-    ...part,
-    providerMetadata: {
-      ...provider_metadata,
-      downcity: {
-        ...downcity_metadata,
-        source_url,
-        ...(localization_error ? { localization_error } : {}),
-      },
-    },
-  };
-}
-
 /** 受大小上限保护地读取远程响应。 */
 async function read_response_bytes(response: Response): Promise<Buffer> {
   const declared_length = Number(response.headers.get("content-length") || 0);
@@ -109,11 +83,11 @@ async function read_response_bytes(response: Response): Promise<Buffer> {
   return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total_bytes);
 }
 
-/** 下载一张远程图片并返回 Workspace 相对路径。 */
+/** 下载一张远程图片并返回 Agent private runtime directory 私有目录中的绝对路径。 */
 async function persist_remote_image(input: {
   context: ImagePluginResultStorageInput["context"];
   job_id: string;
-  part: Record<string, unknown>;
+  part: Extract<SessionAssistantResultPart, { type: "file" }>;
   source_url: string;
   part_index: number;
   abort_signal?: AbortSignal;
@@ -125,7 +99,7 @@ async function persist_remote_image(input: {
     throw new Error(`image download failed with HTTP ${response.status}`);
   }
 
-  const declared_media_type = String(input.part.mediaType || "").trim();
+  const declared_media_type = input.part.media_type.trim();
   const response_media_type = String(response.headers.get("content-type") || "")
     .split(";", 1)[0]
     .trim();
@@ -138,21 +112,20 @@ async function persist_remote_image(input: {
   const job_segment = to_safe_segment(input.job_id, "job");
   const filename = `image_${String(input.part_index + 1).padStart(2, "0")}${extension}`;
   const relative_path = path.posix.join(
-    ".downcity",
     "image",
     "results",
     job_segment,
     filename,
   );
-  const absolute_path = input.context.files.resolve_path(...relative_path.split("/"));
-  if (!(await input.context.files.path_exists(absolute_path))) {
+  const absolute_path = input.context.data_files.resolve_path(...relative_path.split("/"));
+  if (!(await input.context.data_files.path_exists(absolute_path))) {
     const bytes = await read_response_bytes(response);
-    await input.context.files.ensure_directory(path.dirname(absolute_path));
-    await input.context.files.write_file_atomically(absolute_path, bytes);
+    await input.context.data_files.ensure_directory(path.dirname(absolute_path));
+    await input.context.data_files.write_file_atomically(absolute_path, bytes);
   } else {
     await response.body?.cancel();
   }
-  return relative_path;
+  return absolute_path;
 }
 
 /**
@@ -162,31 +135,32 @@ export async function localize_image_result(
   input: ImagePluginResultStorageInput,
 ): Promise<ImagePluginResultStorageResult> {
   const errors: string[] = [];
-  const parts = await Promise.all(input.result.parts.map(async (part, part_index) => {
-    const record = to_record(part);
-    if (record?.type !== "file") return part;
-    const source_url = String(record.url || "").trim();
-    if (!HTTP_URL_RE.test(source_url)) return part;
+  const parts: SessionAssistantResultPart[] = await Promise.all(
+    input.result.parts.map(async (part, part_index): Promise<SessionAssistantResultPart> => {
+      if (part.type !== "file") return part;
+      const source_url = part.url.trim();
+      if (!HTTP_URL_RE.test(source_url)) return part;
 
-    try {
-      const local_url = await persist_remote_image({
-        context: input.context,
-        job_id: input.job_id,
-        part: record,
-        source_url,
-        part_index,
-        abort_signal: input.abort_signal,
-      });
-      return {
-        ...with_source_metadata(record, source_url),
-        url: local_url,
-      } as typeof part;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      errors.push(`part ${part_index + 1}: ${message}`);
-      return with_source_metadata(record, source_url, message) as typeof part;
-    }
-  }));
+      try {
+        const local_url = await persist_remote_image({
+          context: input.context,
+          job_id: input.job_id,
+          part,
+          source_url,
+          part_index,
+          abort_signal: input.abort_signal,
+        });
+        return {
+          ...part,
+          url: local_url,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`part ${part_index + 1}: ${message}`);
+        return part;
+      }
+    }),
+  );
 
   return {
     result: {

package/src/image/types/ImagePlugin.ts

@@ -3,17 +3,29 @@
  *
  * 关键点（中文）
  * - 这里仅定义图片 plugin 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
- * - 图片成功结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
+ * - 图片成功结果使用 Downcity Session 消息，保证结果可直接写入会话时间线。
  * - 字段保持 JSON 可序列化，便于通过 Plugin Action 与 Tool 传递。
  */
 
-import type { UIMessage } from "ai";
 import type {
+  ActionResultMessage,
   JsonObject,
   JsonValue,
 } from "@downcity/agent";
 import type { PluginContext } from "@downcity/agent";
 
+/** ImagePlugin 使用的最小图片 AI 服务协议。 */
+export interface ImageAiService {
+  /** 读取当前可用的图片模型目录。 */
+  catalog(): Promise<{ all(): readonly unknown[] }>;
+
+  /** 创建图片生成任务。 */
+  image_create(input: JsonObject): Promise<unknown>;
+
+  /** 查询图片生成任务。 */
+  image_result(input: JsonObject): Promise<unknown>;
+}
+
 /**
  * 图片生成文本内容片段。
  */
@@ -139,7 +151,7 @@ export interface ImagePluginResolvedInput {
 /**
  * ImagePlugin 图片成功结果。
  */
-export type ImagePluginResult = UIMessage;
+export type ImagePluginResult = ActionResultMessage;
 
 /**
  * 图片结果本地存储输入。
@@ -149,7 +161,7 @@ export interface ImagePluginResultStorageInput {
   context: PluginContext;
   /** 当前图片任务 ID，用于划分稳定的本地结果目录。 */
   job_id: string;
-  /** City 或 provider 返回的原始图片 UIMessage。 */
+  /** City 或 provider 返回的原始 Downcity Session 消息。 */
   result: ImagePluginResult;
   /** 当前 Session Turn 的可选取消信号。 */
   abort_signal?: AbortSignal;
@@ -159,7 +171,7 @@ export interface ImagePluginResultStorageInput {
  * 图片结果本地存储输出。
  */
 export interface ImagePluginResultStorageResult {
-  /** 已将可下载远程图片替换为本地 Workspace 路径的 UIMessage。 */
+  /** 已将可下载远程图片替换为本地 Workspace 路径的 Downcity Session 消息。 */
   result: ImagePluginResult;
   /** 未能完成本地化的图片错误；对应 File Part 会保留远程 URL。 */
   errors: string[];
@@ -194,7 +206,7 @@ export interface ImagePluginJobResult {
   job_id: string;
   /** 当前任务状态。 */
   status: ImagePluginJobStatus;
-  /** 成功时返回的 AI SDK UIMessage。 */
+  /** 成功时返回的 Downcity Session 消息。 */
   result?: ImagePluginResult;
   /** 失败时返回的错误消息。 */
   error?: string;
@@ -284,23 +296,17 @@ export type ImagePluginDefaultModel =
 /**
  * ImagePlugin 构造参数。
  */
-export interface ImagePluginOptions {
+export interface ImagePluginProfile {
   /** Plugin 稳定名称，默认 `image`。 */
   name?: string;
   /** Plugin 展示标题，默认 `Image`。 */
   title?: string;
   /** Plugin 用途说明。 */
   description?: string;
-  /** 默认图片模型配置。Agent 调用 `image_create` 未传 `model` 时会自动使用字符串值或函数返回值。 */
-  default_model?: ImagePluginDefaultModel;
-  /** 创建图片生成任务，通常传入 `(input) => city.ai.image_create(input)`。 */
-  image_create?: (
-    input: ImagePluginResolvedInput,
-  ) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
-  /** 查询图片生成任务，通常传入 `(input) => city.ai.image_result(input)`。 */
-  image_result?: (
-    input: ImagePluginJobResultInput,
-  ) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
-  /** 列出可用图片模型，通常传入 `async () => city.ai.catalog().then((catalog) => catalog.forModality("image"))`。 */
-  list_models?: () => Promise<ImagePluginModel[]> | ImagePluginModel[];
+  /** 默认图片模型 ID。 */
+  default_model?: string;
+}
+
+/** ImagePlugin 构造参数。 */
+export interface ImagePluginOptions extends ImagePluginProfile {
 }

package/src/image.ts

@@ -6,6 +6,7 @@
 
 export { ImagePlugin } from "./image/ImagePlugin.js";
 export type {
+  ImageAiService,
   ImagePluginContent,
   ImagePluginDefaultModel,
   ImagePluginDefaultModelResolverInput,
@@ -18,6 +19,7 @@ export type {
   ImagePluginModel,
   ImagePluginModelsResult,
   ImagePluginOptions,
+  ImagePluginProfile,
   ImagePluginResolvedContent,
   ImagePluginResolvedInput,
   ImagePluginResolvedMessage,

package/src/index.ts

@@ -16,3 +16,11 @@ export * from "./sound.js";
 export * from "./task.js";
 export * from "./web.js";
 export * from "./workboard.js";
+export {
+  create_builtin_plugin_registrations,
+} from "./builtin/BuiltinPluginTypes.js";
+export type {
+  BuiltinPluginDefinition,
+  BuiltinPluginRegistration,
+  BuiltinPluginRegistrationsOptions,
+} from "./builtin/BuiltinPluginTypes.js";

package/src/memory/MemoryPlugin.ts

@@ -13,6 +13,8 @@
  */
 
 import type { Command } from "commander";
+import os from "node:os";
+import path from "node:path";
 import { BasePlugin, create_action } from "@downcity/agent";
 import type {
   JsonObject,
@@ -31,6 +33,8 @@ import {
   status_memory_action,
 } from "@/memory/Action.js";
 import { build_memory_plugin_system_text } from "@/memory/runtime/SystemProvider.js";
+import { BuiltinMemoryProvider } from "@/memory/providers/BuiltinMemoryProvider.js";
+import { FileMemoryStorageAdapter, get_default_file_memory_root_path } from "@/memory/adapters/FileMemoryStorageAdapter.js";
 import type {
   MemoryPluginOptions,
   MemoryProvider,
@@ -106,12 +110,20 @@ export class MemoryPlugin extends BasePlugin {
   /** 当前 Plugin 唯一绑定的 Memory Provider。 */
   readonly provider: MemoryProvider;
 
-  constructor(options: MemoryPluginOptions) {
+  constructor(profile: MemoryPluginOptions = {}) {
     super();
-    if (!options?.provider) throw new Error("MemoryPlugin requires provider");
-    const provider_name = String(options.provider.name || "").trim();
-    if (!provider_name) throw new Error("MemoryPlugin provider requires name");
-    this.provider = options.provider;
+    const root_path = profile.root_path?.trim();
+    if (root_path && !path.isAbsolute(root_path)) {
+      throw new Error("MemoryPlugin root_path must be absolute");
+    }
+    this.provider = new BuiltinMemoryProvider({
+      create_storage: ({ agent_id }) => new FileMemoryStorageAdapter({
+        root_path: root_path || get_default_file_memory_root_path({
+          platform_root_path: process.env.DC_PLATFORM_ROOT || path.join(os.homedir(), ".downcity"),
+          agent_id,
+        }),
+      }),
+    });
   }
 
   /** 构建 provider-neutral Memory system 内容。 */

package/src/memory/types/Memory.ts

@@ -386,12 +386,19 @@ export interface MemoryProvider {
   dispose(): Promise<void>;
 }
 
-/** MemoryPlugin constructor 参数。 */
-export interface MemoryPluginOptions {
-  /** 当前 Plugin 唯一使用的主 Memory Provider。 */
-  provider: MemoryProvider;
+/** MemoryPlugin profile。 */
+export interface MemoryPluginProfile {
+  /** 当前启用的 Memory Provider。 */
+  provider?: "builtin";
+  /** 当前启用的 Memory Storage。 */
+  storage?: "file";
+  /** 可选的绝对存储目录。 */
+  root_path?: string;
 }
 
+/** MemoryPlugin profile 的兼容名称别名。 */
+export type MemoryPluginOptions = MemoryPluginProfile;
+
 /** Memory action 可以接受的公开 JSON payload 联合。 */
 export type MemoryActionPayload =
   | Omit<MemoryRecallInput, "scope">

package/src/memory.ts

@@ -17,6 +17,7 @@ export type {
   MemoryForgetInput,
   MemoryForgetResult,
   MemoryPluginOptions,
+  MemoryPluginProfile,
   MemoryProvider,
   MemoryProviderCapabilities,
   MemoryProviderInitializeInput,

package/src/renderers.ts

@@ -0,0 +1,18 @@
+/** Downcity 官方 Plugin Mainview 的 Renderer 专用注册表。 */
+
+import type { PluginRendererComponent } from "@downcity/plugin/react";
+import { CHAT_PLUGIN_RENDERER } from "@/chat/renderer/ChatPluginRenderer.js";
+import {
+  IMAGE_PLUGIN_SETTINGS,
+  SOUND_PLUGIN_SETTINGS,
+  WEB_PLUGIN_SETTINGS,
+} from "@/builtin/PluginSettingsDefinitions.js";
+import { create_plugin_settings_renderer } from "@/builtin/renderer/PluginSettingsRenderer.js";
+
+/** 官方 Plugin ID 到唯一 Mainview 组件的稳定映射。 */
+export const BUILTIN_PLUGIN_RENDERERS: Readonly<Record<string, PluginRendererComponent>> = {
+  chat: CHAT_PLUGIN_RENDERER,
+  web: create_plugin_settings_renderer(WEB_PLUGIN_SETTINGS),
+  image: create_plugin_settings_renderer(IMAGE_PLUGIN_SETTINGS),
+  sound: create_plugin_settings_renderer(SOUND_PLUGIN_SETTINGS),
+};