Wiki Index

kouchou-ai(広聴AI)開発者向けの設計判断・コード構造・運用ノウハウ・既知の落とし穴を整理。コントリビュータが素早く文脈を掴むためのナレッジベース。

このページは人間向けの curated navigation です。AI / LLM 向けの全件カタログは index.txt を、時系列の作業履歴は log.md を参照。

直近の状態(2026-10-28 時点。2026-11-02 の棚卸しと長期戦略は 現状把握と長期戦略): 2026-10 の経緯の整理(大規模レビュー → 鍵漏洩の修正 → v4.2.0、残った可視化 2 つと tokoroten の 2 手法) / 本格コードレビュー 2026-10-19 / 健全性レビュー 2026-10-18 / 定例レポート退避分 2026-10-18 — レビューから出した修正 PR #1015–#1022・#1027–#1041 は 2026-10-19 までに main へ merge 済み。2026-10-21 には、レポート再利用・管理画面の一覧更新・濃い意見 0 件時の表示まわりの修正 #1043–#1047 も merge された(main c57e0bfa)。Claude provider 接続実験は手元の branch だけにあり、PR にはしていない。次に判断が要るのは、散布図ラベルの a/b(#1023。PR #1024 / #1025 のどちらかを選ぶ)と、健全性レビューの Issue 整理提案。

最初に読むべき (推奨順)

kouchou-ai → usage-modes → analysis-core-and-web-ui → architecture-overview → local-dev-setup → gotchas

雰囲気を掴むためのストーリー: deploy-success-but-nothing-changed-story-2026-06-01 — 「デプロイ成功なのに画面が変わらない」という小さな違和感から、Wiki つき Coding Agent が古い設計の沼を一日で遡って直した一日のエピソード。前提知識ゼロで読める

開発者が共通して知るべきこと

  • security-maintenance — CodeQL/Dependabot 保守の durable hub と公開境界ポリシー

  • broadlistening — ブロードリスニング手法の定義と用語

  • zipf-broadlistening — 「なぜサンプリングでなく全件か」を1枚で体験させる nishio のデモサイト(ランダムK件は割合pの意見を exp(-Kp) で丸ごと見落とす)

  • kouchou-ai — プロジェクト全体像と 4 つの配布形態

  • analysis-stance — 広聴AI は構造把握スタンスのツールであって、定量分析スタンスのツールではない、という core stance

  • broadlistening-tool-ecosystem-vision — simple Web UI + CLI 実験の二段構造エコシステムビジョン(analysis-stance の「別ツールで補完」への答え)

  • usage-modes — 非専門家向け Web UI と、研究者・データサイエンティスト向け CLI / analysis-core の使い分け

  • analysis-core-and-web-ui — なぜ Web UI は analysis-core を使う consumer で、Web は JSON、CLI は観察用HTMLを持つのか

  • architecture-overview — 5 サービスのランタイム構成

  • pipeline — 解析パイプライン(extraction → embedding → 階層クラスタリング → 可視化)

  • versioning-strategy — 2025-12 に決めた v4 凍結 / v5 plugin 化の方針と、その後の実際(main で段階移行、v4.1.0 を 2026-10-13・v4.2.0 を 2026-10-26 に発行、v5 は未リリース)

  • llm-providers — OpenAI / Azure / Gemini / OpenRouter / LocalLLM

  • local-dev-setup — Docker 一発からネイティブ Rye/pnpm まで

  • testing — pytest / Jest / Playwright と lint

  • contributing — Issue → 実装計画 → PR の流れ、CLA、レビュー

  • coding-agents — Devin / Claude Code / Codex の協働運用

  • gotchas — 非自明な落とし穴の一覧

