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>
468 lines
14 KiB
Markdown
468 lines
14 KiB
Markdown
# kb-bot 完整使用指南（从零到运行）
|
||
|
||
> 解决："在哪里、怎么用、机器人在哪"的所有困惑
|
||
> 更新时间：2026-07-16
|
||
|
||
---
|
||
|
||
## 问题：你现在卡在哪里？
|
||
|
||
截图显示：
|
||
```bash
|
||
cd ~/work/company-kb/tools/kb-bot/
|
||
cd: no such file or directory: /Users/qiyu/work/company-kb/tools/kb-bot/
|
||
```
|
||
|
||
**原因**：你本地没有 `~/work/company-kb/` 这个目录。
|
||
|
||
**真相**：知识库实际在这里：
|
||
```
|
||
/Users/qiyu/Library/CloudStorage/SynologyDrive-zhishiku/知识库投递区/公司资产信息/company-kb-v0.1-mvp-20260707
|
||
```
|
||
|
||
---
|
||
|
||
## 完整链路：从代码到运行（5个关键位置）
|
||
|
||
```
|
||
位置1：知识库代码（你有）
|
||
/Users/qiyu/Library/.../company-kb-v0.1-mvp-20260707/
|
||
└── tools/kb-bot/ ← kb-bot 的代码在这里
|
||
├── subscribe.sh
|
||
├── handle.py
|
||
└── send.sh
|
||
|
||
位置2：飞书机器人账号（需要创建）
|
||
→ 飞书开放平台创建 Bot 应用
|
||
→ 获得 App ID 和 App Secret
|
||
→ 加入到群里
|
||
|
||
位置3：本地 lark-cli 认证（需要配置）
|
||
→ 运行 lark-cli auth login
|
||
→ 用 Bot 身份登录
|
||
|
||
位置4：运行环境（选一个）
|
||
选项A：你的 Mac 本地运行
|
||
选项B：NAS 上运行
|
||
选项C：阿里云 ECS 运行
|
||
|
||
位置5：飞书群（你有）
|
||
→ @机器人 提问
|
||
→ 机器人自动回复
|
||
```
|
||
|
||
---
|
||
|
||
## 第一步：环境检查（确认依赖都齐）
|
||
|
||
### 1.1 检查 lark-cli
|
||
|
||
```bash
|
||
# 检查是否安装
|
||
lark-cli --version
|
||
|
||
# 如果没装，安装
|
||
npm install -g @larksuiteoapi/lark-cli
|
||
|
||
# 检查认证状态
|
||
lark-cli auth status
|
||
```
|
||
|
||
**预期输出**：显示当前登录的身份（用户或 bot）
|
||
|
||
### 1.2 检查 claude CLI
|
||
|
||
```bash
|
||
# 检查是否安装
|
||
claude --version
|
||
|
||
# 如果没装，安装
|
||
npm install -g @anthropic-ai/claude-cli
|
||
|
||
# 检查能否运行
|
||
claude --help
|
||
```
|
||
|
||
### 1.3 检查 Python 3
|
||
|
||
```bash
|
||
python3 --version
|
||
# 预期：Python 3.12+
|
||
```
|
||
|
||
**如果三个都 OK，继续下一步。**
|
||
|
||
---
|
||
|
||
## 第二步：创建飞书机器人（如果还没有）
|
||
|
||
### 2.1 飞书开放平台创建应用
|
||
|
||
1. 打开：https://open.feishu.cn/app
|
||
2. 点"创建企业自建应用"
|
||
3. 填写：
|
||
- 应用名称：`知识库助手`
|
||
- 应用描述：`查询公司知识库`
|
||
- 应用图标：随便传一个
|
||
4. 创建完成，记下：
|
||
- **App ID**
|
||
- **App Secret**
|
||
|
||
### 2.2 配置机器人权限
|
||
|
||
在应用管理页面：
|
||
1. **权限管理** → 添加权限：
|
||
- `im:message`（接收消息）
|
||
- `im:message:send_as_bot`（发送消息）
|
||
- `im:chat`（获取群信息）
|
||
2. **事件订阅** → 添加事件：
|
||
- `im.message.receive_v1`（接收消息）
|
||
3. **机器人** → 启用机器人
|
||
|
||
### 2.3 把机器人加入测试群
|
||
|
||
1. 飞书客户端，找到你的测试群
|
||
2. 群设置 → 群机器人 → 添加机器人
|
||
3. 搜索"知识库助手"，加入
|
||
|
||
---
|
||
|
||
## 第三步：配置 lark-cli 认证（关键）
|
||
|
||
### 3.1 用 Bot 身份登录
|
||
|
||
```bash
|
||
# 清除旧的认证
|
||
lark-cli auth logout
|
||
|
||
# 用 Bot 身份登录
|
||
lark-cli auth login --type bot
|
||
|
||
# 会提示输入 App ID 和 App Secret
|
||
# → 输入第二步创建的那两个值
|
||
```
|
||
|
||
### 3.2 验证认证
|
||
|
||
```bash
|
||
lark-cli auth status
|
||
|
||
# 预期输出：
|
||
# ✓ Logged in as bot (app_id: cli_xxxx)
|
||
```
|
||
|
||
**如果这步没通过，后面全都跑不起来。**
|
||
|
||
---
|
||
|
||
## 第四步：测试 kb-bot（本地运行）
|
||
|
||
### 4.1 进入 kb-bot 目录（正确路径）
|
||
|
||
```bash
|
||
# 用实际路径（不是 ~/work/company-kb/）
|
||
cd "/Users/qiyu/Library/CloudStorage/SynologyDrive-zhishiku/知识库投递区/公司资产信息/company-kb-v0.1-mvp-20260707/tools/kb-bot"
|
||
|
||
# 或者设个快捷变量
|
||
KB="/Users/qiyu/Library/CloudStorage/SynologyDrive-zhishiku/知识库投递区/公司资产信息/company-kb-v0.1-mvp-20260707"
|
||
cd "$KB/tools/kb-bot"
|
||
```
|
||
|
||
### 4.2 测试 subscribe.sh（收消息）
|
||
|
||
```bash
|
||
# 前台运行，看输出
|
||
bash subscribe.sh
|
||
|
||
# 预期输出：
|
||
# [kb-bot] 订阅飞书群消息事件 → /path/to/events
|
||
# [kb-bot] 只收 im.message.receive_v1；Ctrl-C 停止。
|
||
# （长连接建立，等待消息...）
|
||
```
|
||
|
||
**现在去飞书群里 @知识库助手 说句话**，比如：
|
||
```
|
||
@知识库助手 你好
|
||
```
|
||
|
||
**回到终端，应该看到**：
|
||
```
|
||
[lark-cli] 收到消息: events/msg-xxx.json
|
||
```
|
||
|
||
**检查 events/ 目录**：
|
||
```bash
|
||
ls events/
|
||
# 应该有一个 msg-xxx.json 文件
|
||
```
|
||
|
||
**如果能收到消息，说明 subscribe.sh 正常。按 Ctrl-C 停止。**
|
||
|
||
### 4.3 测试 handle.py（处理消息）
|
||
|
||
```bash
|
||
# 单次处理（不常驻）
|
||
python3 handle.py
|
||
|
||
# 预期：
|
||
# - 读 events/ 里的消息
|
||
# - 调 claude -p "/kb-ask 你好"
|
||
# - 用 lark-cli 回复到群
|
||
|
||
# 如果成功，群里会看到机器人回复
|
||
```
|
||
|
||
**如果群里机器人回复了，说明 handle.py 正常。**
|
||
|
||
### 4.4 常驻运行（测试通过后）
|
||
|
||
```bash
|
||
# 开两个终端
|
||
|
||
# 终端1：起 subscribe（收消息）
|
||
cd "$KB/tools/kb-bot"
|
||
nohup bash subscribe.sh > /tmp/kb-bot-sub.log 2>&1 &
|
||
|
||
# 终端2：起 handle（处理消息）
|
||
cd "$KB/tools/kb-bot"
|
||
nohup python3 handle.py --watch > /tmp/kb-bot-handle.log 2>&1 &
|
||
|
||
# 查看进程
|
||
ps aux | grep -E "subscribe|handle" | grep -v grep
|
||
|
||
# 查看日志
|
||
tail -f /tmp/kb-bot-sub.log
|
||
tail -f /tmp/kb-bot-handle.log
|
||
```
|
||
|
||
**现在去群里 @机器人 提问，应该自动回复。**
|
||
|
||
---
|
||
|
||
## 第五步：部署到 NAS（如果本地测试通过）
|
||
|
||
### 5.1 把代码复制到 NAS
|
||
|
||
```bash
|
||
# SSH 登录 NAS
|
||
ssh 你的用户名@192.168.0.101
|
||
|
||
# 在 NAS 上创建目录
|
||
mkdir -p /volume1/scripts/kb-bot
|
||
cd /volume1/scripts/
|
||
|
||
# 把知识库也 clone 到 NAS（因为 kb-bot 要读 .claude/commands/）
|
||
git clone http://192.168.0.101:3002/robert/company-kb.git
|
||
|
||
# 把 kb-bot 代码复制过来
|
||
cp company-kb/tools/kb-bot/* kb-bot/
|
||
```
|
||
|
||
### 5.2 配置 NAS 上的 lark-cli
|
||
|
||
```bash
|
||
# NAS 上也要装 lark-cli 和 claude CLI
|
||
npm install -g @larksuiteoapi/lark-cli
|
||
npm install -g @anthropic-ai/claude-cli
|
||
|
||
# 用 Bot 身份登录
|
||
lark-cli auth login --type bot
|
||
# 输入 App ID 和 App Secret
|
||
```
|
||
|
||
### 5.3 配置 NAS 定时任务（DSM 控制面板）
|
||
|
||
1. 打开 DSM → 控制面板 → 任务计划
|
||
2. 新增 → 用户定义的脚本
|
||
3. 任务名称：`kb-bot-subscribe`
|
||
4. 用户账号：选你的用户
|
||
5. 计划：开机时运行
|
||
6. 脚本内容：
|
||
```bash
|
||
#!/bin/bash
|
||
cd /volume1/scripts/kb-bot
|
||
nohup bash subscribe.sh > /tmp/kb-bot-sub.log 2>&1 &
|
||
```
|
||
7. 保存
|
||
|
||
重复创建第二个任务：`kb-bot-handle`，脚本内容：
|
||
```bash
|
||
#!/bin/bash
|
||
cd /volume1/scripts/kb-bot
|
||
nohup python3 handle.py --watch > /tmp/kb-bot-handle.log 2>&1 &
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1：subscribe.sh 报错 "lark-cli 不在 PATH"
|
||
|
||
**答**：
|
||
```bash
|
||
# 找到 lark-cli 的路径
|
||
which lark-cli
|
||
|
||
# 把路径加到 subscribe.sh 的 PATH 里
|
||
# 编辑 subscribe.sh，在开头加一行：
|
||
export PATH="/你的路径/bin:$PATH"
|
||
```
|
||
|
||
### Q2：handle.py 报错 "claude 不在 PATH"
|
||
|
||
**答**：同上，编辑 handle.py，在开头加：
|
||
```python
|
||
os.environ["PATH"] = "/你的路径/bin:" + os.environ["PATH"]
|
||
```
|
||
|
||
### Q3：机器人不回复
|
||
|
||
**检查清单**：
|
||
1. `lark-cli auth status` → 确认 bot 身份登录
|
||
2. `ls events/` → 确认有消息文件
|
||
3. `cat events/msg-xxx.json` → 确认消息格式对
|
||
4. `tail -f /tmp/kb-bot-handle.log` → 看错误日志
|
||
5. 手动跑一次 `python3 handle.py`，看输出
|
||
|
||
### Q4：claude -p "/kb-ask xxx" 报错
|
||
|
||
**可能原因**：
|
||
- 工作目录不对（handle.py 的 cwd=ROOT 变量）
|
||
- claude CLI 版本不对
|
||
- /kb-ask 命令文件不存在
|
||
|
||
**验证**：
|
||
```bash
|
||
cd "$KB" # 知识库根目录
|
||
claude -p "/kb-ask 测试问题"
|
||
# 看能否正常执行
|
||
```
|
||
|
||
---
|
||
|
||
## 全链路流程图（清晰版）
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ 飞书群里 @知识库助手 "万牛会L1怎么安排的？" │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置1：飞书服务器 │
|
||
│ - 收到消息 │
|
||
│ - 推送到 WebSocket 长连接 │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置2：你的 Mac / NAS（subscribe.sh 在跑） │
|
||
│ - lark-cli event +subscribe │
|
||
│ - 收到推送，解析消息 │
|
||
│ - 写入 events/msg-12345.json │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置3：你的 Mac / NAS（handle.py 在跑） │
|
||
│ - 轮询 events/ 发现新文件 │
|
||
│ - 解析 JSON 提取问题："万牛会L1怎么安排的？" │
|
||
│ - 调用：subprocess.run([ │
|
||
│ "claude", "-p", │
|
||
│ "/kb-ask 万牛会L1怎么安排的？" │
|
||
│ ], cwd=知识库根目录) │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置4：知识库目录（Claude Code 在这里执行） │
|
||
│ - cd 到知识库根 │
|
||
│ - 读 .claude/commands/kb-ask.md │
|
||
│ - 执行命令逻辑： │
|
||
│ 1. 扫描 projects/ 找相关页 │
|
||
│ 2. 读 frontmatter 筛选 │
|
||
│ 3. 语义检索内容 │
|
||
│ 4. 综合回答 + 挂 source_link │
|
||
│ - 返回答案："根据 [[课程大纲v1]]..." │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置5：handle.py 拿到答案 │
|
||
│ - 调用：lark-cli im +messages-reply │
|
||
│ --message-id 12345 │
|
||
│ --markdown "根据[[课程大纲v1]]..." │
|
||
│ --as bot │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 位置6：飞书服务器 │
|
||
│ - 收到回复请求 │
|
||
│ - 推送到群里 │
|
||
└───────────────────┬────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────────────────┐
|
||
│ 飞书群里显示机器人回复 │
|
||
│ "根据 [[课程大纲v1]]（来源：飞书文档）..." │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 关键位置总结
|
||
|
||
| 位置 | 路径 / 地址 | 作用 |
|
||
|------|------------|------|
|
||
| **知识库代码** | `/Users/qiyu/Library/.../company-kb-v0.1-mvp-20260707/` | kb-bot 代码在这里 |
|
||
| **飞书机器人** | 飞书开放平台 App | 接收消息、发送回复 |
|
||
| **lark-cli 认证** | `~/.lark-cli/` | Bot 身份凭据 |
|
||
| **运行环境** | Mac 本地 / NAS / ECS | subscribe.sh + handle.py 常驻运行 |
|
||
| **飞书测试群** | 你的飞书群 | @机器人 提问的地方 |
|
||
| **events/ 目录** | `kb-bot/events/` | 消息事件临时存放 |
|
||
| **日志文件** | `/tmp/kb-bot-*.log` | 调试用 |
|
||
|
||
---
|
||
|
||
## 下一步行动
|
||
|
||
### 立刻做（10分钟）
|
||
|
||
1. 检查依赖：
|
||
```bash
|
||
lark-cli --version
|
||
claude --version
|
||
python3 --version
|
||
```
|
||
|
||
2. 配置 lark-cli：
|
||
```bash
|
||
lark-cli auth login --type bot
|
||
# 输入 App ID 和 App Secret
|
||
```
|
||
|
||
3. 测试 subscribe：
|
||
```bash
|
||
KB="/Users/qiyu/Library/CloudStorage/SynologyDrive-zhishiku/知识库投递区/公司资产信息/company-kb-v0.1-mvp-20260707"
|
||
cd "$KB/tools/kb-bot"
|
||
bash subscribe.sh
|
||
# 去群里 @机器人，看能否收到消息
|
||
```
|
||
|
||
### 今天完成（1小时）
|
||
|
||
- subscribe 能收消息 ✓
|
||
- handle 能处理并回复 ✓
|
||
- 本地常驻运行 ✓
|
||
|
||
### 本周完成（可选）
|
||
|
||
- 部署到 NAS 常驻
|
||
- 配置开机自启
|
||
- 写使用文档给同事
|
||
|
||
---
|
||
|
||
**有问题随时问我，我逐步帮你排查！**
|