IronClaw Reborn 迁移与兼容性契约:复用存量表结构、桥接新架构的数据迁移实战指南

原创2026-09-24 20:09:171,882 阅读
文章标签:人工智能AI 应用AI Agent本地部署MCP Clients提示词注入防护RAG插件系统

IronClaw Reborn 迁移与兼容性契约:复用存量表结构、桥接新架构的数据迁移实战指南

本文基于 IronClaw 仓库 docs/internal/reborn/contracts/migration-compatibility.md(Contract-freeze draft,2026-04-25)展开。Reborn 是 IronClaw 面向隐私、安全与可扩展性的新一代 Agent OS 架构,本契约冻结了"数据迁移与兼容性"的所有关键决策:何时复用现有生产表、何时允许新建 schema、如何保证 PostgreSQL 与 libSQL 双后端一致,以及迁移上线前必须通过哪些验收测试。读完本文,你将掌握 Reborn 的冻结迁移原则、记忆/密钥/设置/运行时/事件五大领域的兼容策略、整体切换(Cutover)模型与迁移验收清单,并能将其直接用于 Reborn 工程任务的实现与评审。


1. 契约定位:为什么需要一份"迁移与兼容性"契约

1.1 契约的冻结原则

Reborn 必须在不破坏现有生产数据的前提下重构存储层。契约给出的唯一迁移方针是:

Reuse existing schemas where viable, bridge only when necessary.
(现有 schema 可用则复用,仅在必要时桥接。)

这句话同时约束了两件事:

  • 能复用就不重建:任何一张正在工作的生产表,只要其形态能满足冻结契约的需求,就不允许用一张全新的 Reborn 表替换它;
  • 桥接是例外而非默认:新建 schema 必须有契约层面的正当理由,且 PR 必须论证"为什么在现有 schema 之上包一层 adapter 不够"。

该契约在 docs/internal/reborn/contracts/_contract-freeze-index.md 中被列为"New contracts in this packet"之一,并与其依赖的 storage-placement.md、memory.md、settings-config.md、secrets.md 共同构成完整的冻结决策包。契约冻结不代表实现全部完成,而是让工程师接手任务时能明确知道:哪个 crate 拥有领域、持久化状态放在哪里、哪些失败必须 fail-closed、哪些测试必须通过。

1.2 契约适用于哪些工程任务

按照冻结索引的委托就绪清单,凡是触及持久化、权威(authority)、事件、网络、密钥、文件系统、记忆、审批或运行时执行的迁移任务,都必须在任务说明中携带:

Contract doc path(s)          契约文档路径
Target crate(s)               目标 crate
Source-of-truth storage       存储权威位置
Scope fields to propagate     需要传播的 scope 字段
Fail-closed cases             必须失败关闭的场景
Redaction/no-leak requirements 脱敏/无泄漏要求
PostgreSQL/libSQL parity      双后端一致性要求
Acceptance tests              验收测试清单

迁移任务一旦需要修改冻结的归属、scope、存储位置或失败语义,就不再是"实现工作",而是一次"契约变更请求"。


2. 通用规则:八条不可违反的迁移准则

契约第 2 节给出了八条通用规则,是所有迁移工作的总纲:

  1. 不替换可用生产表:现有表形态能满足冻结契约时,禁止用新 Reborn 表替代;
  2. 优先仓储/adapter:尽量在现有 schema 之上编写 repository/adapters,而不是重建表;
  3. 只补契约要求的增量:新增迁移仅用于补充契约强制要求的列、索引或约束;
  4. PostgreSQL 与 libSQL 同时考虑:任何 schema 决策都必须同时验证两个后端,除非契约明确声明某后端不支持;
  5. 已发布迁移不可变:已发布(released)的迁移是 immutable 的,任何变更必须通过新增迁移实现;
  6. 记录回滚/兼容风险:实现 PR 必须记录回滚方案与兼容性风险;
  7. 回填必须幂等(idempotent):重复执行回填不得产生重复或错误数据;
  8. 多租户隔离回归:每次 schema 或映射变更后,都必须重新测试多租户 scope 隔离。

第 5 条与第 7 条是实践中最容易出问题的两个点:迁移文件一旦被消费过就不能再改动(对应仓库 migrations/ 目录下 V1~V34 的版本化命名惯例),而回填脚本必须天然可重放,例如通过 ON CONFLICT DO NOTHING 或先查后写的方式保证重复执行安全。


3. 记忆 schema 兼容(Memory Schema Compatibility)

3.1 需要保留的生产表家族

现有生产环境中的记忆数据由四张表承载,契约要求"在可行时完整保留":

memory_documents
memory_chunks
memory_chunks_fts        # libSQL 专用 FTS 表
memory_document_versions

