State schema 历史

状态 schema 历史¶

Doctor 会在后续工作区和代理检查运行之前，补全早于审计账本的已识别 schema-1 数据库。在 schema 2 或更高版本中，缺少所有权元数据或缺少审计账本仍会阻止修复。

状态模式 19¶

模式 19 为现有 user_profile_identities 行添加可空 authorization_id TEXT 和 authorization_basis_json TEXT。 用户资料所有者复用未中断通道链接的不透明 UUID，并仅记录其原始访问策略授权引用（或 JSON null）。它不会 将通道身份复制到另一个存储中。引用是版本化 JSON { "version": 1, "id": "<uuid>" }，不是凭证：恢复通过用户资料读取工作进程解析它，并重新检查当前角色或身份范围以及原始插件授权。 未知版本、格式错误的引用、缺失的行或损坏的授权事实不会 授权工作。此模式提供所有者契约；消费者必须 保留并重新验证其自身的效果权限。

用户资料权限变更会在与角色、别名或所有权变更相同的交易中清除这些字段。取消链接会删除该行。恢复角色或 链接无法恢复已退役的引用。现有配置机器状态存储 在 operator.channelPolicy 下记录已激活的 gateway.roles 和 gateway.auth.identityScopes 策略 快照。仅身份范围的所有者使用相同 引用契约；移除并恢复其配置的范围无法使 已退役的引用复活。在机密激活锁下，任一策略的变更 会在发布精确的后继快照之前持久化退役现有引用。回滚使用相同操作并采用 合并目标；发布失败会协调存活的活跃策略。 不涉及代理模式变更。

启动和 Doctor 添加可空列，但不会为遗留 行分配权限；未使用的用户资料表在首次使用前保持不存在。规范模式 和用户资料所有者的延迟确保共享表和索引定义。 两个已发布模式标记通常推进到 19。在现有 旧版本更新器发布延迟 期间， 内容可以升级，同时保留较旧的已发布标记。在版本 19 发布之前，引用不能 签发或恢复。

版本 18 写入器无法保留撤销历史，因此即使新增列可空，这也是一个版本化 权限契约。它们的常规 工作进程准入检查在状态协调器下检查外部版本变更，并 拒绝进一步写入，包括比其支持更新的延迟内容。旧读取器也拒绝模式 19。 升级前创建经过验证的、感知 WAL 的备份。降级需要在单独的状态目录中恢复 匹配的升级前备份；切勿降低 标记或移除权限列。恢复备份会丢失后续撤销 和回执，并且不会撤销外部效果；在回滚前使用兼容 构建协调这些内容。

状态模式 18¶

模式 18 为 github_publication_session_lifecycles 和 github_repository_publication_requests 添加可空 requester_authority_json TEXT 列。 共享发布准入在现有请求事务中记录其原始请求者、范围上限，以及 任何所需插件授权身份和原始别名绑定 ID。该 快照在延迟和重启后仍然存在；它不会取代当前角色、授权、 会话或执行权限检查。发布者选择、仓库路由、 人工归属和回执保留保持不变。

启动和 openclaw doctor --fix 将列添加到现有表中，而不会 重建或重写其行。历史值保持为 NULL：迁移 不会从发布者、会话创建者或当前 负责人推断请求者。未证明的待处理请求不能开始新效果。终端回执 保持可读，并且观察已分派的 GitHub 结果不会 授权另一操作。未使用的发布表在正常首次写入之前保持不存在，该写入会创建规范模式。

配置文件模式所有者在现有 user_profile_emails 表中添加可空的 binding_id TEXT，并在其自身事务中初始化缺失的 ID。 每个邮箱到配置文件的绑定都有一个不透明 UUID。创建或实际所有权变更会启动新绑定；同一所有者的刷新会保留它。删除别名并稍后恢复时，无法恢复其原有 ID。发布快照仅保留这些原始 ID，不会复制邮箱地址或更新已接受的回执字节。初始化现有别名不会将缺失的权限回填到历史发布请求中。

发布列添加和版本事实在一个模式事务中提交；失败时一起回滚。两个已发布标记通常推进到 18。 现有的旧更新器发布延迟 可以保留较早的已发布标记，同时记录已应用内容版本 18。 重新打开时使用该内容版本，并且不会重复迁移。

