概述
sensors-cli 是神策数据（Sensors Data）官方提供的命令行工具，作为 AI 编程助手（Claude Code、Cursor、Codex 等）与神策平台之间的桥梁。AI 助手通过 sensors-cli 直接查询数据、管理项目配置、执行分析模型，无需人工登录浏览器操作。
安装 sensors-cli 并将神策数据 skills 接入 AI 编程工具后，你只需用自然语言描述需求，AI 助手即可自动完成元数据解析、数据查询、看板查看、分群与标签查询、归因分析乃至埋点代码实施等操作。工具同时提供 macOS 和 Windows 安装包，安装时通过交互式向导引导填写连接参数，无需手动编辑配置文件。解压安装包、运行一条命令，脚本会自动处理所有环境依赖。
核心能力
AI 驱动的数据查询 — AI 助手通过 sensors-cli 直接查询事件数据、漏斗转化、用户分群、看板书签等，支持结构化输出，结果可直接用于分析与决策。
AI 埋点代码实施 — AI 助手可解析埋点采集方案、检测项目技术栈、自动完成 SDK 安装与代码插桩，并生成交付报告，提升埋点工程效率。
AI 能力集成 — 支持为 Codex、Cursor、Claude 等 AI 编程工具安装神策数据 skills，让 AI 助手在编码过程中直接调用神策平台能力。
环境自动管理 — 安装脚本自动检测并配置 Python、uv 等运行时依赖，无需手动处理复杂的环境搭建。
安装与使用指南
安装前准备
在开始安装之前，请确认以下条件已满足：
1.电脑可以正常联网
安装脚本需要从网络获取部分依赖组件，请确保网络连接正常。
2.不需要手动安装 uv
无需提前安装 uv 工具，安装脚本会自动检查并安装。你只需要解压压缩包、运行脚本即可。
macOS 安装步骤
1.解压安装包
解压整个 sensors-cli-<version>-bundle.zip 压缩包到本地目录。
2.打开终端并进入目录
打开「终端」应用，进入解压后的文件夹。例如：
⚠️注意路径：请将 Desktop 替换为你实际的解压目录路径。
3.执行安装脚本
在终端中运行安装命令：
脚本会自动完成以下操作
✓检查 Python 环境
检测系统里有没有 Python，若缺失则进行提示。
✓自动安装
如果没有 uv，就自动安装 uv。✓安装 sensors 命令
从 dist 目录里的 wheel 文件安装 sensors。
✓启动首次配置
安装完成后自动打开 sensors setup。
💡 macOS 用户运行 install.sh，Windows 用户运行 install.cmd，安装流程完全一致，脚本会自动处理所有环境依赖。
首次配置
无论使用 macOS 还是 Windows，安装完成后系统都会自动进入 sensors setup 交互式配置界面。请按照界面提示依次填写以下信息：
| 配置项 | 说明 | 示例 |
|---|---|---|
| Base URL | 填写浏览器端神策平台的访问根地址，需完整包含 http:// 或 https:// 协议前缀。不可追加 /analytics 等细分页面路径。 |
https://yourcompany.sensorsdata.cn |
| API Key | 在右上角个人中心的「API Key 管理」列表中，选取目标密钥，复制对应的 API Key 值（含前置 # 号）填入配置项。 |
#a1b2c3d4e5f6... |
| Project | 填写后台「平台管理 → 授权信息 → 项目授权」中的项目英文名称。 | production |
⚠️Base URL 格式要求必须为根地址，不可包含路径后缀。正确示例：https://yourcompany.sensorsdata.cn；错误示例：https://yourcompany.sensorsdata.cn/analytics。
💡 API Key 在哪里找？登录神策平台 → 右上角个人中心 → 「API Key 管理」→ 选取目标密钥 → 复制 API Key 值（注意包含前置 # 号）。
安装 AI Skills
基础信息配置完成后，你可以选择安装神策数据 AI 能力，下载对应 AI 编程工具的 skills 到本地环境中使用。
1.回到首页
配置保存后，选择回到首页。
2.选择「安装 AI skills」
通过键盘上下方向键切换至「安装 AI skills」步骤，按回车执行安装操作。
3.选择目标工具
根据你当前使用的 AI 编程工具，选择对应平台并下载安装神策数据的 skills。目前支持Codex、Cursor 、Claude。
✓AI Skills 安装成功后，即可在 Codex、Cursor 或 Claude 中通过已安装 skills 调用神策数据的相关 AI 能力。
健康检查
执行健康检查是验证安装是否成功的最后一步。系统会自动校验以下环境项：✓配置完整性校验
检查 Base URL、API Key、Project 等配置项是否正确填写且格式合法。✓网络联通性校验
验证本地与神策平台之间的网络连接是否畅通。✓CLI 工具版本校验
检查 sensors-cli 版本是否为最新可用版本。若所有检查结果均为通过，则说明 sensors-cli 配置完成，可以正式投入使用了！
💡 安装完成后，后续可以直接在终端使用 sensors 命令与神策平台交互。
安装失败排查
如果安装失败，请优先检查以下几点：
1.网络是否可用
确保电脑可以正常联网，安装脚本需要从网络获取部分依赖组件。
2.是否在正确的目录里运行安装脚本
确认当前所在目录就是解压后的文件夹，其中应包含 install.sh（macOS）或 install.cmd（Windows）以及 dist 目录。
3.dist 目录是否完整
检查压缩包里的 dist 目录是否完整，没有被手动删除或损坏。
AI Agent 使用指引
安装配置并通过健康检查后，你可以在支持 skills 的 AI 编程工具中通过自然语言直接调用神策数据能力——AI 助手会识别你的意图，自动调用 sensors-cli 完成查询与分析。
工作流程
1.在 AI 编程工具中加载神策数据 skills
在 Claude Code、Cursor 或 Codex 中确认已加载 sensors-* 系列 skills。
2.用自然语言描述需求
直接向 AI 助手提出你的问题或任务，例如：
「最近 7 天 App 启动的 DAU 趋势，按渠道分组」
「帮我查一下系统里有哪些用户分群」
「对 demo 项目进行埋点代码实施」
AI 助手会自动识别意图并调用对应 sensors-cli 命令来执行。
3.查看返回结果
AI 助手会解析 sensors-cli 的输出并以自然语言向你呈现结论与分析，同时保留结构化数据供后续复用。
可以使用的 SKILLS
AI 助手通过 sensors-cli 可以完成以下操作：
| 技能 ID | 名称 | 分类 | 说明 |
|---|---|---|---|
sensors-context |
会话与项目上下文 | 前置依赖 | 初始化会话、确认目标项目，所有业务能力的前置步骤 |
sensors-metadata |
元数据解析 | 元数据 | 将口语表述翻译为精确的事件名、属性名和表字段，支持埋点验收 |
sensors-insight |
标准分析查询 | 行为分析 | 趋势、漏斗、留存、间隔、分布、LTV、Session、归因等八类分析模型 |
sensors-dashboard |
看板、概览和书签查询 | 看板 | 查找概览、定位书签、执行已保存报表 |
sensors-cohort |
分群查询 | 分群 | 查找分群对象，查看定义、规则摘要与结果可用性 |
sensors-tag |
标签查询 | 标签 | 查找标签对象，查看定义、数据类型与规则可用性 |
sensors-sql-query |
SQL 查询 | SQL | 当标准分析模型无法覆盖时，生成或执行只读 SQL 查询数仓 |
sensors-tracking |
埋点实施工作流 | 工程实施 | 解析埋点方案、检测技术栈、安装 SDK、代码插桩并生成交付报告 |
使用示例
以下为典型场景的运行效果。
场景一：查询核心指标
场景二：查看留存数据
安全风险声明
AI 代理调用存在固有风险，包括但不限于模型幻觉（生成不存在的命令或参数）、不可预测的执行顺序以及提示注入攻击。授权后，AI 代理将以你的用户身份在授权范围内执行操作，可能导致敏感数据泄露或非预期的数据操作。
使用 sensors-cli 的 AI 能力前，请确认以下安全实践：
1.仅在你信任的私人终端环境中使用，避免在共享或公开场合调用
2.对 AI 代理即将执行的指令保持关注，确认其合理性后再放行
3.定期审查 API Key 权限，遵循最小权限原则——只授予当前任务所需的最小范围
4.强烈建议不要主动修改 sensors-cli 的默认安全设置
5.如发现异常操作，立即撤销相关 API Key 并联系神策技术支持团队
通过遵循以上实践，你可以最大化地降低 AI 代理调用中的安全风险，同时充分发挥 AI 辅助数据分析的效率优势。
macOS 卸载步骤
1.打开终端并进入目录
打开「终端」，进入之前解压后的文件夹（即包含 uninstall.sh 的目录）。
2.执行卸载脚本
在终端中运行卸载命令：
卸载脚本执行内容
1.尝试删除 uv 工具层的 sensors-cli 安装。
2.清理本机的 managed runtime。
如果系统里没有 uv，脚本会提示你先恢复 uv，再手动执行卸载命令。卸载不会删除你的个人配置文件，例如 ~/.sensors/config.toml。如需彻底清理，请手动删除该文件。
💡 macOS 用户运行 uninstall.sh，Windows 用户运行 uninstall.cmd，卸载流程完全一致。