Repository navigation
docs(chapters): 写第十一章《运行时与 harness 选择》并更新路线图 - #10
Merged
Merged
Conversation
jasontopia
force-pushed
the
fm/learn-fm-ch11
branch
from
September 26, 2026 22:39
abba7a4 to
f0a183c
Compare
jasontopia
force-pushed
the
fm/learn-fm-ch11
branch
from
September 26, 2026 22:50
f0a183c to
1f37379
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
继续 Learn FirstMate 教程，写第十一章。前十章已写完或正在走质检流水线。README 的学习路线图里，第十一章的定位是：哪个工具在跑船员，运行时后端与 harness 怎么配，以及什么时候值得为一件活单独指定。第十一章是路线图里「规模、离席、以及到底是哪个工具在跑你的船员」这条线（第 9 到 11 章）的最后一章。
What Changed
chapters/11-harness-and-runtime-backend.md, covering how harness (the tool executing a crewmate) and runtime backend (the terminal session carrier it runs in) are two independent, orthogonal settings, their default fallback chains, when it is legitimate to override one for a single task, and the failure-handling rule that a broken override is a blocker rather than something to silently retry on another backend - each claim sourced toAGENTS.md,bin/fm-spawn.sh's header comment, anddocs/configuration.md.git status --shortandgit diff HEAD.README.md's roadmap table to link chapter 11 and mark its status from 待写 to 已写.🤖 Generated with Claude Code
Risk Assessment
✅ Low: Both prior review rounds' findings (the overstated harness/backend binding claim and the unsourced repo-history assertion) were fixed narrowly and correctly, all quoted source material verified byte-for-byte against the authoritative FirstMate checkout (AGENTS.md §2/§4, docs/configuration.md "Harness support", fm-spawn.sh header), the docs-check script passes, and the change satisfies the stated user intent (chapter 11 on harness/runtime backend selection, README roadmap updated) with no new unsourced or scope-expanding content.
Testing
Baseline
python3 scripts/check-docs.pypassed both before and after inspection; the README link and chapter file resolve correctly, and both prior-round textual fixes were verified word-for-word against the diff and against the cited authoritative FirstMate source file. The one product-level scenario this chapter defines for the reader - running the hands-on exercise against a live FirstMate primary session - remains untested because doing so would require a state-changing interaction in the captain's read-only FirstMate checkout, which this repo's own AGENTS.md forbids; this was already surfaced and dismissed in rounds 1-2, so it is reported here as an untested scenario rather than re-raised as a finding.python3 scripts/check-docs.py→ "checked 14 markdown file(s): no problems found"; README.md:38 linkchapters/11-harness-and-runtime-backend.mdconfirmed present at that path via Readgit diff c98d1c4..1f37379 -- chapters/11-harness-and-runtime-backend.mdshows the unsourced sentence at old line 41 and the presupposed-answer language at old lines 73/79 replaced with history-agnos…Evidence: check-docs.py full run after fixes
Evidence: docs/configuration.md line 350 (kimi/cmux/Orca citation) matches chapter's claim verbatim
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 1 issue found → auto-fixed (2) ✅
chapters/11-harness-and-runtime-backend.md:29- The chapter states categorically: '同一个 harness 能配不同的后端，同一个后端也能承载不同的 harness，不存在「选了这个 harness 就只能配那个后端」这种绑定关系' (any harness can pair with any backend; no such binding exists). This is contradicted by ~/firstmate/docs/configuration.md line 350: 'fm-spawn.shrefuses kimi on cmux and Orca at preflight, because answering Kimi's folder-trust dialog needs a verified viewport-only capture those backends lack.' That is a concrete, source-documented harness-backend incompatibility (kimi cannot run on the cmux or Orca backends), which directly falsifies the chapter's blanket claim. The project's own writing rule (AGENTS.md in this repo) requires every behavioral claim to be traceable to the authoritative FirstMate checkout; this claim is not just untraceable but actively contradicted by docs/configuration.md, which the chapter never consulted (its stated sources are only AGENTS.md §4, §2, and fm-spawn.sh's header). The remedy is textual only - qualify or remove the absolute claim (e.g. note that resolution defaults are independent, butfm-spawnstill preflight-validates specific harness/backend combinations such as the kimi/cmux/Orca restriction) - so this is a mechanical correction, not a change to the chapter's intended teaching goal.🔧 Fix applied.
✅ Re-checked - no issues remain.
✅ No issues found.
chapters/11-harness-and-runtime-backend.md:41- Line 41 states as settled fact that every crewmate spawned for chapters 1-10 of this tutorial repo used the same harness (claude) and the same runtime backend, and that no task ever passed a per-spawn override. Unlike every other behavioral claim in this chapter, this sentence carries no citation to any tracked file, and per AGENTS.md's own writing rule ('every statement about how FirstMate behaves must be traceable to an authoritative tracked file... if it has no source there, leave it out') plus the captain-private carve-out ('data/, state/, config/, projects/, and .no-mistakes/ in that checkout are captain-private... never use their contents as tutorial material'), the only place this project's actual per-task harness/backend dispatch history would live is exactly those captain-private directories. This repo's own git history shows this exact defect class was already caught and fixed twice before: commit e7eea96 'docs: reframe ch8 stale-wake case study as hypothetical' and commit 647d7a3's round 'docs: stop presenting unverifiable ch7 case-study specifics as fact', plus 34b7369 'fix ch5 private-data sourcing, false PR#4 merge claim'. The same unsourced assumption is then baked into the exercise's grading rubric at line 73 ('它会说出这个仓库到目前为止所有船员用的都是同一个 harness...而不是巧合') and line 79 ('它对这个仓库历史的描述是准确的（同一 harness、同一后端、没有单独指定过）'), so a reader whose primary session truthfully reports a different history (e.g. a chapter that in fact used a non-default harness) would be told by the chapter that their agent 'didn't make it' when it was actually correct. Remedy is textual: reframe the sentence as an expectation to verify live (matching how the exercise otherwise works) rather than an asserted fact, and drop the implicit 'this is the correct answer' framing at lines 73 and 79.🔧 Fix applied.
✅ Re-checked - no issues remain.
python3 scripts/check-docs.pypython3 scripts/check-docs.pygit diff --stat a25f2bdf4b514b2a4a7ae68561efcd0b109ff4b8 abba7a41327c0f115f2ba47eec7dbf1db1e89205git diff a25f2bdf4b514b2a4a7ae68561efcd0b109ff4b8 abba7a41327c0f115f2ba47eec7dbf1db1e89205 -- chapters/11-harness-and-runtime-backend.mdLive validation:⚠️ inconclusive - 1 of 3 scenarios driven live against the product
python3 scripts/check-docs.pyoutput: 'checked 12 markdown file(s): no problems found', run against the target commit's working treepython3 scripts/check-docs.pypython3 scripts/check-docs.py (link integrity + formatting hygiene across all 12 chapters, including new chapter 11 and updated README roadmap row)Manual diff review of chapters/11-harness-and-runtime-backend.md (5cf2a5b..f0a183c) against source of truth ~/firstmate/docs/configuration.md lines 347-348Manual diff review of README.md roadmap row for chapter 11Live validation:⚠️ inconclusive - 3 of 4 scenarios driven live against the product
python3 scripts/check-docs.py→ "checked 14 markdown file(s): no problems found"; README.md:38 linkchapters/11-harness-and-runtime-backend.mdconfirmed present at that path via Readgit diff c98d1c4..1f37379 -- chapters/11-harness-and-runtime-backend.mdshows the unsourced sentence at old line 41 and the presupposed-answer language at old lines 73/79 replaced with history-agnos…python3 scripts/check-docs.pypython3 scripts/check-docs.pygit diff c98d1c4..1f37379 -- chapters/11-harness-and-runtime-backend.md (confirms round-4 fix content)grep -n kimi -B3 -A3 ~/firstmate/docs/configuration.md (confirms round-1 citation accuracy against the read-only FirstMate checkout)✅ **Document** - passed
✅ No issues found.
✅ No issues found.
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ No issues found.
✅ No issues found.
✅ **Push** - passed
✅ No issues found.
✅ No issues found.
✅ No issues found.