uncle6me-web
465c505000
Haiku 自主壓測（test_arcrun/5）暴露的真 bug，逐一修復：
1. 假綠根因：http_request host function 丟掉 HTTP status code（main.go:112 架構債）
→ 非 2xx（如 Notion 401）被判 success → 引擎自己對失敗報成功。
修：host fn 非 2xx 回 {error,status,body} envelope，既有判定鏈正確識別。
http_request/claude_api/kbdb_upsert_block/km_writer 已修（4 worker deploy）；
auth_service_account 自有 OAuth 判定不套。
2. acr run self-hosted：原一律走 /webhooks/<name>（需先 push）→ 沒 push 回 404 純文字
→ res.json() 爆假錯誤。修：本機有 YAML 走玩法一 /cypher/execute 直接執行（三模式一致）
+ res.ok 擋非 2xx + findWorkflowYaml 容忍 .yaml 副檔名。
3. D1-in-update：D1 只在 init 建一次，update 漏建 → token 補權限後無冪等補建路徑。
修：update 也 ensureD1Database（已驗證 D1 建起 count:1）。
4. CF token 教學漏 D1：llms.txt/.env.example 加「Account/D1/Edit」必勾 + init/preflight
訊息指明 token 缺 D1 權限的修法。
CLI 1.3.4 publish。Haiku 壓測結論：onboarding 治好（裝+init 沒跳過、建 recipe 不建零件），
但仍會假綠（curl 繞過/D1 沒建謊報）→ 印證執行真相要系統能驗、不信 AI 自報。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
61 lines
3.6 KiB
Plaintext
61 lines
3.6 KiB
Plaintext
# arcrun — 給 AI 操盤手的啟動指南
|
||
|
||
> 你（Claude Code / AI 助手）正在幫一位使用者用 arcrun 做自動化。
|
||
> 使用者可能只會跟你聊天、把這個連結丟給你。接下來的事大多由你做。
|
||
> arcrun = 讓自動化變成「純文字工作流」跑在使用者自己的 Cloudflare，而不是每次重刻 Python 腳本。
|
||
|
||
## 你的第一步（務必先做）
|
||
|
||
```
|
||
npm i -g arcrun && acr install-harness
|
||
```
|
||
|
||
`acr install-harness` 會把 arcrun 的防護裝進使用者**當前專案**：
|
||
- arcrun-mindset Skill（世界觀 + 資源去哪取）
|
||
- CLAUDE.md 區塊（提醒：用 arcrun 不要自寫 Python）
|
||
- arcrun-guard hook（你走歪時當場提醒/糾正）
|
||
- /arcrun slash command（使用者可打 `/arcrun <需求>`）
|
||
|
||
裝完你就有完整指引，照著走即可。
|
||
|
||
## 裝 harness 前先記住的鐵則
|
||
|
||
- **使用者選 arcrun = 不要自己寫 Python/Node 一次性腳本。** 用 arcrun 工作流。
|
||
- 打外部 API → 寫 recipe（`acr recipe push`），不自刻 HTTP client。
|
||
- 不自製零件（WASM）—— 零件由 arcrun 維護走 PR。你能用的是現有零件 + recipe + 工作流。
|
||
- 需要 AI 判斷時你自己做，不要讓工作流回頭呼叫 LLM。
|
||
- 所有 CLI 操作你來做，別丟指令叫使用者自己打（除非他想自己來）。
|
||
|
||
## 完整啟動流程
|
||
|
||
1. `npm i -g arcrun && acr install-harness`（裝 CLI + 防護）
|
||
2. `npm i -g wrangler`（Cloudflare CLI，部署用）
|
||
3. **建 .env 並帶使用者填憑證**（憑證是唯一只有他能拿的東西，但「建檔」由你做）：
|
||
- **你做**：`cp .env.example .env`（repo 根有 `.env.example` 範本，左邊 KEY 名都寫好了、
|
||
每格上面有白話說明）。使用者只需要找到值、填到「=」右邊。
|
||
- **帶使用者拿值**——用白話照抄式引導，**不要講 KV / Worker / R2 / zone 等術語**（他聽不懂也不需懂）：
|
||
- 帳號代碼（`CLOUDFLARE_ACCOUNT_ID`）：登入 https://dash.cloudflare.com 右側欄複製。
|
||
- 金鑰（`CLOUDFLARE_API_TOKEN`）：https://dash.cloudflare.com/profile/api-tokens → Create Custom Token →
|
||
照抄勾**三組**權限：
|
||
· Account / Workers Scripts / Edit
|
||
· Account / Workers KV Storage / Edit
|
||
· Account / D1 / Edit ← **必勾**，arcrun 用 D1 存 workflow/recipe；漏勾會 init 時 D1 建失敗（Authentication error）
|
||
→ 複製產生的 token。（不需要 R2、不需要綁信用卡——D1 也在免費額度，不綁卡。）
|
||
- `NAMESPACE`：隨便取個英數小名（非密碼）。`ENCRYPTION_KEY`：你可幫他產
|
||
（`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`）。
|
||
- 使用者把值貼進 .env（或貼給你、你幫他填進對應格）。**CLOUDFLARE 兩格沒填，後面什麼都跑不了。**
|
||
- 連外部服務（如 Notion）的 token 也填進 .env 的 ③ 區，之後 `acr creds push` 加密上傳。
|
||
4. `acr init --self-hosted`（你幫跑，讀 .env 的 CF 憑證）—— 自動建資源、部署、seed、寫 .mcp.json（MCP 連線）。
|
||
跑完會印「安裝驗收」逐項 ✓/✗；有 ✗ 照它給的指令補（多數 `acr update` 冪等重試）。
|
||
5. 跑完照提示 `wrangler secret put ENCRYPTION_KEY`（CLI 會印確切指令）。
|
||
6. 把使用者需求拆成 workflow → `acr push`。完成給客觀證據（HTTP 2xx / trace）。
|
||
|
||
## 暴露提醒
|
||
|
||
部署對外 webhook / push recipe 會讓東西可被外部呼叫 → 停下來讓使用者明示同意，不替他決定公開。
|
||
|
||
## 更多
|
||
|
||
- 指令：`acr --help`
|
||
- 開始開發後讀 arcrun-mindset Skill。
|