千问办公企业旗舰版开发者文档:使用指南。
技能中心使用指南
认证方式见APP开发者文档 → 认证接入。
技能中心包含技能、专家套件和连接器。当前收录 21 项接口:8 项市场/内置目录查询、5 项安装与偏好管理、5 项连接器授权操作,以及 3 项内置连接器添加/卸载/配置操作。各操作是否可用仍取决于当前权限、状态及服务配置。
接口目录
| 资源 | 列表(GET) | 详情(GET) |
|---|---|---|
| 技能 | /api/openapi/app/v1/ai-assets/skills | /api/openapi/app/v1/ai-assets/skills/{origin}/{id} |
| 专家套件 | /api/openapi/app/v1/ai-assets/expert-kits | /api/openapi/app/v1/ai-assets/expert-kits/{origin}/{id} |
| 连接器 | /api/openapi/app/v1/ai-assets/connectors | /api/openapi/app/v1/ai-assets/connectors/{origin}/{id} |
| 操作 | 方法与路径 |
|---|---|
| 本人手动登记列表 | GET /api/openapi/app/v1/ai-assets/installations |
| 手动添加 | POST /api/openapi/app/v1/ai-assets/installations |
| 手动卸载 | DELETE /api/openapi/app/v1/ai-assets/installations/{resource_type}/{origin}/{id} |
| 读取启停状态 | GET /api/openapi/app/v1/ai-assets/preferences/{resource_type}/{origin}/{id} |
| 修改启停状态 | PATCH /api/openapi/app/v1/ai-assets/preferences/{resource_type}/{origin}/{id} |
调用流程
- 完成认证接入;普通成员按资源权限使用本模块,不要求管理员权限。
- 调用列表接口,可传 keyword、page、page_size。服务端按当前组织、用户、Web 策略和资源有效性过滤,再返回分页结果。
- 使用列表中的 origin 和 id 查询详情。origin 可为 org 或 public;id 是资源 ID,不是 market_item_id。详情会重新检查可见性,资源下架或策略撤销后可能返回 404。
- 技能和基础套件按 capabilities 决定可执行动作。将最近响应的 state_etag 原样作为 If-Match,并使用 8–128 字符的 Idempotency-Key。
- 428 表示缺少版本;412 表示状态已变化,重新查询并确认后再提交。响应丢失时保持原键和请求重试;同键异请求返回 409。
可见性与能力状态
管理员需发布 Web 兼容资源并配置当前成员可发现的策略。浏览器不能自行指定组织、用户或策略端;服务端固定按 qwenwork_web 检查。
目录展示全部可发现且适配 Web 的资源,不局限于自动下发。专家套件返回依赖数量及当前有权连接器的安全状态和操作入口,不展开无权详情;连接器可显示认证类型,但不返回凭据或可执行配置。
技能/套件的 auto_provided 表示策略自动来源,manual_installed 表示 Web 手动登记,user_enabled 表示用户偏好。后两项在目录中使用 true/false/unknown 字符串,不能把 unknown 当成 false。状态依赖不可用时目录仍可显示,但返回 state_unavailable,写接口返回失败,不虚构状态。
安装登记和用户选择保存在服务端独立 PostgreSQL 状态行,与桌面按 surface_code 独立;安装与启停已复用 biz_hub_install。客户端不直接读写服务端状态 JSON。登记不证明资源包已下载。Agent 在工作时检查当前权限并准备资源;preparation 是最近观察,prepared 不保证本轮已加载。
技能和基础套件默认启用,用户可关闭自动或手动资源。当前自动管理资源不能完整卸载,只能停用;重复添加保留选择,完整卸载后重装生成新实例。已失去权限的手动登记保留最小不可用记录供本人清理,不显示无权详情。
连接器默认关闭,需用户启用且完成必要 OAuth 后才可使用,授权成功不自动启用;断开授权同时停用,完整卸载后重装默认关闭。套件 required 连接器必须全部就绪,optional 依赖未就绪时仅省略相应能力;无法映射的内联依赖仍阻止执行。API Key 连接器暂不支持 Web。服务未开放能力或依赖不可用时保持 unknown/不可用。
连接器授权
共同前缀为 /api/openapi/app/v1/ai-assets。
| 操作 | 方法与相对路径 |
|---|---|
| 发起/重新授权 | POST /connectors/{origin}/{id}/connect-sessions |
| 确认当前尝试 | POST /connectors/{origin}/{id}/authorization-attempts/{attempt_id}/complete |
| 取消当前尝试 | DELETE /connectors/{origin}/{id}/authorization-attempts/{attempt_id} |
| 查询状态与恢复进度 | GET /connectors/{origin}/{id}/connection |
| 断开并停用 | DELETE /connectors/{origin}/{id}/connection |