命令参考

arcane-fvtt CLI 的命令按职责分为四组：连接调试、只读状态、世界维护 primitive、战斗写入 primitive。

连接和调试

tabs
login
doctor
wait-ready
screenshot
bring-front
canvas-click
debug-eval
profile-execute-turn
  • login：在受控 Chrome 中按显示名或 user ID 选择账号并登录。
  • doctor：检查 world、system、module、GM 和 combat 就绪状态。
  • debug-eval：人工调试后门，默认禁用。只有设置 ARCANE_FVTT_DEBUG_EVAL=1 才会执行。

只读状态

world-info
scene-snapshot
combat-snapshot
actor-search
actor-get
actor-export
token-details
token-actions
build-combat-catalog
combat-context
list-catalog-actions
verify-catalog
refresh-token-actions
action-result
  • world-info：返回当前 world、system、module 版本与激活状态。
  • combat-snapshot / scene-snapshot：读取 combat 或 scene 的完整快照。
  • build-combat-catalog：从当前 scene 的 tokens 构建可用于 combat-context 的 catalog。
  • combat-context：按 Turn Protocol v2 返回当前行动角色的 action contract。

世界维护 primitive

asset-upload
actor-create-from-compendium
actor-import
actor-update
actor-damage-migrate
actor-bilingual-sync
actor-add-items
actor-add-items-from-compendium
actor-set-image
  • asset-upload：上传本地图片到 Foundry data storage。
  • actor-create-from-compendium：从 compendium clone 一个 NPC，并在创建时打补丁。
  • actor-damage-migrate：按 manifest 审计 Actor 旧版攻击基础伤害 bonus，并保存回滚快照。
  • actor-bilingual-sync：按 manifest 审计或同步双语 Actor 规则数据，并覆盖未链接 Token 的 synthetic Actor/ActorDelta。

战斗写入 primitive

create-token
delete-token
use-action
execute-turn
use-catalog-action
apply-token-state
start-combat
next-turn
advance-turn
  • execute-turn：按 Turn Protocol v2 提交 action，返回四态回执。
  • apply-token-state：直接应用 token HP/effect 状态变化。
  • start-combat / next-turn / advance-turn：战斗生命周期控制命令。

角色卡入口原语

角色卡入口需要单独证明时，使用 activity-ui-click。它会打开默认 dnd5e 角色卡、切换到法术或物品页，精确定位 Item/Activity 对应的 activity-use 控件，再发送真实 CDP 鼠标事件；返回值中的 receipt.isTrusted 必须为 true：

{
  "actorIdentifier": "Wave B QA Caster",
  "itemIdentifier": "guiding-bolt",
  "activityIdentifier": "cast",
  "targetTokenIds": ["Wave B QA Fail A"]
}
npm run fvtt:cdp -- --port 9230 --target-url http://127.0.0.1:30000 activity-ui-click --json '@activity-click.json'

需要证明 dnd5e 角色卡正常结束专注时，使用 effect-ui-break-concentration：

{
  "actorIdentifier": "Wave B QA Caster",
  "effectIdentifier": "ActiveEffectId"
}
npm run fvtt:cdp -- --port 9230 --target-url http://127.0.0.1:30000 effect-ui-break-concentration --json '@break-concentration.json'

这些命令只属于本地 QA，不进入 Turn Protocol，也不替代玩家或 DM 的决策。