feishu-sync

name	feishu-sync
description	双向同步 Markdown 与飞书文档。下载飞书 docx/wiki → md（带 metadata 增量缓存）；上传 md → 飞书 docx（自动检测 LaTeX 公式，有公式走 uploader 渲染，无公式走 feishu-docx）；额外支持 CSV/MD-table/TSV → 飞书电子表格（Sheets，类 Excel 独立页面）。面向所有使用飞书的个人/团队/AI agent，portable，首次调用自装依赖，零硬编码业务信息。

feishu-sync

Markdown ↔ 飞书云文档的双向同步 skill。一条命令搞定上传/下载，按内容特征自动选工具。

什么时候用这个 skill

• 要从飞书拉 docx 或 wiki 空间 → bin/download.sh
• 要把 md 上传到飞书（含公式也能正确渲染）→ bin/upload.sh
• 要把单张表格作为独立飞书电子表格上传（类 Excel 页面，可在线编辑/筛选/排序）→ bin/upload-sheet.sh
• 遇到飞书 API 错误码搞不懂 → 查 docs/error-codes.md
• 不知道该用 tenant 还是 oauth 鉴权 → 查 docs/auth-modes.md
• 接入 AI agent 框架（Multica / LangChain / AutoGen / 自建 runtime） → 查 docs/multica-integration.md（以 Multica 为例，其他框架可类比）

前置：环境变量

export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"
# 可选：Lark 国际版用
# export FEISHU_HOST="open.larksuite.com"   # 默认 open.feishu.cn

应用身份权限必需 scope（应用管理员在开放平台开通并发版）：

• 读：wiki:wiki:readonly + docx:document:readonly
• 写 docx：docx:document + drive:drive
• 写 spreadsheet：sheets:spreadsheet（含创建+读写）；指定 --folder 还需 drive:drive

首次使用：装依赖

bash bin/setup.sh

幂等。第二次跑会自动跳过已装的。装好后：

• feishu-docx 走 pipx（隔离，避免污染系统 Python）
• feishu-markdown-uploader 克隆到 ${HOME}/.feishu-sync/uploader/ 并 npm install

自检

bash bin/probe.sh                         # 凭证 + token
bash bin/probe.sh --wiki <url>            # 加验 wiki 可达
bash bin/probe.sh --doc <url>             # 加验 docx 可读
bash bin/probe.sh --sheets                # 加验 sheets:spreadsheet scope（创建+删除临时表）

验 3-5 件事（按 flag）：

1. 凭证环境变量齐全
2. tenant_access_token 能取
3. 如果给了 --wiki <url>，验证 wiki 可达
4. 如果给了 --doc <url>，验证 docx 正文可读
5. 如果给了 --sheets，验证创建/删除 spreadsheet（顺带验 drive:drive）

主命令：下载

# 单个 docx（默认 cache-mode=auto：metadata 比对，远端未变跳过下载）
bash bin/download.sh "https://xxx.feishu.cn/docx/<token>" -o ./out/

# 整个 wiki 空间（递归）
bash bin/download.sh "https://xxx.feishu.cn/wiki/<root_token>" -o ./out/ --recursive

# 用 OAuth 模式（当 tenant 权限不够时）
bash bin/download.sh <url> -o ./out/ --auth oauth

# 强制重下，覆盖本地 + meta
bash bin/download.sh <url> -o ./out/ --cache-mode force

# 只用本地副本，不联网（仅单 docx URL；无副本则报错）
bash bin/download.sh <url> -o ./out/ --cache-mode skip

cache-mode 选项（命令行 > 环境变量 CACHE_MODE > 默认 auto）：

模式	行为	适用
auto	拉远端 metadata（revision_id/obj_edit_time），与本地 <out>/.meta/<obj>.json 比对，命中跳过	增量同步、定时拉取、CI
force	不查 cache，直接重下覆盖	调试、确认远端无误
skip	不联网，只用本地副本，缺失则报错	离线复用、断网场景（仅单 docx URL）

约束：wiki 全量递归（--recursive）+ feishu-docx 路径暂不做 per-node cache，按 force 重下整个 space。要 per-node cache 改走 lite 路径（python3 bin/download-lite.py <url> --recursive --cache-mode auto）。

降级行为（无需用户干预）：feishu-docx 不在 PATH 时自动降到 bin/download-lite.py（纯 stdlib raw_content，保真度低，不下图片，表格压成文本）。

主命令：上传

# 无公式：走 feishu-docx create，最简
bash bin/upload.sh ./my.md --title "我的文档"

# 有 LaTeX 公式：自动检测，走 uploader（带公式渲染）
bash bin/upload.sh ./paper.md --title "论文"

# 强制走 uploader（即使未检测到公式）
bash bin/upload.sh ./x.md --force-latex

# 指定飞书目录（folder_token）
bash bin/upload.sh ./x.md --folder fldcn_xxxx

降级行为：feishu-docx 不可用时降到 uploader；uploader 不可用时降到 feishu-docx。两个都不在才会失败。

主命令：上传单张表格为飞书电子表格

# CSV → 独立飞书 spreadsheet（类 Excel 页面）
# 默认开启美化：表头加粗+浅蓝底+居中、冻结首行、列宽自适应
bash bin/upload-sheet.sh ./data.csv --title "Q1 销售"

# 从一份 markdown 里抓第一张 GFM 表格上传（忽略其他段落）
bash bin/upload-sheet.sh ./report.md --title "演示" --folder fldcn_xxx

