@downcity/agent 1.1.237 → 1.1.258

package/src/agent/Agent.ts

@@ -0,0 +1,241 @@
+/**
+ * Agent：本地 Agent 核心入口与 facade。
+ *
+ * 职责说明（中文）
+ * - 对外暴露 `Agent` 这一唯一的本地实例类。
+ * - Agent 直接持有自身状态与长期运行时对象，避免额外 Assembly 复制同一批字段。
+ * - Session 集合由 `AgentSessions` 管理；长期运行状态由 `AgentState` 管理。
+ */
+
+import type { Tool } from "ai";
+import type { AgentModel } from "@/agent/AgentModel.js";
+import { AgentContext } from "@/agent/AgentContext.js";
+import type { AgentOptions } from "@/types/agent/AgentOptions.js";
+import type { Shell } from "@downcity/shell";
+import { Logger } from "@/utils/logger/Logger.js";
+import { resolve_agent_env } from "@/config/AgentEnv.js";
+import { normalizeInstructionInput } from "@/agent/AgentInstructions.js";
+import { AgentSessions } from "@/agent/AgentSessions.js";
+import { AgentState } from "@/agent/AgentState.js";
+import { generateId } from "@/utils/Id.js";
+import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+
+/**
+ * SDK 本地 Agent。
+ */
+export class Agent {
+  /** 当前 Agent 的稳定标识，用于区分 Session 存储目录与运行时归属。 */
+  readonly id: string;
+
+  /** 当前 Agent 绑定的项目根目录绝对路径。 */
+  readonly path: string;
+
+  /** 当前 Agent 向所有 Session 提供的工具集合。 */
+  readonly tools: Record<string, Tool>;
+
+  /** 当前 Agent 已装配的 Plugin 调用与注册入口。 */
+  readonly plugins: PluginRegistry;
+
+  /** 当前 Agent 的本地 Session 创建、恢复、查询与归档入口。 */
+  readonly sessions: AgentSessions;
+
+  /**
+   * 当前 Agent 持有的默认运行时模型实例。
+   *
+   * 关键点（中文）
+   * - Agent 只持有调用方传入的实例，不负责模型选择、持久化或恢复。
+   * - Session 未设置自己的模型时，执行会回退使用该实例。
+   */
+  readonly model?: AgentModel;
+
+  /** 当前 Agent 独享的运行日志器。 */
+  private readonly logger: Logger;
+
+  /** 提供给 Plugin、Session 与宿主集成层共享的 Agent 执行上下文。 */
+  private readonly context: AgentContext;
+
+  /** 当前 Agent configured env 的可变共享对象。 */
+  private readonly env: Record<string, string>;
+
+  /** 调用方提供的自定义 Session 类；省略时使用 SDK 默认实现。 */
+  private readonly SessionClass: AgentOptions["Session"];
+
+  /** 当前 Agent 的长期运行状态与生命周期。 */
+  private readonly state: AgentState;
+
+  /** 当前 Agent 可选的内建 Shell 实例。 */
+  private readonly shell?: AgentOptions["shell"];
+
+  /** 当前 Agent configured instruction 的可变有序集合。 */
+  private instruction: string[];
+
+  constructor(options: AgentOptions) {
+    this.id = String(options.id || "").trim();
+    this.path = String(options.path || "").trim();
+    if (!this.id) throw new Error("Agent requires a non-empty id");
+    if (!this.path) throw new Error("Agent requires a non-empty path");
+
+    this.SessionClass = options.Session;
+    this.model = options.model;
+    this.tools = options.tools && typeof options.tools === "object"
+      ? { ...options.tools }
+      : {};
+    this.logger = new Logger();
+    this.logger.bindProjectRoot(this.path);
+    this.env = resolve_agent_env(this.path, options.env);
+    this.instruction = normalizeInstructionInput(options.instruction);
+    this.shell = options.shell;
+
+    this.plugins = new PluginRegistry(options.plugins || []);
+    if (this.shell) {
+      this.shell.configure({
+        root_path: this.path,
+        env: this.env,
+        agent_id: this.id,
+        logger: this.logger,
+      });
+      Object.assign(this.tools, this.shell.tools);
+    }
+
+    this.sessions = new AgentSessions({
+      agent_id: this.id,
+      project_root: this.path,
+      tools: this.tools,
+      logger: this.logger,
+      get_instruction: () => this.instruction,
+      get_agent_env: () => this.getEnv(),
+      get_agent_plugins: () => this.plugins.execution_view(),
+      ensure_agent_ready: async () => {
+        await this.ready();
+      },
+      get_agent_model: () => this.model,
+      SessionClass: this.SessionClass,
+    });
+    this.context = new AgentContext({
+      agent_id: this.id,
+      rootPath: this.path,
+      logger: this.logger,
+      get_env: () => this.env,
+      get_systems: () => this.instruction,
+      sessions: this.sessions,
+      plugins: this.plugins,
+    });
+
+    // 关键点（中文）：装配完成后创建唯一状态对象，并立即启动长期运行时。
+    this.state = new AgentState({
+      context: this.context,
+      plugins: this.plugins,
+      sessions: this.sessions,
+      tools: this.tools,
+      shell: this.shell,
+    });
+  }
+
+  /**
+   * 等待 Agent 持有的长期运行时启动完成。
+   *
+   * 关键点（中文）
+   * - Agent 构造完成即开始启动 plugin lifecycle 与 ActionSchedule。
+   * - 调用方在需要确认运行时就绪时使用，例如启动后立刻读取 plugin 状态。
+   */
+  async ready(): Promise<void> {
+    await this.state.ready();
+  }
+
+  /**
+   * 释放当前 Agent 持有的长期运行时对象。
+   *
+   * 关键点（中文）
+   * - 关闭 plugin lifecycle、ActionSchedule、shell 等 Agent 自有资源。
+   * - 不负责任何 transport（RPC / HTTP）；transport 由 `@downcity/server` 自行管理。
+   */
+  async dispose(): Promise<void> {
+    await this.state.dispose();
+  }
+
+  /**
+   * 更新当前 SDK Agent 的静态基础指令。
+   */
+  setInstruction(input: string | string[]): void {
+    const next_instruction = normalizeInstructionInput(input);
+    this.instruction.splice(0, this.instruction.length, ...next_instruction);
+    this.sessions.broadcast_instruction(this.instruction, generateId());
+  }
+
+  /**
+   * 返回当前 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.apply_env_patch(next);
+    this.sessions.broadcast_env(this.env, generateId());
+  }
+
+  /**
+   * 增量合并 agent env。
+   *
+   * 关键点（中文）
+   * - `null` / `undefined` 表示删除该 key；其他值会强制转字符串后写入。
+   * - configured env 原地更新；已有 Session 在下一 step 检查点提交 effective env。
+   */
+  patchEnv(patch: Record<string, string | null | undefined>): void {
+    this.apply_env_patch(patch);
+    this.sessions.broadcast_env(this.env, generateId());
+  }
+
+  /**
+   * 原地应用一次 env patch，不触发重复广播。
+   */
+  private apply_env_patch(
+    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);
+    }
+  }
+
+  /**
+   * 返回当前 agent 绑定的统一日志器。
+   */
+  getLogger(): Logger {
+    return this.logger;
+  }
+
+  /**
+   * 返回当前 agent context。
+   */
+  getContext(): AgentContext {
+    return this.context;
+  }
+
+  /**
+   * 返回当前 agent 挂载的 Shell。
+   */
+  getShell(): Shell | undefined {
+    return this.shell;
+  }
+}

