@downcity/agent 1.1.74 → 1.1.79

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;
+}

package/src/types/plugin/PluginState.ts

@@ -0,0 +1,82 @@
+/**
+ * Plugin 状态类型。
+ *
+ * 关键点（中文）
+ * - 只描述 plugin 生命周期状态与控制结果。
+ * - 不包含 command/action/hook 等执行协议，避免状态类型被运行时细节污染。
+ */
+
+/**
+ * Plugin 运行状态。
+ *
+ * 说明（中文）
+ * - `starting` / `stopping` 仅用于生命周期过渡态。
+ * - `error` 表示最近一次 lifecycle / command / action 执行失败后留下的状态标记。
+ */
+export type PluginState =
+  | "running"
+  | "stopped"
+  | "starting"
+  | "stopping"
+  | "error";
+
+/**
+ * 单个 plugin 实例内部持有的状态记录。
+ */
+export interface PluginStateRecord {
+  /** 当前运行状态。 */
+  state: PluginState;
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 当前串行控制链。 */
+  chain: Promise<void>;
+}
+
+/**
+ * 单个 plugin 状态的对外快照。
+ */
+export interface PluginStateSnapshot {
+  /** plugin 名称。 */
+  name: string;
+  /** 当前运行状态。 */
+  state: PluginState;
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 是否支持主动生命周期。 */
+  supportsLifecycle: boolean;
+  /** 是否支持 command/action。 */
+  supportsCommand: boolean;
+}
+
+/**
+ * plugin 状态控制动作。
+ */
+export type PluginStateControlAction =
+  | "start"
+  | "stop"
+  | "restart"
+  | "status";
+
+/**
+ * plugin 状态控制结果。
+ */
+export interface PluginStateControlResult {
+  /** 控制动作是否成功。 */
+  success: boolean;
+  /** 成功或失败后返回的最新 plugin 快照。 */
+  plugin?: PluginStateSnapshot;
+  /** 失败时的错误信息。 */
+  error?: string;
+}