---
name: app-record-editor
description: 在 LessChaos App 中新增、更新、删除、批量整理或迁移业务记录，并处理并发冲突与跨 App 写入回执。用户要求实际改数据时使用；表字段结构调整由 app-schema-builder 处理，只读统计由 app-data-analysis 处理。
---

<!-- 本 Skill 拥有业务记录修改的范围确定、读改写和结果核对流程；原子提交、幂等和业务权限由正式 Command 拥有。 -->

# App 记录修改

把用户要求转换为明确的记录与字段变更，使用正式版本依据提交，并核对已提交、被拒绝和结果未知的操作。

下文 `app_*` 是工具用途名；从当前插件工具目录取得实际 Tool 定义。写操作沿宿主批准流程执行；用户已明确授权的范围内继续工作，只有目标歧义或需要扩大变更范围时才补问。

## 1. 确定目标和变更集

有 App Reference 时沿引用定位，没有身份时 `app_list` 查目录。读取 `app_definition`，将用户描述映射为稳定 Table、Field、选项和 Record ID。名称相同不能作为唯一匹配依据。

按条件批量修改时，先用 `app_query` 完整取得目标范围及版本，再确定每条记录的目标值。列出影响记录数、目标字段及新增／更新／删除类别。用户明确给出的选区是目标集合，不自动扩大到全表。

修改所需字段不存在时，由 `app-schema-builder` 处理用户已授权的结构变更；单纯录入任务不自行新建字段或同名 App。派生与系统字段使用正式可写字段间接驱动。

完成条件：每项变更都对应明确的目标记录、字段、旧值依据和期望值；新增记录使用已确定的业务去重键。

## 2. 读取依据并构造载荷

单条更新优先 `app_read_record`，请求变更所需字段和判断条件所需字段，使用返回的 `definitionVersion`、`datasetSequence`、`revision`。`app_update_record` 分别填入三个 expected 字段。

新增、删除、批量或单 App 跨表操作用 `app_command`。其 `expected` 来自查询的 `basis`；更新与删除还需各条 Record 的 `expectedRevision`。同一 Command 的所有表属于同一个 App。多次读取版本不同需重读受影响范围，不能随手选一个最大序列拼成依据。

普通字段值用类型标签封装，省略的字段不变、Null 显式清空，普通多值字段写入完整目标集合。关联字段使用 `app_command` 的 `link_patches` 元素补丁；金额使用精确十进制字符串，选项、人员、附件和关联使用真实身份。具体值形状、关联补丁、Command 与回执示例见 [记录写入模式](references/write-patterns.md)，构造载荷前读取适用段落。

为每个 Command 生成一次稳定 `commandId` 和 `operationGroupId`，保留提交载荷；创建记录可显式给定稳定 `recordId`。受输出或请求预算限制需拆批时，按用户可接受的业务边界分批，保留各批独立回执。

完成条件：载荷包含完整并发依据、合法值形状和稳定身份，未夹带任务以外的字段更新。

## 3. 提交并核对

读取正式 `committed` 或 `unchanged` 结果；`committed` 确认命令身份和数据集序列，`unchanged` 单独记为无需变化。收到工具响应不等于命令已经提交，拒绝和未知分别保留。

提交后重读目标字段，核对实际值是否达到用户要求。批量工作依据回执逐批确认，回读被拒绝时说明“提交已确认、回读未完成”，不把已确认提交改报为失败。金额或数量核对使用精确值，展示舍入不能当作相等依据。

完成条件：所有目标变更都有明确处置状态，已确认提交的部分完成适当回读或说明回读限制。

## 4. 跨 App 写入

先分别取得各目标 App 的定义和写入依据，明确操作依赖。每个 App 使用自己的 Command、版本和回执，不共享 revision 或数据集序列。某个前置来源不可用时，停止依赖它的后续操作。

跨 App 没有共同事务。用户要求全有或全无时，在写入前说明边界并让用户确定可接受的执行方式；未确定前可完成只读核对和变更方案。A 已成功、B 被拒绝时，保留 A 成功并报告 B；撤销 A 是新的业务动作，需要对应用户意图。

## 冲突与未知结果

| 观测                         | 下一步                                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| 确认未提交的版本冲突         | 重读定义、记录和判断条件；重算变更，作为新载荷使用新命令身份                             |
| 字段值或规则拒绝             | 根据明确原因修正；改变业务含义或范围时先取得用户决定                                     |
| 明确权限拒绝                 | 报告具体目标及拒绝，不替换操作者或换来源重试                                             |
| 超时、取消或 outcome unknown | 保留原命令与完全相同的载荷；只在当前范围仍有效时原样重试一次，仍未知就停止该依赖链并报告 |
| 账号或组织范围改变           | 停止旧范围的写入与重试，已发出的操作保留原范围及未知状态                                 |

回读值相同可以证明当前状态，不能单独证明哪一条未知 Command 提交成功。结果未知时不换 `commandId`、不刷新 expected 门后重放，也不盲目重跑整个跨 App 流程。

交付时按 App／批次列实际提交、无需变化、拒绝和未知项，给出返回的资源链接及尚需处理的目标。