@downcity/agent 1.1.126 → 1.1.135

package/src/types/agent/AgentOptions.ts

@@ -10,7 +10,6 @@ import type { Tool } from "ai";
 import type { Shell } from "@downcity/shell";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
-import type { RpcServerInstance } from "@/rpc/Server.js";
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -112,71 +111,3 @@ export interface AgentOptions {
    */
   env?: Record<string, string>;
 }
-
-/**
- * Agent 启动参数。
- */
-export interface AgentStartOptions {
-  /**
-   * 是否启动本机 RPC 服务。
-   *
-   * 关键点（中文）
-   * - `false` 表示不启动。
-   * - 传对象时会按给定 host/port 启动。
-   * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
-   */
-  rpc?: false | AgentRpcStartOptions;
-
-  /**
-   * 是否启动当前 agent 的 plugins。
-   *
-   * 关键点（中文）
-   * - 默认 `true`。
-   * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
-   */
-  plugins?: boolean;
-}
-
-/**
- * Agent 停止结果快照。
- */
-export interface AgentStopResult {
-  /** 本次是否实际停止了本机 RPC 服务。 */
-  rpcStopped: boolean;
-  /** 本次是否实际停止了 plugins。 */
-  pluginsStopped: boolean;
-}
-
-/**
- * Agent 启动后的状态快照。
- */
-export interface AgentStartResult {
-  /** 当前 agent 是否已启动本机 RPC 服务。 */
-  rpc?: AgentRpcBinding;
-  /** 当前 agent 是否已启动 plugins。 */
-  pluginsStarted: boolean;
-}
-
-/**
- * Agent RPC 启动参数。
- */
-export interface AgentRpcStartOptions {
-  /** RPC 监听主机。 */
-  host?: string;
-  /** RPC 监听端口。 */
-  port?: number;
-}
-
-/**
- * Agent RPC 绑定信息。
- */
-export interface AgentRpcBinding {
-  /** 远程访问地址。 */
-  url: string;
-  /** 当前 host。 */
-  host: string;
-  /** 当前 port。 */
-  port: number;
-  /** RPC server 句柄。 */
-  server: RpcServerInstance;
-}

package/src/types/agent/AgentTypes.ts

