HighBridgeDragon/jp-diet-minutes-skill

Skill zur Suche von Parlamentsprotokollen (Kokkai-Gijiroku)

Durchsucht japanische Parlamentsprotokolle (Kokkai) seit der Parlamentsgründung (1947) über die offizielle API des National Diet Library (NDL). Keine Authentifizierung erforderlich. Aufruf erfolgt über die Wrapper bash scripts/<script>.sh.

Protokolle des Kaiserlichen Parlaments (～1947) werden über eine separate API bereitgestellt und sind nicht abgedeckt.

Grundregeln

• Basis-URL: https://kokkai.ndl.go.jp/api/
• Antwortformat: recordPacking=json (wird vom Wrapper-Skript immer erzwungen)
• Authentifizierung: nicht erforderlich
• Aufrufmethode: Verwende bash scripts/<script.sh>. Die direkte Verwendung von WebFetch / Invoke-RestMethod ist nur für Eckfälle erlaubt, die nicht von den Wrappern abgedeckt werden (siehe „Fälle, die raw curl erfordern“ weiter unten).
• Ratenbegrenzung: Offiziell heißt es: „Bei maschinellem Zugriff sind Mehrfachanfragen verboten und es sind Abstände von mehreren Sekunden einzuhalten.“ Parallelisierung verboten, aufeinanderfolgende Aufrufe im Abstand von ca. 2-3 Sekunden.
• Maximale Abfragelänge: 2.000 Byte (japanische Zeichen entsprechen bei URL-Kodierung ca. 9 Byte pro Zeichen).

Endpunktauswahl

Wähle das geeignete Wrapper-Skript basierend auf den Anforderungen des Benutzers. Informationsmenge und Tokenverbrauch steigen in der Reihenfolge list-meetings.sh < search-by-*.sh < fetch-meeting.sh. Grenze daher schrittweise von der leichtesten zur schwersten Variante ein.

„Zeige die Rede von Abgeordnetem XX an“
  → bash scripts/search-by-speaker.sh XX [von] [bis] [limit] --sort <Schlüssel>
  ※ `--sort` ist erforderlich. Typischer Wert: date-desc (neueste zuerst)

„Suche Reden zum Thema YY“
  → bash scripts/search-by-keyword.sh YY [von] [bis] [limit] --sort <Schlüssel>
  ※ any-Suche (AND). Mehrere Schlüsselwörter durch Leerzeichen getrennt. --sort erforderlich.

„Extrahiere Zeugenvernehmungen (inkl. Sachverständige und Referenten)“
  → bash scripts/search-by-role.sh 参考人 [von] [bis] [limit] --sort <Schlüssel>
  ※ Rolle kann 証人 (Zeuge) / 参考人 (Sachverständiger) / 公述人 (Referent) sein. --sort erforderlich.

„Zeige eine Liste der Sitzungen des Ausschusses XX“
  → bash scripts/list-meetings.sh XX [von] [bis] [limit] --sort <Schlüssel>
  ※ Leichtgewichtig. Gibt nur Sitzungs-Metadaten zurück (keine Redetexte). `--sort` erforderlich (nur `date-asc` / `date-desc`)

„Zeige alle Reden einer bestimmten Sitzung an“ / „Vollständiges Protokoll des Ausschusses XX vom YYYY-MM-DD“
  → Schritt 1: Ermittle die issueID der Zielsitzung mit bash scripts/list-meetings.sh
  → Schritt 2: bash scripts/fetch-meeting.sh <issueID>
  ※ Eine einzige Anfrage gibt die gesamte Sitzung zurück, daher groß. Vor dem Aufruf unbedingt eingrenzen.

Weitere Details findest du in api-reference.md, parameters.md, response-format.md und recipes.md.

Verwendung der einzelnen Endpunkte

1. search-by-speaker.sh — Suche nach Reden eines Abgeordneten (am häufigsten verwendet)

