@downcity/agent 1.1.74 → 1.1.81

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,152 @@
+/**
+ * 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 { AgentManagedSession } from "@/types/agent/AgentTypes.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: () => 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: 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 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/{runtime/host → agent/local}/ProjectSetup.ts

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

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

@@ -0,0 +1,268 @@
+/**
+ * AgentAssemblyService：本地 Agent 装配服务。
+ *
+ * 关键点（中文）
+ * - 统一装配 logger、config、env、runtime、context、plugin registry 与 plugin port。
+ * - 该服务只负责一次性长期对象装配，不负责 session 缓存和生命周期启动。
+ * - session/lifecycle service 通过它暴露的长期对象协作，避免在 facade 中重复拼装。
+ */
+
+import type { LanguageModel, Tool } from "ai";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.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 { PluginPort } from "@/plugin/types/Plugin.js";
+import type { AgentOptions } from "@/types/agent/AgentTypes.js";
+import { Logger } from "@/utils/logger/Logger.js";
+import { loadDowncityConfig, resolveAgentEnv } from "@/config/Config.js";
+import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import {
+  createFallbackSdkConfig,
+  normalizeInstructionInput,
+} from "@/agent/local/AgentInstructions.js";
+import {
+  createAgentPluginPort,
+  createAgentPluginRegistry,
+} from "@/agent/local/AgentPluginFactory.js";
+import {
+  createAgentContext,
+  createAgentRuntime,
+} from "@/agent/local/AgentRuntimeFactory.js";
+import { setShellToolRuntime } from "@executor/tools/shell/ShellToolDefinition.js";
+import {
+  plugin_tools,
+  setPluginToolRuntime,
+} from "@executor/tools/plugin/PluginToolDefinition.js";
+import type { AgentManagedSession } from "@/types/agent/AgentTypes.js";
+import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+
+type AgentAssemblyServiceOptions = {
+  /**
+   * 当前 agent 构造参数。
+   */
+  options: AgentOptions;
+
+  /**
+   * 读取当前已缓存的 session 实例。
+   */
+  list_cached_sessions: () => AgentManagedSession[];
+
+  /**
+   * 获取或创建 session runtime port。
+   */
+  get_session_port: (session_id: string) => SessionPort;
+
+  /**
+   * 解析指定 session 当前绑定的模型实例。
+   */
+  resolve_session_model: (
+    session_id: string,
+  ) => Promise<LanguageModel | undefined>;
+};
+
+/**
+ * 本地 Agent 装配结果。
+ */
+export interface AgentAssemblyResult {
+  /**
+   * 当前 agent 稳定标识。
+   */
+  id: string;
+
+  /**
+   * 当前项目根目录。
+   */
+  path: string;
+
+  /**
+   * 当前 agent 默认工具集合。
+   */
+  tools: Record<string, Tool>;
+
+  /**
+   * 当前 agent 统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 agent 环境变量快照。
+   */
+  env: Record<string, string>;
+
+  /**
+   * 当前 agent 静态 instruction。
+   */
+  instruction: string[];
+
+  /**
+   * 当前解析后的项目配置。
+   */
+  config: DowncityConfig;
+
+  /**
+   * 当前 plugin 实例集合。
+   */
+  plugin_instances: Map<string, BasePlugin>;
+
+  /**
+   * 当前 plugin 注册表。
+   */
+  plugin_registry: PluginRegistry;
+
+  /**
+   * 当前对外 plugin 调用端口。
+   */
+  plugins: PluginPort;
+
+  /**
+   * 当前 agent runtime。
+   */
+  runtime: AgentRuntime;
+
+  /**
+   * 当前 agent context。
+   */
+  agent_context: AgentContext;
+}
+
+/**
+ * 本地 Agent 装配服务。
+ */
+export class AgentAssemblyService {
+  private readonly options: AgentOptions;
+  private readonly list_cached_sessions: AgentAssemblyServiceOptions["list_cached_sessions"];
+  private readonly get_session_port: AgentAssemblyServiceOptions["get_session_port"];
+  private readonly resolve_session_model: AgentAssemblyServiceOptions["resolve_session_model"];
+
+  constructor(options: AgentAssemblyServiceOptions) {
+    this.options = options.options;
+    this.list_cached_sessions = options.list_cached_sessions;
+    this.get_session_port = options.get_session_port;
+    this.resolve_session_model = options.resolve_session_model;
+  }
+
+  /**
+   * 执行一次性长期对象装配。
+   */
+  assemble(): AgentAssemblyResult {
+    const id = String(this.options.id || "").trim();
+    const path = String(this.options.path || "").trim();
+    const tools =
+      this.options.tools && typeof this.options.tools === "object"
+        ? { ...this.options.tools }
+        : {};
+    if (!id) {
+      throw new Error("Agent requires a non-empty id");
+    }
+    if (!path) {
+      throw new Error("Agent requires a non-empty path");
+    }
+
+    const logger = new Logger();
+    logger.bindProjectRoot(path);
+    const env = resolveAgentEnv(path, this.options.env);
+    const instruction = normalizeInstructionInput(this.options.instruction);
+    const config = this.load_config(id, path);
+    const plugin_instances = new Map<string, BasePlugin>();
+
+    const runtime = createAgentRuntime({
+      agent_id: id,
+      project_root: path,
+      logger,
+      config,
+      env,
+      systems: instruction,
+      plugin_instances,
+      get_session_port: this.get_session_port,
+      list_cached_sessions: this.list_cached_sessions,
+    });
+
+    this.register_plugins(plugin_instances, runtime, this.options.plugins || []);
+
+    let agent_context!: AgentContext;
+    const plugin_registry = createAgentPluginRegistry({
+      plugins: [...plugin_instances.values()],
+      get_context: () => agent_context,
+    });
+    const plugins = createAgentPluginPort(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,
+      logger,
+      config,
+      env,
+      systems: instruction,
+      plugin_instances,
+      plugins,
+      get_session_port: this.get_session_port,
+      resolve_session_model: async (session_id) =>
+        await this.resolve_session_model(session_id),
+    });
+    setShellToolRuntime(agent_context.invoke);
+    setPluginToolRuntime(plugins);
+
+    return {
+      id,
+      path,
+      tools,
+      logger,
+      env,
+      instruction,
+      config,
+      plugin_instances,
+      plugin_registry,
+      plugins,
+      runtime,
+      agent_context,
+    };
+  }
+
+  private load_config(agent_id: string, project_root: string): DowncityConfig {
+    try {
+      return loadDowncityConfig(project_root);
+    } catch {
+      return createFallbackSdkConfig(agent_id);
+    }
+  }
+
+  private register_plugins(
+    plugin_instances: Map<string, BasePlugin>,
+    runtime: AgentRuntime,
+    plugins: BasePlugin[],
+  ): void {
+    for (const plugin of plugins) {
+      const name = String(plugin?.name || "").trim();
+      if (!name) {
+        throw new Error("Agent received a plugin without a valid name");
+      }
+      if (plugin_instances.has(name)) {
+        throw new Error(`Duplicate plugin registration: ${name}`);
+      }
+      plugin.bindAgent(runtime);
+      plugin_instances.set(name, plugin);
+    }
+  }
+
+  /**
+   * 判断是否需要自动注册 plugin_call tool。
+   */
+  private should_register_plugin_call_tool(
+    plugin_instances: Map<string, BasePlugin>,
+  ): boolean {
+    for (const plugin of plugin_instances.values()) {
+      if (
+        plugin.actions &&
+        Object.keys(plugin.actions).some((action_name) =>
+          Boolean(String(action_name || "").trim()),
+        )
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+}