HighBridgeDragon/jp-diet-minutes-skill

Skill de Búsqueda de Actas de la Dieta Nacional (Kokkai)

Investiga las actas de la Dieta japonesa desde su fundación en 1947 a través de la API del sistema de búsqueda de actas de la NDL (Biblioteca Nacional de la Dieta). No requiere autenticación. Se invoca mediante el wrapper bash scripts/<script>.sh.

Las actas de la Dieta Imperial (hasta 1947) quedan excluidas al ser una API separada.

Reglas Básicas

• URL Base: https://kokkai.ndl.go.jp/api/
• Formato de respuesta: recordPacking=json (el script wrapper lo fuerza siempre)
• Autenticación: No requiere
• Método de invocación: Usar bash scripts/<script>.sh. No usar directamente WebFetch / Invoke-RestMethod a menos que sea un caso extremo no cubierto por el wrapper (ver sección "Casos que requieren curl directo" más abajo)
• Límite de tasa: La NDL establece explícitamente "prohibición de múltiples solicitudes simultáneas; dejar intervalos de varios segundos para acceso mecánico". Prohibido paralelizar; dejar intervalos de 2 a 3 segundos entre llamadas consecutivas.
• Límite de tamaño de consulta: 2000 bytes como máximo (japonés equivale a 9 bytes por carácter con URL-encoding).

Selección de Endpoint

Elige el script wrapper adecuado según la solicitud del usuario. La cantidad de información y el consumo de tokens aumentan en el orden list-meetings.sh < search-by-*.sh < fetch-meeting.sh, por lo tanto, reduce gradualmente desde el más ligero.

"Muéstrame los discursos del Sr./Sra. [Nombre]"
  → bash scripts/search-by-speaker.sh [Nombre] [from] [until] [limit] --sort <claves>
  ※ --sort es obligatorio. El valor representativo es date-desc (más reciente primero)

"Busca discursos sobre [Tema]"
  → bash scripts/search-by-keyword.sh [Tema] [from] [until] [limit] --sort <claves>
  ※ Búsqueda 'any' (AND). Varias palabras clave separadas por espacio. --sort obligatorio

"Extrae preguntas de testigos (incluye declaraciones de peritos y expositores)"
  → bash scripts/search-by-role.sh 参考人 [from] [until] [limit] --sort <claves>
  ※ role puede ser 証人 / 参考人 / 公述人. --sort obligatorio

"Muéstrame la lista de reuniones de la comisión [Nombre]"
  → bash scripts/list-meetings.sh [NombreComision] [from] [until] [limit] --sort <claves>
  ※ Ligero. Solo devuelve metadatos de la reunión (sin discursos). `--sort` obligatorio (solo `date-asc` / `date-desc`)

"Muéstrame todos los discursos de una reunión específica" / "Acta completa de la comisión [Nombre] del YYYY-MM-DD"
  → Paso 1: Identificar el issueID con `bash scripts/list-meetings.sh`
  → Paso 2: `bash scripts/fetch-meeting.sh <issueID>`
  ※ Devuelve el acta completa en una sola solicitud, por lo que es grande. Llámalo solo después de haber acotado.

Para más detalles, consulta api-reference.md, parameters.md, response-format.md, recipes.md.

Uso de Cada Endpoint

1. search-by-speaker.sh — Búsqueda de discursos por nombre de legislador (más usado)

