@downcity/city 1.1.1 → 1.1.5

package/src/plugin/PluginCommand.ts

@@ -1,220 +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";
-import { parseBoolean } from "@/cli/IndexSupport.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 输出", parseBoolean, 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,
-      });
-    }
-  }
-}

package/src/plugin/PluginManager.ts

@@ -1,66 +0,0 @@
-/**
- * PluginManager 单例。
- *
- * 关键点（中文）
- * - `main/plugin/*` 是 plugin 的管理层，不是具体 plugin 实现层。
- * - plugin hook / resolve / system 注入所依赖的注册与调度统一收口到这里。
- * - PluginManager 属于 city runtime，不直接反向依赖 agent AgentContext 单例。
- * - agent 只是通过 AgentContext 调用统一 plugin manager。
- * - 具体 plugin 实现位于 `src/plugins/*`，CLI plugin 命令则直接走本地命令执行器。
- */
-
-import { isPluginEnabled } from "@/plugin/Activation.js";
-import { HookRegistry } from "@/plugin/HookRegistry.js";
-import { PluginRegistry } from "@/plugin/PluginRegistry.js";
-import { registerBuiltinPlugins } from "@/plugin/Plugins.js";
-import { getPluginRuntimeContextResolver } from "@/runtime/PluginRuntime.js";
-
-let pluginManager: PluginRegistry | null = null;
-
-/**
- * 初始化全局 plugin manager。
- */
-export function initializePluginManager(): PluginRegistry {
-  if (pluginManager) return pluginManager;
-
-  const contextResolver = getPluginRuntimeContextResolver();
-  let pluginRegistryRef: PluginRegistry | null = null;
-  const hookRegistry = new HookRegistry({
-    contextResolver,
-    pluginEnabledChecker: (pluginName, context) => {
-      const plugin = pluginRegistryRef?.get(pluginName);
-      if (!plugin) return false;
-      return isPluginEnabled({
-        plugin,
-      });
-    },
-  });
-
-  const registry = new PluginRegistry({
-    contextResolver,
-    hookRegistry,
-  });
-  pluginRegistryRef = registry;
-  registerBuiltinPlugins({
-    pluginRegistry: registry,
-  });
-  pluginManager = registry;
-  return registry;
-}
-
-/**
- * 读取全局 plugin manager。
- */
-export function getPluginManager(): PluginRegistry {
-  if (!pluginManager) {
-    return initializePluginManager();
-  }
-  return pluginManager;
-}
-
-/**
- * 重置全局 plugin manager（测试/重启场景）。
- */
-export function resetPluginManager(): void {
-  pluginManager = null;
-}

package/src/plugin/PluginRegistry.ts

