Skill 清单

飞书场景管理的全部能力定义，按清海 AI 实际工作方式分层组织。场景总览见飞书场景管理，飞书妙记详细场景见飞书妙记 · 会议纪要，飞书云文档详细场景见飞书云文档。

架构总览

飞书场景管理的能力分为四层，核心设计原则：自动触发走纯 Python 流水线，用户对话触发走 Skill。

分层判断标准

层级	判断标准	开发产出
A — Skill	用户在对话中触发，AI 需要场景引导、工具组合策略	`skills/feishu_minutes/SKILL.md`
B — Tool	AI 需要调用，tool schema 可自描述	`scripts/direct/tools/feishu_minutes.py`
C — 系统能力	不需要 AI 感知，自动在工具内部或流水线中运行	工具内部逻辑 / 中间件
D — 纯 Python 流水线	Webhook 事件驱动，不经过 agent loop，AI 只作为 LLM 调用	`scripts/feishu_events.py` + `llm/client.py`

Skill / Tool 汇总

名称	描述	状态
`feishu_minutes` Skill	飞书妙记会议纪要 AI 对话技能（SKILL.md）	🔲 待开发
`get_minute_transcript`	获取妙记完整转录文本	🔲 待开发
`create_minutes_doc`	将纪要写入飞书云文档指定目录	🔲 待开发
`list_user_minutes`	列出用户相关的妙记（按时间/会议类型）	🔲 待开发
`get_minutes_archive`	查询飞书云文档中已归档的会议纪要	🔲 待开发
妙记 Webhook 流水线	转录完成事件 → 自动提炼归档（纯 Python）	🔲 待开发

架构决策：Skill vs 纯 Python

这是飞书妙记场景的核心设计决策，直接影响开发方式和代码归属。

两条触发路径的本质差异

	自动触发（Webhook）	主动触发（用户对话）
触发源	飞书平台推送事件	用户在飞书/TG 发消息
是否有人在等	否，后台静默处理	是，用户等待回复
处理路径	纯 Python 流水线	Skill → agent loop
LLM 调用方式	`llm/client.py`（同步，内部调用）	`direct/client.py`（agent loop）
工具调用	Python 函数直接调用（不走 tool_use）	tool_use（AI 决策调用）
灵活性需求	固定流程，不需要 AI 决策	用户意图多样，需 AI 理解

自动触发流水线（D 层）

关键点： 整条链路无 agent loop，LLM 只做一次文本提炼（llm/client.py），Python 负责所有 API 调用。

主动触发路径（A + B 层）

关键点： AI 自己理解转录内容并提炼（在 agent loop 内），工具只负责数据获取和写入。

A 层 — Skill：feishu_minutes 对话技能

SKILL.md 内部结构

yaml

name: feishu_minutes
trigger: 妙记|会议纪要|整理会议|归档纪要|会议记录|分钟会议|处理妙记|会议总结
description: 飞书妙记转录文字提炼为结构化会议纪要，写入飞书云文档归档
tools: [get_minute_transcript, create_minutes_doc, list_user_minutes, get_minutes_archive]
scope: user

覆盖的会话场景

场景	触发词示例	涉及工具
整理指定妙记	"帮我整理 [链接] 的会议纪要"	`get_minute_transcript` → LLM 提炼 → `create_minutes_doc`
整理最近一次会议	"整理一下今天下午的会议"	`list_user_minutes` → `get_minute_transcript` → `create_minutes_doc`
查询已归档纪要	"上周五的会议纪要在哪"	`get_minutes_archive`
本月纪要汇总	"本月的会议纪要整理一下"	`get_minutes_archive(month=当月)`

权限规则（嵌入 SKILL.md）

角色	可访问范围
老板 / 人事	所有人的妙记和纪要
部门负责人	本部门的妙记和纪要 + 本人参与的跨部门会议
普通员工	仅自己参与的妙记和纪要

B 层 — Python Tool 清单

所有工具暴露给 AI，通过 tool_use 调用。同时被 D 层流水线直接调用（Python 函数调用，非 tool_use）。

公共行为

所有工具共享：
- 妙记 API（get_minute_transcript / list_user_minutes）使用 user_access_token（OAuth 授权，自动续期）
- 云文档写入 API（create_minutes_doc）使用 user_access_token —— 确保文档所属人为发起操作的用户，而非清海 Bot
- 消息 API 使用 tenant_access_token（从配置读取，自动刷新）
- minute_token 支持直接传 token 或完整飞书妙记链接（工具层解析）
- 调用前检查 user_access_token 有效性，过期则用 refresh_token 静默续期
- 无有效 token（首次使用 / refresh_token 过期）时返回授权引导消息，不执行 API 调用
- 错误时返回可读错误说明，不抛异常
- 超长文本自动截断并说明省略行数

