Skill 清单

钉钉组织架构识别场景的全部能力定义，按清海 AI 实际工作方式分层组织。会话场景概览见钉钉组织架构识别，角色维度的会话旅程见角色场景。

架构总览

钉钉组织架构识别的能力分为四层：

分层判断标准

层级	判断标准	当前状态
A — Skill	AI 需要场景指导、权限规则、工具组合策略	⬜ 无 SKILL.md
B — Tool	AI 需要调用，tool schema 可自描述	✅ 3 个复用 + 4 个待封装
C — 系统能力	不需要 AI 感知，自动运行	✅ PersonIndex 复用，同步层待实现
D — 主动推送	非对话触发，由事件或定时驱动	⬜ 全部待实现（钉钉特有事件订阅）

Skill / Tool 汇总

名称	描述	状态	来源
`search_contacts`	按姓名或部门查找员工信息	✅ 复用	飞书版直接复用
`save_contact_alias`	AI 在对话中学习并保存人员别名	✅ 复用	飞书版直接复用
`link_platform_identity`	将外部平台身份绑定到公司人员	✅ 复用	飞书版直接复用
`query_org_structure`	返回公司整体组织架构树与部门人数	⬜ 待封装	PersonIndex 已有方法
`query_department_members`	查询指定部门的全部成员列表	⬜ 待封装	PersonIndex 已有方法
`query_person_relations`	查询某人的上下级与同组关系	⬜ 待封装	PersonIndex 已有方法
`query_staff_changes`	查询最近人员变动（入职/离职/调岗）	⬜ 待实现	需新建，依赖事件日志

A 层 — 当前无独立 Skill

现状

当前没有 skills/org-query-dingtalk/SKILL.md，AI 靠以下两条路径回答组织架构问题：

system prompt 身份注入：avatar_core.build_avatar_prompt() 在 Block 1 注入 "张三是销售一组的销售经理"
search_contacts 工具：AI 主动调用查询人员信息

目标设计

后续计划创建 skills/org-query-dingtalk/SKILL.md，提供：

触发词匹配：组织|部门|同事|上级|下属|团队|架构|人员|成员|谁是|有谁|几个人|负责人
角色权限规则（老板 / 经理 / 员工各看什么）
推荐工具组合和调用顺序
回复格式要求

B 层 — Tool 清单

已实现（直接复用飞书版，3 个）

1. search_contacts — 通讯录搜索

按姓名或部门查找员工信息。底层调用 PersonIndex，PersonIndex 数据来源已切换为钉钉通讯录，工具本身无需修改。

数据来源	PersonIndex 内存索引（底层数据来自钉钉 `POST /topapi/v2/user/list`）

参数	必填	说明
`query`	是	搜索关键词（姓名或部分名字）
`department`	否	部门名称（支持模糊匹配）

返回字段：

字段	来源钉钉 API 字段	说明
`name`	`name`	姓名
`job_title`	`title`	职位
`department`	通过 `dept_id_list` 关联部门名	所属部门
`userid`	`userid`	钉钉用户唯一标识
`mobile`	`mobile`	手机号（需申请 `Contact.User.Mobile` 权限）

实现位置：scripts/direct/tools/feishu.py → 复用（PersonIndex 底层已切换钉钉数据）

2. save_contact_alias — 学习别名

AI 在对话中学习到某人的别名后保存。工具无需修改，PersonIndex 层通用。

参数	必填	说明
`person_name`	是	通讯录中的正式姓名
`alias`	是	新别名（如"阿明""明哥"）

3. link_platform_identity — 绑定平台身份

将外部平台（如 CRM、GitLab 等）的用户标识绑定到公司人员。工具无需修改。

参数	必填	说明
`person_name`	是	通讯录中的正式姓名
`platform`	是	平台名（`crm` / `gitlab` 等）
`identifier`	是	平台上的用户标识

待封装的工具（4 个）

PersonIndex 已有对应方法，封装为 AI 可调用的 tool：

4. query_org_structure — 组织架构概览

目标	返回公司整体组织架构：部门树 + 各部门人数 + 负责人

底层方法：PersonIndex.get_org_summary(role)

钉钉数据来源：POST /topapi/department/list（一次返回所有部门，字段 dept_id、name、parent_id）

注：钉钉根部门 dept_id=1，与飞书 parent_department_id=0 不同。

5. query_department_members — 部门成员查询

目标	返回指定部门的全部成员列表（姓名 + 职位 + 是否主管）

参数	说明
`department`	部门名称（支持模糊匹配）

底层方法：PersonIndex.get_department_members(department)

钉钉数据来源：POST /topapi/v2/user/list（参数 dept_id，游标分页 cursor + size）

