company-kb/docs/kb-bot-usage-guide.md

kb-bot 完整使用指南（从零到运行）

解决："在哪里、怎么用、机器人在哪"的所有困惑 更新时间：2026-07-16

---

问题：你现在卡在哪里？

截图显示：

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

# 检查是否安装
lark-cli --version

# 如果没装，安装
npm install -g @larksuiteoapi/lark-cli

# 检查认证状态
lark-cli auth status

预期输出：显示当前登录的身份（用户或 bot）

1.2 检查 claude CLI

# 检查是否安装
claude --version

# 如果没装，安装
npm install -g @anthropic-ai/claude-cli

# 检查能否运行
claude --help

1.3 检查 Python 3

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 身份登录

# 清除旧的认证
lark-cli auth logout

# 用 Bot 身份登录
lark-cli auth login --type bot

# 会提示输入 App ID 和 App Secret
# → 输入第二步创建的那两个值

3.2 验证认证

lark-cli auth status

# 预期输出：
# ✓ Logged in as bot (app_id: cli_xxxx)

如果这步没通过，后面全都跑不起来。

---

第四步：测试 kb-bot（本地运行）

4.1 进入 kb-bot 目录（正确路径）

# 用实际路径（不是 ~/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 subscribe.sh

# 预期输出：
# [kb-bot] 订阅飞书群消息事件 → /path/to/events
# [kb-bot] 只收 im.message.receive_v1；Ctrl-C 停止。
# （长连接建立，等待消息...）

现在去飞书群里 @知识库助手 说句话，比如：

@知识库助手 你好

回到终端，应该看到：

[lark-cli] 收到消息: events/msg-xxx.json

检查 events/ 目录：

ls events/
# 应该有一个 msg-xxx.json 文件

如果能收到消息，说明 subscribe.sh 正常。按 Ctrl-C 停止。

4.3 测试 handle.py（处理消息）

# 单次处理（不常驻）
python3 handle.py

# 预期：
# - 读 events/ 里的消息
# - 调 claude -p "/kb-ask 你好"
# - 用 lark-cli 回复到群

# 如果成功，群里会看到机器人回复

如果群里机器人回复了，说明 handle.py 正常。

4.4 常驻运行（测试通过后）

# 开两个终端

# 终端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

# 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

# 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. 脚本内容：

   #!/bin/bash
   cd /volume1/scripts/kb-bot
   nohup bash subscribe.sh > /tmp/kb-bot-sub.log 2>&1 &
   

7. 保存

重复创建第二个任务：kb-bot-handle，脚本内容：

#!/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"

答：

# 找到 lark-cli 的路径
which lark-cli

# 把路径加到 subscribe.sh 的 PATH 里
# 编辑 subscribe.sh，在开头加一行：
export PATH="/你的路径/bin:$PATH"

Q2：handle.py 报错 "claude 不在 PATH"

答：同上，编辑 handle.py，在开头加：

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 命令文件不存在

验证：

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. 检查依赖：

   lark-cli --version
   claude --version
   python3 --version
   

2. 配置 lark-cli：

   lark-cli auth login --type bot
   # 输入 App ID 和 App Secret
   

3. 测试 subscribe：

   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 常驻
• 配置开机自启
• 写使用文档给同事

---

有问题随时问我，我逐步帮你排查！