这四张表的真实物理结构可以在 migrations/V1__initial.sql 与 migrations/V16__document_versions.sql 中确认:

  • memory_documents:id(UUID 主键)、user_id TEXT、agent_id UUID(可为 NULL,NULL 表示该用户下所有 agent 共享)、path TEXT(如 context/vision.md、daily/2024-01-15.md)、content TEXT、created_at/updated_at、metadata JSONB,并有 UNIQUE (user_id, agent_id, path) 唯一约束;
  • memory_chunks:按文档切分用于混合检索(FTS + 向量),content_tsv TSVECTOR 由 to_tsvector('english', content) 生成,embedding VECTOR(1536)(对应 text-embedding-3-small),并建有 GIN 的 idx_memory_chunks_tsv 与 HNSW 的 idx_memory_chunks_embedding(vector_cosine_ops,m=16、ef_construction=64);
  • memory_document_versions:每次内容更新保存上一版本(version、content、content_hash、changed_by),UNIQUE(document_id, version),支持回滚与审计。

3.2 必需的 Reborn 映射

契约要求将上述存量数据映射到 Reborn 的全局 scope 模型:

tenant_id + user_id -> scoped owner key in user_id,除非未来迁移直接加 tenant_id 列
agent_id            -> 已有 agent_id 列存在时直接复用
project_id          -> project path 前缀,或未来显式列
relative path       -> path
content             -> content
metadata            -> metadata JSON/JSONB
chunks              -> memory_chunks
versions            -> memory_document_versions

这与 memory.md 中"复用现有生产 schema"的映射完全一致:user_id 承载 scoped owner key(形如 tenant:{tenant}:user:{user}),agent_id 保留为可选的一等 scope,项目映射在物理 schema 变更前继续使用 projects/{project_id}/{relative_path} 前缀。注意:当前没有 agents/{agent} 段的实现路径是过渡性的,契约要求在记忆服务声明"parity 完成"之前必须补上 AgentId。

3.3 兼容性硬性要求

  • agent_id = NULL 的存量行在缺失 AgentId 时必须仍然可见(即 NULL 语义被保留为"未绑定 agent");
  • 存量 agent-scoped 行必须映射到 Reborn 的 AgentId;
  • 现有 sha256:{hex} 版本哈希格式必须继续有效(对应 memory_document_versions.content_hash 的既有格式);
  • libSQL 的 FTS 触发器行为必须保持有效(对应 memory_chunks_fts);
  • pgvector / libSQL 向量嵌入在维度匹配处必须保持可读(存量 VECTOR(1536) 嵌入不能被破坏);
  • project path 前缀映射必须保证既有文档依旧可被发现(如 projects/alpha/notes.md 不会被搜索丢出)。

双读/回填先行原则:如果未来迁移要增加显式的 tenant_id、project_id 或 agent_id 字符串列,那么在切换读取路径之前,必须先对新列做 dual-read(双读)或从存量行回填,绝不能先切读后补数。


4. 根文件系统兼容(Root Filesystem Compatibility)

root_filesystem_entries 是 Reborn 中承载"通用 DB 支撑的文件内容"的合法表。契约明确它适用于:

不需要领域特定查询语义的 file-shaped 状态
适合 DB 文件存储的小型 JSON / 文件投影

同时明确禁止将其作为以下记录的权威来源(source of truth):

memory documents(需要搜索/索引/版本能力)
secrets 生产记录
settings 权威记录
events / audit 追加日志
需要类型化查询的 process / control-plane 记录

这条边界与 storage-placement.md 的混合存储模型完全一致:文件形态内容走 RootFilesystem / ScopedFilesystem / CompositeRootFilesystem,结构化、查询密集、控制面或安全敏感的记录走领域拥有的类型化仓储,派生数据(chunks、搜索索引、嵌入、投影)归各自的服务/索引器/投影层所有。工程上最常见的错误就是把 secrets 或 settings 塞进通用文件表"图省事"——这正是契约禁止的行为。


5. 密钥兼容(Secrets Compatibility)

5.1 生产权威与既有实现

生产环境密钥的 source of truth 是类型化的加密密钥仓储。契约要求将现有已测试实现的加密逻辑整体移植/适配到 Reborn:

src/secrets/crypto.rs
src/secrets/keychain.rs
src/secrets/store.rs
src/secrets/types.rs

现有 schema 血统(lineage)如下,迁移时必须保持兼容:

secrets(
  id,
  user_id,
  name,
  encrypted_value,
  key_salt,
  provider,
  expires_at,
  last_used_at,
  usage_count,
  created_at,
  updated_at
)

