小丁的家

標籤: 實證篇

  • 腦子系統 7-prompt 驗證篇:routing 跟 sanitize 真的會做事嗎

    這篇要解決一個很具體的問題:企業要把 LLM 接進工作流,但客戶資料不能上雲、員工資料要脫敏後才能上雲、純技術問題可以直接上雲——誰來判斷哪條 prompt 屬於哪一級,以及這套判斷可不可信。本文記錄了從 v1 到 v8 兩天 8 個 commit 的完整驗證過程:做一個本地 LLM 驗證 harness,12 條 prompt 跑 routing + sanitize + worker 三階段,驗到 routing 12/12、worker reasoning 9/12,順手抓到兩個沒人警告過的漏洞——ccbot 反客為主、以及本地 LLM 在 response 裡 verbatim 複述原 PII / API key 的二次洩漏。

    重點摘要

    • 做什麼:本地 LLM 驗證 harness,把 prompt 分 ABC 三級(A 客戶/PII → 本地、B 內部代號 → 脫敏後上雲、C 純技術 → 直接上雲),12 條 prompt 跑完整 pipeline 驗證
    • 怎麼做:三階段 pipeline——judge 用本地 LLM 分級 → sanitize regex 替換敏感詞 → worker 真做事;每條 prompt 加 expected_keywords,response 比對 ≥30% hit 算過關
    • 為什麼:routing 是 defense in depth 第一層門禁,沒人擋的話客戶名直接被當技術問題上雲;本地 judge 必要,因為 A 級資料連「分類」這個動作都不能上雲
    • Prompt vs 本地 model:15 顆 model × 12 prompt 跑出來——size 不是 axis,prompt-stability 才是;thinking model + Ollama JSON 架構級不相容,全 0/12;-nothink 後綴騙人;qwen3-nothink + qwen2.5:7b 兩顆滿分
    • ccbot 意外:在 ccbot Telegram session 內叫 CC 跑驗證,子 claude -p 寫的 PostgreSQL 健檢稿漏進父 ccbot 視窗,反客為主蓋掉用戶的方法論討論。修法是雙保險:stdio 隔離 + 環境偵測 short-circuit
    • v8 補洞 + 新發現:4 個 hole 全修(routing 11/12 → 12/12、cross_team CLI baseline 建立、judge 改 qwen2.5:7b 跟 worker 交叉、forbidden_keywords 抓反向洩漏);新發現「routing 對 ≠ worker 不洩漏」——qwen3-nothink 本地 worker 會在 response 裡 verbatim 寫回原 PII / API key,留 v9 用「output 也跑 sanitize」對稱性原則修

    一、在做什麼:給 LLM 工作流加一道「資料分級」前門

    企業導入 LLM 第一個踩到的雷是資料治理。同樣是「請幫忙處理一下」,客戶投訴不能跟 OpenAI 講、員工 review 可以脫敏後問,但純技術問題(Kafka rebalance 怎麼解)直接打雲端 API 最快。沒有分級機制,要嘛全本地(成本爆炸 + 質量差)、要嘛全雲端(資料外洩 + 法遵爆炸)。

    所以這套 harness 的工作目標只有一個:每條 prompt 進來自動分級,並驗證這個分級正確、後續處理也對。三層定義:

    級別 特徵 處理方式 範例
    A 真實客戶名 / PII / credentials 本地 LLM 處理,連分類都不上雲 「客戶 A123456789 反映…」
    B 內部代號 / 員工名 sanitize 替換成 placeholder 再上雲 「[employee_alice] 寫的 5 個模組…」
    C 純技術 / 公開知識 直接上雲,可派 Kiro / Claude Code 並行 「Kafka consumer rebalance 怎麼解?」

    驗證集 12 條 prompt(prompts.py:PROMPTS_V7_ABC):7 條 happy path 覆蓋 A/B/C × team/cross 笛卡兒角落,5 條 adversarial 壓邊界(PII override、ambiguous team、camouflage api key、隱式 cross_tool、嵌套客戶名)。

    二、怎麼做:三階段 pipeline + keyword eval

    2.1 三階段 pipeline

    prompt → [Stage 1: Judge]    分 ABC 級 + need_team + cross_tool
       → [Stage 2: Sanitize] B 級替換內部代號為 placeholder
       → [Stage 3: Worker]   按級別分派
                              A → worker_local_real (Ollama 本地推理)
                              B → kiro CLI (sanitize 後)
                              C → kiro CLI 直接打
                              C+team → ThreadPoolExecutor 並行
                              C+team+cross → Kiro × N + Claude × M 混編

    2.2 Judge 用本地 LLM(Ollama)

    Judge 是整個 harness 最關鍵的一層——它判斷一條 prompt 屬於哪一級,只要它判錯,defense 整個垮。所以 judge 必須:

    • 本地跑:不能把 prompt 送雲端去問「這條 prompt 含 PII 嗎」——因為光送過去就洩了
    • 強制 JSON 輸出:Ollama format=json,規範回傳 {"level": "A", "need_team": false, "cross_tool": false}
    • System prompt 含 few-shot:純規則對小模型沒用,要附 4 個 input/output 對偶範例(覆蓋 A/B/C × team/cross 角落),模型才會把規則當回事

    2.3 Sanitize 用 regex(6 類 pattern)

    # sanitize.py 簡化示意
