2009scape-wiki-api

# 2009scape-wiki-api 一个后端服务，将2009scape游戏数据转化为一个干净、可搜索的知识库。它读取原始游戏数据（物品、NPC、商店、掉落表、任务等），将它们清理成统一的格式，并通过两个接口提供服务： - 一个HTTP JSON API，适用于单独的wiki网站 - 一个MCP服务器，供Claude等AI代理回答游戏问题 ## 工作原理 1. 读取原始游戏数据。 2. 将它们清理成实体（物品、NPC、任务、商店、地点）和它们之间的关系（掉落、出售、奖励）。 3. 将结果存储为构建产物（一个SQLite数据库）。 4. 通过HTTP API和MCP服务器提供服务。 数据库始终从源头重建，从不手动编辑。清理后的数据集发布到Hugging Face，并在运行时下载，因此它不提交到此仓库。 ## 项目布局 - src/wiki_api：可安装的包 - domain：核心数据模型（实体和关系） - repository：一个接口后面的数据访问（SQLite/FTS5和内存） - core：两个接口共享的查询逻辑 - surfaces/http：FastAPI HTTP API - surfaces/mcp：MCP服务器 - pipeline/artifact：构建数据集的离线代码 - tests：集成测试和手动知识修复 - scripts：开发和发布的辅助脚本 - docs：公共API文档 ## 知识模型 API提供的所有内容都是一个**实体**：一个物品、NPC、商店或任务，具有一个身份、一个形状和与其他实体的类型**关系**。 - 身份是`(type, id)`，永远不会改变。数字id在类型之间重叠，因此id本身永远不是身份。 - 每个实体还具有一个可读的`slug`，在其类型中唯一。已退休的slug和社区简写作为**别名**保留，以便重定向，因此链接不会失效。 - 相同事物的重复id（标注、绑定或占位物品）指向一个规范实体，并避免搜索和索引列表。 - 类型特定的值（购买限制、生命值、任务长度）在一份**属性注册表**中声明，该注册表包含其标签、组和单位，以便页面和API负载可以渲染而无需任何代码了解字段名称。 - 关系携带它们自己的数据含义，掉落保留其权重*和*其分母，因此速率完全渲染（例如`1/128`）。 - 每个事实记录了它来自哪里以及它反映了哪个游戏版本。 ## 开发 需要uv，它为您安装和管理固定的Python版本。 ``` uv sync --all-extras // 安装所有依赖项 uv run poe check // 运行检查、类型检查、边界检查和测试 uv run poe fix // 自动修复格式和简单的检查问题 scripts/test_ci.sh --fix --no-act // 修复、运行检查、忽略CI工作流 scripts/test_ci.sh --fix // 修复、运行检查、然后在本地运行CI工作流 ```