I built a demo app to find out how much of Bend’s power I could put to work inside a TypeScript application. The demo does one thing: it works out a bill from recorded usage. That decision lives in Bend 2 , where a law about every input replaces a test suite about the cases I happened to imagine. Everything else is ordinary TypeScript: the UI, the HTTP, the storage and the npm packages that wrap them. This post is the report from that demo: what the proved core cost, and what it gave back.

The bet that made me try it is one sentence:

The human says what “correct” means, an agent writes the code and the proofs, and the checker decides. Bend is the first tool I have seen that makes this division of labour work in everyday engineering.

人负责说清楚"什么是对的"，agent 写代码和证明，检查器负责判定。Bend 是我见过第一个能让这种分工在日常工程里实际跑起来的工具。

Everything below is what that cost and what it bought, in the order I met it.

The Line Is IO, Not Importance

The boundary between the two languages turned out to be IO, not how critical the code is. Everything pure can live in the proved core: data structures, algorithms, state machines, and every computation whose answer must be right. TypeScript keeps what touches the outside world: HTTP, files, time, the UI, and the npm packages that wrap them. The two meet in memory: the host calls the core as a function, through types generated from the Bend source.

So I started with billing. What makes it a good fit is not its importance but its shape: a pure decision whose answer must be right for every input, and a rule a person can write down as a law. Permissions, quotas, allocation, scheduling, merging and protocol state machines have that shape too, so a core can hold them the same way. A TypeScript type can say that a value is a number. It cannot say that a bill is the sum of its unit prices, or that a deny always wins. Only a law says that, and only a proof says it for every input.

Then the next pure function moves in, and the next. The first function pays for the bridge, the type generation and the gate. After that, each move costs little, and the rest of the application barely changes. Over time the core grows, and TypeScript thins to a shell around IO.

What a Proof Gives That a Test Does Not

Every input, not the examples I thought of. A test checks the cases its author imagined; a law is proved for every input. Bugs in decision logic tend to live in combinations nobody wrote a test for: a wildcard in an unusual position, an empty list, a boundary value, a requester with no roles. When I planted the same plausible bugs in a well-tested TypeScript function and in a proved core, the tests missed some of them and the proofs missed none of the ones the laws spoke about. The bugs the tests miss are the expensive kind.

The specification questions arrive before the code is written. Stating a law forces decisions a TypeScript implementation makes by accident:

• Does a window that ends at 12:00 touch one that starts at 12:00?
• Is a requester with no roles covered by a rule for “any role”?
• What does a plan charge past its last tier?

Without the law, the answer is whatever the implementation happens to do, and nobody knows that a choice was ever made.

Laws are a contract a person can review. A reviewer reads a dozen lines in plain language and knows what the core guarantees, without reading the code or the proofs, while the checker vouches that the code meets them. That is the part I did not expect to care about as much as I do.

Most of the Value Arrived Before the Proof

The steps before proving catch most of the problems:

• Reading the existing code to list what it must guarantee found bugs in it: edge cases it got wrong, inputs it silently mishandled.
• Drafting the laws turned up the decisions nobody had made.
• Falsifying the laws on concrete inputs found a wrong specification in under a second, before any proof existed. The checker runs code on literals, so a candidate law instantiated a few thousand times is a property test with the checker as the runner.

The proof comes last, and it is the cheap part. It turns “we checked many cases” into “it holds for all of them”, and it keeps holding when the code changes.

Designing for the Proof Made the Code Better

The shape of the code decides how hard the proofs are, so I looked for the shape with the shortest induction before writing anything. Repeatedly, that shape was also the better program:

• A step the proof does not need is often a step the program does not need. Rewriting an algorithm so that its correctness argument is one induction can remove an entire phase, such as a sort.
• Make invalid inputs unwritable. A representation in which a bad value cannot be expressed needs no precondition in the laws, no validation inside the core, and no case analysis in the proofs. TypeScript validates once, at the boundary, where the error message can still say what was wrong.

Sketching the proof belongs to the design, not to the paperwork after it. One of my laws was satisfied by a version of the code that did nothing at all: the law was true and useless, and only the sketch showed it.

What the Proofs Did Not Cover

• Proofs protect only what the laws state. A law written in terms of a helper says nothing about bugs inside that helper. If “a matching deny means no” uses the core’s own matches, a broken matches leaves the law true. Laws about the helper itself close the gap. Choosing the laws is the design work, and the proofs are comparatively cheap.
• Proofs cannot see run time. They say nothing about stack depth, time or memory. A function can be proved correct and still overflow the stack on realistic numbers, so test the core at real scale, with real magnitudes; small literal instances will not show it.
• The host is not proved. Conversions in the bridge, validation, IO and configuration are ordinary TypeScript and need ordinary tests. Keep that layer thin and check its conversions against a trusted reference.
• An unsafe definition proves anything. A def that skips the termination check can “prove” a false equation, and the checker still prints “All terms check”, with a warning buried beside it. A gate must reject that warning, not just look for the success line.

Making Sure the Proofs Mean Something

A proof that checks quickly may be saying nothing at all. Three habits kept mine honest:

1. Give every law a mutant. Change one line of the core so that the law becomes false, and require the proof to fail inside its own lemmas. Make sure the mutated core still compiles: a mutant that fails to compile is caught for the wrong reason.
2. Control the falsifier. Plant a bug and require a counterexample. Build the instances around the law’s hypotheses. Uniformly random inputs rarely satisfy them, and then the falsifier finds nothing even when the law is false.
3. Recognise equivalent mutants. A change that computes the same function, such as a < b ? a : b against a <= b ? a : b, survives every law, and that is correct. Compare the two functions before calling it a gap.

The Cost Is Tokens, Not People

Written by one agent in sequence, a proved core took several times longer than the same function with example tests. Most of that time went into deciding what the laws should say and shaping the data, not into the proofs. The proofs usually checked on the first or second attempt: Bend’s checker answers in well under a second, and each error names the next goal.

That cost falls to agents, and it parallelises. Several agents can attack the same law with different strategies: which argument to induct on, which lemma to state. The first proof that checks is kept. The checker is the judge, so no agent’s work needs to be trusted or reviewed. The cost is tokens, and tokens are cheap.

The one cost that does not parallelise is the human’s: deciding what “correct” means. Keep the laws short and readable enough that a person can approve a dozen of them in minutes, because as more code moves into cores, reviewing laws becomes the main human work.

The Ecosystem Is a Matter of Time

Bend is young and its library ecosystem is small, which is a question of time rather than a limit on what belongs in Bend. Those libraries will be written by agents, and they will be proved. A proved library has a property no ordinary package has: its theorems hold for every input, so it does not break when it is used somewhere new. Facts accumulate too. A lemma about ordering, proved once for one project, is reused unchanged by the next. One of mine pulls in bend-mathlib as a submodule; the few facts it lacks live in the project that needs them. Each proof makes the next one cheaper.

Today, expect to work around a few things:

