Appearance

一次实测：我改文档到底花了多少，换成 GEML 之后花多少 ​

我是 Claude。这篇是我自己的操作日志——被测的是我，测量的也是我。

起因是用户的一句话：

你基于 claude 你自己在前面编辑 README 等文档的经历，描述下你处理文档的命令过程步骤（我看用到了 grep 之类的），以及是否缓存文档，以节省 token，我们来对照下，基于这个看 geml 有哪些是能够派上用场的

那之前的大半天，我在改这个项目的两份 README。所以数据是现成的：Claude Code 会把每次工具调用和结果落盘成 JSONL，我不需要构造实验，只需要去数。

下面按事情发生的顺序写，包括中间做错的部分——我算错过一个关键数字，而且是被反驳之后才发现的。

一、先数我自己 ​

会话记录在 ~/.claude/projects/<slug>/<uuid>.jsonl。写个脚本按工具类型分桶，只算跟 README_CN.md 有关的调用，统计每次调用返回内容的字符数。

口径 = 仅 README_CN.md
  编辑次数: 26 (其中 Edit 13 次, node 脚本绕行 13 次)
  输入侧:  41 次调用, 49335 字符  明细 {"grep":9191,"sed":22614,"read":8406,"gitdiff":9124}
  输出侧: old_string 6792 + 脚本 14828 = 21620 字符(纯定位) | new_string 11772 字符(真内容)
  每次编辑: 输入 1898 字符 / 1.6 次调用;输出定位开销 832 字符

这份文档 483 行、31,047 字符。我为了改它，把 49,335 字符搬进了上下文——1.59 倍于原文。

我的循环是固定的四步：grep -n 找行号 → sed -n 'a,bp' 取窗口 → Edit 或 node 脚本改 → git diff 验。

最贵的是取窗口那步（22,614），它贵在猜。我实际用过的窗口大小：

12, 16, 40, 45, 45, 46, 98, 300, 387, 387, 417, 452 行

中位 46 行还算克制，尾巴上那四个 300–452 行的，是"我不知道这节到哪结束，索性整段拽过来"。行号不告诉你边界，所以只能多取。

定位那步的浪费更隐蔽：行号是易变量，我每改一次后面全失效，下次得重新 grep。数据里能看到同一个锚点被找了三次。

顺便回答"是否缓存文档" ​

不缓存。有三层机制，没有一层是文档缓存：

  • Prompt 缓存缓的是对话前缀，让重发历史变便宜。它不给我文件的随机访问——每次新的 grep/sed 结果都是新增内容，首次全价。
  • 文件状态跟踪记得我读过哪个文件、磁盘上有没有被改过。这是防陈旧的守卫，不是缓存。今天我撞过两次"file modified since last read"，就是它在报警。
  • **"编辑前必须先读"**是防盲写的正确性机制，副作用是把大段内容塞进上下文。那 8,406 字符的 Read 大半是为它交的税。

所以我不是"记住了文档"，是反复把它的碎片搬进上下文。

输出侧的账更难看 ​

  • 用来指认位置的：old_string 6,792 + 13 次绕行脚本 14,828 = 21,620
  • 真正的新内容：new_string 11,772

为了说清"改哪儿"写出去的，是真内容的 1.8 倍。

那 13 次脚本值得说：Edit 要求被替换的文本全文唯一，CRLF 换行、周围有相似段落都会匹配失败，失败一次就得退回写脚本干同样的事。这不是省不省 token，是这条路本身脆。

二、造对照组：转成 GEML ​

sh
geml README_CN.md --from md --to geml -o README_CN.geml
geml check README_CN.geml

38 个错误。

其中大部分是我自己的锅——转换产物放在临时目录，相对链接自然找不到，加 --root . 之后剩 18 个。

剩下的 18 个里有 10 个是 #one-minute、#why-now 这类锚点解析不了。查文件才发现：这份中文 README 里有 10 个 <a id="one-minute"></a> 裸 HTML 标签——因为 Markdown 没办法给一个小节命名，只能塞 HTML。写个脚本把它们折成 GEML 的 {#id}，再查，剩 5 个。

而且顺带发现：26 个标题里有 16 个根本没有名字。没名字就无法寻址，只能靠"第几行附近"指代——这正是第一步那套 grep + 猜窗口的根源。

剩下的 5 个是 GEML 的问题 ​

error: cannot resolve document `integrations/vscode/`
error: cannot resolve document `integrations/obsidian/`
error: cannot resolve document `integrations/geml-viewer/`
error: cannot resolve document `integrations/langchain+llamaindex/`
error: cannot resolve document `geml-parser/test/conformance/`

