Skip to content
QUIZQEPublic

About

SPT(逃离塔科夫离线版)AI 助手:服务端工具层 + 游戏内 F3 聊天面板。查价、改枪、仓库、藏身处、任务,支持 OpenAI 兼容 / Anthropic / Gemini / 阿里云百炼。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SPT-Agent

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

服务端

  1. 备份 SPT/user/mods/SptAgentMod。
  2. 把 server/SPT/ 内容覆盖到 SPT 根目录。
  3. 确认 SPT 根目录有 e_sqlite3.dll;压缩包已在 server/SPT/ 提供。
  4. 编辑:
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 Debug

Release 构建会自动部署:

  • 服务端: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):只限制聊天窗口显示的历史长度,不影响发给模型的内容。

DashScope / 千问

{
  "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> 切换服务端地址。

服务端 HTTP 接口

客户端 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

  • 当前 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。

Agent 命令

命令 作用
/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。

License

MIT,见 LICENSE。

About

SPT(逃离塔科夫离线版)AI 助手:服务端工具层 + 游戏内 F3 聊天面板。查价、改枪、仓库、藏身处、任务,支持 OpenAI 兼容 / Anthropic / Gemini / 阿里云百炼。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages