Repository navigation
[任务] 读列表：通用抓取、配置和往回翻页 #6
Description
关联与状态
路线图 #2，一期。状态：已完成，@Xi1495：PR #83 已合并。有问题直接在这里留言。
这个 Issue 原来是「抓取节点原型：从列表页抓到快照」。抓取节点的骨架已经搭好，原来的范围拆成了几个任务：读列表（这里）、读正文和附件 #40、浏览器抓取 #41、图片的文字识别 #47。
目标
鼠钟要从各学院官网的「通知公告」页里找出保研通知。这个任务写一轮里的第一步 Steps.list_items：从来源的列表页取出每条通知的标题、链接和日期。第一次抓时往回翻页，补上前两年的通知；结构特殊的网站按配置取（总体设计 §7.1、§7.2）。
已经有的
- 项目骨架：
crawler/是 Python 3.14 + uv 的项目，装依赖uv sync，跑全部检查./check.sh（格式、lint、Pyright 严格模式、测试）。命令见 AGENTS.md。 - 一轮的流程：
crawl/rounds.py的crawl_source已经把一个来源的一轮串好：读列表 → 初筛 → 读正文和附件 → 抽取 → 交结果。四步作为Steps传进来，签名和交接的数据写在那里，测试的写法见rounds_test.py。抓不成时抛FetchError或StepError，流程会把原因记进抓取记录（开发约定 §2）。 - 请求层：所有对来源网站的请求都经过
crawl/fetch.py的Fetcher，它管 UA、同一网站一次一个请求和间隔，不要自己用 httpx 发请求。 - 和网站交接的类型：
crawl/contract.py由网站的接口定义生成，不手改（接口 §6）。 - 选定的库：用 lxml 按 CSS 或 XPath 取（总体设计 §5.1）。
范围
要做（可以一项一项做，每项一个 PR）：
- 通用抓取：
- 不用配置，从规整的列表页取出每条通知的标题、绝对网址和日期（
YYYY-MM-DD），返回ListedItem的列表； - 先拿厦大信息学院的招生信息练手，再多试几个 [任务] 第一批来源清单 #5 里的来源；
- 按建站系统总结常见的写法，一种写法能管一批网站。
- 不用配置，从规整的列表页取出每条通知的标题、绝对网址和日期（
- 往回翻页：
WorkSource.backfill为真时，顺着「下一页」往回翻，翻到两年前的通知或者没有下一页为止；平时只读第一页。 - 配置：
- 通用抓取取不对的来源，用几行配置指明列表、标题、链接、日期和翻页在哪；
- 配置的格式由这个任务定：写进开发约定 §2，用 Pydantic 校验，就是
WorkSource.config的内容； - 管理员在网站上填（[任务] 管理院校清单和来源 #37），试抓时 LLM 也按它生成（[任务] 试抓：抓取节点这边 #46）；
- 网站只把它当 JSON 存，不认得格式。配置不合法时（填错了，或者格式后来改了）抛
StepError("error", "配置不对：…")，记进抓取记录，管理员在抓取看板上看得到；不要让校验的异常直接抛出去，那样这一轮不交记录，租约过期后反复重来。
- 只能用 HTTP 的：浙大计算机学院的 HTTPS 连不上，在配置里能指定用 HTTP 抓。
- 失败：列表页返回 4xx、5xx 时抛
StepError("http_status", "HTTP 403")这样的错误，读不到条目就返回空列表，一轮的流程会记成no_items。
不做：浏览器抓取（#41）、正文和附件（#40）、初筛和抽取。
需要知道的
- 测试不连外网，用保存下来的列表页。仓库里只放页面结构，通知的标题可以换成自己编的。
- 手动试抓真实网站只抓需要的几页（AGENTS.md · 底线）。
建议的第一步
- 在本 Issue 留言认领。
- 把厦大的列表页存一份到测试数据目录，在
crawler/src/crawler/parse/下写通用抓取和它的测试，跑通./check.sh，开一个 Draft PR。
验收标准
- 至少 5 个不同建站系统的来源能用通用抓取或配置取对标题、链接和日期
- 第一次抓能往回翻到两年前，平时只读第一页
- 配置的格式写进开发约定，有校验，不合法的记进抓取记录；只能用 HTTP 的来源能抓
- 测试只用保存下来的页面，
./check.sh通过
Activity
JunieXD commentedon Oct 27, 2026
（已更新）这里的建议已经写进 Issue 正文：原型直接写在
crawler/里，按正式代码合入；电科计算机学院改用浏览器抓取，设置见开发约定 §2。正文和附件用哪些库，在这个任务里比较后写回总体设计 §5.1。统一换行和编辑器设置，任务按部署单元加标签 (#9)
定下技术栈：网站和鼠洞同一套，抓取节点用 Python (#11)
搭好网站和抓取节点的骨架，接上 CI (#12)
[-][任务] 抓取节点原型[/-][+][任务] 抓取节点原型：从列表页抓到快照[/+][-][任务] 抓取节点原型：从列表页抓到快照[/-][+][任务] 读列表：通用抓取、配置和往回翻页[/+]附件和文字识别的库改由对应的任务比较后定 (#61)
Xi1495 commentedon Nov 6, 2026
我来认领 #6，接着已有来源清单做
Steps.list_items。先从厦大信息学院招生列表开始，按不同建站系统的结构准备固定测试页面，再完成首次两年回补和配置抓取。配置拟使用 XPath，分别定位条目、标题、链接、日期和下一页；另提供显式 HTTP 选项，写进开发约定 §2，用 Pydantic 校验，非法配置转换为
StepError。本任务只做列表，不混入正文、浏览器、初筛或抽取。依赖使用 Issue 已选定的
lxml，另加开发依赖types-lxml供严格类型检查，均通过uv add管理。所有源站请求继续通过共用的原版Fetcher；测试只用保留页面结构、替换通知内容的本地样例。会先开 Draft PR，按 Issue 验收项逐条列出证据，配置格式如需调整可在 PR 中继续对齐。JunieXD commentedon Nov 6, 2026
感谢认领，已经指派给你！方案和 Issue 对得上：lxml 按 XPath 取，配置用 Pydantic 校验、不合法时转成
StepError，只能用 HTTP 的来源（范围第 4 项）在配置里指定。提醒一点：先做范围第 1 项不用配置的通用抓取，按建站系统总结写法，一种写法管一批网站；配置只留给通用抓取取不对的来源。验收要求的 5 个建站系统，能用通用抓取取对的就不写配置。
#80、#81、#82 我们正在审，意见会分别发在各自的 PR 里。
Xi1495 commentedon Nov 7, 2026
#83 已按两轮审查意见修改，最新提交为 a7aa799，现为待审。
crawl，parse只解析一页，时间用可注入的clock。link、next选中元素时取href，配置文档已简化，XPath 返回类型用isinstance判断。验证：格式、lint、严格类型、生成类型检查及 170 项离线测试通过，远端 crawler、web CI 通过。复用此前按
Fetcher规矩取得的 30 个非浏览器来源首页，离线复算仍为 390 条、390 条都有日期，修正 40 个标题，未新增源站请求；逐来源条数仍列在 PR 描述中。需浏览器的 15 个来源继续归 #41，#77 的PageSession改动按审查说明由该 PR 衔接。请复审 #83；本 Issue 等维护者验收后关闭。
JunieXD commentedon Nov 7, 2026
PR #83 已合并，验收标准逐条做到了，这个 Issue 随之关闭。感谢 Xi1495！
force_http。./check.sh通过。要执行脚本才能打开的 15 个来源（北邮 8 个、电科 7 个）归浏览器抓取 #41。下一步是读正文和附件 #40，待认领。