いま何を考えるか / 何が起きているか:

  • long-term-strategy-2026-11-02 — 現状把握と長期戦略(最新、AI の叩き台)。活動量・貢献者分布・利用の観測・運営の場(定例停止、戦略会議調整中)を棚卸しし、書籍同期の v5.0 宣言 / 利用の観測 / 人間がボトルネックにならない形にする(判断を規則にし、AI が進める) / 結果 JSON の層分離 / 入口の役割分担、の 5 本と戦略会議への問いを整理

  • serverless-product-direction-2026-09-08 — dd2030の目的から見たブラウザ版・既存版の役割、互換範囲、次の開発順序(本流化は未決)

  • thinking-targets — 今、人間の思考と判断が要る論点のハブ (ラベル品質仕切り直し / 次の view 方向 / pipeline 境界 / 公開運用摩擦)

  • refactoring-status — Phase 別の実装状況、current main との同期

  • open-decisions — 未定 / 方針決定済 / 着手済の三分類 (全体棚卸し)

  • issue-backlog-audit-2026-10-28 — 現行の全件 issue 棚卸し(最新。open 89 件を 2026-10-28 の main と照合。10-12 版 issue-backlog-audit-2026-10-12 と 2026-05〜06 の triage はこれに置換済み)。2026-11-02 に停滞 Issue 56 件の処し方を決め、30 件を close(stale-issue-disposition-2026-11-02)

  • kouchou-ai-docs-policy-history / kouchou-ai-docs-overhaul-2026-10 — 本体 docs 方針の系譜と 2026-10 改善スプリントの総括

  • faithful-aggregation-vs-deliberation-dynamics — 忠実な集約 vs 熟議ダイナミクス(分析スタンスの核)

  • dependabot-alerts-2026-10-14 — security / dependency 保守の観測(脆弱性の具体詳細は公開 wiki に書かない方針)

  • retrospective-2026-10-28 — 2026-10 の大規模レビュー 4 段と鍵漏洩の修正・v4.2.0 までの流れ、残った可視化 2 つと tokoroten の賛否分離 2 手法の取り込み案

  • user-api-key-leak-2026-10 — ユーザー API キーが結果 JSON と公開ページに含まれていた問題の原因・経緯・対応・教訓

  • deep-code-review-2026-10-19 — 8 領域+横断フロー追跡の本格コードレビュー(36 件。修正 PR #1032–#1041 は 2026-10-19 merge 済み)

  • code-health-review-2026-10-18 — コード・wiki・Issue の健全性レビュー(新規改善点と 5 PR、未着手 backlog、Issue 整理提案。5 PR は 2026-10-19 merge 済み)

  • source-review-findings-2026-10-16 — ソースコードレビュー確定 10 件の棚卸し

過去の優先度整理(歴史的文脈。現行判断は上の棚卸しを優先):

CLI / analysis-core 開発者向け

WebUI 開発者向け

  • deployment — Azure 本番、静的サイト書き出し、PyPI リリース
  • public-viewer-build-behavior — public-viewer の build の前提(通常 build は API 不要、API が要るのは build:static だけ)と 2026-05 時点の build failure の切り分け
  • npm-vs-pnpm — なぜ pnpm 必須か

プロジェクト自体について

全件カタログ / 人物・組織

Sources / Analyses / Entities の全件は index.txt を参照。人物・組織(dd2030 / talk-to-the-city / nishio / tokoroten / nasuka / ohki-shingo / kuboon / anno など)も同ファイルから stem 検索で辿れる。

Updates

  • 2026-11-02: 「いま何を考えるか」の先頭に 現状把握と長期戦略の考察 を追加し、「直近の状態」からも導線を張った
  • 2026-10-21: 「直近の状態」を main c57e0bfa と GitHub の PR の状態に合わせて書き直し(merge 済みの PR を反映し、本格コードレビューへの導線を追加)、slack-logs の mirror の窓を 14 日から 75 日に訂正。あわせて versioning-strategy と public-viewer-build-behavior の説明を、今の内容(2025-12 の決定とその後の実際、build の前提)に合わせた