@downcity/agent 1.1.287 → 1.1.310

package/src/types/plugin/PluginCommand.ts

@@ -1,77 +1,15 @@
 /**
- * Plugin command 与 lifecycle 类型。
+ * Plugin 生命周期类型。
  *
- * 关键点（中文）
- * - command 面向显式 CLI/control 调用。
- * - lifecycle 面向 runtime 主动 start/stop 钩子。
+ * 关键点（中文）：生命周期只负责启动和停止；所有显式能力调用统一使用 Action。
  */
 
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 
-/**
- * Plugin 命令执行上下文。
- *
- * 关键点（中文）
- * - 这里表达的是“CLI 命令执行 plugin 时真正需要的最小上下文”。
- * - plugin 命令不应依赖 session、plugin invoke、agent runtime 等长期宿主对象。
- * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
- */
-export interface PluginCommandContext {
-  /** 当前 Agent 稳定标识。 */
-  agent_id: string;
-  /** 当前项目根目录。 */
-  rootPath: string;
-  /** 当前统一日志器。 */
-  logger: Logger;
-  /**
-   * 当前项目环境变量快照。
-   *
-   * 关键点（中文）
-   * - 这里约定为宿主已经整理好的最终可见 env 视图。
-   * - plugin 不再区分 global env 与 agent env，避免上下文语义膨胀。
-   */
-  env: Record<string, string>;
-}
-
-/**
- * Plugin 非 action 命令执行参数。
- */
-export interface PluginCommandParams {
-  /** 当前统一执行上下文。 */
-  context: AgentContext;
-  /** 当前命令名称。 */
-  command: string;
-  /** 命令附带 payload（可选）。 */
-  payload?: JsonValue;
-}
-
-/**
- * Plugin 非 action 命令执行结果。
- */
-export interface PluginCommandResult {
-  /** 本次命令是否成功。 */
-  success: boolean;
-  /** 人类可读消息。 */
-  message?: string;
-  /** 结构化返回数据。 */
-  data?: JsonValue;
-}
-
-/**
- * Plugin 生命周期定义。
- *
- * 关键点（中文）
- * - 生命周期只描述 plugin 启动、停止和非 action 命令处理。
- */
+/** Plugin 生命周期定义。 */
 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 启动钩子。 */
+  start?(context: PluginContext): Promise<void> | void;
+  /** Plugin 停止钩子。 */
+  stop?(context: PluginContext): Promise<void> | void;
 }

package/src/types/plugin/PluginContext.ts

@@ -0,0 +1,43 @@
+/**
+ * PluginContext：Agent 向 Plugin 投影的稳定能力视图。
+ *
+ * 边界说明（中文）
+ * - Plugin 只依赖本接口，不持有 Agent 实例，也不参与 Session 内核编排。
+ * - 动态状态通过只读 getter 暴露，保证 Workspace env 与 instruction 始终来自唯一状态源。
+ */
+
+import type { AgentSessions } from "@/agent/AgentSessions.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { Shell } from "@downcity/shell";
+
+/** Agent 向 Plugin 开放的最小、稳定运行时能力。 */
+export interface PluginContext {
+  /** 当前 Agent 的稳定标识。 */
+  readonly agent_id: string;
+
+  /** 当前 Workspace 的绝对根目录。 */
+  readonly workspace_path: string;
+
+  /** 当前 Workspace 的统一文件能力。 */
+  readonly files: FileSystem;
+
+  /** 当前 Workspace 显式挂载的 Shell；未启用时为空。 */
+  readonly shell?: Shell;
+
+  /** 当前 Agent 独享的统一日志器。 */
+  readonly logger: Logger;
+
+  /** 当前 Agent 的 Session 集合入口。 */
+  readonly sessions: AgentSessions;
+
+  /** 当前 Agent 唯一的 Plugin 调用与注册入口。 */
+  readonly plugins: AgentPlugins;
+
+  /** 当前 Workspace 已配置环境变量的只读快照。 */
+  readonly workspace_env: Readonly<Record<string, string>>;
+
+  /** 当前 Agent 已配置静态指令的只读快照。 */
+  readonly instructions: readonly string[];
+}

package/src/types/plugin/PluginDefinition.ts

@@ -3,28 +3,19 @@
  *
  * 关键点（中文）
  * - 这里只组合 plugin 的各类能力，不展开每个能力的细节。
