@downcity/agent 1.1.25 → 1.1.35

package/src/plugin/core/BasePlugin.ts

@@ -0,0 +1,134 @@
+/**
+ * BasePlugin：统一 plugin 类基座。
+ *
+ * 关键点（中文）
+ * - 主动运行型能力与被动扩展型能力统一收敛到 plugin 概念。
+ * - plugin 的长期状态归属于实例本身，而不是模块级单例。
+ * - 旧生命周期模型暂时通过 `lifecycle` 兼容，后续可逐步收敛到 `start/stop/command`。
+ */
+
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type {
+  Plugin,
+  PluginActions,
+  PluginAvailability,
+  PluginCommandContext,
+  PluginConfigDefinition,
+  PluginHooks,
+  PluginHttpDefinition,
+  PluginLifecycle,
+  PluginResolves,
+  PluginSetupDefinition,
+  PluginStateRecord,
+  PluginUsageDefinition,
+} from "@/plugin/types/Plugin.js";
+import type { StructuredConfig } from "@/core/AgentContextTypes.js";
+
+/**
+ * BasePlugin 抽象基类。
+ */
+export abstract class BasePlugin implements Plugin {
+  /**
+   * 当前实例持有的通用 plugin 运行状态记录。
+   */
+  public readonly pluginStateRecord: PluginStateRecord = {
+    state: "stopped",
+    updatedAt: Date.now(),
+    chain: Promise.resolve(),
+  };
+
+  /**
+   * 当前 plugin 所属的 agent 宿主。
+   */
+  protected agent: AgentRuntime | null;
+
+  constructor(agent: AgentRuntime | null = null) {
+    this.agent = agent;
+  }
+
+  /**
+   * 当前 plugin 名称。
+   */
+  abstract readonly name: string;
+
+  /**
+   * 插件标题。
+   */
+  readonly title = "";
+
+  /**
+   * 插件说明。
+   */
+  readonly description = "";
+
+  /**
+   * 插件配置定义。
+   */
+  readonly config?: PluginConfigDefinition<StructuredConfig>;
+
+  /**
+   * 插件 setup 协议。
+   */
+  readonly setup?: PluginSetupDefinition;
+
+  /**
+   * 插件 usage 协议。
+   */
+  readonly usage?: PluginUsageDefinition;
+
+  /**
+   * 显式 action 集合。
+   */
+  readonly actions: PluginActions = {};
+
+  /**
+   * pipeline / guard / effect 扩展点。
+   */
+  readonly hooks?: PluginHooks;
+
+  /**
+   * resolve 扩展点。
+   */
+  readonly resolves?: PluginResolves;
+
+  /**
+   * HTTP 路由扩展。
+   */
+  readonly http?: PluginHttpDefinition;
+
+  /**
+   * 生命周期兼容层。
+   */
+  lifecycle?: PluginLifecycle;
+
+  /**
+   * Plugin 可用性检查。
+   */
+  availability?(
+    context: PluginCommandContext | AgentContext,
+  ): Promise<PluginAvailability> | PluginAvailability;
+
+  /**
+   * Plugin system 文本提供器。
+   */
+  system?(context: AgentContext): Promise<string> | string;
+
+  /**
+   * 绑定当前 plugin 所属的 agent 宿主。
+   */
+  bindAgent(agent: AgentRuntime | null): this {
+    this.agent = agent;
+    return this;
+  }
+
+  /**
+   * 读取绑定的 agent 宿主。
+   */
+  protected requireAgent(): AgentRuntime {
+    if (this.agent) return this.agent;
+    throw new Error(
+      `Plugin "${this.name}" is not bound to an agent instance.`,
+    );
+  }
+}

package/src/plugin/core/BuiltinPluginClasses.ts

