按日常使用、常用进阶和框架集成三个层级理解 Agent SDK 的公开能力

SDK Surface

@downcity/agent 的根入口会导出完整的扩展类型，但普通应用不需要理解全部导出。先掌握日常核心，再按场景进入 Session、Plugin 或 transport 集成层。

第一层：日常核心

大多数本地应用只需要：

Workspace：创建项目资源与安全边界，并接收 Shell。
Agent：组合模型、指令、Tools、Plugins 和 Sessions。
agent.sessions.create() / get()：创建或恢复 Session。
session.prompt()：启动一次 Turn。
turn.finished：等待最终结果。
agent.dispose()：释放 Agent 及其独占 Workspace。

const workspace = new Workspace({ path, shell });
const agent = new Agent({ id, workspace, model });

try {
  const session = await agent.sessions.create();
  const turn = await session.prompt({ query: "检查项目" });
  const result = await turn.finished;
} finally {
  await agent.dispose();
}

本地 SDK 是 session-first 的：Agent 负责组合，真正承载交互和执行状态的是 Session。

第二层：常用进阶

Agent 与 Workspace

agent.ready()：需要显式启动检查点时等待 Plugin runtime。
agent.set_instruction()：更新 Agent 静态指令。
agent.plugins：查询、控制或调用 Plugin。
workspace.get_env() / set_env() / patch_env()：管理项目执行环境。
agent.get_logger() / get_shell()：宿主集成入口。

Session

get_info()：读取 Session 状态。
subscribe()：订阅实时 Mutation。
messages()：读取消息快照。
stop()：停止当前执行。
system()：读取当前 system。
interactions() / respond()：处理审批、问题等用户异步交互。
fork()：从现有 Session 创建分支。
snapshot() / syncshot()：管理本地 Session system 快照。
set({ model })：只覆盖当前本地 Session 的模型。

如果应用有实时 UI，应先读取初始 Session 与 Message 快照，再建立 subscribe()；重连后重新读取快照，不要把事件流当作完整数据库。

第三层：框架集成

以下能力只在构建 Plugin、服务端或自定义运行时组件时使用：

PluginContext：Agent 投影给 Plugin 的稳定能力视图；宿主不应主动获取或持有它。
SessionTurnContext：一个 Turn 中统一管理身份、生命周期、Step、输入与输出协作的执行上下文；Plugin 只接收其只读投影 PluginExecutionContext。
create_session_turn_context(...)：自定义 Executor 或运行时组件创建上述 Turn Context 的标准工厂。
AgentSession、SessionExecutor 等接口：替换或扩展默认实现。
RPC/HTTP 类型：实现自定义 transport 或协议集成。

网络服务实现位于 @downcity/server。本地 Agent 不监听端口，也不管理 transport 生命周期。

本地与远程

能力	本地 `Agent`	`RemoteAgent`
创建、获取、列出 Session	支持	支持
`prompt()`、订阅、消息、停止、审批、fork	支持	支持
注入 Workspace、Shell、Tools、Plugins	支持	不支持
设置 Agent 默认模型	支持	不支持
`session.set({ model })`	支持	不支持
`session.set({ security })` / `session.status()`	支持	支持
`snapshot()` / `syncshot()`	支持	不支持
管理服务端 transport	不负责	只连接

远程 Session 的模型与 system 持久化策略始终由服务端宿主决定。

生命周期规则

一个 Workspace 实例 → 一个 Agent → 一次 agent.dispose()

Workspace 由调用方构造，绑定后由 Agent 统一释放。
多个 Agent 可以指向同一物理目录，但必须分别创建 Workspace 实例。
agent.dispose() 会释放 Plugin runtime、Workspace、Shell、PTY 和 Sandbox。
RemoteAgent.close() 只关闭客户端连接，不释放服务端 Agent。

继续阅读：Agent API和Session 总览。

SDK Surface

目录