@downcity/plugins 1.0.95 → 1.0.103

package/src/chat/runtime/ChatPluginActionRegistry.ts

@@ -9,6 +9,8 @@
 
 import type { Command } from "commander";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import { createAction } from "@downcity/agent/internal/plugin/core/PluginActionFactory.js";
+import { z } from "zod";
 import type {
   ChatCloseActionPayload,
   ChatConfigurationActionPayload,
@@ -101,7 +103,12 @@ export function createChatPluginActions(params: {
   channelState: ChatChannelState;
 }): PluginActions {
   return {
-    status: {
+    status: createAction({
+      description: "查看 chat 渠道连接状态。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "查看 chat 渠道连接状态",
         configure(command: Command) {
@@ -113,11 +120,16 @@ export function createChatPluginActions(params: {
         return executeChatStatusAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatStatusActionPayload,
+          payload: actionParams.input as ChatStatusActionPayload,
         });
       },
-    },
-    test: {
+    }),
+    test: createAction({
+      description: "测试 chat 渠道连通性。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "测试 chat 渠道连通性",
         configure(command: Command) {
@@ -129,11 +141,16 @@ export function createChatPluginActions(params: {
         return executeChatTestAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatTestActionPayload,
+          payload: actionParams.input as ChatTestActionPayload,
         });
       },
-    },
-    reconnect: {
+    }),
+    reconnect: createAction({
+      description: "重连 chat 渠道（默认全部）。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "重连 chat 渠道（默认全部）",
         configure(command: Command) {
@@ -145,11 +162,16 @@ export function createChatPluginActions(params: {
         return executeChatReconnectAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatReconnectActionPayload,
+          payload: actionParams.input as ChatReconnectActionPayload,
         });
       },
-    },
-    open: {
+    }),
+    open: createAction({
+      description: "打开（启用）指定 chat 渠道。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "打开 chat 渠道（enabled=true，已配置则尝试启动）",
         configure(command: Command) {
@@ -161,11 +183,16 @@ export function createChatPluginActions(params: {
         return executeChatOpenAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatOpenActionPayload,
+          payload: actionParams.input as ChatOpenActionPayload,
         });
       },
-    },
-    close: {
+    }),
+    close: createAction({
+      description: "关闭（禁用）指定 chat 渠道。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "关闭 chat 渠道（enabled=false，并停止运行）",
         configure(command: Command) {
@@ -177,11 +204,16 @@ export function createChatPluginActions(params: {
         return executeChatCloseAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatCloseActionPayload,
+          payload: actionParams.input as ChatCloseActionPayload,
         });
       },
-    },
-    configuration: {
+    }),
+    configuration: createAction({
+      description: "查看 chat 渠道配置元信息。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "查看 chat 渠道配置元信息（字段、类型、说明）",
         configure(command: Command) {
@@ -192,11 +224,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatConfigurationAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatConfigurationActionPayload,
+          payload: actionParams.input as ChatConfigurationActionPayload,
         });
       },
-    },
-    configure: {
+    }),
+    configure: createAction({
+      description: "更新 chat 渠道运行态参数。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "更新 chat 渠道运行态参数（可选立即重载）",
         configure(command: Command) {
@@ -214,11 +251,16 @@ export function createChatPluginActions(params: {
         return executeChatConfigureAction({
           state: params.channelState,
           context: actionParams.context,
-          payload: actionParams.payload as ChatConfigureActionPayload,
+          payload: actionParams.input as ChatConfigureActionPayload,
         });
       },
-    },
-    list: {
+    }),
+    list: createAction({
+      description: "列出当前 agent 已记录的 chat 会话。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "列出当前 agent 已记录的 chat 会话（chatTitle/chatKey）",
         configure(command: Command) {
@@ -232,11 +274,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatListAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatListActionPayload,
+          payload: actionParams.input as ChatListActionPayload,
         });
       },
-    },
-    info: {
+    }),
+    info: createAction({
+      description: "查看指定 chat 会话的路由/路径/上下文快照。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "查看指定 chat 会话信息（路由/本地路径/上下文快照）",
         configure(command: Command) {
@@ -249,11 +296,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatInfoAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatInfoActionPayload,
+          payload: actionParams.input as ChatInfoActionPayload,
         });
       },
-    },
-    send: {
+    }),
+    send: createAction({
+      description: "向目标 chatKey 发送消息（支持文本/附件/延迟）。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "发送消息到目标 chatKey",
         configure(command: Command) {
@@ -274,11 +326,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatSendAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatSendActionPayload,
+          payload: actionParams.input as ChatSendActionPayload,
         });
       },
-    },
-    react: {
+    }),
+    react: createAction({
+      description: "给目标消息贴表情（当前仅 Telegram 支持）。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "给目标消息贴表情（当前仅 Telegram 支持）",
         configure(command: Command) {
@@ -297,11 +354,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatReactAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatReactActionPayload,
+          payload: actionParams.input as ChatReactActionPayload,
         });
       },
