@downcity/agent 1.1.35 → 1.1.43

package/src/plugin/core/PluginCatalog.ts

@@ -0,0 +1,178 @@
+/**
+ * PluginCatalog：通用 plugin 目录视图工具。
+ *
+ * 关键点（中文）
+ * - 这里不关心 plugin 来源，不区分内建、外部、本地或远程。
+ * - 调用方只需要传入当前已注册或准备展示的 plugin 实例集合。
+ * - Agent 的视角只有“传入的 plugin”，目录视图和可用性检查都从这些实例推导。
+ */
+
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import type {
+  Plugin,
+  PluginAvailability,
+  PluginView,
+} from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+
+/**
+ * 判断 plugin 是否声明了运行时生命周期。
+ */
+export function hasPluginLifecycle(plugin: Plugin): boolean {
+  return Boolean(plugin.lifecycle);
+}
+
+/**
+ * 过滤出声明了运行时生命周期的 plugin。
+ */
+export function listPluginsWithLifecycle<T extends Plugin>(plugins: Iterable<T>): T[] {
+  return [...plugins].filter((plugin) => hasPluginLifecycle(plugin));
+}
+
+/**
+ * 过滤出没有运行时生命周期、可直接执行 action 的 plugin。
+ */
+export function listPluginsWithoutLifecycle<T extends Plugin>(plugins: Iterable<T>): T[] {
+  return [...plugins].filter((plugin) => !hasPluginLifecycle(plugin));
+}
+
+/**
+ * 按名称查找 plugin。
+ */
+export function findPluginByName<T extends Plugin>(
+  plugins: Iterable<T>,
+  pluginName: string,
+): T | null {
+  const key = String(pluginName || "").trim();
+  if (!key) return null;
+  return [...plugins].find((plugin) => plugin.name === key) || null;
+}
+
+/**
+ * 将 plugin 定义转换为目录视图。
+ */
+export function toPluginView(plugin: Plugin): PluginView {
+  return {
+    name: plugin.name,
+    title: String(plugin.title || plugin.name || "").trim(),
+    description: String(plugin.description || "").trim(),
+    actions: Object.keys(plugin.actions || {}).sort((left, right) =>
+      left.localeCompare(right),
+    ),
+    pipelines: Object.keys(plugin.hooks?.pipeline || {}).sort((left, right) =>
+      left.localeCompare(right),
+    ),
+    guards: Object.keys(plugin.hooks?.guard || {}).sort((left, right) =>
+      left.localeCompare(right),
+    ),
+    effects: Object.keys(plugin.hooks?.effect || {}).sort((left, right) =>
+      left.localeCompare(right),
+    ),
+    resolves: Object.keys(plugin.resolves || {}).sort((left, right) =>
+      left.localeCompare(right),
+    ),
+    hasSystem: typeof plugin.system === "function",
+    hasAvailability: typeof plugin.availability === "function",
+  };
+}
+
+/**
+ * 列出 plugin 目录视图。
+ */
+export function listPluginViews(plugins: Iterable<Plugin>): PluginView[] {
+  return [...plugins]
+    .map((plugin) => toPluginView(plugin))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/**
+ * 构建 plugin 可用性视图。
+ *
+ * 关键点（中文）
+ * - 传入 context 时会调用 plugin 自己的 availability。
+ * - 未传 context 时只做静态启用态检查，适合 Console 或 CLI 的目录回退展示。
+ */
+export async function resolvePluginAvailability(params: {
+  plugins: Iterable<Plugin>;
+  pluginName: string;
+  context?: AgentContext;
+  agentError?: string;
+}): Promise<PluginAvailability> {
+  const plugin = findPluginByName(params.plugins, params.pluginName);
+  if (!plugin) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Unknown plugin: ${params.pluginName}`],
+    };
+  }
+
+  if (params.context && plugin.availability) {
+    return await plugin.availability(params.context);
+  }
+
+  const enabled = isPluginEnabled({
+    plugin,
+    ...(params.context ? { context: params.context } : {}),
+  });
+  if (!enabled) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Plugin "${plugin.name}" is disabled`],
+    };
+  }
+
+  const agentReason = String(params.agentError || "").trim();
+  if (agentReason || !params.context) {
+    return {
+      enabled: true,
+      available: false,
+      reasons: agentReason
+        ? [`Agent server unavailable: ${agentReason}`]
+        : ["Static catalog view only. Agent-side availability is not loaded."],
+    };
+  }
+
+  return {
+    enabled: true,
+    available: true,
+    reasons: [],
+  };
+}
+
+/**
+ * 同步构建静态 plugin 可用性视图。
+ */
+export function buildStaticPluginAvailability(params: {
+  plugins: Iterable<Plugin>;
+  pluginName: string;
+  agentError?: string;
+}): PluginAvailability {
+  const plugin = findPluginByName(params.plugins, params.pluginName);
+  if (!plugin) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Unknown plugin: ${params.pluginName}`],
+    };
+  }
+
+  const enabled = isPluginEnabled({ plugin });
+  if (!enabled) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Plugin "${plugin.name}" is disabled`],
+    };
+  }
+
+  const agentReason = String(params.agentError || "").trim();
+  return {
+    enabled: true,
+    available: false,
+    reasons: agentReason
+      ? [`Agent server unavailable: ${agentReason}`]
+      : ["Static catalog view only. Agent-side availability is not loaded."],
+  };
+}

