@downcity/agent 1.1.35 → 1.1.51

package/README.md

@@ -7,7 +7,7 @@
 - 本地 SDK：`Agent`、`Session`、`RemoteAgent`
 - 内部执行内核：history、system、tool loop、增量输出
 - Plugin 框架：hook、action、内建插件
-- 运行时实现：HTTP/RPC server、transport、sandbox、host
+- 运行时实现：HTTP server、sandbox、host
 
 `@downcity/city` 负责多 Agent 管理、控制面网关、平台 CLI、模型池与 daemon 进程管理；`@downcity/agent` 只负责单 Agent 的执行面。
 
@@ -15,14 +15,14 @@
 
 - 面向单个 Agent 项目的执行面
 - 对外通过 `@downcity/agent` 根入口暴露公共 API
-- 负责 session SDK、executor 内核、plugin、sandbox、HTTP/RPC server、SDK 本地 Agent
+- 负责 session SDK、executor 内核、plugin、sandbox、HTTP server、SDK 本地 Agent
 - 不负责多 Agent registry、control plane daemon、console UI 聚合和平台级编排
 
 ## 与其他包的边界
 
 - `@downcity/agent`
   - 单 Agent runtime
-  - 单 Agent HTTP/RPC server
+  - 单 Agent HTTP server
   - session SDK、executor 内核、plugin 框架、sandbox
   - 本地 SDK facade
 - `@downcity/city`
@@ -58,8 +58,7 @@ src/
 ├── runtime/               # 运行时实现细节层，统一收纳 host / sandbox / server / transport
 │   ├── host/              # 宿主注入能力与 daemon 协议
 │   ├── sandbox/           # 命令沙箱与沙箱协议
-│   ├── server/            # HTTP / RPC 服务端实现
-│   └── transport/         # 调用端 transport 协议与 RPC client
+│   └── server/            # HTTP 服务端实现
 ├── sdk/                   # 本地 SDK facade，提供 Agent / RemoteAgent / Session 等高层 API
 │   └── session/           # SDK session 的 metadata、落盘路径、持久化与 runtime 端口适配
 ├── types/                 # 跨模块共享协议类型，集中放置 common / config / runtime 等稳定契约
@@ -101,15 +100,14 @@ src/
   - 单 Agent 的运行时实现细节层
   - `host/` 放宿主注入能力与 daemon 协议
   - `sandbox/` 放命令执行隔离与沙箱协议
-  - `server/` 放 HTTP / RPC 服务端实现
-  - `transport/` 放 agent client 侧 transport 协议与 RPC client
+  - `server/` 放 HTTP 服务端实现
   - 模型实例解析不在 `agent` 包内完成，而由宿主先创建 `LanguageModel`，再通过 `new Agent({ model })` 或 `session.set({ model })` 注入
 
 - `src/types/`
   - 跨模块、跨包共享协议类型
   - `common/` 放 JSON、模板等无领域依赖的基础类型
   - `config/` 放 `downcity.json`、LLM、execution binding、plugin 配置、start options 等配置契约
-  - `runtime/` 放 auth、daemon、host、http、platform、rpc 等运行时与控制面共享协议
+  - `runtime/` 放 auth、daemon、host、http、platform 等运行时与控制面共享协议
   - 领域内部类型仍保留在对应领域目录，例如 `plugin/types/`、`executor/types/`
 
 - `src/utils/`