@@ -19,12 +19,7 @@ export type {
 } from "@/types/session/SessionOptions.js";
 export type {
   AgentOptions,
-  AgentRpcBinding,
-  AgentRpcStartOptions,
   AgentSessionConstructor,
-  AgentStartOptions,
-  AgentStartResult,
-  AgentStopResult,
 } from "@/types/agent/AgentOptions.js";
 export type { RemoteAgentOptions } from "@/types/agent/RemoteAgentOptions.js";
 export type {

package/src/types/runtime/agent/AgentContext.ts

@@ -3,11 +3,12 @@
  *
  * 职责说明（中文）
  * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - `AgentContext` 是一个 class，表达“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
  *
  * 边界说明（中文）
  * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
- * - 这里只定义协议，不负责任何上下文装配逻辑。
+ * - 这里同时声明类型协议与默认实现；plugin 作者拿到的就是这个 class 的实例。
  */
 
 import type { LanguageModel } from "ai";
@@ -18,7 +19,7 @@ import type {
   AgentPluginConfigRuntime,
 } from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   SessionMetadataV1,
@@ -216,61 +217,120 @@ export interface SessionCollectionPort {
 }
 
 /**
- * 统一执行上下文。
+ * AgentContext 构造参数。
+ *
+ * 关键点（中文）
+ * - 装配方负责把 runtime / session / plugins 等上层依赖注入进来。
+ * - `env` 必须传入 agent 持有的 mutable 共享对象引用，不要在这里克隆。
  */
-export interface AgentContext {
-  /**
-   * 当前执行上下文对应的 agent 状态。
-   */
+export interface AgentContextOptions {
+  /** 当前执行上下文对应的 agent 状态。 */
   agent: AgentRuntime;
-  /**
-   * 当前命令工作目录。
-   */
+  /** 当前命令工作目录。 */
   cwd: string;
-  /**
-   * 当前项目根目录。
-   */
+  /** 当前项目根目录。 */
   rootPath: string;
-  /**
-   * 统一日志器。
-   */
+  /** 统一日志器。 */
   logger: Logger;
-  /**
-   * 当前运行时已解析配置。
-   */
+  /** 当前运行时已解析配置。 */
   config: DowncityConfig;
   /**
-   * 当前项目环境变量快照。
+   * 当前 agent env 共享对象引用。
+   *
+   * 关键点（中文）
+   * - 必须是 Agent 持有的同一个 mutable 引用，不要克隆后再传入。
+   * - 通过 `agent.setEnv` / `agent.patchEnv` 原地更新会被本 context 立即感知。
    */
   env: Record<string, string>;
-  /**
-   * 当前生效的 system 文本集合。
-   */
+  /** 当前生效的 system 文本集合。 */
   systems: string[];
-  /**
-   * 当前可见的路径能力集合。
-   */
+  /** 当前可见的路径能力集合。 */
   paths: AgentPathRuntime;
-  /**
-   * 当前可见的 plugin 配置持久化能力集合。
-   */
+  /** 当前可见的 plugin 配置持久化能力集合。 */
   pluginConfig: AgentPluginConfigRuntime;
+  /** Session 能力入口。 */
+  session: SessionCollectionPort;
+  /** Plugin 调用入口。 */
+  plugins: AgentPlugins;
+}
+
+/**
+ * 统一执行上下文。
+ *
+ * 关键点（中文）
+ * - 字段全部 readonly，构造一次后语义稳定，避免 plugin 误改。
+ * - `env` 引用 agent 级共享 mutable 对象，`...ctx.env` / `ctx.env.FOO` 直接可用。
+ * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
+ */
+export class AgentContext {
+  /** 当前执行上下文对应的 agent 状态。 */
+  readonly agent: AgentRuntime;
+  /** 当前命令工作目录。 */
+  readonly cwd: string;
+  /** 当前项目根目录。 */
+  readonly rootPath: string;
+  /** 统一日志器。 */
+  readonly logger: Logger;
+  /** 当前运行时已解析配置。 */
+  readonly config: DowncityConfig;
+  /** 当前项目环境变量共享视图。 */
+  readonly env: Record<string, string>;
+  /** 当前生效的 system 文本集合。 */
+  readonly systems: string[];
+  /** 当前可见的路径能力集合。 */
+  readonly paths: AgentPathRuntime;
+  /** 当前可见的 plugin 配置持久化能力集合。 */
+  readonly pluginConfig: AgentPluginConfigRuntime;
+  /** Session 能力入口。 */
+  readonly session: SessionCollectionPort;
+  /** Plugin 调用入口。 */
+  readonly plugins: AgentPlugins;
+  /** 跨 plugin runtime 调用主入口。 */
+  readonly invoke: InvokePluginPort;
+
+  constructor(options: AgentContextOptions) {
+    this.agent = options.agent;
+    this.cwd = options.cwd;
+    this.rootPath = options.rootPath;
+    this.logger = options.logger;
+    this.config = options.config;
+    this.env = options.env;
+    this.systems = options.systems;
+    this.paths = options.paths;
+    this.pluginConfig = options.pluginConfig;
+    this.session = options.session;
+    this.plugins = options.plugins;
+    this.invoke = {
+      invoke: (params) => this.invoke_plugin_action(params),
+    };
+  }
+
   /**
-   * Session 能力入口。
+   * 跨 plugin runtime 调用 action 的内部实现。
    *
    * 关键点（中文）
-   * - plugin runtime 与 plugin 都通过这里访问 session 执行与持久化能力。
-   * - 内外统一使用 `sessionId` 语义。
-   */
-  session: SessionCollectionPort;
-  /**
-   * 跨 plugin runtime 调用主入口。
-   */
-  invoke: InvokePluginPort;
-  /**
-   * Plugin 调用入口。
-   */
-  plugins: AgentPlugins;
+   * - 统一把 `runAction` 的成功/失败结果归一化为 `InvokePluginResult`。
+   * - 这里替代了原 `createAgentContext` 工厂里的胶水匿名函数。
+   */
+  private async invoke_plugin_action(
+    params: InvokePluginParams,
+  ): Promise<InvokePluginResult> {
+    const result = await this.plugins.runAction({
+      plugin: params.plugin,
+      action: params.action,
+      ...(params.payload !== undefined ? { payload: params.payload } : {}),
+    });
+    if (!result.success) {
+      return {
+        success: false,
+        error: result.error || result.message || "plugin action failed",
+      };
+    }
+    return {
+      success: true,
+      ...(result.data !== undefined ? { data: result.data } : {}),
+    };
+  }
 }
 
 /**