htsy-skill/htsy/SKILL.md

name, description

name	description
htsy	当用户需要通过海豚私域 htsy-cli 操作账号、用户、登录注册、席位、角色、微号、客户、标签、群、素材、话术库、关键词、SOP、群发、营销计划、客服或知识库接口时使用本 skill。本 skill 面向公开业务使用场景，说明 htsy-cli 登录状态检查、接口路径选择、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. 如果不存在，读取 cli-install.md 后按当前系统和架构安装。
3. 执行 htsy-cli status 查看登录状态；未登录时执行 htsy-cli login --username USER --password PASS。
4. 根据用户目标读取对应模块参考，从字段表中选择接口路径和 JSON 请求体。
5. 使用 htsy-cli call 接口路径 -d JSON 调用接口。空请求体统一使用 -d '{}'。

登录与调用

login 会按用户名是否包含 @ 自动选择登录方式：带 @ 的用户名走子账号登录，不带 @ 的用户名走主账号登录。登录成功后，CLI 会把登录信息保存到用户主目录下的 .htsy/config.json。

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 '{"page":1,"pageSize":20,"botType":2}'   # 企微
htsy-cli call /api/bot/wx/list -d @request.json

只有用户明确要求隔离凭据时，才使用 HTSY_CONFIG 或 --config 指定独立配置文件。

模块参考

按用户目标只读取需要的文件：

• 通用字段、分页、botType、消息体：读 api-common.md。
• 账号、用户、注册、登录、席位、角色、订单：读 api-account.md。
• 微号列表、分组、登录二维码、发送/撤回消息、状态、二维码、迁移：读 api-bot.md。
• 客户、联系人、备注、同步、单向客户、黑名单、标签：读 api-friend.md。
• 群、群成员、群分组、群管理、群公告、欢迎语、群守卫、群查重、群转播、批量入群/邀请：读 api-group.md。
• 素材、话术库、话术分类/标签、上传 token：读 api-material.md。
• 关键词、SOP、群发、快速推送、朋友圈、订阅、社群氛围、监听、中控群、淘客：读 api-automation.md。
• 客服会话、客服消息、AI 回复、知识库、飞书配置：读 api-customer.md。
• 不确定模块时先读 htsy-api.md 索引。

回复风格

• 面向普通业务用户回复，先给结论，再给必要明细；语气自然一点，像在帮同事查数据，不要像在解释代码执行过程。
• 默认不要在最终回复里暴露接口路径、HTTP 方法、CLI 命令、JSON 字段名、变量名或内部字段名。只有用户明确要求“接口怎么调”“请求参数是什么”“排查为什么失败”时，才补充这些技术细节。
• 把接口字段翻译成用户能直接理解的说法。例如把 total 说成“总数”，把 corpId 说成“企业主体”，把 botType=2 说成“企微”。
• 汇总查询结果时，用“我查到”“目前有”“分别是”这类自然表达；列表只保留用户关心的名称、数量、状态、时间等业务信息。
• 不要说“我先调用了某接口”“返回里的某字段是...”这类实现细节。可以说“我查到当前有...”或“目前这个账号下能看到...”。
• 如果结果不完整或权限可能影响数据，用业务语言说明限制，例如“这个结果只包含当前登录账号有权限查看的数据”。
• 结尾只在自然需要时给下一步建议，避免固定套话。建议应贴合用户当前目标，例如“需要的话，我可以继续按群类型、分组或在线状态拆一下。”

示例：

不要这样说：
我先调用了 POST /api/wx/group/list，结果里的 total 是 634。

应该这样说：
我查到当前共有 634 个群。

使用原则

• 常规业务 API 操作必须优先使用 htsy-cli，不要手写 HTTP 客户端代替。
• 下载安装 CLI 可以使用系统下载工具；业务 API 调用不要用 curl 或自写脚本绕过 htsy-cli。
• 不要在回答里输出用户密码、token 或 .htsy/config.json 的完整内容。
• 不确定字段时，先读对应模块参考，不要臆造请求字段。
• botType 常用取值：1 个微，2 企微。
• 企微接口需要 corpId 时，先调用 POST /api/bot/wx/corp/list 获取主体列表，返回项的 id 就是请求里的 corpId。
• 时间字段如未特别说明，按毫秒时间戳处理。
• 不面向用户直接调用的协议实例、Cron、客户端节点、回调上报、内部专用、第三方特供接口不要主动提供给用户。