-    },
-    context: {
+    }),
+    context: createAction({
+      description: "查看当前会话上下文快照。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "查看当前会话上下文快照",
         configure(command: Command) {
@@ -318,11 +380,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatContextAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatSessionActionPayload,
+          payload: actionParams.input as ChatSessionActionPayload,
         });
       },
-    },
-    delete: {
+    }),
+    delete: createAction({
+      description: "彻底删除指定 chat 会话（映射+历史+context）。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "彻底删除指定 chat 会话（映射+历史+context）",
         configure(command: Command) {
@@ -335,11 +402,16 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatDeleteAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatDeleteActionPayload,
+          payload: actionParams.input as ChatDeleteActionPayload,
         });
       },
-    },
-    history: {
+    }),
+    history: createAction({
+      description: "读取 chat 历史消息。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
       command: {
         description: "读取 chat 历史消息（默认最近 30 条）",
         configure(command: Command) {
@@ -359,9 +431,9 @@ export function createChatPluginActions(params: {
       execute: async (actionParams) => {
         return executeChatHistoryAction({
           context: actionParams.context,
-          payload: actionParams.payload as ChatHistoryActionPayload,
+          payload: actionParams.input as ChatHistoryActionPayload,
         });
       },
-    },
+    }),
   };
 }

package/src/contact/Action.ts

@@ -9,6 +9,8 @@
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import { createAction } from "@downcity/agent/internal/plugin/core/PluginActionFactory.js";
+import { z } from "zod";
 import type {
   ContactApproveCommandPayload,
   ContactChatCommandPayload,
@@ -94,7 +96,18 @@ export type ContactActionHandlers = {
  */
 export function createContactActions(handlers: ContactActionHandlers): PluginActions {
   return {
-    link: {
+    link: createAction({
+      description: "生成一次性 contact link code，供其他 agent approve。",
+      input_schema: {
+        zod: z.object({ ttlSeconds: z.number().optional() }),
+        json_schema: {
+          type: "object",
+          properties: {
+            ttlSeconds: { type: "number", description: "link 过期秒数，默认 600" },
+          },
+        },
+      },
+      examples: [{ title: "生成默认 link", payload: {} }],
       command: {
         description: "生成一次性 contact link code，交给另一个 agent approve",
         configure(command) {
@@ -110,11 +123,29 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: await handlers.link(
           params.context,
-          params.payload as ContactLinkCommandPayload,
+          params.input as ContactLinkCommandPayload,
         ),
       }),
-    },
-    approve: {
+    }),
+    approve: createAction({
+      description: "使用 contact link code 建立点对点联系。",
+      input_schema: {
+        zod: z.object({
+          code: z.string(),
+          name: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["code"],
+          properties: {
+            code: { type: "string", description: "link code" },
+            name: { type: "string", description: "本地 contact 别名" },
+          },
+        },
+      },
+      examples: [
+        { title: "approve link", payload: { code: "abc123", name: "alice" } },
+      ],
       command: {
         description: "使用 contact link code 建立点对点联系",
         configure(command) {
@@ -134,11 +165,17 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: await handlers.approve(
           params.context,
-          params.payload as unknown as ContactApproveCommandPayload,
+          params.input as unknown as ContactApproveCommandPayload,
         ),
       }),
-    },
-    list: {
+    }),
+    list: createAction({
+      description: "列出已建立的 contact。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {} },
+      },
+      examples: [{ title: "列出 contact", payload: {} }],
       command: {
         description: "列出已建立的 contact",
         mapInput() {
@@ -151,8 +188,26 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
           contacts: await listContacts(params.context.rootPath),
         } as unknown as JsonValue,
       }),
-    },
-    check: {
+    }),
+    check: createAction({
+      description: "检查 contact 或 endpoint 当前是否在线可用。",
+      input_schema: {
+        zod: z.object({
+          target: z.string().optional(),
+          endpoint: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          properties: {
+            target: { type: "string", description: "已保存的 contact 名" },
+            endpoint: { type: "string", description: "直接检查的 endpoint" },
+          },
+        },
+      },
+      examples: [
+        { title: "检查 contact", payload: { target: "alice" } },
+        { title: "检查 endpoint", payload: { endpoint: "https://example.com" } },
+      ],
       command: {
         description: "检查 contact 或 endpoint 当前是否在线可用",
         configure(command) {
@@ -172,11 +227,30 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: await handlers.check(
           params.context,
-          params.payload as ContactCheckCommandPayload,
+          params.input as ContactCheckCommandPayload,
         ),
       }),
-    },
-    chat: {
+    }),
+    chat: createAction({
+      description: "和某个 contact 的长期对话线聊天，或读取对话历史。",
+      input_schema: {
+        zod: z.object({
+          to: z.string(),
+          message: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["to"],
+          properties: {
+            to: { type: "string", description: "目标 contact" },
+            message: { type: "string", description: "要发送的消息" },
+          },
+        },
+      },
+      examples: [
+        { title: "发送消息", payload: { to: "alice", message: "hello" } },
+        { title: "读取历史", payload: { to: "alice" } },
+      ],
       command: {
         description: "和某个 contact 的长期对话线聊天",
         configure(command) {
@@ -195,11 +269,36 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: await handlers.chat(
           params.context,
-          params.payload as unknown as ContactChatCommandPayload,
+          params.input as unknown as ContactChatCommandPayload,
         ),
       }),
-    },
-    share: {
+    }),
+    share: createAction({
+      description: "向 contact 分享文本、链接、文件或目录。",
+      input_schema: {
+        zod: z.object({
+          to: z.string(),
+          text: z.string().optional(),
+          links: z.array(z.string()).optional(),
+          paths: z.array(z.string()).optional(),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["to"],
+          properties: {
+            to: { type: "string", description: "目标 contact" },
+            text: { type: "string", description: "分享文本" },
+            links: { type: "array", items: { type: "string" }, description: "分享链接" },
+            paths: { type: "array", items: { type: "string" }, description: "分享文件/目录路径" },
+          },
+        },
+      },
+      examples: [
+        {
+          title: "分享一段文本",
+          payload: { to: "alice", text: "看看这个" },
+        },
+      ],
       command: {
         description: "向 contact 分享文本、链接、文件或目录",
         configure(command) {
@@ -227,11 +326,17 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: await handlers.share(
           params.context,
-          params.payload as unknown as ContactShareCommandPayload,
+          params.input as unknown as ContactShareCommandPayload,
         ),
       }),
-    },
-    inbox: {
+    }),
+    inbox: createAction({
+      description: "查看 contact inbox。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {} },
+      },
+      examples: [{ title: "查看 inbox", payload: {} }],
       command: {
         description: "查看 contact inbox",
         mapInput() {
@@ -244,8 +349,20 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
           shares: await listContactInboxShares(params.context.rootPath),
         } as unknown as JsonValue,
       }),
-    },
-    receive: {
+    }),
+    receive: createAction({
+      description: "接收 inbox 中的 share。",
+      input_schema: {
+        zod: z.object({ shareId: z.string() }),
+        json_schema: {
+          type: "object",
+          required: ["shareId"],
+          properties: {
+            shareId: { type: "string", description: "inbox 中的 shareId" },
+          },
+        },
+      },
+      examples: [{ title: "接收 share", payload: { shareId: "share_1" } }],
       command: {
         description: "接收 inbox 中的 share",
         configure(command) {
@@ -261,40 +378,44 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         success: true,
         data: (await receiveShare({
           projectRoot: params.context.rootPath,
-          shareId: (params.payload as unknown as ContactReceiveCommandPayload).shareId,
+          shareId: (params.input as unknown as ContactReceiveCommandPayload).shareId,
         })) as unknown as JsonValue,
       }),
-    },
-    remoteping: {
+    }),
+    remoteping: createAction({
+      description: "处理远端 ping 请求（内部 endpoint）。",
       execute: async (params) => ({
         success: true,
         data: (await handlers.remotePing(
           params.context,
-          params.payload as unknown as { token?: string },
+          params.input as unknown as { token?: string },
         )) as unknown as JsonValue,
       }),
-    },
-    remoteapprove: {
+    }),
+    remoteapprove: createAction({
+      description: "处理远端 approve 请求（内部 endpoint）。",
       execute: async (params) => ({
         success: true,
         data: (await handlers.remoteApprove(
           params.context,
-          readContactObject(params.payload) as unknown as ContactApproveLinkRequest,
+          readContactObject(params.input) as unknown as ContactApproveLinkRequest,
         )) as unknown as JsonValue,
       }),
-    },
-    remoteconfirm: {
+    }),
+    remoteconfirm: createAction({
+      description: "处理远端 confirm 请求（内部 endpoint）。",
       execute: async (params) => ({
         success: true,
         data: (await handlers.remoteConfirm(
           params.context,
-          readContactObject(params.payload) as unknown as ContactConfirmRequest,
+          readContactObject(params.input) as unknown as ContactConfirmRequest,
         )) as unknown as JsonValue,
       }),
-    },
-    remotechat: {
+    }),
+    remotechat: createAction({
+      description: "处理远端 chat 请求（内部 endpoint）。",
       execute: async (params) => {
-        const payload = readContactObject(params.payload);
+        const payload = readContactObject(params.input);
         const body = readContactObject(payload.body);
         return {
           success: true,
@@ -305,12 +426,13 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
           })) as unknown as JsonValue,
         };
       },
-    },
-    remoteshare: {
+    }),
+    remoteshare: createAction({
+      description: "处理远端 share 请求（内部 endpoint）。",
       execute: async (params) => ({
         success: true,
-        data: (await handlers.remoteShare(params.context, params.payload)) as unknown as JsonValue,
+        data: (await handlers.remoteShare(params.context, params.input)) as unknown as JsonValue,
       }),
-    },
+    }),
   };
 }