Jcchen2026/feishu-doc-publish

Feishu-Dokumenten-Veröffentlichung (Feishu Doc Publisher)

Agenten-Grundregeln (zwingend zu lesen)

1. Bei Feishu-Veröffentlichungsaufgaben → zuerst dieses Skill lesen, dann CLI ausführen; den Benutzer nicht nur anweisen, den Befehl selbst zu starten.
2. OAuth abgelaufen / kein Token → Agent stellt automatisch wieder her (siehe §Automatische OAuth-Wiederherstellung); der Benutzer muss nur im Browser auf „Autorisieren“ klicken.
3. Reihenfolge der Credential-Suche (bereits in config.py implementiert, Agent nicht duplizieren):
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (projektintern, Standard)
   • Falls nicht vorhanden → ~/.cursor/tools/feishu_doc_publisher/ oder ~/.claude/tools/feishu_doc_publisher/ (lokale Überschreibung)
4. Registry: tools/feishu_doc_publisher/clusters/registry.json (optional; ohne Registry wird gemäß Konvention docs/modules/<cluster>-module-map.md abgeleitet)

Erstinstallation (Zielprojekt)

# Einzeilige Installation (öffentliches Repository)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /path/to/your-repo

# Oder nach Klonen installieren
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/path/to/feishu-doc-publish/install.sh /path/to/your-repo

Nach der Installation .env konfigurieren und einmalig OAuth durchführen – Details siehe tools/feishu_doc_publisher/README.md.

Standardveröffentlichung (einzelnes Markdown)

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

Standardveröffentlichung (module-map)

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

Benutzer sagt „Feishu veröffentlichen / module-map sync“ → Agent führt die obigen Befehle selbst aus und gibt die feishu_url zurück.

---

Veröffentlichungs-Sicherheitsgate (P0)

Hintergrund: PUBLISH_INCIDENTS.md · Vorfälle mit Überschreiben falscher Feishu-Dokumente.

Wenn eine Bedingung nicht erfüllt ist → STOPP, Veröffentlichung untersagt.

Checkliste vor der Veröffentlichung (Agent-Selbstprüfung)

• Cluster-Modus muss feishu_doc_state_<cluster>.json verwenden
• Verboten, stillschweigend feishu_doc_state.json als Ziel für Modul-Map-Veröffentlichungen zu verwenden
• Aus der module-map.md die feishu.cn/docx/<id> extrahieren – diese muss mit der document_id im Status übereinstimmen
• Zuerst --dry-run ausführen und prüfen, ob die Ausgabe publish_target: OK enthält
• Nach erfolgreicher Veröffentlichung: Nicht automatisch die Feishu-URL in module-map / README ändern (außer der Benutzer fordert explizit die Bindung eines neuen Dokuments)
• Für die menschliche Prüfung ausgeben: state_file · doc_id · module-map doc_id

Verboten

• ❌ Bei Cluster-Veröffentlichung feishu_doc_state.json als Ziel verwenden
• ❌ Aufgrund abweichender URL in der Veröffentlichungsausgabe und der module-map automatisch den Feishu-Link in der module-map ändern
• ❌ Ohne --dry-run zur Überprüfung von publish_target direkt die endgültige Veröffentlichung durchführen

---

Automatische OAuth-Wiederherstellung (P0 · Agent muss ausführen)

Wann wird sie ausgelöst

Fehlerschlüsselwort	Bedeutung
No user_access_token found	Kein Token
Authentication token expired / 99991677	access_token abgelaufen
invalid_grant / refresh token has been revoked	refresh_token ungültig

Standardablauf des Agenten

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

Der Agent muss:

1. Selbst oauth serve ausführen (kann im Hintergrund laufen + regelmäßig prüfen, bis „OAuth complete“ erscheint).
2. Den Benutzer informieren: „Im Browser wurde die Feishu-Autorisierungsseite geöffnet. Bitte klicken Sie einmal auf „Autorisieren“.“
3. Nach erfolgreicher Autorisierung sofort die ursprüngliche Aufgabe wiederholen.
4. Bei gemeinsam genutztem Token das neue feishu_tokens.json committen (App Secret nicht einchecken).

Verboten

• ❌ Nur ausgeben: „Bitte führen Sie zuerst oauth start / finish aus“ und den Benutzer die Terminal-Befehle selbst ausführen lassen
• ❌ Nach OAuth-Wiederherstellung den lokalen alten Token über das projektinterne feishu_tokens.json legen

---

Dokumentenklassifizierung

• Regeln: tools/feishu_doc_publisher/CLASSIFY.md
• Konfiguration: feishu_categories.json (von feishu_categories.json.example kopieren)
• Status angleichen: python3 cli.py reconcile-states
• Neue Kategorie erstellen: python3 setup_category.py <category> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

BugFix-Reparaturbeschreibung

Element	Wert
Kategorie	bugfix (oder projektspezifisch)
Erstellungsrichtlinie	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Cursor-Regel	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git behält den Quellcode ```mermaid bei
• Standard FEISHU_MERMAID_MODE=addons: ```mermaid → natives Feishu-Add-On „Text-to-Diagramm“-Flussdiagramm
• Bei Fehlschlag kann auf begleitendes PNG zurückgegriffen werden: docs/assets/<cluster>/

Umfang

• Erlaubte Änderungen: tools/feishu_doc_publisher/**, docs/**, .cursor/skills/feishu-doc-publish/**
• Nicht committen: .env (enthält Secret), feishu_tokens.json (Teamstrategie selbst festlegen), feishu_folders.json, feishu_wiki.json (lokaler Cache)