Stagewise AgentSystemState 权威注解:Agent 状态模型、持久化映射与父子 Agent 不变量
Stagewise AgentSystemState 权威注解:Agent 状态模型、持久化映射与父子 Agent 不变量
导读
本篇文章围绕 @stagewise/agent-core 包中的 AgentSystemState 状态模型展开,系统讲解它是如何与宿主应用(apps/browser)的 Karton AppState.agents / AppState.toolbox 切片逐字段对齐(parity)、每个字段是「持久化」还是「临时态」、以及父子 Agent(child-agent)树在重启、删除、归档场景下必须遵守的四条不变量。读完本文,你将能够:对照 state-annotation.md 定位任意字段的存储位置与恢复行为;理解 agent-core 包与宿主之间三类被刻意保留的结构差异(D14 / D22)及其桥接方式;并在编写新的切片迁移或状态恢复逻辑时,不破坏已有的持久化与父子树语义。
AgentSystemState 是 AgentStore 拥有的内存态规范(canonical in-memory state),其类型定义与字段级注解位于 state.ts,而 state-annotation.md 则是该状态的权威参考文档,记录了 Karton 对齐表、持久化映射和 D13 子 Agent 不变量。本文以这份注解文档为主体,结合仓库源码进行展开。
1. 文档的定位:一份「状态契约」而非实现说明
state-annotation.md 的定位很明确:它关闭了项目 SPEC(packages/agent-core/SPEC.md)中 Phase 0 / S4 pre-spike 遗留的悬而未决问题。它承担三项职责:
- 对齐:说明
AgentSystemState如何映射到 KartonAppState.agents与AppState.toolbox切片,且每个差异(delta)都被命名并有决策依据; - 分类:将每个字段划分为「持久化」或「临时」两类,使切片迁移与「重启后恢复」(resume-after-restart)代码有唯一事实来源;
- 锁定不变量:固化子 Agent 不变量(D13),防止未来的切片迁移静默破坏父子树。
同时,这份文档有一个配套的编译期断言文件:apps/browser/src/shared/karton-contracts/ui/agent-core-parity.ts。该文件是纯类型文件,不产生任何运行时输出,它通过严格的类型相等断言(AssertEqual<A, B>)保证 @stagewise/agent-core 的 AgentSystemState 与 Karton 的 AppState 两个切片在结构上始终一致——任何一侧的「路过式修改」都会直接触发类型检查错误,而不是产生静默的桥接 bug。这正是「注解文档 + 编译期断言」双保险的设计。
2. 与 Karton AppState 的逐字段对齐(Parity)
对齐的依据有两处:
- Karton 侧:
apps/browser/src/shared/karton-contracts/ui/index.ts中AppState的agents与toolbox切片(对应文档标注的 477–517 行,实际定义见 index.ts); - 包侧:同目录的 state.ts。
文档对「对齐状态」给出了精确定义:match 表示展开别名后字节级一致的结构类型;delta 表示一个已命名、有决策依据的差异;missing 表示尚未闭合的缺口。
2.1 AppState.agents.instances[id] ↔ AgentInstanceState
| Karton 字段 | agent-core 字段 | 状态 | 说明 |
|---|---|---|---|
type |
type |
match | 两侧都是 AgentTypes;core 的枚举通过 agent-core 类型模块再导出到 Karton。 |
canSelectModel |
canSelectModel |
match | 两侧均为 boolean。 |
requiredModelCapabilities |
requiredModelCapabilities |
delta | Karton 使用 ModelSettings['capabilities'];agent-core 使用不透明的 Record<string, boolean | undefined>,依据 D14。运行时结构一致,见 §3.1。 |
allowUserInput |
allowUserInput |
match | — |
parentAgentInstanceId |
parentAgentInstanceId |
match | 两侧均为 string | null。该反向指针(back-pointer)是树重建的唯一依据(D13,见 §4)。 |
state |
state |
match | AgentState 结构对齐;toolApprovalMode 在 core 形态上是 store-canonical(见 §3.2)。Karton 侧仍将字面量 ToolApprovalMode 联合类型收窄用于 UI。 |
对照 index.ts 可见,Karton 的 agents.instances 同样包含 sideChatParentId: string | null 字段——这也是两个切片保持同步的字段之一(side chat 父指针,用于「以侧边聊天形式呈现主聊天」的场景,见 state.ts 的注解)。
2.2 AppState.toolbox[id] ↔ ToolboxAgentState
| Karton 字段 | agent-core 字段 | 状态 | 说明 |
|---|---|---|---|
workspace.mounts |
workspace.mounts |
match | 两侧都是来自 @stagewise/agent-core/types/metadata 的 MountEntry[]。 |
| — | pendingFileDiffs |
delta | 内部 diff 历史,用于 checkpoint/undo 与已编辑文件上下文;不再镜像到 UI Karton。 |
| — | editSummary |
delta | 内部 diff 历史(已定稿但仍相关的 diff),同上。 |
pendingUserQuestion |
pendingUserQuestion |
delta | Karton 用 QuestionField / QuestionAnswerValue(宿主拥有的工具 schema)特化泛型;agent-core 保持泛型,见 §3.4。 |
pendingSandboxOutputs |
pendingSandboxOutputs |
match | Record<string, string[]> | undefined。 |
pendingSandboxAttachments |
pendingSandboxAttachments |
match | Record<string, AttachmentMetadata[]> | undefined。 |
pendingShellOutputs |
pendingShellOutputs |
match | Record<string, string[]> | undefined。 |
pendingShellSessionIds |
pendingShellSessionIds |
match | Record<string, string> | undefined。 |
shells |
shells |
delta | Karton 使用 ShellSessionSnapshot[];agent-core 使用 ShellSessionSummary[](依据 D14,为避免宿主导入而保持独立)。结构一致,见 §3.3。 |
activeApp |
activeApp |
match | 两侧对象形状相同。 |
pendingAppMessage |
pendingAppMessage |
match | 两侧对象形状相同。 |
两个 core-only 的 diff 历史字段被有意从 UI 契约中移除(因为 pending-edit review 已下线),除此之外没有意外的多余或缺失字段。这点在 agent-core-parity.ts 中体现为 Omit<CoreToolboxAgentState<...>, 'pendingFileDiffs' | 'editSummary'> 桥接。
3. 持久化映射:每个字段「存哪、从哪恢复、是否重置」
这是文档的核心实战价值所在:一张覆盖 AgentSystemState 全部字段的持久化映射表,标注每个字段的持久化类别、resumeAgent 重新水合(re-hydrate)时的来源,以及恢复时是否被重置。
持久化行的事实来源是 agentInstances / agentMessages 表(schema 见 schema.sql)以及 storeAgentInstance / getStoredAgentInstanceById 路径(见 db.ts);恢复逻辑的事实来源是 AgentManager.resumeAgent(见 agent-manager.ts)。
持久化类别共分四类:
persisted-core:存储在 agent 行上,重启后存活;persisted-side:存储在独立 side-table(diff-history DB、附件 blob 等)中,重启后存活,但恢复时由专门服务重新派生,而非从核心 agent 行读取;ephemeral:仅存内存,进程重启或resumeAgent重新水合时被重置;derived:从其他持久化状态计算(典型如通过type查AgentsMap[type].config),不直接存储。
3.1 AgentInstanceState(每 Agent 的顶层信封)
| 字段 | 类别 | 恢复来源 | 恢复时是否重置 |
|---|---|---|---|
type |
persisted-core | agentInstances.type |
否 |
canSelectModel |
derived | 创建时取自 AgentsMap[type].config.allowModelSelection |
重新计算 |
requiredModelCapabilities |
derived | AgentsMap[type].config.requiredCapabilities |
重新计算 |
allowUserInput |
derived | AgentsMap[type].config.allowUserInput |
重新计算 |
parentAgentInstanceId |
persisted-core | agentInstances.parent_agent_instance_id,是树重建的唯一依据(§4) |
否 |
state.* |
mixed | 见下一子表 | 逐字段 |
3.2 AgentState(每 Agent 的推理状态)
| 字段 | 类别 | 恢复来源 | 恢复时是否重置 |
|---|---|---|---|
title |
persisted-core | agentInstances.title |
否 |
titleLockedByUser |
persisted-core | agentInstances.title_locked_by_user;为 null 时回退为 undefined |
否 |
isWorking |
ephemeral | 不存储;resumeAgent 显式传 isWorking: false 给 createAgent |
是 — 恒为 false |
history |
persisted-core | agentMessages 侧表(按 agentInstanceId, seq 键控)。遗留的 agentInstances.history JSON 列仅保留用于回滚 |
否 |
queuedMessages |
persisted-core | agentInstances.queued_messages(JSON) |
否 |
activeModelId |
persisted-core | agentInstances.active_model_id,经模型提供方注册表校验;模型已不存在时回退为 undefined(→ 默认) |
否(除非失效) |
toolApprovalMode |
persisted-core | agentInstances.tool_approval_mode;为 null 时 fail-closed 回退到宿主默认 |
否 |
pendingApprovals |
ephemeral | 不存储;createAgent 初始化为 {},resumeAgent 不覆盖 |
是 — 恒为 {} |
inputState |
persisted-core | agentInstances.input_state(JSON 编码字符串) |
否 |
usedTokens |
persisted-core | agentInstances.used_tokens |
否 |
contextWindowSize |
ephemeral | 不存储;会话激活期间由活动 runtime 上报 | 是 — 恒为 undefined |
error |
ephemeral | 不存储;由 runloop 在失败时设置 | 是 — 被清除 |
unread |
persisted-core | agentInstances.unread |
恢复原值 |
usageWarning |
ephemeral | 不存储;由模型提供方在接近软限额时填充 | 是 — 被清除 |
自 Phase 6(见 §3.2 决策)起,toolApprovalMode 在 AgentState 中是 store-canonical 且类型为 string;宿主通过其 AgentState overlay 将字符串联合类型收窄。对应 schema 中的 tool_approval_mode TEXT NOT NULL DEFAULT 'alwaysAsk' 列(schema.sql),以及 tool-approval.ts 中定义的 'alwaysAsk' | 'alwaysAllow' | 'smart' 三值枚举与 DEFAULT_TOOL_APPROVAL_MODE = 'alwaysAsk' 默认值。
3.3 ToolboxAgentState(每 Agent 的工具箱状态)
工具箱字段没有一个落在 agent 行上。能够挺过重启的字段,是因为某个专门服务在加载时从自己的存储中重新派生它们。
| 字段 | 类别 | 恢复来源 | 恢复时是否重置 |
|---|---|---|---|
workspace.mounts |
persisted-core | 通过 MountManager.mountWorkspace(instanceId, path, permissions)(core 的 @stagewise/agent-core/mount-manager,实现见 mount-registry.ts)依据 agentInstances.mounted_workspaces 重新挂载;宿主 shell(MountManagerService)包装它做文件选择器与 ClientRuntimeNode/LSP 编排;工具箱切片通过同址的 setAgentMounts writer 副作用填充 |
否(重新创建) |
pendingFileDiffs |
persisted-side | core-only。由 DiffHistoryService 从 <userData>/stagewise/diff-history/data.sqlite(snapshots + operations 表,外加磁盘 blob 目录)重建 |
否(重新创建) |
editSummary |
persisted-side | core-only。与 pendingFileDiffs 同一 DB;表示已定稿但仍相关的 diff |
否(重新创建) |
pendingUserQuestion |
ephemeral | 不存储;进行中的 askUserQuestions 状态 |
是 — 被清除 |
pendingSandboxOutputs |
ephemeral | 不存储 | 是 — 被清除 |
pendingSandboxAttachments |
ephemeral | 不存储。注意:底层附件 blob(<userData>/stagewise/agents/<id>/data-attachments/<blobKey>)确实持久化——只有进行中的「pending」索引是临时的 |
是 — 被清除 |
pendingShellOutputs |
ephemeral | 不存储 | 是 — 被清除 |
pendingShellSessionIds |
ephemeral | 不存储;shell 会话不跨重启存活 | 是 — 被清除 |
shells.sessions |
ephemeral | 从宿主 shell 服务的进程内会话注册表重建 | 是 — 重建为空 |
activeApp |
ephemeral | 不存储;mini-app 仅存活于进程内 | 是 — 被清除 |
pendingAppMessage |
ephemeral | 不存储;一次性消息总线条目 | 是 — 被清除 |
diff-history 的持久化细节可在 diff-history/schema.sql 中看到:snapshots 表(含 delta_target_oid 索引)、operations 表(顺序记录 baseline/edit 等文件操作,snapshot_oid 外键级联删除),以及磁盘 blob 目录共同承载 pendingFileDiffs / editSummary。
3.4 侧表存储总览
| 侧表 / 位置 | 所有者 | 支撑字段 |
|---|---|---|
agentInstances(核心行) |
AgentPersistenceDB |
大部分 AgentState + agent 元数据 |
agentMessages(按 agentInstanceId, seq 键控的侧表) |
AgentPersistenceDB |
history(每消息一行,规范化存储) |
<userData>/stagewise/diff-history/data.sqlite |
DiffHistoryService |
pendingFileDiffs、editSummary |
<userData>/stagewise/agents/<id>/data-attachments/<blobKey> |
attachments blob store | 消息/元数据中引用的附件字节负载 |
依据 D15(SPEC.md 的向后兼容硬性要求),Phase 1 期间任何持久化路径或 schema 都不得改变,新数据只能通过增量迁移(additive migrations)进入。
4. 被刻意保留的结构差异(Intentional Deltas)
以下结构差异是锁定的决策,不是漂移。每个差异都在 Karton 边界被桥接,使得 agent-core-parity.ts 中的编译期断言依然通过。桥接的基本原则在断言文件中写得很清楚:每个桥接只重新类型化 core 形态以匹配 Karton 形态,恰好对应一个文档化决策,桥接是可叠加的(additive),组合后得到「Karton 投影的 core 状态」,再与真实 Karton 状态做严格相等比较。
4.1 requiredModelCapabilities(D14)
- Karton:
ModelSettings<a href="https://link.gitcode.com/i/b885917a48e0d116e92847664f3e446b" target="_blank">'capabilities'],定义于 [shared-types.ts; - agent-core:
RequiredModelCapabilities = Record<string, boolean | undefined>,见 state.ts; - 为什么:模型提供方配置类型(
ModelSettings、ProviderConfig、CustomModel等)是宿主特有的(SPEC.md 353–357 行的 D14),留在apps/browser;agent 只需要不透明的能力标志来做模型选择门控; - 桥接:结构上完全一致。宿主写入时把 agent-core 的 record 当作
ModelSettings['capabilities']处理;agent 从不内省具体标志名。
从源码看,ModelSettings<a href="https://link.gitcode.com/i/e274867edbc47b145fcd6b3b6221f3c7" target="_blank">'capabilities'] 在 [models.ts 中实际包含 inputModalities / outputModalities 等结构化子对象,而 RequiredModelCapabilities 只是 Record<string, boolean | undefined>——两者的运行时 JSON 形状在值层面保持一致,这正是「不透明能力标志」的设计意图。
4.2 toolApprovalMode 收窄(D22,Phase 6 取代)
- Karton:
AgentState通过宿主AgentStateshim 将toolApprovalMode收窄为ToolApprovalMode(见 agent/index.ts); - agent-core:
AgentState.toolApprovalMode: string(Phase 6 起 store-canonical); - 为什么:Phase 6 让
agents.instances成为 store-canonical。BaseAgent.set使用的通用 recipe 通道会写入整个AgentState,因此toolApprovalMode必须存在于 core 形态上,否则 recipe 将被迫横跨两个 store。字段仍由宿主收窄(字符串联合 vs 裸字符串),采用与activeModelId相同的Omit+ 重新添加模式; - 桥接:Karton 侧的
AgentState使用Omit<CoreAgentState<AgentMessage>, 'activeModelId' | 'toolApprovalMode'> & { activeModelId: ModelId; toolApprovalMode: ToolApprovalMode };桥接的前向镜像将收窄后的值原样复制。
在 agent-core-parity.ts 中还有一条配套的键集合断言:宿主的 AgentState 与 core 的 AgentState<AgentMessage> 必须拥有完全相同的键——既不能增也不能删。若该断言被破坏,说明宿主 shim 或 core 的 AgentState 发生了漂移,审查者需要同步检查 state-annotation.md 的持久化映射是否仍然准确。
4.3 ShellSessionSummary vs ShellSessionSnapshot(D14)
- Karton:
ShellSessionSnapshot,定义于 agent/metadata.ts; - agent-core:
ShellSessionSummary,内联定义于本包(state.ts); - 为什么:
ShellSessionSnapshot是宿主拥有的环境快照类型(D14 规定环境快照类型留在宿主侧)。agent-core 的类型在结构上保持一致但留在包内,避免@stagewise/agent-core产生指向apps/browser的导入边; - 桥接:Karton 桥接原样复制字段;两个类型运行时字节级一致。断言文件中的
_ShellSessionParity直接断言AssertEqual<CoreShellSessionSummary, ShellSessionSnapshot>(agent-core-parity.ts)。
ShellSessionSummary 的字段包括 id、exited、exitCode、lineCount、logPath、tailContent、lastLine、cwd、createdAt,以及可选的 watcher(含 title/command/startedAt/expiresAt)与 watcherResult(outcome: 'triggered' | 'timed_out' | 'failed' + finishedAt)。
4.4 PendingUserQuestion 泛型特化(D14)
- Karton:
PendingUserQuestion以QuestionField与QuestionAnswerValue特化(定义于 agent/tools/types.ts); - agent-core:
PendingUserQuestion<TField, TAnswer>泛型,默认unknown(state.ts); - 为什么:问题字段与答案值的形态由宿主拥有的工具 schema 定义;agent-core 只建模容器,让宿主去做特化;
- 桥接:Karton 侧的
AppState.toolbox<a href="https://link.gitcode.com/i/dd86f5c6fd0d1de81080b9d201d9f066" target="_blank">id].pendingUserQuestion引用宿主特化类型;桥接原样复制值。断言文件通过重新声明 Karton 侧的泛型实例化形态并断言与CorePendingUserQuestion<QuestionField, QuestionAnswerValue>相等来锁定([agent-core-parity.ts)。
5. 子 Agent 不变量(D13)
依据 D13(SPEC.md 327–332 行),父子 Agent 是一等公民状态(first-class state),包拥有的 schema 从第一天就表示它们。
5.1 树的重建
- 仅反向指针:
AgentInstanceState.parentAgentInstanceId是树唯一的存储表示。任何地方都没有显式的子列表(状态上没有childInstanceIds字段,也没有 join 表)。 - 按需遍历:需要某父节点子节点的操作,通过过滤
state.agents.instances中parentAgentInstanceId === parent的条目实现:- 删除级联:
AgentManager.deleteAgent(见 agent-manager.ts),先递归删除子 Agent,再归档、清持久化、最后移除磁盘 blob 目录; - 归档级联:
AgentManager.archiveAgent(同文件 L1559 起),对内存态做同样的深度优先遍历但不删除持久化行; - 持久化删除级联:
AgentPersistenceDB.deleteAgentInstance(db.ts),先删子、再删父(在同一事务中先删agentMessages再删agentInstances)。
- 删除级联:
- 无工具箱继承:
ToolboxAgentState是 per-instance 的。子 Agent 拥有自己独立的工具箱切片——自己的挂载、diff 与 pending 状态,不从父节点继承。
注意:getChildAgentInstanceIds 的查询条件同时匹配 parentAgentInstanceId 与 sideChatParentId(db.ts),即 side chat 也纳入级联删除范围。
5.2 四条不变量
- 更新时父节点必须存在:若某实例的
parentAgentInstanceId非 null,则同一 tick 内state.agents.instances中必须存在该键的条目。目前由宿主强制(AgentManagerService.createAgent在子 Agent 调用spawnChildAgent之前先写入父行);包内的AgentStore尚未强制——后续将agents切片移入AgentStore-canonical 的切片迁移必须添加事务性更新守卫。 - 恢复仅限根节点(resume is root-only):
resumeAgent(agent-manager.ts)在目标有非 nullparentAgentInstanceId时抛出异常。子 Agent 只能通过活跃父节点的spawnChildAgent临时创建,且永远不会单独跨进程重启存活。它们之所以仍被存储在磁盘上,是因为删除级联需要这个指针,但它们不可独立恢复。这在 create-handler.test.ts 中有对应测试:对带父指针的实例调用resumeAgent会被断言为抛错。 - 删除深度优先级联:
deleteAgent先递归进入子节点,再从内存态与持久化层删除父节点,最后才移除 per-agent blob 目录;archiveAgent对内存侧执行相同的深度优先遍历但不删除持久化行。 createAgent时按实例创建工具箱:子 Agent 的工具箱切片由与根 Agent 相同的服务(mount-manager、diff-history 等)填充,不从父节点复制任何工具箱状态。
5.3 留给后续切片迁移的未决项
这些在 S4 spike 中明确未修复,在此记录以防未来的迁移静默回归:
- 父存在性守卫:当
agents切片移入AgentStore时,parentAgentInstanceId的更新路径必须拒绝指向缺失父节点的非 null 值。当前无类型检查、无测试。 - 孤儿处理:若父行被损坏或手动删除而子节点仍存在:持久化层在显式删除时能正确级联,但不一致的 DB 会留下可读的孤儿子行,且没有防御性清理。
- 跨树的 revert-to-user-message:当前不是现有操作;标记它是为了未来的 revert 语义需要决定父节点 revert 是否触及子子树。
6. 从源码验证:AgentStore 与恢复链路如何兑现这份契约
6.1 AgentStore:规范内存态的所有者
AgentSystemState 由 AgentStore 类持有(agent-store.ts)。它基于 Immer 的 produceWithPatches 实现:
update(recipe)表达所有变更,嵌套更新会被拒绝(nested AgentStore.update is not allowed);- 普通订阅者(
subscribe)同步按注册顺序执行,并接收state、previous与 Immerpatches——patches 让下游投影(特别是 Karton 桥接)可以按路径转发增量变更,从而恢复重构前的分块流式负载大小; - 副作用订阅者(
registerSideEffect)同步派发但可返回 promise,通过SideEffectHandle.readiness()让命令等待其完成(对应 D19 的订阅排序契约); whenSettled()聚合等待最近一次更新触发的全部在途副作用 promise。
createInitialAgentSystemState()(initial-state.ts)是无参纯工厂,返回空的 { agents: { instances: {} }, toolbox: {} },用于宿主启动时播种全新的 AgentStore——不接收任何参数以保证包级纯净(无 Karton、宿主或环境形态泄漏)。
6.2 resumeAgent 的重新水合路径
resumeAgent(agent-manager.ts)的执行顺序恰好印证了 §3 的持久化映射:
- 已激活则直接返回(
activeAgents缓存命中); - 通过
getStoredAgentInstanceById读取行,找不到或已归档则抛错; - 有
parentAgentInstanceId则抛错(不变量 2); - 校验持久化的
activeModelId在模型注册表中仍然存在(可能曾被删除的自定义模型); - 调用
createAgent,把title、titleLockedByUser、history、queuedMessages、activeModelId、activeProviderInstanceId、toolApprovalMode(null 时回退DEFAULT_TOOL_APPROVAL_MODE)、inputState、usedTokens、isWorking: false(显式重置)、unread传入; - 遍历
mountedWorkspaces调用handleMountWorkspace重新挂载。
对照 §3.2 表:isWorking 恒为 false、pendingApprovals 保持 {}(createAgent 初始化且不覆盖)、contextWindowSize / error / usageWarning 被清空——所有 ephemeral 字段的重置行为都在这一条链路中兑现。
6.3 测试与静态断言的守护
- 编译期:
agent-core-parity.ts的_AgentsSliceParity/_ToolboxSliceParity断言保证包 ↔ Karton 两个切片严格相等; - 单元测试:
AgentManager的 create-handler 与 startup-policy 测试(agent-manager.create-handler.test.ts、agent-manager.startup-policy.test.ts)覆盖「子 Agent 不可恢复」与「启动时对指定 id 调用resumeAgent」等路径; - 挂载语义:
mount-registry.test.ts(mount-registry.test.ts)验证mountWorkspace写新数组、按(agent, path)幂等等行为,支撑工具箱workspace.mounts的恢复语义。
7. 给迁移者的实践清单
基于文档与源码,任何涉及 AgentSystemState 的改动都应遵循以下清单:
- 改结构前先看断言:任何对
AgentSystemState或 KartonAppState的形态修改都会让agent-core-parity.ts的类型检查失败——这是预期行为,请同步更新桥接类型而不是绕过断言。 - 持久化改动遵守 D15:Phase 1 内不改路径与 schema,新数据走增量迁移;历史 SQL 迁移中内联的
'alwaysAsk'字符串默认值不要改写成常量引用(为了重放稳定性)。 - 新增字段先分类:在
state.ts/types/agent.ts上标注@persistence注解,并在state-annotation.md中补充对应行(persistence class、resume 来源、reset 行为)。 - 父子树三处级联要同步:内存删除(
deleteAgent)、内存归档(archiveAgent)、持久化删除(deleteAgentInstance)三处都要深度优先处理子节点。 - 恢复只对根节点:不要为带
parentAgentInstanceId的实例提供 resume 路径。 - 警惕未决项:父存在性守卫、孤儿行清理、跨树 revert 语义目前都未实现,新的切片迁移不应假设它们存在。
参考资料(仓库相对路径)
- 本文主体:
packages/agent-core/src/store/state-annotation.md - 类型定义:
packages/agent-core/src/store/state.ts、packages/agent-core/src/types/agent.ts - Store 实现:
packages/agent-core/src/store/agent-store.ts、packages/agent-core/src/store/initial-state.ts - 编译期断言:
apps/browser/src/shared/karton-contracts/ui/agent-core-parity.ts - Karton 契约:
apps/browser/src/shared/karton-contracts/ui/index.ts - 恢复 / 级联实现:
packages/agent-core/src/services/agent-manager/agent-manager.ts、packages/agent-core/src/services/agent-persistence/db.ts - Schema:
packages/agent-core/src/services/agent-persistence/schema.sql、packages/agent-core/src/services/diff-history/schema.sql - 决策依据:
packages/agent-core/SPEC.md(D13/D14/D15/D18/D19/D22)