Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

feat(tooling): 公开文字发布前对照本机账本检查成串列出的馆藏

longmeidao102e2ae9e2b0
diff --git a/.claude/settings.json b/.claude/settings.json
index 63a15fd34..3884a1880 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -6,6 +6,9 @@
]
},
"hooks": {
+ "PreToolUse": [{"matcher": "Bash|PowerShell", "hooks": [
+ {"type": "command", "command": "uv", "args": ["run", "--no-project", "python", "-X", "utf8", "${CLAUDE_PROJECT_DIR}/scripts/check_public_text.py", "--hook-event"], "timeout": 30}
+ ]}],
"Stop": [{"hooks": [
{"type": "command", "command": "${CLAUDE_PROJECT_DIR}/.venv/Scripts/python.exe", "args": ["-X", "utf8", "${CLAUDE_PROJECT_DIR}/scripts/job_status.py", "--write", "--hook-event"], "timeout": 30},
{"type": "command", "command": "uv", "args": ["run", "--no-project", "python", "-X", "utf8", "${CLAUDE_PROJECT_DIR}/scripts/release_due.py", "--hook-event"], "timeout": 30}
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 6040645df..b0537fa43 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -826,6 +826,7 @@ Windows 托盘在取得单实例锁后启动独立监视器。监视器用 Win32
- **什么时候该发**:`scripts/agent_worktree.py integrate` 不改版本号,只报当前值,并输出 `release` 字段(`scripts/changelog.py` 的 `due()`)。`due` 为真时提出发布,理由在 `why`。节奏是每周一次、条目攒够提前、破坏性变化和安全修复不等周期(`DUE_DAYS = 7`、`DUE_ENTRIES = 10`)。只数使用者看得见的变更条目,不数提交。`DUE_ENTRIES` 是没有样本时的保守起点,`due()` 每次都报出实际条目数与分组,积累几次真实发布后再校准。
- **会话收尾提醒**:`scripts/release_due.py --hook-event` 挂在 Claude 的 `.claude/settings.json` 与 Codex 的 `.codex/hooks.json` 的 `Stop` 钩子上(两边约定一致:stdin 收 JSON、stdout 回 `systemMessage`、退出码 0)。只有在主检出、在 master、工作区干净、这个 master sha 还没问过,并且 `due` 为真时才输出一句,其余情况什么都不打印。已问记录在 `<Peach 数据目录>/state/release-due.json`,master 前进后才会再问。手工查看用不带参数的 `python scripts/release_due.py`,它只读,不改记录。
- 钩子用 `uv run --no-project` 找解释器,同一条命令在两个平台都能用。`--no-project` 不能省:`release_due.py` 只用标准库;如果让 uv 识别项目,它会在一个有 `pyproject.toml` 但还没建 venv 的检出里建一个空 venv,`scripts/test.ps1` 随后会优先选中它,测试连 `filelock` 都导入不了。`tests/test_release_due.py` 会把配置里的命令原样执行一遍,并检查工作目录没有多出 `.venv`。需要 `uv` 在 PATH 上,推荐 `winget install --id astral-sh.uv`,不要把远端脚本直接管道进 shell。
+- **公开文字检查**:`scripts/check_public_text.py --hook-event` 挂在 Claude 的 `PreToolUse`(Bash、PowerShell)上,同样用 `uv run --no-project`。命令里没有 `gh pr|issue create|edit|comment` 或改评论的 `gh api` 时直接放行;有就把命令连同 `--body-file`、`-F body=@` 引用的文件,对照本机账本(`mode=ro`)检查。成串列出番号、人物或标题片段时退出码 2,理由交给模型改写。`agent_worktree.py integrate` 对 PR 正文和分支提交说明做同一检查,覆盖不走钩子的 Codex。没有账本的机器放行;确需多列时正文写一行 `peach-public-text: <理由>`。手工检查用 `python scripts/check_public_text.py <文件>`。
- 「检查更新」只 fetch 和比较;「同步开发进度」只做 `merge --ff-only`,不 stash、不 rebase、不 `--force`:并行工作树和主检出共用同一个对象库与 reflog,任何改写历史的操作都会波及其他分支。工作区有改动或两边分叉时,原样报告交给人处理。本地不落后远端或连不上远端时,按构建身份判断打包托盘要不要重建(见「桌面入口与发布」);这条路径不拦有改动的工作区,因为构建用的就是检出里的代码。
- 快进涉及 `tray.py`/`menubar.py`/`versioning.py`/`certs.py`/`netwatch.py`/`config.py`/`pyproject.toml` 时,只重启子服务不够,托盘要用 `launchctl kickstart -k` 重启自己:先 `stop_owned()` 再 kickstart,前提是 launchd 报的 pid 等于自己的 pid。
diff --git a/scripts/check_public_text.py b/scripts/check_public_text.py
new file mode 100644
index 000000000..2b532f1ff
--- /dev/null
+++ b/scripts/check_public_text.py
@@ -0,0 +1,171 @@
+"""要公开的文字发出去之前,对照本机账本找成串列出的馆藏细节。
+
+PR、issue、评论与提交说明都公开在 GitHub 上,编辑后旧版仍留在编辑历史里。问题本身需要的
+一两个番号、前缀或标签照常写;把账本里的作品番号、人物名、标题片段成串列出来就拦下。
+判据只读本机账本(SQLite `mode=ro`),仓库里不带任何馆藏数据;没有账本的机器(CI、
+其他贡献者)一律放行。确有必要多列时,在正文里写一行 `peach-public-text: <理由>` 放行。
+
+用法:
+ python scripts/check_public_text.py FILE... # 检查文件,`-` 读 stdin
+ python scripts/check_public_text.py --hook-event # Claude PreToolUse 钩子:拦 gh 发布命令
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sqlite3
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+CODE = re.compile(r"(?<![A-Za-z0-9])([A-Za-z]{2,7})-?(\d{2,6})(?![0-9])")
+CJK = re.compile(r"[぀-ヿ㐀-鿿ヲ-゚]{2,}")
+#: 标题片段按这么长的连续假名、汉字比对;短了会撞上普通用语。
+GRAM = 7
+#: 一段文字里达到这些数目才算「成串」;问题本身需要的一两个例子不拦。
+LIMITS = {"番号": 3, "人物": 2, "标题片段": 2}
+WAIVER = re.compile(r"peach-public-text:\s*\S")
+#: 会把文字发到 GitHub 的 gh 子命令。
+PUBLISH = re.compile(r"\bgh\s+(?:(?:pr|issue)\s+(?:create|edit|comment)\b|api\b[^\n]*\bcomments\b)")
+BODY_FILE = re.compile(r"""(?:--body-file|-F)[=\s]+(?:body=@)?(?P<path>"[^"]+"|'[^']+'|[^\s"';|&]+)""")
+
+
+def code_key(prefix: str, digits: str) -> str:
+ return f"{prefix.upper()}-{int(digits):03d}"
+
+
+@dataclass
+class Library:
+ """账本里能认出馆藏的几样东西;只读载入,不写账本。"""
+ codes: set[str] = field(default_factory=set)
+ names: set[str] = field(default_factory=set)
+ grams: set[str] = field(default_factory=set)
+
+ @classmethod
+ def load(cls, ledger: Path) -> "Library":
+ library = cls()
+ connection = sqlite3.connect(f"file:{ledger.as_posix()}?mode=ro", uri=True)
+ try:
+ rows = connection.execute("SELECT code FROM asset WHERE code<>'' UNION SELECT code FROM feed_item WHERE code<>''")
+ library.codes = {code_key(*match.groups()) for (code,) in rows
+ for match in [CODE.fullmatch(code.strip())] if match}
+ names = connection.execute(
+ "SELECT canonical_name FROM entity WHERE kind IN ('performer','creator')"
+ " UNION SELECT label FROM follow_source WHERE label IS NOT NULL")
+ library.names = {name for (name,) in names if name and len(name) >= 3}
+ for row in connection.execute("SELECT catalog_title, original_title, name FROM asset"):
+ for text in row:
+ for run in CJK.findall(text or ""):
+ library.grams.update(run[i:i + GRAM] for i in range(len(run) - GRAM + 1))
+ finally:
+ connection.close()
+ return library
+
+ def findings(self, text: str) -> dict[str, list[str]]:
+ found: dict[str, set[str]] = {"番号": set(), "人物": set(), "标题片段": set()}
+ for match in CODE.finditer(text):
+ if code_key(*match.groups()) in self.codes:
+ found["番号"].add(match.group(0).upper())
+ for name in self.names:
+ if name.isascii():
+ if len(name) >= 5 and re.search(rf"(?<![\w-]){re.escape(name)}(?![\w-])", text):
+ found["人物"].add(name)
+ elif name in text:
+ found["人物"].add(name)
+ for run in CJK.findall(text):
+ if any(run[i:i + GRAM] in self.grams for i in range(len(run) - GRAM + 1)):
+ found["标题片段"].add(run)
+ return {kind: sorted(values) for kind, values in found.items() if values}
+
+
+def problems(text: str, library: Library | None) -> list[str]:
+ """达到「成串」的那几类,各一句;没有账本或写了放行理由时为空。"""
+ if library is None or WAIVER.search(text):
+ return []
+ found = library.findings(text)
+ return [f"{kind} {len(values)} 个:" + "、".join(values[:8]) + ("……" if len(values) > 8 else "")
+ for kind, values in found.items() if len(values) >= LIMITS[kind]]
+
+
+def ledger_for(project: Path) -> Path | None:
+ """这个检出所用 Peach 数据目录里的账本;找不到数据目录或账本时返回 None。"""
+ sys.path.insert(0, str(ROOT / "src"))
+ try:
+ from peach.settings_file import discover_data_root
+ root, found = discover_data_root(project)
+ except Exception: # noqa: BLE001 - 认不出数据目录就当这台机器没有账本
+ return None
+ ledger = root / "database" / "ledger.db"
+ return ledger if found and ledger.is_file() else None
+
+
+def load_library(project: Path) -> Library | None:
+ ledger = ledger_for(project)
+ return Library.load(ledger) if ledger else None
+
+
+def publish_text(command: str, cwd: Path) -> str | None:
+ """gh 发布命令要发出去的全部文字:命令本身(含 --title、--body 与 heredoc)加上引用的正文文件。"""
+ if not PUBLISH.search(command):
+ return None
+ parts = [command]
+ for match in BODY_FILE.finditer(command):
+ raw = match.group("path").strip("\"'")
+ if raw == "-":
+ continue
+ path = Path(raw) if Path(raw).is_absolute() else cwd / raw
+ try:
+ parts.append(path.read_text(encoding="utf-8"))
+ except (OSError, UnicodeError):
+ continue
+ return "\n".join(parts)
+
+
+def hook(payload: dict) -> int:
+ """PreToolUse:gh 要发的文字成串列了馆藏就退出码 2,stderr 交给模型改。"""
+ command = str((payload.get("tool_input") or {}).get("command") or "")
+ if "gh" not in command:
+ return 0
+ cwd = Path(payload.get("cwd") or ROOT)
+ if not cwd.is_dir():
+ cwd = ROOT
+ text = publish_text(command, cwd)
+ if text is None:
+ return 0
+ found = problems(text, load_library(cwd))
+ if not found:
+ return 0
+ print("这次要发到 GitHub 的文字成串列出了本机账本里的馆藏细节(" + ";".join(found) + ")。"
+ "按 peach-issue-delivery:规则效果写类型和定性结论,只留问题本身需要的一两个例子;"
+ "确有必要多列时,正文加一行 `peach-public-text: <理由>`。", file=sys.stderr)
+ return 2
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("files", nargs="*", help="要检查的文件,`-` 读 stdin")
+ parser.add_argument("--hook-event", action="store_true", help="从 stdin 收 PreToolUse 钩子 JSON")
+ args = parser.parse_args(argv)
+ if args.hook_event:
+ try:
+ payload = json.load(sys.stdin)
+ except (ValueError, OSError):
+ return 0
+ return hook(payload if isinstance(payload, dict) else {})
+ library = load_library(ROOT)
+ if library is None:
+ print("没有找到本机账本,跳过检查")
+ return 0
+ failed = False
+ for name in args.files or ["-"]:
+ text = sys.stdin.read() if name == "-" else Path(name).read_text(encoding="utf-8")
+ for problem in problems(text, library):
+ failed = True
+ print(f"{name}: {problem}")
+ return 1 if failed else 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/test_runner.py b/scripts/test_runner.py
index 1618c68a4..13893521f 100644
--- a/scripts/test_runner.py
+++ b/scripts/test_runner.py
@@ -112,7 +112,7 @@ SCOPES: dict[str, tuple[str, ...]] = {
"test_seed_pack.py", "test_seed_followup.py", "test_seed_corrections.py"),
"tooling": ("test_scripts.py", "test_trash_junk.py", "test_auth.py", "test_access.py", "test_cli.py", "test_server.py", "test_diagnostics.py", "test_error_reporting.py", "test_remote_reporting.py", "test_reporting_*.py", "test_library_sharing.py", "test_library_diagnostics.py", "test_script_policy.py",
"test_scan.py", "test_record_rehome.py", "test_wants.py", "test_push_discovery.py", "test_media_probe.py", "test_subtitles.py", "test_onboarding.py", "test_configuration_sources.py", "test_clouddrive_proxy.py", "test_folder_picker.py", "test_ledger_backups.py", "test_clear_camera_filename_codes.py",
- "test_agent_worktree.py", "test_star_history.py", "test_test_evidence.py", "test_test_history.py", "test_test_environment.py", "test_dependency_policy.py",
+ "test_agent_worktree.py", "test_check_public_text.py", "test_star_history.py", "test_test_evidence.py", "test_test_history.py", "test_test_environment.py", "test_dependency_policy.py",
"test_version_bump.py", "test_changelog.py", "test_release_due.py", "test_release_candidate.py", "test_media_build_cache.py", "test_runner_launcher.py",
"test_restart_windows_tray.py", "test_deploy_windows_tray.py", "test_runtime_prepare.py",
"test_buildinfo.py", "test_versioning.py", "test_macos_standalone.py",
diff --git a/tests/test_check_public_text.py b/tests/test_check_public_text.py
new file mode 100644
index 000000000..3e8c12659
--- /dev/null
+++ b/tests/test_check_public_text.py
@@ -0,0 +1,132 @@
+import io
+import json
+import sqlite3
+import subprocess
+import tempfile
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+from unittest import mock
+
+from scripts import check_public_text
+from scripts.check_public_text import Library, problems, publish_text
+
+
+def ledger(path: Path) -> Path:
+ """只有判据读到的那几列;内容全是虚构的。"""
+ connection = sqlite3.connect(path)
+ connection.executescript("""
+ CREATE TABLE asset(code TEXT, catalog_title TEXT, original_title TEXT, name TEXT);
+ CREATE TABLE feed_item(code TEXT);
+ CREATE TABLE entity(kind TEXT, canonical_name TEXT);
+ CREATE TABLE follow_source(label TEXT);
+ INSERT INTO asset VALUES ('ZZQ-101', '架空作品のための長い題名です', '', 'ZZQ-101.mp4'),
+ ('zzq102', '', '', ''), ('ZZQ-103', '', '', ''), ('', '', '', '');
+ INSERT INTO feed_item VALUES ('YYW-007');
+ INSERT INTO entity VALUES ('performer', '虚构女优甲'), ('performer', '虚构女优乙'), ('tag', '虚构标签名'),
+ ('creator', 'Fictional Maker');
+ INSERT INTO follow_source VALUES ('fictional_account'), (NULL);
+ """)
+ connection.commit()
+ connection.close()
+ return path
+
+
+class LibraryTests(unittest.TestCase):
+ def setUp(self):
+ directory = tempfile.TemporaryDirectory()
+ self.addCleanup(directory.cleanup)
+ self.library = Library.load(ledger(Path(directory.name) / "ledger.db"))
+
+ def test_the_ledger_is_read_into_codes_names_and_title_fragments(self):
+ self.assertEqual(self.library.codes, {"ZZQ-101", "ZZQ-102", "ZZQ-103", "YYW-007"})
+ self.assertEqual(self.library.names, {"虚构女优甲", "虚构女优乙", "Fictional Maker", "fictional_account"})
+ self.assertIn("架空作品のため", self.library.grams)
+
+ def test_a_list_of_owned_codes_names_or_titles_is_a_problem(self):
+ cases = {"ZZQ-101、zzq-102、ZZQ103 都要人判": "番号 3 个",
+ "虚构女优甲 对 虚构女优乙": "人物 2 个",
+ "系列名:架空作品のための長い題名 对 題名です長い架空作品のため": "标题片段 2 个"}
+ for text, expected in cases.items():
+ with self.subTest(text=text):
+ self.assertTrue(problems(text, self.library)[0].startswith(expected))
+
+ def test_the_example_a_fix_needs_and_unrelated_text_pass(self):
+ for text in ("只修 ZZQ-101 的前缀,YYW-007 是反例。", "虚构女优甲 的别名修好了。",
+ "ABC-123、DEF-456、GHI-789 都不在账本里。", "Fictional 与 Maker 分开写不算。"):
+ with self.subTest(text=text):
+ self.assertEqual(problems(text, self.library), [])
+
+ def test_a_stated_reason_or_a_machine_without_a_ledger_passes(self):
+ listed = "ZZQ-101、ZZQ-102、ZZQ-103"
+ self.assertEqual(problems(listed + "\n<!-- peach-public-text: 三个番号就是这次修的前缀 -->", self.library), [])
+ self.assertNotEqual(problems(listed + "\npeach-public-text:", self.library), [])
+ self.assertEqual(problems(listed, None), [])
+
+
+class PublishCommandTests(unittest.TestCase):
+ def setUp(self):
+ directory = tempfile.TemporaryDirectory()
+ self.addCleanup(directory.cleanup)
+ self.cwd = Path(directory.name)
+ (self.cwd / "body.md").write_text("正文文件里的内容", encoding="utf-8")
+
+ def test_gh_commands_that_publish_carry_their_text_and_body_files(self):
+ for command in ("gh pr create --title t --body-file body.md", "gh pr edit 3 -F body.md",
+ "cd x && gh issue comment 5 --body-file=body.md",
+ f"gh api -X PATCH repos/o/r/issues/comments/9 -F body=@{self.cwd / 'body.md'}"):
+ with self.subTest(command=command):
+ text = publish_text(command, self.cwd)
+ self.assertIn(command, text)
+ self.assertIn("正文文件里的内容", text)
+ heredoc = "gh pr create --body \"$(cat <<'EOF'\n正文直接写在命令里\nEOF\n)\""
+ self.assertIn("正文直接写在命令里", publish_text(heredoc, self.cwd))
+
+ def test_commands_that_only_read_are_not_publishing(self):
+ for command in ("gh pr view 3 --json body", "gh pr list", "gh api repos/o/r/pulls/3", "echo hello"):
+ with self.subTest(command=command):
+ self.assertIsNone(publish_text(command, self.cwd))
+
+ def test_the_hook_blocks_with_a_reason_and_lets_everything_else_through(self):
+ library = Library(codes={"ZZQ-101", "ZZQ-102", "ZZQ-103"})
+ listed = {"cwd": str(self.cwd), "tool_input": {"command": "gh pr create --body 'ZZQ-101 ZZQ-102 ZZQ-103'"}}
+ with mock.patch.object(check_public_text, "load_library", return_value=library) as load:
+ error = io.StringIO()
+ with redirect_stderr(error):
+ self.assertEqual(check_public_text.hook(listed), 2)
+ self.assertIn("番号 3 个", error.getvalue())
+ self.assertIn("peach-public-text", error.getvalue())
+ self.assertEqual(check_public_text.hook({"tool_input": {"command": "gh pr create --body 'ZZQ-101'"}}), 0)
+ load.reset_mock()
+ self.assertEqual(check_public_text.hook({"tool_input": {"command": "git status"}}), 0)
+ load.assert_not_called()
+
+ def test_the_hook_reads_a_missing_cwd_as_this_checkout(self):
+ payload = {"cwd": "/no/such/place", "tool_input": {"command": "gh pr create --body x"}}
+ with mock.patch.object(check_public_text, "load_library", return_value=None) as load:
+ self.assertEqual(check_public_text.hook(payload), 0)
+ load.assert_called_once_with(check_public_text.ROOT)
+
+ def test_the_configured_claude_hook_runs_as_written(self):
+ """配置里的命令原样跑一遍:PATH 上没有 uv 就是测试红,不是钩子静默;`--no-project` 不建 venv。"""
+ settings = json.loads((check_public_text.ROOT / ".claude" / "settings.json").read_text(encoding="utf-8"))
+ [matcher] = settings["hooks"]["PreToolUse"]
+ self.assertEqual(matcher["matcher"], "Bash|PowerShell")
+ [hook] = matcher["hooks"]
+ argv = [hook["command"], *(arg.replace("${CLAUDE_PROJECT_DIR}", str(check_public_text.ROOT))
+ for arg in hook["args"])]
+ venv = (self.cwd / ".venv").exists()
+ result = subprocess.run(argv, input=json.dumps({"cwd": str(self.cwd), "tool_input": {"command": "git status"}}),
+ capture_output=True, text=True, encoding="utf-8", cwd=self.cwd, timeout=120)
+ self.assertEqual((result.returncode, result.stderr), (0, ""))
+ self.assertEqual((self.cwd / ".venv").exists(), venv)
+
+ def test_unreadable_hook_input_never_blocks(self):
+ with mock.patch("sys.stdin", io.StringIO("not json")):
+ self.assertEqual(check_public_text.main(["--hook-event"]), 0)
+ with mock.patch("sys.stdin", io.StringIO(json.dumps([1]))):
+ self.assertEqual(check_public_text.main(["--hook-event"]), 0)
+
+
+if __name__ == "__main__":
+ unittest.main()