@downcity/agent 1.1.74 → 1.1.81

package/bin/types/plugin/ImagePlugin.js

@@ -0,0 +1,10 @@
+/**
+ * ImagePlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里仅定义 agent 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
+ * - 图片生成结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
+ * - 字段保持 JSON 可序列化，便于通过 plugin action 与 tool bridge 传递。
+ */
+export {};
+//# sourceMappingURL=ImagePlugin.js.map

package/bin/types/plugin/ImagePlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImagePlugin.js","sourceRoot":"","sources":["../../../src/types/plugin/ImagePlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

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

@@ -0,0 +1,119 @@
+/**
+ * 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>;
+};
+//# sourceMappingURL=PluginAction.d.ts.map

package/bin/types/plugin/PluginAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginAction.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginAction.ts"],"names":[],"mappings":"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"}

package/bin/types/plugin/PluginAction.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin action 类型。
+ *
+ * 关键点（中文）
+ * - action 是 plugin 对外暴露的显式能力。
+ * - CLI / HTTP 只是 action 的输入适配层，真正执行器统一走 `execute`。
+ */
+export {};
+//# sourceMappingURL=PluginAction.js.map

package/bin/types/plugin/PluginAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginAction.js","sourceRoot":"","sources":["../../../src/types/plugin/PluginAction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,80 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=PluginCommand.d.ts.map

package/bin/types/plugin/PluginCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginCommand.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginCommand.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,mBAAmB;IACnB,KAAK,EAAE,gBAAgB,CAAC;IACxB,8BAA8B;IAC9B,YAAY,EAAE,wBAAwB,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,KAAK,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,mBAAmB;IACnB,IAAI,CAAC,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,4BAA4B;IAC5B,OAAO,CAAC,CACN,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACvD"}

package/bin/types/plugin/PluginCommand.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin command 与 lifecycle 类型。
+ *
+ * 关键点（中文）
+ * - command 面向显式 CLI/control 调用。
+ * - lifecycle 面向 runtime 主动 start/stop 钩子。
+ */
+export {};
+//# sourceMappingURL=PluginCommand.js.map

package/bin/types/plugin/PluginCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginCommand.js","sourceRoot":"","sources":["../../../src/types/plugin/PluginCommand.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,57 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=PluginDefinition.d.ts.map

package/bin/types/plugin/PluginDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginDefinition.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACf,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,CAAC,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IAClD,+BAA+B;IAC/B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,+BAA+B;IAC/B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,qBAAqB;IACrB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,yBAAyB;IACzB,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,oBAAoB,GAAG,YAAY,KACzC,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACtD,4BAA4B;IAC5B,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC7B"}

package/bin/types/plugin/PluginDefinition.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin 顶层定义类型。
+ *
+ * 关键点（中文）
+ * - 这里只组合 plugin 的各类能力，不展开每个能力的细节。
+ * - 细节类型分散在 State / Command / Action / Runtime / Setup / HTTP 模块。
+ */
+export {};
+//# sourceMappingURL=PluginDefinition.js.map

package/bin/types/plugin/PluginDefinition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginDefinition.js","sourceRoot":"","sources":["../../../src/types/plugin/PluginDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,34 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=PluginHttp.d.ts.map

package/bin/types/plugin/PluginHttp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginHttp.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginHttp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qBAAqB;IACrB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE;QACf,oBAAoB;QACpB,GAAG,EAAE,IAAI,CAAC;QACV,mBAAmB;QACnB,UAAU,EAAE,MAAM,YAAY,CAAC;QAC/B,sBAAsB;QACtB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;CACV;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC"}

package/bin/types/plugin/PluginHttp.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin HTTP 注入类型。
+ *
+ * 关键点（中文）
+ * - plugin 只声明自己的路由与鉴权策略。
+ * - server 装配、代理和鉴权执行仍由宿主负责。
+ */
+export {};
+//# sourceMappingURL=PluginHttp.js.map

package/bin/types/plugin/PluginHttp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginHttp.js","sourceRoot":"","sources":["../../../src/types/plugin/PluginHttp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

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

@@ -0,0 +1,148 @@
+/**
+ * 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>;
+};
+//# sourceMappingURL=PluginRuntime.d.ts.map

package/bin/types/plugin/PluginRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginRuntime.d.ts","sourceRoot":"","sources":["../../../src/types/plugin/PluginRuntime.ts"],"names":[],"mappings":"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"}

package/bin/types/plugin/PluginRuntime.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin runtime 类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 Agent runtime 如何查看、调用、检查 plugin。
+ * - setup/usage UI 协议与 action 输入适配不放在这里。
+ */
+export {};
+//# sourceMappingURL=PluginRuntime.js.map

package/bin/types/plugin/PluginRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginRuntime.js","sourceRoot":"","sources":["../../../src/types/plugin/PluginRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}