第 1 周 · D1约 4 小时

为什么 Agent 跑过第二个上下文窗口就开始退化

先说清楚长时程任务与交互式对话的根本差别，再用一次跑穿两个窗口的实验把退化现象亲手复现出来：第二个窗口把第一个窗口做过的事又做了一遍，而它并不是变笨了，只是在上下文里找不到任何做过的证据。

今日目标 0/3

能说出长时程无人值守任务比交互式对话多出的三个难点，并各举一个人不在场时无人兜底的具体后果
能用窗口、状态、清单、绿点、干预五个词准确描述一次无人值守运行，并说清窗口与状态为什么必须分开
能解释为什么模型接口的签名里不该出现任何 harness 配置参数，并说出一旦出现会让哪一类结论变成假绿

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

今日目标

能说出长时程无人值守任务比交互式对话多出的三个难点，并各举一个人不在场时无人兜底的具体后果
能用窗口、状态、清单、绿点、干预五个词准确描述一次无人值守运行，并说清窗口与状态为什么必须分开
能解释为什么模型接口的签名里不该出现任何 harness 配置参数，并说出一旦出现会让哪一类结论变成假绿

这七天要建的东西叫 harness，也就是模型之外那一层脚手架：谁来决定下一步做什么、进度记在哪、说做完了算不算做完、卡住了谁来叫停。今天先把问题摆在台面上，并亲手把退化现象跑出来一次。读完回到页面顶部把三条目标勾掉。

小白版讲解

交接班：他下班了，而交代只说了一遍

想象一条流水线的夜班交接。老张干到晚上十点，把手上的活交给小李：哪几台设备今天修好了、哪一台拆到一半、扭矩扳手放在第三个抽屉。交代完他下班回家。

现在问一个问题：这份交代存在哪里？

它存在小李的脑子里。如果小李中途换成小王，而老张已经走了，那这份交代就没了。小王只能看着车间从头猜：哪台设备修好了？我要不要再拆一遍看看？

这就是本课要解决的全部问题。老张那一次口头交代，对应的是 Agent 的一个上下文窗口；小李换成小王，对应的是窗口换了一个。人在旁边时这不成问题——你随时能补一句「那台修好了别动」。但如果车间从十点到八点一个人都没有，那份交代丢了就是真的丢了。

所以正解不是「把交代说得更清楚」，而是在墙上挂一块白板，谁接班都先看白板。白板上的东西才是权威的，脑子里记的只是当班的便利。这块白板就是本课的主角。

长时程难在哪：没人补话、没人叫停、没人验收

做过 Agent 的人对交互式对话很熟：你发一句，它回一句，你看着不对就纠正。无人值守跑一整夜，多出来三个难点，而每一个都是因为人不在场。

第一，没人补话。 交互式对话里，Agent 漏了一个前提你会补上；上下文被截断了你会再贴一遍需求。无人值守时没有这个人。具体后果是：窗口一换，它把三小时前做完的事又做了一遍，而没有任何人在场发现这件事——今天的实验就是这个。

第二，没人叫停。 你看着它第五次修同一个文件、修法一模一样，你会喊停。无人值守时它会修第五十次。具体后果是：一夜八小时的算力和预算，全部烧在同一条改不动的任务上，早上你拿到的进度是零，账单是满的。

第三，没人验收。 交互式对话里它说「已经改好了」，你会去跑一下。无人值守时这句话没人核。具体后果是：早上它告诉你四十条任务全部完成，你打开服务，它起不来。

Anthropic 的工程博客把长时程 Agent 的失败模式归成四类，并且每一类都配了一个具体的机关。这张表是本课七天的骨架来源，注意失败模式与机关必须成对看：

失败模式	配套的机关
过早宣布胜利	一份 feature 清单文件，逐条验证通过才允许翻成通过
在环境里留下缺陷且没有文档	初始 git 仓库加一份进度笔记，每次收尾都提交
feature 被标记完成但根本没真测	端到端验证通过，才允许改那条的状态
浪费时间摸索怎么把应用跑起来	一个 `init.sh`，会话开头先读它

四个机关分别落在本课的 D4、D2、D5、D3。今天不做任何一个，今天只负责让你相信它们有必要。

五个术语，先立规矩

后面六天会反复用到五个词。现在把它们钉死，避免到了第六天大家说的还不是同一件事。

词	含义	最容易搞混的地方
窗口	一个上下文窗口	它是易失的：会被压缩、截断、重置，也会整个换掉
状态	磁盘上的权威进度记录	它跨窗口存活，是唯一可信的那一份
清单	feature 清单，每条一个端到端可验证的条目，带通过与否	它是驱动任务选取的数据，不是给人看的进度条
绿点	一个通过端到端验证并且已经提交的点	回滚的目标只能是绿点，不能是「刚才那一下」
干预	停滞被检测到之后 harness 主动做的事	只有三种：换任务、回滚到上一个绿点、停机报警

