source-tracker

Source Tracker

概述

Source Tracker 是一款用于研究工作流的小型持久化引文管理器。 研究资料常常散落在浏览器标签页、笔记、临时文件和不同会话中。URL 引用一次后便消失，重复项不断累积为 http/https 或 www 变体，文末导出参考书目也成了手动清理工作。

此工具通过维护一个包含所有已引用 URL 的便携式 SQLite 数据库来解决这些问题： 引用来源时立即添加，按主题添加标签，合并重复的 URL 变体，重新检查过时链接，并以 Markdown、BibTeX、CSV 或 JSON 格式导出参考书目。

可通过 --db-path 或 SOURCE_TRACKER_DB 环境变量配置数据库路径。如果两者都未设置，命令会使用相对于当前工作目录的 ./sources.db。

快速开始

在技能目录中：

python scripts/source_db.py add --url URL --topic TOPIC

一个实用示例：

python scripts/source_db.py add \
  --url "https://example.org/report" \
  --topic "battery supply chain" \
  --title "Example Battery Report" \
  --notes "Baseline market-size estimate" \
  --type report

如果研究跨越多个文件夹或会话，请使用持久化的项目数据库：

export SOURCE_TRACKER_DB="$HOME/research/sources.db"
python scripts/source_db.py add --url "https://example.org" --topic "market scan"

或者显式传入路径：

python scripts/source_db.py --db-path "$HOME/research/sources.db" add --url "https://example.org" --topic "market scan"

工作流

1. 添加来源

每个 URL 成为引用来源时，都应立即添加。务必指定主题。 如果资料不是普通网页，请指定来源类型。

python scripts/source_db.py add \
  --url "https://example.com/article#section" \
  --topic "ai regulation" \
  --title "Example Article" \
  --notes "Defines the enforcement timeline" \
  --type news \
  --session-id "research-2026-07-06"

如果省略 --title，脚本会尝试发送 GET 请求并解析 <title>。如果获取失败，仍会添加来源，但标题留空。

完成标准：命令会输出一个 JSON 对象；对于新记录，inserted: true；对于数据库中已存在的完全匹配的规范 URL，inserted: false。

2. 搜索来源

按主题和可选筛选条件搜索。结果为 JSON 格式，因此可以通过管道传递给 其他工具。

python scripts/source_db.py search --topic "ai regulation"

按日期范围筛选：

python scripts/source_db.py search \
  --topic "ai regulation" \
  --from 2026-01-01 \
  --to 2026-12-31

按来源类型和验证状态筛选：

python scripts/source_db.py search \
  --topic "ai regulation" \
  --type report \
  --verified true

完成标准：JSON 数组仅包含符合主题和筛选条件的记录。

3. 合并重复的 URL 变体

完成一轮集中研究后或导出前，运行去重。此操作会合并常见的 URL 变体， 例如 http 与 https、www. 与裸域名、仅片段不同以及尾部斜杠不同的 URL。

python scripts/source_db.py dedup

完成标准：命令会输出包含 merged_groups、 removed_rows 和 removed_ids 的 JSON 摘要。保留的记录会沿用最早的 accessed_at，并合并所有被合并记录中的非空备注。

4. 导出参考书目

导出某个主题的参考书目。如果省略 --output，内容会输出到标准输出。 如果设置了 --output，请向用户提供文件路径。

Markdown：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format markdown \
  --output ai-regulation-sources.md

BibTeX：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format bibtex \
  --output ai-regulation-sources.bib

CSV：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format csv \
  --output ai-regulation-sources.csv

JSON：

python scripts/source_db.py export \
  --topic "ai regulation" \
  --format json \
  --output ai-regulation-sources.json

完成标准：输出包含该主题的所有来源，并按主题／标题／日期排序，格式符合指定要求。

5. 健康检查

在提交最终报告前手动运行链接健康检查，或通过 cron 调度程序运行。 检查器会发送 HEAD 请求，将 HTTP 200-399 标记为正常，更新 last_checked，并通过设置 verified = 0 标记失效链接。

python scripts/url_health.py --stale-days 30 --timeout 10 --batch-size 50

显式指定数据库路径：

python scripts/url_health.py \
  --db-path "$HOME/research/sources.db" \
  --stale-days 7 \
  --timeout 5 \
  --batch-size 100

完成标准：命令会输出 Checked N URLs: M alive, K dead，并以代码 0 退出。失效链接会记录在数据库中，不会被视为运行时错误。

6. 统计信息与主题列表

按主题、类型和验证状态显示来源数量：

python scripts/source_db.py stats

列出所有主题标签：

python scripts/source_db.py list-topics

完成标准：统计信息以 JSON 格式输出，主题列表则输出由不同主题字符串组成的 JSON 数组。

URL 规范化规则

Source Tracker 使用两级 URL 处理方式：

