第一次冒险 · TARP

先确认已经启动桌面应用，能够看到 TARP 首页。下面按导入模组、完成选角和开场、提交第一次行动的顺序操作，具体角色和开局名称由模组决定。

先连接并选择模型

按连接模型服务完成登录或保存连接，再选择默认模型。回到设置时，「默认主持模型」应当显示你选中的模型名称。新建冒险后，主持就能使用这个模型处理行动。

寻找模组

可以前往 GitHub 仓库搜索，查找添加了 tarp-module Topic 的仓库。搜索入口预填了 topic:tarp-module，可以保留它并追加关键词，例如 topic:tarp-module 古墓。未添加这个 Topic 的仓库不会出现在结果中；作者分享文件和添加标记的方法见发布模组。

Topic 由仓库作者自行添加，不代表 TARP 审核或推荐。找到仓库后，先阅读它的 README，确认提供的是 TARP 模组，并查看使用条件、分支，以及仓库是否在固定的 module/ 中提供完整模组。普通 D&D 或其他跑团资料不能直接当作 TARP 模组导入，文件结构见模组结构。

取得仓库地址后，按下方「从 Git 导入」操作；作者提供 ZIP 或完整文件夹时，也可以选择对应方式导入。

导入模组

在「设置 → 常规」查看「模组保存路径」。默认位置是系统「文档」目录下的 tarp/modules，首页会列出这个目录里的各个模组文件夹。

首页和模组库点击「导入模组」，选择导入方式：

ZIP：选择一份模组压缩包。可以直接打包模组内容，也可以保留外层文件夹；应用会识别模组所在目录。一个压缩包只导入一个模组，加密 ZIP 需要先解密。
文件夹：选择包含 module.toml 或 module.json 的完整模组内容文件夹，也可以选择包含固定 module/ 的仓库外层。应用只复制模组内容，原文件夹保持不变。
Git：输入仓库地址，按需要填写分支或标签。应用保留完整仓库，固定读取 module/，具体用法见下方说明。

导入完成后列表自动刷新。同名目录已存在时会提示错误，不会覆盖已有模组。导入失败时修复文件或配置后可以重新选择。ZIP 文件最多 512 MiB，单个解压文件最多 512 MiB，解压总量最多 2 GiB、10,000 个文件与目录条目。

手动放入模组

先准备一份完整的模组文件夹，把整个文件夹复制到模组保存路径。不要只复制其中的 module.toml，也不要把内容文件直接散放到保存路径根目录。

如果已经取得源码，可用 apps/desktop/examples/建卡控件演示/ 验证建卡流程；正式游玩按自己取得的模组操作。

目录应该像这样：

模组保存路径/
└── 我的模组/
    ├── module.toml
    ├── .types/
    ├── character/
    ├── location/
    └── …

也可以用「选择文件夹」把保存路径改成已有多份模组的父目录，例如自己整理的模组目录。这里选的是容纳模组的父目录，单份模组的配置文件可以直接放在下一层的模组文件夹中，也可以放在该文件夹的固定 module/ 中；两处不能同时包含清单。

回到首页，应当看到「我的模组」卡片。没有出现时，先确认选的是模组父目录，再重新打开应用读取列表。卡片提示配置或文档错误时，先检查文件是否复制完整；文件命名和必要配置见模组目录结构。

已有完整剧情模组时，也可以复制它提供的整个 module/ 目录，并给复制后的文件夹取一个便于辨认的名字，放在同一个模组保存路径下。想保留本地 Git 仓库用于更新时，可以把完整仓库放在这里，应用只读取仓库中的 module/。

从 Git 导入

在「导入模组」中选择「Git」。先安装系统 Git，再输入仓库的 HTTPS 或 SSH 地址，按需要填写分支／标签；留空使用默认分支。每个仓库提供一个模组，内容必须放在固定的 module/ 中，包含 module.toml 或 module.json、.types/ 和引用素材。

应用下载并检查模组后，把它保存到设置中的模组目录并刷新列表。同名目录已存在时会提示错误；私有仓库使用本机已有的 Git 凭据或 SSH 密钥。

导入保留完整的浅克隆仓库，包括 .git/ 和仓库说明；仓库文件夹使用仓库名，TARP 固定读取里面的 module/。应用不会自动拉取后续更新，也不会初始化 Git 子模块；仓库内容需要使用普通文件和目录，不支持内部符号链接。

手动更新 Git 模组

使用默认分支或指定分支导入时，可以在模组保存路径中的仓库文件夹执行：

cd "<模组保存路径>/<仓库名>"
git pull --ff-only

更新后重新打开模组列表或预览，读取最新文件。新建冒险使用更新后的内容；已有冒险使用独立副本，可按下方「同步已有冒险的模组」手动更新。

指定标签导入的是固定版本，不会通过 git pull 自动跟随分支；需要跟踪更新时，应选择分支导入。文件夹和 ZIP 导入得到的是内容副本，不提供 Git 更新能力。

同步已有冒险的模组

开发模组时，可以把修改同步到已经开始的游戏，继续用当前进度测试。

打开冒险，进入「冒险设置 → 模组与存档 → 模组同步」。
确认来源目录。新建游戏会记录创建时的模组目录；没有来源记录或目录已移动时，点击「选择来源目录」或「更换来源目录」。可以选择模组内容目录，也可以选择包含固定 module/ 的仓库外层。
保存模组修改后，点击「检查更新」。提示「发现模组更新，可以同步」时，点击「同步模组」。

