@downcity/agent 1.1.1 → 1.1.5

package/src/host/sdk/Agent.ts

@@ -0,0 +1,316 @@
+/**
+ * Agent SDK 本地入口。
+ *
+ * 关键点（中文）
+ * - `new Agent({ id, path, tools, services })` 只做同步装配，不在构造阶段启动任何 I/O。
+ * - session、HTTP、RPC、service lifecycle 都按需异步初始化。
+ * - SDK Agent 通过最小 `AgentContext` 适配层复用现有 service/chat runtime，而不是重复实现一套执行链。
+ */
+
+import fs from "fs-extra";
+import { nanoid } from "nanoid";
+import type { Tool } from "ai";
+import { Logger } from "@shared/utils/logger/Logger.js";
+import type { BaseService } from "@/service/builtins/BaseService.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
+import type { JsonValue } from "@/shared/types/Json.js";
+import type {
+  AgentOptions,
+  AgentSessionMetadata,
+} from "@/host/sdk/AgentSdkTypes.js";
+import { SdkSession } from "@/host/sdk/Session.js";
+import { loadStaticSystemPrompts } from "@session/composer/system/default/StaticPromptCatalog.js";
+import { getSdkAgentSessionsRootDirPath } from "@/host/sdk/Paths.js";
+import { SdkAgentHttpServer } from "@/host/sdk/HttpServer.js";
+import { SdkAgentRpcServer } from "@/host/sdk/RpcServer.js";
+import { createAgentPathRuntime } from "@/host/runtime/AgentHostRuntime.js";
+import { loadDowncityConfig } from "@/config/Config.js";
+import { appendExecSessionMessage } from "@/service/builtins/chat/runtime/ChatIngressStore.js";
+import { readChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";
+import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueueStore.js";
+
+function createFallbackSdkConfig(agentId: string): DowncityConfig {
+  return {
+    name: agentId,
+    version: "0.0.0",
+  } as DowncityConfig;
+}
+
+/**
+ * SDK 本地 Agent。
+ */
+export class Agent {
+  readonly id: string;
+  readonly path: string;
+  readonly tools: Record<string, Tool>;
+  readonly http: SdkAgentHttpServer;
+  readonly rpc: SdkAgentRpcServer;
+  readonly services: Map<string, BaseService>;
+
+  private readonly logger: Logger;
+  private readonly sessionsById = new Map<string, SdkSession>();
+  private readonly runtime: AgentRuntime;
+  private readonly serviceContext: AgentContext;
+  private readonly config: DowncityConfig;
+  private systems: string[];
+  private servicesStartPromise: Promise<void> | null = null;
+
+  constructor(options: AgentOptions) {
+    this.id = String(options.id || "").trim();
+    this.path = String(options.path || "").trim();
+    this.tools = options.tools && typeof options.tools === "object"
+      ? { ...options.tools }
+      : {};
+    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.logger = new Logger();
+    this.logger.bindProjectRoot(this.path);
+    this.systems = loadStaticSystemPrompts(this.path);
+    this.config = this.loadConfig();
+    this.services = this.createServiceMap(options.services || []);
+    this.runtime = this.createRuntime();
+    for (const service of this.services.values()) {
+      service.bindAgent(this.runtime);
+    }
+    this.serviceContext = this.createServiceContext();
+    this.http = new SdkAgentHttpServer(this);
+    this.rpc = new SdkAgentRpcServer(this);
+  }
+
+  /**
+   * 获取或创建一个 session。
+   */
+  async session(sessionId?: string): Promise<SdkSession> {
+    const session = this.getOrCreateSession(sessionId);
+    await session.initialize();
+    return session;
+  }
+
+  /**
+   * 列出当前 agent 的全部 session 元数据。
+   */
+  async sessions(): Promise<AgentSessionMetadata[]> {
+    const rootDir = getSdkAgentSessionsRootDirPath(this.path, this.id);
+    if (!(await fs.pathExists(rootDir))) return [];
+    const entries = await fs.readdir(rootDir, { withFileTypes: true });
+    const items: AgentSessionMetadata[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      let sessionId = "";
+      try {
+        sessionId = decodeURIComponent(entry.name);
+      } catch {
+        sessionId = entry.name;
+      }
+      if (!sessionId) continue;
+      const session = await this.session(sessionId);
+      items.push(await session.toMetadata());
+    }
+    items.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    return items;
+  }
+
+  /**
+   * 确保显式注入的 services 已启动。
+   */
+  async ensureServicesStarted(): Promise<void> {
+    if (this.servicesStartPromise) {
+      await this.servicesStartPromise;
+      return;
+    }
+    this.servicesStartPromise = (async () => {
+      for (const service of this.services.values()) {
+        await service.lifecycle?.start?.(this.serviceContext);
+      }
+    })();
+    await this.servicesStartPromise;
+  }
+
+  /**
+   * 刷新静态 system 文本集合。
+   */
+  reloadStaticPrompts(): void {
+    this.systems = loadStaticSystemPrompts(this.path);
+  }
+
+  private loadConfig(): DowncityConfig {
+    try {
+      return loadDowncityConfig(this.path, {
+        projectEnv: {},
+        agentEnv: {},
+        globalEnv: {},
+      });
+    } catch {
+      return createFallbackSdkConfig(this.id);
+    }
+  }
+
+  private createServiceMap(input: BaseService[]): Map<string, BaseService> {
+    const services = new Map<string, BaseService>();
+    for (const service of input) {
+      const name = String(service?.name || "").trim();
+      if (!name) {
+        throw new Error("Agent received a service without a valid name");
+      }
+      if (services.has(name)) {
+        throw new Error(`Duplicate service registration: ${name}`);
+      }
+      services.set(name, service);
+    }
+    return services;
+  }
+
+  private createRuntime(): AgentRuntime {
+    const runtime = {
+      cwd: this.path,
+      rootPath: this.path,
+      logger: this.logger,
+      config: this.config,
+      env: {},
+      globalEnv: {},
+      systems: this.systems,
+      paths: createAgentPathRuntime(this.path),
+      pluginConfig: {
+        async persistProjectPlugins(): Promise<string> {
+          return "";
+        },
+      },
+      model: undefined,
+      getSession: (sessionId: string) => {
+        return this.getOrCreateSession(sessionId).getServicePort() as never;
+      },
+      listExecutingSessionIds: () =>
+        [...this.sessionsById.values()]
+          .filter((session) => session.isExecuting())
+          .map((session) => session.id),
+      getExecutingSessionCount: () =>
+        [...this.sessionsById.values()].filter((session) => session.isExecuting()).length,
+      services: this.services,
+    } satisfies Omit<AgentRuntime, "getSession"> & {
+      getSession(sessionId: string): never;
+    };
+    return runtime as unknown as AgentRuntime;
+  }
+
+  private createServiceContext(): AgentContext {
+    let context!: AgentContext;
+    context = {
+      agent: this.runtime,
+      cwd: this.path,
+      rootPath: this.path,
+      logger: this.logger,
+      config: this.config,
+      env: {},
+      globalEnv: {},
+      systems: this.systems,
+      paths: this.runtime.paths,
+      pluginConfig: this.runtime.pluginConfig,
+      session: {
+        get: (sessionId) => this.getOrCreateSession(sessionId).getServicePort(),
+        listExecutingSessionIds: () => this.runtime.listExecutingSessionIds(),
+        getExecutingSessionCount: () => this.runtime.getExecutingSessionCount(),
+      },
+      invoke: {
+        invoke: async (params: {
+          service: string;
+          action: string;
+          payload?: JsonValue;
+        }) => {
+          const serviceName = String(params.service || "").trim();
+          const actionName = String(params.action || "").trim();
+          const service = this.services.get(serviceName);
+          if (!service) {
+            return {
+              success: false,
+              error: `Unknown service: ${serviceName}`,
+            };
+          }
+          const action = service.actions[actionName];
+          if (!action) {
+            return {
+              success: false,
+              error: `Unknown action: ${serviceName}.${actionName}`,
+            };
+          }
+          const result = await action.execute({
+            context,
+            payload: params.payload ?? null,
+            serviceName,
+            actionName,
+          });
+          if (!result.success) {
+            return {
+              success: false,
+              ...(result.error ? { error: result.error } : {}),
+            };
+          }
+          return {
+            success: true,
+            ...(result.data !== undefined ? { data: result.data } : {}),
+          };
+        },
+      },
+      chat: {
+        readMetaBySessionId: async (sessionId: string) => {
+          return await readChatMetaBySessionId({
+            context,
+            sessionId,
+          });
+        },
+        appendExecSessionMessage: async (params) => {
+          await appendExecSessionMessage({
+            context,
+            sessionId: params.sessionId,
+            text: params.text,
+            extra: params.extra,
+          });
+        },
+        enqueue: (params) => resolveChatQueueStore(context).enqueue(params),
+      },
+      plugins: {
+        list: () => [],
+        availability: async () => ({
+          enabled: false,
+          available: false,
+          reasons: ["SDK Agent plugin runtime is not configured"],
+        }),
+        runAction: async () => ({
+          success: false,
+          error: "SDK Agent plugin runtime is not configured",
+        }),
+        pipeline: async <T>(_: string, value: T): Promise<T> => value,
+        guard: async (): Promise<void> => {},
+        effect: async (): Promise<void> => {},
+        resolve: async () => {
+          throw new Error("SDK Agent plugin resolve is not configured");
+        },
+      },
+    };
+    return context;
+  }
+
+  private getOrCreateSession(sessionId?: string): SdkSession {
+    const resolvedSessionId =
+      String(sessionId || "").trim() || `session-${Date.now()}-${nanoid(8)}`;
+    const cached = this.sessionsById.get(resolvedSessionId);
+    if (cached) return cached;
+
+    const created = new SdkSession({
+      agentId: this.id,
+      projectRoot: this.path,
+      sessionId: resolvedSessionId,
+      tools: this.tools,
+      logger: this.logger,
+      getStaticSystemPrompts: () => this.systems,
+    });
+    this.sessionsById.set(resolvedSessionId, created);
+    return created;
+  }
+}

package/src/host/sdk/AgentSdkTypes.ts

@@ -0,0 +1,275 @@
+/**
+ * Agent SDK 对外类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 `Agent` / `RemoteAgent` / `Session` 面向外部调用方的稳定接口。
+ * - 不把内部 `AgentRuntime`、`AgentContext`、service/plugin 管理细节暴露给 SDK 用户。
+ * - v1 先聚焦本地/远程 session 运行与基础落盘能力。
+ */
+
+import type { LanguageModel, Tool } from "ai";
+import type { BaseService } from "@/service/builtins/BaseService.js";
+import type { JsonValue } from "@/shared/types/Json.js";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+
+/**
+ * 本地 Agent 构造参数。
+ */
+export interface AgentOptions {
+  /**
+   * 当前 agent 的稳定标识。
+   *
+   * 关键点（中文）
+   * - 用于 `.downcity/agents/<agentId>/...` 目录分区。
+   * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
+   */
+  id: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  path: string;
+
+  /**
+   * 当前 agent 默认可用的工具集合。
+   *
+   * 关键点（中文）
+   * - tools 归属于 agent 级，而不是 session 级。
+   * - session 运行时会直接复用这份工具集合。
+   */
+  tools?: Record<string, Tool>;
+
+  /**
+   * 当前 agent 显式持有的 service 实例集合。
+   *
+   * 关键点（中文）
+   * - 这里接收已经实例化好的 service，而不是 service class。
+   * - `Agent` 会在构造阶段按名称注册这些实例，并在启动时自动绑定 runtime。
+   * - v1 推荐显式传入 `new ChatService(...)` 这类实例，而不是依赖包内隐式注册表。
+   */
+  services?: BaseService[];
+}
+
+/**
+ * 远程 Agent 构造参数。
+ */
+export interface RemoteAgentOptions {
+  /**
+   * 远程 SDK HTTP 基础地址。
+   *
+   * 例如：`http://127.0.0.1:15314`
+   */
+  baseUrl: string;
+}
+
+/**
+ * Session 可变配置。
+ */
+export interface AgentSessionSetInput {
+  /**
+   * 当前 session 默认模型实例。
+   *
+   * 关键点（中文）
+   * - 这里接受运行中的模型实例，而不是模型 ID。
+   * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
+   */
+  model?: LanguageModel;
+}
+
+/**
+ * Session 当前配置快照。
+ */
+export interface AgentSessionConfigSnapshot {
+  /**
+   * 当前 session 绑定的默认模型实例。
+   */
+  model?: LanguageModel;
+
+  /**
+   * 当前模型的轻量可读标签。
+   */
+  modelLabel?: string;
+}
+
+/**
+ * Session 运行输入。
+ */
+export interface AgentSessionRunInput {
+  /**
+   * 当前轮用户查询文本。
+   */
+  query: string;
+}
+
+/**
+ * Session 运行结果。
+ */
+export interface AgentSessionRunResult {
+  /**
+   * 本轮执行是否成功。
+   */
+  success: boolean;
+
+  /**
+   * 失败时的错误文本。
+   */
+  error?: string;
+
+  /**
+   * 最终 assistant 文本。
+   */
+  text: string;
+
+  /**
+   * 最终 assistant 原始 UIMessage。
+   */
+  assistantMessage: SessionMessageV1;
+}
+
+/**
+ * SDK 对外的流式事件。
+ */
+export type AgentSessionStreamEvent =
+  | {
+      /**
+       * 文本增量事件。
+       */
+      type: "text-delta";
+      /**
+       * 当前追加的文本片段。
+       */
+      text: string;
+    }
+  | {
+      /**
+       * reasoning 增量事件。
+       */
+      type: "reasoning-delta";
+      /**
+       * 当前追加的 reasoning 文本片段。
+       */
+      text: string;
+    }
+  | {
+      /**
+       * 工具调用可用事件。
+       */
+      type: "tool-call";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 工具输入参数。
+       */
+      args: JsonValue;
+    }
+  | {
+      /**
+       * 工具调用结果事件。
+       */
+      type: "tool-result";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 工具输出结果。
+       */
+      result: JsonValue;
+    }
+  | {
+      /**
+       * 工具调用失败事件。
+       */
+      type: "tool-error";
+      /**
+       * 当前工具调用唯一标识。
+       */
+      toolCallId: string;
+      /**
+       * 工具名称。
+       */
+      toolName: string;
+      /**
+       * 错误文本。
+       */
+      error: string;
+    }
+  | {
+      /**
+       * 运行结束事件。
+       */
+      type: "finish";
+      /**
+       * 最终完成原因（若底层可提供）。
+       */
+      finishReason?: string;
+    }
+  | {
+      /**
+       * 运行错误事件。
+       */
+      type: "error";
+      /**
+       * 错误文本。
+       */
+      error: string;
+    };
+
+/**
+ * Session 元数据列表项。
+ */
+export interface AgentSessionMetadata {
+  /**
+   * 当前 session 所属 agentId。
+   */
+  agentId: string;
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 首次创建时间（ms）。
+   */
+  createdAt?: number;
+
+  /**
+   * 当前 session 最近一次更新时间（ms）。
+   */
+  updatedAt?: number;
+
+  /**
+   * 当前 session 已落盘消息数。
+   */
+  messageCount: number;
+
+  /**
+   * 当前 session 绑定模型的可读标签。
+   */
+  modelLabel?: string;
+}
+
+/**
+ * Session fork 输入。
+ */
+export interface AgentSessionForkInput {
+  /**
+   * 可选分叉锚点消息 ID。
+   *
+   * 关键点（中文）
+   * - 省略时复制当前 session 的完整消息历史。
+   * - 传入时复制到该消息为止（包含该消息）。
+   */
+  messageId?: string;
+}

package/src/host/sdk/AsyncQueue.ts

@@ -0,0 +1,92 @@
+/**
+ * SDK AsyncQueue。
+ *
+ * 关键点（中文）
+ * - 用于把 callback 风格的 stream 事件桥接成 `AsyncIterable`。
+ * - 保持实现轻量，不引入额外第三方依赖。
+ */
+
+type QueueState<T> = {
+  /**
+   * 已入队但尚未消费的值。
+   */
+  values: T[];
+
+  /**
+   * 等待中的消费者回调。
+   */
+  waiters: Array<(result: IteratorResult<T>) => void>;
+
+  /**
+   * 队列是否已关闭。
+   */
+  closed: boolean;
+};
+
+/**
+ * 极简异步队列。
+ */
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly state: QueueState<T> = {
+    values: [],
+    waiters: [],
+    closed: false,
+  };
+
+  /**
+   * 推入一个值。
+   */
+  push(value: T): void {
+    if (this.state.closed) return;
+    const waiter = this.state.waiters.shift();
+    if (waiter) {
+      waiter({
+        done: false,
+        value,
+      });
+      return;
+    }
+    this.state.values.push(value);
+  }
+
+  /**
+   * 关闭队列。
+   */
+  close(): void {
+    if (this.state.closed) return;
+    this.state.closed = true;
+    while (this.state.waiters.length > 0) {
+      const waiter = this.state.waiters.shift();
+      if (!waiter) continue;
+      waiter({
+        done: true,
+        value: undefined as T,
+      });
+    }
+  }
+
+  /**
+   * 返回异步迭代器。
+   */
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: () => {
+        if (this.state.values.length > 0) {
+          return Promise.resolve({
+            done: false,
+            value: this.state.values.shift() as T,
+          });
+        }
+        if (this.state.closed) {
+          return Promise.resolve({
+            done: true,
+            value: undefined as T,
+          });
+        }
+        return new Promise<IteratorResult<T>>((resolve) => {
+          this.state.waiters.push(resolve);
+        });
+      },
+    };
+  }
+}