SDK / Platform 边界与重建基线
日期：2026-10-15。状态：已确认的交付与职责边界；公共接口签名和新实现尚未交付。
旧业务代码已经清除。项目先形成 agentloom-sdk 和 agentloom-platform 两份独立交付物，继续共用当前仓库，是否拆仓库另行决定。当前目录不保留旧实现的兼容代码。
1. 两份交付物
| 范围 | SDK | Platform |
|---|---|---|
| 用户、空间、权限、应用 CRUD | 不包含 | 负责 |
| 草稿、发布、配置版本选择 | 不包含 | 负责，并保存恢复时使用的原配置 |
| Agent 与 Workflow 构造 | 接收执行配置、节点绑定和依赖，构造可执行程序 | 将用户配置解析成 SDK 参数 |
| 模型 | 调用接口、供应商适配、流式响应处理 | 凭据、模型目录和配置管理 |
| Skill、Tool、MCP、Hook | 加载与执行协议、资源访问范围、事件与调用处理 | 上传／导入、配置、资源目录和应用授权 |
| 执行 | Loop、轻量 Agent 引擎、Workflow 引擎、预算、并行和调用 | 接收请求、鉴权、安排运行机器、调用 SDK |
| 上下文与检查点 | 管理轮次与角色上下文、保存现场、恢复、执行权保护 | 提供存储依赖及会话／Run 关联，展示运行状态 |
| 文件与沙箱 | 使用工作空间及沙箱适配器，执行路径范围控制 | 分配应用文件根、准备挂载、管理资源生命周期 |
唯一业务依赖方向为 Platform → SDK。SDK 不导入平台模块，不回查平台应用、发布记录或用户，不要求 user_id、space_id 或 AgentRelease。独立开发者可以直接使用 SDK。
SDK 可以读写执行所需的持久存储，但通过注入的存储协议访问；这不等于依赖平台业务数据库。内存实现可用于最小示例，进程故障恢复需要可持久读取的存储。
2. 构造与调用
平台先读取应用配置、选择版本并完成权限检查，再准备模型客户端、能力资源、Prompt、策略、存储和工作空间，最后构造 SDK Agent。SDK 不负责解析平台发布 ID。
| 时机 | 输入 |
|---|---|
| 构造可执行对象 | 已解析的行为／图配置、模型与能力、执行策略、存储和环境依赖 |
| 发起一次执行 | 用户输入、会话标识、稳定 Run 标识 |
| 故障后重新构造 | 原 Run 的执行配置、同一持久存储和环境范围、原 Run 标识 |
配置可以直接传值；文件、Skill、历史消息和检查点可通过已注入的路径、加载器或存储接口按需读取，不要求一次全部加载进内存。
new Agent 创建进程内对象，不等于创建新 Run，也不在构造函数里偷偷开始业务执行。对象的固定配置与每次运行的上下文、预算、进度必须分离。
3. 发布与恢复配置的责任
发布、配置版本和恢复时选择哪份配置全部归调用者；平台场景由 Platform 负责，独立 SDK 场景由集成方负责。
SDK 不维护平台配置版本指纹，不比较应用发布版本，不在恢复时自行选择最新版。调用者必须传回该 Run 对应的配置。检查点自己的数据格式和执行协议校验仍属于 SDK 的存储／恢复契约，与平台发布管理区分。
旧 SD-3 / ID-1 中 AgentRelease、OwnerRef.space_id、发布绑定 hash、平台表外键等混合字段不能直接成为 SDK 必填字段；保留的领域和事务方案需要按此边界重新划分。
4. 恢复属于 SDK
平台用相同构造和执行入口交回原 Run；SDK 判断该 Run 的状态并处理：
| 执行现场 | SDK 行为 |
|---|---|
| 尚未建立 | 初始化本次执行 |
| 未完成且允许接管 | 取得执行权，从可靠保存点恢复 |
| 仍由有效实例执行 | 不启动第二个执行者，不直接抢占 |
| 已进入终态 | 返回已有结果或终态错误，不重新执行 |
同一 Session 的新提问创建新 Run。机器故障后继续原请求沿用原 Run；重复进入执行入口不重复追加原始输入。补充说明使用输入接收协议，不能靠重复 invoke 隐式追加。
平台负责故障检测和机器调度，不需要查询各 Executor 的 Loop 位置、拼接上下文、判断汇合条件或重写恢复算法。只有相同的 Session 标识不足以恢复一次执行，必须关联具体 Run。
Plan–Executor 的恢复
保存 Planner 和各次 Executor 调用的私有上下文、执行阶段、调用结果、批次／汇合关系、剩余额度及截止时间。
例如 Planner 已委派 A、B、C，A/C 已完成并保存，B 正在第三次 Loop。恢复时复用 A/C 结果，接回 B 原任务和上下文；B 完成后全批交给原 Planner 继续下一次 Loop。不会把所有 Executor 历史塞回 Planner 重新规划，也不从计划文本猜测执行位置。
已保存的工具结果只需继续消费；未完成的模型输出不能当作完整决策；外部调用已发出而结果未保存时属于结果可能不确定的情况，不能宣称检查点提供外部副作用恰好一次保证。SDK 恢复的是可靠保存的状态，不是 Python 栈或模型生成到一半的 token 位置。
业务失败后是否调整计划由 Planner 决定。进程重建本身不触发全新规划，也不重新分配总预算。
内外层的交接
轻量 AgentGraphEngine 与通用 WorkflowEngine 均归 SDK，分别保存各自状态，经统一检查点协议和父子调用关联恢复。Workflow 的 AgentNode 必须接回原 Agent 调用，不在恢复时另起根 Run。
内层 Plan 的 Planner 和 Executor 是同一 Agent 图内的角色任务；同类型两次委派产生两个私有上下文的 NodeTask。普通 Tool／MCP 调用是 Operation，不因此新建图实例。外层调用完整 Agent 才通过 AgentNode 进入对应内层图范围。
5. 当前仓库清理范围
已移除旧前端、后端、Runtime、图模块、工具 SDK、配套业务测试、数据库迁移、部署脚本和产品依赖清单，同时删除旧 API、数据库、Hook、工作区、Embedding 与运维使用说明。
保留产品设计约定、领域／检查点／事件等设计草案及文档站。Git 历史从本次重建基线重新开始。本地 .env、用户未提交的 Agent/Skill 示例、私有文件不纳入源码删除或 Git 提交；原 Demo 的本地 hosting 元数据移至被 Git 忽略的 work/rebuild-preserved/。测试服务器和数据库未在本次操作中变更。
新目录只是结构，不表示 SDK 或平台已经实现。旧 SD-3 / ID-1 的详细字段、接口和 Schema 仍需按新边界调整，不作为当前可执行 SDK 的契约。其他设计草案与本文冲突时，以本文已确认的交付边界为准。
6. 重建顺序与验收
- 明确 SDK 公共构造／执行接口、角色与能力配置、Run 和恢复端口；平台身份和发布数据留在调用方。
- 实现 ReAct、Plan–Executor 最小闭环与持久恢复，独立于平台测试；再实现 Workflow 内核适配和 AgentNode 交接。外层设计必须覆盖，不能用空实现宣称兼容 LangGraph。
- 交付三个可独立运行的示例：ReAct 的模型—工具循环；Plan 的委派、上下文隔离与汇合；Workflow 的状态、能力节点与完整 Agent 组合。
- 对原 Run 的跨进程恢复、已保存结果不重做、重复输入不追加、有效 owner 不被抢占和预算不重置做确定性验收。模拟模型与真实模型分别报告。
- Platform 仅通过 SDK 公共接口装配执行，再建设管理端、API 与新部署流程；不能通过导入 SDK 私有实现补全公开接口的缺口。
验收底线：移走整个 Platform 后，SDK 及三个示例仍可独立运行。当前尚未满足该运行验收条件；本次只完成旧源码清理和重建结构。