第 1 周 · D2约 4 小时

状态与上下文的分界：把权威状态搬出窗口

把昨天那个退化修掉：权威进度写进磁盘，窗口重置后从磁盘重建一个等效上下文。重点不是怎么写文件，而是这条分界线该画在哪里，以及为什么重建的目标是等效而不是还原。

今日目标 0/3

能说出哪三类信息必须进磁盘状态、哪两类只该留在窗口里，并各说明判断依据
能解释等效上下文与原上下文的区别，并举出一个还原原上下文反而更糟的具体情形
能通过关掉状态层让昨天的重复现象重现，用这个变异检验证明状态层真的在起作用

登录后可以勾选并保存进度。

今日目标

能说出哪三类信息必须进磁盘状态、哪两类只该留在窗口里，并各说明判断依据
能解释等效上下文与原上下文的区别，并举出一个还原原上下文反而更糟的具体情形
能通过关掉状态层让昨天的重复现象重现，用这个变异检验证明状态层真的在起作用

昨天那个退化，修法其实已经摆在眼前：进度一直在内存里躺着，只是没人把它写进下一个窗口的开场。今天要做的不是「写个文件」，而是画三条分界线。读完回到页面顶部把三条目标勾掉。

小白版讲解

白板：交代一遍会忘，写下来不会

昨天那个夜班交接的比方还没讲完。老张把手上的活口头交代给小李，小李中途换成小王，交代就没了。

修法车间里早就有了：墙上挂一块白板。 修好了哪几台、哪一台拆到一半、扭矩扳手在第三个抽屉——全写白板上。谁接班都先看白板。

白板和脑子的区别有三层，而且每一层都对应今天要做的一个决定：

白板比当班的人活得久。 老张下班了白板还在，这是「跨窗口存活」。
白板上写的是结论，不是过程。 没人会把「我先试了扳手 A 发现拧不动又换了扳手 B」写上去，只写「第三台修好了」。这是等效不是还原。
白板只有一块。 脑子里记的和白板不一致时，以白板为准。这是权威的意思。

今天要写的 work/state/run.json 就是这块白板。

分界线画在哪：权威的归磁盘，易失的归窗口

先把话说准。昨天我们发现「进度其实一直在内存里活着」——features[].passes 跨窗口没有被擦掉，昨天真正丢的是证据，不是数据。

那为什么还非得写盘？因为内存和进程同生共死。kill -9 一下、机器重启一下、容器被驱逐一下，账本就没了。人在旁边时这不要紧，你会重新起一次；跑一整夜时，没有这个人。

所以分界线是这么画的：

	住在窗口里	住在磁盘上
寿命	到下一次压缩、截断或重置为止	跨窗口、跨进程、跨机器重启
可信度	参考。它可能是几步之前的旧结论	权威。冲突时以它为准
内容	当前这一小段工作的上下文	做完了什么、正在做什么、试了几次
丢了会怎样	重建一份就行	整晚白跑，而且没人知道

还有一条容易忽略但今天必须定下来的边界：状态文件放在靶子仓库之外。

实验里靶子在 work/repo，账本在 work/state，是两个目录。写进 work/repo 会有两个后果：它会进 agent 自己的 commit（D4 的绿点里混进 harness 的簿记），而且回滚到上一个绿点时账本会被一起回滚掉——回滚的目标是代码，不该把「我已经试过三次」这种教训也一起忘掉。

三类必须写进磁盘

不是所有东西都值得持久化。判据只有一条：下一个窗口要做出正确的下一步，非知道不可的是什么？ 按这条筛，只剩三类。

第一类，做完了什么。 这是最直接的一类，昨天的重复劳动就是因为它缺席。对应 done: string[]，顺序即完成顺序。注意它存的是 feature 编号而不是描述文本——编号是稳定的，描述会随需求改。

第二类，正在做什么。 对应 current: string | null。它比第一类微妙：进程如果崩在半路，磁盘上会留下一条「正在做 F07」而 F07 既不在已完成里、也没有失败记录。这个悬空状态是有用的信息，不是脏数据——它告诉下一个窗口「F07 到底成没成不知道，先确认，别当成做完了」。丢掉它，下一个窗口要么重做一遍，要么直接跳过一条根本没做完的。

