@downcity/plugins 1.0.96 → 1.0.103

package/src/task/runtime/TaskPluginActionRegistry.ts

@@ -8,6 +8,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 { TaskListActionPayload } from "@/task/types/TaskPluginTypes.js";
 import type {
   TaskCreateRequest,
@@ -36,6 +38,53 @@ import {
   mapTaskUpdateCommandPayload,
 } from "./TaskActionInput.js";
 
+const TASK_STATUS_SCHEMA = z.enum(["enabled", "paused", "disabled"]);
+const TASK_KIND_SCHEMA = z.enum(["agent", "script"]);
+
+const TASK_LIST_SCHEMA = z.object({
+  status: TASK_STATUS_SCHEMA.optional(),
+});
+
+const TASK_CREATE_SCHEMA = z.object({
+  title: z.string(),
+  when: z.string(),
+  description: z.string(),
+  sessionId: z.string(),
+  kind: TASK_KIND_SCHEMA.optional(),
+  review: z.boolean().optional(),
+  status: TASK_STATUS_SCHEMA.optional(),
+  body: z.string().optional(),
+  overwrite: z.boolean().optional(),
+});
+
+const TASK_UPDATE_SCHEMA = z.object({
+  title: z.string(),
+  titleNext: z.string().optional(),
+  when: z.string().optional(),
+  clearWhen: z.boolean().optional(),
+  description: z.string().optional(),
+  sessionId: z.string().optional(),
+  kind: TASK_KIND_SCHEMA.optional(),
+  review: z.boolean().optional(),
+  status: TASK_STATUS_SCHEMA.optional(),
+  body: z.string().optional(),
+  clearBody: z.boolean().optional(),
+});
+
+const TASK_RUN_SCHEMA = z.object({
+  title: z.string(),
+  reason: z.string().optional(),
+});
+
+const TASK_DELETE_SCHEMA = z.object({
+  title: z.string(),
+});
+
+const TASK_STATUS_REQ_SCHEMA = z.object({
+  title: z.string(),
+  status: TASK_STATUS_SCHEMA,
+});
+
 /**
  * 创建 task plugin runtime 的 action 定义表。
  */
@@ -43,7 +92,25 @@ export function createTaskPluginActions(params: {
   reloadSchedulerAfterMutation: TaskSchedulerReloadPort;
 }): PluginActions {
   return {
-    list: {
+    list: createAction({
+      description: "列出任务定义；可按状态过滤。",
+      input_schema: {
+        zod: TASK_LIST_SCHEMA,
+        json_schema: {
+          type: "object",
+          properties: {
+            status: {
+              type: "string",
+              enum: ["enabled", "paused", "disabled"],
+              description: "按任务状态过滤",
+            },
+          },
+        },
+      },
+      examples: [
+        { title: "全部任务", payload: {} },
+        { title: "只看已启用", payload: { status: "enabled" } },
+      ],
       command: {
         description: "列出任务",
         configure(command: Command) {
@@ -57,11 +124,42 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskListAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskListActionPayload,
+          payload: actionParams.input as TaskListActionPayload,
         });
       },
-    },
-    create: {
+    }),
+    create: createAction({
+      description: "创建任务定义。",
+      input_schema: {
+        zod: TASK_CREATE_SCHEMA,
+        json_schema: {
+          type: "object",
+          required: ["title", "when", "description", "sessionId"],
+          properties: {
+            title: { type: "string", description: "任务名称（唯一语义标识）" },
+            when: { type: "string", description: "触发条件（@manual | cron | time:ISO8601）" },
+            description: { type: "string", description: "任务描述" },
+            sessionId: { type: "string", description: "任务执行 sessionId" },
+            kind: { type: "string", enum: ["agent", "script"], description: "执行类型" },
+            review: { type: "boolean", description: "是否启用 review 多轮复核" },
+            status: { type: "string", enum: ["enabled", "paused", "disabled"], description: "任务状态" },
+            body: { type: "string", description: "任务正文" },
+            overwrite: { type: "boolean", description: "是否覆盖已有 task.md" },
+          },
+        },
+      },
+      examples: [
+        {
+          title: "创建一个手动任务",
+          payload: {
+            title: "daily-report",
+            when: "@manual",
+            description: "每天生成报告",
+            sessionId: "session-1",
+            status: "enabled",
+          },
+        },
+      ],
       command: {
         description: "创建任务定义",
         configure(command: Command) {
@@ -92,12 +190,25 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskCreateAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskCreateRequest,
+          payload: actionParams.input as TaskCreateRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
-    run: {
+    }),
+    run: createAction({
+      description: "手动运行任务。",
+      input_schema: {
+        zod: TASK_RUN_SCHEMA,
+        json_schema: {
+          type: "object",
+          required: ["title"],
+          properties: {
+            title: { type: "string", description: "任务名称" },
+            reason: { type: "string", description: "手动运行原因" },
+          },
+        },
+      },
+      examples: [{ title: "手动运行", payload: { title: "daily-report" } }],
       command: {
         description: "手动运行任务",
         configure(command: Command) {
@@ -110,11 +221,23 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskRunAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskRunRequest,
+          payload: actionParams.input as TaskRunRequest,
         });
       },
-    },
-    delete: {
+    }),
+    delete: createAction({
+      description: "删除任务定义与历史运行目录。",
+      input_schema: {
+        zod: TASK_DELETE_SCHEMA,
+        json_schema: {
+          type: "object",
+          required: ["title"],
+          properties: {
+            title: { type: "string", description: "任务名称" },
+          },
+        },
+      },
+      examples: [{ title: "删除任务", payload: { title: "daily-report" } }],
       command: {
         description: "删除任务定义与历史运行目录",
         configure(command: Command) {
@@ -125,12 +248,39 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskDeleteAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskDeleteRequest,
+          payload: actionParams.input as TaskDeleteRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
-    update: {
+    }),
+    update: createAction({
+      description: "更新任务定义。",
+      input_schema: {
+        zod: TASK_UPDATE_SCHEMA,
+        json_schema: {
+          type: "object",
+          required: ["title"],
+          properties: {
+            title: { type: "string", description: "当前任务名称" },
+            titleNext: { type: "string", description: "新任务名称" },
+            when: { type: "string", description: "新触发条件" },
+            clearWhen: { type: "boolean", description: "是否清空触发条件" },
+            description: { type: "string", description: "新描述" },
+            sessionId: { type: "string", description: "新 sessionId" },
+            kind: { type: "string", enum: ["agent", "script"] },
+            review: { type: "boolean" },
+            status: { type: "string", enum: ["enabled", "paused", "disabled"] },
+            body: { type: "string", description: "新正文" },
+            clearBody: { type: "boolean", description: "是否清空正文" },
+          },
+        },
+      },
+      examples: [
+        {
+          title: "更新触发器",
+          payload: { title: "daily-report", when: "cron:0 9 * * *" },
+        },
+      ],
       command: {
         description: "更新任务定义",
         configure(command: Command) {
@@ -157,12 +307,27 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskUpdateAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskUpdateRequest,
+          payload: actionParams.input as TaskUpdateRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
-    status: {
+    }),
+    status: createAction({
+      description: "设置任务状态（enabled|paused|disabled）。",
+      input_schema: {
+        zod: TASK_STATUS_REQ_SCHEMA,
+        json_schema: {
+          type: "object",
+          required: ["title", "status"],
+          properties: {
+            title: { type: "string", description: "任务名称" },
+            status: { type: "string", enum: ["enabled", "paused", "disabled"] },
+          },
+        },
+      },
+      examples: [
+        { title: "暂停任务", payload: { title: "daily-report", status: "paused" } },
+      ],
       command: {
         description: "设置任务状态（enabled|paused|disabled）",
         configure(command: Command) {
@@ -173,12 +338,22 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskStatusAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskSetStatusRequest,
+          payload: actionParams.input as TaskSetStatusRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
-    enable: {
+    }),
+    enable: createAction({
+      description: "启用任务（status=enabled）。",
+      input_schema: {
+        zod: z.object({ title: z.string() }),
+        json_schema: {
+          type: "object",
+          required: ["title"],
+          properties: { title: { type: "string", description: "任务名称" } },
+        },
+      },
+      examples: [{ title: "启用", payload: { title: "daily-report" } }],
       command: {
         description: "启用任务（status=enabled）",
         configure(command: Command) {
@@ -189,12 +364,22 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskStatusAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskSetStatusRequest,
+          payload: actionParams.input as TaskSetStatusRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
-    disable: {
+    }),
+    disable: createAction({
+      description: "禁用任务（status=disabled）。",
+      input_schema: {
+        zod: z.object({ title: z.string() }),
+        json_schema: {
+          type: "object",
+          required: ["title"],
+          properties: { title: { type: "string", description: "任务名称" } },
+        },
+      },
+      examples: [{ title: "禁用", payload: { title: "daily-report" } }],
       command: {
         description: "禁用任务（status=disabled）",
         configure(command: Command) {
@@ -205,10 +390,10 @@ export function createTaskPluginActions(params: {
       execute: async (actionParams) => {
         return executeTaskStatusAction({
           context: actionParams.context,
-          payload: actionParams.payload as TaskSetStatusRequest,
+          payload: actionParams.input as TaskSetStatusRequest,
           reloadSchedulerAfterMutation: params.reloadSchedulerAfterMutation,
         });
       },
-    },
+    }),
   };
 }

package/src/tts/Plugin.ts

@@ -8,6 +8,8 @@
  */
 
 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 { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type {
   JsonObject,
@@ -227,11 +229,43 @@ export class TtsPlugin extends BasePlugin {
    * 显式 action 集合。
    */
   readonly actions = {
-    synthesize: {
-      execute: async ({ payload }: { payload: JsonValue }) => {
+    synthesize: createAction({
+      description:
+        "Synthesize speech from text. Returns a UIMessage whose audio file part is auto-saved under the project resources directory.",
+      input_schema: {
+        zod: z
+          .object({
+            text: z.string(),
+            language: z.string().optional(),
+            voice: z.string().optional(),
+            format: z.string().optional(),
+            speed: z.number().optional(),
+            provider_options: z.record(z.string(), z.unknown()).optional(),
+          })
+          .passthrough(),
+        json_schema: {
+          type: "object",
+          required: ["text"],
+          properties: {
+            text: { type: "string", description: "需要合成的文本" },
+            language: { type: "string", description: "语言代码（可选）" },
+            voice: { type: "string", description: "音色（可选）" },
+            format: { type: "string", description: "音频格式（可选）" },
+            speed: { type: "number", description: "语速（可选）" },
+          },
+        },
+      },
+      examples: [
+        { title: "默认音色", payload: { text: "你好，世界" } },
+        {
+          title: "指定音色",
+          payload: { text: "Welcome back", voice: "alloy", format: "mp3" },
+        },
+      ],
+      execute: async ({ input }: { input: JsonValue }) => {
         try {
-          const input = normalize_tts_payload(payload);
-          const message = await this.synthesize(input);
+          const synth_input = normalize_tts_payload(input);
+          const message = await this.synthesize(synth_input);
           return {
             success: true,
             data: message as unknown as JsonObject,
@@ -245,6 +279,6 @@ export class TtsPlugin extends BasePlugin {
           };
         }
       },
-    },
+    }),
   };
 }

package/src/web/Plugin.ts

@@ -9,6 +9,8 @@
  */
 
 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 { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type {
   JsonObject,
@@ -136,7 +138,39 @@ export class WebPlugin extends BasePlugin {
    * WebPlugin 对外 action。
    */
   readonly actions = {
-    install: {
+    install: createAction({
+      description: "安装联网相关 skill / CLI 依赖（web-access、agent-browser）。",
+      input_schema: {
+        zod: z.object({
+          target: z.enum(["web-access", "agent-browser", "all"]).optional(),
+          scope: z.enum(["user", "project"]).optional(),
+          yes: z.boolean().optional(),
+          agent: z.string().optional(),
+        }),
+        json_schema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              enum: ["web-access", "agent-browser", "all"],
+              description: "要安装的联网能力",
+            },
+            scope: {
+              type: "string",
+              enum: ["user", "project"],
+              description: "安装作用域",
+            },
+            yes: { type: "boolean", description: "跳过确认" },
+            agent: { type: "string", description: "skill installer 目标 agent" },
+          },
+        },
+      },
+      examples: [
+        {
+          title: "用户级安装全部联网能力",
+          payload: { target: "all", scope: "user" },
+        },
+      ],
       allowWhenDisabled: true,
       command: {
         description: "安装联网相关 skill / CLI 依赖",
@@ -162,12 +196,12 @@ export class WebPlugin extends BasePlugin {
           } satisfies JsonObject;
         },
       },
-      execute: async ({ context, payload }) => {
+      execute: async ({ context, input }) => {
         const data = await installWebPluginTargets({
           context,
           payload:
-            payload && typeof payload === "object" && !Array.isArray(payload)
-              ? (payload as WebPluginInstallPayload)
+            input && typeof input === "object" && !Array.isArray(input)
+              ? (input as WebPluginInstallPayload)
               : undefined,
         });
         return {
@@ -176,7 +210,7 @@ export class WebPlugin extends BasePlugin {
           message: "web dependencies installed",
         };
       },
-    },
+    }),
   };
 
   /**

package/src/workboard/Plugin.ts

@@ -8,6 +8,8 @@
  */
 
 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 {
   PluginActions,
   PluginHttpDefinition,
@@ -56,7 +58,13 @@ export class WorkboardPlugin extends BasePlugin {
    * Workboard 对外 action。
    */
   readonly actions: PluginActions = {
-    snapshot: {
+    snapshot: createAction({
+      description: "读取 workboard 当前的结构化运行态快照。",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {} },
+      },
+      examples: [{ title: "读取快照", payload: {} }],
       execute: async ({ context }) => {
         const response = await readWorkboardSnapshot(context);
         return {
@@ -66,7 +74,7 @@ export class WorkboardPlugin extends BasePlugin {
           } as unknown as JsonValue,
         };
       },
-    },
+    }),
   };
 
   /**