zkcrm（智客CRM）开放接口技能
本技能用于从智客CRM（dkdcrm）读取业务数据做查询、统计与分析。所有请求经 scripts/dk_api.py 完成 HMAC-SHA256 签名（协议对应 CRM 侧 application/common/library/ApiKeyAuth.php）。
使用流程
- 确认凭据已配置：凭据从
~/.workbuddy/dkcrm.json（或环境变量DK_CRM_URL/DK_ACCESS_KEY/DK_SECRET_KEY）读取。执行任何端点前无需检查——脚本缺凭据时会打印明确指引。 - 查端点清单：读
references/api.md，找到匹配用户意图的端点短名与参数。共 17 个端点（11 查询 + 6 写端点：followup.create/followup.delete/plan.create/plan.status/plan.delete/notice.mark_read）。 - 调用：
bash python "<本skill目录>/scripts/dk_api.py" <端点短名> [--data '<JSON请求体>' | --data-file <文件>] [--query '<查询串>']
---data传 JSON 请求体时为 POST，不传为 GET；--query传 URL 查询参数（如page=1&status=0）；--data-file从文件读 JSON（Windows PowerShell 下首选，绕开引号转义）
- 响应为 JSON：{"http_status":200,"response":{"code":1,"msg":"ok","data":{...}}}；code=1成功，code=0失败且msg为原因 - 呈现结果：用中文、贴业务的措辞回复用户（如「张三，跟进中，上次跟进 10-12」），不要把原始 JSON 直接丢给用户。按业务员统计优先用
stats.by_owner一次取数，无需拉全量列表本地算。
端点扩展规则
CRM 侧每新增一个 Openapi 端点：
- 在
scripts/dk_api.py的ENDPOINTS字典登记：短名 → 服务端路径 - 在
references/api.md补该端点的参数与响应字段说明 - 两处必须同步，缺失任一处视为端点不可用
安全规则
- Secret Key 严禁出现在 SKILL.md、api.md、对话输出、日志中
- 凭据只存
~/.workbuddy/dkcrm.json或环境变量；用户要求更换 Key 时指引其更新配置文件 - 写端点（followup.create / followup.delete / plan.create / plan.status / plan.delete / notice.mark_read）调用前必须：向用户复述将要写入/删除的完整内容（对象、内容、状态），获得明确确认后才能执行；绝不静默写入或删除。删除操作额外提醒「不可恢复」
- 查询端点可自由调用；
meta.list/employee.list用于把用户的业务语言（选项标签、成员姓名）翻译成接口参数 - 新增跟进时 content 必须有实质内容——用户只说「记一下跟进」时，先问清楚沟通内容再写入
故障速查
| 现象 | 处理 |
|---|---|
code=0,msg=请求已过期 |
本机时间偏差超 5 分钟，提示校时 |
签名校验失败 |
Secret Key 不对或 body 与签名不一致（--data 内容改动后重跑即可，脚本自动重签） |
Access Key 不存在/已停用/已过期 |
到 CRM 个人资料页检查 API Key 状态 |
缺少 xxx（但 --data 里明明传了） |
Windows PowerShell 5.1 传参剥双引号，服务端收到 {scope:xx} 无法解析。首选 --data-file body.json（从文件读，彻底绕开）；或内层引号前加 \；或 --% 停止解析符；或改 Git Bash/WSL。签名能通过而 JSON 解析失败=典型引号被剥 |
| 网络失败 | 检查 url 配置（应填站点根域名，不带 go.php） |