1. get_minute_transcript — 获取转录全文

获取指定飞书妙记的完整转录文本，含说话人标注和时间戳。

飞书 API	`GET /minutes/v1/minutes/{minute_token}/transcript`（⚠️ 需实测确认接口可用性）

参数	必填	说明
`minute_token`	是	妙记 token 或完整链接
`map_speakers`	否（默认 true）	是否通过 PersonIndex 将说话人 ID 映射为真实姓名

返回内容： 格式化文本（说话人 + 时间戳 + 内容），超 50,000 字自动分段标注

C 层联动： 内部调用 PersonIndex 做说话人映射；超长文本触发分段逻辑

2. create_minutes_doc — 写入飞书云文档

在飞书云文档的指定目录下创建会议纪要文档。

飞书 API	`POST /docx/v1/documents` + `POST /docx/v1/documents/{document_id}/blocks/{block_id}/children`（追加内容块）

参数	必填	说明
`title`	是	文档标题（格式：`YYYY-MM-DD-会议主题`）
`content`	是	结构化纪要文本（Markdown）
`folder_token`	否	目标目录 token，默认写入「会议记录」根目录
`minute_token`	否	关联的妙记 token，用于重复归档检测

C 层联动： 写入前检查同一 minute_token 是否已归档（重复检测），已存在则追加版本号

返回内容： 文档链接 + 文档 token

3. list_user_minutes — 列出用户妙记

列出指定用户相关的妙记（作为参会人或组织者）。

⚠️ API 边界说明：飞书 minutes/v1 下无妙记列表接口。此 Tool 实际通过 Drive API 在云空间中按文件类型（mindnote）搜索，或结合 get_minutes_archive 从已归档目录反向查找。若用户直接提供妙记链接（含 minute_token），优先走 get_minute_transcript 直接处理，无需列表接口。

飞书 API	`GET /drive/v1/files`（按 `folder_token` + 文件类型过滤，替代不存在的列表接口）

参数	必填	说明
`user_id`	否	指定用户，默认为当前对话用户
`days`	否（默认 7）	最近 N 天内的妙记（通过 `created_time` 过滤）
`status`	否	`transcribed`（已转录）/ `all`

C 层联动： 权限过滤（普通员工只能查自己的）

返回内容： 妙记列表（标题、时间、转录状态、是否已生成纪要）

降级策略： 若 Drive 搜索结果不准确，提示用户直接提供妙记链接

4. get_minutes_archive — 查询已归档纪要

查询飞书云文档会议记录目录中已归档的纪要。

飞书 API	`GET /drive/v1/files`（按目录列出）

参数	必填	说明
`month`	否	按月筛选（格式：`YYYY-MM`），不填返回全部
`keyword`	否	按会议主题关键词搜索
`folder_token`	否	目标目录 token，默认会议记录根目录

C 层联动： 权限过滤（角色决定可见的目录范围）

返回内容： 纪要文档列表（标题、创建时间、链接）

C 层 — Python 系统能力

不暴露给 AI，在 Tool 内部或 D 层流水线中自动运行。

能力	说明	实现位置	状态
PersonIndex 映射	妙记说话人 ID → 中文姓名	Tool 内部 + 流水线	复用现有
长文本分段	转录 > 50,000 字时自动分段，LLM 分段提炼后合并	`get_minute_transcript` 内部	🔲 待开发
权限过滤	角色 × 妙记可见范围，自动过滤无权访问的内容	Tool 返回前	🔲 待开发
重复归档检测	同一 `minute_token` 防止重复写入云文档	`create_minutes_doc` 内部	🔲 待开发
用户 Token 管理	OAuth 授权引导 + user_access_token / refresh_token 持久化存储 + 2 小时自动续期 + 30 天过期重授权引导	OAuth 中间件	🔲 待开发
Token 自动刷新（Bot）	`tenant_access_token` 2 小时过期，自动刷新	HTTP 客户端层	复用飞书现有

D 层 — 纯 Python 流水线（自动触发）

这是飞书妙记与其他场景最大的不同：自动归档完全不经过 agent loop，是独立的后台处理链路。

非 agent loop，事件驱动，llm/client.py 做 LLM 调用（同步），Python 函数直接调用各飞书 API。

流水线步骤

