lbp-growth-calendar

增长日历 CLI 工具 —— Agent AI Friendly 规范

特性

• 结构化 JSON 输出：所有命令默认输出 { "ok": true, "data": ... } 结构，方便 AI Agent 和程序化调用
• 清晰的命令层次：auth（认证）、dau（查询）、events（增删改查）、correct-meta/correct-event/correct（订正）、penetration（AI 渗透率）
• AI Friendly 原子操作：订正接口是全量覆盖语义，CLI 提供 correct-meta 与 correct-event add|update|delete 自动合并当日数据，避免误删
• 全量高级模式：correct 命令支持直接传完整 events 列表或 JSON 文件，适合脚本批处理
• 一致的错误结构：错误输出 { "ok": false, "error": "CODE", "message": "..." } 且退出码非 0
• 无交互式设计：所有命令完全非交互式，所有参数通过 CLI 参数传入，适合自动化脚本和 AI Agent 调用
• 强制配置检查：所有业务命令（dau / events / correct）强制从本地配置文件读取 API Key，不支持命令行传入 token。未配置时自动提示执行 auth init → auth verify 流程

安装

npm install -g lbp-growth-calendar-cli

认证

所有业务命令需要 API Key。应先检查认证状态，只在未授权或授权失效时才完成授权流程。

认证检查流程

auth status
  ├── configured: true  → 直接执行业务命令
  ├── configured: false + 有 authCode → 执行 auth verify <authCode>
  └── configured: false + 无 authCode → 执行 auth init → 浏览器授权 → auth verify <code>

步骤 1：检查当前认证状态

lbp-growth-calendar auth status

• 若返回 configured: true → 直接执行业务命令，不要重复授权。
• 若返回 configured: false 但有 authCode → 执行步骤 2b（跳过 init）。
• 若返回 configured: false 且无任何认证信息 → 执行步骤 2a（完整授权流程）。

步骤 2a：完整授权流程（首次使用或认证已清除）

# 获取授权码
lbp-growth-calendar auth init

在浏览器中访问返回的 authUrl，完成登录授权。

用户确认已授权后：

lbp-growth-calendar auth verify <auth-code>

步骤 2b：继续未完成授权（已 init 但未 verify）

lbp-growth-calendar auth verify <auth-code>

authCode 从 auth status 的输出中获取。

步骤 3：验证

lbp-growth-calendar auth status

若返回 configured: true，即可调用业务命令。

查询 DAU 数据

lbp-growth-calendar dau list --start-date 2026-07-01 --end-date 2026-07-31

事件管理

# 查询事件列表
lbp-growth-calendar events list --start-date 2026-07-01 --end-date 2026-07-31
lbp-growth-calendar events list --event-type activation

# 获取 / 创建 / 更新 / 删除
lbp-growth-calendar events get <event-id>
lbp-growth-calendar events create --date 2026-07-15 --event-type activation \
  --name "渠道投放-抖音" --expected-users 4.2 --tags "渠道&SMB"
lbp-growth-calendar events update <event-id> --name "渠道投放-快手" --expected-users 5.1
lbp-growth-calendar events delete <event-id>

数据订正（推荐 AI Friendly 原子操作）

订正接口 POST /openapi/dau/correct 是 全量覆盖 语义（未列出事件会被删除）。为便于 AI 与人工使用，CLI 提供两种模式：

模式 1：AI Friendly 原子操作（推荐）

CLI 自动拉取当日现状并合并本次改动，避免误删事件。

# 只订正 DAU / 额度 / 说明（事件保持不变）
lbp-growth-calendar correct-meta --date 2026-07-15 \
  --corrected-dau 35.0 \
  --quota 12.5 \
  --correction-note "新版本灰度放量"

# 只改其中一项也可以：只订正说明
lbp-growth-calendar correct-meta --date 2026-07-15 --correction-note "确认为正常波动"

# 新增一条订正事件（其它事件与 meta 不变）
lbp-growth-calendar correct-event add --date 2026-07-15 \
  --event-type activation \
  --name "渠道投放-抖音" \
  --expected-users 4.2 \
  --tags "渠道&SMB"

# 更新指定事件的字段
lbp-growth-calendar correct-event update e805f39d-a380-4244-a8c5-aae58ebc63a3 \
  --date 2026-07-15 \
  --expected-users 5.1

# 删除指定事件
lbp-growth-calendar correct-event delete e805f39d-a380-4244-a8c5-aae58ebc63a3 \
  --date 2026-07-15

模式 2：全量订正（高级/脚本使用）

直接传完整 events 列表，未列出的事件会被删除。适合脚本批处理。

# 通过 --events JSON 字符串
lbp-growth-calendar correct --date 2026-07-15 \
  --corrected-dau 35.0 --quota 12.5 --correction-note "订正说明" \
  --events '[{"id":"e805...","eventType":"activation","name":"渠道投放-抖音","expectedUsers":4.2,"tags":["渠道&SMB"]},{"eventType":"recall","name":"新召回事件","expectedUsers":1.0}]'

# 通过 --events-file JSON 文件
lbp-growth-calendar correct --date 2026-07-15 \
  --corrected-dau 35.0 --quota 12.5 \
  --events-file events.json

目标与现状查询

查询各客户分群的 DAU/额度目标、当前进度与历史最高值（默认昨天，自动跳过周末取最近工作日）。

# 查询昨天（自动回退到最近工作日）
lbp-growth-calendar target list

