XERJ.code — 參考編碼
一個不熟悉 API 的代理會猜測、執行、失敗，然後再次猜測。每一次循環都會消耗輸出Token，這是最昂貴的類型。此技能用一次查詢取代多次循環：複製包含正確實作的程式庫，使用 XERJ 建立索引，並在撰寫程式碼前擷取相關段落。
這個取捨是經過深思熟慮的。檢索使用的是輸入Token，每個 Token 更便宜且可以快取；循環則使用輸出Token。有關具體的數學計算以及在何種條件下這個取捨會失敗，請參閱 COSTS.md。
狀態，明確說明：經過測量，其價值是真實但有限的。 （包含實際 Token 和費用的完整案例研究：
docs/case-studies/reference-coding/CASE_STUDY.md，2026-08-05。）重要的比較對象是原生 Claude Code——同一個代理，但使用可以自行 grep 原始碼的工具，而非裸模型。在三種情境、同一個代理、一個客觀判決（編譯通過 + 通過隱藏測試）下進行測量：
- 模型無法回憶的不熟悉程式碼與合約（一個密封、一個世代句柄、一個惰性重填、一個特定的雜湊方案——針對七個專用函式庫，21 次執行進行測量）：原生和 xerj 都解決了 21/21；xerj 使用的輸出 Token 比原生少 1.5 倍，成本低 1.3 倍，因為檢索取代了 grep。純記憶模式在 1/21 情況下失敗，並且消耗了 6.5 倍的成本。這是它的優勢所在，而且是決定性的。編譯器可以在重試循環中透露 API 名稱，但絕不會透露合約。
- 記憶的程式碼（任何流行的公開 crate——即使是一個 256 值的表格，或一個 protobuf 風格的 varint）：檢索變成了額外開銷。純記憶模式最便宜；注入一個大型參考可能是最差的選項，因為模型會重新輸出它接收到的內容。
因此：當參考是模型尚未記憶的程式碼時使用此功能——你自己的私有/專有程式碼、內部 API、截止日期之後或小眾的函式庫。對於模型已經知道的公開函式庫參考，它消耗的成本比節省的還多。原生與 xerj 之間的差距會隨著語料庫大小而增長（grep 會將整個目錄樹拉入上下文；檢索只會拉入一個段落）。
自 #977 起，整個循環都位於 xerj 二進制檔案 內部——xerj corpus add / xerj corpus index / xerj code——以及用於沒有 shell 的代理的 xerj_code_search MCP 工具。舊的包裝腳本（xc-corpus.sh、xc-index.sh、xc.py）已移除；你現有的 ~/.xerj-code 語料庫和索引可以無縫運作（請參閱下面的遷移）。
此倉庫的常規語料庫（自 2026-08-06 起為強制要求）
在 xerj 倉庫中，對於非簡單的引擎開發，檢索後在撰寫程式碼是必需的，而非可選選項。下面的每個語料庫在 hub/ 中都有一個固定、經過許可審查的定義——xerj corpus add --from hub/<name>.json 會在其他所有人使用的相同提交點上重建語料庫：
| 語料庫 | 專案 | 用途 |
|---|---|---|
xerj-search | lucene, tantivy, meilisearch, quickwit, sonic, elasticsearch | 全文搜尋、BM25、張貼列表、合併策略、打字容錯、分段佈局、ES 有線語義 |
xerj-vector | qdrant, usearch, instant-distance, hnswlib | HNSW 建構、鄰居啟發式、量化、過濾式 kNN |
xerj-storage | sled, fjall, redb | WAL、刷新週期、崩潰恢復、壓縮、頁面分配 |
xerj-columnar | clickhouse | 列式存儲、聚合執行、壓縮編解碼器、向量化掃描 |
僅供方法參考的來源： elasticsearch (AGPL-3.0 / SSPL-1.0 / Elastic-2.0) 和 sonic (MPL-2.0)。切勿將其程式碼複製到 Apache-2.0 的 XERJ 中；對於 ES，貼上原始碼也會偽造專案公開的「與 Elasticsearch 無關的程式碼」聲明。meilisearch 的核心是 MIT，但其企業版部分使用 BUSL-1.1——請先檢查標題/路徑。閱讀設計，撰寫我們自己的實作。每個清單的 review.use 欄位會說明儲存庫屬於哪個類別；hub/README.md 解釋了這三種類別。
中樞語料庫或本地語料庫
兩種類型的語料庫位於同一個本地節點上。每種語料庫回答不同類型的問題：
| 中樞語料庫 | 本地語料庫 | |
|---|---|---|
| 內容 | 固定提交點的公開資料：函式庫原始碼、標準、法規、建議摘要 | 僅此機器擁有的檔案：你正在開發的專案、私人文件、匯出檔案 |
| 使用時機 | 你需要一個無法從記憶中準確引用的細節 | 答案在你的自己的檔案中 |
| 新增方式 | xerj corpus add --from ./<slug>.json，然後執行 xerj corpus index <slug> | xerj autoindex <資料夾> |
| 查詢方式 | xerj code <slug> "<問題>" · MCP xerj_code_search | xerj search "<字詞>" · xerj def "<符號>" · MCP xerj_search |
使用 xerj autoindex --prefix <p> 建立索引的資料夾是該表中的本地路徑，而非 xerj code 語料庫：xerj corpus list 讀取 ~/.xerj-code 並且在 xerj corpus add 註冊該資料夾之前不會列出 <p>，而搜尋它的指令是 xerj search --prefix <p> 和 xerj def --prefix <p>。
對於你已經能準確陳述的事實，兩者都不要使用：對於已記憶的內容，檢索是額外開銷（請參閱上面的狀態說明）。
中樞清單來自 corpus-hub 分支的檢出（tools/xerj-code/hub/<slug>.json），或者在沒有檢出的情況下，來自其原始 URL。corpus index 和 code 都與正在運行的節點通信：
curl -fsSLO https://raw.githubusercontent.com/xerj-org/xerj/corpus-hub/tools/xerj-code/hub/<slug>.json
xerj corpus add --from ./<slug>.json # 最後一行: next: xerj corpus index <slug>
xerj corpus index <slug> # 結束: corpus '<slug>' searchable: <N> records
xerj code <slug> "<question>" # 以檔案路徑和行號為標題的段落
--from 讀取本地檔案：v1.0.0-rc.95 不擷取 URL，傳遞 URL 會回應 no such manifest。
為手頭專案選擇語料庫
上面的四個引擎語料庫是此倉庫的常規集合。完整的即時目錄可在 hub.xerj.org 瀏覽，並在 hub.xerj.org/llms.txt 中為每個語料庫提供一行；節點已載入的內容是 xerj corpus list --url <node>。每個語料庫都固定在一個提交點，並記錄了每個來源的許可證。G7（一個五問題檢索門控，其測試套件在檢索執行之前就已預先註冊）已對某些語料庫進行了評分，而其他語料庫則沒有，每個中樞頁面都會說明。根據專案的領域選擇，而不是根據規模：
| 如果專案是… | 從哪個開始 | 原因 |
|---|---|---|
| 搜尋/查詢引擎 | xerj-search | 張貼列表、BM25、合併策略、分段佈局、ES 有線語義 |
| 向量搜尋/ANN | xerj-vector、faiss、annoy | HNSW 建構、鄰居啟發式、量化、過濾式 kNN；faiss 是參考性的 ANN 實作，annoy 是森林變體 |
| 儲存引擎/KV | xerj-storage、duckdb、rocksdb、leveldb、badger、lmdb、pebble、valkey-src | WAL、崩潰恢復、壓縮、頁面分配；LSM 與 B 樹；pebble 用於 L0 子層級和範圍刪除語義；valkey 用於記憶體內 KV 伺服器的資料結構 |
| 分析/列式 | xerj-columnar、duckdb、arrow-rs、parquet-format、iceberg | 列式佈局、編解碼器、向量化掃描、表格格式 |
| 資料庫伺服器 | sqlite-src、postgres-src | 解析器、規劃器、執行器——該領域研究最多的兩個程式碼庫 |
| 訊息傳遞/共識 | kafka-src、rabbitmq、nats-server、etcd-src、raft-rs、dragonboat | 日誌壓縮、傳遞語義、法定人數/租約正確性 |
| 監控/時間序列 | influxdb、prometheus-src | TSDB 佈局、降取樣、抓取/接收路徑 |
| TLS/加密/隧道 | rustls、openssl、s2n-tls、boringtun | 手動實作現代 TLS、強化先例、常數時間模式 |
| QUIC/HTTP/網路 | quinn、nghttp2、curl-src、libuv、caddy、envoy、nginx | 協議狀態機、連線池、事件循環 |
| 壓縮/序列化 | zstd、lz4、brotli、zlib-ng、snappy、protobuf、flatbuffers、capnproto、msgpack-c | 格式設計、分塊/熵編碼、零拷貝模式 |
| 秘密/配置服務 | openbao | 具有密封/解封、租約機制的 KV 儲存 |
| API 設計審查 | rust-api-guidelines、msft-api-guidelines、zalando-restful-api-guidelines、google-eng-practices | 命名、錯誤型態、版本控制；Zalando 是最條款完整的 REST 政策集，google-eng-practices 主導程式碼審查原則 |
| 協議/規範符合性 | openapi-spec、graphql-spec、json-schema-spec、w3c-css、whatwg-specs、ecma262、nats-protocol、kafka-protocol | 用於判斷實作是否合規的規範性文本——HTML/DOM/URL 即時標準、ECMAScript 語法、有線協議框架 |
| 在閱讀前定位正確的 RFC | ietf-rfc-abstracts | 每個 RFC 一條記錄（共 9,015 條）：編號、標題、日期、摘要——「哪個 RFC 實際上涵蓋了 X」而無需提取全文（TLP-5.0） |
| 生產運維/SRE | gitlab-runbooks、school-of-sre、tldr-pages、mozilla-ssl-configs、twelve-factor | 真實事件應對手冊、完整 SRE 課程、依工具分類的命令語法、已部署的 TLS 配置、部署原則 |
| 管理 Unix 系統 | freebsd-handbook、openbsd-faq | rc/ZFS/監獄/網路程序、OpenBSD 的權威 FAQ 立場 |
| 針對託管 API 進行文件撰寫 | github-api-description | github.rest 的 OpenAPI 描述——欄位語義、枚舉值、預覽標頭 |
| 資料儲存操作文件 | valkey-docs、etcd-docs | 命令語義、配置參數、調優指南——每個的運維參考 |
| 遙測/可觀測性連接 | otel-proto 的 semconv 部分（候選——G7 2/5，暫停至語義通道） | OpenTelemetry 屬性名稱的語義慣例；詞彙層無法彌合釋義到規範性散文之間的差距 |
| 國際化 | unicode-cldr | CLDR 地區資料結構、日曆/數字/日期骨架 |
| Rust 依賴項的安全審查 | rustsec-advisories、rust-vulns 包（使用 xerj corpus add --from 中樞配方） | 每個公告一條文字記錄（共 1,963 條：RustSec + crates.io OSV，零別名重疊）：受影響版本、已修復版本、271 上的受影響函數符號列表；該包仍是用於已修補配對挖掘的工具（#1111 缺陷類別研究） |
| Python 依賴項的安全審查 | pysec | PYSEC 公告記錄，包含受影響和已修復版本、CVE/GHSA 別名 |
| 跨生態系依賴項審計 | ghsa-db | GitHub 審查過的公告（共 36,263 條文字記錄）：CVSS 向量、已修復範圍、npm/PyPI/Go/Rust/maven 等受影響的套件 |
| Go 模組的安全審查 | go-vulndb | Go 團隊策劃的公告（共 4,577 條）：受影響的套件和符號、已修復版本、帶有 CVE 別名的 GO 編號 |
| 正則表達式拒絕服務先例 | redos-precedent | 634 個正則表達式特定的 ReDoS 公告（CWE-1337/185 類別，非單純 CWE-400）：導致問題的輸入、受影響的函數、有界重寫 |
| 加密濫用先例 | crypto-misuse-precedent | 721 個 CWE-326/327/328/329/347 類別公告：弱密碼、硬編碼金鑰、nonce 重複使用、簽名驗證繞過、填充預言、ECB |
| 漏洞/弱點分類法 | mitre-cwe、mitre-capec | CWE 弱點定義和 CAPEC 攻擊模式，ID 層級 |
| 對手技術/檢測工程 | mitre-attck | ATT&CK v19.2 每技術記錄：技術 ID、戰術、檢測資料來源、程序範例（企業/行動/ICS；軟體和群體物件超出範圍） |
| 補丁優先級分類 | cisa-kev | 已知被利用漏洞目錄，每個 CVE 一條記錄——野外利用狀態、具有約束力的修復日期 |
| Web 應用程式安全實用方法 | owasp-cheatsheets | 備忘單系列針對每個主題的應對措施配方——工作階段管理、驗證秘密、錯誤處理、上傳處理 |
| 規劃 Web 應用程式滲透測試 | owasp-wstg | Web 安全測試指南 v4.2 目錄：每個測試的目標和方法，按類別組織（認證、授權、工作階段、輸入處理） |
| 分類活躍攻擊活動 | cisa-alerts | CISA 公告的入侵指標、必要動作和緩解措施（2025-05..2026-10 窗口） |
| 查詢端點可見性 | osquery-config-examples | 真實部署的 osquery 包和排程查詢型態 |
| 非軟體（稅務、僱傭、英國法律） | ecfr-title-12、ecfr-title-29、ecfr-title-26、uk-legislation | 合併的現行法規，每節一個檔案 |
| 航空（FAR） | ecfr-title-14 | 14 CFR 每節一個檔案：能見度最低要求、應答器空域、檢查間隔、通行權 |
| 海上航行規則 | navrules | COMDTINST M16672.2D 每條規則文字——碰撞危險、狹窄水道、交叉情況、燈光和聲音信號 |
| 無障礙 UI 元件 | govuk-design-system | GOV.UK 元件選項和無障礙標準——確切的選項語義（maxwords 與 maxlength、分隔線文字、焦點載入） |
| 藥品/藥物標籤 | dailymed | FDA 標籤章節：適應症、禁忌症、給藥時間 |
| 臨床治療指導 | cdc-clinical | CDC STI 治療方案和劑量、梅毒脫敏、麻疹臨床體徵 |
| 餐飲服務安全 | fda-food-code | FDA 食品法典 2022 規定：手部接觸表面、時間作為公共衛生控制、日期標記、裸手準備 |
| 交通控制設施 | mutcd | FHWA MUTCD 第 11 版（修訂 1）：標誌和信號設置條件、標線、工作區典型應用 |
| 建築工程（英格蘭） | uk-building-regs | 2010 年建築法規（SI 2010/2214）每條規定：A–P 部分要求、威爾斯變更 |
…
[為翻譯而截斷]