標籤: monorepo

  • 腦子系統小白指南: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 installpipx 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_startcontent_block_start/delta/stopmessage_deltamessage_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: xxxAuthorization: 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,連配置都不用改。

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

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

  • 80人AI腦子系統實戰建置:從0到上線的16個步驟

    重點摘要(TL;DR)

    • 把 80 人 AI 腦子系統從 0 蓋起來,共 5 個 Phase、16 個 Step、約 16 週。本文逐步拆解每一步的目標、動作、產出、坑。
    • 每一步都用四維框架檢查:安全(不洩漏)、穩定(不掛)、累積(知識變資產)、好用(員工願意用)。任何一步如果四維都不過,就砍掉。
    • 核心心法:物理保證 > 規則約束、拉力 > 推力、先粗版再精修、安全在前但好用不能放最後
    • 順序很重要,不能跳步。例如沒有 Step 6(分級對應表)就做 Step 9(Gateway),Gateway 規則沒依據;沒有 Step 12(Curator)就累積知識,3 個月後變垃圾堆。
    • 本文是《80人公司的AI腦子系統:從個人腦擴展到全公司不洩密的工程設計》的實作續篇。前篇講為什麼,本篇講怎麼做。

    為什麼要從「順序」談起

    很多公司導入 AI 治理失敗,不是技術不行,是順序錯了。常見錯誤:

    • 先買 Gateway 軟體,再去定資料分級 → 規則沒依據,Gateway 變裝飾
    • 先請大家寫 brain markdown,沒有 Curator 制度 → 3 個月後變過期文件墳場
    • 先做華麗 Dashboard,沒有 audit log 來源 → KPI 是亂編的
    • 先全公司鋪開,沒先試點 → 第一週體驗不好,80 人對系統信任歸零,救不回來

    本文每個 Step 都標「為什麼是這個位置」,讓你看完知道哪些可以平行、哪些必須串行。

    四維檢查框架

    每個 Step 都要回答四個問題。如果一個 Step 四維都打不到 ≥1 分,就砍掉 — 是 nice-to-have,不是 must-have。

    維度 問題 具體判斷
    🔒 安全 這步降低洩漏面積嗎? A 級資料更不會出去?稽核能找到證據?
    🛡️ 穩定 這步可用性夠嗎? 壞了能降級?有災難回復?HA?
    📚 累積 這步留下了什麼長期資產? 員工離職還在?可審計?可移交?
    😊 好用 員工這步以後生活更好嗎? 少打字?少切視窗?少等待?少抱怨?

    Phase 0:基礎準備(W0–W2)

    不要先動程式碼。先把組織結構知識容器建好。

    Step 1 — 召集 Working Group(W0,3 天)

    • 目標:讓 5-7 人(準 CISO + 法務 + IT + 3-4 部門 senior + 老闆 sponsor)成為這套系統的第一批決策者
    • 動作:第一次會議 60 分鐘,議程:同步為什麼要做、確認名單、排定 Phase 0 清單會議、訂下兩週一次例會
    • 產出:一份 working group 章程文件、會議紀錄、共享日曆
    • 四維:🔒 ✅(分級權威來源)、🛡️ —、📚 ✅(決策歷史可追)、😊 ✅(員工知道有人扛責)
    • 常見坑:老闆不到場 → 後面拍板沒人敢動;法務一個人說了算 → 後面所有東西判 A 級

    Step 2 — 建立雙 Repo(W1,2 天)

    • 目標:把「公司腦」和「個人腦」變成兩個物理上分離的 git repo
    • 動作:在公司 GitHub Org 建 company-brain(private)、發給每位員工一份 personal-brain template(github classroom 或 cookiecutter)
    • 產出:兩個 repo + README 說明使用方式 + .gitignore 範本
    • 四維:🔒 ✅✅(個人腦永不 push 中央=物理保證)、🛡️ ✅(git 提供版本+回復)、📚 ✅(每筆變更有 PR)、😊 ✅(員工用熟悉的 git workflow)
    • 常見坑:個人腦放公司 GitHub 而不是員工自己的 → 隱私保證失效;沒有 .gitignore 擋掉 .env / 密碼檔 → 第一週就有人 commit 進去

    Step 3 — Iron Rules v0(W1-W2,1 週)

    • 目標:寫下 3-5 條全公司必守的紅線,變成 company-brain/global/CLAUDE.md
    • 動作:Working Group 開 1 次會議,每個人提 5 條,合併成 3-5 條全體共識
    • 範例:「禁止把客戶合約原文送雲端 LLM」「Bug log 進公司腦前必須脫敏」「所有 brain 修改必須走 PR」
    • 產出:CLAUDE.md v0 commit 進 company-brain/global/
    • 四維:🔒 ✅(底線設定)、🛡️ —、📚 ✅(規則進 git)、😊 ✅(規則少而清楚 > 50 條沒人記)
    • 常見坑:寫成 30 條 → 沒人記得住;寫太抽象(「做正確的事」)→ 不能執行

    Phase 1:同步機制(W3–W4)

    讓「腦子」能流到員工每個 AI 工具。不寫 Gateway,先解決 build & sync

    Step 4 — build.sh 中性編譯器(W3,3-5 天)

    • 目標:一個 script 把 markdown 編譯到所有 AI 工具的格式
    • 動作:寫 bash / Python script,輸入 company-brain/ + personal-brain/,輸出:
      • .claude/CLAUDE.md(Claude Code / Desktop)
      • .cursor/rules/*.mdc(Cursor)
      • .github/copilot-instructions.md(Copilot)
      • ~/chatgpt-system-prompt.md(ChatGPT 用 Custom GPT 貼用)
    • 關鍵設計:每個 brain 檔的 frontmatter 加 tools: [claude, cursor, copilot, gpt],編譯時依目標 model 過濾
    • 產出:可執行的 build.sh + 4-5 種工具的編譯範例
    • 四維:🔒 ✅(可依工具過濾敏感腦)、🛡️ ✅(編譯失敗有錯誤訊息)、📚 ✅(中性格式不被工具鎖死)、😊 ✅✅(員工不用學新格式)
    • 常見坑:編譯太久 → 員工不願意每天 build,設成 git pre-push hook 自動跑

    Step 5 — 種子部門試跑(W4,1 週)

    • 目標:挑 10-15 人的部門(通常是 RD)當第一批用戶,真實流量驗證 Phase 0+1
    • 動作:每天收 1 次回饋(短 Slack 頻道)、每週 1 次 30 分鐘 retro 會議、補 brain
    • milestone:第一週結束,company-brain 有 ≥10 筆 brain markdown(由種子用戶產出)
    • 四維:🔒 —、🛡️ ✅(早期發現問題)、📚 ✅(brain 種子)、😊 ✅(早期使用者教其他員工)
    • 常見坑:挑錯部門 → 行政部根本不寫 brain;挑太大部門 → 回饋處理不過來。挑用 AI 最多的小團隊

    Phase 2:分級與脫敏(W5–W8)

    這是整個系統的核心。沒這 Phase,後面 Gateway 全是空殼。

    Step 6 — 分級對應表 v0.1(W5-W6,2 週)

    • 目標:列出 50-100 種公司會接觸的資料類型,粗分 A/B/C
    • 動作:Working Group 兩次會議,每次 90 分鐘,一次處理 30 種
    • 產出:company-brain/global/data-classification.md 表格化,進 git 管理
    • 原則:不糾結邊界 → 先有 v0.1 → Phase 2 試點時精修
    • 四維:🔒 ✅✅✅(整套架構的權威來源)、🛡️ —、📚 ✅✅(可審計、可移交)、😊 —(員工目前還用不到,但是後續所有 UX 的基礎)
    • 常見坑:法務說「不確定就 A 級」→ 後續 Gateway 90% 流量被擋,系統失效。**邊界 case 預設 B 級**(脫敏後可送雲),不是 A 級

    Step 7 — 脫敏字典 v0(W7,5 天)

    • 目標:三份純文字字典,擋掉 80% 紅字
    • 動作:從 CRM / HR / 專案系統匯出
      • client_names.txt(客戶公司名 + 簡稱)
      • employee_names.txt(員工姓名 + 暱稱 + Slack ID)
      • project_codes.txt(內部專案代號、產品代號、合約格式 regex)
    • 產出:三份 .txt + 每月由 HR / PM 維護的責任分配
    • 進階(可選):接 Microsoft Presidio v2.2.362(2025/3 釋出,2026/5 仍是最新版)當第二層補強。Presidio 是開源 PII 脫敏框架,內建 NER + regex + checksum,支援多語言,還有 image redactor 處理 DICOM 醫療影像。字典擋已知字、Presidio 擋通用 PII(信用卡、身分證、地址等),兩層疊加。
    • 四維:🔒 ✅✅(一次擋掉 80% 洩漏)、🛡️ ✅(純文字,壞不掉)、📚 ✅(離職員工從字典移除有歷程)、😊 ✅(員工不用記哪些字是紅字)
    • 常見坑:字典放 git 中 → 字典本身就是敏感資料(客戶 list)。要放另一個 access-controlled repo,build.sh 用 SSH key 拉

    Step 8 — Pre-commit Hook + Browser Extension MVP(W8,1 週)

    • 目標:在員工提交 brain 時、貼資料到網頁版 LLM 時,第一道防線
    • 動作:
      • Pre-commit hook(.git/hooks/pre-commit):掃 staged 檔案,字典命中就 block commit
      • Browser Extension(Chrome/Edge):偵測 chat.openai.com / claude.ai 的 paste 事件,字典命中跳警告 + 自動替換
    • 產出:兩個工具 + 內部 IT 自助安裝頁
    • 四維:🔒 ✅✅(防呆,擋住 80% 「員工懶得開 IDE」場景)、🛡️ ✅(本地執行,不 break 工作流)、📚 —、😊 ✅(警告比阻擋友善)
    • 常見坑:Pre-commit 跑太慢(掃整個 repo) → 員工 git commit --no-verify 繞過。**只掃 staged diff**,< 1 秒

    Phase 3:Gateway 上線(W9–W16)

    這是工程量最大的 Phase。前面都做完才有意義。

    Step 9 — LLM Gateway 骨架(W9-W11,3 週)

    • 目標:用開源 AI Gateway 做基礎,偽裝 Anthropic / OpenAI API。2026 主流選擇:LiteLLM(unified API 到 100+ providers)、Portkey(內建 guardrails + PII redaction + observability)、Kong AI Gateway。企業常見組合是 LiteLLM 當 proxy + Portkey 做 observability
    • 動作:
      • 架 LiteLLM 在內網(Docker),或用 Portkey self-host
      • 第一版只做 proxy + audit log,不做分級
      • 讓種子部門切過來:ANTHROPIC_BASE_URL=https://company-llm.internal/v1
    • 產出:可用 Gateway + audit log 進 SIEM + 每日 throughput 報告
    • 四維:🔒 ✅(流量集中)、🛡️ ✅✅(HA + 健康檢查)、📚 ✅✅(全程 audit)、😊 ✅(員工只改一行設定)
    • 常見坑:沒做 HA,Gateway 掛 = 80 人不能工作。**第一天就要 HA**,或備用 endpoint 自動切換

    Step 10 — 三層漏斗實作(W12-W14,3 週)

    • 目標:在 Gateway 內加分級 + 路由邏輯
    • 動作:
      • Layer 1:Aho-Corasick 演算法搜字典(< 5ms)
      • Layer 2:fine-tune 小模型做分類(BERT、Qwen3 1.7B、Llama 3.2 3B 都可),0.1-0.3s
      • Layer 3:fail-safe 全部判 B 級走脫敏 + 雲端
    • 產出:三層命中率分布 dashboard
    • 四維:🔒 ✅✅✅(自動分級)、🛡️ ✅(每層獨立可降級)、📚 ✅(每筆分類有紀錄)、😊 ✅(員工無感)
    • 常見坑:一開始就追求 Layer 2 LLM 完美 → 永遠上不了線。**先 Layer 1 + Layer 3 兩層上線**,Layer 2 之後加

    Step 11 — 雙引擎接入(W15-W16,2 週)

    • 目標:把雲端 frontier 和本地頂級開源模型都接進 Gateway
    • 動作:
      • 雲端:簽 Anthropic Enterprise(Claude Opus 4.7)、Azure OpenAI(GPT-5.5)、AWS Bedrock(多家)、Google Vertex AI(Gemini 3.1 Pro)。要 DPA + zero data retention 條款。2026 主流是「routing by task type」:Opus 4.7 跑 multi-file coding、GPT-5.5 跑 terminal/browser、Gemini 3.1 Pro 跑 long-context research。
      • 本地:架 Ollama 或 vLLM(production 用 vLLM,2-4x 並發)+ Qwen3-Coder-Next(80B 總參 / 3B active,MoE,256K context)或 Qwen3.6,給 A 級任務專用。MoE 架構讓消費級 GPU 可跑。
      • Gateway 路由規則:A 級 → 本地、B 級 → 脫敏 + 雲端、C 級 → 直接雲端,並依任務型別選最適合的雲端模型。
    • 產出:完整雙引擎可用、第一張月度安全報告(攔了多少 A 級)
    • 四維:🔒 ✅✅✅(A 級永不出去)、🛡️ ✅(雲端掛了本地頂)、📚 ✅(成本/用量數據)、😊 ✅(員工拿到 frontier 能力)
    • 常見坑:用個人帳號的 Claude / GPT → ISO 27001 第三方供應商不過。**必須 Enterprise 合約有 DPA**,費用貴 30-50% 但這是硬門檻

    Phase 4:治理機制(W13+,與 Phase 3 並行)

    沒這個 Phase,brain 會在 6 個月內變垃圾堆。Gateway 蓋好但沒 KPI,3 個月後沒人知道有沒有效。

    Step 12 — Curator 制度(W13,2 週啟動)

    • 目標:每個 team 一個 Curator,有權合併 / 刪除 brain
    • 動作:
      • 挑選:每 team 一個 senior(自願 + 部門主管同意)
      • 授權:GitHub team admin 權限 + 每週 1 小時 review brain PR
      • 儀式:每季全公司「腦子健檢日」,半天清掃過時 brain
    • 產出:Curator list + review SLA(PR 5 個工作天內處理)
    • 四維:🔒 ✅(防止劣化)、🛡️ —、📚 ✅✅✅(知識保鮮)、😊 ✅(垃圾不會堆)
    • 常見坑:Curator 沒被分配時間 → 永遠不 review。**1 小時/週要正式排進 KPI**,不是「有空就做」

    Step 13 — KPI Dashboard(W14-W16,3 週)

    • 目標:把 North Star + 四象限 KPI 變成可看的 dashboard
    • 動作:
      • 串 Gateway audit log → Grafana / Metabase / 自寫
      • 串 firewall log → 偵測網頁版 LLM 流量
      • 串 git activity → 計算 brain 增長率
      • 每月例會看「3 個問題」:North Star、Top 3 繞過原因、安全收益
    • 產出:每月 dashboard + 月報自動產生
    • 四維:🔒 ✅(可量測)、🛡️ ✅(早期警告)、📚 ✅(歷史趨勢)、😊 ✅(高層願意持續投資)
    • 常見坑:做太多指標(20+)→ 沒人看。**只看 5-7 個**,北極星 + 四象限就夠

    Phase 5:長期演進(M5+,持續)

    系統上線後不是結束。三件事要持續做。

    Step 14 — ISO 對應與稽核準備(M5-M6)

    • 目標:把 Step 1-13 的產出對應到 ISO 27001 / 42001 控制措施
    • 動作:
      • 產出 iso-mapping.md:每條 ISO 控制措施 → 對應的 Step + 證據(git log / Gateway log / Dashboard)
      • 第一次內部稽核(找外部顧問跑一遍)
      • 修正稽核發現的 gap
    • 產出:ISO 對應表 + 稽核 readiness 報告
    • 四維:🔒 ✅✅(對外背書)、🛡️ ✅(壓力測試)、📚 ✅✅(合規資產)、😊 —(這 Phase 員工不會直接受益,但對外贏單時受益)
    • 常見坑:把稽核當一次性活動 → 證書到手就鬆懈,3 年後重審手忙腳亂。**Dashboard 要持續跑**,稽核資料 90% 自動產出

    Step 15 — 第二批工具支援(M5+)

    • 目標:涵蓋第一批沒處理的工具
    • 動作:
      • ChatGPT 透過 Custom GPT Action 串 Gateway HTTP API
      • 移動端 Claude / ChatGPT app(只能靠規則 + 教育,管不到)
      • n8n / Dify / 自建 workflow 接 Gateway
    • 四維:🔒 ✅(更多入口受控)、🛡️ —、📚 ✅、😊 ✅(更多員工享受到拉力)

    Step 16 — 過時知識淘汰機制(M6+)

    • 目標:防止 brain 累積成考古學遺址
    • 動作:
      • 每筆 brain 加 last_verified: 2026-05 frontmatter
      • 用量遙測:90 天無 reference 的 brain 自動標 stale: true
      • 每季 Curator 審 stale list,合併 / 刪除 / 更新
    • 四維:🔒 —、🛡️ ✅(防誤用過期知識)、📚 ✅✅(品質才是知識的本質)、😊 ✅(搜尋更準)

    16 Step 全景表

    Phase Step 時程 產出 主導
    0 基礎 1 Working Group W0 章程 + 例會 準 CISO
    0 基礎 2 雙 Repo W1 git repo x2 IT
    0 基礎 3 Iron Rules v0 W2 CLAUDE.md Working Group
    1 同步 4 build.sh W3 編譯器 RD
    1 同步 5 種子部門試跑 W4 ≥10 brain 部門主管
    2 分級 6 分級對應表 v0.1 W5-W6 A/B/C 表 Working Group
    2 分級 7 脫敏字典 v0 W7 三份 .txt HR + PM
    2 分級 8 Pre-commit + Browser Ext W8 兩個工具 RD
    3 Gateway 9 Gateway 骨架 W9-W11 LiteLLM 上線 RD
    3 Gateway 10 三層漏斗 W12-W14 分級+路由 RD
    3 Gateway 11 雙引擎接入 W15-W16 本地+雲端 RD + 法務(合約)
    4 治理 12 Curator 制度 W13+(並行) Curator list + SLA 部門主管
    4 治理 13 KPI Dashboard W14-W16 月報 準 CISO + RD
    5 演進 14 ISO 稽核準備 M5-M6 對應表 準 CISO
    5 演進 15 第二批工具 M5+ ChatGPT etc. RD
    5 演進 16 知識淘汰 M6+ stale 機制 Curator

    關鍵心法:這 16 步背後的設計原則

    1. 安全在前,但好用不能放最後

    Phase 0-2 都在做安全基礎設施,但每個 Step 的「好用」維度都要 ≥1 分。**安全是必要不充分,沒有好用的安全系統會被員工繞過,等於沒做**。Step 4 的 build.sh、Step 8 的 Browser Extension,都是「安全 + 好用」並重的範例。

    2. 物理保證 > 規則約束

    能用 git 結構保證的(Step 2 雙 Repo),不要靠政策文件。能用 Pre-commit hook 自動擋的(Step 8),不要靠員工自律。能用 Gateway 路由強制的(Step 11),不要靠規範。**規則會被忘記,結構不會**。

    3. 拉力 > 推力

    Step 11 雲端 frontier 接入是「拉力」核心 — 員工為什麼選 Gateway 不選網頁版?因為 Gateway 給他 frontier model + 公司腦自動注入 + 速度更快,**而且不用自己付費**。讓 Gateway 比網頁版好用,員工自然不繞過。

    4. 先粗版上線,真實流量精修

    Step 6 分級表 v0.1、Step 7 字典 v0、Step 9 Gateway 骨架都明確標 v0 / 骨架。**等想清楚才上線 = 永遠不上線**。Phase 2 試點 4-6 週收斂的速度,比關門想 6 個月快 10 倍。

    5. 治理機制與技術建設並行

    很多公司先蓋 Gateway 再想 Curator,結果 Gateway 上線 6 個月後 brain 變垃圾堆。Step 12 Curator 在 W13 啟動,**和 Step 13 KPI Dashboard 並行**,因為 brain 累積速度從 Phase 1 試點就開始,治理不能等。

    常見問題

    16 週太長,3 個月能上線嗎?

    可以,但要砍 Phase 3+4。「3 個月版」=Step 1-8 + 簡化版 Gateway(只做 proxy + audit log,不做分級),Phase 4 治理機制延後。**重點是先把基礎(雙 Repo + 分級表 + 脫敏字典 + 種子部門)立起來**,Gateway 可以 v0.5 上線、v1.0 慢慢迭代。

    16 步可以跳哪幾步?

    可跳:Step 8(Browser Ext)、Step 15(第二批工具)。 不可跳:Step 1(Working Group)、Step 6(分級表)、Step 12(Curator)— 跳了系統會壞。 可緩:Step 14(ISO 稽核)— 等系統穩定再啟動。

    一個人(全職)能撐多少?

    • Phase 0-2(8 週):一個人可獨立完成,主要是文件 + 字典 + 簡單 script
    • Phase 3 Gateway(8 週):**要 1.5-2 個 RD**,因為要做 HA + 規則層 + 雲/本地對接
    • Phase 4-5(持續):0.5 個 RD + 0.3 個 CISO 角色就能維護
    • **最低配置:1 個全職 RD + 1 個準 CISO 兼職,跑 4 個月**

    沒有 ISO 認證需求,還要做這套嗎?

    要,只是 Step 14 可以跳。這套架構即使不認證 ISO,**對「accumulating domain knowledge」「員工生產力」「資安基線」三件事**都有獨立價值。ISO 是副產品,不是目的。

    結語:安全 / 穩定 / 累積 / 好用,缺一不可

    大部分企業 AI 治理失敗,不是某一維崩了,是四維沒有平衡:

    • 只要安全 → 員工地下繞過 → 安全也沒了
    • 只要穩定 → 沒有治理 → 半年後變垃圾堆
    • 只要累積 → 沒有 Gateway → 客戶資料外流
    • 只要好用 → 沒有分級 → 一夕事故

    這 16 步的順序,就是「四維平衡的最小可行路徑」。每一步都至少打中兩維,串起來就是一個能跑、能審、能成長、員工願意用的系統。

    第 0 週要做的事只有一件:打開行事曆,把 Step 1 的 Working Group 第一次會議排進去。其他 15 步都會跟著動起來。

    延伸閱讀:《80人公司的AI腦子系統:從個人腦擴展到全公司不洩密的工程設計》 — 講為什麼這樣設計、雙引擎本地+雲、能管 vs 不能管的邊界、拉力哲學。本文是它的實作續篇。

    2026/5 技術棧時間戳

    本文 Step 9-11 涉及的具體工具版本以撰文時間為準:

    • Gateway:LiteLLM(open source)、Portkey(內建 guardrails + PII redaction + 1600+ LLM)、Kong AI Gateway。企業常見組合 LiteLLM + Portkey 雙搭。
    • 本地 LLM:Qwen3-Coder-Next(80B-A3B MoE,256K context)、Qwen3.6、Kimi K2.6、DeepSeek V4、Llama 3.3 70B。Ollama 為日常 default,production 並發推 vLLM V1。
    • 雲端 frontier:Claude Opus 4.7(2026/4)、GPT-5.5(2026/4)、Gemini 3.1 Pro、DeepSeek V4。各家擅長領域不同,「routing by task type」是 2026 主流架構。
    • PII 脫敏:Microsoft Presidio v2.2.362(2025/3 釋出,2026/5 仍是最新版),含 image redactor + DICOM 支援。
    • 合規認證:ISO/IEC 42001:2023(目前唯一可認證的 AI 管理系統標準)。Schellman、TÜV SÜD、BSI、DNV 都是合格認證機構。
  • 80人公司的AI腦子系統:從個人腦擴展到全公司不洩密的工程設計

    重點摘要(TL;DR)

    • 把個人「腦子系統」(CLAUDE.md + brain markdown + skills)擴展到 80 人公司,核心不是技術,是畫清楚「能管」和「不能管」的邊界
    • 架構=雙 Repo(公司腦+個人腦)+ LLM Gateway 中間人 + 雙引擎(本地 model + 雲端 frontier)。員工感受不到分級存在,系統默默路由。
    • 分級判斷用三層漏斗:regex 5ms 攔 90%、小型分類器 300ms 攔 9%、保守 fail-safe 1%。不要員工自選,他們不可能每次選。
    • 「拉力 > 推力」:讓 Gateway 比網頁版 ChatGPT 好用,員工自然不繞過。唯一最重要的 KPI 是「Gateway request 數 ÷ (Gateway + 偵測到的網頁版流量)」
    • 真正的雙贏:傳統 IT 做永遠改不完的 UI,客戶都嫌不好用。AI 時代轉做「給 AI 安全取資料的入口」,客戶用自己愛的 AI 工具,RD 回去做 ISO、審核、累積 domain knowledge。

    緣起:為什麼個人腦子系統撐不住 80 個人

    過去一年,我在自己的多台電腦之間累積了一套「腦子系統」。它由四件東西組成:全域規則(CLAUDE.md)、領域知識庫(brain markdown,例如 OSGi 踩坑、Kafka 注意事項、Shopee API 陷阱)、可重用的能力包(skills)、自動記憶(MEMORY.md + 各種 user/project/feedback 檔)。同步靠 git repo,個人用 100 分。

    但當需求變成「給一間 80 人公司用,讓所有人都能累積知識、快速成長、自行用 AI 開發小工具,並且不限定 Claude Code,可能員工 A 用 Claude、B 用 Cursor、C 用 ChatGPT」,個人架構幾乎所有環節都會崩。本文把整套放大設計鉅細靡遺寫下來,讓 RD 或 IT 主管可以直接拿去當藍圖。

    你以為的「腦子」其實是四層

    先把概念釐清。很多人講「AI 腦子」其實是把四件不同的東西黏在一起,擴展時要分開看待:

    內容 載體 擴展邏輯
    規則層 Iron Rules、語言、Git 流程、安全紅線 CLAUDE.md / .cursorrules 全公司一致,變動少,PR review 嚴管
    知識層 領域踩坑、API 陷阱、業務眉角 brain/*.md 分部門、分主題、有 curator 治理
    能力層 可重用 skill、自動化腳本、模板 skills/, plugins 員工貢獻 + PR + 用量遙測
    記憶層 個人偏好、進行中工作、context MEMORY.md / 個人 .md 永遠留個人,不上中央

    這四層的擴展方式不一樣。規則層是法律,知識層是百科,能力層是函式庫,記憶層是日記。設計時要分開,不能當一坨處理。

    擴展前必須先回答的三個問題

    不要直接跳進畫架構圖。先把這三題定義清楚,不同答案會走到完全不同的系統。

    Q1:「同時使用」是什麼意思?

    • (a) 員工各挑工具,讀同一份共用知識 ✅ 正確答案,可實作
    • (b) 同一任務同時派 Claude + GPT 工作 ❌ 反模式,幾乎沒實用場景

    Q2:員工貢獻知識的開放程度?

    實務建議:opt-out(預設進公司腦,標記私人才留個人),特別是 bug 經驗 — 踩過的坑是最有價值的共享資產。但 opt-out 強制要配「自動脫敏管道」,不然 raw bug log 一進公司腦就帶四種污染:客戶名、訂單 ID、同事名、合約號。

    Q3:資料敏感度怎麼分?

    分級 例子 處理方式
    A 紅 客戶合約、財務數字、員工個資、未公開合作案 嚴禁所有雲端 AI,只能本地 LLM
    B 黃 bug log、客戶踩坑、商務邏輯、process 設計 脫敏後可送雲端
    C 綠 純技術問題、開源元件、公開文件 直接送雲端 frontier model

    務實話:不要追求 100% 不洩漏,要追求「降低洩漏面積」。100% 在 80 人團隊中不存在,追下去會做出沒人用的合規劇場。

    架構藍圖:雙 Repo + LLM Gateway + 雙引擎

    ┌─ 公司腦 repo (private GitHub Org) ─────────────────┐
    │  global/    Iron Rules(PR + 2 reviewer 才能改)      │
    │  teams/                                              │
    │    backend/  brain/* skills/*                        │
    │    frontend/ ...                                     │
    │  shared/skills/  跨部門通用 skills                   │
    │  build/    編譯器:MD → 各工具格式                    │
    │  redact/   自動脫敏規則 + 字典                       │
    └──────────────────────────────────────────────────────┘
                  │ git pull (每天自動)
                  ↓
    ┌─ 員工本機 ─────────────────────────────────────────┐
    │  公司腦/  ← clone 自上面                            │
    │  個人腦/  ← 自己的另一個 repo,永遠不 push 中央       │
    │  build.sh 把兩者編譯到所有工具:                      │
    │   → .claude/CLAUDE.md  (Claude Code/Desktop)        │
    │   → .cursor/rules/     (Cursor)                     │
    │   → .github/copilot-instructions.md (Copilot)       │
    │   → ~/chatgpt-prompt.md (給 Custom GPT 貼用)        │
    └──────────────────────────────────────────────────────┘
                  │ HTTP / MCP
                  ↓
    ┌─ 公司內網 LLM Gateway ─────────────────────────────┐
    │  攔截 → 分級 → 脫敏 → 路由 → 串流回應                │
    │  本地 Ollama (A 級任務專用)                         │
    │  雲端 frontier (B/C 級脫敏後)                       │
    │  審計 log → SIEM                                    │
    └──────────────────────────────────────────────────────┘

    為什麼是「公司腦 + 個人腦」兩個 repo

    • 員工本機把兩個 repo clone 在一起,build.sh 編譯時個人腦覆寫公司腦(個人偏好優先)
    • 個人腦本機 commit,永遠不 push 到中央 — 這就是「自己選擇要不要上」的物理保證
    • 要分享某筆個人筆記時,員工自己 git mv 進公司腦發 PR
    • 「不上傳」變成預設物理行為,不是靠規則約束

    關鍵概念釐清:Brain ≠ Model

    很多人問「為什麼一定要雲?所有人都用本地 model 配腦子就好了啊?」這個直覺方向是對的,但前提是要把兩件事拆開:

    概念 是什麼 耗 GPU? 在哪
    Brain(腦子) Markdown 文件、規則、踩坑紀錄 ❌ 完全不耗 都本地(git repo)
    Model(推理引擎) LLM(Claude / Qwen / Llama) ✅ 很耗 看你選

    腦子永遠該全本地,這沒有爭議 — 它就是 markdown 檔。爭議只在 model 要不要本地。所以真正的問題是「為什麼推理引擎要用雲」。

    為什麼不能「全本地 model」— 三個誠實的事實

    1. 能力差距是真實的

    2026/5 現況:本地頂級開源這一年大幅追上 — Qwen3-Coder-Next(80B 總參 / 3B active,MoE 架構,256K native context)已能跟 Claude Code、Cline、OpenCode 等 coding agent 直接整合;Qwen3.6、Kimi K2.6、DeepSeek V4是 2026/4 的 open-weight 第一梯隊。MoE 架構讓 80B 總參只啟動 3B per token,消費級硬體加量化可跑。但跟 frontier 雲端(Claude Opus 4.7(2026/4)、GPT-5.5(2026/4)、Gemini 3.1 Pro、DeepSeek V4)比,在 long-context agentic、跨檔案 reasoning、tool orchestration 上還是差一個檔次。差距比一年前縮小很多,但沒抹平。

    2. 80 人「全本地」的硬體成本

    • 中央 inference server(8x A100 80GB):採購百萬人民幣級別 + 機房 + 維運,80 人並發要排隊
    • 每人一台 Mac Studio M3 Ultra 192GB:採購 44 萬美金,出差不能用
    • 對比 80 人用 Claude/GPT API:每人每月 $50-200 美金,年成本 5-20 萬美金
    • 雲端在中小公司階段便宜一個量級

    3. 強制全本地會把員工逼地下

    能力不夠 → 員工抱怨 → 私下偷貼資料到 ChatGPT。把人逼到地下,比讓他在地上用更糟。雲端 ≠ 資料變成 OpenAI 訓練資料,Enterprise 合約(Azure OpenAI / AWS Bedrock / Anthropic Enterprise)是另一回事。

    真正的答案:Local-first, Cloud-when-needed(雙引擎)

    員工的 prompt
        ↓
    ┌─ 本地閘門 (Qwen3-Coder-Next / Qwen3.6) ─────┐
    │  1. 偵測敏感度(A/B/C 級)                     │
    │  2. A 級:本地 model 直接處理,不出去           │
    │  3. B 級:自動脫敏後送雲端                     │
    │  4. C 級:直接送雲端                           │
    └──────────────────────────────────────────────┘
        ↓ (B / C 級才會到這)
    ┌─ 雲端 frontier model ────────────────────────┐
    │  Claude Opus 4.7 / GPT-5.5                  │
    │  Gemini 3.1 Pro / DeepSeek V4               │
    │  各家擅長領域不同,Gateway 依任務型別路由       │
    └──────────────────────────────────────────────┘

    這才是「資料安全」和「員工生產力」雙贏的解。全雲洩漏 A 級、全本地犧牲 B/C 級體驗,雙引擎才永續

    LLM Gateway:員工感受不到的中間人

    員工不可能每次手動選分級,要他們按 🟢🟡🔴 三天就沒人用了。正確做法是系統默默判,員工不感知。員工的 IDE / Claude Code / Cursor 不直接連雲端 API,改連公司內網的 Gateway:

    員工的設定只有一行:
    ANTHROPIC_BASE_URL=https://company-llm.internal/v1
    
    之後做什麼都不變。Cursor 還是 Cursor,Claude Code 還是 Claude Code。

    Gateway 的三個職責:

    職責 在做什麼 用什麼
    分級 判 A / B / C Regex + 本地小型 LLM 分類器
    脫敏 B 級資料抽掉客戶名/同事名/合約號 字典 + regex + 本地 LLM 補刀(Microsoft Presidio 可借力)
    路由 送本地還是送雲端 規則引擎

    三層漏斗:5ms 路由掉 90% 流量

    不是「每個 prompt 都過 LLM 判」,那會塞爆。是三層漏斗:

    1. Layer 1:Regex / 字典比對(< 5ms,攔 90%)
      • 含「大有建設」/「老王」/合約號格式 → 紅,本地
      • 純英文技術詞、無中文人名地名 → 綠,雲端
      • 命中就路由,不過 LLM
    2. Layer 2:小型分類器(0.1-0.3 秒,攔 9%)
      • 用 fine-tune 過的 BERT 或 1B-7B LLM 做專門分類
      • 不是 70B 判分級,是 1B 做分類
      • 100ms 級延遲,員工幾乎感受不到
    3. Layer 3:保守路由(fail-safe,1%)
      • 真模糊的 case,全部判 B 級 → 走脫敏 + 雲端
      • 寧可多脫敏,不要誤送:錯就錯在不便利,不要錯在洩漏

    實際員工體驗:問「這個 process 跑 NPE,客戶大有建設訂單 SO20260415 卡住」→ Gateway 5ms 偵測到「大有建設」「SO\d+」→ 自動改寫成「客戶 [CUSTOMER_A] 訂單 [ORDER_ID]」→ 路由到雲端 Claude → 員工完全不知道發生了什麼,只覺得 AI 答得很好。

    能管的世界 vs 不能管的世界

    追求 100% 覆蓋會害死系統。要清楚畫出邊界,每塊用對應措施:

    範疇 可管性 措施
    Claude Code / Cursor / Continue / Aider ✅ 可改 BASE_URL Gateway 嚴管
    Claude Desktop / 自寫 script / n8n ✅ 可改 endpoint Gateway 嚴管
    公司網路出站流量 ✅ Firewall force proxy Gateway 嚴管
    ChatGPT 網頁 / Claude.ai 網頁 ⚠️ Browser extension 半攔 即時 paste 脫敏 + 警告
    GitHub Copilot inline ❌ MS endpoint 不能改 規則 + 教育
    手機 app / 私人裝置 ❌ 物理上管不到 合約 + 信任 + 事後追溯

    核心心法:不假裝管得到不該管的東西。每塊都有對應措施,沒有「假裝有但實際沒有」的灰區。資安部門能說明、員工能理解、出事能追責。

    「拉力 > 推力」的設計哲學

    對「不能管的世界」,訴諸三層(從硬到軟):

    Layer 1: 用「拉力」把人留在 Gateway 裡(最重要)

    讓 Gateway 比網頁版好用,員工自然不繞過:

    • Gateway 自動注入公司腦(員工不用每次貼 context)
    • Gateway 連 frontier 雲(Claude Opus 4.7、GPT-5.5、Gemini 3.1 Pro、DeepSeek V4),員工不用自己付費,還能依任務路由到最強模型
    • Gateway 整合公司 codebase RAG,網頁版做不到
    • Gateway 串流速度比網頁版快(內網直連)

    這是設計哲學的轉換:不是「禁止你用 X」,而是「Y 比 X 好用」。員工是理性人,會選好用的。80 人裡會有 70 人自動留在 Gateway,不用任何 enforcement。

    Layer 2: Browser Extension(半受控的中間地帶)

    • 偵測員工開啟 chat.openai.com / claude.ai / gemini.google.com
    • input 框 paste 時即時 regex 脫敏
    • 大量 paste(>500 字)跳警告:「這段內含 X 個敏感字,已自動替換 Y 個」
    • 不阻擋、不上報,只做防呆 condom

    Layer 3: 規則 + 教育 + 事後追溯

    • 明確紅字 list 寫進員工守則
    • 每季資安訓練(講具體案例)
    • DLP 遙測不阻擋只記 log,事後可追
    • 離職前 audit log 過一遍

    分級對應表怎麼從 0 開始建

    這是組織問題不是技術問題。沒有這張表,所有 Gateway 規則都是空的。

    誰主導

    • 準 CISO 角色(IT 主管 + 法務 + 老闆都接受的人)
    • 不要 IT 一個人定(太技術)
    • 不要法務一個人定(會把所有東西判 A 級,系統失效)
    • 不要部門主管各說各話

    Working Group(5-7 人)

    • 1 × 準 CISO(主導)
    • 1 × 法務(合規紅線)
    • 1 × IT 實作者(技術可行性)
    • 3-4 × 部門 senior(業務視角,挑會用 AI 的人)
    • 1 × 老闆 sponsor(拍板用,不參與每週會)

    四個 Phase(漸進式,不要追求一次到位)

    Phase 時間 目標
    Phase 0 1 週 列資料種類清單(50-100 種)
    Phase 1 2 週 粗分 A/B/C,先有 v0.1
    Phase 2 4-6 週 挑一部門試點,每週開會精修
    Phase 3 持續 全公司 + 月度 patch

    五個必避陷阱

    • ❌「不確定就 A 級」→ 系統失效,員工全跑網頁版
    • ❌ 追求 100% 完整才上線 → 永遠定不下來
    • ❌ 一次寫完不再動 → 6 個月後過時,員工不信任
    • ❌ 黑盒不公開 → 員工不知道為什麼被判 A 級
    • ❌ 法務一個人說了算 → 變成沒人用的合規劇場

    核心原則:先有粗版上線,再用真實流量精修 > 想清楚再上線

    KPI:唯一最重要的數字

    North Star(唯一最重要)

    本月 Gateway request 數
    ÷
    (Gateway request 數 + 偵測到的網頁版 LLM 流量)

    公司網路 DNS / firewall log 看得到員工開了多少次 chat.openai.com / claude.ai / gemini.google.com(域名級,不看內容,沒有隱私問題)。這個比例 = 「員工選 Gateway 的比例」,目標6 個月內達 90%+。< 70% 代表 Gateway 拉力不夠,要查為什麼。

    四象限 Dashboard

    象限 指標 目標
    採用 月活用戶 / 全員 80%+
    替代 North Star 90%+
    體驗 Gateway p50 延遲 < 500ms
    體驗 月度 NPS(vs 網頁版) 4.0/5+
    健康 Layer 1 regex 命中率 > 85%
    健康 員工申訴誤判率 < 0.5%

    月度報告:三個問題就夠

    1. 「上個月 X% 員工選擇 Gateway over 網頁版」← North Star
    2. 「員工繞過 Gateway 的 Top 3 原因」← 下個月修哪邊
    3. 「Gateway 帶來的安全收益 + 成本」← 攔住多少 A 級洩漏、雲端費用變化

    第一個月 MVP 時程

    不要一次蓋大廟。Phase 0 砍到極簡,先讓 Claude Code + Cursor 用戶跑起來,驗證治理流程能不能撐 80 人,再擴展。

    交付
    W1 公司腦 repo + 3-5 條 Iron Rules + build.sh(支援 Claude Code & Cursor)
    W2 個人腦 repo template + 員工 onboarding 文件 + 第一場培訓
    W3 脫敏字典 v0(client_names.txt + employee_names.txt)+ pre-commit hook 擋紅字
    W4 Curator 制度上線(每 team 一個 + 每週 1 小時 review)

    Brain Server / ChatGPT 整合 / 本地 Ollama / 完整 Gateway → 全部砍到 Phase 1(第 2-4 個月)。樂觀估計:1 個全職工程師 3-4 個月做到可上線 Gateway。悲觀:6 個月 + 2 個工程師。

    結語:這是 AI 時代的雙贏

    傳統 IT 部門做了再美的 UI,客戶都會嫌不好用 — 這是 ERP 行業 30 年的詛咒。AI 時代的反轉是:不要再做永遠改不完的 UI 了,做「給 AI 安全取資料的入口」就好。客戶用自己愛的 AI 工具(ChatGPT、Claude、Cursor),透過你架的 Gateway 安全地取資料、做事情。

    這對 RD 是解放:

    • 不再被「客戶嫌頁面醜」「客戶嫌操作太多步」這類無底洞的 UI/UX 工單吃掉時間
    • 可以回去做真正有複利的工作:ISO 流程符合性、資安審核、業務邏輯正確性
    • 每一個 RD 寫的 brain markdown,都是公司 domain knowledge 的長期資產,不會因員工離職就消失
    • 新進員工從第一天就站在累積的 brain 上工作,onboarding 從 3 個月縮到 3 週

    對員工是賦能:每個人都能用自己最熟的 AI 工具,在公司架好的安全護欄內,自行開發小工具、解決自己的痛點。對公司是護城河:domain knowledge 從個人腦袋變成公司資產,可累積、可審計、可傳承。

    整套設計的核心心法只有四句:

    • 能管的嚴管,不能管的不假裝管
    • 拉力 > 推力,讓 Gateway 比網頁版好用
    • 員工不感知,系統默默路由
    • 先粗版上線,真實流量精修

    剩下的就是把 working group 召集起來,開第一次會。

    2026/5 技術參考時間戳

    本文涉及的具體模型版本、開源工具、ISO 標準以撰文時間為準,LLM 領域變化快,請以最新發布為主:

    • 雲端 frontier(2026/4 發布):Claude Opus 4.7、GPT-5.5、Gemini 3.1 Pro、DeepSeek V4。各家擅長領域不同,「routing by task type」已成為主流架構。
    • 本地頂級開源:Qwen3-Coder-Next(80B 總參 / 3B active,MoE,256K context)、Qwen3.6、Kimi K2.6、DeepSeek V4、Llama 3.3 70B。
    • 本地 LLM 平台:Ollama 仍是預設選擇,production 並發推 vLLM V1(2-4 倍吞吐)。
    • AI Gateway 開源工具:LiteLLM(unified API to 100+ providers)、Portkey(observability + guardrails + PII redaction)、Kong AI Gateway。2026 企業常見組合是 LiteLLM 當 proxy + Portkey 做 observability。
    • PII 脫敏:Microsoft Presidio v2.2.362(2025/3 釋出,2026/5 仍是最新版),含 image redactor 與 DICOM 醫療影像支援。
    • 合規標準:ISO/IEC 42001:2023(AI 管理系統,目前唯一可認證 AI 標準)、ISO 27001:2022、ISO 27701。Schellman、TÜV SÜD、BSI、DNV 都是合格認證機構。
  • 我的家庭照顧 14 個 HTML 工具:dementia-care monorepo + 實戰使用指南

    重點摘要

    • dementia-care monorepo 是 14 個 HTML/Python 工具的 personal toolkit:圍繞「家人照顧」這件事,自家用為主,朋友(藥師)+ 社區照護者也用得上。
    • 起源:照失智媽媽 2 年急速進展 + 育兒 2023 年出生女兒,前面有 15 年照爸爸 stroke 失能 secondary 經驗。每天遇到 friction 就寫一個小工具。
    • 上位 mission:「讓整個家忙起來」(ambient engagement,Marx & Cohen-Mansfield 2010 循證概念)—— 工具不是治療,是降低照護者啟動 friction。
    • 共用 spec:純前端、單檔 HTML、0 CDN、0 build、離線可用、繁體中文、大字大按鈕、SVG emoji favicon、GitHub Pages 部署。
    • 5 條自我約束(2026-04-28 後):凍結新 sub-project 60 天 / commit cap 20/天 / 每週一個下午全關 / 0 CDN 機器化守門 / 不主動推工具只分享方法。
    • 跨專案 lessons:純黑白對白內障是錯的 frame、圖書館 ≠ 景點 precision contract、Google Maps fallback default pin 陷阱、Selenium 驗證 self-use 例外、物件 literal 尾逗號讓整頁 blank。

    dementia-care monorepo 是 14 個圍繞家庭照顧的 HTML/Python 工具集,過去半年累積。為什麼會有這個 repo?照失智媽媽,順便做給太太、藥師朋友的太太、社區照護者用 ——「自家工具集 + 經驗分享」,不是 community product。

    這篇是這個 monorepo 的全面整理:14 個工具的分工、起源故事、共用設計原則、5 條自我約束、5 條跨專案踩坑 lessons。給想做類似 personal toolkit 的人參考,也給之後的我自己回頭看為什麼這樣設計。

    為什麼會有這個 monorepo?

    結構上設計給:白天只有你跟長輩、家屬 backup 0、商業 app 都假設你有時間引導。我家 timeline:

    • 15 年照父親 stroke 失能(secondary,媽媽是 primary,2024 過世)
    • 2024 起媽媽輕度失智 → 2 年急速進展到中重度
    • 2023 出生女兒進入 toddler 階段
    • 太太是藥師、有正職,白天無法 backup
    • 過去半年我變 primary caregiver

    每天遇到 friction(媽媽問同樣問題第 50 次 / 居服員交班沒交集 / 回診忘記想問什麼 / 女兒週末沒地方去) —— 直接寫一個小工具,不寫 spec、不開會、不等 backlog。半年累積 14 個。

    上位 mission 是「讓整個家忙起來」。對應的循證概念是 ambient engagement(Marx & Cohen-Mansfield 2010 “Engagement of Persons with Dementia”):環境引發的活動 vs 人引發的活動,失智長輩參與有意義活動的「量」與認知衰退斜率負相關。工具不是治療,是降低照護者啟動 friction —— 讓 engagement 在沒人陪伴的疲累照護日實際發生。

    14 個工具分四大類

    🧠 失智照護生態系(主線資料閉環)

    工具 類型 說明
    陪伴小幫手 v1 互動遊戲 15 個認知訓練遊戲,8 級難度滑桿自動選 10 個顯示
    陪伴小幫手 v2 試驗版 推薦式首頁 + 照護者陪伴指南 + 今日摘要分享
    白板 OCR Bot Telegram Bot 每日白板照 → Gemini 3 Flash(box-index 策略,磁鐵在第幾格)→ iDempiere Z_momSystem
    就診小幫手 Web App 回診前 prep:抓 iDempiere 異常、症狀分類、診間錄音

    👶 兒童 + 親子

    工具 類型 說明
    小朋友學習樂園 學齡前互動 1-6 歲 23 個活動,4 年齡層自適應深度
    週末出遊地圖 親子景點 全台 22 縣市 850+ 景點 + 多點路線規劃
    托嬰幼兒園手冊 方法論 0-6 歲托嬰中心 + 幼兒園選擇方法論(4 種類型對照,評估 SOP)

    📖 生活方法論手冊

    手冊 主題
    care-handbook 長照手冊:找居服員 / 日照 / 喘息 / 機構 / 看護工 / 失智專屬支援系統
    home-handbook 家中照護手冊:13 項物理改動 + 早午晚 SOP + 援手系統 awareness
    home-handbook-classic 家中照護手冊舊版(保留作對照,新版改用 home-handbook)
    garden-handbook 家庭園藝手冊(可食 + 觀葉 + 觀花 + 根莖類,陽台/窗邊/室內)— 對失智長輩是 behavior redirection 工具
    pet-handbook 家中寵物生活手冊(貓/狗/兔/鳥/魚/烏龜)—「會主動靠近的家人」,失智長輩 + 小孩雙受惠
    mindset 心法手冊 — 6 條視角(失智不是失能 / 用加法對抗減法 / 躁動不是無聊 / 動線是功能可及性 / 誠實版優於善意包裝 / 手冊是網狀不是清單)

    🧃 飲食 / 健康

    • health-drinks:**19 款醫療營養品 + 嬰幼兒配方 + 高蛋白補充品**並排比較(180-280ml 容量範圍。三重使用者:Tom 自家、藥師朋友、藥局客戶)

    失智照護主線:資料閉環長什麼樣?

    14 個工具裡 4 個是失智照護核心,串成一條 daily/weekly 閉環:

    [居服員 / 我]
        ↓ 拍白板照傳 Telegram
    whiteboard-ocr-bot
        ↓ Gemini 3 OCR + 人工 confirm
    iDempiere Z_momSystem(每天一筆紀錄)
        ↓ REST API
    mom-clinic-companion
        → 回診前產出「今天要問醫生的 3 件事」

    白板每天記錄媽媽 餐食 / 用藥 / 行為事件 / 睡眠時數。OCR Bot 把照片轉成結構化資料寫進 iDempiere(自家 ERP-as-PHR,Z_momSystem 表 12 欄位)。回診前 mom-clinic-companion 比對「上次回診 → 今天」vs「上上次回診 → 上次回診」兩個 window,抓變化顯著項目給神經科醫師看具體事件,不是「最近狀況不太好」這種模糊描述。

    這條主線運轉半年,媽媽每月回診從「我也不知道要說什麼」變成「上週三晚上她突然找不到回家的路」這種具體 evidence。神經科醫師根據具體事件調藥,比根據家屬情緒描述準確很多。

    共用設計原則 — 為什麼都是單檔 HTML?

    14 個工具共用同一套 spec:

    • 單檔 HTML:HTML + CSS + JS 全塞 `index.html`,不拆檔。對 backup / 修改 / 分享(直接寄一份)極友善。
    • 離線可用:所有資源 inline(SVG favicon、base64 圖、不依賴 CDN)。山區農場、長輩家 wifi 弱 都能跑。
    • 0 CDN 強制:禁止任何 fonts.googleapis / cdnjs / unpkg / jsdelivr / Google Analytics / 外部 script。原因:使用者打開網頁時瀏覽器會從使用者裝置直接發請求到 CDN 伺服器,洩漏 IP + User-Agent + 時間給第三方,違反 COPPA(兒童)/ GDPR-K / 個資法。有專屬 CI workflow `monorepo-cdn-ban.yml` 機器化守門(2026-04 加),違反即擋 push。**Caveat**:`health-drinks` 因為較早期建置仍用 Chart.js + Google Fonts CDN,是 monorepo 唯一例外,計畫之後遷移成 inline。
    • 0 build step:不進 npm、不進 webpack。寫完開瀏覽器看,改完 commit push 30-60 秒 GitHub Pages 部署。
    • 繁體中文 + 大字大按鈕:觸控友善,最小點擊區 48×48px。
    • SVG data URL emoji favicon:離線也有 tab icon。

    低視力對比:原本以為「純黑底 + 純白字 = 最大對比 = 最適合低視力長輩」,後來發現對中度白內障(monorepo 主場景)會因 forward light scatter 引發 halation/glare —— 21:1 是 over-shoot,不是越高越好。Evidence-based 替代:米白底深字(#222 on #f5f5f5)/ 深底淺字(#e8e8e8 on #1a1a1a)/ 字級 ≥ 24px / line-height ≥ 1.6。維持 WCAG AAA(7:1+)但消除極端 glare。

    5 條自我約束(2026-04-28 後加)

    跨 6 domain expert review 共識項。寫進 CLAUDE.md 變強制規則,我自己做時也守:

    1. 凍結新 sub-project 60 天(到 2026-06-30):14 個已過載,主軸佔比 < 35%。6 個月 450+ commits(`git log –since=’2025-11-01’`),「持續產出 = 情緒迴避」紅旗。例外:只允許 archive / 整併 / 刪除。解凍後若仍想開新工具,先在 blog 寫一篇「為什麼這值得開一個工具」,沒寫完不開。
    2. Commit cap 20 / 天 (soft warning):超過 20:pre-commit hook 跳對話框問「今天你媽吃幾餐、女兒抱了你幾次、你笑了幾次」。失智照護者 burnout 是 monorepo 結構性 SPOF —— Tom 倒下 = mom-clinic 朋友家屬可能誤診 = 整個生態系凍結
    3. 每週一個下午全關:不寫 code、不寫 blog、不規劃 feature。陪女兒、發呆、睡覺都行。「讓整個家忙起來」mission 不該包含 Tom 自己一刻不停。
    4. 0 CDN 機器化守門:`.github/workflows/monorepo-cdn-ban.yml` 自動掃所有 *.html。違反即擋 push。不再靠人記得。
    5. 不主動推工具,只分享方法:工具是 personal toolkit,維護優先順序看當下需要。不主動推給陌生使用者(避免讓人對「會被維護」產生錯誤期待)。朋友(藥師)是「資訊交流」不是「使用者」,不發配工具帳號。方法寫成 blog,blog 才是擴散渠道(這篇就是)。

    5 條跨專案踩坑 lessons

    1. 純黑白對白內障是錯的 frame

    「最大對比 = 最適合低視力」是錯的。對白內障(monorepo 主場景)forward light scatter 引發 glare,21:1 反而降可讀性。WCAG 21:1 是 物理可量化(luminance ratio),「適合低視力」是 臨床效果(可讀 + 不疲勞 + 不誘發 glare),兩者不是同一件事。Evidence-based:米白底深字 / 深底淺字 / 字級 24px+ / line-height 1.6。

    2. 圖書館 ≠ 景點:precision contract

    不同 place category 對 precision 容忍度不同。景點(公園 / 山林 / 老街)area centroid 1-2 km 噪音 OK(本身就大);圖書館 = 單一建築,1 km 偏差 = 不同樓棟 = 錯,不能套同一條 fallback 規則。對「single building」類,寧可 entry 數量少(精確) 也不要 area centroid(誤導 user)。

    3. Google Maps fallback default pin 陷阱

    Google Maps geocoding 找不到地址時不會回 error,而是 silent fallback 回最後一個成功 query 的 cached coord。kids-weekend 跑 23 筆 Playwright 有 3 筆全部 fallback 到同一個 [24.9790, 121.4579]。必跑 sanity gate:縣市 bounding box 比對。任何 geocoding pipeline 必須有 downstream sanity check —— 不能信「200 OK + 有 @lat,lng」就當作對的。

    4. Selenium 驗證 self-use 例外 ≠ photo scraping hard violation

    Google Maps Platform ToS 是合約不是法律,enforcement profile 對「自用 / 非商業 / 中等規模」幾乎為零。判斷不是 binary —— 看(1) self-use vs 商業化 (2) 一次性 vs 持續性 (3) 文字 vs 照片 三維度。kids-weekend 圖書館 geocode 落在「self-use + 一次性 + 文字座標」三個都 OK 的格子,屬技術性 ToS issue。但 photo extraction + redistribute 仍是 hard violation(著作權法 §91 §92),商業化應升級付費 API。

    5. 物件 literal 尾逗號讓整頁 blank

    2026-04-21 kids-companion 整頁 blank 事故:新增 IMG 物件忘記前一筆尾逗號,SyntaxError 整頁掛。單檔 HTML 沒 webpack 兜住,JS 一錯整頁 die。寫 lint script (`scripts/lint_places.py`)機器化檢查每筆 entry 結尾。

    為什麼不對外推銷?

    因為這是 tier 2 personal toolkit 不是 community product。三個原因:

    1. 維護順序看自家當下需要:某天我家 schedule 變、媽媽病程變、女兒入學,工具優先順序就變。對外推銷會建立「會被維護」期待,實際上我可能突然停某個工具 —— 對 user 不公平。
    2. SPOF 問題:14 個工具只有我一個 maintainer,我倒下整個 stop。對外推 = 對外承諾,承諾兌現不了 = 信譽損傷。
    3. 方法 vs 工具:方法可以用文字傳承,擴散性高;工具 binding 在我家 schedule + 我家硬體 + 我家數據格式。方法寫成 blog,工具留給有能力 fork 改的人。

    朋友(藥師)是「資訊交流者」不是「使用者」 —— 我跟她討論失智用藥,她跟我討論病人家屬,但我不發給她工具帳號讓她依賴我的伺服器。她想用就 fork,改成她家用。

    給想做類似 personal toolkit 的人的建議

    1. 明確 scope = self-use:這個 frame 鎖死所有設計決定 —— 不做 user account、不做 paywall、不對外推銷、不收 review。Scope 一變,所有 compliance / privacy / 合規 trade-off 全變。
    2. 單檔 HTML 是 personal toolkit 的甜蜜點:0 build / 0 server / 直接寄一份檔案 / 純前端 / 離線 / GitHub Pages 免費部署。技術簡單到不會卡住做事的人。
    3. 0 CDN 是隱私底線:任何外部 fonts / analytics 都洩漏 user IP。家庭應用(兒童 / 醫療 / 失智)不能讓 Google 知道你家在訪問什麼工具。寫 CI workflow 機器化守門,不靠人記得。
    4. 每個工具對應一個 friction:不要先想「我要做什麼工具」,要想「我每天卡在什麼」。卡在交班 → OCR Bot;卡在回診 → mom-clinic;卡在週末 → kids-weekend。
    5. 政府開放資料 > 商業 API scraping:libstat / data.gov.tw / TGOS 對台灣應用是乾淨 source,合規且持久。每個 domain 找對應的政府 source(圖書館 / 醫院 / 學校 / 古蹟)。
    6. self-use 工具不是免責令:Photo extraction、持續性 production scraping、商業化 仍是 hard violation。判斷 framework 看 (1) self-use vs 商業 (2) 一次性 vs 持續性 (3) 文字 vs 照片 三維度。
    7. 給自己自我約束:照護者 burnout 是結構性 SPOF。commit cap、每週全關一下午、凍結新 sub-project,這些不是「強制症」是「對抗持續產出 = 情緒迴避」的 hard rule。

    —— 工具實戰判斷與用法 ——

    三層分工:Handbook、工具、專業

    使用 monorepo 之前,先建立三層分工的觀念:

    作用 對應 monorepo 頻率
    Handbook 認識系統、申請流程、SOP 學習 care-handbook / home-handbook / childcare-handbook 階段性(剛確診、要申請居服員)
    工具 每日操作、降低啟動 friction 陪伴小幫手 / OCR Bot / mom-clinic / kids-weekend 每日 / 每週
    專業 診斷、用藥、急救、法律 神經科 / 精神科 / 1966 / 1925 / 119 / 共照中心個管師 回診 + 突發事件

    實戰原則:剛確診先讀 handbook(2-3 天密集吸收),3 個月後 handbook 慢慢變參考書,工具變每日操作,專業在事件發生時 escalate。

    7 個照顧場景對應工具速查

    場景 主要工具 配合 handbook
    失智剛確診那週 無工具(handbook 為主) home-handbook P0 + care-handbook 申請流程
    居服員每天交班 白板 OCR Bot home-handbook 居家日 SOP
    媽媽情緒不好想做點事 陪伴小幫手 v2(推薦)/ v1(自選)
    回診前一晚 mom-clinic-companion
    週末帶孩子去哪 kids-weekend(住哪 → 路線)
    孩子在家想做活動 kids-companion(2-6 歲 4 年齡層自適應) — (kids-companion 自己分齡)
    第一次申請長照 無工具(handbook 為主) care-handbook 7 步 SOP + 援手系統

    場景 1:失智剛確診那週 — handbook 為主

    剛確診那週不要急著上工具。先做 5 件事(home-handbook P0 章節):

    1. 法律 P0:輔助宣告 / 監護宣告 / 預立醫療決定 — 趁失智長輩仍有意思能力時辦,過了會難辦
    2. 醫療 P0:確認確診醫院 + 預約共照中心 + 申請重大傷病卡
    3. 防走失:愛心手鍊 / GPS / 鄰里通報網
    4. 物理改動 13 項(home-handbook 列清單):防滑地墊 / 衛浴扶手 / 廚房瓦斯總開關 / 大門感應…
    5. 申請長照:1966 → 照管專員到府評估 → 失能等級 → 服務媒合(care-handbook 7 步 SOP)

    這週不要碰工具。一邊吸收 handbook,一邊處理法律醫療 P0,一邊跟家人討論分工。工具是後面 2-3 個月開始有居服員 / 日照排班後才會用得上。

    場景 2:居服員每天交班 — 白板 OCR Bot

    白板 OCR Bot 解決交班斷層:居服員早上來、下午走;家屬晚上接手 — 中間 8 小時居服員紀錄不傳給家屬,神經科回診也說不清楚。

    實際流程:

    1. 家裡放一塊白板,居服員每天用筆寫紀錄(餐食 / 用藥 / 行為事件 / 睡眠)+ 用磁鐵標記固定欄位的選項
    2. 居服員下班前 / 我經過時拍照傳 Telegram bot(`telegram_bot.py`)
    3. Bot 走 `ocr_pipeline.py` → Gemini 3 Flash Preview API,**用 box-index 策略**(磁鐵在第幾格)避開手寫中文字元 OCR — human-as-verifier 設計
    4. 手機收到 bot push 訊息「請確認」,3 秒過目即可。錯了直接改文字回傳
    5. 自動寫入 iDempiere Z_momSystem(每天一筆 row,12 個欄位)
    6. 家屬晚上看 iDempiere 知道白天發生什麼,銜接夜間照護

    另也支援 📝 文字訊息 → 加時間戳(早 / 晚 / 大夜班)append 到當天備註欄;`/status` `/today` 指令查當天/累積狀態。`whiteboard-ocr-bot/index.html` 是純前端 demo 版本(模擬對話流程,不連網不傳資料),正式版要 Python + iDempiere REST API 跑在自家 server。

    關鍵 design:box-index 策略 + human-as-verifier 不是全自動。Gemini OCR 對手寫長輩字跡不一定 100%(尤其用藥名稱),所以白板用固定欄位 + 磁鐵 — Gemini 只要識別「第幾格有磁鐵」這種離散 boolean,不用識別自由手寫,大幅降低錯誤率。

    場景 3:媽媽情緒不好想做點事 — 陪伴小幫手 v2

    陪伴小幫手有 v1 / v2 兩版本並存:

    情境 用 v1 還是 v2?
    媽媽心情好,自己想挑 v1(10 格遊戲卡讓她挑)
    媽媽疲累 / 不擅選擇 / 照護者也累 v2(一鍵推薦「今天一起做這個好嗎」)
    想知道對長輩說什麼話帶遊戲 v2(每遊戲 3 條陪伴指南)
    想記錄今天玩了什麼貼 LINE 給家人 v2(每日摘要一鍵複製)

    v2 推薦邏輯:依時段(早 / 午 / 晚 / 深夜)+ 最近玩過避免重複 + 當前難度自動挑一個遊戲。次要選項「換一個 / 我想自己選」字級縮小、無底色,降低照護者選擇癱瘓 — 是給疲累照護者的設計。

    難度滑桿 1-8 對應方式(`v1 CLAUDE.md` 規格):

    • 1-2 輕度:遊戲篩選後較難(辨識變化小、選項多),語音只朗讀題目
    • 3-6 中度:遊戲難度中等,語音朗讀題目 + hover 選項唸出
    • 7-8 重度:遊戲篩選後最簡單(選項少、對比大),語音朗讀題目 + 所有選項,重複一次

    遊戲庫(`GAME_LIBRARY`)15 個遊戲每個有 `min`/`max` 範圍,`selectGames(level)` 從符合範圍的遊戲中隨機抽 10 個顯示首頁。選擇難度時看當週實際狀況試,不是越難越好 — 失智長輩做不到會挫折,做太簡單會無聊

    場景 4:回診前一晚 — mom-clinic-companion

    失智回診最大的問題是「**最近狀況不太好**」這種家屬模糊描述,神經科沒辦法調藥。mom-clinic-companion 讀 iDempiere `Z_momSystem` 表(白板 OCR Bot 寫入的),把 raw data 歸納成照護者可以記住、可以問的內容。

    實際 4 個 sections(`mom-clinic-companion/index.html` H2):

    1. 🚨 值得跟醫生討論的 — 規則引擎自動比對「上次回診 → 今天」vs「上上次回診 → 上次回診」兩個 window,找變化顯著項目
    2. 💭 這一個月媽媽發生過 — 從白板 OCR Description 欄抓症狀關鍵字
    3. 📋 這次要問醫生 — 從上面兩區一鍵「加進問題」,手動補其他
    4. 🎙️ 診間錄音 — 醫師講話 STT 轉字,回家同步回 iDempiere

    核心設計是回診日期感知:`APP.visits` 是回診日期 array,`computeWindows()` 產生最新兩段比對區間 — 因為實際回診頻率不規則(通常每月,有時兩週),按日曆切會不準。

    場景 5:週末帶孩子去哪 — kids-weekend(MAP 工具)

    kids-weekend 是 monorepo 裡最大的 MAP 工具:全台 22 縣市 851 筆親子景點 + 路線規劃(`STATE_VERSION` 3,單檔 HTML ~700KB)。解決的具體問題是「從家出發 X 公里範圍內,有什麼順路可以串成一日」 —— 媽媽社團、IG 收藏、Google Maps 我的清單,都做不到「按距離 + 順路 + 一鍵多點導航」這件事。

    1 題 wizard 是 deliberate 砍簡 — 從 4 題到 1 題

    2026-04 砍簡前,wizard 有 4 題:住哪 + 天氣 + 年齡 + 範圍。實測發現 user(太太、藥師朋友)80% 都直接 next 跳過後 3 題:

    • 天氣晴雨:家長自己抬頭看,問了多餘
    • 年齡:每筆景點 entry 已有 `ages: [‘0-2′,’2-3′,’3-6’]` 標籤,filter UI 之後再勾就好
    • 範圍:**家庭多在 20 km 內**(自家 + 朋友家實測 4 個月),預設 20 km 一拉就動

    所以剩 1 題:**「住哪?」**(GPS 一鍵 / 縣市 + 區下拉)。設完直接看推薦清單,範圍可拉滑桿改 5-400 km。砍題目比加 feature 更重要 —— personal toolkit 的設計訓練。

    實際 6 步使用流程

    1. 設家 — 第一次選,之後 `localStorage[kidsWeekendState]` 記住。GPS 一鍵會 reverse geocode 成「📍 新北土城」(不顯示醜的經緯度)
    2. 看推薦清單 — 預設 20 km 內景點,室內/戶外/觀光工廠/博物館/公園/海邊/廟宇/老街全混合
    3. 篩 filter — 晴天/雨天/0-2 歲/室內/避開人多/避開假日塞車黑名單
    4. 勾比較籃 — 1-3 個目的地加入比較籃
    5. 看路線預覽 — corridor 演算法找順路景點(預設 5 km corridor,`STATE.preferences.corridorWidthKm`)+ 計算多點總公里 + 拖 ⋮⋮ 換站順序
    6. 一鍵 Google Maps 多段導航 — 直接丟 Maps app(`maps.google.com/dir/?…` URL),不用手動複製貼

    實例(README 範例):「搜尋觀音山設目的地 → IKEA 新莊距路線 0.44 km ➕ 加入 → 五股 ➕ 加入 → 想加林口三井但 5.13 km 擦邊 → corridor 拉到 6 km → 拖 ⋮⋮ 把林口移到第 1 站 → 一鍵 Google Maps」。

    Place precision contract:景點 vs 圖書館 fallback 策略

    kids-weekend 的距離計算 priority(`getPlaceCoords()` line 2354):

    1. 先查 `PRECISE_COORDS[place.id]` — 有就用
    2. 沒有 → fallback `getCoordsFromArea(place.area)` 取「縣市 + 區」中心點(`TAIWAN_DISTRICTS` lookup,286 個區 centroid)
    3. 都沒有 → null,distance filter 排除

    但圖書館不能 fallback 區中心(本文上方「跨專案 lesson 2」)。圖書館是單一建築,1 km 偏差 = 不同樓棟 = 錯。所以 2026-04-30 圖書館 wave A→C 擴點時,**沒有精確 coord 的圖書館直接 drop,不入庫**(reject 連江縣文化處 / 桃園兒童文學館 / 高雄新興閱覽室 3 筆,因為 Google Maps fallback 到 default pin)。

    Metadata flag 系統 — 怕感冒 / 怕塞 / 失智注意

    每筆景點除了基本欄位(name / area / ages / types / hours / website),還帶 metadata flag 給推薦邏輯參考:

    Flag 含意 影響
    `elder_friendly: true` 長輩友善(平緩、無障礙、有座位) 失智 + 親子混合家庭優先推薦
    `weekend_jam: true` 假日塞車黑名單(陽明山 / 九份 / 淡水) 勾「避開塞車」會排除
    `dementia_caution: true` 失智長輩慎入(動物園 / 大型賣場 / 高 crowd 易迷路) 混合家庭手動觀察
    `crowd: ‘low|mid|high’` 人潮 enum UI「🤧 避開人多景點」剔除 high

    851 筆景點怎麼累積 — 5 wave + 圖書館 wave A→C

    景點不是一次抓進來的,分 wave 增量。每 wave 對應「家附近還缺什麼類型」的 surface gap:

    Wave 主題 +景點
    v3.11 base 親子館 / 公園 / 觀光工廠 主軸 ~770
    v3.12 0-2 歲友善 補嬰幼兒場域(托嬰中心 / 兒童美術館) +8
    v3.13 觀光工廠 DIY 體驗 + 雨天首選 +12
    v3.14 露營區 Glamping + 渡假農場 +10
    v3.15 雲嘉南高屏 南台灣覆蓋補齊 +14
    圖書館 wave A→C(2026-04-30) 縣市總館 + 親子閱覽室 + 文學/繪本 +33

    圖書館 wave 走獨立 pipeline:libstat 國家圖書館抓政府公開資料 → OSM Overpass strict verify(`amenity=library` POI 全台 853 個)→ Google Maps Selenium geocode 補不足 → 縣市 bbox sanity 過濾 → 通過才入庫。三條 source 各補不同覆蓋率,合規(政府開放資料 0 ToS)+ 精確(building-level coord)。

    每個 wave 的關鍵 lesson:**對應實際 user gap,不盲目擴量**。盲目擴點會稀釋信號(user 搜「週末去哪」跳出一堆樓上閱覽室,反而難用)。圖書館 wave 砍 46 筆閱覽室因為「樓上小空間 ≠ destination」,只進 33 筆 high-value。

    場景 6:孩子在家想做活動 — kids-companion

    kids-companion 是 2-6 歲兒童平板學習 app,核心設計是「自適應深度 (Adaptive Depth)」 —— 同一內容,不同年齡,不同深度。4 個年齡層各有版本:

    • toddler(幼幼班 1-2 歲):選項 2、語音題目+選項重複、目標字 140px、無拖拉
    • small(小班 3-4 歲):選項 2-3、語音題目+選項、目標字 120px
    • middle(中班 4-5 歲):選項 3-4、語音題目+hover、目標字 100px、可拖拉
    • large(大班 5-6 歲):選項 4-6、只朗讀題目、目標字 80px

    使用流程:設角色 emoji + 年齡層(toddler/small/middle/large) → 首頁活動卡 → 系統依年齡層自動調選項數 / 字級 / 互動方式。設計哲學在 brain memory `project_kids_companion_philosophy.md`。

    跟陪伴小幫手 v1/v2 關鍵差異:Web Speech API pitch 設定不同。kids-companion `pitch: 1.2`(高頻活潑感吸引兒童);陪伴小幫手 v1/v2 都已校正成 `pitch: 0.95`(老年聽力 presbycusis 高頻損失,低頻反而清楚)。同 API 不同設定,因為使用者生理不一樣。

    場景 7:第一次申請長照 — care-handbook 7 步 SOP

    長照申請新手最大的痛點:不知道要打給誰、要準備什麼、評估會問什麼。care-handbook 直接給 7 步 SOP:

    1. 打 1966(長照專線,免費)→ 報長輩姓名 + 縣市 + 失智症
    2. 等照管專員到府評估(通常 1-2 週內)
    3. 準備評估會問的:長輩 ADL/IADL 量表自評 + 失智診斷書 + 重大傷病卡(如有)
    4. 失能等級判定(2-8 級)→ 對應給付額度
    5. 服務媒合(居服員 / 日照 / 喘息)→ 排面試
    6. 居服員 / 日照面試 SOP:重點問題、紅旗信號、簽約注意事項(handbook 列詳細 checklist)
    7. 失智專屬支援:申請共照中心 + GA07 家屬訓練諮商給付碼 + 巷弄失智據點(這條在 care-handbook 獨立章節,大多家屬不知道)

    handbook 不取代 1966,是讓你打 1966 之前知道要問什麼。直接打 1966 也可以,但你會發現照管專員講的有些聽不懂(BA / CA / GA01-07 給付碼),先看 handbook 心裡有底再打。

    場景 8:選托嬰中心 / 幼兒園 — childcare-handbook

    childcare-handbook 是托嬰中心 + 幼兒園選擇方法論手冊(0-6 歲),不是「找最便宜」「找最近」這種比價工具,而是教**怎麼系統性評估** —— 在報名截止前知道「該看哪些點、該準備哪些東西、該追蹤哪些時間」。

    4 種托育類型(0-2 / 2-6 歲分流)

    • 托嬰(0-2 歲)3 類型:公托 / 準公共 / 私立
    • 幼兒園(2-6 歲)4 類型:公幼 / 非營利 / 準公共 / 私立

    5W1H 評估方法論(Who / What / When / Where / Why / How)

    Handbook H1「🎯 5W1H 評估方法論」拆 5 個 H2:你家是誰 / 選哪一類 / 什麼時候動 / 距離與動線 / 決策框架。每個維度有具體 checklist。

    核心 family mode:`sandwich`(三明治世代) — 全域狀態 `STATE.familyMode` 有 4 個值:`normal` / `sandwich`(同時照顧失智長輩 + 幼兒)/ `dual_income` / `single_parent`。**Tom 家是 sandwich**,工具設計 deliberately 給三明治世代設想:選離長輩家近 vs 離公司近的 trade-off、晚接送對失智長輩晚餐 SOP 的影響、公幼接送時間跟長輩日照時間怎麼對齊。

    state(`localStorage[childcareHandbookState]`):`childAge` enum + `familyMode` enum + `favorites` 收藏園所類型 + `checklist` 文件 / 行動完成度。可匯出匯入 JSON。

    場景 9:陽台種菜 / 觀葉 / 觀花 — garden-handbook

    garden-handbook 是家庭可食 + 觀葉 + 觀花 + 根莖類種植手冊,涵蓋陽台、窗邊、室內盆栽。每個 plant 一個 entry,**統一 10-section 結構 + 5W1H 總覽 + 購物籃匯入**。

    為什麼 garden 在失智照護 monorepo 裡?

    因為 repo 上位 mission「讓整個家忙起來」(ambient engagement)—— 用植物讓家裡有生長中的東西、每天互動的動作、可採可賞的成果。對失智長輩,種植是 behavior redirection 的有效工具:她躁動時遞她澆水器,「來,我們去澆花」是個比「坐下休息」更不抗拒的指令,因為她可以「做有意義的事」。

    10-section 結構 + 5W1H + 規劃模式

    每個 plant entry 統一格式:

    • 5W1H 5 秒總覽:`renderPlantOverview()` 從 meta + sections 自動抽 6 行摘要(怎麼種 / 多久收成 / 適合哪些家)
    • 10-section 結構:選盆 / 選土 / 種法 / 澆水 / 採光 / 病蟲害 / 採收 / 留種 / 失敗訊號 / 跟其他植物搭配 — 每株都這 10 段
    • 規劃模式:設定頁 toggle 開啟,filter 按「家庭模式 / 季節 / 採光」推薦對應 plant
    • 購物籃匯入:一鍵把該 plant 需要的盆/土/工具加入購物清單(連到 brain memory `feedback_starter_kit_ordering.md`「基礎設施先,活體後」原則)

    state:`localStorage[gardenHandbookState]` — 最愛 / 購物籃 / 規劃模式 / 照護級數 / memos,可匯出匯入 JSON。

    場景 10:讓家有「會主動靠近的成員」 — pet-handbook

    pet-handbook 是家中寵物生活手冊,按 6 個物種分類:**貓 / 狗 / 兔 / 鳥 / 魚 / 烏龜**。每物種下有多個 topics(親訓 / 飼料 / 醫療 / 訓練)。

    跟 garden 的 frame 區別 — 寵物是會主動靠近的家人

    核心定位:寵物是會主動靠近你的家人。跟植物不一樣 —— 他會自己跳上你腿、用頭頂你手、發出呼嚕聲。他不是被動被照顧的對象,**是家庭成員**。

    對失智長輩尤其重要 —— 當她大腦退化、溝通困難,一個會自己靠近的生命,是「她還被需要、她還存在」的證明。garden 是 ambient(植物在那裡),pet 是 active(寵物來找你)—— 兩者並用補不同層次的 family vitality。

    對小孩:寵物從小同住的孩子發展(empathy / 責任感 / motor skills)有 evidence-based 好處。混合家庭(失智長輩 + 幼兒 + 寵物)是 monorepo 主場景之一。

    場景 11:照護判斷迷茫時 — mindset(6 條視角)

    mindset 是「心法手冊」 — 不是 SOP、不是 checklist,是一位失智照護者面對新狀況時,腦袋裡跑的判斷視角。中英雙語(zh + en),開源歡迎其他家屬補充。

    6 條視角

    • 視角 1:失智不是失能 — 她不是壞了,是用不一樣的方式運轉
    • 視角 2:用加法對抗減法 — 認知衰退是減法,加新刺激抵銷
    • 視角 3:躁動不是無聊 — 行為背後通常有具體 trigger(尿急、肚子餓、燈太亮)
    • 視角 4:動線是功能可及性 — 她做不到不一定是失能,可能是動線設計
    • 視角 5:誠實版優於善意包裝 — 不要編故事騙她,她感受得到
    • 視角 6:手冊是網狀不是清單 — 沒有「按順序做完」這種事

    caveat 自註:Handbook 自己寫了「⚠️ 不要把任何視角當絕對」 —— 「這 6 條視角是我寫家中照護手冊時用的判斷方式,不是失智照護的真理」。比如「視角 2 加法對抗減法」跟主流的「懷舊治療(Reminiscence Therapy)」(用過去記憶喚起情感連結)有衝突。Tom 在文章明文承認這個衝突。

    這個工具不解決具體問題,而是在其他工具給不了答案時,**回頭問:我用什麼 frame 在想這件事?** Handbook 是網狀的,在失智路上某些時刻會用上。

    場景 12:長輩 / 病人 / 嬰兒選營養品 — health-drinks

    health-drinks 是19 款醫療營養品 + 嬰幼兒配方 + 高蛋白補充品的並排比較工具(180-280ml 容量範圍)。**不是市售飲料**,是給病人 / 長輩 / 嬰兒喝的營養補充品(葡勝納 / 完膳 / 安素 / S-26 / 倍速益 / 康健等)。

    三重使用者

    • Tom 自家 — 失智媽媽吞嚥退化階段選低糖高蛋白配方
    • 藥師朋友 — 跟客戶解釋「葡勝納原味跟菁選香草」差別時要快速比成分
    • 藥局客戶 — 拿出手機看比較表自己挑(藥師沒空講)

    資料流:拍包裝 → AI 擷取 → 手填 drinks.js

    每加新飲品的流程:

    1. 藥局買回來拍包裝側標籤
    2. AI(Gemini / Claude)從圖片擷取營養成分
    3. **手填**到 `data/drinks.js`(brain memory `health-drinks-data-entry.md` 「拍標籤說『加進去』就全填,包含微量元素,不可自行省略」原則 — `feedback_nutrition_label_fulldata.md` lesson)
    4. UI 並排比熱量 / 糖 / 鈉 / 蛋白質 / 脂肪 / 維生素 / 礦物質

    monorepo 唯一 CDN 例外:health-drinks 較早建置仍用 Chart.js + Google Fonts CDN(Noto Sans TC)。圖表呈現用 Chart.js 4,字體用 Noto Sans TC。違反 monorepo 0 CDN 強制規定 —— 計畫之後遷移成 inline,但目前留著作為「歷史包袱」example。新工具不准走這條路。

    何時不該用工具,直接找專業

    工具看到「預期外的 pattern」就停用,改找專業。具體訊號:

    訊號 該找誰 為什麼
    突然拒食 ≥ 3 天 神經科 / 急診 可能是 UTI / 吞嚥退化 / 譫妄,不是「沒胃口」
    行為驟變 24 小時內 急診先排除 UTI 中老年 UTI 常表現為譫妄不是發燒
    跌倒 119 / 急診 頭部撞擊、髖關節骨折看似輕微會延遲爆發
    照顧者撐不住 1925 安心專線 / 共照中心個管師 Burnout / 預期性悲傷有專業 evidence-based 支援
    小孩發燒 ≥ 39°C 連 2 天 兒科 / 急診 tools 不會幫你看川崎 / 流感 / 腸病毒

    原則:工具是 baseline 操作,異常事件外溢就 escalate。不要用「我家工具上看了沒問題」當不去看醫生的理由。

    工具互鎖:資料閉環怎麼運作

    14 個工具裡不是每個都獨立。失智照護核心 4 個工具串成 daily/weekly 閉環:

    每天:
    [居服員 / 我] 寫白板 → 拍照傳 Telegram
        ↓
    [白板 OCR Bot] Gemini OCR + confirm
        ↓
    [iDempiere Z_momSystem] 每天一筆紀錄
    
    每月:
    [mom-clinic-companion] 拉一個月紀錄
        ↓
    產出回診清單 → 神經科看具體 evidence
        ↓
    醫師調藥決定寫回 iDempiere
    
    每月共照中心月聚:
    [care-handbook 援手系統] 個管師有資料看可以諮詢
        ↓
    社工 / 物理治療 介入決定

    關鍵設計:資料只進 iDempiere 一次,各工具讀同一個 source。不是 OCR Bot 一個資料庫、mom-clinic 另一個資料庫 — 那會分裂。所有寫入收斂到 iDempiere,所有讀取從 iDempiere 出來。

    iDempiere 是台灣 open source ERP,我把它當 PHR (Personal Health Record) 用。對家庭規模 overkill,但有 Z_table 自訂 + REST API + audit log 的 enterprise 級資料管理,這條主線運轉半年沒掉資料。

    不是處方,是 invitation

    這套工具不是處方。每家狀況不同 — 有的家有外籍看護工、有的家三代同堂家屬 backup 充足、有的家在偏鄉服務不完整。我家是「白天 solo + 配偶藥師有正職 + 兒女幼小 + 父母 secondary 經驗 15 年」這個極窄 niche,所以工具 design 偏向「降低 solo 啟動 friction」。

    如果你家狀況跟我接近,這套工具開箱可用;不接近,把它當「一個照護者怎麼設計自家工具」的 reference,fork 改成你家用的。原始碼在 GitHub,部署在 tm731531.github.io/dementia-care

    有相關問題歡迎在 blog 留言 — 工具不主動推,但方法 / 經驗 / 踩過的坑歡迎交流。