package/bin/agent/Agent.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Agent 本地入口与实例装配中心。
+ *
+ * 职责说明（中文）
+ * - 对外暴露 `Agent` 这一唯一的本地实例类。
+ * - 统一承接单个 agent 实例的配置加载、plugin 装配、session 创建、RPC 启停。
+ * - 把原先独立的实例内核装配逻辑收敛到 `Agent` 内部，避免 facade 与 core 双层跳转。
+ *
+ * 边界说明（中文）
+ * - 这里负责“单个 agent 实例”的长期状态与装配，不负责平台级多 agent 管理。
+ * - 这里不直接实现 session 执行细节，而是继续复用 `Session` / `Executor` 体系。
+ */
+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 { PluginPort } from "../plugin/types/Plugin.js";
+import type { AgentSession, AgentCreateSessionInput, AgentListSessionsInput, AgentOptions, AgentStartOptions, AgentStartResult, AgentStopResult, AgentSessionCollection, AgentSessionSummaryPage } from "../types/agent/AgentTypes.js";
+import { Logger } from "../utils/logger/Logger.js";
+/**
+ * SDK 本地 Agent。
+ */
+export declare class Agent {
+    readonly id: string;
+    readonly path: string;
+    readonly tools: Record<string, Tool>;
+    readonly plugins: PluginPort;
+    private readonly logger;
+    private readonly sessionsById;
+    private readonly runtime;
+    private readonly agentContext;
+    private readonly pluginRegistry;
+    private readonly config;
+    private readonly env;
+    private readonly defaultModel?;
+    private readonly pluginInstances;
+    private readonly sessionCollection;
+    private instruction;
+    private configuredSessionIds;
+    private pluginsStarted;
+    private actionScheduleRuntime;
+    private startPromise;
+    private rpcBinding;
+    constructor(options: AgentOptions);
+    /**
+     * 新建一个 session。
+     *
+     * 关键点（中文）
+     * - 若调用方显式传入 `sessionId`，这里会先检查缓存与磁盘目录，避免重复创建。
+     * - session 初始化完成后会立即应用默认模型。
+     */
+    createSession(input?: AgentCreateSessionInput): Promise<AgentSession>;
+    /**
+     * 获取一个已存在的 session。
+     *
+     * 关键点（中文）
+     * - 若缓存中没有该 session，会根据磁盘目录决定是否允许懒加载恢复。
+     * - 返回前同样会兜底执行一次默认配置装配。
+     */
+    getSession(sessionId: string): Promise<AgentSession>;
+    /**
+     * 列出当前 agent 的 session 摘要页。
+     */
+    listSessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+    /**
+     * 启动当前 agent 实例的长期运行能力。
+     *
+     * 关键点（中文）
+     * - `start()` 是唯一公开的长期运行生命周期入口。
+     * - 多次并发调用会复用同一个启动 Promise，避免重复启动 plugins / rpc。
+     */
+    start(options?: AgentStartOptions): Promise<AgentStartResult>;
+    /**
+     * 停止当前 agent 实例的长期运行能力。
+     *
+     * 关键点（中文）
+     * - 停止顺序保持为 plugins -> rpc，与当前运行语义一致。
+     * - 停止后会清空 `startPromise`，允许后续再次 `start()`。
+     */
+    stop(): Promise<AgentStopResult>;
+    /**
+     * 更新当前 SDK Agent 的静态基础指令。
+     *
+     * 关键点（中文）
+     * - instruction 不做动态变量替换。
+     * - 已创建的 session 后续 run 会读取最新 instruction blocks。
+     */
+    setInstruction(input: string | string[]): void;
+    /**
+     * 返回当前项目根目录解析后的配置快照。
+     */
+    getConfig(): DowncityConfig;
+    /**
+     * 返回当前 agent 绑定的统一日志器。
+     */
+    getLogger(): Logger;
+    /**
+     * 返回当前 agent runtime。
+     *
+     * 关键点（中文）
+     * - 供宿主在 agent 外部装配 transport（例如 city HTTP gateway）时复用。
+     * - 不暴露启动语义，只暴露运行时访问口。
+     */
+    getRuntime(): AgentRuntime;
+    /**
+     * 返回当前 agent context。
+     *
+     * 关键点（中文）
+     * - 供宿主装配 plugin/control 相关外层协议面。
+     */
+    getContext(): AgentContext;
+    /**
+     * 返回当前 session collection。
+     *
+     * 关键点（中文）
+     * - 供宿主在外层挂载 RemoteAgent transport 时复用。
+     */
+    getSessionCollection(): AgentSessionCollection;
+    /**
+     * 确保当前 plugins 已启动。
+     *
+     * 关键点（中文）
+     * - 这里只负责托管 plugin 的生命周期启动，不隐式启动 RPC 能力。
+     * - 启动失败的 plugin 会记录日志，但保留与原行为一致的整体启动流程。
+     */
+    private ensurePluginsStarted;
+    /**
+     * 确保 ActionSchedule runtime 已随 Agent 长期生命周期启动。
+     *
+     * 关键点（中文）
+     * - ActionSchedule 不作为 plugin 注册，但它依赖 plugin action 执行能力。
+     * - 因此这里放在普通 plugins 启动之后，避免到期任务执行到尚未启动的 plugin。
+     */
+    private ensureActionScheduleRuntimeStarted;
+    /**
+     * 停止 ActionSchedule runtime。
+     *
+     * 关键点（中文）
+     * - Agent 停止时先停 ActionSchedule，再停普通 plugin，避免关停期间继续触发 action。
+     */
+    private stopActionScheduleRuntime;
+    /**
+     * 启动当前 agent 的本机 RPC server。
+     */
+    private startRpc;
+    /**
+     * 停止当前 agent 的本机 RPC server。
+     */
+    private stopRpc;
+    /**
+     * 读取当前项目配置。
+     *
+     * 关键点（中文）
+     * - 若项目根目录尚未存在合法 `downcity.json`，会退回最小 SDK 占位配置。
+     * - 这样可以允许纯 SDK 场景在尚未初始化项目时继续装配本地 Agent。
+     */
+    private loadConfig;
+    /**
+     * 注册当前 agent 可见的 plugin 实例。
+     *
+     * 关键点（中文）
+     * - SDK 只注册宿主显式传入的 plugin 实例，不再隐式装配 built-in 集合。
+     * - 所有 plugin 在注册前都会绑定到当前实例 runtime。
+     */
+    private registerPlugins;
+    /**
+     * 创建 plugin 注册表。
+     *
+     * 关键点（中文）
+     * - registry 本身不直接持有静态上下文，而是通过 resolver 延迟读取当前 `agentContext`。
+     * - 这样 hook 调度与 availability 判断都能复用同一份上下文视图。
+     */
+    private createPluginRegistry;
+    /**
+     * 创建对外暴露的 plugin 调用门面。
+     */
+    private createPluginPort;
+    /**
+     * 读取当前 agent 静态 instruction blocks。
+     */
+    private loadInstructionSystemBlocks;
+    /**
+     * 读取当前可用 plugin 暴露的 system blocks。
+     *
+     * 关键点（中文）
+     * - 单个 plugin system 失败不会阻断 session 主链路。
+     * - 这里只加载当前启用且可用的 plugin system 文本。
+     */
+    private loadPluginSystemBlocks;
+    /**
+     * 创建实例级 runtime 视图。
+     *
+     * 关键点（中文）
+     * - runtime 描述的是当前 agent 实例持有的长期状态。
+     * - 其他 server / plugin / transport 都通过这个视图读取统一状态。
+     */
+    private createRuntime;
+    /**
+     * 创建统一执行上下文。
+     *
+     * 关键点（中文）
+     * - `AgentContext` 是执行期能力视图，不是状态实体本身。
+     * - plugin runtime、chat runtime、shell tool 都通过这里消费能力。
+     */
+    private createAgentContext;
+    /**
+     * 获取或创建一个本地 Session 实例。
+     *
+     * 关键点（中文）
+     * - 同一个 `sessionId` 在单个 Agent 实例内只会装配一次。
+     * - 新建 session 时会把 instruction 与 plugin system 读取能力注入进去。
+     */
+    private getOrCreateSession;
+    /**
+     * 为 session 应用默认模型。
+     *
+     * 关键点（中文）
+     * - 同一个 session 在单个 Agent 实例中只会执行一次配置装配。
+     * - 默认模型会在首次访问/首次执行前写入当前 session。
+     */
+    private applySessionDefaults;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/bin/agent/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"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"}