@@ -0,0 +1,48 @@
+/**
+ * 内建 plugin class 清单。
+ *
+ * 关键点（中文）
+ * - 所有内建 plugin 统一收敛到一套 `BasePlugin` class 注册表。
+ * - 不再保留“plugin runtime / static plugin”两套定义源。
+ * - 运行方式差异只通过 plugin 自身能力体现，例如是否声明 `lifecycle`。
+ */
+
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import { AuthPlugin } from "@/plugin/builtins/auth/Plugin.js";
+import { SkillPlugin } from "@/plugin/builtins/skill/Plugin.js";
+import { WebPlugin } from "@/plugin/builtins/web/Plugin.js";
+import { AsrPlugin } from "@/plugin/builtins/asr/Plugin.js";
+import { TtsPlugin } from "@/plugin/builtins/tts/Plugin.js";
+import { WorkboardPlugin } from "@/plugin/builtins/workboard/Plugin.js";
+import { ChatPlugin } from "@/plugin/builtins/chat/ChatPlugin.js";
+import { ContactPlugin } from "@/plugin/builtins/contact/ContactPlugin.js";
+import { SchedulePlugin } from "@/plugin/builtins/schedule/SchedulePlugin.js";
+import { TaskPlugin } from "@/plugin/builtins/task/TaskPlugin.js";
+import { MemoryPlugin } from "@/plugin/builtins/memory/MemoryPlugin.js";
+import { ShellPlugin } from "@/plugin/builtins/shell/ShellPlugin.js";
+
+/**
+ * 单个内建 plugin class 构造器。
+ */
+export type BuiltinPluginClass<T extends BasePlugin = BasePlugin> = new (
+  agent: AgentRuntime | null,
+) => T;
+
+/**
+ * 全部内建 plugin classes。
+ */
+export const BUILTIN_PLUGIN_CLASSES: BuiltinPluginClass[] = [
+  AuthPlugin,
+  SkillPlugin,
+  WebPlugin,
+  AsrPlugin,
+  TtsPlugin,
+  WorkboardPlugin,
+  ChatPlugin,
+  ContactPlugin,
+  SchedulePlugin,
+  TaskPlugin,
+  MemoryPlugin,
+  ShellPlugin,
+];

package/src/plugin/core/Catalog.ts

@@ -3,11 +3,12 @@
  *
  * 关键点（中文）
  * - 这里承载 console 侧的静态 plugin 元数据视图。
- * - 目标是把“控制面可见的 plugin 定义”从 agent 执行态里拆出来复用。
+ * - 全部视图统一来源于 `BasePlugin` class 注册表，不再维护独立静态定义。
  * - 当前先服务 Console 与 `city plugin` CLI 的静态回退场景。
  */
 
-import { PLUGINS } from "@/plugin/core/Plugins.js";
+import { listRegisteredPlugins } from "@/plugin/core/PluginClassRegistry.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import type {
   Plugin,