检查只在点击按钮时执行，不自动监听文件，也不会拉取 Git。提示和时间表示上次检查结果；即使没有修改模组版本号，文档、类型、布局、阅读页和附件内容变化也能检测到。同步会重新读取来源，采用点击同步时的最新内容。

同步保留聊天、笔记、角色归属、开局进度、本局新增文档和已修改字段；未被本局修改的字段采用新模组值。数组按整体覆盖保存，已覆盖数组中的元素不会分别继承模组更新。同步不会重新播放开局，也不会替换本局主持指令和独立设置。

AI 正在回复、序章或开场正在播放、回应队列未结束时，先等待完成再同步。不兼容的类型、权限、引用或流程改动会提示具体问题，并保留原存档；删除有本局覆盖或角色记录的文档、让新模组文档与本局新增文档重名，也会拒绝同步。修复来源后可以重新检查、同步。已结束的冒险需要先重新开启。

创建这一局

在模组卡片上点击「开始」。
在「新的冒险」弹窗中填写冒险名称。
点击「创建并进入冒险」。

名称只用来区分你的存档，不会改模组名称。同一份模组可以创建多段冒险，各自保存聊天和游戏状态。

进入后先看到模组封面和简介。点击「准备好了」，再按聊天提示完成开局。如果模组有多个开局，按「选择开局方案」卡片选择；只有一个开局时会直接进入选角。

选一个角色

出现「请选择角色」卡片后，点击想扮演的角色。卡片上的「详情」可以查看角色资料，选定后点击「确认选择」，聊天中的头像和角色名才会更新；确认前保持原有身份。角色被选择时就会占用，取消或换选会释放，不能同时交给自己和 AI 队友。

有些模组允许创建角色，会在名单下方提供建卡入口。按各阶段的提示填写资料或掷骰，核对角色卡并确认。是否能自建、有哪些预设角色，由模组决定。

决定是否和队友一起开场

首次确认自己的角色后，如果还有未占用且支持 AI 扮演的角色，聊天会出现「要添加 AI 队友，一起冒险吗？」选择卡。点击「添加 AI 队友」，选择一名或多名同伴，再点击「开始冒险」；想先自己玩，可以点击「独自开始」。没有可添加的角色时，应用直接开场。

队友选择和已加入的小队会随冒险保存，重新打开后可以继续未完成的步骤。游戏中也可以从「冒险设置 → 冒险小队」添加队友，具体条件见AI 队友。

组队确认后，主持开始交代正式场景。等开场完成，再提交行动；开场还在进行时，可以切到「聊天」先说句话。角色的位置与参与情况由模组状态及主持解释。

写下第一个行动

切到「行动」，确认输入区使用「自动提交」，然后像对主持说话一样写出你的行动。例如：

我先观察营地周围，留意有没有人活动过的痕迹，暂时不离开营地。

把打算做什么、想确认什么说清楚就够了。主持会依据场景和规则回应；需要检定时，掷骰卡片会出现在聊天里，结果由程序生成。

主持完成一条回复，就说明模型和模组可用，行动也已成功提交。想先讨论计划再一起提交，可以改用手动提交；无点名的聊天用于不调用 AI 的消息，合法点名会唤起对应队友，点名「主持人」则用于询问规则或澄清描述。两种提交方式与队友讨论的用法见AI 主持。

冒险界面

右侧主区域始终显示聊天。左侧提供「模组设定」「笔记」和「冒险设置」；笔记和冒险设置在对话框中打开，点击右上角关闭按钮或按 Esc 返回聊天。聊天草稿和滚动位置会保留，主持正在生成的回复也会继续。

笔记对话框再次打开时，会保留本次冒险中的编辑内容。「模组设定」在独立窗口打开，可以与聊天并排查看。

冒险设置采用左侧分类、右侧内容的布局：

模型与主持：当前模型、主持指令。
对话与上下文：主持插话、文档字段订阅、自动压缩。
冒险小队：同伴管理、连续响应上限、队友默认模板和扮演指导。
语音朗读：本局默认声音、自动朗读和主持人声音。
显示与调试：推理细节、全部模组内容。
会话状态：角色上下文、模型用量与手动压缩。
模组与存档：模组同步、结束冒险和永久删除。

切换设置分类或关闭冒险设置前，会尝试保存尚未提交的配置；保存失败时留在当前分类，修正或重试后再离开。本次打开设置期间，各分类保留各自的查阅位置。

开场卡住怎么办

先打开「冒险设置 → 模型与主持 → AI 模型」，检查当前冒险是否选择了模型、连接是否可用。若你在创建冒险后才设置了默认模型，这一局不会自动跟着更新，需要单独选择。

模型配好后，回到聊天，按页面提示点击「继续开场」。应用从当前游戏状态继续，已经完成的开场不会重新播放。调用仍失败时，回到模型连接排查检查。

下次接着玩

聊天、角色变化和笔记会保存到当前冒险。按 Esc 打开退出确认，确认后返回首页；有弹窗或菜单时，Esc 优先关闭当前浮层。退出到首页不会停止后台生成和排队回应；想暂停时先点击「停止生成」，再退出游戏。离开冒险会停止本机语音播放。之后回到首页，点击「继续冒险」打开这份存档即可。

首页展示最近更新的冒险及最多 6 个其他进行中的房间。点击「全部冒险」，可以查看其余进行中的房间和已结束的存档。