使用正确的 Folosa 账户
请使用拥有点数和历史生成记录的同一个已验证账户。Bridge 的历史列表严格按账户隔离。
FOLOSA BRIDGE 操作手册
从 Folosa 创意到可上场的 Foundry Actor。
面向 Game Master 的完整操作指南：安装模块、安全连接账户、选择三种创建模式、查看渲染进度、导入新旧任务，并排查整条使用链路。
- Foundry
- V13 及以上；已验证 V14
- 权限
- 需要 Game Master 权限
- 输入
- 引导构建、提示词、上传图片
- 交付
- 校验 WebM 与 PNG 后创建 Actor
1. 开始前准备
安装前先确认账户、文件、权限和 Foundry 环境，避免做到一半才发现条件不满足。
以 Game Master 身份进入 Foundry
只有 GM 可以连接 Bridge、提交消耗点数的任务、向 Foundry Data 写入文件和创建 Actor。
确认 Foundry 版本
使用 Foundry V13 或更高版本；当前已验证 V14。排查问题前先确认模块不是旧版本。
准备上传图片
支持 PNG、JPG、WebP，至少 300x300 px，最大 10 MB。优先使用主体居中、全身完整、手脚武器翅膀和特效四周有余量的图片。
2. 安装并启用模块
可以使用 ZIP 手动安装，也可以在 Foundry 包管理器允许时使用 manifest 地址。
备份世界
添加或更新模块前，先为当前 Foundry 世界创建备份。
安装模块
下载 Bridge ZIP。在 Foundry Setup 中通过 manifest 安装，或把解压后的 folosa-bridge 文件夹放进 Data/modules。
重启 Foundry
重启 Foundry 应用或服务器，让新版脚本和模板完整加载。
在世界中启用
进入目标世界的 Manage Modules，勾选 Folosa Bridge，确认依赖提示并保存。
打开面板
GM 在 Settings 中点击 Folosa Bridge，或按 Ctrl+B。生成期间可以关闭面板。
3. 安全连接账户
Bridge 使用短时设备码和可撤销的最小权限凭据，不会要求你在 Foundry 中输入 Folosa 密码。
开始连接
点击 Connect Folosa，Bridge 会打开 Folosa 授权页，并显示一个临时设备码。
登录 Folosa
在打开的浏览器中登录 folosa.com，批准前先确认显示的邮箱。
批准设备
只批准你认识的 Foundry 客户端和世界。设备码会过期，并且只能用于本次授权。
确认账户栏
返回 Foundry，等待出现 Connected、邮箱、点数和等级。面板会自动轮询状态。
了解权限范围
凭据只能读取点数、创建和读取任务、读取本人资产、创建支付跳转；不能读取密码或其他用户资产。
4. 选择三种创建模式之一
三种模式与网站输入路径对应，但 Bridge 每次只提交一个 Foundry-ready 任务。
Build 引导构建
选择种族、职业、场景和动作。Bridge 自动组织全身 Token 提示词，并加入透明背景和清晰轮廓要求。
Prompt 高级提示词
输入一个不超过 800 字符的精确角色描述。说明单一主体、可见装备、动作和风格，避免互相冲突的镜头或肢体要求。
Upload 上传图片
选择你有权使用的图片。可选动作意图可写“举起原有长剑进入防御姿态”或“用现有手部施法”。
不要混用模式
系统只提交当前激活模式。其他模式中残留的内容不会进入任务，防止隐藏提示词污染上传图片。
选择风格
Dark Fantasy、Anime 和 Ink 控制视觉方向；上传模式下，参考图仍是角色身份来源。
保持可用构图
上传图不要使用肢体被裁切的近景；提示词应明确一个居中、全身、轮廓清楚的主体。
5. 选择质量并理解点数
质量决定交付规格和预留点数，不会建立另一个账户或另一套历史记录。
Standard VTT
每个 Token 80 CRD，目标为适合实时场景的轻量 512p 透明 WebM。
HD Pro
每个 Token 200 CRD，提供更清晰的 1080p 交付，适合主要角色和展示。
4K Master
每个 Token 280 CRD，包含面向高分辨率归档的输出。
预留与结算
任务接受时预留点数，成功后结算；确认属于系统失败时释放预留。渲染需要数分钟不代表失败，不要因此重复提交。
6. 提交、等待、刷新与取消
任务列表是状态事实来源。面板只有一个 Refresh，同时更新账户和任务历史。
复核当前模式
确认模式、图片或提示词、风格、质量和可见点数余额。
只点击一次 Create token
Bridge 使用幂等键，避免同一份已接受提交被系统主动重复计费。
理解状态
Queued 表示等待资源；Processing 表示工作节点或模型正在处理；Completed 表示文件可用；Partial failed 表示至少有一项成功。
继续其他工作
可以关闭 Bridge 或继续准备世界。任务在服务器运行，连接状态下 Bridge 每 10 秒检查一次。
只在按钮出现时取消
Cancel 只对尚未被认领的 queued Bridge 任务显示。进入处理后应等待最终结果，不要重复提交。
重要：外部生成服务认领任务后，处理中任务不能安全撤回。只有尚未被认领的排队任务可以取消。
7. 使用新任务和以前的生成结果
列表显示当前账户最近 50 个任务，包括网页版 Forge 的历史记录。
识别来源
Foundry 表示任务在 Bridge 中创建；Website 表示任务在 folosa.com 网页创建。
自动导入
开启后只自动导入新完成的 Bridge 任务，不会在打开面板时把网站历史批量导入。
手动导入
对任何已完成且兼容的任务点击 Import。Bridge 获取签名下载地址，校验大小和 SHA-256，再上传到 Foundry 并创建 Actor。
打开已有 Actor
任务已导入时点击 Open Actor。以后直接从 Actors 目录把它拖进 Scene 即可复用。
恢复被删除的 Actor
如果 Actor 被删，Refresh 后会重新出现 Import。重新导入只恢复文件和 Actor，不会重新生成或扣点。
8. 在跑团中使用导入的 Actor
Bridge 按任务保存文件，并把动态 Token 与角色头像分开处理。
找到文件
导入文件位于 Data/folosa/tokens/<job-id>。Actor 仍引用这些路径时不要移动或改名。
检查 Actor
打开 Actor，确认 PNG 头像和 WebM Prototype Token 纹理。系统专属 NPC 数据可以正常补充。
放入场景测试
把 Actor 拖到小型测试 Scene，解除暂停，缩放画面，检查透明、循环、尺寸和性能。
安全复用
同一 Actor 可以放进多个 Scene，无需重复导入。只有需要不同属性或 Token 设置时才复制 Actor。
9. 点数、支付与凭据安全
账户和支付通过短时 handoff 打开 folosa.com，Bridge 凭据不会放入支付 URL。
购买点数
点击 Credits 打开当前连接账户和支付页。支付前核对邮箱和点数包，完成后返回 Foundry 使用唯一的 Refresh。
轮换密钥
设备凭据可能泄露时点击 Rotate key。旧凭据会撤销，并为当前客户端替换新凭据。
断开连接
Disconnect 会撤销当前凭据并从这个 Foundry 浏览器配置中移除，但不会删除任务、资产或 Actor。
共享电脑
其他人使用同一 Foundry 客户端前先断开。不要把凭据粘贴到聊天、工单、宏或设置截图中。
10. 故障排查
按表格顺序检查。在确认原任务是否被接受前，不要重新提交。
| 现象 | 先检查 | 解决方法 |
|---|---|---|
| 无法连接 | 检查授权页、邮箱和设备码是否过期。 | 重新发起连接并批准新代码，不要复用过期代码。 |
| 401 或凭据失效 | 确认凭据是否已轮换、撤销或被复制到其他配置。 | Disconnect 后重新连接，一个客户端配置只保留一份凭据。 |
| 余额没有更新 | 确认支付是否在同一邮箱账户完成。 | 点击唯一的 Refresh；仍不一致时先到 Folosa 账户核对交易，不要先提交任务。 |
| 任务一直 Queued | 记录任务 ID 和时间，不要再创建一份。 | 继续等待，或仅在 Cancel 仍显示时取消；队列异常再提交工单。 |
| Processing 已持续数分钟 | 表示外部生成仍在运行。 | 等待即可，关闭面板是安全的，重复提交不安全。 |
| Completed 但 Import 失败 | 检查 GM 权限、Foundry Data 写权限、磁盘空间和浏览器控制台。 | 修正存储权限，Refresh 后再次 Import；不会重新生成或扣点。 |
| Actor 有但视频空白 | 检查 Prototype Token 路径、WebM 支持、场景暂停和设备性能。 | 打开 Actor 核对路径，在解除暂停的小场景测试，低性能设备使用 Standard VTT。 |
| 找不到网站旧任务 | 检查连接邮箱，并确认任务是否在最近 50 条内。 | 先 Refresh；更早记录到 Folosa 账户历史中手动下载。 |
11. 开团前最终检查
正式跑团前，用这份简短验收单检查生成 Token。
账户
已连接预期邮箱，点数余额已经刷新。
任务
任务状态为 Completed 或 Partial failed，而且目标 Token 只有一次提交。
文件
Actor 可以打开，PNG 头像加载正常，WebM Token 纹理能够播放。
场景
在代表性的玩家设备上确认透明、缩放、循环、性能和可见性。
支持证据
真实质量问题请保留任务 ID、时间、模式、质量、截图和简短说明后提交工单；不要附带凭据。