Destiny---Codex

<p align="center"> <img src="assets/MCP-Banner.png" alt="命运编目" width="100%"> </p> # 命运编目 > 版本 **0.5.1.0** (02.07.2026) > > 将命运2的Manifest（难以理解的哈希引用JSON）转换为干净的、适合AI读取的文本——并具有完整的关联遍历、结构化筛选、物品比较和武器特效提取功能。 命运编目是一个CLI工具**和**MCP服务器。它适用于**100%的Manifest**——每个定义表都得到了通用支持。哈希引用会自动解析为人类可读的名称，支持双向查询。 ## 更新日志 ### 0.5.1.0 (02.07.2026) **新功能：** - **离线模式** —— 远程Manifest版本仅在缓存丢失或上次检查时间超过1小时时进行检查。如果Bungie无法访问，缓存的Manifest将被使用，并附带警告。命令速度更快，无需互联网连接。 - **快速反向特效搜索** —— `codex perksearch`现在使用预计算的`weapon_perks`表存储在索引数据库中，而不是每次查询扫描约40k个物品。运行`codex index --rebuild`一次即可升级现有的索引缓存（较旧的缓存会自动回退到完整扫描）。 - **`--json` 输出** —— `search`、`filter`、`browse`、`rolls`和`perksearch`接受`--json`参数以进行原始结构化输出（适用于脚本编写，无需REST服务器）。 - **每种语言的Manifest元数据** —— 在来回切换语言时，如果缓存的数据库仍然当前，则不会重新下载Manifest。 - **网络强化** —— 所有Bungie调用现在都有超时时间（15秒元数据，120秒下载）；Manifest下载最多重试3次，并在替换缓存之前验证SQLite标头。 - **CI** —— GitHub Actions工作流（每次推送/拉取请求时构建和测试）。 **错误修复：** - **统计名称筛选器** —— 统计名称（`--stat "Swing Speed:50"`，`statsByName`）现在针对Manifest的`DestinyStatDefinition`表进行解析，而不是使用包含错误哈希值的硬编码列表（Accuracy、Charge Rate、Swing Speed、Guard Endurance等）。这也使得统计筛选器在每个Manifest语言中都有效。 - **`itemSubType`标签** —— 格式化器使用错误的枚举（例如`1: Helmet`）；替换为正确的`DestinyItemSubType`值（Hand Cannon、Sword、Glaive等）。 - **类型声明** —— `dist/api.d.ts`现在实际发出（`declaration: true`）；库消费者获取TypeScript类型。 - **`zod`依赖** —— 显式声明，而不是依赖MCP SDK的传递副本。 - **筛选完整性** —— `filter`不再提前停止扫描（`limit * 3`），这可能会根据表顺序静默丢弃匹配的物品。 - **表名验证** —— CLI/MCP/REST输入的表名在用于SQL之前会针对Manifest进行验证。REST服务器针对未知表返回400。 **改进：** - **共享套接字逻辑** —— `rolls`、`perksearch`和`weapon_perks`索引构建现在共享一个`sockets.ts`特效提取实现，而不是三个可能相互冲突的副本。 - 定义查找的预备语句缓存（热点如`rolls`、`browse`、`graph`不再重复准备相同的SQL数千次）。 - API查询缓存现在涵盖`search`、`get`、`resolve`、`relationships`、`graph`和`compare`（以前仅限`filter`/`browse`/`rolls`/`perksearch`）。 - 类/伤害名称的中心`enums.ts`；`filter`输出现在显示`class=Titan`/`dmg=Solar`而不是数字代码；REST `class`/`damage`参数不区分大小写。 - **测试** —— 从50个扩展到74个，包括一个夹具内存Manifest DB，涵盖`filter`、`rolls`、`perksearch`、`sockets`、`relationships`和表验证守卫。`package.json`和`src/version.ts`之间的版本一致性由测试强制执行。 --- ### 0.5.0.0 (07.01.2026) **新功能：** - **`browse` MCP工具 + CLI命令** —— 浏览具有完整显示数据的物品：图标、统计数据、插槽、伤害类型、水印、风味文本。类似于`filter`但更丰富。 - **`compare` MCP工具** —— 通过MCP比较2-6个物品（统计数据、特效、属性以对齐的列显示）。以前仅在CLI和REST中可用。 - **`item` MCP工具** —— 通过名称查找物品并一步获取其完整的易读定义。取代搜索+获取的两次调用模式。 - **AGENTS.md更新** —— `browse.ts`和`compare.ts`现在在架构部分有文档。 **错误修复：** - **`resolve` MCP工具** —— 删除不必要的数据库查询，该查询加载了一个定义，只是为了丢弃它（`void def`）。 --- ## 快速开始 ```bash # 1. 安装依赖 + 构建 npm install npm run build # 2. 全局安装`codex`命令（链接此仓库） npm link # 或：npm install -g . # 3. 添加您的Bungie API密钥（在https://www.bungie.net/en/Application获取） codex config set-key your_key_here # 4. （可选）设置您的首选语言（默认为en） codex config set-language zh # 简体中文 # 5. 下载Manifest + 构建索引 codex sync codex index # 6. 使用它 codex item Gjallarhorn ``` > 以下所有命令都使用全局`codex`命令。如果您不想全局安装，可以在仓库根目录从`node dist/index.js <command>`运行它（例如`node dist/index.js item Gjallarhorn`）。 您也可以通过`.env`文件提供密钥（`cp .env.example .env`，然后设置`BUNGIE_API_KEY=...`）或`BUNGIE_API_KEY`环境变量。 ## CLI命令 ### 查询 & 搜索 | 命令 | 描述 | |---|---| | `codex item <name>` | 通过名称查找物品，显示完整的易读定义。自动选择最佳匹配。 | | `codex search <query>` | 通过名称搜索（子字符串，不区分大小写）。`-t <table>`筛选，`-l <n>`限制。 | | `codex filter [options]` | 结构化筛选：`--tier`、`--type`、`--class`、`--damage`、`--bucket`、`--stat`。 | | `codex browse [options]` | 浏览具有完整显示数据的物品（图标、统计数据、插槽、伤害、风味文本）。与`filter`相同的筛选器，但更丰富。 | | `codex rolls <name>` | 显示武器的所有可能特效滚动（枪管、弹药库、特效、模组、催化剂）。回答“这个武器可以有哪些特效？” | | `codex perksearch <perk>` | 反向特效搜索：查找可以滚动给定特效的所有武器。别名：`perks`。 | | `codex get <table> <hash>` | 通过表+哈希获取完整的易读定义（所有引用内联解析）。 | | `codex resolve <hash>` | 裸哈希 → 简短摘要（自动检测表）。 | | `codex raw <table> <hash>` | 定义的原始JSON。 | ### 关联 & 图 | 命令 | 描述 | |---|---| | `codex relationships <table> <hash>` | 显示外出+进入引用。别名：`codex rels`。 | | `codex graph <table> <hash>` | 将引用图遍历为树。别名：`codex tree`。 | | `codex compare <name1> <name2> [name3...]` | 比较2+个物品（统计数据、特效、属性以对齐的列显示）。 | ### 管理 | 命令 | 描述 | |---|---| | `codex sync` | 下载/刷新Manifest。 `--force`强制重新下载。 | | `codex index` | 构建搜索索引（加速所有操作约10倍）。 `--rebuild`强制重新构建。 | | `codex info` | 显示Manifest版本+表列表。 | | `codex tables` | 列出所有定义表。 | | `codex mcp` | 启动MCP服务器（用于AI工具集成）。 | | `codex serve` | 启动REST API HTTP服务器用于应用集成。 `--port`、`--host`。 | | `codex config set-key <key>` | 保存您的Bungie API密钥。 | | `codex config set-language <lang>` | 保存首选Manifest语言（`zh`、`en`等）。运行`sync`后。 | | `codex config get-language` | 显示当前保存的语言。 | ## 示例 ### 查询物品 ```bash codex item Gjallarhorn codex item "Last Wish" --table DestinyActivityDefinition ``` ### 搜索 ```bash codex search Gjallarhorn codex search "Wolfpack Rounds" -t DestinySandboxPerkDefinition codex find "Last Wish" -l 5 ``` ### 筛选 ```bash # 所有异国火箭发射器 codex filter --tier Exotic --type "Rocket Launcher" # 所有传奇泰坦头盔 codex filter --tier Legendary --class Titan --bucket Helmet # 火箭发射器爆炸半径 >= 90 codex filter --type "Rocket Launcher" --stat "Blast Radius:90" # 太阳系侧臂，限制10个结果 codex filter --damage Solar --type "Sidearm" --limit 10 ``` ### 浏览（丰富物品数据） ```bash # 异国火箭发射器，图标、统计数据、插槽、风味文本 codex browse --tier Exotic --type "Rocket Launcher" # 传奇泰坦头盔，完整显示数据 codex browse --tier Legendary --class Titan --bucket Helmet --limit 10 # 太阳系侧臂，图标和统计数据 codex browse --damage Solar --type "Sidearm" --limit 10 ``` ### 关联（事物如何连接） ```bash # Gjallarhorn引用了什么（外出） codex rels DestinyInventoryItemDefinition 1363886209 -d outgoing # 谁使用“Wolfpack Rounds”特效（进入） codex rels DestinySandboxPerkDefinition 2447763556 -d incoming # 两个方向 codex rels DestinyInventoryItemDefinition 1363886209 ``` ### 图遍历 ```bash codex graph DestinyInventoryItemDefinition 1363886209 --depth 3 codex tree DestinyInventoryItemDefinition 1363886209 --depth 2 --branch 10 ``` ### 比较物品 ```bash codex compare Gjallarhorn "Hezen Vengeance" codex compare "Deathbringer" "Two-Tailed Fox" "Eyes of Tomorrow" ``` ### 武器特效滚动 ```bash # Code Duello可以有哪些特效？ codex rolls "Code Duello" # 异国特效 + 催化剂 codex rolls Gjallarhorn # 突袭武器滚动 codex rolls "Hezen Vengeance" ``` ### 反向特效搜索 ```bash # 哪些武器可以滚动Incandescent？ codex perksearch Incandescent # 哪些武器可以滚动Bait and Switch？ codex perks "Bait and Switch" # 哪些武器可以滚动Vorpal Weapon？ codex perksearch "Vorpal Weapon" ``` ### 多语言支持 ```bash # 切换到简体中文 codex config set-language zh codex sync codex index --rebuild # 现在一切都是简体中文 codex item Gjallarhorn # "火箭发射器（异国）" codex filter --tier Exotic --type "火箭发射器" codex rolls "Code Duello" # "固有属性", "武器特效" # 一次性语言同步（无需保存） codex sync --language fr codex sync -l ja # 支持的语言 zh, en, es, es-mx, fr, fr-ca, it, ja, ko, pl, pt-br, ru, zh-chs, zh-cht ``` ## MCP服务器（用于AI工具） 命运编目作为[MCP服务器](https://modelcontextprotocol.io/)通过stdio运行。像Devin、Claude等AI助手可以直接调用它。 ### 启动服务器 ```bash codex mcp ``` ### 在MCP客户端配置 如果您全局安装了`codex`命令（`npm link` / `npm install -g .`）， 请直接指向它： ```json { "mcpServers": { "destiny-codex": { "command": "codex", "args": ["mcp"] } } } ``` 如果您**没有**全局安装，请从构建输出运行： ```json { "mcpServers": { "destiny-codex": { "command": "node", "args": ["/path/to/destiny-codex/dist/index.js", "mcp"] } } } ``` ### MCP工具 | 工具 | 描述 | |---|---| | `manifest_info` | Manifest版本、语言、表列表，含行数。自动同步。 | | `list_tables` | 所有定义表。 | | `search` | 名称搜索，含可选表筛选。 | | `filter` | 结构化查询：物品类型、层级类型、类类型、伤害类型、桶、统计范围。 | | `browse` | 丰富的物品数据：图标、统计数据、插槽、伤害、风味文本。与`filter`相同的筛选器。 | | `rolls` | 武器的所有可能特效滚动（枪管、弹药库、特效、模组、催化剂）。 | | `perk_search` | 反向特效搜索：哪些武器可以滚动给定的特效？ | | `item` | 通过名称查找物品 → 一步到位获取完整易读定义（模糊匹配）。 | | `compare` | 比较2-6个物品（统计数据、特效、属性以列显示）。 | | `get` | 定义的可读文本渲染（所有哈希引用内联解析）。 | | `resolve` | 裸哈希 → 简短摘要。 | | `relationships` | 出去+进入引用（事物如何连接）。 | | `graph` | 将引用图遍历为树形结构，N层深度。 | | `raw` | 定义的原始JSON。 | ## 应用集成 命运编目可以作为您自己的应用的后端——无需AI，无需CLI。 ### 程序API（Node.js） ```ts import { DestinyCodex } from "destiny-codex"; const codex = new DestinyCodex({ apiKey: "your-bungie-key" }); await codex.sync(); // 下载Manifest await codex.index(); // 构建索引 // 搜索 const hits = await codex.search("Gjallarhorn"); // 武器特效滚动 const rolls = await codex.getRolls("Code Duello"); // 反向特效搜索 const weapons = await codex.findWeaponsWithPerk("Incandescent"); // 筛选 const exotics = await codex.filter({ tierTypeName: "Exotic", itemTypeDisplayName: "Rocket Launcher" }); // 浏览（丰富：图标、统计数据、插槽、风味文本） const browseResults = await codex.browse({ tierTypeName: "Exotic", itemTypeDisplayName: "Rocket Launcher" }); // 比较 const comparison = await codex.compare(["Gjallarhorn", "Hezen Vengeance"]); // 引用 const rels = await codex.relationships("DestinyInventoryItemDefinition", 1363886209) // 原始JSON const raw = await codex.raw("DestinyInventoryItemDefinition", 1363886209); codex.close(); ``` ### REST API服务器（用于网页应用 / 前端） ```bash codex serve --port 3000 ``` 所有端点返回JSON并启用CORS： | 端点 | 描述 | |---|---| | `GET /health` | 健康检查 | | `GET /api/info` | Manifest版本、语言、表 | | `GET /api/tables` | 所有定义表 | | `GET /api/search?q&q=<name>&table=<t>&limit=<n>`搜索名称 | | `GET /api/filter?tier=<t>&type=<t>&class=<c>&damage=<d>` | 结构化筛选 | | `GET /api/browse?tier=<t>&type=<t>&class=<c>&damage=<d>` | 浏览具有完整显示数据的物品（图标、统计数据、插槽） | | `GET /api/get/<table>/<hash>` | 可读定义 | | `GET /api/resolve/<hash>` | 裸哈希 → 摘要 | | `GET /api/rolls/<name-or-hash>` | 武器特效滚动 | | `GET /api/perksearch/<perk-name-or-hash>` | 可以滚动特效的武器 | | `GET /api/compare?items=<n1,n2,n3>` | 比较物品 | | `GET /api/relationships/<table>/<hash>?direction=<both\|outgoing\|incoming>` | 引用 | | `GET /api/graph/<table>/<hash>?depth=<n>&branch=<n>` | 图遍历 | | `GET /api/raw/<table>/<hash>` | 原始JSON | ```bash # 示例 curl http://localhost:3000/api/search?q=Gjallarhorn curl http://localhost:3000/api/rolls/Code%20Duello curl http://localhost:3000/api/perksearch/Incandescent curl "http://localhost:3000/api/filter?tier=Exotic&type=Rocket%20Launcher&limit=5" curl "http://localhost:3000/api/browse?tier=Exotic&type=Rocket%20Launcher&limit=5" ``` ## 工作原理 命运2的Manifest是一个SQLite数据库，包含约83个JSON定义表。每个定义都充满了哈希引用——`itemHash: 1363886209`, `statHash: 155624089`等——如果不查找目标，是毫无意义的。 命运编目： 1. **下载**来自Bungie API的Manifest并本地缓存为SQLite。 2. **构建索引**（正向哈希→表，名称索引，反向引用索引）存储为版本化的SQLite DB。 3. **解析**哈希引用双向： - **字段名称启发式**：`itemHash` → `DestinyInventoryItemDefinition`（快速，无需查找） - **反向索引回退**：任意哈希 → 其表（处理未知字段名称） 4. **格式化**定义为干净的缩进文本，哈希引用内联替换为`"Gjallarhorn" (hash 1363886209, DestinyInventoryItemDefinition)`。 5. **遍历**引用图双向：出去（什么引用X？）和进来（谁引用X？）。 ## 性能 | 操作 | 时间 | |---|---| | Manifest下载 | ~10s（37 MB压缩） | | 索引构建 | ~15s（一次性每次Manifest版本） | | `codex search`（有索引） | ~1.3s | | `codex rels`（有索引） | ~1.2s | | `codex graph`（有索引） | ~1.2s | | `codex filter` | ~0.3s | | `codex perksearch`（有索引） | ~1s | ## 要求 - Node.js **22.5+**（使用内置`node:sqlite`）。在Node 22/23上可能需要`--experimental-sqlite`标志；在Node 24+上稳定。 - 一个Bungie.net API密钥（免费，在https://www.bungie.net/en/Application获取） ## 许可 PolyForm Noncommercial 1.0.0 — 见[LICENSE](LICENSE)。 该软件**永远**不得用于商业目的。个人使用、研究、教育、慈善组织和政府机构是允许的。见[完整许可文本](https://polyformproject.org/licenses/noncommercial/1.0.0)获取详细信息。