步骤	模块	说明
1. 接收 Webhook	`scripts/feishu_events.py`	监听 `minutes.transcription_completed` 事件（⚠️ 需在控制台「事件订阅」搜索"妙记"确认准确事件名）
2. 过滤判断	流水线内部	三层过滤，不满足条件则跳过（见下方）
3. 检查用户 Token	OAuth 中间件	校验会议组织者的 user_access_token 是否有效；过期则续期；无 token 则发消息提示用户先授权
4. 获取转录文本	直接调用飞书 API（复用 B 层逻辑）	含说话人映射（PersonIndex）
5. LLM 提炼纪要	`llm/client.py`（同步调用）	固定 Prompt 模板，输出标准纪要格式
6. 写入云文档	直接调用飞书 API（复用 B 层逻辑）	使用会议组织者的 user_access_token 创建文档（所属人为组织者）；含重复归档检测
7. 通知相关人	飞书消息 API	通知会议组织者 + 人事部门

过滤逻辑（第 2 步展开）

Webhook 触发后先拉取妙记基本信息（GET /minutes/v1/minutes/{minute_token}），做三层过滤再决定是否进入 LLM 处理。

第一层：基础条件过滤

条件	处理	原因
时长 < 5 分钟	跳过	误录、测试、随手开着忘关
参会人数 = 1	跳过	个人录音，不是会议
已处理过（minute_token 重复）	跳过	防重复归档

此层不读转录文本，仅用基本信息，成本极低。

第二层：敏感内容路由

检查会议标题是否含敏感关键词：薪酬 / 绩效 / 调薪 / 裁员 / offer / 晋升 / 淘汰

匹配结果	归档目标	通知对象
未命中	会议记录 / 部门目录	会议组织者
命中	会议记录 / HR 专属目录	仅 HR，不通知普通参会人

第三层：归档范围配置（默认全员开启）

默认对所有满足条件的妙记自动归档（模式 A），管理员可切换为模式 B（员工主动开启后才生效）。对内部工具场景推荐模式 A。

LLM 提炼 Prompt 关键设计

系统角色：你是会议纪要助手，负责将会议转录文字整理为结构化纪要。

提炼规则：
1. 过滤：笑声、语气词（嗯、好的好的）、重复确认、闲聊
2. 识别话语类型：陈述/提问/决策/待办
3. 保留：具体数字、时间点、人名、决策结论
4. 待办事项必须明确 owner 和 deadline（转录中提到则提取，未提到则留空）
5. 超过 2 小时的会议：按议题或时间段分节，不要一堆流水账

失败处理

失败场景	处理方式
用户未授权（首次使用）	发送 OAuth 授权链接「需要你授权一次才能访问妙记，点击这里：{链接}」，本次跳过处理
refresh_token 过期（30 天未用）	同上，重新引导授权
妙记 API 获取失败	重试 3 次，失败后通知会议组织者手动处理
LLM 提炼失败	降级：将原始转录文字发给组织者，提示 AI 处理失败
云文档写入失败	将纪要文本以飞书消息形式发送给组织者，附提示「请手动归档」
权限不足	通知管理员，记录日志

推送约束

约束	说明
工作时段	工作时间内立即处理（9:00-19:00），非工作时间延迟到次日 9:00
防重推	同一妙记不重复发送通知
通知对象	仅通知会议组织者 + 人事部门，不群发给所有参会人

复用的现有能力

能力	本场景用途	状态
PersonIndex	说话人 ID → 中文姓名映射，参会人权限判断	✅ 已实现
飞书 HTTP 客户端	tenant_access_token 鉴权、API 调用	✅ 已实现（feishu_bot.py）
llm/client.py	D 层流水线的 LLM 提炼调用	✅ 已实现
NotificationEngine	推送防骚扰控制（冷却/时段/上限）	✅ 已实现
feishu-message Skill	主动触发场景完成后发通知	✅ 已实现

全局约束

约束	说明
妙记权限	仅能访问清海 Bot 有权限的妙记；企业外部人员的妙记不可访问
敏感内容	含薪酬/绩效/人事决定的会议，纪要仅归档至人事专属目录，不通知其他人
转录质量	置信度低的段落标注 `⚠️ 此段转录可能不准确`，不强行脑补
云文档权限	清海 Bot 需提前配置云文档写入权限，否则降级为消息发送
最短时长	< 5 分钟的妙记跳过自动处理，避免误录场景

实现路线

Phase 1：D 层自动流水线（优先级最高）

自动触发是核心价值，对用户无感，先做。

