XERJ.code — 参考编码 是做什么的？
一个不了解 API 的智能体会猜测、运行、失败，然后再次猜测。每轮循环都会消耗昂贵的输出 token。本技能用检索来替代循环：克隆包含正确实现的仓库，使用 XERJ 进行索引，在编写代码前检索代码片段。
这种权衡是深思熟虑的。检索消耗的是输入 token，它们更便宜且可缓存；而循环消耗的是输出 token。有关具体计算，以及此权衡在哪些条件下会失败，请参见 COSTS.md。
现状，直言不讳：经过衡量，价值真实但狭窄。 （完整的案例研究，包含真实的 token 和美元数据：
docs/case-studies/reference-coding/CASE_STUDY.md，2026-08-05。）最有意义的比较对象是原生 Claude Code——即使用本身就能 grep 源代码工具的同一个智能体，而不是裸模型。在三种情况下，使用同一个智能体，以唯一客观标准（编译通过 + 通过隐藏测试）进行衡量：
- 模型无法回忆的、具有合约（contract）的陌生代码（如一个密封（seal）、一个生成式句柄（generational handle）、一个惰性重填（lazy refill）、一种特定的哈希方案——在七个专门构建的库，21 次运行中测量）：原生和 xerj 均解决 21/21；xerj 使用 1.5 倍更少的输出 token，成本比原生低 1.3 倍，因为检索替代了 grep。纯记忆模式失败 1/21，并消耗 6.5 倍的成本 进行挣扎。这是胜利，且是决定性的。编译器可以在重试循环中泄露 API 名称，但永远不会泄露合约。
- 记忆化代码（任何流行的公共 crate——即使是 256 值的表，或 protobuf 风格的 varint）：检索是开销。纯记忆模式成本最低；注入大量引用可能是最差的选择，因为模型会重新输出它被喂入的内容。
因此：当参考代码是模型未记忆的代码时使用此技能——你自己的私有/专有代码、内部 API、截止日期后的库或小众库。对于模型已经知道的公共库引用，此技能的成本高于其节省的成本。原生 vs 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 | 预写日志、刷新周期、崩溃恢复、压缩、页面分配 |
xerj-columnar | clickhouse | 列式存储、聚合执行、压缩编解码器、向量化扫描 |
仅限参考（approach-only）的源码： 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 <folder> |
| 查询方式 | 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 并且不会列出 <p>，直到 xerj corpus add 注册该文件夹为止；搜索该文件夹的命令是 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 # 最后一行：下一步：xerj corpus index <slug>
xerj corpus index <slug> # 结束：语料库 '<slug>' 可搜索：<N> 条记录
xerj code <slug> "<问题>" # 代码片段前带有文件路径和行号
--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（一个包含五个问题的检索门控（retrieval gate），其测试套件在检索运行之前就已预注册）已对部分语料库进行了评分，但并非全部；每个中心页面都会说明。请根据项目的领域选择，而不是大小：
| 项目是…… | 从……开始 | 原因 |
|---|---|---|
| 搜索引擎 / 查询引擎 | 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 | 预写日志、崩溃恢复、压缩、页面分配；LSM-vs-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 | 带有封缄/解封（seal/unseal）、租约机制的 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 前定位正确的 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/jail/网络程序、OpenBSD 的规范常见问题解答 |
| 针对托管 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 条）：受影响的包和符号、修复版本、GO ID 及 CVE 别名 |
| 正则表达式拒绝服务先例 | 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、策略、检测数据源、过程示例（企业/移动/工控；软件和组对象不在范围内） |
| 补丁优先级排序 | cisa-kev | 已知被利用漏洞目录，每条 CVE 一条记录——野外利用状态、强制性修复日期 |
| Web 应用程序安全操作指南 | owasp-cheatsheets | Cheat Sheet 系列中按主题划分的应对措施手册——会话管理、认证密钥、错误处理、上传处理 |
| 规划 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 | 合并的现行法规，每个文件一个章节 |
| 航空（联邦航空条例，FARs） | ecfr-title-14 | 14 CFR 每个章节一个文件：能见度最低要求、应答机空域、检查间隔、航行优先权 |
| 海上避碰规则 | navrules | COMDTINST M16672.2D 每条规则文本——碰撞危险、狭窄水道、交叉局面、灯光和声音信号 |
| 可访问的 UI 组件 | govuk-design-system | GOV.UK 组件选项和可访问性标准——确切的选项语义（maxwords 与 maxlength、分隔符文本、焦点加载行为） |
| 制药 / 药品标签 | dailymed | FDA 标签章节：适应症、禁忌症、给药时机 |
| 临床治疗指南 | cdc-clinical | CDC 性传播感染治疗方案和剂量、梅毒脱敏治疗、麻疹临床体征 |
| 餐饮服务安全 | fda-food-code | FDA 食品法典 2022 条款：手接触表面、作为公共卫生控制的时间、日期标记、裸手准备 |
| 交通控制设备 | mutcd | FHWA MUTCD 第 11 版（修订版 1）：标志和信号设置条件、标线、工作区典型应用 |
| 建筑工程（英格兰） | uk-building-regs | 2010 年建筑法规（SI 2010/2214）每条条款：Parts A–P 的要求，威尔士变异 |