@downcity/agent 1.1.129 → 1.1.148

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

@@ -3,11 +3,103 @@
  *
  * 职责说明（中文）
  * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - `AgentContext` 是一个 class，表达"当前一次执行可见的能力面"，不是宿主状态本体。
+ * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
+ */
+/**
+ * 统一执行上下文。
  *
- * 边界说明（中文）
- * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
- * - 这里只定义协议，不负责任何上下文装配逻辑。
+ * 关键点（中文）
+ * - 字段全部 readonly，构造一次后语义稳定，避免 plugin 误改。
+ * - `env` 引用 agent 级共享 mutable 对象，`...ctx.env` / `ctx.env.FOO` 直接可用。
+ * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
  */
-export {};
+export class AgentContext {
+    /** 当前命令工作目录。 */
+    cwd;
+    /** 当前项目根目录。 */
+    rootPath;
+    /** 统一日志器。 */
+    logger;
+    /** 当前运行时已解析配置。 */
+    config;
+    /** 当前项目环境变量共享视图。 */
+    env;
+    /** 当前生效的 system 文本集合。 */
+    systems;
+    /** 当前可见的路径能力集合。 */
+    paths;
+    /** 当前可见的 plugin 配置持久化能力集合。 */
+    pluginConfig;
+    /** 当前 agent 持有的插件实例集合。 */
+    pluginInstances;
+    /** Session 能力入口。 */
+    session;
+    /** Plugin 调用入口。 */
+    plugins;
+    /** 跨 plugin runtime 调用主入口。 */
+    invoke;
+    constructor(options) {
+        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.pluginInstances = options.pluginInstances;
+        this.session = options.session;
+        this.plugins = options.plugins;
+        this.invoke = {
+            invoke: (params) => this.invoke_plugin_action(params),
+        };
+    }
+    /**
+     * 读取指定 sessionId 对应的 session 端口。
+     *
+     * 关键点（中文）
+     * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
+     * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
+     */
+    getSession(sessionId) {
+        return this.session.get(sessionId);
+    }
+    /**
+     * 返回当前执行中的 sessionId 列表。
+     */
+    listExecutingSessionIds() {
+        return this.session.listExecutingSessionIds();
+    }
+    /**
+     * 返回当前执行中的 session 数量。
+     */
+    getExecutingSessionCount() {
+        return this.session.getExecutingSessionCount();
+    }
+    /**
+     * 跨 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;;;;;;;GAOG;AA2PH;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACvB,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,0BAA0B;IACjB,eAAe,CAA0B;IAClD,oBAAoB;IACX,OAAO,CAAwB;IACxC,mBAAmB;IACV,OAAO,CAAe;IAC/B,8BAA8B;IACrB,MAAM,CAAmB;IAElC,YAAY,OAA4B;QACtC,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,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,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;IACH,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,uBAAuB;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,wBAAwB;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,wBAAwB,EAAE,CAAC;IACjD,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/bin/types/runtime/platform/Platform.d.ts

@@ -23,7 +23,7 @@ export interface PlatformAgentOption {
      */
     projectRoot: string;
     /**
-     * 当前 Town 托管的 Agent 进程是否存活。
+     * 当前 downcity 托管的 Agent 进程是否存活。
      */
     running: boolean;
     /**
@@ -51,11 +51,11 @@ export interface PlatformAgentOption {
      */
     stoppedAt?: string;
     /**
-     * 当前读取到的 Town 托管进程 pid（仅 running=true 时有值）。
+     * 当前读取到的 downcity 托管进程 pid（仅 running=true 时有值）。
      */
     daemonPid?: number;
     /**
-     * Town 托管进程日志路径（用于排障展示）。
+     * downcity 托管进程日志路径（用于排障展示）。
      */
     logPath?: string;
     /**
@@ -141,7 +141,7 @@ export interface PlatformAgentDirectoryInspection {
     /** 该目录是否已出现在 managed agent registry 中。 */
     knownAgent: boolean;
     /**
-     * 若已登记，当前 Town 托管进程是否运行中。
+     * 若已登记，当前 downcity 托管进程是否运行中。
      */
     running: boolean;
     /**
@@ -297,7 +297,7 @@ export interface ManagedAgentRegistryEntry {
      */
     projectRoot: string;
     /**
-     * registry 最近一次记录的 Town 托管进程 pid。
+     * registry 最近一次记录的 downcity 托管进程 pid。
      */
     pid: number;
     /**
@@ -335,7 +335,7 @@ export interface ManagedAgentRegistryV1 {
     agents: ManagedAgentRegistryEntry[];
 }
 /**
- * `town agent list --running` 输出可复用的受管 agent 运行态视图。
+ * `downcity agent list --running` 输出可复用的受管 agent 运行态视图。
  */
 export interface ManagedAgentProcessView {
     /**
@@ -347,7 +347,7 @@ export interface ManagedAgentProcessView {
      */
     registeredPid: number;
     /**
-     * 当前实际存活的 Town 托管进程 pid。
+     * 当前实际存活的 downcity 托管进程 pid。
      */
     daemonPid: number;
     /**
@@ -363,7 +363,7 @@ export interface ManagedAgentProcessView {
      */
     updatedAt: string;
     /**
-     * Town 托管进程日志文件路径。
+     * downcity 托管进程日志文件路径。
      */
     logPath: string;
 }

package/bin/types/runtime/platform/PlatformGateway.d.ts

@@ -96,11 +96,11 @@ export interface PlatformAgentShipPluginsConfig {
  */
 export interface PlatformAgentShipStartConfig {
     /**
-     * Town Agent HTTP gateway host。
+     * downcity Agent HTTP gateway host。
      */
     host?: unknown;
     /**
-     * Town Agent HTTP gateway port。
+     * downcity Agent HTTP gateway port。
      */
     port?: unknown;
 }

package/bin/types/sdk/AgentSessionStop.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent Session stop 类型定义。
+ *
+ * 关键点（中文）
+ * - `session.stop()` 用于停止当前正在执行的 turn。
+ * - 尚未被当前 turn 吸收的排队 prompt 会被取消，不会自动开启下一轮。
+ */
+/**
+ * Session stop 的最终结果。
+ */
+export interface AgentSessionStopResult {
+    /**
+     * 本次调用是否实际停止了活跃 turn 或取消了排队 prompt。
+     */
+    stopped: boolean;
+    /**
+     * 被停止的当前 turn 标识。
+     *
+     * 说明（中文）
+     * - 当前没有活跃 turn 时不会返回该字段。
+     * - 如果只是清空尚未启动的队列，也不会返回该字段。
+     */
+    turnId?: string;
+    /**
+     * 本次 stop 取消的未绑定 prompt 数量。
+     *
+     * 说明（中文）
+     * - 已经被当前 turn 吸收的 prompt 不计入这里，它们会随当前 turn 一起结束。
+     */
+    cancelledQueuedPrompts: number;
+    /**
+     * 本次 stop 的归因。
+     */
+    reason: "stopped" | "idle";
+}
+//# sourceMappingURL=AgentSessionStop.d.ts.map

package/bin/types/sdk/AgentSessionStop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionStop.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionStop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;CAC5B"}

package/bin/types/sdk/AgentSessionStop.js

@@ -0,0 +1,9 @@
+/**
+ * Agent Session stop 类型定义。
+ *
+ * 关键点（中文）
+ * - `session.stop()` 用于停止当前正在执行的 turn。
+ * - 尚未被当前 turn 吸收的排队 prompt 会被取消，不会自动开启下一轮。
+ */
+export {};
+//# sourceMappingURL=AgentSessionStop.js.map

package/bin/types/sdk/AgentSessionStop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionStop.js","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionStop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.129",
+  "version": "1.1.148",
   "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.28",
+    "@downcity/type": "0.1.62",
     "@larksuiteoapi/node-sdk": "^1.66.0",
     "ai": "^6.0.193",
     "commander": "^15.0.0",

package/scripts/city-model-tool-loop.test.mjs

@@ -230,7 +230,7 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
     const city = new City({
       role: "user",
       city_url: `http://127.0.0.1:${String(address.port)}`,
-      town_id: "town_demo",
+      city_id: "city_demo",
       user_token: "ub_test",
     });
     const catalog = await city.ai.listModels();
@@ -266,7 +266,7 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
     assert.equal(tool_executed, true);
     assert.equal(stream_requests, 0);
     assert.equal(agent_requests.length, 2);
-    assert.equal(requests.every((request) => request?.town_id === "town_demo"), true);
+    assert.equal(requests.every((request) => request?.city_id === "city_demo"), true);
     assert.equal(agent_requests[0]?.model, "mock-model");
 
     const second_request_messages = Array.isArray(agent_requests[1]?.messages)

package/scripts/session-prompt-runtime.test.mjs

@@ -98,6 +98,7 @@ test("SessionPromptRuntime merges queued prompts at the next step boundary", asy
         assistantMessage: createAssistantMessage("done", 1),
       };
     },
+    stopTurn: () => false,
   });
 
   const firstTurn = await runtime.prompt({ query: "first" });
