飞书文档发布 (Feishu Doc Publisher)

飞书文档发布（Feishu Doc Publisher）

Agent 总则（必读）

1. 遇飞书发布任务 → 先读本 skill，再执行 CLI；不要只告诉用户去跑命令。
2. OAuth 过期 / 无 token → Agent 自动恢复（见 §OAuth 过期自动恢复）；用户只需在浏览器点「授权」。
3. 凭证查找顺序（config.py 已实现，Agent 勿重复复制）：
   • tools/feishu_doc_publisher/.env + feishu_tokens.json（项目内，默认）
   • 若无 → ~/.cursor/tools/feishu_doc_publisher/ 或 ~/.claude/tools/feishu_doc_publisher/（本机覆盖）
4. Registry：tools/feishu_doc_publisher/clusters/registry.json（可选；无 registry 时按 docs/modules/<cluster>-module-map.md 约定推断）

首次安装（目标项目）

# 一行安装（公开仓库）
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /path/to/your-repo

# 或 clone 后安装
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/path/to/feishu-doc-publish/install.sh /path/to/your-repo

安装后配置 .env 并 OAuth 一次，见 tools/feishu_doc_publisher/README.md。

标准发布（单篇 Markdown）

cd tools/feishu_doc_publisher
python3 cli.py publish \
  --markdown ../../docs/guides/<file>.md \
  --title "<飞书文档标题>" \
  --state-file feishu_doc_state_<slug>.json

标准发布（module-map）

tools/feishu_doc_publisher/sync_module_map.sh --dry-run --cluster <cluster>
tools/feishu_doc_publisher/sync_module_map.sh --cluster <cluster>

用户说「发布飞书 / sync module-map」→ Agent 自己跑上述命令，回传 feishu_url。

---

Publish Safety Gate（P0）

背景：PUBLISH_INCIDENTS.md · 误覆写无关飞书文档事故。

任一不满足 → STOP，禁止 publish。

发布前 checklist（Agent 自检）

• cluster 模式必须使用 feishu_doc_state_<cluster>.json
• 禁止静默使用 feishu_doc_state.json 作为 module-map 发布目标
• 从 module-map.md 提取 feishu.cn/docx/<id>，与 state 内 document_id 必须一致
• 先跑 --dry-run，确认输出含 publish_target: OK
• publish 成功后：禁止自动修改 module-map / README 中的飞书 URL（除非用户明确要求绑定新文档）
• 输出供人类核对：state_file · doc_id · module-map doc_id

禁止

• ❌ cluster publish 时使用 feishu_doc_state.json 作为目标
• ❌ 因 publish 输出 URL 与 module-map 不同而 自动改 module-map 飞书链接
• ❌ 未 --dry-run 校验 publish_target 直接正式 publish

---

OAuth 过期自动恢复（P0 · Agent 必执行）

何时触发

报错关键字	含义
No user_access_token found	无 token
Authentication token expired / 99991677	access_token 过期
invalid_grant / refresh token has been revoked	refresh_token 失效

Agent 标准流程

cd tools/feishu_doc_publisher
python3 cli.py oauth serve --timeout 600

Agent 必须：

1. 自己执行 oauth serve（可 background + 轮询直到 OAuth complete）。
2. 告知用户：「已在浏览器打开飞书授权页，请点一次授权即可」。
3. 授权成功后 立即重试 原任务。
4. 团队共享 token 时 commit 新 feishu_tokens.json（勿提交 App Secret）。

禁止

• ❌ 只输出「请先 oauth start / finish」让用户自己终端操作
• ❌ OAuth 恢复后用本机旧 token 覆盖 项目内 feishu_tokens.json

---

文档归类

• 规则：tools/feishu_doc_publisher/CLASSIFY.md
• 配置：feishu_categories.json（从 feishu_categories.json.example 复制）
• 对齐 state：python3 cli.py reconcile-states
• 新建 category：python3 setup_category.py <category> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

BugFix 修复说明

项	值
category	bugfix（或项目自定义）
撰写规范	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Cursor rule	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git 保留 ```mermaid 源码
• 默认 FEISHU_MERMAID_MODE=addons：```mermaid → 飞书 add_ons「文本绘图」 原生流程图
• 失败时可 fallback 伴生 PNG：docs/assets/<cluster>/

范围

• 允许修改：tools/feishu_doc_publisher/**、docs/**、.cursor/skills/feishu-doc-publish/**
• 勿提交：.env（含 Secret）、feishu_tokens.json（团队策略自定）、feishu_folders.json、feishu_wiki.json（本机缓存）