@downcity/plugins 1.0.59 → 1.0.61

package/bin/task/TaskPlugin.js

@@ -12,6 +12,7 @@ import { registerTaskCronJobs } from "../task/Scheduler.js";
 import { createTaskPluginActions, } from "../task/runtime/TaskPluginActions.js";
 import { reloadTaskSchedulerAfterMutation, } from "../task/runtime/TaskActionExecution.js";
 import { TASK_PLUGIN_PROMPT } from "../task/runtime/TaskPluginSystem.js";
+import { resolveRuntimeTimezone } from "@downcity/agent/internal/utils/Time.js";
 const TASK_LOG_PREFIX = "[TASK]";
 function formatTaskLogMessage(message) {
     return `${TASK_LOG_PREFIX} ${message}`;
@@ -32,6 +33,10 @@ export class TaskPlugin extends BasePlugin {
      * task plugin 的 action 定义表。
      */
     actions;
+    /**
+     * 当前实例持有的显式配置。
+     */
+    options;
     /**
      * 当前实例持有的 cron engine。
      *
@@ -40,8 +45,17 @@ export class TaskPlugin extends BasePlugin {
      * - 不再复用 module-global 单例。
      */
     cronEngine = null;
-    constructor() {
+    /**
+     * 当前实例持有的运行中 task 锁。
+     *
+     * 关键点（中文）
+     * - scheduler reload 会替换 cron engine。
+     * - 锁必须挂在 plugin 实例上，避免 reload 后同一 task 被新旧调度器并发触发。
+     */
+    runningTaskIds = new Set();
+    constructor(options) {
         super();
+        this.options = options || {};
         this.actions = createTaskPluginActions({
             reloadSchedulerAfterMutation: async (params) => this.reloadSchedulerAfterMutation(params),
         });
@@ -84,6 +98,8 @@ export class TaskPlugin extends BasePlugin {
         const registerResult = await registerTaskCronJobs({
             context,
             engine,
+            timezone: this.resolveTimezone(),
+            runningTaskIds: this.runningTaskIds,
         });
         await engine.start();
         this.cronEngine = engine;
@@ -122,5 +138,11 @@ export class TaskPlugin extends BasePlugin {
             reloadScheduler: async (context) => this.restartCronRuntime(context),
         });
     }
+    /**
+     * 解析当前 task cron 使用的时区。
+     */
+    resolveTimezone() {
+        return String(this.options.timezone || "").trim() || resolveRuntimeTimezone();
+    }
 }
 //# sourceMappingURL=TaskPlugin.js.map

package/bin/task/TaskPlugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskPlugin.js","sourceRoot":"","sources":["../../src/task/TaskPlugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TaskPlugin.js","sourceRoot":"","sources":["../../src/task/TaskPlugin.ts"],"names":[],"mappings":"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"}

package/bin/task/types/TaskPluginOptions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * TaskPluginOptions：TaskPlugin 构造参数。
+ *
+ * 关键点（中文）
+ * - TaskPlugin 本身就是定时任务 runtime，不提供 enabled 开关。
+ * - 只暴露用户能直接理解的时区配置，内部调度实现细节不进入 constructor。
+ */
+/**
+ * TaskPlugin 构造参数。
+ */
+export interface TaskPluginOptions {
+    /**
+     * cron task 使用的 IANA 时区。
+     *
+     * 说明（中文）
+     * - 例如 `Asia/Shanghai`、`America/Los_Angeles`。
+     * - 省略时使用当前运行机器的本机时区。
+     * - `time:<ISO8601-with-timezone>` 一次性任务以 ISO 字符串自身的 offset 为准，这里的时区主要影响 cron 表达式。
+     */
+    timezone?: string;
+}
+//# sourceMappingURL=TaskPluginOptions.d.ts.map

package/bin/task/types/TaskPluginOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskPluginOptions.d.ts","sourceRoot":"","sources":["../../../src/task/types/TaskPluginOptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/bin/task/types/TaskPluginOptions.js

@@ -0,0 +1,9 @@
+/**
+ * TaskPluginOptions：TaskPlugin 构造参数。
+ *
+ * 关键点（中文）
+ * - TaskPlugin 本身就是定时任务 runtime，不提供 enabled 开关。
+ * - 只暴露用户能直接理解的时区配置，内部调度实现细节不进入 constructor。
+ */
+export {};
+//# sourceMappingURL=TaskPluginOptions.js.map

package/bin/task/types/TaskPluginOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskPluginOptions.js","sourceRoot":"","sources":["../../../src/task/types/TaskPluginOptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/plugins",
-  "version": "1.0.59",
+  "version": "1.0.61",
   "type": "module",
   "description": "Downcity 内建 plugin 集合包",
   "main": "./bin/index.js",
@@ -22,7 +22,7 @@
     "node-cron": "^4.2.1",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@downcity/agent": "^1.1.105"
+    "@downcity/agent": "^1.1.107"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/src/BuiltinPlugins.ts

@@ -16,6 +16,15 @@ import { ContactPlugin } from "@/contact/ContactPlugin.js";
 import { TaskPlugin } from "@/task/TaskPlugin.js";
 import { MemoryPlugin } from "@/memory/MemoryPlugin.js";
 import { ShellPlugin } from "@/shell/ShellPlugin.js";
+import { ImagePlugin } from "@/image/ImagePlugin.js";
+import { AsrPlugin } from "@/asr/Plugin.js";
+import { TtsPlugin } from "@/tts/Plugin.js";
+import type { ImagePluginOptions } from "@/image/types/ImagePlugin.js";
+import type { AsrPluginOptions } from "@/asr/types/AsrPlugin.js";
+import type { TtsPluginOptions } from "@/tts/types/TtsPlugin.js";
+import type { TaskPluginOptions } from "@/task/types/TaskPluginOptions.js";
+import type { MemoryPluginOptions } from "@/memory/types/Memory.js";
+import type { ShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
 
 /**
  * 内建 plugin class 构造器。
@@ -23,7 +32,9 @@ import { ShellPlugin } from "@/shell/ShellPlugin.js";
 export type BuiltinPluginClass<T extends BasePlugin = BasePlugin> = new () => T;
 
 /**
- * 全部内建 plugin classes。
+ * 可直接无参创建的内建 plugin classes。
+ *
+ * 关键点（中文）：image / asr / tts 需要宿主注入 City AI 能力，不能放入无参 class 列表。
  */
 export const BUILTIN_PLUGIN_CLASSES: BuiltinPluginClass[] = [
   SkillPlugin,
@@ -36,9 +47,62 @@ export const BUILTIN_PLUGIN_CLASSES: BuiltinPluginClass[] = [
   ShellPlugin,
 ];
 
+/**
+ * 内建 plugin 工厂参数。
+ */
+export interface BuiltinPluginOptions {
+  /**
+   * 图片生成 plugin 的 City AI 能力注入。
+   */
+  image?: ImagePluginOptions;
+
+  /**
+   * 语音转写 plugin 的 City AI 能力注入。
+   */
+  asr?: AsrPluginOptions;
+
+  /**
+   * 文本转语音 plugin 的 City AI 能力注入。
+   */
+  tts?: TtsPluginOptions;
+
+  /**
+   * task plugin 的定时任务运行参数。
+   */
+  task?: TaskPluginOptions;
+
+  /**
+   * memory plugin 的 LLM Wiki 能力注入。
+   */
+  memory?: MemoryPluginOptions;
+
+  /**
+   * shell plugin 的可选 runtime 参数。
+   */
+  shell?: ShellPluginOptions;
+}
+
 /**
  * 创建完整内建 plugin 实例集合。
  */
-export function createBuiltinPlugins(): BasePlugin[] {
-  return BUILTIN_PLUGIN_CLASSES.map((PluginClass) => new PluginClass());
+export function createBuiltinPlugins(options: BuiltinPluginOptions = {}): BasePlugin[] {
+  const plugins = BUILTIN_PLUGIN_CLASSES.map((PluginClass) =>
+    PluginClass === TaskPlugin
+      ? new TaskPlugin(options.task)
+      : PluginClass === MemoryPlugin
+        ? new MemoryPlugin(options.memory)
+        : PluginClass === ShellPlugin
+          ? new ShellPlugin(options.shell)
+      : new PluginClass(),
+  );
+  if (options.image?.image_create && options.image?.image_result) {
+    plugins.push(new ImagePlugin(options.image));
+  }
+  if (options.asr?.asr) {
+    plugins.push(new AsrPlugin(options.asr));
+  }
+  if (options.tts?.tts) {
+    plugins.push(new TtsPlugin(options.tts));
+  }
+  return plugins;
 }

package/src/contact/ContactPlugin.ts

@@ -30,6 +30,7 @@ import type { ContactPingResponse } from "@/contact/types/ContactCheck.js";
 import type { ContactChatResponse } from "@/contact/types/ContactChat.js";
 import type { AgentContact } from "@/contact/types/Contact.js";
 import type { SaveContactInboxShareInput } from "@/contact/types/ContactShare.js";
+import type { ContactPluginOptions } from "@/contact/types/ContactPluginOptions.js";
 import {
   appendContactMessage,
   createStableContactId,
@@ -145,8 +146,14 @@ export class ContactPlugin extends BasePlugin {
    */
   readonly actions: PluginActions;
 
-  constructor() {
+  /**
+   * 当前实例持有的显式配置。
+   */
+  public readonly options: ContactPluginOptions;
+
+  constructor(options?: ContactPluginOptions) {
     super();
+    this.options = options || {};
     this.actions = createContactActions({
       link: async (context, payload) =>
         (await this.link(context, payload)) as unknown as JsonValue,
@@ -164,11 +171,6 @@ export class ContactPlugin extends BasePlugin {
       remoteShare: async (context, payload) =>
         (await this.remoteShare(context, payload)) as unknown as JsonValue,
     });
-
-    this.lifecycle = {
-      start: () => undefined,
-      stop: () => undefined,
-    };
   }
 
   /**
@@ -180,10 +182,16 @@ export class ContactPlugin extends BasePlugin {
 
   private async link(context: AgentContext, payload: ContactLinkCommandPayload) {
     const now = Date.now();
-    const ttlSeconds = Math.max(60, Number(payload.ttlSeconds || 600));
+    const ttlSeconds = Math.max(
+      60,
+      Number(payload.ttlSeconds || this.options.ttlSeconds || 600),
+    );
     const linkId = createContactId("link");
     const secret = createContactToken();
-    const endpoint = await resolveSelfEndpoint(context, payload.endpoint);
+    const endpoint = await resolveSelfEndpoint(
+      context,
+      payload.endpoint || this.options.endpoint,
+    );
     const agentName = getAgentName(context);
 
     await saveContactLinkRecord(context.rootPath, {
@@ -228,7 +236,7 @@ export class ContactPlugin extends BasePlugin {
       targetReachability === "loopback" ||
       targetReachability === "private";
     const requesterEndpointCandidate = shouldResolveRequesterEndpoint
-      ? await resolveSelfEndpoint(context, payload.endpoint)
+      ? await resolveSelfEndpoint(context, payload.endpoint || this.options.endpoint)
       : undefined;
     const callbackDecision = buildContactApproveCallbackDecision({
       targetEndpoint: parsed.endpoint,

package/src/contact/types/ContactPluginOptions.ts

@@ -0,0 +1,30 @@
+/**
+ * ContactPluginOptions：ContactPlugin 构造参数。
+ *
+ * 关键点（中文）
+ * - 这里只保留 agent 运行时真正需要的显式配置。
+ * - contact token、link secret 等协议密钥都由运行时自动生成，不从 constructor 传入。
+ */
+
+/**
+ * ContactPlugin 构造参数。
+ */
+export interface ContactPluginOptions {
+  /**
+   * 当前 agent 对外可访问的 HTTP endpoint。
+   *
+   * 说明（中文）
+   * - 传入后会优先写入 `contact link` 生成的一次性联系码。
+   * - 适合反向代理、tunnel、公网域名等自动探测不可靠的环境。
+   */
+  endpoint?: string;
+
+  /**
+   * 默认 link 有效秒数。
+   *
+   * 说明（中文）
+   * - `contact link` action 没有显式传 `ttlSeconds` 时使用该值。
+   * - 最终运行时仍会强制不少于 60 秒，避免生成过短的人工转交 code。
+   */
+  ttlSeconds?: number;
+}

package/src/index.ts

@@ -11,8 +11,12 @@ export {
   BUILTIN_PLUGIN_CLASSES,
   createBuiltinPlugins,
 } from "./BuiltinPlugins.js";
-export type { BuiltinPluginClass } from "./BuiltinPlugins.js";
+export type {
+  BuiltinPluginClass,
+  BuiltinPluginOptions,
+} from "./BuiltinPlugins.js";
 export { ChatPlugin } from "./chat/ChatPlugin.js";
+export { ContactPlugin } from "./contact/ContactPlugin.js";
 export {
   FeishuChannel,
   QqChannel,
@@ -25,6 +29,9 @@ export { WebPlugin } from "./web/Plugin.js";
 export { AsrPlugin } from "./asr/Plugin.js";
 export { TtsPlugin } from "./tts/Plugin.js";
 export { WorkboardPlugin } from "./workboard/Plugin.js";
+export { TaskPlugin } from "./task/TaskPlugin.js";
+export { MemoryPlugin } from "./memory/MemoryPlugin.js";
+export { ShellPlugin } from "./shell/ShellPlugin.js";
 export {
   listChatAuthorizationRoles,
   readChatAuthorizationConfigSync,
@@ -54,6 +61,39 @@ export type {
   ChatChannelRuntimePatch,
   ChatPluginOptions,
 } from "./chat/types/ChatPluginOptions.js";
+export type { ContactPluginOptions } from "./contact/types/ContactPluginOptions.js";
+export type { TaskPluginOptions } from "./task/types/TaskPluginOptions.js";
+export type {
+  ResolvedShellPluginOptions,
+  ShellPluginOptions,
+} from "./shell/types/ShellPluginOptions.js";
+export type {
+  MemoryActionPayload,
+  MemoryDefaults,
+  MemoryDigestHandler,
+  MemoryDigestHandlerInput,
+  MemoryDigestHandlerOutput,
+  MemoryDigestPayload,
+  MemoryDigestResponse,
+  MemoryPluginOptions,
+  MemoryReadPayload,
+  MemoryReadResponse,
+  MemoryRememberPayload,
+  MemoryRememberResponse,
+  MemoryReviseHandler,
+  MemoryReviseHandlerInput,
+  MemoryReviseHandlerOutput,
+  MemoryRevisePayload,
+  MemoryReviseResponse,
+  MemorySearchMode,
+  MemorySearchPayload,
+  MemorySearchResponse,
+  MemorySearchResultItem,
+  MemorySourceStat,
+  MemorySourceType,
+  MemoryStatusResponse,
+  MemoryWikiPageDraft,
+} from "./memory/types/Memory.js";
 export type {
   AsrPluginInput,
   AsrPluginOptions,