Drama Flux 报表 CLI

Node.js 20+ 的只读广告报表命令行工具。npm 包与 Drama Flux Server 的单文件下载入口共用同一份 report-cli.mjs；包内不包含用户凭证。

安装与使用

页面开放 npm 安装后，直接运行：

npm install -g @kunworlds-ai/drama-flux-cli@latest
flux login --server https://你的-drama-flux-域名/api
flux auth status
flux report material --business-model IAP --from 2026-09-14 --to 2026-09-20 --group-by miniProgram,countries,payment
flux logout

让 Agent 先找到剧目或素材

CLI 0.3.0 支持直接查目录，无需知道内部 ID、日期或是否投放过：

flux search drama --keyword "剧名"
flux search drama --serial-number 1049
flux search drama --id "剧目内部ID"
flux search material --keyword "素材名"
flux search material --id "素材内部ID"
flux search material --drama-id "剧目内部ID"

搜索结果包含名称、内部 ID，以及剧目编号和语言或素材所属剧目，便于辨认同名对象。UNIQUE 表示唯一匹配，Agent 可使用返回的 id 查询报表；AMBIGUOUS 表示多个候选，需要进一步明确，不能直接选第一条。剧目编号 serialNumber 与报表使用的 dramaId 不同。NOT_FOUND 表示当前组织没有匹配对象；对象存在但报表为空表示指定条件下没有可见的已同步报表数据。剧目查询需要剧目读取权限，素材查询需要素材读取权限。

例如告诉 Agent“帮我看一下《某剧》哪个解锁集 ROAS 高”，它先运行 search drama，再使用确定的 id 运行 report drama --drama-id。搜索与报表均输出 JSON；业务分析由 Agent 根据数据完成。

电脑授权

运行 flux login 会打开 Drama Flux 浏览器授权页。核对终端和网页的数字，确认电脑名称、组织与有效期；CLI 随后自动保存这台电脑的独立凭证，网页不会显示秘密。若不能自动打开浏览器，运行 flux login --server URL --no-browser，并手动打开终端提供的地址。Windows PowerShell 执行策略阻止脚本时可运行 flux.cmd。

页面关闭 npm 安装入口期间，可以从“广告监控 → 接入 CLI”下载 flux.mjs，然后在该文件所在目录运行 node flux.mjs login --server URL。运行 flux help、flux --help、flux -help 或 flux -h 查看完整参数与指标口径。

个人凭证默认 90 天；网页可选择 7、30 或 90 天，并可在“已授权设备”中单独撤销。旧版手动签发的凭证仍可使用；已有自动化可以通过 --token-stdin 注入凭证，普通用户无需复制令牌。

在 Windows Codex 中使用

CLI 使用原 Windows 登录用户的 DPAPI 加密凭证。Codex 原生沙箱可能以 CodexSandboxOffline / CodexSandboxOnline 独立账户运行，无法继承该用户的登录态。0.3.1 会在这种环境下提前返回明确错误，保留现有凭证。

遇到 WINDOWS_CREDENTIAL_CONTEXT_UNAVAILABLE，让 Agent 通过正常权限审批，以原 Windows 用户执行当前 flux 命令。先验证 flux auth status 成功，再用相同执行方式查询。解密失败不表示服务端会话过期，反复在隔离账户里运行 login 不能解决此问题。

flux auth info 可以在沙箱里读取服务器地址、是否保存过凭证和当前执行身份；它不解密、不联网、不展示秘密，也不证明登录有效。Agent 无需读取凭证文件或分析 CLI 源码来查找服务器地址。

发布检查

在本目录运行 npm pack --dry-run，核对发布包仅含 package.json、README.md 和 report-cli.mjs。prepack 校验 npm 版本与 CLI 版本一致，并运行 CLI 测试。0.2.0 的浏览器授权依赖 Server 的 0280 迁移与新版 Web 授权页；部署并验证后，再由有组织发布权限的账号执行 npm publish --access public，验证无登录安装，最后设置 REPORT_CLI_NPM_INSTALL_AVAILABLE=true。Server Dockerfile 不因 npm 包发布而修改。0.3.0 的目录搜索需要先部署提供 /flux/cli/v1/search 的新版 Server，再发布 npm 包；不需要新的数据库迁移。