文档/Markdown 写入会静默覆盖网页端的并发编辑（缺少冲突检测）

更新(2026-05-25,已实证):docs_ai 的 revision_id 服务端语义已用真实 API 验证,详见此评论。据此修正下文「根因」中 overwrite 的描述,并更新「改进方向」(原"服务端乐观锁"方案不可行)。

问题概述

当 AI agent 通过 lark-cli 创建/编辑文档时,如果用户同时在网页端编辑同一篇文档,agent 的下一次写入会在无任何冲突提示的情况下覆盖/串改用户的网页端修改。CLI 和 skill 都没有向 agent 暴露并发/协作信号,因此 agent 完全无法察觉有其他人改动过这篇文档。

根因

所有写入路径默认"作用于最新版本",且没有任何冲突检测——已实证:服务端对过期 revision_id 静默接受、直接 rebase 到最新(见评论 E2/E4)。

• docs +update 的 --revision-id 是隐藏参数,默认 -1(最新)——shortcuts/doc/docs_update_v2.go。create→fetch→edit 生命周期从不记录基准版本、写入前也不比对。且实证表明:即便把真实基准版本串进去也没用,服务端不会因版本过期而拒绝(revision_id 非 If-Match,仅校验"版本须存在")。
• docs_update_check.go(名字有误导性)其实是 Markdown 格式 linter,并不是并发检查。
• docs +fetch 输出只透出 document.content(docs_fetch_v2.go),丢弃了返回里本就带的 revision_id,也不暴露最后修改人/时间,agent 无从发现文档已被改动。
• --command overwrite(v2 / docs_ai):经实证,它走的是语义 diff/merge 而非清空重写——未匹配到的 section 会保留。所以并发改动落在不同区域时大概率被保住,但改同一段时仍会静默丢失,且全程无冲突信号。
• docs +update --mode overwrite(v1,已废弃) 与 markdown +overwrite:才是真正的无条件全量覆盖(v1 清空重写;markdown 直接整文件重传,不接受 base-version 前置条件 —— shortcuts/markdown/markdown_overwrite.go)。
• lark-doc skill 仅在风格层面提示"精准修改优于全量覆盖"(lark-doc-update-workflow.md),没有"写入前重新 fetch 并比对"的步骤。

影响

在人 + AI 协作编辑同一篇文档时丢失更新——而这正是本 CLI 主打的混合协作场景。

改进方向

已实证:docs_ai 服务端不提供冲突拒绝能力(过期 revision_id 静默接受),因此冲突检测只能放在客户端。

1. 服务端乐观锁:把基准 revision_id 串入 update,版本前进时由服务端返回 conflict。 不可行——实证表明服务端不会拒绝过期写入。
2. 客户端协作感知(主方向):fetch 输出透出 revision_id(并尽量补最后修改人/时间);记录 agent 读取时的基准版本,写入前 re-fetch,若 head 已前进则中止并提示用户而非盲写。服务端只提供可读的 revision_id,强制逻辑由客户端实现。
3. Markdown 路径:为 +overwrite 增加客户端 base-version 比对(同样,服务端无前置条件支持)。

Start by tracing docs +fetch and docs +update through docs_fetch_v2.go and shortcuts/doc/docs_update_v2.go, then inspect markdown +overwrite in shortcuts/markdown/markdown_overwrite.go. Review the linked evidence comment and the lark-doc-update-workflow.md guidance. Done should mean concurrent edits are detected client-side and surfaced before a conflicting write, with the relevant revision information exposed.