Escape from Tarkov 离线版(SPT)AI 助手:服务端工具层 + 游戏内聊天 UI。模型协议通过配置切换,支持 OpenAI 兼容、Anthropic、Gemini 和阿里云百炼 DashScope。
当前版本:1.0.0
在游戏里按 F3 打开聊天面板,用中文问它,它会自己去查 SPT 的数据库再回答:
- 改枪任务:读任务条件(人机工效、后座、弹匣、重量等),查出厂预设和兼容配件,编译出满足条件的方案并写成武器预设,不用退出游戏。
- 价格/来源:物品手册价、跳蚤价、各商人报价(含 Fence),以物易物换什么。
- 仓库与角色:指定类别搜仓库、容器内物品、当前装备、生命状态。
- 藏身处:升级材料与现有库存对比。
- 任务:搜索任务、查玩家进度、看任务详情。
模型返回工具调用 → 服务端执行本地工具查库 → 结果回灌 → 下一轮,循环上限可配(默认 20)。
| 项 | 要求 |
|---|---|
| SPT 服务端 | >= 4.0.0(开发与测试基于 SPTarkov.Server.Core 4.0.13) |
| .NET(服务端 mod) | net9.0 |
| 客户端 | net471 + BepInEx 5(Harmony) |
| EFT 客户端 | 0.16.9.0.40087 实测通过 |
| 模型 | 必须支持 function calling / tool use |
到 Releases 下载:
| 包 | 内容 |
|---|---|
SPT-Agent-1.0.0-client.zip |
只需要游戏内聊天 UI |
SPT-Agent-1.0.0-server.zip |
只需要服务端工具层 |
SPT-Agent-1.0.0-all.zip |
客户端 + 服务端 + 源码,一次装完 |
不想下载直接构建看下面的 构建。
发布包目录:
SPT-Agent-1.0.0/
├── server/
│ └── SPT/
├── client/
│ └── BepInEx/
├── README.md
├── CHANGELOG.md
└── LICENSE
- 备份
SPT/user/mods/SptAgentMod。 - 把
server/SPT/内容覆盖到 SPT 根目录。 - 确认 SPT 根目录有
e_sqlite3.dll;压缩包已在server/SPT/提供。 - 编辑:
SPT/user/mods/SptAgentMod/config/config.json
填入 provider、model、apiKey、apiUrl,然后启动服务端。
把 client/BepInEx/plugins/SptChatUI_Restyled/ 放到游戏根目录对应位置,启动游戏后按 F3。
客户端 GUID 为 com.sptagent.chatui,旧 BepInEx 配置不会复用。
- 服务端 DLL 可覆盖;不要覆盖现有 config.json。
- 旧版配置字段(
deepseekApiKey等)已移除,请按config.example.json重写。 - 旧客户端 DLL 建议先移除,避免两个 GUID 同时加载。
SPT-Agent/
├── SPT-Agent.sln
├── Directory.Build.props # TARKOV_DIR / SPT_PATH / DeployToGame
├── global.json
├── src/
│ ├── SptAgentMod/ # SPT 服务端 mod
│ │ ├── Configuration/ # 配置与路径解析
│ │ ├── DTOs/ # LLM / 工具消息模型
│ │ ├── Handlers/ # 对话与 Agent loop
│ │ ├── Http/ # /spt-agent HTTP 接口
│ │ ├── Llm/ # 四类协议适配器
│ │ ├── Services/ # 游戏数据、SQLite、日志
│ │ ├── config/ # config.example.json
│ │ └── skills/ # Agent 技能文件
│ └── SptChatUI_Restyled/ # 当前使用的游戏内聊天 UI
├── tools/
│ ├── SptAgentConsole/ # 控制台测试客户端
│ └── AssetCaptureTool/ # UI 资源抓取辅助插件(开发工具)
├── legacy/
│ └── SptChatUI/ # 旧版 UI,默认不构建/不部署
└── scripts/
├── build.ps1
├── deploy-server.ps1
└── deploy-client.ps1
bin/、obj/、pkg/、本地 config.json、日志不会提交。
默认路径为 F:\EFT\Client.0.16.9.0.40087\。其他安装位置用环境变量覆盖:
$env:TARKOV_DIR = "D:\EFT"
$env:SPT_PATH = "D:\EFT\SPT" # 可选,默认 $env:TARKOV_DIR\SPT# 只构建,不复制到游戏目录
.\scripts\build.ps1 -Configuration Release
# 构建并部署服务端 + 当前 UI
.\scripts\build.ps1 -Configuration Release -Deploy
# 只部署客户端 UI
.\scripts\deploy-client.ps1
# 也可以直接构建解决方案(不部署)
dotnet build SPT-Agent.sln -c DebugRelease 构建会自动部署:
- 服务端:
SPT/user/mods/SptAgentMod/ - 客户端:
BepInEx/plugins/SptChatUI_Restyled/
旧版 UI 在 legacy/,不包含在解决方案中;需要时单独构建。
服务端 mod GUID:com.sptagent.server。
第一次部署时,scripts/deploy-server.ps1 会把 src/SptAgentMod/config/config.example.json 复制为:
SPT/user/mods/SptAgentMod/config/config.json
示例:
{
"provider": "openai",
"model": "gpt-4o-mini",
"apiKey": "sk-...",
"apiUrl": "",
"modelsUrl": "",
"contextWindow": 0,
"maxTokens": 8192,
"maxTokensField": "max_tokens",
"temperature": 0.7,
"reasoningEffort": "",
"sendTemperature": true,
"systemPrompt": "你是 SPT-Agent,塔科夫离线版助手。",
"maxIterations": 20
}| 字段 | 说明 |
|---|---|
provider |
openai / openrouter / ollama / anthropic / gemini / dashscope / qwen |
model |
模型名 |
apiKey |
provider 的 API Key;本地模型可留空 |
apiUrl |
留空使用 provider 默认地址;也可填完整 URL |
modelsUrl |
可选模型列表端点;留空从 apiUrl 推导 /models |
contextWindow |
可选覆盖;0 表示使用 /models 返回的 context_window |
reasoningEffort |
思考等级;留空使用模型默认,可选 none/low/high/max |
maxTokensField |
多数模型用 max_tokens,部分 reasoning 模型用 max_completion_tokens |
sendTemperature |
模型拒绝 temperature 时设为 false |
systemPrompt |
系统提示词 |
maxIterations |
Agent 工具循环上限 |
provider 为空时会根据 apiUrl 推断。OpenAI 兼容服务(OpenRouter、Ollama、LM Studio、vLLM、各类中转)统一使用 provider: "openai" 加自定义 apiUrl。
旧版本的配置字段已移除。升级后请按 config.example.json 重写 config.json,只保留 apiKey / apiUrl / provider / model 等通用字段。
- 上下文窗口不再写死。启动时请求 provider 的
/models,读取context_window、max_output_tokens、effort;/models不支持时用contextWindow配置覆盖。 maxTokens:限制模型单次回复的长度。配置大于模型max_output_tokens时自动截到模型上限;Anthropic Messages API 仍强制要求该字段。reasoningEffort:发给 OpenAI 兼容接口的reasoning_effort;DeepSeek 支持none/low/high/max,留空使用模型默认档位。- 工具结果压缩:这是输入上下文保护,避免一个大工具结果撑爆模型上下文。
ToolOutputCompactor按工具给不同预算(8k–24k 字符),在行边界裁掉中间,保留头部和尾部,并提示缩小查询。 - 客户端
MAX_CHAT_LENGTH(30000):只限制聊天窗口显示的历史长度,不影响发给模型的内容。
{
"provider": "dashscope",
"model": "qwen-plus",
"apiKey": "sk-...",
"apiUrl": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1",
"maxTokens": 8192,
"maxTokensField": "max_tokens"
}- 不填
apiUrl时使用北京默认地址。 - 业务空间地址可填 base 或完整
.../services/aigc/text-generation/generation。 - 多模态模型需要完整的多模态端点。
- 也可以走 DashScope 的 OpenAI 兼容模式:
provider: "openai",apiUrl填.../compatible-mode/v1/chat/completions。
dotnet run --project tools/SptAgentConsole进入后默认连接 https://localhost:6969,可用 connect <url> 切换服务端地址。
客户端 UI 通过这几个接口和服务端通信,自己做前端也可以直接用:
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | /spt-agent/chat |
发起一次对话,立即返回 { requestId },后台处理 |
| POST | /spt-agent/chat/poll |
轮询结果 { intermediates, reply, done } |
| GET | /spt-agent/history |
当前会话历史 |
| POST | /spt-agent/status |
上下文占用、缓存命中率、模型与思考等级 |
| GET/POST | /spt-agent/tool/execute |
直接执行单个工具(调试用) |
| GET | /spt-agent/tools |
列出所有可用工具 |
| POST | /spt-agent/tools/refresh |
刷新工具表 |
| POST | /spt-agent/weapon-builds |
拉取存档里的用户武器预设,供客户端合并 |
服务端是多轮轮询模型,不是流式;chat 一返回就拿到 requestId,之后按需 poll。
| provider | 请求格式 | 工具调用 |
|---|---|---|
openai / openrouter / ollama |
Chat Completions | tools[].function / tool_calls / role: tool |
anthropic |
Messages | input_schema / tool_use / tool_result |
gemini |
generateContent |
functionDeclarations / functionCall / functionResponse |
dashscope / qwen |
DashScope 原生 | parameters.tools / output.choices[].message.tool_calls |
服务端 Agent loop 与 provider 无关:模型返回工具调用后执行本地工具,把结果追加到消息历史,再请求下一轮。
create_weapon_build 保存成功后,聊天客户端会请求 /spt-agent/weapon-builds,把存档里的用户武器预设合并进客户端的 WeaponBuildsStorage。只添加本地不存在的预设,不触发整包 Profile 重载,因此不会复制工厂预设。
改枪完成后不需要退出游戏重进;关闭并重新打开游戏内的武器预设列表即可看到新预设。若预设列表已经打开,先关闭再打开即可。
- 当前 UI:
src/SptChatUI_Restyled,显示名 SPT-Agent。 - 默认
F3开关。 - 支持从游戏界面捕获 TMP 字体,中文显示正常。
- 请求进行中关闭面板不会抢回输入焦点。
- 历史同步只显示最终问答,不显示中间工具消息。
- 插件 GUID:
com.sptagent.chatui。 - GUID 已重新整理,旧 BepInEx 配置不会自动迁移;快捷键恢复默认
F3,可在 BepInEx 配置里修改。
界面优化:
- 面板扩大到 840×540,输入区加高,长回答可读性更好。
- 聊天区增加行距和边距,中英文混排更舒展。
- 空历史时显示引导文案和示例问题。
- 用户/助手/系统标签改为中文(
你/SPT-Agent/系统)。 - 输入框增加光标颜色、选区颜色、细边框,发送按钮改为“发送”。
- AI 等待状态增加动态省略号。
- 新消息只在用户位于底部时自动滚到底;向上翻历史时不会被新消息拉走。
- 面板增加细边框;拖拽标题栏时限制在屏幕范围内,避免拖出屏幕。
- 顶部状态栏显示最近一次请求的上下文占用 / 模型上下文窗口进度条,以及 token 缓存命中率(
prompt_cache_hit_tokens / (hit + miss))。颜色随占用从绿到黄到红变化。 - 右上角 SPT-Agent 开启按钮改为整块按钮居中文字,去掉图标偏移,避免文字与背景错位。
- 服务端 Debug / Release:0 errors。
- 客户端 Debug / Release:0 errors(未启动游戏做视觉回归)。
- 控制台客户端:0 errors。
- Provider 适配器离线测试覆盖 OpenAI / Anthropic / Gemini 请求与响应映射。
- 工具输出压缩测试覆盖:短结果不处理、按行截断、保留头尾、按工具提示、无换行兜底。
/spt-agent/weapon-builds实测返回当前存档的用户武器预设,客户端按预设 ID 去重合并到WeaponBuildsStorage。/spt-agent/status实测返回contextUsed/contextBudget/cacheHitTokens/cacheMissTokens/cacheHitRate/reasoningEffort/model。- DeepSeek
/models实测:context_window=1048576、max_output_tokens=393216、effort=high;对话后状态栏显示约 95% token 缓存命中率。 - DashScope 适配器离线测试覆盖 URL、Bearer、
input.messages、result_format、tools、tool_calls、tool result、数组 content、usage、max_completion_tokens。
| 命令 | 作用 |
|---|---|
/help |
命令列表 |
/new |
开始新会话(清空当前上下文) |
/clear |
清空当前上下文和统计 |
/history [n] |
查看最近 n 条对话 |
/context / /tokens |
上下文用量、缓存命中率、思考等级 |
/model |
模型上下文窗口、最大输出、支持/当前思考等级 |
/effort <none/low/high/max/default> |
设置当前会话思考等级 |
/toggle |
开关 AI 助手 |
- 非流式请求,工具循环等待完整响应。
- 只处理文本 + function calling;图片/音频/文件输入未接入。
- OpenAI 使用 Chat Completions,不使用 Responses API。
- Gemini 使用经典
generateContent。 - Anthropic 的
max_tokens受具体模型上限限制。 - 模型必须支持 tool/function calling。
- 客户端 UI 未做多分辨率/多语言回归,只在 1920×1080 中文环境下验证。
- 没有自动化测试套件;provider 适配器只做过离线映射测试和手动联调。
- 本项目是 SPT(Single Player Tarkov)的第三方 mod,与 Battlestate Games、SPT 官方无关。
- 仓库不包含《逃离塔科夫》的任何游戏资源、资产或数据;
Escape from Tarkov、SPT相关名称与商标归各自权利人所有。 - 构建需要你自备正版游戏与 SPT 安装,编译时引用游戏目录中的 DLL 属于本地使用。
- 游戏内 AI 回答建立在 SPT 数据库之上,模型可能编错,价格和任务条件以游戏内为准。用它做交易决策前自己核一遍。
- 使用本 mod 导致的存档问题、封禁风险,作者不承担责任;SPT 是离线版,请勿在任何在线环境使用。
- 本项目在开发过程中大量使用 AI 辅助(代码、文档、排查),人类负责需求、验证和取舍。
- 提交 Issue / PR 请附上 SPT 版本、客户端版本、
provider/model和复现步骤,日志里贴SPT/user/mods/SptAgentMod/logs/。不要在 issue 里贴 API Key。
MIT,见 LICENSE。