SDK Surface

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

第一层：日常核心

大多数本地应用只需要：

• Workspace：创建项目资源与安全边界，并接收 Shell。
• Agent：组合身份、模型、指令、Tools 与 Sessions。
• City：持有 Workspaces、Power 唯一实例、Agent/Group 集合与 transport。
• agent.sessions.create({ workspace }) / get()：创建或恢复当前目录的 Session。
• agent.session()：打开 Agent 自己的那段对话。
• session.prompt()：启动一次 Turn。
• turn.finished：等待最终结果。
• agent.dispose()：释放 Agent 的 Sessions 并解除当前 City 装配关系。

const workspace = new Workspace({ id: workspace_id, path, shell });
const agent = new Agent({ id, model });
// Session 在创建时选择 Workspace。

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

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

第二层：常用进阶

Agent 与 Workspace

• agent.set_instruction()：更新 Agent 静态指令。
• city.powers：添加或移除 Power 实例并调用宿主管理 action。
• city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id })：在明确的 Agent/Workspace 执行作用域查询或调用 Power。
• workspace.get_env() / set_env() / patch_env()：管理项目执行环境。
• agent.get_logger()：读取 Agent 级日志；Shell 从当前选择的 Workspace 获取。

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()；重连后重新读取快照，不要把事件流当作完整数据库。

第三层：框架集成

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

• @downcity/type 的 CityRuntime：自定义组合根嵌入 Agent 时使用的最小 City 跨包协议；具体 City 已经直接实现该协议。
• PowerContext：City 为当前 Agent/Workspace/Session/Turn 投影给 Power 的受限能力视图；宿主不应主动获取或持有它。
• SessionTurnContext：一个 Turn 中统一管理身份、生命周期、Step、输入与输出协作的执行上下文；Power 只接收其只读投影 PowerExecutionContext。
• create_session_turn_context(...)：自定义执行器或运行时组件创建上述 Turn Context 的标准工厂。
• SessionExecutor 与 SessionExecutorPort：模型请求与 Tool Loop 的默认执行器，以及 SessionLoop 接受注入的执行端口。
• AgentSession 等接口：替换或扩展默认实现。
• RPC/HTTP 类型：实现自定义 transport 或协议集成。

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

本地与远程

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

生命周期规则

一个 Agent → 多个 `agent.sessions.create({ workspace })` Session → 一次 agent.dispose()

• Agent 不绑定单一 Workspace，同一个 Agent 可以进入多个 Workspace。
• AgentSessions 持有 Agent 的 Session；每个 Session 独立接收 Workspace 与 Power 上下文。
• agent.dispose() 会释放 Session 使用的资源并解除当前 City 绑定；Power 唯一实例和生命周期由 City 收口。
• RemoteAgent.close() 只关闭客户端连接，不释放服务端 Agent。

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