# 制表符分隔
bash bin/upload-sheet.sh ./data.tsv --title "原始日志"

# 不知道扩展名时显式指定格式
bash bin/upload-sheet.sh ./data.txt --format csv --title "无后缀"

# 只解析+打印请求体，不真发请求（联调用）
bash bin/upload-sheet.sh ./data.csv --dry-run

# 关闭所有美化，只写数据（适合后续要程序化读 + 不在意展示）
bash bin/upload-sheet.sh ./data.csv --plain

# 颗粒度更细：单独关某一项（其它默认仍开）
bash bin/upload-sheet.sh ./data.csv --no-freeze       # 加粗+列宽，不冻结
bash bin/upload-sheet.sh ./data.csv --no-autosize     # 加粗+冻结，不动列宽
bash bin/upload-sheet.sh ./data.csv --no-header-style # 冻结+列宽，不加粗

# 自定义表头底色（默认 #E8F0FE 浅蓝；想要暖色用 #FFE5E5 等）
bash bin/upload-sheet.sh ./data.csv --header-bg "#FFE5E5"

# RAW 模式：保留代码片段、保留前导零（航班号/邮编/ID），公式 = 不被执行
# 默认（USER_ENTERED 模式）会自动给 = 开头加 ' 防注入；literal 不需要
bash bin/upload-sheet.sh ./flight-numbers.csv --literal

# 刷新已有 spreadsheet 内容（不新建）：传 URL 或 raw token，自动跳过 create + 样式
bash bin/upload-sheet.sh ./weekly.csv --update "https://my.feishu.cn/sheets/XYZ"

成功后输出 [DONE] https://xxx.feishu.cn/sheets/<token> ——直接打开就能看到 Excel 风格页面。

数据保真行为表：

输入	默认（USER_ENTERED）	--literal（RAW）
42	int 42	str "42"
1.23e10	float	str "1.23e10"
007	str "007"（保前导零）	str "007"
=SUM(A1:A3)	str "'=SUM(...)"（前缀防注入）	str "=SUM(...)"
2026-04-26	飞书识别为日期	字符串
true/false	bool（飞书自动识别）	bool（飞书自动识别）

决策树（agent 遇到"该用哪个"时看这里）

任务要在飞书产出什么？
├── 一份图文/段落/带公式的文档？
│   └── bin/upload.sh ./x.md --title "..."
│       ├── md 里有 $...$ / $$...$$ / \\frac / \\sum 等 LaTeX 符号
│       │   → 自动走 uploader（公式渲染为 equation 块）
│       └── 否 → 自动走 feishu-docx create（最简）
│
├── 一张可在线编辑/筛选/排序的表格（类 Excel）？
│   └── bin/upload-sheet.sh ./data.{csv,tsv,md} --title "..."
│       ├── .csv → 逗号分隔
│       ├── .tsv → 制表符分隔
│       └── .md  → 抓文件中第一张 GFM 表格
│       │
│       ├── 数据是否含 = 公式 / 前导零 ID（航班号/邮编）？
│       │   └── 是 → 加 --literal（切 RAW 模式，全部当字符串）
│       ├── 后续要程序化读，不需要展示美观度？
│       │   └── 是 → 加 --plain（关样式 / 关冻结 / 关列宽）
│       └── 想自定义表头颜色？
│           └── 加 --header-bg "#RRGGBB"（默认浅蓝 #E8F0FE）
│
任务是要从飞书拿内容？
├── URL 是 /docx/<token>？
│   └── bin/download.sh <url>（单文档导出）
├── URL 是 /wiki/<token> 且只要一个文档？
│   └── bin/download.sh <url>（自动走 wiki_token）
├── URL 是 /wiki/<token> 且要整个空间？
│   └── bin/download.sh <url> --recursive
│
任务是更新已有文档的某个 block？
├── 不走本 skill，直接 feishu-docx update（本 skill 不封装）
│
任务是删除文档？
├── 不走本 skill——本 skill 禁止写删除操作

错误排查（出错了先看这里）

agent 遇到 code 非 0 时，第一步到 docs/error-codes.md 查对应修法。常见 4 个：

错误码	含义	修法
99991672	应用身份 scope 不足	回开放平台加 scope 并发版（写 sheet 需 sheets:spreadsheet）
131006	非成员或 wiki 不公开	读场景：加应用到 wiki 成员（只读）；写场景：加 edit 权限
20027	OAuth scope 不足	换 OAuth2Authenticator(scopes=[...]) 只请最小集
20029	redirect_uri 不匹配	开放平台 → 安全设置加 http://127.0.0.1:9527/（带结尾斜杠）

禁止清单

• 不删除：skill 不封装 delete 操作，删除必须人工
• 不硬编码：url、wiki_token、obj_token 都由调用方传入
• 不记日志含密钥：FEISHU_APP_SECRET 不得出现在任何输出或错误信息中（脚本里已做脱敏）
• 不自动改权限：skill 不会自己去改应用可用范围或加知识库成员——那是人工动作

设计原则

1. 薄编排 > 重实现：skill 不重新写下载/上传，只做路由 + 决策
2. 链接/参数由调用方传：skill 里零硬编码业务信息
3. 自证可用：setup.sh 和 probe.sh 让 agent 能自己诊断环境
4. 错误可操作：错误码直接指向 docs/error-codes.md 里具体修法
5. 优雅降级：外部依赖（feishu-docx / uploader）缺失时自动降到 stdlib 或互为兜底；LaTeX 检测失败时退回到 feishu-docx——保证基础能力永不中断