blog-notebooklm

Blog NotebookLM -- Pesquisa com Base em Fontes de Seus Documentos

Consulte notebooks do Google NotebookLM diretamente do Claude Code para obter respostas com citações baseadas no Gemini. Cada pergunta abre uma sessão de navegador headless, recupera a resposta exclusivamente de seus documentos carregados e fecha. As respostas são de Nível 1 (fontes primárias do próprio usuário) -- risco zero de alucinação.

Referência Rápida

Comando	O que faz
/blog notebooklm ask <pergunta>	Consulta um notebook para respostas com base em fontes
/blog notebooklm discover <url>	Descobre inteligentemente o conteúdo do notebook antes de catalogar
/blog notebooklm library list	Lista todos os notebooks na biblioteca
/blog notebooklm library add <url>	Adiciona um notebook à biblioteca
/blog notebooklm library search <consulta>	Pesquisa notebooks por palavra-chave
/blog notebooklm library remove <id>	Remove um notebook da biblioteca
/blog notebooklm setup	Autenticação única no Google (navegador visível)
/blog notebooklm status	Verifica o status da autenticação
/blog notebooklm cleanup	Limpa o estado do navegador (preserva a biblioteca)

Pré-requisitos

• Conta do Google com acesso ao NotebookLM
• Python 3.11+ (venv gerenciado automaticamente pelo run.py)
• Google Chrome (instalado automaticamente na primeira execução via Patchright)
• Configuração de autenticação única (login interativo no Google em navegador visível)

Sempre Use o Wrapper run.py

NUNCA chame scripts diretamente. SEMPRE use python3 scripts/run.py [script]:

# CORRETO:
python3 scripts/run.py auth_manager.py status
python3 scripts/run.py ask_question.py --question "..."

# ERRADO -- falha sem venv:
python3 scripts/auth_manager.py status

O wrapper run.py cria automaticamente .venv, instala dependências, configura o Chrome e executa o script de destino.

Verificação de Autenticação (Padrão Gate)

Antes de qualquer operação de consulta, verifique a autenticação:

python3 scripts/run.py auth_manager.py status

• Se autenticado: prossiga com a consulta
• Se não autenticado: informe o usuário e oriente para configuração: "NotebookLM requer login do Google. Execute /blog notebooklm setup para autenticar."
• Quando chamado internamente (do blog-write ou blog-researcher): retorne silenciosamente sem erro se não estiver autenticado. Nunca bloqueie o fluxo de escrita.

Fluxo de Configuração

Para /blog notebooklm setup:

# Abre um navegador visível para login manual no Google (uma única vez)
python3 scripts/run.py auth_manager.py setup

Diga ao usuário: "Uma janela do navegador será aberta. Por favor, faça login na sua conta do Google." A autenticação persiste via perfil do navegador + injeção de cookies (abordagem híbrida).

Outros comandos de autenticação:

python3 scripts/run.py auth_manager.py status   # Verificar auth
python3 scripts/run.py auth_manager.py reauth   # Reautenticar
python3 scripts/run.py auth_manager.py clear     # Limpar todos os dados de auth

Fluxo de Consulta

Para /blog notebooklm ask <pergunta>:

Etapa 1: Verificar Autenticação

Execute a verificação de auth (consulte o padrão gate acima). Se não estiver autenticado, oriente para configuração.

Etapa 2: Resolver Notebook

Determine qual notebook consultar:

• Se --notebook-url fornecido: use diretamente
• Se --notebook-id fornecido: procure na biblioteca
• Se nenhum: use o notebook ativo da biblioteca
• Se não houver notebook ativo: mostre a biblioteca e peça ao usuário para selecionar

Etapa 3: Faça a Pergunta

# Consulta básica (usa o notebook ativo)
python3 scripts/run.py ask_question.py --question "Sua pergunta aqui"

# Consultar notebook específico por ID
python3 scripts/run.py ask_question.py --question "..." --notebook-id id-do-notebook

# Consultar por URL diretamente
python3 scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

# Saída JSON (para uso interno/programático)
python3 scripts/run.py ask_question.py --question "..." --json

# Mostrar navegador para depuração
python3 scripts/run.py ask_question.py --question "..." --show-browser

Etapa 4: Analisar e Acompanhar

Toda resposta termina com um prompt de acompanhamento. Comportamento obrigatório:

1. PARE -- não responda imediatamente ao usuário
2. ANALISE -- compare a resposta com a solicitação original do usuário
3. IDENTIFIQUE LACUNAS -- determine se mais informações são necessárias
4. FAÇA ACOMPANHAMENTO -- se houver lacunas, faça imediatamente uma pergunta de acompanhamento
5. REPITA -- continue até que a informação esteja completa
6. SINTETIZE -- combine todas as respostas antes de responder ao usuário

