Jcchen2026/feishu-doc-publish

{
  "name": "Jcchen2026/feishu-doc-publish",
  "description": "飛書文檔發布工具。觸發：飛書發布、Markdown發布、module-map同步、BugFix說明上飛書。OAuth過期時Agent**必須**按此技能自動`oauth serve`彈瀏覽器授權，**禁止**讓用戶手動執行命令。"
}

飛書文檔發布（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（本機快取）