Skip to content

详细使用教程.md

Latest commit

 

History

History
459 lines (305 loc) · 10.3 KB

详细使用教程.md

File metadata and controls

459 lines (305 loc) · 10.3 KB
Raw

knowledge-sweet 详细使用教程

这份教程对应的是 knowledge-sweet 工作区。
目标是复现一个最小可用的“知识库分拣 + 飞书接入 + 可选 Obsidian 同步”环境。

一、先理解这份包到底复现什么

这份包复现的是 4 件事：

  1. knowledge-sweet 工作区目录结构
  2. 飞书群接入 main
  3. dispatcher 脚本和最小队列能力
  4. 可选的 Obsidian 单向同步

这份包不复现：

  1. 你的真实飞书凭证
  2. 你的真实群 ID
  3. 你的本机路径
  4. 与知识库落库无关的其他业务协议
  5. 任意运行态文件和历史日志

二、复现前准备

开始之前，环境至少要有：

  1. 一套可运行的 OpenClaw
  2. 一台能运行 node 的机器
  3. 一个飞书机器人应用
  4. 一个飞书群
  5. 可选：一个 Obsidian Vault

建议先确认这 3 个基础信息：

OpenClaw 根目录：<YOUR_OPENCLAW_HOME>
目标飞书群 ID：<YOUR_GROUP_ID>
Obsidian 目录：<YOUR_OBSIDIAN_VAULT>

三、包内文件怎么理解

1. configs/

放配置模板。

  • openclaw.knowledge-sweet.template.json 用来并入目标环境的 openclaw.json
  • DISPATCHER_CONFIG.template.json 用来生成 knowledge-sweet/DISPATCHER_CONFIG.json

2. scripts/

放脚本模板。

  • dispatch-daemon.mjs dispatcher 主脚本
  • enqueue-dispatch.mjs 入队脚本
  • start-dispatcher.sh 启动 dispatcher
  • stop-dispatcher.sh 停止 dispatcher
  • sync-to-obsidian.sh 同步到 Obsidian
  • ai.openclaw.knowledge-sweet-obsidian-sync.plist macOS launchd 定时同步模板

3. docs/

放工作区说明和分类规则参考。

这些文件不一定都参与程序执行，但能帮助别人理解：

  • 这个 workspace 怎么分类
  • 内容怎么落库
  • 共享上下文怎么定义

四、正式开始前的阅读顺序

人工阅读顺序

建议按下面顺序阅读：

  1. README.md
  2. FEISHU_CONFIG_README.md
  3. OpenClaw-Windows-安装教程.md
  4. 文档关系与高频问题说明.md
  5. 10分钟复现清单.md
  6. 部署说明-knowledge-sweet.md
  7. 分发规则-knowledge-sweet.md
  8. 详细使用教程.md

这样安排的原因是：

  1. 先看总览
  2. 再看飞书与平台接入说明
  3. 再看 Windows 端安装说明
  4. 再看文档关系和高频问题
  5. 再看最快落地清单
  6. 再理解部署结构
  7. 再理解分发规则
  8. 最后按详细步骤执行

AI 学习顺序

如果由 AI 代做，建议先让 AI 学习下面这些文件，并要求它按顺序读取：

  1. README.md
  2. FEISHU_CONFIG_README.md
  3. OpenClaw-Windows-安装教程.md
  4. 文档关系与高频问题说明.md
  5. 部署说明-knowledge-sweet.md
  6. 分发规则-knowledge-sweet.md
  7. 详细使用教程.md
  8. docs/CONFIG.md
  9. docs/SKILL.md
  10. docs/TEAM_CONTEXT.md
  11. configs/openclaw.knowledge-sweet.template.json
  12. configs/DISPATCHER_CONFIG.template.json
  13. scripts/dispatch-daemon.mjs
  14. scripts/enqueue-dispatch.mjs
  15. scripts/start-dispatcher.sh
  16. scripts/sync-to-obsidian.sh

推荐要求 AI 先做 3 件事，再开始改文件：

  1. 总结当前部署结构
  2. 总结当前分发规则
  3. 列出必须修改的占位符和目标文件

五、先做机器人资料盘点与映射

在真正替换模板之前，建议先做一次“机器人资料盘点”。

需要盘点的最小信息

  1. 目标环境里有哪些飞书机器人
  2. 每个机器人的显示名是什么
  3. 每个机器人对应的 appId / appSecret
  4. 它们在 openclaw.json 里对应哪个 accountId
  5. 是否已经有 agentId 与它们绑定
  6. 目标群当前挂在哪个飞书账号下面

盘点后要输出一张映射表

建议至少输出下面这类表：

角色职责 -> 飞书显示名 -> accountId -> agentId -> 目标群 -> 备注

可直接使用：

  • 映射表示例模板.md

为什么这一步不能省

因为模板里只有占位符，没有目标环境的真实绑定关系。
如果不先盘点，最常见的问题是：

  1. 显示名替换了，但 accountId 没对上
  2. groups 写到了错误账号下
  3. 已有 main 被重复创建
  4. 旧机器人配置被误覆盖

六、AI 学完文件后应该怎么做

如果由 AI 落地，推荐执行顺序如下：

  1. 先盘点现有环境
  2. 再盘点机器人资料并建立映射表
  3. 再创建或补齐 knowledge-sweet 工作区
  4. 再替换模板占位符
  5. 再并入 openclaw.json
  6. 再落地 dispatcher
  7. 再配置 Obsidian 同步
  8. 最后启动并验收

每一步都应输出：

  1. 检查了什么
  2. 改了哪些文件
  3. 还缺什么
  4. 下一步做什么

七、第一步：创建工作区目录

在目标机器创建：

<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet

建议至少准备这些目录或文件位置：

