Android 本地 AI 的 JSON Patch 提案复核与原子提交

直接回答

JSON Patch 文档是按顺序应用到目标 JSON 文档的一组操作。RFC 6902 定义 add、remove、replace、move、copy 和 test；操作按数组顺序执行，前一步结果成为后一步输入。因此模型生成的 patch 是一项提议状态变化，不是按字段名合并的普通部分对象。必须把它视为不可信输入，校验操作集合、path 策略、值和基础版本；应用接受完整结果前，源记录应保持不变。 JSON Pointer 有自己的转义合同：reference token 中的斜线写成 ~1，波浪号写成 ~0。求值时先解码 ~1 再解码 ~0，避免把 ~01 错误转换为斜线。空 pointer 指向整个目标文档；路径还按当前结构求值，数组插入或删除会移动后续索引。数组目标中的短横线表示 add 语义的追加位置；copy 和 move 的目标也按 add 语义处理，因此应分别测试目标规则。它不是通用已有数组索引。不能把 path 字符串转成 Java/Kotlin 属性反射；应限制到 schema 的 allowlist 指针，并逐段验证。 test 操作会依据 RFC 6902 的类型和值相等规则，对比目标路径当前值和 patch 给定值：JSON 类型必须匹配，数字按数值比较，字符串按字符码点比较，数组和对象按内容递归比较。它可作为内容前置条件，却不是授权、持久版本号或用户确认。如果 test 与保存之间发生新编辑，除非 owner 在提交时重新核对版本，否则仍可能覆盖新状态。应携带源文档基础 revision 或 digest，并在批准结果的同一事务中再次比较。 不要假设任意 JSON Patch library 都会原子修改。RFC 6902 规定操作失败时应终止求值，且该 patch 不能被视为成功；它另外指出 HTTP PATCH 在 RFC 5789 下具有原子性。这个 HTTP 规则不会自动应用到本地可变对象、Android data class 或多次数据库写入。应对隔离的深拷贝或不可变文档应用 patch，校验最终 schema 和领域规则，生成差异供用户审阅，然后仅在 owner 仍持有基础版本时整体替换记录。任何 test、路径、操作或提交检查失败，都丢弃候选并保证不产生部分持久化。 按具体功能限制操作集。笔记编辑可能只需要 replace/add 和 test，不需要 move、copy 或替换根对象。设置提案可以只改指定叶子字段和枚举值；尝试修改身份、权限、账户 ID、存储路径或未知字段时，应在求值前拒绝。数组 add/remove 会移动后续索引，move 的 from 不能是 path 的父级。不要声称所有 RFC 合法 patch 都能作为产品变更；schema 和应用授权范围比 patch 格式窄得多。 分别限制操作数量、来源大小、path 长度、值大小、数组索引、嵌套与求值时间。候选状态、已批准状态和用户原始记录必须分开。界面应展示易读的前后差异，包括删除文本和敏感字段，再请求确认重要修改。模型信心、test 成功或语法有效都不代表用户同意。默认只记录隐私安全的提案 ID、基础版本、通过验证的操作类别、用户决策和提交版本，不记录原始私人值。 每个操作都必须有 op 和 path；add、replace、test 还必须有 value；move、copy 还必须有 from。格式必需成员与产品只开放部分操作的策略不同，也要遵循按操作适用的成员规则。使用精确 adapter 和存储事务做夹具：包含斜线/波浪号的 pointer 键、~01、数组插入/删除位移、add/copy/move 目标中的短横线追加、缺失 from 路径、move 到子路径、test 的类型差异、数值比较、null、未知 op、重复 JSON 对象键及中途操作失败。还要模拟预览后源记录被其他操作更新；此时必须出现版本冲突而非静默重基。失败后同时检查候选值和原文未变。patch 格式不能证明模型提议正确，也不能证明所有存储层事务语义相同。 本文是本地结构化编辑方法，不是 Cove 功能声明。它不能证明 Cove 将记录保存为 JSON、提供 patch 编辑能力或支持特定 Room 事务。如果应用确实将 JSON 文档存入 Room，应使用其 owner 数据库与事务合同；若数据存为普通列，应将用户复核后的提议映射到有类型的应用层，而不是盲目改写序列化状态。源历史、生成建议、已批准变更和 schema migration 应保持为不同记录。

