| name | harness-install |
| description | 安裝並初始化本 repo 的 harness 制度庫（symlink、個人環境配置 env.md、健康檢查、導覽）。使用者 clone 本 repo 後說「安裝」「初始化」「setup」「裝起來」，或第一次在本 repo 目錄開 session 時使用。 |
harness-install：安裝精靈
目標：讓 clone 本 repo 的人一次完成安裝＋個人配置＋驗證，並知道怎麼開始用。
全程使用台灣用語的繁體中文。
步驟 1：選擇要 symlink 的 CLI/IDE
自動掃描發現可用的 AI 代理 CLI 工具（copilot、opencode、codex、antigravity、gemini、hermes、claude 等），列出已安裝和未安裝的狀態：
════════════════════════════════════════════
可用的 CLI / IDE 工具
════════════════════════════════════════════
✓ 已安裝：
1. claude → /home/yao/.local/bin/claude
2. codex → /home/yao/.nvm/versions/node/v22.20.0/bin/codex
3. copilot → /home/yao/.nvm/versions/node/v22.20.0/bin/copilot
4. gemini → /home/yao/.nvm/versions/node/v22.20.0/bin/gemini
5. hermes → /home/yao/.local/bin/hermes
6. opencode → /home/yao/.nvm/versions/node/v22.20.0/bin/opencode
選擇要 symlink 的工具：
a = 全部已安裝
1,2,3,... = 選擇特定工具編號
(直接按 Enter 略過此步驟)
規則：
- 自動掃描 PATH、npm global、常見 npm 套件位置
- 支持 6+ 個 AI 代理工具，並可擴展
- 已安裝的工具才能選，未安裝的工具不顯示
- 使用者可選「全部已安裝」(a) 或輸入編號組合 (1,2,3)
- 使用者略過本步驟 → 跳過 CLI symlink，只做核心安裝
步驟 2：跑安裝腳本
python3 claude/install.py
腳本是冪等的，會自動：
- 運行 AI CLI 工具選擇器（互動式選擇要 symlink 的工具）
- 改寫制度檔內的 HARNESS 路徑（repo 位置變了才改）
- 備份既有的
~/.claude/CLAUDE.md
- 建立入口 symlink
- 根據選擇在
~/.claude/cli/ 建立 CLI 工具的 symlink
~/.claude/env.md 不存在時從 claude/env.example.md 複製範本- 跑健康檢查
若腳本失敗，把錯誤原文貼給使用者，不要腦補修法；
symlink 不可用的環境（少見）改走 claude/README.md 的手動步驟。
步驟 3：訪談並填寫個人環境配置
讀 ~/.claude/env.md。若仍是範本佔位符（含 <GITLAB_HOST> 等字樣），逐項詢問使用者：
| 問題 | 對應欄位 | 可略過 |
|---|
| 有自架 GitLab 或其他內網 git 主機嗎？位址是？ | <GITLAB_HOST> | ✅ |
| 用什麼 CLI 操作 ticket？使用說明在哪？ | <TICKET_CLI>、<TICKET_CLI_DOC_URL> | ✅ |
| 有工作專案對應表（CSV 等）嗎？路徑是？ | <PROJECT_MAPPING_CSV_PATH> | ✅ |
| 有本機知識庫（LLM wiki）嗎？路徑是？ | <WIKI_ROOT> | ✅ |
| 本機有什麼要提醒未來 session 的注意事項？ | 本機注意事項 | ✅ |
規則：
- 一次問完（用一則訊息列出所有問題），不要一題一題往返。
- 使用者略過的項目：整行刪除或標「（無）」，不要留佔位符。
- 填完寫回
~/.claude/env.md。這個檔不在版控內，內網／公司資訊只能寫在這裡。
- 若 env.md 已有實際值（沒有佔位符），跳過本步驟，只回報「env.md 已配置」。
步驟 4：驗證
python3 claude/check_harness.py
- 全綠 → 繼續步驟 5。
- 有問題 → 照腳本印出的修復指令處理，修完重跑；連續兩輪修不好就停下來問使用者。
- 已知例外：若使用者自行安裝了會改
~/.claude/CLAUDE.md 的框架（如 OMC），
行數警告可能持續存在，如實回報並讓使用者決定，不要自行刪除框架內容。
步驟 5：一分鐘導覽（安裝完成後回報）
用簡短篇幅告訴使用者：
- 入口是
~/.claude/CLAUDE.md（symlink 到本 repo），每個 session 自動載入。
- 核心機制是路由表：命中情境才讀對應子檔，不要一次全讀。
- 紅線：內網位址、公司資訊、憑證只能寫
~/.claude/env.md，不可寫進 repo（公開的）。
- 客製化入口：改制度檔前先讀
claude/maintenance-protocol.md。
- 之後任何 Claude 相關工具安裝／升級後，重跑
python3 claude/check-harness.py。
