Basepilot MCP server

BasePilot

<!-- mcp-name: io.github.Peterwong666/basepilot -->

面向企业交付的飞书多维表格 MCP Server —— 用 MCP 工具把多维表格变成

Claude Code / Cursor 可安全读写的业务台账。

English · 简体中文

这是什么

中小企业已经在用飞书多维表格承载业务台账（库存、广告、差评跟进）， 数据靠人工从 Seller Central / 广告后台导 CSV 再粘贴进去，每天 1-2 小时。 公司想上 AI，但第一件事就卡住了：

这不是技术选型问题，是没有人把多维表格的真实约束包一层。 业务等不了，AI 落地就停在这里 —— 这是很多「客户买过 AI 工具但没用起来」的真实原因。

BasePilot 就是那一层。

看图说话（全部为真实运行输出，非手绘）

1. 入口宽容，出口严格—— 适配层把 LLM 的错误输入吃掉

scripts/demo_coerce.py 把LLM 最常犯的四种错误喂给适配层，看它们被自动纠正：

2. 业务诊断：15 个环节逐条打分，明确劝退 2 个

四象限分布（7 个不需要 AI，4 个 AI 主导，2 个明确劝退）：

3. 评测：9 项指标全部实算，无一手写

4. 离线全量门禁：lint + 类型 + 测试 + 评测 + 文档校验

5. cassette 重放：真实租户交互在 CI 可复现（已脱敏）

6. 交付文档链：五份「报告即代码」自动生成

排障 SOP由 errors.py 自动生成，与代码零漂移：

全部截图由 scripts/make_screenshots.py 执行真实命令后渲染，不存在手绘图。

脚本内置「解释器污染」防护 —— 用错Python 环境会导致场景包静默降级，

生成数字错误的图，已加断言阻止出图。

架构

┌─ MCP 工具层 ──────────────────────────────────────────────┐
│  describe_table · create/update/delete · search            │
│  batch_upsert · dry_run_create · diagnose_scenarios        │
└────────────────────────┬───────────────────────────────────┘
                         │
┌─ 引擎五层 ────────────────────────────────────────────────┐
│  serialization.py  per-table 锁 + 0.5s 节流                │
│  client.py         串联调用链 · upsert_records             │
│  coerce.py         13 类编码器 + normalize_key 解码        │
│  ratelimit.py      分桶限流（write/search/list 独立）│
│  auth.py           token 缓存 + asyncio 单飞               │
└────────────────────────┬───────────────────────────────────┘
                         │
┌─ 横切三线 ────────────────────────────────────────────────┐
│  config.py飞书约束常量（每个数值标注官方出处）      │
│  errors.py       34 条错误码 → 客户现场动作               │
│  cassette.py     录制/重放 + 凭证与租户标识符脱敏           │
└────────────────────────┬───────────────────────────────────┘
                         │
              https://open.feishu.cn/open-apis

分层原则：不是把 API 包装成工具，而是把飞书的真实约束收敛到三层里。 工具层只表达业务意图（batch_upsert），约束由引擎层统一兜住 —— 否则同一条记录走不同入口会得到不同结果（见 ADR-004）。

三个适配层（核心）

不是把 API 包装成工具，而是治理飞书的真实约束。

1. 鉴权层 —— token 缓存 ✅

tenantaccesstoken 有效期 7200 秒。官方明确：剩余有效期小于 30 分钟时返回新 token， 大于等于 30 分钟时返回原 token。所以刷新窗口必须落在 [0, 30min] 区间内， 否则会拿到同一个 token，白白消耗配额。

实现：进程内缓存 + asyncio.Lock 单飞（并发下只换一次，其余复用）。

实测指标：100 次业务请求 → 向飞书换 token 1 次。 （tests/testauth.py::test100requestsfetchtokenonce，可复现）

2. 并发层 —— 单表写串行 ✅

官方错误码 1254291 的排查建议原文：「在接口与接口之间增加 0.5 或 1 秒的延迟」； 1254607 补充说明底层「基于版本维度的串行方式，不支持并发」。

Shortened. The full README is on GitHub.