Skip to content

知らない分野を、原文にたどりつくまで芋づる式に掘る Claude Code のスキル

Python

詳細レポート(digest.py): 入門編・隣接分野編の解説と、検索の全記録

MaryCache4eee4c617706
diff --git a/README.en.md b/README.en.md
index 7ff4dac..7b79e16 100644
--- a/README.en.md
+++ b/README.en.md
@@ -112,6 +112,10 @@ log.md per round: what was searched, what turned up, decisions and why
sources/ saved sources
extracts.json extracts
report.html extract page
+queries.jsonl every hit for every search query
+fetch-log.jsonl fetch record (URL and OK/FAIL)
+digest.json explanation for the detailed report
+digest.html detailed report (beginner and adjacent-field explanations, plus the full search record)
```
A sample extract page is in `examples/demo/`, and this command tries the script on its own.
@@ -125,7 +129,8 @@ python3 skills/imozuru/scripts/report.py examples/demo
### Why it does not summarise
Kuhlthau (1991) describes how summarising in detail during the confused early stage of a search invites premature closure and gets in the way of the search process.
-So imozuru stops at pointing to where things are in the sources.
+So while it is searching, imozuru stops at pointing to where things are in the sources.
+Explanation is written only after the stop decision, in the detailed report.
### When to stop
@@ -158,6 +163,14 @@ Dozens of saved sources leave the user with no idea where to start.
So, following extracting from Ellis's model, the skill builds a page that cuts the relevant passage from a source for each claim.
`report.py` checks that each extract appears verbatim at the given lines of its source, and if even one word differs, it does not build the page.
+### The two layers of the detailed report
+
+Extracts alone do not tell a newcomer what the terms mean or what to read first.
+So after stopping, the skill builds a detailed report with two layers: explanation and record.
+The explanation comes in two levels, one for readers with no background and one for readers who know a neighbouring field, and every sentence carries a verbatim quote from a source as its evidence.
+`digest.py` checks those quotes the same way as the extracts, and refuses to build the page if any sentence lacks one.
+The record is assembled by machine from every hit of every query and from the fetch results, so it shows everything that was searched and found, including queries that found nothing.
+
## Where the rules come from
`skills/imozuru/references/theory.md` lists which paper, and which part of it, each rule in the skill comes from (in Japanese).
diff --git a/README.md b/README.md
index a58696e..4e5df5b 100644
--- a/README.md
+++ b/README.md
@@ -106,6 +106,10 @@ log.md 周ごとに、何を探して何が出たか・判断とその
sources/ 落とした原文
extracts.json 抜き書き
report.html 抜き書きのページ
+queries.jsonl 検索語ごとのヒットの全件
+fetch-log.jsonl 取得の記録(URL と OK/FAIL)
+digest.json 詳細レポートの解説
+digest.html 詳細レポート(入門編・隣接分野編の解説と、検索の全記録)
```
抜き書きのページの見本は `examples/demo/` にあり、次のコマンドでスクリプトだけを試せます。
@@ -119,7 +123,8 @@ python3 skills/imozuru/scripts/report.py examples/demo
### 要約しない理由
Kuhlthau(1991)は、調べ始めの混乱した段階で詳しくまとめると、早すぎる閉じ(premature closure)を招き、探索の過程が妨げられると述べています。
-そのためimozuruは、原文の場所を示すところまでにとどめています。
+そのためimozuruは、調べている間は原文の場所を示すところまでにとどめています。
+解説を書くのは、止める判定が出たあとの詳細レポートだけです。
### 止めどきの決め方
@@ -152,6 +157,14 @@ imozuruはそうした記事も論文と同じようにたどるので、保存
そこでEllisのモデルにある抜き書き(extracting)にならい、主張ごとに原文の該当部分を切り出したページを作ります。
`report.py` は、切り出した文が原文の指定の行にそのまま在るかを照合し、1語でも違えばページを作りません。
+### 詳細レポートの2層
+
+抜き書きだけでは、その分野を知らない人には言葉の意味も読む順も分かりません。
+そこで止めたあとに、解説と記録の2層からなる詳細レポートを作ります。
+解説は前提知識の無い人向けの入門編と、近い分野を知っている人向けの隣接分野編に分け、1文ごとに原文からの引用を根拠として付けます。
+`digest.py` は抜き書きと同じ方法で引用を照合し、根拠の無い文が1つでもあればページを作りません。
+記録は、検索語ごとのヒットの全件と取得の結果から機械で組むので、空振りの検索語も含めて、何を探して何が出たかがそのまま見えます。
+
## 決まりの出典
スキルの各決まりがどの論文のどこから来ているかは、`skills/imozuru/references/theory.md` にまとめています。
diff --git a/skills/imozuru/SKILL.md b/skills/imozuru/SKILL.md
index 782f919..2f9e5ba 100644
--- a/skills/imozuru/SKILL.md
+++ b/skills/imozuru/SKILL.md
@@ -17,11 +17,11 @@ description: |
# imozuru
知らない分野を、言葉を知らないところから原文にたどりつくまで調べる。
-大事な決まりは2つ。**原文を要約せずに保存する**ことと、**止めどきを確信度ではなく証拠で決める**こと。
+大事な決まりは2つ。**調べている間は原文を要約せずに保存する**ことと、**止めどきを確信度ではなく証拠で決める**こと。
## なぜこの形か(先に読む)
-- **要約しない理由**: 調べ始めの混乱した段階で詳しくまとめると、早すぎる結論(premature closure)を招いて、調べる過程を妨げる(Kuhlthau 1991)。エージェントが早い周で要約すると、エージェントの見方で結論が固まり、ユーザーが判断に使う細部が抜ける。このスキルは「自分の感覚と AI の調査結果がかみあわない」という経験から生まれた。判断するのは原文を読むユーザーで、エージェントは原文の場所を指すだけ
+- **要約しない理由**: 調べ始めの混乱した段階で詳しくまとめると、早すぎる結論(premature closure)を招いて、調べる過程を妨げる(Kuhlthau 1991)。エージェントが早い周で要約すると、エージェントの見方で結論が固まり、ユーザーが判断に使う細部が抜ける。このスキルは「自分の感覚と AI の調査結果がかみあわない」という経験から生まれた。判断するのは原文を読むユーザーで、エージェントは原文の場所を指すだけ。要約を止めるのは調べている間だけで、止めたあとは詳細レポート(下の節)で解説を書く。止める判定が出たあとなら、要約しても調べる過程を妨げない
- **決め打ちしない理由**: AI の検索は、方向がいくつもありうる段階で1つを選び、その後の検索も同じ方向へ重ねて失敗する(Zhou ら 2026 HypoSearch)。迷ったら仮説ごとに調べを分けて並べ、比べてから進む
- **検索語が無いとき**: 引用をたどる方法は、主題を言葉で言い表す問題を避けられる(Bates 1989)。検索語が出てこないときは引用と著者でたどる
- 理論と原文の場所は `references/theory.md`
@@ -36,6 +36,10 @@ log.md … たどった経過。周ごとに、誰が何を探して何が
sources/ … 原文。PDF とその .txt、HTML は .md。要約ファイルは置かない
extracts.json … 抜き書き(止めたあとに書く・下の「抜き書きのページ」)
report.html … 抜き書きのページ(report.py が作る)
+queries.jsonl … 検索の記録。検索語ごとのヒットの全件(digest.py add と chain.py --log が足す)
+fetch-log.jsonl … 取得の記録。fetch.py が URL と OK/FAIL を自動で足す
+digest.json … 詳細レポートの解説(止めたあとに書く・下の「詳細レポート」)
+digest.html … 詳細レポート(digest.py が作る)
watch.tsv … 見張る先(見張りのモードを使ったときだけ)
watch/ … 見張りの結果。<日付>.md
```
@@ -70,6 +74,7 @@ map.md を下の書式で作り、**問い**と、答えるのに要る**主張*
- 報告は「見つけた/探したが無い/探していない」の3つに分けてもらう。「探していない」がそのまま次の手がかりになる
- **要約は頼まない**。名前と URL を正確に拾うことを優先させる
- **ファイルを書かせない**。ダウンロードは親の仕事。試行で検索役が curl で一時ファイルを書いた
+- **検索語ごとのヒットを、報告の末尾に JSON で全件返させる**。形は `[{"query": "<検索語>", "method": "WebSearch", "hits": [{"title": "…", "url": "…"}]}]`。ヒットが無かった検索語も `"hits": []` で入れる。選んだものだけでなく、挙がったものを全部入れる。親はこの JSON を手で写し直さず、報告からそのまま `digest.py add <topic_dir> --round <周> --by <検索役の名前>` の標準入力に渡す(写すと誤記が記録に入る。試行では頼みの中の書式の見本を取り違えて1行入れ、消して入れ直した)。親が自分で検索したときも同じ形で足す
- **場は一覧から選ばず、0周目で探させる**。「この分野の詳しい人はどこに書いているか」「定番の資料はどこで公開されているか」を検索役への問いとして渡し、挙がった場を map.md の「場」に足す。どの場から何件挙がったかを log.md に残す(分野ごとの場の偏りを記録に溜める)。論文と個人の発信のどちらに知恵があるかは分野しだいで、0周目では決めつけない。次の一覧は、場の見当がまったくつかないときの例にとどめる=学会・雑誌・arXiv、個人ブログ、Qiita・Zenn・note、YouTube、GitHub、X、pixiv・FANBOX の講座、フォーラム。固定の一覧だけで当たると、一覧を作った人がよく見る場所(日本語の技術記事など)に偏る
- 最初に検索する言葉が分からない分野では、粒度の粗い順に当たらせる=百科事典(英語版 Wikipedia の References)→ 専門事典 → 教科書・講義資料 → サーベイ論文 → 原著(横井 2017)。論文の無い分野なら、用語集・入門記事 → その分野で名前の挙がる人 → その人自身の実践の記録、の順
- 日本語で検索語が見つからない分野は英語で始める(「berrypicking ベイツ」は果物狩りの記事ばかりだった)
@@ -94,6 +99,7 @@ map.md を下の書式で作り、**問い**と、答えるのに要る**主張*
**論文の無い分野ほど、知恵は個人の発信にある**(塗り方・MIX・ツールの使いこなしなど)。権威のある場所だけに絞らない。
+- **`chain.py` は `--log <topic_dir> --round <周>` を付けて回す**。出した一覧が検索の記録に入る
- **論文は DOI で引く**。題名で引くと別の記録や解説記事が出ることがあるので、`chain.py find` の候補を年と題で確かめてから使う
- **出て1年ほどの論文は `chain.py` が0件を返す**。OpenAlex に引用の登録が追いついていない(試行では出て1年以内の論文で refs も cites も0件)。0件は「無い」ではない。後ろへは、保存した本文の参考文献の節を grep する(試行ではこれで目当ての論文が見つかった)。前へは、検索役に「<題名> を引いている論文」を探させる
- **方向が2つ以上ありえるときは決め打ちしない**。検索役を2本、別の仮説で並べ、戻ってから比べる
@@ -131,12 +137,12 @@ map.md を下の書式で作り、**問い**と、答えるのに要る**主張*
1. **止めた理由**(上の5つのどれか)
2. **主張ごとの原文の場所**(`sources/<file>` の何行目)。1主張1〜2行
3. **届かなかったもの**(有料で取れない定番など)
-4. **抜き書きのページ(`report.html`・下の節)のパスを最初に示し**、ほかに一番読んでほしい原文を2〜4本選んで、パスと「どこを読むか」を1行ずつ添える
+4. **詳細レポート(`digest.html`)と抜き書きのページ(`report.html`)のパスを最初に示し**(どちらも下の節)、ほかに一番読んでほしい原文を2〜4本選んで、パスと「どこを読むか」を1行ずつ添える
5. **ログインか有料で読めないが、大事そうなもの**は、URL と「なぜ大事そうか」を1行で並べる。ユーザーがログイン済みのブラウザで開いて読む。エージェントはアカウントを作らない・ログインしない
6. 流れのほうで気づいた問題(道具の不具合・検索役が頼んだ範囲の外でしたこと)
7. **ユーザーに「感覚と合った?」と一言だけ聞き、答えを `<話題>/log.md` の末尾に原文のまま残す**(言い換えない)。止めどきの7割や周の上限を変えるかは、この記録を何回分か並べて決める(記憶では決めない)
-返事に要約や解説を書かない。ユーザーに「まとめて」と頼まれたら、そこで初めて書く。
+解説は詳細レポートに書き、返事には書かない。返事は上の7つにとどめる。
### 抜き書きのページ(読むための形)
@@ -155,6 +161,32 @@ map.md を下の書式で作り、**問い**と、答えるのに要る**主張*
3. エージェントが書いてよいのは、見出し・状態(付いた/一部だけ/付かなかった)・1行の注記・訳だけ。注記にも結論や評価は書かない(「順番は記事ごとに違う」はよい、「この順が正しい」は書かない)。注記は、誰が何をどうしたかが分かる文で書く
4. 自動字幕の誤変換は直さずにそのまま切り出す(直すと言い換えになる)。印に「自動字幕」と書けば、読む人が動画で確かめられる
+### 詳細レポート(解説と記録)
+
+抜き書きは原文を並べるだけなので、その分野を知らない人には、どれから読めばよいかも言葉の意味も分からない。詳細レポートは、調べたドメインの知識を読み手の負担が少ない形で渡し、同時に何を探して何が出たかを全部見せる。止めたあとに作る(要約を止めていたのは早すぎる結論を避けるためで、止めたあとなら書いてよい)。
+
+2つの層に分ける。
+
+- **解説**: エージェントが `digest.json` に書く。読み手の水準ごとに2編を分ける
+ - **入門編**(前提知識が無い人向け): 要旨を3〜5文、用語は日常の言葉で定義する、要る主張ごとの答え
+ - **隣接分野編**(近い分野を知っている人向け): 同じ構成で、用語は「〇〇でいう××に当たる」と隣の分野の言葉に結び付ける
+ - 両編に共通で、人と場(誰がどこで発信しているか)と、未解決の点(原文が付かなかった主張・届かなかった資料)
+- **記録**: `queries.jsonl` と `fetch-log.jsonl` から機械で組む。周ごとに、検索語・誰が探したか・ヒットの全件を並べ、それぞれに〔保存〕〔取得失敗〕〔未取得〕を付ける。空振りの検索語も載る。検索で挙がっていない取得(記事の中のリンクをたどったもの)も別に並ぶ。エージェントはこの層を書かない
+
+手順:
+
+1. `<topic_dir>/digest.json` を書く。**解説の1文ごとに、根拠として原文からそのまま切り出した引用を1つ以上付ける**(ファイル・行・必要なら `end`。抜き書きと同じ形)。根拠の無い文は書かない。両編で同じ引用を使ってよい
+ 形(digest.py の冒頭と同じ):
+ ```
+ {"title", "question", "stopped",
+ "levels": {"intro": 編, "adjacent": 編},
+ "people_places": [文], "unresolved": ["..."]}
+ 編 = {"summary": [文], "terms": [{"term", "sentences": [文]}], "answers": [{"claim", "sentences": [文]}]}
+ 文 = {"text", "quotes": [{"file", "line", "end"?, "text"}]}
+ ```
+2. `scripts/digest.py <topic_dir>` を回す。**全部の文の引用を抜き書きと同じ方法で原文と照合し**、根拠の無い文や原文に無い引用が1つでもあれば HTML を作らずに止まる。通れば `digest.html` ができる。文の後ろの番号から根拠の引用と原文の前後を開ける
+3. 解説の文は、誰が何をどうしたかが分かる文で書く。照合で確かめられるのは「引用が原文に在ること」までで、「文が引用の言うとおりか」は確かめられない。引用が言っていないことを文に足さない
+
## 見張る(watch モード)
調べたあとの map.md の「場」を、新着を追う先にする(Ellis の monitoring)。「〇〇の新着見て」「今週の〇〇まとめて」「/imozuru watch <話題>」で入る。**ユーザーが頼んだときだけ回す**。定期に自動で回すかは、何回か思いどおりに動いてから決める。
@@ -228,8 +260,9 @@ map.md を下の書式で作り、**問い**と、答えるのに要る**主張*
- `scripts/fetch.py <sources_dir> <name> <url>` — ダウンロードして本物か確かめる。PDF は .pdf と .txt(`pdftotext -layout`・poppler か Xpdf)、HTML は .md、YouTube は字幕を `[分:秒] 文` の .md(`yt-dlp`・動画は保存しない)。文字の層が無い PDF は `pdftoppm` と `tesseract` で OCR する。言語は tesseract の言語データに `jpn`・`jpn_vert` があれば英語に足し、環境変数 `IMOZURU_OCR_LANG` があればそれを使う。読み取りの確信度が低いとき(言語データが合わず意味のない字の列になったとき)と、読めなかったページがあるときは OCR の結果を使わず、理由を添えて `FAIL` する。要るコマンドが無いときは、無いコマンドの名前を書いて `FAIL` する。HTML は [ax](https://github.com/yusukebe/ax) があれば ax で、無ければ標準ライブラリで本文を文字にする(見出しや表の形は ax のほうが残る)。取得はいつも fetch.py 自身が宛先を確かめながら行い、ax には取ってきた HTML を渡して変換だけさせる。HTML のページは、名乗りを変えてもう一度頼み、PDF 本体が返ればそちらを残す(HAL はブラウザの名乗りに閲覧用の HTML を返す)。取ってきたものは作業用のフォルダで検査し、通ったものだけを sources_dir へ移す。404・ログインの要求・短すぎる本文は `FAIL`(同じ名前の原文がすでにあれば、そのまま残る)。短さの下限は PDF が 3,000字、HTML が 1,000字で、和文の字が3割を超える PDF は HTML と同じ 1,000字で判定する。X は本文が取れないので取りに行かず `FAIL`=URL と、検索役が拾った抜粋を(未確認)で map.md に残す
- 動画の場所は行番号の代わりに時刻で指す(`sources/x.md [12:34]`)
- `scripts/report.py <topic_dir> [--check]` — extracts.json の抜き書きを原文と照合し、合えば report.html にする。`--check` は照合だけ
+- `scripts/digest.py add <topic_dir> [--round N] [--by 誰]` — 標準入力の JSON(検索語ごとのヒット)を queries.jsonl に足す。`scripts/digest.py <topic_dir> [--check]` — digest.json の解説の引用を原文と照合し、合えば検索の記録と合わせて digest.html にする
- `scripts/watch.py add|list|check` — 見張り。RSS / Atom を引いて前回からの新着を出す。検索を使わないので費用はかからず結果も揺れない。DOCTYPE・ENTITY を含むフィードは安全のため読まない。フィードの場所にタブや改行が入っていたら足さない
-- `scripts/chain.py find|refs|cites|author` — OpenAlex で引用と著者をたどる。1日 1,000 回まで無料の枠で、プリペイド残高が 0 なら超えても止まるだけ。**API キーや支払いの登録はしない**。古めの論文に強く、新しい論文と同名の多い著者に弱い(author は名前の検索の1位を使うので、同名の別人の論文を返すことがある。出力の「# 別の候補」に別人の ID が並ぶので、所属と論文数で確かめ、違えば `chain.py author A…` で引き直す。ただし OpenAlex の著者の記録は、古い論文ほど当てにならない。著者の欄に ID が無い論文や、同名の何人もの論文を1人にまとめた記録がある(試行では、情報探索の Ellis の 1989 年の論文には ID が無く、1993 年の論文は所属が国際ポテトセンターで論文289本の記録に入っていた)。著者で追うときは、所属先や本人のページにある論文の一覧を検索役に探させ、chain.py author の結果はその一覧と突き合わせる)
+- `scripts/chain.py find|refs|cites|author [--log <topic_dir> --round N]` — OpenAlex で引用と著者をたどる。`--log` を付けると出した一覧を queries.jsonl に足す。1日 1,000 回まで無料の枠で、プリペイド残高が 0 なら超えても止まるだけ。**API キーや支払いの登録はしない**。古めの論文に強く、新しい論文と同名の多い著者に弱い(author は名前の検索の1位を使うので、同名の別人の論文を返すことがある。出力の「# 別の候補」に別人の ID が並ぶので、所属と論文数で確かめ、違えば `chain.py author A…` で引き直す。ただし OpenAlex の著者の記録は、古い論文ほど当てにならない。著者の欄に ID が無い論文や、同名の何人もの論文を1人にまとめた記録がある(試行では、情報探索の Ellis の 1989 年の論文には ID が無く、1993 年の論文は所属が国際ポテトセンターで論文289本の記録に入っていた)。著者で追うときは、所属先や本人のページにある論文の一覧を検索役に探させ、chain.py author の結果はその一覧と突き合わせる)
- ファイル名は `<著者>-<年>-<短い題>`、arXiv は `arxiv-<番号>-<短い題>`
## 境界
diff --git a/skills/imozuru/scripts/chain.py b/skills/imozuru/scripts/chain.py
index 1c663d1..44560d3 100755
--- a/skills/imozuru/scripts/chain.py
+++ b/skills/imozuru/scripts/chain.py
@@ -13,6 +13,7 @@ OpenAlex は1日 1,000 回まで無料の枠(x-ratelimit-limit-usd 0.1)。
chain.py cites <ID か DOI> [-n 20] … 前へ: その論文を引いている文献(被引用の多い順)
chain.py author <著者名か著者ID> [-n 20] … 著者で追う: その人の論文(被引用の多い順)
名前なら「# 別の候補」の行に同名の別人の ID も出す
+ --log <topic_dir> --round N を付けると、出した一覧を詳細レポートの記録(queries.jsonl)にも足す
出力: 1行1本、タブ区切り(年 被引用数 ID 題名 DOI 無料PDF)
"""
@@ -145,10 +146,30 @@ def main() -> int:
return 2
n = int(value)
del args[i:i + 2]
+ log_topic, log_round = None, None
+ if "--log" in args:
+ i = args.index("--log")
+ if i + 1 >= len(args):
+ print("--log には調べものの置き場を書く", file=sys.stderr)
+ return 2
+ log_topic = args[i + 1]
+ del args[i:i + 2]
+ if "--round" not in args:
+ print("--log には --round N も付ける", file=sys.stderr)
+ return 2
+ if "--round" in args:
+ i = args.index("--round")
+ value = args[i + 1] if i + 1 < len(args) else ""
+ if not re.fullmatch(r"[0-9]+", value):
+ print("--round には周の数を書く", file=sys.stderr)
+ return 2
+ log_round = int(value)
+ del args[i:i + 2]
if len(args) < 2:
print(__doc__, file=sys.stderr)
return 2
cmd, key = args[0], " ".join(args[1:])
+ shown: list[dict] = []
if cmd == "find":
# 題名のときは候補を全部見せる。どれが本体かを読み手が確かめられるように。
@@ -157,6 +178,7 @@ def main() -> int:
print(f"候補なし: {clean(key)}(DOI で引き直すか、題名の語を減らす)")
for w in hits:
print(row(w))
+ shown += hits
elif cmd in ("refs", "cites"):
# 応答の ID も次の問い合わせに入るので、形を確かめてから使う
wid = (resolve(key).get("id") or "").rsplit("/", 1)[-1]
@@ -168,6 +190,7 @@ def main() -> int:
print(f"# {cmd} {wid} 全{clean(res['meta']['count'])}本中 上位{len(res['results'])}本")
for w in res["results"]:
print(row(w))
+ shown += res["results"]
elif cmd == "author":
# 著者 ID(A と数字)ならその人を直接引く。名前なら検索の1位を使い、ほかの候補も並べる。
# 名前だけでは同姓同名を見分けられないので、別人だったら候補の ID で引き直せるようにする
@@ -188,12 +211,34 @@ def main() -> int:
**{"per-page": n}, select=FIELDS)
for w in res["results"]:
print(row(w))
+ shown += res["results"]
else:
print(__doc__, file=sys.stderr)
return 2
+ if log_topic:
+ log(log_topic, log_round, cmd, key, shown)
return 0
+def log(topic: str, round_: int, cmd: str, key: str, works: list[dict]) -> None:
+ """出した一覧を queries.jsonl に足す。URL は DOI を先に、無ければ OpenAlex の頁。無料 PDF も照合に使う。"""
+ from pathlib import Path
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
+ import digest # 同じフォルダ。--log を使うときだけ読む
+ hits = []
+ for w in works:
+ oa = (w.get("best_oa_location") or {}).get("pdf_url")
+ url = w.get("doi") or w.get("id") or ""
+ if not url:
+ continue
+ hit = {"title": clean(w.get("display_name") or ""), "url": url}
+ if oa:
+ hit["also"] = [oa]
+ hits.append(hit)
+ digest.append_records(Path(topic).expanduser(), [{
+ "round": round_, "by": "chain.py", "method": cmd, "query": key, "hits": hits}])
+
+
if __name__ == "__main__":
try:
sys.exit(main())
diff --git a/skills/imozuru/scripts/digest.py b/skills/imozuru/scripts/digest.py
new file mode 100644
index 0000000..e837e96
--- /dev/null
+++ b/skills/imozuru/scripts/digest.py
@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""調べ終えたあとの詳細レポート(digest.html)を作る。解説と、検索の全記録の2層。
+
+抜き書き(report.py)は原文を切り出して並べるだけで、その分野を知らない人には
+読む順も言葉の意味も分からない。詳細レポートは、止めたあとに初めて解説を書く場所で、
+前提知識ゼロ向けの「入門編」と、隣の分野を知っている人向けの「隣接分野編」を分けて置く。
+要約を止めていたのは早すぎる閉じ(Kuhlthau 1991)を避けるためなので、調べを止めた後なら書いてよい。
+
+解説の1文ごとに、原文からそのまま切り出した文(ファイル・行)を根拠として付ける。
+根拠は report.py と同じ照合にかけ、1つでも合わない・根拠の無い文があれば HTML は作らない。
+記録の層は queries.jsonl(検索語ごとのヒットの全件)と fetch-log.jsonl(fetch.py の
+取得の記録)から機械で組み、エージェントは書かない。空振りの検索語もそのまま載る。
+
+使い方:
+ digest.py add <topic_dir> [--round N] [--by 誰] … 標準入力の JSON を queries.jsonl に足す
+ JSON は記録の配列: [{"query", "method"?, "round"?, "by"?, "hits": [{"title", "url", "also"?}]}]
+ --round・--by は、記録に無いときの既定値
+ digest.py <topic_dir> … digest.json と queries.jsonl → digest.html
+ digest.py <topic_dir> --check … 照合だけして HTML は作らない
+
+digest.json の形:
+ {"title", "question", "stopped",
+ "levels": {"intro": 編, "adjacent": 編},
+ "people_places": [文], "unresolved": ["..."]}
+ 編 = {"summary": [文], "terms": [{"term", "sentences": [文]}], "answers": [{"claim", "sentences": [文]}]}
+ 文 = {"text", "quotes": [{"file", "line", "end"?, "text"}]}
+"""
+
+import html
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import report # noqa: E402 照合と引用の描画は抜き書きと同じものを使う
+
+QUERIES = "queries.jsonl"
+FETCH_LOG = "fetch-log.jsonl"
+LEVELS = (("intro", "入門編", "前提知識が無い人向け"),
+ ("adjacent", "隣接分野編", "近い分野を知っている人向け"))
+
+
+def append_records(topic: Path, records: list[dict]) -> int:
+ """検索の記録を queries.jsonl の末尾に足す。足した件数を返す。"""
+ topic.mkdir(parents=True, exist_ok=True)
+ with (topic / QUERIES).open("a", encoding="utf-8") as f:
+ for r in records:
+ f.write(json.dumps(r, ensure_ascii=False) + "\n")
+ return len(records)
+
+
+def normalize_record(r: dict, round_: int | None, by: str | None) -> dict:
+ """形を確かめてそろえる。query と hits が無い記録は受け付けない(空振りは hits を空の配列で書く)。"""
+ if not isinstance(r, dict) or not isinstance(r.get("query"), str) or not r["query"].strip():
+ raise ValueError(f"query の無い記録: {json.dumps(r, ensure_ascii=False)[:80]}")
+ hits = r.get("hits")
+ if not isinstance(hits, list):
+ raise ValueError(f"hits が配列でない(空振りは []): {r['query']}")
+ out_hits = []
+ for h in hits:
+ if not isinstance(h, dict) or not isinstance(h.get("url"), str):
+ raise ValueError(f"url の無いヒット: {r['query']}")
+ hit = {"title": str(h.get("title") or ""), "url": h["url"]}
+ if h.get("also"):
+ hit["also"] = [str(u) for u in h["also"]]
+ out_hits.append(hit)
+ rnd = r.get("round", round_)
+ if type(rnd) is not int:
+ raise ValueError(f"周(round)が整数でない: {r['query']}")
+ return {"round": rnd, "by": str(r.get("by") or by or "不明"),
+ "method": str(r.get("method") or "WebSearch"), "query": r["query"], "hits": out_hits}
+
+
+def url_key(url: str) -> str:
+ """照合用に URL をそろえる。http と https、www、末尾の /、#以降の違いは同じものとして扱う。"""
+ try:
+ p = urlsplit(url.strip())
+ except ValueError:
+ return url.strip()
+ host = (p.hostname or "").lower().removeprefix("www.")
+ path = p.path.rstrip("/")
+ return f"{host}{path}" + (f"?{p.query}" if p.query else "")
+
+
+def load_jsonl(path: Path) -> list[dict]:
+ if not path.is_file():
+ return []
+ rows = []
+ for line in path.read_text(encoding="utf-8").splitlines():
+ if line.strip():
+ rows.append(json.loads(line))
+ return rows
+
+
+def fetch_status(fetches: list[dict]) -> dict[str, dict]:
+ """URL ごとの最後の取得の結果。同じ URL を取り直したら新しいほうを使う。"""
+ return {url_key(f["url"]): f for f in fetches if isinstance(f.get("url"), str)}
+
+
+def sentence_problems(src: Path, where: str, sentences) -> list[str]:
+ """文の並びを照合する。根拠の無い文・原文に無い引用を、場所つきで返す。"""
+ bad = []
+ if not isinstance(sentences, list) or not sentences:
+ return [f"{where}: 文が無い"]
+ for i, s in enumerate(sentences, 1):
+ if not isinstance(s, dict) or not isinstance(s.get("text"), str) or not s["text"].strip():
+ bad.append(f"{where} {i}文目: text が無い")
+ continue
+ quotes = s.get("quotes")
+ if not isinstance(quotes, list) or not quotes:
+ bad.append(f"{where} {i}文目「{s['text'][:30]}」: 根拠の引用が無い")
+ continue
+ for q in quotes:
+ if not isinstance(q, dict) or not report.verify(src, q)[0]:
+ loc = f"{q.get('file')}:{q.get('line')}" if isinstance(q, dict) else "?"
+ bad.append(f"{where} {i}文目「{s['text'][:30]}」: 原文に見つからない引用 {loc}")
+ return bad
+
+
+def check(topic: Path, data: dict) -> list[str]:
+ src = topic / "sources"
+ bad = []
+ levels = data.get("levels") or {}
+ for key, name, _ in LEVELS:
+ lv = levels.get(key)
+ if not isinstance(lv, dict):
+ bad.append(f"{name}が無い")
+ continue
+ bad += sentence_problems(src, f"{name}の要旨", lv.get("summary"))
+ for t in lv.get("terms") or []:
+ bad += sentence_problems(src, f"{name}の用語「{t.get('term')}」", t.get("sentences"))
+ for a in lv.get("answers") or []:
+ bad += sentence_problems(src, f"{name}の主張「{a.get('claim')}」", a.get("sentences"))
+ if data.get("people_places"):
+ bad += sentence_problems(src, "人と場", data["people_places"])
+ return bad
+
+
+esc = report.esc
+
+
+def link(url: str, text: str) -> str:
+ """http(s) だけをリンクにする。javascript: などはそのまま文字で出す。"""
+ if urlsplit(url).scheme in ("http", "https"):
+ return f'<a href="{esc(url)}" rel="noreferrer noopener">{esc(text or url)}</a>'
+ return esc(text or url)
+
+
+class Notes:
+ """編ごとの脚注。文の後ろに [n] を付け、引用は節の末尾に並べる。"""
+
+ def __init__(self, src: Path, prefix: str):
+ self.src, self.prefix, self.items = src, prefix, []
+
+ def sentence(self, s: dict) -> str:
+ marks = []
+ for q in s["quotes"]:
+ self.items.append(q)
+ n = len(self.items)
+ marks.append(f'<a class="fn" href="#{self.prefix}{n}">[{n}]</a>')
+ return esc(s["text"]) + "".join(marks)
+
+ def paragraph(self, sentences: list[dict]) -> str:
+ # 1文ごとに改行する。続けて組むと、どの番号がどの文の根拠かを目で追いにくい
+ return '<p class="lines">' + "".join(f"<span>{self.sentence(s)}</span>" for s in sentences) + "</p>"
+
+ def render(self) -> str:
+ if not self.items:
+ return ""
+ out = ['<details class="notes"><summary>根拠の原文(' + str(len(self.items)) + '件)</summary><ol>']
+ for n, q in enumerate(self.items, 1):
+ _, ctx, c0, _ = report.verify(self.src, q)
+ out.append(f'<li id="{self.prefix}{n}">' + report.quote_html(self.src, q, ctx, c0) + "</li>")
+ out.append("</ol></details>")
+ return "\n".join(out)
+
+
+def level_html(src: Path, key: str, name: str, lead: str, lv: dict) -> str:
+ notes = Notes(src, f"{key}-")
+ body = [f'<section id="{key}"><h2>{esc(name)}<span class="status">{esc(lead)}</span></h2>',
+ "<h3>要旨</h3>", notes.paragraph(lv["summary"])]
+ if lv.get("terms"):
+ body.append("<h3>用語</h3><dl>")
+ for t in lv["terms"]:
+ body.append(f"<dt>{esc(t['term'])}</dt><dd>{notes.paragraph(t['sentences'])}</dd>")
+ body.append("</dl>")
+ if lv.get("answers"):
+ body.append("<h3>主張ごとの答え</h3>")
+ for a in lv["answers"]:
+ body.append(f'<h4>{esc(a["claim"])}</h4>{notes.paragraph(a["sentences"])}')
+ body.append(notes.render())
+ body.append("</section>")
+ return "\n".join(body)
+
+
+def records_html(records: list[dict], fetched: dict[str, dict]) -> str:
+ """検索の全記録。周ごとに折りたたみ、検索語ごとにヒットを全件並べる。"""
+ linked = set()
+ total_hits = sum(len(r["hits"]) for r in records)
+ empty = sum(1 for r in records if not r["hits"])
+ body = ['<section id="record"><h2>記録<span class="status">機械で生成</span></h2>',
+ f'<p class="note">検索 {len(records)}本・ヒット {total_hits}件・空振り {empty}本。'
+ "ヒットは検索で挙がったものの全件で、〔保存〕は fetch.py が原文を保存できたもの。</p>"]
+ for rnd in sorted({r["round"] for r in records}):
+ rs = [r for r in records if r["round"] == rnd]
+ n_hits = sum(len(r["hits"]) for r in rs)
+ body.append(f"<details><summary>{rnd}周目(検索 {len(rs)}本・ヒット {n_hits}件)</summary>")
+ for r in rs:
+ body.append(f'<h4>「{esc(r["query"])}」<span class="meta">{esc(r["by"])}・{esc(r["method"])}</span></h4>')
+ if not r["hits"]:
+ body.append('<p class="note">ヒット0</p>')
+ continue
+ body.append("<ul class=\"hits\">")
+ for h in r["hits"]:
+ f = None
+ for u in [h["url"], *h.get("also", [])]:
+ k = url_key(u)
+ if k in fetched:
+ f = fetched[k]
+ linked.add(k)
+ break
+ if f is None:
+ tag = '<span class="tag">未取得</span>'
+ elif f.get("status") == "OK":
+ tag = f'<span class="tag ok">保存</span><code>{esc(f.get("file", ""))}</code>'
+ else:
+ tag = f'<span class="tag ng">取得失敗</span><span class="cn">{esc(f.get("reason", ""))}</span>'
+ body.append(f"<li>{tag} {link(h['url'], h['title'])}</li>")
+ body.append("</ul>")
+ body.append("</details>")
+ loose = [f for k, f in fetched.items() if k not in linked]
+ if loose:
+ body.append("<h3>どの検索にも結び付かない取得</h3>"
+ '<p class="note">記事の中のリンクをたどったものや、検索の URL と取得の URL が違うもの。</p><ul class="hits">')
+ for f in loose:
+ st = "保存" if f.get("status") == "OK" else "取得失敗"
+ detail = f.get("file", "") if f.get("status") == "OK" else f.get("reason", "")
+ body.append(f'<li><span class="tag">{st}</span> {link(f["url"], f["url"])} <code>{esc(detail)}</code></li>')
+ body.append("</ul>")
+ body.append("</section>")
+ return "\n".join(body)
+
+
+CSS = report.CSS + """
+nav{display:flex;flex-wrap:wrap;gap:.4rem 1rem;margin:1rem 0;font-size:.9rem}
+a{color:var(--accent)}
+h3{font-size:1.05rem;margin:2rem 0 .3rem}
+h4{font-size:.95rem;margin:1.2rem 0 .2rem}
+dt{font-weight:600;margin-top:1rem}
+dd{margin:0}
+dd p{margin:.2rem 0}
+p.lines span{display:block;margin:.15rem 0}
+a.fn{font-size:.7rem;vertical-align:super;text-decoration:none;margin-left:.1rem}
+.meta{font-weight:400;font-size:.8rem;color:var(--sub);margin-left:.5rem}
+ul.hits{padding-left:1.1rem;font-size:.88rem}
+ul.hits li{margin:.25rem 0;overflow-wrap:anywhere}
+.tag.ok{border-color:var(--accent);color:var(--accent)}
+.tag.ng{border-style:dashed}
+.notes ol{padding-left:1.4rem}
+.cn{font-size:.8rem;color:var(--sub);margin-left:.3rem}
+"""
+
+
+def build(topic: Path, check_only: bool) -> int:
+ data = json.loads((topic / "digest.json").read_text(encoding="utf-8"))
+ records = load_jsonl(topic / QUERIES)
+ bad = check(topic, data)
+ if bad:
+ print("根拠の照合に通らない文がある(根拠が無いか、引用が原文と合わない):")
+ print("\n".join(" " + b for b in bad))
+ return 1
+ print(f"照合 OK: 解説の文がすべて原文の引用を持つ・検索の記録 {len(records)}本")
+ if check_only:
+ return 0
+
+ src = topic / "sources"
+ fetched = fetch_status(load_jsonl(topic / FETCH_LOG))
+ nav = ['<a href="#intro">入門編</a>', '<a href="#adjacent">隣接分野編</a>']
+ body = [f"<h1>{esc(data['title'])}</h1>",
+ f'<p class="lead">問い: {esc(data["question"])}</p>',
+ f'<p class="lead">止めた理由: {esc(data["stopped"])}</p>',
+ '<p class="note">解説の文の後ろの番号は、その文の根拠として原文からそのまま切り出した引用(機械で照合済み)。'
+ "解説はエージェントが書いた。記録の層は機械で組んだ。</p>"]
+ sections = [level_html(src, k, n, lead, data["levels"][k]) for k, n, lead in LEVELS]
+ if data.get("people_places"):
+ notes = Notes(src, "pp-")
+ sections.append('<section id="people"><h2>人と場</h2>' + notes.paragraph(data["people_places"])
+ + notes.render() + "</section>")
+ nav.append('<a href="#people">人と場</a>')
+ if data.get("unresolved"):
+ sections.append('<section id="open"><h2>未解決</h2><ul>'
+ + "".join(f"<li>{esc(u)}</li>" for u in data["unresolved"]) + "</ul></section>")
+ nav.append('<a href="#open">未解決</a>')
+ sections.append(records_html(records, fetched))
+ nav.append('<a href="#record">記録</a>')
+ body.append("<nav>" + "".join(nav) + "</nav>")
+ body += sections
+ body.append(f'<footer>imozuru の詳細レポート・原文はこのページと同じ場所の {esc(src.name)}/</footer>')
+
+ page = f"""<!doctype html>
+<html lang="ja"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>{esc(data['title'])} 詳細レポート</title><style>{CSS}</style></head>
+<body><main>
+{chr(10).join(body)}
+</main></body></html>
+"""
+ out = topic / "digest.html"
+ # 一時ファイルに書いてから置き換える。途中で止まっても前のページが壊れずに残る
+ tmp = out.with_name(".digest.html.tmp")
+ tmp.write_text(page, encoding="utf-8")
+ os.replace(tmp, out)
+ print(f"→ {out}")
+ return 0
+
+
+def add(argv: list[str]) -> int:
+ topic = Path(argv[0]).expanduser()
+ round_, by = None, None
+ rest = argv[1:]
+ while rest:
+ flag = rest.pop(0)
+ if flag == "--round" and rest and re.fullmatch(r"[0-9]+", rest[0]):
+ round_ = int(rest.pop(0))
+ elif flag == "--by" and rest:
+ by = rest.pop(0)
+ else:
+ print(f"分からない指定: {flag}", file=sys.stderr)
+ return 2
+ try:
+ raw = json.loads(sys.stdin.read() or "[]")
+ records = [normalize_record(r, round_, by) for r in (raw if isinstance(raw, list) else [raw])]
+ except ValueError as e: # 壊れた JSON も ValueError
+ print(f"足せなかった: {e}", file=sys.stderr)
+ return 1
+ topic.mkdir(parents=True, exist_ok=True)
+ n = append_records(topic, records)
+ print(f"{n}本を {topic / QUERIES} に足した(ヒット {sum(len(r['hits']) for r in records)}件)")
+ return 0
+
+
+def main() -> int:
+ args = sys.argv[1:]
+ if not args:
+ print(__doc__, file=sys.stderr)
+ return 2
+ if args[0] == "add" and len(args) >= 2:
+ return add(args[1:])
+ return build(Path(args[0]).expanduser(), "--check" in args[1:])
+
+
+if __name__ == "__main__":
+ sys.stdout.reconfigure(errors="replace")
+ sys.exit(main())
diff --git a/skills/imozuru/scripts/fetch.py b/skills/imozuru/scripts/fetch.py
index 4dfb893..2faf6e3 100755
--- a/skills/imozuru/scripts/fetch.py
+++ b/skills/imozuru/scripts/fetch.py
@@ -17,7 +17,10 @@
"""
import codecs
+import contextlib
+import io
import ipaddress
+import json
import os
import re
import shutil
@@ -859,8 +862,41 @@ def main() -> int:
sources.mkdir(parents=True, exist_ok=True)
# 変換や FAIL の後始末は一時置き場だけで行う。同名の原文を検査前に上書きしない。
# 保存先の中に作るので、成功時の replace はファイルシステムをまたがない。
- with tempfile.TemporaryDirectory(prefix=".imozuru-fetch-", dir=sources) as tmp:
- return fetch_source(Path(tmp), name, url, sources)
+ # 結果の行は画面に出すのと同じものを取得の記録にも残す。詳細レポート(digest.py)が
+ # 検索で挙がった URL と突き合わせて〔保存〕〔取得失敗〕を付ける。URL は OK の行に出ないので、ここで書く
+ buf = io.StringIO()
+ try:
+ with tempfile.TemporaryDirectory(prefix=".imozuru-fetch-", dir=sources) as tmp, \
+ contextlib.redirect_stdout(buf):
+ code = fetch_source(Path(tmp), name, url, sources)
+ finally:
+ sys.stdout.write(buf.getvalue())
+ record_fetch(sources, name, url, buf.getvalue())
+ return code
+
+
+def record_fetch(sources: Path, name: str, url: str, printed: str) -> None:
+ """最後の OK/FAIL の行を、調べものの置き場の fetch-log.jsonl に1行足す。書けなくても取得の結果は変えない。
+
+ 置き場は sources/ の親。sources/ には原文だけを置く決まりなので、記録は外に出す。
+ 保存先が sources という名前でないとき(手で別の場所を指したとき)は、親が何か分からないので書かない。
+ """
+ if sources.name != "sources":
+ return
+ lines = [l for l in printed.splitlines() if l.startswith(("OK\t", "FAIL\t"))]
+ if not lines:
+ return
+ parts = lines[-1].split("\t")
+ entry = {"url": url, "name": name, "status": parts[0]}
+ if parts[0] == "OK" and len(parts) > 2:
+ entry["file"] = Path(parts[2]).name
+ elif len(parts) > 2:
+ entry["reason"] = parts[2]
+ try:
+ with (sources.parent / "fetch-log.jsonl").open("a", encoding="utf-8") as f:
+ f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+ except OSError:
+ pass
if __name__ == "__main__":
diff --git a/tests/test_digest.py b/tests/test_digest.py
new file mode 100644
index 0000000..143f022
--- /dev/null
+++ b/tests/test_digest.py
@@ -0,0 +1,188 @@
+"""詳細レポート(digest.py)と、その記録を作る fetch.py・chain.py の口を検査する。"""
+
+import contextlib
+import importlib.util
+import io
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPTS = Path(__file__).resolve().parents[1] / "skills/imozuru/scripts"
+
+
+def load(name):
+ spec = importlib.util.spec_from_file_location(f"digest_{name}", SCRIPTS / f"{name}.py")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+digest = load("digest")
+fetch = load("fetch")
+chain = load("chain")
+
+SOURCE = "Sunlight is scattered by air molecules.\nBlue light scatters more than red light.\n"
+
+
+def sentence(text, line=2, quote="Blue light scatters more than red light."):
+ return {"text": text, "quotes": [{"file": "paper.txt", "line": line, "text": quote}]}
+
+
+def level():
+ return {"summary": [sentence("青い光ほど強く散らばる。")],
+ "terms": [{"term": "散乱", "sentences": [sentence("光が粒に当たって向きを変えること。", 1,
+ "Sunlight is scattered by air molecules.")]}],
+ "answers": [{"claim": "なぜ赤いか", "sentences": [sentence("青が先に散って赤が残る。")]}]}
+
+
+class DigestTests(unittest.TestCase):
+ def setUp(self):
+ tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(tmp.cleanup)
+ self.topic = Path(tmp.name) / "sunset"
+ (self.topic / "sources").mkdir(parents=True)
+ (self.topic / "sources" / "paper.txt").write_text(SOURCE, encoding="utf-8")
+ self.data = {"title": "夕焼け", "question": "なぜ赤いか", "stopped": "主張に原文が付いた",
+ "levels": {"intro": level(), "adjacent": level()},
+ "people_places": [sentence("散乱の論文がある。")],
+ "unresolved": ["雲の色は調べていない"]}
+
+ def build(self, *extra):
+ (self.topic / "digest.json").write_text(json.dumps(self.data, ensure_ascii=False), encoding="utf-8")
+ out = io.StringIO()
+ with patch.object(sys, "argv", ["digest.py", str(self.topic), *extra]), contextlib.redirect_stdout(out):
+ code = digest.main()
+ return code, out.getvalue()
+
+ def add(self, payload, *flags):
+ out = io.StringIO()
+ with patch.object(sys, "argv", ["digest.py", "add", str(self.topic), *flags]), \
+ patch.object(sys, "stdin", io.StringIO(json.dumps(payload, ensure_ascii=False))), \
+ contextlib.redirect_stdout(out), contextlib.redirect_stderr(io.StringIO()):
+ return digest.main()
+
+ def test_cited_digest_builds_page_with_both_levels(self):
+ code, _ = self.build()
+ self.assertEqual(code, 0)
+ page = (self.topic / "digest.html").read_text(encoding="utf-8")
+ self.assertIn("入門編", page)
+ self.assertIn("隣接分野編", page)
+ self.assertIn("Blue light scatters more than red light.", page)
+
+ def test_sentence_without_quote_is_rejected(self):
+ self.data["levels"]["intro"]["summary"].append({"text": "根拠の無い文。", "quotes": []})
+ code, out = self.build()
+ self.assertEqual(code, 1)
+ self.assertIn("根拠の引用が無い", out)
+ self.assertFalse((self.topic / "digest.html").exists())
+
+ def test_paraphrased_quote_is_rejected(self):
+ self.data["levels"]["adjacent"]["answers"][0]["sentences"] = [
+ sentence("言い換え。", 2, "Blue light is scattered more strongly.")]
+ code, out = self.build()
+ self.assertEqual(code, 1)
+ self.assertIn("原文に見つからない引用", out)
+
+ def test_quote_outside_sources_is_rejected(self):
+ self.data["people_places"] = [sentence("外。", 1, "x") | {"quotes": [{"file": "../digest.json", "line": 1, "text": "{"}]}]
+ code, _ = self.build()
+ self.assertEqual(code, 1)
+
+ def test_both_levels_are_required(self):
+ del self.data["levels"]["adjacent"]
+ code, out = self.build()
+ self.assertEqual(code, 1)
+ self.assertIn("隣接分野編が無い", out)
+
+ def test_failed_build_keeps_prior_page(self):
+ (self.topic / "digest.html").write_text("Previous", encoding="utf-8")
+ self.data["levels"]["intro"]["summary"] = []
+ code, _ = self.build()
+ self.assertEqual(code, 1)
+ self.assertEqual((self.topic / "digest.html").read_text(encoding="utf-8"), "Previous")
+
+ def test_records_list_every_hit_empty_queries_and_fetch_status(self):
+ self.assertEqual(self.add([
+ {"query": "why is the sunset red", "hits": [
+ {"title": "Paper", "url": "http://www.example.test/paper/"},
+ {"title": "Blog", "url": "https://blog.example.test/a"},
+ {"title": "Gone", "url": "https://gone.example.test/"}]},
+ {"query": "夕焼け 赤い 理由 論文", "hits": []}], "--round", "0", "--by", "検索役A"), 0)
+ (self.topic / "fetch-log.jsonl").write_text(
+ json.dumps({"url": "https://example.test/paper", "name": "paper", "status": "OK", "file": "paper.txt"}) + "\n"
+ + json.dumps({"url": "https://gone.example.test", "name": "gone", "status": "FAIL", "reason": "404"}) + "\n"
+ + json.dumps({"url": "https://other.example.test/x", "name": "x", "status": "OK", "file": "x.md"}) + "\n",
+ encoding="utf-8")
+ code, _ = self.build()
+ self.assertEqual(code, 0)
+ page = (self.topic / "digest.html").read_text(encoding="utf-8")
+ self.assertIn("検索 2本・ヒット 3件・空振り 1本", page)
+ self.assertIn("ヒット0", page)
+ self.assertIn("未取得", page)
+ self.assertIn("取得失敗", page)
+ self.assertIn("paper.txt", page)
+ # 検索で挙がっていない取得も隠さず出す
+ self.assertIn("other.example.test/x", page)
+
+ def test_non_http_hit_is_not_linked(self):
+ self.add([{"query": "q", "hits": [{"title": "bad", "url": "javascript:alert(1)"}]}], "--round", "1")
+ self.build()
+ page = (self.topic / "digest.html").read_text(encoding="utf-8")
+ self.assertNotIn('href="javascript:', page)
+
+ def test_add_rejects_record_without_hits_array(self):
+ self.assertEqual(self.add([{"query": "q"}], "--round", "1"), 1)
+ self.assertEqual(self.add([{"query": "q", "hits": []}]), 1) # 周が無い
+ self.assertFalse((self.topic / "queries.jsonl").exists())
+
+
+class FetchLogTests(unittest.TestCase):
+ def test_fetch_result_is_recorded_beside_sources(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ sources = Path(tmp) / "topic" / "sources"
+ with patch.object(sys, "argv", ["fetch.py", str(sources), "x", "file:///etc/passwd"]), \
+ contextlib.redirect_stdout(io.StringIO()):
+ self.assertEqual(fetch.main(), 1)
+ rows = [json.loads(l) for l in (sources.parent / "fetch-log.jsonl").read_text().splitlines()]
+ self.assertEqual(rows[0]["status"], "FAIL")
+ self.assertEqual(rows[0]["url"], "file:///etc/passwd")
+ self.assertEqual(list(sources.iterdir()), [])
+
+ def test_fetch_log_is_skipped_outside_a_sources_folder(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ target = Path(tmp) / "elsewhere"
+ with patch.object(sys, "argv", ["fetch.py", str(target), "x", "file:///etc/passwd"]), \
+ contextlib.redirect_stdout(io.StringIO()):
+ fetch.main()
+ self.assertFalse((Path(tmp) / "fetch-log.jsonl").exists())
+
+
+class ChainLogTests(unittest.TestCase):
+ def test_chain_log_records_listed_works(self):
+ works = {"meta": {"count": 1}, "results": [
+ {"id": "https://openalex.org/W1", "display_name": "Rayleigh", "publication_year": 1871,
+ "cited_by_count": 9, "doi": "https://doi.org/10.1/x",
+ "best_oa_location": {"pdf_url": "https://example.test/x.pdf"}}]}
+ with tempfile.TemporaryDirectory() as tmp:
+ with patch.object(chain, "resolve", return_value={"id": "https://openalex.org/W9"}), \
+ patch.object(chain, "get", return_value=works), \
+ patch.object(sys, "argv", ["chain.py", "cites", "W9", "--log", tmp, "--round", "2"]), \
+ contextlib.redirect_stdout(io.StringIO()):
+ self.assertEqual(chain.main(), 0)
+ row = json.loads((Path(tmp) / "queries.jsonl").read_text())
+ self.assertEqual((row["round"], row["method"], row["by"]), (2, "cites", "chain.py"))
+ self.assertEqual(row["hits"][0]["url"], "https://doi.org/10.1/x")
+ self.assertEqual(row["hits"][0]["also"], ["https://example.test/x.pdf"])
+
+ def test_chain_log_requires_round(self):
+ with patch.object(sys, "argv", ["chain.py", "cites", "W9", "--log", "/tmp/x"]), \
+ contextlib.redirect_stderr(io.StringIO()):
+ self.assertEqual(chain.main(), 2)
+
+
+if __name__ == "__main__":
+ unittest.main()