<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/
<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/知识库/
<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/launchd/

八、第二步：把模板放到对应位置

最低可用放法如下：

configs/DISPATCHER_CONFIG.template.json
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/DISPATCHER_CONFIG.json

scripts/dispatch-daemon.mjs
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/dispatch-daemon.mjs

scripts/enqueue-dispatch.mjs
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/enqueue-dispatch.mjs

scripts/start-dispatcher.sh
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/start-dispatcher.sh

scripts/stop-dispatcher.sh
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/stop-dispatcher.sh

scripts/sync-to-obsidian.sh
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/sync-to-obsidian.sh

scripts/ai.openclaw.knowledge-sweet-obsidian-sync.plist
-> <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/launchd/ai.openclaw.knowledge-sweet-obsidian-sync.plist

docs/ 下的文件可以整体复制到：

<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/
或
<YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet/参考文档/

如果只是最小复现，脚本和配置优先，说明文档其次。

九、第三步：替换所有占位符

必换项

1. configs/openclaw.knowledge-sweet.template.json

必须替换：

  • <DISPLAY_NAME_MAIN>
  • <APP_ID>
  • <APP_SECRET>
  • <YOUR_GROUP_ID>

作用：

  • 注册 main
  • 绑定飞书账号
  • 把目标群交给这个账号监听

2. configs/DISPATCHER_CONFIG.template.json

必须替换：

  • <YOUR_GROUP_ID>

作用：

  • 让 dispatcher 知道默认监听哪个群

3. scripts/sync-to-obsidian.sh

如果要同步 Obsidian，必须替换：

  • <YOUR_OPENCLAW_HOME>
  • <YOUR_OBSIDIAN_VAULT>

4. scripts/ai.openclaw.knowledge-sweet-obsidian-sync.plist

如果要用 launchd 自动同步，必须替换：

  • <YOUR_OPENCLAW_HOME>

不需要改的原则

  • 不要随便改脚本逻辑
  • 不要把运行态文件一起分享
  • 不要把别人的机器人显示名写死在模板里

十、第四步：并入 openclaw.json

把 configs/openclaw.knowledge-sweet.template.json 的内容并入目标环境的 openclaw.json。

最小要求只有 3 条：

  1. agents.list 里有 main
  2. bindings 里把该飞书账号绑定给 main
  3. channels.feishu.accounts.<accountId>.groups 里写入 <YOUR_GROUP_ID>

如果环境中已有自己的 main，不要盲目覆盖。
做法应该是：

  1. 保留已有的 main
  2. 只把飞书账号和目标群那部分并进去
  3. 确认 accountId、bindings 和实际飞书机器人应用一致

十一、第五步：启动 dispatcher

进入工作区后执行：

cd <YOUR_OPENCLAW_HOME>/workspace/knowledge-sweet
./start-dispatcher.sh

正常情况下会看到类似输出：

dispatcher started: pid=...

如果再次运行，可能看到：

dispatcher already running: pid=...

这表示脚本检测到已有进程，不是错误。

十二、第六步：可选开启 Obsidian 同步

如果需要把知识库同步到 Obsidian：

  1. 先把模板 plist 复制到：
~/Library/LaunchAgents/ai.openclaw.knowledge-sweet-obsidian-sync.plist
  1. 再执行：
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.knowledge-sweet-obsidian-sync.plist

同步脚本默认是：

  • 从 workspace/knowledge-sweet/知识库/
  • 同步到 <YOUR_OBSIDIAN_VAULT>/knowledge-sweet/知识库/

同时会同步根目录 README.md。

十三、第七步：重启 gateway

只复制文件还不够。
如果改了 openclaw.json，必须让 gateway 重新加载配置。

原则是：

  1. 先确认 openclaw.json 合法
  2. 再重启或热加载 gateway
  3. 再去群里做测试

十四、第八步：做最小验收

验收 1：飞书群是否接入

在目标群里发：

存一下：这是一个 OpenClaw 配置说明。

预期：

  • main 会接手
  • 不会报“群未授权”或完全无响应

验收 2：dispatcher 是否在跑

检查工作区是否出现运行态文件，例如：

DISPATCHER.pid
DISPATCHER.stdout.log

验收 3：Obsidian 是否同步

如果启用了同步，检查：

<YOUR_OBSIDIAN_VAULT>/knowledge-sweet/知识库/

看是否能看到同步后的内容。

十五、最容易出错的地方

1. 群 ID 没换

表现：

  • 机器人在线，但目标群不响应

优先检查：

  • openclaw.json
  • DISPATCHER_CONFIG.json

是不是都写成了同一个目标群 ID。

2. 飞书账号绑定错了

表现：

  • main 有配置，但实际机器人不接消息

优先检查：

  • appId
  • appSecret
  • bindings.accountId

是不是同一个应用。

3. dispatcher 没启动

表现：

  • 主通道能说话，但队列、分发、后台处理都没动

优先检查：

  • start-dispatcher.sh 有没有执行
  • DISPATCHER.pid 是否存在
  • DISPATCHER.stdout.log 是否有输出

4. Obsidian 同步路径没换

表现：

  • 脚本能跑，但同步不到目标目录

优先检查：

  • sync-to-obsidian.sh
  • plist

里的 <YOUR_OPENCLAW_HOME>、<YOUR_OBSIDIAN_VAULT> 有没有替换。

十六、复现完成后的检查顺序

复现完成后，建议按下面顺序检查：

  1. openclaw.json 是否已并入目标群
  2. knowledge-sweet/ 工作区脚本是否到位
  3. DISPATCHER_CONFIG.json 是否为真实配置
  4. dispatcher 是否已启动
  5. 飞书群是否可接入
  6. 如启用 Obsidian，同步链路是否生效