package/src/agent/AgentContext.ts

@@ -0,0 +1,92 @@
+/**
+ * AgentContext：本地 Agent 的统一执行上下文。
+ *
+ * 职责说明（中文）
+ * - 同一 Agent 实例全程共享同一个 Context。
+ * - 向 Plugin、Session 与宿主投影当前 Agent 的稳定运行时能力。
+ * - Context 不复制 Agent 状态，env 与 systems 始终从唯一状态源读取。
+ */
+
+import type { AgentSessions } from "@/agent/AgentSessions.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/**
+ * AgentContext 构造参数。
+ */
+interface AgentContextOptions {
+  /** 当前 Agent 稳定标识。 */
+  agent_id: string;
+
+  /** 当前项目根目录。 */
+  rootPath: string;
+
+  /** 当前 Agent 统一日志器。 */
+  logger: Logger;
+
+  /** 读取当前 Agent configured env。 */
+  get_env: () => Readonly<Record<string, string>>;
+
+  /** 读取当前 Agent configured systems。 */
+  get_systems: () => readonly string[];
+
+  /** 当前 Agent 直接持有的 Session 集合。 */
+  sessions: AgentSessions;
+
+  /** 当前 Agent 唯一的 Plugin 调用入口。 */
+  plugins: AgentPlugins;
+}
+
+/**
+ * 本地 Agent 的统一执行上下文。
+ */
+export class AgentContext {
+  /** 当前 Agent 稳定标识。 */
+  readonly agent_id: string;
+
+  /** 当前项目根目录。 */
+  readonly rootPath: string;
+
+  /** 当前 Agent 统一日志器。 */
+  readonly logger: Logger;
+
+  /** 当前 Agent configured env 读取器。 */
+  private readonly get_env: AgentContextOptions["get_env"];
+
+  /** 当前 Agent configured systems 读取器。 */
+  private readonly get_systems: AgentContextOptions["get_systems"];
+
+  /** 当前 Agent 直接持有的 Session 集合。 */
+  readonly sessions: AgentSessions;
+
+  /** 当前 Agent 唯一的 Plugin 调用入口。 */
+  readonly plugins: AgentPlugins;
+
+  constructor(options: AgentContextOptions) {
+    this.agent_id = options.agent_id;
+    this.rootPath = options.rootPath;
+    this.logger = options.logger;
+    this.get_env = options.get_env;
+    this.get_systems = options.get_systems;
+    this.sessions = options.sessions;
+    this.plugins = options.plugins;
+  }
+
+  /**
+   * 读取 Agent 已配置的 env。
+   *
+   * 关键点（中文）
+   * - Session step 的 effective env 由 Plugin action 参数 `run_context.agentEnv` 显式提供。
+   * - 该 getter 不根据异步调用链隐式切换结果。
+   */
+  get env(): Readonly<Record<string, string>> {
+    return this.get_env();
+  }
+
+  /**
+   * 读取 Agent 已配置的 instruction。
+   */
+  get systems(): readonly string[] {
+    return this.get_systems();
+  }
+}