旧读取器会精确验证这些可选表，因此单纯的可空列不会使这成为同版本新增。支持状态模式 17 或更早版本的构建会拒绝模式 18。升级前停止旧写入器，并创建经过验证的、支持 WAL 的备份。回滚需要在单独的状态目录中使用匹配的构建和升级前备份，而不是降低版本标记或删除权限字段。保留较新的数据库，并在回滚前使用兼容构建协调已接受的 GitHub 效果：恢复备份会丢失后续本地回执，并且不会撤销已推送的提交或拉取请求。

状态模式 17¶

模式 17 添加了完整的 prepared-worker 存储契约。worker_environments 中可空的 preparation_key、preparation_demand_at_ms、 preparation_expires_at_ms 和 preparation_consumed_at_ms 列构成一个受约束的 元组，用于一次性容量。单独的可空 last_activated_at_ms 列 存储成功激活时间。就绪池准入写入准备 元组；消耗该容量并分配会话放置共享一个 事务。成功的放置激活在同一事务中记录其需求时间。消耗在附加失败、放置退役 和重新打开后仍然存在，而终态行保留未过期需求和不确定清理。 迁移将现有 worker 的所有五个值保留为 NULL，并且不会从历史行推断 需求、激活或未使用容量。

专用节点在首次使用的 node_worker_prepared_workspaces 表中注册固定构建路径。它记录精确的环境和 已完成的 preparation_key、用于标识兼容 项目/运行时内容的必需 cache_key，以及固定的 workspace 和 HOME 路径。单独的必需 source_manifest_ref 和 prepared_manifest_ref 摘要标识干净的 Git 基线和已完成的设置树。初始绑定验证已完成的树； 重放保留已绑定会话的编辑。绑定一次记录会话和 所有者纪元。退役会保留该绑定直到机器拆除，因此 退役路径不能被另一个会话认领。

注册在其现有同步写 事务中创建仅节点表。中止的注册会回滚该 DDL，稍后的尝试 可以再次创建它。普通数据库打开和迁移会使该表 保持不存在。每个 agent 的模式和原生伴随表不变；原生 客户端可以在状态模式 17 下继续验证和读取其现有拥有的表， 而无需执行迁移。

启动和 openclaw doctor --fix 在打开模式-15 数据库时，会在 prepared-worker 迁移之前应用模式-16 Skill Workshop 迁移。 模式-16 数据库仅接收 prepared-worker 迁移。元组 约束属于最后添加的列，因此迁移只扫描一次现有 环境，并保留该表而不是重建它。租约、 凭据、放置、推理轮次、未知附加数据和不确定 清理保持完整。迁移事务中不运行任何 provider 操作。

迁移内容及其版本事实一起提交；失败会回滚该尝试的所有 数据库更改。两个已发布标记通常在该事务中推进到 17。当旧更新器仍拥有尾部账本读取时， 现有的版本发布延迟 将已发布标记保留在较早版本，并单独记录已应用内容 17。重新打开不会重复该内容迁移。Workshop 目录重定位随后在模式事务之外运行。

升级前，停止旧写入器并创建经过验证的、支持 WAL 的备份。 支持状态模式 16 或更早版本的构建会拒绝已发布的模式 17。 要回滚，请使用兼容构建完成云清理，停止所有写入器， 然后将升级前备份恢复到单独的状态目录。恢复 不会保留该备份之后所做的更改。不要降低任一版本 标记或擦除已消耗的绑定。未解决的 provider 清理可能会继续 产生费用，直到删除得到确认。

状态模式 16¶

模式 16 从 skill_workshop_proposals 中移除 workspace_dir 和 claim_released_time。它还从集合审查 历史中移除 workspace_dir 和 idx_skill_workshop_collection_reviews_workspace_time，并添加 owner_agent_id 及其所有者/时间索引。提案行保持完整。某个提案的声明被 集合审查释放后，该提案变为带有状态原因的 stale，因此它曾经创建的 skill 路径保持用户所有，Doctor 永远不会重定位它。