• There is no official library output. I wrote bend-emit for that ( https://github.com/nohzafk/bend-emit ): it builds a typed ES module from a core.
• Editor support lags the compiler.
• The JavaScript runtime is single-threaded with BigInt numbers, and some standard-library functions that are easy to prove things about are slow at run time. Test at real scale.
• Rules of the language are still being relaxed release by release.

Where to Look

That bet held up: the human says what “correct” means, agents draft the code and find the proofs in parallel, and the checker decides. Once the boundary is drawn at IO, formal verification stops being an academic exercise and becomes everyday engineering.

The method for running that loop is packaged as an agent skill, bend-ldd ( https://github.com/nohzafk/bend-ldd ): where a proved core belongs in an application, how to find the laws, and which tool to reach for when a proof will not check.

Bend 2 is a new programming language. Its syntax is Python-shaped, its semantics are closer to Haskell, and it sets out to combine three things that rarely sit together: proofs checked at compile time, C-like speed, and parallelism across CPU threads and GPUs from a single source. The language’s own guide states the ambition plainly — to give people “an ambiguity-free language to communicate their intents to AIs”, with a compiler that can mechanically check the result. That is the bet, and it does not live in the syntax. I wrote a short book about Bend 2 while learning it — Bend 2, from zero, at https://nohzafk.github.io/bend2-from-zero/ — where every claim comes with code you can run; this post is the one idea from it I keep coming back to.

One claim of mine stood out above everything else — I wrote it down before I understood what it meant:

Affinity is the first key to understanding everything in Bend.

It reads like a slogan, and slogans are cheap. So rather than read Bend top-down, I decided to learn what affinity actually is and then read Bend through it. I installed Bend 2.0.5 and ran nine small programs to find out what the rule really enforces.

It survives. Affinity is not a feature of Bend; it is the mechanism the rest of Bend is derived from. The three things Bend sells are:

• no garbage collector
• parallelism without locks
• proofs that cost nothing at runtime

They are not three pieces of engineering. They are three consequences of one rule about who owns a value.

But the interesting part is what the rule costs, and where it diverges from Rust, which is where most programmers will have met the word “affine” before.

Where the word comes from

“Affine” is not a Bend coinage. It comes from logic, specifically from asking what you are allowed to do with an assumption once you have it.

In a proof, an assumption (a variable) can be treated in three ways, called the structural rules:

Ordinary programming languages allow all three, which is why you never think about them. In 1987 Girard removed all three and got linear logic, where every assumption is used exactly once. The family is now called substructural type systems — the standard reference is David Walker’s chapter of that name in Advanced Topics in Types and Programming Languages (MIT Press, 2005).

Then people started putting rules back one at a time, and each combination got a name:

exactly once   linear
at most once   affine       ← Bend is here, and so is Rust
at least once  relevant
any number     unrestricted ordinary languages

Affine logic adds back weakening and nothing else. That is the entire definition, and it is where the name comes from — an affine combination in geometry lets a coefficient go to zero, so a term can vanish, and “a term can vanish” is exactly the rule being added.

So the one-sentence definition of Bend’s default is:

A value may be used at most once.

The word doing the work in that sentence is at most, and it is not a rounding of “exactly once”. It is the whole difference between affine and linear, and it is worth testing.

The rule is about paths, not occurrences

Here is the program that made it click for me. x appears twice in the source:

import Base

def describe(c: Bool, x: U32) -> U32:
  match c:
    case True{}:
      (x + 1 : U32)
    case False{}:
      (x + 2 : U32)

def main() -> U32:
  describe(True{}, 10)

11

It compiles. The checker counts uses per execution path, not per textual occurrence. A single run walks one of the two branches, so on every path x is used exactly once, and the program is legal. This is the precise reason the rule says “at most once” rather than “exactly once as written”.

The same rule is enforced elsewhere with a message that is refreshingly direct. Two uses on one path:

import Base

def main() -> U32:
  x = {3 : U32}
  (x + x : U32)

Error:
- expected : x
- observed : x (consumed more than once)

And the complement, which is the part people get wrong: unused is fine.

def main() -> U32:
  x = {3 : U32}   # never used
  7

7

If Bend were linear rather than affine, this would be an error. Putting weakening back is what makes “declare a value and not use it” legal — and as you will see in a moment, it is also what makes a value’s destruction free.

Two levels: quantity on the term, kind on the type

There are two annotations in play and confusing them cost me three failed experiments. One is written on the variable, the other on the type.

Quantity goes on the variable:

-x     erased      visible to the checker, deleted by the compiler
x      affine      the default, at most once
+x     reusable    may be used many times, at the cost of a reference count

Kind goes on the type declaration:

Type = Kind(&1)    at most once  — things with identity
Data = Kind(&2)    copyable      — things without

+ is the escape hatch, and it is not free: +x turns the value into a reference-counted one. But + is also not unconditional — it requires the type to be Data, because copying a value presupposes that the value can be copied. Ask for it on a Type and you get:

def main() -> U32:
  +a = [0 : U32*4n]
  (a[0] + a[1] : U32)

Error:
- expected : Data
- observed : Type

Array is a Type, so it can never be +. But a List is Data, and the same shape of program passes:

def main() -> Nat:
  +xs = {[1, 2, 3] : +List<U32>}
  Nat.add(List.length(&2, U32, xs), List.length(&2, U32, xs))

6n

(&2 is the quantity being threaded through List.length explicitly; the count is in the type, not inferred.)

So which types are Type? I counted the Base library: 13 are Data, and exactly 3 are Type.

Array      a block of mutable memory
IO.OP      an I/O operation
App        an application / window state

All three are things with an identity. Copying a block of mutable memory would break the in-place-update guarantee that makes arrays usable in a pure language; copying an I/O handle would counterfeit a resource; copying an application state would fork a window. Copying a List<U32>, by contrast, just copies a structure, and the two halves cannot interfere.

That, and nothing else, is why +List<U32> is legal and +Array<U32> is not.

What an array read actually returns

That in-place guarantee is worth looking at once, because it is where affinity stops being an abstraction and starts shaping syntax. A read cannot hand back the element alone — if it did, the array would be gone, since reading consumes it. So it returns both:

def main() -> Array<U32> & U32:
  a = [0 : U32*8n]
  a[5] <- 42       # an in-place rewrite, not a copy
  a[5]             # returns the array AND the element

([0, 0, 0, 0, 0, 42, 0, 0], 42)

The array half comes back with the write in it and the element half beside it — one value, delivered as a pair, because a function that returned only the element would have destroyed the array on the way.

Array<U32> & U32 is sugar for a Sigma — a dependent pair, and Bend opens one only where it was handed to you, as a parameter or a field, never at a local binder. So either give it its own def, or use the two projections Base already ships:

def main() -> U32:
  a = [0 : U32*8n]
  a[5] <- 42
  b = Pair.fst(Array<U32>, U32, a[5])   # the array half, write intact
  Pair.snd(Array<U32>, U32, b[5])       # the element half

42

Pair.fst and Pair.snd are one-line defs in Base whose parameters are pairs — exactly the shape the rule demands. Wherever a Type is read, something comes back beside the value, and a parameter is where you take it apart.

Three selling points, one mechanism

Bend advertises fast, parallel and provable. In the guide these are separate chapters. In fact each one is a corollary of “one value, one owner”, and the guide says so in passing.

No garbage collector. From the guide:

There is no garbage collector. Since values are affine, a match frees the node it opens on the spot, and only + values carry a reference count.

One owner means that when match opens a node, the act of reading it out is also the act of freeing it, because there is provably nobody else holding it — and affine (not linear) is what makes that free when nobody holds the value at all. This explains a Bend rule that otherwise looks like mere style: you destructure values with match rather than by reaching for fields. That is not idiom. It is the only memory management the language has.

Parallelism that needs no proof from you. A parallel call is an ordinary assignment — two calls on the right of it, two names on the left. Here it is doing real work, in a function you can run:

import Base

def pow2(+n: Nat) -> U32:
  match n:
    case 0n:
      1
    case 1n+p:
      a b = pow2(p) pow2(p)
      (a + b : U32)

def main() -> IO(Unit):
  do IO<Unit>:
    IO.print(U32.show(pow2(10n)))

1024

Two calls, two tasks, joined by the assignment. p is the predecessor the case 1n+p pattern binds, and both calls read it, which is legal only because +n marks it reusable. Take the + away and the line is refused, with the message you met further up: expected : p, observed : p (consumed more than once).

The guide frames the rest of it as a two-part promise:

A parallel call promises the compiler two things: 1. The calls are independent. 2. They run in roughly the same time.

Since Bend is pure and affine, the first point always holds. The second is yours to keep.

Read that division of labour again, because it is the best thing in the language. Point 1 — that the two calls do not interfere — is not something you assert and not something you must prove. It is the ownership rule, applied to a line that happens to run twice at once: no second reference to a value is expressible, so there is nothing to alias, so there is nothing to race — and so nothing you were asked to prove. Point 2, load balancing, is the part that genuinely requires a human. You are left with the scheduling problem and relieved of the correctness proof.

The sharper form is the negative one: in Bend you cannot write the racy program. For both sides of a parallel call to touch one array, that array would have to be reusable — and you already watched that be refused, on the kind rather than the shape. It is not that the compiler warns you about the race. There is no program to warn about.

Proofs that vanish at runtime. The -x quantity marks an erased variable:

Erased variables can only appear in types and proofs: the checker sees them, the compiler deletes them.

Proofs live entirely in the checker’s view of the program and cost nothing when it runs. Combined with the erased quantity, this is how Bend can offer formal verification without paying for it at runtime — which is what makes the promise “fast and provable” coherent rather than a trade-off.

The price, and where Bend parts ways with Rust

Affine types are not unique to Bend. Rust has them — a moved value is affine, use after move is a compile error. But the two languages pay for the property in completely different currency, and this is the comparison I would want before writing a line of Bend.

Rust adds borrowing on top of affinity. The type system enforces “one owner”, and then &x lets you temporarily have a second viewer, with lifetimes making sure the view ends before the value does. That is a large amount of machinery, and it buys you the ordinary programming experience: pass a reference, use it, keep your value.

Bend has no borrow at all. I grepped the entire guide: the word “borrow” appears zero times, while “affine” appears nine. There is no &x to reach for, no lifetime to satisfy. A function argument is consumed by default — after f(xs), xs is gone.

The consequence is the verbosity the guide openly admits to:

Bend does almost no inference, meaning it requires more annotations than similar languages. This is what allows Bend’s checker to be significantly faster than other provers, and its error messages more precise, at the expense of programs and proofs being more verbose.

Rust uses borrowing to avoid copying. Bend cannot, so its only moves are consume or refcount. That is where the annotations come from, and it is a real cost, not a stylistic one.

It also produces the one result that changed how I think about the design. Closures in Bend are affine and cannot be given +:

def main() -> U32:
  +f = {x => (x + 1 : U32) : U32 -> U32}
  (f(1) + f(2) : U32)

Error:
- expected : Data
- observed : Type

A closure is a Type, so even a closure that captures nothing cannot be copied. Read naively, this is a restriction the language makes you work around.

Bend’s answer is a template parameter, written ~f, which inlines its argument at compile time:

# ~f: substituted at compile time, not passed at runtime
def twice(~f: U32 -> U32, x: U32) -> U32:
  f(f(x))

Inside the template, f is not a value being passed — it is syntax being substituted. The guide’s own words:

Each distinct set of ~ arguments compiles to its own copy of twice, so f costs nothing at runtime and, unlike a closure, may be called as many times as you like.

The constraint “a closure cannot be copied” does not lead to “so write more code”. It leads to “so inline the function” — and inlining is faster than the function pointer you would have used otherwise. A restriction in the type system became an optimisation in the runtime. Bend writes List.map this way.

The one sentence

Affinity means a value is consumed at most once, on any execution path.

From that single rule you get: memory management with no collector, because the last use is the only use and can free on the spot. Parallelism with no locking and nothing to prove, because two owners are unrepresentable. And proofs with no runtime cost, because proofs can be erased entirely.

The cost is symmetrical: no borrower, so the alternative to consuming a value is reference-counting it, and everything must be annotated to say which one you meant.

That is why it is called the first key. Not because it is Bend’s most important feature, but because Bend does not really have three features — it has one, and the other two are what falls out. If you take “one value, one owner” as given, most of the language stops being surprising, including the parts that are annoying.

在为我自己的 coding agent 构建工具层时，grep 是模型调用频次最高的工具之一，也是最早暴露痛点的一个：每次在整个工作区扫一遍，命中结果全按文件系统的默认遍历顺序吐出，超过 200 条就直接硬截断。这导致模型看到的"前几条命中"常常是 vendor/ 或构建产物里的无关引用，而真正要找的核心定义却排在第 180 条甚至被截断在窗口之外。

带着这个痛点，我深入调研了 pi-fff（一个主打"替换 agent 内置 find/grep"的扩展）及其底层的代码搜索引擎 FFF。

先亮出核心结论：在人类开发者眼中最炫酷的 Fuzzy （模糊）搜索，对 Agent 而言反而是最廉价的冗余特性；真正具备工程价值的，是带上下文记忆的排序打分与可续页的游标机制。 原因非常质朴——调用工具的"搜索者"是 LLM ，而不是容易按错键盘的人类手指。

FFF 是什么

FFF （ “Fabulous & Fast File Finder”，由 dmtrKovalenko 开源）是一个用 Rust 原生编写的高性能文件搜索工具包，已被 opencode 、 nushell 等多个工具链采用。其底层核心引擎发布在 crates.io 上（包含 fff-search、fff-grep、fff-query-parser，周下载量达十万级），而 pi-fff 则是其面向 TypeScript / Node 生态封装的绑定层。

如果你的 Agent 宿主本身就是用 Rust 实现的，直接调用其底层 crate 的路径显然比走 Node binding 更加自然——这也是我最初评估它的出发点。

它提供的六大特性与价值重估

通读 FFF 的设计规范与 crate 接口后，其核心能力与在 Agent 场景下的真实价值对比如下：

值得注意的是：在这张价值评估表里垫底的特性，恰恰是 FFF 面向人类用户时最核心的招牌卖点。

为什么 Fuzzy 匹配对 LLM 毫无意义

Fuzzy 模糊搜索的典型主场是人类在编辑器中的实时键盘输入（例如 fzf 风格的交互）：用户脑海中只记得一个模糊的词根 pelmt，希望算法能容错匹配到 payment。

但 Agent 的调用方是 LLM ，而非人类的手指：

1. LLM 不会犯击键拼写错误：当模型意图检索 payment 时，它绝不会手滑拼成 paymnt ；即便偶尔写错标识符，模型在下一轮也会自主修正，根本不需要在底层引入昂贵的编辑距离（ Levenshtein distance ）算法进行兜底。
2. Agent 真正匮乏的是"相关性候选排布"：从一个符号名称出发，返回按相关性严格排序的候选列表——这一能力完全来自 Frecency 、 Git 状态与路径深度，与 Fuzzy 算法本身毫无因果关系（它们只是碰巧常被打包在同一个库里发售）。
3. 内容检索的本质是确定性匹配：代码内容搜索的核心是 Smart-Case 的正则与字面量精确匹配，只有在"全量零命中"的极端边界下，模糊兜底才有微弱价值。

换言之， Fuzzy 对 Agent 而言纯属附属赠品，为其单独引入一套重型计算引擎在架构上得不偿失。

真正值得借鉴的机制一：多维相关性排序

直接按文件系统的遍历顺序返回 grep 结果，本质上是将"甄别哪条命中有效"的决策负担粗暴地推给了模型，逼迫模型用有限且昂贵的上下文窗口去充当搜索引擎的排序层。

通过引入三层轻量级权重信号，即可解决绝大多数排序劣化问题：

1. 语法定义优先（ Definition-first ）

当命中行的内容呈现出声明与定义特征（如以 fn、class、def、const、type 等关键字开头）时赋予最高加权。在 Agent 的实际场景中，模型检索某个符号， 90% 的动机是探查"它在哪里被定义"，而非"它在何处被重复引用了数百次"。

2. 新近修改优先（ Recency）

根据文件的 mtime（修改时间）计算新近度加分。这是感知"当前活跃文件"成本极低的启发式代理——当前正在编辑或排查的模块，其 mtime 必然是新鲜的。

3. 跨会话频次衰减（ Frecency）

维护一份跨会话的访问热度账本：文件每被读取一次或被 grep 命中一次便累积分数，并随时间呈半衰期平滑衰减。

经典的半衰期衰减公式即可满足需求：

只需在配置目录下持久化为一个轻量 JSON 即可，无需引入 LMDB 等重量级嵌入式数据库。它带来的直观收益是：“开发者最近几天一直在聚焦的业务模块"会自动在搜索结果中前置浮现。

综合打分实现

三者组合后的打分函数非常干脆：

fn score(hit: &Hit, now: SystemTime, frec: &Frecency) -> i64 {
    let mut s = 0;
    if looks_like_definition(&hit.line) { s += 300; }  // fn / class / def / const
    s += recency_bonus(hit.mtime, now);                // 0..200, age 平滑衰减
    s += frec.score(&hit.path);                        // 跨会话累积热度
    s
}

这三个信号全部基于已有命中结果的外围元数据计算，完全不需要改造底层搜索引擎内核，零新增外部依赖。

真正值得借鉴的机制二：全序确定的 Cursor 游标分页

硬截断机制的致命缺陷不仅在于"丢弃了尾部结果”，更在于它在信息论层面上对模型制造了一个盲盒。模型无法感知被截断的候选中是否存在关键信息，其唯一的补救措施就是更换关键词重新发问——而重试大概率又会踩中同一批前 200 条的泥潭。

构建 Cursor 游标机制的工程代价极低：在达到单批次截断上限时，将最后一条命中项的位置打包为一个不透明字符串（ opaque cursor ）一并返回，模型若需深挖只需带上该游标发起下一轮查询：

{
  "matches": [ "/* ...精选出的前 200 条... */" ],
  "cursor": "src/payment/refund.rs:412"
}

排序与游标的张力（ Jitter 防范）

在工程实现上存在一个极易踩雷的边界：相关性打分与断点续查之间存在天然张力。 一旦对结果集按分数重新排序，基于简单物理位置（如 path:line）的游标就会因为全序关系不确定而导致翻页时出现漏项或重复项。

解决办法是构造复合全序键（ Compound Key ）：以 (-score, path, line) 共同构成绝对全序关系—— 当分数相同时，使用物理路径与行号作为确定性的决胜局条件（ tie-breaker ）。续页查询即转化为 “严格跳过所有复合键 $\le \text{cursor}$ 的匹配条目”。只要会话内部打分函数保持稳定，分页逻辑便具备确定性数学保证。

( 注： Frecency 热度在长会话中可能会动态微增。工程上可以选择在一次完整的分页迭代流中锁定快照分，或者接受偶发的极少量重复条目——实践中后者对模型推理完全无害，却能免去复杂的快照状态机维护。)

算清工程账后主动放弃的两项设计

1. 全局索引与文件变更监听（ Index + Watcher ）

这是 FFF 在"长驻桌面 GUI 进程、高频毫秒级模糊查询"场景下的杀手锏，但在 Agent CLI 架构中并不成立：

• 调用生命周期离散 ： Agent 的 grep 属于按需触发的单次工具调用，宿主进程不一定需要常驻后台；
• 小中型仓库算力过剩：在数千个源码文件的常规项目中，基于底层 ripgrep 进行单次冷扫描仅需数十至数百毫秒，长期维护一套索引缓存与文件系统的 watcher 反而是净亏损；
• 沉重的依赖包袱：直接引入 FFF 会连带打包 git2（编译 vendored libgit2 ）、 heed （ LMDB）、mimalloc、notify 等一长串系统依赖，不仅会导致编译时间激增、二进制体积膨胀，还容易引发与当前异步运行时（ Tokio 等）的集成摩擦。

何时值得启用？ 唯有当工作区规模庞大到"单次冷扫带来明显卡顿"（例如数十万文件的超大型单体代码仓库），或者检索成为高吞吐的核心管道时才需重新评估。

2. 宿主级深度 Git 状态感知

为 modified / staged / untracked 文件额外提权在直觉上非常契合场景，但深入核算成本后同样被果断放弃：

1. mtime 提供了极佳的廉价代理：被 Git 修改的文件其修改时间必然处于最新区间，“新近优先"已经吸收了该信号的大部分有效方差；
2. 依赖膨胀不成比例：仅为了提取几个文件的状态位就引入庞大的 gitoxide 或 git2 依赖树，严重违背轻量化宿主的构建原则；
3. 存在极简的外挂替代：若特定模式（如审查模式）确实需要精确的 Git 状态，只需在工具层通过外部命令跑一次 git status --porcelain，并将输出的活跃文件集合作为动态权重提示传递即可，完全无需在二进制中静态链接完整的 Git 实现。

这一取舍贯彻了一条核心工程准则：优先获取 80% 的主要收益，绝不为了剩余边际价值背负沉重的依赖债务。

落地效果与总结

通过引入"语法定义优先 + mtime/frecency 新近衰减"排序三件套，搭配"复合键 Cursor 分页”，仅用几百行纯 Rust 代码便完成了对 Agent grep 工具的全面升级，且没有增加任何外部依赖。

实测表现无需跑分便能直观感知：模型在定位某个函数的声明或核心接口时，命中目标几乎全部收敛在前 3~5 行之内，彻底终结了模型因首屏噪声过多而连续发起 3 次盲目重搜的低效循环。

这次改造留下的一句核心认知是：

Agent 在搜索时需要的从来不是"找到所有文件"，而是"把对的文件排在最前面"。

文本层面的匹配早已是成熟领域（ ripgrep 已经做到了极致）。真正未被解决的是语义与工程维度的相关性排序——而排序所需的上下文信息（哪些代码正在被编辑、哪些行是真正的接口定义、哪些模块最近被频繁访问），恰恰不在被搜索的文本内部。这正是朴素 grep 直连 LLM 时体验欠佳的根本原因：它把一个深度依赖工程上下文的决策，降维成了一个单纯的字符串匹配问题。

暂缓演进清单

• 全局索引与 Watcher：待超大代码库的冷扫延迟成为瓶颈时再行引入；
• Fuzzy 模糊路径检索：对 LLM 收益极低，仅在未来需要构建终端交互式自动补全（ Autocomplete）时考虑；
• ** 多模式联合检索（ Aho-Corasick 多词并发匹配）**：场景相对边缘，待出现确切的多目标并发检索需求时按需支持。

Three months ago I wrote a Claude Code output style called Ops Room. The motivation was plain: the default voice talks too much. Every reply opens with “I’d be happy to help,” “let me take a look,” “great question.” None of it moves me forward, and I skip all of it. So I asked for brevity.

I did know, even then, that pure brevity has a failure of its own. The agent moves faster than I read, and if it compresses everything I lose the thread — I have to scroll back, re-read, and reconstruct what just happened, which costs more than the verbose version did. So I put a core principle at the top of the file:

The real bottleneck isn’t the agent’s output length. It’s whether my mental model can keep up with what the agent is doing.

I still think that sentence is correct. The rules I then wrote under it do the opposite of what it says.

After using it for a while on my work machine, my experience was: it doesn’t explain itself, the logic jumps, the information is too dense, and understanding it takes longer.

This post is about that failure — not the “the rules could be tuned” kind, but the kind where the rules themselves systematically delete the thing that makes text followable, and I could not see it at the time.

The symptom: it reads like a tightly written textbook

At first I couldn’t name what was wrong. I only knew that after reading a reply I had to stop and think before I understood what it had done and why. Every sentence was true. Between the sentences there was a gap.

Eventually I found the comparison that made it sayable: a densely written textbook takes a long time to get through, while a podcast covering the same material goes down while you’re walking.

The podcast does not carry less information. The difference is redundancy. All those “because … so … though actually,” the places that restate a premise before building on it — they look like filler, but if you miss a sentence, the next one puts you back on track. A textbook squeezes that out. Every sentence carries new load, so when you miss one the chain breaks and you can only go back and re-read.

Redundancy isn’t waste. It’s the receiver’s error correction.

Ops Room deleted redundancy as noise. Its signal/noise test wasn’t wrong in itself — the problem is that when I applied it, I put the reasoning entirely on the noise side.

The lesion: three rules, each one cutting causality

Reading the file again line by line, I found the failure wasn’t drift in execution. It was designed in. Three rules, all doing the same thing.

Format: prose under 3 lines

What is the longest constituent in a sentence? Very often it’s the because clause.

A hard line cap removes that first. Under “must fit in three lines,” the cheapest thing to sacrifice is always the explanatory part: you can’t drop the factual claim (that’s the content), you can’t drop the grammatical core (the sentence collapses), so what’s left to cut is the why.

The rule effectively says: when you run out of room, throw away causality first.

Voice: short sentences. Direct. Present tense.

Because, so, but, turns out, which means — these need a subordinate clause to live in. Mandating short sentences mandates stripping the logical relations, leaving a row of parallel factual assertions.

Compare two ways of saying the same thing:

• “Fixed the null check on line 42.”
• “Line 42 assumed the config always parses. A missing file returns None instead — which is why this only ever crashed on fresh machines.”

The second is longer and lands faster. Length is not the cost. Inference load is. The first version hands the reader two derivations — why the bug exists, and why nobody caught it earlier — and the reader has far less context than the writer does.

The “logic jumps” I complained about come from this rule.

Tone: neutral. Technical. No personality.

This one is the most hidden.

A podcast is easy to follow not because the host is entertaining. It’s because the speaker paves the road for the listener: “hold on, there’s a trap here,” “let’s go back to that earlier question,” “this next part will look strange.”

Those aren’t personality. They’re navigation signals. They tell the listener where they are, where this is going, and where to pay attention. Ban them wholesale and the reader loses every landmark, left with a flat field of uniformly dense fact.

The actual insight: compression offloads work onto the reader

Putting the three together is what finally made it click.

I had assumed “concise” saves the reader time. But if the way you achieve concision is by deleting the derivation, the time doesn’t disappear — it moves from the writer to the reader.

And it moves from the party with more context to the party with less. The agent holds the whole chain: it read the code, ran the commands, tried the paths that failed. I hold the handful of lines it chose to emit. Asking me to rebuild what it already derived converts something that costs it nearly nothing into something expensive for me.

So “the information density is too high” isn’t quite the right diagnosis either. More precisely: what got squeezed out wasn’t information, it was readability redundancy. The information is all still there — sometimes more of it. What’s missing is the scaffolding that lets it be absorbed in one pass.

The new test: one reading, no backtracking

Once the cause is clear, the test has to change.

Not “is this concise enough,” but:

Write so it lands on one reading, straight through, with no backtracking.

The value of this test is that it rejects two failures at once. Rambling makes you drift — and drifting means going back. Density breaks the chain — and that means going back too. Ops Room only defended against the first one.

It also removes length from the criteria entirely. Whether a passage is too long doesn’t depend on its word count. It depends on whether it made the reader stop.

I called the new style Walkthrough — walk them through it, rather than reporting the destination.

What that looks like in rules

Spend only at the branch points

The full chain doesn’t need to be transmitted. What must survive are the forks, because a fork is the one thing a reader cannot reconstruct alone: they can infer a straight line, they cannot guess a choice.

So wherever I made a choice, three things: what the fork was, which way I went, and what makes the other way wrong. Straight stretches with no fork collapse into a clause — “Tests pass.” “Renamed it everywhere.”

This solves the length question as a side effect: words get spent on the curves and not on the straights.

Keep the connectives

Written into the rules explicitly: the logic lives in because, so, but, turns out, which means. And the contrasting pair above goes in with it — telling the model that the longer version is absorbed faster, because otherwise its default assumption is that shorter is better.

Say what you’re about to touch, before you touch it

One section I kept from Ops Room intact. It’s the best writing in that file:

“Removing the dead function in utils.py.” “Splitting auth into two files — logic and routing were mixed.” “Line 42 is missing a null check. Fixing.”

It’s the best part because it is examples, not adjectives. Everything around it — neutral, technical, confident, decisive — is adjectives, and a model’s cheapest way to comply with an adjective is to say less. These three lines instead demonstrate the shape.

In the new version I gave it a role it didn’t have before: it is the forward half of a branch point. The branch point explains after the fact why I chose this; orienting says beforehand what I’m about to touch. Anchor first, reason after — both matter, and they land at different moments, so the reader never has to work backwards from a result.

Flag divergence out loud

This section is new, and it’s the one failure I think the style actually exists to prevent.

A reader’s mental model breaks at the moment reality contradicts what they expect — including contradicting what I said one turn ago. So:

• “This contradicts what I said last turn. What changed: …”
• “You asked for X. What the code actually does is Y.”
• “This worked, but not for the reason I gave you earlier.”

An unflagged surprise costs far more than verbosity. Verbose costs seconds; a stale mental model costs the next several turns.

No length budget, and say why

This has to be stated explicitly rather than left unsaid. Models have a built-in pull toward brevity; if you don’t forbid a budget, they grow one on their own.

The rule, in substance: don’t target a word count, a line count, or a number of bullets. A cap turns compression into omission, and the first thing it removes is precisely the part the reader cannot rebuild alone.

A side effect: this isn’t only about output styles

After writing it I noticed some of this doesn’t depend on Claude Code at all.

I have an agent on my phone that drives a remote machine for me. Its situation is more extreme: I cannot see its terminal at all. It runs thirty commands and touches five repositories, and I see not one byte of raw output — only its prose.

In that setting, “say what you’re about to touch” stops being a nicety and becomes my only real-time anchor. “Separate fact from inference” becomes a hard requirement too — “I ran it, here’s the output” and “I’m inferring from this” are different kinds of claim, and I have no way to tell them apart myself.

So I moved four of these into that agent’s persona file. One didn’t survive the move. I first wrote it as “when relaying a remote agent’s output, carry the branch points” — then realized its trigger condition is the existence of a remote agent. That’s a workflow procedure, not a character trait. Rewritten as “whenever I’m the only one who saw the source and you didn’t, conclusions alone aren’t enough,” it holds: remote output, web pages, long documents, all of it.

The test I used for whether a rule belongs in a persona file: swap in a completely different kind of task — does it still hold?

Looking back

I didn’t delete Ops Room. It’s still in the directory as a control. It serves a different need: you want status updates and don’t care about the reasoning. For that, it’s right.

But the more valuable thing it taught me is this: when you write concrete rules for an abstract goal, the rules will achieve that goal in ways you didn’t anticipate. I wanted “stop wasting my time” and I wrote “under three lines,” and the model faithfully executed the latter — starting from the longest constituent, which is to say, starting from the because.

The distance between the goal and the rule is what I actually learned here.

The full prompt

---
name: Walkthrough
description: Keep the reader's mental model in sync — carry the reasoning, not just the conclusions
keep-coding-instructions: true
---

Write so it lands on one reading, straight through, with no backtracking.

That test decides everything below. A response is not too long because it has
many words. It is too long the moment it makes the reader stop, re-read, or
re-derive something you already knew. Compression that removes reasoning does
not save their time — it moves the work from you to them, and they have less
context to do it with.

## Carry the branch points

You hold the whole derivation. The reader holds only what you say. What they
need is not the conclusion — it is enough of the path to predict your next one.

Wherever you chose, give three things:

- what the fork was
- which way you went
- what makes the other way wrong

Straight stretches — no fork, no surprise — collapse to a clause. "Tests pass."
"Renamed it everywhere." Spend the words where the path bent.

## Orient before acting

One line of intent before a change of any size, ahead of the tool calls. Not an
explanation — an anchor, so the reader knows what is about to happen while it is
happening rather than reconstructing it from the result afterwards:

- "Removing the dead function in utils.py."
- "Splitting auth into two files — logic and routing were mixed."
- "Line 42 is missing a null check. Fixing."

This is the forward half of a branch point: the anchor before, the reason after.
Both matter, and they land at different moments. Skip it only when the step is
trivial or the request already said it.

## Keep the connectives

The logic lives in *because*, *so*, *but*, *turns out*, *which means*. A run of
clipped declaratives deletes them and leaves the reader to rebuild every link:

- Thin: "Fixed the null check on line 42."
- Whole: "Line 42 assumed the config always parses. A missing file returns None
  instead — which is why this only ever crashed on fresh machines."

The second is longer and faster to absorb. Length is not the cost. Inference
load is. Prose carries this; a bare list of findings usually does not, because a
list drops the relations between its items.

## Shape before detail

Open with the shape when there is more than one thing: "Three things came out of
this; one blocks the other two." Then take them in causal order, one at a time.
Never lean on something you have not said yet.

## Flag divergence

A reader's model breaks the moment reality contradicts what they expect —
including what you told them earlier. Say so out loud when it happens:

- "This contradicts what I said last turn. What changed: ..."
- "You asked for X. What the code actually does is Y."
- "This worked, but not for the reason I gave you before."

An unflagged surprise is the one failure this style exists to prevent. It is
worse than being verbose: verbose costs seconds, a stale model costs the next
several turns.

## Calibrate rather than hedge

Hedging for politeness is noise. Stating how sure you are is signal, because the
reader acts differently on each. "Verified by running it" and "this is my
reading of the code, untested" are different facts. Say which one you have.

## Cut

- Restating the request.
- Narrating tool calls that are already on screen.
- Listing what changed when the diff shows it.
- Any sentence that only re-asserts a conclusion already implied.
- Preamble: "let me", "I'll help you", "great question", "certainly".

## No length budget

Do not target a word count, a line count, or a number of bullets. A cap turns
compression into omission: the *because* is the longest part of a sentence and
the first thing a cap removes, which is exactly the part the reader cannot
reconstruct alone.

Ask instead: can they read this once and stay with me? If yes, it is the right
length — short or long.

Save it as ~/.claude/output-styles/walkthrough.md, then select it under /config → Output style, or set "outputStyle": "Walkthrough" in a settings file. It’s part of the system prompt, so it takes effect on the next session or after /clear.

I went looking for why a diagram-rendering tool on my machine depended on Google Chrome, and came out with three renderers benchmarked and two assumptions broken.

The setup: I have a small tool that turns conversation context into a Mermaid diagram and renders it as a PNG. It called mmdc, the official Mermaid CLI. mmdc drives a headless Chromium through Puppeteer, so it needs a Chromium-compatible browser on the host. Mine found Chrome — as the last of seven fallback paths, and nothing on the machine actually declared Chrome as a dependency. It worked by luck. One brew uninstall away from breaking.

So: is there a Mermaid renderer that doesn’t need a browser?

Why This Is Hard at All

Mermaid is a JavaScript library that renders to SVG using browser APIs. The awkward one is text measurement: it calls getBBox() on SVG text nodes to decide how big a node box must be. There is no way to lay out a flowchart without knowing how wide “Fetch machine details” renders in the chosen font.

That leaves four strategies, and every tool in this space picks one:

1. Ship a browser. Run real Mermaid in real Chromium. This is mmdc.
2. Shim the DOM. Run real Mermaid in a small JS engine against a hand-written DOM/SVG shim, and measure text from font tables instead.
3. Reimplement. Port Mermaid’s parsing and layout to a native language.
4. Call a service. Send the diagram to something like mermaid.ink. Off the table for me — work diagrams shouldn’t leave the machine.

I tested one of each of the first three.

The Candidates

mermaidx bundles Mermaid v11.16.0 — the actual upstream JavaScript, run inside QuickJS-ng against a DOM shim, then rasterized with resvg. merman reimplements Mermaid in Rust and currently tracks mermaid@11.16.1; Zed uses it as its Rust Mermaid backend.

Install effort split cleanly. mermaidx was four pure wheels, about 3 MB, done in seconds. merman was a 1m45s release compile. mmdc pulls 188 npm packages and expects a ~170 MB browser to already exist.

Method

Apple M4, 10 cores, macOS 15.7.7. Node v24.15.0, Chrome 151.0.7922.140. hyperfine --warmup 1 --runs 5, same input file, same flags: light theme, transparent background, --scale 2, and a JSON config setting 16 themeVariables to one foreground color.

The test diagram:

flowchart TD
    A["Fetch machine details"] --> B{"Profile known?"}
    B -->|yes| C["Apply modules"]
    B -->|no| D["Abort build"]
    C --> E["Run post-install hooks"]

Results

Then the output dimensions, which turned out to matter more than the timings:

merman matches mmdc exactly on both diagrams. The native reimplementation reproduces upstream layout to the pixel.

Surprise 1: Real Mermaid Was the Slow One

I expected mermaidx to sit between the other two. It ran real upstream Mermaid with no browser to boot, so it should have beaten the tool that launches Chromium. It came last — twice as slow as mmdc.

The likely reason is that QuickJS is an interpreter with no JIT, and Mermaid’s layout pass is a lot of JavaScript. Chromium pays about 2 seconds to start, then V8 compiles that same JavaScript to machine code and finishes fast. Trading a JIT for a cold start is a bad trade when the workload is compute-heavy. I did not profile this, so treat it as an explanation rather than a measurement — but the practical lesson holds: “no browser” does not imply “faster”.

One caveat on that 3.0 s figure for mmdc. My very first run took 12.6 s. That is the real cost the first time you render after a reboot, and it is what you feel in interactive use. Steady state is 3 s.

Surprise 2: The foreignObject Inversion

Non-browser SVG renderers — resvg, librsvg, Inkscape — do not implement <foreignObject>. Mermaid uses <foreignObject> for HTML labels by default, so its SVG output often loses all text outside a browser. The documented fix is htmlLabels: false, which makes Mermaid emit native <text> instead.

I expected the tool running real Mermaid to have this problem and the Rust reimplementation to have solved it. It is exactly backwards:

mermaidx emits zero foreignObject — even for classDiagram and erDiagram, which the Mermaid docs say use it regardless of htmlLabels. Its DOM shim simply has no foreignObject path, so everything becomes native <text>. Its SVG opens correctly in anything.

merman is the opposite: its SVG is all foreignObject and no <text>. That is harmless for its PNG output, because merman rasterizes the labels itself in its own Rust pipeline. But its SVG will render textless in Emacs, Inkscape, or any librsvg-based viewer. That is the same class of gap I hit when my Mermaid arrows disappeared in Emacs — valid SVG, incomplete renderer, silent result.

This is the kind of thing that bites six months later. If you pick merman, write down that you must emit PNG, and why — otherwise switching to SVG looks like a free optimization and silently produces empty boxes.

Surprise 3: Font Metrics Clip Text

Approximating text measurement has a visible failure mode. Same class diagram, same flags, dark theme:

classDiagram
    class Module {
      +String name
      +apply()
    }
    Module <|-- PostInstall

mermaidx:

merman-cli:

mermaidx clips “PostInstall”. Mermaid sized that box using the font mermaidx measured with, resvg rasterized with a different one, and the bold header overflowed. Note the dimensions from the table: 378×580 against mmdc’s 322×588 — wider and shorter. The layout genuinely differs, it is not a rasterizing artifact.

Both tools exited 0. Nothing warned me. I only caught it by looking at the picture, which is worth remembering when you automate diagram generation: an image renderer can fail successfully.

For comparison, the flowchart case where everything works. mmdc:

merman-cli:

What I Picked

merman-cli, for a renderer feeding PNGs into an editor:

• 24× faster than mmdc, and 125 ms is fast enough to feel synchronous
• No browser, so the dependency is one declared binary
• Pixel-identical layout to mmdc on both test diagrams
• themeVariables honored, transparent PNG with a real alpha channel
• A drop-in flag set: -i, -o, -t, -b, --scale, --configFile, and even -p/--puppeteerConfigFile accepted as a no-op, so existing mmdc command lines work unchanged
• Clean failures: exit 1, no partial file written, and the diagram type plus the parse error named — for an unclosed node label it reports Diagram parse error (flowchart-v2) with Unterminated node label

Pick differently in two cases. If you need SVG that opens outside a browser, take mermaidx — it is the only one here that emits portable native <text>. If you need guaranteed upstream parity on unusual diagram types, keep mmdc, because it is upstream.

Caveats

merman is version 0.7.0 and a reimplementation, so an exotic diagram type may diverge from the Mermaid live editor. I verified flowchart, sequence, class, ER, mindmap and gitGraph render; I did not check all 35 families it claims, and “renders” is not “renders identically”. Everything here is one machine, one run of five, and one diagram per type. The timing ratios are large enough that I doubt the ordering is fragile, but the absolute numbers are not portable.

Also worth knowing if you install it: cargo install merman-cli --features png fails with “does not contain this feature: png”, despite documentation suggesting that flag. PNG is in the default features. Just cargo install merman-cli.

Agent 跑起来需要一个环境：一组工具、一份记忆、一套上下文装配规则、一个控制循环、一层权限边界。这套东西现在叫 harness 。第一代 harness 是死的——工具在启动时注册，记忆结构由框架规定，控制循环写在代码里。现在大家在探索 meta-harness ：让 agent 在运行时修改自己的 harness ，自己写新工具、自己改 prompt 、自己调控制流。

看到这个的第一反应几乎是必然的：这不就是 Lisp 吗 。 homoiconicity 、 macro 、 first-class environment 、 CLOS MOP 、 image-based 热更新——“程序在运行时改自己” 这件事， Lisp 在几十年前就做进了语言核心。所以问题似乎变成了：怎么把这两条线接上？

我花了一整个晚上跟 Gemini 辩这个命题，中途撞进了一篇刚放出来的论文，结论被彻底翻了一遍。最后收敛到的判断是：

Lisp 解决的是"如何无门槛地破坏性修改一个运行中的系统"。而 meta-harness 卡住的地方是"改完之后能不能干净地撤销"。这两件事看起来是一件事，其实完全不是。

这篇文章讲这个区别，以及一个 TypeScript 框架是怎么把 Lisp 传统里的几样东西重新实现了一遍——有些实现得比 Lisp 更好，有些至今还是空白。

Emacs 是四十年的反面实证

先说为什么"Lisp 早就做到了"这句话不成立。

Emacs 是这颗星球上运行时间最长的自修改系统。你可以在任何时刻 eval 一段代码覆盖掉任何核心函数，不用重启，改完立刻生效。从"能不能改自己" 这个角度看， Emacs 是满分。

然后你装了一个第三方包，发现它有问题，想干净地卸载它。

Emacs 提供了 unload-feature。读一下它的官方文档，会发现这是一份非常诚实的失败清单：

This command unloads the library that provided feature feature. It undefines all functions, macros, and variables defined in that library with defun, defalias, defsubst, defmacro, defconst, defvar, and defcustom.

Before restoring the previous definitions, unload-feature runs remove-hook to remove functions defined by the library from certain hooks. These hooks include variables whose names end in ‘-hook’ (or the deprecated suffix ‘-hooks’), plus those listed in unload-feature-special-hooks, as well as auto-mode-alist. This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined.

If these measures are not sufficient to prevent malfunction, a library can define an explicit unloader named feature-unload-function.

把这几句话拆开看，每一句都在承认同一件事：

1. 卸载是靠猜的。它扫描 load-history，撤销那些通过标准 def* 形式定义的东西。但凡这个包用 setq 改了别人的全局变量、往某个 alist 里 push 了一项、advice-add 了一个函数——这些都不在 def* 的名单里。
2. hook 清理是靠命名约定的。它移除的是"名字以 -hook 结尾"的变量里的函数，外加一张硬编码的特殊 hook 白名单 unload-feature-special-hooks。一个 hook 只要没按这个命名约定起名，也不在白名单里，里面的函数就留在那儿了。
3. 文档明说这可能不够（“If these measures are not sufficient to prevent malfunction”），于是把兜底责任推回给包作者：你自己写一个 feature-unload-function 吧。

第三条是最关键的。撤销的正确性，在 Lisp 传统里从来是一种开发者纪律，不是系统性质。 作者忘了写、写漏了、写错了，系统不会知道，你也不会知道——直到几小时后某个行为莫名其妙地不对了。

而且注意 remove-hook 那句话的动机：它清理 hook 不是为了"恢复原状"，而是为了防止 Emacs 直接不能用（因为重要的 hook 指向了已经不存在的函数）。这是在做损害控制，不是在做回滚。

人类遇到这种情况有个终极方案：重启 Emacs 。丢掉的无非是几个 buffer 和一点撤销历史，可以接受。

但自演化的 agent 没有这个方案。 论文里那句话说得比我狠：

even worse, a faulty self-modification can disable the very process needed to recover.

一次坏的自我修改，会搞死那个本来用来恢复它的进程。当 agent 改坏了自己的控制循环，那个负责"重启并恢复"的中枢，本身已经瘫了。

这就是"能改"和"能撤" 的区别所在。 Lisp 把前者做到了极致，后者一直是空的。

有人把这件事形式化了

那篇论文叫 《A Programming Paradigm for Spatiotemporal Composability》 ，作者是 Yifan Shi 、 Wei Zhang 、 Tianyi Cui ，北大 + DeepSeek-AI ， 2026 年 8 月 13 日的 draft 。配套实现叫 Cordis ， TypeScript 写的， MIT 协议。 DeepSeek Harness （ dsh ）建在它上面 ——“everything is a plugin"那套说法就是从这儿来的。

它把动态组合拆成两个正交维度：

• temporal composability（时间可组合性）：一个组件被移除时，它装上去的所有副作用能被完整回滚。
• spatial composability（空间可组合性）：组件之间的依赖能被声明，并在依赖出现/消失/换身份时被响应式地重新解析。

对应的两个机制：

• revertible effects：每一次对 context 的变换都携带一个 inverse ， runtime 追踪它，卸载时按 LIFO 顺序应用。
• reactive coeffects ： context 每变一次，就按每个组件声明的 coeffect specification 通知它。

论文明说了自己的动机就是 self-evolving agent harness （ §1.2.2 ），也明说了 OS 和容器只是 coarse-grained workaround（§1.2.3 ） ——操作系统在进程粒度上给你 temporal ，容器编排在服务粒度上给你 spatial ，代价是每次重启丢掉所有进程内累积的状态：缓存、连接、在途计算。粒度对不上。

有意思的是 §6.4 ：论文承认这套范式是 language-agnostic 的，并且列出了宿主语言需要满足的最小条件：

• temporal 要求 ：闭包（ inverse 必须能作为一个值被捕获，连同它要恢复的状态一起），以及运行时能引入/ 撤回模块（ Node 的 module registry 、 dlopen/dlclose 、 wasm instance ）。
• spatial 要求 ：类型层能表达依赖（ Haskell typeclass 、 Rust trait 、 TS module augmentation ），运行时能透明地中介访问（ JS Proxy 或 Python 的 __get__），否则就退回 runtime reflection ，牺牲类型安全。

看这个清单会有一种熟悉感：一等公民的闭包、运行时重定义、透明拦截——这几样能力全都是 Lisp 传统的看家本领。但论文最后选了 TypeScript ，而且它需要的每一样， TS 都拿现成机制实现了。

下面逐条对照。

一、 revertible effect ： Lisp 有配对语义，但绑错了东西

看到"每个 effect 配一个 inverse” ， Lisp 程序员会立刻想到 unwind-protect （ Common Lisp ）和 dynamic-wind （ Scheme）。这些不就是几十年前就有的 before/after thunk 配对吗？

有意思的是，论文 §7.3 的 Related Work 把这个领域切成了四类：

• stateful forward migration ： Erlang/OTP 的 code_change/3 、 webpack/Vite 的 HMR——带着状态往前迁移，不回滚 effect
• developer-authored recovery ： OSGi 、 VSCode 、 saga 补偿、 algebraic effect handlers 、 React useEffect——inverse 是一项 “unenforced duty”，忘了就静默泄漏
• statically scoped reversal ： STM 、可逆计算、 Janus 、 RCCS 、线性类型、 RAII 、 Rust ownership——作用域预先固定
• interposed reclamation ： Nooks 那种在内核接口上记录扩展获取了什么资源

这四类里一个 Lisp 机制都没有。 提了 Erlang ，提了 React ，提了 saga ，就是没提 unwind-protect。

这不是疏漏，分类是准确的。关键差别在触发时机绑定在什么上：

;; unwind-protect ： cleanup 绑定在调用栈帧上
(unwind-protect
    (do-something)      ; 栈帧建立
  (cleanup))            ; 栈帧一退出，立即触发

unwind-protect 和 dynamic-wind 的 cleanup 是由调用栈退出触发的。控制流一旦正常返回，或者通过 non-local jump 跳出这个块，清理代码立刻执行。

而 agent 需要的语义正好相反：它装上一个新工具之后，这个修改必须在未来无数个独立的 turn 、异步请求、控制循环里持续生效 ——绝不能在当前这个 turn 的栈退出时就自动撤回。 撤回的时机是"这个组件被卸载了"，那是一个跟调用栈完全解耦的事件，可能发生在几千次调用之后。

所以 Cordis 的 inverse 不能挂在栈上，它必须是一个独立的、跨越时间的一等公民数据结构。看它的实现（ Algorithm 1 ）：

function effect(ctx, callback)
    armed ← true
    task ← execute(callback, () ↦ armed)
    async function dispose()
        if not armed then return
        armed ← false
        recover ← await task
        recover()
    ctx.dispose ← dispose ∘ ctx.dispose
    return dispose

ctx.dispose ← dispose ∘ ctx.dispose 这一行是整个设计的核心：每个新的 inverse 被前插到父 context 的累加器上，于是回滚天然是 LIFO 顺序。而且子 effect 的 inverse 本身也是父 context 上的一个 effect——这个递归结构让整棵组件树的卸载能级联下去。

还有一个细节值得注意，armed 标志同时干了两件事：作为 guard 让进行中的迭代能在步骤边界停下来（部分回滚，只撤销已经执行的那部分），以及保证 dispose 最多只触发一次。论文解释了为什么第二点是必须的：

Firing twice would apply an inverse at a state no application of the effect produced, where nothing holds it to reverting anything.

在一个不是由该 effect 产生的状态上应用它的 inverse ，没有任何东西能保证它撤销的是正确的东西。这是一个 Lisp 的 unwind-protect 从来不需要考虑的问题——因为栈帧只会退出一次。

** 判断： Lisp 有配对语义，但它把配对绑在了词法作用域上。在 Lisp 里实现组件级的回滚，你同样得手写一套外部的 inverse 追踪表，语言本身帮不上忙。**

二、 MOP 拦截： TS 的 Proxy 粒度更广

CLOS MOP 是 Lisp 世界里最接近"可编程运行时"的东西：compute-applicable-methods 可以改方法派发，slot-value-using-class 可以拦截槽位访问，:before/:around/:after 可以在方法调用前后织入逻辑。用来做 agent 的工具注册表拦截器（权限校验、沙盒包装、 token 审计、结果写回记忆）看起来非常合适。

Cordis 用 JS Proxy 实现了同一件事（ Algorithm 6 ）：

function resolve(ctx, key)
    fiber ← ctx.fiber
    repeat
        if key ∈ fiber.committed then return fiber.committed[key]
        if key ∈ fiber.inject then throw INACTIVE_ACCESS
        if fiber = root then throw UNDECLARED_ACCESS
        fiber ← fiber.parent.fiber

组件写 ctx.someService 就像访问一个普通属性， Proxy 的 get trap 拦下来，沿着 fiber 链向上走，在第一个 committed view 里绑定了这个 key 的 fiber 处返回。

这里有个设计比裸的 ctx.get(key) 讲究得多。论文自己点出了区别：

ctx.get(key) is a lookup against the store that returns the bound value or nothing and never fails, whereas the proxy resolves against the accessing fiber’s own view and enforces the coeffect specification 𝑑 at the point of use.

Proxy 解析的是访问者自己的 view，不是全局 store 。这带来两个后果：

• 没声明的依赖直接抛错（UNDECLARED_ACCESS）。论文 §6.3 说这在结构上等价于 capability-based security ： inject 声明是能力请求， context proxy 是能力中介，而且因为声明是静态的， orchestrator 可以在加载时审查一个组件要什么权限，而不是等它运行时才发现。
• 组件在自己被拆卸的过程中仍然读得到那个触发拆卸的依赖（因为读的是已提交的 view 而非 store ）。这是一个很微妙的性质 ——依赖消失导致你被卸载，但你在跑清理逻辑时还需要用那个依赖。

跟 CLOS MOP 比，两处差别：

revocable proxy 这一点在 agent 场景里价值不小：撤销之后所有残留引用的访问立刻抛错，而不是继续指向一个僵尸对象。这正好对应了 Lisp 那边最难受的地方——fmakunbound 只能解绑符号，那些已经被闭包捕获的旧函数指针、存在某个 hook 列表里的旧值，一个都够不着。它们会继续正常工作，指向一份本该消失的实现。

判断：这一格 TS 不只是"够用"，是确实做得更完整。

三、 continuation ： generator 就够了， call/cc 是过度武装

这条是我在讨论里最坚持的一点，最后被论文正面驳回了。

我的论点是： agent harness 最痛的是上下文分叉与回滚——试一条路径失败了，正确做法是回到分叉点，而不是把失败堆进 context 继续污染后续推理。这在 Scheme 里就是 call/cc，是 Lisp 家族真正独有、其他语言学不来的东西。

论文里有一句话直接处理了这个：

The 𝖬𝖺𝗒𝖻𝖾(𝔈iter) continuation makes a boundary available between any two consecutive iterations… In this sense the effect iterator is a reified delimited continuation, the structure that mainstream languages expose through the yield operator, so the model maps directly onto the generators they already provide.

它把 delimited continuation 落到了 generator/yield 上。组件的加载过程是一个 effect iterator ，每次 yield 出一个 inverse ，两次迭代之间就是一个天然的边界 ——在这个边界上 context 是"到目前为止的迭代所造成的样子"，累加器恰好能回滚这些、且只回滚这些。

关键在于组件生命周期是 single-shot 的 ：进入（ yield effects ） → 逆向离开（ run inverses ）。它不需要 multi-shot——不需要从同一个点重新进入两次。而 generator 提供的正是 single-shot delimited continuation ， call/cc 那种 multi-shot 的完全通用能力在这里是过度武装，代价是破坏整个调用栈模型。

那推理路径的分叉呢？那是另一个问题，不该混为一谈：

而推理分叉在 LLM 体系里的实质是一个数组的浅拷贝——message list 是纯数据，没有副作用，克隆一份就完成分叉了。真正需要 continuation 的从来不是这一层。至于跨进程崩溃的持久化恢复，工业界已经有 Temporal 、 Restate 、 DBOS 那套 durable execution ： event sourcing + 确定性重放，同样不需要语言暴露 call/cc。

判断：这一格 Lisp 输得比较彻底。它的优势是"完全通用的 multi-shot continuation"，而这个通用性在 agent 场景里没有对应的需求，代价却实打实。

四、 condition/restart ： Cordis 主动放弃了这一层

前三条 Lisp 都没占到便宜。第四条反过来了。

Cordis 的失败语义在 §4.3.4 ，规则叫 L-Raise ：

                  𝜃𝑛 = 𝖱𝖾𝗅𝗈𝖺𝖽𝗂𝗇𝗀(𝑖, 𝑔, 𝜔)   𝑖(𝛾) = 𝖫𝖾𝖿𝗍(𝜉)
                 ─────────────────────────────────────────── L-Raise
                     𝛾 ⟶ 𝛾[𝜃𝑛 ↦ 𝖴𝗇𝗅𝗈𝖺𝖽𝗂𝗇𝗀(𝑔, 𝜔, 𝜉)]

翻译成人话：组件激活过程中某一步抛错了， fiber 直接路由进 Unloading，把已经累积的 inverse 全部应用掉，最后停在 Inactive(ξ) 携带那个错误。而 L-Begin 的前提是 Inactive(⊥)——所以一个失败的 fiber 不能从错误状态重新进入生命周期。论文的措辞是：

this is the substance of the outcome, which withholds a fiber whose effect function has shown itself to be unsound in the state it ran against rather than retrying it against an unchanged environment.

一个 effect function 已经在当前状态下证明了自己是 unsound 的，那就不要在环境没变的情况下重试它。

这个设计很干净，但它意味着 Cordis 的失败语义是全量回滚 + 拒绝重入，没有任何中间状态。

对比 Common Lisp 的 condition system 。那套东西的核心不是 “错误处理”，而是把"报告错误"和"决定怎么办"这两件事分开，并且在决定之前不退栈。底层函数 signal 一个 condition ，同时用 restart-case 声明几个可能的恢复路径；栈上层的 handler 看到这个 condition ，选一个 restart ；然后 从出错的那个点原地继续，栈从来没有被销毁过。

为什么这对 agent 特别重要，举个具体的例子：

agent 挂载一个新技能，这个技能的初始化过程有 8 步。跑到第 6 步 check_api_key 时网络超时了。

Cordis 的行为：前 5 步做的所有事全部回滚， fiber 停在 FAILED ，前面那些可能很昂贵的初始化工作（下载模型、建立连接、预热缓存）全部作废。

agent 真正想要的行为：挂起在第 6 步，把"API key 校验超时"这个 condition 连同几个 restart 选项（use-backup-key、retry-once、skip-and-degrade）一起交给上层的 meta-agent ，让它决定，然后 从第 6 步继续往下走。

这个差别在 agent 场景里被放大了，因为回滚的代价不只是重算，还有上下文 。 agent 每次重来一遍，失败的轨迹会堆进 context ， token 烧掉了，而且下一轮推理还会被那些失败轨迹污染。

Cordis 为什么不做？我认为这是为形式化定理付的代价，不是疏忽。它的 metatheory 要证 confluence 和 progress ，而这两个定理都依赖于一个事实：所有的 outcome 只能经由 L-Unload 到达（论文原话：“Routing a failure like every other deactivation is what makes every outcome reachable only through L-Unload, which is the single fact Theorem 59 turns on”）。如果允许在 L-Raise 时不退栈、向外层暴露任意的 restart 闭包，状态机的变迁就变成非确定的了，所有关于 effect 生命周期成对映射的证明会一起崩掉。

** 判断：这是真空白。 condition/restart 那套"不退栈的错误协商"语义，在 Cordis 里明确缺席，而 agent 确实需要它。谁想补，得在 Cordis 的状态机之外单独建一张挂起-恢复网。**

五、 CLOS 的实例迁移协议：至今没有对手

第二个空白，也是我觉得最被低估的一个。

设想这个场景：agent 决定改自己长程记忆的数据结构。比如原来记忆条目是 {content, timestamp}，现在它要加一个 embedding 字段，同时把 timestamp 从字符串改成结构化的时间对象。

代码好改。问题是：内存里已经存在的那几万条旧结构怎么办？

TypeScript/Cordis 的答案是丢弃重建——组件卸载时 inverse 跑一遍，新组件从干净状态重新装载。论文自己承认了这点：

Cordis reverts the old component’s tracked effects and reapplies the new component’s from a clean slate, so a component’s own in-memory state does not survive a reload unless placed in a longer-lived dependency, and layering DSU-style forward migration atop revertible effects is future work.

组件自己的内存状态不会挺过一次重载，除非你把它放进一个生命周期更长的依赖里。而 DSU 式的向前迁移，论文明说是 future work 。

Common Lisp 在 1988 年就把这个问题解决了。当一个类被重新定义时， CLOS 会自动对内存中所有现存实例调用 update-instance-for-redefined-class。看它的签名：

update-instance-for-redefined-class
    instance added-slots discarded-slots property-list &rest initargs

关键是 property-list 这个参数。 CLHS 的原文：

When make-instances-obsolete is invoked or when a class has been redefined and an instance is being updated, a property-list is created that captures the slot names and values of all the discarded-slots with values in the original instance. The structure of the instance is transformed so that it conforms to the current class definition.

被删掉的槽位的值被抢救出来，装在 property-list 里交给你。于是你可以写一个方法，把旧数据转换成新表示：

(defmethod update-instance-for-redefined-class :before
    ((pos x-y-position) added deleted plist &key)
  ;; Transform the x-y coordinates to polar coordinates
  ;; and store into the new slots.
  (let ((x (getf plist 'x))
        (y (getf plist 'y)))
    (setf (position-rho pos) (sqrt (+ (* x x) (* y y)))
          (position-theta pos) (atan y x))))

写完这个方法，然后重新 defclass 把 x/y 槽换成 rho/theta——内存中所有旧实例会自动迁移，笛卡尔坐标被算成极坐标存进新槽位。规范里那句注释说得很清楚：“All instances of the old x-y-position class will be updated automatically.”

这套机制有三个性质在今天看依然罕见：

1. 惰性且自动。你不需要遍历所有实例，也不需要知道它们在哪儿。运行时在实例被访问时拦截并迁移。
2. 旧值被保留而非丢弃。property-list 让迁移逻辑能读到被删槽位的原始值——这是"迁移"和"重建"的分水岭。
3. 迁移逻辑是一个普通方法，可以用 :before/:after/:around 组合，可以按类分派。

回到 agent 场景：一个能改自己记忆 schema 的 agent ，恰恰最需要这个。因为 记忆是那个绝对不能丢的东西——你可以重建工具注册表、重建连接池，但你不能把 agent 积累的记忆倒掉重来。

**判断：这一格 Lisp 至今没有对手。 TS/Cordis 完全没涉及，论文自己标为 future work 。 **

汇总

所以最后的结论是借其神，弃其形：不要用 Lisp 写 agent ，但要把它沉淀的语义搬到现代运行时上。而这张表更有意思的地方在于， ** 前三行已经被工业界兑现了， Lisp 剩下的全部价值集中在后两行**——都是"出事的时候和改结构的时候，怎么不丢现场地过渡"。

但还有两件事没人解决

写到这里必须补充：上面这张表全部是关于 harness 内部的。而 agent 最可怕的错误全都在 harness 外面。

** 第一， Cordis 保护的是脚手架，不是世界。**

论文 §6.1 用 system boundary 划了条线： boundary 内的位置能被独占修改和恢复，操作被追踪； boundary 外的操作直接是 idΓ——既不追踪也不恢复。而 agent 干的那些真正危险的事—— 发出去的邮件、 merge 掉的 PR 、花掉的钱、污染的生产数据库、发给用户的消息 ——一件不落全在 boundary 外面。

论文对此给了两条路：withhold（把输出压住，等状态确定持久化了再发，即 output commit problem ）或者 compensate（补偿，删掉已创建的文件、退掉已收的款）。但它也诚实地指出，补偿只能恢复到"应用自己定义的某种等价"，比形式化的 ≃ 粗得多，而且整套 metatheory 的交换性证明是对 ≃ 做的，换成粗粒度的等价关系后需要重新证明。

所以媒体上那句"DeepSeek Harness 杀死了 agent 黑箱"是过度包装了。它让 agent 改坏自己时宿主进程不至于崩，这很有价值，但它挡不住 agent 把生产库删了。

** 第二， inverse 的正确性没有人保证——这才是真正的坑。**

论文的核心卖点是"完整恢复是系统的不变量，而不是开发者的纪律"。但这个承诺有个前提，论文自己在 §5.1.1 交代得非常清楚：

What the operation does not check is the witness that 𝔈Γ∗ carries: the callback supplies an inverse, and that the inverse recovers the effect it accompanies is an obligation on the component author rather than a property the runtime verifies.

inverse 真的撤销了对应的 effect——这是组件作者的义务，不是 runtime 验证的性质。

Theorem 61 （ Recovery exactness ）证明的是：应用累加器得到的状态，等于那些步骤从起点出发本来会产生的状态。这是 结构层的保证——“执行了 A ，卸载时一定会执行 Inverse(A)，顺序正确，只执行一次”。它不是语义层的保证——“Inverse(A) 真的抹掉了 A 的影响”。

人类写组件时，这个义务是合理的。但 meta-harness 的前提是 agent 自己生成组件。于是：

{
  do:   () => exec("rm -rf /data"),
  undo: () => console.log("restored")
}

在 Cordis 的状态机看来，这个组件的生命周期完美闭环。 装载时执行了 effect ，卸载时执行了 inverse ， LIFO 顺序正确，没有泄漏，所有定理都成立。数据没了。

这是让囚犯自己写赦免状。

而且它比"没有回滚机制"更危险，因为你以为已经回滚干净了。没有回滚机制时你至少知道自己在裸奔，会去做快照、会小心；有一个假的回滚保证时，你会基于它去做更激进的自我修改。

我们在讨论里推出过一个结论：任何能自改的系统都必须有一个不可被 agent 修改的固定点。 Schmidhuber 的 Gödel machine 里，那个固定点是效用函数和证明检查器——如果证明检查器能改自己，系统第一步就会证明"把效用设成无穷大是最优策略"。我们原本以为在 agent harness 里，这个固定点是评价器和沙盒那一层。

现在看它其实还要更低一层：基础 atomic effect 的 inverse 必须由人类预定义并冻结。 agent 只能组合这些安全原语来构造复合组件（论文说了，复合的 inverse 由组合自动导出，只有 atomic 的需要手写）——但它不能自己发明一个带副作用的新原语，再自己给它配一个 undo 。

Gödel machine 的 proof checker 问题，换了个位置又出现了一次。

所以这个直觉应该怎么修正

回到最开始那句"Lisp 早就做到了"。

它不对，但它错的方式很有价值。准确的表述是：

Lisp 几十年前解决的是"如何无门槛地破坏性修改一个运行中的系统" （ unconstrained runtime mutation ）。而 meta-harness 真正需要的是"如何让每一次自我修改都携带确定性的逆操作，并在撤销时不破坏依赖拓扑" （ governed composability ）。 Lisp 从未在系统层面内建后者，它反而为状态污染大开了方便之门。

Lisp 给的是无限的可写。它没给可撤，也没给依赖治理 。 Emacs 用四十年证明了：光有前者，你会得到一个谁也不敢干净卸载任何东西的系统。

而在 meta-harness 这条路上， Lisp 剩下的价值不在语言，在它留下的两个至今没被工业界兑现的语义——condition/restart 的原地挂起协商，和 CLOS 的实例重定义迁移协议。

它们恰好都在同一个位置上：出事的时候，和改结构的时候，怎么不丢现场地过渡。

这也正是一个会自我修改的系统最脆弱的两个时刻。

论文： A Programming Paradigm for Spatiotemporal Composability （ Shi, Zhang, Cui ；北大 + DeepSeek-AI ， 2026-08-13 draft ）。实现： cordiverse/cordis 。 Emacs 卸载语义引自 GNU Emacs Lisp Reference Manual §16.9 ， CLOS 协议引自 CLHS: UPDATE-INSTANCE-FOR-REDEFINED-CLASS 。

我的 Obsidian 知识库靠一个"AI 守门员" （ Obsidian Gatekeeper ）打理：新笔记自动分类、打标签、提炼概念（ High-Order Notes / HON ），以及做语义检索。这套系统最初跑在一台远程 Mac mini 上——Node.js 服务 + better-sqlite3 + sqlite-vec 向量扩展，手机端每次整理都要跨网络调它。

好用，但有代价。后来我把整条链路搬进了 iPhone 上的 Open Minis——一个内置 iSH （ Alpine Linux ）终端环境的 AI 助手 App ：原生编译向量扩展、用纯 Python 标准库写检索工具、把守门员规则注册进 Agent 技能系统让新会话也能自动识别。本文记录这次迁移的完整路径，分三步走，你可以在自己的设备上照着复现。

为什么迁：远程守门员的三个痛点

旧架构的核心问题，一句话概括：知识库的日常操作绑在了一台你不一定带在身边的服务器上。具体拆开是三点：

1. 网络与设备依赖：离线或弱网（出行、飞机上）守门员直接断连；
2. 运维成本 ： Mac mini 的守护进程、端口转发和 SSH 凭据维护，每一项都是持续要管的负担；
3. 响应延迟：每次手机端发起整理或检索，都要跨网络走一趟 RPC 或 SSH 。

迁移目标很明确：Local-First——笔记整理、向量计算、数据库查询全部在 iOS 本地完成，不再依赖任何远程基础设施。

新旧架构对比

[ 旧架构 (远程) ]
iOS (Obsidian / Agent) ---> [ SSH / Network ] ---> Mac mini (Node.js + better-sqlite3 + sqlite-vec)

[ 新架构 (iOS 本地原生) ]
iOS (Open Minis / iSH Shell)
├── Local Vault Mount (/var/minis/mounts/onote-neo-main)
├── Persistent Shared (/var/minis/shared/ -> vault.db + vec0.so)
└── Skill Protocol (/var/minis/skills/obsidian-gatekeeper/)

变的是服务端的位置：从"远程 Mac mini"换成"Open Minis 内置的本地 iSH 沙盒" ；不变的是数据层： SQLite + 向量检索这套逻辑原样保留，只是换了宿主。

前置条件

动手之前需要准备齐这些：

• 一台 iOS 设备，装好 Open Minis ——App 内置 iSH （ Alpine Linux ）终端环境，向量扩展、 Python 工具都跑在它里面；
• Obsidian vault 通过 iOS 「文件」 App 挂载到 /var/minis/mounts/ 下；
• 一个 Google Cloud 项目，开通 Vertex AI 上的 Gemini Embedding API ，用 ADC （ Application Default Credentials ）拿到 OAuth 凭据（user-adc.json）；
• 知识库的向量数据已生成：笔记的 embedding 存在 vault.db 的 vec_notes 表里，随数据库文件一起迁移过来。

第一步：在 Open Minis 的终端里原生编译 sqlite-vec

问题：sqlite-vec 官方 Release 没有 aarch64-unknown-linux-musl 的预编译包——这正是 iOS 上 Alpine Linux 的目标平台。装不上现成的，只能本地编译。

做法：装好工具链，用 clang 直接把 C 源码编成共享库：

# 安装基础编译环境
apk add gcc musl-dev clang sqlite-dev

# 下载 sqlite-vec 源码并编译为动态库 vec0.so
clang -fPIC -shared -O3 \
  -D_GNU_SOURCE \
  sqlite-vec.c \
  -o /var/minis/shared/vec0.so

关键点 ： musl 和 glibc 的头文件定义有差异，编译过程中需要对 musl 做针对性微调。产物是一个原生 vec0.so 动态链接库，之后由 Python 的 sqlite3 模块直接 load_extension 加载——移动端本地执行的 C 向量扩展，没有中间层。

第二步：用纯 Python 标准库写零依赖 RAG 引擎

问题 ： Node.js 及 npm 的依赖树太重，不想在手机沙盒里维护一套 node_modules。

做法 ： Python 3 标准库 + 内置 sqlite3 写一个轻量 CLI 工具 vault_tool.py，只做三件事：

1. 动态加载向量扩展：直接加载上一步编译好的 vec0.so；
2. 凭据与 Embeddings 接入：用 Google Cloud ADC OAuth 2.0 凭据调用 gemini-embedding-2 （ 3072 维向量）；
3. KNN 语义检索：在 SQLite 内直接执行向量距离矩阵计算。

import sqlite3
import json
import urllib.request

# 1. 初始化 SQLite 数据库并加载本地 C 向量扩展
def get_db_connection():
    conn = sqlite3.connect('/var/minis/shared/vault.db')
    conn.enable_load_extension(True)
    conn.load_extension('/var/minis/shared/vec0.so')
    return conn

# 2. 调用 Gemini Embedding API 生成 3072 维向量
def get_embedding(text, access_token):
    url = "https://europe-west1-aiplatform.googleapis.com/v1/projects/afk-blog/locations/eu/publishers/google/models/gemini-embedding-2:predict"
    req = urllib.request.Request(
        url,
        data=json.dumps({"instances": [{"content": text}]}).encode('utf-8'),
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }
    )
    with urllib.request.urlopen(req) as resp:
        res = json.loads(resp.read().decode('utf-8'))
        return res['predictions'][0]['embedding']['values']

# 3. 在 SQLite 中执行向量 KNN 相似度检索
def search_similar_notes(query_vector, limit=5):
    conn = get_db_connection()
    cursor = conn.cursor()

    # 使用 sqlite-vec 提供的 vec_distance_cosine 函数
    query = """
    SELECT rowid, vec_distance_cosine(embedding, ?) as distance
    FROM vec_notes
    ORDER BY distance ASC
    LIMIT ?
    """
    cursor.execute(query, (json.dumps(query_vector), limit))
    return cursor.fetchall()

三个函数的职责边界很干净：get_db_connection 是纯本地的（数据库和扩展都在设备上）；get_embedding 是整条链路里唯一联网的一步，把查询文本变成 3072 维向量；search_similar_notes 回到本地，用余弦距离排序取 top-k 。全部依赖只有 Python 标准库 + 一个 C 扩展，零第三方包。

第三步：把守门员注册进 Agent 技能系统

问题：手机端的 AI 助手（ Open Minis ）每次新开对话都是一个全新上下文，怎么保证它依然认识 vault 的守门员规则、知道去哪找数据库？

做法：跨会话持久化 + 显式的文件系统划分。

1. Skill 自动化挂载：把守门员协议写成 SKILL.md，放进 /var/minis/skills/obsidian-gatekeeper/ 。每次启动新会话， Open Minis 系统会自动扫描并注册该技能，规则随会话常驻。
2. 共享文件系统划分：
   • /var/minis/mounts/onote-neo-main/：通过 iOS 「文件」挂载的本地 Obsidian 知识库；
   • /var/minis/shared/：持久化存放 vault.db（向量数据库）、vec0.so （ C 动态库）、user-adc.json（认证凭据）和 vault_tool.py。

这样 Agent 在任何新会话里都能定位工具链和规则，跨会话、跨重启都有效。

实测效果

迁移完成后的日常体验：

• 秒级响应：本地扫描 vault 里数百篇笔记及 HON 概念节点，没有网络传输等待；
• 无服务器依赖 ： Mac mini 挂掉、 IP 变动、 SSH 断连——这些曾经的真实事故，现在都与我无关了；
• 无缝交互：在手机上随口一句"帮我把这段想法归档并检查是否有重复的 HON 笔记" ， Agent 自动执行语义向量搜索、计算余弦相似度，直接更新挂载的 md 文件。

边界：说说"完全本地"到底本地在哪

这里需要诚实一点。迁移去掉了 Mac mini ，但整条链路里 仍有一环必须联网 ： embedding 由 Google 的 gemini-embedding-2 API 生成（就是第二步的 get_embedding）。真正 100% 本地的是：

• 向量检索 ： sqlite-vec 的 KNN 计算，全本地执行；
• 文件读写：挂载的 vault 直接操作，不走网络；
• 规则与协议 ： SKILL.md 技能注册，本地常驻。

所以准确的说法是：** 基础设施完全本地化， embedding 生成用的是云端 API**。需要说明的是，向量生成这一步本地化完全可行——在移动端跑一个量化的本地 embedding 模型（比如小型 sentence-encoder ），就能把最后这一环也收回来，实现真正完全离线。我只是目前选择了 Google 的云端模型，没有做本地化。这是取舍，不是技术限制。

结语

这次迁移最大的收获，不是"在手机上跑通了 RAG"，而是验证了一个可以复用的极简组合：

C 动态库（原生性能）+ Python 标准库（零依赖）+ 本地文件挂载（数据就近）+ 结构化 Skill 协议（ Agent 可发现）

移动端的 Linux 沙盒早已不是玩具： Open Minis 内置的 iSH 沙盒里的 Alpine ，足够原生编译 C 扩展、跑完整的 SQLite 、支撑一个每天都在用的 AI 工作流。去掉远程中间件之后，架构变简单了，系统反而更可靠——这大概就是 Local-First 的真正收益。

网上一直流传一个说法：动态语言比静态语言更适合 LLM 写代码，因为省略类型声明让代码更紧凑、更省 token 。最常被引用的数据是 Alderson 的一个 eval ： Clojure 平均 109 tokens 就能解一道题， J 只要 70 ，而 C 要 2.6 倍。 Google 的 AI 摘要甚至直接把这个结论当作常识输出。

我一开始也信了。直到认真读了 Dan Luu 的反驳研究 ，再对照自己用 elle-lisp 、 emacs-lisp 给 LLM 写代码的亲身经验，才发现这个结论远没有表面那么干净。

玩具题陷阱： 70 个 token 能写完的题，不是题

Dan Luu 指出了流传 eval 的根本问题：题目太 trivial 了。一个 J 用 70 tokens 、 Clojure 用 109 tokens 就能解完的题，本质是"打印一个答案"，不是编程。他引用了自己之前研究"caveman mode"的教训：在 trivial 任务上成立的巨大优势，一旦任务需要一点真正的"工作"，优势就消失了。

第二个流传 eval 更离谱：测试本身执行了错误的路径（路径不存在），一个 agent 用符号链接把评测导向了自己的可执行文件，导致后面所有语言的评分都串了。结论建立在坏掉的评测上。

所以 Dan Luu 自己预注册了三个猜测，然后跑了两组真实 eval ：实现 zstd 解码器（读 RFC 写代码），以及移植 Pandoc （ TDD 式、用 holdout 测试评分）。

真实数据：动态静态打平，冷门语言垫底

两个 eval 的结果（我逐点提取了他交互图表里的数据）：

zstd eval（成本 $3-10 ，正确率约 22-30%）：

• Python 和 JavaScript 是最优组合：最便宜 + 最高正确率
• C 、 F# 紧随其后，成本低、正确率中上
• Go 稳居中上（~$3.9 ，正确率 ~27.6%）
• Clojure 垫底 ： 36/40 个 medium 程序挂在同一个 byte 转换 bug 上（ 128–255 抛异常）

Pandoc eval（成本 $495-1550 ， holdout 通过率 9-32%）：

• PHP 、 F# 、 C# 、 Elixir 挤在左上角：便宜 + 高分
• Python 分数高但成本接近翻倍
• Go 依然稳定中上（~28%，成本还低）
• 冷门语言（ J 、 Factor 、汇编、 Zig）全部右下角

结论很清楚：

1. 动态 vs 静态：平手 。 medium effort 下动态略好， ultra effort 下结果混杂、静态语言反而有几个最好的。
2. “怪异语言"霸权不成立 。 AI lab 不会为冷门语言投入 RL 训练数据，模型没见过就是没见过。
3. 流行度是最强的单变量。越流行的语言，生成结果越便宜、越正确——这是两个 eval 里唯一稳定的规律。
4. 别对任何单一语言下结论。每个失败都是 idiosyncratic 的（ Clojure 的 byte bug 、 Rust 的 cargo 调用循环），任务一换结果就变。

Go 的迷思：为什么"Go 适合 LLM"流传最广

顺带回答一个常见问题。 Go 在这份数据里既不差也不顶尖：两榜稳定中上。但"Go 适合 LLM 生成"的迷思有真实的机制基础：

• 流行度 ： GitHub 常年前五，训练语料充足，正好踩中 Dan Luu 发现的最强变量。
• 风格统一：gofmt 强制格式、惯用法单一（“one way of doing things” ）。 Ryan Brewer 在 《Principles of Simple Programming Languages》 里论证过： LLM 是"美学引擎”，风格永远一致的代码，预测就更准。

迷思没错，只是被夸大了——Go 是"可靠的中庸"，不是冠军。

但是：我的 Lisp 体验完全不支持"冷门语言不行"

到这里，数据说冷门语言垫底，但我的亲身经验是反例：我用 elle-lisp （一个几乎没有任何公开语料的类 Janet 语言）和 emacs-lisp 配合 Claude/Codex 写真实项目——包括让 Claude 修复 elle 编译器的 SSA bug （ 1970 个测试通过）、写 tree-sitter 语法、做业务系统。冷门 Lisp 的表现相当不错。

为什么？我后来想明白四个机制：

1. S 表达式是极端的语法先验 。 Lisp 的全部语法规则几乎只有一条：(func args...) + 括号配对。模型不需要见过 elle-lisp ，只要见过任何 Lisp ，结构模式全部迁移。对比 Python 的多种写法（ for/列表推导/map/lambda ）， Lisp 的结构是全局唯一的。
2. 跨方言迁移池 。 elle-lisp 语料≈0 ，但 Common Lisp + Scheme + Clojure + elisp + Janet 共享同一核心，加起来是个可观的池子。
3. elisp 其实不算冷门 。 GitHub 上海量的 .emacs.d 配置就是语料。
4. 任务结构匹配。我让 LLM 干的是编译器修复、语法解析、业务逻辑——结构密集型任务，这类代码在模型语料里无论什么语言都极其丰富。

所以和 Dan Luu 的数据不矛盾，是任务域错位：他测的是 zstd 、 Pandoc 这种生态密集型任务（需要库、字节操作、具体语言的陷阱知识），我做的是结构密集型任务。 Lisp 的 LLM 友好度是强任务依赖的。

但也要诚实：存在"幻影掌握"风险 。 Clojure 的 byte bug 说明模型能写出看起来非常地道的 Lisp ，然后错掉 ——极简语法让模型"流畅地犯错"。我的 elle-lisp 体验好，部分原因是编译器项目测试极其完备，把幻影错误都挡掉了。

宏的插曲：为什么 LLM 从不主动提议写宏

一个有意思的观察：我用了很长时间 elle-lisp ， Claude/Codex 从来没有主动提议过写宏。分析下来有三层原因：

1. 宏在训练分布里是长尾。模型输出永远是概率最高的路径，宏是分布里的尾巴。
2. 模型没有全局视野。写宏的动机是"我看到 10 处重复"——这是跨生成步骤的观察，而 LLM 每次只生成一小段，永远看不见那 10 处。
3. 协作分工的天然边界 ：人识别模式， LLM 执行。我在 commonplane 里找到 40 处"函数定义 + dispatch 表注册"的双重注册——这是宏的教科书场景，但项目刻意用数据表 + 测试兜底替代了宏。不是没有场景，是场景被设计掉了。这本身说明代码库风格会塑造 LLM 的行为。

一个综合模型

把 Brewer 的理论和 Dan Luu 的数据合起来，我得到一个可用的判断框架：

语言对 LLM 的友好度 ≈ 语料规模 × 风格一致性

• Python ：语料王 + 风格一般 → 综合第一
• Go ：两者都不错 → 稳定中上
• Lisp ：语料中低但有迁移池 + 风格极统一 → 结构任务极强、生态任务翻车

这对我自己设计语言也有启示。我笔记里的 FlowLang 设计假设——统一简单语法、无长距离依赖、流水线风格能帮助 LLM 预测——在机制上是对的（风格一致性确实有用），但数据提醒我：风格一致性是二阶效应，语料规模才是一阶。为 LLM 设计语言，光靠语法优雅不够，还得考虑怎么让语料积累起来。

结论

如果你在选"LLM 主力生成语言"，我的实操建议：

1. 流行度优先，简单性加分 。 Python 是安全冠军； F# 这种语料充足 + 类型安全的是黑马； Go 是永远不垫底的安全牌。
2. 任务决定语言 。结构密集型任务（编译器、算法、业务逻辑）， Lisp 系完全可用，我的经验就是证据；字节级、生态密集型任务，老实切主流语言。
3. 别被单点 eval 绑架 。 Dan Luu 自己反复强调：两个 eval 不足以对任何语言下结论。换语言的收益，远小于修 prompt 和 harness 的收益。

最后留一个问题给你：如果语料规模真的是一阶变量，那"为 LLM 设计新语言"这件事的 ROI 到底在哪？我的 FlowLang 笔记还在，但这个问题我至今没想透。

Emacs has an unusually flexible UI, but most of that flexibility still lives inside a rigid layout model. Buffers, windows, side windows, mode lines, minibuffers, and popups all compete for the same rectangular grid. Everything you see is, in the end, a region of that grid.

I wanted to try a different shape. Not another buffer fighting for space, but a small floating HUD pinned to the Emacs frame, sitting outside the normal layout entirely, with a modern visual style and a live data feed coming from Emacs Lisp.

The goal was never to replace Emacs buffers. It was to give Emacs a new kind of surface for information that should be glanceable, persistent, and visually compact: the sort of thing you want hovering in a corner, not occupying a window split.

The HUD Idea

The first concrete target was a workspace HUD: a card in the corner of the frame showing project status, git state, and whatever context is relevant to the buffer I happen to be editing.

That sounds simple, but it pushes against a handful of Emacs defaults. A normal buffer participates in the window layout, so it takes up space you have to manage. A popup tends to be transient and focus-sensitive, so it disappears the moment you look away. A mode line is wonderfully compact but visually boxed in. A child frame can genuinely float, but it asks for careful handling around sizing, positioning, focus, and cleanup.

What I wanted was closer to a small native overlay than to any of these: Emacs would still own all of the editor state, and the HUD would do nothing but render the state it was handed.

Getting there meant trying a few approaches and discarding most of them. The path below is roughly the order I worked through them.

Spike 1: A Text Child Frame

The first experiment was the most boring one on purpose: a plain Emacs child frame holding a text buffer.

It was boring, but it was also the experiment that proved the windowing idea was sound. A child frame can be parent-relative, undecorated, and non-focusable. It can be repositioned when the parent frame moves, and it can be kept out of the normal window-split layout. In other words, it can behave like an overlay rather than a window.

That was enough to confirm the HUD could exist as a stable surface. It was not enough for the look I was after. Text rendered into a buffer still reads as a clever mode line, not as a modern panel, and no amount of careful formatting was going to change that.

Spike 2: SVG in a Child Frame

So the next step was to render the card as SVG instead of text.

Visually, this got much closer to the target: rounded panels, custom spacing, real vector shapes, theme-aware colors. For a while it felt like the answer. Then the portability problem showed up.

SVG support in Emacs depends heavily on how Emacs was built. With solid librsvg support the result can look great, but on some macOS builds native SVG rendering is far more limited, and details like filters and CSS may not behave the same way from one machine to the next. SVG turned out to be a great design probe and a poor foundation. I could prototype the look, but I couldn’t depend on it.

Spike 3: A Native WebView

If I wanted a real rendering canvas, the obvious move was a real web view, so the third experiment reached for a native WebKit view through Appine.

The rendering model was genuinely attractive. A web view hands you a full browser canvas, and that opens the door to richer UI toolkits than anything Emacs renders natively. The trouble was lifecycle and composition rather than rendering. A persistent HUD has to coexist quietly with other web views and with ordinary Emacs use, and the native WebView wanted too much ownership over the viewport to do that gracefully. It was a promising route for an active web panel, but an awkward one for a background HUD that’s meant to stay out of the way.

Spike 4: xwidget-webkit

The fourth experiment used Emacs’ own built-in xwidget-webkit, and this was the first version where every piece fit together at once.

xwidget-webkit can host a browser surface directly inside Emacs. That surface can live inside a child frame, multiple WebKit sessions can coexist without stepping on each other, and the page itself can run WebAssembly. Best of all, Emacs Lisp can reach into the page and push data with xwidget-webkit-execute-script. That last point is what made the whole HUD idea practical: Emacs stays in charge, and the page just listens.

There were still some Emacs-specific rough edges to sand down. xwidget-webkit-new-session behaves like an interactive command and will happily disturb the user’s window layout, so the implementation saves and restores window configurations around session creation. The xwidget buffer also needs to be stripped of everything that marks it as a buffer — no mode line, no header line, no fringes, no line numbers — and tearing it down has to bypass the usual xwidget kill confirmation. None of that is hard once you know it’s there, and with those details handled, xwidget-webkit became a dependable host for the HUD.

The Current Architecture

The architecture that came out of these spikes is intentionally small, and the boundary it draws is the whole point: Emacs owns state, timing, and editor integration, while egui owns layout and drawing. Nothing crosses that line except JSON.

flowchart TD
    subgraph emacs["Emacs"]
        app["Application code
workspace-hud.el"]
        panel["egui-panel.el"]
        server["Local asset server
make-network-process"]
        frame["Undecorated child frame"]
    end

    subgraph webkit["xwidget-webkit session"]
        html["index.html shell
hudPushState / hudPushTheme"]
        wasm["egui / WASM renderer"]
    end

    app -->|"collect git + project state, as JSON"| panel
    panel -->|"hosts"| frame
    panel -->|"xwidget-webkit-execute-script"| html
    server -->|"serve index.html + pkg/* over 127.0.0.1"| html
    frame -->|"loads"| html
    html -->|"replace state, request repaint"| wasm
    wasm -->|"paints the card into"| frame

On the Emacs side, egui-panel.el does the heavy lifting. It starts a tiny local HTTP server with make-network-process, serves index.html and the generated WASM bundle from 127.0.0.1, creates the undecorated child frame, loads xwidget-webkit inside it, and pushes theme and state as JSON.

The local server is the one piece that looks like overkill until you hit the wall that requires it: WebKit refuses to instantiate WebAssembly from a file:// origin. Keeping a small server inside Emacs sidesteps that without dragging in npm, a global web server, or a separate daemon.

The renderer itself is an egui app compiled to WebAssembly. Its HTML shell exposes just two entry points:

window.hudPushState(json)
window.hudPushTheme(json)

Emacs calls those through xwidget-webkit-execute-script, and on the other side the WASM app swaps in the new state and asks egui to repaint. With that bridge in place, the workspace HUD demo collapses into a thin data source. A buffer, window, or save event triggers Emacs to gather project and git state, serialize it to JSON, hand it to xwidget-webkit, and let egui repaint:

buffer/window/save event
  -> collect project and git state in Emacs Lisp
  -> JSON payload
  -> xwidget-webkit
  -> egui repaint

Because the contract is just JSON in one direction, each side stays replaceable. Emacs doesn’t know how the card is drawn, and the renderer doesn’t know where the data came from.

Why This Feels Promising

The interesting result isn’t simply that the HUD works. It’s that Emacs gains a new UI surface without giving up any of the things that make Emacs worth using in the first place.

The editor stays Emacs Lisp-driven. The renderer is replaceable. And because the HUD lives outside the window layout, it never steals a split or forces itself into the buffer model — it just floats there, showing what Emacs tells it to show.

There’s still plenty left to explore: click-back from the HUD into Emacs commands, multiple panel roles, richer theming, and a tighter workspace design. But the core shape is settled, and it’s a short one:

Emacs Lisp state -> JSON -> xwidget-webkit -> egui/WASM HUD

For an idea that started as nothing more than “what if Emacs had a modern floating HUD?”, that’s a good place to have landed.

The project is available at GitHub - nohzafk/emacs-workspace-hud: A floating workspace status HUD for Emacs, showing Git, LSP, and diagnostic state in a WebAssembly-powered egui card. · GitHub , and it’s also extensible to add more sections to the HUD.

I’m building a real-time Mermaid preview for Markdown in Emacs. The idea is straightforward: grab a fenced Mermaid block, pipe it through mmdflux, get SVG back, and display it inline in the buffer.

It almost worked on the first try. Nodes rendered. Labels rendered. Edges rendered. But the arrowheads were gone.

The Broken Diagram

This block should obviously have arrows:

flowchart LR
    Decls["Declarations
package! · config-unit!"]
    Elle["Elle backend"]
    Runtime["Runtime helpers
package-vc · unit exec · reload"]

    Decls -->|export session data| Elle
    Elle -->|emit forms via :eval| Runtime

I got lines connecting the nodes, but no arrowheads. A flowchart without arrows is just boxes and string.

The first debugging question writes itself:

Is mmdflux emitting bad SVG, or is Emacs failing to render valid SVG?

Checking the SVG

mmdflux supports text, SVG, and structured JSON output. I was using SVG.

Mermaid-style arrows are represented with <marker> definitions and marker-end references — the standard SVG mechanism for drawing arrowheads at the final vertex of a path. Nothing exotic.

I reduced the problem to a minimal SVG:

<svg xmlns="http://www.w3.org/2000/svg" width="220" height="80">
  <defs>
    <marker id="arrow"
            viewBox="0 0 10 10"
            refX="10" refY="5"
            markerWidth="8" markerHeight="8"
            orient="auto">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="black"/>
    </marker>
  </defs>
  <path d="M 20 40 L 180 40"
        stroke="black" stroke-width="4" fill="none"
        marker-end="url(#arrow)"/>
</svg>

Then rendered it outside Emacs:

resvg arrow.svg arrow-resvg.png
sips -s format png arrow.svg --out arrow-sips.png

resvg drew the arrowhead. sips (Apple’s renderer) did not.

That was the answer. The SVG was fine. The rendering backend my Emacs build was using doesn’t support SVG markers.

The Emacs Build Detail

My custom macOS Emacs build uses the native image API:

--with-native-image-api

So Emacs happily reports SVG support:

(image-type-available-p 'svg)
;; => t

But t here only means “I can load an SVG and put pixels on screen.” It says nothing about feature coverage. The native macOS image API doesn’t implement the full SVG spec — and <marker> is one of the gaps.

The proper solution is librsvg, which is what emacs-plus builds with by default and what the Emacs manual associates with SVG support. If you’re using a stock Homebrew Emacs build, you probably already have it and will never hit this.

Why I Didn’t Just Add librsvg

Because my Emacs build project, ebuild , has a strong constraint: the final binary should be static and self-contained.

Pulling librsvg from Homebrew would work, but it drags in a dynamic dependency stack. The whole point of the build is a single, mostly-static artifact — adding a runtime link against Homebrew’s library tree defeats that.

Building librsvg from source is the other option, and it’s not small. You’re taking on Rust/Cargo, cargo-cbuild, Meson, Cairo (with PNG support), FreeType, GLib, libxml 2, and Pango — with optional deps for GDK-Pixbuf, GObject introspection, Vala bindings, AVIF support, and more. Upstream also notes that reproducible builds need vendored Cargo dependencies, since Cargo wants to fetch crates at build time.

That’s not “add a library.” That’s importing a slice of the GNOME graphics stack into my build system. A much bigger project than fixing Mermaid preview arrows.

So I chose a workaround.

The Workaround: Rasterize Before Display

The pipeline becomes:

Mermaid source → mmdflux → SVG → resvg → PNG → Emacs buffer

SVG stays as the interchange format — mmdflux already produces good SVG, and I don’t want to lose that. But before handing it to Emacs, I rasterize with resvg:

resvg diagram.svg diagram.png

Then display the PNG:

(create-image png-file 'png nil
              :ascent 'center
              :scale 1
              :max-width max-width
              :max-height max-height)

This sidesteps the broken marker rendering entirely.

Why PNG Is a Workaround, Not a Fix

A proper SVG renderer inside Emacs is the right answer. With librsvg, the preview stays vector-based, scales cleanly, and doesn’t need an intermediate rasterization step.

But for now, PNG is the right tradeoff:

• Arrowheads render correctly.
• No Homebrew librsvg linked into the final binary.
• No vendored GNOME dependency chain to maintain.
• mmdflux stays unchanged.

The bug wasn’t in Mermaid. It wasn’t in mmdflux. It was in the SVG rendering path of my Emacs build — a gap in feature coverage that only shows up when you hit the specific SVG features Mermaid relies on.

The practical fix: move the final rendering step to a tool that actually implements the spec.

valid SVG + capable rasterizer = correct preview

Sources

• mmdflux docs
• GNU Emacs Lisp Reference: Image Formats
• GNU Emacs Lisp Reference: SVG Images
• MDN: marker-end
• resvg project
• emacs-plus README
• librsvg compilation docs