Jcchen2026/feishu-doc-publish

Publicador de Documentos Feishu (Feishu Doc Publisher)

Regras Gerais do Agent (Leitura Obrigatória)

1. Ao receber uma tarefa de publicação no Feishu → Leia este skill primeiro, depois execute a CLI; não se limite a informar o usuário para rodar o comando.
2. OAuth expirado / sem token → O Agent restaura automaticamente (veja §Restauração Automática de OAuth); o usuário só precisa clicar em "Autorizar" no navegador.
3. Ordem de busca de credenciais (já implementada em config.py, Agent não deve replicar):
   • tools/feishu_doc_publisher/.env + feishu_tokens.json (dentro do projeto, padrão)
   • Se não existir → ~/.cursor/tools/feishu_doc_publisher/ ou ~/.claude/tools/feishu_doc_publisher/ (sobrescrita local)
4. Registry: tools/feishu_doc_publisher/clusters/registry.json (opcional; sem registry, inferir conforme convenção docs/modules/<cluster>-module-map.md)

Instalação Inicial (Projeto Alvo)

# Instalação em uma linha (repositório público)
curl -fsSL https://raw.githubusercontent.com/Jcchen2026/feishu-doc-publish/main/install.sh | bash -s -- /caminho/para/seu-repo

# Ou clonar e instalar
git clone https://github.com/Jcchen2026/feishu-doc-publish.git
/caminho/para/feishu-doc-publish/install.sh /caminho/para/seu-repo

Após a instalação, configure .env e faça OAuth uma vez, veja tools/feishu_doc_publisher/README.md.

Publicação Padrão (Markdown Único)

cd tools/feishu_doc_publisher
python3 cli.py publish \
  --markdown ../../docs/guides/<arquivo>.md \
  --title "<Título do Documento Feishu>" \
  --state-file feishu_doc_state_<slug>.json

Publicação Padrão (module-map)

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

Quando o usuário disser "publicar no Feishu / sincronizar module-map" → O Agent executa os comandos acima, retornando o feishu_url.

---

Portão de Segurança para Publicação (P0)

Contexto: PUBLISH_INCIDENTS.md · Incidente de sobrescrita acidental de documento Feishu não relacionado.

Se qualquer condição não for satisfeita → PARE, publicação proibida.

Checklist Pré-publicação (Auto-verificação do Agent)

• No modo cluster, use obrigatoriamente feishu_doc_state_<cluster>.json
• Proibido usar feishu_doc_state.json silenciosamente como destino de publicação de module-map
• Extrair feishu.cn/docx/<id> do module-map.md e verificar se é idêntico ao document_id no state
• Executar primeiro --dry-run e confirmar que a saída contém publish_target: OK
• Após publicação bem-sucedida: proibido modificar automaticamente a URL do Feishu no module-map / README (a menos que o usuário solicite explicitamente vincular um novo documento)
• Exibir para verificação humana: state_file · doc_id · module-map doc_id

Proibido

• ❌ Usar feishu_doc_state.json como destino ao publicar em cluster
• ❌ Alterar automaticamente o link do Feishu no module-map porque a URL de saída da publicação é diferente da do module-map
• ❌ Publicar diretamente sem --dry-run para validar publish_target

---

Restauração Automática de OAuth (P0 · Obrigatório para o Agent)

Quando Acionar

Palavra-chave de Erro	Significado
No user_access_token found	Sem token
Authentication token expired / 99991677	access_token expirado
invalid_grant / refresh token has been revoked	refresh_token inválido

Fluxo Padrão do Agent

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

O Agent DEVE:

1. Executar ele mesmo oauth serve (pode ser em background + polling até OAuth complete).
2. Informar ao usuário: "O navegador já foi aberto na página de autorização do Feishu. Clique em autorizar uma vez."
3. Após autorização bem-sucedida, repetir imediatamente a tarefa original.
4. Para token compartilhado em equipe, fazer commit do novo feishu_tokens.json (não submeter App Secret).

Proibido

• ❌ Apenas exibir "Por favor, execute oauth start/finish" e deixar o usuário operar no terminal
• ❌ Sobrescrever o feishu_tokens.json do projeto com token antigo local após restauração de OAuth

---

Classificação de Documentos

• Regras: tools/feishu_doc_publisher/CLASSIFY.md
• Configuração: feishu_categories.json (copiar de feishu_categories.json.example)
• Alinhar state: python3 cli.py reconcile-states
• Criar nova categoria: python3 setup_category.py <categoria> --drive-name "..." --wiki-name "..." --wiki-root-node <token>

Descrição de Correção de Bug (BugFix)

Item	Valor
categoria	bugfix (ou personalizado do projeto)
Especificação de escrita	tools/feishu_doc_publisher/BUGFIX_DOC_WRITING.md
Regra do Cursor	.cursor/rules/feishu-bugfix-doc-writing.mdc

---

Mermaid

• Git mantém o código fonte ```mermaid
• Padrão FEISHU_MERMAID_MODE=addons: ```mermaid → Diagrama nativo do Feishu via add_ons "Desenho de Texto"
• Em caso de falha, fallback para PNG acompanhante: docs/assets/<cluster>/

Escopo

• Modificações permitidas: tools/feishu_doc_publisher/**, docs/**, .cursor/skills/feishu-doc-publish/**
• Não submeter: .env (contém Secret), feishu_tokens.json (política de equipe a definir), feishu_folders.json, feishu_wiki.json (cache local)