@downcity/agent 1.1.8 → 1.1.10

package/src/plugin/core/HookRegistry.ts

@@ -0,0 +1,249 @@
+/**
+ * Plugin 点注册表。
+ *
+ * 关键点（中文）
+ * - 统一管理 pipeline / guard / effect / resolve 四类 plugin 点。
+ * - service 只依赖固定执行语义，不再自己拼装扩展调度逻辑。
+ */
+
+import type { JsonValue } from "@/utils/types/Json.js";
+import type {
+  PluginEffectHook,
+  PluginGuardHook,
+  PluginPipelineHook,
+  PluginResolveHook,
+} from "@/plugin/types/Plugin.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+
+type ContextResolver = () => AgentContext;
+type PluginEnabledChecker = (pluginName: string, context: AgentContext) => boolean;
+
+type PipelineRecord = {
+  pluginName: string;
+  handler: PluginPipelineHook<JsonValue>;
+};
+
+type GuardRecord = {
+  pluginName: string;
+  handler: PluginGuardHook<JsonValue>;
+};
+
+type EffectRecord = {
+  pluginName: string;
+  handler: PluginEffectHook<JsonValue>;
+};
+
+type ResolveRecord = {
+  pluginName: string;
+  handler: PluginResolveHook<JsonValue, JsonValue>;
+};
+
+/**
+ * HookRegistry：plugin 点注册与执行实现。
+ */
+export class HookRegistry {
+  private readonly contextResolver: ContextResolver;
+  private readonly pluginEnabledChecker: PluginEnabledChecker;
+
+  private readonly pipelineHooks = new Map<string, PipelineRecord[]>();
+
+  private readonly guardHooks = new Map<string, GuardRecord[]>();
+
+  private readonly effectHooks = new Map<string, EffectRecord[]>();
+
+  private readonly resolveHooks = new Map<string, ResolveRecord>();
+
+  constructor(params: {
+    contextResolver: ContextResolver;
+    pluginEnabledChecker: PluginEnabledChecker;
+  }) {
+    this.contextResolver = params.contextResolver;
+    this.pluginEnabledChecker = params.pluginEnabledChecker;
+  }
+
+  /**
+   * 注册 pipeline 扩展点。
+   */
+  pipeline(
+    pointName: string,
+    pluginName: string,
+    handler: PluginPipelineHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Pipeline point name is required");
+    }
+    const bucket = this.pipelineHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.pipelineHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 guard 扩展点。
+   */
+  guard(
+    pointName: string,
+    pluginName: string,
+    handler: PluginGuardHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Guard point name is required");
+    }
+    const bucket = this.guardHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.guardHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 effect 扩展点。
+   */
+  effect(
+    pointName: string,
+    pluginName: string,
+    handler: PluginEffectHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Effect point name is required");
+    }
+    const bucket = this.effectHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.effectHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 resolve 扩展点。
+   *
+   * 关键点（中文）
+   * - resolve 语义要求单点单处理器，避免 service 侧再做二次仲裁。
+   */
+  resolve(
+    pointName: string,
+    pluginName: string,
+    handler: PluginResolveHook<JsonValue, JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Resolve point name is required");
+    }
+    if (this.resolveHooks.has(key)) {
+      throw new Error(`Resolve point already registered: ${key}`);
+    }
+    this.resolveHooks.set(key, {
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+  }
+
+  /**
+   * 列出所有已注册扩展点。
+   */
+  list(): string[] {
+    const keys = new Set<string>([
+      ...this.pipelineHooks.keys(),
+      ...this.guardHooks.keys(),
+      ...this.effectHooks.keys(),
+      ...this.resolveHooks.keys(),
+    ]);
+    return Array.from(keys).sort((a, b) => a.localeCompare(b));
+  }
+
+  /**
+   * 运行 pipeline 扩展点。
+   */
+  async pipelineValue<T = JsonValue>(pointName: string, value: T): Promise<T> {
+    const key = String(pointName || "").trim();
+    if (!key) return value;
+    const bucket = this.pipelineHooks.get(key) || [];
+    if (bucket.length === 0) return value;
+
+    const context = this.contextResolver();
+    let current = value as JsonValue;
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      current = await item.handler({
+        context,
+        value: current,
+        plugin: item.pluginName,
+      });
+    }
+    return current as T;
+  }
+
+  /**
+   * 运行 guard 扩展点。
+   */
+  async guardValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
+    const key = String(pointName || "").trim();
+    if (!key) return;
+    const bucket = this.guardHooks.get(key) || [];
+    if (bucket.length === 0) return;
+
+    const context = this.contextResolver();
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      await item.handler({
+        context,
+        value: value as JsonValue,
+        plugin: item.pluginName,
+      });
+    }
+  }
+
+  /**
+   * 运行 effect 扩展点。
+   */
+  async effectValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
+    const key = String(pointName || "").trim();
+    if (!key) return;
+    const bucket = this.effectHooks.get(key) || [];
+    if (bucket.length === 0) return;
+
+    const context = this.contextResolver();
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      await item.handler({
+        context,
+        value: value as JsonValue,
+        plugin: item.pluginName,
+      });
+    }
+  }
+
+  /**
+   * 运行 resolve 点。
+   */
+  async resolveValue<TInput = JsonValue, TOutput = JsonValue>(
+    pointName: string,
+    value: TInput,
+  ): Promise<TOutput> {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Resolve point name is required");
+    }
+    const record = this.resolveHooks.get(key);
+    if (!record) {
+      throw new Error(`No plugin resolver registered for point: ${key}`);
+    }
+    const context = this.contextResolver();
+    if (!this.pluginEnabledChecker(record.pluginName, context)) {
+      throw new Error(`No active plugin resolver registered for point: ${key}`);
+    }
+
+    return await record.handler({
+      context,
+      value: value as JsonValue,
+      plugin: record.pluginName,
+    }) as TOutput;
+  }
+}