第三类，试了几次。 对应 attempts: Record<string, number>。单看一个窗口，「F23 试了一次没成」是噪声；跨五个窗口看，「F23 试了十二次都没成」是一个必须响的信号。这类信息的价值完全来自跨窗口累计，不写盘就永远攒不起来。D5 的打转检测、D6 的预算熔断，全部建立在这个计数上。

顺带还要记一样：spent，烧掉了多少窗口和多少步。它今天只是打印出来看看，D6 会拿它做熔断。

两类坚决不写

反过来，有两类信息不该进磁盘，而且理由不是「省空间」。

第一类，中间推理。 「我先看了 server.mjs 的结构，发现路由是用一个数组注册的，所以我打算……」——这段话在当时有用，结论落地之后它的使命就结束了。留着它有两个坏处：下一个窗口要花注意力去读一段已经作废的思路，而且它会把状态文件撑成一个越跑越大的日志。结论落地，过程作废。

第二类，一次性的工具回执。 某次 git status 的输出、某次读文件拿到的内容——这些东西的特点是可以随时重新获取，而且重新获取的那份才是对的。把三小时前的 git status 输出存下来喂给新窗口，比不给还糟：它会拿着一份过期快照做决定。

重建的目标是等效，不是还原

现在到今天最反直觉的一条。窗口换了，新开场该拼什么？

最自然的想法是还原：把上一个窗口的对话原样接上去。这个想法看起来无损，实际上是今天最贵的错误。

先看代价。实验里跑一个窗口（三步）产生的原始对话是 962 字符；重建出来的摘要是 175 字符。三步就差五倍多，跑一整夜是几十万 token 对几百 token 的差距。而且还原是不可持续的——上下文本来就是因为装不下才换窗口的，把装不下的东西原样塞回去，第二个窗口会立刻再次撑爆。

但真正的问题不是钱。是还原出来的上下文比摘要更难用。

把一晚上的流水原样喂回去，模型得自己从几百步里重新推断出「所以我到底做完了哪几条」。这是一次有误差、有成本、而且完全没必要的重新推断——因为这个结论 harness 手上明明已经有了，它就记在 done 里。

所以重建做的是一次有损压缩，但对决策无损：中间推理与工具回执被丢掉了（有损），而下一步该做什么这个决定所需的全部输入都在（无损）。

摘要是写给下一个窗口的自己看的

既然要摘要，就得想清楚读者是谁。

D7 那份夜跑报告的读者是人，所以它要好读、有故事线、有前因后果。今天这段文本的唯一读者是下一个窗口里的模型，所以它按机器的口味写：

结论前置，一行一件事，没有过渡句
用 feature 编号，不用「那个笔记列表的接口」这种人话指代
明确写出「更早的对话已经不存在了，不要引用」，免得它去引用自己看不到的东西

实验里重建出来的开场长这样：

TextText

—— 下面这段不是之前对话的回放，是从磁盘状态重建出来的进度摘要 ——
（每一步之后它都被写进磁盘，所以它比上一个窗口活得久。更早的那些对话已经不存在了，不要引用。）
 
进度：已完成 3 条（共 40 条）—— F01 F02 F03
已经烧掉：1 个窗口、3 步。
 
接着做的规则：从上面那份清单里挑第一条不在进度里的，做它。不要重做进度里已有的。

一百七十五个字符，换来的结果是完成条数从 3 变成 9、白干步数从 6 变成 0。

为什么状态文件是结构化数据而不是自由文本

有人会问：既然最后都要拼成一段文本喂给模型，那磁盘上直接存那段文本不就完了？

不行，而且理由很实在：harness 自己要读它。

模型只需要那段人话，但 harness 需要回答「F23 试了几次」「已完成的条数超过预算没有」「上次崩在哪条上」。这些问题对着一段自由文本只能靠正则去抠，而正则会在文案改一个字的时候悄悄失效。存成 JSON，这些都是字段访问。

