daec6a376d
- tools/kb-bridge.py: 原始物料→知识页核心脚本（384行完整实现） 功能：读取PDF/CSV/markdown → Claude API分析 → 生成frontmatter → 保存到projects/ - 完整落地链路.md: 端到端实施方案（Phase 0-3完整路径） - 完整项目现状报告.md: 真实状态验证（脚本真相+架构梳理） - docs/bot-comparison-analysis.md: kb-bot vs bot-v2 深度对比 - docs/kb-bot-usage-guide.md: kb-bot 使用指南 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
# 飞书机器人对比分析报告
|
||
|
||
> 深度验证：kb-bot vs bot-v2 的真实状态、功能对比、配合方案
|
||
> 验证时间：2026-07-16
|
||
> 验证方式：逐行读代码 + 对话记录提取 + 依赖检查
|
||
|
||
---
|
||
|
||
## 一、核心结论（先说结论）
|
||
|
||
### kb-bot（知识库里的Python版）
|
||
|
||
**状态判定**：✅ **代码 100% 完整实现，理论上可运行，但未实际部署验证过**
|
||
|
||
**我之前的判断错误**：
|
||
- 最初我说它是"空壳/骨架" —— **这是错的，向你认错**
|
||
- 错误原因：当时只看了文件大小没读内容，草率判断
|
||
- 实际情况：三个文件（subscribe.sh、handle.py、send.sh）都是**完整实现**，逻辑清晰，依赖齐全
|
||
|
||
**核心逻辑**（已验证）：
|
||
```
|
||
1. subscribe.sh 起 WebSocket 长连接
|
||
→ lark-cli event +subscribe 监听飞书群消息
|
||
→ 事件落到 events/xxx.json
|
||
|
||
2. handle.py 轮询 events/
|
||
→ 解析 JSON 提取问题
|
||
→ 调用: subprocess.run(["claude", "-p", "/kb-ask 问题"], cwd=知识库根)
|
||
→ 调用: lark-cli im +messages-reply 回复到群
|
||
|
||
3. .seen-msg-ids 去重机制
|
||
```
|
||
|
||
**依赖验证**（✓ 全部齐全）：
|
||
- Python 3.12.8 ✓
|
||
- lark-cli 1.0.69 ✓（你本地已装）
|
||
- claude CLI ✓（你本地已装）
|
||
- /kb-ask 命令 ✓（.claude/commands/kb-ask.md 存在）
|
||
|
||
**未验证的风险点**：
|
||
- `claude -p "/kb-ask xxx"` headless 模式能否正确工作（需实测）
|
||
- 是否真的能在群里触发并回复（需实测）
|
||
|
||
### bot-v2（阿里云 ECS 的 Node.js 版）
|
||
|
||
**状态判定**：✅ **已上线运行，生产环境主力机器人**
|
||
|
||
**位置**：阿里云 ECS `47.110.48.113:/opt/bot-v2`
|
||
|
||
**技术栈**：Node.js + lark-cli + SQLite
|
||
|
||
**核心逻辑**（从对话记录提取）：
|
||
```
|
||
1. lark-cli event +subscribe 起长连接
|
||
→ 消息进入 router.js 路由判断意图
|
||
|
||
2. 根据意图分发到不同 handler:
|
||
- "整理" → chat-history.js 拉历史+AI分析
|
||
- "存一下" → save-knowledge.sh 存多维表格
|
||
- 其他 → 快速问答（调 Claude API）
|
||
|
||
3. SQLite 数据库存储:
|
||
- conversations 表：上下文记忆
|
||
- task_queue 表：异步任务队列
|
||
```
|
||
|
||
**9大功能**（对话记录提到的）：
|
||
1. 快速问答（Claude API）
|
||
2. 整理聊天历史（拉取+分析+摘要）
|
||
3. 存知识库（推送到飞书多维表格）
|
||
4. 生图（Gemini API）
|
||
5. RAG 检索（SQLite + 知识库）
|
||
6. 会议纪要自动生成
|
||
7. 任务队列异步处理
|
||
8. 上下文记忆
|
||
9. 多群白名单配置
|
||
|
||
**已验证**：你的截图显示它在群里成功回复了（拉到了135条消息）
|
||
|
||
---
|
||
|
||
## 二、详细对比
|
||
|
||
| 维度 | kb-bot（知识库Python版） | bot-v2（阿里云Node.js版） |
|
||
|------|------------------------|-------------------------|
|
||
| **部署位置** | 未部署（代码在知识库 tools/kb-bot/） | 已部署（阿里云 ECS /opt/bot-v2） |
|
||
| **技术栈** | Python 3 + lark-cli + Claude Code CLI | Node.js + lark-cli + SQLite |
|
||
| **核心能力** | 单一：查知识库问答 | 9大功能（问答+整理+存储+生图+...） |
|
||
| **问答方式** | Claude Code headless (`claude -p "/kb-ask"`) | Claude API 直接调用 |
|
||
| **上下文记忆** | 无 | SQLite conversations 表 |
|
||
| **任务队列** | 无 | SQLite task_queue 表 |
|
||
| **聊天历史** | 不处理 | chat-history.js 拉取+分析 |
|
||
| **知识库整合** | ✅ 深度整合（直接查 projects/） | ✅ 也整合（但通过多维表格） |
|
||
| **代码量** | ~200行（3个文件） | ~数千行（多文件模块化） |
|
||
| **运行状态** | 未实测 | ✅ 生产运行中 |
|
||
| **可靠性** | 未知（未部署验证） | ✅ 已验证（你的截图） |
|
||
| **维护性** | 简单，代码少 | 复杂，功能多 |
|
||
|
||
---
|
||
|
||
## 三、功能对比详表
|
||
|
||
### kb-bot 的功能（1个）
|
||
|
||
| 功能 | 实现方式 | 验证状态 |
|
||
|------|---------|---------|
|
||
| 查知识库问答 | `claude -p "/kb-ask 问题"` → 读 projects/ → 溯源回答 | ✅ 代码完整，未实测 |
|
||
|
||
### bot-v2 的功能（9个）
|
||
|
||
| 功能 | 实现方式 | 验证状态 |
|
||
|------|---------|---------|
|
||
| 1. 快速问答 | Claude API | ✅ 截图证明能跑 |
|
||
| 2. 整理聊天历史 | lark-api.js fetchMessages() + AI分析 | ✅ 截图显示拉到135条消息 |
|
||
| 3. 存知识库 | 推送到飞书多维表格 | ✅ 对话记录提到 |
|
||
| 4. 生图 | Gemini API | 对话记录提到 |
|
||
| 5. RAG 检索 | SQLite + embedding | 对话记录提到 |
|
||
| 6. 会议纪要 | 自动生成 | 对话记录提到 |
|
||
| 7. 任务队列 | SQLite + node-cron | 对话记录提到 |
|
||
| 8. 上下文记忆 | SQLite conversations 表 | 对话记录提到 |
|
||
| 9. 多群白名单 | config/bot-config.json | 对话记录提到 |
|
||
|
||
---
|
||
|
||
## 四、实现逻辑对比
|
||
|
||
### kb-bot 的实现链路
|
||
|
||
```
|
||
群里 @机器人 "万牛会L1怎么安排的？"
|
||
↓
|
||
subscribe.sh（WebSocket长连接）
|
||
↓
|
||
events/msg-12345.json
|
||
↓
|
||
handle.py 轮询到新消息
|
||
↓
|
||
extract() 解析 → 问题："万牛会L1怎么安排的？"
|
||
↓
|
||
ask_kb():
|
||
subprocess.run([
|
||
"claude", "-p",
|
||
"/kb-ask 万牛会L1怎么安排的？"
|
||
], cwd=知识库根目录)
|
||
↓
|
||
Claude Code headless 模式：
|
||
1. cd 到知识库根
|
||
2. 读 .claude/commands/kb-ask.md
|
||
3. 执行命令逻辑：
|
||
- 扫描 projects/ 找相关页
|
||
- 读 frontmatter 筛选
|
||
- 语义检索内容
|
||
- 综合回答 + 挂 source_link
|
||
↓
|
||
返回答案："根据 [[课程大纲v1]]..."
|
||
↓
|
||
reply():
|
||
lark-cli im +messages-reply
|
||
--message-id xxx
|
||
--markdown "答案"
|
||
--as bot
|
||
↓
|
||
答案回到群里
|
||
```
|
||
|
||
### bot-v2 的实现链路（以"整理聊天"为例）
|
||
|
||
```
|
||
群里 @机器人 "整理一下最近3天的讨论"
|
||
↓
|
||
lark-cli event +subscribe（长连接）
|
||
↓
|
||
router.js 判断意图：
|
||
if (msg.includes("整理")) → chatHistoryHandler
|
||
↓
|
||
chat-history.js:
|
||
1. lark-api.fetchMessages(chatId, 3天)
|
||
→ 调飞书API拉历史消息
|
||
→ 拉到135条消息（你的截图）
|
||
2. 解析 content 字段（JSON → text）
|
||
3. 分类：文本/图片/文件/富文本/系统消息
|
||
4. 调 Claude API 分析：
|
||
"这135条消息的核心主题是什么？
|
||
关键决策有哪些？
|
||
待办事项是什么？"
|
||
5. 生成结构化摘要
|
||
↓
|
||
reply():
|
||
lark-cli im +messages-reply --markdown "摘要"
|
||
↓
|
||
存入 SQLite conversations 表（上下文记忆）
|
||
↓
|
||
答案回到群里
|
||
```
|
||
|
||
---
|
||
|
||
## 五、能否配合？配合方案
|
||
|
||
### 场景 1：知识库专属问答（kb-bot）
|
||
|
||
**定位**：轻量、专注、深度整合知识库
|
||
|
||
**优势**：
|
||
- 直接读 projects/ 目录，不经过中间层
|
||
- 溯源铁律（source_link 强制挂）
|
||
- 代码简单，易维护
|
||
|
||
**适用场景**：
|
||
- 公司内部知识库问答
|
||
- 需要严格溯源的场景
|
||
- 不需要聊天历史、任务队列等复杂功能
|
||
|
||
**部署方案**：
|
||
- 可以部署在 NAS 上（常驻运行）
|
||
- 也可以和 bot-v2 部署在同一台 ECS（不冲突）
|
||
- 用不同的机器人账号（一个叫"知识库助手"，一个叫"全能助手"）
|
||
|
||
### 场景 2：全能助手（bot-v2）
|
||
|
||
**定位**：重量级、多功能、生产主力
|
||
|
||
**优势**：
|
||
- 9大功能，覆盖日常协作
|
||
- 任务队列异步处理
|
||
- 上下文记忆
|
||
- 已在生产验证
|
||
|
||
**适用场景**：
|
||
- 日常群聊协作
|
||
- 需要整理聊天、生图、会议纪要等
|
||
- 多群管理
|
||
|
||
**现状**：已部署在阿里云，正常运行
|
||
|
||
### 配合方案 A：双机器人协作（推荐）
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 飞书群（公司知识交流群） │
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ @知识库助手 万牛会L1怎么安排的？ │
|
||
│ ↓ │
|
||
│ kb-bot（NAS）→ 查知识库 → 溯源回答 │
|
||
│ │
|
||
│ @全能助手 整理一下最近3天的讨论 │
|
||
│ ↓ │
|
||
│ bot-v2（ECS）→ 拉历史 → 分析摘要 │
|
||
│ │
|
||
│ @全能助手 帮我生成会议纪要 │
|
||
│ ↓ │
|
||
│ bot-v2 → 任务队列 → 生成 → 推送 │
|
||
│ │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**优点**：
|
||
- 各司其职，不互相干扰
|
||
- kb-bot 专注知识库（深度整合 projects/）
|
||
- bot-v2 覆盖其他协作场景
|
||
|
||
**缺点**：
|
||
- 两个机器人要维护（但 kb-bot 代码简单）
|
||
- 用户要记住@哪个
|
||
|
||
### 配合方案 B：bot-v2 整合 kb-bot 逻辑
|
||
|
||
把 kb-bot 的 `/kb-ask` 逻辑整合到 bot-v2 的 router.js：
|
||
|
||
```javascript
|
||
// bot-v2/router.js 新增
|
||
if (msg.intent === 'query_kb') {
|
||
// 调用 kb-bot 的 ask_kb 逻辑
|
||
const answer = await execClaude([
|
||
'claude', '-p', `/kb-ask ${question}`
|
||
], { cwd: KB_ROOT });
|
||
return answer;
|
||
}
|
||
```
|
||
|
||
**优点**：
|
||
- 只维护一个机器人
|
||
- 用户无需区分
|
||
|
||
**缺点**：
|
||
- bot-v2 要依赖知识库目录（耦合）
|
||
- Claude Code CLI 要在 ECS 上装
|
||
|
||
### 配合方案 C：各管各的（现状）
|
||
|
||
**bot-v2（ECS）**：管日常协作、生图、整理、会议纪要
|
||
|
||
**kb-bot（未部署）**：暂不部署，知识库问答通过 `/kb-ask` 命令手动在 Claude Code 里查
|
||
|
||
**优点**：最简单，不增加维护负担
|
||
|
||
**缺点**：知识库问答不能在群里自动触发
|
||
|
||
---
|
||
|
||
## 六、在知识库框架里的实现方案
|
||
|
||
### 方案 1：kb-bot 部署到 NAS（推荐）
|
||
|
||
**步骤**：
|
||
1. 把 `tools/kb-bot/` 复制到 NAS：`/volume1/scripts/kb-bot/`
|
||
2. 配置 systemd 服务（或 DSM 任务计划）：
|
||
```bash
|
||
# subscribe 长连接
|
||
nohup bash /volume1/scripts/kb-bot/subscribe.sh &
|
||
|
||
# handle 消费者
|
||
nohup python3 /volume1/scripts/kb-bot/handle.py --watch &
|
||
```
|
||
3. 在飞书创建第二个机器人账号："知识库助手"
|
||
4. 配置 lark-cli 认证（bot 身份）
|
||
5. 测试：群里 @知识库助手 提问
|
||
|
||
**优点**：
|
||
- NAS 上常驻，和知识库 Git 仓库在一起
|
||
- 不影响 bot-v2
|
||
|
||
### 方案 2：kb-bot 也部署到 ECS（和 bot-v2 共存）
|
||
|
||
**步骤**：
|
||
1. SSH 到 ECS
|
||
2. 在 `/opt/kb-bot/` 部署
|
||
3. 配置 systemd 服务
|
||
4. 用不同端口/不同机器人账号
|
||
|
||
**优点**：
|
||
- ECS 更稳定（NAS 可能重启）
|
||
|
||
**缺点**：
|
||
- kb-bot 要能访问知识库（需要 Git clone 到 ECS）
|
||
|
||
### 方案 3：不部署 kb-bot，bot-v2 加一个"查知识库"功能
|
||
|
||
在 bot-v2 里新增一个 handler：
|
||
|
||
```javascript
|
||
// bot-v2/handlers/kb-query.js
|
||
async function handleKBQuery(question) {
|
||
// 选项A：调 Claude Code CLI
|
||
const answer = await exec(`claude -p "/kb-ask ${question}"`, {
|
||
cwd: '/opt/company-kb'
|
||
});
|
||
|
||
// 选项B：用 Claude API + 直接读 projects/
|
||
const kbFiles = await readDir('/opt/company-kb/projects');
|
||
const relevant = await searchRelevant(kbFiles, question);
|
||
const answer = await claudeAPI(relevant);
|
||
|
||
return answer;
|
||
}
|
||
```
|
||
|
||
**优点**：
|
||
- 只维护一个机器人
|
||
- 功能集中
|
||
|
||
**缺点**：
|
||
- bot-v2 要依赖知识库
|
||
- 增加复杂度
|
||
|
||
---
|
||
|
||
## 七、最终建议
|
||
|
||
### 立刻可以做的（0成本验证）
|
||
|
||
1. **测试 kb-bot 能否真跑**：
|
||
```bash
|
||
cd ~/work/company-kb/tools/kb-bot/
|
||
|
||
# 测试 subscribe（前台跑，看能否收到消息）
|
||
bash subscribe.sh
|
||
|
||
# 另开终端，去群里 @机器人 说句话
|
||
# 看 events/ 是否生成 JSON 文件
|
||
|
||
# 测试 handle（处理一条消息）
|
||
python3 handle.py
|
||
```
|
||
|
||
2. **如果能跑通** → 部署到 NAS（方案1）
|
||
|
||
3. **如果跑不通** → 记录错误，修bug（我帮你）
|
||
|
||
### 中期方案（1-2天）
|
||
|
||
- **双机器人并行**（方案 A）：
|
||
- kb-bot 专注知识库问答（深度整合）
|
||
- bot-v2 覆盖其他协作场景
|
||
- 各司其职，不冲突
|
||
|
||
### 长期方案（可选）
|
||
|
||
- bot-v2 整合 kb-bot 的核心逻辑（方案 B）
|
||
- 或者继续分离，但 kb-bot 加上下文记忆、任务队列等能力（进化成 kb-bot-v2）
|
||
|
||
---
|
||
|
||
## 八、风险点与注意事项
|
||
|
||
### kb-bot 的风险
|
||
|
||
1. **未实测**：代码写得很完整，但没有实际部署验证过
|
||
2. **headless 模式不确定**：`claude -p "/kb-ask xxx"` 能否在无交互环境下正确工作（需实测）
|
||
3. **错误处理**：代码里有 try-except，但边界情况可能不全
|
||
|
||
### bot-v2 的风险
|
||
|
||
1. **代码分散在 ECS**：本地没备份，如果 ECS 挂了数据可能丢
|
||
2. **复杂度高**：9大功能，维护成本高
|
||
3. **文档缺失**：对话记录里只有部分代码，完整文档不全
|
||
|
||
### 配合的风险
|
||
|
||
1. **双机器人混淆**：用户可能不知道该@哪个
|
||
2. **维护成本**：两套代码要同时维护
|
||
3. **功能重复**：两个机器人都能问答，但实现不同
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
### kb-bot 真实状态
|
||
|
||
✅ **代码 100% 完整，逻辑清晰，依赖齐全，理论上可运行**
|
||
❓ **但未实际部署验证，存在不确定性**
|
||
|
||
**我之前说它是"空壳"是错的，向你认错。**
|
||
|
||
### bot-v2 真实状态
|
||
|
||
✅ **已上线，生产运行，功能强大，你的截图证明它能跑**
|
||
|
||
### 两者关系
|
||
|
||
- **不是一个东西**：技术栈不同、功能不同、定位不同
|
||
- **可以并存**：双机器人各司其职
|
||
- **也可以合并**：bot-v2 整合 kb-bot 逻辑
|
||
|
||
### 下一步
|
||
|
||
**建议：先测 kb-bot 能否跑**（0成本验证），跑通了再决定部署方案。
|
||
|
||
---
|
||
|
||
**验证人**: Claude (Opus 4.8)
|
||
**验证方式**: 逐行读代码 + 依赖检查 + 对话记录提取 + 逻辑推导
|
||
**置信度**: 95%（代码逻辑确认，但未实测运行）
|