@downcity/agent 1.1.73 → 1.1.79

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

@@ -1,5 +1,5 @@
 /**
- * Agent 本地入口与实例装配中心。
+ * Agent local：本地入口与实例装配中心。
  *
  * 职责说明（中文）
  * - 对外暴露 `Agent` 这一唯一的本地实例类。
@@ -15,18 +15,10 @@ import fs from "fs-extra";
 import { nanoid } from "nanoid";
 import type { Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type {
-  AgentContext,
-  SessionPort,
-} from "@/types/runtime/agent/AgentContext.js";
+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 { JsonValue } from "@/types/common/Json.js";
-import type {
-  PluginAvailability,
-  PluginPort,
-  PluginView,
-} from "@/plugin/types/Plugin.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
 import type {
   AgentSession,
   AgentCreateSessionInput,
@@ -44,17 +36,11 @@ import type {
 import type { AgentModel } from "@/model/CityModelAdapter.js";
 import { Logger } from "@/utils/logger/Logger.js";
 import { Session } from "@/session/Session.js";
-import { DEFAULT_SHIP_PROMPTS } from "@executor/composer/system/default/SystemDomain.js";
 import {
   getSdkAgentSessionDirPath,
   listAgentSessionSummaryPage,
 } from "@/session/index.js";
-import {
-  createAgentPathRuntime,
-  createAgentPluginConfigRuntime,
-} from "@/runtime/host/AgentHostRuntime.js";
 import { loadDowncityConfig, resolveAgentEnv } from "@/config/Config.js";
-import { HookRegistry } from "@/plugin/core/HookRegistry.js";
 import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { setShellToolRuntime } from "@executor/tools/shell/ShellToolDefinition.js";
@@ -62,52 +48,19 @@ import { startAllPlugins, stopAllPlugins } from "@/plugin/core/Manager.js";
 import type { ActionScheduleRuntimeHandle } from "@/plugin/core/ActionScheduleRuntime.js";
 import { startActionScheduleRuntime } from "@/plugin/core/ActionScheduleRuntime.js";
 import { startRpcServer } from "@/rpc/Server.js";
-
-function createFallbackSdkConfig(agentId: string): DowncityConfig {
-  return {
-    id: agentId,
-    version: "0.0.0",
-  } as DowncityConfig;
-}
-
-function normalizeInstructionInput(input: string | string[] | undefined): string[] {
-  const items = Array.isArray(input)
-    ? input
-    : typeof input === "string"
-      ? [input]
-      : [];
-  return items
-    .map((item) => String(item || "").trim())
-    .filter((item) => item.length > 0);
-}
-
-function createCoreInstructionContent(projectRoot: string): string {
-  const currentYear = String(new Date().getFullYear());
-  return DEFAULT_SHIP_PROMPTS
-    .replaceAll("{{project_path}}", projectRoot)
-    .replaceAll("{{project_root}}", projectRoot)
-    .replaceAll("{{current_year}}", currentYear);
-}
-
-function createInstructionSystemBlocks(
-  instruction: string[],
-  projectRoot: string,
-): AgentSessionSystemBlock[] {
-  if (instruction.length === 0) {
-    return [
-      {
-        source: "core",
-        name: "default",
-        content: createCoreInstructionContent(projectRoot),
-      },
-    ];
-  }
-  return instruction.map((content, index) => ({
-    source: "instruction" as const,
-    name: instruction.length === 1 ? "agent" : `agent:${index + 1}`,
-    content,
-  }));
-}
+import {
+  createFallbackSdkConfig,
+  createInstructionSystemBlocks,
+  normalizeInstructionInput,
+} from "@/agent/local/AgentInstructions.js";
+import {
+  createAgentPluginPort,
+  createAgentPluginRegistry,
+} from "@/agent/local/AgentPluginFactory.js";
+import {
+  createAgentContext,
+  createAgentRuntime,
+} from "@/agent/local/AgentRuntimeFactory.js";
 
 /**
  * SDK 本地 Agent。
@@ -156,13 +109,40 @@ export class Agent {
     this.defaultModel = options.model;
     this.config = this.loadConfig();
     this.pluginInstances = new Map<string, BasePlugin>();
-    this.runtime = this.createRuntime();
+    this.runtime = createAgentRuntime({
+      agent_id: this.id,
+      project_root: this.path,
+      logger: this.logger,
+      config: this.config,
+      env: this.env,
+      systems: this.instruction,
+      plugin_instances: this.pluginInstances,
+      get_session_port: (session_id) =>
+        this.getOrCreateSession(session_id).getRuntimePort(),
+      list_cached_sessions: () => [...this.sessionsById.values()],
+    });
     this.registerPlugins(options.plugins || []);
-    this.pluginRegistry = this.createPluginRegistry([
-      ...this.pluginInstances.values(),
-    ]);
-    this.plugins = this.createPluginPort();
-    this.agentContext = this.createAgentContext();
+    this.pluginRegistry = createAgentPluginRegistry({
+      plugins: [...this.pluginInstances.values()],
+      get_context: () => this.agentContext,
+    });
+    this.plugins = createAgentPluginPort(this.pluginRegistry);
+    this.agentContext = createAgentContext({
+      runtime: this.runtime,
+      project_root: this.path,
+      logger: this.logger,
+      config: this.config,
+      env: this.env,
+      systems: this.instruction,
+      plugin_instances: this.pluginInstances,
+      plugins: this.plugins,
+      get_session_port: (session_id) =>
+        this.getOrCreateSession(session_id).getRuntimePort(),
+      resolve_session_model: async (session_id) => {
+        const session = await this.getSession(session_id);
+        return session.config.model;
+      },
+    });
     setShellToolRuntime(this.agentContext.invoke);
 
     this.sessionCollection = {
@@ -333,7 +313,7 @@ export class Agent {
    * 返回当前 agent runtime。
    *
    * 关键点（中文）
-   * - 供宿主在 agent 外部装配 transport（例如 city HTTP gateway）时复用。
+   * - 供宿主在 agent 外部装配 transport（例如 Town HTTP gateway）时复用。
    * - 不暴露启动语义，只暴露运行时访问口。
    */
   getRuntime(): AgentRuntime {
@@ -489,61 +469,6 @@ export class Agent {
     }
   }
 
