建立可重現且隔離的工作環境：實作與驗收指南

本課內容

01先把定義說清楚
02現場情境
03實作範例
04照著做，每一步都有檢查點
05實務脈絡
06動手實作
07故障診間
08正式上線前的邊界
09資料來源與主張限制

這一課會完成什麼

將 setup、seed、health 與 teardown 寫成冪等且版本化的生命週期
讓 ready 代表任務最小使用者旅程，而不是程序有啟動
為每個 worktree 派生完整 resource map 與 ownership receipt
在 cleanup 前解析並驗證精確 target，避免碰到其他本機專案

開始前先準備

• 模組 02 的 repository map 與固定 task contract
• 本機能建立 worktree，且可使用課程指定的 port 與合成資料路徑

先把定義說清楚

Initializer 與環境隔離

Initializer 是把乾淨 checkout 帶到可驗收狀態的版本化程序。它檢查 runtime 與 lockfile、安裝依賴、建立 task-scoped 資源、執行 migration、載入 fixture、準備 fixture identity、啟動服務，再以 task 的最小登入旅程判定 ready。Teardown 只清理由 environment ID 明確擁有的程序與檔案；多個 worktree 不能共用可變資料或觀測輸出。

Agent 若連環境是否健康都無法判斷，會把 setup failure 當成 product bug，修改 source 來迎合壞掉的本機狀態。另一個常見問題是只換 application port，database、cache、log 或 fixture 還共用，兩個 task 互相覆寫後卻很難從 trace 看出來。

可靠 initializer 也縮短交接。全新 session 不需要猜安裝順序、手動登入或詢問某個 migration 是否跑過。它取得帶 phase、version、resource map 與 health evidence 的 receipt，失敗時有安全修復；成功時則知道哪些條件已驗過，哪些仍要由功能 eval 判斷。

現場情境

兩個 worktree 共用了 audit database

Port、database、程序、records 與 collision outcome 都是課程 fixture。

負責人: 你是要讓兩個 coding task 同時在本機跑的 developer-platform owner。
要做的決策: 完整 resource identity 應包含哪些欄位，cleanup 如何證明精確 ownership？
目前狀態: 兩個 worktree 使用不同 app port，但 DATABASE_URL、browser profile 與 screenshot folder 相同。Worker A 的 seed 被 B 重設；A 的驗收截圖也被 B 覆寫。
預期成果: 兩套環境能同時操作不同 fixture，receipt 顯示無 collision，cleanup 只移除指定 task 資源。

限制條件

• 不得停止或修改 fixture 標記之外的程序與路徑
• Seed 必須冪等，不能連 production 或讀取真實客戶資料
• Ready 必須通過登入後 request list 與 detail read

實作範例

換 port 還不夠

證據類型: 具名模擬情境

Worker A 用 4101、Worker B 用 4102，畫面看似獨立。兩者仍連同一個 sqlite path、共享 `.cache`、browser profile 與 `artifacts/latest`。B 重跑 seed 後，A 的 audit count 歸零，最後一張截圖也變成 B 的頁面。

Initializer 建立 resource map，所有資源名稱都含 environment ID。Database、cache、log、browser、fixture、PID 與 screenshot 各有獨立路徑。Health receipt 存 identity 與 hash；cleanup 先 dry run，逐項核對 metadata，再停止 exact PID 與移動 exact temporary directory。

Collision fixture 同時啟動兩套環境，各自提交 changes 後 audit count 均為一。清理 A 時 B 仍可操作，課程另放的 unrelated listener 也保持存活。Receipt 保存 exact target，不曝光 session secret。

主張限制

本機 path 隔離適合教材。Production 可能需要 container、ephemeral database、workload identity、network policy 與更嚴格的資源生命週期。

做法

照著做，每一步都有檢查點

現場情境

完整 resource identity 應包含哪些欄位，cleanup 如何證明精確 ownership？

01定義生命週期與輸入
02派生並驗證 resource map
03把 health 延伸到登入旅程

驗收條件

任何新 session 能用一個命令取得健康且隔離的 Release Desk 環境；失敗可以定位到 phase，cleanup 也只作用於明確擁有的資源。

這張圖要幫你看懂什麼Worktree resource map 能把看不見的共享狀態與 cleanup 邊界畫出來。

