讯灵录音助手
一句话：把连接录音卡里的会议录音，自动变成能直接用的会议纪要、周报和待办，并帮你发出去。
它能帮你做什么
- 会议一结束，自动把录音整理成条理清楚的会议纪要：谁说了什么、决定了什么、下一步谁做什么。
- 想把几场会合成一份周报 / 月报，一句话就行。
- 自动从会议里挑出待办清单，责任到人。
- 整理好的内容，帮你发到飞书群、发给同事，或发到企业微信。
怎么用（很简单）
- 在小程序里点「发送」或「获取配对码」，拿到一个 6 位数字。
- 把这个数字告诉我。
- 剩下的交给我：自动连好、自动整理、自动发送。以后开会不用再管。
不用装软件、不用敲命令、不用填任何密钥，也不用一直开着电脑 —— 定时发送由服务器完成。
> 下面「技术说明」部分是给自动化流程看的，普通用户可以跳过。
技术说明（普通用户可跳过）
鉴权：不持有任何静态令牌。用户在小程序里点「获取配对码」拿到 6 位数字，本技能用它换用户态 JWT（7 天，滚动续期），所有接口以 Authorization: Bearer <jwt> 调用；后端按用户身份只返回其绑定设备的会议。
分发（2026-11-05 起架构）：小程序「发送」产生的待发任务，由后端 Java 定时任务（RuoYi Quartz）消费并直接发送，不依赖用户电脑开机，也不再需要本地定时任务 / 本地常驻监听。原 Python 常驻 worker 已下线。本技能只负责：① 接入（配对登录 + 能力上报 + 群同步）；② 会话内的纪要 / 周报 / 待办生成；③ 用户当面指定接收方时的直发（走 WorkBuddy 连接器 lark-cli / wecom-cli）。
零操作：用户只需要报一个 6 位数字。剩下的登录、令牌上报、群同步由 Agent 按本文档自动完成 —— 使用者是普通用户，不要让他们敲命令、改配置、双击脚本。
前置依赖
- Python 3.9+（仅标准库；
qrcode可选）。若python不在 PATH，用 WorkBuddy 自带解释器：
~/.workbuddy/binaries/python/versions/<最新版本>/python.exe（Windows）或python3（macOS/Linux）。 - 后端地址默认
https://rec.19880708.com/prod-api，可用环境变量REC_BASE_URL覆盖。 - WorkBuddy 飞书连接器（
lark-cli）：自动发送不需要（由后端定时任务调服务器上的同名 CLI）；本技能用它做群列表同步兜底和当面直发。企业微信（wecom-cli）可选。
零、首次接入（Agent 必须严格按此执行）
触发：用户发来 6 位数字（配对码），或说「连接连接录音卡 / 绑定设备 / 接入会议纪要」。
步骤 1 —— 确认 skill 目录与 python
<SKILL_DIR> = 本 SKILL.md 所在目录（skillhub 安装在 ~/.workbuddy/skills/xunling-meeting-minutes）。
脚本统一用 python "<SKILL_DIR>/scripts/xxx.py" 调用；python 不存在时依次尝试 python3、WorkBuddy 自带解释器。
步骤 2 —— 一条命令完成登录 + 令牌上报 + 群同步
python "<SKILL_DIR>/scripts/setup.py" --pair <6位配对码>
按输出分流（不要让用户自己去看这些输出）：
| 输出 | 含义 | Agent 动作 |
|---|---|---|
SETUP_OK {...} |
成功 | 继续步骤 3 |
TOKEN_SYNCED |
用户态令牌已上报（兼容保留） | 正常，无需处理；自动发送由后端定时任务负责 |
WARN: ...令牌上报... |
上报接口暂不可用 | 不阻塞；自动发送由后端定时任务负责、不依赖这份令牌，其它功能照常 |
NEED_LOGIN |
没给码也没登录过 | 告诉用户在小程序「会议详情 → 发送 → 获取配对码」拿码 |
AUTH_FAILED |
登录态失效 | 让用户重新出码后再跑一次 |
| 配对码错误/过期（退出码 1） | 码 5 分钟有效、一次性 | 让用户重新出码，不要重试同一个码 |
FEISHU_NOT_CONNECTED |
本机没连飞书连接器 | 自动发送不受影响（走服务器）；影响群同步与当面直发，需要时再引导连接 |
步骤 3 —— 用大白话向用户确认（不要创建定时任务、不要启动常驻监听）
> ⚠️ 不要再创建「会议纪要自动发送」定时任务，也不要启动 watch.py 常驻 —— 待发队列已由后端 Java 定时任务消费，本地再做会重复发送。
> 若发现历史遗留的定时任务（名为「会议纪要自动发送」），提示用户删掉。
固定说清两件事，别贴技术细节：
> 已经连好了。以后在小程序里点「发送」，纪要会自动发到飞书。
> · 不用开着电脑，服务器自动发。
> · 如果隔很久没收到，重新在小程序出一次配对码发我就行。
> · 如果小程序提示「未连接飞书」，跟我说一句「连接飞书」，扫一次码就好。
零点五、连接飞书（只在 WorkBuddy 里扫一次）
触发：用户说「连接飞书 / 飞书发不出去 / 飞书授权过期」，或接入后小程序显示「未连接飞书 / 授权已过期」。
> 铁律
> 1. 飞书授权二维码只在 WorkBuddy 里展示（由本技能输出）。小程序里不放二维码（小程序扫不了），小程序只显示「已连接 / 未连接 / 已过期」。
> 2. 绝不让用户填 appId / appSecret，也不要让用户敲命令改配置。用的就是用户自己扫码创建并授权的飞书 CLI，不是咱们预置的应用。
> 3. 用户只需要做一件事：用手机飞书扫一下码。不用装软件、不用一直开着电脑。
步骤 1 —— 发起并展示二维码
python "<SKILL_DIR>/scripts/feishu_auth.py"
把输出里 FEISHU_AUTH_QR_BEGIN ~ FEISHU_AUTH_QR_END 之间的内容原样放进等宽代码块展示给用户（ASCII 二维码，字体不等宽会变形）；同时备好 FEISHU_AUTH_QR_IMAGE:<路径> 那张图，用户扫不出来时改展示图片。若出现 FEISHU_AUTH_QR_NONE，就把 FEISHU_AUTH_URL 链接给用户手动打开。然后只说一句大白话：
> 用手机飞书扫一下这个码，扫完回来跟我说一声就行。
说完就结束这一轮，不要在这里轮询等待用户扫码（后端授权定时任务会自己完成授权）。
步骤 2 —— 用户说「扫好了」之后查一次
python "<SKILL_DIR>/scripts/feishu_auth.py --check"
| 输出 | 含义 | Agent 动作 |
|---|---|---|
FEISHU_AUTH_OK:<姓名> |
已连上 | 「连好了，以后不开电脑也能发到飞书」 |
FEISHU_AUTH_PENDING |
还没扫完 / 服务器还在出码 | 「再等一小会儿」，稍后重查一次 |
FEISHU_AUTH_NO_WORKER |
等了一阵服务器仍没出码 | 「服务还在准备，我先帮你确认一下服务器状态」；不要让用户反复扫码 / 重新配对 |
FEISHU_AUTH_EXPIRED |
授权过期，或 10 分钟出码窗口已过 | 重新跑步骤 1，让用户再扫一次 |
FEISHU_AUTH_FAILED:<原因> |
失败 | 说明原因，重新跑步骤 1 |
FEISHU_AUTH_WAIT |
后端还没升级 | 告诉用户需要先生效服务端更新，其它功能照常用 |
NEED_LOGIN |
没登录态 | 让用户在小程序出 6 位配对码，先走「零、首次接入」 |
FEISHU_AUTH_NONE |
还没发起过 | 跑步骤 1 |
为什么是这样（给 Agent 看，不要转述给用户）
服务器上的飞书连接器原本只有「机器人」身份，没有「用户本人」身份：拿不到通讯录，也就无法把纪要里的姓名对应到飞书个人。用户电脑上扫码得到的本人令牌锁在 Windows 密钥库里，导不出来。因此改成：服务器自己出一次码 → WorkBuddy 展示 → 用户手机飞书扫 → 令牌直接落在服务器。
扫码后，服务器用这个「用户本人身份」做查询（contact +search-user 按姓名找 open_id、im +chat-list 拉我所在的群）；发送仍用机器人身份：用户身份缺 im:message.send_as_user 权限（该权限要在飞书开放平台开通并发布版本，OAuth 阶段申请不到），后端已做自动降级并记住，后续固定用 bot。结论：
- 私聊 ✅：按姓名搜到 open_id，机器人自动建单聊发送。
- 老群 ✅：机器人在群里就能发。
- 新建的群 ❌：机器人不在群里会报
230002，需把「莫贻敏的飞书 CLI」机器人加进该群。
令牌失效时小程序会提示「去 WorkBuddy 重新扫一次」。以上细节不要转述给用户，用户只需知道「扫一次码，之后不开电脑也能发」。
一、触发条件
- 接入类：用户发来 6 位数字 / 说「连接连接录音卡 / 绑定设备 / 接入会议纪要」→ 走「零、首次接入」。
- 使用类：用户说「总结会议纪要 / 合成周报 / 拉最近会议 / 把纪要发到 XX 群 / 提取待办 / 发一下待发的纪要」。
- 不应触发：只想看原始转写全文、或要求修改/删除后端内容时不进入推送流程。
二、核心流程
- 确认已有登录态：
python "<SKILL_DIR>/scripts/setup.py"（无--pair时只刷新令牌上报、能力与群列表）。 - 拉取会议与转写：
python "<SKILL_DIR>/scripts/fetch.py" --list，只处理transcriptStatus == "2"（已转写完成）的会议。 - 生成纪要：优先用后端
summary/summaryJson；为空时用transcriptText总结。忠于原文，不得编造。 - 合并（merge）：按时间区间或主题合并为周报/月报（见
references/templates.md）。 - 渲染模板：按
single/merge/todos选用模板，按通道裁剪长度（见references/limits.md）。 - 分发
- A. 自动发送（默认）：用户在小程序点「发送」→ 后端 Java 定时任务消费待发队列并直接发送，本技能不参与，用户也不需要再说一句话。
- B. 会话内直发（用户当面指定接收方时） →scripts/notify.py：
bash python "<SKILL_DIR>/scripts/notify.py" --platform feishu --chat-name "产品群" --content-file /tmp/minutes.md python "<SKILL_DIR>/scripts/notify.py" --platform feishu --user-name "莫贻敏" --content "..."
- 直发前必须向用户确认接收方与内容概要；自动发送用的是用户点发送时的快照，不再确认。 - 汇报：处理了 N 场、发给了谁、哪些失败及原因、哪些转写未完成被跳过。
三、接口与数据（详见 references/api.md）
- 登录：
POST /recording/web/auth/pair（配对码）、GET /recording/web/auth/qrcode、/poll（扫码） - 数据：
GET /recording/web/session/list、GET /recording/mini/audio/{fileId}/url - 能力/群：
POST /recording/web/capability/report、POST /recording/web/notify/feishu-chats/sync - 令牌上报：
POST /recording/web/user-token（setup.py 自动调用；兼容保留，Java 定时任务使用服务器本地飞书登录态，不依赖这份令牌） - 飞书用户授权：
POST /recording/web/feishu-auth/start、GET /recording/web/feishu-auth/status（feishu_auth.py调用；出码/完成授权由后端feishuAuthTask定时任务直接调 service 完成，不再走 HTTP 自调用）
四、分发渠道（详见 references/channels.md）
- 自动发送（后端定时任务，默认通道）：查询用用户本人身份（按姓名
contact +search-user找 open_id、im +chat-list拉群），发送用机器人身份（用户身份缺im:message.send_as_user，后端自动降级）。用户只需在 WorkBuddy 里扫一次飞书码，之后关机也能发；新群若没把机器人加进去会失败，小程序会给出人话提示。 - 会话内直发（本地连接器，用户当面指定时）：
- 飞书：
lark-cli，优先--as user以本人身份发；缺send_as_user权限时connector.py自动降级--as bot（私聊仍可发，群发要求机器人在群里）。 - 企业微信：
wecom-cli message aibot，只能发授权人本人 + 机器人最近有往来的会话；sessions=0时直接告诉用户发不了，不要重试。 - 钉钉：未接入，不要承诺。
- 长度限制：企微 markdown 硬上限 20480 UTF-8 字节，飞书以返回错误为准；超长按
references/limits.md截断并注明。
五、接入后 skill 还负责什么
| 动作 | 命令 | 说明 |
|---|---|---|
| 一键接入（登录+令牌上报+群同步） | python scripts/setup.py --pair <码> |
首次 / 登录失效时 |
| 连接飞书 / 重新扫码 | python scripts/feishu_auth.py（--check 查结果） |
二维码只在 WorkBuddy 展示，小程序不出现 |
| 刷新能力与群列表 | python scripts/capability.py |
每次 skill 启动 |
| 拉会议 / 生成纪要 / 周报 / 待办 | python scripts/fetch.py --list + 模板 |
用户会话内要求时 |
| 手工直发 | python scripts/notify.py ... |
用户明确指定接收方时 |
| ~~消费待发队列~~ | ~~scripts/watch.py~~ |
已由后端 Java 定时任务接管，skill 不要执行（脚本保留仅为兼容，勿调用） |
- 待发任务由小程序写入（
FEISHU_GROUP/FEISHU_USER），content是发送时的纪要快照，服务器按快照发送，不要重新生成。 - 回写状态：全成功
SENT，部分成功PARTIAL，全失败FAILED（附failReason）。
六、输出模板（详见 references/templates.md）
- 单场纪要、多场合并周报、待办清单三类 Markdown 模板。
七、安全边界
- 令牌不外泄：JWT 仅存
~/.config/meeting-minutes/token（权限 600），绝不明文出现在对话、推送内容或日志。 - 不持有三方凭证：没有 webhook、没有 app_secret；直发全部经连接器，以用户本人身份执行。
- 只发已完成会议：严格以
transcriptStatus == "2"过滤。 - 直发需确认：外发前让用户确认接收方与内容（自动发送按用户已点的快照，不再二次确认）。
- 不猜目标：群名/姓名多义时列候选让用户选；找不到就停下，宁可漏发不可误发。
- 不删不改：只读取并转发，不修改/删除后端数据。
- 失败可恢复：单条失败记录并继续，不在批量任务中中断；失败原因回写后端。
- 越权隔离：所有数据接口均用户态，只能读登录者本人绑定设备的会议。
八、后端依赖状态
- ✅
GET /recording/web/session/list（JWT 用户态会话查询） - ✅
POST /recording/web/auth/pair（配对码换 JWT） - ✅ 内部通知（站内信）：小程序「发送 → 内部通知」由后端直接落库，不经过本技能
- ✅
capability/report、feishu-chats/sync（已上线） - ✅
POST /recording/web/user-token（令牌上报，setup.py 自动调用） - ✅ 后端 Java 定时任务（Quartz）已接管待发队列消费、飞书授权轮询与群列表同步（2026-11-05 起）：skill 无需创建定时任务、无需本地常驻监听；Python worker 已下线
九、常见边界（避免承诺过度）
- 企微直发不了任意同事：能力边界是「授权人本人 + 机器人最近有消息往来的会话」。
sessions=0时直接说明。 - 飞书搜人靠姓名（该企业通讯录没有手机号字段）：录音里提炼的「陆总」「小萬」通常搜不到真名；匹配不上就保留未关联，让用户在小程序补选，不要硬发。
- 长纪要会截断：按通道上限裁剪并在末尾注明「完整纪要在小程序查看」。
- 自动发送不需要电脑开机：后端定时任务 7×24 消费；发送结果可在管理后台「发送管理 → 发送任务」查看，失败原因已统一为用户能看懂的中文。
- 登录过期时：小程序里重新出一次配对码即可，不需要重装。
十、（已废弃）本地常驻方案
旧版本通过 scripts/install_watch.py 注册计划任务、用 watch.py 常驻轮询消费队列 —— 该方案已废弃（发送已移到服务器）。不要引导用户安装；若用户机器上仍有旧的「会议纪要自动发送」定时任务或 watch 常驻进程，建议删除/停止，避免与服务器重复发送。
