@downcity/agent 1.1.129 → 1.1.135

package/bin/types/runtime/agent/AgentContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContext.d.ts","sourceRoot":"","sources":["../../../../src/types/runtime/agent/AgentContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentContext.d.ts","sourceRoot":"","sources":["../../../../src/types/runtime/agent/AgentContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAC;AAC3F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CASzD;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,WAAW,IAAI,mBAAmB,CAAC;IACnC;;OAEG;IACH,eAAe,IAAI,mBAAmB,CAAC;IACvC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACxE;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,EAAE,sBAAsB,GAAG,uBAAuB,CAAC;IACvE;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7C;;OAEG;IACH,aAAa,IAAI,IAAI,CAAC;IACtB;;OAEG;IACH,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE;QACxB;;WAEG;QACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAClC;;WAEG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd;;WAEG;QACH,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;OAEG;IACH,sBAAsB,CAAC,MAAM,EAAE;QAC7B;;WAEG;QACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAClC;;WAEG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;WAEG;QACH,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;OAEG;IACH,uBAAuB,IAAI,MAAM,EAAE,CAAC;IACpC;;OAEG;IACH,wBAAwB,IAAI,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACrE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,yBAAyB;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB;IACnB,KAAK,EAAE,gBAAgB,CAAC;IACxB,8BAA8B;IAC9B,YAAY,EAAE,wBAAwB,CAAC;IACvC,oBAAoB;IACpB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,mBAAmB;IACnB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,gBAAgB;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,eAAe;IACf,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,aAAa;IACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kBAAkB;IAClB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,oBAAoB;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAChD,oBAAoB;IACpB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;gBAEtB,OAAO,EAAE,mBAAmB;IAiBxC;;;;;;OAMG;YACW,oBAAoB;CAmBnC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;CACtC,CAAC"}

package/bin/types/runtime/agent/AgentContext.js

@@ -3,11 +3,85 @@
  *
  * 职责说明（中文）
  * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - `AgentContext` 是一个 class，表达“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
  *
  * 边界说明（中文）
  * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
- * - 这里只定义协议，不负责任何上下文装配逻辑。
+ * - 这里同时声明类型协议与默认实现；plugin 作者拿到的就是这个 class 的实例。
  */
-export {};
+/**
+ * 统一执行上下文。
+ *
+ * 关键点（中文）
+ * - 字段全部 readonly，构造一次后语义稳定，避免 plugin 误改。
+ * - `env` 引用 agent 级共享 mutable 对象，`...ctx.env` / `ctx.env.FOO` 直接可用。
+ * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
+ */
+export class AgentContext {
+    /** 当前执行上下文对应的 agent 状态。 */
+    agent;
+    /** 当前命令工作目录。 */
+    cwd;
+    /** 当前项目根目录。 */
+    rootPath;
+    /** 统一日志器。 */
+    logger;
+    /** 当前运行时已解析配置。 */
+    config;
+    /** 当前项目环境变量共享视图。 */
+    env;
+    /** 当前生效的 system 文本集合。 */
+    systems;
+    /** 当前可见的路径能力集合。 */
+    paths;
+    /** 当前可见的 plugin 配置持久化能力集合。 */
+    pluginConfig;
+    /** Session 能力入口。 */
+    session;
+    /** Plugin 调用入口。 */
+    plugins;
+    /** 跨 plugin runtime 调用主入口。 */
+    invoke;
+    constructor(options) {
+        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),
+        };
+    }
+    /**
+     * 跨 plugin runtime 调用 action 的内部实现。
+     *
+     * 关键点（中文）
+     * - 统一把 `runAction` 的成功/失败结果归一化为 `InvokePluginResult`。
+     * - 这里替代了原 `createAgentContext` 工厂里的胶水匿名函数。
+     */
+    async invoke_plugin_action(params) {
+        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 } : {}),
+        };
+    }
+}
 //# sourceMappingURL=AgentContext.js.map