6. query_person_relations — 人员关系查询

目标	查询某人的上下级关系

参数	说明
`name`	人名
`relation_type`	`leader`（上级）/ `members`（下属）/ `team`（同组）/ `all`

底层方法：PersonIndex 通过 manager_userid 字段反向查询

钉钉字段依赖：

上级：manager_userid → 反查对应姓名
下属：反查 manager_userid = 当前用户 userid 的所有人
是否主管：leader_in_dept 字段

7. query_staff_changes — 人员变动查询

目标	查询最近的人员变动（入职/离职/调岗）

参数	说明
`days`	查询最近 N 天的变动（默认 7）
`change_type`	`join` / `leave` / `transfer` / `all`

钉钉数据来源：变动日志表（基于事件订阅记录）unified_users.change_log

底层实现：事件接收端点写入变动日志，本工具从日志读取

C 层 — 系统能力

不暴露给 AI，在消息处理链路中自动运行。

能力	说明	状态	实现位置
钉钉通讯录同步	每日凌晨全量同步部门树 + 人员到 MongoDB	⬜ 待实现	`scripts/dingtalk_sync.py`（新建）
PersonIndex 构建	启动时从 `unified_users` 加载全量数据建立内存索引	✅ 复用	`scripts/contacts/index.py`
PersonContext 档案	按场景裁剪输出人物上下文切片	✅ 复用	`scripts/memory/person_context.py`
userid 身份解析	钉钉消息 `senderStaffId` → `person_id` 自动解析 + 注入 system prompt	⬜ 适配层	`avatar_core.py`（扩展 dingtalk 渠道）
权限过滤	根据用户角色过滤查询结果中的人员数据	⬜ 待实现	与飞书版共用同一机制
数据质量自检	同步后检测缺失字段（职位/上级/部门），通知管理员	⬜ 待实现	—
离职处理	`user_leave_org` 事件触发 → `is_active=False` → 消息静默	⬜ 待实现	事件处理器

通讯录同步流程（全量）

事件订阅接收流程（实时）

Access Token 管理

POST https://api.dingtalk.com/v1.0/oauth2/accessToken
Body: { "appKey": "xxx", "appSecret": "xxx" }
→ accessToken（有效期 7200 秒）

存储：内存缓存 + 到期前 5 分钟自动刷新
旧版 API 调用：?access_token=xxx（URL 参数）
新版 API 调用：x-acs-dingtalk-access-token: xxx（Header）

身份解析流程

D 层 — 主动推送

非对话触发，由事件或定时任务驱动。

事件订阅（实时）

场景	钉钉事件	推送对象	状态
新员工入职通知	`user_add_org`	管理员（钉钉消息）	⬜ 待实现
员工离职通知	`user_leave_org`	人事负责人（钉钉消息）	⬜ 待实现
员工信息变更	`user_modify_org`	静默处理（仅更新数据）	⬜ 待实现
部门变更	`org_dept_create/modify/remove`	静默处理（仅更新数据）	⬜ 待实现

定时任务

场景	频率	触发条件	推送对象	状态
每日全量同步	每日凌晨 2:00	定时触发	—	⬜ 待实现
数据质量告警	每日最多 1 次	同步后检测到新增缺失项	管理员	⬜ 待实现

推送约束

约束	说明
防骚扰	数据质量告警每日最多 1 次，只通知新增缺失项
去重	已通知过的缺失项不重复发送
工作时段	仅在工作时间推送（9:00-19:00）
事件幂等	同一事件可能重复推送，处理时以 userid + 时间戳去重

复用的现有能力

能力	本场景用途	状态
PersonIndex	跨平台人员索引（按名/别名/平台 ID 查找）	✅ 直接复用
PersonContextResolver	统一人物工作档案（分层存储 + 按场景切片输出）	✅ 直接复用
contacts_learn 工具	AI 学习别名 + 平台身份绑定	✅ 直接复用
search_contacts 工具	通讯录查询（PersonIndex 底层，数据来源切换即可）	✅ 直接复用
NotificationEngine	主动通知的防骚扰控制（冷却/时段/每日上限）	✅ 直接复用
avatar_core	消息处理主流程（扩展 dingtalk 渠道适配层）	✅ 扩展适配

全局约束

约束	说明
钉钉为权威源	组织相关字段（部门/职位/上级）以钉钉通讯录 `userid` 返回值为准
权威性层级	`qinghai_manual` > `authoritative_sync` > `inferred` > `observed`
只读查询	不修改钉钉通讯录数据，仅读取和同步
手机号权限	获取 `mobile` 字段需申请 `Contact.User.Mobile` 权限，否则返回脱敏值
事件幂等处理	钉钉事件可能重复推送，接收端点需以 `userid + event_type + timestamp` 去重
离职即静默	`user_leave_org` 事件触发后立即静默，不等全量同步
缓存降级	钉钉 API 不可用时使用 `data/cache/dingtalk_contacts.json` 继续服务
Token 有效期	`accessToken` 有效期 7200 秒，需自动刷新，避免请求失败

