Publication de documents Feishu

Publication de documents Feishu (Feishu Doc Publisher)

Règles générales pour l'agent (à lire impérativement)

1. Quand une tâche de publication Feishu se présente → lire d'abord cette compétence, puis exécuter la CLI ; ne pas se contenter de dire à l'utilisateur d'exécuter la commande.
2. Expiration OAuth / absence de token → l'agent rétablit automatiquement (voir §Rétablissement automatique OAuth) ; l'utilisateur n'a qu'à cliquer sur « Autoriser » dans le navigateur.
3. Ordre de recherche des identifiants (déjà implémenté dans config.py, l'agent ne doit pas recopier) :
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (dans le projet, par défaut)
   • Si absent → ~/.cursor/tools/feishu_doc_publisher/ ou ~/.claude/tools/feishu_doc_publisher/ (surcharge locale)
4. Registre : tools/feishu_doc_publisher/clusters/registry.json (facultatif ; sans registre, déduction basée sur la convention docs/modules/<cluster>-module-map.md)

Installation initiale (dans le projet cible)

# Installation en une ligne (dépôt public)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /chemin/vers/votre-repo

# Ou après clonage
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/chemin/vers/feishu-doc-publish/install.sh /chemin/vers/votre-repo

Après l'installation, configurez le fichier .env et effectuez une authentification OAuth initiale. Voir tools/feishu_doc_publisher/README.md.

Publication standard (document Markdown unique)

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

Publication standard (module-map)

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

Quand l'utilisateur dit « publier sur Feishu / synchroniser module-map » → l'agent exécute lui-même ces commandes et renvoie feishu_url.

---

Barrière de sécurité de publication (P0)

Contexte : PUBLISH_INCIDENTS.md · Incident de réécriture accidentelle de documents Feishu non concernés.

Si une condition n'est pas remplie → STOP, publication interdite.

Liste de vérification avant publication (auto-contrôle de l'agent)

• Mode cluster doit utiliser feishu_doc_state_<cluster>.json
• Interdiction d'utiliser silencieusement feishu_doc_state.json comme cible de publication pour module-map
• Extraire feishu.cn/docx/<id> depuis module-map.md, qui doit correspondre à document_id dans le fichier d'état
• Exécuter d'abord --dry-run, vérifier que la sortie contient publish_target: OK
• Après publication réussie : ne pas modifier automatiquement l'URL Feishu dans module-map / README (sauf demande explicite de l'utilisateur de lier un nouveau document)
• Afficher pour vérification humaine : state_file · doc_id · module-map doc_id

Interdictions

• ❌ Utiliser feishu_doc_state.json comme cible lors d'une publication cluster
• ❌ Modifier automatiquement le lien Feishu dans module-map parce que l'URL de sortie de publication diffère de celle de module-map
• ❌ Effectuer une publication réelle sans --dry-run pour valider publish_target

---

Rétablissement automatique de l'authentification OAuth (P0 · L'agent doit exécuter)

Quand déclencher

Mot-clé d'erreur	Signification
No user_access_token found	Aucun token
Authentication token expired / 99991677	access_token expiré
invalid_grant / refresh token has been revoked	refresh_token invalide

Procédure standard pour l'agent

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

L'agent doit :

1. Lui-même exécuter oauth serve (peut être en arrière-plan avec une boucle d'attente jusqu'à ce que OAuth complete soit affiché).
2. Informer l'utilisateur : « La page d'autorisation Feishu s'est ouverte dans le navigateur. Veuillez cliquer une fois sur Autoriser. »
3. Une fois l'autorisation réussie, réessayer immédiatement la tâche d'origine.
4. Pour les tokens partagés en équipe, commiter le nouveau feishu_tokens.json (ne pas commiter le App Secret).

Interdictions

• ❌ Se contenter d'afficher « Veuillez d'abord exécuter oauth start / finish » en laissant l'utilisateur opérer lui-même dans le terminal
• ❌ Après rétablissement OAuth, écraser le feishu_tokens.json du projet avec un ancien token local

---

Classification des documents

• Règles : tools/feishu_doc_publisher/CLASSIFY.md
• Configuration : feishu_categories.json (à copier depuis feishu_categories.json.example)
• Alignement des états : python3 cli.py reconcile-states
• Création d'une nouvelle catégorie : python3 setup_category.py <catégorie> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

Descriptions de corrections de bugs (BugFix)

Élément	Valeur
catégorie	bugfix (ou personnalisée selon le projet)
Règles de rédaction	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Règle Cursor	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git conserve le code source ```mermaid
• Par défaut FEISHU_MERMAID_MODE=addons : ```mermaid → transformé en diagramme natif Feishu via le module complémentaire « Dessin de texte »
• En cas d'échec, fallback avec une image PNG associée : docs/assets/<cluster>/

Périmètre

• Modifications autorisées : tools/feishu_doc_publisher/**, docs/**, .cursor/skills/feishu-doc-publish/**
• Ne pas commiter : .env (contient le Secret), feishu_tokens.json (la politique d'équipe décide), feishu_folders.json, feishu_wiki.json (cache local)