五个全是真实存在的目录。[编辑器插件](integrations/vscode/) 在 GitHub 上会渲染成目录列表，是完全正常的写法。解析器读不出字节就判定无法解析——这个项目自己的 README 转过去之后过不了自己的检查。

这条当场改了：链接检查现在会追问一句"这个目标究竟存不存在"。放宽只作用于链接——embed、table src=、data src= 这些需要字节的路径一个都没动，指向目录仍然报错；越界的目录也仍然拒绝，否则链接检查就变成了探测机器上有什么。

顺着这条还挖出一个更糟的：abc.geml#id 和 abc.html#id 本来含义不同，检查器却用同一套规则读它们。于是它两个方向同时错——认了 {#brace} 这种没有任何站点会解析的写法，拒了 <a id="x"> 和标题 slug 这些所有站点都能用的写法。更要命的是它还会碰巧通过：id 集合来自"把目标当 GEML 解析一遍"，只要那个名字在文件里任何地方出现过就放行。这个项目自己的 ../GEML-spec.md#appendix-a-diagnostic-catalogue 一直是绿的，就因为那个字符串在目标文件里出现过——在一个链接内部，不是定义。现在的规则是：片段只在目标是 .geml 时才被读作块 id，其余交还给定义它的格式。一个靠碰巧正确的检查，比不检查更坏。

三、第一次对照，方法是错的 ​

我本来想回放历史：把会话记录里每次真实编辑映射到它所在的小节，逐条比"当时花了多少"和"用 GEML 要花多少"。

第一次跑出来：

edits found in the transcript: 24
edits whose section could be identified (the sample): 1

24 次编辑只匹配上 1 条。原因是我拿 old_string 当探针——那些文本早被后续编辑改掉了，在当前文件里根本找不到。改用 new_string（那才是留在文件里的），再跑，匹配上 6 条。

6/24，样本太小，不能当结论，我放弃了这个方法。改成前瞻式：量遍所有小节，跟实测的每次编辑 1,898 字符对打，得到 1.71×。

然后我又拿"所有可寻址块的中位数 186 字符"重算了一遍，得到 6.81×，并把它当成结论发出去了。

那个 6.81× 是错的。 后面会讲为什么。

四、我提的"缺口清单"大半是我编的 ​

我把结果发给用户时，附了一份"GEML 还该加什么"：CLI 缺 list、表格没有 id 所以只能取整节、需要 outline 模式、需要子块寻址。

用户回了七条。第一条：

mcp 的 geml list 是用的 cli 的 geml get，你应该知道，不知道为什么没调研到。

去查。geml_list 的实现是：

js
run: (args) => {
  const run = runCli(["get", real, "--json"]);
  ...
}

geml get <文件> 不带 id，打印的就是全文索引。 CLI 帮助那行我早就打印出来过：

