feishu-kb-agent

用 DeepSeek（DeepSeek Harness / 任意 MCP 客户端）管理你的个人飞书知识库。 不是「让 AI 随便改文档」，而是把知识库当成一个有规则的系统：写入可审计、重复会被拦、删除必须过人。

一切设计只服务四件事：可检索、可回指、可重建、可增改查。 做不到这四件事的功能，一律不做。

它解决什么问题

飞书知识库有三个硬约束，直接决定了「AI 该怎么操作它」：

所以这个项目不是把四个 API 包一层，而是补上飞书缺的三样东西：索引、规则、审计。

Related MCP server: ai-wiki-mcp

能力

模型通过 MCP 看到 12 个强类型工具：

人用的命令行补齐了模型不该有的能力：init、doctor、login、delete --confirm、restore、export、eval。

3 分钟跑起来

# 1) 安装（任选其一）
uv tool install git+https://github.com/ZornZL/feishu-kb-agent
# 或
pipx install git+https://github.com/ZornZL/feishu-kb-agent

# 2) 初始化：填飞书自建应用的 App ID / Secret 和知识库入口页链接
feishu-kb init

# 3) 体检：逐项验证权限，失败会直接告诉你去点哪里
feishu-kb doctor

# 4) 建索引
feishu-kb sync

飞书应用怎么建、要开哪些权限、怎么把应用加进知识库：见 飞书配置。

权限通了之后，跑一次真实验收（会创建一页测试页，默认只生成删除提案、不删除）：

python scripts/acceptance.py

它依次验证：实时连通 → 同步 → 创建 → 立即可检索 → 追加 → 读回 → 定位头 → 删除提案。

想用「自己的飞书账号」而不是应用身份（更接近“每个人用自己的账号登录”）：

feishu-kb init --auth-mode user
feishu-kb login

接进 DeepSeek Harness

在 ~/.dsh/cordis.patch.yml 里加一条（Windows 把 command 换成 feishu-kb-mcp.exe 的绝对路径）：

- insert:
    - id: feishu-kb
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: feishu_kb
        transport: stdio
        command: feishu-kb-mcp
        args: []

重启 Harness，工具会以 mcp__feishu_kb__kb_search 这样的名字出现。完整说明与排错见 DSH 接入。

为什么这样设计

写入只追加，不覆盖

飞书没有版本 API，整篇覆盖等于「把历史删了再写一份」：审计断裂、样式丢失、并发时互相踩。 所以 kb_append 是默认写入方式，kb_replace_text 只用于纠错，且写入前会把原文镜像进本地台账（feishu-kb restore 可回滚）。

删除是人的权力，不是模型的能力

模型 kb_propose_delete → 一次性提案号（24h 过期）
        ↓ 人在本机
feishu-kb delete --confirm <提案号> → 再输入 DELETE → 删除 + 墓碑

工具面里没有 delete，不是靠提示词约束模型，而是能力边界。

目录要「长」出来

不按学科建目录，只按用途建；同类页面 ≥5 才建议建，长期 <3 页建议并。 kb_audit 会按阈值给建议，而不是自动搬树——结构调整必须有人拍板。

完整规则判定（哪些吸收、哪些剔除、为什么）：规则取舍。 CRUD 的完整契约与失败模式：CRUD 设计。

文档

分享给别人用

这是一人一库的工具，不是多人共用一个知识库的 SaaS：

• 每个人 clone 后填自己的飞书应用凭据与知识库链接；

• 配置与索引只存在本机 ~/.feishu-kb/，不进 Git；

• 用 user 模式时，权限就是这个人自己的，不需要把应用加成知识库成员；

• 不做中央服务器，也就没有「谁的密钥放在服务端」的问题。

项目结构

feishu_kb/
  config.py      配置解析（env / .env / ~/.feishu-kb）
  client.py      飞书 HTTP 客户端（令牌缓存、重试、错误翻译）
  wiki.py        知识空间节点：树、建、改名、移动、删
  docx.py        文档块 ↔ Markdown
  rules.py       定位头、命名、查重、目录阈值
  store.py       SQLite 索引 + 修订台账 + 删除提案
  service.py     业务操作（供 MCP 与 CLI 共用）
  auth.py        飞书账号 OAuth（user_access_token）
  mcp_server.py  MCP stdio 服务器
  cli.py         命令行
tests/           单元测试 + 假飞书端到端 + MCP 握手
docs/            飞书配置、DSH 接入、规则取舍、CRUD 设计

已知限制

• 只索引与编辑 docx；表格、思维导图、多维表格只能给链接。

• 图片/附件不进索引（飞书 docx 的 image 块没有可检索文本）。

• 中文检索用二元组，不做同义词扩展；专有名词全称/缩写要各写一次。

• 单机单进程假设：没有多人并发写同一页的冲突合并。

• 飞书接口限流约 100 次/分钟，首次全量同步大库会慢。

Roadmap

• 引用回指：回答时返回 (node_token, block_id, 片段)，支持点击定位

• 关系提议队列：supports / contradicts / refines 先提案后落库

• kb_audit 的趋势报告（周环比）

• 图片 OCR 与图注生成

• 可选的本地向量召回（SQLite 扩展，零服务）

License

MIT