HighBridgeDragon/jp-diet-minutes-skill

Skill de Pesquisa de Atas da Dieta Japonesa

Pesquise atas das sessões da Dieta Nacional do Japão desde sua fundação (1947) através da API do sistema de pesquisa de atas da NDL (Biblioteca Nacional da Dieta). Não requer autenticação. Utilize os wrappers bash scripts/<script>.sh.

Atas da Dieta Imperial (até 1947) não são cobertas, pois utilizam uma API separada.

Regras Básicas

• URL Base: https://kokkai.ndl.go.jp/api/
• Formato de Resposta: recordPacking=json (sempre forçado pelos wrappers)
• Autenticação: Não necessária
• Método de Chamada: Use bash scripts/<script>.sh. Não utilize WebFetch / Invoke-RestMethod diretamente, exceto para casos extremos não cobertos pelos wrappers (veja "Casos que exigem curl puro" abaixo)
• Limitação de Taxa: A documentação oficial afirma: "Ao acessar mecanicamente, múltiplas requisições simultâneas são proibidas; aguarde alguns segundos entre requisições." Proibido paralelizar; intervalo de 2 a 3 segundos entre chamadas consecutivas.
• Limite de Tamanho da Consulta: 2.000 bytes (caracteres japoneses codificados em URL equivalem a aproximadamente 9 bytes cada).

Seleção do Endpoint

Escolha o wrapper script apropriado de acordo com a solicitação do usuário. A quantidade de informação e o consumo de tokens aumentam na ordem list-meetings.sh < search-by-*.sh < fetch-meeting.sh; portanto, filtre progressivamente começando pelo mais leve.

"Mostre os discursos do deputado XX"
  → bash scripts/search-by-speaker.sh XX [de] [ate] [limite] --sort <chaves>
  ※ --sort é obrigatório. O valor padrão é date-desc (mais recente primeiro)

"Encontre discursos sobre YY"
  → bash scripts/search-by-keyword.sh YY [de] [ate] [limite] --sort <chaves>
  ※ Pesquisa "any" (operador AND). Múltiplas palavras-chave separadas por espaços simples. --sort é obrigatório.

"Extraia perguntas de especialistas (incluindo testemunhas e expositores)"
  → bash scripts/search-by-role.sh 参考人 [de] [ate] [limite] --sort <chaves>
  ※ role pode ser 証人 (testemunha), 参考人 (especialista) ou 公述人 (expositor). --sort é obrigatório.

"Mostre a lista de reuniões da comissão XX"
  → bash scripts/list-meetings.sh XX [de] [ate] [limite] --sort <chaves>
  ※ Leve. Retorna apenas metadados da reunião (não inclui o texto dos discursos). --sort é obrigatório (apenas date-asc / date-desc).

"Mostre todos os discursos de uma reunião específica" / "Texto completo da ata da comissão XX em YYYY-MM-DD"
  → Passo 1: Identifique o issueID da reunião com bash scripts/list-meetings.sh
  → Passo 2: bash scripts/fetch-meeting.sh <issueID>
  ※ Retorna a reunião completa em uma única requisição, por isso é grande. Chame somente após filtrar.

Consulte api-reference.md, parameters.md, response-format.md, recipes.md para detalhes.

Instruções de Uso de Cada Endpoint

1. search-by-speaker.sh — Busca de discursos por nome de parlamentar (uso mais frequente)