@@ -1,244 +0,0 @@
-/**
- * Plugin 注册表。
- *
- * 关键点（中文）
- * - 统一管理 plugin 注册、可用性检查与显式 action 运行。
- * - Plugin 自身不维护独立状态机；可用性由 enabled 配置与 plugin 自定义 availability 决定。
- */
-
-import { isPluginEnabled } from "@/plugin/Activation.js";
-import type { HookRegistry } from "@/plugin/HookRegistry.js";
-import type {
-  Plugin,
-  PluginActionResult,
-  PluginAvailability,
-  PluginView,
-} from "@/shared/types/Plugin.js";
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-
-type ContextResolver = () => AgentContext;
-
-/**
- * PluginRegistry：plugin 注册与调度实现。
- */
-export class PluginRegistry {
-  private readonly contextResolver: ContextResolver;
-
-  private readonly hookRegistry: HookRegistry;
-
-  private readonly plugins = new Map<string, Plugin>();
-
-  constructor(params: {
-    contextResolver: ContextResolver;
-    hookRegistry: HookRegistry;
-  }) {
-    this.contextResolver = params.contextResolver;
-    this.hookRegistry = params.hookRegistry;
-  }
-
-  /**
-   * 注册单个 Plugin。
-   */
-  register(plugin: Plugin): void {
-    const key = String(plugin.name || "").trim();
-    if (!key) {
-      throw new Error("Plugin name is required");
-    }
-    if (this.plugins.has(key)) {
-      throw new Error(`Plugin already registered: ${key}`);
-    }
-    this.plugins.set(key, plugin);
-
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.pipeline || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.pipeline(hookName, key, handler);
-      }
-    }
-
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.guard || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.guard(hookName, key, handler);
-      }
-    }
-
-    for (const [hookName, handlers] of Object.entries(
-      plugin.hooks?.effect || {},
-    )) {
-      for (const handler of handlers) {
-        this.hookRegistry.effect(hookName, key, handler);
-      }
-    }
-
-    for (const [pointName, handler] of Object.entries(plugin.resolves || {})) {
-      this.hookRegistry.resolve(pointName, key, handler);
-    }
-  }
-
-  /**
-   * 运行 pipeline 点。
-   */
-  async pipeline<T = JsonValue>(pointName: string, value: T): Promise<T> {
-    return this.hookRegistry.pipelineValue(pointName, value);
-  }
-
-  /**
-   * 运行 guard 点。
-   */
-  async guard<T = JsonValue>(pointName: string, value: T): Promise<void> {
-    return this.hookRegistry.guardValue(pointName, value);
-  }
-
-  /**
-   * 运行 effect 点。
-   */
-  async effect<T = JsonValue>(pointName: string, value: T): Promise<void> {
-    return this.hookRegistry.effectValue(pointName, value);
-  }
-
-  /**
-   * 运行 resolve 点。
-   */
-  async resolve<TInput = JsonValue, TOutput = JsonValue>(
-    pointName: string,
-    value: TInput,
-  ): Promise<TOutput> {
-    return this.hookRegistry.resolveValue<TInput, TOutput>(pointName, value);
-  }
-
-  /**
-   * 获取单个 plugin 定义。
-   */
-  get(pluginName: string): Plugin | null {
-    return this.plugins.get(String(pluginName || "").trim()) || null;
-  }
-
-  /**
-   * 列出全部 plugin 概览视图。
-   */
-  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",
-      }))
-      .sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  /**
-   * 检查 plugin 可用性。
-   */
-  async availability(pluginName: string): Promise<PluginAvailability> {
-    const plugin = this.get(pluginName);
-    if (!plugin) {
-      return {
-        enabled: false,
-        available: false,
-        reasons: [`Unknown plugin: ${pluginName}`],
-      };
-    }
-
-    if (plugin.availability) {
-      return await plugin.availability(this.contextResolver());
-    }
-
-    const context = this.contextResolver();
-    const enabled = isPluginEnabled({ plugin });
-
-    if (!enabled) {
-      return {
-        enabled: false,
-        available: false,
-        reasons: [`Plugin "${plugin.name}" is disabled`],
-      };
-    }
-    return {
-      enabled: true,
-      available: true,
-      reasons: [],
-    };
-  }
-
-  /**
-   * 运行 plugin action。
-   */
-  async runAction(params: {
-    plugin: string;
-    action: string;
-    payload?: JsonValue;
-  }): Promise<PluginActionResult<JsonValue>> {
-    const plugin = this.get(params.plugin);
-    if (!plugin) {
-      return {
-        success: false,
-        error: `Unknown plugin: ${params.plugin}`,
-        message: `Unknown plugin: ${params.plugin}`,
-      };
-    }
-
-    const actionName = String(params.action || "").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 = this.contextResolver();
-    const enabled = isPluginEnabled({ plugin });
-    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/Plugins.ts

@@ -1,39 +0,0 @@
-/**
- * 内建 Plugin 清单（单一事实源）。
- *
- * 关键点（中文）
- * - 统一维护全部内建 plugin，避免 CLI / agent / docs 各自硬编码。
- * - 同时提供统一注册入口，减少额外跳转层级。
- */
-
-import type { PluginRegistry } from "@/plugin/PluginRegistry.js";
-import type { Plugin } from "@/shared/types/Plugin.js";
-import { authPlugin } from "@/plugins/auth/Plugin.js";
-import { skillPlugin } from "@/plugins/skill/Plugin.js";
-import { webPlugin } from "@/plugins/web/Plugin.js";
-import { asrPlugin } from "@/plugins/asr/Plugin.js";
-import { ttsPlugin } from "@/plugins/tts/Plugin.js";
-import { workboardPlugin } from "@/plugins/workboard/Plugin.js";
-
-/**
- * 全部内建 Plugin。
- */
-export const PLUGINS: Plugin[] = [
-  authPlugin,
-  skillPlugin,
-  webPlugin,
-  asrPlugin,
-  ttsPlugin,
-  workboardPlugin,
-];
-
-/**
- * 注册全部内建插件体系对象。
- */
-export function registerBuiltinPlugins(params: {
-  pluginRegistry: PluginRegistry;
-}): void {
-  for (const plugin of PLUGINS) {
-    params.pluginRegistry.register(plugin);
-  }
-}

package/src/plugin/ProjectConfigStore.ts

@@ -1,58 +0,0 @@
-/**
- * Plugin 项目配置持久化工具。
- *
- * 关键点（中文）
- * - 新插件体系的用户配置统一写回项目 `downcity.json`。
- * - 这里只负责 `plugins` 配置域，避免把执行期合并态整包落盘。
- * - 这样既能保证重启后配置仍然生效，也能避免把 console 全局配置误写进项目文件。
- */
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
-
-type PersistableSections = {
-  /**
-   * 插件配置块（可选）。
-   */
-  plugins?: DowncityConfig["plugins"];
-};
-
-function getProjectDowncityJsonPath(projectRoot: string): string {
-  return path.join(path.resolve(projectRoot), "downcity.json");
-}
-
-async function readProjectDowncityConfig(projectRoot: string): Promise<DowncityConfig> {
-  const downcityJsonPath = getProjectDowncityJsonPath(projectRoot);
-  const raw = await fs.readFile(downcityJsonPath, "utf-8");
-  const parsed = JSON.parse(raw) as unknown;
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Invalid downcity.json: expected object (${downcityJsonPath})`);
-  }
-  return parsed as DowncityConfig;
-}
-
-/**
- * 将 plugins 配置块写回项目 `downcity.json`。
- */
-export async function persistProjectPluginConfig(params: {
-  /**
-   * 项目根目录。
-   */
-  projectRoot: string;
-  /**
-   * 待持久化的配置块。
-   */
-  sections: PersistableSections;
-}): Promise<string> {
-  const downcityJsonPath = getProjectDowncityJsonPath(params.projectRoot);
-  const current = await readProjectDowncityConfig(params.projectRoot);
-  const next: DowncityConfig = {
-    ...current,
-    ...(params.sections.plugins !== undefined
-      ? { plugins: params.sections.plugins }
-      : {}),
-  };
-  await fs.writeFile(downcityJsonPath, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
-  return downcityJsonPath;
-}