本地模型建议修改已保存资料中的一个字段

离线助手读取用户批准的 JSON 资料，并建议修改显示名称，同时保留其他字段。模型读取后可能已有旧屏幕修改同一行；模型还可能额外返回一个修改私人标识符的操作。

决策

校验窄操作集与 pointer allowlist，在准确源版本的副本上应用，展示前后差异，并在用户确认后通过 owner 版本检查原子提交。

预期结果

资料要么作为一个经过复核的新版本完整更新，要么保持不变并显示冲突；不会推断部分 patch 或模型具有授权。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• ANDROID-JSON-PATCH-APPLICATION-2026-10：RFC 6902 定义有序 patch 操作及失败语义；HTTP PATCH 的原子性不自动保证本地记录事务。
• RAG-01：本地 AI 数据流程的摄取、索引和提示构建应分别验证；该事实不定义 JSON Patch 的原子性。
• ANDROID-PRIVACY-01：用户记录的访问、存储与控制由应用负责；该事实不授予 patch 操作权限。

任务质量需要有版本记录的语料和验收规则；流畅的单条样例不等于准确度结果。

实施流程

1. 定义可编辑文档和操作集. 选择有类型文档 schema、批准的 pointer 路径、允许操作、值限制及绝不可修改的字段。空 pointer 指向整个文档；除非明确需要并充分测试，不开放根替换、move、copy 或 remove。
2. 解析并验证 patch 语法. 要求每个操作只有有效 op/path；验证 RFC 6901 转义与 from 路径。变更前限制操作数、路径长度、值大小、嵌套、数组索引和求值工作。
3. 对隔离的源版本应用操作. 加载当前源记录和稳定版本，在深拷贝上按序应用操作，依据当前值执行 test，再按 schema 与领域规则校验完整候选。
4. 预览并取得用户批准. 针对确切源记录展示前后差异和变更字段摘要。test 只是内容前置条件，不授权保存，也不能替代用户确认。
5. 通过冲突检测提交. 在记录 owner 事务中将当前版本与提案基础版本比较，并原子保存整个候选。若版本不符或任一操作失败，丢弃副本并保持源记录不变。

让每个阶段的状态都可观察。失败信息应指出阶段、模型、运行时和恢复动作，同时避免记录用户私密内容。

验收标准

• 应用使用版本固定的 RFC 6902/6901 实现或经测试子集，并明确操作集合和 pointer 路径策略。
• patch 只作用于隔离副本；任何失败操作都不能部分改变 owner 源记录。
• 提交时在同一 owner 原子事务内比较基础 revision；并发编辑产生冲突，不静默重基。
• 持久化前显示差异并取得用户批准；test 操作和语法有效不能替代授权。

决策对照表

需要避免的失败模式

• 将模型返回的 op/path 直接反射到任意对象或数据库列。
• 误解 JSON Pointer 的 ~0/~1 编码，或把数组索引当稳定对象 ID。
• 把 RFC 6902 的失败语义或 HTTP PATCH 原子性外推为任意本地内存修改的回滚保证。
• 把 test 通过、JSON 有效或模型信心当作用户授权或并发版本检查。

还要避免静默回退、版本未固定、缺少取消处理，以及把不同配置的结果混在一起下结论。失败运行也应与成功记录一并保存。

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• Android privacy and security
• IETF — RFC 6902 JSON Patch 操作与错误处理
• IETF — RFC 6901 JSON Pointer 转义与求值
• AndroidX Room — Transaction API
• IETF — RFC 5789 HTTP PATCH 原子性

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题