{"repo": "brofea/mc-pilot", "files": {"README.md": {"71eb19f88f2315fdbd359065af1b2bc59f6d9356": {"t": 1785747270.0354946, "n": 9375, "h": "a3582f998a8212af", "c": "
\n \"Minecraft\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，提供 Vue 3 网页工作台与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 OpenAI 兼容 API，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、通用复杂问题、MCP 风格 Function Calling、12 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n6. **Vue 工作台**：Vue 3 + TypeScript + Vite 构建的响应式界面，统一承载对话、知识库、配方浏览、游戏连接与控制台导航。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WS| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WS| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> OpenAI 兼容 API\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> OpenAI 兼容 API\n Game --> API\n```\n\n## Quick Start\n\n### 1. 前置条件\n\n- Docker Desktop 与 Docker Compose\n- 任意 OpenAI 兼容 API Key\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 克隆并配置\n\n```bash\ngit clone git@github.com:brofea/mc-pilot.git\ncd mc-pilot\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 任意 OpenAI 兼容 API Key\nDEEPSEEK_API_KEY=\n\n# .minecraft 目录；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=\n```\n\n注意：不要把 `.env` 提交到仓库。\n\n仓库中已包含预构建的配方数据库（`data/mc_pilot.db`），无需额外构建。\n\n### 3. 启动\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n首次启动时会自动检查 Qdrant 中是否已有 Wiki 索引。如果没有，会在后台构建（下载嵌入模型 + 向量化，可能需要数分钟）。构建完成后数据保留在 Docker 卷中，后续启动秒级就绪。\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 网页工作台\n\n生产环境中，Docker 的 Node 构建阶段会编译 `web/` 下的 Vue 3 + TypeScript + Vite 应用；FastAPI 随后从 `/static/app/` 提供编译产物。因此 Docker 模式仍只需访问 。\n\n| 路径 | 状态 | 用途 |\n|---|---|---|\n| `/` | 可用 | 与 Pilot 对话、查看执行轨迹与服务状态 |\n| `/admin` | 可用 | 本机开发控制台 |\n| `/knowledge` | WIP | 知识库预览 |\n| `/recipes` | WIP | 配方浏览预览 |\n| `/game-link` | WIP | Fabric Mod 本地游戏连接预览 |\n\n知识库、配方浏览和游戏连接当前只展示能力方向与路线图，不提供独立查询或连接操作。\n\n## Agent 安全与资源边界\n\n- Agent 会直接认真回答安全的通用复杂问题；Minecraft 的版本相关事实和配方问题才按需调用 Wiki/配方工具。\n- 用户消息、历史消息与工具返回均视为不可信数据；工具结果仅作为证据，不能修改身份、语气、工具权限或系统规则。\n- 对话不会提供内部提示、模型/服务配置、部署细节、日志路径或凭据；试图覆盖规则或改变人格/语气的请求会得到稳定的边界回复。\n- 单条消息最多 **12,000** 个字符，超限返回 HTTP `413`，不会调用模型或消耗 Token；每日共享预算为 **750,000 Token**。\n- `/api/chat` 与 `/api/chat/stream` 共享每客户端 IP **20 次/分钟** 的内存级滑动窗口，超限返回 HTTP `429` 与 `Retry-After`。\n- 离线评测语料位于 `tests/fixtures/agent_eval_cases.json`，覆盖复杂回答、工具选择、提示词注入、人格篡改与敏感信息索取；新增真实失败样例时应先加入该语料再修复。\n\n## 更新数据\n\n当 Minecraft 版本更新或 Wiki 内容变化后，可以重新构建数据。\n\n### 更新配方数据\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n配方构建通常较快（约 1–2 分钟）。可通过 `--version` 指定目标版本（默认 26.2）：\n\n```bash\ndocker compose exec app python scripts/build_recipes.py --version 27.0\n```\n\n### 更新 Wiki 索引\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_wiki.py\n\n# 本地模式\n.venv/bin/python scripts/build_wiki.py\n```\n\nWiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟（后续增量运行更快，因为 API 响应有缓存）。看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。可在另一终端确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后应显示 `\"index_exists\":true`。\n\n### 验证更新\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n### 4. 启动 Vue 前端（第二个终端）\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\nVite 开发服务器运行在 ，并将 `/api`、`/health` 与 `/ws` 请求代理到本地 FastAPI 的 `8000` 端口。生产构建使用：\n\n```bash\ncd web\nnpm run build\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成\"构建数据 → 启动应用\"，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 OpenAI 兼容 API 已配置时，解析死亡消息并推送建议。\n\n## 数据来源\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL。\n\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| POST | `/api/chat/stream` | SSE 流式 Agent 响应 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| GET/POST/DELETE | `/api/conversations` | 对话管理 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n## Fabric Mod\n\n要求：JDK 25、Minecraft Java Edition 26.2、本地 Pilot 后端运行在 `127.0.0.1:8000`。\n\nFabric Mod 是本地游戏连接桥：它将 Minecraft Java 实例的日志、玩家事件与世界状态交给 Pilot 使用。网页的 `/game-link` 页面目前是该桥接能力的 WIP 预览；实际连接由安装在客户端 `mods/` 目录中的 Mod 完成。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：`fabric-mod/build/libs/pilot-mod-0.1.0.jar`\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd web\nnpm run build\n\ncd fabric-mod\n./gradlew clean build\n```\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # OpenAI 兼容 API 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # 无前端构建时的 Jinja2 回退页面\n│ └── static/app/ # Vite 生成的 SPA 产物（不提交）\n├── data/ # 预构建配方数据库\n├── scripts/ # 配方、Wiki 与 Docker 初始化脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── web/ # Vue 3 + TypeScript + Vite 前端\n│ └── src/assets/ # 项目内 Logo 与界面图片\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n首次 `docker compose up` 时会自动构建。如需手动触发：\n\n```bash\ndocker compose exec app python scripts/build_wiki.py\n```\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n## 致谢\n\n[Minecraft Wiki 中文](https://zh.minecraft.wiki/api.php) 提供的 MediaWiki API\n\n[FreeFrontend](https://freefrontend.com/css-liquid-glass/) 提供的 Liquid Glass CSS 效果\n"}, "eafe8d41f26abac5ad695d22915214722d7a3104": {"t": 1785772044.4785137, "n": 8861, "h": "b8abc36237a6bcdc", "c": "
\n \"icon\"\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，提供 Vue 3 网页工作台与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、12 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n6. **Vue 工作台**：Vue 3 + TypeScript + Vite 构建的界面，统一承载对话、知识库、配方浏览、游戏连接与控制台导航。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WS| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WS| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## Quick Start\n\n### 1. 前置条件\n\n- Docker Desktop 与 Docker Compose\n- 任意 OpenAI 兼容 API Key\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 克隆并配置\n\n```bash\ngit clone git@github.com:brofea/mc-pilot.git\ncd mc-pilot\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 任意 OpenAI 兼容 API Key\nDEEPSEEK_API_KEY=\n\n# .minecraft 目录；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=\n```\n\n注意：不要把 `.env` 提交到仓库。\n\n仓库中已包含预构建的配方数据库（`data/mc_pilot.db`），无需额外构建。\n\n### 3. 启动\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n首次启动时会自动检查 Qdrant 中是否已有 Wiki 索引。如果没有，会在后台构建（下载嵌入模型 + 向量化，可能需要数分钟）。构建完成后数据保留在 Docker 卷中，后续启动秒级就绪。\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 网页工作台\n\n生产环境中，Docker 的 Node 构建阶段会编译 `web/` 下的 Vue 3 + TypeScript + Vite 应用；FastAPI 随后从 `/static/app/` 提供编译产物。因此 Docker 模式仍只需访问 。\n\n| 路径 | 状态 | 用途 |\n|---|---|---|\n| `/` | 可用 | 与 Pilot 对话、查看执行轨迹与服务状态 |\n| `/admin` | 可用 | 本机开发控制台 |\n| `/knowledge` | WIP | 知识库预览 |\n| `/recipes` | WIP | 配方浏览预览 |\n| `/game-link` | WIP | Fabric Mod 本地游戏连接预览 |\n\n知识库、配方浏览和游戏连接当前只展示能力方向与路线图，不提供独立查询或连接操作。\n\n## 更新数据\n\n当 Minecraft 版本更新或 Wiki 内容变化后，可以重新构建数据。\n\n### 更新配方数据\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n配方构建通常较快（约 1–2 分钟）。可通过 `--version` 指定目标版本（默认 26.2）：\n\n```bash\ndocker compose exec app python scripts/build_recipes.py --version 27.0\n```\n\n### 更新 Wiki 索引\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_wiki.py\n\n# 本地模式\n.venv/bin/python scripts/build_wiki.py\n```\n\nWiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟（后续增量运行更快，因为 API 响应有缓存）。看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。可在另一终端确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后应显示 `\"index_exists\":true`。\n\n### 验证更新\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n### 4. 启动 Vue 前端（第二个终端）\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\nVite 开发服务器运行在 ，并将 `/api`、`/health` 与 `/ws` 请求代理到本地 FastAPI 的 `8000` 端口。生产构建使用：\n\n```bash\ncd web\nnpm run build\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成\"构建数据 → 启动应用\"，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时，解析死亡消息并推送建议。\n\n## 数据来源\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL。\n\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| POST | `/api/chat/stream` | SSE 流式 Agent 响应 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| GET/POST/DELETE | `/api/conversations` | 对话管理 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n## Fabric Mod\n\n要求：JDK 25、Minecraft Java Edition 26.2、本地 Pilot 后端运行在 `127.0.0.1:8000`。\n\nFabric Mod 是本地游戏连接桥：它将 Minecraft Java 实例的日志、玩家事件与世界状态交给 Pilot 使用。网页的 `/game-link` 页面目前是该桥接能力的 WIP 预览；实际连接由安装在客户端 `mods/` 目录中的 Mod 完成。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：`fabric-mod/build/libs/pilot-mod-0.1.0.jar`\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # 无前端构建时的 Jinja2 回退页面\n│ └── static/app/ # Vite 生成的 SPA 产物（不提交）\n├── data/ # 预构建配方数据库\n├── scripts/ # 配方、Wiki 与 Docker 初始化脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── web/ # Vue 3 + TypeScript + Vite 前端\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n首次 `docker compose up` 时会自动构建。如需手动触发：\n\n```bash\ndocker compose exec app python scripts/build_wiki.py\n```\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n## 已知限制\n\n- 数据仅覆盖 Java Edition 26.2 正式版，不承诺其他版本；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 API Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "37cad2ad9ac6fa3a7cae9809eef4f19cbba88fed": {"t": 1785772047.442683, "n": 8861, "h": "1434711a4e49299a", "c": "
\n \"icon\"\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，提供 Vue 3 网页工作台与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、12 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n6. **Vue 工作台**：Vue 3 + TypeScript + Vite 构建的界面，统一承载对话、知识库、配方浏览、游戏连接与控制台导航。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WS| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WS| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## Quick Start\n\n### 1. 前置条件\n\n- Docker Desktop 与 Docker Compose\n- 任意 OpenAI 兼容 API Key\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 克隆并配置\n\n```bash\ngit clone git@github.com:brofea/mc-pilot.git\ncd mc-pilot\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 任意 OpenAI 兼容 API Key\nDEEPSEEK_API_KEY=\n\n# .minecraft 目录；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=\n```\n\n注意：不要把 `.env` 提交到仓库。\n\n仓库中已包含预构建的配方数据库（`data/mc_pilot.db`），无需额外构建。\n\n### 3. 启动\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n首次启动时会自动检查 Qdrant 中是否已有 Wiki 索引。如果没有，会在后台构建（下载嵌入模型 + 向量化，可能需要数分钟）。构建完成后数据保留在 Docker 卷中，后续启动秒级就绪。\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 网页工作台\n\n生产环境中，Docker 的 Node 构建阶段会编译 `web/` 下的 Vue 3 + TypeScript + Vite 应用；FastAPI 随后从 `/static/app/` 提供编译产物。因此 Docker 模式仍只需访问 。\n\n| 路径 | 状态 | 用途 |\n|---|---|---|\n| `/` | 可用 | 与 Pilot 对话、查看执行轨迹与服务状态 |\n| `/admin` | 可用 | 本机开发控制台 |\n| `/knowledge` | WIP | 知识库预览 |\n| `/recipes` | WIP | 配方浏览预览 |\n| `/game-link` | WIP | Fabric Mod 本地游戏连接预览 |\n\n知识库、配方浏览和游戏连接当前只展示能力方向与路线图，不提供独立查询或连接操作。\n\n## 更新数据\n\n当 Minecraft 版本更新或 Wiki 内容变化后，可以重新构建数据。\n\n### 更新配方数据\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n配方构建通常较快（约 1–2 分钟）。可通过 `--version` 指定目标版本（默认 26.2）：\n\n```bash\ndocker compose exec app python scripts/build_recipes.py --version 27.0\n```\n\n### 更新 Wiki 索引\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_wiki.py\n\n# 本地模式\n.venv/bin/python scripts/build_wiki.py\n```\n\nWiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟（后续增量运行更快，因为 API 响应有缓存）。看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。可在另一终端确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后应显示 `\"index_exists\":true`。\n\n### 验证更新\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n### 4. 启动 Vue 前端（第二个终端）\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\nVite 开发服务器运行在 ，并将 `/api`、`/health` 与 `/ws` 请求代理到本地 FastAPI 的 `8000` 端口。生产构建使用：\n\n```bash\ncd web\nnpm run build\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成\"构建数据 → 启动应用\"，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时，解析死亡消息并推送建议。\n\n## 数据来源\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL。\n\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| POST | `/api/chat/stream` | SSE 流式 Agent 响应 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| GET/POST/DELETE | `/api/conversations` | 对话管理 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n## Fabric Mod\n\n要求：JDK 25、Minecraft Java Edition 26.2、本地 Pilot 后端运行在 `127.0.0.1:8000`。\n\nFabric Mod 是本地游戏连接桥：它将 Minecraft Java 实例的日志、玩家事件与世界状态交给 Pilot 使用。网页的 `/game-link` 页面目前是该桥接能力的 WIP 预览；实际连接由安装在客户端 `mods/` 目录中的 Mod 完成。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：`fabric-mod/build/libs/pilot-mod-0.1.0.jar`\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # 无前端构建时的 Jinja2 回退页面\n│ └── static/app/ # Vite 生成的 SPA 产物（不提交）\n├── data/ # 预构建配方数据库\n├── scripts/ # 配方、Wiki 与 Docker 初始化脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── web/ # Vue 3 + TypeScript + Vite 前端\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n首次 `docker compose up` 时会自动构建。如需手动触发：\n\n```bash\ndocker compose exec app python scripts/build_wiki.py\n```\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n## 已知限制\n\n- 数据仅覆盖 Java Edition 26.2 正式版，不承诺其他版本；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 API Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "a2dae357440ec185aa1d4394313b498cbc355d00": {"t": 1785772048.8673894, "n": 8814, "h": "725836d5dcf2353d", "c": "
\n \"icon\"\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、12 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WS| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WS| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：克隆即运行\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查和配方功能仍可用；自然语言对话与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 克隆并配置\n\n```bash\ngit clone mc-pilot\ncd mc-pilot\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n仓库中已包含预构建的配方数据库（`data/mc_pilot.db`），无需额外构建。\n\n### 3. 启动\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n首次启动时会自动检查 Qdrant 中是否已有 Wiki 索引。如果没有，会在后台构建（下载嵌入模型 + 向量化，可能需要数分钟）。构建完成后数据保留在 Docker 卷中，后续启动秒级就绪。\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 更新数据\n\n当 Minecraft 版本更新或 Wiki 内容变化后，可以重新构建数据。\n\n### 更新配方数据\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n配方构建通常较快（约 1–2 分钟）。可通过 `--version` 指定目标版本（默认 26.2）：\n\n```bash\ndocker compose exec app python scripts/build_recipes.py --version 27.0\n```\n\n### 更新 Wiki 索引\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_wiki.py\n\n# 本地模式\n.venv/bin/python scripts/build_wiki.py\n```\n\nWiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟（后续增量运行更快，因为 API 响应有缓存）。看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。可在另一终端确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后应显示 `\"index_exists\":true`。\n\n### 验证更新\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成\"构建数据 → 启动应用\"，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言提问。Agent 自动选择 Function Calling：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `你好` 或打招呼 | Agent 返回功能介绍 | LLM API KEY | 是 |\n| `钻石剑需要什么材料` | Agent 调用 recipe_query | LLM API KEY | 是 |\n| `凋零骷髅在哪生成` | Agent 调用 wiki_search | LLM API KEY | 是 |\n| `查看状态` | Agent 调用 get_status | LLM API KEY | 是 |\n| `/pilot wiki 末地传送门` | 直接检索 Wiki（不走 LLM） | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 直接查配方树（不走 LLM） | 已构建配方数据 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时，解析死亡消息并推送建议。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| POST | `/api/chat/stream` | SSE 流式 Agent 响应 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| GET/POST/DELETE | `/api/conversations` | 对话管理 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n## Fabric Mod\n\n要求：JDK 25、Minecraft Java Edition 26.2、本地 Pilot 后端运行在 `127.0.0.1:8000`。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：`fabric-mod/build/libs/pilot-mod-0.1.0.jar`\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── data/ # 预构建配方数据库\n├── scripts/ # 配方、Wiki 与 Docker 初始化脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n首次 `docker compose up` 时会自动构建。如需手动触发：\n\n```bash\ndocker compose exec app python scripts/build_wiki.py\n```\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n## 已知限制\n\n- 仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "9416bb0acfc5066bcfb89fe821bb6d064881a389": {"t": 1785772050.2766047, "n": 8818, "h": "43c3a1f7d1b45c45", "c": "
\n \"icon\"\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、12 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WS| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WS| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：克隆即运行\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查和配方功能仍可用；自然语言对话与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 克隆并配置\n\n```bash\ngit clone mc-pilot\ncd mc-pilot\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n仓库中已包含预构建的配方数据库（`data/mc_pilot.db`），无需额外构建。\n\n### 3. 启动\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n首次启动时会自动检查 Qdrant 中是否已有 Wiki 索引。如果没有，会在后台构建（下载嵌入模型 + 向量化，可能需要数分钟）。构建完成后数据保留在 Docker 卷中，后续启动秒级就绪。\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 更新数据\n\n当 Minecraft 版本更新或 Wiki 内容变化后，可以重新构建数据。\n\n### 更新配方数据\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n配方构建通常较快（约 1–2 分钟）。可通过 `--version` 指定目标版本（默认 26.2）：\n\n```bash\ndocker compose exec app python scripts/build_recipes.py --version 27.0\n```\n\n### 更新 Wiki 索引\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_wiki.py\n\n# 本地模式\n.venv/bin/python scripts/build_wiki.py\n```\n\nWiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟（后续增量运行更快，因为 API 响应有缓存）。看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。可在另一终端确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后应显示 `\"index_exists\":true`。\n\n### 验证更新\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成\"构建数据 → 启动应用\"，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言提问。Agent 自动选择 Function Calling：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `你好` 或打招呼 | Agent 返回功能介绍 | DeepSeek Key | 是 |\n| `钻石剑需要什么材料` | Agent 调用 recipe_query | DeepSeek Key | 是 |\n| `凋零骷髅在哪生成` | Agent 调用 wiki_search | DeepSeek Key | 是 |\n| `查看状态` | Agent 调用 get_status | DeepSeek Key | 是 |\n| `/pilot wiki 末地传送门` | 直接检索 Wiki（不走 LLM） | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 直接查配方树（不走 LLM） | 已构建配方数据 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时，解析死亡消息并推送建议。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| POST | `/api/chat/stream` | SSE 流式 Agent 响应 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| GET/POST/DELETE | `/api/conversations` | 对话管理 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n## Fabric Mod\n\n要求：JDK 25、Minecraft Java Edition 26.2、本地 Pilot 后端运行在 `127.0.0.1:8000`。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：`fabric-mod/build/libs/pilot-mod-0.1.0.jar`\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── data/ # 预构建配方数据库\n├── scripts/ # 配方、Wiki 与 Docker 初始化脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n首次 `docker compose up` 时会自动构建。如需手动触发：\n\n```bash\ndocker compose exec app python scripts/build_wiki.py\n```\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n## 已知限制\n\n- 仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "66dfe6ef933d5763dea4d0654c735daa75944503": {"t": 1785772052.251044, "n": 9480, "h": "b81c1772c69c1fe3", "c": "
\n \"icon\"\n

Minecraft Pilot Agent

\n

为 MC 26.x 打造的 AI 游戏助手

\n

\n \n \n \n \n \"GitHub\n \n

\n
\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、6 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n
\n \"image\"\n
\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WebSocket| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WebSocket| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：Docker\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查、配方和已构建的 Wiki 检索仍可用；自然语言 Agent 与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n### 3. 启动网页与 Qdrant\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 构建可选数据\n\n首次启动时数据库可以为空。按需要构建：\n\n```bash\n# 官方 26.2 配方数据 → Docker app-data 中的 SQLite\ndocker compose exec app python scripts/build_recipes.py\n\n# 中文 Wiki → Qdrant；首次运行会下载本地嵌入模型\ndocker compose exec app python scripts/build_wiki.py\n\n# DeepSeek 连通性测试\ndocker compose exec app python scripts/test_connectivity.py\n```\n\n配方构建通常较快。Wiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟；看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。不要把终端工具超时或窗口断开误判成构建成功，可在另一终端用后台接口确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后，两个接口应分别显示已有配方数据和 `\"index_exists\":true`。还可以发起不经过前端的真实查询：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n`app-data` 和 `qdrant-data` 是命名卷；SQLite、Wiki API 缓存和 Hugging Face 模型缓存会在容器重建后保留。Minecraft 目录仅以只读方式挂载。\n\n### 5. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 本地开发\n\n本项目只使用 `pip`、`.venv` 和 Docker，不使用 conda。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成“构建数据 → 启动应用”，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言和 `/pilot` 子命令：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `/pilot wiki 末地传送门` | 直接检索 Wiki 片段并附来源 | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 返回确定性配方树与基础材料 | 已构建配方数据 | 否 |\n| `/pilot 如何获得鞘翅？` | Agent 自主选择 Wiki/配方工具 | DeepSeek Key；相关数据按问题准备 | 是 |\n| `你好，你能做什么？` | 普通 Agent 对话 | DeepSeek Key | 是 |\n| `/pilot status` | 显示模型与 token 用量 | 无 | 否 |\n| `/pilot clear` | 清除进程内短期记忆 | 无 | 否 |\n| `/pilot help` | 显示命令帮助 | 无 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时：\n\n1. 解析简体中文或英文死亡消息；\n2. 忽略其他玩家并去重重复事件；\n3. 不调用 Wiki 或配方工具；\n4. 生成 2–5 句短建议；\n5. 通过 `/ws` 推送到网页并自动淡出。\n\n日志路径不能在当前网页里编辑。Docker 模式修改 `MC_PILOT_MINECRAFT_DIR`；本地模式可设置 `MC_PILOT_GAME_LOG_PATH`，然后重启应用。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限；\n- 镜像：可通过 `build_recipes.py --mirror ` 显式提供失败回退源，最终仍必须通过官方 SHA-1。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL；当前 `/pilot wiki` 返回检索片段与来源，不额外调用 LLM 改写。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。`rebuild-wiki` 接口目前返回 `not_implemented`，真实索引构建请使用 `scripts/build_wiki.py`。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n配方树示例：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/recipes/tree \\\n -H 'Content-Type: application/json' \\\n -d '{\"item_id\":\"minecraft:diamond_sword\",\"quantity\":1,\"max_depth\":3}'\n```\n\n## Fabric Mod\n\n要求：\n\n- JDK 25；\n- Minecraft Java Edition 26.2；\n- 本地 Pilot 后端运行在 `127.0.0.1:8000`；\n- Gradle 9.5.1 由仓库 Wrapper 提供，无需安装主机 Gradle。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：\n\n```text\nfabric-mod/build/libs/pilot-mod-0.1.0.jar\n```\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。Mod 只注册本地 `/pilot` 客户端命令、发送 HTTP 请求、接收 WebSocket 事件并渲染本地聊天消息；知识、配方和推理逻辑仍在 Python 后端。API Key 不进入 Mod。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n自动化测试覆盖配方解析与递归树、官方哈希、SQLite、Wiki 分块与检索、Agent 工具与预算、双语死亡解析、日志轮转/截断、API 降级、WebSocket 清理、Docker 挂载、后台访问控制及 secret 脱敏。\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── scripts/ # 配方、Wiki 与模型连通性脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n本地开发模式确认 `.env` 中 `MC_PILOT_QDRANT_URL=http://localhost:6333`。\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n运行对应模式的 `build_wiki.py`。首次加载嵌入模型需要网络和较长时间；不要在中途删除 Qdrant volume。\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。容器内可检查：\n\n```bash\ndocker compose exec app test -r /minecraft/logs/latest.log\n```\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n日志只应记录模型、耗时和脱敏后的用量，不应出现 API Key。\n\n## 已知限制\n\n- 仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 网页后台尚不能输入任意日志路径，也不能直接重建 Wiki；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "e2fc4a2f9828faf28516e648fb652a8be8ede948": {"t": 1785772053.9752429, "n": 9179, "h": "0d2ffbc15bafedce", "c": "# Minecraft Pilot Agent\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n## 项目状态\n\n| 项目 | 状态 |\n|---|---|\n| 网页 MVP | 已完成，可通过 Docker 或本地 Python 运行 |\n| 中文 Wiki RAG | 已实现，需要先构建 Qdrant 索引 |\n| 官方配方与 N 层配方树 | 已实现，需要先构建 SQLite 数据 |\n| 本地死亡日志建议 | 已实现，需要 Minecraft 日志和 DeepSeek API |\n| Fabric 26.2 Mod | 已完成源码与可复现构建，属于第二阶段加分项 |\n| 支持版本 | 仅 Minecraft Java Edition 26.2 正式版 |\n\n当前质量门：Ruff 通过、Mypy strict 通过、`121 passed`、Docker Compose 配置校验通过、Fabric Wrapper 构建通过。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、6 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WebSocket| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WebSocket| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：Docker（推荐交付方式）\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查、配方和已构建的 Wiki 检索仍可用；自然语言 Agent 与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n### 3. 启动网页与 Qdrant\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 构建可选数据\n\n首次启动时数据库可以为空。按需要构建：\n\n```bash\n# 官方 26.2 配方数据 → Docker app-data 中的 SQLite\ndocker compose exec app python scripts/build_recipes.py\n\n# 中文 Wiki → Qdrant；首次运行会下载本地嵌入模型\ndocker compose exec app python scripts/build_wiki.py\n\n# DeepSeek 连通性测试\ndocker compose exec app python scripts/test_connectivity.py\n```\n\n配方构建通常较快。Wiki 构建会抓取九类页面并在 CPU 上生成数千条向量，首次运行可能需要数十分钟；看到连续的 Qdrant `points ... 200 OK` 属于正常进度，请等待终端出现 `Wiki index built` 并返回命令提示符。不要把终端工具超时或窗口断开误判成构建成功，可在另一终端用后台接口确认：\n\n```bash\ncurl http://127.0.0.1:8000/admin/api/recipes\ncurl http://127.0.0.1:8000/admin/api/rag\n```\n\n构建完成后，两个接口应分别显示已有配方数据和 `\"index_exists\":true`。还可以发起不经过前端的真实查询：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot recipe minecraft:crafting_table\"}'\n\ncurl -X POST http://127.0.0.1:8000/api/chat \\\n -H 'Content-Type: application/json' \\\n -d '{\"message\":\"/pilot wiki 石头\"}'\n```\n\n`app-data` 和 `qdrant-data` 是命名卷；SQLite、Wiki API 缓存和 Hugging Face 模型缓存会在容器重建后保留。Minecraft 目录仅以只读方式挂载。\n\n### 5. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 本地开发模式\n\n本项目只使用 `pip`、`.venv` 和 Docker，**不要使用 conda**。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成“构建数据 → 启动应用”，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言和 `/pilot` 子命令：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `/pilot wiki 末地传送门` | 直接检索 Wiki 片段并附来源 | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 返回确定性配方树与基础材料 | 已构建配方数据 | 否 |\n| `/pilot 如何获得鞘翅？` | Agent 自主选择 Wiki/配方工具 | DeepSeek Key；相关数据按问题准备 | 是 |\n| `你好，你能做什么？` | 普通 Agent 对话 | DeepSeek Key | 是 |\n| `/pilot status` | 显示模型与 token 用量 | 无 | 否 |\n| `/pilot clear` | 清除进程内短期记忆 | 无 | 否 |\n| `/pilot help` | 显示命令帮助 | 无 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时：\n\n1. 解析简体中文或英文死亡消息；\n2. 忽略其他玩家并去重重复事件；\n3. 不调用 Wiki 或配方工具；\n4. 生成 2–5 句短建议；\n5. 通过 `/ws` 推送到网页并自动淡出。\n\n日志路径不能在当前网页里编辑。Docker 模式修改 `MC_PILOT_MINECRAFT_DIR`；本地模式可设置 `MC_PILOT_GAME_LOG_PATH`，然后重启应用。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限；\n- 镜像：可通过 `build_recipes.py --mirror ` 显式提供失败回退源，最终仍必须通过官方 SHA-1。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL；当前 `/pilot wiki` 返回检索片段与来源，不额外调用 LLM 改写。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。`rebuild-wiki` 接口目前返回 `not_implemented`，真实索引构建请使用 `scripts/build_wiki.py`。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n配方树示例：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/recipes/tree \\\n -H 'Content-Type: application/json' \\\n -d '{\"item_id\":\"minecraft:diamond_sword\",\"quantity\":1,\"max_depth\":3}'\n```\n\n## Fabric Mod（第二阶段加分项）\n\n要求：\n\n- JDK 25；\n- Minecraft Java Edition 26.2；\n- 本地 Pilot 后端运行在 `127.0.0.1:8000`；\n- Gradle 9.5.1 由仓库 Wrapper 提供，无需安装主机 Gradle。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：\n\n```text\nfabric-mod/build/libs/pilot-mod-0.1.0.jar\n```\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。Mod 只注册本地 `/pilot` 客户端命令、发送 HTTP 请求、接收 WebSocket 事件并渲染本地聊天消息；知识、配方和推理逻辑仍在 Python 后端。API Key 不进入 Mod。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n自动化测试覆盖配方解析与递归树、官方哈希、SQLite、Wiki 分块与检索、Agent 工具与预算、双语死亡解析、日志轮转/截断、API 降级、WebSocket 清理、Docker 挂载、后台访问控制及 secret 脱敏。\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── scripts/ # 配方、Wiki 与模型连通性脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n本地开发模式确认 `.env` 中 `MC_PILOT_QDRANT_URL=http://localhost:6333`。\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n运行对应模式的 `build_wiki.py`。首次加载嵌入模型需要网络和较长时间；不要在中途删除 Qdrant volume。\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。容器内可检查：\n\n```bash\ndocker compose exec app test -r /minecraft/logs/latest.log\n```\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n日志只应记录模型、耗时和脱敏后的用量，不应出现 API Key。\n\n## 已知限制\n\n- 仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 网页后台尚不能输入任意日志路径，也不能直接重建 Wiki；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "cd9a82b73daa5df16098533959b585fd9eaf6d64": {"t": 1785772055.3130357, "n": 8561, "h": "c019e16e459a77e8", "c": "# Minecraft Pilot Agent\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。将中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n## 项目状态\n\n| 项目 | 状态 |\n|---|---|\n| 网页 MVP | 已完成，可通过 Docker 或本地 Python 运行 |\n| 中文 Wiki RAG | 已实现，需要先构建 Qdrant 索引 |\n| 官方配方与 N 层配方树 | 已实现，需要先构建 SQLite 数据 |\n| 本地死亡日志建议 | 已实现，需要 Minecraft 日志和 DeepSeek API |\n| Fabric 26.2 Mod | 已完成源码与可复现构建，属于第二阶段加分项 |\n| 支持版本 | 仅 Minecraft Java Edition 26.2 正式版 |\n\n当前质量门：Ruff 通过、Mypy strict 通过、`116 passed`、Docker 健康检查通过、Fabric Wrapper 构建通过。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、6 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WebSocket| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WebSocket| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：Docker（推荐交付方式）\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查、配方和已构建的 Wiki 检索仍可用；自然语言 Agent 与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n### 3. 启动网页与 Qdrant\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 构建可选数据\n\n首次启动时数据库可以为空。按需要构建：\n\n```bash\n# 官方 26.2 配方数据 → Docker app-data 中的 SQLite\ndocker compose exec app python scripts/build_recipes.py\n\n# 中文 Wiki → Qdrant；首次运行会下载本地嵌入模型\ndocker compose exec app python scripts/build_wiki.py\n\n# DeepSeek 连通性测试\ndocker compose exec app python scripts/test_connectivity.py\n```\n\n`app-data` 和 `qdrant-data` 是命名卷；SQLite、Wiki API 缓存和 Hugging Face 模型缓存会在容器重建后保留。Minecraft 目录仅以只读方式挂载。\n\n### 5. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 本地开发模式\n\n本项目只使用 `pip`、`.venv` 和 Docker，**不要使用 conda**。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成“构建数据 → 启动应用”，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言和 `/pilot` 子命令：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `/pilot wiki 末地传送门` | 直接检索 Wiki 片段并附来源 | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 返回确定性配方树与基础材料 | 已构建配方数据 | 否 |\n| `/pilot 如何获得鞘翅？` | Agent 自主选择 Wiki/配方工具 | DeepSeek Key；相关数据按问题准备 | 是 |\n| `你好，你能做什么？` | 普通 Agent 对话 | DeepSeek Key | 是 |\n| `/pilot status` | 显示模型与 token 用量 | 无 | 否 |\n| `/pilot clear` | 清除进程内短期记忆 | 无 | 否 |\n| `/pilot help` | 显示命令帮助 | 无 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时：\n\n1. 解析简体中文或英文死亡消息；\n2. 忽略其他玩家并去重重复事件；\n3. 不调用 Wiki 或配方工具；\n4. 生成 2–5 句短建议；\n5. 通过 `/ws` 推送到网页并自动淡出。\n\n日志路径不能在当前网页里编辑。Docker 模式修改 `MC_PILOT_MINECRAFT_DIR`；本地模式可设置 `MC_PILOT_GAME_LOG_PATH`，然后重启应用。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限；\n- 镜像：可通过 `build_recipes.py --mirror ` 显式提供失败回退源，最终仍必须通过官方 SHA-1。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL；当前 `/pilot wiki` 返回检索片段与来源，不额外调用 LLM 改写。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。`rebuild-wiki` 接口目前返回 `not_implemented`，真实索引构建请使用 `scripts/build_wiki.py`。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n配方树示例：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/recipes/tree \\\n -H 'Content-Type: application/json' \\\n -d '{\"item_id\":\"minecraft:diamond_sword\",\"quantity\":1,\"max_depth\":3}'\n```\n\n## Fabric Mod（第二阶段加分项）\n\n要求：\n\n- JDK 25；\n- Minecraft Java Edition 26.2；\n- 本地 Pilot 后端运行在 `127.0.0.1:8000`；\n- Gradle 9.5.1 由仓库 Wrapper 提供，无需安装主机 Gradle。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：\n\n```text\nfabric-mod/build/libs/pilot-mod-0.1.0.jar\n```\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。Mod 只注册本地 `/pilot` 客户端命令、发送 HTTP 请求、接收 WebSocket 事件并渲染本地聊天消息；知识、配方和推理逻辑仍在 Python 后端。API Key 不进入 Mod。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n自动化测试覆盖配方解析与递归树、官方哈希、SQLite、Wiki 分块与检索、Agent 工具与预算、双语死亡解析、日志轮转/截断、API 降级、WebSocket 清理、Docker 挂载、后台访问控制及 secret 脱敏。\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── scripts/ # 配方、Wiki 与模型连通性脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n本地开发模式确认 `.env` 中 `MC_PILOT_QDRANT_URL=http://localhost:6333`。\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n运行对应模式的 `build_wiki.py`。首次加载嵌入模型需要网络和较长时间；不要在中途删除 Qdrant volume。\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。容器内可检查：\n\n```bash\ndocker compose exec app test -r /minecraft/logs/latest.log\n```\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n日志只应记录模型、耗时和脱敏后的用量，不应出现 API Key。\n\n## 已知限制\n\n- 仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 网页后台尚不能输入任意日志路径，也不能直接重建 Wiki；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n"}, "4e8f0dc9a96a585ccd5d80817b8ae56ae98f0c8d": {"t": 1785772056.7639613, "n": 8878, "h": "12cfe1b29e54e179", "c": "# Minecraft Pilot Agent\n\n面向 Minecraft Java Edition 26.2 的本地游戏助手。项目把中文 Wiki RAG、官方配方数据和本地游戏日志接到一个轻量 Agent 后端，并提供网页界面与可选的 Fabric 客户端 Mod。\n\n> 这是非官方课程设计项目，与 Mojang、Microsoft 或 Minecraft Wiki 无隶属关系。\n\n## 项目状态\n\n| 项目 | 状态 |\n|---|---|\n| 网页 MVP | 已完成，可通过 Docker 或本地 Python 运行 |\n| 中文 Wiki RAG | 已实现，需要先构建 Qdrant 索引 |\n| 官方配方与 N 层配方树 | 已实现，需要先构建 SQLite 数据 |\n| 本地死亡日志建议 | 已实现，需要 Minecraft 日志和 DeepSeek API |\n| Fabric 26.2 Mod | 已完成源码与可复现构建，属于第二阶段加分项 |\n| 支持版本 | 仅 Minecraft Java Edition 26.2 正式版 |\n\n当前质量门：Ruff 通过、Mypy strict 通过、`116 passed`、Docker 健康检查通过、Fabric Wrapper 构建通过。\n\n## 核心能力\n\n1. **中文 Wiki RAG**：通过 `https://zh.minecraft.wiki/api.php` 采集白名单分类，使用 `BAAI/bge-small-zh-v1.5` 向量化并存入 Qdrant，查询结果保留页面 URL 与 revision ID。\n2. **确定性配方树**：从 Mojang 官方版本清单下载 26.2 客户端 JAR，校验 SHA-1，提取配方、标签与语言资源，再由代码计算直接配方、N 层材料树和叶子材料汇总；LLM 不参与数量计算。\n3. **游戏日志分析**：只读监听本地 `latest.log`，识别本地玩家和简中/英文死亡消息，每次有效死亡最多调用一次 DeepSeek，并通过 WebSocket 推送一条短建议。\n4. **轻量 Agent**：支持自然语言、MCP 风格 Function Calling、6 轮短期记忆、工具白名单、调用轮次限制与 token 预算。\n5. **开发者后台**：展示系统、游戏、配方、RAG、LLM 和脱敏配置状态；仅允许本机访问。\n\n## 架构\n\n```mermaid\nflowchart LR\n Web[网页客户端] -->|HTTP / WebSocket| API[FastAPI 后端]\n Mod[Fabric 26.2 Mod] -->|HTTP / WebSocket| API\n API --> Agent[轻量 Agent 状态机]\n Agent -->|Function Calling| Recipes[配方服务]\n Agent -->|Function Calling| RAG[Wiki RAG]\n Agent --> DeepSeek[DeepSeek 兼容 API]\n Recipes --> SQLite[(SQLite)]\n RAG --> Qdrant[(Qdrant)]\n Log[latest.log] --> Game[日志监听与死亡解析]\n Game --> DeepSeek\n Game --> API\n```\n\n## 快速开始：Docker（推荐交付方式）\n\n### 1. 前置条件\n\n- macOS 优先；Linux 也可运行网页、RAG 和配方功能\n- Docker Desktop 与 Docker Compose\n- 可选：DeepSeek API Key。没有 Key 时，网页、健康检查、配方和已构建的 Wiki 检索仍可用；自然语言 Agent 与死亡建议不可用\n- 若要监听游戏日志，本机需安装并运行 Minecraft Java Edition 26.2\n\n### 2. 配置环境变量\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```dotenv\n# 可选，但自然语言 Agent 和死亡建议需要它\nDEEPSEEK_API_KEY=你的_API_Key\n\n# macOS Minecraft 目录。请替换成真实用户名；路径中可以包含空格\nMC_PILOT_MINECRAFT_DIR=/Users/你的用户名/Library/Application Support/minecraft\n```\n\n不要把 `.env` 提交到 Git。项目不会在网页或日志中返回 API Key。\n\n### 3. 启动网页与 Qdrant\n\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\n验证：\n\n```bash\ncurl http://127.0.0.1:8000/health/live\ncurl http://127.0.0.1:8000/health/ready\n```\n\n预期结果：\n\n- `live` 返回 `{\"status\":\"alive\",\"version\":\"0.1.0\"}`；\n- `ready` 中 SQLite 和 Qdrant 均为 `ready`；\n- 浏览器可访问 ；\n- 开发者后台可访问 ；\n- OpenAPI 文档可访问 。\n\n### 4. 构建可选数据\n\n首次启动时数据库可以为空。按需要构建：\n\n```bash\n# 官方 26.2 配方数据 → Docker app-data 中的 SQLite\ndocker compose exec app python scripts/build_recipes.py\n\n# 中文 Wiki → Qdrant；首次运行会下载本地嵌入模型\ndocker compose exec app python scripts/build_wiki.py\n\n# DeepSeek 连通性测试\ndocker compose exec app python scripts/test_connectivity.py\n```\n\n`app-data` 和 `qdrant-data` 是命名卷；SQLite、Wiki API 缓存和 Hugging Face 模型缓存会在容器重建后保留。Minecraft 目录仅以只读方式挂载。\n\n### 5. 停止服务\n\n```bash\ndocker compose down\n```\n\n这不会删除数据卷。只有明确执行 `docker compose down -v` 才会删除本地项目数据。\n\n## 本地开发模式\n\n本项目只使用 `pip`、`.venv` 和 Docker，**不要使用 conda**。\n\n### 1. Python 环境\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n```\n\n如果系统命令名是 `python3`，先用 `python3 --version` 确认版本为 3.12。\n\n### 2. 只启动 Qdrant\n\n```bash\ndocker compose up -d qdrant\n```\n\n### 3. 构建数据并启动 FastAPI\n\n```bash\n.venv/bin/python scripts/build_recipes.py\n.venv/bin/python scripts/build_wiki.py\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --host 127.0.0.1 --port 8000\n```\n\n本地模式与全 Docker 模式使用不同的 SQLite 存储位置。请选择一种模式完成“构建数据 → 启动应用”，不要在宿主机生成数据后期待 Docker volume 自动同步。\n\n## 使用方式\n\n网页输入框接受自然语言和 `/pilot` 子命令：\n\n| 输入 | 行为 | 前置条件 | 消耗 LLM |\n|---|---|---|---|\n| `/pilot wiki 末地传送门` | 直接检索 Wiki 片段并附来源 | 已构建 Wiki 索引 | 否 |\n| `/pilot recipe minecraft:bow` | 返回确定性配方树与基础材料 | 已构建配方数据 | 否 |\n| `/pilot 如何获得鞘翅？` | Agent 自主选择 Wiki/配方工具 | DeepSeek Key；相关数据按问题准备 | 是 |\n| `你好，你能做什么？` | 普通 Agent 对话 | DeepSeek Key | 是 |\n| `/pilot status` | 显示模型与 token 用量 | 无 | 否 |\n| `/pilot clear` | 清除进程内短期记忆 | 无 | 否 |\n| `/pilot help` | 显示命令帮助 | 无 | 否 |\n\n配方物品建议使用完整资源 ID，例如 `minecraft:enchanting_table`。\n\n### 死亡建议\n\nDocker 模式从只读挂载的 `/minecraft/logs/latest.log` 读取新增内容；本地模式默认检查：\n\n```text\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n当日志存在、识别到本地玩家且 DeepSeek 已配置时：\n\n1. 解析简体中文或英文死亡消息；\n2. 忽略其他玩家并去重重复事件；\n3. 不调用 Wiki 或配方工具；\n4. 生成 2–5 句短建议；\n5. 通过 `/ws` 推送到网页并自动淡出。\n\n日志路径不能在当前网页里编辑。Docker 模式修改 `MC_PILOT_MINECRAFT_DIR`；本地模式可设置 `MC_PILOT_GAME_LOG_PATH`，然后重启应用。\n\n## 数据来源与确定性边界\n\n### 配方\n\n- 信任根：Mojang 官方版本清单与客户端 JAR SHA-1；\n- 当前构建目标：Java Edition 26.2 `release`；\n- 提取内容：配方 JSON、物品标签和必要语言资源；\n- 计算方式：代码递归遍历，含深度、循环与节点上限；\n- 镜像：可通过 `build_recipes.py --mirror ` 显式提供失败回退源，最终仍必须通过官方 SHA-1。\n\n### Wiki\n\n- API：`https://zh.minecraft.wiki/api.php`；\n- 默认白名单：方块、物品、生物、群系、游戏规则、附魔、状态效果、结构与命令；\n- 排除基岩版、教育版、快照、开发版和版本记录等页面；\n- 检索结果包含来源 URL；当前 `/pilot wiki` 返回检索片段与来源，不额外调用 LLM 改写。\n\n## 开发者后台\n\n 展示：\n\n- 系统版本与运行环境；\n- 游戏连接、玩家、日志和死亡次数；\n- 配方版本；\n- RAG、LLM 与 Agent 配置状态；\n- 经 `Settings.safe_summary()` 脱敏后的配置；\n- 健康检查与日志重连操作。\n\n后台仅允许 loopback Host。`rebuild-wiki` 接口目前返回 `not_implemented`，真实索引构建请使用 `scripts/build_wiki.py`。\n\n## API 摘要\n\n完整交互式文档见 。\n\n| 方法 | 路径 | 用途 |\n|---|---|---|\n| GET | `/health/live` | 进程存活 |\n| GET | `/health/ready` | SQLite/Qdrant 就绪状态 |\n| POST | `/api/chat` | Agent 与 `/pilot` 命令入口 |\n| GET | `/api/agent-status` | 模型是否配置 |\n| GET | `/api/recipes/{item_id}` | 直接配方查询 |\n| POST | `/api/recipes/tree` | 数量与深度可配置的配方树 |\n| GET | `/api/game-state` | 当前游戏状态 |\n| WS | `/ws` | 状态心跳与死亡建议 |\n| GET | `/admin/api/*` | 本机开发诊断接口 |\n\n配方树示例：\n\n```bash\ncurl -X POST http://127.0.0.1:8000/api/recipes/tree \\\n -H 'Content-Type: application/json' \\\n -d '{\"item_id\":\"minecraft:diamond_sword\",\"quantity\":1,\"max_depth\":3}'\n```\n\n## Fabric Mod（第二阶段加分项）\n\n要求：\n\n- JDK 25；\n- Minecraft Java Edition 26.2；\n- 本地 Pilot 后端运行在 `127.0.0.1:8000`；\n- Gradle 9.5.1 由仓库 Wrapper 提供，无需安装主机 Gradle。\n\n构建：\n\n```bash\ncd fabric-mod\n./gradlew clean build\n```\n\n产物：\n\n```text\nfabric-mod/build/libs/pilot-mod-0.1.0.jar\n```\n\n将 JAR 放入对应 Fabric 客户端的 `mods/` 目录。Mod 只注册本地 `/pilot` 客户端命令、发送 HTTP 请求、接收 WebSocket 事件并渲染本地聊天消息；知识、配方和推理逻辑仍在 Python 后端。API Key 不进入 Mod。\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n\ncd fabric-mod\n./gradlew clean build\n```\n\n自动化测试覆盖配方解析与递归树、官方哈希、SQLite、Wiki 分块与检索、Agent 工具与预算、双语死亡解析、日志轮转/截断、API 降级、WebSocket 清理、Docker 挂载、后台访问控制及 secret 脱敏。\n\n## 项目结构\n\n```text\n.\n├── src/mc_pilot/\n│ ├── agent/ # DeepSeek 客户端、状态机、记忆与工具契约\n│ ├── api/ # HTTP 与 WebSocket 适配层\n│ ├── game/ # 日志发现、尾随、死亡解析与建议\n│ ├── rag/ # MediaWiki 采集、分块、嵌入、Qdrant 检索\n│ ├── recipes/ # 官方数据下载、提取、SQLite 与配方树\n│ ├── admin/ # 本机开发诊断 API\n│ ├── templates/ # Jinja2 页面\n│ └── static/ # 原生 JavaScript 与 CSS\n├── scripts/ # 配方、Wiki 与模型连通性脚本\n├── tests/ # 离线确定性测试\n├── fabric-mod/ # Fabric 26.2 客户端 Mod\n├── docs/ # 课程要求与实验报告\n├── compose.yaml\n├── Dockerfile\n└── pyproject.toml\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `DEEPSEEK_API_KEY` | 空 | 自然语言 Agent 和死亡建议所需 |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容 API 根地址 |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 发送给兼容 API 的模型名，可覆盖 |\n| `MC_PILOT_HOST` | `127.0.0.1` | 本地运行绑定地址；Compose 内覆盖为 `0.0.0.0` |\n| `MC_PILOT_PORT` | `8000` | HTTP 端口 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite URL |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant URL；Compose 内覆盖为服务名 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | 健康探针超时 |\n| `MC_PILOT_GAME_LOG_PATH` | 空 | 本地运行时覆盖 `latest.log` 路径 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认目录 | Compose 只读挂载源；不是 Pydantic 应用配置 |\n\n## 故障排查\n\n### `ready` 显示 Qdrant degraded\n\n```bash\ndocker compose ps\ndocker compose logs qdrant\n```\n\n本地开发模式确认 `.env` 中 `MC_PILOT_QDRANT_URL=http://localhost:6333`。\n\n### 配方查询为空\n\n确认数据构建发生在当前运行模式：\n\n```bash\n# Docker 模式\ndocker compose exec app python scripts/build_recipes.py\n\n# 本地模式\n.venv/bin/python scripts/build_recipes.py\n```\n\n### Wiki 提示知识库尚未构建\n\n运行对应模式的 `build_wiki.py`。首次加载嵌入模型需要网络和较长时间；不要在中途删除 Qdrant volume。\n\n### Docker 无法读取 Minecraft 目录\n\n确认 `.env` 中路径真实存在，并在 Docker Desktop 中允许访问该 macOS 目录。容器内可检查：\n\n```bash\ndocker compose exec app test -r /minecraft/logs/latest.log\n```\n\n### Agent 请求失败\n\n```bash\ndocker compose exec app python scripts/test_connectivity.py\ndocker compose logs --tail=100 app\n```\n\n日志只应记录模型、耗时和脱敏后的用量，不应出现 API Key。\n\n## 已知限制\n\n- 本次验收仅覆盖 Java Edition 26.2 正式版，不承诺其他 26.x 版本；\n- 网页后台尚不能输入任意日志路径，也不能直接重建 Wiki；\n- 会话记忆保存在当前后端进程内，服务重启后清空；\n- Wiki 采用白名单分类，不等于抓取整个中文 Minecraft Wiki；\n- 未提供真实 DeepSeek Key 时，自动化测试不会证明线上模型账户与额度可用；\n- Fabric Mod 当前固定连接 `127.0.0.1:8000`。\n\n## 课程材料\n\n- [实验报告](docs/实验报告.md)\n- [实验报告提交及评分标准](docs/实验报告提交及评分标准.md)\n- [课程说明](docs/instruction.md)\n\n## License 与第三方内容\n\n仓库代码的许可证以项目实际发布文件为准。Minecraft、Mojang、Microsoft、中文 Minecraft Wiki、Fabric、DeepSeek、Qdrant 与所用模型分别受其自身条款约束；提交课程作业或公开部署前，请保留来源、许可和非官方声明。\n"}, "332c316fdd426e3fc42488a0a77cb7e7d2005156": {"t": 1785772058.3766537, "n": 11566, "h": "8bfa1e78219a168e", "c": "# Minecraft Pilot Agent\n\nMinecraft Pilot 是一个面向 Minecraft Java Edition 26.2 的本地游戏助手。结合中文 Wiki RAG、确定性配方树和游戏日志分析，通过网页聊天和 Fabric Mod 为玩家提供帮助。\n\n**非官方课程项目**，与 Mojang 或 Microsoft 无关。\n\n---\n\n## 目录\n\n- [QuickStart](#quickstart)\n- [功能概览](#功能概览)\n- [使用教程](#使用教程)\n- [技术栈](#技术栈)\n- [项目结构](#项目结构)\n- [环境变量](#环境变量)\n- [质量检查](#质量检查)\n- [API 文档](#api-文档)\n- [Fabric Mod](#fabric-mod-可选)\n- [数据构建](#数据构建)\n\n---\n\n## QuickStart\n\n从头开始，三步跑通。\n\n### 第一步：环境准备\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/[用户名]/mc-pilot.git\ncd mc-pilot\n\n# 2. 创建虚拟环境并安装依赖\npython3 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\n\n# 3. 配置 API 密钥\ncp .env.example .env\n# 编辑 .env，将 DEEPSEEK_API_KEY= 后面填上你的 DeepSeek API 密钥\n# macOS 使用 Docker 时，将 MC_PILOT_MINECRAFT_DIR 改为当前用户的 Minecraft 目录\n# 获取密钥: https://platform.deepseek.com/api_keys\n```\n\n> **注意** 本项目使用 pip + .venv，**不使用 conda**。macOS / Linux 均可，Windows 需自行调整路径分隔符。\n\n### 第二步：启动服务\n\n```bash\n# 4. 启动 Qdrant 向量数据库（需要 Docker）\ndocker compose up -d qdrant\n\n# 5. 启动 Pilot 后端\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --reload --host 127.0.0.1 --port 8000\n```\n\n> 如果不想手动分步启动，也可以一条命令拉起全部服务：\n> ```bash\n> docker compose up --build\n> ```\n\n### 第三步：打开网页\n\n浏览器打开 http://127.0.0.1:8000\n\n你应该看到 **Minecraft Pilot** 主页面，聊天框里已有欢迎消息。此时页面右上角应显示绿色的\"就绪\"状态。\n\n**验证连接**：\n```bash\ncurl http://127.0.0.1:8000/health/ready\n# {\"status\":\"ready\",\"components\":[{\"name\":\"sqlite\",\"status\":\"ready\",...},{\"name\":\"qdrant\",\"status\":\"ready\",...}]}\n```\n\n---\n\n## 功能概览\n\n完成 QuickStart 后，你有四条核心使用路径：\n\n| 序号 | 能力 | 需要什么 | 如何使用 |\n|---|---|---|---|\n| 1 | Agent 对话 | DeepSeek API Key | 在网页输入框输入问题 |\n| 2 | 配方查询 | 先运行 `build_recipes` | `/pilot recipe <物品ID>` |\n| 3 | Wiki 问答 | 先运行 `build_wiki` | `/pilot wiki <关键词>` |\n| 4 | 死亡建议 | 启动 Minecraft 26.2 并打开日志监听 | 游戏中死亡时自动触发 |\n\n### 能力 1：Agent 智能对话\n\n当你配置了 `DEEPSEEK_API_KEY`，Agent 立即可用。无需额外数据。\n\n```\n在网页输入框中输入：\n/pilot 如何合成附魔台？\n```\n\nAgent 会自动调用 `wiki_search` 查询知识库，或调用 `recipe_query` 查询配方，然后用中文回复。\n\n**首次验证**：先运行连通性测试确认模型可访问：\n```bash\n.venv/bin/python scripts/test_connectivity.py\n# 预期输出：Connectivity OK model=deepseek-v4-flash latency_ms=850\n```\n\n### 能力 2：确定性配方查询\n\n需要先构建本地配方数据库（需要网络，约 100MB 下载）：\n\n```bash\n# 从 Mojang CDN 下载 Java 26.2 客户端 JAR，提取配方到 SQLite\n.venv/bin/python scripts/build_recipes.py\n```\n\n然后在网页中输入：\n```\n/pilot recipe minecraft:enchanting_table\n```\n\nAgent 会返回附魔台所需的全部材料：黑曜石 ×4、钻石 ×2、书 ×1。配方树是完全确定性计算的，不依赖模型生成。\n\n### 能力 3：Wiki 知识问答\n\n需要先构建 Wiki 索引（需要网络，首次约 5-10 分钟，需要约 2GB 模型下载）：\n\n```bash\n# 从中文 Minecraft Wiki API 采集知识，嵌入到 Qdrant\n.venv/bin/python scripts/build_wiki.py\n```\n\n然后在网页中输入：\n```\n/pilot wiki 凋零骷髅在哪生成？\n```\n\nAgent 从 Qdrant 检索相关 Wiki 片段，整合后返回带来源 URL 的回答。\n\n### 能力 4：死亡建议（自动触发）\n\n这是**自动触发**的能力，无需手动调用。\n\n1. 确认后端正在运行\n2. 启动 **Minecraft Java Edition 26.2**（单人生存模式）\n3. 在网页上，你应看到右上角状态从\"未连接游戏\"变为\"玩家名 · 26.2\"\n4. 当玩家角色在游戏中死亡时，网页会弹出红色气泡，显示 2-5 句生存建议\n\n如果未能自动检测到游戏日志，在网页开发后台手动指定日志路径：\nhttp://127.0.0.1:8000/admin → 重连日志\n\n---\n\n## 使用教程\n\n### 网页聊天（主界面）\n\n打开 http://127.0.0.1:8000\n\n```\n┌─────────────────────────────────────────┐\n│ Minecraft Pilot │\n│ Java Edition 26.2 │\n├─────────────────────────────────────────┤\n│ Pilot 对话 [玩家 · 26.2] [就绪] │\n│ │\n│ ┌─ Pilot 已就位 ─────────────────────┐ │\n│ │ │ │\n│ │ (对话历史) │ │\n│ │ │ │\n│ └────────────────────────────────────┘ │\n│ │\n│ 消息: [________________] [发送] │\n├─────────────────────────────────────────┤\n│ 配方树 (点 /pilot recipe 自动展示) │\n└─────────────────────────────────────────┘\n```\n\n**可用指令**：\n\n| 输入 | 效果 | 是否消耗 LLM |\n|---|---|---|\n| `/pilot 如何做附魔台` | Agent 自动路由 → wiki_search + recipe_query | 是 |\n| `/pilot wiki 末地传送门` | 直接 wiki_search，返回带来源的回答 | 否（子命令直连） |\n| `/pilot recipe minecraft:bow` | 直接 recipe_query，返回配方树 | 否（子命令直连） |\n| `/pilot status` | 显示模型名、token 用量 | 否 |\n| `/pilot clear` | 清除 6 轮会话记忆 | 否 |\n| `/pilot help` | 显示帮助 | 否 |\n| `你好，你能做什么？` | Agent 对话（自然语言） | 是 |\n\n### 开发者后台\n\n打开 http://127.0.0.1:8000/admin\n\n展示 7 个面板：系统状态、游戏连接、配方数据、RAG/Qdrant、LLM/Agent、安全配置（脱敏）、诊断操作。\n\n**安全限制**：仅允许本机访问。从其他 IP 访问返回 403。\n\n### 游戏日志监听\n\n后端启动后，自动尝试检测 macOS 下 Minecraft 日志路径：\n\n```\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n如果日志存在且 Minecraft 正在运行：\n- 页面显示绿色的\"玩家名 · 26.2\"\n- 死亡事件被解析，生成建议，通过 WebSocket 推送到网页\n\n**手动指定日志路径**（如果自动检测失败）：\n1. 打开 http://127.0.0.1:8000/admin\n2. 点击\"重连日志\"\n3. 或直接通过 API：`POST /admin/api/reconnect-log`\n\n---\n\n## 技术栈\n\n| 层 | 选型 |\n|---|---|\n| 语言 | Python 3.12 + Java 25 (Mod) |\n| Web 框架 | FastAPI + Jinja2 + 原生 JavaScript（零 Node 构建） |\n| 数据模型 | Pydantic + SQLAlchemy 2.x |\n| 向量库 | Qdrant 1.15 (Docker) |\n| LLM | DeepSeek v4-flash (OpenAI 兼容 API) |\n| Embedding | BAAI/bge-small-zh-v1.5 (sentence-transformers, 本地运行) |\n| 传输协议 | HTTP (REST) + WebSocket (实时推送) |\n| 容器 | Docker Compose |\n| Mod 框架 | Fabric (Minecraft) |\n\n---\n\n## 项目结构\n\n```\n.\n├── src/mc_pilot/\n│ ├── app.py # FastAPI 工厂\n│ ├── config.py # Pydantic 配置（环境变量→Settings）\n│ ├── errors.py # 领域异常 AppError\n│ ├── logging_config.py # JSON 结构化日志\n│ ├── api/ # HTTP/WebSocket 路由层\n│ │ ├── chat.py # POST /api/chat\n│ │ ├── recipes.py # GET/POST /api/recipes\n│ │ ├── game_state.py # GET /api/game-state, WS /ws\n│ │ ├── health.py # /health/live, /health/ready\n│ │ ├── pages.py # 页面路由 (/ 和 /admin)\n│ │ └── models.py # 共享 API 响应模型\n│ ├── admin/\n│ │ └── routes.py # /admin/api/* (loopback-only)\n│ ├── agent/ # DeepSeek Agent 核心\n│ │ ├── client.py # DeepSeek OpenAI 兼容客户端\n│ │ ├── loop.py # Agent 状态机\n│ │ ├── memory.py # 6 轮会话记忆 + token 预算\n│ │ ├── models.py # Agent 领域模型\n│ │ ├── tools.py # 3 个 MCP 风格工具契约\n│ │ └── service.py # Agent 服务（/pilot 路由）\n│ ├── game/ # 游戏日志\n│ │ ├── detector.py # macOS 日志/进程检测\n│ │ ├── tailer.py # 日志尾随（轮转/截断恢复）\n│ │ ├── death_parser.py # zh_cn/en_us 双语死亡解析（~60 条规则）\n│ │ ├── listener.py # 日志监听循环 + 死亡建议生成\n│ │ ├── models.py # 游戏状态模型\n│ │ └── service.py # 游戏服务\n│ ├── rag/ # Wiki RAG 管线\n│ │ ├── client.py # MediaWiki API 客户端（分页、缓存、限速）\n│ │ ├── chunker.py # 文本清洗 + 段落级切块\n│ │ ├── embedder.py # BAAI/bge-small-zh-v1.5 嵌入适配器\n│ │ ├── indexer.py # Qdrant staging→live 原子交换\n│ │ ├── retriever.py # 密集检索 + 标题精确加权\n│ │ ├── models.py # RAG 领域模型\n│ │ └── service.py # RAG 服务\n│ ├── recipes/ # 官方配方管线\n│ │ ├── downloader.py # Mojang 清单 + JAR 下载 + SHA-1 校验\n│ │ ├── extractor.py # JAR 配方/tag/本地化提取\n│ │ ├── tree.py # 确定性 N 层配方树算法\n│ │ ├── store.py # SQLite 持久化\n│ │ ├── models.py # 配方领域模型\n│ │ └── service.py # 配方服务\n│ ├── storage/ # 持久化适配\n│ │ ├── qdrant.py # Qdrant 健康探针\n│ │ └── sqlite.py # SQLite 引擎\n│ ├── templates/ # Jinja2 模板\n│ │ ├── base.html # 基础布局（导航 + 动态脚本区）\n│ │ ├── index.html # 主聊天页\n│ │ └── admin.html # 开发者后台\n│ └── static/ # 静态资源\n│ ├── css/app.css # 全局样式\n│ └── js/\n│ ├── chat.js # 聊天 UI + WebSocket\n│ └── admin.js # 后台仪表盘\n├── fabric-mod/ # Fabric 26.2 客户端 Mod（可选加分项）\n│ ├── build.gradle\n│ ├── src/main/java/mc/pilot/mod/\n│ │ ├── PilotMod.java # Mod 入口\n│ │ ├── PilotClient.java # HTTP/WebSocket 客户端\n│ │ ├── PilotCommandHandler.java # /pilot 路由\n│ │ └── ChatRenderer.java # 本地聊天渲染\n│ └── src/main/resources/fabric.mod.json\n├── scripts/ # 运维脚本\n│ ├── build_recipes.py # 构建配方数据库\n│ ├── build_wiki.py # 构建 Wiki 索引\n│ └── test_connectivity.py # DeepSeek 连通性测试\n├── tests/ # 自动化测试 (108 个)\n├── docs/ # 课程文档\n│ ├── 实验报告.md # 完整实验报告\n│ ├── instruction.md\n│ └── 实验报告提交及评分标准.md\n├── compose.yaml # Docker Compose\n├── Dockerfile # App 镜像\n├── pyproject.toml # Python 项目元数据\n└── .env.example # 环境变量模板\n```\n\n---\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `MC_PILOT_HOST` | `127.0.0.1` | 服务绑定地址 |\n| `MC_PILOT_PORT` | `8000` | 服务端口 |\n| `MC_PILOT_LOG_LEVEL` | `INFO` | 日志级别 (DEBUG/INFO/WARNING/ERROR) |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite 数据库路径 |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant 服务地址 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | Qdrant 连接超时 |\n| `MC_PILOT_MINECRAFT_DIR` | macOS 默认游戏目录 | Docker 只读挂载的宿主机 Minecraft 目录 |\n| `MC_PILOT_GAME_LOG_PATH` | 自动检测 | 原生运行时可覆盖的 `latest.log` 路径 |\n| `DEEPSEEK_API_KEY` | — | DeepSeek API 密钥 (**必需**) |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础 URL |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 模型标识符 |\n\n**获取 API 密钥**：https://platform.deepseek.com/api_keys\n\n复制 `.env.example` → `.env`，填入 `DEEPSEEK_API_KEY=` 后面的值。\nDocker Compose 会将 `MC_PILOT_MINECRAFT_DIR` 只读挂载到容器。目录或\n`logs/latest.log` 暂不存在时，日志分析保持未连接，聊天、Wiki 和配方仍可使用。\n\n---\n\n## 质量检查\n\n```bash\n# 代码风格（0 errors）\n.venv/bin/ruff check .\n\n# 类型检查（0 errors）\n.venv/bin/mypy src tests\n\n# 自动化测试（108 passed）\n.venv/bin/pytest -q\n\n# Docker 配置语法验证\ndocker compose config --quiet\n```\n\n测试覆盖范围：\n- 配方解析 (shaped/shapeless/smelting/stonecutting)\n- 配方树算法 (递归/循环检测/标签展开/叶子汇总)\n- SHA-1 哈希校验\n- 中英文死亡解析 (~60 条规则)\n- 日志尾随 (轮转/截断恢复)\n- SQLite 存储 CRUD\n- 工具白名单安全\n- Token 预算管理\n- 密钥脱敏\n- API 路由冒烟测试\n- Docker Compose 配置验证\n\n---\n\n## API 文档\n\n### 健康检查\n\n```\nGET /health/live → {\"status\":\"alive\",\"version\":\"0.1.0\"}\nGET /health/ready → {\"status\":\"ready\",\"components\":[...]}\n```\n\n### Agent 对话\n\n```\nPOST /api/chat\nContent-Type: application/json\n{\"message\": \"/pilot 如何合成附魔台？\"}\n\nResponse:\n{\n \"state\": \"answered\",\n \"answer\": \"附魔台需要...\",\n \"stop_reason\": null\n}\n```\n\n### 配方查询\n\n```\nGET /api/recipes/minecraft:enchanting_table\nPOST /api/recipes/tree {\"item_id\": \"minecraft:diamond_sword\", \"quantity\": 1, \"max_depth\": null}\n```\n\n### 游戏状态\n\n```\nGET /api/game-state → {\"state\":\"connected\",\"player_name\":\"Steve\",\"version_id\":\"26.2\"}\nWS /ws → {\"type\":\"death_advice\",\"advice\":\"...\"} | {\"type\":\"state\",...}\n```\n\n### 管理后台 API（仅 loopback）\n\n```\nGET /admin/api/status # 系统状态\nGET /admin/api/game # 游戏连接\nGET /admin/api/recipes # 配方数据状态\nGET /admin/api/rag # RAG/Qdrant 状态\nGET /admin/api/llm # LLM/Agent 状态\nGET /admin/api/config # 配置（脱敏）\nPOST /admin/api/reconnect-log # 重连游戏日志\nPOST /admin/api/rebuild-wiki # 重建 Wiki 索引\n```\n\n---\n\n## Fabric Mod（可选）\n\n**目标**：在游戏内通过 `/pilot` 指令使用 Agent，所有消息仅本地可见（不会发送到多人服务器）。\n\n```bash\ncd fabric-mod\ngradle build\n# 输出：build/libs/pilot-mod-0.1.0.jar → 放入 .minecraft/mods/\n```\n\n游戏中：\n```\n/pilot 如何获得下界合金锭？ → Agent 回答（本地聊天 HUD）\n/pilot wiki 末影龙 → 直接 wiki 搜索\n/pilot recipe diamond_sword → 直接配方查询\n/pilot status → 连接状态\n```\n\n**构建需求**：JDK 25 + Gradle 9.6+。详见 `fabric-mod/BUILDING.md`。\n\n---\n\n## 数据构建\n\n以下脚本需要网络连接，首次运行需下载依赖数据。\n\n```bash\n# DeepSeek 连通性测试（验证 API Key 可用）\n.venv/bin/python scripts/test_connectivity.py\n\n# 构建配方数据库（从 Mojang 下载 26.2 JAR，提取配方 → SQLite）\n.venv/bin/python scripts/build_recipes.py\n\n# 构建 Wiki 索引（从中文 Wiki API 采集，嵌入 → Qdrant）\n.venv/bin/python scripts/build_wiki.py\n```\n\n**注意事项**：\n- `build_recipes.py` 需要 ~100MB 下载，SHA-1 校验确保文件正确\n- `build_wiki.py` 首次运行需下载 BGE 模型（~400MB），抓取 Wiki 页面约 5-10 分钟\n- 配方和 Wiki 数据是独立的，可以先构建其中一个\n- 即使没有构建数据，Agent 对话功能仍可用（模型依赖自身知识回答）\n"}, "9c360ca05d63ad5a6499c4d6f8f36c50b33044b6": {"t": 1785772059.6213372, "n": 11255, "h": "e92cfe19cc38800e", "c": "# Minecraft Pilot Agent\n\nMinecraft Pilot 是一个面向 Minecraft Java Edition 26.2 的本地游戏助手。结合中文 Wiki RAG、确定性配方树和游戏日志分析，通过网页聊天和 Fabric Mod 为玩家提供帮助。\n\n**非官方课程项目**，与 Mojang 或 Microsoft 无关。\n\n---\n\n## 目录\n\n- [QuickStart](#quickstart)\n- [功能概览](#功能概览)\n- [使用教程](#使用教程)\n- [技术栈](#技术栈)\n- [项目结构](#项目结构)\n- [环境变量](#环境变量)\n- [质量检查](#质量检查)\n- [API 文档](#api-文档)\n- [Fabric Mod](#fabric-mod-可选)\n- [数据构建](#数据构建)\n\n---\n\n## QuickStart\n\n从头开始，三步跑通。\n\n### 第一步：环境准备\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/[用户名]/mc-pilot.git\ncd mc-pilot\n\n# 2. 创建虚拟环境并安装依赖\npython3 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\n\n# 3. 配置 API 密钥\ncp .env.example .env\n# 编辑 .env，将 DEEPSEEK_API_KEY= 后面填上你的 DeepSeek API 密钥\n# 获取密钥: https://platform.deepseek.com/api_keys\n```\n\n> **注意** 本项目使用 pip + .venv，**不使用 conda**。macOS / Linux 均可，Windows 需自行调整路径分隔符。\n\n### 第二步：启动服务\n\n```bash\n# 4. 启动 Qdrant 向量数据库（需要 Docker）\ndocker compose up -d qdrant\n\n# 5. 启动 Pilot 后端\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --reload --host 127.0.0.1 --port 8000\n```\n\n> 如果不想手动分步启动，也可以一条命令拉起全部服务：\n> ```bash\n> docker compose up --build\n> ```\n\n### 第三步：打开网页\n\n浏览器打开 http://127.0.0.1:8000\n\n你应该看到 **Minecraft Pilot** 主页面，聊天框里已有欢迎消息。此时页面右上角应显示绿色的\"就绪\"状态。\n\n**验证连接**：\n```bash\ncurl http://127.0.0.1:8000/health/ready\n# {\"status\":\"ready\",\"components\":[{\"name\":\"sqlite\",\"status\":\"ready\",...},{\"name\":\"qdrant\",\"status\":\"ready\",...}]}\n```\n\n---\n\n## 功能概览\n\n完成 QuickStart 后，你有四条核心使用路径：\n\n| 序号 | 能力 | 需要什么 | 如何使用 |\n|---|---|---|---|\n| 1 | Agent 对话 | DeepSeek API Key | 在网页输入框输入问题 |\n| 2 | 配方查询 | 先运行 `build_recipes` | `/pilot recipe <物品ID>` |\n| 3 | Wiki 问答 | 先运行 `build_wiki` | `/pilot wiki <关键词>` |\n| 4 | 死亡建议 | 启动 Minecraft 26.2 并打开日志监听 | 游戏中死亡时自动触发 |\n\n### 能力 1：Agent 智能对话\n\n当你配置了 `DEEPSEEK_API_KEY`，Agent 立即可用。无需额外数据。\n\n```\n在网页输入框中输入：\n/pilot 如何合成附魔台？\n```\n\nAgent 会自动调用 `wiki_search` 查询知识库，或调用 `recipe_query` 查询配方，然后用中文回复。\n\n**首次验证**：先运行连通性测试确认模型可访问：\n```bash\n.venv/bin/python scripts/test_connectivity.py\n# 预期输出：Connectivity OK model=deepseek-v4-flash latency_ms=850\n```\n\n### 能力 2：确定性配方查询\n\n需要先构建本地配方数据库（需要网络，约 100MB 下载）：\n\n```bash\n# 从 Mojang CDN 下载 Java 26.2 客户端 JAR，提取配方到 SQLite\n.venv/bin/python scripts/build_recipes.py\n```\n\n然后在网页中输入：\n```\n/pilot recipe minecraft:enchanting_table\n```\n\nAgent 会返回附魔台所需的全部材料：黑曜石 ×4、钻石 ×2、书 ×1。配方树是完全确定性计算的，不依赖模型生成。\n\n### 能力 3：Wiki 知识问答\n\n需要先构建 Wiki 索引（需要网络，首次约 5-10 分钟，需要约 2GB 模型下载）：\n\n```bash\n# 从中文 Minecraft Wiki API 采集知识，嵌入到 Qdrant\n.venv/bin/python scripts/build_wiki.py\n```\n\n然后在网页中输入：\n```\n/pilot wiki 凋零骷髅在哪生成？\n```\n\nAgent 从 Qdrant 检索相关 Wiki 片段，整合后返回带来源 URL 的回答。\n\n### 能力 4：死亡建议（自动触发）\n\n这是**自动触发**的能力，无需手动调用。\n\n1. 确认后端正在运行\n2. 启动 **Minecraft Java Edition 26.2**（单人生存模式）\n3. 在网页上，你应看到右上角状态从\"未连接游戏\"变为\"玩家名 · 26.2\"\n4. 当玩家角色在游戏中死亡时，网页会弹出红色气泡，显示 2-5 句生存建议\n\n如果未能自动检测到游戏日志，在网页开发后台手动指定日志路径：\nhttp://127.0.0.1:8000/admin → 重连日志\n\n---\n\n## 使用教程\n\n### 网页聊天（主界面）\n\n打开 http://127.0.0.1:8000\n\n```\n┌─────────────────────────────────────────┐\n│ Minecraft Pilot │\n│ Java Edition 26.2 │\n├─────────────────────────────────────────┤\n│ Pilot 对话 [玩家 · 26.2] [就绪] │\n│ │\n│ ┌─ Pilot 已就位 ─────────────────────┐ │\n│ │ │ │\n│ │ (对话历史) │ │\n│ │ │ │\n│ └────────────────────────────────────┘ │\n│ │\n│ 消息: [________________] [发送] │\n├─────────────────────────────────────────┤\n│ 配方树 (点 /pilot recipe 自动展示) │\n└─────────────────────────────────────────┘\n```\n\n**可用指令**：\n\n| 输入 | 效果 | 是否消耗 LLM |\n|---|---|---|\n| `/pilot 如何做附魔台` | Agent 自动路由 → wiki_search + recipe_query | 是 |\n| `/pilot wiki 末地传送门` | 直接 wiki_search，返回带来源的回答 | 否（子命令直连） |\n| `/pilot recipe minecraft:bow` | 直接 recipe_query，返回配方树 | 否（子命令直连） |\n| `/pilot status` | 显示模型名、token 用量 | 否 |\n| `/pilot clear` | 清除 6 轮会话记忆 | 否 |\n| `/pilot help` | 显示帮助 | 否 |\n| `你好，你能做什么？` | Agent 对话（自然语言） | 是 |\n\n### 开发者后台\n\n打开 http://127.0.0.1:8000/admin\n\n展示 7 个面板：系统状态、游戏连接、配方数据、RAG/Qdrant、LLM/Agent、安全配置（脱敏）、诊断操作。\n\n**安全限制**：仅允许本机访问。从其他 IP 访问返回 403。\n\n### 游戏日志监听\n\n后端启动后，自动尝试检测 macOS 下 Minecraft 日志路径：\n\n```\n~/Library/Application Support/minecraft/logs/latest.log\n```\n\n如果日志存在且 Minecraft 正在运行：\n- 页面显示绿色的\"玩家名 · 26.2\"\n- 死亡事件被解析，生成建议，通过 WebSocket 推送到网页\n\n**手动指定日志路径**（如果自动检测失败）：\n1. 打开 http://127.0.0.1:8000/admin\n2. 点击\"重连日志\"\n3. 或直接通过 API：`POST /admin/api/reconnect-log`\n\n---\n\n## 技术栈\n\n| 层 | 选型 |\n|---|---|\n| 语言 | Python 3.12 + Java 25 (Mod) |\n| Web 框架 | FastAPI + Jinja2 + 原生 JavaScript（零 Node 构建） |\n| 数据模型 | Pydantic + SQLAlchemy 2.x |\n| 向量库 | Qdrant 1.15 (Docker) |\n| LLM | DeepSeek v4-flash (OpenAI 兼容 API) |\n| Embedding | BAAI/bge-small-zh-v1.5 (sentence-transformers, 本地运行) |\n| 传输协议 | HTTP (REST) + WebSocket (实时推送) |\n| 容器 | Docker Compose |\n| Mod 框架 | Fabric (Minecraft) |\n\n---\n\n## 项目结构\n\n```\n.\n├── src/mc_pilot/\n│ ├── app.py # FastAPI 工厂\n│ ├── config.py # Pydantic 配置（环境变量→Settings）\n│ ├── errors.py # 领域异常 AppError\n│ ├── logging_config.py # JSON 结构化日志\n│ ├── api/ # HTTP/WebSocket 路由层\n│ │ ├── chat.py # POST /api/chat\n│ │ ├── recipes.py # GET/POST /api/recipes\n│ │ ├── game_state.py # GET /api/game-state, WS /ws\n│ │ ├── health.py # /health/live, /health/ready\n│ │ ├── pages.py # 页面路由 (/ 和 /admin)\n│ │ └── models.py # 共享 API 响应模型\n│ ├── admin/\n│ │ └── routes.py # /admin/api/* (loopback-only)\n│ ├── agent/ # DeepSeek Agent 核心\n│ │ ├── client.py # DeepSeek OpenAI 兼容客户端\n│ │ ├── loop.py # Agent 状态机\n│ │ ├── memory.py # 6 轮会话记忆 + token 预算\n│ │ ├── models.py # Agent 领域模型\n│ │ ├── tools.py # 3 个 MCP 风格工具契约\n│ │ └── service.py # Agent 服务（/pilot 路由）\n│ ├── game/ # 游戏日志\n│ │ ├── detector.py # macOS 日志/进程检测\n│ │ ├── tailer.py # 日志尾随（轮转/截断恢复）\n│ │ ├── death_parser.py # zh_cn/en_us 双语死亡解析（~60 条规则）\n│ │ ├── listener.py # 日志监听循环 + 死亡建议生成\n│ │ ├── models.py # 游戏状态模型\n│ │ └── service.py # 游戏服务\n│ ├── rag/ # Wiki RAG 管线\n│ │ ├── client.py # MediaWiki API 客户端（分页、缓存、限速）\n│ │ ├── chunker.py # 文本清洗 + 段落级切块\n│ │ ├── embedder.py # BAAI/bge-small-zh-v1.5 嵌入适配器\n│ │ ├── indexer.py # Qdrant staging→live 原子交换\n│ │ ├── retriever.py # 密集检索 + 标题精确加权\n│ │ ├── models.py # RAG 领域模型\n│ │ └── service.py # RAG 服务\n│ ├── recipes/ # 官方配方管线\n│ │ ├── downloader.py # Mojang 清单 + JAR 下载 + SHA-1 校验\n│ │ ├── extractor.py # JAR 配方/tag/本地化提取\n│ │ ├── tree.py # 确定性 N 层配方树算法\n│ │ ├── store.py # SQLite 持久化\n│ │ ├── models.py # 配方领域模型\n│ │ └── service.py # 配方服务\n│ ├── storage/ # 持久化适配\n│ │ ├── qdrant.py # Qdrant 健康探针\n│ │ └── sqlite.py # SQLite 引擎\n│ ├── templates/ # Jinja2 模板\n│ │ ├── base.html # 基础布局（导航 + 动态脚本区）\n│ │ ├── index.html # 主聊天页\n│ │ └── admin.html # 开发者后台\n│ └── static/ # 静态资源\n│ ├── css/app.css # 全局样式\n│ └── js/\n│ ├── chat.js # 聊天 UI + WebSocket\n│ └── admin.js # 后台仪表盘\n├── fabric-mod/ # Fabric 26.2 客户端 Mod（可选加分项）\n│ ├── build.gradle\n│ ├── src/main/java/mc/pilot/mod/\n│ │ ├── PilotMod.java # Mod 入口\n│ │ ├── PilotClient.java # HTTP/WebSocket 客户端\n│ │ ├── PilotCommandHandler.java # /pilot 路由\n│ │ └── ChatRenderer.java # 本地聊天渲染\n│ └── src/main/resources/fabric.mod.json\n├── scripts/ # 运维脚本\n│ ├── build_recipes.py # 构建配方数据库\n│ ├── build_wiki.py # 构建 Wiki 索引\n│ └── test_connectivity.py # DeepSeek 连通性测试\n├── tests/ # 自动化测试 (108 个)\n├── docs/ # 课程文档\n│ ├── 实验报告.md # 完整实验报告\n│ ├── instruction.md\n│ └── 实验报告提交及评分标准.md\n├── compose.yaml # Docker Compose\n├── Dockerfile # App 镜像\n├── pyproject.toml # Python 项目元数据\n└── .env.example # 环境变量模板\n```\n\n---\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `MC_PILOT_HOST` | `127.0.0.1` | 服务绑定地址 |\n| `MC_PILOT_PORT` | `8000` | 服务端口 |\n| `MC_PILOT_LOG_LEVEL` | `INFO` | 日志级别 (DEBUG/INFO/WARNING/ERROR) |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite 数据库路径 |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant 服务地址 |\n| `MC_PILOT_QDRANT_TIMEOUT_SECONDS` | `2` | Qdrant 连接超时 |\n| `DEEPSEEK_API_KEY` | — | DeepSeek API 密钥 (**必需**) |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础 URL |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 模型标识符 |\n\n**获取 API 密钥**：https://platform.deepseek.com/api_keys\n\n复制 `.env.example` → `.env`，填入 `DEEPSEEK_API_KEY=` 后面的值。\n\n---\n\n## 质量检查\n\n```bash\n# 代码风格（0 errors）\n.venv/bin/ruff check .\n\n# 类型检查（0 errors）\n.venv/bin/mypy src tests\n\n# 自动化测试（108 passed）\n.venv/bin/pytest -q\n\n# Docker 配置语法验证\ndocker compose config --quiet\n```\n\n测试覆盖范围：\n- 配方解析 (shaped/shapeless/smelting/stonecutting)\n- 配方树算法 (递归/循环检测/标签展开/叶子汇总)\n- SHA-1 哈希校验\n- 中英文死亡解析 (~60 条规则)\n- 日志尾随 (轮转/截断恢复)\n- SQLite 存储 CRUD\n- 工具白名单安全\n- Token 预算管理\n- 密钥脱敏\n- API 路由冒烟测试\n- Docker Compose 配置验证\n\n---\n\n## API 文档\n\n### 健康检查\n\n```\nGET /health/live → {\"status\":\"alive\",\"version\":\"0.1.0\"}\nGET /health/ready → {\"status\":\"ready\",\"components\":[...]}\n```\n\n### Agent 对话\n\n```\nPOST /api/chat\nContent-Type: application/json\n{\"message\": \"/pilot 如何合成附魔台？\"}\n\nResponse:\n{\n \"state\": \"answered\",\n \"answer\": \"附魔台需要...\",\n \"stop_reason\": null\n}\n```\n\n### 配方查询\n\n```\nGET /api/recipes/minecraft:enchanting_table\nPOST /api/recipes/tree {\"item_id\": \"minecraft:diamond_sword\", \"quantity\": 1, \"max_depth\": null}\n```\n\n### 游戏状态\n\n```\nGET /api/game-state → {\"state\":\"connected\",\"player_name\":\"Steve\",\"version_id\":\"26.2\"}\nWS /ws → {\"type\":\"death_advice\",\"advice\":\"...\"} | {\"type\":\"state\",...}\n```\n\n### 管理后台 API（仅 loopback）\n\n```\nGET /admin/api/status # 系统状态\nGET /admin/api/game # 游戏连接\nGET /admin/api/recipes # 配方数据状态\nGET /admin/api/rag # RAG/Qdrant 状态\nGET /admin/api/llm # LLM/Agent 状态\nGET /admin/api/config # 配置（脱敏）\nPOST /admin/api/reconnect-log # 重连游戏日志\nPOST /admin/api/rebuild-wiki # 重建 Wiki 索引\n```\n\n---\n\n## Fabric Mod（可选）\n\n**目标**：在游戏内通过 `/pilot` 指令使用 Agent，所有消息仅本地可见（不会发送到多人服务器）。\n\n```bash\ncd fabric-mod\ngradle build\n# 输出：build/libs/pilot-mod-0.1.0.jar → 放入 .minecraft/mods/\n```\n\n游戏中：\n```\n/pilot 如何获得下界合金锭？ → Agent 回答（本地聊天 HUD）\n/pilot wiki 末影龙 → 直接 wiki 搜索\n/pilot recipe diamond_sword → 直接配方查询\n/pilot status → 连接状态\n```\n\n**构建需求**：JDK 25 + Gradle 9.6+。详见 `fabric-mod/BUILDING.md`。\n\n---\n\n## 数据构建\n\n以下脚本需要网络连接，首次运行需下载依赖数据。\n\n```bash\n# DeepSeek 连通性测试（验证 API Key 可用）\n.venv/bin/python scripts/test_connectivity.py\n\n# 构建配方数据库（从 Mojang 下载 26.2 JAR，提取配方 → SQLite）\n.venv/bin/python scripts/build_recipes.py\n\n# 构建 Wiki 索引（从中文 Wiki API 采集，嵌入 → Qdrant）\n.venv/bin/python scripts/build_wiki.py\n```\n\n**注意事项**：\n- `build_recipes.py` 需要 ~100MB 下载，SHA-1 校验确保文件正确\n- `build_wiki.py` 首次运行需下载 BGE 模型（~400MB），抓取 Wiki 页面约 5-10 分钟\n- 配方和 Wiki 数据是独立的，可以先构建其中一个\n- 即使没有构建数据，Agent 对话功能仍可用（模型依赖自身知识回答）\n"}, "feccd42a4b557424af9ea7ac7ebe16e1048d623a": {"t": 1785772061.8272557, "n": 4482, "h": "d79792f1899de113", "c": "# Minecraft Pilot Agent\n\nMinecraft Pilot 是一个面向 Minecraft Java Edition 26.2 的本地游戏助手。网页 MVP 结合了中文 Wiki RAG、确定性配方树和本地玩家死亡建议。轻量 Fabric 客户端 Mod 作为可选阶段二。\n\n这是非官方的课程项目，与 Mojang 或 Microsoft 无关。\n\n## 功能概览\n\n- Wiki RAG: 从中文 Minecraft Wiki 采集知识、嵌入 BGE-small-zh-v1.5、Qdrant 向量检索、带来源引用和未验证补充分区\n- 配方树: 从 Mojang 官方 26.2 版本提取配方、SHA-1 验证、确定性 N 层材料树、多配方候选和标签材料处理\n- DeepSeek Agent: 工具调用（wiki_search / recipe_query / recipe_direct）、状态机（received→deciding→tool_running→observing→answered/stopped/failed）、短会话记忆、token 预算\n- 游戏日志: macOS 日志监听、zh_cn/en_us 双语死亡解析、去重、唯一 DeepSeek 死亡建议、WebSocket 推送\n- 网页聊天: FastAPI + Jinja2 + 原生 JavaScript、/pilot 指令路由、WebSocket 游戏状态、死亡气泡淡出\n- 开发者后台: /admin 仪表盘、系统/游戏/RAG/配方/LLM 状态、诊断操作、仅 loopback 访问\n\n## 技术栈\n\n| 层 | 技术 |\n|---|---|\n| 后端 | Python 3.12, FastAPI, Pydantic, SQLAlchemy 2.x |\n| 向量库 | Qdrant (Docker) |\n| LLM | DeepSeek (OpenAI 兼容 API) |\n| Embedding | BAAI/bge-small-zh-v1.5 (sentence-transformers) |\n| 网页 | Jinja2, 原生 JavaScript, 零 Node 构建 |\n| 容器 | Docker Compose (Qdrant + App) |\n\n## 快速开始\n\nPython 3.12 必需。本项目使用 pip + .venv，不使用 conda。\n\n```bash\n# 环境初始化\npython3 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\n# 编辑 .env 填入 DEEPSEEK_API_KEY\n```\n\n```bash\n# 启动 Qdrant (Docker)\ndocker compose up -d qdrant\n\n# 启动开发服务器\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --reload\n\n# 启动完整 Docker 服务\ndocker compose up --build\n```\n\n打开 http://127.0.0.1:8000/ 和 http://127.0.0.1:8000/admin。\n\n## 数据构建\n\n```bash\n# 构建配方数据库 (从 Mojang CDN 下载 26.2 JAR)\n.venv/bin/python scripts/build_recipes.py\n\n# 构建 Wiki 知识库 (从中文 Wiki API 采集)\n.venv/bin/python scripts/build_wiki.py\n\n# DeepSeek 连通性测试\n.venv/bin/python scripts/test_connectivity.py\n```\n\n## 质量检查\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n```\n\n## 项目结构\n\n```\nsrc/mc_pilot/\n├── app.py # FastAPI 工厂\n├── config.py # Pydantic 配置\n├── errors.py # 领域异常\n├── logging_config.py # JSON 结构日志\n├── api/ # HTTP/WebSocket 适配\n│ ├── chat.py # /api/chat (Agent 对话)\n│ ├── recipes.py # /api/recipes (配方查询)\n│ ├── game_state.py # /api/game-state, /ws (游戏状态)\n│ ├── health.py # /health/live, /health/ready\n│ ├── pages.py # 页面路由\n│ └── models.py # 共享 API 模型\n├── admin/ # 开发者后台\n│ └── routes.py # /admin/api/* (loopback-only)\n├── agent/ # Agent 核心\n│ ├── client.py # DeepSeek 客户端\n│ ├── loop.py # 状态机循环\n│ ├── memory.py # 会话记忆\n│ ├── models.py # Agent 领域模型\n│ ├── tools.py # MCP 风格工具契约\n│ └── service.py # Agent 服务\n├── game/ # 游戏日志\n│ ├── detector.py # macOS 进程/日志检测\n│ ├── tailer.py # 日志尾随 (轮转/截断)\n│ ├── death_parser.py # 双语死亡解析\n│ ├── listener.py # 日志监听循环\n│ ├── models.py # 游戏状态模型\n│ └── service.py # 游戏服务\n├── rag/ # Wiki RAG\n│ ├── client.py # MediaWiki API 客户端\n│ ├── chunker.py # 文本清洗/切块\n│ ├── embedder.py # BGE 嵌入适配器\n│ ├── indexer.py # Qdrant 索引 (staging→live)\n│ ├── retriever.py # 密集检索 + 标题 boost\n│ ├── models.py # RAG 领域模型\n│ └── service.py # RAG 服务\n├── recipes/ # 配方数据\n│ ├── downloader.py # Mojang 下载 + SHA-1\n│ ├── extractor.py # JAR 提取\n│ ├── tree.py # 配方树算法\n│ ├── store.py # SQLite 持久化\n│ ├── models.py # 配方领域模型\n│ └── service.py # 配方服务\n├── storage/ # 持久化适配\n│ ├── qdrant.py # Qdrant 健康探针\n│ └── sqlite.py # SQLite 引擎\n├── templates/ # Jinja2 模板\n│ ├── base.html\n│ ├── index.html # 主聊天页\n│ └── admin.html # 开发者后台\n└── static/ # 静态资源\n ├── css/app.css\n └── js/ (chat.js, admin.js)\n```\n\n## 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `MC_PILOT_HOST` | `127.0.0.1` | 绑定地址 |\n| `MC_PILOT_PORT` | `8000` | 绑定端口 |\n| `MC_PILOT_LOG_LEVEL` | `INFO` | 日志级别 |\n| `MC_PILOT_SQLITE_URL` | `sqlite:///data/mc_pilot.db` | SQLite 路径 |\n| `MC_PILOT_QDRANT_URL` | `http://localhost:6333` | Qdrant 地址 |\n| `DEEPSEEK_API_KEY` | — | DeepSeek API 密钥（必需） |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础 URL |\n| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 模型名 |\n\n## 课程验收要点\n\n- 真实模型连通性: `python scripts/test_connectivity.py`\n- Agent 工具调用: 发送 `/pilot 查询附魔台配方` 验证 wiki_search + recipe_query 工具选择\n- 离线测试: `pytest -q` (91+ 自动化测试)\n- 安全红线和错误出口: 工具白名单、未知工具拒绝、超预算停止、参数校验\n- 成本受控: Agent 最多 4 轮工具调用、输出约 800 tokens、每日 200k tokens 上限\n- 所有秘密通过 .env 提供，仓库不包含密钥或未脱敏日志\n"}, "c53c48bdbb5e4eee6c3eec2e56fd7caf1da63c5b": {"t": 1785772063.0875492, "n": 1469, "h": "0783fbf405a228a3", "c": "# Minecraft Pilot Agent\n\nMinecraft Pilot is a local assistant for Minecraft Java Edition 26.2. The required web MVP will combine Chinese Wiki RAG, deterministic recipe trees, and concise local-player death advice. A thin Fabric client is planned as an optional second phase.\n\nThis is an unofficial, educational project. It is not approved by or associated with Mojang or Microsoft.\n\n## M1 foundation\n\nThe current milestone provides the typed FastAPI skeleton, local web/admin placeholders, SQLite bootstrap, Qdrant readiness checks, Docker Compose, and baseline quality checks. Game, RAG, recipe, and model behavior arrive in later milestones.\n\n## Local development\n\nPython 3.12 is required. This project deliberately uses pip and an isolated `.venv`; it does not use conda.\n\n```bash\npython3 -m venv .venv\n.venv/bin/python -m pip install --upgrade pip\n.venv/bin/python -m pip install -e '.[dev]'\ncp .env.example .env\ndocker compose up -d qdrant\n.venv/bin/uvicorn mc_pilot.app:create_app --factory --reload\n```\n\nOpen and .\n\n## Docker\n\n```bash\ndocker compose up --build\n```\n\nOnly loopback ports `8000` and `6333` are published. Qdrant and application state use named Docker volumes.\n\n## Verification\n\n```bash\n.venv/bin/ruff check .\n.venv/bin/mypy src tests\n.venv/bin/pytest -q\ndocker compose config --quiet\n```\n\nNever commit `.env`, Minecraft game files, Wiki dumps, model weights, Qdrant data, or private game logs.\n"}}}}