Jcchen2026/feishu-doc-publish

Feishu Doc Publisher (Feishu Doc Publisher)

Agent General Rules (Must Read)

1. When encountering a Feishu publish task → read this skill first, then execute the CLI; do not just tell the user to run commands.
2. OAuth expiry / no token → Agent automatically recovers (see §OAuth Expiry Automatic Recovery); the user only needs to click "Authorize" in the browser.
3. Credential lookup order (already implemented in config.py, Agent should not duplicate):
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (inside the project, default)
   • If not found → ~/.cursor/tools/feishu_doc_publisher/ or ~/.claude/tools/feishu_doc_publisher/ (local override)
4. Registry: tools/feishu_doc_publisher/clusters/registry.json (optional; without registry, infer from docs/modules/<cluster>-module-map.md convention)

First-time Installation (Target Project)

# One-line installation (public repo)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /path/to/your-repo

# Or clone and install
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/path/to/feishu-doc-publish/install.sh /path/to/your-repo

After installation, configure .env and perform OAuth once. See tools/feishu_doc_publisher/README.md.

Standard Publish (Single Markdown)

cd tools/feishu_doc_publisher
python3 cli.py publish \
  --markdown ../../docs/guides/<file>.md \
  --title "<Feishu Doc Title>" \
  --state-file feishu_doc_state_<slug>.json

Standard Publish (module-map)

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

When the user says "publish to Feishu / sync module-map" → Agent runs the above commands itself, returns feishu_url.

---

Publish Safety Gate (P0)

Background: PUBLISH_INCIDENTS.md · Incidents of overwriting unrelated Feishu documents.

If any condition is not met → STOP, do not publish.

Pre-publish Checklist (Agent Self-Check)

• Cluster mode must use feishu_doc_state_<cluster>.json
• Do not silently use feishu_doc_state.json as the module-map publish target
• Extract feishu.cn/docx/<id> from module-map.md, must match the document_id in the state
• Run --dry-run first, confirm output contains publish_target: OK
• After successful publish: do not automatically modify the Feishu URL in module-map / README (unless the user explicitly requests binding a new document)
• Output for human verification: state_file · doc_id · module-map doc_id

Prohibitions

• ❌ Using feishu_doc_state.json as the target for cluster publish
• ❌ Automatically modifying the module-map Feishu link because the published URL differs from the module-map
• ❌ Running formal publish without --dry-run to verify publish_target

---

OAuth Expiry Automatic Recovery (P0 · Agent Must Execute)

When It Triggers

Error Keyword	Meaning
No user_access_token found	No token
Authentication token expired / 99991677	access_token expired
invalid_grant / refresh token has been revoked	refresh_token invalid

Agent Standard Procedure

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

Agent must:

1. Execute oauth serve by itself (can be backgrounded + poll until OAuth complete).
2. Notify the user: "The Feishu authorization page has been opened in your browser. Please click 'Authorize' once."
3. After successful authorization, immediately retry the original task.
4. When sharing the token with the team, commit the new feishu_tokens.json (do not commit the App Secret).

Prohibitions

• ❌ Only output "Please run oauth start / finish first" leaving the user to operate on the terminal
• ❌ Overwrite the project's feishu_tokens.json with the local old token after OAuth recovery

---

Document Categorization

• Rules: tools/feishu_doc_publisher/CLASSIFY.md
• Configuration: feishu_categories.json (copy from feishu_categories.json.example)
• Align state: python3 cli.py reconcile-states
• Create new category: python3 setup_category.py <category> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

BugFix Fix Descriptions

Item	Value
category	bugfix (or project-specific custom)
Writing standards	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Cursor rule	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git preserves the source code of ```mermaid blocks
• Default FEISHU_MERMAID_MODE=addons: ```mermaid → Feishu's add_ons "Text to Diagram" native flowchart
• On failure, can fall back to companion PNG: docs/assets/<cluster>/

Scope

• Allowed to modify: tools/feishu_doc_publisher/**, docs/**, .cursor/skills/feishu-doc-publish/**
• Do not commit: .env (contains Secret), feishu_tokens.json (team policy decides), feishu_folders.json, feishu_wiki.json (local cache)