Skill Workshop 所有权现在是物理 <state-dir>/agents/<agentId>/agent/workshop-skills 目录。启动和 openclaw doctor --fix 在共享模式事务中删除已退役的列和索引。然后两者 运行相同的迁移，将已应用的旧版 Workshop 创建重定位到 推断的所有者 agent，并重新定向符合条件的待处理创建。冲突和所有权不明确会 变为陈旧提案，并保持旧版目录不变。审查历史行 在可能时映射到唯一的所有者 agent；否则模式迁移会将其作为 缓存类状态丢弃。

如果数据库报告模式 16，但仍存在可识别的模式 15 Workshop 列，更新预检会识别待处理迁移，Doctor 会在重建规范索引之前运行它。仅提案遗留列也以相同方式处理。修复会保留可归属的评审行和无关索引；无法识别的列集合或对已弃用列的依赖仍会拒绝并回滚事务。

仅技能工作区迁移使用现有 migration_runs 和 migration_sources 表保存迁移前的目录标识、文件哈希以及工作区证明时间戳。迁移完成后，仅退役匹配的仅证明状态；设置状态、路径别名和较新的证明保持完整。中断的迁移会复用已保存的迁移前事实，而不是从空目录推断。工作区重置会移除待处理的工作区范围回执。无需额外的模式版本或表。

状态模式 15¶

模式 15 从 current_conversation_bindings 中移除 target_agent_id 和 target_session_id。目标索引使用完整的 target_session_key，并保持非唯一：多个会话可能指向同一目标。这使得插件拥有的目标可以持久存在，而无需虚构一个 OpenClaw 代理所有者。频道/账户隔离、插件审批、绑定标识符、目标键、JSON 元数据、过期和分离行为均保持不变。

启动和 openclaw doctor --fix 会在现有独占写事务中运行迁移。它们仅移除这两个投影并替换目标索引，同时保留所有其他行值。任何依赖的触发器、索引或失败的架构检查都会回滚事务；迁移不会丢弃未知依赖以强制升级。由于列移除会重写绑定表，升级成本会随其大小增长。

升级前请停止旧版本写入器，并创建经过验证、支持 WAL 的备份。支持共享状态模式 14 或更早版本的构建会拒绝已迁移的数据库。若要返回旧版本构建，请将升级前备份恢复到单独的状态目录；不要降低版本标记或重建代理投影。有关通用恢复约定，请参阅 降级。

状态模式 13¶

模式 13 将 cron_jobs.job_json、cron_jobs.state_json 和 subagent_runs.payload_json 设为规范记录。物理列仅在生产查询、排序或仅运行时更新需要时保留。定时任务从 75 列缩减到 15 列，子代理运行从 59 列缩减到 6 列。迁移会通过将其编码为 JSON null 来保留被显式配置为未定义的失败目标字段；它还会在移除冗余投影之前，将旧版运行状态别名规范化到 state_json 中。

工作区证明合并到 workspace_setup_state。当旧数据库没有 workspace_path_aliases 表时，迁移会保留证明时间戳和生成的引导哈希。仅证明工作区会保留空路径，直到再次遇到该工作区。

共享状态的 auth_profile_stores 和 auth_profile_state 单例移动到 config_machine_state 下的 authProfiles.store 和 authProfiles.state；每个代理的认证表保持不变。由于这些行包含凭据，脱敏的 Git 备份会省略 authProfiles. 机器状态前缀。

状态模式 11¶

模式 11 移除 skill_lifecycle 和 skill_workshop_proposal_origin_runs 表。升级期间会丢弃已归档技能的生命周期状态：之前归档的 Workshop 技能会返回活动集合，由每周集合评审根据内容对其进行判断。源运行行是一个从未被读取的投影；规范提案溯源保留在 skill_workshop_proposals.record_json 中。已记录的技能使用情况和集合评审状态会被保留。

状态模式 9¶

模式 9 在已注册的代理数据库位于该目录内时，将 agent_databases.path 值存储为相对于状态目录的路径。迁移期间，如果对应文件存在，外部默认布局行会重新锚定到根内对应项。仅当同一代理已经持有其根内注册时，该行才会被删除，因为双重默认布局注册无法生成有效的合并会话列表。否则，绝对路径行会被保留，因此真正的外部注册永远不会被删除。这使复制的状态目录保持自包含，同时不会丢弃受支持的外部数据库路径。