Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Improve Mermaid diagrams and viewer UX
sanbuphyfbc6d1f60e65
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex d1bbe8c..b93a14b 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -104,7 +104,13 @@ export default withMermaid(primaryBorderColor: '#D1D1D1',primaryTextColor: '#1A1A1A',lineColor: '#B3B3B3',- fontFamily: 'Inter, sans-serif'+ fontFamily: 'Inter, sans-serif',+ fontSize: '18px'+ },+ flowchart: {+ nodeSpacing: 40,+ rankSpacing: 56,+ padding: 12}},locales: {diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.jsindex 6255b5f..7aa0a61 100644--- a/docs/.vitepress/theme/index.js+++ b/docs/.vitepress/theme/index.js@@ -2,6 +2,16 @@ import DefaultTheme from 'vitepress/theme'import './style.css'let rootEnglishLabel = 'English'+let mermaidViewer+let mermaidViewerBody+let mermaidViewerStage+let mermaidObserver+let mermaidViewerUrl+let mermaidViewerImage+let mermaidViewerNaturalWidth = 0+let mermaidViewerNaturalHeight = 0+let mermaidViewerFitScale = 1+let mermaidViewerScale = 1function dedupeLocaleMenuLinks() {if (typeof document === 'undefined') return@@ -60,16 +70,257 @@ function syncRootLocaleLabel(siteData, href = '') {locales.root.label = relative.startsWith('/zh/') ? locales.zh.label : rootEnglishLabel}+function ensureMermaidViewer() {+ if (typeof document === 'undefined') return+ if (mermaidViewer && mermaidViewerBody && mermaidViewerStage) return++ mermaidViewer = document.createElement('div')+ mermaidViewer.className = 'mermaid-viewer'+ mermaidViewer.innerHTML = `+ <div class="mermaid-viewer__backdrop" data-mermaid-close="true"></div>+ <div class="mermaid-viewer__panel" role="dialog" aria-modal="true" aria-label="Expanded Mermaid diagram">+ <div class="mermaid-viewer__toolbar">+ <button type="button" class="mermaid-viewer__tool" aria-label="Zoom out" data-mermaid-action="zoom-out">−</button>+ <button type="button" class="mermaid-viewer__tool mermaid-viewer__tool--label" aria-label="Reset zoom" data-mermaid-action="reset">100%</button>+ <button type="button" class="mermaid-viewer__tool" aria-label="Zoom in" data-mermaid-action="zoom-in">+</button>+ <button type="button" class="mermaid-viewer__close" aria-label="Close diagram" data-mermaid-close="true">×</button>+ </div>+ <div class="mermaid-viewer__body">+ <div class="mermaid-viewer__stage"></div>+ </div>+ </div>+ `++ mermaidViewerBody = mermaidViewer.querySelector('.mermaid-viewer__body')+ mermaidViewerStage = mermaidViewer.querySelector('.mermaid-viewer__stage')++ mermaidViewer.addEventListener('click', (event) => {+ const target = event.target+ if (!(target instanceof HTMLElement)) return++ if (+ target.dataset.mermaidClose === 'true' ||+ target === mermaidViewerBody ||+ target === mermaidViewerStage+ ) {+ closeMermaidViewer()+ return+ }++ const action = target.dataset.mermaidAction+ if (action === 'zoom-in') {+ setMermaidViewerScale(mermaidViewerScale + 0.2)+ } else if (action === 'zoom-out') {+ setMermaidViewerScale(mermaidViewerScale - 0.2)+ } else if (action === 'reset') {+ setMermaidViewerScale(1)+ }+ })++ document.addEventListener('keydown', (event) => {+ if (event.key === 'Escape' && mermaidViewer?.classList.contains('is-open')) {+ closeMermaidViewer()+ } else if ((event.key === '+' || event.key === '=') && mermaidViewer?.classList.contains('is-open')) {+ setMermaidViewerScale(mermaidViewerScale + 0.2)+ } else if (event.key === '-' && mermaidViewer?.classList.contains('is-open')) {+ setMermaidViewerScale(mermaidViewerScale - 0.2)+ }+ })++ mermaidViewerBody?.addEventListener('wheel', (event) => {+ if (!mermaidViewer?.classList.contains('is-open')) return+ event.preventDefault()+ const delta = event.deltaY < 0 ? 0.12 : -0.12+ setMermaidViewerScale(mermaidViewerScale + delta)+ }, { passive: false })++ window.addEventListener('resize', () => {+ if (mermaidViewer?.classList.contains('is-open')) {+ updateMermaidViewerFitScale()+ setMermaidViewerScale(mermaidViewerScale)+ }+ })++ document.body.appendChild(mermaidViewer)+}++function serializeMermaidSvg(svg) {+ const clone = svg.cloneNode(true)+ if (!(clone instanceof SVGElement)) return null++ if (!clone.getAttribute('xmlns')) {+ clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg')+ }+ if (!clone.getAttribute('xmlns:xlink')) {+ clone.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')+ }++ const rect = svg.getBoundingClientRect()+ const viewBox = svg.viewBox?.baseVal+ const rawWidth = rect.width || viewBox?.width || Number.parseFloat(svg.getAttribute('width') || '') || 1200+ const rawHeight = rect.height || viewBox?.height || Number.parseFloat(svg.getAttribute('height') || '') || 800++ if (!clone.getAttribute('viewBox')) {+ clone.setAttribute('viewBox', `0 0 ${Math.max(1, Math.round(rawWidth))} ${Math.max(1, Math.round(rawHeight))}`)+ }++ clone.setAttribute('width', String(Math.max(1, Math.round(rawWidth))))+ clone.setAttribute('height', String(Math.max(1, Math.round(rawHeight))))++ return {+ markup: new XMLSerializer().serializeToString(clone),+ width: Math.max(1, rawWidth),+ height: Math.max(1, rawHeight)+ }+}++function updateMermaidViewerFitScale() {+ if (!mermaidViewerNaturalWidth || !mermaidViewerNaturalHeight || typeof window === 'undefined') return++ const maxWidth = Math.max(320, window.innerWidth - 16)+ const maxHeight = Math.max(240, window.innerHeight - 16)+ mermaidViewerFitScale = Math.max(+ 0.25,+ Math.min(maxWidth / mermaidViewerNaturalWidth, maxHeight / mermaidViewerNaturalHeight)+ )+}++function setMermaidViewerScale(nextScale) {+ if (!mermaidViewerStage || !mermaidViewerNaturalWidth || !mermaidViewerNaturalHeight) return++ mermaidViewerScale = Math.max(0.5, Math.min(nextScale, 4))++ const width = mermaidViewerNaturalWidth * mermaidViewerFitScale * mermaidViewerScale+ const height = mermaidViewerNaturalHeight * mermaidViewerFitScale * mermaidViewerScale++ mermaidViewerStage.style.width = `${width}px`+ mermaidViewerStage.style.height = `${height}px`++ const resetButton = mermaidViewer?.querySelector('[data-mermaid-action="reset"]')+ if (resetButton instanceof HTMLElement) {+ resetButton.textContent = `${Math.round(mermaidViewerScale * 100)}%`+ }+}++function openMermaidViewer(diagram) {+ ensureMermaidViewer()+ if (!mermaidViewerBody || !mermaidViewer || !mermaidViewerStage) return++ const svg = diagram.querySelector('svg')+ if (!svg) return++ if (mermaidViewerUrl) {+ URL.revokeObjectURL(mermaidViewerUrl)+ mermaidViewerUrl = undefined+ }++ const serialized = serializeMermaidSvg(svg)+ if (!serialized) return++ const blob = new Blob([serialized.markup], { type: 'image/svg+xml;charset=utf-8' })+ mermaidViewerUrl = URL.createObjectURL(blob)++ const image = document.createElement('img')+ image.className = 'mermaid-viewer__image'+ image.alt = 'Expanded Mermaid diagram'+ image.src = mermaidViewerUrl+ image.addEventListener('load', () => {+ mermaidViewerNaturalWidth = serialized.width+ mermaidViewerNaturalHeight = serialized.height+ updateMermaidViewerFitScale()+ setMermaidViewerScale(1)+ if (mermaidViewerBody) {+ mermaidViewerBody.scrollTo({ top: 0, left: 0 })+ }+ })++ mermaidViewerImage = image+ mermaidViewerStage.replaceChildren(image)+ mermaidViewer.classList.add('is-open')+ document.documentElement.classList.add('has-mermaid-viewer')+}++function closeMermaidViewer() {+ if (!mermaidViewer || !mermaidViewerBody || !mermaidViewerStage) return+ mermaidViewer.classList.remove('is-open')+ mermaidViewerStage.replaceChildren()+ mermaidViewerStage.style.width = ''+ mermaidViewerStage.style.height = ''+ if (mermaidViewerUrl) {+ URL.revokeObjectURL(mermaidViewerUrl)+ mermaidViewerUrl = undefined+ }+ mermaidViewerImage = undefined+ mermaidViewerNaturalWidth = 0+ mermaidViewerNaturalHeight = 0+ mermaidViewerFitScale = 1+ mermaidViewerScale = 1+ document.documentElement.classList.remove('has-mermaid-viewer')+}++function bindMermaidZoomables(root = document) {+ if (typeof document === 'undefined') return+ ensureMermaidViewer()++ const diagrams = root.querySelectorAll('.vp-doc .mermaid')+ for (const diagram of diagrams) {+ if (!(diagram instanceof HTMLElement) || diagram.dataset.mermaidZoomBound === 'true') {+ continue+ }++ diagram.dataset.mermaidZoomBound = 'true'+ diagram.tabIndex = 0+ diagram.setAttribute('role', 'button')+ diagram.setAttribute('aria-label', 'Open Mermaid diagram in fullscreen')++ diagram.addEventListener('click', () => {+ openMermaidViewer(diagram)+ })++ diagram.addEventListener('keydown', (event) => {+ if (event.key === 'Enter' || event.key === ' ') {+ event.preventDefault()+ openMermaidViewer(diagram)+ }+ })+ }+}++function queueMermaidBinding() {+ if (typeof window === 'undefined') return+ window.requestAnimationFrame(() => {+ window.requestAnimationFrame(() => {+ bindMermaidZoomables()+ })+ })+}++function ensureMermaidObserver() {+ if (typeof document === 'undefined' || mermaidObserver) return+ mermaidObserver = new MutationObserver(() => {+ bindMermaidZoomables()+ })++ mermaidObserver.observe(document.body, {+ childList: true,+ subtree: true+ })+}+export default {extends: DefaultTheme,enhanceApp(ctx) {syncRootLocaleLabel(ctx.siteData)queueLocaleMenuDedupe()+ queueMermaidBinding()+ ensureMermaidObserver()const previous = ctx.router.onAfterRouteChangectx.router.onAfterRouteChange = async (to) => {syncRootLocaleLabel(ctx.siteData, to)queueLocaleMenuDedupe()+ closeMermaidViewer()+ queueMermaidBinding()if (previous) {await previous(to)}diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.cssindex d897c80..ebbd146 100644--- a/docs/.vitepress/theme/style.css+++ b/docs/.vitepress/theme/style.css@@ -530,15 +530,216 @@}/* ---------- Mermaid Charts styling overrides ---------- */-.mermaid {- background-color: var(--vp-c-bg-elv);- border: 1px solid var(--vp-c-divider);- border-radius: 12px;- padding: 16px;- margin: 16px 0;+.vp-doc .mermaid {+ background: transparent;+ border: 0;+ border-radius: 0;+ padding: 12px 0;+ margin: 20px 0;display: flex;justify-content: center;+ overflow-x: auto;+ overflow-y: visible;+ -webkit-overflow-scrolling: touch;+ cursor: zoom-in;+ position: relative;+}++.vp-doc .mermaid svg {+ display: block;+ width: clamp(780px, 100%, 1040px) !important;+ max-width: none !important;+ min-width: 780px;+ height: auto !important;+ margin: 0 auto;+}++.vp-doc .mermaid .label,+.vp-doc .mermaid .nodeLabel,+.vp-doc .mermaid .edgeLabel {+ font-size: 18px !important;+}++.vp-doc .mermaid::after {+ content: 'Click to expand';+ position: absolute;+ top: 0;+ right: 0;+ padding: 4px 8px;+ border-radius: 999px;+ background: rgba(0, 0, 0, 0.05);+ color: var(--vp-c-text-2);+ font-size: 12px;+ font-weight: 600;+ letter-spacing: 0.01em;+ opacity: 0;+ transition: opacity 0.2s ease;+ pointer-events: none;+}++.vp-doc .mermaid:hover::after,+.vp-doc .mermaid:focus-visible::after {+ opacity: 1;+}++html:lang(zh-CN) .vp-doc .mermaid::after {+ content: '点击放大';+}++.vp-doc .mermaid:focus-visible {+ outline: 2px solid var(--vp-c-brand-1);+ outline-offset: 6px;+}++.dark .vp-doc .mermaid::after {+ background: rgba(255, 255, 255, 0.08);+}++@media (max-width: 768px) {+ .vp-doc .mermaid {+ padding: 14px 10px;+ }++ .vp-doc .mermaid svg {+ width: clamp(640px, 100%, 920px) !important;+ min-width: 640px;+ }++ .vp-doc .mermaid .label,+ .vp-doc .mermaid .nodeLabel,+ .vp-doc .mermaid .edgeLabel {+ font-size: 16px !important;+ }++ .vp-doc .mermaid::after {+ content: 'Tap to expand';+ opacity: 1;+ top: 0;+ right: 0;+ }++ html:lang(zh-CN) .vp-doc .mermaid::after {+ content: '点击放大';+ }+}++html.has-mermaid-viewer,+html.has-mermaid-viewer body {+ overflow: hidden;+}++.mermaid-viewer {+ position: fixed;+ inset: 0;+ z-index: 100;+ display: none;+}++.mermaid-viewer.is-open {+ display: block;}++.mermaid-viewer__backdrop {+ position: absolute;+ inset: 0;+ background: rgba(250, 249, 245, 0.96);+}++.mermaid-viewer__panel {+ position: absolute;+ inset: 0;+ display: flex;+ flex-direction: column;+}++.mermaid-viewer__toolbar {+ position: absolute;+ top: 12px;+ right: 12px;+ z-index: 2;+ display: flex;+ align-items: center;+ gap: 8px;+}++.mermaid-viewer__tool,+.mermaid-viewer__close {+ border: 0;+ border-radius: 999px;+ width: 40px;+ height: 40px;+ background: rgba(0, 0, 0, 0.06);+ color: var(--vp-c-text-1);+ font-size: 24px;+ line-height: 1;+ font-weight: 400;+ cursor: pointer;+}++.mermaid-viewer__tool--label {+ width: auto;+ min-width: 72px;+ padding: 0 14px;+ font-size: 13px;+ font-weight: 600;+}++.mermaid-viewer__body {+ flex: 1;+ overflow: auto;+ display: flex;+ align-items: center;+ justify-content: center;+ padding: 8px;+ cursor: zoom-out;+ background: #fff;+}++.mermaid-viewer__stage {+ flex: 0 0 auto;+ display: block;+}++.mermaid-viewer__image {+ display: block;+ width: 100%;+ height: 100%;+ margin: 0 auto;+ background: transparent;+ user-select: none;+ -webkit-user-drag: none;+ pointer-events: none;+}++@media (max-width: 768px) {+ .mermaid-viewer__panel {+ inset: 0;+ }++ .mermaid-viewer__toolbar {+ top: 8px;+ right: 8px;+ gap: 6px;+ }++ .mermaid-viewer__tool,+ .mermaid-viewer__close {+ width: 36px;+ height: 36px;+ font-size: 20px;+ }++ .mermaid-viewer__tool--label {+ min-width: 64px;+ padding: 0 10px;+ font-size: 12px;+ }++ .mermaid-viewer__body {+ padding: 4px;+ }+}+.VPDoc .back-to-top-btn {border-radius: 50%;}diff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 4cee78d..65e2f61 100644--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -23,26 +23,21 @@ This isn't because the model isn't smart enough. It's because the working enviro## Failure Model Overview```mermaid-graph LR- subgraph "Five Failure Layers"- direction TB- L1["① Task Specification"]- L2["② Context Provision"]- L3["③ Execution Environment"]- L4["④ Verification Feedback"]- L5["⑤ State Management"]- end-- Agent -->|"encounters"| L1- L1 --> L2 --> L3 --> L4 --> L5- L5 -->|"signals defect"| Fix["Fix layer → Re-run"]- Fix -->|"diagnostic loop"| Agent+flowchart TB+ Spec["Task not specific<br/>'add search' can mean many things"] --> Fail["Result:<br/>agent writes code<br/>but work is unreliable"]+ Context["Project rules missing<br/>agent cannot see them"] --> Fail+ Env["Environment broken<br/>deps or commands fail"] --> Fail+ Verify["No tests or check commands"] --> Fail+ State["No progress file<br/>next session starts blind"] --> Fail+ Fail --> Fix["Fix the broken layer,<br/>then rerun"]``````mermaid-graph LR- Bare["Bare Run<br/>20 min / $9<br/>Core features broken"] -->|"Add harness"| Full["Full Harness<br/>6 hr / $200<br/>Playable app"]- Bare -.->|"Same model"| Full+flowchart LR+ Same["Same prompt<br/>same model"] --> Bare["Bare run<br/>20 min / $9<br/>core features broken"]+ Same --> Full["Add planning, checks, and evaluation<br/>6 hr / $200<br/>playable app"]+ Bare --> Lesson["Only the harness changed"]+ Full --> Lesson```## Why This Happensdiff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 3db3efe..268994a 100644--- a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -23,16 +23,13 @@ This lecture gives you a precise, actionable definition. Not an academic abstrac## The Five-Tuple Harness Model```mermaid-graph TB- Agent["AI Agent"] --> I["📋 Instructions<br/><i>AGENTS.md, CLAUDE.md</i>"]- Agent --> T["🔧 Tools<br/><i>Shell, file ops, tests</i>"]- Agent --> E["🖥️ Environment<br/><i>Dependencies, runtime</i>"]- Agent --> S["💾 State<br/><i>Progress files, git</i>"]- Agent --> F["✅ Feedback<br/><i>Test results, lint, build</i>"]-- I ~~~ T ~~~ E ~~~ S ~~~ F-- F -->|"highest ROI"| Star["⭐ Start here"]+flowchart LR+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["Tools<br/>shell / files / tests"]+ Tools --> Env["Runtime<br/>deps / services / versions"]+ Env --> Checks["Check results<br/>test / lint / build"]+ Checks --> Agent```## Why This Happensdiff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 1aa8644..c4080f6 100644--- a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -23,34 +23,29 @@ This lecture explains why you must put everything an agent needs to know into th## Knowledge Visibility```mermaid-graph LR- subgraph "Visible to Agent"- Repo["Repository Files<br/>AGENTS.md, code, tests"]- end- subgraph "Invisible to Agent"- Slack["Slack History"]- Confluence["Confluence Docs"]- Heads["Senior Engineers' Heads"]- Jira["Jira Tickets"]- end-- Repo -->|"accessible"| Agent["🤖 Agent"]- Slack -.->|"inaccessible"| Agent- Confluence -.->|"inaccessible"| Agent- Heads -.->|"inaccessible"| Agent- Jira -.->|"inaccessible"| Agent+flowchart LR+ Slack["Rules in Slack"] --> Write["Write them into repo files<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Rules in Confluence"] --> Write+ Heads["Rules in people's heads"] --> Write+ Jira["Rules in Jira tickets"] --> Write+ Write --> Repo["Repository files"]+ Repo --> Agent["New agent session<br/>reads the repo directly"]+ Warning["If a rule is not in the repo,<br/>the agent cannot see it"] --> Agent``````mermaid-graph TB- subgraph "Cold-Start Test"- Q1["What is this system?"]- Q2["How is it organized?"]- Q3["How do I run it?"]- Q4["How do I verify it?"]- Q5["Where are we now?"]- end- Q1 & Q2 & Q3 & Q4 & Q5 -->|"all must be<br/>answerable from repo"| Pass["✅ Harness Ready"]+flowchart TB+ Q1["What is this system?"] --> A1["AGENTS.md / README"]+ Q2["How is it organized?"] --> A2["ARCHITECTURE.md / module docs"]+ Q3["How do I run it?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["How do I verify it?"] --> A4["Test, lint, and check commands"]+ Q5["Where are we now?"] --> A5["PROGRESS.md / feature list / git history"]++ A1 --> Ready["A new session can start work<br/>without asking a human"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready```## Why This Happensdiff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 9acf550..d00a8fe 100644--- a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -23,26 +23,22 @@ This is the "giant instruction file" trap. This lecture explains why "more infor## Instruction Architecture```mermaid-graph TB- subgraph "Three-Layer Structure"- L1["<b>Layer 1: Routing File</b><br/>AGENTS.md (50–200 lines)<br/>Overview + hard constraints + links"]- L2a["<b>Layer 2a</b><br/>api-patterns.md"]- L2b["<b>Layer 2b</b><br/>database-rules.md"]- L2c["<b>Layer 2c</b><br/>testing-standards.md"]- L3["<b>Layer 3: Inline</b><br/>Type defs, interface comments"]- end-- L1 -->|"link"| L2a- L1 -->|"link"| L2b- L1 -->|"link"| L2c- L2a & L2b & L2c -->|"reference"| L3-- style L1 fill:#D95C41,color:#fff+flowchart LR+ Mono["One 600-line AGENTS.md"] --> MonoLoad["Even a small bug fix<br/>must read deploy rules and old notes"]+ MonoLoad --> MonoRisk["Important rules buried in the middle<br/>are easy to miss"]++ Router["Short AGENTS.md"] --> Topics["Load API / DB / testing docs<br/>only when this task needs them"]+ Topics --> RoutedResult["More context left for code reading<br/>and verification"]``````mermaid-graph LR- Top["Top of file<br/>✅ High recall"] --- Mid["Middle of file<br/>❌ Lost in the middle"] --- Bot["Bottom of file<br/>✅ High recall"]+flowchart TB+ File["600-line instruction file"] --> Top["Top section<br/>quick start + hard constraints"]+ File --> Mid["Middle section<br/>critical security rule at line 300"]+ File --> Bot["Bottom section<br/>explicit end-of-file checklist"]+ Top --> Seen["High chance of recall"]+ Bot --> Seen+ Mid --> Missed["High chance of being diluted or missed"]```## Why This Happensdiff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex 33e7b72..9086386 100644--- a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -23,25 +23,26 @@ This is one of the most painful problems with AI coding agents: cross-session co## Session Continuity Flow```mermaid-graph LR- subgraph "Session N"- Work1["Work on task"] --> Update1["Update PROGRESS.md<br/>Update DECISIONS.md"]- Update1 --> Commit1["Git commit checkpoint"]- end- subgraph "Session N+1"- Read1["Read PROGRESS.md<br/>Read DECISIONS.md"] --> Resume["Resume from<br/>Next Steps"]- Resume --> Work2["Continue work"]- end-- Commit1 -->|"handoff"| Read1+flowchart LR+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]+ End1 --> S2["Session 2 starts fresh"]+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]``````mermaid-graph TB- subgraph "Information Loss"- Full["Full Context<br/>What + Why + How"] -->|"compaction"| Compact["Compacted<br/>What ✓ · Why ✗"]- Full -->|"new session"| Reset["Reset<br/>Rebuild from artifacts"]- end+flowchart LR+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]+ Work --> Verify["Verification notes<br/>which tests pass and fail"]+ Work --> Commit["Git checkpoint<br/>exact repo state"]++ Progress --> Rebuild["Session 2 rebuild"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["New session picks up quickly"]```## Why This Happensdiff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex 1d8cd9a..de72054 100644--- a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -23,24 +23,19 @@ The better approach: before letting the agent start working, use a separate phas## Initialization Lifecycle```mermaid-graph LR- subgraph "Initialization Phase"- I1["Runnable environment<br/><i>deps installed</i>"] --> I2["Test framework<br/><i>example test passes</i>"]- I2 --> I3["Bootstrap contract<br/><i>start/test/verify docs</i>"]- I3 --> I4["Task breakdown<br/><i>ordered feature list</i>"]- I4 --> I5["Git checkpoint<br/><i>clean commit</i>"]- end- subgraph "Implementation Phase"- I5 --> P1["Session 2: Feature 1"]- P1 --> P2["Session 3: Feature 2"]- P2 --> P3["Session N: Feature N"]+flowchart TB+ subgraph Wrong["Mixed session (wrong)"]+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]+ W2 --> W3["Accumulate unverified code"]+ W3 --> W4["Next session must rediscover project state"]end- style I1 fill:#D95C41,color:#fff- style I2 fill:#D95C41,color:#fff- style I3 fill:#D95C41,color:#fff- style I4 fill:#D95C41,color:#fff- style I5 fill:#D95C41,color:#fff+ subgraph Right["Dedicated initialization (right)"]+ R1["Session 1: environment runnable"] --> R2["Example test passing"]+ R2 --> R3["Bootstrap contract + task list written"]+ R3 --> R4["Clean checkpoint committed"]+ R4 --> R5["Later sessions start directly on verified tasks"]+ end```## Why This Happensdiff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdindex 1515ff8..d178c5e 100644--- a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -23,21 +23,23 @@ Anthropic's "Effective harnesses for long-running agents" engineering blog post## WIP=1 Workflow```mermaid-graph LR- subgraph "WIP = 1 (Correct)"- Pick1["Pick feature"] --> Do1["Implement"] --> Verify1["Verify E2E"]- Verify1 -->|"pass"| Commit1["Commit"]- Commit1 --> Next1["Next feature"]- Verify1 -->|"fail"| Do1- end+flowchart LR+ Queue["Feature queue"] --> Pick["Pick exactly one task"]+ Pick --> Active["Only one active item"]+ Active --> Verify["Run end-to-end verification"]+ Verify -->|pass| Commit["Commit and unlock next task"]+ Verify -->|fail| Active+ Commit --> Queue``````mermaid-graph LR- subgraph "Unconstrained (Wrong)"- Pick2["Activate 5 features"] --> Do2["Work on all"]- Do2 --> Result2["800 lines, 12 files<br/>20% pass rate ❌"]- end+flowchart TB+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]+ Budget --> Many["WIP = 5<br/>C / 5 per task"]++ One --> Finish["One feature reaches passing state"]+ Many --> Partial["Five partial implementations"]+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]```## Why This Happensdiff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdindex 21f7eef..bdeb9e2 100644--- a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -23,26 +23,26 @@ Feature lists are not planning documents for humans to read. They are the core d## Feature State Machine```mermaid-stateDiagram-v2- [*] --> not_started- not_started --> active: Agent picks task- active --> passing: Verification command passes- active --> blocked: External dependency- blocked --> active: Dependency resolved- passing --> [*]-- note right of passing- Irreversible: once passing,- cannot go back- end note+flowchart LR+ Feature["One feature row"] --> Behavior["Behavior<br/>for example: POST /cart/items returns 201"]+ Feature --> Check["Verification command<br/>the exact check to run"]+ Feature --> State["State<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Only with all three fields<br/>is the feature row usable"]+ Check --> Complete+ State --> Complete``````mermaid-graph TB- FL["📋 Feature List<br/><i>Single source of truth</i>"] --> Scheduler["Scheduler<br/><i>picks next task</i>"]- FL --> Verifier["Verifier<br/><i>runs check commands</i>"]- FL --> Handoff["Handoff Reporter<br/><i>generates summaries</i>"]- FL --> Progress["Progress Tracker<br/><i>tallies state distribution</i>"]+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Pick the next not_started item"]+ Scheduler --> Agent["Agent works on that one item"]+ Agent --> Verifier["Run that item's verification command"]+ Verifier -->|pass| Passing["Mark it passing<br/>and write the evidence"]+ Verifier -->|fail| Active["Keep it active"]+ Verifier -->|dependency issue| Blocked["Mark it blocked"]+ Passing --> Handoff["Update handoff note<br/>and current progress"]+ Active --> Agent```## Why This Happensdiff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex e3902fb..7c214aa 100644--- a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -23,27 +23,18 @@ This isn't a random event. Guo et al.'s classic 2017 ICML paper proved that **mo## Three-Layer Termination Check```mermaid-graph LR- subgraph "Verification Gates"- L1["Layer 1<br/>Syntax & Static Analysis<br/><i>lint, type check</i>"]- L2["Layer 2<br/>Runtime Behavior<br/><i>unit & integration tests</i>"]- L3["Layer 3<br/>System Validation<br/><i>E2E, user scenarios</i>"]- end-- L1 -->|"must pass"| L2- L2 -->|"must pass"| L3- L3 -->|"all pass"| Done["✅ Done"]-- style L1 fill:#F4F3EE- style L2 fill:#E8E7E2- style L3 fill:#D95C41,color:#fff+flowchart LR+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]+ L1 --> L2["Then run<br/>tests and app startup checks"]+ L2 --> L3["Finally run<br/>the full user flow"]+ L3 --> Done["All three pass -> done"]``````mermaid-graph LR- Agent["Agent: 'I'm done!'"] -->|"confidence"| High["High Confidence"]- Reality["Actual Quality"] -->|"measured"| Low["Low Quality"]- High -.->|"calibration gap"| Low+flowchart LR+ A["Code is written<br/>and unit tests are green"] --> B["But the app was not fully started<br/>and the whole flow was not run"]+ B --> C["Config, database, or email issues<br/>stay hidden"]+ C --> D["So the agent declares done too early"]```## Why This Happensdiff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdindex 8206056..39d126d 100644--- a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -22,26 +22,27 @@ Google's test pyramid tells us: lots of unit tests form the base, but if you sto## Test Pyramid & Review Feedback Loop```mermaid-graph TB- subgraph "Test Adequacy Gradient"- E2E["End-to-End Tests<br/><i>catches component boundary defects</i>"]- Int["Integration Tests"]- Unit["Unit Tests<br/><i>fast but isolated</i>"]+flowchart TB+ subgraph Unit["Unit tests inspect parts in isolation"]+ U1["Renderer test"]+ U2["Preload test"]+ U3["Service test"]end- Unit --> Int --> E2E-- style Unit fill:#F4F3EE- style Int fill:#E0DFD9- style E2E fill:#D95C41,color:#fff+ subgraph E2E["End-to-end run crosses the real system"]+ R["Renderer click"] --> P["Preload bridge"]+ P --> S["Service layer"]+ S --> F["Filesystem / OS"]+ F --> Result["Real exported file"]+ end``````mermaid-graph LR- Review["Code Review<br/>recurring feedback"] --> Pattern["Identify pattern"]- Pattern --> Rule["Create executable check<br/>+ agent-oriented error msg"]- Rule --> Harness["Add to harness"]- Harness -->|"prevents class"| Agent["🤖 Agent"]+flowchart LR+ Review["Reviewer says:<br/>renderer cannot import fs"] --> Rule["Add a check for direct fs import"]+ Rule --> Message["Error tells the agent<br/>to move file access into preload"]+ Message --> Harness["Add the check to the harness"]+ Harness --> Stronger["Next similar mistake fails fast"]```## Why This Happensdiff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdindex d4044ea..643c642 100644--- a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -23,25 +23,13 @@ This isn't about the agent lacking capability. It's about your harness not provi## Layered Observability```mermaid-graph TB- subgraph "Process Layer"- SC["Sprint Contract<br/><i>scope + standards + exclusions</i>"]- ER["Evaluator Rubric<br/><i>structured scoring</i>"]- end- subgraph "System Layer"- Logs["Runtime Logs"]- Traces["Request Traces"]- Health["Health Checks"]- end-- SC -->|"guides"| Gen["Generator"]- Gen -->|"produces"| Runtime["Runtime Behavior"]- Runtime --> Logs & Traces & Health- Logs & Traces & Health -->|"evidence"| ER- ER -->|"feedback"| Gen-- style SC fill:#D95C41,color:#fff- style ER fill:#D95C41,color:#fff+flowchart LR+ Contract["Write down the task first<br/>what to change / what not to change / pass criteria"] --> Generator["Generator"]+ Generator --> Signals["Collect app logs, traces,<br/>and health checks while it runs"]+ Contract --> Review["Check the result item by item<br/>behavior / tests / boundaries"]+ Signals --> Review+ Review --> Verdict["Point to the failed check<br/>and where to fix it"]+ Verdict --> Generator```## Why This Happensdiff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdindex 5a46044..9ea4253 100644--- a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -23,33 +23,29 @@ Both OpenAI and Anthropic state clearly: **long-term reliability depends on oper## Five Dimensions of Clean State```mermaid-graph TB- subgraph "Session Exit Checklist"- B["✅ Build passes"]- T["✅ Tests pass"]- P["✅ Progress recorded"]- A["✅ No stale artifacts"]- S["✅ Startup path available"]- end-- B & T & P & A & S -->|"all required"| Clean["🧹 Clean State"]- Clean -->|"enables"| Next["Next session<br/>immediate productivity"]+flowchart LR+ Work["Feature work complete"] --> Build{"Build passes?"}+ Build -->|yes| Test{"Tests pass?"}+ Build -->|no| Fix["Fix before exit"]+ Test -->|yes| Record["Update feature list + progress"]+ Test -->|no| Fix+ Record --> Cleanup["Remove temp artifacts / debug code"]+ Cleanup --> Startup{"Standard startup path works?"}+ Startup -->|yes| Clean["Clean handoff"]+ Startup -->|no| Fix+ Fix --> Build``````mermaid-graph LR- subgraph "Entropy Over 12 Weeks"- W1["Week 1<br/>100% build, 100% tests"] --> W4["Week 4<br/>95% / 92%"]- W4 --> W8["Week 8<br/>82% / 78%"]- W8 --> W12["Week 12<br/>68% / 61%"]- end-- subgraph "With Cleanup Strategy"- C1["Week 1<br/>100% / 100%"] --> C12["Week 12<br/>97% / 95%"]- end-- style W12 fill:#D95C41,color:#fff- style C12 fill:#4CAF50,color:#fff+flowchart LR+ Dirty["Session ends with<br/>red tests / temp files / no progress update"] --> Diagnose["Next session first has to<br/>figure out what happened"]+ Diagnose --> Fragile["New work starts on a messy repo"]+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]+ More --> Dirty++ Clean["Session ends with<br/>green tests / updated progress / temp files removed"] --> Fast["Next session can start coding immediately"]+ Fast --> Stable["No need to rescue the repo first"]+ Stable --> Clean```## Why This Happensdiff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 73b1a69..e9f815b 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -23,26 +23,21 @@## 五层失败模型```mermaid-graph LR- subgraph "五层失败模型"- direction TB- L1["① 任务规范层"]- L2["② 上下文供给层"]- L3["③ 执行环境层"]- L4["④ 验证反馈层"]- L5["⑤ 状态管理层"]- end-- Agent["🤖 Agent"] -->|"遇到"| L1- L1 --> L2 --> L3 --> L4 --> L5- L5 -->|"信号:缺陷"| Fix["修补对应层 → 重新执行"]- Fix -->|"诊断循环"| Agent+flowchart TB+ Spec["任务没写清楚<br/>比如“加搜索”含义很多"] --> Fail["结果:<br/>agent 写了很多代码<br/>但做事还是不稳定"]+ Context["项目规则没写进仓库<br/>agent 看不到"] --> Fail+ Env["环境没配好<br/>依赖或命令跑不起来"] --> Fail+ Verify["没有测试或检查命令"] --> Fail+ State["没有进度文件<br/>下一会话两眼一抹黑"] --> Fail+ Fail --> Fix["把出错那一层补上<br/>再重新跑"]``````mermaid-graph LR- Bare["裸跑模式<br/>20 分钟 / $9<br/>核心功能跑不起来"] -->|"加上 harness"| Full["完整 harness<br/>6 小时 / $200<br/>应用可以正常使用"]- Bare -.->|"同一个模型"| Full+flowchart LR+ Same["同一个任务<br/>同一个模型"] --> Bare["裸跑<br/>20 分钟 / $9<br/>核心功能失效"]+ Same --> Full["加上规划、检查和评估<br/>6 小时 / $200<br/>应用可以正常使用"]+ Bare --> Lesson["变的只有 harness"]+ Full --> Lesson```## 为什么会这样diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.mdindex e6c303e..7dd3ae9 100644--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -22,16 +22,13 @@## Harness 五子系统模型```mermaid-graph TB- Agent["🤖 AI Agent"] --> I["📋 指令<br/><i>AGENTS.md, CLAUDE.md</i>"]- Agent --> T["🔧 工具<br/><i>Shell, 文件操作, 测试</i>"]- Agent --> E["🖥️ 环境<br/><i>依赖, 运行时</i>"]- Agent --> S["💾 状态<br/><i>进度文件, git</i>"]- Agent --> F["✅ 反馈<br/><i>测试结果, lint, 构建</i>"]-- I ~~~ T ~~~ E ~~~ S ~~~ F-- F -->|"最高投入产出比"| Star["⭐ 从这里开始"]+flowchart LR+ Rules["项目规则<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ State["进度和 git<br/>PROGRESS.md / commits"] --> Agent+ Agent --> Tools["工具<br/>shell / 文件 / 测试"]+ Tools --> Env["运行环境<br/>依赖 / 服务 / 版本"]+ Env --> Checks["检查结果<br/>test / lint / build"]+ Checks --> Agent```## 为什么会这样diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex f84dfb1..8b61598 100644--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -23,34 +23,29 @@## 知识可见性```mermaid-graph LR- subgraph "Agent 可见的"- Repo["仓库文件<br/>AGENTS.md, 代码, 测试"]- end- subgraph "Agent 看不到的"- Slack["Slack 聊天记录"]- Confluence["Confluence 文档"]- Heads["资深工程师的脑子"]- Jira["Jira 工单"]- end-- Repo -->|"可访问"| Agent["🤖 Agent"]- Slack -.->|"不可访问"| Agent- Confluence -.->|"不可访问"| Agent- Heads -.->|"不可访问"| Agent- Jira -.->|"不可访问"| Agent+flowchart LR+ Slack["Slack 里的规则"] --> Write["写进仓库文件<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Confluence 里的规则"] --> Write+ Heads["工程师脑子里的规则"] --> Write+ Jira["Jira 里的规则"] --> Write+ Write --> Repo["仓库文件"]+ Repo --> Agent["新的 agent 会话<br/>直接读仓库"]+ Warning["规则不写进仓库<br/>agent 就看不见"] --> Agent``````mermaid-graph TB- subgraph "冷启动测试"- Q1["这是什么系统?"]- Q2["怎么组织的?"]- Q3["怎么跑?"]- Q4["怎么验证?"]- Q5["现在做到哪了?"]- end- Q1 & Q2 & Q3 & Q4 & Q5 -->|"全部能从仓库回答"| Pass["✅ Harness 就绪"]+flowchart TB+ Q1["这是什么系统?"] --> A1["AGENTS.md / README"]+ Q2["怎么组织的?"] --> A2["ARCHITECTURE.md / 模块文档"]+ Q3["怎么跑?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["怎么验证?"] --> A4["测试、lint、check 命令"]+ Q5["现在做到哪了?"] --> A5["PROGRESS.md / 功能清单 / git 历史"]++ A1 --> Ready["新的会话不用问人<br/>就能开始工作"]+ A2 --> Ready+ A3 --> Ready+ A4 --> Ready+ A5 --> Ready```## 为什么会这样diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex d6b2786..90f1995 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -23,26 +23,22 @@## 指令文件架构```mermaid-graph TB- subgraph "三层结构"- L1["<b>第一层:路由文件</b><br/>AGENTS.md (50–200 行)<br/>概览 + 硬约束 + 链接"]- L2a["<b>第二层 a</b><br/>api-patterns.md"]- L2b["<b>第二层 b</b><br/>database-rules.md"]- L2c["<b>第二层 c</b><br/>testing-standards.md"]- L3["<b>第三层:内联注释</b><br/>类型定义, 接口注释"]- end-- L1 -->|"链接"| L2a- L1 -->|"链接"| L2b- L1 -->|"链接"| L2c- L2a & L2b & L2c -->|"引用"| L3-- style L1 fill:#D95C41,color:#fff+flowchart LR+ Mono["一个超长 AGENTS.md"] --> MonoLoad["改一个小 bug<br/>也得把部署说明和历史备注全读一遍"]+ MonoLoad --> MonoRisk["关键规则埋在中间<br/>很容易漏掉"]++ Router["短 AGENTS.md"] --> Topics["按任务去读 API / 数据库 / 测试文档"]+ Topics --> RoutedResult["把更多上下文留给代码阅读<br/>和验证"]``````mermaid-graph LR- Top["文件顶部<br/>✅ 高召回率"] --- Mid["文件中间<br/>❌ 中间迷失效应"] --- Bot["文件底部<br/>✅ 高召回率"]+flowchart TB+ File["600 行指令文件"] --> Top["顶部<br/>快速开始 + 硬约束"]+ File --> Mid["中部<br/>第 300 行的安全规则"]+ File --> Bot["底部<br/>明确的结束检查清单"]+ Top --> Seen["高概率被记住"]+ Bot --> Seen+ Mid --> Missed["高概率被稀释或忽略"]```## 为什么会这样diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex b7cbce5..7f8bb71 100644--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -23,25 +23,26 @@## 会话连续性流程```mermaid-graph LR- subgraph "会话 N"- Work1["执行任务"] --> Update1["更新 PROGRESS.md<br/>更新 DECISIONS.md"]- Update1 --> Commit1["Git 提交检查点"]- end- subgraph "会话 N+1"- Read1["读取 PROGRESS.md<br/>读取 DECISIONS.md"] --> Resume["从下一步继续"]- Resume --> Work2["继续工作"]- end-- Commit1 -->|"交接"| Read1+flowchart LR+ S1["会话 1<br/>功能做到一半"] --> End1["上下文快满了<br/>会话结束"]+ End1 --> S2["会话 2 重新开始"]+ S2 --> Guess["重新读目录、重跑测试、<br/>猜上次为什么这么写"]+ Guess --> Drift["代码会重复改<br/>恢复速度也很慢"]``````mermaid-graph TB- subgraph "信息损失"- Full["完整上下文<br/>是什么 + 为什么 + 怎么做"] -->|"压缩"| Compact["压缩后<br/>是什么 ✓ · 为什么 ✗"]- Full -->|"新会话"| Reset["重置<br/>从工件重建"]- end+flowchart LR+ Work["会话 1 的工作"] --> Progress["PROGRESS.md<br/>已完成 / 进行中 / 下一步"]+ Work --> Decisions["DECISIONS.md<br/>为什么这样做"]+ Work --> Verify["验证记录<br/>哪些测试通过或失败"]+ Work --> Commit["Git 检查点<br/>当前仓库状态"]++ Progress --> Rebuild["会话 2 重建"]+ Decisions --> Rebuild+ Verify --> Rebuild+ Commit --> Rebuild++ Rebuild --> Resume["新会话能很快接上"]```## 为什么会这样diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex f11e65c..d11507c 100644--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -23,24 +23,19 @@## 初始化生命周期```mermaid-graph LR- subgraph "初始化阶段"- I1["可运行环境<br/><i>依赖已安装</i>"] --> I2["测试框架<br/><i>示例测试通过</i>"]- I2 --> I3["自举契约<br/><i>启动/测试/验证文档</i>"]- I3 --> I4["任务拆分<br/><i>有序的功能清单</i>"]- I4 --> I5["Git 检查点<br/><i>干净提交</i>"]- end- subgraph "实现阶段"- I5 --> P1["会话 2:功能 1"]- P1 --> P2["会话 3:功能 2"]- P2 --> P3["会话 N:功能 N"]+flowchart TB+ subgraph Wrong["混在一起的一次会话(错误)"]+ W1["一上来就开始做功能"] --> W2["做到一半才发现环境和测试缺口"]+ W2 --> W3["累积未经验证的代码"]+ W3 --> W4["下个会话还得重新摸项目状态"]end- style I1 fill:#D95C41,color:#fff- style I2 fill:#D95C41,color:#fff- style I3 fill:#D95C41,color:#fff- style I4 fill:#D95C41,color:#fff- style I5 fill:#D95C41,color:#fff+ subgraph Right["独立初始化阶段(正确)"]+ R1["会话 1:环境可运行"] --> R2["示例测试通过"]+ R2 --> R3["写出启动契约 + 任务清单"]+ R3 --> R4["提交干净检查点"]+ R4 --> R5["后续会话直接开始做已准备好的任务"]+ end```## 为什么会这样diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdindex bca4520..4272ed4 100644--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -23,21 +23,23 @@ Anthropic 在 "Effective harnesses for long-running agents" 工程博客中明## WIP=1 工作流```mermaid-graph LR- subgraph "WIP = 1(正确做法)"- Pick1["选取功能"] --> Do1["实现"] --> Verify1["端到端验证"]- Verify1 -->|"通过"| Commit1["提交"]- Commit1 --> Next1["下一个功能"]- Verify1 -->|"失败"| Do1- end+flowchart LR+ Queue["功能队列"] --> Pick["只选一个任务"]+ Pick --> Active["仅允许一个 active"]+ Active --> Verify["跑端到端验证"]+ Verify -->|通过| Commit["提交并解锁下一个任务"]+ Verify -->|失败| Active+ Commit --> Queue``````mermaid-graph LR- subgraph "无约束(错误做法)"- Pick2["同时激活 5 个功能"] --> Do2["全部做一点"]- Do2 --> Result2["800 行,12 个文件<br/>20% 通过率 ❌"]- end+flowchart TB+ Budget["可用推理预算 = C"] --> One["WIP = 1<br/>每个任务拿到 C / 1"]+ Budget --> Many["WIP = 5<br/>每个任务只有 C / 5"]++ One --> Finish["一个功能进入 passing"]+ Many --> Partial["五个功能都只做了一半"]+ Partial --> VCR["已验证完成率低<br/>下一会话返工高"]```## 为什么会这样diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdindex ab4d0a9..01499c8 100644--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -23,26 +23,26 @@## 功能状态机```mermaid-stateDiagram-v2- [*] --> not_started- not_started --> active: Agent 选取任务- active --> passing: 验证命令通过- active --> blocked: 外部依赖阻塞- blocked --> active: 依赖已解决- passing --> [*]-- note right of passing- 不可逆:一旦 passing,- 不能回退- end note+flowchart LR+ Feature["一行功能项"] --> Behavior["行为<br/>例如:POST /cart/items 返回 201"]+ Feature --> Check["验证命令<br/>具体要跑什么检查"]+ Feature --> State["状态<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["三列都齐了<br/>这行功能项才能用"]+ Check --> Complete+ State --> Complete``````mermaid-graph TB- FL["📋 功能清单<br/><i>单一权威来源</i>"] --> Scheduler["调度器<br/><i>选取下一个任务</i>"]- FL --> Verifier["验证器<br/><i>执行验证命令</i>"]- FL --> Handoff["交接报告器<br/><i>生成摘要</i>"]- FL --> Progress["进度追踪器<br/><i>统计状态分布</i>"]+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["选下一个 not_started"]+ Scheduler --> Agent["agent 只做这一项"]+ Agent --> Verifier["跑这一项自己的验证命令"]+ Verifier -->|通过| Passing["写成 passing<br/>并补上验证证据"]+ Verifier -->|失败| Active["继续保持 active"]+ Verifier -->|依赖问题| Blocked["标成 blocked"]+ Passing --> Handoff["更新交接说明<br/>和当前进度"]+ Active --> Agent```## 为什么会这样diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex 605ff8e..64345d0 100644--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -23,27 +23,18 @@## 三层终止检查```mermaid-graph LR- subgraph "验证闸门"- L1["第一层<br/>语法与静态分析<br/><i>lint, 类型检查</i>"]- L2["第二层<br/>运行时行为<br/><i>单元与集成测试</i>"]- L3["第三层<br/>系统级确认<br/><i>端到端, 用户场景</i>"]- end-- L1 -->|"必须通过"| L2- L2 -->|"必须通过"| L3- L3 -->|"全部通过"| Done["✅ 完成"]-- style L1 fill:#F4F3EE- style L2 fill:#E8E7E2- style L3 fill:#D95C41,color:#fff+flowchart LR+ Claim["agent 说:做完了"] --> L1["先跑<br/>lint / typecheck"]+ L1 --> L2["再跑<br/>测试和启动检查"]+ L2 --> L3["最后跑<br/>完整用户流程"]+ L3 --> Done["三层都过才算完成"]``````mermaid-graph LR- Agent["Agent: '我做完了!'"] -->|"置信度"| High["高置信度"]- Reality["实际质量"] -->|"实测"| Low["低质量"]- High -.->|"校准偏差"| Low+flowchart LR+ A["代码写完了<br/>单测也绿了"] --> B["但应用没真正启动<br/>完整流程也没跑"]+ B --> C["配置、数据库、外部服务问题<br/>还都藏着"]+ C --> D["于是 agent 太早宣告完成"]```## 为什么会这样diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdindex 85da5e5..691c561 100644--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -22,26 +22,27 @@ Google 的测试金字塔告诉我们:大量单元测试是基础,但如果## 测试金字塔与审查反馈提升```mermaid-graph TB- subgraph "测试充分性梯度"- E2E["端到端测试<br/><i>捕获组件边界缺陷</i>"]- Int["集成测试"]- Unit["单元测试<br/><i>快速但隔离</i>"]+flowchart TB+ subgraph Unit["单元测试只看孤立部件"]+ U1["渲染层测试"]+ U2["Preload 测试"]+ U3["服务层测试"]end- Unit --> Int --> E2E-- style Unit fill:#F4F3EE- style Int fill:#E0DFD9- style E2E fill:#D95C41,color:#fff+ subgraph E2E["端到端运行会穿过真实系统"]+ R["点击渲染层按钮"] --> P["Preload 桥"]+ P --> S["服务层"]+ S --> F["文件系统 / 操作系统"]+ F --> Result["真实导出文件"]+ end``````mermaid-graph LR- Review["代码审查<br/>重复性反馈"] --> Pattern["识别模式"]- Pattern --> Rule["创建可执行检查<br/>+ 面向 agent 的错误消息"]- Rule --> Harness["加入 harness"]- Harness -->|"预防同类问题"| Agent["🤖 Agent"]+flowchart LR+ Review["审查意见:<br/>renderer 不能直接 import fs"] --> Rule["加一条 direct fs import 检查"]+ Rule --> Message["报错里直接告诉 agent<br/>把文件访问移到 preload"]+ Message --> Harness["把这条检查加入 harness"]+ Harness --> Stronger["以后再犯会第一时间报错"]```## 为什么会这样diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdindex 069f53a..443b613 100644--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -23,25 +23,13 @@## 双层可观测性```mermaid-graph TB- subgraph "过程层"- SC["冲刺合同<br/><i>范围 + 标准 + 排除项</i>"]- ER["评估评分标准<br/><i>结构化评分</i>"]- end- subgraph "系统层"- Logs["运行时日志"]- Traces["请求追踪"]- Health["健康检查"]- end-- SC -->|"指导"| Gen["生成器"]- Gen -->|"产出"| Runtime["运行时行为"]- Runtime --> Logs & Traces & Health- Logs & Traces & Health -->|"证据"| ER- ER -->|"反馈"| Gen-- style SC fill:#D95C41,color:#fff- style ER fill:#D95C41,color:#fff+flowchart LR+ Contract["先把这次任务写清楚<br/>改哪些文件 / 不改哪些部分 / 怎么算通过"] --> Generator["生成器"]+ Generator --> Signals["运行时收集<br/>日志 / 追踪 / 健康检查"]+ Contract --> Review["按检查表逐项看<br/>功能 / 测试 / 边界"]+ Signals --> Review+ Review --> Verdict["指出哪一项没过<br/>以及应该去改哪里"]+ Verdict --> Generator```## 为什么会这样diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdindex 161c992..d98a571 100644--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -23,33 +23,29 @@ OpenAI 和 Anthropic 都明确指出:**长期可靠性取决于操作纪律,## 清洁状态的五个维度```mermaid-graph TB- subgraph "会话退出检查清单"- B["✅ 构建通过"]- T["✅ 测试通过"]- P["✅ 进度已记录"]- A["✅ 无过时工件"]- S["✅ 启动路径可用"]- end-- B & T & P & A & S -->|"缺一不可"| Clean["🧹 清洁状态"]- Clean -->|"保障"| Next["下一会话<br/>立即进入工作状态"]+flowchart LR+ Work["功能工作已完成"] --> Build{"构建通过?"}+ Build -->|是| Test{"测试通过?"}+ Build -->|否| Fix["先修好再退出"]+ Test -->|是| Record["更新功能清单 + 进度"]+ Test -->|否| Fix+ Record --> Cleanup["清理临时工件 / 调试代码"]+ Cleanup --> Startup{"标准启动路径可用?"}+ Startup -->|是| Clean["干净交接"]+ Startup -->|否| Fix+ Fix --> Build``````mermaid-graph LR- subgraph "12 周后(无清理)"- W1["第 1 周<br/>100% 构建, 100% 测试"] --> W4["第 4 周<br/>95% / 92%"]- W4 --> W8["第 8 周<br/>82% / 78%"]- W8 --> W12["第 12 周<br/>68% / 61%"]- end-- subgraph "12 周后(有清理策略)"- C1["第 1 周<br/>100% / 100%"] --> C12["第 12 周<br/>97% / 95%"]- end-- style W12 fill:#D95C41,color:#fff- style C12 fill:#4CAF50,color:#fff+flowchart LR+ Dirty["这次退出时<br/>测试是红的、临时文件没删、进度也没写"] --> Diagnose["下个会话先花时间<br/>搞清楚发生了什么"]+ Diagnose --> Fragile["接着在一个很乱的仓库上继续改"]+ Fragile --> More["更多调试文件、更多坏检查、<br/>更多说不清的进度"]+ More --> Dirty++ Clean["这次退出前<br/>测试是绿的、进度写了、临时文件删了"] --> Fast["下个会话打开仓库就能继续写代码"]+ Fast --> Stable["不用先救火"]+ Stable --> Clean```## 为什么会这样