AgentSkillsCN

feishu-contact

飞书组织架构与 ID 转换 Skill。搜索成员、获取部门信息、创建部门、ID 互转（OpenID/UserID/UnionID）。当需要查找飞书用户、管理组织架构或在不同 ID 体系间转换时使用此 Skill。

中文原作
SKILL.md
--- frontmatter
name: feishu-contact
description: 飞书组织架构与 ID 转换 Skill。搜索成员、获取部门信息、创建部门、ID 互转（OpenID/UserID/UnionID）。当需要查找飞书用户、管理组织架构或在不同 ID 体系间转换时使用此 Skill。
required_permissions:
  - contact:user.base:readonly
  - directory:department:read
  - directory:department:write
  - directory:employee.create:write
  - directory:employee.idconvert:read
  - directory:department.idconvert:read
  - directory:job_title.base:read
  - directory:place.base:read
  - admin:app.user_usable:readonly

飞书组织架构与 ID 转换

你是飞书通讯录管理专家，负责通过 Contact v3 API 实现成员搜索、部门管理和 ID 转换。

一、API 基础信息

项目值
Base URLhttps://open.feishu.cn/open-apis/contact/v3
认证方式Authorization: Bearer {tenant_access_token}
Content-Typeapplication/json

二、成员查询

1. 搜索成员（通过邮箱/手机号获取 OpenID）

code
GET /open-apis/contact/v3/users/batch_get_id

实测心法：支持邮箱、手机号等多种输入，是对接外部系统的核心桥梁。

2. 获取成员职务

code
GET /open-apis/contact/v3/job_titles/{job_title_id}

实测心法：职务信息需在管理后台预先维护。可基于职级进行自动化审批路由。

三、部门管理

3. 获取部门信息

code
GET /open-apis/contact/v3/departments/{department_id}

实测心法：department_id 有多种格式（OpenID / CustomID），注意区分。

4. 创建部门

code
POST /open-apis/contact/v3/departments
json
{ "name": "新部门", "parent_department_id": "0" }

实测心法：操作敏感，通常需最高管理权限。建议在预发环境多测试。

5. 入职成员

code
POST /open-apis/contact/v3/users
json
{ "name": "张三", "mobile": "13800138000", "department_ids": ["od_xxx"] }

实测心法：合规性操作，建议在预发环境多测试。

四、ID 转换（核心）

飞书有三种用户 ID 体系，对接外部系统时经常需要互转：

ID 类型说明使用场景
open_id应用内唯一同一应用内识别用户
user_id企业内唯一企业内部系统对接
union_id跨应用唯一同一开发者的多个应用间

6. 用户 ID 转换

code
POST /open-apis/contact/v3/users/batch_get_id

实测心法：对接外部系统（如微信、钉钉）时的核心桥梁。

7. 部门 ID 转换

code
POST /open-apis/contact/v3/departments/batch_get_id

实测心法：处理跨企业租户合并时的利器。

五、其他

8. 获取办公地点列表

code
GET /open-apis/contact/v3/places

实测心法：地点 ID 可用于人员地理分布分析，适配多地办公的项目组。

9. 管理外部成员访问

code
GET /open-apis/application/v1/applications/{app_id}/user_usable

实测心法：控制供应商/外包团队对项目的访问权限，合规性管控的核心。

六、最佳实践

  1. •ID 转换先行：对接外部系统前，先通过 batch_get_id 建立 ID 映射
  2. •权限敏感：创建部门、入职成员等操作需最高权限，谨慎使用
  3. •缓存 ID：频繁查询的用户 ID 建议本地缓存，减少 API 调用
  4. •预发测试：组织架构变更操作务必在预发环境验证