AI-readable install page · v0.3.67

English version

給 AI 讀的
安裝與升級指令

本頁給能讀寫本機資料夾、可執行終端機命令的 agentic AI 使用。用戶不用先理解 npm 或選擇指令；AI 讀完本頁後，應在目前資料夾安全判斷要安裝、升級或停止。

版本提示：本頁對齊 v0.3.67；@latest 實際取得版本以 npm registry 為準。

用戶只需貼這一句

請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html ，並在這個資料夾安裝或升級 Agent Handoff Kit。

AI 完成後必須回覆這份報告

執行任何 `npx` 命令前，先記住本段。安裝或升級完成後，AI 不可只說「完成」或只貼終端機輸出；必須用以下格式向用戶交代結果和下一步。

完成報告範本：✅ 安裝完成。📁 目前資料夾：<絕對路徑>。🩺 `doctor` 已通過。⚠️ 下一步不是終端機指令；請在能讀寫此資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」。若 AI 還未指向此資料夾，才使用：`Work in <絕對路徑>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.`

AI 必須先確認目前資料夾

  1. 顯示目前工作資料夾的絕對路徑。
  2. 問用戶：「這是否就是要安裝或升級 Agent Handoff Kit 的資料夾？」
  3. 未能確認時停止，不執行 `init`、`upgrade` 或 `doctor`。
  4. 確認後才檢查本資料夾是否已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`START_NEXT_SESSION_PROMPT.txt` 或 `dev/`。
安全邊界： 不刪除、不覆寫衝突、不處理 credential、不執行 git commit、不執行 git push、不執行 git tag、不執行 npm publish、不建立 GitHub Release。

判斷安裝方式

情況一：完全未安裝

如果沒有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`START_NEXT_SESSION_PROMPT.txt`、`dev/`，使用 fresh install。

npx --yes @adamchanadam/agent-handoff-kit@latest init --yes --root .

情況二：已有 Kit 或 AI 記憶檔

如果已有任何 Kit 檔案或既有 AI 記憶檔，先預演升級，不直接覆寫。

npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run --root .
預演無衝突時： 才執行正式升級。 
npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --yes --root .
預演有 conflict 時： 停止並保持零寫入。用戶不用判斷技術差異，也不用選 npm 指令；能讀寫此資料夾的 AI 要讀 CLI 輸出、衝突檔與正式來源，先取得用戶授權，再把本地有價值的內容與新版 Kit 要求合併。未知本地 hash 只證明內容存在且未被偷換，不代表 Kit 可以理解或覆寫。合併後重新跑 `upgrade --dry-run`，再用 `doctor` 與 hash 讀回驗收；只有能證明是 Kit 誤判未改動的正式舊檔時，才把版本、來源與 hash 證據回報 Kit maintainer。不要用重裝或整檔覆寫繞過 conflict。

完成後驗收

本版亦補強日常規則寫入邊界。之後用戶要求加入長期規則時，依已安裝的 dev/rules/agent-governance.md 中 Governance Write Boundary 查找既有可寫位置、保護官方正文並核對讀取路徑。這不會自動整理先前混入正文的本地規則；遇到這類衝突，仍按上面的授權合併流程處理。

升級結果與整個項目的健康狀態要分開報告。版本號更新本身不是完成證據。原有交接內容會保留，AI 應在下一次正式收工時按新版規則核對整體目標、子任務、續接點與真源閱讀缺口，不得在升級時猜補工作狀態。

  1. 先讀回同次操作的根目錄、CLI 版本、完整終態及健康結果。只有程序以成功退出碼結束、安裝完成或升級已提交（或確定無需更新）、沒有未完成交易、健康結果明示通過，而且其後沒有相關檔案變更或不明狀態時，才直接採用同次 doctor 結果，不再執行一次；所有提醒仍須保留。不能只憑版本號、畫面中的「成功」或舊對話紀錄判斷。
  2. 若操作失敗、中斷、輸出不完整或其後改過相關檔案，不採用先前的通過結果。存在未完成升級交易時，先按 CLI 指引執行 upgrade --yes --root . 恢復，再核對完整終態；不要刪鎖，也不要用單獨 doctor 取代恢復。沒有未完成交易而仍缺乏有效健康結果，或用戶另行要求檢查時，才重新執行以下命令。
npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .

同次健康結果只證明該次本地檢查，不代表重新查過 npm 最新版。需要宣稱版本最新時，仍須核對 npm registry 與實際 CLI／安裝版本；預演通過也不能代替正式安裝或升級完成。此規則不取消正式收工或獨立驗收另有要求的檢查。

  1. 若 `doctor` 通過，讀 `AGENTS.md`，再按 `Start Agent Handoff` 的開工流程接上本資料夾。
  2. 若 `doctor` 失敗，停止並向用戶列出失敗項；不要重裝覆寫。
  3. 若 `doctor` 只提示 `START_NEXT_SESSION_PROMPT.txt` 便利副本落後，說明它會在正式收工時重新產生；不要因此重裝。

AI 回覆格式

本段是頁頂完成報告契約的檢查清單。執行完後，AI 不可只說「完成」或只貼終端機輸出。必須用簡短中文向用戶交代結果和下一步。

完成報告範本：

✅ 安裝完成。📁 目前資料夾：<絕對路徑>。🩺 `doctor` 已通過。下一步不要留在終端機；請在能讀寫此資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」。若 AI 還未指向此資料夾，才使用：`Work in <絕對路徑>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.`