安全边界与性能

这页讲两件事：Agent 能碰什么（安全边界）、动作要跑多快（性能约束）。把 CLI 接进你自己的 Agent 主流程之前，先读这页。

安全边界

正常命令都走 allowlist。不要把任意 eval 暴露给 agent 或 skill 主流程。

接受 --json 的命令可以传 JSON 字面量、@file.json，或传 @- 从标准输入读取；动态 Token ID 等运行时参数优先通过标准输入传递，避免 shell 重写 JSON 引号。

debug-eval 是人工调试后门，默认禁用。只有设置下面的环境变量才会执行：

$env:ARCANE_FVTT_DEBUG_EVAL = "1"
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top debug-eval --expr --script "game.world.id"

debug-eval 可以用于临时读取设置、做 A/B 探索、检查 Foundry runtime 数据结构；确认有效的逻辑必须收敛成正式 allowlist 命令。

性能约束

实时 combat agent 的目标是：

单个行动从发起到结果返回 <= 10s

已确认的关键点：

• Chrome hidden/background 页面会把短 timer clamp 到约 1 秒，导致 Foundry/midi workflow 从亚秒级变成十几秒。
• 专用 Chrome 启动脚本或 --foreground 可以把 completeItemUse 恢复到约 0.5–0.9 秒级。
• 当前剩余主要成本是 npm/tsx/CDP connect 和命令启动。后续生产路径应使用编译后的 node dist/cli.js 或常驻进程。

性能记录见：

docs/foundry-automation/direct-cdp-combat-performance-optimization.md

详细设计

接口设计、后续命令规划和已知问题见：

docs/foundry-automation/direct-cdp-fvtt-cli-design.md