-  /**
-   * 创建 plugin 注册表。
-   *
-   * 关键点（中文）
-   * - registry 本身不直接持有静态上下文，而是通过 resolver 延迟读取当前 `agentContext`。
-   * - 这样 hook 调度与 availability 判断都能复用同一份上下文视图。
-   */
-  private createPluginRegistry(input: BasePlugin[]): PluginRegistry {
-    let pluginRegistryRef: PluginRegistry | null = null;
-    const hookRegistry = new HookRegistry({
-      contextResolver: () => this.agentContext,
-      pluginEnabledChecker: (pluginName) => {
-        const plugin = pluginRegistryRef?.get(pluginName);
-        return plugin
-          ? isPluginEnabled({ plugin, context: this.agentContext })
-          : false;
-      },
-    });
-    const registry = new PluginRegistry({
-      contextResolver: () => this.agentContext,
-      hookRegistry,
-    });
-    pluginRegistryRef = registry;
-
-    for (const plugin of input) {
-      registry.register(plugin);
-    }
-    return registry;
-  }
-
-  /**
-   * 创建对外暴露的 plugin 调用门面。
-   */
-  private createPluginPort(): PluginPort {
-    return {
-      list: (): PluginView[] => this.pluginRegistry.list(),
-      availability: async (pluginName: string): Promise<PluginAvailability> =>
-        await this.pluginRegistry.availability(pluginName),
-      runAction: async (params) => await this.pluginRegistry.runAction(params),
-      pipeline: async <T>(pointName: string, value: T): Promise<T> =>
-        await this.pluginRegistry.pipeline(pointName, value),
-      guard: async <T>(pointName: string, value: T): Promise<void> => {
-        await this.pluginRegistry.guard(pointName, value);
-      },
-      effect: async <T>(pointName: string, value: T): Promise<void> => {
-        await this.pluginRegistry.effect(pointName, value);
-      },
-      resolve: async <TInput, TOutput>(
-        pointName: string,
-        value: TInput,
-      ): Promise<TOutput> =>
-        await this.pluginRegistry.resolve<TInput, TOutput>(pointName, value),
-    };
-  }
-
   /**
    * 读取当前 agent 静态 instruction blocks。
    */
