arcane-fvtt CLI

本地 Foundry VTT 操作 CLI，为 Agent 提供稳定、窄口径、可观测的 runtime primitives。

阅读 CLI 文档加入候补名单

一条命令看状态

$ npm run fvtt:cdp -- doctor

$ npm run fvtt:cdp -- combat-snapshot

$ npm run fvtt:cdp -- execute-turn --json '@turn.json'

核心特性

Turn Protocol v2

只公开 selected-targets / self / placed-template 三种 input.mode，枚举参数与目标模式正交，不存在第四种隐式模式。

四态回执

completed / rejected / partial / indeterminate 四态结果，写操作附带 token diff、chat card 与 timing，Agent 不猜状态。

allowlist 安全边界

正常命令走 allowlist；debug-eval 仅在 ARCANE_FVTT_DEBUG_EVAL=1 时启用，任意 eval 不进入主流程。

token diff 可观测性

每次写操作返回 tokenDiffs、itemCardId、warnings 与 timings，结果可审计、可重放、可对比。

获取 CLI

CLI 当前随 ArcaneDesk 开发版分发，安装依赖后即可运行 npm run fvtt:cdp -- doctor。独立 npm 包已列入路线图。

阅读 CLI 文档

execute-turn 返回示例

{
  "status": "completed",
  "sourceTokenId": "pNPz2V5cFKYZmzds",
  "actionKey": "greatsword.attack",
  "targetTokenIds": ["SUnqlZmNomEYNOzh"],
  "tokenDiffs": [
    {
      "_id": "SUnqlZmNomEYNOzh",
      "system.attributes.hp.value": -12
    }
  ],
  "itemCardId": "KxG8p2mQvLrT5wFj",
  "warnings": [],
  "timings": {
    "totalMs": 1847
  }
}