coding agent initializer worktree isolated environment

實作

建立可重現且隔離的工作環境

用單一初始化程序驗依賴、資料遷移、測試資料、登入與瀏覽器路徑，並替每個 worktree 隔離連接埠、資料、快取、紀錄、截圖與程序。

難度
中階
預估時間
125 分鐘
更新日期
2026-10-02
文案複核
speak-human-tw
兩輪
本課內容
  1. 01先把定義說清楚
  2. 02現場情境
  3. 03實作範例
  4. 04照著做，每一步都有檢查點
  5. 05實務脈絡
  6. 06動手實作
  7. 07故障診間
  8. 08正式上線前的邊界
  9. 09資料來源與主張限制

這一課會完成什麼

  • 將設定、初始資料、就緒檢查與清理寫成可安全重跑且有版本的生命週期
  • 讓就緒代表任務最小使用者旅程，而不是程序有啟動
  • 為每個 worktree 派生完整資源地圖與責任歸屬驗收憑證
  • 在清理前解析並驗證精確目標，避免碰到其他本機專案

開始前先準備

  • • 模組 02 的程式庫地圖與固定任務契約
  • • 本機能建立 worktree，且可使用課程指定的連接埠與合成資料路徑

先把定義說清楚

環境初始化與隔離

初始化程序要有版本，能把乾淨的程式庫帶到可驗收狀態。它檢查執行環境和 lockfile、安裝依賴、建立任務專用資源、執行資料遷移、載入測試資料與身分，再啟動服務。是否就緒，以任務所需的最小登入流程判定。清理程序只能移除環境識別碼明確擁有的程序與檔案；不同 worktree 各自保存可變資料和觀測結果，避免一項工作的啟動、重設或清理影響另一項工作。

Agent 若連環境是否健康都無法判斷，會把設定失敗當成產品 bug，修改來源來迎合壞掉的本機狀態。另一個常見問題是只換應用程式連接埠，資料庫、快取、紀錄或測試資料還共用，兩個任務互相覆寫後卻很難從執行軌跡看出來。

可靠初始化程序也縮短交接。全新工作階段不需要猜安裝順序、手動登入或詢問某個資料遷移是否跑過。它取得帶階段、版本、資源地圖與健康狀態證據的驗收憑證，失敗時有安全修復；成功時則知道哪些條件已驗過，哪些仍要由功能評測判斷。

現場情境

兩個 worktree 共用了稽核資料庫

連接埠、資料庫、程序、紀錄與衝突結果都是課程測試資料。

負責人
你是要讓兩個程式撰寫任務同時在本機跑的 developer-platform 負責人。
要做的決策
完整資源身分應包含哪些欄位，清理如何證明精確責任歸屬？
目前狀態
兩個 worktree 使用不同連接埠，卻共用 DATABASE_URL、瀏覽器設定檔與截圖資料夾。工作單元 B 重建初始資料時覆寫了 A 的資料，也覆寫了 A 的驗收截圖。
預期成果
兩套環境能同時操作不同測試資料，驗收憑證顯示無衝突，清理只移除指定任務資源。

限制條件

  • • 不得停止或修改測試資料標記之外的程序與路徑
  • • 初始資料建立程序必須能安全重跑，不能連正式環境或讀取真實客戶資料
  • • 就緒必須通過登入後請求清單與細節讀取

實作範例

換連接埠還不夠

證據類型: 具名模擬情境

工作單元 A 用 4101、B 用 4102，畫面看似獨立。兩者仍連同一個 SQLite 路徑，共享 `.cache`、瀏覽器設定檔與 `artifacts/latest`。B 重建初始資料後，A 的稽核次數歸零，最後一張截圖也變成 B 的頁面。

初始化程序建立資源地圖，所有名稱都綁定環境 ID。資料庫、快取、紀錄、瀏覽器、測試資料、PID 與截圖各自隔離。就緒憑證記錄身分與雜湊；清理先模擬執行並逐項核對中繼資料，才停止指定 PID、移動指定暫存目錄。

衝突測試資料同時啟動兩套環境，各自提交變更後稽核次數均為一。清理 A 時 B 仍可操作，課程另放的無關監聽程序也保持存活。驗收憑證保存精確目標，不曝光工作階段機密。

主張限制

本機路徑隔離適合教材。正式環境可能需要 container、ephemeral 資料庫、工作負載身分、網路規則與更嚴格的資源生命週期。

做法

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

兩個Release Desk worktree 各自連到獨立連接埠、資料庫、快取、紀錄、瀏覽器、截圖與 PID，清理僅作用於自己的環境 ID。

現場情境

完整資源身分應包含哪些欄位，清理如何證明精確責任歸屬？

  1. 01定義生命週期與輸入
  2. 02派生並驗證資源地圖
  3. 03把健康狀態延伸到登入旅程

驗收條件