Retorna apenas os discursos que correspondem aos critérios de busca. É o mais eficiente em termos de tokens. --sort é obrigatório, e a estrutura força o usuário a especificar explicitamente a ordem de classificação da API (medida contra o problema #41).

# Extrai discursos do parlamentar (correspondência parcial OR), ordem decrescente por data
bash scripts/search-by-speaker.sh 岸田文雄 2024-01-01 2024-12-31 50 --sort date-desc

Para a especificação completa dos argumentos (incluindo detalhes sobre chaves de ordenação possíveis), consulte bash scripts/search-by-speaker.sh -h.

A resposta é um array speechRecord[]. Cada elemento contém metadados da reunião expandidos diretamente (como issueID, session, nameOfHouse, nameOfMeeting, date, etc.).

2. search-by-keyword.sh — Busca por palavra-chave (pesquisa "any", operador AND)

Pesquisa de texto completo no corpo dos discursos. Múltiplas palavras-chave separadas por espaços simples são combinadas com AND. --sort é obrigatório.

# Pesquisa AND: discursos contendo "マイナンバー" E "個人情報", ordem decrescente por data
bash scripts/search-by-keyword.sh 'マイナンバー 個人情報' 2024-01-01 2024-12-31 50 --sort date-desc

Consulte bash scripts/search-by-keyword.sh -h para a especificação completa dos argumentos. A estrutura da resposta é idêntica à de search-by-speaker.sh.

3. search-by-role.sh — Busca de discursos por função (perguntas de especialistas, etc.)

Filtra o papel do orador (speakerRole). Usado para extrair depoimentos de testemunhas, perguntas de especialistas e discursos de expositores. --sort é obrigatório.

# Apenas perguntas de especialistas, ordem decrescente por data
bash scripts/search-by-role.sh 参考人 2024-01-01 2024-12-31 50 --sort date-desc

role deve ser 証人 (testemunha), 参考人 (especialista) ou 公述人 (expositor). Caso contrário, a API retornará HTTP 400.

Consulte bash scripts/search-by-role.sh -h para a especificação completa dos argumentos.

4. list-meetings.sh — Lista de reuniões (índice leve)

Retorna apenas os metadados das reuniões. Não inclui o texto dos discursos, sendo ideal para gerar listas e filtrar. Usado para identificar issueID. --sort é obrigatório (apenas date-asc / date-desc).

# Lista da Comissão de Orçamento em uma data específica, ordem crescente por data
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-31 50 --sort date-asc

Consulte bash scripts/list-meetings.sh -h para a especificação completa dos argumentos.

A resposta é um meetingRecord[]. O array speechRecord[] dentro de cada elemento contém apenas um conjunto mínimo de metadados do discurso (speechID, speechOrder, speaker, speechURL). Para obter o texto, chame search-by-* ou fetch-meeting.sh.

5. fetch-meeting.sh — Texto completo da reunião (último recurso)

Retorna a reunião completa. É pesado, pois uma única requisição retorna todos os discursos. Deve ser chamado somente após identificar o issueID com list-meetings.sh.

# Obtém a ata completa da reunião pelo issueID
bash scripts/fetch-meeting.sh 121405254X00220241004

Consulte bash scripts/fetch-meeting.sh -h para a especificação dos argumentos. maximumRecords=1 é fixo (pois issueID é único). --sort não se aplica à obtenção de uma única reunião (se necessário, processe a saída com jq).

O speechRecord[] de fetch-meeting.sh inclui todos os campos (speech, speakerYomi, speakerGroup, speakerPosition, speakerRole, startPage, createTime/updateTime).

Guia de Economia de Tokens

bash scripts/fetch-meeting.sh pode gerar centenas de KB a MB por reunião. Diretrizes:

1. Prefira search-by-*.sh: Para discursos individuais, obtenha apenas as partes necessárias. Use bash scripts/fetch-meeting.sh somente quando o usuário solicitar explicitamente o "texto completo da reunião".
2. Especifique maximumRecords: O padrão de 30 é suficiente na maioria dos casos. Para obter muitos registros, aumente até o limite (search-by-*/list-meetings: 100, fetch-meeting: 10) para reduzir o número total de requisições.
3. Use a pesquisa em duas etapas: Primeiro, filtre o alvo com list-meetings.sh ou search-by-*.sh para obter o issueID; depois, se necessário, use fetch-meeting.sh para o texto completo. Não chame fetch-meeting.sh diretamente.
4. Retry com variações de notação quando o resultado for zero: Para nomes de parlamentares, tente 福島 みずほ / 福島瑞穂 / hiragana sequencialmente. Nomes de partidos/blocos devem ser o nome oficial completo (自民党 ❌ / 自由民主党 ✅).

Armadilhas na Filtragem de Resultados

Após obter a resposta, observe os seguintes pontos:

1. Linhas com speechOrder igual a 0 são cabeçalhos de informações da ata: São dados estruturais como agenda e itens pautados, não discursos reais. O speaker é fixo como 会議録情報. Exclua essas linhas ao contar discursos.
2. O valor de imageKind: Por padrão, além de 会議録 (ata), podem vir incluídos 目次 (índice), 索引 (índice remissivo), 附録 (apêndice) e 追録 (suplemento). Ao extrair discursos, filtre apenas as linhas onde imageKind é 会議録. Os parâmetros de requisição contentsAndIndex e supplementAndAppendix são false por padrão; especifique true apenas se desejar explicitamente incluí-los.
3. closing retorna null em vez de false: Em sessões ordinárias sem a bandeira de encerramento, o valor é null. Para determinar se é uma sessão de encerramento, compare com true (não compare com false).
4. Valores inválidos de nameOfHouse são ignorados silenciosamente: A resposta HTTP 200 pode conter resultados sem o filtro aplicado. Verifique a validade de numberOfRecords para confirmar se a intenção foi refletida.
5. As quebras de linha no texto do discurso são CRLF (\r\n): Não apenas LF. Pode ser necessário normalizar ao processar texto.
6. A estrutura da resposta de search-by-*.sh é plana: Não possui o wrapper meetingRecord como fetch-meeting.sh. É necessário um parser condicional se for escrever um parser comum.
7. A ordem de classificação da API é fixa em "decrescente por data da reunião": A especificação oficial garante que a ordem é decrescente e não há parâmetro de ordenação na API (válido para search-by-speaker / search-by-keyword / list-meetings / fetch-meeting). A opção --sort dos wrappers desta skill não é um parâmetro da API, mas um pós-processamento de ordenação no lado do cliente via jq (obrigatório em search-by-*.sh / list-meetings.sh). Embora útil, ao usar maximumRecords para recuperação parcial, apenas os N registros mais recentes são retornados.
   • Determinar o discurso mais recente: Use o início da recuperação parcial (maximumRecords=1 é suficiente).
   • Determinar o discurso mais antigo: Não assuma que o resultado parcial contém o mais antigo. Obtenha todos os registros via paginação até o final (numberOfRecords) ou restrinja o período com from/until até que o número de resultados seja ≤ maximumRecords, e então determine.
   • Ordenação secundária dentro do mesmo dia é speechOrder ascendente (baseado em medições, não documentado oficialmente): Se você tentar atingir o final com startRecord=<numberOfRecords>&maximumRecords=1 sem restringir o período, devido à ordenação decrescente fixa da API, obterá o último discurso do dia mais antigo (speechOrder máximo) do período, perdendo o verdadeiro primeiro discurso. Para obter com precisão o discurso mais antigo, restrinja o período com from/until até que numberOfRecords ≤ 100, obtenha todos os registros e use --sort date-asc,speech-order-asc do wrapper em uma única requisição (detalhes em recipes/oldest-speech-by-speaker.md).
8. O uso combinado de any e speaker resulta em interseção (redução significativa no número de resultados): Se o objetivo é pesquisar discursos do parlamentar A, especificar ambos como any=A&speaker=A restringirá apenas aos discursos que satisfazem ambas as condições (discursos do próprio A que contêm seu nome), reduzindo drasticamente o número em comparação com cada parâmetro isoladamente (medição: speaker=石原慎太郎 sozinho: 2.098 resultados vs. combinado: 647). Use speaker sozinho para todos os discursos do parlamentar A e any sozinho para menções a A. Consulte a seção relevante do parameters.md e recipes/speaker-vs-any-disambiguation.md para uso por intenção.
9. O "número de resultados" no erro (19004)startRecord fora do intervalo refere-se ao numberOfRecords da mesma consulta: A mensagem de erro (19004) Por favor, especifique um valor entre 1 e o número de resultados para startRecord. O "número de resultados" refere-se ao numberOfRecords da mesma consulta (baseado em medições, não explicitamente documentado). Usar um valor de numberOfRecords obtido de uma consulta diferente (pesquisa simples sem from/until, speaker sozinho vs. combinado, valores em cache) para definir startRecord resultará no erro 19004. Para diagnosticar, faça uma requisição com a mesma consulta usando startRecord=1&maximumRecords=1 e verifique o numberOfRecords. Isso é comum quando o número de resultados diminui devido à interseção (item 8) ou à adição de from/until (detalhes em api-reference.md seção 19004).

Exemplos de Padrões de Pesquisa Comuns

Discursos de um parlamentar em um período específico

bash scripts/search-by-speaker.sh 石破茂 2024-10-01 2024-10-31 100 --sort date-desc

Acompanhamento da tramitação de um projeto de lei (linha do tempo)

bash scripts/search-by-keyword.sh マイナンバー法 2023-01-01 '' 100 --sort date-asc

Extração de discursos do Primeiro-Ministro

O argumento speakerPosition não é suportado pelos wrappers; use curl puro:

# Não suportado pelos wrappers; use curl puro
curl -s 'https://kokkai.ndl.go.jp/api/speech?speakerPosition=%E5%86%85%E9%96%A3%E7%B7%8F%E7%90%86%E5%A4%A7%E8%87%A3&nameOfMeeting=%E6%9C%AC%E4%BC%9A%E8%AD%B0&from=2024-01-01&recordPacking=json'

Perguntas de especialistas

bash scripts/search-by-role.sh 参考人 2024-01-01 '' 100 --sort date-desc

Texto completo de uma ata de reunião específica (duas etapas)

# Passo 1: Identificar issueID (filtro nameOfHouse não suportado pelos wrappers, selecione manualmente da lista)
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-01 50 --sort date-desc

# Passo 2: Obter texto completo
bash scripts/fetch-meeting.sh <issueID>

Paginação

Comum a todos os endpoints.

• Passe o nextRecordPosition da resposta como startRecord na próxima requisição.
• Determinação da última página:
  • JSON: O valor de nextRecordPosition é null
  • XML: O elemento <nextRecordPosition> está ausente
• Aguarde alguns segundos entre requisições consecutivas (limitação de taxa).

Formato de Saída

Formato recomendado para apresentar discursos ao usuário:

【Orador】XXXX (partido/bloco, cargo)
【Reunião】XXXª Sessão da Dieta, Câmara dos Representantes, Comissão XX, Nº X (YYYY-MM-DD)
【Discurso】
Citação do texto do discurso (normalizar CRLF para quebra de linha)

【Fonte】Sistema de Pesquisa de Atas da Dieta https://kokkai.ndl.go.jp/txt/<issueID>/<speechOrder>

Ao apresentar uma lista de reuniões:

【Lista de Reuniões】N itens
- YYYY-MM-DD: XXXª Sessão da Dieta, Câmara dos Representantes, Comissão XX, Nº X
  https://kokkai.ndl.go.jp/txt/<issueID>
- ...

Casos que Exigem curl Puro

Os seguintes parâmetros não são cobertos pelos wrappers scripts. Quando necessário, use curl / Invoke-RestMethod diretamente na API:

• sessionFrom / sessionTo (filtrar por número de sessão)
• contentsAndIndex / supplementAndAppendix (índice, apêndice)
• closing=true (sessões de encerramento apenas)
• Filtros secundários como nameOfHouse / nameOfMeeting (não incluídos como argumentos dos wrappers)
• Paginação (chamadas consecutivas com startRecord + nextRecordPosition)
• Especificação simultânea de any e speaker (para usar intencionalmente a interseção, como autorreferência do próprio parlamentar. Consulte o padrão 3 de recipes/speaker-vs-any-disambiguation.md)

Exemplo: Extrair apenas a Comissão de Orçamento da 213ª Sessão (requer sessionFrom/sessionTo, não suportado pelos wrappers)

curl -s 'https://kokkai.ndl.go.jp/api/meeting_list?sessionFrom=213&sessionTo=213&nameOfMeeting=%E4%BA%88%E7%AE%97%E5%A7%94%E5%93%A1%E4%BC%9A&maximumRecords=30&recordPacking=json'

Ferramentas que utilizam modelos de sumarização interna, como WebFetch, podem introduzir campos inexistentes na resposta como alucinações. Portanto, não as use para obter dados brutos (consulte response-format.md para detalhes).

Referências Detalhadas

• api-reference.md: Especificações do endpoint, paginação e respostas de erro
• parameters.md: Especificação completa dos parâmetros de busca, modos de pesquisa e exemplos de combinação
• response-format.md: Estrutura da resposta, exemplos de JSON reais e armadilhas baseadas em medição
• recipes.md: Padrões compostos (ex.: filtragem por parlamentar × palavra-chave, que os scripts não cobrem)