VviLog CLI 技能

此技能用于指导 Agent 使用 vvilog CLI 操作 VviLog，而不是让 Agent 绕过 CLI 直接调用接口。

vvilog CLI 负责：

• 读取和维护本机配置：api_key、base_url、default_project
• 自动携带 X-API-Key 认证头
• 根据请求路径统一访问 /api 或 /manage
• 安装、更新和管理 VviLog skills

配置检查与引导

技能加载后，第一步必须检查 ~/.config/vvilog/config.json 中是否存在 VviLog CLI 配置。优先运行：

node ~/.codex/skills/vvilog-cli/scripts/setup.js --json

如果当前环境尚未安装到 ~/.codex/skills/vvilog-cli，可改用本仓库路径：

node skills/vvilog-cli/scripts/setup.js --json

• 配置完整：含 api_key、base_url，可选 default_project，即可执行用户请求。
• 配置缺失或不完整：先引导用户配置，不要先响应数据查询需求。

配置文件字段以 vvilog CLI 为准：

{
  "api_key": "clk_xxxx",
  "base_url": "https://demo.clklog.com",
  "default_project": "hqq"
}

base_url 是 VviLog 站点根地址，CLI 会自动派生分析 API 的 /api 和管理 API 的 /manage。旧字段 api_base_url、manage_base_url、apiBaseUrl、manageBaseUrl 仅作为兼容既有本地配置读取，不要再引导用户填写。

首次配置

需要配置时，向用户收集以下信息：

请提供 VviLog API Key 和站点根地址，空格或换行分隔。

1. API Key：登录 VviLog 后台 -> 密钥管理 -> 创建并复制密钥，格式通常为 clk_xxxx
2. VviLog 站点地址：私有化部署的 VviLog 根地址，如 https://demo.example.com

回复示例：
clk_abc123  https://demo.clklog.com

拿到配置后使用 CLI 写入：

vvilog config set api_key clk_xxxx
vvilog config set base_url https://demo.clklog.com

然后通过 CLI 查询项目列表，让用户选择默认项目：

vvilog --json request post /manage/project/getlist --body '{"pageNum":1,"pageSize":100}'
vvilog config set default_project <项目编码>

常用命令

环境诊断

vvilog doctor
vvilog --json doctor

配置管理

vvilog config list
vvilog config get base_url
vvilog config set api_key clk_xxxx
vvilog config set base_url https://demo.clklog.com
vvilog config set default_project clklogapp
vvilog config unset default_project

项目列表

vvilog --json request post /manage/project/getlist --body '{"pageNum":1,"pageSize":100}'

事件分析请求

当用户提到事件名、事件次数、事件用户数、事件属性、事件样本、自定义事件、广告事件、归因事件、漏斗前置数据或“设桌率”等事件转化口径时，优先使用 vvilog events 高阶命令。

Agent 做结构化分析时优先使用 --json。用户只想快速看结果时可不加 --json，CLI 会输出指标、分组、漏斗、留存和属性摘要。

vvilog --json events list --project "Arrows And Arrows" --start 2026-08-19 --end 2026-08-25
vvilog --json events query --project "Arrows And Arrows" --event ad_impression --metric TOTAL_TIMES --metric uv --group-by event:ad_network
vvilog --json events ratio --project "Arrows And Arrows" --numerator Set_As_Default --denominator Introduce_Click_Continue --metric uv
vvilog --json events ratio --project "Arrows And Arrows" --numerator Set_As_Default --denominator Introduce_Click_Continue --metric uv --group-by user:user_network --filter 'event:$app_version:equal:3.0.8' --limit 10
vvilog --json events query --project "Arrows And Arrows" --event ad_impression --metric uv --start 2026-08-19 --end 2026-08-25 --compare-start 2026-08-12 --compare-end 2026-08-18
vvilog --json events analyze --project "Arrows And Arrows" --body-file ./analysis.json
vvilog --json events query --project "Arrows And Arrows" --event Set_As_Default --metric uv --event-filter 'event:$app_version:equal:3.0.8'
vvilog --json events properties --project "Arrows And Arrows" --event ad_impression
vvilog --json events distribution --project "Arrows And Arrows" --event ad_impression --property event:ad_network --property user:user_network
vvilog --json events samples --project "Arrows And Arrows" --event Adjust_Get_Promote --limit 20
vvilog --json events funnel --project "Arrows And Arrows" --step Introduce_Page_Show --step Introduce_Click_Continue --step Set_As_Default --step-filter '3:event:$app_version:equal:3.0.8'
vvilog --json events retention --project "Arrows And Arrows" --start-event '$AppStart' --return-event '$AppStart' --return-filter 'event:$app_version:equal:3.0.8' --days 7

常用参数：

