@yunkeai/yunke-cli 2.0.6 → 3.0.0-alpha.0

package/dist/skills/yunke-wecom/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: yunke-wecom
+description: "用 yunke 按业务场景查企业微信（企微）数据：企微客户资产盘点、会话与沟通质量、客户群运营、敏感词质检、朋友圈运营、员工回复超时、企微通话与整体看板。用户提到企业微信、企微、企微客户、企微好友、客户群、企微群、聊天记录、会话、敏感词、企微朋友圈、超时回复、企微通话、员工企微号、企微数据盘点时使用。前置：需先完成 CRM 登录（浏览器页面登录）。"
+metadata:
+  requires:
+    bins: ["yunke"]
+---
+
+# 企业微信（yunke-wecom）
+
+按**业务问题**组织企微取数，不按接口组织。参数名、类型、枚举和返回结构一律运行时查，本文只写
+「回答什么问题 → 按什么顺序调 → 按什么口径汇总」。
+
+> **版本门槛：** 依赖 yunke-cli **≥ 3.0.0**（`schema.detail` 的参数/返回值直接来自上游契约）。
+
+> **前置依赖**
+> - 登录、JSON 信封、命令发现规则见 `../yunke-cli-skills/SKILL.md` 与 `../yunke-crm/SKILL.md`。
+>   未登录先 `yunke crm.auth.status`，需要时再 `yunke crm.auth.login-web`（浏览器页面登录；宿主无本地回调时用 `crm.auth.login-device-code`）。
+> - 首次调用某命令前先跑 `yunke schema.detail --command <命令名>`，一次拿全参数。
+> - 本文只覆盖**企业微信**（`crm.wecom.*`）。个人微信是另一套数据（`crm.wechat.*`），不要混用。
+
+## 先认 ID：企微最容易错的一层
+
+同一个概念在不同命令里叫不同名字；喂错不会报错，只会返回空。
+
+| 实体 | 唯一标识 | 从哪拿 | 在别的命令里叫什么 |
+|---|---|---|---|
+| 员工企微账号 | `wechatId` | `wecom_list_contacts` 的 `wechatId` | 会话类命令的 `user_id`、时间轴的 `wechat_id` |
+| 云客员工 | `userId` | `wecom_list_contacts` 的 `userId`、`crm.org.*` | 大多数命令的 `user_id` |
+| 企微主体 | `corpId` | `wecom_list_contacts.corpId`、`wecom_list_chatrooms.corpId`、`wecom_search_messages` 的 `corpNum` | `corp_id`（拉会话消息时必填） |
+| 客户 | `customerId` | `wecom_search_customers.customerId` | `to_id`（type=1）、`customer_ids`、`qw_customer_id` |
+| 群 | `roomId` | `wecom_list_chatrooms.roomId` | `to_id`（type=2） |
+| 会话 | `sessionId` | `wecom_timeline.sessionId` | — |
+
+**最容易踩的：`user_id` 在会话类命令里是员工企微号，在客户/统计类命令里是云客员工 ID。**
+拿不准时先 `wecom_list_contacts`，它同时返回 `userId` 和 `wechatId`，按字段名取。
+
+## 场景配方
+
+### 1. 客户资产盘点
+
+回答：公司企微沉淀了多少客户、谁加的、有没有重复跟进、有没有解绑流失。
+
+```bash
+yunke crm.wecom.wecom_list_contacts
+yunke crm.wecom.wecom_search_customers
+yunke crm.wecom.wecom_get_customer
+yunke crm.wecom.wecom_repeat_friends
+yunke crm.wecom.wecom_new_friend_stats
+yunke crm.wecom.wecom_customer_relations
+```
+
+- 先分页取全客户列表；**行数不是客户数**——一行 = 一个「员工-客户」关系，同一客户被多人添加会出现多行，
+  按 `customerId` 去重后再统计。
+- 重点客户查详情和被哪些员工添加，用 `wecom_get_customer`；关注员工离职对客户的影响时看它的 `followers`。
+- 重复跟进看 `wecom_repeat_friends`；新增趋势看 `wecom_new_friend_stats`；解绑/关联状态看 `wecom_customer_relations`。
+- 口径：客户数按 `customerId` 去重；新增按添加时间；解绑数按关联状态过滤。
+
+### 2. 会话与沟通质量
+
+回答：某员工最近和谁聊过、聊了什么、沟通量多少、有没有长语音和通话。
+
+```bash
+yunke crm.wecom.wecom_timeline
+yunke crm.wecom.wecom_get_chat_records
+yunke crm.wecom.wecom_search_messages
+yunke crm.wecom.wecom_msg_stats
+yunke crm.wecom.wecom_get_calls
+```
+
+- 先用时间轴定位会话（按员工或按客户），再用消息明细还原上下文。
+- 只知道关键词、不知道跟谁聊时，用全文检索；已知会话就直接拉明细，别绕检索。
+- 沟通量、长语音做汇总用 `wecom_msg_stats`，不要拿消息明细自己数。
+- 通话量、接通情况用 `wecom_get_calls`，先分页取全；录音文件与转写不在这个命令里。
+- 口径：会话数按 `sessionId` 去重；消息数用时间轴的收发计数；长语音看统计里的时长与次数。
+- **时间轴没有分页**，必须指定员工或客户，否则会一次拉全企业；时间按小时截断。
+- 消息明细单页固定 20 条，靠首末游标翻页；自动插入的时间分隔行不是真实消息。
+
+### 3. 客户群运营
+
+回答：有多少客户群、哪些群在响应、哪些群快死了、群成员是谁。
+
+```bash
+yunke crm.wecom.wecom_list_chatrooms
+yunke crm.wecom.wecom_chatroom_stats
+yunke crm.wecom.wecom_group_anomalies
+yunke crm.wecom.wecom_get_chatroom_members
+```
+
+- 群档案分页取全 → 响应率/沉默群看统计 → 异动看异动统计 → 指定群拉成员。
+- 口径：群数按 `roomId` 去重；沉默群阈值（例如 7 天无消息）先跟用户确认，并在结论里写明用的阈值。
+- **统计命令不传统计粒度会返回全 0**，这不是没数据，重试无用；只有明细视图才需要起止时间。
+- 群档案默认不排序，翻页顺序不保证稳定；成员是一次全量返回，不分页。
+
+### 4. 敏感词质检
+
+回答：哪些员工/客户触发了敏感词、原文是什么、规则怎么配的。
+
+```bash
+yunke crm.wecom.wecom_get_sensitive_rules
+yunke crm.wecom.wecom_sensitive_stats
+yunke crm.wecom.wecom_get_chat_records
+```
+
+- 先看规则与词库，再取命中记录，最后按需还原会话上下文。
+- 口径：命中数按记录条数；按员工/部门/群分组时先分页取全。
+- 时间窗最长 90 天，且必须给开始时间；不传会走全历史索引并报错。
+- 首次查询某节点会自动补建一条缺省规则记录，是幂等初始化，不是写入了业务数据。
+
+### 5. 朋友圈运营
+
+回答：谁在发圈、发得多不多、内容是什么、互动如何。
+
+```bash
+yunke crm.wecom.wecom_get_moments
+```
+
+- 先出员工汇总定位异常，再用该员工的企微账号查内容明细。
+- 口径：发圈数、点赞数、评论数按员工汇总；明细按发布时间。
+- 统计与明细的时间跨度都不能超过 3 个自然月，超出直接报错、不会自动截断。
+- 明细只查一个账号，需要该账号的 `wechat_id` 与 `corp_id`。
+
+### 6. 员工回复超时
+
+回答：谁没在时限内回客户、超时多久、管理员提醒了没有。
+
+```bash
+yunke crm.wecom.wecom_timeout_records
+```
+
+- 先看今日指标与昨日对比，再下钻超时明细，需要上下文再接会话消息。
+- 口径：超时率的分母（按员工还是按客户）要先跟用户确认；排行前分页取全。
+- 返回里出现翻页提示就说明还没取完，不要按一页数据下结论。
+
+### 7. 整体怎么样 → 看板
+
+回答：某部门/某段时间的企微整体情况。
+
+```bash
+yunke crm.wecom.wecom_dashboard
+```
+
+- 看板只回答「整体怎么样」；一旦知道具体员工、客户或群，直接走上面的明细配方，不要绕看板。
+- 趋势类视图会把缺失日期补零后返回完整序列，空值不是缺数据。
+- 群聊趋势的响应率、免打扰类指标当前不产数（恒为 null），不要当成 0 或异常。
+- 只有登录日志视图分页，其余一次返回完整结果；做统计前把分页取全。
+
+## 通用护栏
+
+- **先取全再汇总**：分页接口出现翻页提示就继续翻，严禁只看第一页下结论。
+- **深度翻页有上限**：客户、消息、群列表都是 ES 查询，页深超过约 30 万条会被后端直接拒绝，
+  改用更窄的时间、部门或员工条件。
+- **空结果不是失败**：`totalCount=0`、空数组、空对象通常是查询成功但无匹配；
+  先检查 ID 语义和时间窗，再决定是否换参数。
+- **汇总与明细分工**：统计/看板只出数字，下钻必须换明细命令，不要拿汇总结果编明细。
+- **参数不猜**：未知参数会被直接拒绝，`details.available` 就是可用参数清单；一次查全比逐个试错快。
+
+## 边界
+
+- 没有数据支撑的结论不写，标注「数据未返回」；不要把缺失当 0。
+- 业务口径（沉默群阈值、超时率分母、活跃定义）由用户确认后在结论里写明，不替业务方默认。
+- 客户手机号、姓名可能带 `*`，是公司脱敏配置，不是数据错误。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunkeai/yunke-cli",
-  "version": "2.0.6",
+  "version": "3.0.0-alpha.0",
   "description": "AI-native pluggable CLI framework",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist/bundle.js",
