QuestPilot

QuestPilot 是一个基于 Mozilla BrowserQuest 源码与资源快照改造的单机游戏 Agent。玩家可以用自然语言询问玩法，或下达开箱、收集补给、移动、装备和战斗目标；系统会读取当前游戏状态，生成类型化任务，并通过受控动作驱动本地游戏运行时。

功能

• 使用 Pydantic AI 将玩家请求转换为直接回答、状态回答、玩法回答、记忆操作或结构化任务。
• 在每个游戏动作前读取最新状态，并根据当前可见对象选择执行目标。
• 通过固定动作模型执行移动、攻击、开箱、拾取、使用药水、撤退、复活和装备。
• 将复合目标拆成一至五个基础任务，记录当前步骤、完成进度、最近结果、执行预算和停止原因。
• 从本地玩法文档检索相关片段，并通过 SSE 返回回答、引用、工具调用和任务进度。

工作方式

自然语言请求
  -> FastAPI /agent/stream
  -> Pydantic AI 工具调用与类型化输出
  -> 任务状态与下一步规划
  -> 浏览器读取最新游戏状态
  -> 白名单动作执行
  -> 执行结果回传并更新任务

Pydantic AI 负责处理一次玩家请求并生成类型化结果。结构化任务创建后，浏览器在每个动作前读取状态，任务规划器根据动作结果选择下一步，运行时再次校验目标和参数。任务、记忆和游戏状态保存在当前服务进程中。

默认模式使用 Pydantic AI FunctionModel 生成确定性结果，完整经过工具调用、结构化输出、输出校验和任务创建流程，不需要模型服务凭据。项目也提供外部决策模型适配器；设置 DEEPSEEK_API_KEY 后，可通过 run_demo.ps1 -UseRealDeepSeek 启用。

玩法检索默认使用 96 维确定性哈希向量进行余弦召回，再结合查询词、标题和章节信息重排。可选的 OpenAI-compatible Embedding 配置位于 .env.example。

技术组成

• Python 3.11+、FastAPI、Pydantic、Pydantic AI
• 原生 JavaScript、HTML、CSS
• REST、WebSocket、Server-Sent Events（SSE）
• pytest、Ruff、Node.js 测试

安装

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock
npm.cmd ci

macOS 或 Linux：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
npm ci

Node.js 用于 JavaScript 测试；运行应用本身只需要 Python 依赖。

启动

Windows PowerShell：

.\run_demo.ps1

macOS 或 Linux：

DEEPSEEK_MOCK=1 .venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8011

打开 http://127.0.0.1:8011/。可以依次尝试：

1. 训练场怪怎么复活？
2. 把所有宝箱都开了
3. 先收集补给，再打三只怪

页面右侧会展示步骤摘要、工具调用、观察结果、引用和任务状态。

“暂停任务”会在当前动作完成并记录结果后暂停，等待期间显示“正在暂停”；“停止任务”会取消自动动作并清除当前移动和攻击目标。再次继续时保留已用步数和时间预算。目标消失等可恢复情况会根据最新状态选择下一步。

测试

.\.venv\Scripts\python.exe -m ruff check app tests
.\.venv\Scripts\python.exe -m pytest -q
npm.cmd test

核心测试覆盖玩法问答与执行意图分流、任务创建与执行结果回传、玩法检索与引用、暂停／停止及执行预算，以及 BrowserQuest 上游文件校验。Python 测试使用离线模型，JavaScript 测试使用模拟浏览器与网络边界。

GitHub Actions 执行上述 Ruff、pytest 和 Node.js 检查。

项目结构

• app/：FastAPI 服务、Agent、任务规划器、游戏运行时和浏览器页面。
• docs/gameplay-knowledge.md：本地玩法知识库。
• tests/：核心 Python 与 JavaScript 测试。
• app/static/browserquest/original/：BrowserQuest 上游源码与资源快照。

BrowserQuest 来源

app/static/browserquest/original/ 对应 Mozilla BrowserQuest 提交 af32d247cac3495ca430d0effbb88dd5f3250b2c。上游代码采用 MPL 2.0，内容资源采用 CC BY-SA 3.0；许可文件、来源说明和核心文件 SHA-256 清单均保存在该目录。详情见 SOURCE.md。