飞书私人助理机器人

一个常驻本机的飞书群机器人：群里 @它，它就能聊天、查知识库、建/查 Tower 任务与笔记。 底层是「AI CLI（claude / hermes）+ 飞书消息轮询」，无需公网、无需长连接。

能做什么

• 聊天答疑 —— 日常对话、解释、出主意。
• 把群讨论建成 Tower 任务 ⭐ —— @它「把上面讨论的建成任务」，它读群聊记录提炼成任务建到对的项目。不用写「上面/刚才」也行：说「建成任务/记一下/复盘下/我们刚聊的」等自然表达都会自动带上讨论上下文（关键词见 runtime/bot.js 的 detectWindow）。
• 查 Tower —— 任务进度、项目、今日待办/总结。
• 记 Tower 笔记。
• 查知识库 —— 本地知识库目录（可选）+ Tower 知识库（MCP ask_project_knowledge，按项目问答）。
• 查飞书 wiki / 云文档、看群里发的图/文件。

三档权限：管理员（建/查/改）、建任务档（查+建任务）、只读（仅查看）。提示词见 CLAUDE.md（claude 引擎）与 SOUL.md+AGENTS.md（hermes 引擎），可自定义项目别名。

启动（git 部署）

没有「变体」——就一个 bot.sh，用哪个 AI CLI 由 config.engine 决定（都是单次调用：起一次 CLI、答完就退）。

./bot.sh start | stop | restart | status | logs
BOT_ENGINE=codex ./bot.sh start     # 临时换引擎（或改 config.engine 再 restart）

Tower 能力：只有 claude 引擎接了 Tower/飞书 MCP，能建/查任务、查知识库。其它引擎（codex/gemini/qwen/hermes…）默认只能聊天/问答/通知，不能建任务（除非你在该 CLI 自己的配置里另配了 Tower MCP）。启动时会打印提示。

npm 部署用 feishu-assistant 命令，等价能力。

提示词怎么注入（不再手写在代码里）

提示词已从 bot.js 里的硬编码字符串抽出成独立 markdown 文件，改提示词只改文件、不动代码：

| 引擎 | 提示词文件 | 加载方式 | |------|-----------|---------| | claude | CLAUDE.md（= claude.md，macOS 大小写不敏感为同一文件） | claude 在工作目录自动加载 | | hermes | SOUL.md（人格）+ AGENTS.md（规则） | hermes 在工作目录自动加载 |

三个文件内容要保持一致——改了 CLAUDE.md 的规则，记得同步 SOUL.md/AGENTS.md。 按角色的动态权限说明（管理员/建任务/只读）仍在 bot.js 里按消息追加，不放这些文件。

安装（npm）

npm i -g feishu-assistant       # 公网 npm，直接装
feishu-assistant setup          # 生成配置到 ~/.feishu-assistant（npm update 不会清掉）
# 按提示填 config.json / mcp-bot.json（appId/secret、你的名字、Tower 路径），再跑一次 setup 校验
feishu-assistant start          # 启动；status / logs / stop / restart / engine <name>

• 配置、提示词、日志、状态都在 ~/.feishu-assistant/（用 FEISHU_ASSISTANT_HOME 可改），与包代码分离——升级不丢配置。
• claude CLI 登录、飞书建应用仍需每人自备（setup 会检测本机已装哪些 AI CLI、自动填好飞书 MCP 路径）。

命令：feishu-assistant setup | start [engine] | stop | restart | status | logs | engine <name>

飞书域名（公司 / 公网都支持）

• config.domain：公网飞书填 https://open.feishu.cn；公司/私有化飞书填你们自己的内网开放平台地址（问管理员）。mcp-bot.json 里飞书 MCP 的 -d 要一致。

选 AI 引擎（能用就配）

• claude（推荐，默认）：带 CLI 层工具 gating，最安全；用 claude CLI 自带 OAuth，无需 API key。只有它接了 Tower（能建/查任务）。
• codex / gemini / qwen / hermes / opencode / cursor-agent：装好并登录对应 CLI 即可切；无工具 gating＝仅管理员可用、不接 Tower（只聊天/问答/通知）。
• 自定义 / 改用法 / 接新 CLI：每个 CLI 的用法都在 runtime/engines.js 一个文件里，或 config.engines 不改代码就能加。详见 docs/引擎适配器.md（维护必读）。
• AI 的登录态/endpoint 由各 CLI 自己管，本 bot 只负责调用。

或：直接用 git 仓库（开发/自定义）

1. 装依赖：node（≥18）、claude CLI（能跑通、已登录）；要用 hermes 再装 hermes。仓库里 pnpm install。
2. ./setup.sh —— 检查依赖、从 example 生成 runtime/config.json / mcp-bot.json 并校验。
3. 填配置：runtime/config.json（ownerName、appId/appSecret/botOpenId、admins、可选 knowledgeDir）、runtime/mcp-bot.json（飞书 appId/secret + Tower MCP 路径）。再跑一次 ./setup.sh 校验。
4. 起机器人：./bot.sh start（引擎由 config.engine 定）。
5. 授权：管理员群里 @机器人 发「授权本群」或「授权本群建任务」开权限。

知识库：机器人的知识来自两处——本地 knowledgeDir（可选）和 Tower 知识库（MCP，按项目组织，每个同事配自己的 Tower 项目即可）。想让它查你的资料，把资料放进 Tower 对应项目的知识库，或设 knowledgeDir 指向本地目录。

目录

assistant/
├── bot.sh                # 单一启动器（git 部署；引擎由 config.engine 定）
├── _bot-lib.sh           # 共享控制逻辑（start/stop/status/logs + 单实例锁）
├── setup.sh              # 同事一键上手（依赖检查 + 生成配置 + 校验）
├── CLAUDE.md             # claude 引擎提示词（= claude.md）
├── SOUL.md + AGENTS.md   # hermes 引擎提示词
├── bin/cli.js            # npm 部署的命令入口（feishu-assistant）
├── runtime/
│   ├── bot.js            # 机器人主程序（飞书轮询/权限/上下文/回复）
│   ├── engines.js        # 引擎适配器（每个 AI CLI 一段；改/接 CLI 只动这里）
│   ├── config.json       # 密钥/白名单（不入库；照 .example 填）
│   ├── mcp-bot.json      # MCP 配置（不入库；照 .example 填）
│   └── state.json        # 运行时状态（不入库）
├── docs/                 # 同事上手教程、引擎适配器文档
└── logs/                 # 日志（不入库）

避坑记录（已在代码里处理，勿回退）

• 密钥不入库：config.json / mcp-bot.json 含飞书 appSecret，已 .gitignore。分享代码只带 *.example.json。
• 代理：启动脚本清掉本机代理污染让飞书轮询走直连；claude 引擎在 bot.js 里按 config.claudeProxy 自行恢复自己的代理（否则会忽略 ~/.claude/settings.json 的代理直连 Anthropic，在家 403）。飞书内网域名列入 NO_PROXY 例外。
• 一次只跑一个变体：变体指向同一个飞书 bot，同时跑会重复回复。控制脚本用共享 PID 锁拦截。
• 单次调用、不做常驻：本 bot 就是「接飞书 + 转发给某个 CLI（claude/codex/…）」的薄适配器，每条消息起一次进程、答完就退，token/登录态全归各 CLI 自己管。曾试过 claude 常驻（stream-json）实测更慢（模型推理+MCP 往返才是大头，非冷启），已删除。真要提速走 webhook 替代 8s 轮询 / 砍 transcript。