AI 一連上就知道「這裡有主人的知識庫」＋「讀不到」不再講成「不存在」 #118
Reference in New Issue
Block a user
Delete Branch "fix/instructions-knowledge-entrypoint"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
leo 2026-08-13：「它應該是你的知識來源⋯⋯沒有它你是瞎的。」
驗收題（leo 定的）：新 session 問「Arcrun 是什麼」要查得到真答案。
病灶一：指路的話被綁在一個會無聲消失的段落上
mcp-handler.ts必定出現的靜態段（startHere）只講工作流／零件／recipe／邊的語法——kbdb_search／kbdb_get_map一個字都沒有。唯一提到知識的是buildLibraryMapInstructions()拼上去的【藏書地圖】，而那段是選配的（1500ms 逾時、catch { text = null }、失敗完全無聲）。實害：同一天一條 portal 連線的 session 為了回答「Arcrun 是什麼」去讀了 682 行原始碼——而
kbdb_search(q="Arcrun 是什麼")當下回得出 33 筆真答案。修：
KNOWLEDGE_FIRST靜態段（與startHere同級，KBDB 掛了照樣出現），排在最前：這條連線有主人的知識庫／第一個動作是kbdb_search／工具怎麼呼叫／「知識庫裡沒有・我沒查・地圖沒取到」三件事不可以講成同一句。buildServerInstructions(env, identity)讓測試能印出完整字串。病灶二：一個 401 被逐字翻譯成「不存在」
arcrun_get_skill('write_intent_workflow')回「skill ... 不存在」，但kbdb_search撈得到page_name: "skill-write_intent_workflow"（entry_type: agent-skill、source: installer-seed）——與該工具查的鍵逐字相符。真兇：kbdbGetByPageName的if (!resp.ok) return null;。401 的來源是該實例的
arcrun-mcp沒有KBDB_INTERNAL_TOKEN（kbdb-client沒 token 就匿名送出）＝部署面的事；但這支 code 把它講成了假話。修：
KbdbAccessError（帶真 status）→kbdb_unauthorized／kbdb_unreachable，訊息明說「這是讀不到，不是不存在」，並交出還走得通的那條路（kbdb_search）。not_found只留給「KBDB 正常回應但真的沒這張卡」，並說明是「這台實例沒 seed」。identity：stale →identity_missing；portal 撞 401 時額外說明「是這批工具還走服務憑據，不是你的帳號讀不到」。arcrun_get_skill('INDEX')（leo21c 實測根本沒 seed 這支）→ 改成先arcrun_list_skills()看這台實例真的有哪幾支。驗
mcp測試 130 passed（新增mcp-instructions.test.ts7 項＋skills-examples-honesty.test.ts10 項），tsc --noEmitexit 0。kbdb_search。renderLibraryMapLines／kbdb_map.ts／kbdb/）。尚未做（誠實標）
entry_type的 listing 端點，要接得補 API（/portal/data/entries?entry_type=），不是在薄殼層拼裝（rule 07 §3.1）；且那需要 cypher 一起部署，否則 MCP 先上會打到 404。本 PR 只把話講對。INDEXskill 在 leo21c 沒被 seed——本 PR 改成不指名該 slug，但沒補 seed。leo 2026-08-13：「它應該是**你的知識來源**⋯⋯**沒有它你是瞎的**， 從你對 Arcrun 的認知就知道你的內建 Memory 是沒用的。」 ## 病灶一：指路的話被綁在一個會無聲消失的段落上 instructions 裡唯一提到「這裡有知識可查」的，是 buildLibraryMapInstructions 拼上去的【藏書地圖】——而那段是**選配的**（1500ms 逾時、catch 回 null、失敗無聲）。 必定出現的那段靜態文字（startHere）從頭到尾只講工作流、零件、recipe、邊的語法， `kbdb_search`／`kbdb_get_map` 一個字都沒有。 實害：同一天，一條 portal 連線的 session 為了回答「Arcrun 是什麼」去讀了 682 行 原始碼——而 `kbdb_search(q="Arcrun 是什麼")` 當下回得出 33 筆真答案。 修法： - 新增 `KNOWLEDGE_FIRST` 靜態段（與 startHere 同級，KBDB 掛了照樣出現）， 排在最前面：這條連線後面有主人的知識庫、第一個動作是 kbdb_search、 工具怎麼呼叫、以及「沒查到／沒查／地圖沒取到」三件事不可以講成同一句。 - 地圖失敗**不再靜默**：拿不到就印【藏書地圖：這次沒取到】， stale token 另印身分版（要使用者重新連線）——「沒取到」與「這裡沒有知識」 不可以長得一樣（Arcrun#109 同族）。鐵律不變：失敗仍然不擋連線。 - 抽出 `buildServerInstructions(env, identity)` 供測試印出完整字串。 ## 病灶二：一個 401 被逐字翻譯成「不存在」 `arcrun_get_skill('write_intent_workflow')` 回「skill ... 不存在」， 但 `kbdb_search` 撈得到 `page_name: "skill-write_intent_workflow"` （entry_type: agent-skill、source: installer-seed）——**與本工具查的鍵逐字相符**。 真兇是 `kbdbGetByPageName` 的 `if (!resp.ok) return null;`。 而 401 的來源是該實例的 arcrun-mcp 沒有 KBDB_INTERNAL_TOKEN （kbdb-client 沒 token 就匿名送出）＝部署面的事，但這支 code 把它講成了假話。 修法： - 非 2xx 一律拋 KbdbAccessError（帶真 status）→ kbdb_unauthorized／kbdb_unreachable， 訊息明說「這是讀不到，不是不存在」，並交出還走得通的那條路（kbdb_search）。 - `not_found` 只留給「KBDB 正常回應但真的沒這張卡」，並說明是「這台實例沒 seed」。 - 五支工具吃 identity：stale → identity_missing；portal 撞 401 時額外說明 「是這批工具還走服務憑據，不是你的帳號讀不到」。 - instructions 步驟 4 不再指名 `arcrun_get_skill('INDEX')`（leo21c 實測根本沒 seed 這支）——改成先 `arcrun_list_skills()` 看這台實例真的有哪幾支。 ## 驗 - `mcp` 測試 130 passed（新增 mcp-instructions 7 項＋skills-examples-honesty 10 項），tsc exit 0。 - 三種情境（地圖抓得到／抓不到／舊 token）各印一份完整 instructions 實測， 三份的開場都指向 kbdb_search。 ⚠️ 未部署（部署是 leo 的手動閘）。上線後才會到用戶手上。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.