新工作階段能用一個指令取得就緒且隔離的 Release Desk 環境。失敗能定位到具體階段，清理只處理已確認屬於該環境的資源。

這張圖要幫你看懂什麼Worktree 資源地圖能把看不見的共享狀態與清理邊界畫出來。
  1. 01

    定義生命週期與輸入

    固定執行環境、套件管理工具、lockfile、資料遷移、初始資料版本與環境 ID 格式。各階段宣告輸入、輸出、退出代號、修復方式、能否安全重跑，以及清理負責人。

    檢查點 · 缺執行環境、依賴與 lockfile 不一致、遷移失敗、初始資料失敗與缺瀏覽器，各回不同狀態，不能被就緒宣告掩蓋。

  2. 02

    派生並驗證資源地圖

    為各 worktree 分配連接埠、資料庫、快取、紀錄、截圖、瀏覽器、測試資料、PID 與暫存路徑。啟動前查衝突，並把解析後的路徑限制在課程指定的暫存根目錄。

    檢查點 · 兩個環境驗收憑證沒有共享可變資源；廣泛路徑、空 ID 與既有負責人衝突都拒絕執行。

  3. 03

    把健康狀態延伸到登入旅程

    依序驗程序、資料庫、資料遷移、測試資料帳戶、工作階段、請求清單、細節與稽核讀取。任何必要層 skipped 都不得回就緒，輸出證據 ID 與安全修復。

    檢查點 · 就緒驗收憑證能從乾淨 worktree 重現第一個任務依賴，且不依賴人工登入。

  4. 04

    執行衝突與清理演練

    同時在 A、B 建立不同狀態，再清理 A。加入無關監聽程序與相似路徑，先檢視模擬執行目標，確認責任歸屬後才執行限定範圍的環境清理。

    檢查點 · A 資源全部移除，B 與無關監聽程序不受影響；目標、負責人與結果保存於驗收憑證。

實務脈絡

展示版之後

G1

把就緒定義到第一個任務相依

程序仍在執行、首頁回 HTTP 200、任務環境已就緒，分別代表不同條件。請求狀態轉移任務還須確認資料遷移完成、測試請求存在、審查者能登入，並能讀取請求清單、細節與稽核。缺瀏覽器執行檔或初始資料時，回報失敗或 blocked，不能略過必要檢查後宣告通過。

每個階段輸出開始、完成或失敗狀態、穩定的錯誤代號與安全修復方式。初始化程序重跑時，不能重複插入測試資料或留下新程序。執行環境、lockfile、資料遷移、初始資料或就緒檢查改版，都要記入驗收憑證。

G2

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

依任務環境 ID 分配連接埠、資料庫名稱或路徑、快取命名空間、紀錄及截圖目錄、瀏覽器設定檔、測試資料識別碼、PID 紀錄與暫存目錄。啟動前查衝突，清理前核對資源歸屬。連接埠可能由其他專案使用，不能只憑連接埠判斷程序是誰的。

任何刪除或停止都先印出 resolved 目標，以精確路徑、環境中繼資料與負責人驗證。空變數、`~`、工作區根目錄、模糊 glob 與遞迴廣泛目標一律拒絕執行。課程測試資料要特別放一個無關監聽程序，證明環境清理不會碰它。

G3

交付補強

初始化憑證逐層列出就緒證據：執行環境與 lockfile 合法、依賴完成、資料遷移已套用、初始資料版本正確、測試身分可用、服務啟動，登入流程也可讀。資料庫就緒但瀏覽器設定壞掉時，只重建該環境擁有的瀏覽器資源，不刪整個工作樹或其他專案快取。各階段能局部修復，才不必為一項設定問題重設所有資源。

資源命名需要同時可讀與不可碰撞。環境 ID 可以由程式庫 slug、worktree 雜湊與任務 ID 組成，再派生連接埠預留額度、資料庫、快取、紀錄、交付檔案與 PID 中繼資料。雜湊避免路徑過長，任務 ID 讓操作人員能辨識負責人。派生結果仍要在使用前檢查，因為連接埠可能被其他程式占用、暫存路徑也可能殘留舊中繼資料；不能因命名看起來唯一就略過讀回核對。

資料初始化要產生指定的測試狀態。相同版本重跑後，請求、審查者和稽核起始數量應一致；舊資料則明確遷移或重建。用課程的洩漏偵測字串（canary）確認程序沒有讀取正式環境變數，也沒有從開發者的資料庫取用紀錄。必須連外下載的資料，固定檢查碼和鏡像來源規則；下載失敗時停止，不改抓未知版本。

清理與初始化使用同一份資源歸屬資料。先模擬執行，列出精確目標、解析後的路徑、歸屬紀錄、目前 PID 身分與預期操作。真正執行前再比對一次；PID 已被重用或路徑超出指定暫存根目錄，就停止。清理後確認指定資源已移除，其他 worktree 和無關監聽程序仍能運作，才記為完成。

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