所以分工很清楚：磁盘上存结构化数据，喂给模型前渲染成文本。 渲染是一个纯函数，改文案不影响 harness 的任何判断。今天 lab 里那个 summarizeState 就是这个渲染函数，它是全课唯一一处「磁盘状态转成模型上下文」的翻译。

源码导读

今天新增两个模块，读的时候重点放在三个位置。

第一个位置：原子写。 直接 writeFileSync 是「截断后再写」，进程死在这两件事之间，磁盘上就留下一个半截的 JSON。那比没有状态更糟——没有状态时下一次运行知道自己从头开始，有个半截文件时它会在解析上炸掉，或者更坏，解析出一份缺了一半的进度然后把做完的事再做一遍。

store.js

// 第 1 步：写进同目录的临时文件，并且 fsync 真按到盘上
function writeStateTemp(stateDir, state) {
  const tmp = join(stateDir, `.run.json.tmp-${process.pid}-${nextSeq()}`)
  const fd = openSync(tmp, 'wx')
  try {
    writeSync(fd, JSON.stringify(state, null, 2) + '\n')
    // 少了这一行，rename 仍然是原子的，但内容可能还在页缓存里
    fsyncSync(fd)
  } finally {
    closeSync(fd)
  }
  return tmp
}
 
// 第 2 步：原子改名。同一文件系统上，任何时刻读到的要么是旧的完整状态、
// 要么是新的完整状态，不存在中间态
function commitStateTemp(stateDir, tmpPath) {
  renameSync(tmpPath, join(stateDir, 'run.json'))
}

store.py

# 第 1 步：写进同目录的临时文件，并且 fsync 真按到盘上
def write_state_temp(state_dir: str, state: dict) -> str:
    tmp = os.path.join(state_dir, f".run.json.tmp-{os.getpid()}-{next_seq()}")
    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL)
    try:
        os.write(fd, (json.dumps(state, ensure_ascii=False, indent=2) + "\n").encode())
        # 少了这一行，rename 仍然是原子的，但内容可能还在页缓存里
        os.fsync(fd)
    finally:
        os.close(fd)
    return tmp
 
 
# 第 2 步：原子改名。同一文件系统上，任何时刻读到的要么是旧的完整状态、
# 要么是新的完整状态，不存在中间态
def commit_state_temp(state_dir: str, tmp_path: str) -> None:
    os.replace(tmp_path, os.path.join(state_dir, "run.json"))

两个细节值得停一下。临时文件必须与 run.json 同目录——rename 只有在同一文件系统上才是原子的，写进临时目录再搬过来就不是了，而这个错在本机测不出来（同一块盘），只有到了容器里挂载不同卷时才炸。临时文件名里除了进程号还要带一个自增序号——只靠时间戳会在同一毫秒内撞名，而 wx 模式撞名直接抛错，那会变成一个只在快机器上偶发的崩。

顺带说清一条能力边界：严格地说 rename 之后还要 fsync 父目录，元数据才算真落盘。本 lab 做到文件级 fsync 加原子 rename 为止，再往下是文件系统语义的话题、不是 harness 的话题，而且各平台差异很大。这是明写出来的边界，不是忘了。

第二个位置：读回来的时候不许吞错。 这一处只有几行，但它是今天最容易写错的地方。

load-state.js

// 对的写法：文件不存在返回 null（那是「全新的运行」，不是错误）；
// 存在但解析不出一份完整状态，直接抛
function loadState(stateDir) {
  const file = join(stateDir, 'run.json')
  if (!existsSync(file)) return null
  const parsed = JSON.parse(readFileSync(file, 'utf8')) // 坏了就让它抛
  if (!isRunState(parsed)) throw new Error(`状态文件坏了：${file}`)
  return parsed
}
 
// 错的写法：把一次数据损坏悄悄变成一次从头重跑。
// 无人值守时没人看得见，早上只会看到进度比预期少了一半
function loadStateSwallow(stateDir) {
  try {
    return JSON.parse(readFileSync(join(stateDir, 'run.json'), 'utf8'))
  } catch {
    return null
  }
}

load_state.py

