Skip to main content

使用指南

千问办公企业旗舰版开发者文档:使用指南。

技能中心使用指南

认证方式见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}
resource_type 支持 skill、expert_kit、connector。

调用流程

  1. 完成认证接入;普通成员按资源权限使用本模块,不要求管理员权限。
  2. 调用列表接口,可传 keyword、page、page_size。服务端按当前组织、用户、Web 策略和资源有效性过滤,再返回分页结果。
  3. 使用列表中的 origin 和 id 查询详情。origin 可为 org 或 public;id 是资源 ID,不是 market_item_id。详情会重新检查可见性,资源下架或策略撤销后可能返回 404。
  4. 技能和基础套件按 capabilities 决定可执行动作。将最近响应的 state_etag 原样作为 If-Match,并使用 8–128 字符的 Idempotency-Key。
  5. 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
授权写入使用 auth_revision,安装/启停使用 state_etag;不可混用。仅发起接口返回限定会话 token,浏览器不得持久保存;不返回第三方凭据。查询是纯读取,不自动绑定或删除连接。 资源创建、编辑、发布和策略配置由管理端完成,不属于这些 APP 接口。

内置连接器管理

仅 dws、lark、wecom 支持 Web,列表和详情按当前 Web DISCOVER 权限过滤。新增 POST/DELETE /api/openapi/app/v1/ai-assets/builtin-connectors/{key}/installations;POST /api/openapi/app/v1/ai-assets/builtin-connectors/wecom/configuration 保存 Bot ID、Bot Secret 到 Nango。启停复用 preferences/connector/org/{id};钉钉、飞书 OAuth 与断开复用 connectors/org/{id} 下现有接口。id 使用固定内置 UUID,不传市场条目 ID。 管理功能与沙箱运行独立,当前 can_use 固定 false。钉钉、飞书需管理员预先在 Nango 配置组织 OAuth 应用,普通成员不能替换应用密钥。企微配置保存不代表第三方验证或沙箱已连接。