@downcity/agent 1.1.287 → 1.1.310

package/bin/plugin/core/PluginRegistry.d.ts

@@ -10,10 +10,12 @@ import type { Plugin } from "../../types/plugin/PluginDefinition.js";
 import type { PluginActionResult } from "../../types/plugin/PluginAction.js";
 import type { AgentPlugins, AgentPluginExecutionRuntime, PluginAvailability, PluginReadView, PluginView } from "../../types/plugin/PluginRuntime.js";
 import type { AgentSessionSystemBlock } from "../../types/agent/SessionTypes.js";
-import type { AgentContext } from "../../agent/AgentContext.js";
+import type { PluginContext } from "../../types/plugin/PluginContext.js";
 import type { JsonValue } from "../../types/common/Json.js";
 import type { PluginSnapshot } from "../../types/plugin/PluginState.js";
-import type { SessionRunContext } from "../../types/executor/SessionRunContext.js";
+import type { PluginExecutionContext } from "../../types/plugin/PluginExecutionContext.js";
+import type { Tool } from "ai";
+import type { PluginRegistrySubscriber, PluginRegistryUnsubscribe } from "../../types/plugin/PluginRegistry.js";
 /**
  * PluginRegistry：Agent plugin 注册、卸载与调用实现。
  */
@@ -22,22 +24,29 @@ export declare class PluginRegistry implements AgentPlugins {
     private readonly hookRegistry;
     private readonly records;
     private readonly retired_records;
-    private change_listener?;
+    /** Plugin 配置变化订阅器。 */
+    private readonly change_subscribers;
     constructor(plugins?: Plugin[]);
     /**
-     * 绑定当前 Registry 所属的唯一 AgentContext。
+     * 绑定当前 Registry 所属的唯一 PluginContext。
      *
      * 关键点（中文）
      * - 初始 Plugin 可以在 Context 创建前同步挂载。
      * - lifecycle、action、hook 首次执行前必须完成绑定。
      */
-    bind_context(context: AgentContext): void;
-    /** 返回已经绑定的 AgentContext。 */
+    bind_context(context: PluginContext): void;
+    /** 返回已经绑定的 PluginContext。 */
     private require_context;
+    /** 订阅 Plugin 配置的后续变化。 */
+    subscribe_change(subscriber: PluginRegistrySubscriber): PluginRegistryUnsubscribe;
     /**
-     * 设置 Agent 内部配置修改监听器。
+     * 返回当前 Registry 向 Agent 提供的 Plugin Tools。
+     *
+     * 关键点（中文）
+     * - 没有任何 Action 时不暴露空壳 Tool。
+     * - Tool 闭包绑定当前 Registry，动态 Plugin 变化无需重建 bridge。
      */
-    set_change_listener(listener: PluginRegistry["change_listener"]): void;
+    tools(): Record<string, Tool>;
     /**
      * 注册单个 plugin。
      *
@@ -51,7 +60,7 @@ export declare class PluginRegistry implements AgentPlugins {
      *
      * 说明（中文）
      * - 仅供 Agent 构造期使用，避免构造函数里 await。
-     * - 后续 `startAll()` 会统一启动这些初始 plugin。
+     * - 后续 `start_all()` 会统一启动这些初始 plugin。
      */
     mount(plugin: Plugin): PluginSnapshot;
     /**
@@ -62,27 +71,29 @@ export declare class PluginRegistry implements AgentPlugins {
      * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
      * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
      */
-    unregister(pluginName: string): Promise<boolean>;
+    unregister(plugin_name: string): Promise<boolean>;
+    /** 将 Plugin 配置变化发布给 Agent 等持有者。 */
+    private publish_change;
     /**
      * 启动全部已挂载 plugin。
      */
-    startAll(): Promise<PluginSnapshot[]>;
+    start_all(): Promise<PluginSnapshot[]>;
     /**
      * 卸载全部 plugin。
      */
-    unregisterAll(): Promise<void>;
+    unregister_all(): Promise<void>;
     /**
      * 判断 plugin 是否已注册且 ready。
      */
-    isReady(pluginName: string): boolean;
+    is_ready(plugin_name: string): boolean;
     /**
      * 读取单个 plugin 快照。
      */
-    status(pluginName: string): PluginSnapshot | null;
+    status(plugin_name: string): PluginSnapshot | null;
     /**
      * 判断 plugin 是否已注册。
      */
-    has(pluginName: string): boolean;
+    has(plugin_name: string): boolean;
     private register_hooks;
     private unregister_hooks;
     private start_record;
@@ -90,23 +101,23 @@ export declare class PluginRegistry implements AgentPlugins {
     /**
      * 运行 pipeline 点。
      */
-    pipeline<T = JsonValue>(pointName: string, value: T): Promise<T>;
+    pipeline<T = JsonValue>(point_name: string, value: T): Promise<T>;
     /**
      * 运行 guard 点。
      */
-    guard<T = JsonValue>(pointName: string, value: T): Promise<void>;
+    guard<T = JsonValue>(point_name: string, value: T): Promise<void>;
     /**
      * 运行 effect 点。
      */
-    effect<T = JsonValue>(pointName: string, value: T): Promise<void>;
+    effect<T = JsonValue>(point_name: string, value: T): Promise<void>;
     /**
      * 运行 resolve 点。
      */
-    resolve<TInput = JsonValue, TOutput = JsonValue>(pointName: string, value: TInput): Promise<TOutput>;
+    resolve<TInput = JsonValue, TOutput = JsonValue>(point_name: string, value: TInput): Promise<TOutput>;
     /**
      * 获取单个 plugin 定义。
      */
-    get(pluginName: string): Plugin | null;
+    get(plugin_name: string): Plugin | null;
     /**
      * 列出全部 plugin 概览视图。
      */
@@ -135,7 +146,7 @@ export declare class PluginRegistry implements AgentPlugins {
     /**
      * 检查 plugin 可用性。
      */
-    availability(pluginName: string): Promise<PluginAvailability>;
+    availability(plugin_name: string): Promise<PluginAvailability>;
     /**
      * 按 action schema 校验 payload。
      */
@@ -143,11 +154,11 @@ export declare class PluginRegistry implements AgentPlugins {
     /**
      * 运行 plugin action。
      */
-    runAction(params: {
+    run_action(params: {
         plugin: string;
         action: string;
         payload?: JsonValue;
-        run_context?: SessionRunContext;
+        execution_context?: PluginExecutionContext;
     }): Promise<PluginActionResult<JsonValue>>;
     /**
      * 从指定记录视图运行 plugin action。
@@ -156,7 +167,7 @@ export declare class PluginRegistry implements AgentPlugins {
     /**
      * 读取当前生效的 plugin system blocks。
      */
-    systemBlocks(run_context?: SessionRunContext): Promise<AgentSessionSystemBlock[]>;
+    system_blocks(execution_context?: PluginExecutionContext): Promise<AgentSessionSystemBlock[]>;
     /**
      * 从指定记录视图解析 plugin system blocks。
      */

package/bin/plugin/core/PluginRegistry.d.ts.map

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

package/bin/plugin/core/PluginRegistry.js

@@ -6,8 +6,9 @@
  * - 注册时自动启动 plugin lifecycle；卸载时自动停止 plugin lifecycle。
  * - action、system、hook、resolve 都统一以“已注册且 ready”为生效边界。
  */
-import { toPluginView } from "../../plugin/core/PluginCatalog.js";
+import { to_plugin_view } from "../../plugin/core/PluginCatalog.js";
 import { HookRegistry } from "../../plugin/core/HookRegistry.js";
+import { create_plugin_tools } from "../../plugin/tool/PluginTools.js";
 function now_ms() {
     return Date.now();
 }
@@ -65,18 +66,19 @@ export class PluginRegistry {
     hookRegistry;
     records = new Map();
     retired_records = new Set();
-    change_listener;
+    /** Plugin 配置变化订阅器。 */
+    change_subscribers = new Set();
     constructor(plugins = []) {
         this.hookRegistry = new HookRegistry({
             get_context: () => this.require_context(),
-            is_plugin_ready: (plugin_name) => this.isReady(plugin_name),
+            is_plugin_ready: (plugin_name) => this.is_ready(plugin_name),
         });
         for (const plugin of plugins) {
             this.mount(plugin);
         }
     }
     /**
-     * 绑定当前 Registry 所属的唯一 AgentContext。
+     * 绑定当前 Registry 所属的唯一 PluginContext。
      *
      * 关键点（中文）
      * - 初始 Plugin 可以在 Context 创建前同步挂载。
@@ -88,18 +90,31 @@ export class PluginRegistry {
         }
         this.context = context;
     }
-    /** 返回已经绑定的 AgentContext。 */
+    /** 返回已经绑定的 PluginContext。 */
     require_context() {
         if (!this.context) {
             throw new Error("PluginRegistry context is not bound");
         }
         return this.context;
     }
+    /** 订阅 Plugin 配置的后续变化。 */
+    subscribe_change(subscriber) {
+        this.change_subscribers.add(subscriber);
+        return () => {
+            this.change_subscribers.delete(subscriber);
+        };
+    }
     /**
-     * 设置 Agent 内部配置修改监听器。
+     * 返回当前 Registry 向 Agent 提供的 Plugin Tools。
+     *
+     * 关键点（中文）
+     * - 没有任何 Action 时不暴露空壳 Tool。
+     * - Tool 闭包绑定当前 Registry，动态 Plugin 变化无需重建 bridge。
      */
-    set_change_listener(listener) {
-        this.change_listener = listener;
+    tools() {
+        if (!this.list().some((plugin) => plugin.actions.length > 0))
+            return {};
+        return { ...create_plugin_tools({ plugins: this }) };
     }
     /**
      * 注册单个 plugin。
@@ -121,7 +136,7 @@ export class PluginRegistry {
         this.register_hooks(plugin);
         try {
             await this.start_record(record);
-            this.change_listener?.({ type: "register", plugin_name: key });
+            this.publish_change({ type: "register", plugin_name: key });
             return to_plugin_snapshot(record);
         }
         catch (error) {
@@ -135,7 +150,7 @@ export class PluginRegistry {
      *
      * 说明（中文）
      * - 仅供 Agent 构造期使用，避免构造函数里 await。
-     * - 后续 `startAll()` 会统一启动这些初始 plugin。
+     * - 后续 `start_all()` 会统一启动这些初始 plugin。
      */
     mount(plugin) {
         const key = normalize_plugin_name(plugin.name);
@@ -158,8 +173,8 @@ export class PluginRegistry {
      * - lifecycle.stop 等当前活跃 Session step 的 execution lease 全部释放后执行。
      * - 该方法返回配置修改结果，不等待仍在运行的 step 结束。
      */
-    async unregister(pluginName) {
-        const key = normalize_plugin_name(pluginName);
+    async unregister(plugin_name) {
+        const key = normalize_plugin_name(plugin_name);
         if (!key)
             return false;
         const record = this.records.get(key);
@@ -168,13 +183,24 @@ export class PluginRegistry {
         this.unregister_hooks(key);
         this.records.delete(key);
         this.retire_record(record);
-        this.change_listener?.({ type: "unregister", plugin_name: key });
+        this.publish_change({ type: "unregister", plugin_name: key });
         return true;
     }
+    /** 将 Plugin 配置变化发布给 Agent 等持有者。 */
+    publish_change(change) {
+        for (const subscriber of this.change_subscribers) {
+            try {
+                subscriber(change);
+            }
+            catch {
+                // 观察者失败不能回滚已经完成的 Plugin 配置修改。
+            }
+        }
+    }
     /**
      * 启动全部已挂载 plugin。
      */
-    async startAll() {
+    async start_all() {
         const snapshots = [];
         for (const record of this.records.values()) {
             try {
@@ -190,7 +216,7 @@ export class PluginRegistry {
     /**
      * 卸载全部 plugin。
      */
-    async unregisterAll() {
+    async unregister_all() {
         for (const name of Array.from(this.records.keys())) {
             await this.unregister(name);
         }
@@ -202,22 +228,22 @@ export class PluginRegistry {
     /**
      * 判断 plugin 是否已注册且 ready。
      */
-    isReady(pluginName) {
-        const record = this.records.get(normalize_plugin_name(pluginName));
+    is_ready(plugin_name) {
+        const record = this.records.get(normalize_plugin_name(plugin_name));
         return Boolean(record && record.state === "ready");
     }
     /**
      * 读取单个 plugin 快照。
      */
-    status(pluginName) {
-        const record = this.records.get(normalize_plugin_name(pluginName));
+    status(plugin_name) {
+        const record = this.records.get(normalize_plugin_name(plugin_name));
         return record ? to_plugin_snapshot(record) : null;
     }
     /**
      * 判断 plugin 是否已注册。
      */
-    has(pluginName) {
-        return this.records.has(normalize_plugin_name(pluginName));
+    has(plugin_name) {
+        return this.records.has(normalize_plugin_name(plugin_name));
     }
     register_hooks(plugin) {
         const key = normalize_plugin_name(plugin.name);
@@ -236,12 +262,12 @@ export class PluginRegistry {
                 this.hookRegistry.effect(hookName, key, handler);
             }
         }
-        for (const [pointName, handler] of Object.entries(plugin.resolves || {})) {
-            this.hookRegistry.resolve(pointName, key, handler);
+        for (const [point_name, handler] of Object.entries(plugin.resolves || {})) {
+            this.hookRegistry.resolve(point_name, key, handler);
         }
     }
-    unregister_hooks(pluginName) {
-        this.hookRegistry.unregisterPlugin(pluginName);
+    unregister_hooks(plugin_name) {
+        this.hookRegistry.unregister_plugin(plugin_name);
     }
     async start_record(record) {
         if (record.lifecycle_started) {
@@ -280,39 +306,39 @@ export class PluginRegistry {
     /**
      * 运行 pipeline 点。
      */
-    async pipeline(pointName, value) {
-        return this.hookRegistry.pipelineValue(pointName, value);
+    async pipeline(point_name, value) {
+        return this.hookRegistry.pipelineValue(point_name, value);
     }
     /**
      * 运行 guard 点。
      */
-    async guard(pointName, value) {
-        return this.hookRegistry.guardValue(pointName, value);
+    async guard(point_name, value) {
+        return this.hookRegistry.guardValue(point_name, value);
     }
     /**
      * 运行 effect 点。
      */
-    async effect(pointName, value) {
-        return this.hookRegistry.effectValue(pointName, value);
+    async effect(point_name, value) {
+        return this.hookRegistry.effectValue(point_name, value);
     }
     /**
      * 运行 resolve 点。
      */
-    async resolve(pointName, value) {
-        return this.hookRegistry.resolveValue(pointName, value);
+    async resolve(point_name, value) {
+        return this.hookRegistry.resolveValue(point_name, value);
     }
     /**
      * 获取单个 plugin 定义。
      */
-    get(pluginName) {
-        return this.records.get(normalize_plugin_name(pluginName))?.plugin || null;
+    get(plugin_name) {
+        return this.records.get(normalize_plugin_name(plugin_name))?.plugin || null;
     }
     /**
      * 列出全部 plugin 概览视图。
      */
     list() {
         return Array.from(this.records.values())
-            .map((record) => toPluginView(record.plugin))
+            .map((record) => to_plugin_view(record.plugin))
             .sort((a, b) => a.name.localeCompare(b.name));
     }
     /**
@@ -326,9 +352,9 @@ export class PluginRegistry {
     /**
      * 读取 action metadata。
      */
-    readAction(actionName, action) {
+    readAction(action_name, action) {
         return {
-            name: actionName,
+            name: action_name,
             description: String(action.description || "").trim(),
             has_input_schema: Boolean(action.input_schema),
             ...(action.input_schema?.json_schema
@@ -349,24 +375,24 @@ export class PluginRegistry {
      * 从指定记录视图读取 plugin/action metadata。
      */
     read_from_records(records, params) {
-        const pluginName = normalize_plugin_name(params.plugin || "");
-        if (!pluginName) {
+        const plugin_name = normalize_plugin_name(params.plugin || "");
+        if (!plugin_name) {
             return {
                 plugins: Array.from(records.values())
-                    .map((record) => toPluginView(record.plugin))
+                    .map((record) => to_plugin_view(record.plugin))
                     .sort((left, right) => left.name.localeCompare(right.name)),
             };
         }
-        const plugin = records.get(pluginName)?.plugin || null;
+        const plugin = records.get(plugin_name)?.plugin || null;
         if (!plugin) {
-            throw new Error(`Unknown plugin: ${pluginName}`);
+            throw new Error(`Unknown plugin: ${plugin_name}`);
         }
-        const actionName = normalize_plugin_name(params.action || "");
-        if (actionName && !plugin.actions?.[actionName]) {
-            throw new Error(`Unknown action: ${pluginName}.${actionName}`);
+        const action_name = normalize_plugin_name(params.action || "");
+        if (action_name && !plugin.actions?.[action_name]) {
+            throw new Error(`Unknown action: ${plugin_name}.${action_name}`);
         }
         const actions = Object.entries(plugin.actions || {})
-            .filter(([name]) => !actionName || name === actionName)
+            .filter(([name]) => !action_name || name === action_name)
             .sort(([left], [right]) => left.localeCompare(right))
             .map(([name, action]) => this.readAction(name, action));
         return {
@@ -379,14 +405,14 @@ export class PluginRegistry {
     /**
      * 检查 plugin 可用性。
      */
-    async availability(pluginName) {
-        const key = normalize_plugin_name(pluginName);
+    async availability(plugin_name) {
+        const key = normalize_plugin_name(plugin_name);
         const record = this.records.get(key);
         if (!record) {
             return {
                 enabled: false,
                 available: false,
-                reasons: [`Unknown plugin: ${pluginName}`],
+                reasons: [`Unknown plugin: ${plugin_name}`],
             };
         }
         if (record.state !== "ready") {
@@ -418,14 +444,14 @@ export class PluginRegistry {
         }
         return {
             success: false,
-            error: `Invalid payload for ${params.pluginName}.${params.actionName}: ${parsed.error.message}`,
-            message: `Invalid payload for ${params.pluginName}.${params.actionName}`,
+            error: `Invalid payload for ${params.plugin_name}.${params.action_name}: ${parsed.error.message}`,
+            message: `Invalid payload for ${params.plugin_name}.${params.action_name}`,
         };
     }
     /**
      * 运行 plugin action。
      */
-    async runAction(params) {
+    async run_action(params) {
         return await this.run_action_from_records(this.records, params);
     }
     /**
@@ -441,8 +467,8 @@ export class PluginRegistry {
                 message: `Unknown plugin: ${params.plugin}`,
             };
         }
-        const actionName = normalize_plugin_name(params.action);
-        if (!actionName) {
+        const action_name = normalize_plugin_name(params.action);
+        if (!action_name) {
             return {
                 success: false,
                 error: "action is required",
@@ -456,18 +482,18 @@ export class PluginRegistry {
                 message: `Plugin "${record.plugin.name}" is not ready`,
             };
         }
-        const action = record.plugin.actions?.[actionName];
+        const action = record.plugin.actions?.[action_name];
         if (!action) {
             return {
                 success: false,
-                error: `Plugin "${record.plugin.name}" does not implement action "${actionName}"`,
-                message: `Plugin "${record.plugin.name}" does not implement action "${actionName}"`,
+                error: `Plugin "${record.plugin.name}" does not implement action "${action_name}"`,
+                message: `Plugin "${record.plugin.name}" does not implement action "${action_name}"`,
             };
         }
         try {
             const parsed_payload = this.parseActionPayload({
-                pluginName: record.plugin.name,
-                actionName,
+                plugin_name: record.plugin.name,
+                action_name,
                 payload: (params.payload ?? {}),
                 action,
             });
@@ -477,9 +503,11 @@ export class PluginRegistry {
             const result = await action.execute({
                 context: this.require_context(),
                 input: parsed_payload.input,
-                pluginName: record.plugin.name,
-                actionName,
-                ...(params.run_context ? { run_context: params.run_context } : {}),
+                plugin_name: record.plugin.name,
+                action_name,
+                ...(params.execution_context
+                    ? { execution_context: params.execution_context }
+                    : {}),
             });
             return result;
         }
@@ -494,13 +522,13 @@ export class PluginRegistry {
     /**
      * 读取当前生效的 plugin system blocks。
      */
-    async systemBlocks(run_context) {
-        return await this.system_blocks_from_records(this.records, run_context);
+    async system_blocks(execution_context) {
+        return await this.system_blocks_from_records(this.records, execution_context);
     }
     /**
      * 从指定记录视图解析 plugin system blocks。
      */
-    async system_blocks_from_records(records, run_context) {
+    async system_blocks_from_records(records, execution_context) {
         const context = this.require_context();
         const out = [];
         for (const record of records.values()) {
@@ -515,7 +543,7 @@ export class PluginRegistry {
                     if (!availability.available)
                         continue;
                 }
-                const text = String(await plugin.system(context, run_context)).trim();
+                const text = String(await plugin.system(context, execution_context)).trim();
                 if (!text)
                     continue;
                 out.push({
@@ -537,8 +565,8 @@ export class PluginRegistry {
         const records = new Map(this.records);
         return {
             read: (params) => this.read_from_records(records, params),
-            runAction: async (params) => await this.run_action_from_records(records, params),
-            systemBlocks: async (run_context) => await this.system_blocks_from_records(records, run_context),
+            run_action: async (params) => await this.run_action_from_records(records, params),
+            system_blocks: async (execution_context) => await this.system_blocks_from_records(records, execution_context),
             acquire: () => this.acquire_execution_view(records),
         };
     }
@@ -559,8 +587,8 @@ export class PluginRegistry {
         let released = false;
         return {
             read: (params) => this.read_from_records(leased_records, params),
-            runAction: async (params) => await this.run_action_from_records(leased_records, params),
-            systemBlocks: async (run_context) => await this.system_blocks_from_records(leased_records, run_context),
+            run_action: async (params) => await this.run_action_from_records(leased_records, params),
+            system_blocks: async (execution_context) => await this.system_blocks_from_records(leased_records, execution_context),
             release: async () => {
                 if (released)
                     return;