company-kb/docs/08-飞书双向前端方案.md

08 · 飞书双向前端方案（群机器人 + 呈现）

把飞书从「单向导出源」升级为「双向前端」：采集入口 + 查询入口 + 呈现面。 状态：方案待批 | 底座已验证：lark-cli 已装(bot 身份 cli_a9458d254e3a5bc3)，鉴权可用。

关键技术验证结论（已实测）

能力	命令	状态
发消息	lark-cli im +messages-send --chat-id oc_xxx --markdown "..."	✅ bot 可用
回复(thread)	lark-cli im +messages-reply	✅
收群消息	lark-cli event +subscribe --event-types im.message.receive_v1 --compact	✅ WebSocket 长连接，无需公网回调
找群 chat_id	lark-cli im +chat-search --query "群名"	✅
多维表格	lark-cli api POST /open-apis/bitable/v1/apps/...（通用 api，CLI 1.0.3 无 bitable 子命令但通用 api 通鉴权）	✅
云文档	lark-doc-manager skill（已激活）/ lark-cli docs	✅

最大收获：能问能答走长连接而非公网 HTTP 回调——省掉 VPS 上常驻 web 服务，5 人团队负担骤降。

---

一、群机器人：能问能答

架构（长连接，无公网）

同事在飞书群 @机器人 "客户A为什么不用一口价"
   ↓ 飞书事件 (im.message.receive_v1)
lark-cli event +subscribe  ── WebSocket 长连接 ──> 本地/VPS 常驻进程
   ↓ NDJSON 每行一事件，--compact 提取文本
kb-bot 调度器：解析 → 剥离 @ → 得到问题
   ↓
调 CC 跑 /kb-ask（基于知识库检索，强制溯源，无据报 Gap）
   ↓
lark-cli im +messages-reply  ── 回复到原消息 thread

落地组件

• tools/kb-bot/subscribe.sh — 起长连接：lark-cli event +subscribe --event-types im.message.receive_v1 --compact --output-dir ./events/
• tools/kb-bot/handle.py — 消费事件：过滤 @机器人 的消息 → 抽问题 → 调 CC headless (claude -p "/kb-ask <问题>") → 取答案 → lark-cli im +messages-reply。
• 防重：event 有 idempotency，handle 记已处理 message_id。
• 铁律继承：答案强制带 source_link，无据回「知识库暂无，可 /kb-link 补充」，绝不编造。

部署（MVP）

• 跑在一台常开机器（你的 Mac mini / LA VPS 均可，长连接不挑落点）。
• MVP 用 shell + 轮询 events 目录起步；稳定后再包成 launchd/systemd 常驻。
• 不建公网服务、不开端口——这是刻意的反过度工程。

---

二、飞书呈现架构：三层投影

核心原则：飞书是「读屏」不是「数据库」。 真相源永远是 Git 仓库，飞书上所有内容都是从 Git 单向投影的镜像；同事在飞书上看/问，不在飞书上改知识（改走 Obsidian/Git）。飞书怎么动都不污染真相源。

三层对应同事三种消费姿势：

┌─────────────────────────────────────────────────────┐
│ 第3层 群机器人（问）  "客户A为什么不用一口价？"         │ 找答案·秒回
│   @机器人 → /kb-ask → 带溯源回复（实时，读 Git 真相源） │
├─────────────────────────────────────────────────────┤
│ 第2层 多维表格（查）  全库一张表，按项目/状态筛选/看板  │ 扫全局·俯瞰
│   每页一行：type/status/source/项目/source_link        │
├─────────────────────────────────────────────────────┤
│ 第1层 云文档（读）    项目概览、决策来龙去脉            │ 读故事·了解
│   projects/*/_index + 关键 decision → 飞书文档         │
└─────────────────────────────────────────────────────┘
      ↑ 三层都从同一 Git 仓库单向投影，飞书只读

为什么分三层：同事需求本就分三种——「了解一个项目」读云文档、「俯瞰筛选全局」用多维表格、「要一个具体答案」问机器人。一层满足不了三种姿势。

更新节奏（反过度工程）：MVP 第 1/2 层不做实时同步——录入后手动跑一次 feishu-render，或每天定时同步一次即可；第 3 层机器人是实时的（读 Git 真相源本身，不依赖投影）。

---

载体 A：云文档（第 1 层·叙事型呈现）

• 用途：项目概览、决策来龙去脉——适合「读故事」。
• 同步：projects/<代号>/_index.md + 关键 decision 页 → 飞书云文档。
• 工具：tools/feishu-render.py --docs <代号>，调 lark-doc-manager / lark-cli docs +create/+update。
• 频率：按需/手动触发（MVP 不做实时）。

载体 B：多维表格 Bitable（第 2 层·结构型呈现）

• 用途：全库总览——每条 decision/doc/conversation 一行，带 type/status/source/created/项目/source_link 字段，同事可筛选/分组/看板/仪表盘。这是「呈现全库」的主力。
• 同步：扫 projects/**/*.md frontmatter → 每页一条记录 → 通用 api 写入 Bitable。
• 工具：tools/feishu-render.py --bitable，用 lark-cli api POST /open-apis/bitable/v1/apps/{app}/tables/{table}/records。
• 字段严格对齐 meta/kb-contract.yaml（type/status enum 一致）。
• 频率：录入后增量 upsert（按 source_link 或页路径做唯一键）。

Wiki 空间暂不做（用户判断现阶段不适合）。

---

三、对既有架构的影响（需回改的文档）

1. docs/04-架构.md L4 呈现层：飞书从「只读呈现」补充为「双向」——采集(群机器人收/kb-link)、查询(群@问答)、呈现(云文档+Bitable)。写路径仍唯一(Obsidian/Git)，机器人问答不写库、只读。
2. docs/04-架构.md §4 双前端映射表：飞书行的「写」列注明——群机器人问答是读操作(调/kb-ask)，不构成第二条写路径。
3. docs/05-路线图.md：群机器人 + 呈现属 P2（原 P2 只有 feishu-pull，现扩为完整双向）。
4. docs/07-AI-native工作流.md：新增「循环 E · 飞书问答」——群 @ → /kb-ask → 回复，人机分工同查询循环。
5. 命令面：无新 /kb 命令（机器人内部调 /kb-ask），但新增 tools/kb-bot/ 与 tools/feishu-render.py。

---

四、安全与凭据

• lark-cli 凭据由其自身管理（非本仓环境变量），不入库。
• 机器人问答只读知识库，不执行写/删——继承「AI 永不擅自有损操作」铁律。
• 群机器人回答带 source_link，同事可核。
• 长连接进程日志不含敏感 token（--quiet 抑制 stderr）。

---

五、分步实施顺序（建议）

1. P2-a 发消息打通：kb-bot 先做「只发」——手动触发把一条测试答案发到群，验证 chat-id/markdown 渲染。
2. P2-b 收消息打通：起 event +subscribe，@机器人能在 events/ 看到事件。
3. P2-c 闭环：handle.py 串起「收→/kb-ask→回复」，群里问答跑通。
4. P2-d 呈现-Bitable：建一张多维表，把 _example 项目的页同步成记录。
5. P2-e 呈现-云文档：把 _example 的 _index 同步成飞书文档。

每步独立可验收，任一步卡住不影响已完成步骤。