動手實作

實作初始化程序、資源地圖與限定範圍的環境清理

同時啟動兩個 Release Desk worktree，完成各自的登入與請求操作。再刻意製造資源衝突、初始資料失敗與無關監聽程序，驗證診斷和清理。

準備項目

  • • 檢查本機既有監聽程序與課程可用連接埠，不要終止不屬於本專案的程序
  • • 準備兩個明確 worktree 路徑與環境 ID，禁止用空變數或 home 目錄當目標

本課產出

初始化腳本、階段清單、資源地圖 schema、可安全重跑的初始資料程序、就緒驗證流程、兩份環境憑證、衝突案例，以及模擬清理和精確目標清理的報告。

起始模板: 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

預期結果

新工作階段能用一個指令取得就緒且隔離的 Release Desk 環境。失敗能定位到具體階段，清理只處理已確認屬於該環境的資源。

留給下一課

後續功能台帳、工具、評測、執行軌跡與截圖都要記環境 ID。任何恢復或平行派送執行在環境驗收憑證不健康、責任歸屬不一致時必須停止。

驗收條件

  1. 01初始化程序重跑不增加測試資料操作效果或孤兒程序
  2. 02就緒涵蓋資料遷移、測試資料身分、登入、請求清單、細節與稽核讀取
  3. 03兩個 worktree 的網路、資料、快取、紀錄、截圖、瀏覽器與程序完全隔離
  4. 04清理拒絕廣泛目標，並證明另一個 worktree 和無關監聽程序未受影響

常見故障

故障診間

F1初始化程序顯示就緒，登入後第一頁卻報錯。
先檢查
分別檢查程序存活、資料遷移、初始資料、登入工作階段、請求清單與瀏覽器基本流程。
可能原因
就緒判斷只看程序或首頁，沒有檢查任務所需條件。
修復方式
把必要登入旅程納入就緒，缺任何一層就 fail。
下次怎麼避免
任務契約改版時，同步審查就緒檢查清單。
F2第二個 worktree 改變第一個的紀錄或截圖。
先檢查
比較兩份驗收憑證的連接埠、資料路徑、快取、紀錄、瀏覽器、測試資料與 PID。
可能原因
只隔離應用程式連接埠，其他可變資源仍為全域。
修復方式
把全部資源納入 environment-ID 地圖，清掉測試資料後重新建立。
下次怎麼避免
啟動變更都跑雙 worktree 衝突測試資料。
F3清理修好實作，卻關掉另一個專案。
先檢查
檢查 PID、連接埠、路徑與責任歸屬是如何解析與驗證。
可能原因
使用廣泛查詢或未解析變數決定破壞性目標。
修復方式
復原不相關程序，改用環境中繼資料與精確目標。
下次怎麼避免
清理先模擬執行，拒絕範圍過大的根目錄、空變數、模糊 glob，以及只按連接埠推測的程序歸屬。

展示版之後

正式上線前的邊界

  1. 01初始化程序的輸入、鎖定、階段、終止程式碼、修復與版本都在程式庫
  2. 02就緒檢查涵蓋任務需要的最小登入流程與實際資料持久化
  3. 03每個 worktree 隔離網路、資料、快取、紀錄、瀏覽器、截圖、程序與測試資料
  4. 04初始資料程序可安全重跑，不存取正式資料或真實憑證
  5. 05失敗輸出有穩定程式碼、安全修復、證據 ID 與敏感資訊遮蔽
  6. 06清理解析、列印、驗證並只移除帶有明確環境責任歸屬的目標

證據類型

資料來源與主張限制

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

  1. [1]
    長時間執行 agent 的有效 harness

    Anthropic · 已發表研究 · 2026-08-26

    initializer 模式 · feature ledger · session 交接 · 端到端驗證
  2. [2]知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
  3. [3]
    Harness Engineering Guide

    Nexu · 公開案例 · 2026-08-26

    執行環境邊界 · 工具系統 · sandbox · 復原模式
  4. [4]
    Learn Harness Engineering

    Walking Labs · 公開案例 · 2026-08-26

    專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
  5. [5]
    Harness Engineering 學習指南

    deusyu · 公開案例 · 2026-08-26

    repository 是工作紀錄 · 機械式規則 · agent 可讀性 · 持續整理

延伸的 Tenten 資源

Field guide

Sandboxed Autonomy

Tenten's guide to worktrees, ephemeral environments, and blast-radius control.

查看資源Field guide

Production security and cost

Continue into staged deployment, threat boundaries, secrets, and operating cost.

查看資源

當本機 harness 要接進真實程式庫

帶著驗收憑證、失敗案例，以及那條還拿不準的控制邊界來。

在團隊拉長 agent 自治時間前，Tenten 可以一起檢查程式庫可讀性、權限、評測器涵蓋、worktree 隔離、復原與上線證據。

預約成果檢視查看 FDE 交付方法