thth 3.8.2__tar.gz → 3.9.0__tar.gz

{thth-3.8.2 → thth-3.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thth
-Version: 3.8.2
+Version: 3.9.0
 Summary: 承認済みの投稿だけを投げる門（Threads・Bluesky・Mastodon）。人が承認し、記録は利用者の git に残る。
 Project-URL: Homepage, https://thth.me
 Project-URL: Source, https://github.com/aokings/thth

{thth-3.8.2 → thth-3.9.0}/skills/thth/SKILL.md

@@ -19,6 +19,8 @@ description: 投稿する前・返信を書く前・出したあと・絡みに
 
 **click はリンク先を投稿ごとに分けると投稿単位で測れる**（3.7.0）。あるリンク先を前後 72 時間で 1 本の投稿しか使っていなければ、`clicks_by_url` のそのリンク先の投稿日を含む 3 暦日のクリックを投稿のものとして出す（`basis: unique_url_72h`・`window: post_day_plus_2`・クリック率は clicks_72h / views_24h）。同じリンク先を前後 72 時間に 2 本以上で使う・リンクが無い・プロフィールのリンク（台帳の `profile_links`）と同じなら `url_shared_72h`・`no_link`・`profile_link` で言わない。lint は同じリンク先を前後 72 時間に使う click の原稿を `warning: url_shared_72h` で知らせる（断らない・同じ日でもリンク先が違えば測れる）。**本文に札（utm）を付けて書き換えない**——リンク先を分ける。follow の投稿が毎日出ていれば `no_comparison_days`（事実だけ・推奨しない）。週の表は `thth analytics-report <account> --weekly-goals --weeks 6`（観察の表）。承認は 1 段目だけでは出ない——**確定するまで出ません**（queue・board・observe に「確定待ち」、publish_at まで 3 時間を切ると observe の次の一手に `confirm_due` と確定の命令）。`thth account` は「run を止めるもの」と「run が自分で直すもの」（repo が遅れているだけ）を分け、出られない原稿（held）は別の段（「投稿できます」のまま）。連投も段ごとのリンク先が記録に残り、click の照合に入る。`thth lint`・`preview`・`approve` は手元の Mac のパス（`…/docs/sns/queue/<file>`）を VM のパスに読み替える。`thth where` は `--also <語>`（同じ結果を絞るだけ・追加の検索なし）・0 件は `zero_or_filtered`（無いのか受け付けなかったのか区別できない）・`--aggregate [--lexicon <file>]`（数と時刻だけ・本文も username も返さない・保存しない）。
 
+**検索の語は道具が数えて候補を出し、クリックは目的に依らず投稿ごとに見る**（3.9.0）。`thth analytics-report <account> --per-post-clicks [--since 30d]` は goal を問わず、一意のリンク先の投稿（`unique_url_72h`）の 72h のクリック・クリック率・窓の後（参考）・窓の前（`clicks_before_post`）を並べる——goal の層とは混ぜない（unrecorded の投稿もリンク先が記録にあれば並ぶ）。**窓の前と後は窓の和に足さない**。`clicks_before_post` が 1 以上なら「THTH を通していない投稿か Threads の外のクリックが混ざっている可能性」の 1 行（原因は言わない）。`--by goal` の click にも同じ欄。`thth where <account> <語…> --also <語>` は語ごとの当たり率（取れた件数・also に合った件数）を高い順に並べ、0 件の語に「also に合った投稿が 0 件（直近 n 日）」。`--suggest` は語の候補: 自分のデータ（地図の点・原稿の topic と goal・反応の多かった topic）が先、次に also に合った投稿の本文で 2 投稿以上に出た語（その場の人が書いた語・上位 10）。**語と数だけで、本文・username・post_id は出ない・保存しない**（MCP の `where_to_appear` には無い）。`--aggregate` の `rate_by_span` は返った投稿の期間で割った速さ（n と期間の時間つき・n < 20 は `rough`）。要求数に届かず期間が短いと `more_may_exist`（これで全部かは区別できない）。
+
 段だけを読み直したいときは `thth handoff-report <account> --since-last-read --json` を読む。`tool.changed_since_last_read` が真なら、手元の `tool.notes_root_local_hint` を手掛かりに `tool.release_notes` の相対名を読んでから作業する。既読の記録は `--mark-read --by <名前>` の明示時だけ。`tool.notes_reason` が `notes_directory_unavailable` なら、このインストールには読める docs がない。空の `release_notes` を「変更なし」と解釈しない。
 
 添付を付ける前に `tool.capabilities` を読む（媒体ごとの「出せるもの」表。`thth doctor` にも同じ表が出る。`unverified` は「非対応」ではない）。

thth-3.9.0/tests/test_v390_docs.py

@@ -0,0 +1,51 @@
+"""3.9.0 文書と skill（設計 3.9.0 §A〜§C）。
+
+見るのは:
+  - skill と使い方の文書に 3.9.0 の段（--per-post-clicks・clicks_before_post・also の当たり率・
+    --suggest は語と数だけで保存しない・rate_by_span・more_may_exist）。
+  - リリースノートの題（「— 下書き」の有無は固定しない）と、各 project のセッション向けの 5 行、
+    材料の報告 id。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+REPORT_IDS = ("r20260924-8b8d37b5", "r20260924-9d3a6e1a", "r20260924-a1ba1829")
+
+
+def test_skillに3_9_0の段():
+    skill = (ROOT / "skills" / "thth" / "SKILL.md").read_text(encoding="utf-8")
+    marker = "**検索の語は道具が数えて候補を出し、クリックは目的に依らず投稿ごとに見る**（3.9.0）"
+    assert marker in skill
+    section = skill.split(marker)[1].split("\n\n")[0]
+    for text in ("--per-post-clicks", "unique_url_72h", "goal の層とは混ぜない", "clicks_before_post",
+                 "**窓の前と後は窓の和に足さない**", "--also", "also に合った投稿が 0 件",
+                 "--suggest", "**語と数だけで、本文・username・post_id は出ない・保存しない**",
+                 "where_to_appear", "rate_by_span", "rough", "more_may_exist"):
+        assert text in section, text
+
+
+def test_使い方の文書に3_9_0の段():
+    doc = (ROOT / "docs" / "使い方_プロジェクトのセッション向け_2026-09-09.md").read_text(encoding="utf-8")
+    heading = "## 3.9.0: 検索の語選びと、クリック・速さの見え方"
+    assert heading in doc
+    section = doc.split(heading)[1].split("\n## ")[0]
+    for text in ("--per-post-clicks", "unrecorded", "clicks_before_post", "**窓の前と後は窓の和に足しません**",
+                 "原因は言えません", "--also", "also に合った投稿が 0 件（直近 n 日）", "--suggest",
+                 "その場の人が書いた語", "**語と数だけで、本文・username・post_id・author_key は出ません。"
+                 "候補も当たり率も保存しません**", "rate_by_span", "rough: true", "more_may_exist",
+                 "一次資料で未確認"):
+        assert text in section, text
+
+
+def test_リリースノートの題とセッション向けの5行と材料の報告id():
+    note = (ROOT / "docs" / "リリースノート_3.9.0_2026-09-24.md").read_text(encoding="utf-8")
+    assert note.startswith("# リリースノート 3.9.0（検索の語選びと、クリック・速さの見え方）")
+    section = note.split("## 各 project のセッション向け")[1].split("\n## ")[0]
+    lines = [line for line in section.splitlines() if line[:2] in ("1.", "2.", "3.", "4.", "5.")]
+    assert len(lines) == 5
+    assert "--per-post-clicks" in lines[0] and "clicks_before_post" in lines[1]
+    assert "--also" in lines[2] and "--suggest" in lines[3] and "rate_by_span" in lines[4]
+    for report_id in REPORT_IDS:
+        assert report_id in note, report_id

thth-3.9.0/tests/test_v390_per_post_clicks.py

@@ -0,0 +1,138 @@
+"""3.9.0 §A 投稿ごとのクリックを目的に依らず（`analytics-report <account> --per-post-clicks`）。
+
+- goal を問わず、unique_url_72h を満たす投稿を並べる（unrecorded でも出る）。
+  **goal の層（`--by goal`）とは混ぜない**。
+- 各投稿と全体に `clicks_before_post`（投稿日より前 3 暦日のそのリンク先のクリック）。
+  **窓の和（clicks_72h）には足さない**。1 以上なら静的な 1 行（原因は言わない）。
+- `--by goal` の click にも同じ欄。
+"""
+from __future__ import annotations
+
+import json
+
+from tests.test_v370_click_attribution import _clicks, _daily, _post, _yard, _by_id, _at
+from thth import analytics_clicks, cli, jst
+
+NOW = jst.parse("2026-09-24T12:00:00+09:00")
+URL_U = "https://example.com/u"
+
+
+def _fixture(account):
+    # U: goal を書く口が無かった頃の投稿（sent に goal の欄が無い＝unrecorded）。
+    _post(account, "U", _at("15T09:00:00"), text=f"記事 {URL_U}", goal=None, views=100)
+    _post(account, "R", _at("10T09:00:00"), text="https://example.com/r", goal="reach", views=50)
+    _post(account, "C", _at("19T09:00:00"), text="https://example.com/c", goal="click", views=40)
+    _post(account, "N", _at("20T09:00:00"), text="リンクなし", goal="reach")
+    rows = [("14", _clicks({URL_U: 1})),                        # 窓の前（投稿日の前日）
+            ("15", _clicks({URL_U: 5, "https://example.com/r": 1})),
+            ("16", _clicks({URL_U: 4})), ("17", _clicks({URL_U: 3})),
+            ("18", _clicks({URL_U: 2})), ("19", _clicks({URL_U: 2, "https://example.com/c": 6})),
+            ("20", _clicks({"https://example.com/c": 1})), ("21", {"clicks": 0}),
+            ("10", _clicks({"https://example.com/r": 2})), ("11", {"clicks": 0}),
+            ("12", _clicks({"https://example.com/r": 1})), ("13", {"clicks": 0})]
+    _daily(account, rows)
+
+
+def test_goalを問わず並べる_unrecordedでも出る_goalの層と混ぜない(isolated_account_factory):
+    account = isolated_account_factory()
+    _fixture(account)
+    payload = analytics_clicks.answer(account["name"], since="30d", now=NOW)
+    assert payload["report_type"] == "per_post_clicks" and payload["population"] == "all_goals"
+    ids = [row["post_id"] for row in payload["posts"]]
+    assert ids == ["R", "U", "C"], "reach・unrecorded・click のどれも並ぶ（投稿日時の順）"
+    assert payload["not_attributable"] == {"no_link": 1}
+    assert payload["summary"]["n_posts"] == 4 and payload["summary"]["n_attributable"] == 3
+    # 層に分けない・行に goal を持たない。
+    assert "strata" not in payload and "by_goal" not in payload
+    assert all("goal" not in row for row in payload["posts"])
+    # `--by goal` の click の層は click の投稿だけのまま（per-post-clicks を混ぜない）。
+    _payload, yard = _yard(account, now=NOW, window_days=14)
+    assert set(_by_id(yard)) == {"C"}
+
+
+def test_clicks_before_postは窓の和に足さない_静的な1行(isolated_account_factory):
+    account = isolated_account_factory()
+    _fixture(account)
+    payload = analytics_clicks.answer(account["name"], since="30d", now=NOW)
+    row = {r["post_id"]: r for r in payload["posts"]}["U"]
+    assert row["window_days"] == ["2026-09-15", "2026-09-16", "2026-09-17"]
+    assert row["clicks_72h"] == 12, "5+4+3（前日の 1 は足さない）"
+    assert row["clicks_before_post"] == 1
+    assert row["before_post"]["days"] == ["2026-09-12", "2026-09-13", "2026-09-14"]
+    assert row["before_post"]["days_counted"] == 3 and row["before_post"]["days_missing"] == 0
+    # 窓の後（参考）: 18〜21 日（2+2+0+0）。22・23 日は日次に行が無い（欠測）・24 日は閉じていない。
+    assert row["clicks_after_window"] == 4
+    assert row["after_window"]["days_missing"] == 2 and row["after_window"]["days_not_closed"] == 1
+    assert row["window_share"] == {
+        "value": round(12 / 17, 4), "numerator": 12, "denominator": 17,
+        "basis": "clicks_72h / (clicks_before_post + clicks_72h + clicks_after_window)",
+        "reason": None}
+    assert row["click_rate"] == 0.12 and row["rate_basis"] == "clicks_72h / views_24h"
+    s = payload["summary"]
+    assert s["clicks_before_post"]["sum"] == 1
+    assert payload["notes"] == [{"code": "clicks_before_post_present",
+                                 "message": analytics_clicks.BEFORE_PRESENT_NOTE}]
+    assert "原因は言えません" in analytics_clicks.BEFORE_PRESENT_NOTE
+    text = analytics_clicks.render_markdown(payload)
+    assert "窓の前 1（窓には足さない）" in text and "clicks_before_post_present" in text
+
+
+def test_窓の和の合計は窓の前を含まない(isolated_account_factory):
+    account = isolated_account_factory()
+    _fixture(account)
+    payload = analytics_clicks.answer(account["name"], since="30d", now=NOW)
+    by = {r["post_id"]: r for r in payload["posts"]}
+    assert by["R"]["clicks_72h"] == 2 + 0 + 1 and by["C"]["clicks_72h"] == 6 + 1 + 0
+    assert payload["summary"]["clicks_72h"]["sum"] == 12 + 3 + 7
+    assert payload["summary"]["clicks_72h"]["median"] == 7
+
+
+def test_同じリンク先のほかの投稿の窓の日は窓の前にも後にも数えない(isolated_account_factory):
+    account = isolated_account_factory()
+    url = "https://example.com/x"
+    _post(account, "X1", _at("10T09:00:00"), text=url)
+    _post(account, "X2", _at("13T12:00:00"), text=url)     # 75 時間後（共有ではない）
+    _daily(account, [(f"{d:02d}", _clicks({url: 1})) for d in range(7, 24)])
+    payload = analytics_clicks.answer(account["name"], since="30d", now=NOW)
+    by = {r["post_id"]: r for r in payload["posts"]}
+    before = by["X2"]["before_post"]
+    assert before["days"] == ["2026-09-10", "2026-09-11", "2026-09-12"]
+    assert before["days_excluded_other_post_window"] == 3
+    assert by["X2"]["clicks_before_post"] is None and before["reason"] == "no_countable_day"
+    after = by["X1"]["after_window"]
+    assert after["days_excluded_other_post_window"] == 3, "13〜15 日は X2 の窓"
+    assert by["X1"]["clicks_after_window"] == 4, "16〜19 日"
+    assert by["X1"]["clicks_before_post"] == 3, "7〜9 日"
+
+
+def test_by_goalのclickにもclicks_before_post(isolated_account_factory):
+    account = isolated_account_factory()
+    url = "https://example.com/c"
+    _post(account, "C", _at("19T09:00:00"), text=url)
+    _daily(account, [("18", _clicks({url: 2})), ("19", _clicks({url: 5})),
+                     ("20", _clicks({url: 1})), ("21", {"clicks": 0})])
+    payload, yard = _yard(account, now=NOW, window_days=14)
+    row = _by_id(yard)["C"]
+    assert row["clicks_72h"] == 6 and row["clicks_before_post"] == 2
+    assert yard["per_post"]["clicks_72h"]["median"] == 6, "窓の前は窓の和に入らない"
+    before = yard["clicks_before_post"]
+    assert before["sum"] == 2 and before["n"] == 1 and before["denominator"] == 1
+    assert before["code"] == "clicks_before_post_present"
+    from thth import analytics_report
+    assert "窓の前のクリック 2（窓には足さない）" in analytics_report.render_markdown(payload)
+
+
+def test_CLIのper_post_clicksとsinceの組み合わせ(isolated_account_factory, capsys):
+    account = isolated_account_factory()
+    _fixture(account)
+    name = account["name"]
+    assert cli.main(["analytics-report", name, "--per-post-clicks", "--since", "30d", "--json"]) == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out["report_type"] == "per_post_clicks" and out["period"]["since"] == "30d"
+    assert cli.main(["analytics-report", name, "--per-post-clicks"]) == 0
+    assert "# 投稿ごとのクリック" in capsys.readouterr().out
+    assert cli.main(["analytics-report", name, "--since", "30d"]) == 2
+    assert cli.main(["analytics-report", name, "--per-post-clicks", "--compare-previous",
+                     "--by", "goal"]) == 2
+    assert cli.main(["analytics-report", "--project", "p", "--per-post-clicks"]) == 2
+    assert cli.main(["analytics-report", name, "--per-post-clicks", "--since", "abc"]) == 2

thth-3.9.0/tests/test_v390_where_rate.py

@@ -0,0 +1,93 @@
+"""3.9.0 §C `--aggregate` の速さ（`rate_by_span`・`rough`・`more_may_exist`）。
+
+- `per_day = n / max(期間の日数, 1)` は、期間が 1 日より短いとどの語も「n 件／日」に揃って
+  見える。`rate_by_span` は返った投稿の期間（最古〜最新）の日数で割る（底上げしない）。
+  分母（n・期間の時間）を添え、n < 20 は `rough: true`。
+- 返った件数が要求数に届かず、期間が 24 時間未満で n が 5 以上なら
+  `cannot_say: more_may_exist`（これで全部か、もっとあるかは区別できない）。
+"""
+from __future__ import annotations
+
+import datetime
+import json
+
+import pytest
+
+from thth import accounts, adapters, cli, jst, where_cli
+
+BASE = jst.parse("2026-09-24T06:00:00+09:00")
+
+
+def _rows(n, hours, base=BASE):
+    step = hours / (n - 1) if n > 1 else 0
+    return [{"message_id": f"m{i}", "author_key": f"{i:016x}", "username": f"u{i}",
+             "timestamp": jst.iso(base + datetime.timedelta(hours=step * i)), "text": "本文"}
+            for i in range(n)]
+
+
+@pytest.fixture
+def search(isolated_account_factory, monkeypatch):
+    isolated_account_factory("one", media="threads")
+    monkeypatch.setattr(accounts, "load_token", lambda cfg: {"access_token": "FAKE"})
+    table = {}
+
+    class Fake:
+        def keyword_search(self, word, **kwargs):
+            return [dict(row) for row in table[word]]
+    monkeypatch.setattr(adapters, "make_adapter", lambda *a: Fake())
+    return table
+
+
+def _agg(result, word):
+    return result["by_account"]["one"]["by_word"][word]["aggregate"]
+
+
+def test_rate_by_spanは期間そのもので割る_per_dayと揃わない(search):
+    search["にぎやか"] = _rows(10, 6)      # 6 時間に 10 件
+    search["静か"] = _rows(10, 60)         # 60 時間に 10 件
+    result = where_cli.answer(account_name="one", words=["にぎやか", "静か"], aggregate_mode=True,
+                              now=BASE + datetime.timedelta(days=3))
+    busy, calm = _agg(result, "にぎやか"), _agg(result, "静か")
+    assert busy["per_day"] == 10.0, "従前の per_day は 1 日で底上げ"
+    assert busy["rate_by_span"] == {"value": 40.0, "unit": "per_day", "n": 10, "span_hours": 6.0,
+                                    "basis": "n ÷ 返った投稿の期間（最古〜最新）の日数",
+                                    "rough": True, "rough_below_n": 20, "reason": None}
+    assert calm["rate_by_span"]["value"] == 4.0 and calm["rate_by_span"]["span_hours"] == 60.0
+    assert calm["per_day"] == 4.0
+
+
+def test_roughはn20未満_期間が0や時刻なしはnullと理由():
+    assert where_cli.rate_by_span(20, [BASE, BASE + datetime.timedelta(hours=48)])["rough"] is False
+    same = where_cli.rate_by_span(3, [BASE, BASE])
+    assert same["value"] is None and same["reason"] == "span_zero"
+    none = where_cli.rate_by_span(0, [])
+    assert none["value"] is None and none["reason"] == "no_timestamp" and none["span_hours"] is None
+
+
+def test_要求数に届かず期間が短いとmore_may_exist(search):
+    search["短い"] = _rows(10, 6)
+    search["長い"] = _rows(10, 30)
+    search["少ない"] = _rows(4, 2)
+    result = where_cli.answer(account_name="one", words=["短い", "長い", "少ない"], limit=25,
+                              aggregate_mode=True, now=BASE + datetime.timedelta(days=3))
+    (item,) = _agg(result, "短い")["cannot_say"]
+    assert item["code"] == "more_may_exist"
+    assert item["message"] == "これで全部か、もっとあるかは区別できません"
+    assert "一次資料で未確認" in item["unverified"]
+    assert item["n_returned"] == 10 and item["requested_limit"] == 25 and item["span_hours"] == 6.0
+    assert _agg(result, "長い")["cannot_say"] == [], "期間が 24 時間以上"
+    assert _agg(result, "少ない")["cannot_say"] == [], "n が 5 未満"
+    full = where_cli.answer(account_name="one", words=["短い"], limit=10, aggregate_mode=True,
+                            now=BASE + datetime.timedelta(days=3))
+    assert _agg(full, "短い")["cannot_say"] == [], "要求数に届いている"
+
+
+def test_画面に期間あたりと分母とmore_may_exist(search, capsys):
+    search["短い"] = _rows(6, 5, base=jst.now_jst() - datetime.timedelta(hours=6))
+    assert cli.main(["where", "one", "短い", "--aggregate"]) == 0
+    out = capsys.readouterr().out
+    assert "期間あたり=28.8/日（n=6・期間 5.0 時間" in out and "粗い（n<20）" in out
+    assert "これで全部か、もっとあるかは区別できません（more_may_exist" in out
+    assert cli.main(["where", "one", "短い", "--aggregate", "--json"]) == 0
+    agg = json.loads(capsys.readouterr().out)["by_account"]["one"]["by_word"]["短い"]["aggregate"]
+    assert agg["rate_by_span"]["n"] == 6 and agg["rate_by_span"]["span_hours"] == 5.0

thth-3.9.0/tests/test_v390_where_suggest.py

@@ -0,0 +1,217 @@
+"""3.9.0 §B 検索の語の候補（`thth where … --also … --suggest`）。
+
+- `--also` と一緒なら語ごとの「取れた件数・also に合った件数・当たり率」を当たり率の順に。
+  合った件数 0 の語に「also に合った投稿が 0 件（直近 n 日）」。
+- `--suggest`: also に合った投稿の本文から語の候補を上位 10 まで（漢字・カタカナ・英字の
+  2〜12 字の連なり・検索語と also の語と数字だけの語を除く・2 投稿以上）。
+  **本文・username・post_id・author_key は出さない**。**保存しない**。
+- 自分の台帳からの候補（地図の点・原稿の topic・反応の多かった topic）を先頭に。
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import os
+
+import pytest
+
+from tests.conftest import write_queue_file
+from tests.test_after_cli import _insight_path, _write_ndjson
+from thth import accounts, adapters, cli, jst, map_store, runs, where_cli, where_suggest
+
+NOW = jst.parse("2026-09-24T12:00:00+09:00")
+STAMP = "2026-09-23T00:00:00Z"
+LONG = "スペシャルティコーヒーロースター"   # 16 字——12 字を超える連なりは語にしない
+
+COFFEE = [
+    {"message_id": "POSTID111", "author_key": "a1a1a1a1a1a1a1a1", "username": "roaster",
+     "timestamp": STAMP,
+     "text": f"深煎りの珈琲豆をハンドドリップで淹れた {LONG} https://x.example/beans"},
+    {"message_id": "POSTID222", "author_key": "b2b2b2b2b2b2b2b2", "username": "USERNAMEB",
+     "timestamp": STAMP, "text": f"珈琲豆は深煎りが好き。ハンドドリップ最高 2026 {LONG}"},
+    {"message_id": "POSTID333", "author_key": "c3c3c3c3c3c3c3c3", "username": "USERNAMEC",
+     "timestamp": STAMP, "text": "浅煎りの豆もハンドドリップで。roasterの店 2026 @USERNAMEB"},
+    {"message_id": "POSTID444", "author_key": "d4d4d4d4d4d4d4d4", "username": "USERNAMED",
+     "timestamp": STAMP, "text": "紅茶の話"},
+]
+TEA = [
+    {"message_id": "POSTID444", "author_key": "d4d4d4d4d4d4d4d4", "username": "USERNAMED",
+     "timestamp": STAMP, "text": "紅茶の話"},
+    {"message_id": "POSTID555", "author_key": "e5e5e5e5e5e5e5e5", "username": "USERNAMEE",
+     "timestamp": STAMP, "text": "紅茶とケーキ"},
+]
+SECRETS = ([row["text"] for row in COFFEE + TEA] + [row["message_id"] for row in COFFEE + TEA]
+           + [row["author_key"] for row in COFFEE + TEA]
+           + [row["username"] for row in COFFEE + TEA] + ["USERNAMEB".casefold(), "POSTID",
+                                                          "x.example"])
+
+
+@pytest.fixture
+def account(isolated_account_factory, monkeypatch, thth_root):
+    made = isolated_account_factory("one", media="threads", project="cafe")
+    monkeypatch.setattr(accounts, "load_token", lambda cfg: {"access_token": "FAKE"})
+    calls = []
+
+    class Fake:
+        def keyword_search(self, word, **kwargs):
+            calls.append(word)
+            return [dict(row) for row in (COFFEE if word == "珈琲" else TEA)]
+    monkeypatch.setattr(adapters, "make_adapter", lambda *a: Fake())
+    return {"calls": calls, "root": thth_root, "made": made}
+
+
+def _answer(**kw):
+    return where_cli.answer(account_name="one", words=["珈琲", "紅茶"], now=NOW,
+                            also=["豆", "ハンドドリップ"], **kw)
+
+
+def test_当たり率の順に並べ_0件の語に知らせる(account):
+    result = _answer(since="7d")
+    hits = result["by_account"]["one"]["also_hits"]
+    assert [row["word"] for row in hits] == ["珈琲", "紅茶"], "当たり率の高い順"
+    assert hits[0] == {"word": "珈琲", "n_fetched": 4, "n_matched": 3, "hit_rate": 0.75,
+                       "denominator": 4, "reason": None}
+    assert hits[1]["n_matched"] == 0 and hits[1]["hit_rate"] == 0.0
+    assert hits[1]["zero_note"] == "also に合った投稿が 0 件（直近 7 日）"
+    assert account["calls"] == ["珈琲", "紅茶"], "also の語で検索しない"
+    assert "suggest" not in result["by_account"]["one"], "--suggest が無ければ候補は出さない"
+
+
+def test_当たり率の期間と取れなかった語():
+    rows = where_suggest.also_hits([("a", 0, 0), ("b", 10, 1), ("c", 4, 2)],
+                                   period_days={"a": None, "b": 3})
+    assert [row["word"] for row in rows] == ["c", "b", "a"]
+    assert rows[2]["hit_rate"] is None and rows[2]["reason"] == "no_posts_fetched"
+    assert rows[2]["zero_note"] == "also に合った投稿が 0 件（期間は不明）"
+    stamps = [{"timestamp": "2026-09-21T13:00:00+09:00"}]
+    assert where_cli._period_days(stamps, None, NOW) == 3
+    assert where_cli._period_days([], None, NOW) is None
+
+
+def test_suggestは語と数だけ_検索語とalsoの語と数字と長い連なりと名前を除く(account):
+    result = _answer(suggest=True)
+    search = result["by_account"]["one"]["suggest"]["from_search"]
+    assert search["label"] == "その場の人が書いた語"
+    assert search["candidates"] == [{"word": "深煎", "n_posts": 2, "denominator": 3},
+                                    {"word": "珈琲豆", "n_posts": 2, "denominator": 3}]
+    words = {row["word"] for row in search["candidates"]}
+    assert "ハンドドリップ" not in words, "also の語は除く"
+    assert "珈琲" not in words and "2026" not in words and LONG not in words
+    assert "roaster" not in words, "取れた投稿の username と同じ語は候補にしない"
+    assert "浅煎" not in words and "最高" not in words, "1 投稿にしか出ない語は出さない"
+    text = json.dumps(result["by_account"]["one"]["suggest"], ensure_ascii=False)
+    for secret in SECRETS:
+        assert secret not in text, secret
+
+
+def test_aggregateとsuggestの画面にも本文や名前を出さない(account, capsys):
+    assert cli.main(["where", "one", "珈琲", "紅茶", "--also", "豆", "--also", "ハンドドリップ",
+                     "--aggregate", "--suggest", "--json"]) == 0
+    raw = capsys.readouterr().out
+    for secret in SECRETS:
+        assert secret not in raw, secret
+    result = json.loads(raw)
+    assert result["suggest"] is True and result["suggest_storage"] == "display_only"
+    assert cli.main(["where", "one", "珈琲", "紅茶", "--also", "豆", "--also", "ハンドドリップ",
+                     "--aggregate", "--suggest"]) == 0
+    out = capsys.readouterr().out
+    for secret in SECRETS:
+        assert secret not in out, secret
+    assert "語の候補（その場の人が書いた語）" in out and "深煎  2/3 投稿" in out
+    assert "also の当たり率（高い順）" in out and "also に合った投稿が 0 件" in out
+    assert "候補は表示だけで、道具は保存しません" in out
+
+
+def _snapshot(root):
+    out = {}
+    for base, _dirs, files in os.walk(root):
+        for name in files:
+            path = os.path.join(base, name)
+            with open(path, "rb") as f:
+                out[path] = f.read()
+    return out
+
+
+def test_suggestは保存しない_runsは語と件数の1行だけ(account, capsys):
+    before = _snapshot(account["root"])
+    assert cli.main(["where", "one", "珈琲", "紅茶", "--also", "豆", "--also", "ハンドドリップ",
+                     "--suggest", "--json"]) == 0
+    capsys.readouterr()
+    after = _snapshot(account["root"])
+    changed = {path for path in after if before.get(path) != after[path]
+               and not path.endswith(".lock")}
+    assert changed and all(os.path.basename(path).startswith("runs-") for path in changed), \
+        sorted(changed)
+    (path,) = changed
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    last = json.loads(text.splitlines()[-1])
+    assert last["action"] == "where_to_appear" and last["words"] == ["珈琲", "紅茶"]
+    assert last["n"] == 3, "also に合った件数（珈琲 3・紅茶 0）"
+    assert runs.read_runs(accounts.state_dir_for("one"))[-1]["n"] == 3
+    for word in ("深煎", "珈琲豆", "suggest", "hit_rate", "also"):
+        assert word not in text, word
+
+
+def test_自分の台帳からの候補を先頭に(account, capsys):
+    made = account["made"]
+    map_store.add_node("cafe", "焙煎", by="masaru")
+    map_store.add_node("cafe", "珈琲", by="masaru")                 # 検索語は候補にしない
+    for index, (topic, goal) in enumerate((("水出し", "click"), ("水出し", "reach"),
+                                           ("器", None))):
+        fm = {"account": "one", "status": "draft", "topic": topic, "publish_at": None}
+        if goal:
+            fm["goal"] = goal
+        write_queue_file(made["queue_dir"], f"d{index}.md", commit=False, fm_overrides=fm)
+    posted = NOW - datetime.timedelta(days=3)
+    for post_id, topic, likes in (("M1", "ラテアート", 9), ("M2", "ラテアート", 5),
+                                  ("M3", "器", 1), ("M4", "無反応", 0)):
+        _write_ndjson(_insight_path(made, post_id), [{
+            "account": "one", "post_id": post_id, "posted_at": jst.iso(posted),
+            "collected_at": jst.iso(posted + datetime.timedelta(hours=25)), "age_hours": 25,
+            "marks": [24], "reply_to": None, "topic": topic,
+            "metrics": {"views": 10, "likes": likes, "replies": 1 if likes else 0,
+                        "reposts": 0}}])
+    result = _answer(suggest=True)
+    mine = result["by_account"]["one"]["suggest"]["from_self"]
+    assert mine["label"] == "自分のデータ"
+    words = [row["word"] for row in mine["candidates"]]
+    assert words == ["焙煎", "水出し", "器", "ラテアート"], words
+    by = {row["word"]: row for row in mine["candidates"]}
+    assert by["焙煎"]["sources"] == ["map_node"]
+    assert by["水出し"]["draft"] == {"n": 2, "goals": {"click": 1, "reach": 1}}
+    assert by["器"]["sources"] == ["draft_topic", "reacted_topic"]
+    assert by["ラテアート"]["reacted"] == {"median_likes_plus_replies_24h": 8.0,
+                                          "n_observed": 2, "n_posts": 2}
+    assert "無反応" not in words and "珈琲" not in words
+    suggest = result["by_account"]["one"]["suggest"]
+    assert list(suggest) == ["from_self", "from_search", "storage", "storage_note"], "自分のデータが先"
+    assert cli.main(["where", "one", "珈琲", "--also", "豆", "--suggest"]) == 0
+    out = capsys.readouterr().out
+    assert out.index("語の候補（自分のデータ）") < out.index("語の候補（その場の人が書いた語）")
+
+
+def test_alsoが無ければその場の候補は出さない(account):
+    result = where_cli.answer(account_name="one", words=["珈琲"], now=NOW, suggest=True)
+    search = result["by_account"]["one"]["suggest"]["from_search"]
+    assert search["candidates"] == [] and search["reason"] == "no_also"
+    assert "also_hits" not in result["by_account"]["one"]
+    with pytest.raises(where_cli.WhereError):
+        where_cli.answer(account_name="one", words=["珈琲"], now=NOW, suggest="yes")
+
+
+def test_語の切り出しは静的な方法():
+    assert where_suggest.tokens("ＩＰｈｏｎｅ１５で撮ったラテアート。２０２６年 @someone https://a.example/x") \
+        == {"iphone15", "ラテアート"}
+    assert where_suggest.tokens("ーー　あ") == set()
+    assert where_suggest.tokens(None) == set()
+
+
+def test_MCPのwhere_to_appearには足さない():
+    path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "mcp", "server.py")
+    with open(path, encoding="utf-8") as f:
+        source = f.read()
+    assert "--suggest" not in source and "also_hits" not in source
+    start = source.index('"name": "where_to_appear"')
+    schema = source[start:source.index('"name": "who_is_this"')]
+    assert "suggest" not in schema and "also" not in schema

thth-3.9.0/thth/VERSION

@@ -0,0 +1 @@
+3.9.0