analyticscli-cli

AnalyticsCLI CLI

使用此技能的场景

• 查询 AnalyticsCLI 项目的产品分析数据
• 验证 SDK 埋点是否正确生效
• 通过 AnalyticsCLI 查看或提交项目反馈
• 在不使用原始 SQL 的情况下，回答有关新手引导、付费墙、问卷、留存或导出的问题

支持的版本

• 技能包：1.0.7
• 目标包：@analyticscli/cli
• 支持范围：>=0.1.3 <0.2.0
• 如果未来的 CLI 主版本以不兼容的方式更改命令或标志，应拆分出一个同级技能，例如 analyticscli-cli-v1

请参阅版本说明。

非目标

• 不要生成原始 SQL。
• 不要请求无上限的原始事件转储。
• 除非用户明确提出要求，否则不要包含调试数据。

安全规则

• 始终限定项目上下文：使用 analyticscli projects select 设置一次默认项目，或在需要时传入 --project <id>。
• 始终限定时间范围：使用 --last 或明确指定 since/until。
• 优先使用高级查询端点，而非原始导出。
• 限制分组和结果集的范围。
• 默认仅使用发布版本数据。
• 切勿通过 CLI 标志或内联字面量传递密钥（存在通过 argv/命令行历史记录泄露的风险）。请改用交互式提示。
• 生成文档或帮助文本时，使用租户开发者的口吻（your workspace、your project），避免使用以服务提供方为中心的措辞，例如 our SaaS。
• 随 CLI 更新 analyticscli-cli 技能，但不要自动强制更新各代码库中的 analyticscli-ts-sdk 技能。

错误恢复顺序

发生问题、错误、意外输出或 CLI/API 功能缺失时：

1. 重新获取此技能并先更新 CLI。
2. 重新运行完全相同的失败命令，或运行最小可复现命令。
3. 如果没有更新版本、更新失败，或最新版本仍存在问题，请使用 analyticscli feedback submit 向 AnalyticsCLI SaaS 所有者提交经过脱敏的产品反馈。

建议的更新检查：

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli || npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

反馈必须包含版本/更新尝试、失败的命令或端点、经过脱敏的负载结构、状态/错误正文（如有，请包含请求 ID）、预期行为、实际行为及解决方法。

查询优先级

优先使用以下命令系列：

• funnel
• conversion-after
• paths-after
• retention
• survey
• timeseries
• breakdown
• generic

仅当用户明确需要原始 CSV 时，才使用 events export。

反馈命令

当任务涉及对 AnalyticsCLI 本身的反馈时，例如缺少功能、CLI/API/仪表板行为异常、错误信息令人困惑、文档质量差或工作流受阻，请使用以下命令：

analyticscli feedback list --last 30d --format json
analyticscli feedback summary --last 30d --format json
analyticscli feedback submit --category bug --message "Short symptom" --origin-name "dashboard feedback form" --location-id "dashboard/feedback"

规则：

• 不要将其与 AnalyticsCLI 反馈功能收集的、由租户拥有的终端用户反馈混淆
• 当其他工具或技能需要范围受限的主题摘要时，优先使用 feedback summary --format json
• 当需要确切的原始消息时，优先使用 feedback list --format json
• 提交时，如已知 origin-name 和 location-id，务必一并提供
• 对于 API/CLI 故障，请先更新/重新获取当前技能和 CLI；如果最新可用版本仍然失败，请提供经过脱敏的端点/命令、版本/更新尝试、状态码、错误正文（如有，请包含请求 ID）、预期行为，以及所用的解决方法

数据保真规则

• CLI 和仪表板都查询 API。不存在仅供 CLI 使用的独立分析数据源。
• 对顺序和队列敏感的查询应使用原始事件。
• 仅当 API 报告了相应的计划结构时，才可接受基于聚合数据的读取。
• SDK 会自动附加 runtimeEnv。不要另行编造模式字段。

一次性设置

运行设置前，请从信息中心收集所需值：

• 打开 dash.analyticscli.com 并选择目标项目。
• 在 API Keys 中创建/复制 readonly_token（CLI 令牌，范围为 read:queries）。
• 如果 SDK 埋点在范围内，请从同一 API Keys 页面复制可公开的摄取 API 密钥。
• 可选：复制 project_id，以便显式覆盖单个命令的项目。
• 登录后，通过 analyticscli projects select 一次性设置默认项目（使用方向键的交互式选择器）。

首选：

npm install -g @analyticscli/cli
command -v analyticscli
npx -y @analyticscli/cli setup
# Paste readonly token only when prompted; do not pass token as a command argument.