package/src/plugin/core/PluginCommand.ts

@@ -1,21 +1,26 @@
 /**
- * Plugin Action CLI 注册器。
+ * PluginCommand：通用 plugin action CLI 注册器。
  *
  * 关键点（中文）
- * - 负责把“本地可执行”的 plugin actions 挂到 commander（`city <plugin> <action>`）。
- * - 需要运行中 agent 的 plugin 不在这里注册，避免和受托管命令桥接冲突。
+ * - 这里只把调用方传入的 plugin actions 挂到 commander。
+ * - 是否传入某类 plugin 由宿主决定，agent 不内置任何 plugin 清单。
  */
 
 import path from "node:path";
 import type { Command } from "commander";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import { listLocalPlugins } from "@/plugin/core/PluginClassRegistry.js";
 import type { Plugin, PluginAction } from "@/plugin/types/Plugin.js";
-import { runLocalPluginAction } from "@/plugin/core/LocalExecution.js";
+import { runLocalPluginAction } from "@/plugin/core/PluginLocalExecution.js";
 import { printResult } from "@/utils/cli/CliOutput.js";
 
 type PluginCliBridgeOptions = {
+  /**
+   * 项目根目录。
+   */
   path?: string;
+  /**
+   * 是否以 JSON 输出。
+   */
   json?: boolean;
 };
 
@@ -88,9 +93,7 @@ function flattenPluginActionCommandArgs(values: unknown[]): string[] {
     if (!text) return;
     out.push(text);
   };
-  for (const value of values) {
-    pushValue(value);
-  }
+  for (const value of values) pushValue(value);
   return out;
 }
 
