84f7950589
- 完整的知识库框架（P0-P5 路线图） - 12篇治理文档 - 工具脚本（kb-init.sh, kb-lint-fm.py, feishu-sync.py, kb-bot） - 7个 Claude 命令 - 示例项目和测试项目（wanniu-l1） - 契约文件（meta/kb-contract.yaml） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
120 lines
7.4 KiB
Markdown
Executable File
120 lines
7.4 KiB
Markdown
Executable File
# 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 同步成飞书文档。
|
||
|
||
每步独立可验收，任一步卡住不影响已完成步骤。
|