tako 文档 GitHub

文件写入竞争:短写入互斥、版本校验、原子替换与长任务隔离

性质:部分落地(2026-11-10,短写入三件套已落地;长任务隔离由 doc/74 承担,已落地 2026-11-12) 状态:短写入的互斥、版本校验与原子替换已按本稿 §4.3 落地并验收;§6 只保留长任务隔离的动机与方向,具体施工设计由 doc/74 承担。 日期:2026-11-09;落地回填:2026-11-10;doc/74 指针补记:2026-11-11 代码落点:互斥 = filelock.go(PG advisory lock,多副本裁决);写入依据 = filefp.go(读取基准 + 指纹比对);原子替换 = atomicfile.go(同目录 .tako-tmp-* 临时文件 + rename,write_file / edit_file / move_file 之后的 Markdown 记忆文件与迁移搬运共用);调用面 filetools.go。 验收:存储侧 atomicfile_test.go(失败路径目标字节不变、临时文件清理、软链写穿、0644)与 filefp_test.go;活体 scripts/acceptance/memory_file_race.sh(两台隔离引擎共连同一 PG/共享 workspace:flock 串行、写前版本拒绝、原子读、kill -9 释放,11/11 通过)。 关系:doc/61 解释当前已落地的存储层互斥;本文补普通文件写入的完整边界。记忆文件的特殊写入由 doc/65 §5 消费本文原则;多 Agent 长任务编排以 doc/70 为执行底座,通用工作区隔离、不可变结果交接与发布恢复由 doc/74 专项设计;Git 只是其中一种 Provider。

0. 一句话

同一份文件有多个写者时,最终只有三条根本路径:

  1. 串行写入:同一路径的短写入临界区排队;
  2. 隔离后合并:长任务各写自己的 worktree/副本,最后显式合并;
  3. 协同编辑算法:CRDT/OT 让多份操作持续收敛,适合实时协同文本,不自动解决代码语义。

哈希、revision、互斥锁和原子 rename 不是互相替代的四种答案。它们分别防止不同事故,必须讲清谁服务哪一段。

1. 先演一场只有锁也会输的戏

文件最初是:

name=alpha
port=5432
  1. 会话 A 读取该版本,准备整篇重写端口,模型据此生成 name=alpha + port=5433,尚未写盘。
  2. 会话 B 先把名字改成 name=beta,写盘成功。
  3. A 随后拿到文件锁,把自己基于旧版生成的整份内容写进去。

A 的结果变成 name=alpha + port=5433,B 的名字修改被抹掉。锁确实保证了两个写盘动作没有重叠,却没有回答「A 的写入依据是否已经过期」。

所以:

少了第一项,检查与写入之间会插入别人;少了第二项,旧理解会覆盖新版本;少了第三项,不加锁的读者可能看到半截内容。

2. 当前 tako 代码事实

机制 当前真实行为 不能据此宣称什么
fileBaseline run 内按 agent + 绝对路径记录读取指纹;写后刷新 不是跨 run、跨进程或跨机器锁
指纹 ≤64MB 以 SHA256 判断内容是否同版;大文件退化为 mtime + size 弱判据可能漏掉同大小且保留 mtime 的变化
write_file flock 内在写前比较当前指纹;未读、已变化或读后被删会拒绝 不只靠锁就能防旧版整份覆盖
edit_file flock 内现读,按 old_text 精确匹配,0 处/多处默认拒绝;不查整份基准表 只能发现内容锚点失配,不能理解业务语义冲突
锁文件 使用独立锁文件与固定桶,不锁会被删除/rename 的目标 inode 不同路径可能撞桶而多等,但不会因此失去互斥
最终写盘 已走原子替换(atomicfile.go,2026-11-10):同目录临时文件写完整内容 → rename 覆盖目标 原子替换不防「最后写者覆盖」——防那个靠锁 + 写前指纹比对(上面两行)
bash 任意命令可以绕开文件工具锁 文件工具声明路径不能证明 bash 不写别处

现行实现分别见 filefp.go 的 Fingerprint、fileBaseline、lockPaths,filelock.go(PG advisory lock),atomicfile.go(原子替换),以及 filetools.go 的 newWriteFileTool / newEditFileTool。§6 的长任务隔离未施工,仍按本稿原样作方向。

3. 为什么 write_file、edit_file 和 Memory 不该共用一套借口

3.1 整文件覆盖:write_file

模型给程序的是完整新文件。程序无法分辨哪些字节是故意修改、哪些是从旧版照抄,因此需要:

读取时记录整份指纹
→ 模型在锁外生成完整内容
→ 写入前拿锁并重新计算当前指纹
→ 一致才覆盖;不一致则重读、合并、重新生成

这相当于文件系统中的 expectedRevision。它不是为了把 map 全局化,而是为了让当前 agent 证明「我读过,而且依据仍有效」。

3.2 局部修改:edit_file

模型只给 old_text 与 new_text。程序在锁内读取最新内容并应用修改:

old_text 是操作的内容前提,因此不必再查整文件基准表。它仍然是整份文件写回,只是最终结果在锁内根据最新内容计算。

3.3 条目式 Memory

Hermes 的 MEMORY.md / USER.md 使用 add/replace/remove/batch:锁内重读条目、定位目标、校验预算、原子替换。它同样是「锁内根据最新状态执行操作」,所以不需要额外的文件指纹 map。

doc/65 的 markdown 模式沿用这条,而不是把通用 write_file 的基准表硬搬过去。详见 doc/65 §5。

4. 原子 rename 与锁各负责什么

4.1 没有写锁,只有原子 rename

两个写者分别写自己的临时文件,再先后 rename:

4.2 有写锁,但直接截断目标写入