@@ -159,6 +160,7 @@ test("SessionPromptRuntime moves unmerged prompts into the next turn", async ()
         ),
       };
     },
+    stopTurn: () => false,
   });
 
   const firstTurn = await runtime.prompt({ query: "first" });
@@ -185,3 +187,60 @@ test("SessionPromptRuntime moves unmerged prompts into the next turn", async ()
     ["turn-start", "turn-finish", "turn-start", "turn-finish"],
   );
 });
+
+test("SessionPromptRuntime stops current turn and cancels unmerged queued prompts", async () => {
+  const events = [];
+  const executionFinished = createDeferred();
+  let stopRequested = false;
+
+  const runtime = new SessionPromptRuntime({
+    sessionId: "test",
+    publish: (event) => {
+      events.push(event);
+    },
+    createAndPersistUserMessage: async (input) => {
+      return createUserMessage(input.query, events.length + 1);
+    },
+    executeTurn: async (input) => {
+      await new Promise((resolve) => {
+        input.abortSignal.addEventListener("abort", resolve, { once: true });
+      });
+      await executionFinished.promise;
+      return {
+        text: "should-not-succeed",
+        success: true,
+        assistantMessage: createAssistantMessage("should-not-succeed", 1),
+      };
+    },
+    stopTurn: () => {
+      stopRequested = true;
+      executionFinished.resolve();
+      return true;
+    },
+  });
+
+  const firstTurn = await runtime.prompt({ query: "first" });
+  const secondTurnPromise = runtime.prompt({ query: "second" });
+  await waitUntil(() => runtime.isActive());
+
+  const stopResult = runtime.stop();
+  const secondTurn = await secondTurnPromise;
+  const firstResult = await firstTurn.finished;
+  const secondResult = await secondTurn.finished;
+
+  assert.equal(stopRequested, true);
+  assert.equal(stopResult.stopped, true);
+  assert.equal(stopResult.turnId, firstTurn.id);
+  assert.equal(stopResult.cancelledQueuedPrompts, 1);
+  assert.equal(firstResult.success, false);
+  assert.equal(firstResult.error, "Turn stopped");
+  assert.equal(secondResult.success, false);
+  assert.equal(
+    secondResult.error,
+    "Prompt cancelled because session was stopped",
+  );
+  assert.deepEqual(
+    events.map((event) => event.type),
+    ["turn-start", "turn-start", "turn-finish", "turn-finish"],
+  );
+});