# 指定日期
lbp-growth-calendar target list --date 2026-07-13

# 按分群筛选（多个逗号分隔）
lbp-growth-calendar target list --date 2026-07-13 --industries "大制造,大消综"

客户日数据

# 按日期查询客户日数据列表（支持模糊搜索、精确筛选与分页）
lbp-growth-calendar customer-daily list --date 2026-08-05
lbp-growth-calendar customer-daily list --date 2026-08-05 --customer-name ByteDance --display-id F123456

# 根据 ID 获取单条客户日数据
lbp-growth-calendar customer-daily get <id>

# 批量创建或更新客户日数据（按 date+customer_name 幂等 upsert）
lbp-growth-calendar customer-daily batch-create --items '[{"date":"2026-08-05","customerName":"ByteDance","displayId":"F123456","smartPartnerDau":3500}]'

# 批量删除客户日数据
lbp-growth-calendar customer-daily batch-delete --ids "id1,id2"

# 客户日数据趋势分析（按天/周对比最后一个工作日）
lbp-growth-calendar customer-daily trend --date 2026-08-06 --granularity day
lbp-growth-calendar customer-daily trend --date 2026-08-06 --granularity week

AI 渗透率数据

# 查询
lbp-growth-calendar penetration list --start-date 2026-07-01 --end-date 2026-07-31

# 新增
lbp-growth-calendar penetration create \
  --type free \
  --date 2026-07-15 \
  --tenant-type paid_conversion \
  --feishu-dau 120.5 \
  --activated-users 8.6

# 幂等写入
lbp-growth-calendar penetration upsert \
  --type paid \
  --date 2026-07-15 \
  --customer-industry retail \
  --arr 100000 \
  --smart-partner-dau 3.6

命令参考

Auth 命令（认证管理）

| 命令 | 说明 | AI/Agent 友好 | |------|------|---------------| | auth init | 发起授权流程，获取授权码和授权链接 | ✅ 非交互式 | | auth verify <code> | 用授权码换取 API Key 并保存到本地配置 | ✅ 非交互式 | | auth status | 查看当前认证配置状态 | ✅ 输出结构化 JSON | | auth clear | 清除本地保存的所有认证信息 | ✅ 非交互式 |

DAU 命令

| 命令 | 说明 | |------|------| | dau list [--start-date] [--end-date] | 按日期范围查询每日 DAU 数据 |

Events 命令

| 命令 | 说明 | |------|------| | events list [--start-date] [--end-date] [--event-type] | 查询事件列表 | | events get <id> | 获取单个事件详情 | | events create --date --event-type --name --expected-users [--tags] | 新增事件 | | events update <id> [--name] [--expected-users] [--tags] | 更新事件 | | events delete <id> | 删除事件 |

客户日数据命令

| 命令 | 说明 | |------|------| | customer-daily list --date [--customer-name] [--display-id] [--data-type] [--page] [--page-size] | 按日期查询客户日数据列表 | | customer-daily get <id> | 根据 ID 获取单条客户日数据 | | customer-daily batch-create --items | 批量创建或更新客户日数据（幂等 upsert） | | customer-daily batch-delete --ids | 根据 ID 列表批量删除客户日数据 | | customer-daily trend --date --granularity | 客户日数据趋势分析（按天/周对比） |

订正命令

| 命令 | 模式 | 说明 | |------|------|------| | correct-meta --date [--corrected-dau] [--quota] [--correction-note] | 原子 | 只改 DAU/额度/说明，事件保持不变 | | correct-event add --date --event-type --name --expected-users [--tags] [--correction-note] | 原子 | 新增一条订正事件 | | correct-event update <id> --date [--event-type] [--name] [--expected-users] [--tags] [--correction-note] | 原子 | 更新指定事件 | | correct-event delete <id> --date [--correction-note] | 原子 | 删除指定事件 | | correct --date [--corrected-dau] [--quota] [--correction-note] (--events \| --events-file) | 全量 | 直接传完整 events 列表 |

输出格式

成功

{
  "ok": true,
  "data": { ... }
}

失败

{
  "ok": false,
  "error": "NOT_FOUND | INVALID_ARGS | REQUEST_FAILED | API_ERROR",
  "message": "错误描述"
}

返回码

| 码 | 含义 | |----|------| | 0 | 成功 | | 1 | 请求失败 / 参数错误 / 资源不存在 |

Agent 使用示例

const { execSync } = require('child_process');

// 先确认认证状态
const status = JSON.parse(execSync('lbp-growth-calendar auth status', { encoding: 'utf8' }));
if (!status.configured) {
  console.error('请先执行 auth init → auth verify 完成授权');
  process.exit(1);
}

const dauData = JSON.parse(execSync(
  'lbp-growth-calendar dau list --start-date 2026-07-01 --end-date 2026-07-31',
  { encoding: 'utf8' }
));
if (dauData.ok) console.log('DAU 数据:', dauData.data);

const createRes = JSON.parse(execSync(
  'lbp-growth-calendar events create --date 2026-07-15 ' +
  '--event-type activation --name "渠道投放-抖音" --expected-users 4.2 --tags "渠道&SMB"',
  { encoding: 'utf8' }
));
if (createRes.ok) console.log('创建成功:', createRes.data);

execSync('lbp-growth-calendar correct-meta --date 2026-07-15 --correction-note "确认正常波动"');

License

MIT