@@ -582,109 +507,6 @@ export class Agent {
     return out;
   }
 
-  /**
-   * 创建实例级 runtime 视图。
-   *
-   * 关键点（中文）
-   * - runtime 描述的是当前 agent 实例持有的长期状态。
-   * - 其他 server / plugin / transport 都通过这个视图读取统一状态。
-   */
-  private createRuntime(): AgentRuntime {
-    const runtime = {
-      cwd: this.path,
-      rootPath: this.path,
-      logger: this.logger,
-      config: this.config,
-      env: this.env,
-      systems: this.instruction,
-      paths: createAgentPathRuntime(this.path, this.id),
-      pluginConfig: createAgentPluginConfigRuntime(this.path),
-      getSession: (sessionId: string): SessionPort =>
-        this.getOrCreateSession(sessionId).getRuntimePort(),
-      listExecutingSessionIds: () =>
-        [...this.sessionsById.values()]
-          .filter((session) => session.isExecuting())
-          .map((session) => session.id),
-      getExecutingSessionCount: () =>
-        [...this.sessionsById.values()].filter((session) => session.isExecuting()).length,
-      pluginInstances: this.pluginInstances,
-    } satisfies AgentRuntime;
-    return runtime;
-  }
-
-  /**
-   * 创建统一执行上下文。
-   *
-   * 关键点（中文）
-   * - `AgentContext` 是执行期能力视图，不是状态实体本身。
-   * - plugin runtime、chat runtime、shell tool 都通过这里消费能力。
-   */
-  private createAgentContext(): AgentContext {
-    let context!: AgentContext;
-    context = {
-      agent: this.runtime,
-      cwd: this.path,
-      rootPath: this.path,
-      logger: this.logger,
-      config: this.config,
-      env: this.env,
-      systems: this.instruction,
-      paths: this.runtime.paths,
-      pluginConfig: this.runtime.pluginConfig,
-      session: {
-        get: (sessionId) => this.getOrCreateSession(sessionId).getRuntimePort(),
-        listExecutingSessionIds: () => this.runtime.listExecutingSessionIds(),
-        getExecutingSessionCount: () => this.runtime.getExecutingSessionCount(),
-        resolveModel: async (sessionId) => {
-          const session = await this.getSession(sessionId);
-          return session.config.model;
-        },
-      },
-      invoke: {
-        invoke: async (params: {
-          plugin: string;
-          action: string;
-          payload?: JsonValue;
-        }) => {
-          const pluginName = String(params.plugin || "").trim();
-          const actionName = String(params.action || "").trim();
-          const plugin = this.pluginInstances.get(pluginName);
-          if (!plugin) {
-            return {
-              success: false,
-              error: `Unknown plugin: ${pluginName}`,
-            };
-          }
-          const action = plugin.actions[actionName];
-          if (!action) {
-            return {
-              success: false,
-              error: `Unknown action: ${pluginName}.${actionName}`,
-            };
-          }
-          const result = await action.execute({
-            context,
-            payload: params.payload ?? null,
-            pluginName,
-            actionName,
-          });
-          if (!result.success) {
-            return {
-              success: false,
-              ...(result.error ? { error: result.error } : {}),
-            };
-          }
-          return {
-            success: true,
-            ...(result.data !== undefined ? { data: result.data } : {}),
-          };
-        },
-      },
-      plugins: this.plugins,
-    };
-    return context;
-  }
-
   /**
    * 获取或创建一个本地 Session 实例。
    *

package/src/agent/local/AgentInstructions.ts

@@ -0,0 +1,68 @@
+/**
+ * Agent instruction 组装工具。
+ *
+ * 关键点（中文）
+ * - 这里只处理静态 instruction 与默认 core prompt。
+ * - 不读取 session、plugin 或 runtime 状态，保持为纯函数。
+ */
+
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/AgentTypes.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。
+ */
+export function normalizeInstructionInput(
+  input: string | string[] | undefined,
+): string[] {
+  const items = Array.isArray(input)
+    ? input
+    : typeof input === "string"
+      ? [input]
+      : [];
+  return items
+    .map((item) => String(item || "").trim())
+    .filter((item) => item.length > 0);
+}
+
+function createCoreInstructionContent(project_root: string): string {
+  const current_year = String(new Date().getFullYear());
+  return DEFAULT_SHIP_PROMPTS
+    .replaceAll("{{project_path}}", project_root)
+    .replaceAll("{{project_root}}", project_root)
+    .replaceAll("{{current_year}}", current_year);
+}
+
+/**
+ * 构造进入 session system prompt 的 instruction block。
+ */
+export function createInstructionSystemBlocks(
+  instruction: string[],
+  project_root: string,
+): AgentSessionSystemBlock[] {
+  if (instruction.length === 0) {
+    return [
+      {
+        source: "core",
+        name: "default",
+        content: createCoreInstructionContent(project_root),
+      },
+    ];
+  }
+  return instruction.map((content, index) => ({
+    source: "instruction" as const,
+    name: instruction.length === 1 ? "agent" : `agent:${index + 1}`,
+    content,
+  }));
+}

