@downcity/agent 1.1.74 → 1.1.81

package/bin/plugin/types/Plugin.d.ts

@@ -1,847 +1,15 @@
 /**
- * Plugin 类型定义。
+ * Plugin 类型 facade。
  *
  * 关键点（中文）
- * - Plugin 现在同时承载两类定义：CLI actions 与 runtime hooks。
- * - CLI action 面向显式命令调用；hooks / resolves / system 面向 agent 运行时 plugin。
- * - Plugin 的依赖实现应内聚在插件内部，而不是挂成公共执行上下文能力。
+ * - 保留旧的 `@/plugin/types/Plugin.js` 导入路径。
+ * - 真实类型按职责拆到 `src/types/plugin/*`，避免单文件继续膨胀。
  */
-import type { Command } from "commander";
-import type { Context as HonoContext, Hono } from "hono";
-import type { AgentPathRuntime, AgentPluginConfigRuntime } from "../../types/runtime/host/AgentHost.js";
-import type { AgentContext, StructuredConfig } 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";
-import type { AuthRoutePolicy } from "../../types/runtime/auth/AuthRoute.js";
-/**
- * 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;
-}
-/**
- * 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 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 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;
-}
-/**
- * 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>;
-};
-/**
- * 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>;
-};
-/**
- * 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;
-}
-/**
- * Plugin HTTP 注入参数。
- *
- * 关键点（中文）
- * - plugin 只声明自己的路由与鉴权策略，不感知 server 装配细节。
- * - console 会复用相同路径策略保护代理请求，但不会重复注册路由本身。
- */
-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;
-}
-/**
- * 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;
-}
+export type { PluginState, PluginStateControlAction, PluginStateControlResult, PluginStateRecord, PluginStateSnapshot, } from "../../types/plugin/PluginState.js";
+export type { PluginCommandContext, PluginCommandParams, PluginCommandResult, PluginLifecycle, } from "../../types/plugin/PluginCommand.js";
+export type { PluginAction, PluginActionApi, PluginActionCommand, PluginActionCommandInput, PluginActionInvokeParams, PluginActionInvokePort, PluginActionInvokeResult, PluginActionResult, PluginActions, } from "../../types/plugin/PluginAction.js";
+export type { PluginAvailability, PluginConfigDefinition, PluginEffectHook, PluginGuardHook, PluginHooks, PluginPipelineHook, PluginPort, PluginResolveHook, PluginResolves, PluginView, } from "../../types/plugin/PluginRuntime.js";
+export type { PluginSetupDefinition, PluginSetupField, PluginSetupFieldOption, PluginUsageDefinition, PluginUsageField, PluginUsageFieldOption, } from "../../types/plugin/PluginSetup.js";
+export type { PluginHttpDefinition, PluginHttpRegistration, } from "../../types/plugin/PluginHttp.js";
+export type { Plugin } from "../../types/plugin/PluginDefinition.js";
 //# sourceMappingURL=Plugin.d.ts.map