安装前准备
获取安装包后，在开始安装之前，请确认以下条件已满足：
1.电脑可以正常联网
安装脚本需要从网络获取部分依赖组件，请确保网络连接正常。
2.不需要手动安装 uv
无需提前安装 uv 工具，安装脚本会自动检查并安装。你只需要解压压缩包、运行脚本即可。
macOS 安装步骤
1.解压安装包
解压整个 sensors-cli-<version>-bundle.zip 压缩包到本地目录。
2.打开终端并进入目录
打开「终端」应用，进入解压后的文件夹。例如： cd ~/Desktop/sensors-cli-1.1.1-bundle
⚠️注意路径：请将 Desktop 替换为你实际的解压目录路径。
3.执行安装脚本
在终端中运行安装命令：bash install.sh
脚本会自动完成以下操作
✓检查 Python 环境
检测系统里有没有 Python，若缺失则进行提示。
✓自动安装 uv
如果没有 uv，就自动安装 uv。
✓安装 sensors 命令
从 dist 目录里的 wheel 文件安装 sensors。
✓启动首次配置
安装完成后自动打开 sensors setup。
安装完成后，按照界面提示填写 Base URL、API Key 和 Project，完成首次配置。
💡 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 |
|
Write operations |
若需通过 CLI 执行创建或编辑类写操作，须先开启写操作开关；仅进行查询、统计等只读操作时无需开启。 |
开启/关闭 |
⚠️Base URL 格式要求必须为根地址，不可包含路径后缀。正确示例：https://yourcompany.sensorsdata.cn；错误示例：https://yourcompany.sensorsdata.cn/analytics。
安装 AI Skills
基础信息配置完成后，你可以选择安装神策数据 AI 能力，下载对应 AI 编程工具的 skills 到本地环境中使用。
1.回到首页
配置保存后，选择回到首页。
2.选择「安装 AI skills」
通过键盘上下方向键切换至「安装 AI skills」步骤，按回车执行安装操作。
3.选择目标工具
Sensors-CLI目前支持Codex、Cursor 、Claude、WorkBuddy。根据当前使用的工具选择 Skills 的目标平台与安装范围（当前目录/ 全局，其中 WorkBuddy 仅支持 全局；推荐使用全局配置，可在所有工作区中调用相关Skills），将神策打包的 Skills 安装到对应 AI 助手的平台目录。
✓AI Skills 安装成功后，即可在 Codex、Cursor 、Claude 、WorkBuddy中通过已安装 skills 调用神策数据的相关 AI 能力。
健康检查
健康检查会逐项核对配置、网络与版本等，并以中文体检报告的形式输出结果。具体检查项如下：
| 检查类别 | 检查项 | 含义 |
|---|---|---|
| 配置完整性 | 配置文件已找到（~/.sensors/config.toml） |
配置文件存在且可读 |
| 配置完整性 | 当前正在使用的配置上下文正常 | 上下文结构合法 |
| 配置完整性 | 默认项目已设置 | 已选定具体神策项目 |
| 配置完整性 | 关联环境配置正常 | 上下文指向的环境有效 |
| 配置完整性 | API Key 已填写 | 凭证非空 |
| 网络与权限连通性 | 平台地址可以连通 | Base URL 可访问 |
| 网络与权限连通性 | API Key 可以访问当前项目 | 凭证在指定项目上有权限 |
| 版本 | 当前 CLI 版本（sensors-cli x.x.x） |
CLI自身可用 |
每项结果明确标注「通过 / 失败 / 提醒 / 跳过」；失败项附带可直接执行的修复建议；末尾给出整体结论，告知是否可以开始使用 Sensors-CLI。若所有检查结果均为通过，则说明 sensors-cli 配置完成，可以正式投入使用了！
使用示例
workbuddy
以WorkBuddy为例，安装完成后即可在技能目录中看到sensors-tag等相关skill，如无法展示请重启workbudyd或查看安装aiskill步骤中所选平台是否为workbuddy。
实际使用中无需选中skill名称，workbuddy会自动实现意图识别与技能路由。仅需输入自然语言，例如：user_tag_cs2344这个标签规则和命中的人数是多少？AI助手即可执行对应的任务并返回结果。
Cursor
同WorkBuddy，输入自然语言，例如：user_tag_cs2344这个标签规则和命中的人数是多少？AI助手即可执行对应的任务并返回结果。
安装失败排查
如果安装失败，请优先检查以下几点：
1.网络是否可用
确保电脑可以正常联网，安装脚本需要从网络获取部分依赖组件。
2.是否在正确的目录里运行安装脚本
确认当前所在目录就是解压后的文件夹，其中应包含 install.sh（macOS）或 install.cmd（Windows）以及 dist 目录。
3.dist 目录是否完整
检查压缩包里的 dist 目录是否完整，没有被手动删除或损坏。
macOS 卸载步骤
1.打开终端并进入目录
打开「终端」，进入之前解压后的文件夹（即包含 uninstall.sh 的目录）。
2.执行卸载脚本
在终端中运行卸载命令： bash uninstall.sh
卸载脚本执行内容
- 尝试删除 uv 工具层的 sensors-cli 安装。
- 清理本机的 managed runtime。
如果系统里没有 uv，脚本会提示你先恢复 uv，再手动执行卸载命令。卸载不会删除你的个人配置文件，例如 ~/.sensors/config.toml。如需彻底清理，请手动删除该文件。
💡 macOS 用户运行 uninstall.sh，Windows 用户运行 uninstall.cmd，卸载流程完全一致。