- * - 细节类型分散在 State / Command / Action / Runtime / Setup / HTTP 模块。
+ * - 细节类型分散在 State / Action / Runtime / Lifecycle / HTTP 模块。
  */
 
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.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 { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
 import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
 
 /**
  * Plugin 定义。
@@ -36,26 +27,8 @@ export interface 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 点集合（可选）。 */
@@ -64,17 +37,17 @@ export interface Plugin {
    * Plugin system 文本构建器（可选）。
    *
    * @param context Agent 稳定能力上下文。
-   * @param run_context 当前 Session run 上下文；非 Session 快照读取时可缺省。
+   * @param execution_context 当前 Session Turn 的只读 Plugin 执行快照；非 Session 调用时可缺省。
    */
   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;

package/src/types/plugin/PluginExecutionContext.ts

@@ -0,0 +1,34 @@
+/**
+ * Plugin 单次调用的执行上下文。
+ *
+ * 关键点（中文）
+ * - 只暴露 plugin 业务需要的只读 Session 快照。
+ * - 不暴露 Executor 内部队列、callback 或 plugin lease。
+ * - CLI、HTTP 与 scheduler 等非 Session 调用可能不提供该对象。
+ */
+
+/**
+ * Plugin action 与 system provider 可读取的执行快照。
+ *
+ * Session 调用时，该对象是当前 Turn 的只读 Plugin 投影；CLI、HTTP 与
+ * scheduler 等非 Session 调用也可以提供自己的调用快照或完全缺省。
+ */
+export interface PluginExecutionContext {
+  /** 当前调用所属的 Session 标识。 */
+  readonly session_id: string;
+
+  /** 当前调用所属的 Turn 标识。 */
+  readonly turn_id?: string;
+
+  /** 当前 Agent 绑定的项目根目录。 */
+  readonly project_root?: string;
+
+  /** 当前 Session Step 已提交生效的 Workspace env 快照。 */
+  readonly workspace_env?: Readonly<Record<string, string>>;
+
+  /** 当前 Session Step 已提交生效的 instruction 快照。 */
+  readonly agent_systems?: readonly string[];
+
+  /** 当前 Turn 的取消信号。 */
+  readonly abort_signal?: AbortSignal;
+}

package/src/types/plugin/PluginHttp.ts

@@ -7,23 +7,23 @@
  */
 
 import type { Hono } from "hono";
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
+import type { AuthRoutePolicy } from "@downcity/type";
 
 /**
  * Plugin HTTP 注入参数。
  */
 export interface PluginHttpRegistration {
   /** 该组路由对应的鉴权策略列表。 */
-  authPolicies?: AuthRoutePolicy[];
+  auth_policies?: AuthRoutePolicy[];
   /** 向 runtime Hono 应用注册路由。 */
   register(params: {
     /** 当前 Hono 应用实例。 */
     app: Hono;
     /** 获取当前统一执行上下文。 */
-    getContext: () => AgentContext;
+    get_context: () => PluginContext;
     /** 当前 plugin 稳定名称。 */
-    pluginName: string;
+    plugin_name: string;
   }): void;
 }
 

package/src/types/plugin/PluginRegistry.ts

@@ -0,0 +1,25 @@
+/**
+ * PluginRegistry 变化订阅类型。
+ *
+ * 关键点（中文）
+ * - Agent 订阅 Registry 变化后同步 Plugin Tools 与 Session execution view。
+ * - PluginRegistry 不直接修改 Agent 持有的工具集合。
+ */
+
+/** PluginRegistry 的单次配置变化。 */
+export interface PluginRegistryChange {
+  /** 当前修改是注册还是卸载。 */
+  type: "register" | "unregister";
+
+  /** 当前发生修改的 Plugin 稳定名称。 */
+  plugin_name: string;
+}
+
+/** PluginRegistry 变化监听器。 */
+export type PluginRegistrySubscriber = (
+  /** 当前 Plugin 配置变化。 */
+  change: PluginRegistryChange,
+) => void;
+
+/** 取消 PluginRegistry 变化订阅的函数。 */
+export type PluginRegistryUnsubscribe = () => void;

package/src/types/plugin/PluginRuntime.ts

@@ -6,15 +6,14 @@
  * - setup/usage UI 协议与 action 输入适配不放在这里。
  */
 
-import type { AgentContext } from "@/agent/AgentContext.js";
-import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type { PluginActionExample } from "@/types/plugin/PluginAction.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.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";
 
 /**
  * Plugin 概览视图。
@@ -37,9 +36,9 @@ export interface PluginView {
   /** Plugin resolve 点名称列表。 */
   resolves: string[];
   /** 是否声明了 system 注入。 */
-  hasSystem: boolean;
+  has_system: boolean;
   /** 是否声明了 availability 检查。 */
-  hasAvailability: boolean;
+  has_availability: boolean;
 }
 
 /**
@@ -101,17 +100,17 @@ export interface AgentPlugins {
    * - 返回值表示 configured registry 是否发生删除。
    * - 活跃 Session step 仍可使用已捕获的 execution lease，lifecycle.stop 在 lease 释放后执行。
    */
-  unregister(pluginName: string): Promise<boolean>;
+  unregister(plugin_name: string): Promise<boolean>;
   /** 启动全部已挂载 plugin lifecycle。 */
-  startAll(): Promise<PluginSnapshot[]>;
+  start_all(): Promise<PluginSnapshot[]>;
   /** 卸载全部 plugin，并等待所有 execution lease 释放后的 lifecycle.stop 完成。 */
-  unregisterAll(): Promise<void>;
+  unregister_all(): Promise<void>;
   /** 判断 plugin 是否已注册。 */
-  has(pluginName: string): boolean;
+  has(plugin_name: string): boolean;
   /** 读取单个 plugin 定义。 */
-  get(pluginName: string): Plugin | null;
+  get(plugin_name: string): Plugin | null;
   /** 读取单个 plugin 注册快照。 */
-  status(pluginName: string): PluginSnapshot | null;
+  status(plugin_name: string): PluginSnapshot | null;
   /** 列出全部已注册 plugin 快照。 */
   snapshots(): PluginSnapshot[];
   /** 列出全部已注册 plugin。 */
@@ -124,31 +123,31 @@ export interface AgentPlugins {
     action?: string;
   }): PluginReadView | { plugins: PluginView[] };
   /** 检查指定 plugin 可用性。 */