1. 规范存储 URL

   • 将协议和主机名转换为小写。
   • 删除 URL 片段，例如 #section。
   • 删除非根路径末尾的斜杠。
   • 保留查询字符串。
   • 保留 www.，因为它可能是用户希望看到的 URL。

2. 去重比较键

   • 应用所有规范存储规则。
   • 将 http 和 https 变体视为同一来源。
   • 仅用于比较时，删除主机名前导的 www. 前缀。

示例：

输入	规范 URL	去重比较
HTTPS://WWW.Example.com/Page/#intro	https://www.example.com/Page	//example.com/Page
http://example.com/	http://example.com/	//example.com/
https://www.example.com	https://www.example.com/	//example.com/

来源类型

使用以下值之一作为 --type：

类型	适用场景
web	标准网页、文档页面、博客文章、落地页。
pdf	直接 PDF URL，或主要来源为 PDF 的页面。
api	API 端点、JSON/XML 数据端点、机器可读的服务输出。
dataset	数据下载、CSV/Parquet 仓库、公共数据目录。
book	在线图书、书籍章节、扫描件，或书籍的书目页面。
news	新闻文章、通讯社报道、采访、实时博客。
report	白皮书、政府报告、分析师报告、机构报告。

研究工作流集成

深度研究

在迭代搜索／提取／综合工作中，来源通过质量筛选后，应立即添加，然后再用于综合：

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "PROJECT_TOPIC" \
  --title "SOURCE_TITLE" \
  --notes "Supports sub-question: ..." \
  --session-id "SESSION_ID"

最终报告完成前：

python scripts/source_db.py dedup
python scripts/source_db.py export --topic "PROJECT_TOPIC" --format markdown --output bibliography.md

笔记本式来源库

构建来源库时，每个来源加入来源库后都应立即添加。将来源库或语料库标识符存储在 --session-id 中，并使用备注标记覆盖类别，例如 primary evidence、background 或 contradiction。

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "VAULT_TOPIC" \
  --notes "Vault source 007; primary evidence" \
  --session-id "vault-007"

实体研究

对于实体档案，使用实体名称加研究视角为来源添加标签。使用来源类型区分官方登记记录、不利媒体报道、报告和数据集。

python scripts/source_db.py add \
  --url "SOURCE_URL" \
  --topic "Acme Ltd adverse media" \
  --type news \
  --notes "Allegation source; not independently verified"

Cron 用法

使用 cron 调度程序运行每周健康检查。crontab 条目示例：

0 9 * * 1 cd /path/to/source-tracker && SOURCE_TRACKER_DB=/path/to/sources.db python scripts/url_health.py --stale-days 30 --batch-size 100 >> /path/to/source-health.log 2>&1

对于非常大的数据库，请使用较小的批次，以避免调度任务运行时间过长：

0 9 * * 1 cd /path/to/source-tracker && python scripts/url_health.py --db-path /path/to/sources.db --stale-days 30 --batch-size 50

输出格式

• Markdown 参考书目 — 按主题分组，每个来源的呈现格式为 - [Title](URL) — notes (accessed_at)。
• BibTeX — @misc{key, title={...}, url={...}, note={...}, urldate={...}}。
• CSV — id,url,title,topic,source_type,accessed_at,notes,verified,last_checked。
• JSON — 完整来源对象数组，包含 session_id 和规范化 URL 字段。

具体示例请参阅 references/export-formats.md。

常见问题

1. 虚构的 URL — 除非 URL 来自网络搜索工具、网页提取工具、用户提供的来源或其他可验证的来源渠道，否则切勿添加。如果 URL 是猜测的，请先验证再添加。
2. 缺少主题标签 — --topic 是必需项，自有其原因。请使用一致的主题名称，以免搜索、统计和导出结果被近似重复项拆散。
3. 健康检查过时 — verified = 1 表示来源在上次检查时可访问，不代表它永远可访问。对于长期运行的项目，请在最终交付前运行 url_health.py。
4. 重复变体 — https://www.example.com/、http://example.com 和 https://example.com#intro 可能指向同一来源。导出前请运行 dedup。
5. 标题为空 — 标题提取尽力而为。对于重要引用，请显式传入 --title，而不要依赖远程页面抓取。
6. 相对数据库路径造成的困惑 — 默认的 ./sources.db 取决于当前工作目录。对于长期运行的项目，请使用 SOURCE_TRACKER_DB 或 --db-path。

验证清单

• 添加前，已通过真实来源渠道核实每个引用的 URL。
• 每个新增行都有有意义的 --topic 和合适的 --type。
• 导出参考文献前，已运行 python scripts/source_db.py dedup。
• 已于近期运行 python scripts/url_health.py，用于最终交付。
• 导出的参考文献采用了指定格式和输出路径。
• 在最终引用前，已检查失效或未经核实的链接。
• 对于多会话工作，已明确指定数据库路径（--db-path 或 SOURCE_TRACKER_DB）。