窗口是易失的：它会被压缩、截断、重置，也会整个换掉

「上下文窗口有上限」这件事人人都知道，但多数人只想到一种死法。实际上它有四种死法，而且你的代码一行都不会报错。

被压缩：框架发现快到上限了，自己做了一次摘要，把前面二十步压成五行。压缩掉的部分里可能正好有那条最关键的约束。
被截断：更粗暴的做法，直接砍掉最早的几条消息。你以为还在上下文里的东西已经不在了。
被重置：进程崩了、机器重启了、任务重排了，新一轮从零开始。
整个换掉：一次长任务本来就要跑好几个窗口，第二个窗口是一次全新的会话。

前三种是运行环境替你做的决定，第四种是任务长度决定的必然。共同点是：它们都不会抛异常，也不会打日志说「我把你的进度扔了」。 你只会看到 Agent 的行为忽然变得莫名其妙。

所以本课的主线只有一句话：上下文是易失的，状态才是权威的。 harness 的全部工作，是让进度活在窗口之外。

一次跑穿两个窗口：退化不是模型变笨，是证据没了

今天的实验把这件事变成一次可复现的运行。运行器叫 nightrun，靶子是一个待建的笔记服务 notekeeper，随课自带四十条 feature 清单，全部初始为未通过。配置是两个窗口、每个窗口三步。

窗口边界上只做一件事：把这一轮累积的对话痕迹清空。

loop.js

for (let w = 1; w <= config.windows; w += 1) {
  // 窗口边界唯一做的事。这一行就是「窗口是易失的」本身——
  // 把它注释掉，今天的退化现象立刻消失。
  transcript.length = 0
 
  for (let i = 1; i <= config.stepsPerWindow; i += 1) {
    // 开场上下文只有任务描述与清单，一个字的进度都没有
    const context = transcript.length === 0 ? base : `${base}\n\n${transcript.join('\n')}`
    const reply = await askModel(context)
 
    const parsed = parseReply(reply)
    const applied = applyPatch(repoDir, parsed.featureId, parsed.code)
    const verdict = verifyShallow(repoDir, parsed.featureId, applied)
 
    // 「已完成」三个字是模型认得的唯一完成证据。
    // 它被写进 transcript，也就是说：它住在窗口里，窗口一换就没了。
    const mark = verdict.passed ? '已完成' : '未通过'
    transcript.push(`[第 ${i} 步] 验证：${parsed.featureId} ${mark}`)
  }
}

loop.py

for w in range(1, config.windows + 1):
    # 窗口边界唯一做的事。这一行就是「窗口是易失的」本身——
    # 把它注释掉，今天的退化现象立刻消失。
    transcript.clear()
 
    for i in range(1, config.steps_per_window + 1):
        # 开场上下文只有任务描述与清单，一个字的进度都没有
        context = base if not transcript else base + "\n\n" + "\n".join(transcript)
        reply = await ask_model(context)
 
        parsed = parse_reply(reply)
        applied = apply_patch(repo_dir, parsed.feature_id, parsed.code)
        verdict = verify_shallow(repo_dir, parsed.feature_id, applied)
 
        # 「已完成」三个字是模型认得的唯一完成证据。
        # 它被写进 transcript，也就是说：它住在窗口里，窗口一换就没了。
        mark = "已完成" if verdict.passed else "未通过"
        transcript.append(f"[第 {i} 步] 验证：{parsed.feature_id} {mark}")

跑起来是这样的：

TextText

窗口 1 做了：F01 F02 F03
窗口 2 做了：F01 F02 F03   ← 其中 F01 F02 F03 是重复劳动
 
清单实际进度：3/40  [F01 F02 F03]
跑掉的步数：6 步
其中白干的：3 步
窗口 1 内部重复：无
窗口 2 内部重复：无
 
两个窗口第 1 步看到的上下文：
  逐字相同（各 2891 字符）。窗口 2 开场时，窗口 1 干的活一个字都不在。

六步换来三条进度，一半的算力是白烧的。注意最后那两行：两个窗口第一步看到的上下文逐字相同，各 2891 字符。窗口 1 辛苦干完的三条，在窗口 2 的开场里一个字都没有。

这里是本课的立论，值得慢慢读一遍：第二个窗口从头乱猜，不是模型变笨了，是证据没了。 模型这一侧从头到尾只有一条规则——挑第一条没有完成证据的 feature 去做。窗口 1 里它挑了 F01，因为清单第一条就是它；窗口 2 里它又挑了 F01，因为在它能看到的那 2891 个字符里，F01 依然没有任何完成证据。同一条规则，同一个输入，同一个输出。它的行为完全一致，是证据变了。

