MCP 模组预演

MCP 预演用于验证模组在指定局面下的实际表现。开发 Agent 提交测试数据，客户端创建独立临时冒险，再由已有 AI 队友与主持运行。过程显示在正常游戏界面，游戏页不增加托管按钮；测试输入、运行、暂停、结果读取和清理均通过 MCP 完成。

预演使用已连接的模型服务，会产生正常的模型调用。角色必须是指定开局允许选择、且配置了 AI 队友预设的角色。

连接客户端

在客户端打开 设置 → 开发者工具 → MCP 服务，开启服务，再点击“复制连接配置”，将配置添加到支持 Streamable HTTP 的 Agent 客户端。无需下载源码、设置环境变量或运行开发命令。

服务默认关闭，开启后立即生效，并记住选择。首次开启自动分配本机端口并生成令牌；以后沿用同一地址和令牌，Agent 通常只需配置一次。地址和“最近请求”可用于确认服务是否运行、是否收到请求；收到请求不代表模型预演已经完成。

连接配置包含访问令牌，请作为本机凭据保存。服务只监听 127.0.0.1，不提供远程访问。客户端同时在 ~/.tarp/mcp.json 写入发现文件；设置了 TARP_HOME 时，该文件位于对应目录。发现文件只在服务运行时存在。状态页面不显示令牌，复制连接配置会将完整凭据写入剪贴板。

端口被占用时会显示启动失败，释放该端口后点击“重试启动”。客户端不会自动换端口，避免已有 Agent 配置失效。关闭服务会取消当前预演并保留临时局和记录；重新开启或重启客户端只恢复服务，不会自动继续模型运行。

源码调试可用 TARP_MCP_PORT=0 bun run dev 强制启动，或设置固定端口及至少 16 字符的 TARP_MCP_TOKEN。环境变量覆盖不改变已保存的连接信息；0 覆盖时每次分配的地址可能不同。一般作者使用设置入口即可。

模型默认沿用应用的游戏默认配置。也可以在创建参数中通过 model 指定已经连接的 provider、model 和可选的 thinkingLevel；参数不包含 API Key。创建本身不调用模型，模型连接问题会在运行时报告。

准备指定局面

调用 playtest_create，提供：

参数	用途
modulePath	包含模组元配置的绝对目录路径
name	可选测试名称，1–70 字符，默认“临时预演”
startId	模组中已经存在的开局 ID
background	所有队友可知的前置背景和当前目标，1–16000 字符
hostBackground	可选，仅主持可知的前置事实，最多 16000 字符，不向队友注入
model	可选，已经连接的服务商和模型标识
documents	可选文档初始值列表，最多 100 项，每项为 path 与 values
companions	1 到 6 名队友，每项提供角色文档 path

文档路径支持模组内的文档标识和格式扩展名。values 替换对应文档的顶层字段；未提供的字段保持原值，嵌套对象和数组整体替换。初始值可以包含运行中不可修改的原始字段，但不能覆盖 computed 公式配置；派生结果依然由真实公式计算。

需要配置生命、物品、任务、线索或场景时，填写模组已经定义的字段，不存在平台统一的测试字段。位置、参与关系和分队状态直接写入模组定义的文档字段，平台不额外安排场景或入场。

客户端会复制模组并按声明校验初始值、引用和公式，再设置开局和队友。场景与位置使用所提供的文档状态，不额外建立默认场景。测试跳过序章、选角和实际开场，从所提供的局面继续；前置背景只是测试起点，不表示这些经过已被实际游玩验证。

公开背景进入正常游戏聊天；主持背景进入本局主持提示词。不会伪造既有对话或 AI 记忆。创建失败清理未完成的 session；成功后返回 roomId 并打开现有游戏页，源模组保持不变。

驱动与观察

调用 playtest_run，传入 roomId、maxTurns 和可选 timeoutSeconds。maxTurns 默认 1，上限 100；超时默认 180 秒，允许 1 到 600 秒。

每一步是一名队友的决策，加上它提交行动后的主持裁定。聊天或沉默也占一步；没有行动时不运行主持。多名队友按顺序轮换，多次单步调用继续轮换。自动点名不会额外启动不计数的回应。全体队友连续不提交行动、冒险结束、达到次数、超时或失败时停止推进。

运行异步返回。通过 playtest_inspect 读取真实进度、近期聊天和骰子、当前活动、初始文档结果及每步完成后的文档快照。默认返回 documents 和队友角色对应的文档；传入 paths 可以选择其他文档。beforeSequence 和返回的 nextBeforeSequence 用于读取更早的聊天。

状态	含义
idle	当前没有运行任务
running	正在执行队友或主持运行
limit	达到本次步数上限
waiting	全体队友连续未提交行动，等待调整测试或人工干预
ended	运行检查到冒险已经结束
paused	已停止生成和后续推进
timeout	达到本次时间上限，已请求取消
failed	运行失败，结合错误和实际聊天检查

activity 和 roomStatus 提供真实房间活动及结局状态。MCP 报告包含开发调试资料，可能涉及主持信息，不应原样作为队友的玩家上下文。

通过前后快照、实际裁定和规则要求比较结果。Agent 提出的剧情问题属于审查意见，不等同于自动化断言通过。相同测试数据可以重复生成同一起点，但 AI 选择和随机骰点不保证相同。

停止和清理

playtest_pause 停止预演循环并取消当前生成，等待运行收尾，保留已经保存的状态和对话；取消不回滚已提交的变化。中断留下待处理行动或未接收输入时，先读取记录，再从原测试数据重新创建临时局。

playtest_dispose 停止并删除对应临时冒险。该工具只接受预演创建的 session，不能删除普通冒险。需要留存结果时先读取报告或保留临时局。临时局不会在预演结束或客户端退出时自动删除；客户端重启后可继续读取，正在运行的自动任务不会恢复。

修改模组后，使用同一份测试数据重新创建临时局即可重测。预演局保存的是创建时的模组副本；修改源文件不会自动改变已经创建的测试局。