Devuelve solo los discursos que coinciden con los criterios de búsqueda. Es el más eficiente en tokens. --sort es obligatorio, y la estructura del script fuerza al usuario a ser consciente explícitamente del orden de ordenación de la API (medida contra #41).

# Extraer discursos por nombre de legislador (coincidencia parcial O), orden descendente por fecha
bash scripts/search-by-speaker.sh 岸田文雄 2024-01-01 2024-12-31 50 --sort date-desc

Para la especificación completa de argumentos (incluidos detalles de las claves de ordenación posibles), consulta bash scripts/search-by-speaker.sh -h.

La respuesta es un array speechRecord[]. Cada elemento contiene los metadatos de la reunión (issueID, session, nameOfHouse, nameOfMeeting, date, etc.) de forma plana.

2. search-by-keyword.sh — Búsqueda por palabra clave (búsqueda 'any', AND)

Búsqueda de texto completo sobre el cuerpo del discurso. Varias palabras clave se combinan con AND separadas por espacio. --sort obligatorio.

# Búsqueda AND: discursos que contengan "マイナンバー" Y "個人情報", orden descendente por fecha
bash scripts/search-by-keyword.sh 'マイナンバー 個人情報' 2024-01-01 2024-12-31 50 --sort date-desc

Para la especificación completa, consulta bash scripts/search-by-keyword.sh -h. La estructura de la respuesta es idéntica a search-by-speaker.sh.

3. search-by-role.sh — Búsqueda por rol (preguntas de testigos, etc.)

Filtra a los oradores por speakerRole. Se utiliza para extraer declaraciones de testigos, preguntas de peritos o intervenciones de expositores. --sort obligatorio.

# Solo preguntas de peritos, orden descendente por fecha
bash scripts/search-by-role.sh 参考人 2024-01-01 2024-12-31 50 --sort date-desc

El role puede ser 証人 / 参考人 / 公述人. Si se especifica otro valor, la API devolverá un error HTTP 400.

Para la especificación completa, consulta bash scripts/search-by-role.sh -h.

4. list-meetings.sh — Listado de reuniones (índice ligero)

Devuelve solo metadatos de la reunión. No incluye el texto de los discursos, por lo que es adecuado para generar listas y acotar. Se utiliza para identificar el issueID. --sort obligatorio (solo date-asc / date-desc).

# Listado de la Comisión de Presupuestos en una fecha específica, orden ascendente por fecha
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-31 50 --sort date-asc

Para la especificación completa, consulta bash scripts/list-meetings.sh -h.

La respuesta es un meetingRecord[]. El array speechRecord[] bajo cada elemento contiene solo el conjunto mínimo de metadatos del discurso (speechID, speechOrder, speaker, speechURL). Para obtener el texto completo, llama a search-by-* o fetch-meeting.sh.

5. fetch-meeting.sh — Acta de reunión completa (último recurso)

Devuelve el acta completa de la reunión. Es pesada porque devuelve todos los discursos en una sola solicitud. Asegúrate de identificar el issueID con list-meetings.sh antes de llamarla.

# Obtener acta completa por issueID
bash scripts/fetch-meeting.sh 121405254X00220241004

Para la especificación de argumentos, consulta bash scripts/fetch-meeting.sh -h. maximumRecords=1 fijo (porque el issueID es único). --sort no aplica para la obtención de una sola reunión (si es necesario, procesa posteriormente la salida con jq).

El speechRecord[] de fetch-meeting.sh incluye todos los campos (speech, speakerYomi, speakerGroup, speakerPosition, speakerRole, startPage, createTime/updateTime).

Guía de Ahorro de Tokens

bash scripts/fetch-meeting.sh puede ser de cientos de KB a MB por reunión. Puntos a cumplir:

1. Priorizar search-by-*.sh: Si se necesitan discursos individuales, se obtiene solo la parte necesaria. Usar bash scripts/fetch-meeting.sh solo cuando el usuario solicite explícitamente "el acta completa"
2. Especificar maximumRecords explícitamente: Se puede omitir si el valor predeterminado de 30 es suficiente. Para obtener muchos resultados, aumentar hasta el límite superior (search-by-*/list-meetings: 100, fetch-meeting: 10) para reducir el número total de solicitudes
3. Usar búsqueda de dos etapas: Primero acotar el objetivo con list-meetings.sh o search-by-*.sh para obtener el issueID, luego llamar a fetch-meeting.sh para el acta completa si es necesario. No llamar directamente a fetch-meeting.sh desde el principio
4. Reintentar con variaciones ortográficas si hay 0 resultados: Probar nombres de legisladores con 福島 みずほ / 福島瑞穂 / hiragana secuencialmente. Para nombres de grupos parlamentarios, usar siempre el nombre oficial (自民党 ❌ / 自由民主党 ✅)

Errores Comunes en el Filtrado de Resultados

Tras obtener la respuesta, presta atención a los siguientes puntos:

1. Las filas con speechOrder igual a 0 son la cabecera de información del acta: Contienen información estructural como el orden del día, etc., no son discursos reales. El speaker es fijo como 会議録情報. Al contar discursos, excluye las filas con speechOrder igual a 0
2. Valor de imageKind: Por defecto, además de 会議録, se mezclan 目次 / 索引 / 附録 / 追録. Al extraer discursos, filtra solo las filas con imageKind igual a 会議録 (los parámetros de solicitud contentsAndIndex / supplementAndAppendix son false por defecto, por lo que normalmente se pueden omitir. Especificar true solo si se desea incluirlos explícitamente)
3. closing devuelve null en lugar de false: En sesiones ordinarias sin bandera de sesión cerrada, devuelve null. La determinación de si es una sesión cerrada se realiza solo cuando el valor de closing es true (no comparar con false, usar comparación con true)
4. Los valores no válidos de nameOfHouse se ignoran silenciosamente: La API devuelve un HTTP 200 con resultados sin aplicar el filtro. Verificar la validez de numberOfRecords para confirmar que la intención se ha reflejado
5. Los saltos de línea en el texto del discurso son CRLF (\r\n): No solo LF. Puede ser necesario normalizar al procesar texto
6. La estructura de respuesta de search-by-*.sh es plana: No tiene un wrapper meetingRecord como fetch-meeting.sh. Es necesario bifurcar la lógica si se escribe un parser común
7. El orden de ordenación de la API es fijo "descendente por fecha de la reunión": La especificación oficial garantiza que el orden es descendente y no existe un parámetro de ordenación en la API (igual para search-by-speaker, search-by-keyword, list-meetings y fetch-meeting). El --sort del script wrapper de esta skill no es un parámetro de la API, sino un procesamiento secundario de ordenación en el cliente a través de jq (obligatorio en search-by-*.sh / list-meetings.sh). Aunque es útil, hay que tener en cuenta que al obtener un subconjunto con maximumRecords, solo se devuelven las N más recientes.
   • Determinar el discurso más reciente: Basta con el primer resultado del subconjunto (maximumRecords=1 es suficiente)
   • Determinar el discurso más antiguo: No afirmar que el resultado del subconjunto sea el más antiguo. Obtener todos los registros hasta el final de la paginación con numberOfRecords, o acotar el período con from/until hasta que el número de resultados sea ≤ maximumRecords
   • El orden secundario dentro del mismo día es ascendente por speechOrder (basado en mediciones, no en la especificación oficial): Si se apunta al final con startRecord=<numberOfRecords>&maximumRecords=1 sin acotar el período, debido a que la API es descendente fija, se obtiene el último discurso del día más antiguo del período (máximo speechOrder), perdiendo el primer discurso real. Acotar el período con from/until hasta que numberOfRecords ≤ 100, obtener todos los resultados y usar --sort date-asc,speech-order-asc del wrapper para confirmar en una sola solicitud (ver detalles en recipes/oldest-speech-by-speaker.md)
8. El uso conjunto de any y speaker es una intersección (reduce drásticamente el número de resultados): Si se busca discursos del legislador A y se especifica any=A&speaker=A, solo se obtendrán los discursos que cumplan ambas condiciones (aquellos en los que el propio A menciona su nombre), reduciendo el número de resultados drásticamente en comparación con usar solo uno (medición: solo speaker=石原慎太郎 2098 resultados / ambos 647 resultados). Para todos los discursos del legislador A, usar solo speaker; para menciones sobre A, usar solo any. Para la distinción según la intención, consulta la sección correspondiente de parameters.md y recipes/speaker-vs-any-disambiguation.md
9. El "número de resultados de búsqueda" en el error (19004)startRecord fuera de rango es el numberOfRecords de la misma consulta: El mensaje de error (19004)startRecord debe especificar un valor desde 1 hasta el número de resultados de búsqueda. se refiere al numberOfRecords de la misma consulta (basado en mediciones, no especificado en la documentación oficial). Si se decide startRecord basándose en el número de resultados obtenidos de otra consulta (búsqueda simple sin from/until, solo speaker vs combinación, valores cacheados, etc.), se producirá el error 19004. Para diagnosticar, enviar una solicitud con startRecord=1&maximumRecords=1 en la misma consulta y volver a confirmar numberOfRecords. Esto ocurre con frecuencia en los casos de intersección del punto 8 o al añadir from/until, donde el número de resultados se reduce (ver detalles en la explicación de 19004 en api-reference.md)

Ejemplos de Patrones de Búsqueda Comunes

Discursos de un legislador en un período específico

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

Seguimiento de la discusión de un proyecto de ley (serie temporal)

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

Extraer discursos del Primer Ministro

El argumento speakerPosition no es compatible con el wrapper, por lo que se usa curl directamente:

# No compatible con el wrapper, usar curl directamente
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'

Preguntas de peritos

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

Acta completa de una reunión específica (dos pasos)

# Paso 1: Identificar issueID (el filtro nameOfHouse no es compatible con el wrapper, seleccionar manualmente de la lista)
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-01 50 --sort date-desc

# Paso 2: Obtener acta completa
bash scripts/fetch-meeting.sh <issueID>

Paginación

Común a todos los endpoints.

• Pasar el nextRecordPosition de la respuesta al startRecord de la siguiente solicitud
• Determinación de la última página:
  • JSON: El valor de nextRecordPosition es null
  • XML: El elemento <nextRecordPosition> está ausente
• Dejar un intervalo de varios segundos entre solicitudes consecutivas (límite de tasa)

Formato de Salida

Formato recomendado al presentar discursos al usuario:

【Orador】○○○○ (grupo parlamentario / cargo)
【Reunión】Sesión XXX de la Dieta, Cámara de Representantes, Comisión ○○, Núm. X (YYYY-MM-DD)
【Discurso】
Cita del texto del discurso (normalizar CRLF a saltos de línea)

【Fuente】Sistema de Búsqueda de Actas de la Dieta https://kokkai.ndl.go.jp/txt/<issueID>/<speechOrder>

Al presentar un listado de reuniones:

【Lista de reuniones】N  resultados
- YYYY-MM-DD: Sesión XXX de la Dieta, Cámara de Representantes, Comisión ○○, Núm. X
  https://kokkai.ndl.go.jp/txt/<issueID>
- ...

Casos que Requieren curl Directo

Los siguientes parámetros no están cubiertos por el script wrapper. Cuando sea necesario, llama directamente a la API con curl / Invoke-RestMethod:

• sessionFrom / sessionTo (acotar por número de sesión)
• contentsAndIndex / supplementAndAppendix (índice, apéndice)
• closing=true (sesiones cerradas únicamente)
• nameOfHouse / nameOfMeeting y otros filtros secundarios (no incluidos en los argumentos del wrapper)
• Paginación (llamadas consecutivas con startRecord + nextRecordPosition)
• Especificación simultánea de any y speaker (para uso intencionado de la intersección, como auto-referencias de un legislador. Ver patrón 3 de recipes/speaker-vs-any-disambiguation.md)

Ejemplo: Extraer solo la Comisión de Presupuestos de la sesión 213 de la Dieta (requiere sessionFrom/sessionTo, no compatible con el wrapper)

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'

Se ha observado que las herramientas que utilizan modelos de resumen internos como WebFetch pueden alucinar campos que no existen en la respuesta. Por lo tanto, no se recomienda usarlas para obtener datos en bruto (ver detalles en response-format.md).

Referencias Detalladas

• api-reference.md: Especificaciones del endpoint, paginación, respuestas de error
• parameters.md: Especificación completa de los parámetros de búsqueda, métodos de búsqueda, ejemplos de combinaciones
• response-format.md: Estructura de la respuesta, ejemplos JSON reales, errores comunes basados en mediciones
• recipes.md: Colección de patrones complejos (acotación por legislador y palabra clave, etc., casos no cubiertos por los scripts)