@@ -44,8 +45,8 @@ export function toStaticPluginView(plugin: Plugin): PluginView {
 /**
  * 列出全部内建 plugin 定义。
  */
-export function listBuiltinPlugins(): Plugin[] {
-  return [...PLUGINS];
+export function listBuiltinPlugins(): BasePlugin[] {
+  return listRegisteredPlugins();
 }
 
 /**
@@ -60,7 +61,7 @@ export function listStaticPluginViews(): PluginView[] {
 /**
  * 按名称查找内建 plugin 定义。
  */
-export function findBuiltinPlugin(pluginName: string): Plugin | null {
+export function findBuiltinPlugin(pluginName: string): BasePlugin | null {
   const key = String(pluginName || "").trim();
   if (!key) return null;
   return listBuiltinPlugins().find((plugin) => plugin.name === key) || null;

package/src/plugin/core/HttpRoutes.ts

@@ -2,12 +2,12 @@
  * Plugin HTTP 路由装配。
  *
  * 关键点（中文）
- * - 这里统一装配内建 plugin 的 runtime HTTP 路由与鉴权策略。
+ * - 这里统一装配内建 plugin 的 HTTP 路由与鉴权策略。
  * - plugin 自己声明路由；server 与 console 只负责消费这份声明。
  */
 
 import type { Hono } from "hono";
-import { PLUGINS } from "@/plugin/core/Plugins.js";
+import { listRegisteredPlugins } from "@/plugin/core/PluginClassRegistry.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
 
@@ -27,9 +27,9 @@ function dedupeAuthPolicies(policies: AuthRoutePolicy[]): AuthRoutePolicy[] {
 /**
  * 列出全部内建 plugin runtime 鉴权策略。
  */
-export function listBuiltinPluginRuntimeAuthPolicies(): AuthRoutePolicy[] {
+export function listBuiltinPluginAuthPolicies(): AuthRoutePolicy[] {
   return dedupeAuthPolicies(
-    PLUGINS.flatMap((plugin) => plugin.http?.runtime?.authPolicies || []),
+    listRegisteredPlugins().flatMap((plugin) => plugin.http?.server?.authPolicies || []),
   );
 }
 
@@ -40,8 +40,8 @@ export function registerBuiltinPluginHttpRoutes(params: {
   app: Hono;
   getContext: () => AgentContext;
 }): void {
-  for (const plugin of PLUGINS) {
-    plugin.http?.runtime?.register({
+  for (const plugin of listRegisteredPlugins()) {
+    plugin.http?.server?.register({
       app: params.app,
       getContext: params.getContext,
       pluginName: plugin.name,

package/src/plugin/core/LocalExecution.ts

@@ -12,6 +12,7 @@ import { logger as defaultLogger } from "@/utils/logger/Logger.js";
 import { loadAgentEnvSnapshot, loadDowncityConfig, loadGlobalEnvFromStore } from "@/config/Config.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { findBuiltinPlugin, listStaticPluginViews } from "@/plugin/core/Catalog.js";
+import { isManagedPlugin } from "@/plugin/core/PluginClassRegistry.js";
 import {
   createAgentPathRuntime,
   createAgentPluginConfigRuntime,
@@ -24,6 +25,7 @@ import type {
   PluginCommandContext,
   PluginView,
 } from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 
 function createLocalFallbackPlatformRuntime(): AgentPlatformRuntime {
   return {
@@ -67,7 +69,10 @@ export function createLocalPluginCommandContext(projectRoot: string): PluginComm
     config,
     env,
     globalEnv,
-    paths: createAgentPathRuntime(rootPath),
+    paths: createAgentPathRuntime(
+      rootPath,
+      String(config.name || "").trim() || path.basename(rootPath) || "agent",
+    ),
     pluginConfig: createAgentPluginConfigRuntime(rootPath),
     platform,
   };
@@ -95,6 +100,13 @@ export async function getLocalPluginAvailability(
       reasons: [`Unknown plugin: ${pluginName}`],
     };
   }
+  if (isManagedPlugin(plugin)) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Plugin "${plugin.name}" must run through an active agent.`],
+    };
+  }
 
   const context = createLocalPluginCommandContext(projectRoot);
   if (plugin.availability) {
@@ -134,6 +146,13 @@ export async function runLocalPluginAction(params: {
       message: `Unknown plugin: ${params.pluginName}`,
     };
   }
+  if (isManagedPlugin(plugin)) {
+    return {
+      success: false,
+      error: `Plugin "${plugin.name}" must run through an active agent`,
+      message: `Plugin "${plugin.name}" must run through an active agent`,
+    };
+  }
 
   const actionName = String(params.actionName || "").trim();
   if (!actionName) {
@@ -165,7 +184,7 @@ export async function runLocalPluginAction(params: {
 
   try {
     return await action.execute({
-      context,
+      context: context as unknown as AgentContext,
       payload: (params.payload ?? {}) as JsonValue,
       pluginName: plugin.name,
       actionName,

package/src/plugin/core/Manager.ts

@@ -0,0 +1,21 @@
+/**
+ * Plugin Manager 门面模块。
+ */
+
+export type {
+  PluginStateControlAction,
+  PluginStateControlResult,
+  PluginStateSnapshot,
+} from "@/plugin/types/Plugin.js";
+export {
+  controlPluginState,
+  getPluginRootCommandNames,
+  getStaticPlugins,
+  isPluginRunning,
+  listPluginStates,
+  startAllPlugins,
+  stopAllPlugins,
+} from "@/plugin/core/PluginStateController.js";
+export {
+  runPluginCommand,
+} from "@/plugin/core/PluginActionRunner.js";

package/src/plugin/core/PluginActionRunner.ts

@@ -0,0 +1,267 @@
+/**
+ * PluginActionRunner：主动型 plugin action/command 执行模块。
+ */
+
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import type {
+  PluginAction,
+  PluginActionResult,
+  PluginCommandResult,
+  PluginStateControlAction,
+  PluginStateSnapshot,
+} from "@/plugin/types/Plugin.js";
+import type { PluginCommandScheduleInput } from "@/plugin/types/PluginSchedule.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import { PluginScheduleStore } from "@/plugin/core/schedule/Store.js";
+import { normalizeRunAtMsOrThrow } from "@/plugin/core/schedule/Time.js";
+import {
+  controlPluginState,
+  ensurePluginStateRecord,
+  markPluginCommand,
+  markPluginState,
+  resolvePluginByName,
+  toPluginStateSnapshot,
+} from "@/plugin/core/PluginStateController.js";
+
+function resolveLifecycle(plugin: BasePlugin) {
+  return plugin.lifecycle;
+}
+
+/**
+ * 按名称解析主动型 plugin action。
+ */
+export function resolvePluginAction(
+  plugin: BasePlugin,
+  actionName: string,
+): PluginAction<JsonValue, JsonValue> | null {
+  const key = String(actionName || "").trim();
+  if (!key) return null;
+  return plugin.actions[key] || null;
+}
+
+/**
+ * 执行一个主动型 plugin action。
+ */
+export async function invokePluginAction(params: {
+  plugin: BasePlugin;
+  actionName: string;
+  payload?: JsonValue;
+  context: AgentContext;
+}): Promise<PluginActionResult<JsonValue>> {
+  const action = resolvePluginAction(params.plugin, params.actionName);
+  if (!action) {
+    return {
+      success: false,
+      error: `Plugin "${params.plugin.name}" does not implement action "${params.actionName}"`,
+    };
+  }
+
+  try {
+    return await action.execute({
+      context: params.context,
+      payload: (params.payload ?? {}) as JsonValue,
+      pluginName: params.plugin.name,
+      actionName: params.actionName,
+    });
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+function toControlCommandAction(
+  command: string,
+): PluginStateControlAction | null {
+  if (
+    command === "status" ||
+    command === "start" ||
+    command === "stop" ||
+    command === "restart"
+  ) {
+    return command;
+  }
+  return null;
+}
+
+async function schedulePluginAction(params: {
+  plugin: BasePlugin;
+  command: string;
+  payload?: JsonValue;
+  schedule: JsonValue | PluginCommandScheduleInput;
+  recordSnapshot: PluginStateSnapshot;
+  context: AgentContext;
+}): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
+  try {
+    const scheduleInput = params.schedule as Partial<PluginCommandScheduleInput>;
+    const runAtMs = normalizeRunAtMsOrThrow(
+      scheduleInput.runAtMs,
+      "schedule.runAtMs",
+    );
+    const store = new PluginScheduleStore(params.context.rootPath);
+    try {
+      const job = store.createJob({
+        pluginName: params.plugin.name,
+        actionName: params.command,
+        payload: params.payload ?? null,
+        runAtMs,
+      });
+      return {
+        success: true,
+        plugin: params.recordSnapshot,
+        data: {
+          scheduled: true,
+          jobId: job.id,
+          runAtMs: job.runAtMs,
+          status: job.status,
+        },
+      };
+    } finally {
+      store.close();
+    }
+  } catch (error) {
+    return {
+      success: false,
+      plugin: params.recordSnapshot,
+      message: String(error),
+    };
+  }
+}
+
+/**
+ * 统一执行主动型 plugin command。
+ */
+export async function runPluginCommand(params: {
+  pluginName: string;
+  command: string;
+  payload?: JsonValue;
+  schedule?: JsonValue | PluginCommandScheduleInput;
+  context: AgentContext;
+}): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
+  const plugin = resolvePluginByName(params.pluginName, {
+    context: params.context,
+  });
+  if (!plugin) {
+    return {
+      success: false,
+      message: `Unknown plugin: ${params.pluginName}`,
+    };
+  }
+
+  const record = ensurePluginStateRecord(plugin);
+  const command = String(params.command || "")
+    .trim()
+    .toLowerCase();
+  if (!command) {
+    return {
+      success: false,
+      plugin: toPluginStateSnapshot(record, plugin),
+      message: "command is required",
+    };
+  }
+
+  markPluginCommand(record, command);
+
+  const action = resolvePluginAction(plugin, command);
+  if (params.schedule !== undefined && params.schedule !== null) {
+    if (!action) {
+      return {
+        success: false,
+        plugin: toPluginStateSnapshot(record, plugin),
+        message: `Scheduling only supports plugin actions. "${plugin.name}.${command}" is not a schedulable action.`,
+      };
+    }
+
+    return await schedulePluginAction({
+      plugin,
+      command,
+      payload: params.payload,
+      schedule: params.schedule,
+      recordSnapshot: toPluginStateSnapshot(record, plugin),
+      context: params.context,
+    });
+  }
+
+  if (action) {
+    if (record.state !== "running") {
+      return {
+        success: false,
+        plugin: toPluginStateSnapshot(record, plugin),
+        message: `Plugin "${plugin.name}" is not running`,
+      };
+    }
+
+    const result = await invokePluginAction({
+      plugin,
+      actionName: command,
+      payload: params.payload,
+      context: params.context,
+    });
+
+    if (!result.success) {
+      return {
+        success: false,
+        plugin: toPluginStateSnapshot(record, plugin),
+        message: result.error || "plugin action failed",
+      };
+    }
+
+    return {
+      success: true,
+      plugin: toPluginStateSnapshot(record, plugin),
+      ...(result.data !== undefined ? { data: result.data } : {}),
+    };
+  }
+
+  const controlAction = toControlCommandAction(command);
+  if (controlAction) {
+    const result = await controlPluginState({
+      pluginName: plugin.name,
+      action: controlAction,
+      context: params.context,
+    });
+    return {
+      success: result.success,
+      ...(result.plugin ? { plugin: result.plugin } : {}),
+      ...(result.error ? { message: result.error } : {}),
+    };
+  }
+
+  if (record.state !== "running") {
+    return {
+      success: false,
+      plugin: toPluginStateSnapshot(record, plugin),
+      message: `Plugin "${plugin.name}" is not running`,
+    };
+  }
+
+  const handler = resolveLifecycle(plugin)?.command;
+  if (handler) {
+    try {
+      const result = await handler({
+        context: params.context,
+        command,
+        payload: params.payload,
+      });
+      return {
+        ...result,
+        plugin: toPluginStateSnapshot(record, plugin),
+      };
+    } catch (error) {
+      markPluginState(record, "error", String(error));
+      return {
+        success: false,
+        plugin: toPluginStateSnapshot(record, plugin),
+        message: String(error),
+      };
+    }
+  }
+
+  return {
+    success: false,
+    plugin: toPluginStateSnapshot(record, plugin),
+    message: `Plugin "${plugin.name}" does not implement command "${command}"`,
+  };
+}

package/src/plugin/core/PluginClassRegistry.ts

@@ -0,0 +1,88 @@
+/**
+ * PluginClassRegistry：统一内建 plugin 类注册表。
+ *
+ * 关键点（中文）
+ * - 所有内建 plugin 都通过这里暴露实例与名称。
+ * - “是否由运行中的 agent 承载”不再由独立类型区分，而是从 plugin 能力推导。
+ */
+
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BUILTIN_PLUGIN_CLASSES } from "@/plugin/core/BuiltinPluginClasses.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
+
+let staticPluginInstances: Map<string, BasePlugin> | null = null;
+
+function createPluginInstance(
+  PluginClass: new (agent: AgentRuntime | null) => BasePlugin,
+  agent: AgentRuntime | null,
+): BasePlugin {
+  return new PluginClass(agent);
+}
+
+/**
+ * 判断 plugin 是否需要运行中的 agent 来承载生命周期/命令。
+ */
+export function isManagedPlugin(plugin: BasePlugin): boolean {
+  return Boolean(plugin.lifecycle);
+}
+
+/**
+ * 返回全部已注册内建 plugin 名称。
+ */
+export function listRegisteredPluginNames(): string[] {
+  return BUILTIN_PLUGIN_CLASSES.map((PluginClass) => new PluginClass(null).name);
+}
+
+/**
+ * 返回全部已注册内建 plugin 实例视图。
+ */
+export function listRegisteredPlugins(): BasePlugin[] {
+  return BUILTIN_PLUGIN_CLASSES.map((PluginClass) => new PluginClass(null));
+}
+
+/**
+ * 返回全部本地 plugin 实例视图。
+ *
+ * 关键点（中文）
+ * - 本地 plugin 指“不依赖运行中 agent lifecycle”的那一类。
+ * - 这类 plugin 可直接由 CLI / 控制面在本进程执行。
+ */
+export function listLocalPlugins(): BasePlugin[] {
+  return listRegisteredPlugins().filter((plugin) => !isManagedPlugin(plugin));
+}
+
+/**
+ * 返回全部受 agent 托管的 plugin 实例视图。
+ */
+export function listManagedPlugins(): BasePlugin[] {
+  return listRegisteredPlugins().filter((plugin) => isManagedPlugin(plugin));
+}
+
+/**
+ * 返回无宿主静态 plugin 实例集合。
+ */
+export function getRegisteredStaticPluginInstances(): Map<string, BasePlugin> {
+  if (staticPluginInstances) return staticPluginInstances;
+  staticPluginInstances = createRegisteredPluginInstances(null);
+  return staticPluginInstances;
+}
+
+/**
+ * 为当前 agent 创建一组内建 plugin instances。
+ */
+export function createRegisteredPluginInstances(
+  agent: AgentRuntime | null,
+): Map<string, BasePlugin> {
+  if (agent === null && staticPluginInstances) {
+    return staticPluginInstances;
+  }
+  const plugins = new Map<string, BasePlugin>();
+  for (const PluginClass of BUILTIN_PLUGIN_CLASSES) {
+    const plugin = createPluginInstance(PluginClass, agent);
+    plugins.set(plugin.name, plugin);
+  }
+  if (agent === null) {
+    staticPluginInstances = plugins;
+  }
+  return plugins;
+}