Skill 清单
飞书组织架构识别场景的全部能力定义，按清海 AI 实际工作方式分层组织。 会话场景概览见 飞书组织架构识别，角色维度的会话旅程见 角色场景。
架构总览
飞书组织架构识别的能力分为四层，从 AI 对话侧到系统自动化逐层递进：
分层判断标准
| 层级 | 判断标准 | 当前状态 |
|---|---|---|
| A — Skill | AI 需要场景指导、权限规则、工具组合策略 | ⬜ 无 SKILL.md |
| B — Tool | AI 需要调用、tool schema 可自描述 | ✅ 3 个工具已实现 |
| C — 系统能力 | 不需要 AI 感知，自动运行 | ✅ 核心已实现，权限待补 |
| D — 主动推送 | 非对话触发，由定时或事件驱动 | ✅ 同步已实现，通知待补 |
Skill / Tool 汇总
| 名称 | 描述 | 状态 |
|---|---|---|
search_contacts | 按姓名或部门查找员工信息 | ✅ 已实现 |
save_contact_alias | AI 在对话中学习并保存人员别名 | ✅ 已实现 |
link_platform_identity | 将外部平台身份绑定到公司人员 | ✅ 已实现 |
query_org_structure | 返回公司整体组织架构树与部门人数 | ✅ 已实现 |
query_department_members | 查询指定部门的全部成员列表 | ✅ 已实现 |
query_person_relations | 查询某人的上下级与同组关系 | ✅ 已实现 |
query_staff_changes | 查询最近人员变动（入职/离职/调岗） | ⬜ 待实现 |
A 层 — 当前无独立 Skill
现状
当前没有 skills/org-query/SKILL.md，AI 靠以下两条路径回答组织架构问题：
- system prompt 身份注入：
avatar_core.build_avatar_prompt()在 Block 1 注入 "王五是产品部的产品经理" - search_contacts 工具：AI 主动调用查询人员信息
目标设计
后续计划创建 skills/org-query/SKILL.md，提供：
- 触发词匹配：
组织|部门|同事|上级|下属|团队|架构|人员|成员|谁是|有谁|几个人|负责人 - 角色权限规则（老板/组长/员工各看什么）
- 推荐工具组合和调用顺序
- 回复格式要求
B 层 — Tool 清单
已实现的工具（3 个）
1. search_contacts — 通讯录搜索
按姓名或部门查找员工信息。这是当前 AI 可用的唯一组织查询工具。
| 数据来源 | PersonIndex 内存索引（底层数据来自飞书 GET /contact/v3/users/find_by_department） |
|---|
| 参数 | 必填 | 说明 |
|---|---|---|
query | 是 | 搜索关键词（姓名或部分名字） |
department | 否 | 部门名称（支持模糊匹配） |
返回字段：
| 字段 | 来源飞书 API 字段 | 说明 |
|---|---|---|
name | name | 姓名 |
job_title | job_title | 职位 |
department | 通过 department_ids 关联部门名 | 所属部门 |
open_id | open_id | 飞书用户唯一标识（ou_ 开头） |
mobile | mobile | 手机号 |
实现位置：scripts/direct/tools/feishu.py → PersonIndex.search(query, department)
2. save_contact_alias — 学习别名
AI 在对话中学习到某人的别名后保存。
| 参数 | 必填 | 说明 |
|---|---|---|
person_name | 是 | 通讯录中的正式姓名（name 字段值） |
alias | 是 | 新别名（如"阿远""远哥"） |
实现位置：scripts/direct/tools/contacts_learn.py → PersonIndex.add_alias() + MongoDB 同步
3. link_platform_identity — 绑定平台身份
将外部平台（如 GitLab）的用户标识绑定到公司人员。
| 参数 | 必填 | 说明 |
|---|---|---|
person_name | 是 | 通讯录中的正式姓名 |
platform | 是 | 平台名（gitlab / wecom 等） |
identifier | 是 | 平台上的用户标识（如 GitLab username） |
实现位置：scripts/direct/tools/contacts_learn.py → PersonIndex.add_identity() + MongoDB 同步
待封装的工具（4 个）
PersonIndex 已有对应方法，但尚未封装为 AI 可调用的 tool：
4. query_org_structure — 组织架构概览
| 目标 | 返回公司整体组织架构：部门树 + 各部门人数 + 负责人 |
|---|
底层方法：PersonIndex.get_org_summary(role)
飞书数据来源：GET /contact/v3/departments（open_department_id、name、member_count）
5. query_department_members — 部门成员查询
| 目标 | 返回指定部门的全部成员列表（姓名 + 职位 + 是否管理者） |
|---|
| 参数 | 说明 |
|---|---|
department | 部门名称（支持模糊匹配） |
底层方法：PersonIndex.get_department_members(department)
飞书数据来源：GET /contact/v3/users/find_by_department（name、job_title、department_ids）
注：
search_contacts(department=...)部分覆盖此功能，但返回格式和完整度不同。
6. query_person_relations — 人员关系查询
| 目标 | 查询某人的上下级关系 |
|---|
| 参数 | 说明 |
|---|---|
name | 人名 |
relation_type | leader（上级）/ members（下属）/ team（同组）/ all |
底层方法：PersonIndex.get_person_leader() / get_team_members() / get_team_group()
7. query_staff_changes — 人员变动查询
| 目标 | 查询最近的人员变动（入职/离职/调岗） |
|---|
| 参数 | 说明 |
|---|---|
days | 查询最近 N 天的变动（默认 7） |
change_type | join / leave / transfer / all |
飞书数据来源：同步时对比 status.is_resigned、status.is_activated、department_ids 的变更
底层实现：基于 unified_users.updated_at + is_active 变更检测
C 层 — 系统能力
不暴露给 AI，在消息处理链路中自动运行。
| 能力 | 说明 | 状态 | 实现位置 |
|---|---|---|---|
| 飞书通讯录同步 | 每 30 分钟调用飞书 API 同步部门树 + 人员到 MongoDB | ✅ | scripts/feishu_sync.py |
| PersonIndex 构建 | 启动时从 unified_users 加载全量数据建立内存索引 | ✅ | scripts/contacts/index.py |
| PersonContext 档案 | 按场景裁剪输出人物上下文切片（dialog/concern/send_message/dashboard） | ✅ | scripts/memory/person_context.py |
| 身份解析 | 飞书消息 open_id → person_id 自动解析 + 注入 system prompt | ✅ | avatar_core.py |
| 权限过滤 | 根据用户角色过滤查询结果中的人员数据 | ⬜ | 待实现 |
| 数据质量自检 | 同步后检测缺失字段（职位/上级/部门），通知管理员 | ⬜ | 待实现 |
| 离职处理 | status.is_resigned=true → is_active=False → 消息静默 | ✅ | 同步逻辑 |
通讯录同步流程
身份解析流程
权限过滤流程（目标设计）
D 层 — 主动推送
非对话触发，由定时任务驱动。
定时任务
| 推送场景 | 频率 | 触发条件 | 推送对象 | 状态 |
|---|---|---|---|---|
| 通讯录同步 | 每 30 分钟 | 定时触发 | — | ✅ 已实现 |
| 数据质量告警 | 每日最多 1 次 | 同步后检测到新增缺失项 | 管理员（飞书） | ⬜ 待实现 |
| 新员工入职通知 | 同步时触发 | 检测到新 open_id | 管理员（飞书） | ⬜ 待实现 |
| 员工离职通知 | 同步时触发 | 检测到 status.is_resigned=true | 人事（飞书） | ⬜ 待实现 |
实现依赖：FeishuSync + NotificationEngine + feishu-message Skill
推送约束
| 约束 | 说明 |
|---|---|
| 防骚扰 | 数据质量告警每日最多 1 次，只通知新增缺失项 |
| 去重 | 已通知过的缺失项不重复发送 |
| 工作时段 | 仅在工作时间推送（9:00-19:00） |
| 语气 | 信息性通知，客观陈述 |
复用的现有能力
| 能力 | 本场景用途 | 状态 |
|---|---|---|
| 飞书通讯录 API | 部门树 + 人员信息同步 | ✅ 已实现 |
| FeishuSync | 定时同步通讯录到 MongoDB + 本地缓存 | ✅ 已实现 |
| PersonIndex | 跨平台人员索引（按名/别名/平台ID查找） | ✅ 已实现 |
| PersonContextResolver | 统一人物工作档案（分层存储 + 按场景切片输出） | ✅ 已实现 |
| contacts_learn 工具 | AI 学习别名 + 平台身份 | ✅ 已实现 |
| feishu-message Skill | 管理员通知、人事通知推送 | ✅ 已实现 |
| NotificationEngine | 主动通知的防骚扰控制（冷却/时段/每日上限） | ✅ 已实现 |
| 角色匹配 | .claude/roles/ 下按职位/部门匹配角色提示词 | ✅ 已实现 |
全局约束
| 约束 | 说明 |
|---|---|
| 飞书为权威源 | 组织相关字段（部门/职位/上级）以飞书 GET /contact/v3/users 返回值为准 |
| 权威性层级 | qinghai_manual > authoritative_sync > inferred > observed |
| 只读查询 | 不修改飞书通讯录数据，仅读取和同步 |
| 隐私保护 | 聊天原文只有 AI 和本人知道，向他人只说判断不说原文 |
| 离职即静默 | MVP 阶段 status.is_resigned=true 的员工立即静默 |
| 缓存降级 | 飞书 API 不可用时使用 data/cache/contacts.json 继续服务 |
实现路线
Phase 1：数据打通 + 身份识别（已完成）
| # | 事项 | 状态 |
|---|---|---|
| 1 | 飞书通讯录同步（FeishuSync） | ✅ |
| 2 | PersonIndex 内存索引 | ✅ |
| 3 | PersonContextResolver 统一档案 | ✅ |
| 4 | 身份自动识别（avatar_core 消息链路） | ✅ |
| 5 | search_contacts 通讯录查询工具 | ✅ |
| 6 | save_contact_alias + link_platform_identity 学习工具 | ✅ |
Phase 2：专用工具 + 权限（待实现）
| # | 事项 | 状态 |
|---|---|---|
| 7 | 封装 query_org_structure 工具 | ⬜ |
| 8 | 封装 query_department_members 工具 | ⬜ |
| 9 | 封装 query_person_relations 工具 | ⬜ |
| 10 | 封装 query_staff_changes 工具 | ⬜ |
| 11 | 权限过滤中间件（角色 × 数据范围） | ⬜ |
| 12 | org-query SKILL.md 场景化编写 | ⬜ |
Phase 3：主动推送 + 数据质量
| # | 事项 | 状态 |
|---|---|---|
| 13 | 数据质量自检 + 管理员通知 | ⬜ |
| 14 | 人员变动通知（入职/离职/调岗） | ⬜ |