@downcity/plugins 1.0.96 → 1.0.108

package/src/image/types/ImagePlugin.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里仅定义图片 plugin 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
- * - 图片生成结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
+ * - 图片成功结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
  * - 字段保持 JSON 可序列化，便于通过 plugin action 与 tool bridge 传递。
  */
 
@@ -24,15 +24,13 @@ export interface ImagePluginTextContent {
 }
 
 /**
- * 图片生成参考图片内容片段。
+ * 图片生成图片内容片段。
  */
 export interface ImagePluginFileContent {
   /** 内容类型，固定为图片。 */
   type: "image";
-  /** 远程图片 URL。 */
-  url?: string;
-  /** data URL 图片内容。 */
-  data_url?: string;
+  /** 图片地址，支持 http(s) URL、本地绝对路径或相对项目根目录的路径。 */
+  url: string;
   /** 图片 MIME 类型，例如 `image/png`。 */
   media_type?: string;
 }
@@ -45,13 +43,27 @@ export type ImagePluginContent =
   | ImagePluginFileContent;
 
 /**
- * 图片生成上下文消息。
+ * ImagePlugin 内部解析后的图片内容片段。
  */
-export interface ImagePluginMessage {
-  /** 消息角色。 */
-  role: "system" | "user" | "assistant";
-  /** 该消息内的文本与图片内容。 */
-  content: ImagePluginContent[];
+export type ImagePluginResolvedContent =
+  | ImagePluginContent
+  | {
+    /** 内容类型，固定为图片。 */
+    type: "image";
+    /** 本地图片由 ImagePlugin 读取后转换得到的 data URL。 */
+    data_url: string;
+    /** 图片 MIME 类型，例如 `image/png`。 */
+    media_type: string;
+  };
+
+/**
+ * ImagePlugin 内部解析后的图片消息。
+ */
+export interface ImagePluginResolvedMessage {
+  /** 消息角色。ImagePlugin 目前只会生成单条 user 消息。 */
+  role: "user";
+  /** 已解析的文本与图片内容。 */
+  content: ImagePluginResolvedContent[];
 }
 
 /**
@@ -62,8 +74,45 @@ export interface ImagePluginInput {
   model?: string;
   /** 单句快捷提示词。 */
   prompt?: string;
-  /** 多轮或多模态图片生成上下文。 */
-  messages?: ImagePluginMessage[];
+  /** 简单多模态内容。带参考图或改图时使用。 */
+  content?: ImagePluginContent[];
+  /** 生成图片数量。 */
+  n?: number;
+  /** 生成图片数量，兼容部分上游使用的 count 命名。 */
+  count?: number;
+  /** 图片尺寸，例如 `1024x1024`。 */
+  size?: string;
+  /** 图片宽高比，例如 `1:1`。 */
+  aspect_ratio?: string;
+  /** 图片宽高比，兼容部分上游使用的 ratio 命名。 */
+  ratio?: string;
+  /** 图片质量，例如 `standard`、`hd`、`ultra`、`4k`。 */
+  quality?: string;
+  /** 随机种子。 */
+  seed?: number;
+  /** 业务侧任务 ID，用于 provider 侧幂等、追踪和恢复。 */
+  client_job_id?: string;
+  /** Provider 私有参数，例如 `{ openai: {...}, gemini: {...}, luchi: {...} }`。 */
+  provider_options?: JsonObject;
+  /** 允许外部 image 函数接收其他 JSON 可序列化参数。 */
+  [key: string]: JsonValue | ImagePluginContent[] | undefined;
+}
+
+/**
+ * ImagePlugin 传给 image_create 回调的已解析输入。
+ *
+ * 关键点（中文）
+ * - Agent 公开 payload 只使用 `prompt` 或 `content`。
+ * - 当公开 payload 使用 `content` 时，ImagePlugin 会把本地图片读取为 data URL，并把内容转成 `messages`。
+ * - 这个类型只描述 ImagePlugin 到 City / provider adapter 的内部边界，不是 Agent 调用 payload。
+ */
+export interface ImagePluginResolvedInput {
+  /** 图片模型引用。 */
+  model?: string;
+  /** 单句快捷提示词。纯文本生成时保留。 */
+  prompt?: string;
+  /** 已解析后的多模态消息。带参考图或改图时由 `content` 转换得到。 */
+  messages?: ImagePluginResolvedMessage[];
   /** 生成图片数量。 */
   n?: number;
   /** 生成图片数量，兼容部分上游使用的 count 命名。 */
@@ -83,11 +132,11 @@ export interface ImagePluginInput {
   /** Provider 私有参数，例如 `{ openai: {...}, gemini: {...}, luchi: {...} }`。 */
   provider_options?: JsonObject;
   /** 允许外部 image 函数接收其他 JSON 可序列化参数。 */
-  [key: string]: JsonValue | ImagePluginMessage[] | undefined;
+  [key: string]: JsonValue | ImagePluginResolvedMessage[] | undefined;
 }
 
 /**
- * ImagePlugin 生成结果。
+ * ImagePlugin 图片成功结果。
  */
 export type ImagePluginResult = UIMessage;
 
@@ -136,21 +185,37 @@ export interface ImagePluginJobResult {
 export interface ImagePluginJobResultInput {
   /** 图片任务 ID，由 `image_create` 返回。 */
   job_id: string;
-  /** 是否持续轮询直到任务进入成功或失败终态，默认由 action 决定。 */
-  until_finish?: boolean;
-  /** 单次查询最大等待时间，单位毫秒。 */
-  timeout_ms?: number;
-  /** 轮询间隔下限，单位毫秒。 */
-  min_poll_interval_ms?: number;
-  /** 轮询间隔上限，单位毫秒。 */
-  max_poll_interval_ms?: number;
+  /**
+   * 是否阻塞等待任务到达终态（`succeeded` / `failed`）。
+   *
+   * 关键点（中文）
+   * - 默认 false：行为与历史一致，调用一次 provider 即返回。
+   * - true：plugin 内部按 `poll_interval_ms` 节奏轮询，直到任务终止或 `max_wait_ms` 到期。
+   */
+  until_done?: boolean;
+  /**
+   * 轮询的总等待上限（毫秒）。
+   *
+   * 关键点（中文）
+   * - 仅当 `until_done` 为 true 时生效。
+   * - 默认 60_000；命中上限后返回当前最后一次状态，不抛错。
+   */
+  max_wait_ms?: number;
+  /**
+   * 单次轮询之间的等待间隔（毫秒）。
+   *
+   * 关键点（中文）
+   * - 仅当 `until_done` 为 true 时生效。
+   * - 默认 1500；若 provider 返回 `poll_after_ms`，则取两者较大值。
+   */
+  poll_interval_ms?: number;
 }
 
 /**
  * ImagePlugin 可见模型信息。
  */
 export interface ImagePluginModel {
-  /** 模型唯一 ID，用于 `image_create` / `generate` payload 的 `model` 字段。 */
+  /** 模型唯一 ID，用于 `image_create` payload 的 `model` 字段。 */
   id: string;
   /** 模型展示名称。 */
   name: string;
@@ -190,7 +255,7 @@ export interface ImagePluginOptions {
   description?: string;
   /** 创建图片生成任务，通常传入 `(input) => city.ai.image_create(input)`。 */
   image_create?: (
-    input: ImagePluginInput,
+    input: ImagePluginResolvedInput,
   ) => Promise<ImagePluginJobCreateResult> | ImagePluginJobCreateResult;
   /** 查询图片生成任务，通常传入 `(input) => city.ai.image_result(input)`。 */
   image_result?: (
@@ -198,10 +263,4 @@ export interface ImagePluginOptions {
   ) => Promise<ImagePluginJobResult> | ImagePluginJobResult;
   /** 列出可用图片模型，通常传入 `async () => city.ai.listModels().then((catalog) => catalog.forModality("image"))`。 */
   list_models?: () => Promise<ImagePluginModel[]> | ImagePluginModel[];
-  /** 图片任务最大等待时间，默认 300000ms。 */
-  timeout_ms?: number;
-  /** 轮询间隔下限，默认 100ms。 */
-  min_poll_interval_ms?: number;
-  /** 轮询间隔上限，默认 10000ms。 */
-  max_poll_interval_ms?: number;
 }

package/src/index.ts

@@ -109,10 +109,12 @@ export type {
   ImagePluginJobResult,
   ImagePluginJobResultInput,
   ImagePluginJobStatus,
-  ImagePluginMessage,
   ImagePluginModel,
   ImagePluginModelsResult,
   ImagePluginOptions,
+  ImagePluginResolvedContent,
+  ImagePluginResolvedInput,
+  ImagePluginResolvedMessage,
   ImagePluginResult,
   ImagePluginTextContent,
 } from "./image/types/ImagePlugin.js";

package/src/memory/MemoryPlugin.ts

@@ -12,6 +12,8 @@ import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/commo
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import { createAction } from "@downcity/agent/internal/plugin/core/PluginActionFactory.js";
+import { z } from "zod";
 import {
   digestMemoryAction,
   readMemoryAction,
@@ -124,7 +126,13 @@ export class MemoryPlugin extends BasePlugin {
    * 当前 plugin action 定义表。
    */
   readonly actions: PluginActions = {
-    status: {
+    status: createAction({
+      description: "查看 memory wiki 状态（wiki/source/working）。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {} },
+      },
+      examples: [{ title: "查看状态", payload: {} }],
       command: {
         description: "查看 memory wiki 状态（wiki/source/working）",
         mapInput() {
@@ -135,8 +143,30 @@ export class MemoryPlugin extends BasePlugin {
         const state = this.getOrCreateRuntimeState(params.context);
         return await statusMemoryAction(params.context, state);
       },
-    },
-    search: {
+    }),
+    search: createAction({
+      description: "检索 memory wiki，可选择是否扩展到 source 层。",
+      input_schema: {
+        zod: z.object({
+          query: z.string(),
+          maxResults: z.number().optional(),
+          minScore: z.number().optional(),
+          includeSources: z.boolean().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["query"],
+          properties: {
+            query: { type: "string", description: "检索关键词" },
+            maxResults: { type: "number", description: "返回条数上限" },
+            minScore: { type: "number", description: "最小相关分数" },
+            includeSources: { type: "boolean", description: "是否包含 source 层" },
+          },
+        },
+      },
+      examples: [
+        { title: "搜索记忆", payload: { query: "用户偏好" } },
+      ],
       command: {
         description: "检索 memory wiki",
         configure(command: Command) {
@@ -163,7 +193,7 @@ export class MemoryPlugin extends BasePlugin {
         },
       },
       execute: async (params) => {
-        const body = readBodyObject(params.payload);
+        const body = readBodyObject(params.input);
         const state = this.getOrCreateRuntimeState(params.context);
         return await searchMemoryAction(params.context, state, {
           query: readString(body, "query"),
@@ -172,8 +202,28 @@ export class MemoryPlugin extends BasePlugin {
           includeSources: readOptionalBoolean(body, "includeSources"),
         });
       },
-    },
-    read: {
+    }),
+    read: createAction({
+      description: "读取 memory wiki/source 文件片段。",
+      input_schema: {
+        zod: z.object({
+          path: z.string(),
+          from: z.number().optional(),
+          lines: z.number().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["path"],
+          properties: {
+            path: { type: "string", description: "记忆文件路径（相对项目根目录）" },
+            from: { type: "number", description: "起始行（1-based）" },
+            lines: { type: "number", description: "读取行数" },
+          },
+        },
+      },
+      examples: [
+        { title: "读取整页", payload: { path: ".downcity/memory/wiki/index.md" } },
+      ],
       command: {
         description: "读取 memory wiki/source 文件片段",
         configure(command: Command) {
@@ -196,15 +246,37 @@ export class MemoryPlugin extends BasePlugin {
         },
       },
       execute: async (params) => {
-        const body = readBodyObject(params.payload);
+        const body = readBodyObject(params.input);
         return await readMemoryAction(params.context, {
           path: readString(body, "path"),
           from: readOptionalNumber(body, "from"),
           lines: readOptionalNumber(body, "lines"),
         });
       },
-    },
-    remember: {
+    }),
+    remember: createAction({
+      description: "把事实/偏好/决策记入 memory wiki。",
+      input_schema: {
+        zod: z.object({
+          content: z.string(),
+          topic: z.string().optional(),
+          path: z.string().optional(),
+          source: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["content"],
+          properties: {
+            content: { type: "string", description: "需要记住的内容" },
+            topic: { type: "string", description: "记忆主题" },
+            path: { type: "string", description: "目标 wiki page 路径" },
+            source: { type: "string", description: "来源说明" },
+          },
+        },
+      },
+      examples: [
+        { title: "记住偏好", payload: { content: "用户偏好简短回答", topic: "user-prefs" } },
+      ],
       command: {
         description: "把事实/偏好/决策记入 memory wiki",
         configure(command: Command) {
@@ -231,7 +303,7 @@ export class MemoryPlugin extends BasePlugin {
         },
       },
       execute: async (params) => {
-        const body = readBodyObject(params.payload);
+        const body = readBodyObject(params.input);
         return await rememberMemoryAction(params.context, this.options, {
           content: readString(body, "content"),
           topic: readOptionalString(body, "topic"),
@@ -239,8 +311,26 @@ export class MemoryPlugin extends BasePlugin {
           source: readOptionalString(body, "source"),
         });
       },
-    },
-    digest: {
+    }),
+    digest: createAction({
+      description: "把 session 提炼进 memory wiki。",
+      input_schema: {
+        zod: z.object({
+          sessionId: z.string(),
+          maxMessages: z.number().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["sessionId"],
+          properties: {
+            sessionId: { type: "string", description: "会话 ID" },
+            maxMessages: { type: "number", description: "提取消息窗口" },
+          },
+        },
+      },
+      examples: [
+        { title: "提炼会话", payload: { sessionId: "sess-1" } },
+      ],
       command: {
         description: "把 session 提炼进 memory wiki",
         configure(command: Command) {
@@ -259,14 +349,37 @@ export class MemoryPlugin extends BasePlugin {
         },
       },
       execute: async (params) => {
-        const body = readBodyObject(params.payload);
+        const body = readBodyObject(params.input);
         return await digestMemoryAction(params.context, this.options, {
           sessionId: readString(body, "sessionId"),
           maxMessages: readOptionalNumber(body, "maxMessages"),
         });
       },
-    },
-    revise: {
+    }),
+    revise: createAction({
+      description: "基于新证据修订 memory wiki page。",
+      input_schema: {
+        zod: z.object({
+          path: z.string(),
+          instruction: z.string(),
+          evidence: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["path", "instruction"],
+          properties: {
+            path: { type: "string", description: "目标 wiki page 路径" },
+            instruction: { type: "string", description: "修订指令" },
+            evidence: { type: "string", description: "新证据" },
+          },
+        },
+      },
+      examples: [
+        {
+          title: "修订条目",
+          payload: { path: "wiki/preferences.md", instruction: "替换最新偏好" },
+        },
+      ],
       command: {
         description: "基于新证据修订 memory wiki page",
         configure(command: Command) {
@@ -287,14 +400,14 @@ export class MemoryPlugin extends BasePlugin {
         },
       },
       execute: async (params) => {
-        const body = readBodyObject(params.payload);
+        const body = readBodyObject(params.input);
         return await reviseMemoryAction(params.context, this.options, {
           path: readString(body, "path"),
           instruction: readString(body, "instruction"),
           evidence: readOptionalString(body, "evidence"),
         });
       },
-    },
+    }),
   };
 
   /**

package/src/skill/Plugin.ts

@@ -8,8 +8,11 @@
  */
 
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import { createAction } from "@downcity/agent/internal/plugin/core/PluginActionFactory.js";
+import { z } from "zod";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginActionResult } from "@downcity/agent/internal/types/plugin/PluginAction.js";
 import type {
   SkillPluginFindPayload,
   SkillPluginInstallPayload,
@@ -104,7 +107,26 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
       return [SKILL_PLUGIN_PROMPT, dynamicText].filter(Boolean).join("\n\n");
     },
     actions: {
-      [SKILL_PLUGIN_ACTIONS.find]: {
+      [SKILL_PLUGIN_ACTIONS.find]: createAction({
+        description: "查找 `list` 中不存在的未学会 skills（缺失时再 install）",
+        input_schema: {
+          zod: z.object({
+            query: z.string(),
+          }),
+          json_schema: {
+            type: "object",
+            required: ["query"],
+            properties: {
+              query: { type: "string", description: "Skill 查询词" },
+            },
+          },
+        },
+        examples: [
+          {
+            title: "查找 skill",
+            payload: { query: "web-search" },
+          },
+        ],
         command: {
           description: "查找 `list` 中不存在的未学会 skills（缺失时再 install）",
           configure(command) {
@@ -116,8 +138,8 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
             return { query };
           },
         },
-        async execute(params) {
-          const payload = params.payload as SkillPluginFindPayload;
+        async execute(params): Promise<PluginActionResult<JsonObject>> {
+          const payload = params.input as SkillPluginFindPayload;
           const rootPath = params.context.rootPath;
           const exactLearned = findLearnedSkillExact(
             rootPath,
@@ -134,7 +156,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
                 nextAction: "lookup",
                 learnedSkill: exactLearned,
                 learnedHints: [],
-              },
+              } as JsonObject,
             };
           }
 
@@ -154,11 +176,36 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
               nextAction: "install",
               learnedSkill: null,
               learnedHints,
-            },
+            } as JsonObject,
           };
         },
-      },
-      [SKILL_PLUGIN_ACTIONS.install]: {
+      }),
+      [SKILL_PLUGIN_ACTIONS.install]: createAction({
+        description: "安装 `list` 中不存在的 skill（完成后请先 lookup）",
+        input_schema: {
+          zod: z.object({
+            spec: z.string(),
+            global: z.boolean().optional(),
+            yes: z.boolean().optional(),
+            agent: z.string().optional(),
+          }),
+          json_schema: {
+            type: "object",
+            required: ["spec"],
+            properties: {
+              spec: { type: "string", description: "Skill 安装 spec" },
+              global: { type: "boolean", description: "是否全局安装" },
+              yes: { type: "boolean", description: "跳过确认" },
+              agent: { type: "string", description: "指定 agent" },
+            },
+          },
+        },
+        examples: [
+          {
+            title: "安装 skill",
+            payload: { spec: "web-search", global: true, yes: true },
+          },
+        ],
         command: {
           description: "安装 `list` 中不存在的 skill（完成后请先 lookup）",
           configure(command) {
@@ -179,8 +226,8 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
             };
           },
         },
-        async execute(params) {
-          const payload = params.payload as SkillPluginInstallPayload;
+        async execute(params): Promise<PluginActionResult<JsonObject>> {
+          const payload = params.input as SkillPluginInstallPayload;
           const rootPath = params.context.rootPath;
           const queryFromSpec = inferSkillQueryFromSpec(payload.spec);
           const beforeList = listSkills(rootPath, options).skills;
@@ -201,7 +248,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
                 queryFromSpec,
                 addedSkills: [],
                 learnedSkill: learnedBefore,
-              },
+              } as JsonObject,
             };
           }
 
@@ -228,11 +275,25 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
               queryFromSpec,
               addedSkills,
               learnedSkill: learnedAfter || null,
-            },
+            } as JsonObject,
           };
         },
-      },
-      [SKILL_PLUGIN_ACTIONS.list]: {
+      }),
+      [SKILL_PLUGIN_ACTIONS.list]: createAction({
+        description: "列出当前已学会（本地可发现）的 skills",
+        input_schema: {
+          zod: z.object({}).passthrough(),
+          json_schema: {
+            type: "object",
+            properties: {},
+          },
+        },
+        examples: [
+          {
+            title: "列出 skills",
+            payload: {},
+          },
+        ],
         command: {
           description: "列出当前已学会（本地可发现）的 skills",
           mapInput() {
@@ -242,14 +303,33 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
         api: {
           method: "GET",
         },
-        execute(params) {
+        execute(params): PluginActionResult<JsonObject> {
           return {
             success: true,
-            data: listSkills(params.context.rootPath, options),
+            data: listSkills(params.context.rootPath, options) as unknown as JsonObject,
           };
         },
-      },
-      [SKILL_PLUGIN_ACTIONS.lookup]: {
+      }),
+      [SKILL_PLUGIN_ACTIONS.lookup]: createAction({
+        description: "读取已学会 skill 内容（SKILL.md）",
+        input_schema: {
+          zod: z.object({
+            name: z.string(),
+          }),
+          json_schema: {
+            type: "object",
+            required: ["name"],
+            properties: {
+              name: { type: "string", description: "Skill 名称" },
+            },
+          },
+        },
+        examples: [
+          {
+            title: "读取 skill",
+            payload: { name: "web-search" },
+          },
+        ],
         command: {
           description: "读取已学会 skill 内容（SKILL.md）",
           configure(command) {
@@ -270,8 +350,8 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
             return { name };
           },
         },
-        async execute(params) {
-          const payload = params.payload as SkillPluginLookupPayload;
+        async execute(params): Promise<PluginActionResult<JsonObject>> {
+          const payload = params.input as SkillPluginLookupPayload;
           const result = await lookupSkill({
             projectRoot: params.context.rootPath,
             request: {
@@ -316,10 +396,10 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
                 toolOutputMessage:
                   "skill lookup success; content injected as <skill> user message.",
               },
-            },
+            } as JsonObject,
           };
         },
-      },
+      }),
     },
   };
 }