package/src/agent/local/AgentPluginFactory.ts

@@ -0,0 +1,83 @@
+/**
+ * Agent plugin 装配工厂。
+ *
+ * 关键点（中文）
+ * - 这里只负责把 plugin 实例装配成 registry 与对外 port。
+ * - Agent 仍然持有长期状态；这里不创建新的运行时层级。
+ */
+
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type {
+  PluginAvailability,
+  PluginPort,
+  PluginView,
+} from "@/plugin/types/Plugin.js";
+import { HookRegistry } from "@/plugin/core/HookRegistry.js";
+import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+
+/**
+ * 创建 plugin registry 的参数。
+ */
+export interface CreateAgentPluginRegistryOptions {
+  /** 当前 agent 显式注册的 plugin 实例。 */
+  plugins: BasePlugin[];
+  /** 延迟读取当前 AgentContext。 */
+  get_context: () => AgentContext;
+}
+
+/**
+ * 创建 plugin 注册表。
+ */
+export function createAgentPluginRegistry(
+  options: CreateAgentPluginRegistryOptions,
+): PluginRegistry {
+  let plugin_registry_ref: PluginRegistry | null = null;
+  const hook_registry = new HookRegistry({
+    contextResolver: options.get_context,
+    pluginEnabledChecker: (plugin_name) => {
+      const plugin = plugin_registry_ref?.get(plugin_name);
+      return plugin
+        ? isPluginEnabled({ plugin, context: options.get_context() })
+        : false;
+    },
+  });
+  const registry = new PluginRegistry({
+    contextResolver: options.get_context,
+    hookRegistry: hook_registry,
+  });
+  plugin_registry_ref = registry;
+
+  for (const plugin of options.plugins) {
+    registry.register(plugin);
+  }
+  return registry;
+}
+
+/**
+ * 创建对外暴露的 plugin 调用门面。
+ */
+export function createAgentPluginPort(
+  plugin_registry: PluginRegistry,
+): PluginPort {
+  return {
+    list: (): PluginView[] => plugin_registry.list(),
+    availability: async (plugin_name: string): Promise<PluginAvailability> =>
+      await plugin_registry.availability(plugin_name),
+    runAction: async (params) => await plugin_registry.runAction(params),
+    pipeline: async <T>(point_name: string, value: T): Promise<T> =>
+      await plugin_registry.pipeline(point_name, value),
+    guard: async <T>(point_name: string, value: T): Promise<void> => {
+      await plugin_registry.guard(point_name, value);
+    },
+    effect: async <T>(point_name: string, value: T): Promise<void> => {
+      await plugin_registry.effect(point_name, value);
+    },
+    resolve: async <TInput, TOutput>(
+      point_name: string,
+      value: TInput,
+    ): Promise<TOutput> =>
+      await plugin_registry.resolve<TInput, TOutput>(point_name, value),
+  };
+}

package/src/{runtime/host/AgentHostRuntime.ts → agent/local/AgentRuntimeAssembly.ts}