Gibt nur die Reden zurück, die den Suchkriterien entsprechen. Die Token-Effizienz ist am besten. --sort ist erforderlich, um den Benutzer explizit auf die API-Sortierreihenfolge aufmerksam zu machen (Workaround für Problem #41).

# Extrahiere Reden nach Abgeordnetennamen (Teilübereinstimmung ODER), absteigend nach Datum
bash scripts/search-by-speaker.sh 岸田文雄 2024-01-01 2024-12-31 50 --sort date-desc

Die vollständigen Parameter (einschließlich Details zu den möglichen Sortierschlüsseln) findest du unter bash scripts/search-by-speaker.sh -h.

Die Antwort ist ein speechRecord[]-Array. Jedes Element enthält flach eingebettete Sitzungs-Metadaten (issueID, session, nameOfHouse, nameOfMeeting, date usw.).

2. search-by-keyword.sh — Schlüsselwortsuche (any-Suche, AND)

Volltextsuche im Redetext. Mehrere Schlüsselwörter werden durch Leerzeichen getrennt und mit AND verknüpft. --sort erforderlich.

# UND-Suche: Reden, die „マイナンバー“ UND „個人情報“ enthalten, absteigend nach Datum
bash scripts/search-by-keyword.sh 'マイナンバー 個人情報' 2024-01-01 2024-12-31 50 --sort date-desc

Die vollständigen Parameter findest du unter bash scripts/search-by-keyword.sh -h. Die Antwortstruktur ist identisch mit search-by-speaker.sh.

3. search-by-role.sh — Suche nach Reden nach Rolle (z. B. Zeugenvernehmungen)

Filtert den Redner nach seiner speakerRole. Wird verwendet, um Zeugenvernehmungen, Sachverständigenanhörungen und Referentenreden zu extrahieren. --sort erforderlich.

# Nur Sachverständigenanhörungen, absteigend nach Datum
bash scripts/search-by-role.sh 参考人 2024-01-01 2024-12-31 50 --sort date-desc

role kann 証人 (Zeuge) / 参考人 (Sachverständiger) / 公述人 (Referent) sein. Andere Werte führen zu HTTP 400.

Die vollständigen Parameter findest du unter bash scripts/search-by-role.sh -h.

4. list-meetings.sh — Liste der Sitzungen (leichter Index)

Gibt nur Sitzungs-Metadaten zurück. Enthält keine Redetexte, daher geeignet für die Listenansicht und das Eingrenzen von Sitzungen. Wird verwendet, um die issueID zu ermitteln. --sort erforderlich (nur date-asc / date-desc).

# Liste der Sitzungen des Haushaltsausschusses an einem bestimmten Tag, aufsteigend nach Datum
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-31 50 --sort date-asc

Die vollständigen Parameter findest du unter bash scripts/list-meetings.sh -h.

Die Antwort ist ein meetingRecord[]-Array. Das speechRecord[]-Unterarray jedes Elements enthält nur das Minimum an Redemetadaten (speechID, speechOrder, speaker, speechURL). Rufe search-by-* oder fetch-meeting.sh auf, um den Text zu erhalten.

5. fetch-meeting.sh — Vollständige Sitzung (letztes Mittel)

Gibt die gesamte Sitzung zurück. Da eine einzige Anfrage alle Reden liefert, ist sie schwer. Rufe zuerst list-meetings.sh auf, um die issueID zu ermitteln, und verwende sie dann.

# Vollständige Sitzung per issueID abrufen
bash scripts/fetch-meeting.sh 121405254X00220241004

Die Parameter findest du unter bash scripts/fetch-meeting.sh -h. maximumRecords=1 ist fest eingestellt (da die issueID eindeutig ist). --sort ist nicht anwendbar, da eine einzelne Sitzung abgerufen wird (bei Bedarf kann die Ausgabe mit jq nachbearbeitet werden).

Das speechRecord[] von fetch-meeting.sh enthält alle Felder (speech, speakerYomi, speakerGroup, speakerPosition, speakerRole, startPage, createTime/updateTime).

Anleitung zur Token-Einsparung

bash scripts/fetch-meeting.sh kann für eine Sitzung mehrere hundert KB bis MB groß sein. Bitte beachte Folgendes:

1. search-by-*.sh bevorzugen: Für einzelne Reden können nur die benötigten Teile abgerufen werden. bash scripts/fetch-meeting.sh nur verwenden, wenn der Benutzer explizit eine „vollständige Sitzung“ anfordert.
2. maximumRecords explizit angeben: Der Standardwert 30 ist in den meisten Fällen ausreichend. Bei vielen Ergebnissen kann der Wert auf das Limit erhöht werden (search-by-*/list-meetings: 100, fetch-meeting: 10), um die Gesamtzahl der Anfragen zu reduzieren.
3. 2-stufige Suche verwenden: Zuerst mit list-meetings.sh oder search-by-*.sh eingrenzen und die issueID abrufen → dann bei Bedarf mit fetch-meeting.sh den Volltext holen. Nicht direkt fetch-meeting.sh aufrufen.
4. Bei 0 Treffern alternative Schreibweisen versuchen: Bei Abgeordnetennamen nacheinander 福島 みずほ / 福島瑞穂 / Hiragana versuchen. Fraktionsnamen müssen unbedingt offiziell sein (自民党 ❌ / 自由民主党 ✅).

Fallstricke bei der Ergebnis-Filterung

Beachte nach dem Abruf der Antwort folgende Punkte:

1. Zeilen mit speechOrder gleich 0 sind Protokoll-Informationsköpfe: Strukturinformationen wie Tagesordnung und Anträge, keine eigentlichen Reden. speaker ist fest auf 会議録情報 gesetzt. Bei der Zusammenstellung von Reden Zeilen mit speechOrder gleich 0 ausschließen.
2. Werte von imageKind: Standardmäßig können zusätzlich zu 会議録 auch 目次 (Inhaltsverzeichnis), 索引 (Index), 附録 (Anhang) und 追録 (Nachtrag) enthalten sein. Filtere bei der Redenextraktion nur auf Zeilen mit imageKind = 会議録. Die Anfrageparameter contentsAndIndex / supplementAndAppendix sind standardmäßig false und können daher normalerweise weggelassen werden. Nur auf true setzen, wenn sie explizit einbezogen werden sollen.
3. closing gibt null statt false zurück: Bei normalen Sitzungen ohne Vertagungsflag wird null zurückgegeben. Die Prüfung auf eine Vertagung erfolgt nur, wenn closing den Wert true hat (Vergleich mit true, nicht mit false).
4. Ungültige Werte für nameOfHouse werden stillschweigend ignoriert: Die Antwort erfolgt mit HTTP 200, aber ohne angewendeten Filter. Überprüfe die Plausibilität von numberOfRecords, um sicherzustellen, dass die Absicht umgesetzt wurde.
5. Zeilenumbrüche im Redetext sind CRLF (\r\n): Nicht nur LF. Bei der Textverarbeitung kann eine Normalisierung erforderlich sein.
6. Die Antwortstruktur von search-by-*.sh ist flach: Sie hat keinen meetingRecord-Wrapper wie fetch-meeting.sh. Wenn ein gemeinsamer Parser geschrieben wird, ist eine Verzweigung erforderlich.
7. Die Sortierreihenfolge der API ist fest auf „absteigend nach Sitzungsdatum“ eingestellt: Die offizielle Spezifikation garantiert die absteigende Reihenfolge. Die API selbst hat keinen Sortierparameter (gilt für alle Endpunkte). Das --sort-Flag der Wrapper-Skripte dieses Skills ist kein API-Parameter, sondern eine clientseitige Nachsortierung mit jq (erforderlich für search-by-*.sh / list-meetings.sh). Obwohl praktisch, bedeutet dies, dass bei Verwendung von maximumRecords für einen Teilabruf nur die neuesten N Elemente zurückgegeben werden.
   • Bestimmung der neuesten Rede: Der erste Eintrag des Teilabrufs ist ausreichend (maximumRecords=1 genügt).
   • Bestimmung der ältesten Rede: Nicht basierend auf dem ältesten Eintrag eines Teilabrufs. Entweder alle numberOfRecords bis zum Ende der Paginierung abrufen oder den Zeitraum mit from / until so eingrenzen, dass die Trefferzahl ≤ maximumRecords ist, und dann bestimmen.
   • Sekundäre Sortierung innerhalb eines Tages aufsteigend nach speechOrder (empirisch, nicht in der offiziellen Spezifikation): Ein direkter Sprung zum Ende mit startRecord=<numberOfRecords>&maximumRecords=1 innerhalb eines Zeitraums die letzte Rede (speechOrder max) des ältesten Tages in diesem Zeitraum abrufen, da die API absteigend sortiert, und die tatsächliche erste Rede verpassen. Grenze den Zeitraum mit from/until so ein, dass numberOfRecords ≤ 100, rufe alle ab und verwende --sort date-asc,speech-order-asc des Wrappers, um die erste Rede mit einer einzigen Anfrage zu bestimmen (Details siehe recipes/oldest-speech-by-speaker.md).
8. Die gleichzeitige Verwendung von any und speaker ergibt eine Schnittmenge (deutlich weniger Treffer): Wenn du die Reden von Abgeordnetem A mit any=A&speaker=A suchst, werden nur Reden gefunden, die beide Bedingungen erfüllen (A spricht und erwähnt seinen eigenen Namen), was zu deutlich weniger Treffern führt als bei der alleinigen Verwendung eines Parameters (empirisch: speaker=石原慎太郎 allein 2.098 Treffer / beide zusammen 647 Treffer). Verwende speaker allein für alle Reden von Abgeordnetem A und any allein für Erwähnungen von A. Siehe den entsprechenden Abschnitt in parameters.md und recipes/speaker-vs-any-disambiguation.md für die Unterscheidung nach Absicht.
9. Die „Suchergebnisanzahl“ im Fehler (19004)startRecord 範囲外 bezieht sich auf numberOfRecords derselben Abfrage: Der Fehler (19004)startRecord には 1 から検索件数までの値を指定してください。 verwendet den Begriff „Suchergebnisanzahl“, der sich auf die numberOfRecords derselben Abfrage bezieht (empirisch, nicht in der offiziellen Spezifikation erwähnt). Wenn startRecord auf der Grundlage einer anderen Abfrage (einfache Suche ohne from/until, nur speaker vs. kombiniert, zwischengespeicherte Werte usw.) festgelegt wird, tritt Fehler 19004 auf. Führe zur Ursachenanalyse dieselbe Abfrage mit startRecord=1&maximumRecords=1 aus und überprüfe numberOfRecords erneut. Dies tritt häufig auf, wenn die Anzahl der Treffer durch die Schnittmengenbildung aus Punkt 8 oder durch Hinzufügen von from/until reduziert wird (Details siehe api-reference.md zur 19004-Erklärung).

Häufig verwendete Suchmuster – Beispiele

Reden eines Abgeordneten in einem bestimmten Zeitraum

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

Verfolgung der Gesetzesberatung (zeitlicher Ablauf)

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

Extraktion von Reden des Premierministers

Der speakerPosition-Parameter wird nicht vom Wrapper unterstützt. Verwende daher raw curl:

# raw curl, da nicht vom Wrapper unterstützt
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'

Zeugenvernehmungen

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

Vollständiges Protokoll einer bestimmten Sitzung (2-stufig)

# Schritt 1: issueID ermitteln (nameOfHouse-Filter wird nicht vom Wrapper unterstützt, daher manuelle Auswahl aus der Liste)
bash scripts/list-meetings.sh 予算委員会 2024-03-01 2024-03-01 50 --sort date-desc

# Schritt 2: Volltext abrufen
bash scripts/fetch-meeting.sh <issueID>

Paginierung

Gilt für alle Endpunkte.

• Gib nextRecordPosition aus der Antwort als startRecord für die nächste Anfrage weiter.
• Erkennung der letzten Seite:
  • JSON: Der Wert von nextRecordPosition ist null.
  • XML: Das Element <nextRecordPosition> fehlt ganz.
• Bei aufeinanderfolgenden Abrufen ist ein Abstand von mehreren Sekunden einzuhalten (Ratenbegrenzung).

Ausgabeformat

Empfohlenes Format für die Darstellung von Reden für den Benutzer:

【Sprecher】○○○○ (Fraktionszugehörigkeit/Titel)
【Sitzung】XXX. Sitzungsperiode, Repräsentantenhaus, Ausschuss XX, Nr. X (YYYY-MM-DD)
【Rede】
Zitat des Redetextes (CRLF in Zeilenumbrüche normalisiert)

【Quelle】National Diet Library Sitzungsprotokoll-Suchsystem https://kokkai.ndl.go.jp/txt/<issueID>/<speechOrder>

Für die Darstellung einer Sitzungsliste:

【Sitzungsliste】N Einträge
- YYYY-MM-DD: XXX. Sitzungsperiode, Repräsentantenhaus, Ausschuss XX, Nr. X
  https://kokkai.ndl.go.jp/txt/<issueID>
- ...

Fälle, die raw curl erfordern

Die folgenden Parameter werden nicht von den Wrapper-Skripten abgedeckt. Verwende bei Bedarf direkt curl / Invoke-RestMethod für die API:

• sessionFrom / sessionTo (Eingrenzung auf eine bestimmte Sitzungsperiode)
• contentsAndIndex / supplementAndAppendix (Inhaltsverzeichnis, Index, Anhänge)
• closing=true (nur vertagte Sitzungen)
• Sekundäre Filter wie nameOfHouse / nameOfMeeting (nicht als Wrapper-Argumente enthalten)
• Paginierung (aufeinanderfolgende Aufrufe von startRecord + nextRecordPosition)
• Gleichzeitige Angabe von any und speaker (für Fälle wie Selbstbezüge eines Abgeordneten, bei denen bewusst die Schnittmenge beider genutzt wird. Siehe recipes/speaker-vs-any-disambiguation.md, Muster 3).

Beispiel: Nur Sitzungen des Haushaltsausschusses der 213. Sitzungsperiode extrahieren (erfordert sessionFrom/sessionTo, nicht vom Wrapper unterstützt):

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'

Tools, die ein internes Zusammenfassungsmodell wie WebFetch verwenden, neigen nachweislich dazu, nicht in der Antwort vorhandene Felder als Halluzinationen einzufügen. Verwende sie daher nicht zum Abrufen von Rohdaten (Details siehe response-format.md).

Detaillierte Referenzen

• api-reference.md: Endpunktspezifikationen, Paginierung, Fehlerantworten
• parameters.md: Vollständige Spezifikation der Suchparameter, Suchmethoden, Kombinationsbeispiele
• response-format.md: Antwortstruktur, echte JSON-Beispiele, empirische Fallstricke
• recipes.md: Sammlung komplexer Muster (z. B. Eingrenzung nach Abgeordnetem × Schlüsselwort, Fälle, die nicht von den Skripten abgedeckt werden).