@downcity/agent 1.1.7 → 1.1.10

package/src/plugin/Catalog.ts

@@ -1,118 +0,0 @@
-/**
- * Plugin Catalog。
- *
- * 关键点（中文）
- * - 这里承载 console 侧的静态 plugin 元数据视图。
- * - 目标是把“控制面可见的 plugin 定义”从 agent 执行态里拆出来复用。
- * - 当前先服务 Console 与 `city plugin` CLI 的静态回退场景。
- */
-
-import { PLUGINS } from "@/plugin/Plugins.js";
-import { isPluginEnabled } from "@/plugin/Activation.js";
-import type {
-  Plugin,
-  PluginAvailability,
-  PluginView,
-} from "@/shared/types/Plugin.js";
-
-/**
- * 将 Plugin 定义转换成静态概览视图。
- */
-export function toStaticPluginView(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((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",
-  };
-}
-
-/**
- * 列出全部内建 plugin 定义。
- */
-export function listBuiltinPlugins(): Plugin[] {
-  return [...PLUGINS];
-}
-
-/**
- * 列出全部内建 plugin 的静态概览视图。
- */
-export function listStaticPluginViews(): PluginView[] {
-  return listBuiltinPlugins()
-    .map((plugin) => toStaticPluginView(plugin))
-    .sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * 按名称查找内建 plugin 定义。
- */
-export function findBuiltinPlugin(pluginName: string): Plugin | null {
-  const key = String(pluginName || "").trim();
-  if (!key) return null;
-  return listBuiltinPlugins().find((plugin) => plugin.name === key) || null;
-}
-
-/**
- * 按名称查找内建 plugin 的静态概览视图。
- */
-export function findStaticPluginView(
-  pluginName: string,
-): PluginView | null {
-  const plugin = findBuiltinPlugin(pluginName);
-  return plugin ? toStaticPluginView(plugin) : null;
-}
-
-/**
- * 构建静态 plugin 可用性视图。
- *
- * 关键点（中文）
- * - 这里表达的是“控制面视角下可见的 city 配置事实”，不是执行链路中的最终可用性。
- * - `enabled` 只对齐 city 级 plugin lifecycle，不再读取 agent 项目配置。
- * - `available` 仅在无需执行上下文即可明确判断为 false 时返回 false；否则静态层视为可用。
- */
-export function buildStaticPluginAvailability(params: {
-  pluginName: string;
-  agentError?: string;
-}): PluginAvailability {
-  const plugin = findBuiltinPlugin(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 in city config.`],
-    };
-  }
-
-  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/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/Lifecycle.ts

@@ -1,116 +0,0 @@
-/**
- * Plugin 生命周期配置模块。
- *
- * 关键点（中文）
- * - Plugin enable/disable 属于 city 级全局配置，不再写入 agent `downcity.json`。
- * - 当前实现把 lifecycle 配置存入 PlatformStore 的统一 JSON 设置。
- * - 默认策略：除显式关闭外，内建 plugin 视为启用。
- */
-
-import { PlatformStore } from "@/shared/utils/store/index.js";
-import type {
-  CityPluginLifecycleConfig,
-  CityPluginLifecycleItem,
-} from "@/shared/types/PluginLifecycle.js";
-
-const PLUGIN_LIFECYCLE_SETTING_KEY = "plugins.lifecycle";
-
-function normalizeLifecycleItem(input: unknown): CityPluginLifecycleItem | null {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
-  const record = input as Record<string, unknown>;
-  if (typeof record.enabled !== "boolean") return null;
-  const updatedAt = String(record.updatedAt || "").trim() || new Date().toISOString();
-  return {
-    enabled: record.enabled,
-    updatedAt,
-  };
-}
-
-function normalizeLifecycleConfig(input: unknown): CityPluginLifecycleConfig {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
-  const out: CityPluginLifecycleConfig = {};
-  for (const [pluginName, raw] of Object.entries(input as Record<string, unknown>)) {
-    const key = String(pluginName || "").trim();
-    if (!key) continue;
-    const item = normalizeLifecycleItem(raw);
-    if (!item) continue;
-    out[key] = item;
-  }
-  return out;
-}
-
-/**
- * 读取当前 city 级 plugin lifecycle 配置。
- */
-export function readCityPluginLifecycleConfig(): CityPluginLifecycleConfig {
-  const store = new PlatformStore();
-  try {
-    return normalizeLifecycleConfig(
-      store.getSecureSettingJsonSync<CityPluginLifecycleConfig>(
-        PLUGIN_LIFECYCLE_SETTING_KEY,
-      ),
-    );
-  } finally {
-    store.close();
-  }
-}
-
-/**
- * 写入完整 city 级 plugin lifecycle 配置。
- */
-export function writeCityPluginLifecycleConfig(
-  value: CityPluginLifecycleConfig,
-): CityPluginLifecycleConfig {
-  const normalized = normalizeLifecycleConfig(value);
-  const store = new PlatformStore();
-  try {
-    store.setSecureSettingJsonSync(PLUGIN_LIFECYCLE_SETTING_KEY, normalized);
-    return normalized;
-  } finally {
-    store.close();
-  }
-}
-
-/**
- * 读取单个 plugin 的 city 级 lifecycle 状态。
- */
-export function readCityPluginLifecycleItem(
-  pluginName: string,
-): CityPluginLifecycleItem | null {
-  const key = String(pluginName || "").trim();
-  if (!key) return null;
-  return readCityPluginLifecycleConfig()[key] || null;
-}
-
-/**
- * 读取单个 plugin 是否启用。
- *
- * 关键点（中文）
- * - 除显式关闭外，一律默认启用。
- */
-export function isCityPluginEnabled(pluginName: string): boolean {
-  const item = readCityPluginLifecycleItem(pluginName);
-  if (!item) return true;
-  return item.enabled === true;
-}
-
-/**
- * 设置单个 plugin 的 city 级启用态。
- */
-export function setCityPluginEnabled(
-  pluginName: string,
-  enabled: boolean,
-): CityPluginLifecycleConfig {
-  const key = String(pluginName || "").trim();
-  if (!key) {
-    throw new Error("pluginName is required");
-  }
-  const current = readCityPluginLifecycleConfig();
-  return writeCityPluginLifecycleConfig({
-    ...current,
-    [key]: {
-      enabled,
-      updatedAt: new Date().toISOString(),
-    },
-  });
-}

package/src/plugin/LocalExecution.ts

@@ -1,157 +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 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);
-
-  return {
-    cwd: rootPath,
-    rootPath,
-    logger: defaultLogger,
-    config,
-    env,
-    globalEnv,
-    paths: createAgentPathRuntime(rootPath),
-    pluginConfig: createAgentPluginConfigRuntime(rootPath),
-  };
-}
-
-/**
- * 列出本地内建 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 });
-  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 });
-  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),
-    };
-  }
-}