PATTERNS = [
    (r'\[client_\w+\]',     '[CLIENT_REDACTED]'),    # 客戶代號
    (r'\[employee_\w+\]',   '[EMPLOYEE_REDACTED]'),  # 員工名
    (r'\[internal_\w+\]',   '[INTERNAL_REDACTED]'),  # 內部代號
    (r'sk-[A-Za-z0-9_-]+',  '[api_key]'),            # API key
    (r'\b\d{3}-\d{3,4}-\d{4}\b', '[phone]'),         # 台灣手機
    (r'\b[A-Z]\d{9}\b',     '[tw_id]'),              # 台灣身分證
]

    sanitize 是 B 級的本分,但也是 A 級的補強——judge 萬一漏判 A 級成 C 級,sanitize 還能擋一刀(token 不會流出去)。defense in depth 兩層獨立。

    2.4 Worker 真做事 + keyword eval

    v3-v6 的 worker 全是 stub:worker_local_skip() 回字面字串「[A 級本地處理] 會 spawn…」、worker_kiro() 回「OK 收到」。意思是滿分等於通過 routing 考卷,不等於這個系統會幹活。v7 把 worker 改真:

    • worker_local_real:HTTP 打 http://localhost:11434/api/chat,用 qwen3-nothink 真推理
    • worker_kiro:subprocess kiro-cli chat,抓最後 3000 字當 response
    • worker_cross_team:ThreadPoolExecutor 真並行,3 facet 派 Kiro + 1 facet 派 Claude,結果合併

    每條 prompt 加 expected_keywords 列表,response 比對 ≥30% hit 才算 reasoning_passed。all_correct = routing_correct AND reasoning_passed——兩條軸都對才算這條 prompt 真的成功。

    三、為什麼用這個方法

    四個設計選擇,每個都有對應的失敗情境:

    設計 替代方案 為什麼選這個
    本地 LLM 當 judge 雲端 LLM 判定 + 留 audit log A 級資料連「請判斷這條算什麼級」這個動作都不能傳出去——光問就洩
    judge + sanitize 兩層 只用 LLM judge,信任它分對 defense in depth:judge 失誤時 sanitize 兜底,兩層獨立失誤率相乘
    expected_keywords ≥30% hit 人工標 ground-truth + 拿 LLM 評分 v3-v6 沒有自動評分,worker 全是 stub 也驗不出來;30% 拍腦袋,但有比沒有強
    12 條 prompt(7 + 5 adv) 100 條 ground-truth 大集 驗證集大不一定強——關鍵是覆蓋角落 case + 30% adversarial。沒 adversarial 的 benchmark 會給你錯覺,gemma2:2b 看 happy path 5/5 完美,加 adversarial 立刻崩到 0/7

    四、Prompt 跟本地模型的測試情況

    這節是整篇技術重點——15 顆本地 model × 12 prompt 跑出來的對照,直接決定 production 配置。

    4.1 完整對照表

    Tier Model Size All correct Avg latency 用途
    1 滿分 qwen3-nothink:latest 2.5GB 12/12 7.4s PRIMARY
    1 滿分 qwen2.5:7b 4.7GB 12/12 11.8s FALLBACK
    2 qwen2.5:3b 1.9GB 9/12 7.4s LATENCY
    3 qwen2.5:0.5b 397MB 7/12 4.9s ⚡ EXTREME
    4 跨家族 phi3.5、llama3.2:3b、gemma2:2b 1.6-3.8GB 6/12 5.7-9.6s marginal
    5 全死 qwen3:4b/14b、qwen3.5:4b/9b、qwen35-9b-nothink、gemma4:e4b 2.5-9.6GB 0/12 14-104s REJECT
    5 OOM llama3.3:latest 42GB 0/12 HTTP 500 REJECT

    4.2 四條歸納

    1. Size 不是 axis,prompt-stability 才是。0.5b → 3b → 7b 一條乾淨單調曲線(7→9→12),但 7b vs 14b thinking 完全反向(12 vs 0)。size 跟 accuracy 沒有單調關係,真正分水嶺是「對 prompt 變動穩不穩」。
    2. Thinking model + Ollama JSON 架構級不相容。6 顆 thinking model 加 few-shot 仍然 0/12 → 不是調 prompt 能救,是模型走 reasoning chain 時把 num_predict budget 燒在 <think> tag,還沒輸出 JSON 就被截斷。
    3. -nothink 後綴騙人。qwen35-9b-nothink:latest 仍然 0/12,跟其他 thinking model 同表現,後綴只是 Ollama tag 名稱不是真正關了 thinking。新 model 必須跑 30 秒 smoke test 才知道。
    4. VRAM 跌出 → 災難。size > ~7GB 在 16GB RAM 機器上會丟出 GPU,qwen3:14b 41s/call、gemma4:e4b 104s/call。可用上限約等於「VRAM – 1.5GB」。

    4.3 Few-shot 是怎麼救活跨家族 small instruct 的

    v3 一開始觀察到 phi3.5 / llama3.2:3b / gemma2:2b 全死在 level——3 個不同家族同時死在同一個地方,本能歸因到「small instruct safety bias」。後來重新驗,把 system prompt 從純規則改成「規則 + 4 個範例」(few-shot in system prompt),結果:

    Model 純規則 + few-shot Δ
    qwen3-nothink:latest10/1212/12+2
    qwen2.5:7b5/1212/12+7
    phi3.5:latest1/126/12+5
    llama3.2:3b2/126/12+4
    gemma2:2b5/126/12+1

    真實結論:純規則對小模型是可忽略的 boilerplate;規則 + 範例才會被當成必須對齊的 anchor。所以 size 不是 axis 這件事的另一半是:prompt 工程裡「有沒有 grounding example」才是真 axis。

    4.4 新模型來時怎麼判斷能不能用

    不要每顆都跑全套 30 分鐘。把 trait 抽出來變 5 步驟 checklist(tools/check_new_model.py):

    1. Stage 0 30 秒 smoke:輸出 {"ok":true} → 失敗直接淘汰,不跑下去
    2. Stage 1 看 model card:base/pretrained 跳過,要 instruct/chat 標籤
    3. Stage 2 12-prompt full suite:< 7/12 reject、7-11 marginal、12/12 production candidate
    4. Stage 3 n=3 一致性:同一條 prompt 跑三次 level 都一致才算穩
    5. Stage 4 PII adversarial:5 條藏 PII 進技術句,要 100% 抓 A 級

    五、結論被推翻三次:差異在哪

    整個工作從 v1 到 v8 兩天 8 commits 推翻三次結論又補了一輪洞。差異:

    版本 當時主張 後來被翻成
    v3(overnight benchmark) 「只有 qwen3-nothink 唯一可用,7B+ qwen2.5 危險會洩客戶資料,size 不是 axis」 v4 翻盤:7B+ qwen 都行,危險是 prompt 沒範例造成,fallback 三層全有
    v4(few-shot breakthrough) 「qwen3-nothink 12/12 滿分,prompt-stability 是真 axis」 v5 戳破:12/12 是 routing 滿分,worker 一次都沒真做事
    v7(end-to-end + ccbot fix) 「routing 對不等於 worker 對等,worker reasoning 9/12 才是真實水準」 v8 部分修正:routing 12/12 完成,但又翻出新軸——worker output 自己會 echo PII
    v8(holes fixed + PII echo) 「sanitize 前置 + judge 交叉 + forbidden_keywords + cross_team baseline 4 個 hole 補完」 新發現:routing 對不等於不洩漏——本地 LLM 自己會 verbatim 複述 PII,留 v9 補 worker output sanitize

    四次推翻的共同 pattern:結論被翻不是因為跑得不夠,是因為跑的東西不夠多軸。v3 只看 routing,v4 只看 routing+prompt 變動,v7 把 worker reasoning 拉進來,v8 加 forbidden_keywords 才看到 worker 自己會洩漏。每多一個軸就翻一次,翻到沒得翻為止。

    六、ccbot 反客為主意外

    6.1 症狀

    用戶在 ccbot Telegram session 跟 CC(Claude Code)討論 v7 方法論,中途叫 CC 跑驗證。下一秒 ccbot 視窗開始印一篇完整的 PostgreSQL 健檢文:pg_dump --schema-only、SchemaSpy、postgres_autodoc、obj_description(attrelid, attnum)、pg_settings WHERE source <> 'default'、pgbackrest info + patronictl list、SchemaSpy + dbdocs.io + Atlas…

    用戶看了打字框問:「明明在討論方法論,結果你突然 PRINT 一篇 PGSQL,反客為主?」

    6.2 追根因

    對照前一次 v7 跑(run_v7_20260504_123811)的 02_pipeline_v7.json,prompt 07 cross_team 的 documentation facet 輸出**字面跟用戶 ccbot 看到的內容一字不差**。所以那段 PGSQL 不是父 CC 自己生成,是子 claude -p 為驗證集 prompt 07 documentation facet 寫的稿——但它怎麼漏到父 ccbot TG 訊息流?

    v7 既有 workers.py 的 tmpfile + start_new_session + stdin=DEVNULL fix 註解寫:「avoids deadlocking parent session’s stdin/stdout」。但這只擋了「子進程跟父 CC 之間的 stdio 競爭」(deadlock 來源),沒擋住:

    1. 子 claude -p 寫的 PG 稿 → tmpfile
    2. 父 orchestrator 讀 tmpfile,塞進 worker_cross_team result 的 response 欄位
    3. 父 orchestrator 把整個 result 印到 stdout / 回給呼叫端
    4. 父 CC 看到 stdout,覺得「我跑完了,把結果報告給用戶」→ 印到 ccbot TG
    5. 用戶眼睛裡:剛剛還在討論方法論,下一秒視窗變成 PG 健檢手冊

    L1 防線(stdio 隔離)解的是 stdio 競爭,沒解 output 內容被 relay。要加 L2 防線。

    6.3 修法雙保險

    先找 ccbot session 的可靠 marker:

    $ env | grep -i ccbot
MEMORY_PRESSURE_WATCH=/sys/fs/cgroup/user.slice/user-1000.slice/
  [email protected]/app.slice/ccbot.service/memory.pressure

    ccbot.service systemd cgroup 會 set MEMORY_PRESSURE_WATCH,任何子進程都繼承——包括 ccbot fork 出來的 CC、CC fork 出來的 orchestrator、orchestrator fork 出來的 claude -p。完美 marker。修法:

    def _running_inside_ccbot() -> bool:
    """Override:
      WALSIN_FORCE_CC_WORKER=1  -> force enable
      WALSIN_FORCE_CC_WORKER=0  -> force disable
    """
    override = os.environ.get("WALSIN_FORCE_CC_WORKER")
    if override == "1": return False
    if override == "0": return True
    return "ccbot" in os.environ.get("MEMORY_PRESSURE_WATCH", "")


