Jcchen2026/feishu-doc-publish

Publicación de documentos en Feishu (Feishu Doc Publisher)

Reglas generales del agente (lectura obligatoria)

1. Al recibir una tarea de publicación en Feishu → primero lee esta skill, luego ejecuta la CLI; no te limites a decirle al usuario que ejecute el comando.
2. OAuth caducado / sin token → El agente lo restaura automáticamente (ver §Restauración automática de OAuth); el usuario solo necesita hacer clic en "Autorizar" en el navegador.
3. Orden de búsqueda de credenciales (config.py ya lo implementa, el agente no debe duplicarlo):
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (dentro del proyecto, por defecto)
   • Si no existen → ~/.cursor/tools/feishu_doc_publisher/ o ~/.claude/tools/feishu_doc_publisher/ (anulación local)
4. Registry: tools/feishu_doc_publisher/clusters/registry.json (opcional; si no hay registry, se infiere según la convención docs/modules/<cluster>-module-map.md)

Instalación inicial (en el proyecto destino)

# Instalación en una línea (repositorio público)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /ruta/a/tu-repo

# O clonar e instalar
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/ruta/a/feishu-doc-publish/install.sh /ruta/a/tu-repo

Después de la instalación, configura .env y realiza OAuth una vez; consulta tools/feishu_doc_publisher/README.md.

Publicación estándar (Markdown individual)

cd tools/feishu_doc_publisher
python3 cli.py publish \
  --markdown ../../docs/guías/<archivo>.md \
  --title "<Título del documento en Feishu>" \
  --state-file feishu_doc_state_<slug>.json

Publicación estándar (module-map)

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

Cuando el usuario diga "publicar en Feishu / sincronizar module-map" → el agente ejecuta los comandos anteriores y devuelve feishu_url.

---

Puerta de seguridad de publicación (P0)

Contexto: PUBLISH_INCIDENTS.md · Accidente por sobrescritura de documentos no relacionados en Feishu.

Si no se cumple alguna de las condiciones → DETENER, prohibido publicar.

Lista de verificación previa a la publicación (autocomprobación del agente)

• Modo clúster debe usar feishu_doc_state_<clúster>.json
• Prohibido usar silenciosamente feishu_doc_state.json como destino de publicación para module-map
• Extraer de module-map.md feishu.cn/docx/<id> y debe coincidir con document_id en el state
• Ejecutar primero --dry-run y confirmar que la salida contiene publish_target: OK
• Después de publicar exitosamente: prohibido modificar automáticamente la URL de Feishu en module-map / README (a menos que el usuario solicite explícitamente vincular un nuevo documento)
• Mostrar para verificación humana: state_file · doc_id · module-map doc_id

Prohibido

• ❌ Usar feishu_doc_state.json como destino al publicar un clúster
• ❌ Porque la URL publicada sea diferente a la del module-map, modificar automáticamente el enlace de Feishu en el module-map
• ❌ Publicar directamente sin ejecutar --dry-run para validar publish_target

---

Restauración automática de OAuth caducado (P0 · El agente debe ejecutarlo)

Cuándo se activa

Palabra clave del error	Significado
No user_access_token found	Sin token
Authentication token expired / 99991677	access_token caducado
invalid_grant / refresh token has been revoked	refresh_token inválido

Procedimiento estándar del agente

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

El agente debe:

1. Ejecutar él mismo oauth serve (puede ser en segundo plano + sondeo hasta que aparezca "OAuth complete").
2. Informar al usuario: "Se ha abierto la página de autorización de Feishu en el navegador, solo haz clic en autorizar una vez".
3. Después de la autorización exitosa, reintentar inmediatamente la tarea original.
4. Si el token se comparte en equipo, hacer commit del nuevo feishu_tokens.json (no incluir el App Secret).

Prohibido

• ❌ Solo mostrar "Ejecuta primero oauth start / finish" y dejar que el usuario lo haga en su terminal
• ❌ Después de restaurar OAuth, sobrescribir feishu_tokens.json del proyecto con el token local antiguo

---

Clasificación de documentos

• Reglas: tools/feishu_doc_publisher/CLASSIFY.md
• Configuración: feishu_categories.json (copiar desde feishu_categories.json.example)
• Alinear estados: python3 cli.py reconcile-states
• Crear nueva categoría: python3 setup_category.py <categoría> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

Notas de corrección de bugs (BugFix)

Elemento	Valor
categoría	bugfix (o personalizado del proyecto)
Guía de redacción	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Regla de Cursor	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git conserva el código fuente de ```mermaid
• Por defecto FEISHU_MERMAID_MODE=addons: ```mermaid → se convierte en el diagrama de flujo nativo del add-on "Texto a diagrama" de Feishu
• Si falla, se puede usar un PNG complementario en docs/assets/<clúster>/

Alcance

• Permite modificar: tools/feishu_doc_publisher/**、docs/**、.cursor/skills/feishu-doc-publish/**
• No incluir en commit: .env (contiene Secret)、feishu_tokens.json (política del equipo)、feishu_folders.json、feishu_wiki.json (caché local)