尧图网站建设 
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 作为以隐私、安全与可扩展性为核心的 Agent OS其Reborn持久化体系persistence rules定义了整个工作区所有数据落盘的唯一范式一个存储平面RootFilesystem挂载目录、一套原子性规则共享的cas_updateCAS 路径、以及严格的多后端行为一致性要求。本文以 .claude/rules/database.md 为骨架结合 ironclaw_filesystem 的源码与测试逐条讲解每条规则背后的设计意图、落地代码与验证手段帮助你在为 IronClaw 新增任何持久化能力新领域存储、挂载点、版本化写操作时一次做对、不踩并发与数据安全陷阱。一、单一存储平面一切持久化都活在挂载目录里规则第一条即声明新增持久化必须使用RootFilesystem挂载目录mount catalog。消费者拿到的是ScopedFilesystem与类型化的领域包装typed domain wrappers它们从不自己挑选后端也不维护并行的后端分发 trait。这意味着整个工作区——密钥secrets、租约leases、进程processes、记忆文档memory documents、项目文件、事件日志event logs、引擎状态、设置等——全部收敛到同一组操作之上put/get/delete/list_dir/list_dir_page/query/ensure_index/stat/begin/append/tail。这一边界在 ironclaw_filesystem/CONTRACT.md 中被描述为universal storage dispatch fabric通用存储分发织网。1.1 核心类型一个 trait、一个 Entry、一个分发器从 src/root.rs 可以看到整个体系只有一个 traitRootFilesystemput/get统一 Entry 平面的读写put携带CasExpectation比较交换前置条件并返回新的RecordVersionlist_dir/list_dir_page目录列举后者是受max_entries约束、以子节点名做续传键keyset的分页query/ensure_index声明式索引与查询原语SQL 字符串不越过这一边界begin供原生支持多键事务的后端使用append/tail日志形态挂载event plane的追加与回放。同时还有CompositeRootFilesystemsrc/catalog.rs——它本身也是一个RootFilesystem通过最长前缀longest-prefix匹配的挂载表把虚拟路径路由到具体后端。这里刻意没有Backend / Dispatcher两级拆分分发器就是后端唯一的 trait 贯穿始终。ScopedFilesystemsrc/scoped.rs是调用作用域化的视图高层存储在其构造函数中接收ArcScopedFilesystemF每次操作都会携带调用方的ResourceScope由MountViewResolver解析出MountView并在任何后端分发之前先做权限校验。生产环境组合composition提供的解析器会把/secrets、/authorization等消费方别名解析到/tenants/tenant/users/user/alias这样的真实虚拟路径租户隔离来自解析器而非每租户的存储缓存。1.2 用命令验证核心面规则文档给出的验证命令可以直接复现rg -n trait RootFilesystem|struct ScopedFilesystem|fn cas_update crates/substrates/ironclaw_filesystem三条命中分别对应 src/root.rs、src/scoped.rs 与 src/cas.rs是一个平面最直接的代码证据。改动任何存储行为前都应先读 ironclaw_filesystem/CONTRACT.md 与所属领域契约。二、所有权划分谁拥有什么边界在哪持久化体系的第二根支柱是清晰的职责归属规则文档给出四层划分层拥有什么ironclaw_filesystem路径paths、挂载mounts、包含关系containment、版本versions、CAS领域 cratedomain crates记录 schema、序列化、领域不变量组合层composition选择具体后端并把它们挂载起来产品工作流product workflow消费类型化存储绝不穿透到后端配套的硬性红线是不要仅仅因为某个领域 DTO 或策略分支需要被持久化就把它们塞进 filesystem crate。领域 crate 拥有记录语法与服务契约这是 crates/AGENTS.md 中domains 是系统所知道的记录这一分层模型在存储侧的延伸。ironclaw_filesystem自身还坚持一套严格的依赖边界从 CONTRACT.md 看它只允许依赖ironclaw_host_api、ironclaw_safety仅一个敏感路径脱敏谓词、ironclaw_libsql_runtime连接准入它从不自建连接池与ironclaw_observability超出即属边界违规由架构测试ironclaw_architecture_tests把关。三、新增持久化操作的标准流程规则文档给出了六步流程配合审查标志使用定位领域所有者在 crates/AGENTS.md 中找到领域 owner阅读其本地契约在该领域 crate 内定义类型化操作与记录形态Entry的新 record kind、索引投影indexed projections属于消费方 crate不属于 filesystem crate复用现有作用域挂载若领域确实是全新的才通过 filesystem catalog 与 composition 装配新增挂载后端选择留在组合层领域存储不得依据 PostgreSQL、libSQL 或本地文件系统配置做分支版本化文件系统变更用cas_update后端原生多语句不变量用后端事务在公开领域操作或类型化包装接缝处补契约测试涉及挂载选择、重启或跨域行为时再补一个生产组合production-composition测试。3.1 五个红灯审查标志评审新代码时以下任一情况都该停下来重新设计新增的Store/Repositorytrait 唯一目的只是挑选后端应直接使用RootFilesystem挂载消费者直接打开具体后端连接应只接触ScopedFilesystem与类型化包装类型化存储接收RootFilesystem而实际上ScopedFilesystem就足够作用域与权限校验会被绕过一次写入先读版本、随后不经过 CAS 直接覆盖读改写必须走 CAS 路径在文件系统/后端 I/O 上横跨持有一个按记录粒度的 async mutex进程内锁无法协调多进程且会在爆发流量下造成运行时队头阻塞。其中最后一条正是后面要展开的 CAS 规则的核心动机。四、原子性与并发cas_update是唯一合法的读改写通道规则文档的并发章节可以浓缩为一句话每一个 read-modify-write 都必须走共享的有界 CAS 更新路径。不要持有进程内 mutex 跨越后端 I/O——它既无法协调多进程又会在同作用域写者爆发时形成车队convoy把运行时拖垮。4.1 为什么不能用 per-record mutex一次真实事故从 src/cas.rs 的模块文档可以读到完整来龙去脉历史上每个存储用tokio::sync::Mutex包裹整个 CAS 循环并横跨.await持有爆发流量下这些锁形成车队最终造成 2026-06-24 的运行时 wedge 事故。PR #5142 从ironclaw_turns中移除了 mutex验证了无锁模式乐观 CAS 重试循环配上有界重试、抖动指数退避与总超时。cas_update把这个经过验证的模式抽取成唯一被审计的实现让每个存储都能把 mutex 换成它。4.2cas_update的契约与常量cas_update 是一个泛型助手调用方提供三个闭包decode: Fn([u8]) - ResultS, E——把存储体反序列化为快照类型Sencode: Fn(S) - ResultEntry, E——把下一版快照序列化为版本化Entry在此设置kind/content_typeapply: FnMut(OptionS) - Future...——接收当前快照记录缺失时是None计算下一版快照与结果。apply必须幂等、可重入每次 CAS 重试都会基于最新读到的快照重新调用它因此绝不能修改外部状态。循环语义如下读取path当前的版本化快照并解码运行apply得到下一版快照与调用方定义的结果T或错误E快照未变化或调用方显式返回 no-op时直接返回结果不写盘否则以读到的版本作为 CAS 前置条件写回首次写入用CasExpectation::Absent或按CasApply::delete做条件删除命中FilesystemError::VersionMismatch则重读、以抖动指数退避重试成功的条件删除也必须重读重放apply后再返回防止 delete recreate 的 ABA 周期提前满足调用方后置条件。整个循环被FILESYSTEM_APPLY_TIMEOUT超时包裹——一个卡死的后端操作只消耗本次调用方的尝试配额不会让无关调用方无限等待。相关常量与ironclaw_turns参考实现逐字对齐见 cas.rs常量值含义FILESYSTEM_CAS_RETRIES32竞争下的变更尝试上限FILESYSTEM_APPLY_TIMEOUT15s整个循环含全部重试的截止时间FILESYSTEM_CAS_BACKOFF_BASE2ms首次重试前的退避FILESYSTEM_CAS_BACKOFF_MAX50ms指数退避的天花板退避是2ms 基数、每次翻倍、封顶 50ms再加最多一个基数时长的抖动cas_retry_backoff抖动由RandomState播种的尝试索引哈希产生在粗时钟平台VM、容器、Windows上也不会塌缩为零。4.3 四种变更结果与失败关闭apply通过CasApplyS, T选择四种类型化变更结果cas.rsCasApply::new(snapshot, outcome)——正常写回当快照与apply收到的一致时走PartialEq快速路径跳过写盘CasApply::no_op(snapshot, outcome)——无条件跳过写入用于当前记录为None且不应创建空/默认记录的场景CasApply::delete(snapshot, outcome)——按刚读到的版本条件删除删除成功后还会再读一次并重跑apply以验证调用方后置条件在 delete recreate 的 ABA 周期下依然成立CasApply::force_write(snapshot, outcome)——只绕过解码快照的相等性快速路径仍然走相同的有界、能力门控的 CAS 重试用于修复Entry侧车sidecar如索引投影元数据的场景。失败模式由CasUpdateErrorE承载cas.rs调用方apply的错误以Apply(E)原样透传不二次包裹Timeout、RetriesExhausted、CasUnsupported与Backend(FilesystemError)由调用方用一个map_err闭包统一映射进自己的错误枚举。失败关闭fail-closed能力门控是cas_update的底线它绝不在非 CAS 后端上退化为盲写CasExpectation::Any。门控分两层预检pre-flight若后端声明了已知能力形态且不含TxnCapability::Cas或更丰富直接返回CasUnsupported——这能在字节型挂载如仅支持字节读写的DiskFilesystem误配时于写操作前就拦住操作时op-time能力形态为空/未知即组合路由器时延后到写操作把FilesystemError::Unsupported映射为同一个CasUnsupported。无论哪层结果都是拒绝而非无条件变更。所有生产存储挂载都解析到支持 CAS 的数据库/内存后端因此失败关闭是正确且安全的默认。4.4 并发验证CAS 风暴测试规则冲突、重试耗尽、重启、部分失败行为必须在公开领域操作接缝测试在 tests/concurrent_cas_storm.rs 中有直接落地多线程 tokio 运行时上每轮tokio::spawn16 个写者、重复 100 轮全部并发对同一个快照路径做cas_update自增——每个cas_update必须成功捕获后端错误缺陷且最终计数必须等于WRITERS * ITERATIONS1600捕获丢失更新缺陷。该测试同时覆盖 in-memory、libSQL 与 PostgreSQL 三种后端libSQL 变体是 #5466 的回归钉此前每次操作新建连接策略在 C 库内间歇性失败、而被否决的单共享连接设计又会把 CAS 影响行数读回损坏成丢失更新Postgres 变体用每次运行唯一的 UUID 前缀隔离共享数据库且在后端不可达时优雅跳过。配套的run_delete_storm进一步压测delete_if_version本身的并发每轮重建共享路径到已知版本16 个任务以精确版本竞争条件删除断言每轮恰好一个赢家、其余全部观察到格式良好的NotFound绝无丢失或重复删除。五、多后端一致性行为一致而非仅 schema 一致当某个领域显式支持多个持久化后端时规则要求对排序、唯一性、时间戳、索引、事务、错误分类保持行为一致并且把对抗性adversarial一致性用例放进共享的一致性套件shared conformance suite而不是为每个实现复制一份测试。规则文档明确强调Parity is behavioral, not merely schema-shaped.即一致性是行为层面的不是表结构层面的。需要对比的点包括唯一性与索引、时间戳精度与排序、JSON/枚举序列化、事务回滚、并发写者结果、种子/默认记录、迁移回放、错误分类。修复某个实现时要同时搜索它的同类实现与共享一致性套件中相同的模式。从源码结构看ironclaw_filesystem正是通过让全部后端实现同一个RootFilesystemtrait 来支撑这一要求的DiskFilesystem、PostgresRootFilesystem、LibSqlRootFilesystem、InMemoryBackend、HsmBackend都是该 trait 的实现可用rg -n impl RootFilesystem for crates/substrates/ironclaw_filesystem/src/复现契约测试与 CAS 风暴测试直接以同一份测试体驱动多个后端天然构成共享一致性套件。能力由BackendCapabilities/Capability/TxnCapability在挂载前声明src/types.rs挂载时校验拒绝无法满足消费方声明的后端见 catalog.rs 的mount_dyn运行期Unsupported只是兜底信号而非主要信号。后端选择确实发生在组合层例如 production_backend_assembly.rs 中libSQL 路径用LibSqlRootFilesystem::from_runtime装配、Postgres 路径用PostgresRootFilesystem::new装配领域存储只依赖类型化包装不感知具体后端。数据库 schema 演进则集中由 migrations/ 目录管理V1 到 V34覆盖 wasm 版本化、用户身份、根文件系统条目与索引、工具作用域等主题这与规则中迁移回放属于一致性对比点相互印证。六、数据安全模型输出与用户数据绝不静默丢弃最后一条规则划定不可逾越的数据安全底线绝不静默丢弃模型输出、审计事件、对话记录transcripts或用户数据破坏性操作需要显式的产品契约product contract、授权authorization与作用域隔离测试存储错误在返回给边界时必须脱敏sanitized boundary error同时保留服务端原因以便排障——这与 src/types.rs 中Display 输出刻意使用作用域/虚拟路径而非原始宿主路径保护主机路径机密性的约定一致缓存淘汰不等于持久删除缓存未命中必须能从属主存储重新加载任何保留/删除功能都需要显式的租户/用户作用域、可审计证据、重启安全行为以及证明无关记录存活的测试。七、落地清单与验证手段把规则文档落到实际工作可总结为一张检查清单定位 owner先读 crates/AGENTS.md 与领域契约再动手不建新 trait一个RootFilesystem足够特殊情况优先考虑拓宽Entry或扩展 trait而不是另立门户读改写一律cas_update有界重试32 次、总超时15s、抖动退避2ms 起、50ms 封顶、失败关闭能力门控绝不复制本地重试循环、绝不加 per-record mutex历史遗留的本地循环见 CONTRACT.md 的迁移追踪不是可模仿的先例多语句不变量用后端事务顺序 await 不构成原子性同时有 Postgres 与 libSQL 实现时用共享一致性套件验证相同的提交/回滚与并发行为索引投影是唯一可查询面后端绝不解析Entry::body来求值过滤器一切可查询内容都在Entry::indexed请求路径使用query_ordered 声明的精确/前缀索引 keyset 游标且容量/能力挂载时校验补测试在公开领域操作接缝补契约测试可借助 fault.rs 的FaultInjecting装饰器让真实存储走故障路径涉及挂载选择/重启/跨域时补生产组合测试验证命令cargo test -p ironclaw_filesystem跑完整 crate 测试rg -n impl RootFilesystem for crates/substrates/ironclaw_filesystem/src/复核后端清单。遵循这套规则新增的持久化能力就会自然获得多进程安全的原子性、跨后端的行为一致性与可审计的数据安全而这正是 IronClaw 以隐私和安全为核心的设计哲学在存储层最直接的体现。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐AgentView 存储规则全解SQLite 归档、DuckDB 镜像与多后端一致性设计AgentView 存储规则全解SQLite 归档、DuckDB 镜像与多后端一致性设计 AgentView 是一个本地优先local first的编码AI 应用数据分析数据可视化可观测性Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约 导读 本文是 Agent Storage Spec https://link.gi后端微服务配置中心服务注册发现云原生Slang 内存一致性模型实战指南数据竞争、原子操作、内存屏障与多后端验证Slang 内存一致性模型实战指南数据竞争、原子操作、内存屏障与多后端验证 导读 本文以 Slang 语言参考文档 https://link.gitcode.编译器图形学编程语言创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw 持久化规则实战解析：单一存储平面、CAS 原子性与多后端一致性
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 作为以隐私、安全与可扩展性为核心的 Agent OS其Reborn持久化体系persistence rules定义了整个工作区所有数据落盘的唯一范式一个存储平面RootFilesystem挂载目录、一套原子性规则共享的cas_updateCAS 路径、以及严格的多后端行为一致性要求。本文以 .claude/rules/database.md 为骨架结合 ironclaw_filesystem 的源码与测试逐条讲解每条规则背后的设计意图、落地代码与验证手段帮助你在为 IronClaw 新增任何持久化能力新领域存储、挂载点、版本化写操作时一次做对、不踩并发与数据安全陷阱。一、单一存储平面一切持久化都活在挂载目录里规则第一条即声明新增持久化必须使用RootFilesystem挂载目录mount catalog。消费者拿到的是ScopedFilesystem与类型化的领域包装typed domain wrappers它们从不自己挑选后端也不维护并行的后端分发 trait。这意味着整个工作区——密钥secrets、租约leases、进程processes、记忆文档memory documents、项目文件、事件日志event logs、引擎状态、设置等——全部收敛到同一组操作之上put/get/delete/list_dir/list_dir_page/query/ensure_index/stat/begin/append/tail。这一边界在 ironclaw_filesystem/CONTRACT.md 中被描述为universal storage dispatch fabric通用存储分发织网。1.1 核心类型一个 trait、一个 Entry、一个分发器从 src/root.rs 可以看到整个体系只有一个 traitRootFilesystemput/get统一 Entry 平面的读写put携带CasExpectation比较交换前置条件并返回新的RecordVersionlist_dir/list_dir_page目录列举后者是受max_entries约束、以子节点名做续传键keyset的分页query/ensure_index声明式索引与查询原语SQL 字符串不越过这一边界begin供原生支持多键事务的后端使用append/tail日志形态挂载event plane的追加与回放。同时还有CompositeRootFilesystemsrc/catalog.rs——它本身也是一个RootFilesystem通过最长前缀longest-prefix匹配的挂载表把虚拟路径路由到具体后端。这里刻意没有Backend / Dispatcher两级拆分分发器就是后端唯一的 trait 贯穿始终。ScopedFilesystemsrc/scoped.rs是调用作用域化的视图高层存储在其构造函数中接收ArcScopedFilesystemF每次操作都会携带调用方的ResourceScope由MountViewResolver解析出MountView并在任何后端分发之前先做权限校验。生产环境组合composition提供的解析器会把/secrets、/authorization等消费方别名解析到/tenants/tenant/users/user/alias这样的真实虚拟路径租户隔离来自解析器而非每租户的存储缓存。1.2 用命令验证核心面规则文档给出的验证命令可以直接复现rg -n trait RootFilesystem|struct ScopedFilesystem|fn cas_update crates/substrates/ironclaw_filesystem三条命中分别对应 src/root.rs、src/scoped.rs 与 src/cas.rs是一个平面最直接的代码证据。改动任何存储行为前都应先读 ironclaw_filesystem/CONTRACT.md 与所属领域契约。二、所有权划分谁拥有什么边界在哪持久化体系的第二根支柱是清晰的职责归属规则文档给出四层划分层拥有什么ironclaw_filesystem路径paths、挂载mounts、包含关系containment、版本versions、CAS领域 cratedomain crates记录 schema、序列化、领域不变量组合层composition选择具体后端并把它们挂载起来产品工作流product workflow消费类型化存储绝不穿透到后端配套的硬性红线是不要仅仅因为某个领域 DTO 或策略分支需要被持久化就把它们塞进 filesystem crate。领域 crate 拥有记录语法与服务契约这是 crates/AGENTS.md 中domains 是系统所知道的记录这一分层模型在存储侧的延伸。ironclaw_filesystem自身还坚持一套严格的依赖边界从 CONTRACT.md 看它只允许依赖ironclaw_host_api、ironclaw_safety仅一个敏感路径脱敏谓词、ironclaw_libsql_runtime连接准入它从不自建连接池与ironclaw_observability超出即属边界违规由架构测试ironclaw_architecture_tests把关。三、新增持久化操作的标准流程规则文档给出了六步流程配合审查标志使用定位领域所有者在 crates/AGENTS.md 中找到领域 owner阅读其本地契约在该领域 crate 内定义类型化操作与记录形态Entry的新 record kind、索引投影indexed projections属于消费方 crate不属于 filesystem crate复用现有作用域挂载若领域确实是全新的才通过 filesystem catalog 与 composition 装配新增挂载后端选择留在组合层领域存储不得依据 PostgreSQL、libSQL 或本地文件系统配置做分支版本化文件系统变更用cas_update后端原生多语句不变量用后端事务在公开领域操作或类型化包装接缝处补契约测试涉及挂载选择、重启或跨域行为时再补一个生产组合production-composition测试。3.1 五个红灯审查标志评审新代码时以下任一情况都该停下来重新设计新增的Store/Repositorytrait 唯一目的只是挑选后端应直接使用RootFilesystem挂载消费者直接打开具体后端连接应只接触ScopedFilesystem与类型化包装类型化存储接收RootFilesystem而实际上ScopedFilesystem就足够作用域与权限校验会被绕过一次写入先读版本、随后不经过 CAS 直接覆盖读改写必须走 CAS 路径在文件系统/后端 I/O 上横跨持有一个按记录粒度的 async mutex进程内锁无法协调多进程且会在爆发流量下造成运行时队头阻塞。其中最后一条正是后面要展开的 CAS 规则的核心动机。四、原子性与并发cas_update是唯一合法的读改写通道规则文档的并发章节可以浓缩为一句话每一个 read-modify-write 都必须走共享的有界 CAS 更新路径。不要持有进程内 mutex 跨越后端 I/O——它既无法协调多进程又会在同作用域写者爆发时形成车队convoy把运行时拖垮。4.1 为什么不能用 per-record mutex一次真实事故从 src/cas.rs 的模块文档可以读到完整来龙去脉历史上每个存储用tokio::sync::Mutex包裹整个 CAS 循环并横跨.await持有爆发流量下这些锁形成车队最终造成 2026-06-24 的运行时 wedge 事故。PR #5142 从ironclaw_turns中移除了 mutex验证了无锁模式乐观 CAS 重试循环配上有界重试、抖动指数退避与总超时。cas_update把这个经过验证的模式抽取成唯一被审计的实现让每个存储都能把 mutex 换成它。4.2cas_update的契约与常量cas_update 是一个泛型助手调用方提供三个闭包decode: Fn([u8]) - ResultS, E——把存储体反序列化为快照类型Sencode: Fn(S) - ResultEntry, E——把下一版快照序列化为版本化Entry在此设置kind/content_typeapply: FnMut(OptionS) - Future...——接收当前快照记录缺失时是None计算下一版快照与结果。apply必须幂等、可重入每次 CAS 重试都会基于最新读到的快照重新调用它因此绝不能修改外部状态。循环语义如下读取path当前的版本化快照并解码运行apply得到下一版快照与调用方定义的结果T或错误E快照未变化或调用方显式返回 no-op时直接返回结果不写盘否则以读到的版本作为 CAS 前置条件写回首次写入用CasExpectation::Absent或按CasApply::delete做条件删除命中FilesystemError::VersionMismatch则重读、以抖动指数退避重试成功的条件删除也必须重读重放apply后再返回防止 delete recreate 的 ABA 周期提前满足调用方后置条件。整个循环被FILESYSTEM_APPLY_TIMEOUT超时包裹——一个卡死的后端操作只消耗本次调用方的尝试配额不会让无关调用方无限等待。相关常量与ironclaw_turns参考实现逐字对齐见 cas.rs常量值含义FILESYSTEM_CAS_RETRIES32竞争下的变更尝试上限FILESYSTEM_APPLY_TIMEOUT15s整个循环含全部重试的截止时间FILESYSTEM_CAS_BACKOFF_BASE2ms首次重试前的退避FILESYSTEM_CAS_BACKOFF_MAX50ms指数退避的天花板退避是2ms 基数、每次翻倍、封顶 50ms再加最多一个基数时长的抖动cas_retry_backoff抖动由RandomState播种的尝试索引哈希产生在粗时钟平台VM、容器、Windows上也不会塌缩为零。4.3 四种变更结果与失败关闭apply通过CasApplyS, T选择四种类型化变更结果cas.rsCasApply::new(snapshot, outcome)——正常写回当快照与apply收到的一致时走PartialEq快速路径跳过写盘CasApply::no_op(snapshot, outcome)——无条件跳过写入用于当前记录为None且不应创建空/默认记录的场景CasApply::delete(snapshot, outcome)——按刚读到的版本条件删除删除成功后还会再读一次并重跑apply以验证调用方后置条件在 delete recreate 的 ABA 周期下依然成立CasApply::force_write(snapshot, outcome)——只绕过解码快照的相等性快速路径仍然走相同的有界、能力门控的 CAS 重试用于修复Entry侧车sidecar如索引投影元数据的场景。失败模式由CasUpdateErrorE承载cas.rs调用方apply的错误以Apply(E)原样透传不二次包裹Timeout、RetriesExhausted、CasUnsupported与Backend(FilesystemError)由调用方用一个map_err闭包统一映射进自己的错误枚举。失败关闭fail-closed能力门控是cas_update的底线它绝不在非 CAS 后端上退化为盲写CasExpectation::Any。门控分两层预检pre-flight若后端声明了已知能力形态且不含TxnCapability::Cas或更丰富直接返回CasUnsupported——这能在字节型挂载如仅支持字节读写的DiskFilesystem误配时于写操作前就拦住操作时op-time能力形态为空/未知即组合路由器时延后到写操作把FilesystemError::Unsupported映射为同一个CasUnsupported。无论哪层结果都是拒绝而非无条件变更。所有生产存储挂载都解析到支持 CAS 的数据库/内存后端因此失败关闭是正确且安全的默认。4.4 并发验证CAS 风暴测试规则冲突、重试耗尽、重启、部分失败行为必须在公开领域操作接缝测试在 tests/concurrent_cas_storm.rs 中有直接落地多线程 tokio 运行时上每轮tokio::spawn16 个写者、重复 100 轮全部并发对同一个快照路径做cas_update自增——每个cas_update必须成功捕获后端错误缺陷且最终计数必须等于WRITERS * ITERATIONS1600捕获丢失更新缺陷。该测试同时覆盖 in-memory、libSQL 与 PostgreSQL 三种后端libSQL 变体是 #5466 的回归钉此前每次操作新建连接策略在 C 库内间歇性失败、而被否决的单共享连接设计又会把 CAS 影响行数读回损坏成丢失更新Postgres 变体用每次运行唯一的 UUID 前缀隔离共享数据库且在后端不可达时优雅跳过。配套的run_delete_storm进一步压测delete_if_version本身的并发每轮重建共享路径到已知版本16 个任务以精确版本竞争条件删除断言每轮恰好一个赢家、其余全部观察到格式良好的NotFound绝无丢失或重复删除。五、多后端一致性行为一致而非仅 schema 一致当某个领域显式支持多个持久化后端时规则要求对排序、唯一性、时间戳、索引、事务、错误分类保持行为一致并且把对抗性adversarial一致性用例放进共享的一致性套件shared conformance suite而不是为每个实现复制一份测试。规则文档明确强调Parity is behavioral, not merely schema-shaped.即一致性是行为层面的不是表结构层面的。需要对比的点包括唯一性与索引、时间戳精度与排序、JSON/枚举序列化、事务回滚、并发写者结果、种子/默认记录、迁移回放、错误分类。修复某个实现时要同时搜索它的同类实现与共享一致性套件中相同的模式。从源码结构看ironclaw_filesystem正是通过让全部后端实现同一个RootFilesystemtrait 来支撑这一要求的DiskFilesystem、PostgresRootFilesystem、LibSqlRootFilesystem、InMemoryBackend、HsmBackend都是该 trait 的实现可用rg -n impl RootFilesystem for crates/substrates/ironclaw_filesystem/src/复现契约测试与 CAS 风暴测试直接以同一份测试体驱动多个后端天然构成共享一致性套件。能力由BackendCapabilities/Capability/TxnCapability在挂载前声明src/types.rs挂载时校验拒绝无法满足消费方声明的后端见 catalog.rs 的mount_dyn运行期Unsupported只是兜底信号而非主要信号。后端选择确实发生在组合层例如 production_backend_assembly.rs 中libSQL 路径用LibSqlRootFilesystem::from_runtime装配、Postgres 路径用PostgresRootFilesystem::new装配领域存储只依赖类型化包装不感知具体后端。数据库 schema 演进则集中由 migrations/ 目录管理V1 到 V34覆盖 wasm 版本化、用户身份、根文件系统条目与索引、工具作用域等主题这与规则中迁移回放属于一致性对比点相互印证。六、数据安全模型输出与用户数据绝不静默丢弃最后一条规则划定不可逾越的数据安全底线绝不静默丢弃模型输出、审计事件、对话记录transcripts或用户数据破坏性操作需要显式的产品契约product contract、授权authorization与作用域隔离测试存储错误在返回给边界时必须脱敏sanitized boundary error同时保留服务端原因以便排障——这与 src/types.rs 中Display 输出刻意使用作用域/虚拟路径而非原始宿主路径保护主机路径机密性的约定一致缓存淘汰不等于持久删除缓存未命中必须能从属主存储重新加载任何保留/删除功能都需要显式的租户/用户作用域、可审计证据、重启安全行为以及证明无关记录存活的测试。七、落地清单与验证手段把规则文档落到实际工作可总结为一张检查清单定位 owner先读 crates/AGENTS.md 与领域契约再动手不建新 trait一个RootFilesystem足够特殊情况优先考虑拓宽Entry或扩展 trait而不是另立门户读改写一律cas_update有界重试32 次、总超时15s、抖动退避2ms 起、50ms 封顶、失败关闭能力门控绝不复制本地重试循环、绝不加 per-record mutex历史遗留的本地循环见 CONTRACT.md 的迁移追踪不是可模仿的先例多语句不变量用后端事务顺序 await 不构成原子性同时有 Postgres 与 libSQL 实现时用共享一致性套件验证相同的提交/回滚与并发行为索引投影是唯一可查询面后端绝不解析Entry::body来求值过滤器一切可查询内容都在Entry::indexed请求路径使用query_ordered 声明的精确/前缀索引 keyset 游标且容量/能力挂载时校验补测试在公开领域操作接缝补契约测试可借助 fault.rs 的FaultInjecting装饰器让真实存储走故障路径涉及挂载选择/重启/跨域时补生产组合测试验证命令cargo test -p ironclaw_filesystem跑完整 crate 测试rg -n impl RootFilesystem for crates/substrates/ironclaw_filesystem/src/复核后端清单。遵循这套规则新增的持久化能力就会自然获得多进程安全的原子性、跨后端的行为一致性与可审计的数据安全而这正是 IronClaw 以隐私和安全为核心的设计哲学在存储层最直接的体现。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐AgentView 存储规则全解SQLite 归档、DuckDB 镜像与多后端一致性设计AgentView 存储规则全解SQLite 归档、DuckDB 镜像与多后端一致性设计 AgentView 是一个本地优先local first的编码AI 应用数据分析数据可视化可观测性Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约 导读 本文是 Agent Storage Spec https://link.gi后端微服务配置中心服务注册发现云原生Slang 内存一致性模型实战指南数据竞争、原子操作、内存屏障与多后端验证Slang 内存一致性模型实战指南数据竞争、原子操作、内存屏障与多后端验证 导读 本文以 Slang 语言参考文档 https://link.gitcode.编译器图形学编程语言创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考