Redistricting News Harvester

• 研究场景对齐：输入为可池化事件表（学区 NCES ID、校名、州、事件年、事件类型等），输出为「事件 × 文章」展开后的宽表，直接进统计软件，而不是零散链接列表。
• 成本与冗余控制：以 (district, event_year) 为缓存键检索一次，多行 E/M/H 等级共享同一批链接，显著减少重复搜索调用。
• 可续跑批处理：结果写入追加式 JSONL、已完成键列表与进度日志；中断后可合并 partial 再继续，适合长会话与多天分批跑完。
• 规则前置：查询矩阵、过滤管线、停止条件与「硬规则」写在 prompts/subagent.md，减少子代理中途偷懒（例如未跑满基础查询就停）。
• 英文下游字段：每条链接附 source、标题、日期、以及一句英文 coverage_summary，便于跨国团队与审稿材料统一语言。
• 落地推广：合作方使用后，同一套工作流已推广至 USC 所在研究组，组内用于同类检索—汇总任务，反馈积极。

数据规模与输入

典型输入为含约 652 条事件行、31 列的 CSV；其中 district（NCES LEA ID）与 event_year 组成缓存键，约 485 个唯一键（同一学区同年多行代表 E/M/H 等级等）。检索侧消费字段包括清理后的 lea_name、state_location、event_type（如 fixed / opening 等）；其余研究字段在输出中原样保留。

输出形态

终表为「每条接受的新闻一行」：原始 31 列保留顺序，再追加事件级字段（如 link_count、stop_reason、不完整与日期不确定计数等）与文章级字段（article_index、url、source、title、published_date、source_query、coverage_summary）。追加文本字段均为英文。若无任何命中，事件仍保留一行，文章列为空。设计规格中以合计约 42 列描述该宽表（以协作方仓库内 spec.md 为准）。

查询矩阵（概要）

对学区短名 D、州 S、事件年 Y、类型 T，子代理按固定顺序执行多组 Web 检索查询（例如含 redistricting、attendance zone、rezoning、school boundary change 等）；当 T 表示新校开办类时，追加与 new school 相关的组合查询。在基础查询跑完后，仅在「已接受链接数处于中段且长尾仍有信号」等条件下，才允许执行少量扩展查询（年份窗口、plan、同义词等）——具体条件与顺序以 spec 为准。

过滤管线（概要）

对候选 URL：规范化与去参、跨查询去重；日期截断为不晚于 2022-12-31（与研究工作者的样本窗口一致）；相关性要求学区名与划界语义关键词出现在标题或摘要中。日期缺失时可计数标记，而非静默丢弃整条事件。批量模式下以检索摘要为主做相关性判断，避免对每链全文抓取。

停止理由与质量门槛

子代理输出需带合法 stop_reason；设计上以「尽量接近 10 条可接受链接」为目标，4 条为下限参考而非提前收工借口；须跑完规定的基础查询矩阵，禁止因「已经够四条」而跳过查询类型。这些以 HARD RULES 形式写在子代理提示词中。

中间态与脚本

运行过程写入 state/results.jsonl（每键一行 JSON）、state/completed_keys.txt、state/progress.log；批内可先落 state/partial/ 再合并。最终由标准库 Python 脚本将 JSONL 与原始 CSV 对齐生成终表。

编排器（主 Claude Code 会话，入口为 GUIDE）：先可进入单事件测试模式——同步派一个子代理、打开完整轨迹，便于人肉验收检索是否「偷懒」；通过后进入批量模式——按未完成缓存键分批并行派子代理、合并 JSON、刷进度，全部结束后跑 CSV 转换。

子代理通过 Agent 工具按模板注入变量；批量时多路并行，并行度受会话时长与计划限制需分段执行。不设独立「校验 Agent」：合规性主要靠子代理提示词内的硬规则与 JSON schema 约束。

自包含目录：GUIDE.md（续跑说明）、spec.md（规格）、prompts/orchestrator.md、prompts/subagent.md、调度模板、scripts/jsonl_to_csv.py 及合并辅助脚本、示例输入与 state/、outputs/ 约定路径。合作方在本地安装 Claude Code 与 Python 3.9+ 即可按文档操作。

本人侧重：提示词体系与硬规则、批调度模板、缓存键与去重策略、JSON 与 CSV 契约对齐、以及测试模式与批量模式的衔接；对方提供研究问题、事件表与领域判定边界。

合作方在课题中验证流程后，将同一套工作流推广至南加州大学（USC）所在研究组；组内成员沿用该流水线做同类「检索—结构化—汇总 CSV」任务，整体反响好。本页不包含对方内部数据路径、仓库地址或未公开样本细节。

English（可拆成多条 bullet）

Co-designed a Claude Code–driven research pipeline for an economics-of-education PhD project: an orchestrator dispatches parallel WebSearch subagents per (district, year) cache key with a fixed query matrix and filter pipeline; append-only JSONL state for resume; Python stdlib merges to a one-row-per-article CSV with English metadata and coverage summaries. Rolled out to the collaborator’s USC research group for similar harvest workflows.

中文要点

教育经济学合作、Claude Code 编排器与子代理、缓存键去重、JSONL 可续跑、查询矩阵与硬规则、英文摘要字段、USC 组内推广。

完整代码与数据在协作方侧维护；本页不附公开仓库链接。规格若有迭代，以对方仓库内 spec.md 为权威版本。