替代方案：

analyticscli login
# Choose readonly-token interactively; do not put tokens in command args.

如果出现 analyticscli: command not found，请安装或更新 npm 包。包名为 @analyticscli/cli；二进制名称为 analyticscli。

请勿在 npm 上搜索 analyticscli 或 analyticsscli。

npm install -g @analyticscli/cli
analyticscli --help

在禁止全局 npm 安装的 VPS 主机上，请使用用户本地前缀：

mkdir -p "$HOME/.local"
npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
analyticscli --help

仅获取或更新此技能本身并不足够。 每次更新技能后，也要更新 npm 包并验证二进制：

npx -y skills add wotaso/analyticscli-skills --skill analyticscli-cli
npm install -g @analyticscli/cli || npm install -g --prefix "$HOME/.local" @analyticscli/cli
export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"
command -v analyticscli
analyticscli --help

如果 command -v analyticscli 仍无输出，但存在用户本地二进制，请先自行更新 shell 配置文件，再报告成功：

for f in "$HOME/.profile" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zshrc" "$HOME/.zprofile"; do
  touch "$f"
  grep -Fq 'export PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"' "$f" ||
    printf '\n# AnalyticsCLI CLI user-local npm bin\nexport PATH="$HOME/.local/bin:$HOME/.local/analyticscli-npm/bin:$PATH"\n' >> "$f"
done
bash -lc 'source "$HOME/.bashrc" 2>/dev/null || true; source "$HOME/.profile" 2>/dev/null || true; command -v analyticscli && analyticscli --help >/dev/null'

在你能控制的同一命令上下文中，成功运行 command -v analyticscli && analyticscli --help >/dev/null 之前，请勿声称 analyticscli 已修复。

输出模式

• 自动化或 Agent 推理时，优先使用 --format json。
• 简短的人类可读摘要请使用 --format text。
• 需要精确值时，请使用 timeseries --viz table。
• 只需扫描趋势时，请使用 timeseries --viz chart 或 svg。

验证循环

SDK 部署或查询变更后，请通过几次稳定读取进行验证：

analyticscli schema events --limit 200
analyticscli goal-completion --start onboarding:start --complete onboarding:complete --last 30d
analyticscli get onboarding-journey --last 30d --format text

空状态指南（必需）

当用户没有任何已列出的项目时：

• 说明他们需要先创建第一个项目，CLI 查询才能返回分析数据。
• 引导他们在 AnalyticsCLI 信息中心 (dash.analyticscli.com) 中创建项目。
• 创建后，运行 analyticscli projects list，然后使用 analyticscli projects select 设置默认项目。

当项目已存在但尚无事件时：

• 说明该项目尚未开始数据摄取。
• 告知用户在应用代码库中集成 @analyticscli/sdk。
• 告知用户使用 Dashboard -> API Keys 中的可公开 API 密钥初始化 SDK。
• 告知用户触发至少一个事件，然后重新运行 analyticscli schema events --project <id> --last 14d。
• 如果他们已经集成 SDK，建议扩大 --last 的范围或移除限制性筛选条件，然后再进行深入调试。

缺失功能处理流程

如果当前 CLI 功能无法完成所请求的数据获取：

1. 说明缺少此功能。
2. 如果其他命令并不等效，请勿假装它们等效。
3. 向 AnalyticsCLI 反馈存储提交一份可复现的缺口报告。

analyticscli feedback submit \
  --category feature \
  --message "Missing CLI functionality: <short capability>" \
  --origin-name "analyticscli cli" \
  --location-id "analyticscli-cli" \
  --context "Requested fetch: <what user asked>; attempted command: <command>" \
  --meta '{"expected":"<expected output>","actual":"CLI has no command or endpoint"}'

自动反馈规则

当用户报告行为异常、输出不符合预期或功能缺失时，首先更新/重新获取当前技能和 CLI，然后重试最小复现步骤。如果没有更新版本、更新受阻，或最新版本仍然失败，请先解释问题，然后自动提交一份简洁的 analyticscli feedback submit 报告。

包括：

• 在 --message 中清楚描述症状
• 在 --context 中提供准确的失败命令或操作流程
• 在 --meta 中说明预期行为与实际行为
• 在 --context 或 --meta 中提供已安装版本和更新尝试信息

参考资料

• 版本说明
• 专用事件操作手册
• 事件放置操作手册
• 付费墙用户旅程操作手册
• 应用商店审核操作手册
• CLI 用例操作手册