package/src/agent/local/Agent.ts

@@ -9,20 +9,12 @@
 
 import type { Tool } from "ai";
 import type { 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";
 import type {
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
   AgentModel,
   AgentOptions,
-  AgentSession,
   AgentSessionCollection,
-  AgentSessionSummaryPage,
-  AgentStartOptions,
-  AgentStartResult,
-  AgentStopResult,
 } from "@/types/agent/AgentTypes.js";
 import type {
   ShellApprovalMode,
@@ -41,7 +33,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。
@@ -53,7 +45,6 @@ export class Agent {
   readonly plugins: AgentPlugins;
 
   private readonly logger: Logger;
-  private readonly runtime: AgentRuntime;
   private readonly agentContext: AgentContext;
   private readonly pluginRegistry: PluginRegistry;
   private readonly config: DowncityConfig;
@@ -61,7 +52,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[];
@@ -92,7 +83,6 @@ export class Agent {
     this.tools = assembly.tools;
     this.plugins = assembly.plugins;
     this.logger = assembly.logger;
-    this.runtime = assembly.runtime;
     this.agentContext = assembly.agent_context;
     this.pluginRegistry = assembly.plugin_registry;
     this.config = assembly.config;
@@ -102,50 +92,34 @@ 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,
     });
   }
 
   /**
-   * 新建一个 session。
+   * 等待 Agent 后台能力启动完成。
+   *
+   * 关键点（中文）
+   * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
+   * - 调用方在需要确认后台能力就绪时使用，例如启动后立刻读取 plugin 状态。
    */
-  async createSession(input?: AgentCreateSessionInput): Promise<AgentSession> {
-    return await this.sessionManager.create_session(input);
+  async ready(): Promise<void> {
+    await this.backgroundService.ready();
   }
 
   /**
-   * 获取一个已存在的 session。
+   * 释放当前 Agent 的后台能力。
+   *
+   * 关键点（中文）
+   * - 关闭 plugin lifecycle、ActionSchedule、shell 等后台资源。
+   * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
    */
-  async getSession(sessionId: string): Promise<AgentSession> {
-    return await this.sessionManager.get_session(sessionId);
-  }
-
-  /**
-   * 列出当前 agent 的 session 摘要页。
-   */
-  async listSessions(
-    input?: AgentListSessionsInput,
-  ): Promise<AgentSessionSummaryPage> {
-    return await this.sessionManager.list_sessions(input);
-  }
-
-  /**
-   * 启动当前 agent 实例的长期运行能力。
-   */
-  async start(options?: AgentStartOptions): Promise<AgentStartResult> {
-    return await this.lifecycleService.start(options);
-  }
-
-  /**
-   * 停止当前 agent 实例的长期运行能力。
-   */
-  async stop(): Promise<AgentStopResult> {
-    return await this.lifecycleService.stop();
+  async dispose(): Promise<void> {
+    await this.backgroundService.dispose();
   }
 
   /**
@@ -204,6 +178,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);
+    }
+  }
+
   /**
    * 返回当前项目根目录解析后的配置快照。
    */
@@ -218,13 +237,6 @@ export class Agent {
     return this.logger;
   }
 
-  /**
-   * 返回当前 agent runtime。
-   */
-  getRuntime(): AgentRuntime {
-    return this.runtime;
-  }
-
   /**
    * 返回当前 agent context。
    */
@@ -233,9 +245,9 @@ export class Agent {
   }
 
   /**
-   * 返回当前 session collection。
+   * 返回当前 session collection 入口。
    */
-  getSessionCollection(): AgentSessionCollection {
+  session_collection(): AgentSessionCollection {
     return this.sessionManager.get_session_collection();
   }
 
@@ -254,8 +266,7 @@ export class Agent {
       project_root: this.path || assembly.path,
       tools: this.tools || assembly.tools,
       logger: this.logger || assembly.logger,
-      runtime: this.runtime || assembly.runtime,
-      get_agent_context: () => this.agentContext || assembly.agent_context,
+      get_agent_context: () => this.agentContext ?? assembly.agent_context,
       get_instruction: () => this.instruction,
       plugin_instances: assembly.plugin_instances,
       default_model: this.defaultModel,

package/src/agent/local/ProjectSetup.ts

@@ -30,14 +30,14 @@ function ensureContextFiles(projectRoot: string): void {
   // Check if initialized（启动入口一次性确认工程根目录与关键文件）
   if (!fs.existsSync(getProfileMdPath(projectRoot))) {
     console.error(
-      '❌ Project not initialized. Please run "town agent create" first',
+      '❌ Project not initialized. Please run "downcity agent create" first',
     );
     process.exit(1);
   }
 
   if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
     console.error(
-      '❌ downcity.json does not exist. Please run "town agent create" first',
+      '❌ downcity.json does not exist. Please run "downcity agent create" first',
     );
     process.exit(1);
   }