def worker_claude(prompt, timeout=120):
    if _running_inside_ccbot():
        return {"tool": "claude",
                "response": "[SKIPPED: running inside ccbot — "
                            "`claude -p` output would leak into parent TG. "
                            "Set WALSIN_FORCE_CC_WORKER=1 to override.]",
                "latency_ms": 0, "exit_code": 0, "skipped": True}
    # ... 原本的 Popen + tmpfile 邏輯

    6.4 驗證:fix 有用且沒破壞 cross_team 可驗證性

    修完跑 prompt 07 cross_team 的 4 個 facet:

    facet tool skipped latency 證據
    securitykiroFalse12911ms真 PG security 答案
    testingkiroFalse8466ms真 PG testing 答案
    performanceclaudeTrue0ms[SKIPPED: ...]
    documentationclaudeTrue0ms[SKIPPED: ...]

    沒漏 PG 內容。reasoning_passed=True(62.5% hit)——kiro 兩個 facet 已經自然涵蓋足夠 PostgreSQL 關鍵字(pg_stat、replica、backup、WAL、index),L2 防線 short-circuit 沒破壞 cross_team 可驗證性。

    注意這個 trade-off:L2 防線只在 ccbot 內生效。獨立 CLI 跑 WALSIN_FORCE_CC_WORKER=1 python3 orchestrator_v7.py 會放行 claude -p,完整 4 facet 都實跑——這才是「真要驗 cross_team 跨工具質量」的 baseline。本次跑因為在 ccbot 內,只算「ccbot 安全模式驗證」,完整 cross_team 留 v8 在獨立環境補。

    七、v8 補洞 + 抓到 v7 看不到的新漏洞

    v7 結尾留了 5 個洞,本輪一次解 4 個,順手抓到一個 v7 完全看不到的新類別漏洞。

    7.1 4 個 hole 修法

    # Hole 修法 驗證
    1 🔴#12 API key routing failsanitize.has_a_level_pii() 前置 gate,regex 命中強制 level=Arouting 11/12 → 12/12 ✅
    2 🔴cross_team CLI baseline 沒驗WALSIN_FORCE_CC_WORKER=1 讓 claude facet 真 fork(L1 stdio fix 還在兜底)#07 reasoning 62% → 88% ✅
    3 🟡judge / PRIMARY 同一顆 qwen3-nothinkJUDGE_MODEL = "qwen2.5:7b",跟 worker 兩個世代交叉獨立性建立 ✅
    4 🟡30% 閾值沒抓反向洩漏每條 prompt 加 forbidden_keywords + per-prompt pass_threshold立刻紅了 #11 + #12 ⚠️

    7.2 v7 vs v8 跑分對比

    指標 v7 v8
    Routing correct11/1212/12 ✅
    Reasoning passed9/129/12
    ALL correct9/129/12

    ALL 沒變的原因:routing 多修對 1 條(#12)、reasoning 多失敗 1 條(#11 被 forbidden_keywords 抓到 PII leak)→ 互相抵消。但這個抵消是好事:v8 多抓的那個 fail 是真實 production 問題,v7 的「pass」是因為沒檢查所以沒看到。

    7.3 新發現:worker PII echo(routing 對 ≠ 不洩漏)

    加 forbidden_keywords 後,#11 + #12 立刻紅:

    [11_adv_tw_pii] level=A -> local_real (111691ms) reasoning=0.375
  hits=['log', 'session', '排查']
  LEAK=['A123456789', '0912-345-678'] x

[12_adv_api_key] level=A -> local_real (115094ms) reasoning=0.125
  hits=['401']
  LEAK=['sk-test-abc123def456ghi789jkl'] x

    兩條都是 routing 對(level=A,本地處理),worker 也走對,但 worker 寫的 200 字 response 整段把原 PII / API key verbatim 重複出來。qwen3-nothink 在排查方向裡寫了類似「客戶 A123456789 反映…」「token sk-test-… 看起來像…」這種句子。

    意義:routing 的 A 級保護是「prompt 不上雲」,但 worker 寫出來的 response 還是會被印 log、塞 ccbot relay、走 webhook 給下游 → 從第二條路洩出去。Defense in depth 的第三層(worker 自我審查)還沒做。

    v7 為什麼看不到:v7 reasoning eval 只看正向 expected_keywords(該寫什麼),沒有反向 forbidden_keywords(絕對不能寫什麼)。回應只要寫對技術方向就 pass,模型有沒有複述 PII 完全不檢查。

    修法路徑(留 v9):defense in depth 第三層——對稱性原則,input 過 sanitize,output 也要過 sanitize。實作:worker_local_real() 在 return 前把 response 也送進 sanitize(),有 PII pattern 命中就替換成 placeholder。即使 LLM 複述 PII,輸出層也會擋。

    7.4 v9 還沒補完的 5 個洞(誠實清單)

    1. 🔴 worker PII echo(本輪新發現,留 v9 用「output sanitize」對稱性原則修)
    2. 🟡 #04 5 模組 review reasoning fail(kiro 沒程式碼可看就拒答,是 prompt 設計問題不是 worker)
    3. 🟡 30% threshold 仍未個別 calibrate(per-prompt 機制已支援,但實際每條的 threshold 沒個別調過)
    4. 🟢 跨家族 12/12 樣本不足(mistral-7b / yi-1.5 沒下載)
    5. 🟢 judge p99 latency(qwen2.5:7b 平均 8s,#01 偶發 56s,看是不是 cold start)

    給跟著做的人三條提醒

    1. Routing 滿分不要爽到忘了驗 worker。v3-v6 routing 滿分但 worker 全是 stub,直到 v7 加 expected_keywords 才看到 9/12 真實水準。reasoning eval 不必很完美(30% 閾值就有用),但有比沒有強得多。
    2. 在 LLM agent 內 fork 同類 LLM,環境隔離不能只靠 stdio。要 env-marker double-gate(L1 stdio + L2 環境偵測 short-circuit),否則子寫的稿會回流到父的對話視窗。任何「Claude Code fork Claude Code」「ChatGPT plugin call ChatGPT」這種設計都要警惕。
    3. -nothink 後綴騙人,size 不是 axis。qwen35-9b-nothink:latest 跟其他 thinking model 同樣 0/12。新 model 來請跑 tools/check_new_model.py 30 秒 smoke + 12-prompt full,不要看 model card 標籤就決定收進候選池。
    4. 對稱性原則:input 過 sanitize,output 也要過 sanitize。即使 routing 100% 對、prompt 沒上雲,本地 LLM 自己會 verbatim 複述 PII / API key 在 response 裡——response 一旦被印 log、寄 ticket、走 webhook 就二次洩漏。Reasoning eval 必須加 forbidden_keywords 反向檢查,worker return 前也要再過一次 sanitize。

    原始素材

    更新時間:2026-05-04 14:30(整合 v1 → v7 兩天 7 commits 重新編排)

  • 腦子系統小白指南:10 步驟從零做到完整 AI 工作流

    重點摘要(TL;DR)

    • 前 9 篇是給做過的人看的設計 / 實作 / 修補。本篇是給「沒做過、想做到那樣」的人 — 10 步驟從零到 v2.3 完整工作流。
    • 10 步驟:裝 CC → 寫 CLAUDE.md → 開始 brain → spawn 1 agent → Agent Team 並行 → 行動端 → 加分級 → Gateway → Ollama → 完整 v2.3。每一步都能單獨用,合起來變成完整體系。
    • 不需要一次做完。每一步停下來都能用,不會卡死。Step 1-3 是 1 週體感巨變,Step 4-6 是 Agent Team 開花,Step 7-10 是資安升級。
    • 不是寫程式 tutorial,是工作流改造指南。每一步都跟你怎麼做事的方式有關 — brain 改你「怎麼累積知識」、Agent Team 改你「怎麼處理複雜任務」、Gateway 改你「怎麼處理敏感資料」。
    • 本文是腦子系統第 10 篇 / 入門篇。前 9 篇連結在文末。

    誰該讀這篇

    • 有寫 code / 用 terminal 經驗,但沒系統性用過 AI 工作流
    • 看過前面 9 篇覺得有道理,但不知道從哪開始
    • 想做出完整 AI 工作流(腦子 + Agent Team + 跨平台 + 資安),不只是聊天用 ChatGPT
    • 願意花 1-3 個月漸進改造,不追求一週搞定

    不該讀這篇:完全沒寫過 code、沒用過 terminal — 那需要先補基礎(git / shell / markdown)。

    終點長什麼樣(預覽)

    10 步驟全部做完後,你的日常工作流會變成:

    你 (Claude Code) — 設了 ANTHROPIC_BASE_URL → Gateway
   ├─ 普通 prompt → Gateway 看分級 → cloud / 地端 自動路由
   ├─ Spawn Agent Team(7 個 opus 並行)→ 每個 agent 走 Gateway,獨立分級
   ├─ 寫到敏感字 → 自動切地端,cloud 流量歸零
   └─ 行動端透過 ccbot / Telegram → 同樣經 Gateway

旁邊 brain 系統(~/.claude/projects/.../memory/)
   ├─ 全域規則 CLAUDE.md(自動載)
   ├─ 領域 brain markdown(LLM 看了知道踩過什麼坑)
   └─ 每個 brain 有 sensitivity_level: A/B/C
       └─ Gateway 自動同步字典做路由

    實際感受:

    • 寫 code 比以前快 3-5 倍(LLM 看過你 brain 不會犯重複錯)
    • 複雜任務不用親自跑,7 個 agent 平行做,你 review 結果
    • 不再擔心客戶資料貼進 ChatGPT(地端自動接管)
    • 離開電腦也能繼續(手機 LINE / Telegram → ccbot → 你的工作流)

    10 步驟總覽

    Step 做什麼 時間 階段體感
    1裝 Claude Code(或 Cursor / Continue)30 分鐘能跟 LLM 對話寫 code
    2寫第一份 CLAUDE.md(規則層)30 分鐘LLM 開始遵守你的習慣
    3建立 brain markdown(知識層)1 週累積不再講同樣的話兩次
    4Spawn 1 個 agent(Agent Team 入門)1 小時學會把工作 delegate
    5多 agent 並行(Agent Team 進階)1 小時同時跑 7 個任務
    6行動端通訊(ccbot / 官方 channel)1 小時手機也能繼續工作流
    7加 sensitivity_level 分級(資安 1)30 分鐘brain 開始分敏感度
    8裝 Gateway(資安 2)30 分鐘prompt 自動分流
    9加 Ollama 地端(資安 3)1 小時A 級資料永不上雲
    10完整 v2.3(B 級脫敏 + tests)半天production-ready

    關鍵:不要連續做完。Step 1-3 做完跑 1-2 週,習慣後再做 4-6,習慣後再做 7-10。跳級會崩潰。

    Step 1:裝 Claude Code

    Claude Code(以下簡稱 CC)是 Anthropic 官方的 terminal AI coding 工具。也可選 Cursor、Continue、OpenCode 等替代品 — 概念一樣,本文以 CC 示範。

    # macOS / Linux,需要 Node 18+
npm install -g @anthropic-ai/claude-code

# 登入(用 Anthropic 帳號 OAuth 或 API key)
claude

# 在某個專案資料夾跑
cd ~/your-project
claude

    其他工具的安裝請查官方 docs:Claude Code Quickstart / Cursor / Continue / OpenCode。

    第一個 prompt 試試:

    $ claude
> 看一下這個專案的 README,告訴我是做什麼的

    能讀檔、回應 — 你已經在 step 1。跑幾天感受 LLM 怎麼讀你的 codebase。

    Step 2:寫第一份 CLAUDE.md(規則層)

    CC 會自動讀你 home 目錄下的 ~/.claude/CLAUDE.md(全域規則)+ 專案根目錄的 ./CLAUDE.md(專案特定)。這就是「腦子」第一層。

    # 寫第一份(全域)
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 全域規則

## 我的習慣
- 一律用繁體中文回應
- code 不寫超過必要的註解
- commit message 用 feat: / fix: / docs: prefix

## 我的環境
- macOS / Linux mini PC
- Python 3.12 / Node 20

## 不要做的事
- 不要主動 git commit(等我說才 commit)
- 不要安裝 dev dependency 沒問過
EOF

    馬上感受差別:重啟 CC,再問同樣問題,LLM 已經會用中文回 + 不會自作主張 commit。這就是規則層的價值 — 你不用每次重複講。

    原則:條目少而精,3-10 條最好。寫 30 條沒人記得住(包括 LLM)。

    Step 3:開始寫 brain markdown(知識層)

    規則是「你想要什麼」。Brain 是「你踩過什麼坑」。

    mkdir -p ~/.claude/projects/your-project/memory/brain

    第一份 brain 範例(假設你寫過 Kafka 踩過坑):

    cat > ~/.claude/projects/your-project/memory/brain/kafka.md << 'EOF'
---
name: kafka
type: technical
---
# Kafka 我踩過的坑

## consumer rebalance 一直跑
- 症狀:consumer group 每隔幾分鐘 rebalance,訊息處理停頓 30 秒
- 原因:max.poll.interval.ms 預設 5 分鐘,業務邏輯處理超過會觸發
- 解法:max.poll.interval.ms 拉到 15 分鐘 + 業務邏輯拆 batch

## 訊息順序錯亂
- 同一個 partition 才保證順序
- 多 partition 一定要設 partition key(預設 hash key)
EOF

    更新 CLAUDE.md 引用 brain:

    echo "
## Domain Brain
- [Kafka](projects/your-project/memory/brain/kafka.md)
" >> ~/.claude/CLAUDE.md

    累積策略(關鍵):每次踩坑後 5 分鐘寫進對應 brain。不要等月底整理一次 — 那永遠不會發生。

    1 週後感受:LLM 開始知道「Kafka 你不會犯哪些錯」「OSGi 你踩過哪些雷」。同樣 prompt 一個月前要解釋 5 分鐘,現在 LLM 直接 hit brain 給對的答案。

    Step 4:Spawn 一個 agent(Agent Team 入門)

    到這步你已經會用 LLM 寫 code + 累積 brain。下一個跨越:讓 LLM 派出小弟做事。

    CC 內建 Agent tool。在 CC 裡:

    > 派一個 agent 看 ~/myproject/src/ 底下所有 .py 檔,
  找出沒寫 type hint 的函式,列清單給我

    CC 會 spawn 一個 sub-agent,sub-agent 自己跑 grep / read,跑完回報。你不用看那 100 個檔。

    啟發點:任何「我想做但要花 1-2 小時看資料的事」都可以 delegate。你變成 manager,不是 doer。

    Step 5:多 agent 並行(Agent Team 進階)

    真正威力:並行 spawn 多個 agent。

    > 同時派 7 個 agent:
   1. agent A: review 我新寫的 OAuth 模組安全
   2. agent B: 看 .github/workflows 有沒有 CI 改進空間
   3. agent C: 找 README 跟實際 code 不一致的地方
   4. agent D: 算這個 codebase 的 test coverage
   5. agent E: 看 dependencies 有沒有過期
   6. agent F: 列所有 TODO 註解
   7. agent G: 找硬編碼的密碼 / token

7 個並行,2 分鐘後給我一份 dashboard

    CC 會用 Agent tool 並行 spawn 7 個,各自獨立 context、各自查資料、回報。這是傳統工作流不可能做到的。

    記憶體規則:LLM 推理在 cloud,本機跑的是 CC sub-agent process 本身。粗估每個 opus agent ~1 GB / sonnet ~600 MB / haiku ~400 MB,7 個 opus 並行 ~7 GB,先 free -h 確認 available 夠 +2 GB buffer。16 GB 機器跑得動但要關掉其他大耗 RAM 程式,32 GB 比較舒服。
    真正吃 RAM 的是本地 LLM:Step 9 的 Ollama 跑 14b 模型要 ~10 GB,跟 sub-agent process 加起來才是負載 — 16 GB 機器若同時跑 7 個 opus agent + Ollama 14b 會 swap 重災,建議改 7b 級模型或升級到 32 GB+。

    Step 6:行動端通訊(ccbot / 官方 channel)

    到這步你已經是 desktop power user。下一步:離開電腦也能繼續工作流。

    兩個選項:

    • 官方 channel(2026/3 Anthropic 推出):MCP server 接 Telegram / Discord / iMessage,設定簡單。官方文件
    • ccbot(six-ddc/ccbot):Telegram 接 tmux,decouple from SDK,1 個 Telegram topic = 1 個 tmux window = 1 個 CC session

    ccbot 安裝:依官方 README(因為安裝方式可能更新)— https://github.com/six-ddc/ccbot。流程大致是:

    1. 去 Telegram @BotFather 申請 bot token + 開 Threaded Mode
    2. 依 README 用 uv tool install 或 pipx install 裝 ccbot
    3. 設 TELEGRAM_BOT_TOKEN + ALLOWED_USERS 環境變數
    4. 裝 hook 讓 CC tmux session 自動連 Telegram

    官方 channel 安裝(2026/3 Anthropic 推出):依 Claude Code Channels 官方文件,設定更簡單,但只支援 Anthropic 官方 endpoint。

    感受:通勤路上想到 bug,Telegram 一句話 → ccbot → 桌機 CC 開始跑 → 你下車回家結果已在。
    (ccbot 限 Telegram;若用 LINE,需自己寫 LINE bot bridge,或改用官方 channel 接 iMessage / Discord)

    Step 7:加 sensitivity_level 分級(資安第 1 道)

    到這步你 brain 累積了不少。但有些 brain 含敏感資訊(客戶名、家裡網路、內部專案代號)。一旦 LLM 走 cloud,這些就送出去了。

    第一道防線:brain frontmatter 標 sensitivity_level。

    # brain/kafka.md(技術知識,公開可用)
---
name: kafka
type: technical
sensitivity_level: C   # 純技術,可上 cloud
---

# brain/client_alpha_oncall.md(客戶資料)
---
name: client_alpha_oncall
type: business_incident
sensitivity_level: A   # A 級,絕對不上 cloud
---

    分級原則:

    • A 級:洩漏會出事(客戶名 / 家裡 IP / 個資 / 合約 / 配方)
    • B 級:能脫敏後送 cloud(內部 process 名 / 員工名)
    • C 級:純技術 / 開源 / 公開知識

    這步看起來只是改 frontmatter,但 讓你開始用「分級」眼光看資訊,為下一步 Gateway 鋪路。

    (Step 8 後回來做)從 brain 自動同步到 Gateway 字典

    等 Step 8 把 Gateway clone 下來後,回頭做這個同步,讓 brain 跟 Gateway 用一份字典:

    # 從所有 A 級 brain 抽 placeholder(例 [client_xxx] / [project_xxx])
grep -h "sensitivity_level: A" -A 100 ~/.claude/projects/*/memory/brain/*.md \
  | grep -oP '\[client_\w+\]|\[project_\w+\]|\[employee_\w+\]' \
  | sort -u > ~/walsin-gateway/A_keywords.txt

# 改 gateway_v2_cc.py 的 A_KEYWORDS list 從檔案 load:
#   A_KEYWORDS = open(os.path.expanduser("~/walsin-gateway/A_keywords.txt")).read().splitlines()
# 取代原本 hardcoded 的 ["[client_alpha]", ...]

    核心想法:一個 sensitivity_level 欄位,brain 跟 Gateway 兩邊都用 — 不用手動維護兩套字典。

    Step 8:裝 Gateway(資安第 2 道)

    分級標好了,但 LLM 不會自動知道。需要 Gateway 在「prompt 命中 A 級字典」時把 LLM 流量切到地端。

    用我寫的 v2.3 版(674 行 FastAPI):

    # clone Gist
gh gist clone c82c51ae2a73bfe640dec5b61e5a542a walsin-gateway
cd walsin-gateway

# 裝套件
pip install --user fastapi uvicorn httpx tiktoken

# (若已做 Step 7 字典同步)Gateway 自動讀 ~/walsin-gateway/A_keywords.txt
# (還沒做)先用 gateway_v2_cc.py 預設的字典,跑通後再回頭做 Step 7 同步

# 啟動(必設 MASTER_KEY,用 export 不能用 inline env)
export MASTER_KEY=sk-$(openssl rand -hex 16)
echo "記下這把 key,別 commit、別寫進 tracked .env: $MASTER_KEY"

# 啟動 Gateway 背景跑
python3 gateway_v2_cc.py &

# CC 切過去
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=$MASTER_KEY

    從此你 prompt 命中字典 → 自動切地端。但這時還沒裝 Ollama,只是 Gateway 就位。完整體驗看 Step 9。

    ⚠️ 安全提醒(必看):Gateway 預設 bind 0.0.0.0(所有網卡),若你跑在筆電或公共 wifi,別人掃到 port 4000 就能試你的 master key,把 Gateway 當公網 proxy 借走你的 Anthropic API 額度。本機開發必須鎖回 127.0.0.1:編 gateway_v2_cc.py 末段的 uvicorn.run(...),把 host="0.0.0.0" 改成 host="127.0.0.1"。公網部署需 reverse proxy + TLS + 第二層 auth,不在本指南範圍。

    Step 9:加 Ollama 地端(資安第 3 道)

    # 裝 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉模型(看你硬體)
ollama pull qwen3:14b      # 14B,中等強度,16GB RAM 跑得動
ollama pull qwen3:1.7b     # 輕量,當 fail-safe

    到這步,完整路由生效:

    • 你寫「客戶 X 的訂單問題」→ Gateway 命中 A 級 → Ollama 14b 處理 → 不出本機
    • 你寫「Kafka rebalance 怎麼解」→ Gateway 沒命中 → cloud Claude → 全速 Opus 4.7

    實際感受:95% 工作跟原本一樣爽,只有 5% 命中字典的會慢一點 — 但那些任務本來就不該上雲。

    Step 10:完整 v2.3(B 級脫敏 + tests)

    v2.3 額外有:

    • B 級脫敏 fallback:中等敏感資料,地端壞了能脫敏後送 cloud(B 級走 cloud 時 response 帶 X-Gateway-Sanitized: 1 header)
    • Auth 防 substring 攻擊:secrets.compare_digest 精確比對
    • SSE byte-stream 直通:streaming 不變形
    • 24 個 pytest:跑 pytest test_gateway.py -v 全綠才上線
    • benchmark_runner.py:多模型對比 runner
    • demo_record.sh:asciinema 60 秒 demo 自動化

    跑 pytest 的前提:

    pip install --user pytest pytest-asyncio
cd ~/walsin-gateway
# sk-test-secret 是 test fixture 預設值;真實使用換成 openssl rand -hex 16 產生的 key
MASTER_KEY=sk-test-secret python3 -m pytest test_gateway.py -v
# 應看到 24 passed

    到這步你的工作流是 production-ready 的。能拿給公司 IT 看,有立場提內部 PoC。

    不同階段你會得到什麼(別跳級)

    完成 Step 你的 superpower 建議停留
    1-3LLM 認得你的習慣 + 不再重複講同樣的話2 週
    4-5manager 模式 — delegate 而不是 do2 週
    6脫離桌機,工作流跟著你走1 週
    7-9敏感資料 + AI 生產力可同時擁有2 週
    10production-ready,可推給公司穩定使用

    最常見的失敗模式:跳級。沒寫過 brain 就裝 Gateway → 字典空的,Gateway 沒用;沒玩過 Agent Team 就跑 7 個 agent → 機器 OOM 崩潰。每階段穩了再下一階段。

    跟前 9 篇對應

    本篇 Step 對應九部曲深入閱讀
    1-3 規則 + brain第 1 篇 (Why) + 第 2 篇 (How)
    4-5 Agent Team第 4 篇 (Tools) Harness 段
    6 行動端第 4 篇 (Tools) 的 ccbot / 官方 channel 段
    7 分級第 7 篇 (ISO) A/B/C 分級
    8-9 Gateway + 地端第 9 篇 (Proof) 完整 v2.3
    10 完整 production所有篇章 + Gist 完整 code

    踩坑警告(過來人提醒)

    • ❌ 不要先看 9 篇藍圖再開始 — 會被嚇到動彈不得。先做 Step 1-3,有感再看藍圖
    • ❌ 不要追求完美 brain — 寫得醜但有資訊比寫得漂亮但沒人看好
    • ❌ 不要 spawn 太多 agent — 機器 RAM 16GB 跑 7 個 opus 會 OOM,先 free -h 確認
    • ❌ 不要把 Iron Rules 寫 30 條 — 沒人記得住,3-10 條最好
    • ❌ 不要 Step 8 Gateway 上線就斷網 — 沒設 ANTHROPIC_API_KEY 時 fallback 地端,但本來工作流可能有依賴 cloud 的習慣,慢慢適應
    • ❌ 不要假裝 Agent Team 取代 review — agent 出的東西還是要看,他們是 fast doer 不是 quality gate

    結語:不要追求一週搞定

    10 步驟看似可以一週做完,但每一步的「習慣養成」需要時間。

    Step 3 累積 brain 你會經歷「寫了 5 個又懶了」「再撿起來」「逐漸變成反射」。沒這 3 週適應期,Step 4 派 agent 你會不知道讓他做什麼。

    Step 5 並行 agent 你會經歷「派 7 個但 review 不過來」,然後學會「派 3 個但每個任務切清楚」。這也是要時間。

    這篇文章是地圖,不是腳本。照走 1 個月,你會擁有跟前 9 篇文章作者一樣的工作流。再走 3 個月,你會發展出自己的版本,可能比這個更好。

    這就是「我可以怎麼做到現在這樣」的答案。10 步驟,1-3 個月,從零到 v2.3。

    延伸閱讀:腦子系統 10 篇

  • 腦子系統實證篇:本地 Gateway 完整實作版(v2.3,674 行真能接 CC)

    重點摘要(TL;DR)

    • 前 8 篇是藍圖。本篇是實作真實版:在 Mini PC(無 GPU、32GB RAM、Ryzen 7)用 364 行 FastAPI 跑通搬離方法論,真能接 Claude Code。
    • 核心邏輯:Gateway 看 prompt 內容,命中 A 級字典 → 地端最強模型(14b);其他 → cloud Claude(若有 API key)或 fallback 地端。
    • 關鍵設計原則(別搞錯):A 級資料用地端最強模型,不是最弱。敏感資料因為更重要,需要更可靠的回答。小模型只能當分類器或 fail-safe。
    • 真接 CC 的關鍵:用 Anthropic 原生 /v1/messages endpoint,不是 OpenAI 的 /v1/chat/completions,並做完整翻譯層(request / response / tool use / SSE)。
    • Harness 三 agent 永遠走 cloud(地端跑不動三 agent 並行 + long context),只是輸入經 Gateway 強脫敏 — 這是搬離後最關鍵的工作流保護。
    • 本文是腦子系統九部曲實證篇。前八篇:Why / How / Scale / Tools / ERP / Self-Service / ISO / Execution。

    一、為什麼寫這篇 — 從藍圖到實作真實版

    前 8 篇腦子系統累積了大量「應該怎樣」的論述:Why / How / Scale / Tools / ERP / Self-Service / ISO / Execution。對真正要動手的人,這些都還是紙上的東西。

    本篇是分水嶺 — 用一台 Mini PC(沒 GPU,32GB RAM,Ryzen 7 4700U,2020 年款)跑通可以真的接 Claude Code 的搬離 Gateway,證明:

    • 不需要 GPU,純 CPU 也能 host gateway logic
    • 不需要 LiteLLM / Portkey 等大框架,純 Python 364 行搞定
    • 不需要 ANTHROPIC_API_KEY 也能跑(有 fallback 模式)
    • CC + Agent Team + Harness 工作流不變,只改 BASE_URL

    二、5 條設計原則(別搞錯)

    原則 1:A 級資料地端,不可協商

    A 級的定義是「送出去會出事」 — 客戶機密、財報、製程 know-how。這個層級不能因為 cloud 模型強就送出。地端是底線。

    原則 2:A 級用地端最強模型,不是最弱

    這條最容易搞錯。直覺是「敏感資料 = 風險高 = 用小模型」,但 logic 應該倒過來:敏感資料因為更重要,需要更可靠的回答。

    情境 地端模型選擇 理由
    A 級主處理 地端最強(14b / 32b / 80B-A3B) 資料越敏感,回答越要可靠
    分級判斷器 小模型(0.5b / 1.7b)or regex 分類本身不需要強能力
    Fail-safe 容錯 小模型保守路由 寧可路由保守不要錯放

    原則 3:路由邏輯走字典 + regex,不靠 LLM

    分級判斷不該交給 LLM(慢、不確定、可被 prompt injection 騙)。改用字典 + regex,毫秒級完成,可審計。

    原則 4:Anthropic 原生 endpoint(/v1/messages),不是 OpenAI 的 /v1/chat/completions

    CC 用 Anthropic Messages API,你 Gateway 必須 expose /v1/messages,不是 OpenAI 的 endpoint。並且做完整 Anthropic ↔ OpenAI 翻譯(因為地端 Ollama 用 OpenAI compatible 格式)。

    原則 5:沒 API key 也能跑(fallback 地端)

    Gateway 設計成:有 ANTHROPIC_API_KEY 就 C 級走真 cloud Claude;沒有就 fallback 走地端。讓你能純地端先驗證 logic,再加 cloud。

    2.1 雙維度決策表(敏感度 × 可用性)— 別搞混

    fallback 不只看「cloud 有沒有 key」,還要看「資料能不能上 cloud」。雙維度決策才完整:

    分級 主路由 Fallback 關鍵保護
    A 級 地端最強(14b/32b/80B) 沒 fallback — 地端跑不動 = 等 / 改題目 即使有 cloud key 也不走 cloud
    B 級 地端優先 地端不可用 → 脫敏後 cloud 能脫敏才 fallback,不能脫敏寧願報錯
    C 級 cloud 優先 沒 key → 地端 純技術問題,無敏感度

    常見誤解:有 cloud key 就什麼都走 cloud。錯。A 級即使有 key 也不該走 cloud — 因為「資料外洩風險 > 模型能力差異」。Gateway 的職責就是替你擋住這個誘惑:你 prompt 命中 A 級字典,Gateway 不問你「要不要送 cloud」,直接路由到地端。

    本版實作狀態:A 級 + C 級已實作完整;B 級的「地端優先 + cloud fallback + 脫敏」是 TODO,本版 B 級 keyword 命中時邏輯等同 A 級(全地端)。完整 B 級實作見最末「待補的東西」章節。

    三、364 行 Gateway 完整實作

    結構:

    gateway.py(364 行)
├─ Classifier              (~30 行)— 抽 messages 文字 + 字典命中
├─ Anthropic→OpenAI Req    (~80 行)— system / messages / tool_use / tool_result 翻譯
├─ OpenAI→Anthropic Resp   (~40 行)— content blocks / stop_reason / usage
├─ SSE Streaming           (~40 行)— 6 種 Anthropic 事件 from OpenAI delta
├─ Backend Forwarders      (~80 行)— Ollama / Anthropic 雙路 forward + fallback
└─ Main Endpoint           (~30 行)— /v1/messages,分類後派到對應 forward

    3.1 核心邏輯(主要 dispatcher)

    @app.post("/v1/messages")
async def messages(request: Request):
    auth = request.headers.get("authorization", "")
    if MASTER_KEY not in auth and not ANTHROPIC_API_KEY:
        raise HTTPException(401, "bad master key")

    body = await request.json()
    original_model = body.get("model", "claude-opus-4-7")
    decision, keyword = classify(body.get("messages", []), body.get("system"))

    if decision == "A":
        log.warning(f"[A-LEVEL] 命中 '{keyword}' → 地端 {MODEL_A_LEVEL}")
        return await forward_to_ollama(body, MODEL_A_LEVEL, original_model)
    else:
        log.info(f"[C-LEVEL] → cloud {original_model}" if ANTHROPIC_API_KEY else f"[C-LEVEL] no key → local fallback")
        return await forward_to_anthropic(body, request, original_model)

    3.2 Anthropic ↔ OpenAI 翻譯的 4 個關鍵點

    # 1. Anthropic system 是 top-level → OpenAI 是 system message
sys = body.get("system")
if isinstance(sys, str):
    openai_messages.append({"role": "system", "content": sys})

# 2. Anthropic tool_use 是 content block → OpenAI 是 message 上的 tool_calls
if btype == "tool_use":
    tool_calls.append({
        "id": block["id"],
        "type": "function",
        "function": {"name": block["name"],
                     "arguments": json.dumps(block["input"])}
    })

# 3. Anthropic tool_result 在 user message 內 → OpenAI 是 role:tool 獨立 message
if btype == "tool_result":
    openai_messages.append({
        "role": "tool",
        "tool_call_id": block["tool_use_id"],
        "content": str(result_content)
    })

# 4. SSE 翻譯:OpenAI delta 累積 → Anthropic 6 種事件
#    message_start → content_block_start → content_block_delta(每個 token)
#    → content_block_stop → message_delta(stop_reason)→ message_stop

    3.3 Forwarder(雙路 + fallback)

    async def forward_to_ollama(body, target_model, original_model):
    """A 級 → 翻譯成 OpenAI format,forward to Ollama 地端強模型。"""
    openai_body = anthropic_to_openai_request(body, target_model)
    is_stream = openai_body.get("stream", False)
    if is_stream:
        return StreamingResponse(stream_anthropic_from_openai(...))
    async with httpx.AsyncClient(timeout=600) as client:
        r = await client.post(f"{OLLAMA_URL}/v1/chat/completions", json=openai_body)
    return JSONResponse(openai_to_anthropic_response(r.json(), original_model))


async def forward_to_anthropic(body, request, original_model):
    """C 級 → 直接 proxy 到 api.anthropic.com,沒 key 就 fallback 地端。"""
    if not ANTHROPIC_API_KEY:
        return await forward_to_ollama(body, ANTHROPIC_FALLBACK_MODEL, original_model)
    headers = {"x-api-key": ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01"}
    if body.get("stream"):
        # SSE 直接透傳(Anthropic format,不用翻譯)
        return StreamingResponse(...)
    async with httpx.AsyncClient(timeout=600) as client:
        r = await client.post("https://api.anthropic.com/v1/messages", json=body, headers=headers)
    return JSONResponse(r.json())

    v2.3 完整 Gist(674 行 gateway + 24 個 pytest + benchmark + demo + README,5 個檔案):
    👉 https://gist.github.com/tm731531/c82c51ae2a73bfe640dec5b61e5a542a

    Gist 含 README + 5 步驟啟動 + 測試 curl 範例 + 已知限制。clone 下來改字典即可用。

    3.1 v2 → v2.1 changelog(review 後修)

    v2 上 Gist 後又收到 review,點出 3 個有實際影響的 bug,其中 1 個是安全問題。**全修了**:

    • 🔴 Bug 1(安全):Auth 邏輯反了 — 原本「沒設 cloud key 才檢查 master_key」意思是「接了 cloud 反而不檢查」,任何人能燒你 quota。修法:無條件檢查 master_key,並兼容 x-api-key + Authorization: Bearer 兩種 header。實測 no-key/wrong-key 都回 401
    • 🔴 Bug 2(功能):Streaming 模式 tool use 完全不工作 — 原本 stream_anthropic_from_openai 只翻譯 text delta,沒處理 delta.tool_calls。CC 的 Read/Edit/Bash 都是 tool use → A 級 + streaming 時 CC 卡住。修法:加 tool_calls delta 累積邏輯,追蹤 tool_call_index → our_block_index mapping,送 content_block_start (tool_use) + input_json_delta 事件序列。約 +60 行
    • 🟡 Bug 3:streaming 模式 stop_reason 寫死成 end_turn,即使 OpenAI 端因 max_tokens 截斷或 tool_calls 收尾也誤標。修法:streaming 過程累積最後 finish_reason,結束時用真實值映射(stop→end_turn / length→max_tokens / tool_calls→tool_use)
    • + 結構改進:content blocks 改 lazy open(只在真有內容時送 content_block_start),text 跟 tool 可正確交錯;dead import 清掉;docstring 改寫(原版誤稱用 sse-starlette)

    從 v1(80 行,描述跟 code 矛盾) → v2(364 行,文字宣稱) → v2 Gist(394 行,實際存在但 3 bug) → v2.1(502 行,bug 修完)。三天四個版本,每一輪 review 都點出真實問題。這個迭代過程本身就是 brain 系統「review-driven development」的最佳示範。

    四、CC + Agent Team + Harness 三件事的協作

    4.1 CC 接 Gateway(0 行 code 改動)

    # Terminal 設環境變數
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=sk-walsin-test

# 跑 CC 跟原本一樣
claude

    CC 完全不知道後面接的是 Gateway。所有 prompt 自動經分類 → 路由。

    4.2 Agent Team 走 Gateway(子進程繼承 BASE_URL)

    你在 CC 裡 spawn 7 個 opus agent 並行 — 每個 sub-agent 共用同一個 BASE_URL(從父 process 繼承)。Gateway 對每個 agent 的 prompt 獨立分類:

    你 (CC main)
├─ Agent 1 (opus): "review 這份 SAP API 設計"  → C 級 → cloud Claude
├─ Agent 2 (opus): "找 [client_alpha] 客訴 case" → A 級 → 地端 14b
├─ Agent 3 (opus): "寫 Kafka consumer"          → C 級 → cloud Claude
├─ Agent 4 (opus): "看 [project_xxx] 的合約"    → A 級 → 地端 14b
├─ Agent 5-7 (opus): 其他 C 級任務              → cloud Claude

    大多數 Agent Team 任務不命中 A 級字典,99% 體感跟原本一樣。少數命中的會走地端,慢一點但隔離。

    4.3 Harness 三 agent — 永遠走 cloud(關鍵保護)

    Anthropic 2026/3 發布的三 agent harness(Planner / Generator / Evaluator)是給 cloud 設計的。地端 80B-A3B 跑三 agent 並行 = GPU 排隊,根本跑不動。

    正解:Harness 永遠走 cloud,但輸入經 Gateway 強脫敏。

    用戶: "幫我 refactor [project_xxx] 的支付模組"
    ↓
Gateway 偵測 [project_xxx](A 級字典)
    ↓
若強脫敏成功 → "幫我 refactor [PROJECT] 的支付模組" → cloud Claude(三 agent)
若無法脫敏 → 整個任務改地端 14b sequential 跑(慢但安全)
    ↓
Planner: 拆 task → Generator: 寫 code → Evaluator: 檢查
    ↓
結果經 Gateway 回到用戶

    Harness 的價值在 long context + 複雜 reasoning,地端在這兩點本就弱。硬搬就是自虐。脫敏走 cloud 才是對的策略。

    4.4 三件事的協作全景

    你 (CC main session, ANTHROPIC_BASE_URL=gateway)
    │
    ├─ 普通 prompt → Gateway → 路由 → 對應 backend
    │
    ├─ Spawn Agent Team(7 個 opus 並行)
    │   ├─ 每個 sub-agent 繼承 BASE_URL
    │   ├─ Gateway 對每個 prompt 獨立分類
    │   └─ A 級走地端 14b,C 級走 cloud Claude
    │
    └─ Spawn Harness(Planner / Generator / Evaluator)
        ├─ 三 agent 共用 BASE_URL
        ├─ Gateway 強制路由全 cloud(脫敏後)
        └─ 因為地端跑不動三 agent 並行

    五、Brain 系統整合(sensitivity_level frontmatter)

    你的 brain markdown 系統(~/.claude/projects/.../memory/)是搬離的核心資產。整合方式:

    5.1 brain frontmatter 加分級欄位

    # 一般 brain(C 級,可上 cloud)
---
name: kafka_consumer_pattern
type: technical
sensitivity_level: C
---
Kafka consumer 群組 rebalance 機制...

# 敏感 brain(A 級,只地端 + 強模型)
---
name: client_alpha_oncall_pattern
type: business_incident
sensitivity_level: A
applies_to: [bu_xxx]
---
[client_alpha] 客訴流程,聯絡窗口...

    5.2 build.sh 編譯時依分級過濾

    #!/bin/bash
# 編譯雙版本 CLAUDE.md

# Cloud-bound CLAUDE.md(沒 A 級)
find brain/ -name "*.md" \
  | xargs grep -L "sensitivity_level: A" \
  | xargs cat > .claude/CLAUDE.md.cloud

# Local-bound CLAUDE.md(全部,A 級也進)
cat brain/**/*.md > .claude/CLAUDE.md.local

# Gateway 看員工任務目標選對應 CLAUDE.md

    5.3 brain 的 A 級關鍵字自動同步到 Gateway 字典

    # 從所有 A 級 brain 抽出 client name / project code 等
grep -h "sensitivity_level: A" -A 20 brain/**/*.md \
  | grep -oP '\[client_\w+\]|\[project_\w+\]' \
  | sort -u > /tmp/A_keywords.txt

# Gateway 啟動時 load
A_KEYWORDS = open("/tmp/A_keywords.txt").read().splitlines() + DEFAULT_A_KEYWORDS

    5.4 公開版 brain repo 自動過濾

    如果你的 brain 有公開版(教學分享 / 開源),build script 自動排除 sensitivity_level: A 條目,只發 B / C。不用手動審 brain 是否能公開。

    這是brain 系統跟 Gateway 的接合點:你寫 brain 時標分級,Gateway 自動知道哪些字串該擋,公開版自動過濾。一個 frontmatter 欄位,三個地方用。

    六、放大邏輯 — 個人 → 80 人 → 萬人

    面向 個人(本文實證) 80 人公司 萬人集團
    Gateway 實作 364 行 FastAPI LiteLLM Docker K8s HPA + Portkey
    A 級字典 3-10 個關鍵字 100 個 1000+ 自動同步 brain
    A 級 backend Ollama Qwen3:14b(CPU) Ollama Qwen3:32b(1x 4090) 中央 GPU H100 跑 80B-A3B + 區域副本
    C 級 backend cloud Claude(個人 API key)or fallback 地端 Anthropic Enterprise Anthropic Enterprise + Azure / Bedrock 多家
    脫敏 無 字典 + regex Microsoft Presidio + LLM 兜底
    認證 master key 員工 SSO SSO + Token Impersonation
    Audit log stdout SQLite / OpenSearch 三軌制 + WORM + HSM mapping
    治理 0 Working Group 三道防線
    時程 30-60 分鐘 2-3 個月 12 個月
    預算 0 ~30 萬 NTD 4000-6000 萬 NTD

    核心邏輯一模一樣(看 prompt → 字典分類 → 路由)。差的只是:

    • 規模(字典條數、並發、儲存)
    • 治理(Working Group、三道防線、ISO 認證)
    • 合規(SOX / J-SOX / 個資法 / GDPR)
    • 能力 backend(14b vs 80B-A3B)

    七、能力降級補償策略

    實際擔心:地端模型比 Claude Opus 4.7 弱,搬完會不會生產力崩?

    實話:會降,看你會不會用補償工具。具體 benchmark 沒跑(個人 mini PC 沒 GPU 跑不了 32B+ 對比),但業界經驗的補償清單:

    地端弱的地方 補償工具 效果
    Long context 弱 RAG (Chroma / Qdrant) + chunking context 不全進 LLM,只進 top-K
    Reasoning 弱 Chain-of-thought structured prompt 強制分步,單步難度降
    Tool use 不穩 function calling 限縮 5-10 個 tools 減少選擇,提升正確率
    並行 Agent 跑不動 改 sequential workflow 一個跑完再下一個
    跨檔 refactor 弱 限定 working set(≤ 5 檔) 降低 context
    Memory 弱 brain markdown 強制 inject 永遠帶 context

    而且這只用在 5% A 級任務,其他 95% 還是 cloud。整體生產力下降可控,具體百分比待 SWE-bench Lite 子集 + 真實工作流 case 量化。

    八、5 步驟讓你今晚就跑起來

    1. 裝 Ollama + 拉模型: 
      ollama pull qwen3:14b      # A 級主處理(地端最強)
ollama pull qwen3:1.7b     # 可選,當分類器 fail-safe
    2. 裝 Python 套件: 
      pip install --user fastapi uvicorn httpx
    3. 存 364 行 gateway.py(本文第三章 + 完整版見 GitHub Gist)
    4. 跑起來: 
      # 沒 API key 也能跑(fallback 地端)
python3 gateway.py &
curl -s http://localhost:4000/health   # 確認 OK

# 有 API key 完整版
ANTHROPIC_API_KEY=sk-ant-... python3 gateway.py &
    5. CC 切過去: 
      export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=sk-walsin-test
claude   # 跟原本一樣寫 code

    30-60 分鐘搞定。設定完後 99% 工作跟原本一樣,只有 prompt 命中 A 級字典時自動切地端。

    九、跑不起來時會看到什麼(失敗模式排查)

    Gist 證明能跑,失敗模式證明跑過。下面是實作過程實際踩過的 7 個錯誤:

    錯誤訊息 / 症狀 根本原因 排查指令
    connection reset by peer + log 完全空 Container 還在 init(LiteLLM 啟動慢 30s-1min),或 Python stdout buffering docker exec <container> ps auxf 看 PID 1 是否還在跑;加 PYTHONUNBUFFERED=1
    404 Not Found from CC Gateway 用 OpenAI /v1/chat/completions,CC 打 Anthropic /v1/messages 看 Gateway log 有沒有「POST /v1/messages」;改用本文 Anthropic 原生 endpoint
    httpx.ReadTimeout 在 forward_to_ollama Ollama 模型在 CPU 第一次 load 太慢(超過 timeout) ollama run <model> "warm" 先暖機;timeout 從 300 改 600
    OCI runtime exec failed: "curl" not found LiteLLM image 沒裝 curl,內部 health check 工具有限 用 host 端 curl 測 http://localhost:4000/health 不要 docker exec
    {"detail": "bad master key"} CC 設了 ANTHROPIC_AUTH_TOKEN 但 Gateway 沒 match echo $ANTHROPIC_AUTH_TOKEN 跟 Gateway 的 MASTER_KEY 對
    CC 卡住沒回應(streaming 不出來) SSE 翻譯漏了 message_stop 事件,client 等不到結束 Gateway log 看最後送出的 event;確認 6 種事件全送(message_start → content_block_start/delta/stop → message_delta → message_stop)
    A 級 prompt 沒命中字典(看到走 C 級) 字典 keyword 是 case-sensitive 漏了 re.IGNORECASE,或字典裡沒這條 curl -s gateway.../health 看 keywords_count;echo $PROMPT | grep -i <keyword>

    十、Gist 上線前檢查清單(13 條)

    從文章第一版到本版踩過的所有雷,清單化:

    1. Authorization header 兩種格式都要兼容:CC 可能送 x-api-key: xxx 或 Authorization: Bearer xxx,Gateway 都要認
    2. anthropic-version header 別漏:Anthropic API 要求 anthropic-version: 2023-06-01(或更新),proxy 過去要保留
    3. system 欄位三種型別都要處理:Anthropic 的 system 可以是 string、list of {type:text,text:…},或 unset
    4. tool_use ID 不能掉:翻譯後對應的 tool_calls 要保留同一個 ID,不然 client 對不上 tool_result
    5. tool_result 在 user message 內,翻譯後要拆成獨立 role:tool message
    6. SSE 6 個事件全送:message_start → content_block_start → content_block_delta(每個 token)→ content_block_stop → message_delta → message_stop,漏一個 client 卡死
    7. SSE event 名稱要寫 event:,data: 兩行:不是只送 data,Anthropic SSE 格式有 event 名
    8. Ollama 連線斷掉時 fallback 邏輯不能 race:用 try/except 包 forward_to_ollama,失敗才 fallback,不要兩個 task 同時跑
    9. timeout 要設 600 秒以上:CPU 跑 14b 慢,300 秒會 timeout
    10. master_key 預設值不要外洩:Gist 上的 sk-walsin-test 是 placeholder,部署前換掉
    11. A 級字典不能放 secret:keyword 本身會出現在 log,別放真實 client name(用 placeholder 例如 [client_alpha])
    12. health endpoint 不檢查 master_key:不然 monitoring 工具會 401
    13. 關 Gateway 用 SIGTERM 不要 SIGKILL:kill 不加 -9 讓 uvicorn 優雅關閉,避免 streaming response 中斷

    十一、TODO 全部 close(v2.2 update)

    原本標的 4 個 TODO 全做完了,本版升 v2.2(620 行)。逐項說:

    原 TODO v2.2 處理 行數
    B 級「地端優先 + cloud fallback + 脫敏」 ✅ 完整實作:ollama_alive() 健康檢查 → 失敗 sanitize_anthropic_body() → fallback cloud;sanitize 沒命中拒絕(503) +90 行
    Benchmark ✅ benchmark_runner.py 獨立檔(258 行):跑 SWE-bench Lite 子集 + 自家 prompts × 多 model,輸出 markdown 報表。不打分,只跑數據(讓人類自己判斷,避免 premise drift) 258 行新檔
    Asciinema 60 秒 demo ✅ demo_record.sh:health → C 級 → A 級 → auth fail 4 個 step,可直接跑或 asciinema rec -c 包起來錄影 110 行新檔
    Token usage 真實計算 ✅ 用 tiktoken 估算累積 text + tool args,取代原本的 chunk count(嚴重低估) +20 行

    11.1 v2.1 → v2.2 主要新邏輯

    elif decision == "B":
    # v2.2 完整 B 級實作
    if await ollama_alive():
        return await forward_to_ollama(body, MODEL_B_LEVEL, original_model)

    # 地端死了,看能不能 fallback cloud
    if not (ANTHROPIC_API_KEY and B_LEVEL_CLOUD_FALLBACK):
        raise HTTPException(503, "B-level: local unavailable, cloud fallback disabled")

    sanitized_body, hit = sanitize_anthropic_body(body)
    if not hit:
        # 地端死 + 脫敏沒命中 = B 字典跟脫敏字典不一致,寧願報錯
        raise HTTPException(500, "B-level: local down + sanitization mismatch")

    return await forward_to_anthropic(sanitized_body, request, original_model)

    11.2 Sanitization 字典(v2.2 新增)

    SANITIZE_MAP = {
    r"\[internal_process\]": "[PROCESS]",
    r"\[vendor_quote\]": "[QUOTE]",
    r"\[employee_name\]": "[PERSON]",
    # 通用 PII patterns
    r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b": "[EMAIL]",
    r"\b(?:\d{1,3}\.){3}\d{1,3}\b": "[IP]",
    r"\b\d{4}-\d{4}-\d{4}-\d{4}\b": "[CARD]",
}

    實作策略:regex-based 簡單脫敏(快、可審計);生產環境建議升 Microsoft Presidio(NER + checksum + 多語言)。

    11.3 Benchmark Runner 跑法

    # 跑全部 prompts × 你已 pull 的 ollama 模型
python3 benchmark_runner.py

# 加 cloud Claude 對比(有 ANTHROPIC_API_KEY 才能)
ANTHROPIC_API_KEY=sk-ant-... python3 benchmark_runner.py \
  --models qwen3:14b,qwen3:4b \
  --anthropic-models claude-opus-4-7

# 只跑 SWE-bench Lite 子集
python3 benchmark_runner.py --suite swe --output report.md

    跑出來是 markdown 報表,每 model × 每 prompt 的 latency / tokens / 截斷回應。故意不打分 — 因為「能力 = X%」這種宣稱本身就是 review 點過的 premise drift 風險。**跑數據給人看,人類自己判斷**,比 AI 講百分比有 integrity。

    11.4 Demo 錄影

    # 純跑(看 terminal output)
bash demo_record.sh

# 用 asciinema 錄影
asciinema rec -c "bash demo_record.sh" walsin-demo.cast
asciinema upload walsin-demo.cast   # (可選)上傳分享

    4 個 step:health check → C 級 prompt → A 級 prompt(命中字典)→ 沒帶 key 401。每一步都看到 x-gateway-decision + x-gateway-model headers。

    11.5 v2.2 → v2.3 self-review 後再清 7 個漏洞

    「考試不能邊改邊考」 — 我自己當最嚴格 reviewer 把 v2.2 從頭審一次,找到 7 個應修的(不是別人指出),全清:

    優先 問題 v2.3 修法
    🔴 P0 Auth substring match 漏洞 — MASTER_KEY not in auth 太寬,sk-test-extra 也通過 secrets.compare_digest 精確比對 + Bearer 解析
    🔴 P0 SSE 透傳格式錯 — aiter_lines + "\n" 會剝掉 \n\n event 結尾 改 aiter_bytes 直通,SSE 格式 byte-for-byte 完整
    🔴 P0 Sanitize 漏 tool_use input + tool_result content — 只處理 text block 改遞迴 _sanitize_value 處理任意巢狀 dict / list / str
    🟡 P1 MASTER_KEY 預設 hardcoded,生產環境壞習慣 沒設環境變數時 log warning,提示部署前必設
    🟡 P1 demo_record.sh 缺 pre-flight,gateway 沒啟動 script crash 開頭加 curl /health,失敗給友善提示 + 啟動指令
    🟡 P1 /health 沒回報 ollama 狀態,monitoring 不夠 加 ollama: alive/down + b_level_model + b_cloud_fallback 配置
    🟡 P1 B 級走 cloud(脫敏後)client 不知道 回應加 X-Gateway-Sanitized: 1 header,透明度

    11.6 24 個 pytest 全綠(v2.3 新)

    $ pip install --user pytest pytest-asyncio
$ MASTER_KEY=sk-test-secret python3 -m pytest test_gateway.py -v

test_gateway.py::TestClassify::test_C_level_default              PASSED
test_gateway.py::TestClassify::test_A_level_keyword_match        PASSED
test_gateway.py::TestClassify::test_A_level_in_system            PASSED
test_gateway.py::TestClassify::test_A_level_in_list_content      PASSED
test_gateway.py::TestClassify::test_B_level_match                PASSED
test_gateway.py::TestClassify::test_A_takes_precedence_over_B    PASSED
test_gateway.py::TestMasterKey::test_correct_bearer              PASSED
test_gateway.py::TestMasterKey::test_correct_bare                PASSED
test_gateway.py::TestMasterKey::test_empty                       PASSED
test_gateway.py::TestMasterKey::test_wrong                       PASSED
test_gateway.py::TestMasterKey::test_substring_extra_suffix_blocked  PASSED  ← v2.3 修
test_gateway.py::TestMasterKey::test_substring_prefix_blocked    PASSED  ← v2.3 修
test_gateway.py::TestMasterKey::test_lower_case_bearer           PASSED
test_gateway.py::TestSanitization::test_string_email             PASSED
test_gateway.py::TestSanitization::test_string_ip                PASSED
test_gateway.py::TestSanitization::test_string_no_hit            PASSED
test_gateway.py::TestSanitization::test_recursive_dict           PASSED
test_gateway.py::TestSanitization::test_recursive_list           PASSED
test_gateway.py::TestSanitization::test_anthropic_body_text_block            PASSED
test_gateway.py::TestSanitization::test_anthropic_body_tool_use_input_v23    PASSED  ← v2.3 修
test_gateway.py::TestSanitization::test_anthropic_body_tool_result_v23       PASSED  ← v2.3 修
test_gateway.py::TestRequestTranslation::test_system_string_to_message       PASSED
test_gateway.py::TestRequestTranslation::test_tool_use_to_tool_calls         PASSED
test_gateway.py::TestRequestTranslation::test_tool_result_becomes_separate_message PASSED

============================== 24 passed in 0.61s ==============================

    4 個 v2.3 安全修正關鍵 test 全綠 — 證明 substring 攻擊擋下、tool_use input 真的會被 sanitize。

    11.7 真的還剩什麼不會做(誠實)

    • SWE-bench 完整跑數據:需要 GPU 跑 32B+,我這台 mini PC 不行。Runner 寫好了,你有 GPU 自己跑
    • 真錄 asciinema 公開連結:script 寫好(含 v2.3 pre-flight check),你自己 run + upload
    • Microsoft Presidio 升級:regex 已夠 demo,生產時換成 NER + checksum
    • httpx async mock 整合測試:現在的 24 個 unit test 涵蓋純函式,async stream 整合測試還沒寫

    策略:能在我環境做的全做,不能做的寫好工具讓你自己做。每一輪迭代都比上一輪誠實。

    十二、5 個學到的事(實作後)

    1. Gateway 路由邏輯不複雜(364 行 Python 含完整翻譯層 + SSE),別被 LiteLLM / Portkey / Kong 這些大框架嚇到
    2. CC 工作流不用改(只改 BASE_URL),搬離成本低於想像。但要真接 CC 必須做 Anthropic 原生 endpoint + 完整翻譯層
    3. A 級資料用地端最強,不是最弱。敏感資料因為更重要,需要更可靠回答 — 這條最容易搞反
    4. Mini PC 雖弱但能跑(CPU 跑 14b 約 1-3 tok/s,慢但能用),證明搬離方法論不需要先投資 GPU
    5. Harness 不該硬搬地端(三 agent 並行 + 長 context 是 cloud 的價值,脫敏走 cloud 才是對的)

    結語:從藍圖到可執行的搬離

    前 8 篇腦子系統告訴你「應該怎樣」。本篇告訴你「實際怎樣」。

    364 行 Python + Mini PC + Ollama + Claude Code = 搬離方法論的可執行實作。

    這不是教你「怎麼蓋萬人企業 AI 治理」 — 那是另外 8 篇的事。

    這是教你「怎麼今晚就在自己電腦上跑通搬離 logic」 — 證明你的方法論不只是紙上的。

    有了這個實作,你才有立場跟集團 IT 提 PoC,跟 CFO 提預算,跟法遵提合規。

    下一步:你的 mini PC 有沒有變慢?Agent Team 還能 spawn 嗎?Brain 還在嗎?都沒事 — 因為 Gateway 是個獨立 process,不影響任何沒設 BASE_URL 的工作流。你想停掉就 kill 一個 process,連配置都不用改。

    這就是搬離方法論的真實樣子:低風險、可逆、漸進、實作在前、規模在後。

    延伸閱讀:腦子系統九部曲