@downcity/agent 1.1.8 → 1.1.11

package/src/plugin/HookRegistry.ts

@@ -1,249 +0,0 @@
-/**
- * Plugin 点注册表。
- *
- * 关键点（中文）
- * - 统一管理 pipeline / guard / effect / resolve 四类 plugin 点。
- * - service 只依赖固定执行语义，不再自己拼装扩展调度逻辑。
- */
-
-import type { JsonValue } from "@/shared/types/Json.js";
-import type {
-  PluginEffectHook,
-  PluginGuardHook,
-  PluginPipelineHook,
-  PluginResolveHook,
-} from "@/shared/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/HttpRoutes.ts

@@ -1,50 +0,0 @@
-/**
- * Plugin HTTP 路由装配。
- *
- * 关键点（中文）
- * - 这里统一装配内建 plugin 的 runtime HTTP 路由与鉴权策略。
- * - plugin 自己声明路由；server 与 console 只负责消费这份声明。
- */
-
-import type { Hono } from "hono";
-import { PLUGINS } from "@/plugin/Plugins.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { AuthRoutePolicy } from "@/shared/types/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 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/LocalExecution.ts

@@ -1,179 +0,0 @@
-/**
- * Plugin 本地命令执行器。
- *
- * 关键点（中文）
- * - plugin 本质上是一些本地 CLI 命令，这里只负责为命令准备最小上下文并直接执行。
- * - 不依赖 agent daemon，不伪造 session / service / agent runtime。
- * - 真正需要完整 runtime 的场景，仍由 agent 内部自行复用同一批 plugin 定义。
- */
-
-import path from "node:path";
-import { logger as defaultLogger } from "@shared/utils/logger/Logger.js";
-import { loadAgentEnvSnapshot, loadDowncityConfig, loadGlobalEnvFromStore } from "@/config/Config.js";
-import { isPluginEnabled } from "@/plugin/Activation.js";
-import { findBuiltinPlugin, listStaticPluginViews } from "@/plugin/Catalog.js";
-import {
-  createAgentPathRuntime,
-  createAgentPluginConfigRuntime,
-} from "@/host/runtime/AgentHostRuntime.js";
-import { getAgentRuntimeBase } from "@/agent/AgentRuntimeState.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-import type {
-  PluginActionResult,
-  PluginAvailability,
-  PluginCommandContext,
-  PluginView,
-} from "@/shared/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/PluginCommand.ts

@@ -1,219 +0,0 @@
-/**
- * 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 "@/shared/types/Json.js";
-import { PLUGINS } from "@/plugin/Plugins.js";
-import type { Plugin, PluginAction } from "@/shared/types/Plugin.js";
-import { runLocalPluginAction } from "@/plugin/LocalExecution.js";
-import { printResult } from "@shared/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,
-      });
-    }
-  }
-}