• --project-id：已知项目 ID 时优先使用。
• --project：项目展示名、项目编码或 ID；CLI 会自动解析成 projectId。
• --event：事件名。
• ratio --numerator --denominator：查询两个事件的同口径指标并计算分子/分母，适合设桌率、点击率等转化比例；默认建议用 --metric uv，需要按买量/渠道/版本拆分时加 --group-by。
• --metric：指标，可重复传入；支持 TOTAL_TIMES、TRIGGER_USERS、AVG_EVENT_COUNT_PER_USER、SUM(field)、AVG(field)、COUNT_DISTINCT(field)；常用别名是 count 和 uv。
• analyze --body-file：执行完整 /api/event-analyze JSON 配置，适合复杂分析面板、保存配置或多事件多指标查询。
• 前端导出的 vvilog-event-analysis JSON 可直接作为 events analyze --body-file 输入，CLI 会自动读取其中的 eventAnalyzePayload。
• --compare-start、--compare-end：开启周期对比，用于回答“本期比上期/投放前后变化”等问题。
• --filter：全局筛选，格式为 event:name:op:value 或 user:name:op:value，可以重复传入。
• --event-filter：当前指标事件筛选，格式同 --filter。
• --group-by：分组，格式为 event:name 或 user:name，可以重复传入；events query 和 events ratio 都支持。
• properties：扫描某个事件出现过的事件属性和用户属性。
• distribution --property：查询属性值分布，--property 格式为 event:name 或 user:name。
• funnel --step：按顺序传入漏斗步骤，至少两个步骤。
• funnel --step-filter：漏斗步骤筛选，格式为 步骤序号:event:name:op:value。
• retention --start-event --return-event --days：查询留存矩阵，return-event 不传时默认等于起始事件。
• retention --start-filter --return-filter：留存起始/回访事件筛选，格式同 --filter。

只有当前高阶命令无法表达、且不适合写成 events analyze --body-file 配置的底层排障，才退回 /api/event-analyze raw request。

vvilog --json events analyze --project "Arrows And Arrows" --body-file ./analysis.json
vvilog --json request post /api/event-analyze --body-file ./payload.json

访问分析请求

vvilog --json request post /api/flow/getFlow --body '{"projectName":"clklogapp","timeType":"day","channel":[]}'

复杂请求体优先写入临时 JSON 文件，再通过 --body-file 传入，避免 shell 引号和中文编码问题：

vvilog --json request post /api/flow/getFlowTrend --body-file ./payload.json

Skill 管理

vvilog skills list
vvilog skills releases
vvilog skills find cli
vvilog skills add vvilog-cli
vvilog skills remove vvilog-cli

项目编码选择规则

projectName 是项目编码，不是展示名称。确定规则按优先级：

1. 用户明确说了编码，例如“查 clklogapp 项目”：直接使用。
2. 用户说的是展示名称，例如“查 clklog”：先用 vvilog --json request post /manage/project/getlist --body '{"pageNum":1,"pageSize":100}' 获取项目列表，再匹配对应编码。
3. 用户没有指定项目：使用 vvilog config get default_project 或 vvilog config list 中的 default_project。
4. 无法确定项目：刷新项目列表并让用户选择。

切换项目后，如果涉及渠道筛选，需要重新查询该项目的渠道列表。

事件分析例外：vvilog events 和 /api/event-analyze 使用 projectId。用户给展示名时可以直接传 --project "<展示名>" 让 CLI 解析，不要把展示名或 projectName 填进 projectId。

请求路径约定

vvilog request 的路径必须以 /api/ 或 /manage/ 开头：

• 分析接口：/api/...
• 管理接口：/manage/...

不要在 Skill 中直接拼接 curl、fetch、Node HTTP 请求或数据库查询来替代 CLI。除非用户明确要求底层排障，否则所有 VviLog 后端访问都应通过：

vvilog request <method> <path> [--body <json>] [--body-file <file>]

API 参考

加载 references/api_docs.md 获取常见 VviLog 接口、请求体和字段说明。该文档只作为选择 CLI 请求路径和请求体的参考，不表示 Agent 应直接调用 API。

场景模板

当用户描述的是具体任务场景，而不是明确给出接口路径时，加载 templates/index.md 选择真实业务模板，再结合 references/api_docs.md 生成 CLI 命令。

模板按当前前端菜单和后端 Controller 组织，用于统一 Agent 的业务路由、必要前置检查、命令示例和结果解释方式。模板不是固定脚本；执行时应根据用户项目、时间范围、渠道、事件类型和当前 CLI 配置调整参数。

关键注意事项

• 管理 API 和分析 API 都通过同一个 API Key 授权，CLI 会自动携带请求头。
• 如果返回 401/403，优先让用户更新 api_key。
• 请求返回的 code 通常为整数 200 表示成功。
• timeType 控制趋势分组粒度，不是时间范围本身：多日趋势通常用 "week"，单日小时趋势通常用 "day"。
• 渠道参数沿用前端业务枚举：安卓、苹果、网站、微信小程序；不确定时传 [] 表示全部，不要编造不存在的渠道列表接口。
• 下载类接口返回二进制文件流，使用 CLI 时应保存到文件或后续扩展专用命令。