+    "dist/skills",
     "scripts/postinstall.cjs"
   ],
   "publishConfig": {
@@ -19,18 +20,19 @@
   },
   "scripts": {
     "build": "tsc",
-    "build:npm": "bun scripts/build-npm.ts",
-    "build:bin": "bun scripts/build-bin.ts",
+    "build:npm": "bun scripts/build-npm.ts --env prod",
+    "build:bin": "bun scripts/build-bin.ts --env prod",
     "build:bin:min": "bun build ./src/index.ts --compile --minify --outfile yunke",
-    "build:bin:darwin-arm64": "bun scripts/build-bin.ts --target=darwin-arm64",
-    "build:bin:darwin-x64": "bun scripts/build-bin.ts --target=darwin-x64",
-    "build:bin:linux": "bun scripts/build-bin.ts --target=linux-x64",
-    "build:bin:windows": "bun scripts/build-bin.ts --target=windows-x64",
-    "build:release": "mkdir -p dist && bun scripts/build-bin.ts",
-    "build:release:upx": "mkdir -p dist && UPX_COMPRESS=1 bun scripts/build-bin.ts",
-    "prepublishOnly": "bun scripts/build-npm.ts",
+    "build:bin:darwin-arm64": "bun scripts/build-bin.ts --env prod --target=darwin-arm64",
+    "build:bin:darwin-x64": "bun scripts/build-bin.ts --env prod --target=darwin-x64",
+    "build:bin:linux": "bun scripts/build-bin.ts --env prod --target=linux-x64",
+    "build:bin:windows": "bun scripts/build-bin.ts --env prod --target=windows-x64",
+    "build:release": "mkdir -p dist && bun scripts/build-bin.ts --env prod",
+    "build:release:upx": "mkdir -p dist && UPX_COMPRESS=1 bun scripts/build-bin.ts --env prod",
+    "prepublishOnly": "bun scripts/build-npm.ts --env prod",
     "postinstall": "node scripts/postinstall.cjs",
     "dev": "bun run src/index.ts",
+    "check:skills": "bun scripts/check-skill-docs.ts --strict",
     "test": "bun test --isolate"
   },
   "dependencies": {
@@ -38,11 +40,12 @@
     "fflate": "^0.8.3"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.1.0",
     "citty": "^0.1.6",
-    "zod": "^3.23.8",
-    "zod-to-json-schema": "^3.23.3",
+    "javascript-obfuscator": "^5.9.0",
     "typescript": "^5.5.3",
-    "@types/node": "^22.0.0",
-    "bun-types": "^1.1.0"
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.3"
   }
 }