package/bin/types/runtime/agent/AgentContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentContext.js","sourceRoot":"","sources":["../../../../src/types/runtime/agent/AgentContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}
+{"version":3,"file":"AgentContext.js","sourceRoot":"","sources":["../../../../src/types/runtime/agent/AgentContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqPH;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACvB,2BAA2B;IAClB,KAAK,CAAe;IAC7B,gBAAgB;IACP,GAAG,CAAS;IACrB,eAAe;IACN,QAAQ,CAAS;IAC1B,aAAa;IACJ,MAAM,CAAS;IACxB,kBAAkB;IACT,MAAM,CAAiB;IAChC,oBAAoB;IACX,GAAG,CAAyB;IACrC,yBAAyB;IAChB,OAAO,CAAW;IAC3B,mBAAmB;IACV,KAAK,CAAmB;IACjC,8BAA8B;IACrB,YAAY,CAA2B;IAChD,oBAAoB;IACX,OAAO,CAAwB;IACxC,mBAAmB;IACV,OAAO,CAAe;IAC/B,8BAA8B;IACrB,MAAM,CAAmB;IAElC,YAAY,OAA4B;QACtC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG;YACZ,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC;SACtD,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,oBAAoB,CAChC,MAA0B;QAE1B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;YAC1C,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,sBAAsB;aAChE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.129",
+  "version": "1.1.135",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -17,8 +17,8 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@downcity/shell": "^0.1.17",
-    "@downcity/type": "0.1.52",
+    "@downcity/shell": "^0.1.19",
+    "@downcity/type": "0.1.54",
     "@larksuiteoapi/node-sdk": "^1.66.0",
     "ai": "^6.0.193",
     "commander": "^15.0.0",

package/src/agent/local/Agent.ts

@@ -20,9 +20,6 @@ import type {
   AgentSession,
   AgentSessionCollection,
   AgentSessionSummaryPage,
-  AgentStartOptions,
-  AgentStartResult,
-  AgentStopResult,
 } from "@/types/agent/AgentTypes.js";
 import type {
   ShellApprovalMode,
@@ -41,7 +38,7 @@ import {
   type AgentAssemblyResult,
 } from "@/agent/local/services/AgentAssemblyService.js";
 import { AgentSessionManager } from "@/agent/local/services/AgentSessionManager.js";
-import { AgentLifecycleService } from "@/agent/local/services/AgentLifecycleService.js";
+import { AgentBackgroundService } from "@/agent/local/services/AgentBackgroundService.js";
 
 /**
  * SDK 本地 Agent。
@@ -61,7 +58,7 @@ export class Agent {
   private readonly defaultModel?: AgentModel;
   private readonly SessionClass: AgentOptions["Session"];
   private readonly sessionManager: AgentSessionManager;
-  private readonly lifecycleService: AgentLifecycleService;
+  private readonly backgroundService: AgentBackgroundService;
   private readonly shell?: AgentOptions["shell"];
 
   private instruction: string[];
@@ -102,11 +99,10 @@ export class Agent {
 
     this.sessionManager = this.create_session_manager(assembly);
     session_manager_ref = this.sessionManager;
-    this.lifecycleService = new AgentLifecycleService({
+    // 关键点（中文）：构造完成即触发后台能力启动；调用方可 `await agent.ready()` 等待。
+    this.backgroundService = new AgentBackgroundService({
       logger: this.logger,
       agent_context: this.agentContext,
-      session_collection: this.sessionManager.get_session_collection(),
-      get_runtime: () => this.runtime,
       get_shell: () => this.shell,
     });
   }
@@ -135,17 +131,25 @@ export class Agent {
   }
 
   /**
-   * 启动当前 agent 实例的长期运行能力。
+   * 等待 Agent 后台能力启动完成。
+   *
+   * 关键点（中文）
+   * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
+   * - 调用方在需要确认后台能力就绪时使用，例如启动后立刻读取 plugin 状态。
    */
-  async start(options?: AgentStartOptions): Promise<AgentStartResult> {
-    return await this.lifecycleService.start(options);
+  async ready(): Promise<void> {
+    await this.backgroundService.ready();
   }
 
   /**
-   * 停止当前 agent 实例的长期运行能力。
+   * 释放当前 Agent 的后台能力。
+   *
+   * 关键点（中文）
+   * - 关闭 plugin lifecycle、ActionSchedule、shell 等后台资源。
+   * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
    */
-  async stop(): Promise<AgentStopResult> {
-    return await this.lifecycleService.stop();
+  async dispose(): Promise<void> {
+    await this.backgroundService.dispose();
   }
 
   /**
@@ -204,6 +208,51 @@ export class Agent {
     this.instruction = normalizeInstructionInput(input);
   }
 
+  /**
+   * 返回当前 agent env 的浅拷贝快照。
+   *
+   * 关键点（中文）
+   * - 返回的是拷贝，调用方修改它不会影响 agent 真实状态。
+   * - 想改 env 请使用 `setEnv` / `patchEnv`。
+   */
+  getEnv(): Record<string, string> {
+    return { ...this.env };
+  }
+
+  /**
+   * 整体覆盖 agent env。
+   *
+   * 关键点（中文）
+   * - 直接清空当前共享 env 对象，再写入新值，保证 plugin / runtime / shell 看到的是同一引用。
+   * - 仅写入字符串值，`null` / `undefined` 表示删除该 key。
+   */
+  setEnv(next: Record<string, string | null | undefined>): void {
+    for (const key of Object.keys(this.env)) {
+      delete this.env[key];
+    }
+    this.patchEnv(next);
+  }
+
+  /**
+   * 增量合并 agent env。
+   *
+   * 关键点（中文）
+   * - `null` / `undefined` 表示删除该 key；其他值会强制转字符串后写入。
+   * - 修改原地生效，所有持有 `context.env` 引用的模块立即可见。
+   */
+  patchEnv(patch: Record<string, string | null | undefined>): void {
+    if (!patch || typeof patch !== "object") return;
+    for (const [raw_key, raw_value] of Object.entries(patch)) {
+      const key = String(raw_key || "").trim();
+      if (!key) continue;
+      if (raw_value === null || raw_value === undefined) {
+        delete this.env[key];
+        continue;
+      }
+      this.env[key] = String(raw_value);
+    }
+  }
+
   /**
    * 返回当前项目根目录解析后的配置快照。
    */

package/src/agent/local/AgentRuntimeFactory.ts

@@ -2,21 +2,16 @@
  * Agent runtime / context 装配工厂。
  *
  * 关键点（中文）
- * - 这里只创建长期 runtime 视图与执行期 context 视图。
+ * - 这里只创建长期 runtime 视图。
+ * - `AgentContext` 已经收敛为 class，调用方直接 `new AgentContext(...)`，不再走工厂。
  * - Agent 仍然持有 session/plugin 状态；这里通过函数参数读取状态。
  */
 
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { LanguageModel } from "ai";
-import type { JsonValue } from "@/types/common/Json.js";
-import type {
-  AgentContext,
-  SessionPort,
-} from "@/types/runtime/agent/AgentContext.js";
+import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
-import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type { AgentManagedSession } from "@/types/agent/AgentTypes.js";
 import {
   createAgentPathRuntime,
@@ -35,7 +30,12 @@ export interface CreateAgentRuntimeOptions {
   logger: Logger;
   /** 当前解析后的配置。 */
   config: DowncityConfig;
-  /** 当前环境变量快照。 */
+  /**
+   * 当前 agent 共享 env 对象。
+   *
+   * 关键点（中文）
+   * - 必须传入 Agent 持有的同一份 mutable 对象，runtime / context 直接复用同一引用。
+   */
   env: Record<string, string>;
   /** 当前静态 system 文本集合。 */
   systems: string[];
@@ -47,32 +47,6 @@ export interface CreateAgentRuntimeOptions {
   list_cached_sessions: () => AgentManagedSession[];
 }
 
-/**
- * 创建 AgentContext 的参数。
- */
-export interface CreateAgentContextOptions {
-  /** 当前 AgentRuntime。 */
-  runtime: AgentRuntime;
-  /** 当前项目根目录。 */
-  project_root: string;
-  /** 统一日志器。 */
-  logger: Logger;
-  /** 当前解析后的配置。 */
-  config: DowncityConfig;
-  /** 当前环境变量快照。 */
-  env: Record<string, string>;
-  /** 当前静态 system 文本集合。 */
-  systems: string[];
-  /** 当前 plugin 实例集合。 */
-  plugin_instances: Map<string, BasePlugin>;
-  /** 对外 plugin 调用端口。 */
-  plugins: AgentPlugins;
-  /** 获取或创建 session runtime port。 */
-  get_session_port: (session_id: string) => SessionPort;
-  /** 解析 session 当前绑定的模型实例。 */
-  resolve_session_model: (session_id: string) => Promise<LanguageModel | undefined>;
-}
-
 /**
  * 创建实例级 runtime 视图。
  */
@@ -102,51 +76,3 @@ export function createAgentRuntime(
     pluginInstances: options.plugin_instances,
   };
 }
-
-/**
- * 创建统一执行上下文。
- */
-export function createAgentContext(
-  options: CreateAgentContextOptions,
-): AgentContext {
-  let context!: AgentContext;
-  context = {
-    agent: options.runtime,
-    cwd: options.project_root,
-    rootPath: options.project_root,
-    logger: options.logger,
-    config: options.config,
-    env: options.env,
-    systems: options.systems,
-    paths: options.runtime.paths,
-    pluginConfig: options.runtime.pluginConfig,
-    session: {
-      get: (session_id) => options.get_session_port(session_id),
-      listExecutingSessionIds: () => options.runtime.listExecutingSessionIds(),
-      getExecutingSessionCount: () => options.runtime.getExecutingSessionCount(),
-      resolveModel: async (session_id) =>
-        await options.resolve_session_model(session_id),
-    },
-    invoke: {
-      invoke: async (params: {
-        plugin: string;
-        action: string;
-        payload?: JsonValue;
-      }) => {
-        const result = await options.plugins.runAction(params);
-        if (!result.success) {
-          return {
-            success: false,
-            error: result.error || result.message || "plugin action failed",
-          };
-        }
-        return {
-          success: true,
-          ...(result.data !== undefined ? { data: result.data } : {}),
-        };
-      },
-    },
-    plugins: options.plugins,
-  };
-  return context;
-}

package/src/agent/local/services/AgentAssemblyService.ts

@@ -9,7 +9,7 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
@@ -25,7 +25,6 @@ import {
   createAgentPluginRegistry,
 } from "@/agent/local/AgentPluginFactory.js";
 import {
-  createAgentContext,
   createAgentRuntime,
 } from "@/agent/local/AgentRuntimeFactory.js";
 import {
@@ -165,6 +164,9 @@ export class AgentAssemblyService {
 
     const logger = new Logger();
     logger.bindProjectRoot(path);
+    // 关键点（中文）
+    // - 这里产出的 env 是 agent 全生命周期共享的 mutable 对象引用。
+    // - runtime / context / shell 都持有同一引用；后续 `agent.setEnv()` 会原地修改它。
     const env = resolveAgentEnv(path, this.options.env);
     const instruction = normalizeInstructionInput(this.options.instruction);
     const config = this.load_config(id, path);
@@ -184,27 +186,42 @@ export class AgentAssemblyService {
 
     this.register_plugins(plugin_instances, this.options.plugins || []);
 
-    let agent_context!: AgentContext;
+    // 关键点（中文）
+    // - plugin_registry 仍然延迟读取 agent_context（避免循环依赖）。
+    // - context 一构造完就赋值，registry 第一次读 get_context 时已经是非空。
+    let agent_context: AgentContext | undefined;
     const plugin_registry = createAgentPluginRegistry({
       plugins: [...plugin_instances.values()],
-      get_context: () => agent_context,
+      get_context: () => {
+        if (!agent_context) {
+          throw new Error("AgentContext is not assembled yet");
+        }
+        return agent_context;
+      },
     });
     const plugins = plugin_registry;
     if (this.should_register_plugin_call_tool(plugin_instances)) {
       tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
     }
-    agent_context = createAgentContext({
-      runtime,
-      project_root: path,
+    const resolve_session_model = this.resolve_session_model;
+    agent_context = new AgentContext({
+      agent: runtime,
+      cwd: path,
+      rootPath: path,
       logger,
       config,
       env,
       systems: instruction,
-      plugin_instances,
+      paths: runtime.paths,
+      pluginConfig: runtime.pluginConfig,
+      session: {
+        get: (session_id) => this.get_session_port(session_id),
+        listExecutingSessionIds: () => runtime.listExecutingSessionIds(),
+        getExecutingSessionCount: () => runtime.getExecutingSessionCount(),
+        resolveModel: async (session_id) =>
+          await resolve_session_model(session_id),
+      },
       plugins,
-      get_session_port: this.get_session_port,
-      resolve_session_model: async (session_id) =>
-        await this.resolve_session_model(session_id),
     });
     const shell = this.options.shell;
     if (shell) {
@@ -216,7 +233,7 @@ export class AgentAssemblyService {
         emit_event: (event) => {
           const session_id = String(event.session_id || "").trim();
           if (!session_id) return;
-          agent_context.session.get(session_id).publishEvent(event as unknown as AgentSessionEvent);
+      agent_context!.session.get(session_id).publishEvent(event as unknown as AgentSessionEvent);
         },
       });
       Object.assign(tools, shell.tools);
@@ -235,7 +252,7 @@ export class AgentAssemblyService {
       plugin_registry,
       plugins,
       runtime,
-      agent_context,
+      agent_context: agent_context!,
       ...(shell ? { shell } : {}),
     };
   }

package/src/agent/local/services/AgentBackgroundService.ts

@@ -0,0 +1,116 @@
+/**
+ * AgentBackgroundService：本地 Agent 后台能力生命周期服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 plugins 与 ActionSchedule 的启动 / 停止。
+ * - 在 Agent 构造阶段自动启动后台能力，调用方通过 `await agent.ready()` 等待启动完成。
+ * - RPC / HTTP 等 transport 不再属于 Agent 内部职责，由 `@downcity/server` 等外部包按需挂载。
+ */
+
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { ActionScheduleRuntimeHandle } from "@/plugin/core/ActionScheduleRuntime.js";
+import { startActionScheduleRuntime } from "@/plugin/core/ActionScheduleRuntime.js";
+import { startAllPlugins, stopAllPlugins } from "@/plugin/core/Manager.js";
+import type { Shell } from "@downcity/shell";
+
+type AgentBackgroundServiceOptions = {
+  /**
+   * 当前统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 agent context。
+   */
+  agent_context: AgentContext;
+
+  /**
+   * 读取当前 agent 挂载的 Shell。
+   */
+  get_shell?: () => Shell | undefined;
+};
+
+/**
+ * 本地 Agent 后台能力生命周期服务。
+ *
+ * 关键点（中文）
+ * - 构造时自动触发 plugin lifecycle 与 ActionSchedule 启动。
+ * - 失败由 logger.error 记录，不抛错；调用方通过 `ready()` 等待启动完成。
+ */
+export class AgentBackgroundService {
+  private readonly logger: Logger;
+  private readonly agent_context: AgentContext;
+  private readonly get_shell: AgentBackgroundServiceOptions["get_shell"];
+
+  private plugins_started = false;
+  private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
+  private ready_promise: Promise<void> | null = null;
+
+  constructor(options: AgentBackgroundServiceOptions) {
+    this.logger = options.logger;
+    this.agent_context = options.agent_context;
+    this.get_shell = options.get_shell;
+    // 关键点（中文）：Agent 构造完成即触发后台启动，不再要求外部显式 `start()`。
+    this.ready_promise = this.boot();
+  }
+
+  /**
+   * 等待后台能力启动完成。
+   */
+  async ready(): Promise<void> {
+    if (!this.ready_promise) return;
+    await this.ready_promise;
+  }
+
+  /**
+   * 释放当前 Agent 的后台能力。
+   */
+  async dispose(): Promise<void> {
+    if (this.ready_promise) {
+      await this.ready_promise.catch(() => undefined);
+      this.ready_promise = null;
+    }
+    if (this.plugins_started) {
+      await this.stop_action_schedule_runtime();
+      await stopAllPlugins(this.agent_context);
+      this.plugins_started = false;
+    }
+    await this.get_shell?.()?.dispose();
+  }
+
+  private async boot(): Promise<void> {
+    await this.ensure_plugins_started();
+  }
+
+  private async ensure_plugins_started(): Promise<void> {
+    if (this.plugins_started) return;
+    const lifecycle = await startAllPlugins(this.agent_context);
+    this.plugins_started = true;
+    for (const item of lifecycle.results) {
+      if (!item.success) {
+        this.logger.error(
+          `Plugin start failed: ${item.plugin?.name || "unknown"} - ${item.error || "unknown error"}`,
+        );
+      }
+    }
+    await this.ensure_action_schedule_runtime_started();
+  }
+
+  private async ensure_action_schedule_runtime_started(): Promise<void> {
+    if (this.action_schedule_runtime) return;
+    try {
+      this.action_schedule_runtime = await startActionScheduleRuntime(
+        this.agent_context,
+      );
+    } catch (error) {
+      this.logger.error(`ActionSchedule start failed: ${String(error)}`);
+    }
+  }
+
+  private async stop_action_schedule_runtime(): Promise<void> {
+    const runtime = this.action_schedule_runtime;
+    this.action_schedule_runtime = null;
+    runtime?.stop();
+  }
+}

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -493,6 +493,28 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     });
   }
 
+  /**
+   * 批量追加消息。
+   *
+   * 关键点（中文）
+   * - 一次锁、一次 IO，适合 fork 等需要拷贝整段历史的场景。
+   * - 不处理 inflight，调用方需自行确保历史已经收口。
+   */
+  async appendMany(messages: SessionMessageV1[]): Promise<void> {
+    if (!Array.isArray(messages) || messages.length === 0) return;
+    const normalized_list = messages
+      .map((message) => this.normalizePersistedMessage(message))
+      .filter((message): message is SessionMessageV1 => message !== null);
+    if (normalized_list.length === 0) return;
+
+    const payload = normalized_list
+      .map((message) => `${JSON.stringify(message)}\n`)
+      .join("");
+    await this.withWriteLock(async () => {
+      await fs.appendFile(this.getMessagesFilePath(), payload, "utf8");
+    });
+  }
+
   async readInflight(): Promise<SessionMessageV1 | null> {
     await this.ensureLayout();
     return this.readInflightUnsafe();

package/src/index.ts

@@ -26,11 +26,6 @@ export type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
   AgentOptions,
-  AgentRpcBinding,
-  AgentRpcStartOptions,
-  AgentStartOptions,
-  AgentStartResult,
-  AgentStopResult,
   RemoteAgentOptions,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
@@ -61,8 +56,9 @@ export type {
   AgentSessionTurnResult,
 } from "./types/sdk/AgentSessionTurn.js";
 export type { AgentRuntime, AgentRuntimeBase } from "./types/runtime/agent/AgentRuntime.js";
+export { AgentContext } from "./types/runtime/agent/AgentContext.js";
 export type {
-  AgentContext,
+  AgentContextOptions,
   InvokePluginPort,
   SessionCollectionPort,
   SessionPort,
@@ -130,9 +126,6 @@ export {
   registerPluginActionCommandsForCli,
 } from "./plugin/core/PluginCommand.js";
 
-// Agent RPC 集成
-export { startRpcServer } from "./rpc/Server.js";
-
 // Runtime plugin 运行集成
 export {
   startAllPlugins,

package/src/session/services/SessionViewService.ts

@@ -302,13 +302,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
     },
     messages: SessionMessageV1[],
   ): Promise<void> {
-    for (const message of messages) {
-      await forked_bundle.history_store.append(message);
-    }
-    await forked_bundle.state_service.ensure_title_from_history({
-      generate: true,
-    });
-    await forked_bundle.state_service.touch_metadata();
+    await forked_bundle.history_store.appendMany(messages);
   }
 
   private stringify_system_content(content: unknown): string {