package/src/plugin/core/HttpRoutes.ts

@@ -0,0 +1,50 @@
+/**
+ * Plugin HTTP 路由装配。
+ *
+ * 关键点（中文）
+ * - 这里统一装配内建 plugin 的 runtime HTTP 路由与鉴权策略。
+ * - plugin 自己声明路由；server 与 console 只负责消费这份声明。
+ */
+
+import type { Hono } from "hono";
+import { PLUGINS } from "@/plugin/core/Plugins.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AuthRoutePolicy } from "@/host/http/auth/types/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 runtime 鉴权策略。
+ */
+export function listBuiltinPluginRuntimeAuthPolicies(): AuthRoutePolicy[] {
+  return dedupeAuthPolicies(
+    PLUGINS.flatMap((plugin) => plugin.http?.runtime?.authPolicies || []),
+  );
+}
+
+/**
+ * 注册全部内建 plugin runtime HTTP 路由。
+ */
+export function registerBuiltinPluginHttpRoutes(params: {
+  app: Hono;
+  getContext: () => AgentContext;
+}): void {
+  for (const plugin of PLUGINS) {
+    plugin.http?.runtime?.register({
+      app: params.app,
+      getContext: params.getContext,
+      pluginName: plugin.name,
+    });
+  }
+}

package/src/plugin/core/LocalExecution.ts

