Leo
20c7610371
leo 2026-07-20 明令：「已經改用 cf 自己的 secrets，不要再說它了」 「我希望以後再也看不到這個詞再出現」 背景：credential 早已遷移至 CF Workers per-script Secrets + D1 目錄， 舊的自管金鑰（client 端 AES-GCM + KV 密文 + crypto_decrypt）是遷移期遺留。 本次連根移除，含一併作廢的死 SaaS 碼。 移除： - 舊 KV 密文解密路徑（credential-injector.ts 整檔、dual-read fallback） 前置驗證：leo21c / youlin 兩帳號 CREDENTIALS_KV 實測 *:cred:* 皆 0 筆 - migrate-to-workers-secrets 搬家端點（回填已完成，無可回填） - /register 路由與 generateApiKey（HMAC 產 ak_ key 是 SaaS 遺物； self-hosted 走 namespace 明碼 D21，已無人使用） - platform_crypto component（三帳號實測 404 已退役，無 workflow 引用） 保留（附理由）： - crypto_decrypt 保留為永遠回失敗的 stub——現役三個 auth .wasm 仍宣告該 import，缺項會讓 WASM instantiate 直接失敗。待零件重編後可真正刪除。 順帶修復（原不在範圍，但會實際壞事）： - /auth/callback 有 `if (!key) redirect(server_error)` 閘，未設該 secret 的 實例會登入直接失敗 → 已移除 - OAuth 兩處把 provider token 寫進舊加密 KV（租戶鍵與實際 api_key 在 rotate 後必然分歧，已失效）→ 改導向 Workers Secrets，包 try/catch 不影響登入 - acr init Standard 模式呼叫已刪除的 /register → 改引導 OAuth 取 key - .claude/rules 與 system-dev/docs 是同一規範的兩份鏡像，先前只改 rules 導致鏡像仍在教舊做法 → 已同步（此類雙檔同步應納入檢查） 新用戶安裝從此零 secret 前置。 測試 187/188（唯一 fail 為 pre-existing，stash 驗證與本次無關）； cypher-executor 與 cli typecheck 全綠。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
361 lines
24 KiB
Markdown
361 lines
24 KiB
Markdown
---
|
||
status: paused
|
||
superseded_by: ""
|
||
---
|
||
|
||
# Design: 用戶 CC harness（acr install-harness）
|
||
|
||
> 2026-06-03。richblack 已授權建此 SDD（白名單已加）。**待 review design 後動 code。**
|
||
> 背景：richblack 釐清「arcrun 是給 CC 的 harness」的真正意思（§0）。
|
||
|
||
---
|
||
|
||
## 0. 問題（richblack 原話）
|
||
|
||
> 「叫 CC 用 Arcrun 開發，它說『好，我先用 Python 測試』，因為它熟悉的還是 Python。
|
||
> harness 要：先提醒 CC 要用、它要用時知道去哪取得資源、做錯時被糾正，
|
||
> 讓用戶的 CC 不會再問這個笨問題。」
|
||
|
||
**核心區分（richblack 2026-06-03）**：
|
||
- **開發 arcrun**（richblack + 他的 CC）：用本 repo 本機 `.claude/CLAUDE.md`（SDD 協議、禁令）。
|
||
**不給用戶、不進公開 repo**（已 git rm --cached，本機保留供開發）。
|
||
- **使用 arcrun**（外部工程師 + 他的 CC）：在自己的專案用 arcrun。需要**另一套** harness，
|
||
透過「安裝」裝進他自己的專案。
|
||
|
||
用戶不 clone arcrun 來改，他在自己專案工作 → harness 必須裝在**用戶專案目錄**，
|
||
他的 CC 才會自動載入（Claude Code 只自動讀「當前工作目錄樹」的 CLAUDE.md / .claude）。
|
||
|
||
---
|
||
|
||
## 0.5 設計鐵則：guardrail 擋下時必須指出正路（從內部 harness 的慘痛教訓來）
|
||
|
||
> 2026-06-03 教訓：內部開發 harness 的 `pre-write-guard.sh` 規則 4.3 擋 CC 建新 SDD 目錄，
|
||
> 但 block 訊息只說「先與 richblack 確認」，**沒說「確認後要更新白名單才能往下」** →
|
||
> 開發 CC 被自己的 guardrail 卡死、不知正路、動不了。
|
||
|
||
**用戶 harness 的每個 guardrail（hook / 提醒）擋下時，必須在訊息裡給「具體怎麼做才能合法通過」的下一步。**
|
||
- 只說「不行」= 把 CC 卡死。
|
||
- 要說「不行，因為 X；正確做法是 Y（具體指令 / 檔案 / 步驟）」。
|
||
- 這是 DECISIONS §7「會回嘴的 CLI——exit 2 + **指回正路**」的「+指回正路」那半，內部版漏做，用戶版必須做足。
|
||
|
||
**驗收新增一條**：每個 guardrail 的 block/提醒訊息都含可執行的下一步（§7.6）。
|
||
|
||
---
|
||
|
||
## 0.6 骨架：一張前置清單，兩種人同走，必做的事白癡化（richblack 2026-06-03 收斂）
|
||
|
||
> richblack：「我有一系列必要做的前置環境設定，把它列出。技術好的一一完成；技術不好的只是許願，
|
||
> 讓他做盡量少，要做的所有事情白癡化。」
|
||
|
||
**整份 design 的核心模型**：不是「兩套不同流程」，是**同一張前置清單、差別只在誰執行**。
|
||
|
||
### 前置環境設定清單（PREREQ，權威清單）
|
||
| # | 項目 | 只能用戶做？ | 技術好的 | 技術不好的（許願型）|
|
||
|---|---|---|---|---|
|
||
| P1 | 裝 Node + `npm i -g arcrun` | 否 | 自己跑 | CC 代跑 |
|
||
| P2 | 裝 `npm i -g wrangler`（CF CLI）| 否 | 自己跑 | CC 代跑 |
|
||
| P3 | `acr install-harness`（裝防護）| 否 | 自己跑 | CC 代跑（CC 讀 llms.txt 第一步就做）|
|
||
| P4 | **建 CF 帳號 + 拿 Account ID + API Token** | **是**（憑證在用戶手上）| 自己建 | **CC 白癡化手把手帶**（§1.0 步驟2）|
|
||
| P5 | `acr init --self-hosted`（貼 token，自動建 KV/部署/seed）| 否 | 自己跑 | CC 代跑（用 P4 拿到的兩串）|
|
||
| P6 | `wrangler secret put CF_SECRETS_API_TOKEN` | 否 | 自己跑 | CC 代跑 |
|
||
| P7 | 連 arcrun MCP（`claude mcp add`，CC 偏好的工具）| 否 | 自己跑 | CC 代跑（install-harness 順便）|
|
||
|
||
### 兩種執行者
|
||
- **技術好**：拿這張清單，一一完成。清單清楚就夠（README / llms.txt 列出即可）。
|
||
- **技術不好（許願型，主要用戶）**：他只說「我要用 arcrun 做 X」=許願。CC 拿同一張清單，
|
||
**能代勞的全代勞（P1/P2/P3/P5/P6），唯一只能他做的 P4 白癡化成笨到不會錯的手把手步驟。**
|
||
|
||
### 用戶畫像（richblack 2026-06-03 鎖定第一版）
|
||
- **會開 terminal / vscode、會用 CC** → 跑指令、貼 token **不是**障礙（不用把跑指令白癡化）。
|
||
- **但 CF 概念對他們太抽象**（richblack 實測：很多人聽不懂 CF）→ **白癡化焦點 = CF 那段**。
|
||
|
||
### 設計要求：白癡化「焦點在 CF」，不是全面白癡化
|
||
- **P4（CF）必須白癡化到「不用懂 CF 概念也能完成」**：CC 對用戶**絕不講** KV namespace / Workers /
|
||
R2 bucket / zone 這些 CF 術語 → 只講「開這個網址、點這個鈕、複製這串、貼回來」。把 CF 的抽象**藏起來**。
|
||
- 其餘 CC 能代勞的（P1/P2/P3/P5/P6）→ CC 代跑，用戶會跑指令但不必自己想。
|
||
- 目標：**用戶不需要懂 CF 是什麼，照著做就裝好。** 用戶做的事 → 許願 + 跟著 CF 步驟點幾下 + 貼兩串。
|
||
|
||
→ 後面 §1.0（llms.txt 入口）、§2（install-harness）、§4（hook）都是「讓 CC 能拿著這張清單替用戶跑完」的手段。
|
||
|
||
---
|
||
|
||
## 1. harness 三層（對應三需求 + Claude Code 載入機制）
|
||
|
||
依 claude-code-guide 查證（2026-06-03）：
|
||
|
||
| 需求 | 機制 | 強制力 | 裝進用戶專案 |
|
||
|---|---|---|---|
|
||
| **事前提醒**「用 arcrun 別自寫 Python」| CLAUDE.md（session 必載入）| 弱（可能遺忘）| 用戶 `CLAUDE.md` append arcrun 區塊 |
|
||
| **資源去哪取** | Skill（按需觸發）+ CLAUDE.md 指令 | 中 | `.claude/skills/arcrun/SKILL.md` |
|
||
| **做錯被糾正** | PreToolUse hook（exit 2）| 強（需 workspace trust）| `.claude/hooks/arcrun-guard.sh` + settings.json |
|
||
|
||
三層互補：CLAUDE.md 會被 compaction 丟、Skill 可能不觸發、hook 最強但需 trust。事前+事中+事後，缺一不可。
|
||
|
||
---
|
||
|
||
## 1.0 第一接觸點：用戶只會聊天，CC 讀入口檔自己啟動（richblack 2026-06-03 鎖定用戶畫像）
|
||
|
||
> richblack：「用戶只會跟 CC 聊天，不裝不打指令、連 slash command 都不會用。
|
||
> 路2 = 把 arcrun 網站/GitHub 連結丟給 CC + 一句『我要用 arcrun 做這個專案，怎麼做』，然後兩手一攤。」
|
||
|
||
**用戶全部操作 = 丟連結 + 一句話。** 其餘全 CC 做。所以 harness 的「第一接觸點」必須是
|
||
**CC 在用戶還沒裝任何東西時就讀得到的入口檔**，且讀了就知道正確啟動順序。
|
||
|
||
### 雞生蛋問題 + 解法
|
||
- slash command / hook / skill 都要**先裝進用戶專案**才存在 → 但用戶還沒裝任何東西 → CC 看不到它們。
|
||
- 解：用「裝之前就讀得到的入口檔」叫 CC 去裝。兩個入口（CC 丟網站或丟 GitHub 都涵蓋）：
|
||
- **`arcrun.dev/llms.txt`**（網站根目錄，給 LLM 的標準入口檔）—— 用戶丟網站連結時 CC 會讀。
|
||
- **README 開頭一段「給 AI 操盤手」**—— 用戶丟 GitHub 連結時 CC 讀 README。
|
||
- 兩者內容一致，核心是：**「第一步：跑 `npm i -g arcrun && acr install-harness`，裝完你就有完整防護」**
|
||
+ 裝前先記的鐵則（別寫 Python、用戶只聊天你來操作 CLI）。
|
||
|
||
### 啟動流程（CC 讀入口檔後照做）
|
||
```
|
||
1. acr install-harness ← 裝防護（mindset Skill / arcrun-guard hook / /arcrun command / CLAUDE.md 區塊）
|
||
2. 手把手帶用戶建 CF 帳號、拿 token ← 唯一用戶親手做的事，CC 用內建話術一步步帶（見下）
|
||
3. acr init --self-hosted ← CC 幫跑，貼用戶 token
|
||
4. 把用戶需求拆 workflow → acr push ← CC 在 harness 防護下做事
|
||
```
|
||
|
||
→ llms.txt / README「叫 CC 去裝」（裝前就讀得到）；install-harness 提供「裝後的完整防護」。
|
||
→ 用戶從頭到尾只說人話。
|
||
|
||
### 步驟 2 細化：CC 手把手帶用戶拿 CF 憑證（richblack 2026-06-03）
|
||
|
||
> richblack：「連 CF 他都不會。但 CC 可以說：你現在去申請 CF 帳號，方法是…，完成後把 xxx 和 ooo 貼給我。」
|
||
|
||
**這是唯一用戶必須親手做的事**（憑證在用戶手上，CC 拿不到），所以 CC 的引導必須**手把手、零技術假設**。
|
||
這套話術要**內建在 llms.txt / harness 指引裡**，讓每個用戶的 CC 都用同一套清楚步驟帶，不自己亂講、不假設用戶懂。
|
||
|
||
CC 該給用戶的（**不講 CF 術語**，照抄式；用戶不用懂「Workers/KV/R2」是什麼，照著勾就好）：
|
||
```
|
||
我需要你去一個叫 Cloudflare 的免費服務拿「兩串文字」給我（你不用懂它是什麼，照做就好）。
|
||
做完把兩串貼回來：
|
||
|
||
【第一串：帳號代碼】
|
||
1. 開 https://dash.cloudflare.com/sign-up 用 email 註冊（免費）。
|
||
2. 登入後，畫面右邊有一塊寫 "Account ID"，點它旁邊的複製小圖示 → 這是第一串。
|
||
|
||
【第二串：金鑰】
|
||
3. 開 https://dash.cloudflare.com/profile/api-tokens
|
||
4. 點藍色 "Create Token" → 找 "Create Custom Token" 那欄點 "Get started"。
|
||
5. 在 "Permissions" 區照抄勾三組（不用懂意思，照填，按 "+ Add more" 加組）：
|
||
Account / Workers Scripts / Edit
|
||
Account / Workers KV Storage / Edit
|
||
Account / Workers R2 Storage / Edit
|
||
6. 一直按 Continue / Create Token，最後會顯示一串長文字 → 立刻複製（只出現這一次）→ 這是第二串。
|
||
7. 把兩串貼給我，我幫你裝好，你不用再碰 Cloudflare。
|
||
```
|
||
|
||
**白癡化要點**：CC 全程**不解釋**「什麼是 KV / Worker / token」——用戶聽不懂也不需要懂，
|
||
CF 術語當「照抄的咒語」。用戶卡住（找不到鈕）時，CC 用更白話描述位置，**不丟術語**。
|
||
|
||
CC 拿到兩串 → 跑 `acr init --self-hosted`（貼進去）→ 後續全自動。
|
||
**誠實/安全**：token 是用戶的、貼給 CC 用於部署到他自己的 CF；CC 不外傳、用完寫進用戶本機 config（init 已處理）。
|
||
|
||
---
|
||
|
||
## 1.5 第四層：slash command `/arcrun`（裝好後的主動入口，可選）
|
||
|
||
> richblack：「我的使用者技術不好，應該做很少的事，其他交給 CC。harness 一部分寫在 slash command 裡。」
|
||
|
||
> 定位（richblack 2026-06-03 鎖定用戶畫像後）：用戶**只會聊天、不一定會打 slash command**。
|
||
> 所以 `/arcrun` **不是主要路徑**——主要路徑是 §1.0（丟連結給 CC，CC 讀 llms.txt/README 自己啟動）。
|
||
> `/arcrun` 是 install-harness 裝好後的**可選**入口，給「願意打指令的用戶」或「CC 自己引用」用。不強求用戶會用。
|
||
|
||
**用戶實際路徑（重申，§1.0）**：丟連結 + 一句話 → CC 讀入口檔 → CC 跑 install-harness → CC 引導。
|
||
用戶不需要知道 `/arcrun` 存在。它存在是錦上添花（裝好後若用戶想要更明確的入口可打），不是必經。
|
||
|
||
**為何 command 而非只靠 Skill**（claude-code-guide）：
|
||
- Skill = Claude **自己判斷**要不要觸發（可能不觸發 → 用戶以為在用 arcrun，CC 卻自己寫 Python）。
|
||
- Command = 用戶**主動打 `/arcrun`** = 明確宣告「進入 arcrun 模式」→ CC 照 command 流程走，最可靠把用戶帶進正軌。
|
||
- **坑（claude-code-guide 警告）**：`/arcrun` 不要同時做成 command 又做成 skill（觸發邏輯衝突）。
|
||
→ **`/arcrun` 做成 command（用戶主動入口）；mindset 做成 Skill（被動世界觀，名字不同避免撞）。**
|
||
|
||
**command 檔機制**（claude-code-guide 查證）：
|
||
- 放 `.claude/commands/arcrun.md` → 自動成為 `/arcrun`，clone/放檔即可用，無需安裝/信任。
|
||
- 用戶打 `/arcrun <需求>`，`<需求>` 字串自動串進 prompt（無 $ARGUMENTS 變數，純文字追加）。
|
||
- command 檔是 prompt 模板，可指示 CC「讀 arcrun Skill、跑 `acr parts`、輸出 yaml、別寫 Python」。
|
||
- ⚠️ command 檔**不可用相對路徑引用 arcrun repo**（用戶專案沒有）→ 指令裡只提「跑 `acr xxx`」「讀你專案的 CLAUDE.md」。
|
||
|
||
---
|
||
|
||
## 2. 安裝指令（兩狀況、一指令）
|
||
|
||
richblack：用戶兩種狀況都「一個指令完成」——已有執行中專案、或新啟動專案。
|
||
|
||
- `acr install-harness`（主指令，獨立）：當前目錄安裝。新舊專案皆可。
|
||
- `acr init` 末尾呼叫同一套邏輯（兩者皆裝）。
|
||
|
||
### install-harness 行為（冪等）
|
||
|
||
```
|
||
acr install-harness （用戶專案根目錄）
|
||
1. CLAUDE.md：無→建；有→append arcrun 區塊（<!-- arcrun-harness:start/end --> 包夾，重裝取代區塊不重複）
|
||
2. .claude/skills/arcrun-mindset/SKILL.md：複製世界觀 Skill（覆蓋舊版；名 arcrun-mindset，避免與 /arcrun command 撞）
|
||
3. .claude/commands/arcrun.md：複製 /arcrun slash command（技術不好用戶的主動入口，§5.1）
|
||
4. .claude/hooks/arcrun-guard.sh：複製用戶版 guard（§4）
|
||
5. .claude/settings.json：無→建並註冊 hook；有→合併（不覆蓋用戶既有 hooks/設定）
|
||
6. （P7，optional）claude mcp add arcrun MCP —— CC 偏好工具；MCP 對齊未完成前可跳過（§2.5）
|
||
7. 印提示：首次開 Claude Code 要 trust 工作區 hook 才生效；技術不好的話直接打 /arcrun 描述需求
|
||
```
|
||
|
||
冪等：重裝不重複、不破壞用戶既有 CLAUDE.md / settings。
|
||
|
||
**技術不好用戶連 `acr install-harness` 都不用自己跑**：跟 CC 說「幫我把這專案設定成用 arcrun」→
|
||
CC 跑 `acr install-harness` → 裝好後用戶打 `/arcrun <需求>` 即可。用戶全程只說人話。
|
||
|
||
### 2.5 MCP（P7）：CC 偏好的工具，納入安裝 + update（richblack 2026-06-03）
|
||
|
||
> richblack：「先前有 MCP，因為是 CC 比較喜歡的工具，也要排入讓它 update。」
|
||
|
||
- arcrun MCP（`@inkstone/arcrun-mcp`）是 **Cloudflare Workers 上的 Remote MCP Server**，CC 用 `claude mcp add <url>` 連。
|
||
- **install-harness 順便連 MCP**（P7）：跑 `claude mcp add` 把 arcrun MCP 加進用戶的 Claude Code。
|
||
CC 偏好 MCP 工具 → 有 MCP，CC 操作 arcrun 更順（直接呼叫 MCP 工具，不用記 acr 指令細節）。
|
||
- **`acr update` 納入 MCP**：update 時確保 MCP 連線指向最新（URL / 版本對齊）。
|
||
- ⚠️ **誠實前置（BACKLOG 既有待辦）**：arcrun MCP 本身**尚待對齊**（`u6u_*`→arcrun 命名、`finally.click`→
|
||
arcrun.dev、移除 GUIDE.md 教 `api_config` 的反模式、確認薄殼）。**MCP 對齊是另一條 BACKLOG 線**；
|
||
本 SDD 只負責「把 MCP 納入 install-harness / update 的接點」。MCP 對齊未完成前，install-harness 的
|
||
MCP 步驟可先標 optional（用戶可跳過），對齊後再設為預設。self-host 用戶連哪個 MCP（公共 vs 自部署）待 §8 釐清。
|
||
|
||
---
|
||
|
||
## 3. harness 素材從哪來（內嵌 npm 套件）
|
||
|
||
用戶的 `acr` 是 `npm i -g arcrun` 裝的，不能假設用戶有 arcrun repo
|
||
→ harness 素材內嵌 npm 套件：放 `cli/harness/`，build 進 `dist/`，`files` 帶上。
|
||
install-harness 從已安裝套件目錄（`import.meta.url` 解析）複製到用戶 cwd。
|
||
SSOT = `cli/harness/`，與本 repo 開發版 `.claude` **不共用**（對象不同）。
|
||
|
||
---
|
||
|
||
## 4. 用戶版 hook 擋什麼（與開發版完全不同）
|
||
|
||
開發版擋「registry/components 寫 TS / 建 auth worker」——對用戶無意義。
|
||
用戶版 `arcrun-guard.sh`（每條都依 §0.5 給正路）：
|
||
|
||
| 偵測 | 動作 | block/提醒訊息含的正路 |
|
||
|---|---|---|
|
||
| arcrun 專案裡跑 `python *.py`/`node` 寫一次性自動化（典型「我先用 Python」）| **提醒**（不硬擋，避免誤殺正常 python）| 「這專案用 arcrun。串服務/自動化請寫 workflow：先跑 `acr parts` 看零件，寫 .yaml，`acr run`。確定要自刻請說明為何 workflow 做不到。」|
|
||
| 自寫「打某 API 的 script」而非 recipe | 提醒 | 「打固定 endpoint → 寫 recipe：`acr recipe push`。見 arcrun-mindset Skill §1。」|
|
||
| 暴露動作（部署 webhook）非 TTY 自動確認 | **exit 2**（明確越界）| 「暴露資料需人類在終端機確認。請把這動作交給人類執行。」|
|
||
|
||
**誠實限制（mindset §7）**：「跑 python」不絕對錯 → 多用「提醒 + 要 CC 自證」而非硬擋。
|
||
硬擋（exit 2）只留給「暴露資料未經人類同意」。把關依風險分級，不一刀切誤殺。
|
||
|
||
---
|
||
|
||
## 5. CLAUDE.md arcrun 區塊（事前提醒，精簡對外）
|
||
|
||
```markdown
|
||
<!-- arcrun-harness:start -->
|
||
## 這個專案用 arcrun 做自動化
|
||
|
||
需要「串服務 / 排程 / 打 API / 資料自動化」時：
|
||
- 用 arcrun 工作流，**不要自己寫 Python/Node 一次性腳本**。工作流是純文字、可複用、跑在你的 Cloudflare。
|
||
- 打外部 API → 寫 recipe（`acr recipe push`），不自刻 HTTP client。
|
||
- 先查能力：`acr parts`（零件）、`acr auth-recipe list`（認證）。
|
||
- **不要自製零件**（WASM）——零件由 arcrun 維護走 PR；你能擴充的是 recipe + 工作流。
|
||
- 開始前讀 arcrun-mindset Skill。
|
||
<!-- arcrun-harness:end -->
|
||
```
|
||
|
||
---
|
||
|
||
## 5.1 `/arcrun` slash command 內容（技術不好用戶的入口）
|
||
|
||
`.claude/commands/arcrun.md`（裝進用戶專案後，用戶打 `/arcrun <需求>` 觸發）：
|
||
|
||
```markdown
|
||
# 用 arcrun 完成這個自動化需求
|
||
|
||
用戶（可能技術不好）想做一個自動化。你的任務：用 arcrun 把它做出來，全程不要讓用戶寫程式。
|
||
|
||
## 鐵則
|
||
- **用 arcrun 工作流 / recipe，絕不自己寫 Python/Node 腳本。** 用戶選 arcrun 就是不想要一次性腳本。
|
||
- 需要打外部 API → 寫 recipe（`acr recipe push`），不自刻 HTTP client。
|
||
- 不自製零件（WASM）—— 零件由 arcrun 維護。你能用的是現有零件 + recipe + 工作流。
|
||
|
||
## 步驟
|
||
1. 先讀 arcrun-mindset Skill（世界觀）。
|
||
2. 跑 `acr parts` 看有哪些零件、`acr auth-recipe list` 看支援的認證。
|
||
3. 把用戶需求拆成工作流（哪些零件、什麼順序、什麼條件），寫成 .yaml。
|
||
4. 需要 credential（API key / token）→ 明確告訴用戶要去哪取得、怎麼 `acr creds push`。
|
||
5. `acr validate` 通過後，`acr push` 部署，告訴用戶 webhook URL / 怎麼 `acr run`。
|
||
6. 完成後給客觀證據（HTTP 2xx / trace），不要只說「做好了」。
|
||
|
||
## 遇到要暴露資料（對外 webhook）
|
||
停下來，明確告訴用戶「這會讓 X 可被外部呼叫」，要他同意。不要替他決定公開。
|
||
|
||
## 用戶的需求
|
||
（用戶打在 /arcrun 後面的文字會接在這裡）
|
||
```
|
||
|
||
> 注意：command 檔不可引用 arcrun repo 的相對路徑（用戶專案沒有）。只提「跑 `acr xxx`」「讀 arcrun-mindset Skill」。
|
||
|
||
---
|
||
|
||
## 6. 動到的檔（review 後）
|
||
|
||
| 檔 | 動作 |
|
||
|---|---|
|
||
| 新增 `llms.txt`（網站根 + repo 根）| **第一接觸點**（§1.0）：給 CC 的啟動指南（叫 CC 跑 install-harness + 裝前鐵則）。網站部署到 arcrun.dev/llms.txt；repo 也放一份 |
|
||
| README 開頭加「給 AI 操盤手」段 | 用戶丟 GitHub 連結時 CC 讀 README → 同樣導向「第一步 install-harness」（§1.0）|
|
||
| 新增 `cli/harness/CLAUDE.block.md` | CLAUDE.md 區塊模板（§5）|
|
||
| 新增 `cli/harness/skills/arcrun-mindset/SKILL.md` | 用戶版 mindset + 資源指引（複用 skills/arcrun-mindset，加「資源去哪取」、去 DECISIONS 引用）|
|
||
| 新增 `cli/harness/commands/arcrun.md` | `/arcrun` slash command（§5.1，技術不好用戶入口）|
|
||
| 新增 `cli/harness/hooks/arcrun-guard.sh` | 用戶版 guard（§4，每條訊息含正路）|
|
||
| 新增 `cli/harness/settings.fragment.json` | hook 註冊片段 |
|
||
| 新增 `cli/src/commands/install-harness.ts` | 指令（§2 冪等，複製上述 harness 素材進用戶專案）|
|
||
| `cli/src/commands/init.ts` | init 末尾呼叫 install-harness |
|
||
| `cli/src/index.ts` | 註冊 `acr install-harness` |
|
||
| `cli/package.json` | `files` 帶 `harness/` 素材（確保 npm 發布帶上）|
|
||
|
||
不動：本 repo 開發版 `.claude`（對象不同，本機保留）。
|
||
命名：Skill 叫 `arcrun-mindset`、command 叫 `/arcrun`（不同名，避免 claude-code-guide 警告的 command/skill 觸發衝突）。
|
||
|
||
---
|
||
|
||
## 7. 驗收（客觀證據）
|
||
|
||
1. 空目錄 `acr install-harness` → 產生 CLAUDE.md + .claude/skills/arcrun + hooks + settings.json。
|
||
2. 已有 CLAUDE.md → append 區塊（標記包夾）不破壞既有；重跑不重複。
|
||
3. 已有 settings.json（用戶自己 hooks）→ arcrun hook 合併，用戶 hook 不丟。
|
||
4. 裝完開 Claude Code → trust → 試「寫 python 自動化」→ 收到提醒指回 arcrun。
|
||
5. `npm pack` tarball 含 harness/ 素材。
|
||
6. **（§0.5 鐵則）每個 guard 的 block/提醒訊息都含可執行的下一步**——故意觸發每條，確認訊息有正路，不是只說「不行」。
|
||
7. 裝完後 `.claude/commands/arcrun.md` 存在 → 用戶打 `/arcrun 每天抓 RSS 存 Sheets` → CC 走 command 流程（讀 Skill、跑 acr parts、產 yaml），不自寫 Python。
|
||
8. 技術不好情境：對 CC 說「幫我把專案設定成用 arcrun」→ CC 跑 `acr install-harness` → 用戶全程沒碰指令。
|
||
|
||
---
|
||
|
||
## 8. 開放問題（review 拍板）
|
||
|
||
1. **python 提醒強度**：§4 傾向「提醒 + 要 CC 自證」而非硬擋（避免誤殺正常 python）。要更硬還是分級？
|
||
2. **CLAUDE.md append vs 獨立檔**：傾向 append + 標記包夾（CLAUDE.md 必載入、可乾淨移除）。動到用戶的檔可接受？
|
||
3. **是否放靜態零件清單**：傾向 CLAUDE.md 只指「跑 acr parts」（動態），不放會過時的靜態清單。
|
||
4. **MCP（P7）self-host 連哪個**：用戶連你的公共 arcrun MCP，還是連他自部署的？（MCP 是 CF Worker，self-host 要不要也部署一份 MCP？）+ MCP 對齊（BACKLOG）何時做完才設 P7 為預設。
|
||
|
||
5. **暴露動作的同意機制：要不要支援「選③ AI 代跑」+「以後不要問我」+ 同意記錄？**（壓測 §9，待 richblack 拍板）
|
||
|
||
> 來源：壓測報告階段 9（`test_arcrun/docs/壓測報告.md` §9.1–9.8）。壓測者立的設計原則：
|
||
> **需同意的動作要依使用者技術能力分級提供路徑，最低能力者也要能用；我們的義務是提醒 + 記錄同意，不是刁難。**
|
||
|
||
壓測者的「一問三路」模型（使用者選哪種走哪條）：
|
||
- 選①（專家）：使用者自己改 settings.json 加允許清單。
|
||
- 選②（中等）：**AI 給可複製貼上的完整指令，使用者貼到終端機跑**（真 TTY → guard 自動放行）。→ **A6 已修字串比對 bug，這條現在做得到（hook 能印出含 push 的指令而不自擋）。**
|
||
- 選③（最低）：**使用者對話中口頭同意 → AI 代跑 → 同意記錄下來（用於法律效益）**，且第一次同意可選「以後同類動作不要再問我」。
|
||
|
||
**🔴 關鍵安全約束（壓測 §9.5/§9.6 實證，不可違反）**：
|
||
- 「人類已同意」的同意訊號**絕不能由 AI 自己產生**（AI 自寫 consent.log / env 旗標 / wrapper script 偷渡都已被安全分類器正確擋下）。否則 guard 形同虛設——AI 想公開時先自寫一筆假同意即可繞過。
|
||
- 結論（壓測 §9.6）：**現行架構下「選③ AI 代跑」沒有正當實現路徑。** guard hook 只認 TTY / env 旗標，這兩者 AI 都無法在「人類同意」語意下合法提供。
|
||
- 正解方向（需**上游/harness** 支援，arcrun 控不了 Claude Code harness）：同意訊號從「人類產生、AI 控制不了、但 AI 能觸發詢問」的管道進入 hook——例如 `AskUserQuestion` 的人類點擊結果 → 由 **harness（非 AI）** 寫一個 hook 能驗證的同意 token（含動作、時效、簽章）→ hook 驗 token 放行。**寫 token 的是 harness 不是 AI** 是整個機制的安全前提。
|
||
|
||
**待拍板的選項**（richblack 決定）：
|
||
- (a) **維持現狀，只支援選①/②**：選③在 arcrun 端做不到（跨 harness），`acr push` 被擋時誠實告知「選③目前不支援，請選①或②」+ 附選②可貼指令。**不在本地削弱 hook 去假裝支援選③**（壓測 §9.6 結論：要靠繞才能做＝設計錯，那就不該繞、該回報）。← 壓測者+本次討論傾向此，A6 已落地選②那條。
|
||
- (b) **arcrun 端預留「hook 驗同意 token」那半**：實作 guard 驗證一個帶簽章/時效/動作範圍的同意 token 的能力，token 由未來 harness（非 AI）寫入；harness 那半未到位前選③仍不能用。
|
||
- (c) **「以後不要問我」+ 法律記錄**：第一次人類同意（透過合法管道，非 AI 自產）時可選記住，之後同類動作免問；同意記錄含時間戳/動作/同意人，作為**法律歸責 + 軌跡可審**（mindset §7：機制價值是法律憑證，不是技術防偽）。此項依賴 (b) 的「harness 寫、hook 驗」管道才安全成立。
|
||
|
||
> 已透過 `arcrun_report_feedback` 回報上游（block_id `6284b2ca-d453-4078-85ca-3f50c3507a13`）。
|
||
> **本次（2026-06-06）只修了 A6（選②的字串比對 bug）；(a)/(b)/(c) 待 richblack 拍板，未動 code。**
|