# 对的写法：文件不存在返回 None（那是「全新的运行」，不是错误）；
# 存在但解析不出一份完整状态，直接抛
def load_state(state_dir: str):
    file = os.path.join(state_dir, "run.json")
    if not os.path.exists(file):
        return None
    parsed = json.loads(open(file, encoding="utf8").read())  # 坏了就让它抛
    if not is_run_state(parsed):
        raise ValueError(f"状态文件坏了：{file}")
    return parsed
 
 
# 错的写法：把一次数据损坏悄悄变成一次从头重跑。
# 无人值守时没人看得见，早上只会看到进度比预期少了一半
def load_state_swallow(state_dir: str):
    try:
        return json.loads(open(os.path.join(state_dir, "run.json"), encoding="utf8").read())
    except Exception:
        return None

那个 catch 返回 null 的写法，在交互式场景里是个无伤大雅的兜底；在无人值守场景里它是一类静默故障：不抛异常、不打警告，只是安静地把一整夜的进度清零重来。坏状态必须响。

第三个位置：重建的落点。 窗口边界处只有两行，但有一个决定藏在里面。

rebuild-hook.js

for (let w = 1; w <= config.windows; w += 1) {
  transcript.length = 0 // 与 D1 逐字相同：上下文照样被清空
 
  // 读的是磁盘，不是内存里那个 state 对象。
  // 内存里的进度其实一直是活的（D1 已经证明了），拿它拼一样能跑——
  // 但那样窗口边界就永远只能是一次函数调用，不可能是一次进程重启
  const disk = config.withState ? loadState(stateDir) : null
  const opening = config.withState ? rebuildContext(base, disk ?? state, features) : base
  // ...
}

rebuild_hook.py

for w in range(1, config.windows + 1):
    transcript.clear()  # 与 D1 逐字相同：上下文照样被清空
 
    # 读的是磁盘，不是内存里那个 state 对象。
    # 内存里的进度其实一直是活的（D1 已经证明了），拿它拼一样能跑——
    # 但那样窗口边界就永远只能是一次函数调用，不可能是一次进程重启
    disk = load_state(state_dir) if config.with_state else None
    opening = rebuild_context(base, disk or state, features) if config.with_state else base
    # ...

注意今天改的不是「别丢上下文」。清空那一行与昨天逐字相同，窗口照样是易失的。改的是「丢了之后拿什么接上」。

还有一件事请留意：model/mock.ts 今天一个字都没改，自检拿内容哈希钉着它。开关 withState 属于 harness 侧，绝不传进 askModel。所以昨天的退化今天自己消失，不是被特判掉的——模型甚至不知道状态层存在，它只是在它一贯认的那个位置上第一次读到了进度。

动手实验

🧪 D2 实验：把权威状态搬出窗口

代码位置：labs/agent-harness-7days/day-02-state-layer

今天的 lab 是同一份代码跑两遍：一遍关状态层、一遍开状态层，把差摆出来。练习有五处，src/state/store.ts 三处（原子写两步加读回来）、src/state/rebuild.ts 两处（摘要与拼接）。昨天的四个冻结文件逐字复制，一个字都不用改。

先读 src/core/loop.ts 里状态层那个落点，看清今天新增的两行接在哪、为什么读磁盘不读内存。
补上 src/state/store.ts 的原子写两步与 loadState，注意解析失败必须抛、不许 catch 掉。
补上 src/state/rebuild.ts 的 summarizeState 与 rebuildContext。
跑 MOCK=1 pnpm selftest 到二十七项全绿。
跑 MOCK=1 pnpm start，确认完成条数从 3 变成 9、白干步数从 6 变成 0。

跑完记得对比两份账本。这是今天最该亲眼看一遍的一条：关状态层那趟的 work/no-state/state/run.json 里同样有一份完整账本，写着 done = [F01 F02 F03]。丢的从来不是数据，是证据——账本一直在写，只是没有人把它写进下一个窗口的开场。

今天的变异检验不是「关掉状态层」（pnpm start 本来就跑了两趟）。README 里那条更值得做：把 summarizeState 里进度行的「已完成」换成「做好了」，其它一个字不动，再跑一次。