@downcity/agent 1.1.287 → 1.1.310

package/src/plugin/core/HookRegistry.ts

@@ -13,25 +13,25 @@ import type {
   PluginPipelineHook,
   PluginResolveHook,
 } from "@/types/plugin/PluginRuntime.js";
-import type { AgentContext } from "@/agent/AgentContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 
 type PipelineRecord = {
-  pluginName: string;
+  plugin_name: string;
   handler: PluginPipelineHook<JsonValue>;
 };
 
 type GuardRecord = {
-  pluginName: string;
+  plugin_name: string;
   handler: PluginGuardHook<JsonValue>;
 };
 
 type EffectRecord = {
-  pluginName: string;
+  plugin_name: string;
   handler: PluginEffectHook<JsonValue>;
 };
 
 type ResolveRecord = {
-  pluginName: string;
+  plugin_name: string;
   handler: PluginResolveHook<JsonValue, JsonValue>;
 };
 
@@ -39,7 +39,7 @@ type ResolveRecord = {
  * HookRegistry：plugin 点注册与执行实现。
  */
 export class HookRegistry {
-  private readonly get_context: () => AgentContext;
+  private readonly get_context: () => PluginContext;
   private readonly is_plugin_ready: (plugin_name: string) => boolean;
 
   private readonly pipelineHooks = new Map<string, PipelineRecord[]>();
@@ -51,7 +51,7 @@ export class HookRegistry {
   private readonly resolveHooks = new Map<string, ResolveRecord>();
 
   constructor(params: {
-    get_context: () => AgentContext;
+    get_context: () => PluginContext;
     is_plugin_ready: (plugin_name: string) => boolean;
   }) {
     this.get_context = params.get_context;
@@ -62,17 +62,17 @@ export class HookRegistry {
    * 注册 pipeline 扩展点。
    */
   pipeline(
-    pointName: string,
-    pluginName: string,
+    point_name: string,
+    plugin_name: string,
     handler: PluginPipelineHook<JsonValue>,
   ): void {
-    const key = String(pointName || "").trim();
+    const key = String(point_name || "").trim();
     if (!key) {
       throw new Error("Pipeline point name is required");
     }
     const bucket = this.pipelineHooks.get(key) || [];
     bucket.push({
-      pluginName: String(pluginName || "").trim(),
+      plugin_name: String(plugin_name || "").trim(),
       handler,
     });
     this.pipelineHooks.set(key, bucket);
@@ -82,17 +82,17 @@ export class HookRegistry {
    * 注册 guard 扩展点。
    */
   guard(
-    pointName: string,
-    pluginName: string,
+    point_name: string,
+    plugin_name: string,
     handler: PluginGuardHook<JsonValue>,
   ): void {
-    const key = String(pointName || "").trim();
+    const key = String(point_name || "").trim();
     if (!key) {
       throw new Error("Guard point name is required");
     }
     const bucket = this.guardHooks.get(key) || [];
     bucket.push({
-      pluginName: String(pluginName || "").trim(),
+      plugin_name: String(plugin_name || "").trim(),
       handler,
     });
     this.guardHooks.set(key, bucket);
@@ -102,17 +102,17 @@ export class HookRegistry {
    * 注册 effect 扩展点。
    */
   effect(
-    pointName: string,
-    pluginName: string,
+    point_name: string,
+    plugin_name: string,
     handler: PluginEffectHook<JsonValue>,
   ): void {
-    const key = String(pointName || "").trim();
+    const key = String(point_name || "").trim();
     if (!key) {
       throw new Error("Effect point name is required");
     }
     const bucket = this.effectHooks.get(key) || [];
     bucket.push({
-      pluginName: String(pluginName || "").trim(),
+      plugin_name: String(plugin_name || "").trim(),
       handler,
     });
     this.effectHooks.set(key, bucket);
@@ -125,11 +125,11 @@ export class HookRegistry {
    * - resolve 语义要求单点单处理器，避免 service 侧再做二次仲裁。
    */
   resolve(
-    pointName: string,
-    pluginName: string,
+    point_name: string,
+    plugin_name: string,
     handler: PluginResolveHook<JsonValue, JsonValue>,
   ): void {
-    const key = String(pointName || "").trim();
+    const key = String(point_name || "").trim();
     if (!key) {
       throw new Error("Resolve point name is required");
     }
@@ -137,7 +137,7 @@ export class HookRegistry {
       throw new Error(`Resolve point already registered: ${key}`);
     }
     this.resolveHooks.set(key, {
-      pluginName: String(pluginName || "").trim(),
+      plugin_name: String(plugin_name || "").trim(),
       handler,
     });
   }
@@ -145,40 +145,40 @@ export class HookRegistry {
   /**
    * 移除指定 plugin 注册的全部扩展点。
    */
-  unregisterPlugin(pluginName: string): void {
-    const key = String(pluginName || "").trim();
+  unregister_plugin(plugin_name: string): void {
+    const key = String(plugin_name || "").trim();
     if (!key) return;
 
-    for (const [pointName, bucket] of this.pipelineHooks.entries()) {
-      const next = bucket.filter((item) => item.pluginName !== key);
+    for (const [point_name, bucket] of this.pipelineHooks.entries()) {
+      const next = bucket.filter((item) => item.plugin_name !== key);
       if (next.length > 0) {
-        this.pipelineHooks.set(pointName, next);
+        this.pipelineHooks.set(point_name, next);
       } else {
-        this.pipelineHooks.delete(pointName);
+        this.pipelineHooks.delete(point_name);
       }
     }
 
-    for (const [pointName, bucket] of this.guardHooks.entries()) {
-      const next = bucket.filter((item) => item.pluginName !== key);
+    for (const [point_name, bucket] of this.guardHooks.entries()) {
+      const next = bucket.filter((item) => item.plugin_name !== key);
       if (next.length > 0) {
-        this.guardHooks.set(pointName, next);
+        this.guardHooks.set(point_name, next);
       } else {
-        this.guardHooks.delete(pointName);
+        this.guardHooks.delete(point_name);
       }
     }
 
-    for (const [pointName, bucket] of this.effectHooks.entries()) {
-      const next = bucket.filter((item) => item.pluginName !== key);
+    for (const [point_name, bucket] of this.effectHooks.entries()) {
+      const next = bucket.filter((item) => item.plugin_name !== key);
       if (next.length > 0) {
-        this.effectHooks.set(pointName, next);
+        this.effectHooks.set(point_name, next);
       } else {
-        this.effectHooks.delete(pointName);
+        this.effectHooks.delete(point_name);
       }
     }
 
-    for (const [pointName, record] of this.resolveHooks.entries()) {
-      if (record.pluginName === key) {
-        this.resolveHooks.delete(pointName);
+    for (const [point_name, record] of this.resolveHooks.entries()) {
+      if (record.plugin_name === key) {
+        this.resolveHooks.delete(point_name);
       }
     }
   }
@@ -199,8 +199,8 @@ export class HookRegistry {
   /**
    * 运行 pipeline 扩展点。
    */
-  async pipelineValue<T = JsonValue>(pointName: string, value: T): Promise<T> {
-    const key = String(pointName || "").trim();
+  async pipelineValue<T = JsonValue>(point_name: string, value: T): Promise<T> {
+    const key = String(point_name || "").trim();
     if (!key) return value;
     const bucket = this.pipelineHooks.get(key) || [];
     if (bucket.length === 0) return value;
@@ -208,11 +208,11 @@ export class HookRegistry {
     const context = this.get_context();
     let current = value as JsonValue;
     for (const item of bucket) {
-      if (!this.is_plugin_ready(item.pluginName)) continue;
+      if (!this.is_plugin_ready(item.plugin_name)) continue;
       current = await item.handler({
         context,
         value: current,
-        plugin: item.pluginName,
+        plugin: item.plugin_name,
       });
     }
     return current as T;
@@ -221,19 +221,19 @@ export class HookRegistry {
   /**
    * 运行 guard 扩展点。
    */
-  async guardValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
-    const key = String(pointName || "").trim();
+  async guardValue<T = JsonValue>(point_name: string, value: T): Promise<void> {
+    const key = String(point_name || "").trim();
     if (!key) return;
     const bucket = this.guardHooks.get(key) || [];
     if (bucket.length === 0) return;
 
     const context = this.get_context();
     for (const item of bucket) {
-      if (!this.is_plugin_ready(item.pluginName)) continue;
+      if (!this.is_plugin_ready(item.plugin_name)) continue;
       await item.handler({
         context,
         value: value as JsonValue,
-        plugin: item.pluginName,
+        plugin: item.plugin_name,
       });
     }
   }
@@ -241,19 +241,19 @@ export class HookRegistry {
   /**
    * 运行 effect 扩展点。
    */
-  async effectValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
-    const key = String(pointName || "").trim();
+  async effectValue<T = JsonValue>(point_name: string, value: T): Promise<void> {
+    const key = String(point_name || "").trim();
     if (!key) return;
     const bucket = this.effectHooks.get(key) || [];
     if (bucket.length === 0) return;
 
     const context = this.get_context();
     for (const item of bucket) {
-      if (!this.is_plugin_ready(item.pluginName)) continue;
+      if (!this.is_plugin_ready(item.plugin_name)) continue;
       await item.handler({
         context,
         value: value as JsonValue,
-        plugin: item.pluginName,
+        plugin: item.plugin_name,
       });
     }
   }
@@ -262,10 +262,10 @@ export class HookRegistry {
    * 运行 resolve 点。
    */
   async resolveValue<TInput = JsonValue, TOutput = JsonValue>(
-    pointName: string,
+    point_name: string,
     value: TInput,
   ): Promise<TOutput> {
-    const key = String(pointName || "").trim();
+    const key = String(point_name || "").trim();
     if (!key) {
       throw new Error("Resolve point name is required");
     }
@@ -274,14 +274,14 @@ export class HookRegistry {
       throw new Error(`No plugin resolver registered for point: ${key}`);
     }
     const context = this.get_context();
-    if (!this.is_plugin_ready(record.pluginName)) {
+    if (!this.is_plugin_ready(record.plugin_name)) {
       throw new Error(`No active plugin resolver registered for point: ${key}`);
     }
 
     return await record.handler({
       context,
       value: value as JsonValue,
-      plugin: record.pluginName,
+      plugin: record.plugin_name,
     }) as TOutput;
   }
 }

package/src/plugin/core/PluginActionFactory.ts

@@ -2,13 +2,13 @@
  * PluginActionFactory：创建带 metadata 和 schema 的 plugin/action。
  *
  * 关键点（中文）
- * - `createAction` 让 action 的运行时 schema 与 TypeScript 输入类型保持一致。
- * - `createPlugin` 只做轻量对象装配，不强制继承 BasePlugin。
+ * - `create_action` 让 action 的运行时 schema 与 TypeScript 输入类型保持一致。
+ * - `create_plugin` 只做轻量对象装配，不强制继承 BasePlugin。
  * - 旧的 class extends BasePlugin 写法仍可继续使用。
  */
 
 import type { z } from "zod";
-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 {
   PluginAction,
@@ -22,21 +22,12 @@ import type {
 import type { Plugin } from "@/types/plugin/PluginDefinition.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 { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
 import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
-import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
 
 /**
  * 从 Zod schema 推导 JSON 输入类型。
@@ -45,7 +36,7 @@ type InferZodJson<TSchema extends z.ZodTypeAny> =
   z.infer<TSchema> extends JsonValue ? z.infer<TSchema> : JsonValue;
 
 /**
- * createAction 参数。
+ * create_action 参数。
  */
 export interface CreatePluginActionOptions<
   P extends JsonValue,
@@ -64,20 +55,20 @@ export interface CreatePluginActionOptions<
   /** Action 执行器。 */
   execute: (params: {
     /** 当前执行上下文。 */
-    context: AgentContext;
-    /** 当前 action 的显式 Session run 上下文。 */
-    run_context?: PluginRunContext;
+    context: PluginContext;
+    /** 当前 action 所属 Session Turn 的只读执行快照。 */
+    execution_context?: PluginExecutionContext;
     /** 已通过 schema 校验后的输入。 */
     input: P;
     /** 当前插件名称。 */
-    pluginName: string;
+    plugin_name: string;
     /** 当前 Action 名称。 */
-    actionName: string;
+    action_name: string;
   }) => Promise<PluginActionResult<R>> | PluginActionResult<R>;
 }
 
 /**
- * createPlugin 参数。
+ * create_plugin 参数。
  */
 export interface CreatePluginOptions<TActions extends PluginActions> {
   /** Plugin 稳定名称。 */
@@ -88,26 +79,20 @@ export interface CreatePluginOptions<TActions extends PluginActions> {
   description?: string;
   /** Plugin 显式 action 集合。 */
   actions?: TActions;
-  /** Plugin 配置定义。 */
-  config?: PluginConfigDefinition<StructuredConfig>;
-  /** Plugin setup 定义。 */
-  setup?: PluginSetupDefinition;
-  /** Plugin usage 定义。 */
-  usage?: PluginUsageDefinition;
   /** Plugin hook 集合。 */
   hooks?: PluginHooks;
   /** Plugin resolve 集合。 */
   resolves?: PluginResolves;
   /** Plugin system 文本构建器。 */
   system?: (
-    context: AgentContext,
-    run_context?: PluginRunContext,
+    context: PluginContext,
+    execution_context?: PluginExecutionContext,
   ) => string | Promise<string>;
   /** Plugin 生命周期定义。 */
   lifecycle?: PluginLifecycle;
   /** Plugin 可用性检查。 */
   availability?: (
-    context: PluginCommandContext | AgentContext,
+    context: PluginContext,
   ) => Promise<PluginAvailability> | PluginAvailability;
   /** Plugin HTTP 注入定义。 */
   http?: PluginHttpDefinition;
@@ -129,7 +114,7 @@ function normalize_input_schema<P extends JsonValue>(
 /**
  * 创建带 metadata 的 action。
  */
-export function createAction<
+export function create_action<
   TSchema extends z.ZodTypeAny,
   R extends JsonValue = JsonValue,
 >(
@@ -138,10 +123,10 @@ export function createAction<
     input_schema?: TSchema | PluginActionInputSchema<InferZodJson<TSchema>>;
   },
 ): PluginAction<InferZodJson<TSchema>, R>;
-export function createAction<R extends JsonValue = JsonValue>(
+export function create_action<R extends JsonValue = JsonValue>(
   options: CreatePluginActionOptions<JsonValue, R>,
 ): PluginAction<JsonValue, R>;
-export function createAction(
+export function create_action(
   options: CreatePluginActionOptions<JsonValue, JsonValue>,
 ): PluginAction<JsonValue, JsonValue> {
   return {
@@ -159,21 +144,18 @@ export function createAction(
 /**
  * 创建 plugin 对象。
  */
-export function createPlugin<TActions extends PluginActions>(
+export function create_plugin<TActions extends PluginActions>(
   options: CreatePluginOptions<TActions>,
 ): Plugin & { actions: TActions } {
   const name = String(options.name || "").trim();
   if (!name) {
-    throw new Error("createPlugin requires a non-empty name");
+    throw new Error("create_plugin requires a non-empty name");
   }
   return {
     name,
     title: String(options.title || name).trim(),
     description: String(options.description || "").trim(),
     actions: options.actions || ({} as TActions),
-    ...(options.config ? { config: options.config } : {}),
-    ...(options.setup ? { setup: options.setup } : {}),
-    ...(options.usage ? { usage: options.usage } : {}),
     ...(options.hooks ? { hooks: options.hooks } : {}),
     ...(options.resolves ? { resolves: options.resolves } : {}),
     ...(options.system ? { system: options.system } : {}),

package/src/plugin/core/PluginActionRunner.ts

@@ -1,196 +1,36 @@
 /**
- * PluginActionRunner：plugin command/action 执行模块。
+ * Plugin Action 解析与执行辅助。
  *
- * 关键点（中文）
- * - 新模型中注册即生效，不再要求 plugin 处于 running 状态。
- * - CLI/RPC command 优先解析为同名 action，再处理 plugin 自定义命令。
- * - 延迟调度仍复用本模块，保证 schedule 到点后走统一 action 规则。
+ * 关键点（中文）：Plugin 对外调用协议只有 Action，不再提供 command 兼容层。
  */
 
-import type { AgentContext } from "@/agent/AgentContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { PluginAction, PluginActionResult } from "@/types/plugin/PluginAction.js";
-import type { PluginCommandResult } from "@/types/plugin/PluginCommand.js";
-import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
-import type { PluginActionScheduleInput } from "@/plugin/types/ActionSchedule.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import { ActionScheduleStore } from "@/plugin/core/ActionScheduleStore.js";
-import { normalizeRunAtMsOrThrow } from "@/plugin/core/ActionScheduleTime.js";
 
-/**
- * 按名称解析 plugin action。
- */
-export function resolvePluginAction(
-  plugin: {
-    actions?: Record<string, PluginAction<JsonValue, JsonValue>>;
-  },
-  actionName: string,
+/** 按名称解析一个 Plugin Action。 */
+export function resolve_plugin_action(
+  plugin: { actions?: Record<string, PluginAction<JsonValue, JsonValue>> },
+  action_name: string,
 ): PluginAction<JsonValue, JsonValue> | null {
-  const key = String(actionName || "").trim();
-  if (!key) return null;
-  return plugin.actions?.[key] || null;
+  const key = String(action_name || "").trim();
+  return key ? plugin.actions?.[key] ?? null : null;
 }
 
-/**
- * 执行一个 plugin action。
- */
-export async function invokePluginAction(params: {
-  pluginName: string;
-  actionName: string;
+/** 通过当前 Plugin Registry 执行一个 Action。 */
+export async function invoke_plugin_action(params: {
+  /** Plugin 稳定名称。 */
+  plugin_name: string;
+  /** Action 稳定名称。 */
+  action_name: string;
+  /** 可选 JSON 输入。 */
   payload?: JsonValue;
-  context: AgentContext;
+  /** 当前 Agent Plugin Context。 */
+  context: PluginContext;
 }): Promise<PluginActionResult<JsonValue>> {
-  return await params.context.plugins.runAction({
-    plugin: params.pluginName,
-    action: params.actionName,
+  return await params.context.plugins.run_action({
+    plugin: params.plugin_name,
+    action: params.action_name,
     payload: params.payload,
   });
 }
-
-async function schedulePluginAction(params: {
-  pluginName: string;
-  command: string;
-  payload?: JsonValue;
-  schedule: JsonValue | PluginActionScheduleInput;
-  recordSnapshot: PluginSnapshot;
-  context: AgentContext;
-}): Promise<PluginCommandResult & { plugin?: PluginSnapshot }> {
-  try {
-    const scheduleInput = params.schedule as Partial<PluginActionScheduleInput>;
-    const runAtMs = normalizeRunAtMsOrThrow(
-      scheduleInput.runAtMs,
-      "schedule.runAtMs",
-    );
-    const store = new ActionScheduleStore(params.context.rootPath);
-    try {
-      const job = store.createJob({
-        pluginName: params.pluginName,
-        actionName: params.command,
-        payload: params.payload ?? null,
-        runAtMs,
-      });
-      return {
-        success: true,
-        plugin: params.recordSnapshot,
-        data: {
-          scheduled: true,
-          jobId: job.id,
-          runAtMs: job.runAtMs,
-          status: job.status,
-        },
-      };
-    } finally {
-      store.close();
-    }
-  } catch (error) {
-    return {
-      success: false,
-      plugin: params.recordSnapshot,
-      message: String(error),
-    };
-  }
-}
-
-/**
- * 统一执行 plugin command。
- */
-export async function runPluginCommand(params: {
-  pluginName: string;
-  command: string;
-  payload?: JsonValue;
-  schedule?: JsonValue | PluginActionScheduleInput;
-  context: AgentContext;
-}): Promise<PluginCommandResult & { plugin?: PluginSnapshot }> {
-  const pluginName = String(params.pluginName || "").trim();
-  const command = String(params.command || "")
-    .trim()
-    .toLowerCase();
-  const plugin = params.context.plugins.get(pluginName);
-  const snapshot = params.context.plugins.status(pluginName) || undefined;
-
-  if (!plugin || !snapshot) {
-    return {
-      success: false,
-      message: `Unknown plugin: ${params.pluginName}`,
-    };
-  }
-
-  if (!command) {
-    return {
-      success: false,
-      plugin: snapshot,
-      message: "command is required",
-    };
-  }
-
-  if (command === "status") {
-    return {
-      success: true,
-      plugin: snapshot,
-    };
-  }
-
-  const action = resolvePluginAction(plugin, command);
-  if (params.schedule !== undefined && params.schedule !== null) {
-    if (!action) {
-      return {
-        success: false,
-        plugin: snapshot,
-        message: `Scheduling only supports plugin actions. "${plugin.name}.${command}" is not a schedulable action.`,
-      };
-    }
-
-    return await schedulePluginAction({
-      pluginName: plugin.name,
-      command,
-      payload: params.payload,
-      schedule: params.schedule,
-      recordSnapshot: snapshot,
-      context: params.context,
-    });
-  }
-
-  if (action) {
-    const result = await params.context.plugins.runAction({
-      plugin: plugin.name,
-      action: command,
-      payload: params.payload,
-    });
-
-    return {
-      success: result.success,
-      plugin: params.context.plugins.status(plugin.name) || snapshot,
-      ...(result.message || result.error
-        ? { message: result.message || result.error }
-        : {}),
-      ...(result.data !== undefined ? { data: result.data } : {}),
-      ...(result.error ? { error: result.error } : {}),
-    };
-  }
-
-  const handler = plugin.lifecycle?.command;
-  if (handler) {
-    try {
-      const result = await handler({
-        context: params.context,
-        command,
-        payload: params.payload,
-      });
-      return {
-        ...result,
-        plugin: params.context.plugins.status(plugin.name) || snapshot,
-      };
-    } catch (error) {
-      return {
-        success: false,
-        plugin: params.context.plugins.status(plugin.name) || snapshot,
-        message: String(error),
-      };
-    }
-  }
-
-  return {
-    success: false,
-    plugin: snapshot,
-    message: `Plugin "${plugin.name}" does not implement command "${command}"`,
-  };
-}