hn-extract

核心用法

hn-extract 是一款专为 HackerNews 设计的轻量级内容提取工具。用户只需提供帖子 ID、完整 URL 或本地 JSON 文件路径，即可一键获取完整的帖子内容。工具内部通过 HackerNews Algolia API 拉取元数据与评论线程，同时利用 trafilatura 库智能抓取并清洗原始文章 HTML，最终输出一份结构清晰的 Markdown 文档，包含文章正文、嵌套评论及关键元信息。

使用方式极为简洁：通过 uv run --script 直接执行，无需预先安装依赖。支持 -o 参数指定输出路径，省略时则输出至标准输出。工具内置 HTTP 重试机制（最多 3 次），并能自动创建输出目录，提升使用便利性。

显著优点

1. 零配置即用：依托 uv 的脚本运行能力，依赖自动隔离安装，无需手动管理虚拟环境。
2. 内容整合度高：将分散的文章原文与 HN 评论线程合并为单一文档，便于离线阅读或向 LLM 提供完整上下文。
3. 输出格式友好：Markdown 格式通用性强，评论按层级缩进，保留讨论结构。
4. 输入灵活：同时支持 ID、URL 和本地缓存文件，适应不同使用场景。

潜在缺点与局限性

• 抓取成功率受限：部分网站启用反爬机制或需要身份验证，可能导致文章提取失败。
• 依赖外部服务：核心功能依赖 HN Algolia API 与目标文章的可访问性，任一环节故障均会影响结果。
• 无增量更新机制：每次执行均为全量抓取，对于长帖或高频使用场景效率一般。
• 格式简化损失：trafilatura 提取过程会丢弃部分富媒体内容与复杂排版。

适合的目标群体

• 需要快速归档 HN 讨论的技术研究者与内容策展人
• 希望将 HN 内容作为知识库素材喂给 LLM 的 AI 应用开发者
• 追求极简工具链、偏好命令行工作流的效率型用户

使用风险

• 网络稳定性：API 与目标站点访问受网络环境影响，重试机制虽存在但仍可能超时。
• 依赖项演进：trafilatura 等库的更新可能引入行为变更，需关注兼容性。
• 合规边界：抓取行为需遵守目标网站的 robots.txt 与服务条款，商业用途需谨慎评估。

核心用法

hn-extract 是一个轻量级 Python 脚本，用于将 HackerNews 帖子（包含外链文章与完整评论线程）提取为单一 Markdown 文件。使用时仅需提供 HN ID 或完整 URL，脚本自动完成：

1. 文章内容获取：通过 trafilatura 清理外链文章的 HTML，提取正文并转为 Markdown
2. 评论线程重建：调用 HackerNews Algolia API 获取嵌套评论，按层级缩进格式化
3. 元数据整合：合并标题、作者、发布时间、投票数等关键信息

执行命令示例：

uv run --script hn-extract.py 46861313 -o /tmp/post.md

依赖 uv 实现零配置运行，自动创建隔离虚拟环境并安装依赖，无需手动 pip 安装。

显著优点

• 极简部署：仅需系统安装 uv，无需 Python 环境管理烦恼
• 阅读友好：输出文件结构清晰，文章与评论分层展示，支持离线阅读
• LLM 就绪：标准 Markdown 格式，token 占用低，适合直接作为大语言模型输入
• 网络鲁棒性：内置 urllib3 Retry 机制，自动重试失败请求
• 输出灵活：支持指定文件路径或标准输出，目录自动创建

潜在缺点与局限性

• 反爬限制：部分网站需认证或主动阻止爬虫，文章提取可能失败
• 无增量更新：每次运行重新拉取全部数据，不支持增量同步
• 单文件输出：大型帖子（数千评论）生成单文件可能体积较大
• 格式依赖源站：文章提取质量取决于 trafilatura 对目标网站的解析能力

适合人群

• 需要离线阅读 HN 长帖的深度用户
• 研究人员收集 HN 讨论数据用于分析
• 希望将 HN 内容快速喂给 LLM 的 AI 辅助阅读场景

常规风险

• 依赖外部 API（Algolia）和源站可用性
• 提取的文章内容可能因网站结构变化而不完整
• 输出路径需确保有写入权限，避免路径遍历输入