@@ -115,6 +118,7 @@ function isPlainOptionsObject(
 
 function registerPluginActionCommand(params: {
   program: Command;
+  plugins: Plugin[];
   plugin: Plugin;
   actionName: string;
   action: PluginAction<JsonValue, JsonValue>;
@@ -182,6 +186,7 @@ function registerPluginActionCommand(params: {
     }
 
     const local = await runLocalPluginAction({
+      plugins: params.plugins,
       projectRoot: resolveProjectRoot(bridgeOptions.path),
       pluginName: params.plugin.name,
       actionName: params.actionName,
@@ -203,13 +208,18 @@ function registerPluginActionCommand(params: {
 }
 
 /**
- * 注册全部 plugin actions 的 CLI 命令。
+ * 注册指定 plugin 集合的 action CLI 命令。
  */
-export function registerAllPluginsForCli(program: Command): void {
-  for (const plugin of listLocalPlugins()) {
+export function registerPluginActionCommandsForCli(params: {
+  program: Command;
+  plugins: Iterable<Plugin>;
+}): void {
+  const plugins = [...params.plugins];
+  for (const plugin of plugins) {
     for (const [actionName, action] of Object.entries(plugin.actions || {})) {
       registerPluginActionCommand({
-        program,
+        program: params.program,
+        plugins,
         plugin,
         actionName,
         action,

package/src/plugin/core/PluginCommandRequest.ts

@@ -4,15 +4,15 @@
  * 关键点（中文）
  * - 统一收口 HTTP / RPC 两种入口的请求体解析。
  * - plugin runtime 远程调用统一走 runtime command 协议，不再让 action 自带 HTTP route。
- * - 通用调度参数（`schedule` / `delay` / `time`）也在这里一次性归一化。
+ * - ActionSchedule 参数（`schedule` / `delay` / `time`）也在这里一次性归一化。
  */
 
 import type { JsonValue } from "@/types/common/Json.js";
-import type { PluginCommandScheduleInput } from "@/plugin/types/PluginSchedule.js";
+import type { PluginActionScheduleInput } from "@/plugin/types/ActionSchedule.js";
 import {
   normalizeRunAtMsOrThrow,
-  parseScheduledRunAtMsOrThrow,
-} from "@/plugin/core/schedule/Time.js";
+  parseActionScheduleRunAtMsOrThrow,
+} from "@/plugin/core/ActionScheduleTime.js";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -35,7 +35,7 @@ export type PluginCommandRequestBody = {
   /**
    * 可选调度信息。
    */
-  schedule?: PluginCommandScheduleInput;
+  schedule?: PluginActionScheduleInput;
 };
 
 function isJsonRecord(value: unknown): value is JsonRecord {
@@ -47,7 +47,7 @@ function isJsonRecord(value: unknown): value is JsonRecord {
  */
 function readScheduleInput(
   body: JsonRecord,
-): PluginCommandScheduleInput | undefined {
+): PluginActionScheduleInput | undefined {
   const nestedSchedule = isJsonRecord(body.schedule) ? body.schedule : undefined;
   const nestedRunAtMs = nestedSchedule?.runAtMs;
   const topLevelDelay = body.delayMs ?? body.delay;
@@ -68,7 +68,7 @@ function readScheduleInput(
     };
   }
 
-  const runAtMs = parseScheduledRunAtMsOrThrow({
+  const runAtMs = parseActionScheduleRunAtMsOrThrow({
     delay: topLevelDelay as string | number | undefined,
     time: topLevelTime as string | number | undefined,
   });

package/src/plugin/core/PluginHttpRoutes.ts

@@ -0,0 +1,47 @@
+/**
+ * PluginHttpRoutes：通用 plugin HTTP 声明装配工具。
+ *
+ * 关键点（中文）
+ * - 这里只消费调用方传入的 plugin 集合，不关心 plugin 来源。
+ * - HTTP route 与鉴权策略由 plugin 自己声明，宿主只负责收集和注册。
+ */
+
+import type { Hono } from "hono";
+import type { Plugin } from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
+
+function dedupeAuthPolicies(policies: AuthRoutePolicy[]): AuthRoutePolicy[] {
+  const records = new Map<string, AuthRoutePolicy>();
+  for (const policy of policies) {
+    const key = `${String(policy.method || "*").trim().toUpperCase()}:${String(policy.path || "").trim()}`;
+    if (!key.endsWith(":")) records.set(key, policy);
+  }
+  return [...records.values()];
+}
+
+/**
+ * 收集全部 plugin HTTP 鉴权策略。
+ */
+export function listPluginAuthPolicies(plugins: Iterable<Plugin>): AuthRoutePolicy[] {
+  return dedupeAuthPolicies(
+    [...plugins].flatMap((plugin) => plugin.http?.server?.authPolicies || []),
+  );
+}
+
+/**
+ * 注册全部 plugin HTTP 路由。
+ */
+export function registerPluginHttpRoutes(params: {
+  app: Hono;
+  getContext: () => AgentContext;
+  plugins: Iterable<Plugin>;
+}): void {
+  for (const plugin of params.plugins) {
+    plugin.http?.server?.register({
+      app: params.app,
+      getContext: params.getContext,
+      pluginName: plugin.name,
+    });
+  }
+}

package/src/plugin/core/PluginLocalExecution.ts

@@ -0,0 +1,155 @@
+/**
+ * PluginLocalExecution：通用本地 plugin action 执行工具。
+ *
+ * 关键点（中文）
+ * - 这里不创建或维护任何全局注册表，调用方必须显式传入 plugin 集合。
+ * - 用于 CLI / 控制面这类没有运行中 Agent 实例、但需要执行 setup action 的场景。
+ * - 真正运行中的 Agent 仍应优先使用 `PluginRegistry.runAction`。
+ */
+
+import path from "node:path";
+import { logger as defaultLogger } from "@/utils/logger/Logger.js";
+import { loadAgentEnvSnapshot, loadDowncityConfig } from "@/config/Config.js";
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import { findPluginByName } from "@/plugin/core/PluginCatalog.js";
+import {
+  createAgentPathRuntime,
+  createAgentPluginConfigRuntime,
+} from "@/runtime/host/AgentHostRuntime.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type {
+  Plugin,
+  PluginActionResult,
+  PluginAvailability,
+  PluginCommandContext,
+} from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+
+/**
+ * 创建本地 plugin 命令上下文。
+ */
+export function createLocalPluginCommandContext(projectRoot: string): PluginCommandContext {
+  const rootPath = path.resolve(String(projectRoot || "").trim() || ".");
+  const env = loadAgentEnvSnapshot(rootPath);
+  const config = loadDowncityConfig(rootPath, {
+    projectEnv: env,
+    agentEnv: env,
+    globalEnv: {},
+  });
+
+  defaultLogger.bindProjectRoot(rootPath);
+
+  return {
+    cwd: rootPath,
+    rootPath,
+    logger: defaultLogger,
+    config,
+    env,
+    paths: createAgentPathRuntime(
+      rootPath,
+      String(config.name || "").trim() || path.basename(rootPath) || "agent",
+    ),
+    pluginConfig: createAgentPluginConfigRuntime(rootPath),
+  };
+}
+
+/**
+ * 读取本地 plugin availability。
+ */
+export async function getLocalPluginAvailability(params: {
+  plugins: Iterable<Plugin>;
+  projectRoot: string;
+  pluginName: string;
+}): Promise<PluginAvailability> {
+  const plugin = findPluginByName(params.plugins, params.pluginName);
+  if (!plugin) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Unknown plugin: ${params.pluginName}`],
+    };
+  }
+
+  const context = createLocalPluginCommandContext(params.projectRoot);
+  if (plugin.availability) {
+    return await plugin.availability(context);
+  }
+
+  const enabled = isPluginEnabled({ plugin, context });
+  if (!enabled) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Plugin "${plugin.name}" is disabled`],
+    };
+  }
+
+  return {
+    enabled: true,
+    available: true,
+    reasons: [],
+  };
+}
+
+/**
+ * 直接执行本地 plugin action。
+ */
+export async function runLocalPluginAction(params: {
+  plugins: Iterable<Plugin>;
+  projectRoot: string;
+  pluginName: string;
+  actionName: string;
+  payload?: JsonValue;
+}): Promise<PluginActionResult<JsonValue>> {
+  const plugin = findPluginByName(params.plugins, params.pluginName);
+  if (!plugin) {
+    return {
+      success: false,
+      error: `Unknown plugin: ${params.pluginName}`,
+      message: `Unknown plugin: ${params.pluginName}`,
+    };
+  }
+
+  const actionName = String(params.actionName || "").trim();
+  if (!actionName) {
+    return {
+      success: false,
+      error: "action is required",
+      message: "action is required",
+    };
+  }
+
+  const action = plugin.actions?.[actionName];
+  if (!action) {
+    return {
+      success: false,
+      error: `Plugin "${plugin.name}" does not implement action "${actionName}"`,
+      message: `Plugin "${plugin.name}" does not implement action "${actionName}"`,
+    };
+  }
+
+  const context = createLocalPluginCommandContext(params.projectRoot);
+  const enabled = isPluginEnabled({ plugin, context });
+  if (!enabled && action.allowWhenDisabled !== true) {
+    return {
+      success: false,
+      error: `Plugin "${plugin.name}" is disabled`,
+      message: `Plugin "${plugin.name}" is disabled`,
+    };
+  }
+
+  try {
+    return await action.execute({
+      context: context as unknown as AgentContext,
+      payload: (params.payload ?? {}) as JsonValue,
+      pluginName: plugin.name,
+      actionName,
+    });
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+      message: String(error),
+    };
+  }
+}

package/src/plugin/core/PluginRegistry.ts

@@ -7,6 +7,7 @@
  */
 
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import { toPluginView } from "@/plugin/core/PluginCatalog.js";
 import type { HookRegistry } from "@/plugin/core/HookRegistry.js";
 import type {
   Plugin,
@@ -14,7 +15,7 @@ import type {
   PluginAvailability,
   PluginView,
 } from "@/plugin/types/Plugin.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { JsonValue } from "@/types/common/Json.js";
 
 type ContextResolver = () => AgentContext;
@@ -122,28 +123,7 @@ export class PluginRegistry {
    */
   list(): PluginView[] {
     return Array.from(this.plugins.values())
-      .map((plugin) => ({
-        name: plugin.name,
-        title: String(plugin.title || plugin.name || "").trim(),
-        description: String(plugin.description || "").trim(),
-        actions: Object.keys(plugin.actions || {}).sort((a, b) =>
-          a.localeCompare(b),
-        ),
-        pipelines: Object.keys(plugin.hooks?.pipeline || {}).sort((a, b) =>
-          a.localeCompare(b),
-        ),
-        guards: Object.keys(plugin.hooks?.guard || {}).sort((a, b) =>
-          a.localeCompare(b),
-        ),
-        effects: Object.keys(plugin.hooks?.effect || {}).sort((a, b) =>
-          a.localeCompare(b),
-        ),
-        resolves: Object.keys(plugin.resolves || {}).sort((a, b) =>
-          a.localeCompare(b),
-        ),
-        hasSystem: typeof plugin.system === "function",
-        hasAvailability: typeof plugin.availability === "function",
-      }))
+      .map((plugin) => toPluginView(plugin))
       .sort((a, b) => a.name.localeCompare(b.name));
   }
 

package/src/plugin/core/PluginStateController.ts

@@ -2,8 +2,8 @@
  * PluginStateController：主动型 plugin 状态控制与状态记录模块。
  */
 
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   Plugin,
   PluginLifecycle,
@@ -13,11 +13,6 @@ import type {
   PluginStateRecord,
   PluginStateSnapshot,
 } from "@/plugin/types/Plugin.js";
-import {
-  getRegisteredStaticPluginInstances,
-  listRegisteredPluginNames,
-  listRegisteredPlugins,
-} from "@/plugin/core/PluginClassRegistry.js";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 
 function nowMs(): number {
@@ -43,7 +38,7 @@ export function listPluginInstances(input?: {
   if (runtimePlugins instanceof Map && runtimePlugins.size > 0) {
     return [...runtimePlugins.values()];
   }
-  return [...getRegisteredStaticPluginInstances().values()];
+  return [];
 }
 
 /**
@@ -141,14 +136,14 @@ export function markPluginCommand(
  * 返回静态主动型 plugin 定义清单。
  */
 export function getStaticPlugins(): Plugin[] {
-  return listRegisteredPlugins();
+  return [];
 }
 
 /**
  * 返回主动型 plugin 根命令名清单。
  */
 export function getPluginRootCommandNames(): string[] {
-  return listRegisteredPluginNames();
+  return [];
 }
 
 /**