package/src/agent/{local/AgentInstructions.ts → AgentInstructions.ts}

@@ -7,20 +7,9 @@
  * - 不读取 session、plugin 或 runtime 状态，保持为纯函数。
  */
 
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import { DEFAULT_SHIP_PROMPTS } from "@executor/composer/system/default/SystemDomain.js";
 
-/**
- * 创建 SDK 场景的最小 fallback 配置。
- */
-export function createFallbackSdkConfig(agent_id: string): DowncityConfig {
-  return {
-    id: agent_id,
-    version: "0.0.0",
-  } as DowncityConfig;
-}
-
 /**
  * 归一化调用方传入的静态 instruction。
  */

package/src/{model/CityModelAdapter.ts → agent/AgentModel.ts}

@@ -1,8 +1,8 @@
 /**
- * CityModel 到 AI SDK LanguageModel 的归一化模块。
+ * AgentModel：Agent 与 Session 统一使用的运行时模型协议。
  *
  * 关键点（中文）
- * - Agent 对外可以接收 CityModel，但 executor 内部只处理 AI SDK LanguageModel。
+ * - Agent 与 Session 对外统一接收 AgentModel，executor 内部只处理 AI SDK LanguageModel。
  * - CityModel 保留模型目录信息；运行时连接信息通过隐藏协议提供。
  * - 这里直接创建 OpenAI-compatible LanguageModel，不再保留旧的 text/stream 反向适配。
  * - 这里不依赖 @downcity/city，只依赖 @downcity/type 的共享协议。
@@ -16,6 +16,9 @@ import {
 } from "@downcity/type";
 import type { LanguageModel } from "ai";
 
+/** 已完成转换的 CityModel 与 LanguageModel 对应关系。 */
+const normalized_models = new WeakMap<object, LanguageModel>();
+
 /**
  * Agent SDK 可接受的模型输入。
  */
@@ -39,7 +42,11 @@ function cityModelToLanguageModel(model: CityModel): LanguageModel {
  */
 export function normalizeAgentModel(model: AgentModel): LanguageModel {
   if (isCityModel(model)) {
-    return cityModelToLanguageModel(model);
+    const cached = normalized_models.get(model);
+    if (cached) return cached;
+    const normalized = cityModelToLanguageModel(model);
+    normalized_models.set(model, normalized);
+    return normalized;
   }
   return model;
 }