01
定義生命週期與輸入
鎖定 runtime、package manager、lockfile、migration、seed version 與 environment ID 格式。每個 phase 宣告輸入、輸出、terminal code、repair、是否可安全重跑，以及 cleanup owner。
檢查點 · 缺 runtime、lock drift、migration fail、seed fail 與 browser missing 都回不同狀態，不會被 ready 蓋掉。
02
派生並驗證 resource map
為每個 worktree 建 port、database、cache、log、screenshot、browser、fixture、PID 與 temp path。啟動前檢查 collision，將 resolved path 限定在明確課程 temporary root。
檢查點 · 兩個 environment receipt 沒有共享可變資源；broad path、空 ID 與既有 owner collision 都 fail closed。
03
把 health 延伸到登入旅程
依序驗程序、database、migration、fixture account、session、request list、detail 與 audit read。任何必要層 skipped 都不得回 ready，輸出 evidence ID 與安全修復。
檢查點 · Ready receipt 能從乾淨 worktree 重現第一個 task dependency，且不依賴人工登入。
04
執行 collision 與 cleanup drill
同時在 A、B 建立不同狀態，再清理 A。加入 unrelated listener 與相似路徑，先檢視 dry-run target，確認 ownership 後才執行 scoped teardown。
檢查點 · A 資源全部移除，B 與 unrelated listener 不受影響；target、owner 與結果保存於 receipt。

實務脈絡

展示版之後

把 ready 定義到第一個任務相依

程序 liveness、HTTP root 200 與真正 ready 是三件事。Request transition 任務至少要驗 database migration、fixture request、reviewer session、request list、detail page 與讀取 audit 的安全路徑。若 browser binary 缺少或 seed 不完整，狀態應為 failed 或 blocked，不能把相關 suite 記為 optional pass。

每個 phase 都輸出 started、completed、failed 與 stable code，並保留 safe repair。Initializer 重跑不能重複插入 fixture 或留下一批新程序。版本、lockfile、migration、seed 與 health check 變更都要反映在 receipt。

隔離所有可變與可觀測資源

從 task environment ID 派生 app port、database name 或 path、cache namespace、log directory、screenshot directory、browser profile、fixture identifier、PID record 與 temporary directory。啟動前檢查 collision，cleanup 前再核對 ownership。只憑 port 找程序不夠，因為同一個 port 可能屬於另一個專案。

任何刪除或停止都先印出 resolved target，以 exact path、environment metadata 與 owner 驗證。空變數、`~`、workspace root、模糊 glob 與遞迴 broad target 一律 fail closed。課程 fixture 要特別放一個 unrelated listener，證明 teardown 不會碰它。

交付補強

Initializer receipt 要能回答環境到底準備到哪一層。Runtime 與 lockfile 合法、依賴安裝完成、migration 套用、seed 對應版本、fixture identity 可用、服務啟動、登入旅程可讀，各自都要有 phase 與 evidence。若 database ready 但 browser profile 壞掉，repair 應只重建 owned browser resource，不該刪掉整個工作樹或清除其他專案的 cache。可局部修復會減少 agent 為 setup 問題做大範圍重置的衝動。

資源命名需要同時可讀與不可碰撞。Environment ID 可以由 repository slug、worktree hash 與 task ID 組成，再派生 port reservation、database、cache、log、artifact 與 PID metadata。Hash 避免路徑過長，task ID 讓 operator 能辨識 owner。派生結果仍要在使用前檢查，因為 port 可能被其他程式占用、temporary path 也可能殘留舊 metadata；不能因命名看起來唯一就略過 read-back。

Seed 應以 desired fixture state 為目標，而不是每次盲目 insert。相同 version 重跑，request、reviewer 與 audit 起始數量保持一致；舊 version 需要明確 migration 或 rebuild。課程 canary 要能證明程式沒有讀 production environment variable，也沒有從開發者既有資料庫撈出類似紀錄。若 fixture 必須連外下載，先固定 checksum 與 mirror policy，network failure 不得偷偷改用未知最新版。

Teardown 是 initializer 的對稱交付。Dry run 列每個 exact target、resolved path、recorded owner、目前 PID identity 與預期操作。執行前再次比對，PID 若已被系統重用就停止，不以舊紀錄殺程序；路徑若不在明確 temporary root 也停止。刪除完成後做 read-back，證明指定資源不存在、相鄰 worktree 仍健康、unrelated listener 仍可回應，receipt 才能寫 cleanup complete。

環境失敗的回饋要讓接手者看得懂，也要限制可執行修復。例如依賴版本不符，可以建議使用 repository 宣告的套件管理指令；資料遷移失敗，應指出哪一個版本、哪一段唯讀檢查與保存紀錄，不可直接建議刪除資料庫。每個修復都先確認資源擁有者與路徑，執行後重新跑受影響階段，再跑登入旅程。這能避免 agent 為了快速回到綠燈，採用清空所有狀態或停止未知程序等高風險手段。

動手實作