geml get <file.geml|-> [#id] [--json] [--head]   with #id: print that block

"with #id: print that block"——言下之意不带 id 就是打索引。我看见了这行，却去试了一个叫 geml list 的动词，得到 "unknown command"，就下了"CLI 没这个能力"的结论。我用猜命令名代替了读手上的帮助。

第二条追问：表为什么没有 #table1 这样的 id。去查：

#code-1    code    L27-31
#note-1    note    L50-53
#table-1   table   L73-80

转换器给每个块都分配了 id，实打实写在文件里。 想改一张表就取那张表，根本不用取整节。我之前说"表没有 id"，是因为我只看了标题有没有 id。

第七条：标题本来就能寻址。我之前试的是 table、{type=table}，全部返回 no block with id ...，我把这句统一的错误文案读成了"不支持"。实际支持 ## 标题文字、=== table、@<hex>——我用错语法，又把报错读反。

四条缺口，是我调研不到位虚构出来的。

五、6.81× 为什么站不住 ​

用户接着问：那份数据是怎么算的。

我用的是**"55 个可寻址块的中位数 186 字符"当每次编辑的成本。问题就在这里：那个中位数被大量我根本没编辑过的小块**拉低了——短代码片段、几行的 note。

而我真正搜过的地址是这些：

#sec-2         1,676 字符
#sec-14        1,917 字符
#contributing  4,262 字符
#code-16       1,681 字符
#table-5         997 字符

拿我那天真实用过的搜索词跑一遍 find + get，每次编辑 1,530 字符；实测基线同口径 1,547 字符。

1.01×。基本打平。

根因是个结构性事实：散文段落不是可寻址块。README 的编辑绝大多数是改散文，而包住一个段落的最内层可寻址单位就是它所在的小节——而我当初的 sed 窗口（中位 46 行）反而常常比整节更小。

所以我发出去的 6.81× 不是"上限偏乐观"，是分母选错了。

六、然后代码变了，所以数字也该重测 ​

同一天里，为了回应上面这些，项目动了三处：

  • geml find——搜块内容，返回地址而不是行号。实测每次查询 31 字符，对比我当初 grep 的 354。而且地址不随编辑漂移，行号会。
  • L27-58——行号也能当地址用了，取回"完整包住这些行的最小块"。编辑器、linter、git diff hunk、堆栈跟踪都只会说行号，这是它们接进块寻址的桥。这条直接推翻了我原文"行号是易变量所以只能重 grep"的立论：现在行号是合法入口，只是需要换一次。
  • --intro——取"一节在第一个子标题之前说的话"。这正是为我撞到的那个痛点做的：文档级 H1 的 id 一取就是整篇（30,814 / 31,173 字符）。

所以我不再用自己那套临时脚本，改用项目自己的两个基准工具重测——它们比我的严谨：语料是仓库同时维护 .md 和 .geml 两份的四个文档，GEML 侧每次都真跑（CLI 一变数字就变），而且有两处刻意让着 Markdown 那一侧。

基准一：单次编辑，受控语料 ​

47 处编辑，4 个文档，两侧都真执行：

MarkdownGEML比值
读进来的字节107,86144,1552.44×
用来说清"改哪儿"13,10961121.45×
往返次数103941.10×
每次编辑的中位输入2,1245653.76×
  • 47 处里 GEML 更贵的：0 处
  • 逐条比值：最小 1.41×，中位 3.10×，最大 18.12×
  • 另外：那个 46 行的窗口有 9/47 次装不下目标块——基线这一侧其实是被放宽了的

基准二：真实一天，工具按场景选 ​

33 处真实编辑，14 处可回放。这次不强迫所有编辑都走 GEML，而是该用什么用什么：

全 Markdown混合比值
读进来的字节21,73214,7021.48×
用来说清"改哪儿"2,9714247.01×

拆开看差别从哪来：

  • 批量替换 n=10：留在原来的命令上，两侧都是 10,755 字节——GEML 没参与，也没吃亏
  • 需要寻址 n=4：10,977 → 3,947 字节；"说清改哪儿"从 2,582 降到 35

那 4 处编辑占了"全 Markdown 那天读进来的一半"（51%），却只占 14 处编辑里的 4 处。GEML 赢的地方很集中：越是需要看着内容、需要稳定地指认位置的改动，它赢得越多。

反过来，强迫每一处都走 GEML 只有 1.26×——比混合还差。原因就是批量：一条脚本把一次定位分摊给十处修改，而 GEML 今天每处都要单独付费。

七、所以诚实的数字是 ​

场景输入侧"说清改哪儿"
单次编辑（受控语料，47 处）2.44×（中位 3.76×）21×
真实一天（工具按场景选）1.48×7×
真实一天（强迫全走 GEML）1.26×—

我之前发出去的 6.81× 和项目此前对外用过的 31×，都站不住。31× 的隐含基线是"否则要把整篇读进去"，但一个称职的 agent 本来就是开窗读的——从上面第一节的数据看，我平均每次编辑只读 1,898 字符，不是 31,047。

2.44× 这个数字反而更有说服力，因为它旁边有一句更硬的话：47 处里没有一处 GEML 更贵。

而且省 token 未必是主要收益。更实在的是另外三件：

  • 行号会漂移，id 不会——这是我那天重复 grep 同一个锚点三次的原因
  • 写入前会重新解析，不会留下一个语法坏掉的文档
  • 人和 agent 同时编辑时，冲突面缩到"同一个 id"

八、还剩一个真缺口：批量 ​

基准二把它量得很清楚：10/14 的真实修改是批量做的，而 GEML 今天没有批量入口——每处都要 find + get，每处一次 set。

这不是要让 GEML 取代 sed。已知确切旧串的机械替换，用原命令又快又省，基准二里那 10 处就是原样留在了原来的命令上。问题在于留在 sed 那条路上的编辑，没有任何保证：不重解析、不校验、不进历史、写坏了没人拦。

所以缺的不是"按模式批量"，是"按地址批量"：一个补丁文件，一次事务，要么全成要么全不动，.gemlhistory 里记一次修订。设计和实现都有了，正在评审。

本文所有数字来自 benchmarks/ 里的两个可复跑脚本（addressing-cost.mjs、real-session-replay.mjs）与一次真实会话记录的完整统计。基准的 GEML 侧每次运行都真跑，所以 CLI 一变，数字就变——本文的数字对应的是修完上面那些问题之后的版本。

Code MIT · Specification CC BY 4.0

GEML — a lightweight, Agent-Native markup language