实现路线

Phase 1：数据打通 + 身份识别

#	事项	状态
1	钉钉 Access Token 获取与自动刷新	⬜
2	钉钉通讯录全量同步（`DingTalkSync`）	⬜
3	`avatar_core` 适配 `senderStaffId` 身份解析	⬜
4	PersonIndex 扩展 `channels.dingtalk` 支持	⬜
5	事件订阅接收端点（HTTP 回调 + 验签）	⬜
6	事件处理：`user_add_org` / `user_leave_org` / `user_modify_org`	⬜

Phase 2：专用工具 + 权限

#	事项	状态
7	封装 `query_org_structure` 工具	⬜
8	封装 `query_department_members` 工具	⬜
9	封装 `query_person_relations` 工具（依赖 `manager_userid`）	⬜
10	封装 `query_staff_changes` 工具（依赖事件日志）	⬜
11	权限过滤中间件（角色 × 数据范围）	⬜
12	`org-query-dingtalk` SKILL.md 场景化编写	⬜

Phase 3：主动推送 + 数据质量

#	事项	状态
13	数据质量自检 + 管理员通知	⬜
14	人员变动通知（入职/离职推送给管理员）	⬜
15	事件处理：部门变动（`org_dept_*`）	⬜

文档

电子表格

多维表格

知识库

Skill 清单

架构总览

分层判断标准

Skill / Tool 汇总

A 层 — 当前无独立 Skill

现状

目标设计

B 层 — Tool 清单

已实现（直接复用飞书版，3 个）

1. search_contacts — 通讯录搜索

2. save_contact_alias — 学习别名

3. link_platform_identity — 绑定平台身份

待封装的工具（4 个）

4. query_org_structure — 组织架构概览

5. query_department_members — 部门成员查询

6. query_person_relations — 人员关系查询

7. query_staff_changes — 人员变动查询

C 层 — 系统能力

通讯录同步流程（全量）

事件订阅接收流程（实时）

Access Token 管理

身份解析流程

D 层 — 主动推送

事件订阅（实时）

定时任务

推送约束

复用的现有能力

全局约束

实现路线

Phase 1：数据打通 + 身份识别

Phase 2：专用工具 + 权限

Phase 3：主动推送 + 数据质量

Skill 清单 ​

架构总览 ​

分层判断标准 ​

Skill / Tool 汇总 ​

A 层 — 当前无独立 Skill ​

现状 ​

目标设计 ​

B 层 — Tool 清单 ​

已实现（直接复用飞书版，3 个） ​

1. search_contacts — 通讯录搜索 ​

2. save_contact_alias — 学习别名 ​

3. link_platform_identity — 绑定平台身份 ​

待封装的工具（4 个） ​

4. query_org_structure — 组织架构概览 ​

5. query_department_members — 部门成员查询 ​

6. query_person_relations — 人员关系查询 ​

7. query_staff_changes — 人员变动查询 ​

C 层 — 系统能力 ​

通讯录同步流程（全量） ​

事件订阅接收流程（实时） ​

Access Token 管理 ​

身份解析流程 ​

D 层 — 主动推送 ​

事件订阅（实时） ​

定时任务 ​

推送约束 ​

复用的现有能力 ​

全局约束 ​

实现路线 ​

Phase 1：数据打通 + 身份识别 ​

Phase 2：专用工具 + 权限 ​

Phase 3：主动推送 + 数据质量 ​

Skill 清单

架构总览

分层判断标准

Skill / Tool 汇总

A 层 — 当前无独立 Skill

现状

目标设计

B 层 — Tool 清单

已实现（直接复用飞书版，3 个）

1. search_contacts — 通讯录搜索

2. save_contact_alias — 学习别名

3. link_platform_identity — 绑定平台身份

待封装的工具（4 个）

4. query_org_structure — 组织架构概览

5. query_department_members — 部门成员查询

6. query_person_relations — 人员关系查询

7. query_staff_changes — 人员变动查询

C 层 — 系统能力

通讯录同步流程（全量）

事件订阅接收流程（实时）

Access Token 管理

身份解析流程

D 层 — 主动推送

事件订阅（实时）

定时任务

推送约束

复用的现有能力

全局约束

实现路线

Phase 1：数据打通 + 身份识别

Phase 2：专用工具 + 权限

Phase 3：主动推送 + 数据质量