實作 initializer、resource map 與 scoped teardown

讓兩個 Release Desk worktree 同時啟動，完成各自登入與 request 操作，再故意製造 collision、seed failure 與 unrelated listener，驗證診斷和 cleanup。

準備項目

• 檢查本機既有 listener 與課程可用 port，不要終止不屬於本專案的程序
• 準備兩個明確 worktree path 與 environment ID，禁止用空變數或 home directory 當 target

本課產出

Initializer script、phase manifest、resource map schema、idempotent seed、readiness journey、兩個環境 receipt、collision fixture、dry-run teardown 與 exact-target cleanup report。

起始模板: Initializer phase manifest

YAML

version: 1
environmentId: derive-from-worktree
phases:
  - inspect
  - install
  - prepare-fixture
  - start
  - verify-user-path
resources:
  port: task-scoped
  database: task-scoped
  logs: task-scoped
  screenshots: task-scoped
cleanup:
  printResolvedTargets: true
  requireEnvironmentId: true

可下載的實作檔

Initializer contract

initializer-contract.yml · YAML

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-03-receipt.json · JSON

A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.

驗收指令

npm run harness:init -- --environment he-03-a && npm run harness:health -- --environment he-03-a

預期 receipt

PASS he-03 environment-ready
environment=he-03-a userPathReady=true
isolation=verified cleanupScope=task-only

預期結果

任何新 session 能用一個命令取得健康且隔離的 Release Desk 環境；失敗可以定位到 phase，cleanup 也只作用於明確擁有的資源。

留給下一課

後續 feature ledger、tool、eval、trace 與 screenshot 都要記 environment ID。任何 resume 或 parallel dispatch 在環境 receipt 不健康、ownership 不一致時必須停止。

驗收條件

01Initializer 重跑不增加 fixture effect 或孤兒程序
02Ready 涵蓋 migration、fixture identity、登入、request list、detail 與 audit read
03兩個 worktree 的 network、資料、cache、log、截圖、browser 與程序完全隔離
04Cleanup 拒絕 broad target，並證明另一個 worktree 和 unrelated listener 未受影響

常見故障

故障診間

F1Initializer 顯示 ready，登入後第一頁卻報錯。

先檢查: 分開檢查 liveness、migration、seed、session、request list 與 browser smoke。
可能原因: Readiness 停在程序或 root page，沒有涵蓋 task 依賴。
修復方式: 把必要登入旅程納入 ready，缺任何一層就 fail。
下次怎麼避免: Task contract 變更時同步 review readiness registry。

F2第二個 worktree 改變第一個的紀錄或截圖。

先檢查: 比較兩份 receipt 的 port、資料路徑、cache、log、browser、fixture 與 PID。
可能原因: 只隔離 app port，其他可變資源仍為 global。
修復方式: 把全部資源納入 environment-ID map，清掉 fixture 後重新建立。
下次怎麼避免: Startup 變更都跑 two-worktree collision fixture。

F3Cleanup 修好 lab，卻關掉另一個專案。

先檢查: 檢查 PID、port、path 與 ownership 是如何解析與驗證。
可能原因: 使用 broad lookup 或未解析變數決定 destructive target。
修復方式: 復原不相關程序，改用 environment metadata 與 exact target。
下次怎麼避免: 所有 cleanup 先 dry run，拒絕 broad root、空變數、模糊 glob 與 port-only ownership。

展示版之後

正式上線前的邊界

01Initializer 的輸入、lock、phase、terminal code、repair 與版本都在 repository
02Readiness 證明 task 所需的最小登入與 authoritative persistence 旅程
03每個 worktree 隔離 network、資料、cache、log、browser、截圖、程序與 fixture
04Seed 冪等且不存取 production 資料或真實憑證
05Failure output 有 stable code、safe repair、evidence ID 與 redaction
06Cleanup 解析、列印、驗證並只移除帶有明確 environment ownership 的 target

證據類型

資料來源與主張限制

資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。

[1]
長時間執行 agent 的有效 harness
Anthropic · 已發表研究 · 2026-08-26
initializer 模式 · feature ledger · session 交接 · 端到端驗證
[2]
Harness engineering：在 agent-first 開發環境中運用 Codex
OpenAI · 公開案例 · 2026-08-26
知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
[3]
Harness Engineering Guide
Nexu · 公開案例 · 2026-08-26
執行環境邊界 · 工具系統 · sandbox · 復原模式
[4]
Learn Harness Engineering
Walking Labs · 公開案例 · 2026-08-26
專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
[5]
Harness Engineering 學習指南
deusyu · 公開案例 · 2026-08-26
repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理