#	事项	状态
1	飞书 OAuth 授权引导流程（授权链接发送 + token 存储 + 2h 续期 + 30d 重授权）	🔲 待开发
2	飞书 Webhook 接收端点（`feishu_events.py`）	🔲 待开发
3	妙记 API 封装（获取转录文本，使用 user_access_token）	🔲 待开发
4	LLM 提炼 Prompt + `llm/client.py` 调用	🔲 待开发
5	飞书云文档写入（创建文档 + 写内容）	🔲 待开发
6	完成通知（飞书消息推送）	🔲 待开发
7	失败处理与降级逻辑（含未授权降级）	🔲 待开发

Phase 2：B 层 Tool + A 层 Skill（用户主动触发）

#	事项	状态
7	`get_minute_transcript` Tool	🔲 待开发
8	`create_minutes_doc` Tool	🔲 待开发
9	`list_user_minutes` Tool	🔲 待开发
10	`get_minutes_archive` Tool	🔲 待开发
11	`feishu_minutes` SKILL.md	🔲 待开发

Phase 3：C 层系统增强

#	事项	状态
12	权限过滤中间件	🔲 待开发
13	长文本分段处理	🔲 待开发
14	重复归档检测	🔲 待开发

文档

电子表格

多维表格

知识库

Skill 清单

架构总览

分层判断标准

Skill / Tool 汇总

架构决策：Skill vs 纯 Python

两条触发路径的本质差异

自动触发流水线（D 层）

主动触发路径（A + B 层）

A 层 — Skill：feishu_minutes 对话技能

SKILL.md 内部结构

覆盖的会话场景

权限规则（嵌入 SKILL.md）

B 层 — Python Tool 清单

公共行为

1. get_minute_transcript — 获取转录全文

2. create_minutes_doc — 写入飞书云文档

3. list_user_minutes — 列出用户妙记

4. get_minutes_archive — 查询已归档纪要

C 层 — Python 系统能力

D 层 — 纯 Python 流水线（自动触发）

流水线步骤

过滤逻辑（第 2 步展开）

LLM 提炼 Prompt 关键设计

失败处理

推送约束

复用的现有能力

全局约束

实现路线

Phase 1：D 层自动流水线（优先级最高）

Phase 2：B 层 Tool + A 层 Skill（用户主动触发）

Phase 3：C 层系统增强

Skill 清单 ​

架构总览 ​

分层判断标准 ​

Skill / Tool 汇总 ​

架构决策：Skill vs 纯 Python ​

两条触发路径的本质差异 ​

自动触发流水线（D 层） ​

主动触发路径（A + B 层） ​

A 层 — Skill：feishu_minutes 对话技能 ​

SKILL.md 内部结构 ​

覆盖的会话场景 ​

权限规则（嵌入 SKILL.md） ​

B 层 — Python Tool 清单 ​

公共行为 ​

1. get_minute_transcript — 获取转录全文 ​

2. create_minutes_doc — 写入飞书云文档 ​

3. list_user_minutes — 列出用户妙记 ​

4. get_minutes_archive — 查询已归档纪要 ​

C 层 — Python 系统能力 ​

D 层 — 纯 Python 流水线（自动触发） ​

流水线步骤 ​

过滤逻辑（第 2 步展开） ​

LLM 提炼 Prompt 关键设计 ​

失败处理 ​

推送约束 ​

复用的现有能力 ​

全局约束 ​

实现路线 ​

Phase 1：D 层自动流水线（优先级最高） ​

Phase 2：B 层 Tool + A 层 Skill（用户主动触发） ​

Phase 3：C 层系统增强 ​

Skill 清单

架构总览

分层判断标准

Skill / Tool 汇总

架构决策：Skill vs 纯 Python

两条触发路径的本质差异

自动触发流水线（D 层）

主动触发路径（A + B 层）

A 层 — Skill：feishu_minutes 对话技能

SKILL.md 内部结构

覆盖的会话场景

权限规则（嵌入 SKILL.md）

B 层 — Python Tool 清单

公共行为

1. get_minute_transcript — 获取转录全文

2. create_minutes_doc — 写入飞书云文档

3. list_user_minutes — 列出用户妙记

4. get_minutes_archive — 查询已归档纪要

C 层 — Python 系统能力

D 层 — 纯 Python 流水线（自动触发）

流水线步骤

过滤逻辑（第 2 步展开）

LLM 提炼 Prompt 关键设计

失败处理

推送约束

复用的现有能力

全局约束

实现路线

Phase 1：D 层自动流水线（优先级最高）

Phase 2：B 层 Tool + A 层 Skill（用户主动触发）

Phase 3：C 层系统增强