Drama Flux 报表 CLI

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

安装与使用

直接通过公共 npm 包安装：

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

从旧组织包升级

首次安装直接使用上面的新包名即可。已安装 @kunworlds-ai/drama-flux-cli 的电脑先卸载旧包，再安装新包，避免两者争用同一个 flux 命令：

npm uninstall -g @kunworlds-ai/drama-flux-cli
npm install -g @kunworlds-cli/drama-flux-cli@latest
flux --version

命令仍为 flux，准备发布的仓库版本为 0.6.0。本机 .drama-flux-cli 配置目录和已有有效登录授权保留，无需为更换包名重新授权。

CLI 0.6.0：小时指标

先用 flux search drama 或 flux search ad 取得内部 ID，再读取本地最近 1～168 个小时桶：

flux search ad --keyword "广告名或平台广告ID"
flux search ad --drama-id "剧目内部ID"
flux hourly drama --drama-id "剧目内部ID" --hours 168
flux hourly ad --ad-id "广告内部ID" --hours 168

省略 --hours 默认 168。records 只返回平台真实小时行，不返回物理补零行；hourOfDay 按账户报表当地小时汇总已完成的小时，方便比较消耗、样本与购买/订阅/广告收入 ROAS。coverageByHour 的 CONFIRMED_ZERO_SPEND 才表示缺行确认为零消耗，UNKNOWN 表示没有足够的同步证据。不同币种、IAA/IAP 和报表时区分开。小时表现不能单独证明在该小时开机更好。需要先部署支持 /flux/cli/v1/hourly 的 Server，并给用户授权 metrics:hourly:read；仓库版本号不代表 npm 已发布。

CLI 0.5.0

本版本包含 macOS/Linux npm 命令软链接启动修复。安装后先运行 flux --version（应输出 0.5.0）及 flux help 验证入口，再运行登录命令。正常使用直接运行 flux，无需额外的 node 命令。

最近七天查询使用 --preset last7，包括各广告账户当地今天，由服务端按账户时区解析：

flux report drama --drama-id "剧目内部ID" --business-model IAP --preset last7 --group-by payment,unlock --all

--preset last7 与 --from/--to 互斥；显式日期继续支持。结果的 query.dateWindows 提供实际日期与时区，display 提供网页名称对应的百分比值，原始指标仍为精确数值字符串。充值配置以报表权限、组织和广告账户读取范围授权，不受渠道创建人或个人可见名单限制；投放侧原有渠道规则不变。历史配置缺失原因由 configurationDiagnostics 和 configurationIssues 分别说明，不用当前配置替代历史值。

发布顺序为先部署配套 Server，再发布 npm 0.5.0。仅更新本机 CLI 不会更新服务端的日期、权限或诊断能力；旧 Server 不支持 last7 时明确报错，不在本机推算日期。无需新增数据库迁移。

让 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。

既有单文件客户端可以继续使用 node flux.mjs；网页仅展示 npm 安装引导。运行 flux help、flux --help、flux -help 或 flux -h 查看完整参数与指标口径，子命令也支持 --help。

个人凭证默认 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，验证无登录安装。Server Dockerfile 不因 npm 包发布而修改。0.3.0 的目录搜索需要先部署提供 /flux/cli/v1/search 的新版 Server，再发布 npm 包；不需要新的数据库迁移。

一次性全量报表（0.4.0）

flux report ... --all 使用一次数据库聚合取得完整结果，避免翻页重复计算和期间排序变化。需要先部署支持 all=true 的新版 Server，再发布 CLI 0.4.0；原凭证、登录、搜索和单页报表保持兼容。旧 Server 不支持时明确提示升级，不静默使用逐页查询。

全量最多 10,000 个分组且 records JSON 不超过 8 MiB。超限请限定日期、账户、剧目或素材；不把截断结果当成完整排名。Server 全库同时最多两条重报表、同用户最多一条，繁忙时稍后重试。端原生归因与排除规则保持不变。

单对象配置对比与查询边界（0.4.0）

每次报表必须提供单个 --drama-id 或 --material-id。某剧全部素材用 report material --drama-id；跨剧分析逐剧串行请求，不能一次发起全组织报表。--all 只读取该对象范围内的全部分组，仍受 10,000 组 / 8 MiB、30 秒超时和并发限额约束。旧 CLI 未提供对象 ID 的请求同样被新版 Server 拒绝。

• IAP 同素材或同剧：--group-by payment,unlock，比较完整充值配置与起始收费集。广告指标不能识别用户实际选购哪一个可选档位，不提供虚构的档位购买转化率。
• IAA 同素材或同剧：--group-by unlock,preferInterstitial,unlockNumber，比较起始锁定集、是否优先插屏及每次广告解锁集数。不优先插屏不等于禁用插屏。
• 日期、币种、转化事件和样本量需一致；国家、小程序等分层可继续追加。点击 CVR 检查 conversionRateByClickCoveredClicks，充值、锁定集和插屏配置检查 coverage；缺失保持未知。

新分组需要部署更新后的 Server。沿用 0279/0280 迁移，不新增第三方调用或表；历史配置只从成功创建证据回填，不用当前可编辑配置假冒初始事实。

Agent 只看 help 的使用方式

安装包内的 flux help 包含登录检查 → 目录搜索 → 唯一对象确认 → 限定范围报表 → 完整性检查 → 指标解释的操作顺序，无需访问源码。六种完整报表示例覆盖同素材、同剧、一部剧全部素材的 IAP/IAA 对比；另列出全部分组与筛选项、默认分组、返回字段、权限和错误恢复说明。示例中的 ID 和日期必须替换为实际值，不能复制占位符当作真实数据查询。

apps/server/test/ad-report-cli.test.ts 会直接读取 help 输出中的六条命令，替换占位符后运行 CLI，再使用真实 reportQuerySchema 校验产生的 API 参数；每条全量示例只能发起一次限定对象的请求。公共 npm 包的 help 与服务端下载文件使用同一实现。修改 help 后应继续执行此测试及包安装验证，防止文案与接口漂移。