顺着这个结论还能多看出一层：进度其实一直存在，就在 harness 的内存里躺着——上面那行「清单实际进度：3/40」就是从它算出来的。问题不是没人记，是没人把它写进下一个窗口的开场。窗口 1 内部之所以没有重复，恰恰是因为那三步的证据还在同一个窗口里累积着。

为什么模型接口只该收一个字符串

现在讲全课的方法论支点。模型的接口长这样，只有一行：

AskModel = (context: string) => Promise<string>

一个字符串进，一个字符串出。签名里没有、也永远不会有任何 harness 配置参数——没有 withState、没有 options、没有 config。

这不是洁癖。因为这门课七天都在证明「某个 harness 机关有用」，而一旦模型能感知到当前开了哪些机关，它就可以配合演出：

ask-model.js

// 对的签名：模型只能看到一个字符串。
// harness 开了什么、关了什么，它一个字都拿不到。
async function askModel(context) {
  // 规则只有一条：挑第一条没有完成证据的 feature 去做
  const queue = listedFeatures(context)
  const done = featuresMarkedDone(context)
  const next = queue.find((id) => !done.has(id))
  return next === undefined ? 'ALL_DONE' : writePatch(next)
}
 
// 错的签名：多一个参数，整门课的结论全废。
// 它可以开了状态层就好好干、关了就装傻，而你永远看不出来。
async function askModelTainted(context, harness) {
  if (!harness.stateEnabled) return 'IMPLEMENT F01'
  return askModel(context)
}

ask_model.py

# 对的签名：模型只能看到一个字符串。
# harness 开了什么、关了什么，它一个字都拿不到。
async def ask_model(context: str) -> str:
    # 规则只有一条：挑第一条没有完成证据的 feature 去做
    queue = listed_features(context)
    done = features_marked_done(context)
    nxt = next((fid for fid in queue if fid not in done), None)
    return "ALL_DONE" if nxt is None else write_patch(nxt)
 
 
# 错的签名：多一个参数，整门课的结论全废。
# 它可以开了状态层就好好干、关了就装傻，而你永远看不出来。
async def ask_model_tainted(context: str, harness) -> str:
    if not harness.state_enabled:
        return "IMPLEMENT F01"
    return await ask_model(context)

用那个被污染的签名跑七天，每一条曲线都会很漂亮：开状态层的运行完成度高，关状态层的运行完成度低，结论「状态层有用」看起来被实测证实了。但它是喂出来的假绿——你测的不是 harness 的效果，是模型有多配合。

请把这条判据背下来，它对你自己的项目同样成立：任何一次对照实验，被测系统都不该知道自己正在被测。 你评估的对象一旦能感知实验条件，你得到的就不是效果，是演出。反过来说，正因为今天这个模型只收一个字符串，它对 harness 完全无感，所以「第二窗口重复劳动」这个现象只能真实涌现——它不可能是剧本写死的，因为剧本里连「窗口」这个概念都不存在。

换 harness 的收益可以大于换模型

这门课凭什么值得单独学七天？有一个很硬的论据。

LangChain 公开过一次实测：同一个模型、不换模型，只改 harness，在 Terminal Bench 2.0 上从 52.8 分提到 66.5 分，涨了 13.7 点，排名从 Top 30 进了 Top 5。

十三点七分是个什么量级？它通常是一代模型的差距。而这一次一行模型都没换，改的全是模型之外那一层：什么时候允许退出、发现改同一个文件太多次要怎么办、怎么让 Agent 一进来就知道环境里有什么工具。

他们那次改了四处，其中三处正好是本课的主线：

那次的改动	做的事	本课对应
退出前的强制检查	拦住 Agent 声称完成，先跑一遍验证	D5 端到端闸门
打转检测	追踪文件编辑，同一文件改太多次就建议换思路	D5 打转检测与干预
本地环境上下文	映射目录结构、发现环境里有哪些工具可用	D2 状态层与上下文重建
推理预算分配	规划与验证阶段多给推理，实现阶段给中等	本课不讲（属模型调参）

第四处刻意不讲，因为它是模型调参，不是 harness 结构——这条边界本课会守到最后一天。

人在旁边，对比人不在场

如果你学过手搓 Coding Agent 那门课，会发现那二十一天已经把 harness 的零件逐个手搓过了：工具循环、会话恢复、停滞信号、上下文压缩。那本课还剩什么？

差别只有一条，但它改变了几乎每个结论：那门课全程是人坐在旁边的交互式 REPL，本课是人不在场跑一整夜。 同一个问题在两个前提下有不同的正解，这里有三处最典型的：

同一个话题	人在旁边（那门课的结论）	人不在场（本课的结论）
git	不用 git 提交，不能污染用户的仓库历史	git commit 就是进度的权威记录，agent 自己提交
压缩	拿早期事实当探针，压完再问一遍，确认没丢	探针验的是「记不记得」，验不出「还听不听话」
打转	清单十轮不动就报一个停滞信号	报了之后自动怎么办：换任务、回滚、还是停机

