技术记录

今日总结：飞书知识库契约式同步开发

今日总结：飞书知识库契约式同步开发

背景

按照 quanttide/qtcloud-asset 的 roadmap，我需要在 examples/feishu-wiki 中实现契约式同步：用 YAML 契约声明必须存在的知识库和节点关键词，用验证脚本校验下载结果。整个过程要求不破坏现有简洁性。

核心问题：token 获取

飞书 API 需要认证，核心卡点在于 token 获取。

方案演变

方案 原理 结果
lark-cli subprocess 用 lark-cli 执行命令 Windows 上批量包装器有 bug，subprocess 会 hang
proxy 捕获 token lark-cli → 本地代理 → 飞书，代理捕获 Bearer token Windows 后台进程无法稳定运行
App Token (App ID + Secret) 用飞书自建应用换 tenant_access_token App 账号无法直接加入知识库，API 只支持加 user/chat/department
lark-cli subprocess (wiki 子命令) Python 调用 lark-cli wiki spaces list 等命令解析 JSON 可行，lark-cli 已用用户身份登录，能访问所有知识库

最终方案

用 lark-cli wiki 子命令替代有 bug 的 lark-cli api 子命令。wiki 子命令完全正常，可以执行：

  • lark-cli wiki spaces list → 获取知识库列表
  • lark-cli wiki nodes list --space-id xxx → 获取节点列表
  • lark-cli wiki spaces create → 创建知识库

代码产出

contract.yaml

1
2
3
4
5
spaces:
  - id: "7526874705676091393"
    name: "会议档案"
    required_nodes:
      - ""

validate.py

契约验证脚本，加载 contract.yaml 和本地 metadata.json，输出 PASS/FAIL。

catalog.py

重写多版，最终用 lark-cli subprocess 调用 wiki 子命令，执行递归节点下载。

遇到的问题

  1. Windows subprocess hang：lark-cli.cmd 批量包装器检测到 stdin 是管道时会进入交互模式导致进程挂起。加 stdin=DEVNULL 解决。

  2. GBK 编码错误：中文错误信息和 emoji 在 Windows CMD 下导致 UnicodeEncodeError。用 ASCII 标签（[SAVE]、[DEL]、[PASS]）替代 emoji。

  3. App Token 权限体系不兼容：tenant_access_token 属于应用身份，无法直接获得用户有权限访问的知识库。需要换用户 token。

  4. 测试企业隔离：应用发不到正式企业，测试企业的知识库和正式企业完全隔离。

明日计划

  1. 用 lark-cli wiki 子命令重写 catalog.py API 层
  2. 完成测试Wiki节点获取验证
  3. 运行 validate.py 确认契约校验通过

相关链接：