@@ -0,0 +1,179 @@
+/**
+ * Plugin 本地命令执行器。
+ *
+ * 关键点（中文）
+ * - plugin 本质上是一些本地 CLI 命令，这里只负责为命令准备最小上下文并直接执行。
+ * - 不依赖 agent daemon，不伪造 session / service / agent runtime。
+ * - 真正需要完整 runtime 的场景，仍由 agent 内部自行复用同一批 plugin 定义。
+ */
+
+import path from "node:path";
+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 {
+  createAgentPathRuntime,
+  createAgentPluginConfigRuntime,
+} from "@/host/runtime/AgentHostRuntime.js";
+import { getAgentRuntimeBase } from "@/agent/AgentRuntimeState.js";
+import type { JsonValue } from "@/utils/types/Json.js";
+import type {
+  PluginActionResult,
+  PluginAvailability,
+  PluginCommandContext,
+  PluginView,
+} from "@/plugin/types/Plugin.js";
+
+/**
+ * 创建本地 plugin 命令上下文。
+ */
+export function createLocalPluginCommandContext(projectRoot: string): PluginCommandContext {
+  const rootPath = path.resolve(String(projectRoot || "").trim() || ".");
+  const globalEnv = loadGlobalEnvFromStore();
+  const env = loadAgentEnvSnapshot(rootPath);
+  const config = loadDowncityConfig(rootPath, {
+    projectEnv: env,
+    globalEnv,
+  });
+
+  defaultLogger.bindProjectRoot(rootPath);
+
+  const platform = (() => {
+    try {
+      return getAgentRuntimeBase().platform;
+    } catch {
+      return {
+        getGlobalEnv: () => ({}),
+        getAgentEnv: () => ({}),
+        listModels: () => [],
+        listProviders: async () => [],
+        getModel: () => null,
+        getChannelAccount: () => null,
+        readChatAuthorizationConfig: () => ({ roles: {}, channels: {} }),
+        writeChatAuthorizationConfig: async (_projectRoot: string, nextConfig: unknown) =>
+          nextConfig as never,
+        setChatAuthorizationUserRole: async () => ({ roles: {}, channels: {} }),
+        isPluginEnabled: (pluginName: string) => pluginName === "auth",
+      };
+    }
+  })();
+
+  return {
+    cwd: rootPath,
+    rootPath,
+    logger: defaultLogger,
+    config,
+    env,
+    globalEnv,
+    paths: createAgentPathRuntime(rootPath),
+    pluginConfig: createAgentPluginConfigRuntime(rootPath),
+    platform,
+  };
+}
+
+/**
+ * 列出本地内建 plugin 视图。
+ */
+export function listLocalPlugins(): PluginView[] {
+  return listStaticPluginViews();
+}
+
+/**
+ * 读取本地 plugin availability。
+ */
+export async function getLocalPluginAvailability(
+  projectRoot: string,
+  pluginName: string,
+): Promise<PluginAvailability> {
+  const plugin = findBuiltinPlugin(pluginName);
+  if (!plugin) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Unknown plugin: ${pluginName}`],
+    };
+  }
+
+  const context = createLocalPluginCommandContext(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: {
+  projectRoot: string;
+  pluginName: string;
+  actionName: string;
+  payload?: JsonValue;
+}): Promise<PluginActionResult<JsonValue>> {
+  const plugin = findBuiltinPlugin(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,
+      payload: (params.payload ?? {}) as JsonValue,
+      pluginName: plugin.name,
+      actionName,
+    });
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+      message: String(error),
+    };
+  }
+}

package/src/plugin/core/PluginCommand.ts

@@ -0,0 +1,219 @@
+/**
+ * Plugin Action CLI 注册器。
+ *
+ * 关键点（中文）
+ * - 负责把 plugin actions 挂到 commander（`city <plugin> <action>`）。
+ * - plugin 命令默认直接在当前 CLI 进程内执行，不再桥接到 agent transport。
+ */
+
+import path from "node:path";
+import type { Command } from "commander";
+import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import { PLUGINS } from "@/plugin/core/Plugins.js";
+import type { Plugin, PluginAction } from "@/plugin/types/Plugin.js";
+import { runLocalPluginAction } from "@/plugin/core/LocalExecution.js";
+import { printResult } from "@/utils/cli/CliOutput.js";
+
+type PluginCliBridgeOptions = {
+  path?: string;
+  json?: boolean;
+};
+
+function resolveProjectRoot(pathInput?: string): string {
+  return path.resolve(String(pathInput || "."));
+}
+
+function toJsonValue(input: unknown): JsonValue | undefined {
+  if (input === null) return null;
+  if (typeof input === "string") return input;
+  if (typeof input === "number") {
+    return Number.isFinite(input) ? input : undefined;
+  }
+  if (typeof input === "boolean") return input;
+  if (Array.isArray(input)) {
+    const values: JsonValue[] = [];
+    for (const item of input) {
+      const value = toJsonValue(item);
+      if (value === undefined) continue;
+      values.push(value);
+    }
+    return values;
+  }
+  if (typeof input === "object" && input) {
+    const output: JsonObject = {};
+    for (const [key, value] of Object.entries(
+      input as Record<string, unknown>,
+    )) {
+      const normalized = toJsonValue(value);
+      if (normalized === undefined) continue;
+      output[key] = normalized;
+    }
+    return output;
+  }
+  return undefined;
+}
+
+function toPluginActionCommandOpts(
+  options: Record<string, unknown>,
+): Record<string, JsonValue> {
+  const reservedKeys = new Set(["path", "host", "port", "token", "json"]);
+  const normalized: Record<string, JsonValue> = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (reservedKeys.has(key)) continue;
+    const nextValue = toJsonValue(value);
+    if (nextValue === undefined) continue;
+    normalized[key] = nextValue;
+  }
+  return normalized;
+}
+
+function toPluginCliBridgeOptions(
+  options: Record<string, unknown>,
+): PluginCliBridgeOptions {
+  return {
+    path: typeof options.path === "string" ? options.path : ".",
+    json: options.json !== false,
+  };
+}
+
+function flattenPluginActionCommandArgs(values: unknown[]): string[] {
+  const out: string[] = [];
+  const pushValue = (value: unknown): void => {
+    if (value === undefined || value === null) return;
+    if (Array.isArray(value)) {
+      for (const item of value) pushValue(item);
+      return;
+    }
+    const text = String(value).trim();
+    if (!text) return;
+    out.push(text);
+  };
+  for (const value of values) {
+    pushValue(value);
+  }
+  return out;
+}
+
+function isCommanderCommandLike(value: unknown): value is Command {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as { opts?: unknown }).opts === "function",
+  );
+}
+
+function isPlainOptionsObject(
+  value: unknown,
+): value is Record<string, unknown> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof (value as { opts?: unknown }).opts !== "function",
+  );
+}
+
+function registerPluginActionCommand(params: {
+  program: Command;
+  plugin: Plugin;
+  actionName: string;
+  action: PluginAction<JsonValue, JsonValue>;
+}): void {
+  const commandSpec = params.action.command;
+  if (!commandSpec) return;
+
+  const pluginCommand =
+    params.program.commands.find((item) => item.name() === params.plugin.name) ||
+    params.program
+      .command(params.plugin.name)
+      .description(`${params.plugin.name} plugin actions`)
+      .helpOption("--help", "display help for command");
+
+  const actionCommand = pluginCommand
+    .command(params.actionName)
+    .description(commandSpec.description)
+    .helpOption("--help", "display help for command")
+    .option("--path <path>", "项目根目录（默认当前目录）", ".")
+    .option("--json [enabled]", "以 JSON 输出", true);
+
+  commandSpec.configure?.(actionCommand);
+
+  actionCommand.action(async (...rawArgs: unknown[]) => {
+    const last = rawArgs.at(-1);
+    const commandLike = isCommanderCommandLike(last) ? last : null;
+    const positionalArgs = commandLike
+      ? flattenPluginActionCommandArgs(
+          Array.isArray(commandLike.processedArgs)
+            ? (commandLike.processedArgs as unknown[])
+            : [],
+        )
+      : (() => {
+          const fallbackLast = rawArgs.at(-1);
+          const fallbackPositional = isPlainOptionsObject(fallbackLast)
+            ? rawArgs.slice(0, -1)
+            : rawArgs;
+          return flattenPluginActionCommandArgs(fallbackPositional);
+        })();
+    const allOptions = commandLike
+      ? ((commandLike.opts() as Record<string, unknown>) || {})
+      : (() => {
+          const fallbackLast = rawArgs.at(-1);
+          return isPlainOptionsObject(fallbackLast) ? fallbackLast : {};
+        })();
+    const actionOptions = toPluginActionCommandOpts(allOptions);
+    const bridgeOptions = toPluginCliBridgeOptions(allOptions);
+
+    let payload: JsonValue;
+    try {
+      payload = await commandSpec.mapInput({
+        args: positionalArgs,
+        opts: actionOptions,
+      });
+    } catch (error) {
+      printResult({
+        asJson: bridgeOptions.json,
+        success: false,
+        title: `${params.plugin.name}.${params.actionName} failed`,
+        payload: {
+          error: `Failed to parse command input: ${String(error)}`,
+        },
+      });
+      return;
+    }
+
+    const local = await runLocalPluginAction({
+      projectRoot: resolveProjectRoot(bridgeOptions.path),
+      pluginName: params.plugin.name,
+      actionName: params.actionName,
+      payload,
+    });
+    printResult({
+      asJson: bridgeOptions.json,
+      success: Boolean(local.success),
+      title: local.success
+        ? `${params.plugin.name}.${params.actionName} ok`
+        : `${params.plugin.name}.${params.actionName} failed`,
+      payload: {
+        ...(local.data !== undefined ? { data: local.data } : {}),
+        ...(local.message ? { message: local.message } : {}),
+        ...(local.error ? { error: local.error } : {}),
+      },
+    });
+  });
+}
+
+/**
+ * 注册全部 plugin actions 的 CLI 命令。
+ */
+export function registerAllPluginsForCli(program: Command): void {
+  for (const plugin of PLUGINS) {
+    for (const [actionName, action] of Object.entries(plugin.actions || {})) {
+      registerPluginActionCommand({
+        program,
+        plugin,
+        actionName,
+        action,
+      });
+    }
+  }
+}