Agent 设计约定
更新日期：2026-10-15。
当前进入 SDK / Platform 重建阶段。旧业务代码已移除，两份交付物只有目录骨架。前九节保存产品行为与已约定的架构边界；第十节列出工程提案和设计入口。保留的 SD-3 / ID-1 详细设计需按 SDK / Platform 边界重新划分归属；类名、存储介质、票据和提交算法不因出现在链接中就视为全部确认或已经实现。
产品同时支持配置化 Agent和用户编排的 Workflow，先明确领域对象、操作、生命周期及其关系，再确定模块接口与执行协议。已确认采用双引擎：内层使用轻量 AgentGraphEngine，外层使用 WorkflowEngine。 两者统一领域身份、能力调用、Run 控制与检查点管理，各自维护自己的调度规则和恢复载荷，不强制使用同一个执行内核。外层工作流本轮不要求代码实现，但属于产品目标，Definition、节点、实例、接口和检查点必须纳入设计。 外层将复制并适配 LangGraph 的相关设计逻辑与源码，融合进 AgentLoom 包内；不以项目直接依赖 langgraph 包作为方案。现有原型不限制设计，允许重写。
完整入口：系统设计总览、领域 UML、图与 Node、检查点、领域接口。
一、产品目标与基本概念
交付边界与 SDK 恢复
项目分为 agentloom-sdk 和 agentloom-platform 两份独立交付物，暂不拆 Git 仓库。SDK 面向代码构建 ReAct、Plan–Executor 和 Workflow；平台基于 SDK 实现配置生成应用。SDK 不包含用户、空间、应用管理、草稿和发布版本管理，也不要求平台业务数据库。
平台在构造 Agent 前准备完整执行配置、模型与能力、存储及工作空间等依赖。SDK 可以通过注入接口按需读取 Skill、历史和检查点，不回查平台的应用、发布记录或用户。下文应用创建、发布、权限与管理版本的规则属于平台；SDK 的定义是可执行配置，不是平台管理实体。
发布版本选择和恢复时找回原配置由调用者负责。SDK 不维护平台配置版本指纹或判断应用发布版本兼容性；检查点自身的格式校验仍属于 SDK 存储协议。
故障恢复全部在 SDK 内完成。 平台重新构造 Agent，并将原 Run 标识及存储依赖交给执行入口即可。构造对象不等于创建新 Run；同一 Session 新提问才建立新 Run，接管保留原 Run，不能重复添加原始输入、重置额度或抢占仍有效的执行者。已结束 Run 返回已有结果或终态错误。
Plan–Executor 恢复 Planner 与各 Executor 的私有上下文、执行位置、结果和汇合状态：已完成结果复用，未完成任务从可靠保存点继续，全批交付后 Planner 继续 Loop。机器故障不自动触发重新规划，也不把所有 Executor 过程塞回 Planner。外部调用结果未知时不能假设重跑没有副作用。
两个引擎及恢复适配均属于 SDK。平台负责机器调度、配置与资源准备，不实现角色恢复算法。三个 SDK 独立示例与平台解耦后再实施；本次移除旧代码不修改测试服务器和数据库。
产品提供哪些搭建方式
用户既可以配置一个完成某一类工作的 Agent，也可以把多个已发布 Agent 和工具编排成 Workflow。平台提供共享的模型连接、Prompt、Skill、Tool、MCP、Hook、上下文和执行环境能力，并支持发布后通过页面或 API 使用应用。
| 搭建方式 | 用户配置什么 | 运行时由谁决定下一步 |
|---|---|---|
| ReAct Agent | 模型、Prompt、能力、上下文与执行策略 | 入口角色在模型—动作—反馈 Loop 中决定调用工具或完成任务 |
| Plan–Executor Agent | Planner 配置、Executor 角色及各自能力 | Planner 决定普通工具调用或任务委派；Executor 在私有上下文中完成任务，结果汇合后 Planner 继续决策 |
| Workflow 编排 | 完整 Agent／Tool／MCP 节点、连接、输入输出映射、条件、循环、并行与汇合 | 外层图引擎按用户定义的结构和运行状态调度；其中 Agent 节点内部仍按自己的执行模式工作 |
Agent 有 ReAct、Plan–Executor 两种执行模式；Workflow 是组合这些应用和能力的另一种产品形态。 管理端可以统一提供创建入口，领域上仍区分 Agent 与 Workflow，不把 Workflow 硬塞进 Agent 的 mode 字段。Agent 创建后不再修改执行模式。Planner 可以直接调用自身配置的普通工具，工作流也可以只编排工具而不包含 Agent。
Workflow 编排的产品范围
- 选择步骤：添加完整已发布 Agent、内置／自定义 Tool 或 MCP 工具。Agent 节点可以引用 ReAct 或 Plan–Executor Agent；内部 Executor 是该 Agent 的角色，不直接当作独立应用节点。
- 配置流转：定义入口、结束、执行连接、条件分支、受控循环、并行分派和汇合。模型可以产生条件判断所需的数据，图引擎只能选择定义允许的路径；不将 Planner 的计划文本自动解释为工作流拓扑。
- 配置数据：定义工作流输入输出、节点输入来源、结果写入字段以及并行更新的合并规则。共享 GraphState 保存流程业务数据；每个 Agent 的模型上下文保持独立，通过显式输入输出和获准文件引用交换数据。
- 验证和发布：检查节点绑定、资源权限、版本、连接和数据契约，生成不可变 WorkflowRelease。修改草稿不改变正在运行的版本。
- 运行和查看：发布后支持页面和 API 发起执行、查看节点与整次运行状态、结果和错误，并可停止整次运行。故障恢复属于 Runtime，保留已有“用户不需要暂停／恢复按钮”的约定。
- 控制执行：Workflow 单独配置整次运行和流程并发策略；被调用 Agent 保持自己的模型、能力和上下文配置，并接受根 Run 的预算、停止和截止约束。外层并行不自动开启 Agent 内部的工具／Executor 并行。
例如，用户可配置“输入 → MCP 查询 → 并行调用两个资料处理 Agent → 汇合 → Plan–Executor Agent 生成报告 → Tool 保存 → 输出”。其中工作流图由用户配置，Agent 内部的工具使用和委派由模型决策。具体画布交互、导入格式及第一批开放的流程结构随外层实现细化，不因产品目标完整就视为这些界面已经上线。
外层图的状态、同步、调度和检查点计划基于 LangGraph 源码适配；AgentLoom 负责应用发布、能力授权、Hook、上下文、文件环境及内外层调用衔接。内层只处理 ReAct／Plan–Executor 的角色任务与动作批次，不引入外层通用工作流的状态和同步机制。两套检查点适配器接入同一持久化基础设施，外层通过固定调用引用等待内层结果；故障后接回原内层实例，不能重新执行已完成 Agent。具体关系见双引擎与检查点适配。
基本概念及其边界
| 概念 | 含义 |
|---|---|
| Agent 应用 | 用户创建、配置和发布的整体，拥有固定执行模式、文件根及内部角色配置 |
| Workflow 应用 | 用户编排完整 Agent 与能力的应用，拥有自己的流程定义、发布、输入输出和运行策略 |
| 角色配置 | 一类工作的 Prompt、能力选择和执行职责，例如 Planner 或资料检索 Executor |
| 图定义／节点绑定 | 图定义描述位置、连接和数据流转规则；发布绑定将位置关联到角色、能力或完整 AgentRelease |
| Session | 归属于一个 Agent 的连续会话，跨多次提问和多台机器保留历史 |
| WorkflowSession | 归属于一个 Workflow 的交互记录；不作为所有被调用 Agent 的共同会话，不自动读取它们已有的 Session |
| Run | 一次 Agent 提问或 Workflow 执行请求对应的逻辑运行，覆盖内部任务、执行中输入及故障恢复；调用子 Agent 不另起根 Run |
| Loop | 一个业务角色的一次模型决策及其相关动作反馈；与用户提问轮次、网络尝试次数分别计量 |
| 角色执行 | 一次入口任务或 Executor 委派；拥有私有上下文与进度，多次 Loop／等待／恢复沿用同一身份 |
| 完整 Agent 调用 | 一次完整应用执行，包含内部流程及所有角色任务；不同于单个 Executor |
| AgentNode／CapabilityNode | 前者把完整 Agent 接入工作流，后者执行一个 Tool／MCP 能力；普通能力调用不额外创建 Agent 图 |
| 图执行范围 | 内层 Agent 和外层工作流各自的执行、状态及恢复范围 |
| 双引擎 | AgentGraphEngine 负责轻量角色调度；WorkflowEngine 负责用户工作流。每个图实例固定一个所属引擎 |
| GraphState／角色上下文 | 前者供工作流节点按契约交换业务数据；后者保存一个角色给模型使用的消息和摘要，两者不自动合并 |
| 进程执行容器 | 本次 Run 在当前机器上的服务和连接；故障接管时重建，不作为持久身份 |
配置、长期资源、进程内对象和一次执行的状态具有不同生命周期。新提问创建新 Run；恢复未结束的 Run 沿用原逻辑身份，在接管机器上重建进程内对象。
二、Agent 配置
可配置项按 Agent 独立保存
下文 Agent 的所有“可配置”均指每个 Agent 可以单独设置并保存自己的配置。 平台提供默认值，不要求各 Agent 共用相同参数。Workflow 的结构、输入输出和根运行策略归 Workflow 自己配置，不反向覆盖所引用 AgentRelease；相关产品范围见第一节。
| 配置组 | 内容 |
|---|---|
| 工作定义 | 名称、描述、执行模式、Prompt、Prompt 变量，以及可选的标准输入和输出格式 |
| 模型 | 模型连接、Think 开关及强度 |
| 上下文 | 历史完整过程保留轮数、压缩触发条件、用户补充的压缩 Prompt |
| 执行 | Loop 总额度、Run 超时、单次调用超时、并行开关、Executor 最大并行数、自动重试开关、总尝试次数及等待间隔 |
| 运行环境 | 持久沙箱开关、Agent 固定文件根与挂载点、资源及会话工作目录 |
| 能力 | Skill、内置及自定义 Tool、MCP 的选择和允许配置的参数 |
| 协作与扩展 | Executor 角色配置、按触发时机组织的 Hook 配置 |
Planner 和 Executor 可以按角色设置 Prompt、Prompt 变量、任务输入输出要求及 Skill、Tool、MCP，这些角色配置属于 Agent 整体配置。创建 Executor 时可以一次复制 Planner 的能力选择，此后独立维护，不随 Planner 工具集变化自动调整。共享文件不代表共享能力权限或模型上下文；平台管理的资源实体仍可复用，无需为每个 Agent 复制一套资源。
Executor 继承主 Agent 模型，不独立选择模型；压缩 Agent 继承当前角色使用的模型，也不开放独立模型选择。
配置默认值
以下数值均可在单个 Agent 上调整；“不可独立选择模型”等明确约束不因本表而改变。本表的 Run 额度与时限首先指直接 Agent 调用；在 Workflow 中，完整 Agent 调用另外接受工作流根 Run 的控制，不能每调用一个 Agent 就重置整次执行的总额度。
| 配置 | 默认值 | 生效范围 |
|---|---|---|
| 历史完整过程保留轮数 N | 2 | 当前提问之外，同一 Session 最近 N 次已结束提问 |
| 上下文压缩触发比例 | 80% | 每次业务模型调用前检查当前角色上下文；具体预算公式由详细设计定义 |
| 业务 Loop 总上限 | 100 | 同一 Run 的 Planner 与所有 Executor 合计共享；ReAct 模式由入口角色使用 |
| Run 总超时 | 1 小时 | 包含模型输出、工具、Executor、压缩、排队及重试 |
| 并行开关 | 关闭 | 普通工具、MCP、脚本及 Executor 委派 |
| Executor 最大并行数 | 2 | 开启并行后，同一轮 Planner 调用批次的活跃 Executor 实例 |
| Runtime 自动重试开关 | 关闭 | 控制 Runtime 对同一逻辑调用是否自动再次尝试 |
| Runtime 总尝试次数 | 2 次，包含首次执行 | 开启自动重试时，首次加最多一次自动重试；LLM 新调用独立计数 |
| 重试等待间隔 | 2 秒 | 等待仍计入 Run 总时限 |
| 工具／MCP／脚本单次尝试超时 | 10 秒 | 每次实际执行尝试，并受 Run 剩余时限约束 |
| 模型首输出超时 | 1 分钟 | 等待模型开始输出；开始后取消此项计时，Run 总时限继续生效 |
最大并行数不会自动开启并行。平台不管理模型供应商或模型连接的请求并发配额，该容量由模型采购者把控。
Run 配置与发布版本
- Run 使用启动时解析的 Agent 发布配置快照，执行、重试和故障恢复期间不热切换配置。
- 发布会中断进行中的会话执行，接入统一停止流程；中断不等于删除 Session 或历史。
- 同一 Session 后续新 Run 使用最新已发布配置。
- 后续需要支持按版本号选择 Skill、Plan、Prompt 等资源；版本对象及 API 纳入技术设计。
配置归属 Agent，不改变执行预算的作用范围：同一 Run 的业务角色仍共享 Loop 额度和截止时间，创建 Executor 不会获得一份新的总额度。
三、Agent Loop 与任务委派
一套 Loop，两个执行模式
使用同一种图模型组织 ReAct 和 Plan–Executor。ReactNode 继承 Node，PlannerNode 与 ExecutorNode 继承 ReactNode，复用模型—动作—反馈循环；Planner 增加委派与结果处理能力，Executor 完成被委派任务。
ReAct 使用一个入口 ReactNode；Plan–Executor 增加 Executor 及委派／结果返回路径。图引擎负责跨节点调度、按配置并行、汇合、等待和继续；节点负责自身任务的循环与上下文，普通工具通过能力模块执行。
这里的图引擎具体指 AgentGraphEngine。内层行为是“Planner → Tool／MCP／Executor → 本批 Join → 原 Planner”，有最终答案则结束；Replan 是 Planner 基于反馈调整方案的行为，不额外强制建立一个模型节点。Tool／MCP 是调用路径，Join 是批次结算条件，不能仅因出现在流程图中就把它们全部转换成角色节点。行为图及边界见内层循环。
一次节点任务与一次引擎激活分开： 节点任务从接受输入持续到最终交付，可以经历多轮 Loop 和多次激活。一次激活推进任务，直到完成、失败或需要等待其他节点等调度边界，不固定为一轮模型决策。等待后的新激活继续原执行身份和上下文。
准备上下文 → 必要时压缩 → 调用模型 → 解释动作
├─ 最终回答 → 校验 → 完成
│ └─ 不合规 → 下一轮
└─ 普通工具／Planner 委派 Executor
→ 本批结果全部汇合 → 下一轮Executor 在自己的上下文中执行同样的模型—工具—反馈循环。Planner 等待一批 Executor 时，它们仍能继续各自的内部 Loop；结果全部到齐，原 Planner 才继续下一次决策。
上下文、模型、能力调用、文件与环境使用独立服务接口，可分别替换，并通过统一 EventBus 交互；Hook 在有序拦截阶段校验和修改请求／结果，也可订阅生命周期通知。节点提供可恢复阶段与调用状态，由图引擎协调保存与恢复。一次激活内部连续运行多轮时，也需要在安全点记录中间状态，不能只保存最终结果。调用代理统一处理请求与结果，公共 Loop 提供阶段，检查点由基础设施提交，不要求业务节点到处手写发送和保存逻辑。具体状态结构及接口见节点协议和检查点协议。
角色配置、执行实例和进程对象
Run
└─ Planner 执行 P1（自己的 Loop 与上下文）
├─ 资料检索 Executor E1（自己的 Loop 与上下文）
└─ 资料检索 Executor E2（自己的 Loop 与上下文）示例共三个逻辑角色执行实例。E1、E2 引用同一角色配置，但身份、上下文和进度独立。Loop 或等待后继续不创建新任务；新委派创建新实例。恢复继续原逻辑身份，在接管机器上重建进程对象和服务连接。逻辑角色执行、完整 Agent 调用和进程推进的具体实体映射见第十节及领域模型，这些类型属于工程提案。
ReAct 模式只有一个入口角色执行，不创建业务 Executor。Plan 默认不添加通用执行器，只使用用户配置的角色；Executor 不递归委派。压缩作为独立专职任务，有自己的 Prompt、输入与进度记录，继承当前模型，不创建业务 Executor，也不计入业务 Loop 额度。
操作与执行服务
| 操作 | 要求 |
|---|---|
| 内置／自定义工具、MCP | 区分一次逻辑调用与实际网络尝试，保存关联输入与结果 |
| 阅读 Skill 文件 | 受角色授权及文件范围限制，结果进入所属角色上下文 |
| 执行 Skill 脚本 | 在受限环境中执行，保留执行状态，收束后才能清理工作文件 |
| Executor 委派 | 创建独立角色执行，按配置调度并将最终结果交回 Planner |
Executor 以工具形式供模型选择，目录标记为委派动作；Planner 提交委派，由图引擎创建和调度 Executor 任务。普通工具操作通过能力模块执行，不创建新的 Agent。模型／工具等外部调用保留 Operation／Attempt；节点运行、有效上下文及调用身份按SD-3 数据契约关联。
一次模型响应中的调用仍组成固定批次，按 Agent 配置控制串行／并行并汇合结果。批次记录、普通能力执行和节点调度分别承担职责；不得出现多个互相竞争的节点调度者。具体协调器及接口属于详细设计。
调用方使用普通接口，由 Runtime 装配时注入的代理形成带可信身份的事件，进入统一 EventBus。HookManager 在执行和交付前有序校验、允许／拒绝及修改；对应领域 Manager 使用最终有效参数处理并返回有效结果。每条执行请求有一个执行负责人，单次返回一个最终响应，批次等待所有成员后返回响应列表；Hook 的中间决定由系统合成和记录，不要求 Loop 遍历解释。模型、上下文、文件与 Skill、脚本、MCP、委派、环境、Run 控制和交付均可接入同一总线。内部纯函数及底层持久化不递归事件化，处理器执行原始实现以避免重复。详细清单见EventBus 与交付设计。
父子 Agent 的上下文与交付
Planner 向 Executor 传递明确任务、必要约束与材料；系统绑定可信的身份、模型、授权能力、文件范围和预算。Executor 使用自己的角色 Prompt 和私有上下文，不自动继承 Planner 的业务 Prompt 或完整历史。
Executor 的最终汇总结果交给 Planner，失败时交付对应错误。完整的内部模型和工具过程保留在 Executor 自身记录中，不默认注入 Planner。文件按当前 Session／Run 的授权范围共享；共享文件不需要为各 Executor 复制隔离目录。
Planner 基于结果继续决策、重新委派或回答。Executor 执行结束与业务目标满足分别表达，不自动把计划中的相关步骤都标记完成。
四、批次、并行、重试与额度
批次汇合
一个角色的一次模型响应发出的调用组成一个批次。串行和并行均遵守：本批所有成员取得成功或错误结果后，该角色才进入下一轮模型决策。
- 单项结果及时保存，并可展示进度；先完成一项不提前触发本角色下一次模型调用。
- 单项业务失败不取消其他成员；无法识别、未启用重试或重试耗尽的工具错误也纳入批次结果。
- Executor 在自己的私有上下文中运行 Loop；Planner 等待不阻止 Executor 继续其内部模型与工具调用。
- 用户停止、Run 超时、额度耗尽和机器故障是控制流程，不能全部伪装成普通工具错误。
并行调度
是否并行由 Agent 配置决定，LLM 同时提出多个调用不自动开启并行。
关闭并行时，同批逐项执行。开启时按配置启动调用；Executor 最大并行数统计同一轮 Planner 批次内已启动、尚未结束的实例，同一种配置的两次委派算两个实例。
超过活跃实例上限的委派等待调度，同一种角色的多次委派不能合并计数来绕过限制。普通工具不占 Executor 名额，平台不另设工具并发数量配置或跨 Run 的模型并发配额。名额获取、释放和补位协议纳入技术设计。
Runtime 自动重试与 LLM 新调用
Runtime 自动重试由开关、异常分类、尝试次数及剩余时限共同控制；不根据工具是否声明幂等、可重试或可查询决定是否重试。
- 成功结果保存后参与本批汇合。
- 开启重试且异常符合规则时，等待配置的间隔后，在同一逻辑调用下追加尝试。
- 关闭重试、异常不符合规则、无法识别或次数耗尽时，将工具错误纳入批次；本批收齐后交给 LLM 决策。
- 无法确定外部操作是否生效时，如实记录“结果未知”；不额外增加强制核对或工具幂等声明门槛。
异常分类依据错误码、异常类型与调用阶段，不仅凭错误文案猜测。工具／业务提供方负责业务防重，平台记录实际尝试，不承诺外部副作用恰好一次。
尝试次数只限制 Runtime 对同一逻辑调用的执行。 自动重试复用已确定的业务参数和调用身份，不要求 LLM 再生成参数。LLM 后续调用无论参数相同或不同，都作为新调用独立计数；Runtime 不猜测它是否属于业务上的重复尝试。
例如调用 A 两次尝试均失败，LLM 再发起调用 B；开启重试时 B 仍可获得自己的两次尝试额度。整体持续执行由 Run 共享 Loop 总额度与总时限限制。恢复原调用或复用已保存结果不算新调用。
Loop 计量与耗尽
- 同一 Run 的 Planner 和所有 Executor 共用业务 Loop 总额度，角色同时保留自己的 Loop 序号。
- 压缩 Agent 不计业务 Loop，但记录实际模型用量及耗时，仍受 Run 总时限约束。
- 失败返回内容进入后续 Loop 的模型输入时，该失败业务 Loop 计数；内部透明重试的失败没有进入模型上下文，不额外计业务 Loop。
- 同一业务 Loop 中多个工具失败，不按失败工具数量额外增加 Loop。
- 消费保存结果与重新执行分别记录；故障恢复不能重复扣同一笔已记录额度或重置预算。
最后一次合法 Loop 可以正常执行并完成任务。以总上限 100 为例，第 100 次允许执行；如果本次完成任务，Run 正常结束，不能仅因已用次数等于上限而判失败。需要第 101 次时，Runtime 在开始前拒绝执行，进入 Loop 额度耗尽流程。
额度耗尽由 Runtime 返回异常并结束执行，不预留或追加模型总结调用。已保存记录保留；尚未完成的任务不能伪装为成功。格式修正也遵守同一上限，不额外获得 Loop。
流式超时
模型超时限制等待开始输出的阶段。开始输出后，不能继续用该首输出时限截断整条流；整次 Run 的截止时间始终生效。创建 Executor、自动重试及跨机器接管都不重新起算 Run 时限。
模型流的连接中断、停滞检测和异常处理由模型连接层负责；异常时是否自动重试，由当前 Run 固定的 Agent 配置决定。连接层沿用自动重试开关、总尝试次数和间隔，默认关闭自动重试；不再由上层另套一组重试。
停止或 Run 截止后，不得因重试等待间隔结束而重新发起调用。首个有效输出事件、停滞判定及重试片段的记录与展示纳入连接协议技术设计；不能因此恢复整条流的一分钟超时。
五、会话、历史与压缩
连续会话记录
同一 Session 始终属于同一个 Agent。不同提问可调度到不同机器；每次 Run 的进程内实例随本次执行创建和释放，历史与可恢复现场独立保存。
保存连续的原始用户输入、助手消息、调用及结果，包括失败和用户停止过程。每条用户补充都是正式的用户输入，独立记录为用户消息，保留原文、接收顺序及 Session／Run 关联；不能仅作为临时附注或执行过程元数据保存。
执行中的补充仍属于当前 Run，不因多了一条用户消息就创建新 Run。“最近 N 次已结束提问”按已结束的 Run 计数，不按用户消息条数计数。原始记录与模型可见上下文分开，压缩不删除原始历史。轮次、记录顺序、角色 Loop 序号和调用关联由系统维护，不依赖 LLM 生成内部身份。
历史选取规则
- 当前提问单独保留，不占历史名额。
- 从同一 Session 统一取最近 N 次已结束提问；N 使用当前 Run 固定的 Agent 配置。
- 成功、失败、用户停止均计入，保留实际产生的过程与结束状态。
- 没有结果就标记未完成，不虚构结果；只有用户问题和错误状态的轮次也占一个名额。
- 不因失败、内容少或错误信息向前补找成功轮次；不足 N 次时使用现有轮次。
- 故障恢复原 Run 不增加提问轮次；仍在恢复的 Run 不因进程宕机自动成为已结束历史。
Runtime 检查记录归属、提交状态及调用协议完整性，不判断内容“有用／无用”。N 控制模型输入的历史细节范围，不是原始记录保存期限，也不授权 Executor 读取 Planner 的私有历史。
| 内容 | 组装规则 |
|---|---|
| 当前 Run | 保留当前问题、补充和继续执行所需过程 |
| 最近 N 次已结束提问 | 保留实际过程和结束状态；超过预算时按压缩规则处理 |
| 更早提问 | 按顺序保留该轮全部用户输入（原始提问及每条补充）、最终结果和结束状态，省略中间 Loop 过程；没有最终结果则标记未完成，不虚构成功回答 |
较早轮次的用户补充同样属于用户输入，不能随中间工具调用过程一起省略，也不筛选其“有用／无用”。历史裁剪是跨提问的选取规则，Loop 压缩是在执行中达到预算阈值后的摘要处理。把较早轮次简化为用户输入序列、最终结果和结束状态，本身不要求额外调用压缩 Agent。组装后的模型输入仍遵守上下文预算与 Loop 压缩规则，原始用户消息独立保存。
Loop 内压缩与原始输入保护
在每次模型调用前检查准备发送的上下文。当前输入、补充、模型输出及工具结果都会使上下文增长；只发生一次用户提问也可能触发多次压缩，新输入加入后也可能立即触发。
记录新消息 → 组装本角色上下文 → 检查预算
→ 必要时调用压缩 Agent → 提交摘要与覆盖范围
→ 原文接回当前问题、补充及未覆盖消息 → 调用业务模型- 压缩由独立专职 Agent 承担，不作为 Planner 的业务委派目标。
- 压缩模型继承当前角色模型；默认压缩 Prompt 作为 system prompt，用户自定义内容通过 user prompt 补充，待压缩历史是任务数据。
- 当前原始问题和本轮用户补充由代码原样保护，保持顺序和身份，不能只依赖摘要记住，也不能以“原始库里可回查”代替模型实际可见。
- 压缩期间新接收的补充保留为增量，不能被旧摘要覆盖。
- Planner 与各 Executor 各自压缩自身上下文；共享文件不改变私有消息访问范围。
- 摘要记录覆盖范围并可回查原始历史，恢复后接上未覆盖消息。保留工具交互时，维持调用与结果的协议关联。
- 压缩调用成功即接受摘要，不新增语义质量评分或验收模型；压缩失败抛异常并中断 Run，不能先丢弃旧上下文。
压缩调用成功后，仍检查接回原始问题、补充及未覆盖消息后的完整模型输入。若仍超过模型上下文窗口，Runtime 向用户提示原因并中断执行；不继续向业务模型提交超窗口请求，也不自动反复压缩。受保护输入同样占预算，不得通过删掉当前问题绕过限制。该检查是窗口检查，不是摘要语义质量验收。
80% 阈值的计算口径（包括是否扣除输出预留）与摘要目标长度由详细技术设计确定。
六、用户交互、停止与流式交付
执行中补充与新提问
用户侧支持执行、执行中补充、结束，以及进度和终态通知，不提供暂停／恢复按钮。模型连接保持流式接收；本轮明确默认收齐每次模型响应后再交付结果，不逐字向用户或总线透传。后台故障恢复仍保留。
| 时机 | 输入归属 |
|---|---|
| 当前 Run 执行中输入文字 | 当前 Run 的一条正式用户输入，作为补充按接收顺序保存 |
| 当前 Run 已结束后输入文字 | 同一 Session 的新提问，创建新 Run |
| 点击结束 | 请求结束当前 Run，不删除 Agent、Session 或历史 |
Plan 模式的补充只交给 Planner，在它下一次 Loop 调用模型前注入。Runtime 不推断补充与哪个子任务相关，不广播给 Executor，也不修改已发出的请求。Planner 仍先等待当前批次收齐结果，再结合补充决策；后续委派时由 Planner 显式提供必要说明。
如果服务端已接收补充，但尚未交给模型，当前 Run 就结束了，该补充保存在 Session 记录中，转入同一 Session 的下一次提问，随下一次 Run 交给入口角色；Plan 模式仍只交给 Planner。不能丢弃、误标为已处理或留在已结束 Run 中无法接续。此交接不自动启动新 Run，也不重新启动已结束 Run。补充接收与终态提交的竞态、转交标记、ReAct 注入时点及界面／API 反馈由技术协议定义。
停止与统一清理
停止发出中断通知，由 Runtime 关闭新业务工作的准入，再让已发出的调用在最近的可提交安全边界收束。这里明确“边界”不要求把当前 Loop 尚未开始的所有工具做完：不再启动新的模型调用、自动重试、Executor 或排队动作；在途结果保留，但不触发下一次决策。ReAct 对应入口角色，Plan 对应 Planner 与在途 Executor。这是对原“Loop 完成边界”的执行口径细化。
清理发生在整个 Run 收束之后。 不能某个 Executor 先完成就删除共享工作目录；本 Run 管理的在途任务先收束或终止。清理按持久沙箱开关处理，保留系统会话记录。Hook 可订阅结束事件参与扩展处理，必要清理仍由 Runtime 保证，不能因 Hook 失败被跳过。
已结束 Run 不因迟到结果或后台接管重新启动。停止不承诺撤销已生效的外部操作。模型流长期不结束时，总截止仍有效；终止与清理的具体传播协议列入技术设计。
模型流收齐与对外交付
供应商模型连接仍内部接收流片段，用于组装响应与检测首次有效输出；不逐 token／chunk 发业务总线事件，也不默认向客户端透传。一次模型调用正常结束，校验并保存完整响应后，统一交给调用方；调用开始、完成和失败仍可发送低频生命周期事件。
一次模型响应结束不等于 Agent 执行完成。Loop 根据完整响应选择工具、委派或候选最终答案；工具参数尚未完整时不能执行。完成原因不能单独证明业务结束，本轮不引入强制最终回答工具。Executor 的最终结果交 Planner，用户最终答案在整次 Run 的终态交付。API 可保留 SSE 进度与终态通知。
首输出超时根据连接层内部接收解除，不等到总线返回完整响应；整次 Run 截止仍生效。完整流失败时交付错误，不等待永远不会到来的正常结束。
流式失败与终态
流式输出可能在第一个业务片段前就失败。模型某次输出结束、工具等待、HTTP／SSE 断开都不自动代表整个 Run 结束。
Runtime 负责异常终态交付：没有内容时也返回失败原因；已有片段在对应尝试记录中保留并标记未完成，不作为成功最终答案。若提供部分内容查看，也须明确未完成，不能拼接不同尝试的片段。异常交付不要求失败模型另生成解释。Run 正式结束后，本次事件流结束，后续输入按新提问处理。
连接层按配置处理模型流异常；未启用重试、异常不符合规则或尝试耗尽后，将失败交给 Runtime。入口／Planner 模型失败结束 Run；Executor 模型失败结束该子执行并回交错误，Planner 等全批结果后决策；压缩失败按既有约定中断 Run。停止、总超时和额度耗尽仍走整次 Run 的控制流程。模型连接与客户端连接分别管理，客户端断线不自动启动新的业务模型调用。
用户停止、总超时、Loop 耗尽、模型最终失败、压缩失败及压缩后仍超窗口保留各自原因。错误与流式事件的具体字段由技术协议定义。
标准输出格式修正
用户配置标准输出格式后，Runtime 校验模型准备交付的结果；不符合格式时，把校验错误和输出要求交回当前业务角色，由模型在后续 Loop 修正。
修正不单独设置次数上限，与 Planner、Executor 等业务执行共享同一 Run 的 Loop 总额度和总时限。修正次数不是连接层自动重试次数，每次修正属于业务 Loop。只有符合输出格式的结果才能按成功交付；若还需修正但没有剩余额度，走统一 Loop 耗尽流程。模型调用失败或总超时仍按对应异常终结，不因格式修正追加额度。
七、Skill、Tool、MCP 与 Hook
能力调用与脚本
Skill、Tool、MCP 的使用以 Claude Code 为参考，适配平台的环境与权限。Skill 按需发现和加载：
- 上下文提供当前角色授权 Skill 的名称、简介及入口。
- 模型通过工具读取
SKILL.md和引用材料，结果进入自身上下文。 - 模型按说明调用工具、MCP 或脚本；读取说明不自动执行脚本。
脚本在能访问本次授权文件视图的执行环境中运行；执行层准备 Skill 包、解释器、依赖及挂载。脚本使用普通文件路径，不要求把内部每次 open() 改成平台工具调用。脚本内普通函数与文件操作不会自动产生独立平台 Operation 或 Hook。
普通 Tool、MCP 和脚本通过统一 EventBus 及调用管道执行，HookManager 按时机校验和处理请求／结果，适配层不得对同一次生命周期重复生成不同身份的事件。长任务需要可关联的执行记录，接管时区分接续已有任务与重新执行。
Hook 按触发时机组织
每个 Agent 保存自己的 Hook 配置，围绕生命周期时机组织，不划分“通用”和“角色专用”两套类型。以 Claude Code 为基线，可参考 Codex；具体兼容清单由技术规格定义，不把参考方向等同于已兼容全部协议。
- 模型、工具、Executor、上下文等请求和结果进入同一 EventBus。需要修改或决定执行许可的 Hook 必须在相关阶段等待处理完成，纯通知订阅仍可异步。
- Hook 可以校验，允许或拒绝某些执行，并修改获准输入输出和上下文。 allow 不绕过 Runtime 的权限、参数、预算、停止和截止检查；同一链已生效的 deny 不能被后续 allow 推翻。
- 合法前置 deny 阻止对应能力执行，返回带原因的关联响应；后置 deny 只能阻止交付或后续推进，不能撤销外部副作用。拒绝不能表现为永久等待，也不能被 Runtime 自动重试绕过。
- Hook 自身异常、超时、无效返回或非法修改仍不阻断主体执行。 丢弃当前无效修改，保留此前已生效版本继续；这与合法拒绝是两种不同结果；合法 deny 附带的修改无效时仍然拒绝，不能因为丢弃修改就把拒绝变成允许。必要状态提交失败不适用 Hook 的 fail-open。
- Hook 按固定顺序处理，后一个使用前一个的有效结果。调用关联、事件类型、Run／Session／角色身份和系统控制字段不能被 Hook 改写。
- 模型流仍内部收齐后才进入结果处理链，不逐片段广播。有效结果与上下文提交后才向等待者交付，避免绕过后置 Hook。
- Hook 处理本身不递归触发同一业务拦截链；检查点、权限、预算及必要清理由系统保证，不依赖观察 Hook 补写。
Hook 修改全上下文可见
生效修改必须进入授权作用域内的权威有效上下文，让当前处理器、当前 Loop、后续模型调用、历史投影、压缩和恢复都读取同一生效版本。 不能只改事件临时副本，或只在审计里保存而让后续模型继续看到旧参数、旧结果。
例如 Hook 将工具路径从 draft.sql 改为 reviewed.sql，工具执行与后续模型上下文都应明确实际使用后者；运行记录保留原请求和 Hook 修改来源。模型可见内容不得仍把结果归给原路径。
原始用户输入、模型原响应和工具原结果保留不覆盖；ContextManager 管理带来源的有效修改和版本，模型视图体现真实执行内容，不伪造为用户或模型原始表达。Hook 修改后重新校验输入输出结构、权限和上下文预算。
“全上下文”延续已有隔离约定：角色消息在所属角色内全链路可见，显式共享业务字段在授权共享范围内可见；不自动合并 Planner 与 Executor 私有历史或跨 Session 传播。已发出的模型请求不回溯修改，已发生的工具副作用不能被历史重写。后续读取、压缩与恢复必须接上已提交修改；旧摘要不能覆盖更新。
修改型 Hook 的能力及可见性已确认。各挂点的完整可写字段、变更 Schema、冲突处理和处理器恢复策略继续在能力设计、上下文设计细化，不能再把“是否支持修改／拒绝”整体列为待定。
八、共享文件、沙箱与生命周期
固定文件根和 Session 隔离
Agent 创建时即获得固定文件根与挂载点，组织 Skill、Wiki、业务文件、会话记录及工作文件。一个 Agent 开启沙箱时使用一个逻辑共享沙箱，Planner 与 Executor 共享获准的 Session／Run 工作文件，角色上下文仍独立。
不同 Session 的会话上下文和工作文件由系统隔离。文件服务、基础 list／grep／read／write、脚本环境及具有文件访问能力的 MCP 都必须遵守相同边界，不依赖 LLM 自觉。模型提供的路径不能扩大访问权限。
仅检查平台 read/write 或设置 cwd 不能限制脚本直接文件访问，执行环境也必须落实隔离。Skill 包资源以只读方式提供，当前授权工作目录可写；两者分别管理，脚本按稳定挂载路径访问。
系统会话、调用及恢复记录由系统维护，与模型可读写工作文件分开；同一 Session 的脚本也不能通过工作目录任意改写消息、预算或检查点。具体目录和存储实现由技术设计落实。
文件保留
沙箱开关控制工作文件持久化；关闭持久沙箱仍使用受限执行环境，不等于直接在平台宿主机权限下执行。
| 模式 | 文件位置及生命周期 |
|---|---|
| 开启持久沙箱 | 持久存储承载授权会话工作目录，分析过程与生成文件长期保留，暂不自动过期；删除所属 Agent 时一并清理 |
| 关闭持久沙箱 | Agent 文件根下对应 Session 的临时 Run 工作目录；整个 Run 结束并收束后，删除本次全部工作文件 |
无沙箱模式的删除范围包括临时脚本、中间材料、草稿、最终产物及放在工作目录中的上下文文件；不自动转存最终产物。需要 Run 结束后继续访问文件，应开启持久沙箱。
预配置的 Skill、Wiki、Agent 配置及系统会话／恢复记录不属于临时工作文件。返回路径不会延长文件寿命；永久保存文件不等于进程、内存或安装状态永久存活。
页面关闭、流断开、批次等待或机器故障都不自动触发清理。未结束 Run 的恢复现场及所需文件应跨机器可访问；无沙箱也不能随故障进程退出立即删除工作目录。
记录保留与删除 Agent
Agent 存续期间，会话消息、运行记录、操作记录、检查点及持久沙箱文件暂不设置自动过期，后续再设计过期策略。关闭持久沙箱时，Run 结束后删除工作文件的规则继续生效；系统会话与运行记录按上述规则保留。
用户删除 Agent 时，先停止该 Agent 的相关运行并完成收束，再一并删除其配置、会话记录、运行记录、操作记录、检查点及专属文件，包括持久沙箱文件。删除期间不允许新的 Run 使用该 Agent，已结束或正在删除的运行不得被故障接管或迟到结果重新启动。
清理范围依据资源归属确定：Agent 专属目录与文件一并删除；平台共享的模型连接、Skill、MCP 等资源继续保留，仅解除该 Agent 对它们的引用。具体删除顺序、并发访问防护、失败补偿和完成反馈由技术设计确定。
九、故障恢复边界
故障接管继续原 Run、入口及已创建的 Executor 执行，重建物理执行对象，不把恢复登记成新提问。已用预算、原配置快照和截止时间继续有效；用户已结束的 Run 不恢复。
外层工作流与内层 Agent 分别保存各自执行范围的检查点，统一交给检查点存储接口管理。 不在每个节点、Skill 或用户工作目录散放自行维护的检查点。外层持有内层稳定执行引用；内层保存自身 Loop、上下文和调用现场。恢复范围与执行身份必须稳定；具体结构见检查点协议。通用子图编辑能力仍可后置，但外层调用完整 Agent 的嵌套恢复协议必须具备。
恢复需要图的调度位置、节点阶段、上下文引用、批次成员、已完成结果与待处理调用。完整检查点与每项完成结果分别记录，已完成分支不等整批结束才保存。恢复先复用已保存结果，避免重复消费、重复扣额度或重复创建子任务。
节点完成结果、状态推进及后继待执行意图必须一致提交。刚好在节点完成时宕机，接管者应能发现下一项待执行工作；内层已完成但外层尚未消费时，读取原内层结果。通知丢失不能使已提交任务永久失去调度。
节点提供可恢复状态，公共 Loop、图引擎与调用中间件统一管理保存时机，不还原任意 Python 栈、协程或网络连接。保存 Hook 配置版本、处理顺序、决定、有效参数与上下文版本；原始能力结果已保存而后置 Hook 未完成时，只继续后处理，不能重执行工具。这里“检查点不依赖 Hook”指系统必需持久化不能靠用户 Hook 负责，不是忽略 Hook 决定和修改。仅靠调用代理也不能自动恢复未知业务代码的执行位置。
外部操作结果未记录时保留未知事实，按已配置的异常分类策略处理；缺记录本身不等于已识别临时网络故障。检查点不保证外部副作用恰好一次。统一存储、执行权与恢复流程见检查点与消息交付；具体存储介质、索引与增量提交是检查点协议和存储设计中的工程选择。
十、本轮架构设计补充
必须覆盖的需求
- Agent 通过配置和发布获得可执行行为；行为配置与执行结构分开表达，绑定、版本和权限在发布时校验。
- 内层 ReAct／Plan–Executor 和未来工作流使用同一种图运行协议。工作流必须能够编排完整 Agent 与 Tool／MCP、条件、循环和并行汇合；其外层代码可以后续实现，设计不能缺位。
- 节点实现类、图内位置、逻辑任务和一次激活分别定义。同一份 Executor 配置可创建多个独立任务；等待、内部 Loop 和故障恢复不改变原任务身份。
- 普通工具／Skill 阅读／脚本无需新图；完整 Agent 作为外层节点调用时拥有独立内层执行范围及上下文。图里未执行的分支不得造成永久等待。
- 外层与内层集中保存检查点但按范围隔离；外层能准确区分子执行尚未开始、执行中、已完成未消费，以及后继尚未投递。
- 公共运行基础设施承担调用、保存和恢复，业务节点不遍布事件发送和存储代码；内存 Future／Python 栈不是恢复依据。
- Hook 可校验、允许、拒绝和修改。生效修改进入有效上下文，后续执行、历史、压缩和恢复一致可见；原始记录保留，角色隔离不变。
- 模型连接内部流式接收，正常收齐后才统一发送完整结果；一次模型完成、一个 Executor 完成与 Run 最终结果是不同边界。
上述内容补充到设计范围，不表示工作流界面、引擎和新接口已经实现。
本版推荐的对象结构
本节及其链接中的实体名、字段、数据库、批次协调器和算法属于工程方案。前三节约定的 Node／ReactNode 行为复用关系继续保留；没有要求所有实现细节都成为产品配置或固定需求。
| 设计选择 | 本版方案 | 详细依据 |
|---|---|---|
| 应用／行为／结构 | Agent 持有行为定义版本；GraphDefinition 为独立结构资产；AgentRelease 固定二者和 NodeBinding | 领域关系 |
| 节点与角色 | Node → ReactNode → PlannerNode／ExecutorNode；角色配置是 Definition 内部组成 | Node 结构 |
| 实例 | Run → GraphExecution → NodeTask → NodeActivation；完整 Agent 调用另以 AgentInvocation 关联 | 实例 UML |
| Plan 委派 | 两次同 Executor 委派是同一内层图的两个任务，分别保存私有上下文；原 Planner 被唤醒继续 | 图运行协议 |
| 外层组合 | WorkflowDefinition／WorkflowRelease 与 AgentNode；完整 Agent 调用创建内层图，采用统一调用与恢复边界 | 外层图设计 |
| 调度与状态 | 已选择双引擎；内层轻量角色／批次调度，外层迁移适配 LangGraph 的工作流内核，检查点通过适配器统一管理 | 双引擎边界 |
| 检查点 | GraphCheckpoint／NodeCheckpoint＋TaskResult／TaskWrite／ScopeCommit；集中存储且按图隔离 | 恢复结构 |
| 接口 | 应用 API、内部端口、插件受限接口分开；统一 EventBus 调用，CommitCoordinator 统一提交 | 领域接口 |
这些具体类型和工程选择是本轮架构建议，接受整体设计评审；不将它们冒称为此前用户逐字段确认。旧 SD-2 的冲突模型已在对应文档替换，后续工程优化不应改掉前九节产品约定。
详细实施规格
本轮进一步给出实施入口，包含配置/API、持久化/事务、图与Loop、EventBus/Hook、上下文/能力/环境五篇。工程默认值、内部字段和算法是实施设计，不改变前九节产品规则；它们还需通过代码及故障测试验证，未实现的能力不能因此标为已上线。
阅读顺序
系统总览 → 领域与实例 UML → 图与 Node → 数据结构 → 检查点协议 → 领域接口。
上下文、能力与 Hook、存储和验收仍各有专题，入口见总览。设计取舍与有限的后续工程事项见设计决策记录，不再把已完成的 Definition、Node、实例关系整体写作“待设计”。
本轮直接核对本地 LangGraph 源码，固定版本及对应符号在图和检查点文档中列明。外层已从仅借鉴设计调整为计划复制并适配相关源码，尚未执行迁移。具体导入边界和依赖处理仍需工程设计；不宣称自动获得外部工具副作用恰好一次保证，也不宣称兼容其全部 API。