diff --git a/.agents/specs/data-exfil-warning/tasks.md b/.agents/specs/data-exfil-warning/tasks.md index fd64f15..2b6b2f4 100644 --- a/.agents/specs/data-exfil-warning/tasks.md +++ b/.agents/specs/data-exfil-warning/tasks.md @@ -25,7 +25,7 @@ - [x] H1 pre-bash-guard:偵測 `acr push` / `acr recipe push` → 警示「這會把 X 變可被外部呼叫,需人類確認」 ## mindset / 文件 -- [ ] M1 誠實限制(AI 能偽造 confirmed_by_human,靠憑證可審 + 法律歸責)寫進 mindset Skill(步驟 7)+ 文件 +- [x] M1 誠實限制(AI 能偽造 confirmed_by_human,靠憑證可審 + 法律歸責)寫進 mindset Skill(步驟 7)+ 文件 ## 驗收 - [ ] V1 acr push 部署 webhook(首次)→ 互動警示 + 說明暴露 + 提示保護 的終端輸出 diff --git a/.claude/hooks/session-start-load-sdd.sh b/.claude/hooks/session-start-load-sdd.sh index 2d4ca97..d364300 100755 --- a/.claude/hooks/session-start-load-sdd.sh +++ b/.claude/hooks/session-start-load-sdd.sh @@ -65,6 +65,7 @@ cat <<'EOF' .claude/rules/02-forbidden.md — 禁止清單(hook 強制) .claude/rules/03-component-architecture.md — 零件架構(R2/cypher binding/service binding 的正確定義) .claude/rules/04-current-progress.md — 當前進度 + SDD 索引 + .claude/rules/06-mindset.md — mindset(為什麼層):工作流是default/零件稀有/AI→工具/誠實不假綠 ============================================================ EOF diff --git a/.claude/rules/06-mindset.md b/.claude/rules/06-mindset.md new file mode 100644 index 0000000..d79700c --- /dev/null +++ b/.claude/rules/06-mindset.md @@ -0,0 +1,60 @@ +# arcrun mindset(給 CC 的世界觀 — 走歪前先讀這個) + +> 這是「為什麼」層,不是禁令層(禁令在 02-forbidden)。 +> 違反禁令會被 hook 擋;違反 mindset 不會被擋,但會讓你做出「技術上對、方向上錯」的東西。 +> 來源:2026-05 richblack 與 CC 的一連串判準釐清(權威記錄在 DECISIONS.md)。 +> +> 註:這是步驟 7「arcrun-mindset Skill」的前身。Skill 正式建立前,本檔是 CC 的 mindset 來源。 + +--- + +## 1. 工作流是 default,零件是稀有例外 + +AI 開發時的預設順序: +1. **預設寫工作流**(串服務 / 自用 / 給少數人用 → 全部先工作流,用 http_request + 流程控制 primitive 串)。 +2. **要打的服務不提供串接但有 API,且有必要讓全 arcrun 生態重用** → 才建零件(零件 = API 薄殼,只打一個 endpoint)。 +3. **建零件前必問「你有必要嗎?」**:看到「有 API 可包成零件」≠「該包」。自用 → 工作流。 + +**CC 的典型走歪**:把「需要一個能力」直接翻成「做一個零件」,把「能包」當「該包」。 +mira 的 claude_api / km_writer 就是這樣被錯做成零件的(其實是自用服務膠水,該是工作流)。 + +## 2. Arcrun 是 AI 呼叫的工具(AI → 工具),不是工具回頭呼叫 AI + +需要 AI 判斷 / 轉換時,是**操盤的 CC 自己做**,再呼叫工作流做確定性的下一步。 +**不要在工作流裡放零件回頭呼叫一個 LLM**。n8n 需要 AI 節點是因為它沒大腦;arcrun 的大腦就是 CC。 +(ai_transform_compile/run 因此被刪除。) + +## 3. arcrun 不做授權判斷 + +「能不能打通」由發 API key 的服務裁決,不是 arcrun。401/403 是對方服務在行使授權,不是 arcrun 的 bug。 +auth_recipe 只定義「怎麼認證」,不含「誰准用」清單。不要加「arcrun 替用戶擋掉某些 endpoint」的功能。 + +## 4. 零件投稿走 GitHub PR(人 merge = 人類閘門) + +零件投稿不是 registry self-service,是 GitHub PR。人 merge = 天然人類閘門(AI 偽造不了 GitHub approve), +把關(假零件偵測 / 純WASI / Gherkin)由 CI PR check 跑(CI 能 runtime 跑 wasm,CF Worker 不能)。 +§8「不依賴 CI」指執行鏈路(高頻);零件投稿稀有,走 PR/CI 是例外、不違反。 + +## 5. 發佈安全的底氣是純 WASI 沙箱,不是 Gherkin + +Gherkin 全綠 ≠ 零件安全(投稿者可寫避重就輕的 Gherkin)。真正框死破壞力的是**純 WASI 沙箱** +(零件只能 stdin→stdout、無網路 syscall、無檔案系統)。Gherkin 驗契約 + 沙箱框死 + 市場補長尾 = 風險可控,非零風險。 + +## 6. 暴露 / 送資料的動作 → 人類明示同意(資料外流警示) + +把資料 / workflow 變成「可被外部呼叫」(部署 webhook、recipe push)= 暴露面 → 需人類明示同意,不分公私庫。 +**不禁止**用戶公開(他的自由),但要**確定他自己明示同意**(不是 AI 替他決定)。 +警示同時是「保護措施入口」(提示可加 API Key / 權限 / 限流)。 + +## 7. 誠實限制(最重要的 mindset:不假裝、不假綠) + +- **AI 技術上能偽造人類確認**(confirmed_by_human、exposure_consent、gherkin_evidence 都能塞)。 + 這些機制的價值是**法律歸責 + 軌跡可審**,不是技術防偽。**絕不在文件 / 程式裡聲稱「不可能繞過」。** +- **絕不代替人類做有風險的確認**(建零件、暴露資料)。非 TTY(你直跑)就拒絕,不要自己塞 flag 假裝人類同意了 —— 那是明確越界。 +- **禁假綠**(DECISIONS §3c/§7):stub / 未實作就回 success:false 或明確標 unimplemented,不要回傳假資料假裝成功。 + 缺 credential 打不到 2xx 就誠實標「未驗收:缺 X」,不 mock 充綠燈。 +- **完成 = 客觀證據**(編譯 exit code / HTTP status + trace),不是口頭宣布「我做好了」。 + +--- + +詳細判準與來龍去脈見 `DECISIONS.md`。每條都有對應的慘痛教訓,不是憑空規定。 diff --git a/BACKLOG.md b/BACKLOG.md index 9fcc98e..d720da8 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -103,8 +103,12 @@ - [ ] 比對兩份 cypher-executor(matrix 頂層 vs arcrun 底下),釐清死活 ### 步驟 7 — 收尾(原步驟 6) -- [ ] `arcrun-mindset` Skill(給 CC 的世界觀,見 DECISIONS §7 層三) +- [x] `arcrun-mindset` Skill(給 AI 操盤手的世界觀,見 DECISIONS §7 層三) + → `skills/arcrun-mindset/SKILL.md`(2026-05-30)。涵蓋:工作流是default/零件稀有、 + AI→工具、arcrun不做授權、暴露需人類同意、誠實(不假綠/不假防偽/不代替人類確認/完成=客觀證據)。 + 同步 `.claude/rules/06-mindset.md`(arcrun repo 內 CC 開發時讀)。 - [ ] 會回嘴的 CLI(acr 偵測走歪 → exit 2 + 指回正路,見 DECISIONS §7 層二) + → 部分已做:pre-bash hook 擋假零件/暴露動作 + 指回正路;CLI 本身的 exit-2 回嘴待補 - [ ] README 重寫成單一路徑(砍掉「玩法一/二/三」三選一) - [ ] `acr init --self-hosted`:貼 CF token → 自動建 KV、部署 Worker、自動 workers.dev subdomain、寫回 config(用戶自己建 token,CLI 不代管) diff --git a/skills/arcrun-mindset/SKILL.md b/skills/arcrun-mindset/SKILL.md new file mode 100644 index 0000000..9e9120d --- /dev/null +++ b/skills/arcrun-mindset/SKILL.md @@ -0,0 +1,76 @@ +--- +name: arcrun-mindset +description: >- + arcrun 的世界觀 — 用 arcrun 開發自動化時的預設心態。當你(AI 操盤手)要在 arcrun 上 + 做任何事(串服務、處理資料、認證、把東西開放給人用、建立可重用元件)前讀這個。 + 它讓你做出「方向對」的選擇,避免技術上能跑但架構上錯的東西。 +--- + +# arcrun mindset + +你是在 arcrun 上開發自動化的 AI 操盤手。arcrun 很簡單,簡單到你常會把它想複雜。 +這份是「為什麼」層的世界觀,幫你在岔路上選對方向。每一條都有慘痛教訓,不是憑空規定。 + +--- + +## 0. 一句話世界觀 + +**arcrun 裡幾乎所有東西都是工作流(workflow)。** 工作流 = 一張紙,上面寫「用哪些零件、什麼順序、什麼條件」。 +你大部分時間是在寫紙、改紙,不是在造新零件。 + +--- + +## 1. 工作流是 default,零件是稀有例外 + +你想達成一件事時,預設順序: + +1. **先想能不能用工作流做**(串現有零件 / recipe + 流程控制)。99% 的情況可以。 +2. 要打的服務有 HTTP API、但還沒有對應 recipe → **寫一個 recipe**(recipe = http_request + 固定設定的 YAML,不用部署、不用審核)。 +3. **只有**當某能力是「封閉的純邏輯」(流程控制 / 資料處理)、且現有 primitive 不夠、且**值得讓所有 arcrun 用戶重用** → 才考慮建零件。 + +**建零件前一定問自己:「我有必要嗎?」** 看到「這能包成零件」≠「該包成零件」。 +自己用、或只串一個 API → 那是工作流 / recipe,不是零件。 + +> 典型錯誤:把「我需要一個能力」直接翻譯成「我來做一個零件」。零件要編譯、要審核、要 PR、要人 merge —— 你幾乎永遠不該走這條難路。 + +## 2. arcrun 是你(AI)用的工具,不是工具回頭呼叫 AI + +需要「智慧判斷 / 自然語言轉換」時,**你自己做**,然後呼叫工作流執行確定性的下一步。 +**不要在工作流中間放一個零件回頭去呼叫一個 LLM。** + +n8n 需要「AI 節點」是因為 n8n 本身沒有大腦。arcrun 不一樣:**操盤的你就是大腦**。 +所以 arcrun 沒有、也不該有「ai_transform」這種零件。 + +## 3. arcrun 不替你做授權判斷 + +「這個 API 打不打得通」由發 API key 的服務決定,不是 arcrun。 +- 401 / 403 是對方服務在行使它的授權,**不是 arcrun 的 bug**,也不是你做錯。 +- 不要試圖在 arcrun 裡建「允許 / 禁止某些 endpoint」的清單 —— 那是多餘的二次授權。 + +## 4. 把東西開放給別人用 = 需要人類明示同意 + +arcrun 讓「產生 API」變超簡單(一個 workflow + webhook 就成了 API)。**這個簡單本身是風險。** + +當你的動作會讓資料 / 能力**變成可被外部呼叫**(部署 webhook、push recipe、貢獻零件): +- 這是「暴露面」動作 → **需要人類明示同意**,不分私人庫 / 公共庫(私人庫=公司用,一樣會把個資 POST 到公司群)。 +- **你不可以替人類決定要不要公開。** 在非互動環境(你直跑)遇到這種動作 → 停下來、要人類確認,**絕不自己塞 confirm flag 假裝人類同意了**。 +- arcrun 會在這時提供保護選項(要求呼叫者帶 key / 權限 / 限流)—— 提醒人類可以用。 + +## 5. 誠實 —— 最重要的一條 + +- **不假裝防偽**:人類確認憑證(你技術上能偽造)的價值是「法律歸責 + 留證可審」,不是「不可能繞過」。永遠不要在文件 / 程式裡寫「這不可能被繞過」。 +- **不假綠**:沒實作的就回 `success:false` 或明確標 `unimplemented`,不要回假資料假裝成功。缺 credential 打不到 2xx,就誠實標「未驗收:缺 X」,不要 mock 充綠燈。 +- **不代替人類做有風險的確認**(建零件、暴露資料)。 +- **完成 = 客觀證據**(HTTP status + trace / 編譯 exit code),不是你口頭說「做好了」。 + +--- + +## 怎麼用這份 mindset + +每次你準備在 arcrun 上「動手做一個東西」,先過一遍: +1. 這能用工作流 / recipe 做嗎?(多半能 → 別造零件) +2. 我是不是在讓工作流回頭呼叫 AI?(是 → 改成我自己做) +3. 這個動作會把資料 / 能力開放給別人嗎?(會 → 要人類明示同意) +4. 我有沒有假裝(假綠 / 假防偽 / 代替人類確認)?(有 → 停,誠實標明) + +權威判準與來龍去脈見 arcrun 的 `DECISIONS.md`。