@downcity/agent 1.1.74 → 1.1.81

package/src/types/plugin/PluginAction.ts

@@ -0,0 +1,133 @@
+/**
+ * Plugin action 类型。
+ *
+ * 关键点（中文）
+ * - action 是 plugin 对外暴露的显式能力。
+ * - CLI / HTTP 只是 action 的输入适配层，真正执行器统一走 `execute`。
+ */
+
+import type { Command } from "commander";
+import type { Context as HonoContext } from "hono";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * Plugin action 调用参数。
+ */
+export interface PluginActionInvokeParams {
+  /** 目标 plugin 名称。 */
+  plugin: string;
+  /** 目标 action 名称。 */
+  action: string;
+  /** 调用 payload（可选）。 */
+  payload?: JsonValue;
+}
+
+/**
+ * Plugin action 调用结果。
+ */
+export interface PluginActionInvokeResult {
+  /** 调用是否成功。 */
+  success: boolean;
+  /** 结构化返回数据（可选）。 */
+  data?: JsonValue;
+  /** 错误信息（可选）。 */
+  error?: string;
+}
+
+/**
+ * Plugin action 调用端口。
+ */
+export interface PluginActionInvokePort {
+  /** 调用指定 plugin action。 */
+  invoke(
+    params: PluginActionInvokeParams,
+  ): Promise<PluginActionInvokeResult>;
+}
+
+/**
+ * Plugin Action 执行结果。
+ */
+export interface PluginActionResult<R extends JsonValue = JsonValue> {
+  /** Action 是否成功。 */
+  success: boolean;
+  /** 返回数据（可选）。 */
+  data?: R;
+  /** 错误信息（可选）。 */
+  error?: string;
+  /** 人类可读消息（可选）。 */
+  message?: string;
+}
+
+/**
+ * Plugin Action 命令输入。
+ */
+export interface PluginActionCommandInput {
+  /** 位置参数列表。 */
+  args: string[];
+  /** 选项参数对象。 */
+  opts: Record<string, JsonValue>;
+}
+
+/**
+ * Plugin Action CLI 定义。
+ */
+export interface PluginActionCommand<P extends JsonValue = JsonValue> {
+  /** 命令说明。 */
+  description: string;
+  /** 额外 commander 配置（可选）。 */
+  configure?: (command: Command) => void;
+  /** 将 CLI 输入映射为 payload。 */
+  mapInput: (input: PluginActionCommandInput) => P | Promise<P>;
+}
+
+/**
+ * Plugin Action HTTP 定义。
+ */
+export interface PluginActionApi<P extends JsonValue = JsonValue> {
+  /** HTTP 方法。 */
+  method?: "GET" | "POST" | "PUT" | "DELETE";
+  /** HTTP 路径。 */
+  path?: string;
+  /** 将 HTTP 输入映射为 payload（可选）。 */
+  mapInput?: (ctx: HonoContext) => P | Promise<P>;
+}
+
+/**
+ * Plugin Action 定义。
+ */
+export interface PluginAction<
+  P extends JsonValue = JsonValue,
+  R extends JsonValue = JsonValue,
+> {
+  /**
+   * disabled 状态下是否仍允许执行。
+   *
+   * 说明（中文）
+   * - 用于 `on` / `status` / `models` / `configure` / `install` 这类 setup 相关 action。
+   * - 默认 false，避免 disabled plugin 绕过 registry 保护执行普通业务 action。
+   */
+  allowWhenDisabled?: boolean;
+  /** CLI 定义（可选）。 */
+  command?: PluginActionCommand<P>;
+  /** HTTP 定义（可选）。 */
+  api?: PluginActionApi<P>;
+  /** Action 执行器。 */
+  execute: (params: {
+    /** 当前执行上下文。 */
+    context: AgentContext;
+    /** 输入 payload。 */
+    payload: P;
+    /** 当前插件名称。 */
+    pluginName: string;
+    /** 当前 Action 名称。 */
+    actionName: string;
+  }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
+}
+
+/**
+ * Plugin Action 集合。
+ */
+export type PluginActions = {
+  [actionName: string]: PluginAction<JsonValue, JsonValue>;
+};

package/src/types/plugin/PluginCommand.ts

@@ -0,0 +1,89 @@
+/**
+ * Plugin command 与 lifecycle 类型。
+ *
+ * 关键点（中文）
+ * - command 面向显式 CLI/control 调用。
+ * - lifecycle 面向 runtime 主动 start/stop 钩子。
+ */
+
+import type {
+  AgentPathRuntime,
+  AgentPluginConfigRuntime,
+} from "@/types/agent/AgentRuntimeAssembly.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * Plugin 命令执行上下文。
+ *
+ * 关键点（中文）
+ * - 这里表达的是“CLI 命令执行 plugin 时真正需要的最小上下文”。
+ * - plugin 命令不应依赖 session、plugin invoke、agent runtime 等长期宿主对象。
+ * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
+ */
+export interface PluginCommandContext {
+  /** 当前命令工作目录。 */
+  cwd: string;
+  /** 当前项目根目录。 */
+  rootPath: string;
+  /** 当前统一日志器。 */
+  logger: Logger;
+  /** 当前解析后的项目配置。 */
+  config: DowncityConfig;
+  /**
+   * 当前项目环境变量快照。
+   *
+   * 关键点（中文）
+   * - 这里约定为宿主已经整理好的最终可见 env 视图。
+   * - plugin 不再区分 global env 与 agent env，避免上下文语义膨胀。
+   */
+  env: Record<string, string>;
+  /** 当前可见的路径能力集合。 */
+  paths: AgentPathRuntime;
+  /** 当前可见的 plugin 配置持久化能力集合。 */
+  pluginConfig: AgentPluginConfigRuntime;
+}
+
+/**
+ * Plugin 非 action 命令执行参数。
+ */
+export interface PluginCommandParams {
+  /** 当前统一执行上下文。 */
+  context: AgentContext;
+  /** 当前命令名称。 */
+  command: string;
+  /** 命令附带 payload（可选）。 */
+  payload?: JsonValue;
+}
+
+/**
+ * Plugin 非 action 命令执行结果。
+ */
+export interface PluginCommandResult {
+  /** 本次命令是否成功。 */
+  success: boolean;
+  /** 人类可读消息。 */
+  message?: string;
+  /** 结构化返回数据。 */
+  data?: JsonValue;
+}
+
+/**
+ * Plugin 生命周期兼容定义。
+ *
+ * 关键点（中文）
+ * - 这是从旧运行生命周期过渡过来的兼容层。
+ * - 新代码优先直接实现 `start/stop/command`。
+ */
+export interface PluginLifecycle {
+  /** plugin 启动钩子。 */
+  start?(context: AgentContext): Promise<void> | void;
+  /** plugin 停止钩子。 */
+  stop?(context: AgentContext): Promise<void> | void;
+  /** plugin 非 action 命令钩子。 */
+  command?(
+    params: PluginCommandParams,
+  ): Promise<PluginCommandResult> | PluginCommandResult;
+}

package/src/types/plugin/PluginDefinition.ts

@@ -0,0 +1,74 @@
+/**
+ * Plugin 顶层定义类型。
+ *
+ * 关键点（中文）
+ * - 这里只组合 plugin 的各类能力，不展开每个能力的细节。
+ * - 细节类型分散在 State / Command / Action / Runtime / Setup / HTTP 模块。
+ */
+
+import type {
+  AgentContext,
+  StructuredConfig,
+} from "@/types/runtime/agent/AgentContext.js";
+import type { PluginActions } from "@/types/plugin/PluginAction.js";
+import type {
+  PluginAvailability,
+  PluginConfigDefinition,
+  PluginHooks,
+  PluginResolves,
+} from "@/types/plugin/PluginRuntime.js";
+import type {
+  PluginCommandContext,
+  PluginLifecycle,
+} from "@/types/plugin/PluginCommand.js";
+import type {
+  PluginSetupDefinition,
+  PluginUsageDefinition,
+} from "@/types/plugin/PluginSetup.js";
+import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
+
+/**
+ * Plugin 定义。
+ */
+export interface Plugin {
+  /** Plugin 稳定名称。 */
+  name: string;
+  /** Plugin 面向用户界面的展示标题。 */
+  title: string;
+  /** Plugin 面向人类的用途说明。 */
+  description: string;
+  /** Plugin 配置定义（可选）。 */
+  config?: PluginConfigDefinition<StructuredConfig>;
+  /** Plugin 显式 Action 集合（可选）。 */
+  actions?: PluginActions;
+  /**
+   * Plugin setup 定义（可选）。
+   *
+   * 说明（中文）
+   * - 这是 Console 面向用户的安装/配置协议。
+   * - plugin 内部仍可复用 asset/helper，但 UI 只读取这层抽象。
+   */
+  setup?: PluginSetupDefinition;
+  /**
+   * Plugin usage 定义（可选）。
+   *
+   * 说明（中文）
+   * - 这是 agent 侧如何使用该 plugin 的配置协议。
+   * - 与 setup 不同，这里不负责依赖安装，只负责行为选择与运行参数。
+   */
+  usage?: PluginUsageDefinition;
+  /** Plugin Hook 集合（可选）。 */
+  hooks?: PluginHooks;
+  /** Plugin resolve 点集合（可选）。 */
+  resolves?: PluginResolves;
+  /** Plugin system 文本构建器（可选）。 */
+  system?: (context: AgentContext) => string | Promise<string>;
+  /** 旧生命周期兼容定义（可选）。 */
+  lifecycle?: PluginLifecycle;
+  /** Plugin 可用性检查器（可选）。 */
+  availability?: (
+    context: PluginCommandContext | AgentContext,
+  ) => Promise<PluginAvailability> | PluginAvailability;
+  /** Plugin HTTP 注入定义（可选）。 */
+  http?: PluginHttpDefinition;
+}

package/src/types/plugin/PluginHttp.ts

@@ -0,0 +1,36 @@
+/**
+ * Plugin HTTP 注入类型。
+ *
+ * 关键点（中文）
+ * - plugin 只声明自己的路由与鉴权策略。
+ * - server 装配、代理和鉴权执行仍由宿主负责。
+ */
+
+import type { Hono } from "hono";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
+
+/**
+ * Plugin HTTP 注入参数。
+ */
+export interface PluginHttpRegistration {
+  /** 该组路由对应的鉴权策略列表。 */
+  authPolicies?: AuthRoutePolicy[];
+  /** 向 runtime Hono 应用注册路由。 */
+  register(params: {
+    /** 当前 Hono 应用实例。 */
+    app: Hono;
+    /** 获取当前统一执行上下文。 */
+    getContext: () => AgentContext;
+    /** 当前 plugin 稳定名称。 */
+    pluginName: string;
+  }): void;
+}
+
+/**
+ * Plugin HTTP 注入定义。
+ */
+export interface PluginHttpDefinition {
+  /** server HTTP 路由注入（可选）。 */
+  server?: PluginHttpRegistration;
+}

package/src/types/plugin/PluginRuntime.ts

@@ -0,0 +1,169 @@
+/**
+ * Plugin runtime 类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 Agent runtime 如何查看、调用、检查 plugin。
+ * - setup/usage UI 协议与 action 输入适配不放在这里。
+ */
+
+import type {
+  AgentContext,
+  StructuredConfig,
+} from "@/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
+
+/**
+ * Plugin 概览视图。
+ */
+export interface PluginView {
+  /** Plugin 稳定名称。 */
+  name: string;
+  /** Plugin 面向用户界面的展示标题。 */
+  title: string;
+  /** Plugin 面向人类的用途说明。 */
+  description: string;
+  /** Plugin Action 名称列表。 */
+  actions: string[];
+  /** Plugin pipeline 点名称列表。 */
+  pipelines: string[];
+  /** Plugin guard 点名称列表。 */
+  guards: string[];
+  /** Plugin effect 点名称列表。 */
+  effects: string[];
+  /** Plugin resolve 点名称列表。 */
+  resolves: string[];
+  /** 是否声明了 system 注入。 */
+  hasSystem: boolean;
+  /** 是否声明了 availability 检查。 */
+  hasAvailability: boolean;
+}
+
+/**
+ * Plugin 可用性结果。
+ */
+export interface PluginAvailability {
+  /** Plugin 是否启用。 */
+  enabled: boolean;
+  /** Plugin 当前是否可用。 */
+  available: boolean;
+  /** 不可用原因列表。 */
+  reasons: string[];
+}
+
+/**
+ * Plugin 调用端口。
+ */
+export interface PluginPort {
+  /** 列出全部已注册 plugin。 */
+  list(): PluginView[];
+  /** 检查指定 plugin 可用性。 */
+  availability(pluginName: string): Promise<PluginAvailability>;
+  /** 运行指定 plugin action。 */
+  runAction(params: {
+    /** Plugin 名称。 */
+    plugin: string;
+    /** Action 名称。 */
+    action: string;
+    /** Action Payload（可选）。 */
+    payload?: JsonValue;
+  }): Promise<PluginActionResult<JsonValue>>;
+  /** 运行 pipeline 点，按顺序链式变换值。 */
+  pipeline<T = JsonValue>(pointName: string, value: T): Promise<T>;
+  /** 运行 guard 点；任一插件抛错即终止。 */
+  guard<T = JsonValue>(pointName: string, value: T): Promise<void>;
+  /** 运行 effect 点；只执行副作用。 */
+  effect<T = JsonValue>(pointName: string, value: T): Promise<void>;
+  /** 运行 resolve 点；要求存在且仅存在一个处理器。 */
+  resolve<TInput = JsonValue, TOutput = JsonValue>(
+    pointName: string,
+    value: TInput,
+  ): Promise<TOutput>;
+}
+
+/**
+ * Plugin 配置定义。
+ */
+export interface PluginConfigDefinition<T extends StructuredConfig = StructuredConfig> {
+  /** Plugin 稳定名称。 */
+  plugin: string;
+  /** 配置作用域。 */
+  scope: "global" | "project";
+  /** 默认配置值。 */
+  defaultValue: T;
+}
+
+/**
+ * Plugin pipeline 处理器。
+ */
+export type PluginPipelineHook<
+  TValue extends JsonValue = JsonValue,
+> = (params: {
+  /** 当前执行上下文。 */
+  context: AgentContext;
+  /** 当前值。 */
+  value: TValue;
+  /** 当前插件名称。 */
+  plugin: string;
+}) => Promise<TValue> | TValue;
+
+/**
+ * Plugin guard 处理器。
+ *
+ * 关键点（中文）
+ * - 不返回结果；若需阻断流程，直接抛错。
+ */
+export type PluginGuardHook<TValue extends JsonValue = JsonValue> = (params: {
+  /** 当前执行上下文。 */
+  context: AgentContext;
+  /** 当前值。 */
+  value: TValue;
+  /** 当前插件名称。 */
+  plugin: string;
+}) => Promise<void> | void;
+
+/**
+ * Plugin effect 处理器。
+ */
+export type PluginEffectHook<TValue extends JsonValue = JsonValue> = (params: {
+  /** 当前执行上下文。 */
+  context: AgentContext;
+  /** 当前值。 */
+  value: TValue;
+  /** 当前插件名称。 */
+  plugin: string;
+}) => Promise<void> | void;
+
+/**
+ * Plugin resolve 处理器。
+ */
+export type PluginResolveHook<
+  TInput extends JsonValue = JsonValue,
+  TOutput extends JsonValue = JsonValue,
+> = (params: {
+  /** 当前执行上下文。 */
+  context: AgentContext;
+  /** 当前输入值。 */
+  value: TInput;
+  /** 当前插件名称。 */
+  plugin: string;
+}) => Promise<TOutput> | TOutput;
+
+/**
+ * Plugin Hook 定义集合。
+ */
+export interface PluginHooks {
+  /** pipeline 点映射。 */
+  pipeline?: Record<string, PluginPipelineHook<JsonValue>[]>;
+  /** guard 点映射。 */
+  guard?: Record<string, PluginGuardHook<JsonValue>[]>;
+  /** effect 点映射。 */
+  effect?: Record<string, PluginEffectHook<JsonValue>[]>;
+}
+
+/**
+ * Plugin resolve 点集合。
+ */
+export type PluginResolves = {
+  [pointName: string]: PluginResolveHook<JsonValue, JsonValue>;
+};

package/src/types/plugin/PluginSetup.ts

@@ -0,0 +1,138 @@
+/**
+ * Plugin setup / usage UI 协议类型。
+ *
+ * 关键点（中文）
+ * - setup 面向安装与配置。
+ * - usage 面向 agent 使用 plugin 时的行为参数。
+ */
+
+/**
+ * Plugin setup 字段选项。
+ */
+export interface PluginSetupFieldOption {
+  /** 选项展示标签。 */
+  label: string;
+  /** 选项实际值。 */
+  value: string;
+  /** 选项补充说明（可选）。 */
+  hint?: string;
+}
+
+/**
+ * Plugin setup 字段定义。
+ */
+export interface PluginSetupField {
+  /** 字段稳定键。 */
+  key: string;
+  /** 字段展示标签。 */
+  label: string;
+  /**
+   * 字段类型。
+   *
+   * 说明（中文）
+   * - 当前阶段只允许 `select` 与 `checkbox`，避免退回到大量自由输入。
+   */
+  type: "select" | "checkbox";
+  /** 是否必填。 */
+  required?: boolean;
+  /** 静态选项列表（可选）。 */
+  options?: PluginSetupFieldOption[];
+  /**
+   * 动态选项来源 action（可选）。
+   *
+   * 说明（中文）
+   * - 若存在，则 Console 打开 setup 弹窗时会先调用该 action 拉取下拉选项。
+   */
+  sourceAction?: string;
+}
+
+/**
+ * Plugin setup 定义。
+ */
+export interface PluginSetupDefinition {
+  /**
+   * setup 模式。
+   *
+   * 说明（中文）
+   * - `install`：只执行依赖安装。
+   * - `configure`：只写入配置。
+   * - `install-configure`：安装与配置一体化。
+   */
+  mode: "install" | "configure" | "install-configure";
+  /** setup 面板标题。 */
+  title: string;
+  /** setup 面板说明（可选）。 */
+  description?: string;
+  /** setup 字段列表。 */
+  fields: PluginSetupField[];
+  /** 主动作 action 名称。 */
+  primaryAction: string;
+  /** 状态同步 action 名称（可选）。 */
+  statusAction?: string;
+}
+
+/**
+ * Plugin usage 字段选项。
+ */
+export interface PluginUsageFieldOption {
+  /** 选项展示标签。 */
+  label: string;
+  /** 选项实际值。 */
+  value: string;
+  /** 选项补充说明（可选）。 */
+  description?: string;
+}
+
+/**
+ * Plugin usage 字段定义。
+ */
+export interface PluginUsageField {
+  /** 字段稳定键。 */
+  key: string;
+  /** 字段展示标签。 */
+  label: string;
+  /**
+   * 字段类型。
+   *
+   * 说明（中文）
+   * - `usage` 面向 agent 如何使用 plugin，因此允许更丰富的配置类型。
+   */
+  type: "string" | "secret" | "boolean" | "select" | "number";
+  /** 字段占位文案（可选）。 */
+  placeholder?: string;
+  /** 字段说明（可选）。 */
+  description?: string;
+  /** 是否必填。 */
+  required?: boolean;
+  /** 字段是否禁用。 */
+  disabled?: boolean;
+  /** 布尔字段为 true 时的标签（可选）。 */
+  trueLabel?: string;
+  /** 布尔字段为 false 时的标签（可选）。 */
+  falseLabel?: string;
+  /** 静态选项列表（可选）。 */
+  options?: PluginUsageFieldOption[];
+  /**
+   * 动态选项来源 action（可选）。
+   *
+   * 说明（中文）
+   * - Console 打开 usage 面板时会先调用该 action 同步下拉选项。
+   */
+  sourceAction?: string;
+}
+
+/**
+ * Plugin usage 定义。
+ */
+export interface PluginUsageDefinition {
+  /** usage 面板标题。 */
+  title: string;
+  /** usage 面板说明（可选）。 */
+  description?: string;
+  /** agent 使用该 plugin 时可配置的字段列表。 */
+  fields: PluginUsageField[];
+  /** 保存 usage 配置时调用的 action。 */
+  saveAction: string;
+  /** 读取当前 usage 快照时调用的 action（可选）。 */
+  statusAction?: string;
+}