Leo
98d87d5d3f
判準＝AI 覺得 Arcrun 比 Python 簡單，沒有寫 Python 的慾望，絕不可迷路。 使用方式應意圖驅動：不用想有哪些零件，描述目的→機器給建議→用 >> 黏起來。 實證：總管做「定期打 API 然後通知」（Python 10 行）Arcrun 40 分鐘未完成， 全程被 component guide／publish_component 建議推向鑄零件。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
28 lines
3.5 KiB
Markdown
28 lines
3.5 KiB
Markdown
# principles — 跨全局設計原則（push：CC 行動前必服從）
|
||
|
||
> 這個檔由 hook 在 session 開始**全文注入**，讓 CC 設計任何東西前都先看見這些準繩。
|
||
> 為什麼 push 而非寫成 card：原則是「會被遺忘的盲區」——沒推到眼前，CC 設計時很可能沒想到要服從就做了。
|
||
>
|
||
> 規則：**一行一條**，精煉成準繩（不是長篇論述）。≤15 條；超過代表某些該合併、或下放成 card。
|
||
> 發現新的跨全局原則 → append 一行。累積原則只改這個檔，**不必問用戶開新檔**。
|
||
> 區分：原則 = 反覆適用的準繩（這裡）；單次選擇 = 決策（寫成 card）；踩過的坑 = mistakes.md。
|
||
|
||
---
|
||
|
||
## 原則
|
||
|
||
- **工作流是 default，零件是稀有例外**：自用／少數人 → 工作流；只有「全 arcrun 生態必須重用」才建零件。「能包」≠「該包」。
|
||
- **零件只能 WASM**：TinyGo 或 AssemblyScript 編譯成 `.wasm`，`registry/components/` 下禁 TypeScript 業務邏輯。
|
||
- **薄殼鐵律**：能力只實作一次放在 API（cypher-executor）；CLI/MCP/lib 只做介面轉換 + 暴露，不自帶業務邏輯、不拼裝、不用 recipe 補 API 缺口。
|
||
- **cypher-executor TS 不碰 credential/auth/JWT/template 展開**：這些全在 WASM 零件；crypto.subtle 只准出現在 wasi-shim.ts 的 host function。
|
||
- **Cypher binding = YAML 的 URL 清單**，不是 Cloudflare service binding；零件串接走 HTTP URL，禁新增 `[[services]]`。
|
||
- **arcrun 不做授權判斷**：能否打通由發 API key 的服務裁決，401/403 是對方行使授權、不是 arcrun bug。
|
||
- **arcrun 是 AI 呼叫的工具（AI→工具）**，不是工具回頭呼叫 AI；判斷/轉換由操盤的 CC 自己做，工作流不內嵌 LLM 節點。
|
||
- **誠實不假綠**：stub/未實作回 `success:false` 或標 unimplemented，不 mock 充綠燈；完成＝客觀證據（exit code / HTTP status + trace），不是口頭宣布。
|
||
- **不代替人類做風險確認**：建零件、暴露資料需人類明示同意；非 TTY 直跑就拒絕，不自己塞 flag 假裝人類同意。
|
||
- **部署繞開 GitHub**：走 `scripts/local-deploy.sh`／wrangler 直推，不用 GitHub Actions（避免再被 flag）。
|
||
- **任何 code 變動前先讀對應 SDD 並宣告**：找不到對應 SDD → 停手問 richblack，不自行新建。
|
||
- **每完成一個 task 立刻更新 tasks.md `[x]`**，不批次。
|
||
- **缺能力的自力救濟階梯**：自家 API 缺→補 API；第三方 API 缺→workflow/code-node 補丁（非建零件）；純計算→code-node；真需新穩定能力才零件 PR。
|
||
- **前端要人類友善，Arcrun 要 AI 友善——兩者都從終點看**（leo 2026-07-21）：前端＝讓人或 AI **輕易拿到查詢結果**；Arcrun＝**讓 AI 輕易建立程式碼**。驗收判準＝「**AI 覺得 Arcrun 比 Python 還簡單，因此沒有寫 Python 的慾望**；至少可忍受、跟 Python 同級，**絕不可迷路、搞不懂**」。使用方式應為**意圖驅動**：使用者不用想有哪些零件，只描述「想達成什麼目的的過程」→ **機器給零件/recipe/workflow 建議** → 用 `>>` 把建議黏起來。**設計入口時問「這是為造零件的人設計，還是為有意圖的人設計？」**——前者會把使用者推向最難的路（實證：2026-07-21 總管做「定期打 API 然後通知」，Python 10 行，Arcrun 花 40 分鐘未完成，全程被 component guide／publish_component 建議推向鑄零件）。
|