@@ -1,5 +1,5 @@
 /**
- * AgentHostRuntime：装配 AgentRuntime 宿主能力。
+ * AgentRuntimeAssembly：装配本地 AgentRuntime 能力。
  *
  * 关键点（中文）
  * - agent runtime 负责创建这些宿主能力对象，再注入到 AgentRuntime。
@@ -22,7 +22,7 @@ import { persistProjectPluginConfig } from "@/plugin/core/ProjectConfigStore.js"
 import type {
   AgentPathRuntime,
   AgentPluginConfigRuntime,
-} from "@/types/runtime/host/AgentHost.js";
+} from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 
 /**

package/src/agent/local/AgentRuntimeFactory.ts

@@ -0,0 +1,173 @@
+/**
+ * Agent runtime / context 装配工厂。
+ *
+ * 关键点（中文）
+ * - 这里只创建长期 runtime 视图与执行期 context 视图。
+ * - 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 { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
+import type { Session } from "@/session/Session.js";
+import {
+  createAgentPathRuntime,
+  createAgentPluginConfigRuntime,
+} from "@/agent/local/AgentRuntimeAssembly.js";
+
+/**
+ * 创建 AgentRuntime 的参数。
+ */
+export interface CreateAgentRuntimeOptions {
+  /** 当前 agent id。 */
+  agent_id: string;
+  /** 当前项目根目录。 */
+  project_root: string;
+  /** 统一日志器。 */
+  logger: Logger;
+  /** 当前解析后的配置。 */
+  config: DowncityConfig;
+  /** 当前环境变量快照。 */
+  env: Record<string, string>;
+  /** 当前静态 system 文本集合。 */
+  systems: string[];
+  /** 当前 plugin 实例集合。 */
+  plugin_instances: Map<string, BasePlugin>;
+  /** 获取或创建 session runtime port。 */
+  get_session_port: (session_id: string) => SessionPort;
+  /** 读取当前已缓存的 session 实例。 */
+  list_cached_sessions: () => Session[];
+}
+
+/**
+ * 创建 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: PluginPort;
+  /** 获取或创建 session runtime port。 */
+  get_session_port: (session_id: string) => SessionPort;
+  /** 解析 session 当前绑定的模型实例。 */
+  resolve_session_model: (session_id: string) => Promise<LanguageModel | undefined>;
+}
+
+/**
+ * 创建实例级 runtime 视图。
+ */
+export function createAgentRuntime(
+  options: CreateAgentRuntimeOptions,
+): AgentRuntime {
+  return {
+    cwd: options.project_root,
+    rootPath: options.project_root,
+    logger: options.logger,
+    config: options.config,
+    env: options.env,
+    systems: options.systems,
+    paths: createAgentPathRuntime(options.project_root, options.agent_id),
+    pluginConfig: createAgentPluginConfigRuntime(options.project_root),
+    getSession: (session_id: string): SessionPort =>
+      options.get_session_port(session_id),
+    listExecutingSessionIds: () =>
+      options
+        .list_cached_sessions()
+        .filter((session) => session.isExecuting())
+        .map((session) => session.id),
+    getExecutingSessionCount: () =>
+      options
+        .list_cached_sessions()
+        .filter((session) => session.isExecuting()).length,
+    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 plugin_name = String(params.plugin || "").trim();
+        const action_name = String(params.action || "").trim();
+        const plugin = options.plugin_instances.get(plugin_name);
+        if (!plugin) {
+          return {
+            success: false,
+            error: `Unknown plugin: ${plugin_name}`,
+          };
+        }
+        const action = plugin.actions[action_name];
+        if (!action) {
+          return {
+            success: false,
+            error: `Unknown action: ${plugin_name}.${action_name}`,
+          };
+        }
+        const result = await action.execute({
+          context,
+          payload: params.payload ?? null,
+          pluginName: plugin_name,
+          actionName: action_name,
+        });
+        if (!result.success) {
+          return {
+            success: false,
+            ...(result.error ? { error: result.error } : {}),
+          };
+        }
+        return {
+          success: true,
+          ...(result.data !== undefined ? { data: result.data } : {}),
+        };
+      },
+    },
+    plugins: options.plugins,
+  };
+  return context;
+}

package/src/{runtime/host → agent/local}/ProjectSetup.ts

@@ -1,5 +1,5 @@
 /**
- * ProjectSetup：runtime 启动前项目结构准备模块。
+ * ProjectSetup：本地 Agent 启动前项目结构准备模块。
  *
  * 关键点（中文）
  * - 统一校验初始化必要文件（PROFILE.md / downcity.json）。