5.2 密钥迁移五条规则

  1. 尽量保持加密材料兼容:已加密的密文与 key_salt 应能被新仓储直接读取,避免无条件重加密;
  2. 禁止通过通用文件列表暴露:secret 记录绝不能出现在通用文件列举、错误信息、事件或审计中;
  3. 文件型加密 JSON 只是参考/投影模式:filesystem-backed encrypted JSON 不是生产默认方案,仅用于参考或投影;
  4. 迁移必须保留使用元数据:usage_count、last_used_at、expires_at 等审计/生命周期字段在迁移中不可丢失;
  5. master-key/keychain 解析必须先文档化并测试:在向生产注入之前,主密钥与密钥链解析的完整流程必须成文并通过测试。

这与 secrets.md 的边界一致:ironclaw_secrets 只提供"元数据 + 一次性租赁(lease)"原语,加密载荷与每记录盐存储于带 scope 的文件系统路径下,主密钥缺失或畸形时必须 fail-closed;密钥记录的写入只允许走 SecretStore::put(...)(受信任的 setup/迁移路径),运行时与插件不能直接触碰。


6. 设置/配置兼容(Settings/Config Compatibility)

6.1 现状与目标

生产环境目前把部分系统状态存为工作区文档:

.system/settings/**
.system/extensions/**
.system/skills/**
.system/engine/**

而 Reborn 生产的权威来源是类型化仓储 + 可选的文档投影。契约给出的五步迁移策略是:

  1. 读取现有 .system/... 工作区文档;
  2. 校验其是否符合归属 schema;
  3. 导入到类型化仓储;
  4. 保留文档投影用于兼容与诊断;
  5. 标记不支持/畸形文档,并给出可操作的迁移诊断信息。

6.2 投影回写约束

文档投影(如 /system/settings/{scope}/{key}.json)只允许在投影契约明确许可时才支持回写,且回写必须调用类型化仓储,而不是直接改投影存储。这与 settings-config.md 的投影三模式(read-only / validated write-back / export-only)衔接:默认视图是投影而非权威,若视图允许写入,则写入必须先校验 schema 再走类型化 API,绝不能绕过领域不变量直接改原始存储行。

另外注意 settings 的层级划分(bootstrap config、DB-backed settings、secrets、extension config、file projections)与推荐优先级(显式调用覆盖 → agent/project → user → tenant → system default → bootstrap fallback)都由 settings-config.md 冻结,迁移时不得打乱这条解析链。


7. 引擎/运行时状态兼容(Engine/Runtime State Compatibility)

高变更频率(high-churn)的引擎运行时 blob 禁止被索引为记忆。契约点名了当前生产中的典型路径:

engine/.runtime/**
engine/projects/**
engine/orchestrator/failures.json
engine/README.md

迁移策略有四条:

  • 可查询的运行时状态迁入类型化仓储;
  • 文件形态的运行时 blob挂载到 /engine/runtime 或 /engine,并标记 IndexPolicy::NotIndexed;
  • 安全时删除这些路径下迁移/回填过程中产生的陈旧 memory chunks;
  • 不创建语义记忆版本:高变更 blob 除非显式晋升为知识(knowledge),否则不为其创建语义记忆版本。

IndexPolicy::NotIndexed 是真实存在于源码中的枚举值,见 crates/substrates/ironclaw_filesystem/src/types.rs:NotIndexed、FullText、Vector、FullTextAndVector、BackendDefined。在 crates/app/ironclaw_composition/src/filesystem_assembly.rs 中,engine 与 engine/runtime 等挂载点正是以 IndexPolicy::NotIndexed 装配的——这印证了"运行时状态不得污染记忆索引"在组合层已被落实。


8. 事件/审计兼容(Events/Audit Compatibility)

事件与投影需要一个带重放游标(replay cursors)的持久追加日志。契约给出的策略:

  • 当前 JSONL / 内存 sink 可以保留为 adapter 或开发后端,但不能承担生产职责;
  • 生产事件日志必须支持 cursor 重放与 scoped 保留(按租户/用户等 scope 的留存策略);
  • 审计记录保持脱敏,且不被 UI 事件投影取代(UI 投影只是展示层,审计才是合规层);
  • 存量日志在 schema 可校验的前提下可以 best-effort 导入。

这与冻结索引中"Events/projections: durable append log plus scoped replay cursors are substrate dependencies"的决策对应:可重放的事件日志是底层 substrate 依赖,SSE/WebSocket 传输是建立在其上的下游产品集成。


9. 整体切换模型(Cutover Model)

9.1 连贯组合路径,而非孤岛

Reborn 应以连贯的组合路径(coherent composition path)交付给用户,而不是以零散暴露的孤岛形式出现。内部 Reborn crates 与 adapters 可以增量落地,但生产暴露必须由 feature flag、并行二进制或等效部署开关守护,直到调用层集成主干(caller-level integration spine)完成。

9.2 切换硬性要求

  • 一个由配置驱动的生产组合根:为 HostRuntimeServices 及邻近的参考/用户态服务提供单一组合入口;
  • 调用层测试覆盖主干:CapabilityHost -> Dispatcher -> Adapter -> Process/Event/Memory 全链路必须有 caller-level 测试;
  • 复用旧 schema 必须有显式迁移/回填路径;
  • 物理布局迁移是最后一步:凡是"用日志替换热生产 blob"的 RootFilesystem 物理布局迁移(例如旧 turn 状态迁移到 process journal),必须放在整条栈的最后一环——在迁移以幂等方式执行完毕且行回读(row readback)被验证之前,整条栈不得上线;
  • 桥接必须附回滚说明:任何可能影响生产状态的 bridge 都要写清 rollback notes;
  • 杜绝意外双权威:legacy src/ 服务与 Reborn 仓储之间不得出现意外的 dual source of truth。

9.3 与 legacy src/ 的关系

契约没有宣布对 legacy src/ 的一刀切 feature 冻结:安全修复、紧急客户修复、以及明确批准的兼容性工作仍允许继续修改 src/。新的一般性产品工作应在可行时优先使用 Reborn crates,但"是否硬性冻结 src/ 新增功能"是独立的策略决策,不属于本契约的更新范围。


10. 迁移验收测试(Migration Acceptance Tests)

每一项迁移/兼容任务都必须包含以下测试要素(契约逐条列出):

old-shape fixture read test        旧形态 fixture 的读取测试
new-shape write test               新形态的写入测试
idempotent backfill test           幂等回填测试
tenant/user/project/agent isolation test  多租户隔离测试
PostgreSQL/libSQL parity or explicit backend exclusion  双后端一致性或显式后端排除
rollback/failure-mode note         回滚/失败模式说明
no-leak assertion for secrets/events/errors where relevant  密钥/事件/错误无泄漏断言
git diff --check and targeted DB migration checks          差异检查与定向 DB 迁移检查

其中"old-shape fixture read test"直接对应本契约第 3.3 节的所有兼容性硬性要求:agent_id = NULL 可见性、sha256:{hex} 哈希格式、libSQL FTS 触发器行为、向量嵌入可读性、project 前缀可发现性,都需要用旧形态 fixture 固化,防止未来重构悄悄破坏兼容。双后端(PostgreSQL/libSQL)一致性是铁律:除非契约明确声明某后端不支持,否则共享生产仓储必须两个后端都通过测试。


11. 何时允许新建 schema

11.1 新建 schema 的七种正当理由

当现有 schema 无法支持以下任一项时,新建 schema 才被允许:

required scope isolation, especially tenant_id / AgentId    必需的 scope 隔离(尤其 tenant_id / AgentId)
required query shape without unsafe scans                   免不安全扫描的必需查询形态
required transactionality                                   必需的事务性
required redaction/security invariant                       必需的脱敏/安全不变量
required event cursor ordering                              必需的事件游标排序
required lifecycle state machine                            必需的生命周期状态机
required retention/deletion semantics                       必需的保留/删除语义

11.2 PR 论证义务

任何新建 schema 的 PR 必须说明:为什么在现有 schema 之上包一层 adapter 是不够的("The PR must state why an adapter over existing schema is insufficient")。这条论证义务把"复用优先"从口号变成可评审的工程事实——评审者会检查你确实评估过 adapter 方案,而不是默认选择重建。


12. 实战落地检查单(供 Reborn 工程师使用)

结合本契约与 storage-placement.md 第 9 节的工程任务清单,一个迁移任务在开工前必须能回答:

  1. 目标虚拟区/前缀是什么(如 /memory、/secrets、/system/settings、/engine/runtime)?
  2. 权威仓储/后端是哪个(复用 memory_documents,还是新建类型化仓储)?
  3. scope 字段有哪些,是否涉及 AgentId?
  4. 文件系统访问是权威还是投影?
  5. 索引策略是什么(IndexPolicy::NotIndexed 或 BackendDefined 等)?
  6. 删除/版本化行为如何?
  7. PostgreSQL/libSQL 一致性要求是什么?
  8. 迁移/回填影响面多大,回填是否幂等?
  9. 共享存储机制(ironclaw_storage 的 StorageBackendKind、StorageMigration、PageLimit、BlobStore/RecordStore/AppendLog/LockStore 等)是复用还是扩展?

若答案无法从本契约或所属领域契约中找到,该任务尚未达到可实施状态("If the answer is not in this document or the owning domain contract, the task is not ready for implementation")。


13. 相关契约与源码导航

登录后查看全文
ironclaw