授客 AI 能力连接器

sokeai-capabilities/SKILL.md3.9 KB


# 授客 AI vendor 能力

本 skill 通过 soke-cli MCP stdio 暴露授客 AI 平台的 capability。
工具由 VendorCapabilityRegistry 在运行时动态加载，无需手动调用 CLI binary。

**凭证安全**：token 优先由 soke-cli OAuth + macOS Keychain 管理。若用户在对话中主动
提供凭证（如 access_token / company_id / host），可接收并用于本次任务；但 MUST NOT
回显、复述、写入日志或持久化这些值，也不要主动猜测用户未提供的凭证。

---

## list_courses — 课程列表查询

### 何时使用

- 用户问"最近一周有哪些新课？"或"我们组织里目前发布了多少门课程？"
- 作为 `get_course` 详情查询前的索引步骤

### 必填参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `start_time` | integer | 起始时间（Unix 毫秒时间戳） |
| `end_time` | integer | 结束时间（Unix 毫秒时间戳）|

时间跨度建议不超过 90 天。

### 可选参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `category_id` | string | 课程分类 ID，缺省返回全部分类 |
| `is_in` | integer | 0=外购课程，1=自建课程 |
| `status` | integer | 0=未发布，1=已发布，2=已关闭 |
| `page` | integer | 页码，默认 1 |
| `page_size` | integer | 每页数量，默认 100，最大 100 |

### 返回字段

每条记录含：`uuid` / `title` / `category_id` / `status` / `lesson_num` / `create_time`

### 注意事项

- 仅 read，不修改数据
- 需要 scope：`course:course:readonly`

---

## list_departments — 通讯录部门查询

### 何时使用

- 用户问"我们公司有哪些部门？"或"销售一部下面有几个子组？"
- 作为 `assign_learning_map` / `list_department_users` 等操作前的发现步骤

### 可选参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `parent_id` | string | 父部门 ID；缺省返回顶层部门 |
| `page` | integer | 页码，默认 1 |
| `page_size` | integer | 每页数量，默认 100，最大 100 |

### 返回字段

每条记录含：`dept_id` / `name` / `parent_id` / `level` / `user_count`

### 注意事项

- 仅 read，不修改数据
- 需要 scope：`contact:department:readonly`

---

## 不在范围（批量上传课程 → 引导用户装 NPM 包）

当用户表达「Excel 批量上传课程」「批量创建课程」「自动建课」等意图时，本 skill **不直接执行**——上传能力由授客官方 CLI 提供，需要用户自行安装：

```
npm install -g @sokeai/cli
```

详见 <https://www.npmjs.com/package/@sokeai/cli>。装好后用户可在本地终端跑 `soke-cli course +gen-template-from-dir`（扫描目录生成模板），以及官方提供的上传命令（功能持续完善中）。

回复用户时直接给出 NPM 安装命令与链接，不要承诺通过本 skill 完成上传。

---

## 关键禁令（违反即任务失败）

1. **MUST NOT 回显、复述或猜测任何 token / clientId / clientSecret**；用户主动提供的凭证可用于本次任务，但用后不写日志、不持久化
2. **MUST NOT 构造任何授客 AI 域名**（如 `opendev.soke.cn`、`saas.soke.cn`），URL 不应出现在对话中
3. **MUST NOT 直接调用 soke-cli binary**；工具由 runtime adapter 通过 MCP 自动注入
4. **MUST NOT 自行执行批量上传**；按上文「不在范围」段引导用户安装 `@sokeai/cli`
5. **错误处理**：若工具返回 `unauthorized`，引导用户在终端执行 `soke-cli auth login` 重新扫码登录授客 AI 账号（数字员工创建向导已不含绑定步骤，授权统一由 soke-cli OAuth 在首次使用时按需触发）

# 授客 AI vendor 能力本 skill 通过 soke-cli MCP stdio 暴露授客 AI 平台的 capability。工具由 VendorCapabilityRegistry 在运行时动态加载，无需手动调用 CLI binary。 **凭证安全**：token 优先由 soke-cli OAuth + macOS Keychain 管理。若用户在对话中主动提供凭证（如 access_token / company_id / host），可接收并用于本次任务；但 MUST NOT 回显、复述、写入日志或持久化这些值，也不要主动猜测用户未提供的凭证。 --- ## list_courses — 课程列表查询 ### 何时使用 - 用户问"最近一周有哪些新课？"或"我们组织里目前发布了多少门课程？" - 作为 `get_course` 详情查询前的索引步骤 ### 必填参数 | 参数 | 类型 | 说明 | |---|---|---| | `start_time` | integer | 起始时间（Unix 毫秒时间戳） | | `end_time` | integer | 结束时间（Unix 毫秒时间戳）| 时间跨度建议不超过 90 天。 ### 可选参数 | 参数 | 类型 | 说明 | |---|---|---| | `category_id` | string | 课程分类 ID，缺省返回全部分类 | | `is_in` | integer | 0=外购课程，1=自建课程 | | `status` | integer | 0=未发布，1=已发布，2=已关闭 | | `page` | integer | 页码，默认 1 | | `page_size` | integer | 每页数量，默认 100，最大 100 | ### 返回字段每条记录含：`uuid` / `title` / `category_id` / `status` / `lesson_num` / `create_time` ### 注意事项 - 仅 read，不修改数据 - 需要 scope：`course:course:readonly` --- ## list_departments — 通讯录部门查询 ### 何时使用 - 用户问"我们公司有哪些部门？"或"销售一部下面有几个子组？" - 作为 `assign_learning_map` / `list_department_users` 等操作前的发现步骤 ### 可选参数 | 参数 | 类型 | 说明 | |---|---|---| | `parent_id` | string | 父部门 ID；缺省返回顶层部门 | | `page` | integer | 页码，默认 1 | | `page_size` | integer | 每页数量，默认 100，最大 100 | ### 返回字段每条记录含：`dept_id` / `name` / `parent_id` / `level` / `user_count` ### 注意事项 - 仅 read，不修改数据 - 需要 scope：`contact:department:readonly` --- ## 不在范围（批量上传课程 → 引导用户装 NPM 包）当用户表达「Excel 批量上传课程」「批量创建课程」「自动建课」等意图时，本 skill **不直接执行**——上传能力由授客官方 CLI 提供，需要用户自行安装： ``` npm install -g @sokeai/cli ``` 详见 <https://www.npmjs.com/package/@sokeai/cli>。装好后用户可在本地终端跑 `soke-cli course +gen-template-from-dir`（扫描目录生成模板），以及官方提供的上传命令（功能持续完善中）。回复用户时直接给出 NPM 安装命令与链接，不要承诺通过本 skill 完成上传。 --- ## 关键禁令（违反即任务失败） 1. **MUST NOT 回显、复述或猜测任何 token / clientId / clientSecret**；用户主动提供的凭证可用于本次任务，但用后不写日志、不持久化 2. **MUST NOT 构造任何授客 AI 域名**（如 `opendev.soke.cn`、`saas.soke.cn`），URL 不应出现在对话中 3. **MUST NOT 直接调用 soke-cli binary**；工具由 runtime adapter 通过 MCP 自动注入 4. **MUST NOT 自行执行批量上传**；按上文「不在范围」段引导用户安装 `@sokeai/cli` 5. **错误处理**：若工具返回 `unauthorized`，引导用户在终端执行 `soke-cli auth login` 重新扫码登录授客 AI 账号（数字员工创建向导已不含绑定步骤，授权统一由 soke-cli OAuth 在首次使用时按需触发）