dcsunny
90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
---
|
||
name: htsy
|
||
description: 当用户需要通过海豚私域 htsy-cli 操作账号、用户、登录注册、席位、角色、微号、客户、标签、群、素材、话术库、关键词、SOP、群发、营销计划、客服或知识库接口时使用本 skill。本 skill 面向公开业务使用场景，说明 htsy-cli 从 Gitea release 下载、安装、登录状态保存、接口路径选择和 JSON 请求体字段编写方式。
|
||
---
|
||
|
||
# 海豚私域 Htsy
|
||
|
||
## 核心流程
|
||
|
||
1. 确认本机存在 `htsy-cli`：Linux/macOS 用 `command -v htsy-cli && htsy-cli version`，Windows PowerShell 用 `Get-Command htsy-cli.exe -ErrorAction SilentlyContinue` 和 `htsy-cli.exe version`。
|
||
2. 如果不存在，从 `https://git.ikuban.com/server/htsy-cli/releases` 下载当前系统和架构对应的 release 附件并安装。
|
||
3. 执行 `htsy-cli status` 查看登录状态；未登录时执行 `htsy-cli login --username USER --password PASS`。
|
||
4. 根据用户目标读取对应模块参考，从字段表中选择接口路径和 JSON 请求体。
|
||
5. 使用 `htsy-cli call 接口路径 -d JSON` 调用接口。空请求体统一使用 `-d '{}'`。
|
||
|
||
## 安装 CLI
|
||
|
||
Release 页面：`https://git.ikuban.com/server/htsy-cli/releases`。
|
||
|
||
附件按 `htsy-cli_<系统>_<架构>` 命名，Windows 带 `.exe`：
|
||
|
||
| 系统 | 架构 | 附件名 |
|
||
| --- | --- | --- |
|
||
| macOS Intel | x86_64 | `htsy-cli_darwin_amd64` |
|
||
| macOS Apple Silicon | arm64 | `htsy-cli_darwin_arm64` |
|
||
| Linux x86_64 | x86_64 | `htsy-cli_linux_amd64` |
|
||
| Linux arm64 | arm64 | `htsy-cli_linux_arm64` |
|
||
| Windows x86_64 | x86_64 | `htsy-cli_windows_amd64.exe` |
|
||
| Windows arm64 | arm64 | `htsy-cli_windows_arm64.exe` |
|
||
|
||
Linux/macOS 安装示例：
|
||
|
||
```bash
|
||
ASSET_URL="从 https://git.ikuban.com/server/htsy-cli/releases 复制对应 htsy-cli_* 附件下载链接"
|
||
mkdir -p "$HOME/.local/bin"
|
||
curl -fL "$ASSET_URL" -o "$HOME/.local/bin/htsy-cli"
|
||
chmod +x "$HOME/.local/bin/htsy-cli"
|
||
"$HOME/.local/bin/htsy-cli" version
|
||
```
|
||
|
||
Windows PowerShell 安装示例：
|
||
|
||
```powershell
|
||
$AssetUrl = "从 https://git.ikuban.com/server/htsy-cli/releases 复制 htsy-cli_windows_amd64.exe 下载链接"
|
||
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
|
||
Invoke-WebRequest -Uri $AssetUrl -OutFile "$HOME\bin\htsy-cli.exe"
|
||
$env:Path = "$HOME\bin;$env:Path"
|
||
htsy-cli.exe version
|
||
```
|
||
|
||
如果当前系统或架构没有匹配附件，不要猜测下载地址或改用其他架构，先让用户提供可用 release 附件。
|
||
|
||
## 登录与调用
|
||
|
||
`login` 会按用户名是否包含 `@` 自动选择登录方式：带 `@` 的用户名走子账号登录，不带 `@` 的用户名走主账号登录。登录成功后，CLI 会把登录信息保存到用户主目录下的 `.htsy/config.json`。
|
||
|
||
```bash
|
||
htsy-cli status
|
||
htsy-cli login --username USER --password PASS
|
||
htsy-cli call /api/account/user/info -d '{}'
|
||
htsy-cli call /api/bot/wx/list -d '{"page":1,"pageSize":20,"botType":1}'
|
||
htsy-cli call /api/bot/wx/list -d @request.json
|
||
```
|
||
|
||
只有用户明确要求隔离凭据时，才使用 `HTSY_CONFIG` 或 `--config` 指定独立配置文件。
|
||
|
||
## 模块参考
|
||
|
||
按用户目标只读取需要的文件：
|
||
|
||
- 通用字段、分页、`botType`、消息体：读 [api-common.md](references/api-common.md)。
|
||
- 账号、用户、注册、登录、席位、角色、订单：读 [api-account.md](references/api-account.md)。
|
||
- 微号列表、分组、登录二维码、发送/撤回消息、状态、二维码、迁移：读 [api-bot.md](references/api-bot.md)。
|
||
- 客户、联系人、备注、同步、单向客户、黑名单、标签：读 [api-friend.md](references/api-friend.md)。
|
||
- 群、群成员、群分组、群管理、群公告、欢迎语、群守卫、群查重、群转播、批量入群/邀请：读 [api-group.md](references/api-group.md)。
|
||
- 素材、话术库、话术分类/标签、上传 token：读 [api-material.md](references/api-material.md)。
|
||
- 关键词、SOP、群发、快速推送、朋友圈、订阅、社群氛围、监听、中控群、淘客：读 [api-automation.md](references/api-automation.md)。
|
||
- 客服会话、客服消息、AI 回复、知识库、飞书配置：读 [api-customer.md](references/api-customer.md)。
|
||
- 不确定模块时先读 [htsy-api.md](references/htsy-api.md) 索引。
|
||
|
||
## 使用原则
|
||
|
||
- 常规业务 API 操作必须优先使用 `htsy-cli`，不要手写 HTTP 客户端代替。
|
||
- 下载安装 CLI 可以使用系统下载工具；业务 API 调用不要用 `curl` 或自写脚本绕过 `htsy-cli`。
|
||
- 不要在回答里输出用户密码、token 或 `.htsy/config.json` 的完整内容。
|
||
- 不确定字段时，先读对应模块参考，不要臆造请求字段。
|
||
- `botType` 常用取值：`1` 个微，`2` 企微。
|
||
- 时间字段如未特别说明，按毫秒时间戳处理。
|
||
- 不面向用户直接调用的协议实例、Cron、客户端节点、回调上报、内部专用、第三方特供接口不要主动提供给用户。
|