快速开始

这页适合你：你已经有一个 AI Agent（Claude Code、Kimi，或自己写的 Agent），想让它直接操作你本机的 Foundry VTT。

arcane-fvtt 就是这座桥：把你的 Agent 接上 Foundry——读战斗状态、执行回合、维护世界，一条命令一个动作，每个动作都返回明确的结果回执，Agent 不用猜。它不是战术 AI：怎么打由你的 Agent 决定，它只负责把动作可靠地落进 Foundry。

五分钟跑通

  1. 启动一个可调试的 Chrome（见下文「启动 Chrome」）。
  2. 登录 Foundry（见下文「登录 Foundry」）。
  3. 跑第一条命令：npm run fvtt:cdp -- --port 9230 --target-url <你的 Foundry 地址> doctor，看到 JSON 状态输出就通了。

它是怎么工作的

CLI 通过 Chrome DevTools Protocol（CDP）直连已经打开的 GM Foundry 页面，再触达 game / canvas / dnd5e / midi-qol API：

Agent / Skill
  -> arcane-fvtt CLI
  -> Chrome DevTools Protocol
  -> Foundry browser page
  -> game / canvas / dnd5e / midi-qol APIs

读操作返回 Agent 容易消费的 JSON；写操作的回执里带 chat card、HP/effect 变化、warning 和耗时。战斗策略、QA 判定、fallback 逻辑写在 Agent 一侧，不在 CLI 里。

启动 Chrome

推荐用专用脚本启动一个可调试 Chrome。它会使用独立 profile，打开 CDP 端口 9230，默认把窗口放在正常显示区域，并禁用后台 timer throttling：

.\scripts\start-fvtt-chrome-fast.ps1 -KillExisting

这个脚本只会杀掉使用同一 debug port 或专用 Arcane Foundry profile 的 Chrome，不会关闭普通工作浏览器。默认窗口会显示在正常桌面区域，便于登录和观察 Foundry。只有确实需要屏幕外运行时才传 -Offscreen。

如果使用自己启动的 Chrome，至少需要：

--remote-debugging-address=127.0.0.1
--remote-debugging-port=9230

战斗自动化建议再加：

--disable-background-timer-throttling
--disable-renderer-backgrounding
--disable-backgrounding-occluded-windows
--disable-features=CalculateNativeWinOcclusion

基本用法

从仓库根目录运行：

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top doctor
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top world-info
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top scene-snapshot
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top combat-snapshot

登录 Foundry

login 会在受控 Chrome 的 Foundry /join 页面中按显示名或 user ID 精确选择账号，填写访问密码并等待 /game 就绪。登录必须用 --origin（或 ARCANE_FVTT_ORIGIN）声明精确的 Foundry origin；CLI 会严格核对 scheme、host 和 port，避免把密码交给错误页面。默认要求最终用户具有 Gamemaster 权限；已经以同一 Gamemaster 登录时会幂等成功，已经登录为其他用户时不会自动登出或切换。

建议为登录单独启动 Chrome 端口和 profile。例如本地世界：

.\scripts\start-fvtt-chrome-fast.ps1 `
  -Port 9231 `
  -UserDataDir "$env:LOCALAPPDATA\ArcaneDesk\ChromeFoundryLogin-9231" `
  -Url "http://127.0.0.1:30000/game"

无访问密码的账号只需指定名称：

npm run fvtt:cdp -- --port 9231 login --origin http://127.0.0.1:30000 --user GM2

有密码时不要把明文密码放进命令参数。可以用隐藏输入临时设置环境变量：

$securePassword = Read-Host "Foundry access password" -AsSecureString
$env:ARCANE_FVTT_PASSWORD = [System.Net.NetworkCredential]::new("", $securePassword).Password
try {
  npm run fvtt:cdp -- --port 9231 login --origin http://127.0.0.1:30000 --user Gamemaster
} finally {
  Remove-Item Env:ARCANE_FVTT_PASSWORD -ErrorAction SilentlyContinue
}

也可以用 --password-file <path> 从受保护的文件读取密码；文件末尾的一个换行会自动去掉。CLI 不提供明文 --password 参数，因为 npm run 会把命令参数回显到日志。登录 JSON 输出和错误详情会对已解析的非空密码做递归脱敏。如确实要允许普通玩家账号，可显式加 --no-gm。

开发验证

类型检查和单测：

npm run fvtt:cdp:typecheck
npm run fvtt:cdp:test

浏览器 smoke：

npm run fvtt:cdp -- --port 9231 login --origin http://127.0.0.1:30000 --user GM2
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top doctor
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top combat-snapshot

写入 smoke 只在可接受的测试场景里运行。生产世界中不要做模糊批量清理；任何批量删除都必须有明确 pattern 和显式确认。