AI 工作 SOP 配置指南

1飞书应用与权限

在飞书开放平台创建企业自建应用，开启以下权限：

im:message.p2p_msg:readonly / im:message.group_at_msg:readonly
im:message:send_as_bot
im:resource（下载群聊文件）
im:chat:readonly（列出 Bot 所在群，用于 list_feishu_chats.py）
bitable:app（多维表格读写，可选）

Bot 推荐使用长连接模式（无需公网 Webhook）：

python scripts/feishu_echo_bot.py

2Bitable 任务台账建表

新建多维表格「AI 任务台账」，列名必须与下表完全一致：

列名	类型	说明
任务ID	文本	唯一标识
触发来源	单选	群聊文件 / 群聊消息 / 表单提交 / 定时任务
状态	单选	待处理 / 处理中 / 完成 / 失败
用户	文本	提交人 open_id
文件名	文本	可选
任务类型	单选	excel_workflow / text_summary / daily_stats
摘要	多行文本	AI 摘要
标签	多选	如 Excel、财务、自动
耗时ms	数字	处理耗时毫秒
会话ID	文本	工作流 session
结果链接	超链接	大屏/结果页
标题	文本	任务标题
错误信息	多行文本	失败原因
创建时间	日期	毫秒时间戳
完成时间	日期	毫秒时间戳
群聊ID	文本	来源群 chat_id，供 Bitable 自动化回源发消息

从 URL 获取 token：https://xxx.feishu.cn/base/AppToken?table=TableId

3环境变量

FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_WEBHOOK_ENABLED=false   # 长连接 Bot 时必须 false
FEISHU_BITABLE_APP_TOKEN=
FEISHU_BITABLE_TABLE_ID=
FEISHU_NOTIFY_CHAT_ID=        # 团队通知群 chat_id（Bitable 自动化兜底目标群）
FEISHU_CHAT_ENABLED=true      # 群聊默认 AI 问答（非 SOP 指令时不写 Bitable）
# FEISHU_SOP_TEXT_PREFIXES=摘要,/sop
PUBLIC_APP_URL=http://localhost:8000
# FEISHU_GROUP_RESULT_URL=   # 群聊摘要卡片跳转页，默认 /static/sop-dashboard.html
SOP_SCHEDULER_ENABLED=true
SOP_CRON_DAILY_STATS=0 9 * * 1-5

如何获取 FEISHU_NOTIFY_CHAT_ID：

在目标通知群里 @Bot 发送「群id」，Bot 会回复本群 oc_xxx
或运行 python scripts/list_feishu_chats.py 列出 Bot 已加入的群（需 im:chat:readonly）
或 @Bot 发「摘要 xxx」触发 SOP 后，在 Bitable「群聊ID」列查看

4兜底群 vs 来源群

FEISHU_NOTIFY_CHAT_ID 不是「Bot 只能在一个群里用」，而是兜底通知群的固定地址。项目里有两套 chat_id 逻辑：

场景	用哪个 chat_id	要不要改 .env
在任意群 @Bot 发 Excel / SOP 指令	该群自己的 `oc_xxx`（自动）	不用
Web 表单提交	`FEISHU_NOTIFY_CHAT_ID`	只在换默认通知群时改
工作日定时统计	`FEISHU_NOTIFY_CHAT_ID`	同上
Bitable 自动化（规则 1/2）	优先台账「群聊ID」列，为空才用兜底群	同上

配置后能体验：

群聊触发（不依赖兜底 ID）：@Bot 发 .xlsx → Excel SOP；发「摘要 xxx」或「/sop xxx」→ 文本摘要 SOP 并写 Bitable；直接提问 → AI 文本回答（不写表）。摘要卡片可点击打开团队仪表盘（默认 /static/sop-dashboard.html，可用 FEISHU_GROUP_RESULT_URL 自定义）
表单 / 定时：完成卡片与统计摘要发到 FEISHU_NOTIFY_CHAT_ID 对应群

新建群怎么办？

每个群的 oc_xxx 在群存在期间一般不变，不是每次 @Bot 都会变
日常开新群：拉 Bot 进群即可，通知自动回新群，通常不用改 .env
只有更换「团队通知 / 运维群」或旧兜底群解散时，才需更新 FEISHU_NOTIFY_CHAT_ID
在新群确认 ID：@Bot 发送「群id」

推荐用法：兜底 ID 设一个长期不变的运维群（收表单、定时统计）；业务协作群随意新建，各群各自回源。

Bitable 是任务台账，不是群聊监听器，不保存聊天原文。详见 docs/feishu-sop-bitable-write.md 中「Bitable 不是群聊监听器」一节。

5Bitable 内置仪表盘

在多维表格中新建「仪表盘」视图，添加以下图表：

任务趋势：折线图，X=创建时间（按日），Y=记录数
成功率：饼图，维度=状态，筛选完成+失败
耗时分析：柱状图，X=触发来源，Y=耗时ms（平均值）
标签分布：柱状图，X=标签，Y=记录数

详细步骤见 docs/feishu-sop-bitable-dashboard.md

6四种触发方式联调

群聊文件：在飞书群 @Bot 发送 .xlsx
群聊 SOP 文本：@Bot 发送「摘要 xxx」或「/sop xxx」→ 文本摘要 SOP，并触发 Bitable 自动化
群聊 AI 问答：@Bot 直接提问（如「什么是 SOP」）→ 通义 LLM 文本回复，不写 Bitable
表单提交：打开 sop-form.html 或 POST /api/sop/tasks
定时任务：uvicorn 启动后自动注册 cron；手动调试 POST /api/sop/tasks/daily-stats

以上四种方式均会写入 Bitable 台账，详见 docs/feishu-sop-bitable-write.md。

7扩展新 AI 任务类型

在 app/sop/processors/ 新增 Processor 类，注册到 orchestrator._PROCESSORS，并在 Bitable「任务类型」单选中添加选项。详见 docs/feishu-sop-template.md。

8Bitable 内置自动化

在多维表格「自动化」中配置两条规则，实现记录变更 → 发消息与群消息触发 → 受理通知：

规则 1：新增记录且状态=待处理 → 发送消息（目标群优先用「群聊ID」列）
规则 2：状态变更为完成/失败 → 发送结果摘要与链接

详细步骤、消息模板与联调方法见 docs/feishu-sop-bitable-automation.md