最近開始試著使用 CLI/TUI 的 LLM Agent 工具，選擇了 crush。
然後想把之前在 Local Deep Research 的使用習慣轉移過來，原因是 Local Deep Research 彈性略差，加上它的主要賣點之一是研究內容在伺服器端是加密的，但是這個設計造成 UX 上的缺陷：光是開啟清單頁面都需要運行解密而造成網頁會花不少時間在等待解密完成。
把 Local Deep Research 的提示詞抽出來隨便搓了一個 Skill:
https://github.com/FlySkyPie/simple-research-skills
但是發現了一個問題：
恩？為什麼我架的 SearXNG 看起來都搜不到東西？是 MCP 壞掉了嗎？
原來是被搜尋引擎擋了。
但是 crush 的內建工具為什麼可以運作？
翻了一下程式碼發現它是使用鴨鴨 (DuckDuckGo)：
有趣的是，當時 DuckDuckGo 算是第一個在我的 SearXNG 會擋機器人的搜尋引擎，因此它很早之前就被我從 SearXNG 的設定中停用了。
Biomes 的 shared 模組中定義了很多資料，當中不少檔案是超過 500 行的，並且不少有循環仰賴：
export const zBiscuitAttributeAssignment = z.lazy(
memoize(() =>
z.discriminatedUnion("kind", [
zParentTrayAssignment,
zConstantAssignment,
zReferenceAssignment,
zUnassignment,
zInferenceAssignment,
])
)
) as ZodType<BiscuitAttributeAssignment>;
export const zParentTrayAssignment = z.object({
kind: z.literal("parentTray"),
to: zBiscuitAttributeAssignment,
});
為了對仰賴關係有更細的理解，避免太多東西被 import，而把定義資料檔案拆成獨立的檔案，然而循環仰賴會造成 runtime error。
加上很多型別是用 Zod 的 schema 本身進行推論的：
export const zShotMetadata = z.object({
coordinates: zVec3f,
cameraLookAt: zVec3f.optional(),
shotInMinigameId: zBiomesId.optional(),
shotInMinigameInstanceId: zBiomesId.optional(),
shotInMinigameType: zMinigameType.optional(),
});
export type ShotMetadata = z.infer<typeof zShotMetadata>;
造成仰賴 type 的時候依然會 import 到實作，加劇了循環仰賴的問題。
五月份的時候有 Biomes 的內部人員修復了素材包缺失的問題，原本該專案自動化腳本會去 GCP 下載預先打包的素材包，但是該資源已經無法被訪問，修復的內容就是在 GitHub 上 release 一份，並且更新自動化腳本。
在這之前我是以由下而上，從仰賴鏈末端的基本元件慢慢重構與編譯往上組合的。既然原始團隊的人已經做了一些修復並且聲稱自己測試過可以運行，我就試著由上而下跑跑看吧。
Biomes 的程式碼可以看到不少名為 Bob 的東西：
├── deploy/
│ └── k8/
│ └── services/
│ └── bob.yaml
├── Dockerfile.bob
├── scripts/
│ └── deploy_bob.sh
└── src/
└── server/
└── bob/
因為最後是以 Docker 的形式存在，K8s 編排內也有，我之前一直以為這是遊戲本體的內部代號，最近仔細看了一下實作才知道它是手搓的自動化程式，被擬人化為一個名為 Bob 的 Agent。
這個程式在做的事情就是輪詢 Git、運行 Bazel 與 Docker (DnD)、推送映像檔、觸發 Discord 通知...等。給人一種「不知道 CI/CD 為何物的前端仔用 Typescript 搓出來的東西」的感覺。
程式運行後會被 GCP/Firebase 的鑑權擋住，仔細查看程式碼會發現實作高度耦合 BigQuery、Firestore、GCP Storage、App Engine...等 Google 的服務。
幾乎可以想見該團隊被微軟體系的 OpenAI 收購之後會有什麼樣的衝擊。
調查 Dockerfile.bob 和 Dockerfile.biomes 的建構流程會發現明顯有設計 Next.js 和 Webpack 的建置流程。
但是調查 K8s 設定會看到諸如這樣的內容：
containers:
- image: us-central1-docker.pkg.dev/zones-cloud/b/biomes:devin-deploy-2
name: biomes
args:
- '-r'
- ts-node/register
- src/server/gaia_v2/main.ts
- '--bikkieCacheMode'
- redis
- '--biscuitMode'
- redis2
- '--chatApiMode'
- redis
- '--firehoseMode'
- redis
- '--serverCacheMode'
- redis
- '--storageMode'
- firestore
- '--worldApiMode'
- hfc-hybrid
- '--simulations'
- restoration
- lifetime
- ore_growth
所有微服務都是不經過建置，直接用 Typescript 運行的。由此可知程式碼內部有嚴重的割裂，不同時期的進入點同 時存在，可能還有不少類似的廢棄程式碼存在。
由上而下大概是走不通的路線，因為必須要建立完整的 GCP 專案以及完整的 K8s 服務簇才有可能把程式跑起來，跟 GCP 的仰賴又有嚴重耦合，很難透過簡單的重構抽換成其他替代微服務。
最近在學習 OpenBMC，於是爬了一下它的歷史，有點意外跟傳說中的 Gentoo 扯上關係。年份僅供參考，只是用來做相對時間順序的比較之用。
(其他補充野史)
有些人可能會困惑為什麼我要特別提及 Linux From Scratch 跟 Gentoo 兩個跟 OpenBMC 沒有直接關聯的東西。
大部分人使用應用程式都是直接從某個地方下載執行檔然後使用，也就是預建置 (pre-build) 二進制檔案，Linux 的大部份發行版也是如此，然而 Open source 的圈子內有一種概念：
我沒看到原始碼，我不放心。
所以 Gentoo 的邏輯就是「所有東西都從原始碼編譯的 Linux 發行版」。
Linux From Scratch 定位則比較像是教科書，讓人更了解如何自己親手操作獲得 Linux，但是歷史悠久，因此後進的 Linux 使用者即便沒有親自動手做一遍也會有所耳聞。
所以「從 source 編譯 Linux」這件事情對我而言具有神聖的色彩，感覺是只有真正的太古神獸或是大佬才知道的事情。
然而入職的第一周，「恩？你說我剛剛已經從頭編譯一個 Linux 了？」。
另外，如果仔細觀察，會發現每一個企劃發起的時間都比它實際使用的工具來得近代；換句話說，這些計畫都沒有自行開發一套解決方案，而是直接使用已經存在的解決方案進行統整。
雖然經常覺得自己站在巨人的肩膀上，但是即便是這些巨人似乎也是站在其他巨人的肩膀上呢。
最近在寫一些小工具，涉及比較敏感的資料，所以不能直接用雲端的 LLM，要用地端/本地的 LLM 處理。過程中遇到一點問題想記錄下來，但是背景有點複雜，建議先閱讀前一篇文章：
預計開發的小工具是這樣的：
YYYY/MM/YYYY-MM-DD_{STORENAME}_{AMOUNT}NTD.pdf)並刪除原始檔案。不過隨著佈署 LLM 和 OCR 的過程中，謎團越來越多，我只好中止開發先來搞清楚究竟是怎麼回事。
因為我的對外網路是（有限流方案） 4G 無線網路，除了下載速度很感人以外，根據經驗從 Docker Hub 拉取超過 1 GB 的映像檔很高機率會失敗，像這樣：
$ podman pull ghcr.io/ggml-org/llama.cpp:full-vulkan-b9776
Trying to pull ghcr.io/ggml-org/llama.cpp:full-vulkan-b9776...
Getting image source signatures
Copying blob 4f4fb700ef54 skipped: already exists
Copying blob d1f56e4c7f2f skipped: already exists
Copying blob d4a637e5a2c3 [=========>----------------------------] 130.0MiB / 497.0MiB | 458.8 KiB/s
Copying blob 534ac9e261fe done |
Copying blob d2bfdcbbb65a done |
Copying blob a92b05b64059 [===================>------------------] 120.0MiB / 223.3MiB | 105.4 KiB/s
Copying blob 81e2f2053c8f skipped: already exists
Error: copying system image from manifest list: writing blob: storing blob to file "/var/tmp/container_images_storage936046123/2": happened during read: Digest did not match, expected sha256:a92b05b640591907c483d83fccf883b9f5d2b4d90369cd44cca5be58bbf7ea8e, got sha256:38656550ac584269f4bff1c74b238fea1d77c997d8439b484f75d803e7952012
原本使用 llama.cpp 的原因之一就是它比 ollama 瘦很多，很適合作為微服務使用，不過最近觀察到它越來越胖了：
$ podman images | grep llama.cpp
ghcr.io/ggml-org/llama.cpp server-vulkan-b9755 40547717e769 2 days ago 905 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b9737 274d563f216f 3 days ago 905 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b9102 74d080b604c3 6 weeks ago 538 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b8496 33a2ea3a7ef4 3 months ago 530 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b8248 954707a036be 3 months ago 502 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b8234 4af8b883a4d8 3 months ago 501 MB
ghcr.io/ggml-org/llama.cpp server-vulkan-b7129 35763dc5caad 7 months ago 428 MB
所以我有點擔心它會在不久的將來觸及到我的網路環境極限。無線路由器的升級計畫以及調高無線網路資費方案已經排入待辦事項。
想說現在是 2026 年了，試著用用看性價比評價很高的 Gemma 4 看看，但是即便是 Q8_0 量化的 gemma-4-E2B-it 也有 5GB 左右。
後來試著抓了 ggml-org/SmolLM3-3B-GGUF 來用，Q4_K_M 只要 2GB 左右，但是沒開 thinking 的話會笨笨的，連「strawberry 有幾個 r」都會回答錯...
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "To find the number of r's in the word \"strawberry,\" let's break it down letter by letter:\n\ns-t-r-a-w-b-e-r-r-y\n\nNow, we can look for the letter 'r':\n\n1. The first 'r' appears at the third position.\n2. The second 'r' appears at the eighth position.\n\nSo, there are two 'r's in the word \"strawberry.\""
}
}
],
"created": 1782281452,
"model": "SmolLM3-Q4_K_M.gguf",
"system_fingerprint": "b8234-213c4a0b8",
"object": "chat.completion",
"usage": {
"completion_tokens": 89,
"prompt_tokens": 82,
"total_tokens": 171
},
"id": "chatcmpl-dQKDcL7Torw1Y2hGtyKJr9OtD7L0lpHM",
"timings": {
"cache_n": 81,
"prompt_n": 1,
"prompt_ms": 98.934,
"prompt_per_token_ms": 98.934,
"prompt_per_second": 10.10774860007682,
"predicted_n": 89,
"predicted_ms": 6249.039,
"predicted_per_token_ms": 70.2139213483146,
"predicted_per_second": 14.242189879115813
}
}
開了 reasoning 可以改善這個問題，不過因為輸出的 token 量變多，所以反應時間會變長：
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "The word **\"strawberry\"** contains **3** instances of the letter **\"r\"**. \n\nBreaking it down:\n- **Position 3**: \"R\"\n- **Position 8**: \"R\"\n- **Position 9**: \"R\"\n\nSo the total number of r's is **3**. \n\n**Answer:** 3",
"reasoning_content": "\nOkay, let me try to figure out how many times the letter 'r' appears in the word \"strawberry.\" First, I need to write out the word and look at each letter one by one. Let me start by spelling it out: S-T-R-A-W-B-E-R-R-Y. \n\nAlright, starting from the beginning, the first letter is 'S'. Not an 'r'. Next is 'T', still not 'r'. Then the third letter is 'R'. So that's one 'r'. Let me keep going. After the 'R', we have 'A', then 'W', 'B', 'E', and the next letter is another 'R'. So that's the second 'r'. Then there's another 'R' right after that, making it the third 'r'. \n\nLet me double-check. The word is S-T-R-A-W-B-E-R-R-Y. Breaking it down:\n\n1. S\n2. T\n3. R\n4. A\n5. W\n6. B\n7. E\n8. R\n9. R\n10. Y\n\nSo positions 3, 8, and 9 are 'R's. That would make three 'r's in total. Wait, is that right? Let me count again. Starting from the first letter:\n\n1. S\n2. T\n3. R (1)\n4. A\n5. W\n6. B\n7. E\n8. R (2)\n9. R (3)\n10. Y\n\nYes, that's three 'r's. Did I miss any? Let me visualize the word again. \"Strawberry\" – maybe there's a different way to spell it? No, the correct spelling is S-T-R-A-W-B-E-R-R-Y. The 'r' after the 'w' and the two after the 'e' make three. I don't see any other 'r's in there. So the answer should be three.\n"
}
}
],
"created": 1782354762,
"model": "SmolLM3-Q4_K_M.gguf",
"system_fingerprint": "b8496-312d870a8",
"object": "chat.completion",
"usage": {
"completion_tokens": 491,
"prompt_tokens": 262,
"total_tokens": 753,
"prompt_tokens_details": {
"cached_tokens": 0
}
},
"id": "chatcmpl-J02gP2dc5X4IxzJcadTUDxZAOZWpGnvb",
"timings": {
"cache_n": 0,
"prompt_n": 262,
"prompt_ms": 1341.488,
"prompt_per_token_ms": 5.12018320610687,
"prompt_per_second": 195.30551149171666,
"predicted_n": 491,
"predicted_ms": 42248.081,
"predicted_per_token_ms": 86.04497148676171,
"predicted_per_second": 11.621829640025545
}
}
要留意，根據官方文件說明，要使用 thinking/reasoning 必須給予 --jinja 參數1，
但是較舊的 llama.cpp 似乎不支援這個參數，如：ghcr.io/ggml-org/llama.cpp:server-vulkan-b8248，關於 llama.cpp 版本的坑後面還會提到更多。
大約在 b8496 (2026-04-24) 和 b9102 (2026-05-11) 兩個版本之間，llama.cpp 從 Hugging Face 上拉取模型的行為發生了變化，具體是哪個版本我懶得調查了。
當使用這樣的參數時：
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
- LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf
b8496 以前的版本會使用像這樣的路徑下載：
/ggml-org/SmolLM3-3B-GGUF/resolve/main/SmolLM3-Q4_K_M.gguf
b9102 以後則是會先去呼叫這個路徑：
/api/models/ggml-org/SmolLM3-3B-GGUF/refs
而 /refs 這個 API 在我使用的鏡像方案 Olah 並未實做。
在 Python 的體系中，應用程式和 LLM 模型之間還夾了 SDK、Hugging Face Transform、PyTorch，當某人發布了新的 LLM，它的架構會在 SDK 那層會處理。但是 llama.cpp 只有 C++ 實做和 GGUF 模型，所有架構都必須在 llama.cpp 的 C++ 實作內 hard coding。
這造成了 llama.cpp 支援模型的能力高度被 llama.cpp 的更新進度榜定，例如在 b8248 中試圖運行 Gemma 4的話會得到：
llm-1 | llama_model_load: error loading model: error loading model architecture: unknown model architecture: 'gemma4'
llm-1 | llama_model_load_from_file_impl: failed to load model
llm-1 | common_init_from_params: failed to load model '/root/.cache/llama.cpp/unsloth_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q4_K_M.gguf'
llm-1 | srv load_model: failed to load model, '/root/.cache/llama.cpp/unsloth_gemma-4-E2B-it-GGUF_gemma-4-E2B-it-Q4_K_M.gguf'
llm-1 | srv operator(): operator(): cleaning up before exit...
llm-1 | main: exiting due to model loading error
llm-1 exited with code 0
b8496 以下的版本使用這個配置的話可以正常下載模型：
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
- LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf
但是當需要使用像 PaddlePaddle/PaddleOCR-VL-1.5 這樣的模型時，下載一個檔案是不夠的，需要多個檔案才能讓模型在 llama.cpp 內運作：
PaddleOCR-VL-1.5.ggufPaddleOCR-VL-1.5-mmproj.ggufchat_template.jinja這是因為它屬於多模態模型，而不是單純的 LLM，（應該）可以使用以下參數來來下載多個檔案：
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF:Q4_K_M
但是會出現以下錯誤：
error from HF API (http://huggingface.mirrors.solid.arachne/v2/ggml-org/SmolLM3-3B-GGUF/manifests/Q4_K_M), response code: 404, data: {"error":"Sorry, we can't find the page you are looking for."}
因為這是 Docker Registry API，而 Olah 沒有實作。
恩？明明是從 Hugging Face 下載模型，怎麼連 Docker Registry API 都來參一腳了？
稍微搜尋了一下發現這個東西：
https://hub.docker.com/r/ai/gemma4
而且它不能直接用 Podman 下載：
$ podman pull docker.io/ai/gemma4:E2B
Trying to pull docker.io/ai/gemma4:E2B...
Error: parsing image configuration: unsupported image-specific operation on artifact with type "application/vnd.cncf.model.manifest.v1+json"
原因是這是特殊的 OCI 封裝格式2，據我所知是因為它沒有 roofs 的資訊，必須使用像這樣的指令拉取：
podman unshare skopeo copy \
--insecure-policy \
docker://harbor.mirrors.liquid.arachne/docker-hub-proxy/ai/gemma4:E2B \
dir:./
簡單來說，Hugging Face API 目前雖然作為實質產業標準，但是 CNCF 有意對「怎麼佈署與傳輸類神經模型檔案」訂出標準。
llama.cpp 也支援該界面：
| Argument | Explanation |
|---|---|
-dr, --docker-repo [<repo>/]<model>[:quant] | Docker Hub model repository. repo is optional, default to ai/. quant is optional, default to :latest. example: gemma3 (default: unused) (env: LLAMA_ARG_DOCKER_REPO) |
如果這個方案可以普及，我的 Olah 就可以退役了，轉而使用更可靠的 Harbor。不過目前只有 Docker Hub 在使用，而 Docker Hub 的流量限制本身就是害我拉大檔案拉不下來的因素之一。
[ocr] | srv params_from_: Chat format: peg-native
[ocr] | slot get_availabl: id 3 | task -1 | selected slot by LRU, t_last = -1
[ocr] | slot launch_slot_: id 3 | task -1 | sampler chain: logits -> ?penalties -> ?dry -> ?top-n-sigma -> top-k -> ?typical -> top-p -> min-p -> ?xtc -> temp-ext -> dist
[ocr] | slot launch_slot_: id 3 | task 0 | processing task, is_child = 0
[ocr] | slot update_slots: id 3 | task 0 | new prompt, n_ctx_slot = 4096, n_keep = 0, task.n_tokens = 1179
[ocr] | slot update_slots: id 3 | task 0 | n_tokens = 0, memory_seq_rm [0, end)
[ocr] | slot update_slots: id 3 | task 0 | prompt processing progress, n_tokens = 5, batch.n_tokens = 5, progress = 0.004241
[ocr] | slot update_slots: id 3 | task 0 | n_tokens = 5, memory_seq_rm [5, end)
[ocr] | srv process_chun: processing image...
[ocr] | encoding image slice...
[ocr] | image slice encoded in 21944 ms
[ocr] | decoding image batch 1/5, n_tokens_batch = 256
[ocr] | image decoded (batch 1/5) in 197 ms
[ocr] | decoding image batch 2/5, n_tokens_batch = 256
[ocr] | image decoded (batch 2/5) in 576 ms
[ocr] | decoding image batch 3/5, n_tokens_batch = 256
[ocr] | image decoded (batch 3/5) in 335 ms
[ocr] | decoding image batch 4/5, n_tokens_batch = 256
[ocr] | image decoded (batch 4/5) in 412 ms
[ocr] | decoding image batch 5/5, n_tokens_batch = 142
[ocr] | image decoded (batch 5/5) in 428 ms
[ocr] | srv process_chun: image processed in 23892 ms
[ocr] | slot init_sampler: id 3 | task 0 | init sampler, took 0.01 ms, tokens: text = 13, total = 1179
[ocr] | slot update_slots: id 3 | task 0 | prompt processing done, n_tokens = 1179, batch.n_tokens = 8
[ocr] | slot print_timing: id 3 | task 0 |
[ocr] | prompt eval time = 24747.40 ms / 1179 tokens ( 20.99 ms per token, 47.64 tokens per second)
[ocr] | eval time = 93429.63 ms / 2917 tokens ( 32.03 ms per token, 31.22 tokens per second)
[ocr] | total time = 118177.03 ms / 4096 tokens
[ocr] | slot release: id 3 | task 0 | stop processing: n_tokens = 4095, truncated = 1
[ocr] | srv update_slots: all slots are idle
[ocr] | srv stop: cancel task, id_task = 0
[ocr] | srv update_slots: all slots are idle
[ocr] | srv operator(): got exception: {"error":{"code":500,"message":"Failed to parse input at pos 0: TQ；的既然既然 既然既然 称即作四作作作�는戒инин 교 교浦に��집집집 அமை作 (ӀэӀэӀэӀэ的的��ده层透明透明ண்டுண்டு羡羡 the the\n\n\n裔5�(，，，�輒放放��貲支����ver.جی顯顯由於宇丁ine 的有เพ阵年是 ilesuணணஸஸ�興�����。那那那ӀэӀэӀэ蚚��图的疾 ..,то角角���ололол���浆â�，，，的的��，，，，的的�，，場从shshdd�，0，，贺的的的的的的\n\n的的200,,,，，，禹.\nmff..，只有在y���转 .，，，争www-----�� iew徒��\n\n\n\n\nimetையில்ையில்ையில்ையில்友ssss ,,,,,,，，，的的���，，的 war and and and and andsw81生\n({{\\市ne季季食生生生生�清清��在在评ans芽lan\n\n\n\n ���，，，的的的��，，，，,���，，，，,�����-,((���ek of 的的的���，，，00,，，的的的失失失���，，的的的���，，，,,的��，，，99 简称oofCCèге�顯顯韓韓韓韓韓友���的\n�夫夫��与非与非与非与非————��ataadyofofofofof涓,,,niluoppnnnn..，，，，���，，，的的成，ansuu�，，，，，，��，，，\n00ofn�.，，，，ிறிறிறிறிற\n1ไ\n\n\n\n\n\n r.�,,,评\n\n\nbu-..-.-首位ofuns党 from\n评gg\n\n\nss\n\n\n\n\n W I I \n\n\n \n,.\n\n in in in in in in in in in e sl el�� \n\n\n1 ไ\n�.，，，，的��否o�----08��，，\n\n\n\n\n\n1情 \n 妇\n�,，，，，，��，，， or 1 and and and and\n\n\nlot\nر \n\n\n۹ \n\n\n\n\n\n，，，的���，，，，回归--..，\n\n\n �,，，的的的�蛛��-- in in\n\n fa以下的 \n ofans\n F F E E E E连连连新新 F的的的的的的的的 W Group\\.��âè以下的以下的以下的以下的类和�� स्�}}) ,,，，，的wy��域intLLLLLau , 江江\n\n\n�，，，的的的�� of of of欢欢欢欢G� of of������ 相ǎ� ，，，的的的 I 的的 of\n\n\n\n\nl ,------1111 from,,,, of江,,,,,�u\n\n\n\n\n的的的的1���，，的的的的的��艺� (\n Ю�\n of of\n\n\n\n\nзна�\n\n\n\n\n\n\n W资�， Sc6\n\n\n\n的 मा \n\n\n\n\n\n\nssss的�\n江66666是�和在在在在在在在在 …. or or和111在�n�.., or\n\n决定场场场场生, (\n\n\n\n\n\n 的的�� G G G G,天天天6的的的的的 ( (学习方法omuuu\n11111111���，९和\n\n\n\n\n\n S S C C C C C C C C C C۳\n\n\n\n\n\n\n\n\n\ncc1��，，，，的的的�,的的的的�的的的的的的的的的的的的在在在在恢复正常\n\n1111111��，，，，，的的�不可oooooââ�\n�\n .222，，，行文文文生生�文\n��连 请\n\n\n\n\n\n在在在�\n\n\n\n\n\n (�\n�大有有有的的的的���，，，，，的的的���，，，，的的法�\n\n\n\n\n\n的�� \n\n\n\n\n\n\n\n\n\\\\\\\\\\\\��，�阵战委天天天天内内非LL在在在在在在在在在在的\n\n的的的的的的的的的�غ行\n\n\n\n\n\n �����,�1nn0,，，，，的的的 R\n�清有的的的的的的的的的������，，， (\n境\n���\n\n\n C�\n\n and��的的的的的晙�\n\n掉\n\n\n\n\n\n C C C C C C C C C C C C C C C C C C C C C C C C C C C C政政政政政生、,\n天天�掉\n�\n6000,,，，，，的的���， Wh W\n G G G G C C C C C迁迁迁迁 of, ofลง�WW�WL��\nand暚\n\n\n非非 G Out Out Out未婚汲汲汲汲汲諾諾諾�\n\n\n\nC在在在在在 \n大大的\n\n领域的�\n�，，\n\n\n\n\n\n\n\n\n C C C C C C\n\n\n，,，，，\n\n\n\n\n\n\n\n��0,，，，，，��，，，，\n\n\n\n\n\naaaasssss\n�城amâéâââ以下的以下的以下的以下的法和类和 स् WIลงорт政政质质质�\n\nSکن�\n\n\n\n\nandR�.生生\n\n\n\n\n\n\ngauauorotimesotimesotimes.—.—.—諾諾諾諾諾â��,， and天天\n\n�0,，，，，，，\nธ� .,，，，，，的 of of of ofofofofofof灰灰灰\nand��0，\n\nandand�艺\n\n\n\n\nandR�生失失\n\n\n\n\n\n\n in in in in in in in in in in\n\n\n\n\n的的的的的在在在在在前前前前前在âi�n�,,,，资格\nธâl�.艺\n\n���000，，，\n\n\n\n\nธR .��财非非非非非非非非非\n生生\n\n��0,,，，，�ab99�ââ�，，，生生生生生城\n\n\n\n\n\n\naaaaaa C C C C C e e e e e e e评,\n\n\n\n\n\n\n\n6R政\n\n\n\n 함 함 함 함 of of of ofofofofofofofofer\n\nWGGGLL\n\n\n\nGâéâè以下的以下的以下的法和\n\n\nธ城城�开工� and���iideideideideideideararauâ\n\n\n\n\n\n\n\n在在在在在����，ans\n\n\n\nâââ以下的以下的以下的类和类和类和 Duranteवन\n\n\n\nââ\n\n\n\n\n0、生行\n�â�以下的以下的ons域域域000\n\n\n\n\n\n\n\n旧旧旧旧otimes���er掉\nâand and\n\n�âant and and,�行�ââân�,,，的�\n\n\n\n\naa000I的的的的的的的的的的的的的的的的���नानाना新新ererer低估低估汲汲汲汲\n\n\n\n\n\n\n C C C C C C C C C C C C C C���兽骏骏 함 함 함 함 함secsecsecsec骏骏骏 文\n�â�\n\n\n\n\n�R���\n\n\n\n跨跨跨跨��\n\n\n\naaaaaarerereotimes汲汲ना\n (院\n\n\n\n\n\n11111���\n\n�����\n\n\n\n\n\n\n中的的的的的�â�\n\n�\n\n�\n\n\n0���(\n\n\n\n\n\n\n\n\n\n\n\n\n\n在在在在在在在在在在的的的的��and�\n\n\n\n\n\n\nG新新在在在在在在在在在的1���RR2�，\n�\n\n\n\n\n\n\n\n\n ��，，，，，\n\n\n\n\n\n\n\n12��，，，，，的的的�\n\n\n\n\n\nG，，，，，\n\n(R�\n\n\n\n\n\n\n非非非非非icic,�âââ以下的以下的以下的以下的以下的类和类和� Durante\n�0，,，，，，���\n\n\n\n\n\n,1�\n\n\n\n\n���90，，，，的的的的�\n\n\n\n\n�RRRnnnnnnnRFnnn，，，，，，的的���，，，，，的�\n\n\n\n\n\n (RRR者\n\n\n\n\ng新在在在�\n\n\n\n\n\n\n\n在在�\n��111\n\nธ�大大的的的在龙\n\n\n\n\n\n (\n���有有有有境言go\nate\n\n\n\n\n\nL1111���，\n�\n�，\n\n�有\n�\n�要要要要nnnF在在在FF1��，，，，的的���，，，，�\n\n\n\n\n\n\n\n\n在在在在在在在在在在在在在在在在在在在在在1���，，，言言L�i�âââââ âand櫫��ââ�\n���âââ\n\n\n\n\nG，，，۹�艺艺艺����������城城�\n������������言境\n66��â��，\n\n�\n�艺�\n���，，，，，的����â\n\n�éâ以下的以下的以下的一向�\n\n\n�\n��\n�������������â��，，","type":"server_error"}}
[ocr] | srv log_server_r: done request: POST /v1/chat/completions 10.89.62.26 500
有的時候 PaddleOCR-VL-1.5-GGUF 會異常，原因未知。
這個參數不會下載到 /root/.cache/llama.cpp，而是直接放在 /app 之下：
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
- LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf
這個才會，volume 設定才有用：
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
- LLAMA_ARG_HF_FILE=SmolLM3-Q4_K_M.gguf
volumes:
- data:/root/.cache/llama.cpp
前面講的多模態檔案可以用以下配置解決：
services:
downloader:
image: docker.io/huggingface/downloader:0.17.3
entrypoint: ["sh", "-ec"]
command:
- |
echo "Download model... ";
huggingface-cli download "PaddlePaddle/PaddleOCR-VL-1.5-GGUF" \
--include "PaddleOCR-VL-1.5-mmproj.gguf" "PaddleOCR-VL-1.5.gguf" "chat_template.jinja" \
--cache-dir=/hf-cache \
--local-dir=/data/PaddleOCR-VL-1.5-GGUF \
--local-dir-use-symlinks=False
volumes:
- model-cache:/data
- hf-cache:/hf-cache
ocr:
image: ghcr.io/ggml-org/llama.cpp:server-vulkan-b8248
restart: always
devices:
- /dev/dri/:/dev/dri/
ports:
- 8080:8080
entrypoint: /app/llama-server
volumes:
- model-cache:/data
environment:
- LLAMA_ARG_MODEL=/data/PaddleOCR-VL-1.5-GGUF/PaddleOCR-VL-1.5.gguf
- LLAMA_ARG_MMPROJ=/data/PaddleOCR-VL-1.5-GGUF/PaddleOCR-VL-1.5-mmproj.gguf
- LLAMA_ARG_CHAT_TEMPLATE_FILE=/data/PaddleOCR-VL-1.5-GGUF/chat_template.jinja
- LLAMA_ARG_WEBUI=disabled
- LLAMA_ARG_N_GPU_LAYERS=all
- LLAMA_ARG_CTX_SIZE=20000
- LLAMA_ARG_TEMP=0
- LLAMA_ARG_JINJA=1
- LLAMA_ARG_FIT=off
depends_on:
downloader:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 10s
timeout: 20s
retries: 3
volumes:
model-cache:
hf-cache:
一個容器專門跑下載，另外一個容器專門運行模型。不過這個配置有兩個問題：
depends_on 的支援度不夠高因此不會按照預期的順序啟動容器。huggingface-cli 指令的方式，即便檔案已經存在它也不會自動忽略而是重新下載一次。ggml-org/SmolLM3-3B-GGUF · Hugging Face. https://huggingface.co/ggml-org/SmolLM3-3B-GGUF ↩
model-spec/docs/spec.md at main · modelpack/model-spec https://github.com/modelpack/model-spec/blob/main/docs/spec.md ↩
最近在寫一些小工具，涉及比較敏感的資料，所以不能直接用雲端的 LLM，要用地端/本地的 LLM 處理。不過過程中遇到一點問題，想留個紀錄，但是背景有點複雜，於是想說單獨寫一篇解釋一下我目前的各種技術決策。
TensorZero 已經於 2026-06-12 停止維護。
OpenAI-Compatible API 基本上實質產業標準了，不過僅限 LLM 體系，非 LLM 的模型（例如影像或音訊處理）生態比較複雜，沒辦法被這種 API 設計完全覆蓋了。
LLM 可觀測的用途是可以紀錄各種模型、Token 量、費時提示詞以及 reasoning（一般不會直接顯式在應用程式上）。當時選擇 TensorZero 的原因是相對於 Langfuse 和 LiteLLM 的組合更輕量，而且有故障的經驗（雖然事後得知是 ClickHouse 配置失誤的原因）。
模型端則是只使用開放權重的模型，避免供應商鎖定。
應用程式同樣使用 OpenAI-Compatible API 使用 LLM。
使用 llama.cpp 運行 LLM，因為它支援多種 GPU 後端（包含主流的 CUDA、ROCm、SYCL...），特別是其中的 Vulkan 可以避免供應商鎖定。其使用的 GGUF 檔案則是針對量化的支援度很高，使用量化模型在該生態系可以說是預設行為，生態系中的模型大多經過量化，量化後的模型較小，可以節省傳輸流量以及運行時的 VRAM 消耗。同時官方提供可以開箱即用的預建置 OCI (Open Container Initiative) 映像檔，對雲原生環境十分親和。
使用 Podman Compose 運行 OCI 容器。使用 Podman 是因為想要試著脫離 Docker 的體系，並且嘗試 Rootless/Daemonless 的方案。Podman 生態系的 Dokcer Compose 對標容器編排方案是 Quadlet；一個 systemd 風味的方案，但是這樣做會偏離主流開發者太遠，所以我使用 Podman Compose 來繼續使用 docker-compose.yaml。
我的 homelab 對外網路是 4G 無線路由器加上方案有被限流，所以大部分涉及「套件下載」的東西我都有架設本地鏡像/快取來節省流量，包含：apt、npm、pypi、OCI、Hugging Face。同時把快取的職責甩給 homelab，工作電腦就可以經常清掉暫時用不到的快取，有必要再直接從 homelab 拉下來用。
如此一來就可以在本地快速建立一個 LLM 實例供開發測試使用：
services:
llm:
image: ghcr.io/ggml-org/llama.cpp:server-vulkan-b8496
restart: always
devices:
- /dev/dri/:/dev/dri/
ports:
- 8080:8080
entrypoint: /app/llama-server
environment:
- LLAMA_ARG_HF_REPO=ggml-org/SmolLM3-3B-GGUF
- LLAMA_ARG_MODEL=SmolLM3-Q4_K_M.gguf
- LLAMA_ARG_WEBUI=disabled
- LLAMA_ARG_N_GPU_LAYERS=all
- LLAMA_ARG_CTX_SIZE=20000
- LLAMA_ARG_TEMP=0
- HF_ENDPOINT=http://huggingface.mirrors.solid.arachne
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 10s
timeout: 20s
retries: 3
問題的部份下一篇文章再提。
先講結論，我把核心邏輯的實做跟測試案例都搬到 Python 3.12 去了，程式碼在此：
https://github.com/FlySkyPie/tiddlyrag-poc/tree/poc/type-e
不過 HTTP API 的實作就沒繼續了，後面會說明原因。
大方向上，在遵守 TiddlyWiki 社群共識的模型與 API，製作一個兼容的 API 伺服器，不只作為 TiddlyRAG 的微服務組件，更能回饋 TiddlyWiki 社群。拆成兩個階段：
第一階段的細節，使用乾淨架構：
typing.Protocol 抽象 TiddlyWeb 的模型方法如此設計的原因是 TiddlyWeb 的實做缺乏現代開發的邊界感，實作往往有高度的耦合性，很難直接切割，重構策略：
Legacy_Model = 缺血模型 + 界面 + Infrastructure 實作
Legacy_Test(Infrastructure 實作)
盡可能保持原始的界面，來重複使用單元測試，確保複製原始的業務邏輯。
整個過程會是 Strangler Fig Pattern：
過程中可以慢慢把舊的領域模型與業務邏輯轉譯成現代軟體的建模方式（Service, Repository...）。
這邊解釋一下為什麼要把原本的充血模型分解掉：
Legacy_Model = 缺血模型 + 界面 + Infrastructure 實作
Legacy_Test(Infrastructure 實作)
因為在現代後端，Query 類的問題幾乎都交由資料庫進行優化，而從資料庫檢索出來的東西也就只有資料，沒有方法，所以當模型仰賴資料庫進行持久化時，最好不要假設有太多方法的存在。
除此之外，遷移過程我還進行了一些修改，確保程式碼符合現代風格，或是為過度到現代風格做準備。
TiddlyWeb 的大部分實做都是函式，並且透過 environ 來傳遞大部分資訊，只有少部份的邏輯有封裝成物件。這似乎是 CGI (Common Gateway Interface)/WSGI 延續化來的風格。
CGI 時期的 web server 實作其實是一個執行檔，仰賴環境變數與 STDIO 與 parent process 溝通。parent process 是真正對外開埠的程式，在收到 request 之後把 URI 轉換成環境變數去呼叫 CGI 程式，再把拿到的字串作為 response 返回。
透過將原始實做封裝到物件內，我就可以將方法抽離成 Protocol，並且透過建構子解偶對其他函式的仰賴，之後就能清楚的的知道整個仰賴鏈，舉例來說這是重構後測試程式的片段：
specialbag_mock = MagicMock(spec=SpecialBagInterface)
helper = TextSerialization(specialbag_mock)
serializer = SerializationFacade(helper)
store_helper = MemTextStoreHelper(serializer)
store = StoreFacade(store_helper)
select_filter = SelectFilter(store)
sort_filter = SortFilter(store)
filter_facade = FilterFacade(select_filter, sort_filter)
resolver = OverlayResolver(filter_facade)
TiddlyWeb 本身有使用 OOP 的實作都是 Facade 模式，並且有這幾個：
物件對外是用像這樣的語法被使用：
serializer = Serializer('json')
內部則是使用像這樣的語法動態載入：
imported_module = __import__('tiddlyweb.serializations.%s'
% self.engine, {}, {}, ['Serialization'])
一股 Javascript 弱型別特性語言的 require() 味撲鼻而來...
如同你在前面測試程式碼看到的，這的部份我也是用 ID (Dependency Injection) 處理掉了。
另外一個部份 TiddlyWeb 也有使用類似於 Facade 模式的東西，雖然沒有建立 class：
先建立規則表：
FILTER_PARSERS = {
'select': select_parse,
'sort': sort_parse,
'limit': limit_parse,
}
然後根據輸入的 filter 規則視情況選擇具體的解析實做
filters = []
leftovers = []
for string in strings:
query = parse_qs(string)
try:
key, value = list(query.items())[0]
# We need to adapt to different types from the
# query_string. It changes per Python version,
# and per store (because of Python version).
# Sometimes we will already be unicode here,
# sometimes not.
try:
argument = unicode(value[0], 'UTF-8')
except TypeError:
argument = value[0]
func = FILTER_PARSERS[key](argument)
filters.append((func, (key, argument), environ))
except(KeyError, IndexError, ValueError):
leftovers.append(string)
leftovers = '&'.join(leftovers)
return filters, leftovers
解明 Recipe-Bag 的模型邏輯算是調查的重點之一，在 TiddlyWeb 中是被放在名為 control.py 的檔案中，因為它需要從 GET /recipes/{recipe_name:segment}/tiddlers[.{format}] 這樣的路徑中挑選真正的 tiddler。
但是這會和現代 MCV 架構中的 Controller 撞名，於是我把相關邏輯風裝在名為 OverlayResolver 的物件內。
在遷移完核心邏輯之後，就是遷移相關的測試案例，整個過程就是不斷的重複這個步驟：
commit 4630d5c8e58e0531342b64bca8cf3a849d7b854c
Author: Wei Ji (FlySkyPie) <c445dj544@gmail.com>
Date: Sat Jun 6 20:24:31 2026 +0800
feat: adjust test
commit 86e77b44f8603b4fe47ec9e2195fb14987b79c9b
Author: Kilo Code v4.153.0 <deepseek+deepseek-v4-flash@openrouter.ai>
Date: Sat Jun 6 20:20:09 2026 +0800
test: refactoring test to match current project
commit db58f75f56c4aaa9c2f63ef2eebdb91c32d0d909
Author: Wei Ji (FlySkyPie) <c445dj544@gmail.com>
Date: Sat Jun 6 20:17:14 2026 +0800
chore: move test file from legacy
pytest 會直接 壞掉，因為有嚴重的語法錯誤。pytest 就會恢復功能，可以看到 PASSED 跟 FAILED一開始的測試案例我都白嫖 Gemini Flash，後面等到模式建立起來之後就用開放權重的模型跑了，提示詞不複雜：
Your task:
- Read `tiddlymicroweb/infrastructure/store/tests/test_tiddler_slash.py`
- Refactoring `tiddlymicroweb/infrastructure/entities/test_user.py` by following previous refactoring pattern.
一次重構的最終上下文大約為 40k 左右。
最終上下文是指最後一個步驟的 token 數，整個 ReAct 過程總用量要再乘以次數除以二。
另外補充，TiddlyWeb 的程式碼我是透過 Git Subtree 放進專案的，目的是為了保留歷史上下文，同時必要時 ReAct 可以回去檢視 Legacy code。
MemTextStoreHelperTiddlyWeb 原本只實做了 text，會直接把資料寫入檔案系統的 store 實做，並且所有測試都是整合測試，實例之間又有複雜的仰賴，對 store 進行 Mock 其實不切實際。
於是我使用 pyfilesystem2，保留界面與大部分內部實作邏輯，把寫入對象從系統的檔案系統改成記憶體虛擬出來的檔案系統。如此一來便可在最少修改的前提下讓原本的整合測試能夠更「單元」一點。
在 TiddlyWeb 中，關鍵的業務邏輯被分成了三個區塊：
然而這帶來了一 個問題，這在現代後端都是需要跟資料庫溝通的行為，通常被抽象化成 Repository。先不談 Overlay 和 Store 在現代架構下可以被合併成一體，問題在於 Filter。
Filter 存在的目的是提供類似 TiddlyWiki 的語法，但是目前實作都是在 Python 內進行的，如果想要保持兼容性，標準的解法是使用 DSL (Domain-specific language) 或 AST (Abstract syntax tree) 作為 Filter 語法和 SQL 的中介層，但是建構並維護這樣一個中介層的成本非常的高。
另外，因為測試案例都是整合測試，因此當軟體結構遷移到現代的抽象方式時(Service, Repository...)，這些測試都變得毫無用處。
簡言之，雖然我成功把核心的業務邏輯以及相關的測試案例重構到現代環境，因為建模的方式依然和現代模型之間存在巨大的鴻溝，實在很難在完整兼容的前提遷移到現代系統。
抽出 OpenAPI 模型，並在理解舊有實作和測試案例的前提下直接重新實作一個部份兼容的 API Server 可能是更好的選擇。
TiddlyRAG Dev Log - MWS API | 工程屍 FlyPie 的異想世界
在前一篇文章中，我提到了 MWS (MultiWikiServer) 時做了一個名為 Recipe-Bag 多對多模型，用來展現類似於 OverlayFS 的行為。
但是我依然不能百分之百確定這個模型的設計哲學以及正確的行為是什麼，舉例來說：
於是我計畫建構一個 ETL (Extract, Transform, and Load) 來處理這個問題：透過 GitHub API 拉出 Issue 和 Comment （討論紀錄）、進行翻譯、最後 輸出成方便我閱讀的 Markdown。
除了表面的目的以外還有其他考量：最近我在 104 看職缺的時候，發現一些關於 ETL 的職位會提到 Perfect 這類工具，於是我想這是一個嘗試新東西的機會。
雖然我也可以嘗試透過最近完成的 EC-BT (Entity Component Behavior Tree) 進行資料探勘，但是我依然需要對標準的 ETL Pipeline 有基本的認識才能避免重複發明輪子。
一開始我是試著搭建 Prefect 的環境，不過過程中我看到了這個：
這讓我的開源雷達亮紅燈。加上它的文件不是很清楚，我沒辦法一下子搞清楚誰是 Client？誰是 Server？誰是 Workder？
另外一點，這是 Luigi 的官方範例1：
class AggregateArtists(luigi.Task):
date_interval = luigi.DateIntervalParameter()
def output(self):
return luigi.LocalTarget("data/artist_streams_%s.tsv" % self.date_interval)
def requires(self):
return [Streams(date) for date in self.date_interval]
def run(self):
artist_count = defaultdict(int)
for input in self.input():
with input.open('r') as in_file:
for line in in_file:
timestamp, artist, track = line.strip().split()
artist_count[artist] += 1
with self.output().open('w') as out_file:
for artist, count in artist_count.iteritems():
print(artist, count, file=out_file)
它顯式的表明了一個 Task 的輸入與輸出，比較符合我對 ETL 的想像，畢竟是 ETL (Extract, Transform, and Load) 對吧？
反之 Prefect 的官方範例則是長這樣：
from prefect import flow, task
import httpx
@task(log_prints=True)
def get_stars(repo: str):
url = f"https://api.github.com/repos/{repo}"
count = httpx.get(url).json()["stargazers_count"]
print(f"{repo} has {count} stars!")
@flow(name="GitHub Stars")
def github_stars(repos: list[str]):
for repo in repos:
get_stars(repo)
# run the flow!
if __name__ == "__main__":
github_stars(["PrefectHQ/prefect"])
好，你定義了一個像是 Pipeline 的東西，但是你的 Load 勒？
另外，最近學習 NestJS 和 FastAPI 的經驗讓我對於 Prefect 的語法有一點防禦心理。FastAPI 高度仰賴 Dep 注入函式的方式建構，副作用就是專案的組織充滿可能性，造成程式碼很雜亂，反而是 NestJS 基於物件的結構直接隱式的決定了程式碼的位置以及如何在專案中組織。
看起來好像有點用... 但老實說，我覺得用一個簡單的 Makefile 就能搞定所有這些東西了。用這種工具的好處是什麼啊？
路易吉的確是受到 GNU make 的啟發（文章裡不同地方有提到），而且文章裡的微型範例並沒有展現它所有的功能。它跟 Spark 和 Hadoop 這樣的框架配合得很好，它支援開箱即用的不同資料儲存目標，你有錯誤報告、依賴關係圖視覺化等等。 2
這個算是我嘗試 Luigi 的原因之一，CMake 或 Bazel 這類本地建置工具長什麼樣子我心裡有底，所以我需要的是一個光譜在 CI/CD 或本地自動化工具以外的 ETL/Data Orchestration 工具來了解領域模型。
貼文有 11 年老，但是 Luigi 看起來還有在維護，UI 以現代眼光來看也不會太差。初試 Prefect 無果之後我便嘗試 Luigi，
然後沒遇到什麼問題就接著實作，最後把我的需求解決掉了。
先講結論，程式碼在此：
https://github.com/FlySkyPie/github-issue-simple-etl
它在 Luigi 的框架下運行了 ETL：
我用過 Jenkins 之類的 CI/CD，也用過 CMake 之類的本地自動化，這個所謂的 ETL 工具憑什麼自立一個名為 Data Orchestration 的領域？
我沒有完整的答案，但從快速瀏覽 的氣流教學 來看，最明顯的是它是一個自上而下的 DAG 規格，並手動建立節點之間的連接。
相比之下，Luigi 元素之間的連接是隱式的，而且是自下而上的。 3
注意，這裡的上下不是組件的基礎與抽象的上下，而是資料上游下游的上下。CI/CD 這種需要某種東西觸發 (Git Branch 更新)的 Pipeline 就是由上而下，而由下而上更長出現在本地自動化，比如 Makefile：
main: main.o sub.o
gcc main.o sub.o -o main
main.o: main.cpp
gcc main.cpp -c
sub.o: sub.cpp
gcc sub.cpp -c
clean:
rm -rf main.o sub.o
我想要 main 的時候，會觸發它的仰賴 main.o 和 sub.o 於是自動化工具一路找到最上游還沒進行的任務把事情做掉。這一事實會讓工具變成冪等性的，而這也是 Luigi 具備但是不屬於 CI/CD 核心的特性（某些 CI/CD 會透過 Artifact 優化 Pipeline，但是不是特別重視這個特性，它們比較在意產出 latest）。
令一方面 ETL 比起本地自動化更注重分散負載，即 CI/CD 常用的 Server-Worker 架構，ETL 則是缺乏「佈署」或「觸發」的概念，因此多了一個直接操作 Pipeline 的 Client。
不過我認為 ETL 最重要的特性之一是「動態 Pipeline」，不論是 CI/CD 還是本地自動化，參數通常是一開透過設定檔、平台變數或是環境變數決定的，然後 Pipeline 的「形狀」通常是固定的，然而以我的實作為例：
實際上我只定義了五種 Task：
運作後的 Pipeline 中的很多實際任務節點是根據 GitHub repo 下的 Issue 數量與號碼指定的，對於一個翻譯任務節點而言，它的設定如下：
class TranslateSingleIssue(Task):
target_repo: Parameter = Parameter(
description="The issues of GitHub Repo going to translate",
)
api_base: Parameter = Parameter(
description="API base url of OpenAI-Compatible API",
)
model_name: Parameter = Parameter(
description="model name of LLM",
)
language_name: Parameter = Parameter(
description="Target language of translation",
)
issue_number: IntParameter = IntParameter()
api_base、model_name 和 language_name 是可以在 .cfg 檔案設定的，但是 target_repo 和 issue_number 是它的下游指定的：
class GenerateSingleDocument(Task):
def requires(self):
return [
TranslateSingleIssue(
target_repo=self.target_repo, # type: ignore
issue_number=self.issue_number,
)
]
如此一來資料操作者可以輕易的設定全域變數或是指定某個下游任務的參數，它會自己「把訂單往上游傳」然後動態的根據不同的仰賴結構建構不同的 Pipeline。
在我閱讀了 111 個 Issue 後，我驚訝的發現討論大部份圍繞在 ACL (Access Control List) 上，Admin UI 的討論則是次之。
專案的 ACM (Access Control Model) 選擇使用 ACL 是缺陷這個我在前一篇文章就講過了。我沒講的是 Recipe-Bag 這種多對多模型如果要處理 AuthZ (Authorization) 最簡單可靠的方式就是引入 ReBAC (Relationship-based access control)。
好，他們正在錯誤的技術決策上打轉，然後又過度關注 UI，與此同時我還是沒有一個可靠的微服務組件可以使用，怎麼回事？說到底 Recipe-Bag 這個模型到底怎麼來的？
The bags and recipes model is a reference architecture for how tiddlers can be shared between multiple wikis. It was first introduced by TiddlyWeb in 2008.4
於是我回去翻了一下 tiddlyweb 的 Git 紀錄：
看起來是非常早期的 commit 的引入的設計，甚至還在 SVN 時期，我大概很難找到相關討論了，總之這麼模型甚至被 TiddlyWiki 的官方文件收錄了。
另外一個發現是它們在討論某種前後端同步或是後端渲染的機制，這對我而言就是「重新發明 Next.js」！這也解釋了為什麼 API 裡面會有這麼多奇怪的 RPC (Remote procedure call)。
最後讓我得出結論的是這個，MWS 的主要貢獻者說道：
Docker itself doesn't strike me as being very friendly to new users. I'm not sure how you mean we should support Docker Compose.5
如果一個後端專案的主力開發者無法正視 Docker 在現代生態系的意義，那這個專案可以丟進垃圾桶了。
tiddlyweb 用 repomix 打包只有 600 KiB 左右，反觀 MWS 則是 2 MiB，tiddlyweb 抽出來的 OpenAPI 也比較簡潔，沒有 ACL 或是「類 Nest.js」造成的臃腫。我決定把 tiddlyweb 作為 rewrite 對象而不是 MWS。
最近我意外得知，研究方法中除了定量分析以外，還有一種注重少量樣本與群體，更重視「故事」與「脈絡」的質性研究。這才意識到自己其實是對軟體專案進行質性研究呢。
Example – Top Artists — Luigi 3.8.1 documentation. https://luigi.readthedocs.io/en/stable/example_top_artists.html ↩
用 Luigi 在 Python 裡建資料管道 : r/Python. https://www.reddit.com/r/Python/comments/3rjkry/comment/cwppm86/?tl=zh-hant&utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button ↩
用 Luigi 在 Python 裡建資料管道 : r/Python. https://www.reddit.com/r/Python/comments/3rjkry/comment/cwppm86/?tl=zh-hant&utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button ↩
Bags and Recipes: TiddlyWiki v5.4.0 — a non-linear personal web notebook. https://tiddlywiki.com/static/Bags%2520and%2520Recipes.html ↩
Feature Request: Support installation and deployment using Docker Compose · Issue #122 · TiddlyWiki/MultiWikiServer. https://github.com/TiddlyWiki/MultiWikiServer/issues/122#issuecomment-3702946673 ↩
POC Type-A 探索了向量資料庫、嵌入模型並對外暴露 MCP (Model Context Protocol)：
POC Type-B 探索了 AsyncFuncAI/deepwiki-open 專案處理「如何把 Git Repo 轉換成文件？」這個問題的方式，並做出了一些改良，其中一個重點改良是將 Git Repo 微服務化，TiddlyRAG 不直接與檔案系統中的 Git Repo 互動，而是透過 Gitea 提供的 API：
如此一來 Git Repo 相關的業務邏輯就變成了 TiddlyRAG 不關注的通用域問題。舉例來說，TiddlyRAG 不再需要考慮 git clone 失敗與否產生的各種 edge case，只需要呼叫 Gitea 中 migrate 的 API 即可。
透過 HTTP API 操作，更容易實現權限控制與訪問審計等需求，這在基於 LLM 建構的智能體 (Agent) 系統帶來的不可空性中顯得更為重要。
POC Type-C 探索了 ECS (Entity-Component-System) 與行為樹 (Behavior Tree) 建構的智能體框架：
並實做了簡單的深度優先遍歷與廣度優先遍歷作為概念驗證。
在 POC Type-A 中，TiddlyWiki 是以相對隨便定義的方式儲存在 TiddlyRAG 內的資料庫中，但是就像 POC Type-B 處理的問題一樣，「TiddlyWiki」的儲存並不是 TiddlyRAG 關注的問題，因此在 TiddlyRAG 的微服務架構中，應該要有一個專門用儲存 TiddlyWiki 的實例。
以下是我經過調查，跟這個主題有關的專案：
TiddlyServer 的作者同時也是 MultiWikiServer 的主要貢獻者，並且在 README 明確的表明該專案已經中止，後續的開發能量會轉移給 MultiWikiServer。
tiddlyhost-com 雖然有「多租戶」的概念，但是它的主要運作方式是以 static asset 的方式 serve 多個 TiddlyWiki 檔案，因此就算它有 API，原子操作也是 TddilyWiki （整個網頁）而不是 Tiddler （條目）。
tiddlyweb 是完全以 Python 實做的伺服器，然而大部分實作依然停留在 Python 2.7 時期，甚至連 Python 3.3 的遷移也尚未完成就已經中止開發。
並且它是基於 TiddlyWiki 2.0 設計的，現代的 TiddlyWiki (TW5) 要使用這個專案必須做一些調整1。
MultiWikiServer 似乎是 TiddlyWiki 生態系中以官方的角色建構的「TiddlyWiki 微服務後端方案」，然而它依然存在一些問題。
接下來解釋一下 MWS (MultiWikiServer) 有哪些問題，如果依照 README 上的指南試著建立環境：
npm init @tiddlywiki/mws@latest my-foldercd my-foldernpx mws init-storenpx mws listen --listener會遇到很多光怪陸離的事情。
因為在 @tiddlywiki/create-mws 寫死 npm，所以就用：
pnpm create @tiddlywiki/mws@latest my-folder
得到的 node_modules 會報錯。
試圖安裝並執行 mws 指令時也會報錯，因為：
{
"dependencies": {
"prisma-client": "file:prisma/client",
}
}
package.json 的仰賴是寫死的。
如果依照 README 的 docker 安裝步驟：
# Create your data directory
mkdir my-mws-data
cd my-mws-data
# Download the required files
curl -O https://raw.githubusercontent.com/TiddlyWiki/MultiWikiServer/main/docker-compose.directory.yml
curl -O https://raw.githubusercontent.com/TiddlyWiki/MultiWikiServer/main/Dockerfile
# Create store directory
mkdir -p store
# Start MWS
docker-compose -f docker-compose.directory.yml up -d
# Initialize the database (required on first run)
docker-compose -f docker-compose.directory.yml exec mws npx mws init-store
# Access at http://localhost:8080
# Default credentials: admin / 1234
則會得到一個非常簡易的 React.js 前端頁面。
MWS 的設計依然部份延續 TiddlyWiki 的路徑，也就是軟體邊界模糊（前後端不分），以及為了保持自舉的特性，很多功能不使用函式庫而是自己重複造輪子。
舉例來說，透過 Docker 運行起來後，我的瀏覽器插件顯示它的前端使用 React，於是我便調查一下的程式碼，確實有前後端分離的跡象，但是依然出現疑似 JSX 輪子的東西：
packages/jsx-runtime/jsx-render.tsimport { MaybeArray } from "./jsx-utils";
export const JSXElementSymbol: unique symbol = Symbol("__is_jsx_element__");
const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
const MATH_NAMESPACE = "http://www.w3.org/1998/Math/MathML";
const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
const OldPropsSymbol: unique symbol = Symbol("__old_props__");
const KeyChildren: unique symbol = Symbol("__key_children__");
const OwnKeySymbol: unique symbol = Symbol("__own_key__");
const DOMElementSymbol: unique symbol = Symbol("__dom_element__");
const observer = new MutationObserver((mutations) => {
for (const mutation of mutations) {
const callbacks = observerCallbacks.get(mutation.target as Element);
if (callbacks) for (const cb of callbacks) cb();
}
});
const observerCallbacks = new WeakMap<Element, (() => void)[]>();
export function render(root: Element | DocumentFragment, child: MaybeArray<JSX.Node>) {
updateChildren(root, [child].flat(Infinity) as JSX.Node[]);
}
另一方面則是不使用 Express.js 之類主流的後端路由框架，而是自己創造另外一種模式：
packages/mws/src/managers/wiki-external.ts handleLoadBagTiddler = zodRoute({
method: ["GET", "HEAD"],
path: BAG_PREFIX + "/:bag_name/tiddlers/:title",
bodyFormat: "ignore",
zodPathParams: z => ({
bag_name: z.prismaField("Bags", "bag_name", "string"),
title: z.prismaField("Tiddlers", "title", "string"),
}),
inner: async (state) => {
const { bag_name, title } = state.pathParams;
const bag = await state.assertBagAccess(bag_name, false);
throw await state.$transaction(async (prisma) => {
const server = new WikiStateStore(state, prisma);
return await server.serveBagTiddler(bag.bag_id, bag_name, title);
});
}
});
或是手刻 HTTP body 解析：
packages/mws/src/managers/wiki-utils.tsexport async function recieveTiddlerMultipartUpload(state: ZodState<"POST", "stream", any, any, zod.ZodTypeAny>) {
// Process the incoming data
const inboxName = new Date().toISOString().replace(/:/g, "-");
const inboxPath = resolve(state.config.storePath, "inbox", inboxName);
mkdirSync(inboxPath, { recursive: true });
const parts: MultipartPart[] = [];
interface UploadPart2 {
inboxFilename?: string;
value?: string;
hasher?: Hash;
length: number;
fileStream?: Writable;
hash?: string;
}
const incomingParts = new WeakMap<MultipartPart, UploadPart2>();
const inboxFiles = new WeakMap<MultipartPart, string>();
const valueParts = new WeakMap<MultipartPart, string>();
await state.readMultipartData({
cbPartStart: async function (part) {
const part2: UploadPart2 = {
hasher: createHash("sha-256"),
length: 0,
};
if (part.filename) {
const inboxFilename = (parts.length).toString();
const inboxFilename2 = resolve(inboxPath, inboxFilename);
part2.fileStream = createWriteStream(inboxFilename2);
inboxFiles.set(part, inboxFilename2);
} else {
part2.value = "";
}
},
cbPartChunk: async function (part, chunk) {
const part2 = incomingParts.get(part)!;
if (part2.fileStream) {
await new Promise<void>((res) => {
part2.fileStream!.write(chunk) ? res() : part2.fileStream!.once("drain", () => res());
});
} else {
const encoding = part.headers.get("content-type")?.charset || "utf8";
if (!Buffer.isEncoding(encoding)) {
throw new SendError("MULTIPART_INVALID_PART_ENCODING", 400, {
partIndex: parts.length,
partEncoding: encoding,
});
}
part2.value! += chunk.toString(encoding as BufferEncoding);
}
part2.length += chunk.length;
part2.hasher!.update(chunk);
},
cbPartEnd: async function (part) {
const part2 = incomingParts.get(part)!;
if (part2.fileStream) part2.fileStream.end();
else valueParts.set(part, part2.value ?? "");
part2.hash = part2.hasher!.digest("base64url");
part2.fileStream = undefined;
part2.hasher = undefined;
incomingParts.delete(part);
parts.push(part);
},
});
const partFile = parts.find(part => part.name === "file-to-upload" && !!part.filename);
if (!partFile) throw state.sendSimple(400, "Missing file to upload");
const missingfilename = "File uploaded " + new Date().toISOString();
const type = partFile.headers.get("content-type")?.mediaType;
const tiddlerFields: TiddlerFields = { title: partFile.filename ?? missingfilename, type, };
for (const part of parts) {
const tiddlerFieldPrefix = "tiddler-field-";
if (part.name?.startsWith(tiddlerFieldPrefix)) {
const name = part.name.slice(tiddlerFieldPrefix.length);
const value = valueParts.get(part)?.trim() ?? "";
(tiddlerFields as any)[name] = value;
}
}
const contentTypeInfo = state.config.getContentType(type);
const file = await readFile(inboxFiles.get(partFile)!);
tiddlerFields.text = file.toString(contentTypeInfo.encoding as BufferEncoding);
rmSync(inboxPath, { recursive: true, force: true });
return tiddlerFields;
}
MWS 依然處於非常早 期的開發狀態，並沒有穩定到足夠被當作微服務使用，另外它已經實作一些 ACL (Access Control List) 相關的邏輯，如果在缺乏配套的情況下在 POC 中當作微服務使用會構成阻礙。例如：缺乏聲明式配置，必須手動初始化使用者，或是想要進行簡單的 CRUD 卻被 ACL 的 bug 阻擋。
然而就算撇開「開發早期」這個條件不談，差勁的程式碼職責分離除了會造成專案的成長受限以外（實作偏離範式，其他開發者看不懂、無法理解就無法貢獻），這種程式碼很容易產生漏洞，產生漏洞就不能有可靠的安全性保證，造成其身份驗證的功能虛有其表、形同虛設，不只無法提供安全性，反而拖累開發能量。經過調查之後我還發現它的 ACM (Access Control Model) 有根本性的缺陷，這個等等再補充。
因此我打算採取的策略是，根據原始實作抽出 HTTP API 界面，並使用它的資料庫設計當作參考，直接用 NestJS 重新實做，建立一個「MWS API 兼容伺服器」。
一來是出於對官方原始設計的尊重，並且透過兼容的方式避免跟 TiddyWiki 原始的生態系走太遠。二來是當我的實作走得比較前面時，發現的問題或解決方案可以反過來向 TiddlyWiki 的官方回報或貢獻。
經過三天的研究，已經成功抽出 API 定義並且用 OpenAPI YAML 紀錄：
LLM (Large Language Model) 非常擅長幹這種事情，不過隨著進展到特定 API 的細節時往往還是會發現錯誤（幻覺），所以需要在原始實作跟生成的文件中來回閱讀 。
昨天進展到這幾個 API 的實做時：
POST /bag/{bag_name}/tiddlersPOST /admin/bag_create_or_update才開始研究 API 行為跟資料庫之間的互動具體是怎麼進行的。
我們可以看到 Tiddler （條目）實際上是被掛在 Bag （知識包）之下，並且有一個名為 Recipe 的抽象會決定一個 TiddlyWiki 最後要長怎樣。同時 MWS 存在這樣的 API：
這是一個類似 OverlayFS 的設計，POST "/recipe/:recipe_name/tiddlers"，實際上是去找到最上層的 Bag 進行寫入。這個模型設計似乎是延續自 TiddlyWeb。
然而我看到這裡我就瞬間感覺使用 ACL 是一個錯誤的技術決策。Recipe 和 Bag 是多對多關係，同時 Tiddler 的操作界面是 Recipe 的視角看過去，這種關聯性授權 (Authorization) 控制應該由 ReBAC (Relationship-based access control) 處理。
況且我的目的是建立一個支援多租戶邏輯的 TiddlyWiki 的儲存實例，AuthN/AuthZ (Authentication/Authorization) 不是我首要關注的問題。
TiddlyWiki in the Sky (or TiddlyWeb for TW5) - Pleasant Programmer. Retrieved 2026-05-30, from https://pleasantprogrammer.com/posts/tiddlywiki-in-the-sky-or-tiddlyweb-for-tw5.html ↩
TiddlyRAG 的概念最早我在這篇文章就已經提出：
試著在本地運行嵌入模型：
調查幾個開源 LLM 應用程式在處理 RAG 相關的功能：
完成 POC Type-A，能夠匯入 TiddlyRAG 進行嵌入；並透過 MCP 進行檢索：
研究卡片化 (Zettelize) 的其中用例，將 Git Repo 轉換成文件，調查已經存在的實作，沒想到卻十分差勁：
完成 POC Type-B，試著從 deepwiki-open 抽出部份邏輯重新實做：
接著回到本文的重點。
deepwiki-open 的實作方式是採取兩步驟：
並且輸入是從事先把所有文件嵌入的資料中檢索 20 個檔案出來，但是我實際實驗發現在特定情況會有問題。
以 deepwiki-open 自己的 Repo 為例，它包含了 10 個不同語言的 README，因此使用 README 進行向量檢索的時候，會得到一堆不同語言的 README 跟一些 i18n 的檔案，完全不能作為有效的參考資訊。
所以我完成 POC Type-B 到一個程度後沒打算繼續深入，因為這明顯是一條死路。
根本性的原因是僵化的資料探勘策略，Git Repo 的不確定性很高：
需要一種非固定流水線 (Pipeline) 的機制才有可能處理這種不確定性。
我的直覺是透過行為樹 (Behavior Tree) 建立兼富彈性與可控性的資料探勘策略，不過在正式使用以前，我需要調查一下同樣在遊戲界常用的演算法，因此有了以下幾篇文章：
GOAP 和 HTN 建立在 STRIPS 模型之上，而 STRIPS 模型要求建模者必須對環境有一定程度的理解與掌控，用在遊戲環境沒問題（環境是遊戲開發者自己設定的），但是在 Git Repo 這種不確定性高的環境就顯得不合適。
Utility AI 是另外一個遊戲常用的古典 AI，它的行為比較簡單我就沒有特別深入研究寫文章了，基本上運作機制很接近感知機 (Perceptron) 配上可客製化的激勵函數，所以它的可預測性與可解釋性比 BT (Behavior Tree) 來得差。
所以最後還是選擇行為樹。
下一步是了解行為樹的生態，一個完整的行為樹解決方案應該包含以下條件：
話雖如此，但是不考慮遊戲引擎生態的，因為它們的 BT 通常和遊戲引擎高度整合。因此條件變得更嚴苛了，要滿足上述條件還要有解偶與高內聚的特性。
BehaviorTree.CPP 是唯一一個我找到滿足上述條件的，另外一個發現是看來 BT 不只是用在遊戲產業，（實體）機器人產業似乎也有使用。
BehaviorTree.CPP 生態系內一款名為 Groot 的視覺化工具，包含了編輯、遙測與回放功能，乍看之下似乎很完美。就算我另外用 Javascript 做，只要照著 Spec 刻就能對接 BehaviorTree.CPP 的生態系直接使用 Groot。
然而隨著深入調查卻發現不盡人意的事實，Groot 1 不再維護，且僅支援到 BehaviorTree.CPP 3.X （最新版為 4.9），Groot 2 則採取閉源訂閱制付費的方案。
接著我一邊看著 Mistreevous 的行為與文件，並和 BehaviorTree.CPP 的文件比較，我發現我無法理解「正宗行為樹」的邏輯應該為何。BehaviorTree.CPP 的文件經常使用反應式 (Reactive)、非同步 (Async)、觸發 (Trigger)、中斷 (Interrupt)...等詞彙，但是根據描述我又無法跟我平時開發 Javascript 的經驗做連結。
於是我花了一、兩天整理了行為樹的一些先備知識：
https://flyskypie.github.io/microproject-wikis/behavior-tree.html
簡單來說：
BT 最早是無狀態的，但是因為這樣每個 Cycle 都需要重新遍歷，這在大型或複雜的樹中會造成效能方面的問題。
於是狀態被引入了，讓下一個 Cycle 可以根據情況從特定的節點開始檢查，減少重複運算。但是這造成另外一個問題，當環境發生變化時，行為樹無法適應這些變化，因為一些檢查被跳過去了。
於是反應式 (Reactive)、非同步 (Async)、觸發 (Trigger)、中斷 (Interrupt) ...之類概念又被引入，用於抵銷狀態帶來的行為；可以在有狀態的 Scope 下條件性的觸發重新遍歷。
這個歷史過程造成了一些概念上的混淆，然而大部分 BT 教學並沒有提及這個過程。
如果不把一些觀念釐清（Cycle vs Tick, 有狀態 vs 無狀態），跟 LLM 討論會陷入雞同鴨講的 情況。
調查了一下列一個清單：
behavior3js 乍看是聲望最高、又有視覺化工具，但是它自 2018 年以來就沒有更新了，而且文件十分凌亂，分散在程式碼內、GitHub Wiki、死掉的網站連結...內，所以我沒辦法快速的搞清楚這東西要怎麼使用。
BehaviorTree.js 則是 2021 年以來沒有更新，2026 年有推出支援 Typescript 的 beta 版本，不過缺乏生態系其他配套（特別是視覺化）。
Sutra.js 就算撇除作者在 Reddit 跟別人筆戰「Javascript 不需要型別」以外，README 映入眼簾的是 if/else 語法以及事件驅動等功能，完全背離 BT 的設計哲學。並且同樣缺乏 BT 視覺化配套。
Mistreevous 的聲望（星星數）並不是最高的，但是從文件的易用性、原生 Typescript 支援、視覺化的支援、序列化與反序列化的重視程度...綜合考量下是一個優秀的選擇。
具體差異我就不在這邊解釋，情況有一點複雜。
這邊我要先補充一個關於 BT 的先備知識，BT 原則上是無狀態的，典型的 BT 會使用「黑板模式」：所有狀態是儲存在一個叫做黑板 (blackboard) 的東西裡面，簡單來說就是一個 key-value 表，然而實務上容易變成「一堆放在一起的全域變數」。
這對我而言是無法接受的，而碰巧我有使用 ECS (Entity-Component-System) 的經驗：
於是這件事就這樣自然發生了：
簡單來說 ECS 和 BT 都遵守 DoP (Data-oriented programming) 的哲學，因此資料跟邏輯本來就解偶了，所以把 ECS 中處理的資料的 EC 嫁接到 BT 上非常容易。
結論，我完成了一個能夠在「深度優先遍歷」與「廣度優先遍歷」切換的 BT：
https://github.com/FlySkyPie/tiddlyrag-poc/tree/poc/type-c
「僵化的資料探勘策略」的問題並未完全解決，但是 POC 的策略就是一次只驗證一件事情，我認為完成一個具有彈性的 BT 框架就算完成階段性任務了。
以下節錄自我的腦力激盪過程：
原始的設計期望透過「逐步探索」的方式來降低無用的資訊，並假設可以無須遍歷所有檔案，但是這個構想當中存在著謬誤。
LOD (Level of Development) 是在多媒體中經常被使用的技巧，白話來說就是越不重要的東西做得越粗糙，其中一個經典的應用就是遊戲場景，遠景時使用低面數、粗糙的模型，當攝影機拉近時再切換成高面數、精緻的模型。
但是即便如此，LOD 能夠運作的前提是先有一個高面數的理想模型，再對其進行降低面數的處理，因此低模存在的前提是該模型的細緻特徵已知。
再回過頭看原始「逐步探索」的設計就顯得不合理，因為資訊聚合 (Aggregation) 的前提是要先具備完整資訊。
最後我將這個問題定位為：探索與利用問題 (Exploration and Exploitation)。
我已經稍微回顧了：
下一步的重點可能會放在「如何用蒙地卡羅樹搜尋 (MCTS, Monte Carlo tree search) 解決這個資料探勘問題」上。
因為 TiddlyRAG 這個 Side Project 我也跑好一陣子了，最近想該給它一個正式的 LOGO 了，於是這張圖就產生了：
Sutra.js - Fluent Behavior Trees for JavaScript Game Development : r/javascript. https://www.reddit.com/r/javascript/comments/194e8ef/ ↩
在完成了糞 Code 巡禮之後，我發現缺少一個有效的算法來探勘並解析 Git Repo，
關於糞 Code 巡禮請見前一篇文章：
於是我計畫從行之有年且可靠的傳統（經典）遊戲 AI 中尋找靈感，行為樹 (Behavior Tree) 是我的首選，但是在跟 LLM 討論的過程中它提到了 HTN (Hierarchical Task Network)，於是我認為有必要稍微了解它一下。
然後經過簡單的搜索之後，我隱約判斷正確的學習路徑應該是：
經過一番的學習之後，我大致理解了 STRIPS 的概念，並且寫了一篇文章紀錄：
接下來我會假設讀者已經知道 STRIPS 或是閱讀過前一篇文章而不做過多的補充，缺乏先備知識可能會難以理解以下內容。
GOAP 基本上重用了 STRIPS 的問題模型，但是對 Action 加上了成本的概念，並且用 A* 演算法求解。
STRIPS 的問題本質上就是路徑規劃問題，所以用 A* 演算法求解似乎也沒什麼好意外的了。
HTN 同樣沿用了 STRIPS 中大部分概念，只是 Action 在這裡被分解了1：
GOAP 的運作邏輯是先設定一堆 Action，然後 給定起點與目標求解路徑規劃。 HTN 則是先設定由一堆 PrimitiveTask、Method 和 CompoundTask 構成的巨大樹，運行時則是由當前狀態排除那些不符合條件的方法，最後留下一條可行的 PrimitiveTask 路徑（Task 序列）。
接著就會依照剛剛得出的 Task 序列開始運行，直到任務完成或是運行途中實際狀態跟剛剛模擬的情況不符合造成前提條件不滿足，那就回到剛剛那個完整的樹再重新規劃一次並再次運行2。
【遊戲演算法】遊戲AI行為決策-分層任務網路（HTN）的簡單應用 | 白雪萬事屋. Retrieved 2026-05-08, from https://www.shirakoko.xyz/article/htn ↩
遊戲AI行為決策——HTN（分層任務網路） - 狐王駕虎 - 部落格園. Retrieved 2026-05-08, from https://www.cnblogs.com/OwlCat/p/17910900.html ↩