Fluxo de Descoberta Inteligente

Para /blog notebooklm discover <url>:

Ao adicionar um notebook sem saber seu conteúdo, consulte-o primeiro:

# Etapa 1: Descobrir conteúdo
python3 scripts/run.py ask_question.py \
  --question "Qual é o conteúdo deste notebook? Quais tópicos são abordados? Forneça uma visão geral completa de forma breve e concisa" \
  --notebook-url "<URL>"

# Etapa 2: Adicionar com metadados descobertos
python3 scripts/run.py notebook_manager.py add \
  --url "<URL>" \
  --name "<Baseado no conteúdo>" \
  --description "<Baseado no conteúdo>" \
  --topics "<Tópicos extraídos>"

NUNCA adivinhe ou use descrições genéricas. Sempre descubra ou pergunte ao usuário.

Gerenciamento da Biblioteca

# Listar todos os notebooks
python3 scripts/run.py notebook_manager.py list

# Adicionar notebook (todos os parâmetros obrigatórios -- descubra ou pergunte ao usuário!)
python3 scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Nome Descritivo" \
  --description "O que este notebook contém" \
  --topics "topico1,topico2,topico3"

# Pesquisar por palavra-chave
python3 scripts/run.py notebook_manager.py search --query "palavra-chave"

# Definir notebook ativo
python3 scripts/run.py notebook_manager.py activate --id id-do-notebook

# Remover notebook
python3 scripts/run.py notebook_manager.py remove --id id-do-notebook

# Estatísticas da biblioteca
python3 scripts/run.py notebook_manager.py stats

API Interna (para blog-write / blog-researcher)

Quando invocado como um subagente de Tarefa do blog-write ou blog-researcher:

Entrada (fornecida pela skill chamadora):

• question: Pergunta de pesquisa relevante ao tópico do blog
• notebook_id ou notebook_url: Qual notebook consultar
• context: "internal" (sinaliza modo de fallback gracioso)

Processo:

1. Verifique o status de autenticação -- se não autenticado, retorne resultado vazio silenciosamente
2. Consulte o notebook com a pergunta de pesquisa
3. Analise e retorne resposta estruturada

Saída (retornada para a skill chamadora):

### Pesquisa NotebookLM
- **Fonte:** [Nome do notebook]
- **Pergunta:** [O que foi perguntado]
- **Resposta:** [Resposta com base em fontes dos documentos do usuário]
- **Qualidade da Fonte:** Nível 1 (documentos primários carregados pelo usuário)

Fallback gracioso: Se a autenticação estiver ausente ou a consulta falhar, retorne imediatamente sem erro. O fluxo da skill chamadora continua com pesquisa baseada em WebSearch. Nunca bloqueie blog-write ou blog-rewrite porque o NotebookLM não está disponível.

Armazenamento de Dados

Todos os dados armazenados dentro do diretório da skill:

• scripts/data/library.json -- Metadados e biblioteca de notebooks
• scripts/data/auth_info.json -- Status de autenticação
• scripts/data/browser_state/ -- Perfil do Chrome com cookies

Segurança: Todos os diretórios de dados são gitignorados. Nunca confirme autenticação ou estado do navegador.

Tratamento de Erros

Erro	Resolução
Não autenticado	Execute /blog notebooklm setup
ModuleNotFoundError	Sempre use o wrapper run.py
Falha no navegador	cleanup_manager.py --confirm --preserve-library, depois reautentique
Limite de taxa (50/dia)	Aguarde até meia-noite PST ou mude de conta do Google
Notebook não encontrado	Verifique com notebook_manager.py list
Tempo limite da consulta (120s)	Tente novamente com pergunta mais simples ou --show-browser para depurar
MCP indisponível (interno)	Retorne silenciosamente -- o fluxo de escrita usa WebSearch

Limitações

• Sem persistência de sessão (cada pergunta = nova sessão de navegador)
• Limites de taxa em contas gratuitas do Google (50 consultas/dia)
• Upload manual necessário (o usuário deve adicionar documentos à interface web do NotebookLM)
• Sobrecarga do navegador (alguns segundos por pergunta para inicialização + encerramento)
• Apenas Claude Code local (não disponível na interface web)

Documentação de Referência

Carregue sob demanda -- NÃO carregue tudo na inicialização:

• references/commands.md -- Comandos CLI completos, parâmetros e padrões de fluxo de trabalho
• references/troubleshooting.md -- Soluções de erros, procedimentos de recuperação, depuração