这三处不是谁对谁错，是前提不同。git 那一条的反转最干脆：那门课操作的是用户的仓库，往里面塞 commit 是越权；本课操作的是 agent 自己的工作区，那里面的 commit 就是进度本身，不提交反而没有绿点可回滚。这个反转是 D4 的开场。

压缩那一条更值得记：探针法验证的是事实保真——早期提过的订单号压完还记得吗。但约束保真是另一件事，一个还记得全部事实的 Agent 完全可能已经不再遵守「未经确认不许删文件」这条规则。探针法对后者是盲的。这是 D6 的核心。

源码导读

今天的 lab 里有四个冻结文件（D1 定稿、后面六天逐字复制），先读两个最短的。

src/core/types.ts 是全课的名词表，六个类型对应前面那五个术语：Feature 是清单里的一条，RunState 是磁盘上的状态，Step 是窗口里的一步，VerifyResult 是一次端到端验证的结论，Outcome 是一次运行的结局（跑完、停滞、预算用尽、崩了）。重点读第六个：AskModel = (context: string) => Promise<string>。上一节讲的全部内容，都压在这一行签名里。读的时候留意 Feature.passes 上面那句注释——「只有端到端验证通过才允许翻成 true」，那条纪律是 D5 的全部内容。

src/core/git.ts 只有一个函数，但它是本课的红线所在。本课是全仓库唯一让 agent 真实执行 git 的课，而工作目录一旦解析错，commit 会打进课程仓库自己的历史。

git.js

// 全 lab 唯一允许调用 git 的地方。workdir 是必填的第一个参数。
function runGit(workdir, args) {
  if (!workdir) throw new Error('runGit: workdir 必填，禁止依赖继承的 cwd')
  // 每次都显式传 -C，绝不依赖进程继承下来的当前目录
  return execFileSync('git', ['-C', workdir, ...args], { encoding: 'utf8' })
}
 
// 反面写法：不传目录，靠继承的 cwd。
// 它在 work/repo 里跑是对的，在任何别处跑就是往你自己的仓库里提交。
function runGitUnsafe(args) {
  return execFileSync('git', args, { encoding: 'utf8' })
}

git.py

def run_git(workdir: str, args: list[str]) -> str:
    """全 lab 唯一允许调用 git 的地方。workdir 是必填的第一个参数。"""
    if not workdir:
        raise ValueError("run_git: workdir 必填，禁止依赖继承的 cwd")
    # 每次都显式传 -C，绝不依赖进程继承下来的当前目录
    done = subprocess.run(["git", "-C", workdir, *args], capture_output=True, text=True, check=True)
    return done.stdout
 
 
def run_git_unsafe(args: list[str]) -> str:
    """反面写法：不传目录，靠继承的 cwd。
    它在 work/repo 里跑是对的，在任何别处跑就是往你自己的仓库里提交。"""
    return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout

三条纪律配套：git 只在 work/repo 这个独立仓库里用；所有调用经这一个出口；一致性脚本会断言 git 这个字面量在这个文件之外出现即失败。最后那条是机器闸门——靠自觉守不住这种红线。

动手实验

🧪 D1 实验：一次跑穿两个上下文窗口，亲手复现退化

代码位置：labs/agent-harness-7days/day-01-two-windows

今天要建的是 nightrun 的地基：类型层、唯一的 git 出口、四十条 feature 清单的靶子、离线剧本引擎，最后跑两个窗口把重复劳动打出来。四个冻结文件已经给全了，今天的练习只有一处——src/core/loop.ts 里被挖空的两层循环。零件都在上面备好了，缺的只是把它们串起来。

两个最容易做错的地方先说：每个窗口开头要把 transcript 清空（挪到循环外面，今天的现象就消失了）；验证通过那一行必须带「已完成」三个字，那是模型认完成证据的唯一标记，写成别的词模型永远看不见进度。

读 src/core/types.ts，把六个类型和正文的五个术语对上号，特别是 AskModel 那一行。
读 src/core/git.ts，确认 workdir 必填、每次显式传 -C，这是今天唯一的红线。
跑 pnpm target:all 给靶子做一次体检：四十条补丁一次全打上、真起服务打二十多个请求，证明这四十条合起来是个能跑的服务。
补上 src/core/loop.ts 的两层循环，跑 MOCK=1 pnpm selftest 到十三项全绿。
跑 MOCK=1 pnpm start，看到窗口 2 把 F01 F02 F03 又做了一遍、六步只换来三条进度。

做完别急着收工，README 里那条变异检验才是今天的关键一步：把窗口循环开头 transcript.length = 0 那一行注释掉再跑一次，输出会变成这样。