@downcity/plugins 1.0.216 → 1.0.236

package/src/contact/runtime/Paths.ts

@@ -22,118 +22,118 @@ function cleanSegment(input: string, label: string): string {
 /**
  * contact 根目录。
  */
-export function getContactRootPath(projectRoot: string): string {
-  return path.join(projectRoot, ".downcity", "contact");
+export function getContactRootPath(project_root: string): string {
+  return path.join(project_root, ".downcity", "contact");
 }
 
 /**
  * contacts 根目录。
  */
-export function getContactsRootPath(projectRoot: string): string {
-  return path.join(getContactRootPath(projectRoot), "contacts");
+export function getContactsRootPath(project_root: string): string {
+  return path.join(getContactRootPath(project_root), "contacts");
 }
 
 /**
  * 单个 contact 目录。
  */
 export function getContactDirectoryPath(
-  projectRoot: string,
+  project_root: string,
   contactId: string,
 ): string {
-  return path.join(getContactsRootPath(projectRoot), cleanSegment(contactId, "contactId"));
+  return path.join(getContactsRootPath(project_root), cleanSegment(contactId, "contactId"));
 }
 
 /**
  * 单个 contact 元信息文件。
  */
-export function getContactJsonPath(projectRoot: string, contactId: string): string {
-  return path.join(getContactDirectoryPath(projectRoot, contactId), "contact.json");
+export function getContactJsonPath(project_root: string, contactId: string): string {
+  return path.join(getContactDirectoryPath(project_root, contactId), "contact.json");
 }
 
 /**
  * 单个 contact 的长期对话历史文件。
  */
 export function getContactMessagesPath(
-  projectRoot: string,
+  project_root: string,
   contactId: string,
 ): string {
-  return path.join(getContactDirectoryPath(projectRoot, contactId), "messages.jsonl");
+  return path.join(getContactDirectoryPath(project_root, contactId), "messages.jsonl");
 }
 
 /**
  * link 根目录。
  */
-export function getContactLinksRootPath(projectRoot: string): string {
-  return path.join(getContactRootPath(projectRoot), "links");
+export function getContactLinksRootPath(project_root: string): string {
+  return path.join(getContactRootPath(project_root), "links");
 }
 
 /**
  * 单个 link 记录文件。
  */
-export function getContactLinkPath(projectRoot: string, linkId: string): string {
-  return path.join(getContactLinksRootPath(projectRoot), `${cleanSegment(linkId, "linkId")}.json`);
+export function getContactLinkPath(project_root: string, linkId: string): string {
+  return path.join(getContactLinksRootPath(project_root), `${cleanSegment(linkId, "linkId")}.json`);
 }
 
 /**
  * inbox 根目录。
  */
-export function getContactInboxRootPath(projectRoot: string): string {
-  return path.join(getContactRootPath(projectRoot), "inbox");
+export function getContactInboxRootPath(project_root: string): string {
+  return path.join(getContactRootPath(project_root), "inbox");
 }
 
 /**
  * 单个 inbox share 目录。
  */
 export function getContactInboxSharePath(
-  projectRoot: string,
+  project_root: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxRootPath(projectRoot), cleanSegment(shareId, "shareId"));
+  return path.join(getContactInboxRootPath(project_root), cleanSegment(shareId, "shareId"));
 }
 
 /**
  * 单个 inbox share 元信息文件。
  */
 export function getContactInboxShareMetaPath(
-  projectRoot: string,
+  project_root: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(projectRoot, shareId), "meta.json");
+  return path.join(getContactInboxSharePath(project_root, shareId), "meta.json");
 }
 
 /**
  * 单个 inbox share payload 文件。
  */
 export function getContactInboxSharePayloadPath(
-  projectRoot: string,
+  project_root: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(projectRoot, shareId), "payload.json");
+  return path.join(getContactInboxSharePath(project_root, shareId), "payload.json");
 }
 
 /**
  * 单个 inbox share 文件根目录。
  */
 export function getContactInboxShareFilesPath(
-  projectRoot: string,
+  project_root: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(projectRoot, shareId), "files");
+  return path.join(getContactInboxSharePath(project_root, shareId), "files");
 }
 
 /**
  * received 根目录。
  */
-export function getContactReceivedRootPath(projectRoot: string): string {
-  return path.join(getContactRootPath(projectRoot), "received");
+export function getContactReceivedRootPath(project_root: string): string {
+  return path.join(getContactRootPath(project_root), "received");
 }
 
 /**
  * 单个 received share 目录。
  */
 export function getContactReceivedSharePath(
-  projectRoot: string,
+  project_root: string,
   shareId: string,
 ): string {
-  return path.join(getContactReceivedRootPath(projectRoot), cleanSegment(shareId, "shareId"));
+  return path.join(getContactReceivedRootPath(project_root), cleanSegment(shareId, "shareId"));
 }

package/src/contact/runtime/RemoteClient.ts

@@ -2,7 +2,7 @@
  * contact 远端 HTTP 客户端。
  *
  * 关键点（中文）
- * - contact 的 agent-to-agent 调用统一走 plugin runtime command 接口。
+ * - contact 的 agent-to-agent 调用统一走 Plugin Action 接口。
  * - 已建联后的敏感调用必须携带 contact token。
  */
 
@@ -25,24 +25,24 @@ function normalizeEndpoint(endpoint: string): string {
   return url.toString().replace(/\/$/, "");
 }
 
-function unwrapPluginCommandEnvelope<T>(value: T): T {
+function unwrap_plugin_action_envelope<T>(value: T): T {
   if (!isRecord(value)) return value;
   const inner = value.data;
   if (typeof value.success === "boolean" && isRecord(inner)) {
-    // 关键点（中文）：统一 command 路由会包一层 `{ success, data }`。
+    // 关键点（中文）：统一 Action 路由会包一层 `{ success, data }`。
     return inner as T;
   }
   return value;
 }
 
-async function postPluginCommand<T>(params: {
+async function post_plugin_action<T>(params: {
   endpoint: string;
-  command: string;
+  action: string;
   body?: JsonValue;
   token?: string;
   wrapBody?: boolean;
 }): Promise<T> {
-  const url = new URL("/api/plugins/command", normalizeEndpoint(params.endpoint)).toString();
+  const url = new URL("/api/plugins/action", normalizeEndpoint(params.endpoint)).toString();
   const payloadBody =
     params.wrapBody
       ? {
@@ -66,8 +66,8 @@ async function postPluginCommand<T>(params: {
     method: "POST",
     headers,
     body: JSON.stringify({
-      pluginName: "contact",
-      command: params.command,
+      plugin_name: "contact",
+      action_name: params.action,
       payload: payloadBody,
     }),
   });
@@ -78,7 +78,7 @@ async function postPluginCommand<T>(params: {
   if (!response.ok) {
     throw new Error(data?.error || data?.message || `HTTP ${response.status}`);
   }
-  return unwrapPluginCommandEnvelope<T>(data);
+  return unwrap_plugin_action_envelope<T>(data);
 }
 
 /**
@@ -88,9 +88,9 @@ export async function callContactPing<T>(params: {
   endpoint: string;
   token?: string;
 }): Promise<T> {
-  return await postPluginCommand<T>({
+  return await post_plugin_action<T>({
     endpoint: params.endpoint,
-    command: "remoteping",
+    action: "remoteping",
     token: params.token,
   });
 }
@@ -102,9 +102,9 @@ export async function callContactApprove<T>(params: {
   endpoint: string;
   body: JsonValue;
 }): Promise<T> {
-  return await postPluginCommand<T>({
+  return await post_plugin_action<T>({
     endpoint: params.endpoint,
-    command: "remoteapprove",
+    action: "remoteapprove",
     body: params.body,
   });
 }
@@ -116,9 +116,9 @@ export async function callContactConfirm<T>(params: {
   endpoint: string;
   body: JsonValue;
 }): Promise<T> {
-  return await postPluginCommand<T>({
+  return await post_plugin_action<T>({
     endpoint: params.endpoint,
-    command: "remoteconfirm",
+    action: "remoteconfirm",
     body: params.body,
   });
 }
@@ -131,9 +131,9 @@ export async function callContactChat<T>(params: {
   token: string;
   body: JsonValue;
 }): Promise<T> {
-  return await postPluginCommand<T>({
+  return await post_plugin_action<T>({
     endpoint: params.endpoint,
-    command: "remotechat",
+    action: "remotechat",
     token: params.token,
     body: params.body,
     wrapBody: true,
@@ -148,9 +148,9 @@ export async function callContactShare<T>(params: {
   token: string;
   body: JsonValue;
 }): Promise<T> {
-  return await postPluginCommand<T>({
+  return await post_plugin_action<T>({
     endpoint: params.endpoint,
-    command: "remoteshare",
+    action: "remoteshare",
     token: params.token,
     body: params.body,
     wrapBody: true,

package/src/contact/runtime/ShareBundle.ts

@@ -9,7 +9,7 @@
 import crypto from "node:crypto";
 import fs from "fs-extra";
 import path from "node:path";
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type {
   ContactInboxShareFileInput,
   ContactInboxShareMeta,
@@ -127,7 +127,7 @@ export async function createShareInput(params: {
   /**
    * 当前 agent context。
    */
-  context: AgentContext;
+  context: PluginContext;
   /**
    * 发送方 contact id。
    */
@@ -172,7 +172,7 @@ export async function createShareInput(params: {
   }
 
   for (const rawPath of Array.isArray(params.paths) ? params.paths : []) {
-    const sourcePath = path.resolve(params.context.rootPath, String(rawPath || "").trim());
+    const sourcePath = path.resolve(params.context.workspace_path, String(rawPath || "").trim());
     const itemRoot = createItemRoot(sourcePath);
     const collected = await collectPathFiles({
       sourcePath,
@@ -235,7 +235,7 @@ export async function receiveShare(params: {
   /**
    * 项目根目录。
    */
-  projectRoot: string;
+  project_root: string;
   /**
    * share id。
    */
@@ -250,22 +250,22 @@ export async function receiveShare(params: {
    */
   receivedPath: string;
 }> {
-  const payload = await readContactInboxSharePayload(params.projectRoot, params.shareId);
+  const payload = await readContactInboxSharePayload(params.project_root, params.shareId);
   if (!payload) throw new Error(`Share payload not found: ${params.shareId}`);
   if (payload.kind !== "share") throw new Error(`Unsupported share payload: ${payload.kind}`);
 
-  const receivedPath = getContactReceivedSharePath(params.projectRoot, params.shareId);
+  const receivedPath = getContactReceivedSharePath(params.project_root, params.shareId);
   await fs.ensureDir(receivedPath);
   await fs.writeJson(path.join(receivedPath, "payload.json"), payload, { spaces: 2 });
 
-  const filesRoot = getInboxShareFilesRoot(params.projectRoot, params.shareId);
+  const filesRoot = getInboxShareFilesRoot(params.project_root, params.shareId);
   if (await fs.pathExists(filesRoot)) {
     await fs.copy(filesRoot, path.join(receivedPath, "files"), {
       overwrite: true,
     });
   }
 
-  await markContactInboxShareReceived(params.projectRoot, params.shareId);
+  await markContactInboxShareReceived(params.project_root, params.shareId);
   return {
     itemCount: payload.items.length,
     receivedPath,

package/src/contact/types/Contact.ts

@@ -51,7 +51,7 @@ export interface AgentContact {
   /**
    * contact 创建时间戳。
    */
-  createdAt: number;
+  created_at: number;
   /**
    * 最近一次成功通信时间戳。
    */
@@ -78,5 +78,5 @@ export interface ContactChatMessage {
   /**
    * 消息创建时间戳。
    */
-  createdAt: number;
+  created_at: number;
 }

package/src/contact/types/ContactApproval.ts

@@ -43,7 +43,7 @@ export interface ApproveContactLinkRequestInput {
   /**
    * 当前 agent 项目根目录，用于读取 link 记录并保存 contact。
    */
-  projectRoot: string;
+  project_root: string;
   /**
    * 当前 agent 名称，也就是 link 所属方名称。
    */
@@ -121,7 +121,7 @@ export interface ConfirmContactLinkRequestInput {
   /**
    * 当前 agent 项目根目录，用于读取 link 记录并更新 contact。
    */
-  projectRoot: string;
+  project_root: string;
   /**
    * 当前 agent 名称，也就是 link 所属方名称。
    */

package/src/contact/types/ContactChat.ts

@@ -21,7 +21,7 @@ export interface ContactRemoteChatRequest {
   /**
    * 消息创建时间戳。
    */
-  createdAt: number;
+  created_at: number;
 }
 
 /**

package/src/contact/types/ContactLink.ts

@@ -33,11 +33,11 @@ export interface ContactLinkCodePayload {
   /**
    * link 创建时间戳。
    */
-  createdAt: number;
+  created_at: number;
   /**
    * link 过期时间戳。
    */
-  expiresAt: number;
+  expires_at: number;
 }
 
 /**
@@ -63,11 +63,11 @@ export interface ContactLinkRecord {
   /**
    * link 创建时间戳。
    */
-  createdAt: number;
+  created_at: number;
   /**
    * link 过期时间戳。
    */
-  expiresAt: number;
+  expires_at: number;
   /**
    * link 被使用的时间戳。
    */

package/src/image/ImagePlugin.ts

@@ -4,15 +4,15 @@
  * 关键点（中文）
  * - 对 Agent 暴露 `image_create` / `image_result` 两步式任务 action。
  * - City / provider 的图片能力通过 image_create / image_result 任务函数注入。
- * - 成功结果返回 AI SDK UIMessage，后续由 plugin tool bridge 抽取 file parts 写回 assistant 消息。
+ * - 成功结果返回本地文件 UI Parts，Plugin Action 直接声明应写入的 Assistant Message。
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { createAction } from "@downcity/agent";
+import { create_action } from "@downcity/agent";
 import { BasePlugin } from "@downcity/agent";
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type {
   JsonObject,
   JsonValue,
@@ -234,7 +234,7 @@ async function local_image_to_data_url(input: {
  * 归一化单个图片内容片段。
  */
 async function normalize_image_content_part(
-  context: AgentContext,
+  context: PluginContext,
   part: ImagePluginContent,
 ): Promise<ImagePluginResolvedContent> {
   if (part.type === "text") return part;
@@ -253,7 +253,7 @@ async function normalize_image_content_part(
     };
   }
   const local = await local_image_to_data_url({
-    root_path: context.rootPath,
+    root_path: context.workspace_path,
     image_url: url,
     media_type: part.media_type,
   });
@@ -299,7 +299,7 @@ function copy_resolved_image_input(input: ImagePluginInput): ImagePluginResolved
  * 把 Agent 友好的公开输入转成 City 图片任务使用的输入。
  */
 async function normalize_image_create_input(
-  context: AgentContext,
+  context: PluginContext,
   input: ImagePluginInput,
 ): Promise<ImagePluginResolvedInput> {
   assert_public_image_create_input(input);
@@ -323,7 +323,7 @@ async function normalize_image_create_input(
  * 为图片创建输入解析并补齐插件级默认模型。
  */
 async function apply_default_image_model(
-  context: AgentContext,
+  context: PluginContext,
   input: ImagePluginResolvedInput,
   default_model: ImagePluginDefaultModel | undefined,
 ): Promise<ImagePluginResolvedInput> {
@@ -392,6 +392,16 @@ function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   if (!record || !Array.isArray(record.parts)) {
     throw new TypeError("ImagePlugin image provider must return an AI SDK UIMessage");
   }
+  for (const part of record.parts) {
+    const part_record = to_record(part);
+    if (part_record?.type !== "file") continue;
+    const url = String(part_record.url || "").trim();
+    if (!url || url.startsWith("data:") || HTTP_URL_RE.test(url)) {
+      throw new TypeError(
+        "ImagePlugin result file parts must be saved locally before returning",
+      );
+    }
+  }
   return result;
 }
 
@@ -525,7 +535,7 @@ export class ImagePlugin extends BasePlugin {
   /**
    * 图片插件给模型的使用说明。
    */
-  system(_context: AgentContext): string {
+  system(_context: PluginContext): string {
     return [
       "# Image Plugin",
       "",
@@ -611,7 +621,7 @@ export class ImagePlugin extends BasePlugin {
    * 显式 action 集合。
    */
   readonly actions = {
-    models: createAction({
+    models: create_action({
       description: "List image-capable models available to ImagePlugin.",
       input_schema: z.object({}).passthrough(),
       execute: async () => {
@@ -639,7 +649,7 @@ export class ImagePlugin extends BasePlugin {
         }
       },
     }),
-    image_create: createAction({
+    image_create: create_action({
       description:
         "Create an async image job only after explicit user confirmation because image creation consumes quota. Use prompt for text-only generation, or content for reference images and edits.",
       input_schema: {
@@ -711,7 +721,7 @@ export class ImagePlugin extends BasePlugin {
           },
         },
       ],
-      execute: async ({ context, input }: { context: AgentContext; input: JsonValue }) => {
+      execute: async ({ context, input }: { context: PluginContext; input: JsonValue }) => {
         try {
           const normalized_payload = normalize_image_payload(input);
           const normalized_input = await apply_default_image_model(
@@ -735,7 +745,7 @@ export class ImagePlugin extends BasePlugin {
         }
       },
     }),
-    image_result: createAction({
+    image_result: create_action({
       description:
         "Read an async image job. By default reads once; pass until_done=true to block-wait until succeeded/failed or max_wait_ms times out.",
       input_schema: {
@@ -794,16 +804,22 @@ export class ImagePlugin extends BasePlugin {
               message: current.error ?? current.message ?? "image job failed",
             };
           }
-          const data = current.status === "succeeded" && current.result
-            ? current.result as unknown as JsonObject
-            : current as unknown as JsonObject;
+          const { result, ...job } = current;
           return {
             success: true,
-            data,
+            data: job as unknown as JsonObject,
             message:
               current.status === "succeeded"
                 ? "image generated"
                 : `image job ${current.status}`,
+            ...(current.status === "succeeded" && result
+              ? {
+                  messages: [{
+                    role: "assistant" as const,
+                    parts: result.parts,
+                  }],
+                }
+              : {}),
           };
         } catch (error) {
           return {

package/src/image/types/ImagePlugin.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里仅定义图片 plugin 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
  * - 图片成功结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
- * - 字段保持 JSON 可序列化，便于通过 plugin action 与 tool bridge 传递。
+ * - 字段保持 JSON 可序列化，便于通过 Plugin Action 与 Tool 传递。
  */
 
 import type { UIMessage } from "ai";
@@ -12,7 +12,7 @@ import type {
   JsonObject,
   JsonValue,
 } from "@downcity/agent";
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 
 /**
  * 图片生成文本内容片段。
@@ -243,7 +243,7 @@ export interface ImagePluginModelsResult {
  */
 export interface ImagePluginDefaultModelResolverInput {
   /** 当前 Agent 运行上下文，可用于读取项目根目录、会话上下文或宿主状态。 */
-  context: AgentContext;
+  context: PluginContext;
   /** 已解析后的图片生成输入，可用于根据 prompt、messages、尺寸或质量选择模型。 */
   input: ImagePluginResolvedInput;
 }