合作写者会排队,但不参加锁的读者可能在写入中途读取目标,看到空文件或部分内容。

4.3 推荐的短写入临界区

模型生成内容或修改意图(不持锁)
→ 取得稳定锁文件/数据库锁
→ 重新读取当前文件;write_file 校验整份指纹,edit/memory 应用操作
→ 在目标同目录创建唯一临时文件并写完整内容
→ 关闭临时文件;需要崩溃持久性时再明确 fsync 策略
→ 原子 rename 替换目标
→ 刷新本 agent 的读取基准、清理临时文件
→ 释放锁

结果:

fsync 服务崩溃后的持久性,不是原子可见性的来源;临时文件必须与目标在同一文件系统,否则 rename 可能退化为复制或失败。

锁要锁独立且稳定的存在,不能锁将被 rename 替换的目标 inode。当前 tako 使用独立锁文件,这一点保留。

5. 多副本与「锁住不释放」

5.1 短临界区可以持锁,整场 run 不应持锁

锁内只放读取、校验、修改和落盘,不放 LLM 思考、网络搜索或长时间测试。否则一个慢 agent 会把同文件其他工作全部堵住。

锁还需要崩溃释放与等待上限:

5.2 锁的粒度

PG advisory lock 只提供多副本协调,不会把多次文件写入变成一个数据库事务。跨文件全部成功/全部失败不能靠它承诺;需要这种语义时,应使用版本化副本和一次 Git 提交/合并,而不是继续堆锁。

5.3 非合作写者仍是边界

bash、外部编辑器、其他服务可能不取锁。可选处理只有:

不能因为在文件工具里加了锁,就宣称整个 workspace 已无并发写风险。

6. 长任务:优先隔离与合并,不引入 CRDT

Kimi 普通工具的 ToolScheduler 按 ToolAccesses 让同路径读写冲突排队;但调度器在一次工具批次内创建,不是跨机器队列。

其 Tower 模式则给每个 mission 独立 Git worktree,worker 只能写自己的副本;范围重叠的任务建立依赖,合并串行,冲突交回 worker 解决。这比让长任务一直持有文件锁更适合 coding agent。

对 tako:

CRDT/OT 留到真正的多人实时协同编辑需求。它们不自动理解代码或方案语义,不是这次文件竞争的默认答案。

7. 参考实现核查

实现 已核实的机制 对 tako 的边界
Kimi toolContract / toolScheduler 声明 read/write/readwrite/all;路径重叠且至少一方写就排队,纯读可并行 当前调度器按工具批次创建,不是分布式锁
Kimi Tower 每 mission 独立 worktree;写越界拒绝;scope 重叠建立依赖;rebase/merge 处理冲突 长任务隔离的参照,不是普通文件锁的替代品
Hermes FileStateRegistry 同进程跨 subagent 的 per-path 锁、读取记录、last-writer 与过期覆盖拒绝 普通文件协调主要是进程内,不是多副本证明
Hermes 文件工具 整文件写入有完整读取基准与 SHA256;patch 多路径排序取锁;底层临时文件 + 原子替换 与本文短写入方向一致;外部写者仍是边界
Hermes Memory 独立 flock、锁内重读、条目操作、原子替换;subagent 默认无 memory 工具 条目式 Memory 不需要通用 write_file 的指纹 map
Rakazo PG 文档以 expectedRevision + Serializable 事务防覆盖,并保存修订 适合正文在 PG 的文档,不直接解决磁盘文件与 PG 的跨存储原子性

本地核查位置:ref-agent/kimi-code/packages/agent-core-v2/ 的 tool/toolContract.ts、agent/toolExecutor/、features/tower/;ref-agent/hermes-agent/tools/ 的 file_state.py、file_tools.py、file_operations.py、memory_tool_store.py;ref-agent/rakazo/packages/memory/src/index.ts。

8. 活体与回归验收

正式施工前仍需另写 todos 交审。验收至少覆盖:

  1. 两个并发 run 基于同一版本整篇重写:先写者成功,后写者因版本过期被拒绝;重新读取后合并成功。
  2. 两个局部编辑修改不同位置:后一次读取带上前一次结果;修改同一旧锚点时后者明确失败。
  3. 写入期间持续读文件:只能看到完整旧版或新版,不能出现空文件、半截行或混合版本。
  4. 写者 kill -9:锁按所用机制释放,临时文件不冒充目标;另一写者可在等待上限后重试,不发生旧持有者复活覆盖。
  5. 两个引擎副本共写同一路径:多副本锁真实生效;不同路径/项目仍能并行。
  6. 多文件 patch 以相反顺序提交:不死锁;若中途失败,不把它描述成跨文件事务。
  7. bash/外部编辑器绕锁的负路径单独记录,不能用合作写者测试假装覆盖。
  8. 长任务的完整活体验收归 doc/74:Git 项目与同组 worktree、非 Git 项目与独立目录副本都要验证并行执行、不可变结果交接、冲突处理、最终发布和崩溃恢复;不能只验 Git 一条路径。

断言以真实文件字节、错误返回、锁等待与进程状态为准,不以模型说「已经安全写入」作为证据。

9. 所以这解决了什么

本文把普通文件竞争拆成三条互不冒充的保证:**写者短临界区互斥、写入依据仍然新鲜、读者只见完整文件。**普通共享写入用锁 + 版本校验 + 原子替换,多副本把协调放到所有副本共享的 PG;长任务不靠整场持锁,通用工作区隔离、结果交接与发布恢复见 doc/74(已落地 2026-11-12);Memory 使用条目操作,不背通用整文件基准表;bash 与外部写者的边界明说,不假装一把锁覆盖所有入口。