-  availability(pluginName: string): Promise<PluginAvailability>;
+  availability(plugin_name: string): Promise<PluginAvailability>;
   /** 运行指定 plugin action。 */
-  runAction(params: {
+  run_action(params: {
     /** Plugin 名称。 */
     plugin: string;
     /** Action 名称。 */
     action: string;
     /** Action Payload（可选）。 */
     payload?: JsonValue;
-    /** 当前 action 所属的显式 Session run 上下文。 */
-    run_context?: SessionRunContext;
+    /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
+    execution_context?: PluginExecutionContext;
   }): Promise<PluginActionResult<JsonValue>>;
   /** 读取当前生效的 plugin system blocks。 */
-  systemBlocks(
-    run_context?: SessionRunContext,
+  system_blocks(
+    execution_context?: PluginExecutionContext,
   ): Promise<AgentSessionSystemBlock[]>;
   /** 运行 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,
+    point_name: string,
     value: TInput,
   ): Promise<TOutput>;
 
@@ -167,20 +166,20 @@ export interface AgentPluginExecutionView {
   }): PluginReadView | { plugins: PluginView[] };
 
   /** 运行当前视图中捕获的 plugin action。 */
-  runAction(params: {
+  run_action(params: {
     /** Plugin 名称。 */
     plugin: string;
     /** Action 名称。 */
     action: string;
     /** Action Payload（可选）。 */
     payload?: JsonValue;
-    /** 当前 action 所属的显式 Session run 上下文。 */
-    run_context?: SessionRunContext;
+    /** 当前 action 所属 Session Turn 的只读 Plugin 执行快照。 */
+    execution_context?: PluginExecutionContext;
   }): Promise<PluginActionResult<JsonValue>>;
 
   /** 解析当前视图中捕获的 plugin system blocks。 */
-  systemBlocks(
-    run_context?: SessionRunContext,
+  system_blocks(
+    execution_context?: PluginExecutionContext,
   ): Promise<AgentSessionSystemBlock[]>;
 }
 
@@ -212,18 +211,6 @@ export interface AgentPluginExecutionRuntime extends AgentPluginExecutionView {
   acquire(): AgentPluginExecutionLease;
 }
 
-/**
- * Plugin 配置定义。
- */
-export interface PluginConfigDefinition<T extends StructuredConfig = StructuredConfig> {
-  /** Plugin 稳定名称。 */
-  plugin: string;
-  /** 配置作用域。 */
-  scope: "global" | "project";
-  /** 默认配置值。 */
-  defaultValue: T;
-}
-
 /**
  * Plugin pipeline 处理器。
  */
@@ -231,7 +218,7 @@ export type PluginPipelineHook<
   TValue extends JsonValue = JsonValue,
 > = (params: {
   /** 当前执行上下文。 */
-  context: AgentContext;
+  context: PluginContext;
   /** 当前值。 */
   value: TValue;
   /** 当前插件名称。 */
@@ -246,7 +233,7 @@ export type PluginPipelineHook<
  */
 export type PluginGuardHook<TValue extends JsonValue = JsonValue> = (params: {
   /** 当前执行上下文。 */
-  context: AgentContext;
+  context: PluginContext;
   /** 当前值。 */
   value: TValue;
   /** 当前插件名称。 */
@@ -258,7 +245,7 @@ export type PluginGuardHook<TValue extends JsonValue = JsonValue> = (params: {
  */
 export type PluginEffectHook<TValue extends JsonValue = JsonValue> = (params: {
   /** 当前执行上下文。 */
-  context: AgentContext;
+  context: PluginContext;
   /** 当前值。 */
   value: TValue;
   /** 当前插件名称。 */
@@ -273,7 +260,7 @@ export type PluginResolveHook<
   TOutput extends JsonValue = JsonValue,
 > = (params: {
   /** 当前执行上下文。 */
-  context: AgentContext;
+  context: PluginContext;
   /** 当前输入值。 */
   value: TInput;
   /** 当前插件名称。 */
@@ -296,5 +283,5 @@ export interface PluginHooks {
  * Plugin resolve 点集合。
  */
 export type PluginResolves = {
-  [pointName: string]: PluginResolveHook<JsonValue, JsonValue>;
+  [point_name: string]: PluginResolveHook<JsonValue, JsonValue>;
 };

package/src/types/plugin/PluginState.ts

@@ -63,20 +63,3 @@ export interface PluginSnapshot {
   /** 最近错误。 */
   last_error?: string;
 }
-
-/**
- * Plugin 控制动作。
- */
-export type PluginControlAction = "unregister" | "status";
-
-/**
- * plugin 控制结果。
- */
-export interface PluginControlResult {
-  /** 控制动作是否成功。 */
-  success: boolean;
-  /** 成功或失败后返回的最新 plugin 快照。 */
-  plugin?: PluginSnapshot;
-  /** 失败时的错误信息。 */
-  error?: string;
-}

package/src/{executor/tools/plugin/types → types/plugin}/PluginTool.ts

@@ -6,7 +6,10 @@
  * - payload 保持 JSON 对象，避免 tool 层理解具体 plugin 的业务字段。
  */
 
+import type { Tool } from "ai";
 import type { JsonObject } from "@/types/common/Json.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 
 /**
  * plugin_call 输入。
@@ -30,22 +33,6 @@ export interface PluginReadInput {
   action?: string;
 }
 
-/**
- * plugin_call 产生的 assistant 文件摘要。
- */
-export interface PluginCallToolFileResult {
-  /** 文件在本轮 assistant 文件列表中的顺序。 */
-  index: number;
-  /** 文件 MIME 类型，例如 `image/png`。 */
-  media_type: string;
-  /** 原始文件名；若上游未提供则为空字符串。 */
-  filename: string;
-  /** 基于 Agent 项目根目录的相对路径，例如 `.downcity/resources/xxx.png`。 */
-  relative_path: string;
-  /** 当前机器可直接打开的绝对文件路径，按 Agent 项目根目录解析。 */
-  path: string;
-}
-
 /**
  * plugin_call 返回给模型的摘要结果。
  */
@@ -56,10 +43,6 @@ export interface PluginCallToolResult {
   plugin: string;
   /** 目标 action 名称。 */
   action: string;
-  /** 本次 action 产生并写入 assistant 消息的 file part 数量。 */
-  assistant_file_count: number;
-  /** 本次 action 产生的文件摘要，包含可直接打开的绝对路径。 */
-  files?: PluginCallToolFileResult[];
   /** 人类可读消息。 */
   message: string;
   /** 错误信息。 */
@@ -79,3 +62,42 @@ export interface PluginReadToolResult {
   /** 读取到的 metadata。 */
   data: JsonObject;
 }
+
+/** 创建当前 Agent 专属 Plugin Tools 的参数。 */
+export interface CreatePluginToolsOptions {
+  /** 当前 Agent 自己的 Plugin 调用面；Tool 只能访问该 Registry。 */
+  plugins: AgentPlugins;
+}
+
+/** 当前 Agent 专属的 Plugin Tools。 */
+export interface AgentPluginTools {
+  /** 通过闭包绑定当前 Registry 的 Plugin metadata 读取 Tool。 */
+  plugin_read: Tool;
+
+  /** 通过闭包绑定当前 Registry 的 Plugin Action 执行 Tool。 */
+  plugin_call: Tool;
+}
+
+/** 调用 plugin_call 运行时的显式依赖。 */
+export interface InvokePluginCallToolOptions {
+  /** 当前 Agent 自己的 Plugin 调用面。 */
+  plugins: AgentPlugins;
+
+  /** Executor 为当前 Tool Call 绑定的 Session Turn Context。 */
+  turn_context: SessionTurnContext;
+
+  /** 模型提交给 plugin_call 的结构化输入。 */
+  input: PluginCallInput;
+}
+
+/** 调用 plugin_read 运行时的显式依赖。 */
+export interface InvokePluginReadToolOptions {
+  /** 当前 Agent 自己的 Plugin 调用面。 */
+  plugins: AgentPlugins;
+
+  /** Executor 为当前 Tool Call 绑定的 Session Turn Context。 */
+  turn_context: SessionTurnContext;
+
+  /** 模型提交给 plugin_read 的结构化输入。 */
+  input: PluginReadInput;
+}