pp-hackernews

Hacker News — Printing Press CLI

前提条件：安装 CLI

此技能由 hackernews-pp-cli 二进制文件驱动。**调用此技能中的任何命令前，都必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install hackernews --cli-only
   

2. 验证：hackernews-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/hackernews/cmd/hackernews-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。在验证成功前，不要执行此技能的命令。

何时使用此 CLI

当你需要以编程方式监控或分析 HN 动态时，可使用 hackernews-pp-cli：例如由 Agent 生成每日差异、追踪主题热度、汇总招聘帖、提交前检查重复投稿，以及生成适合上下文窗口的结构化讨论串摘要。本地存储让后续查询成本低廉，也便于离线使用。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、订购、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此 Printing Press CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

此 API 的其他工具都不具备这些功能。

不断累积的本地快照

• since — 查看自上次同步以来，首页上哪些内容排名上升、下降、新出现或消失。

  当 Agent 每天启动后需要了解 HN 从昨天到现在有哪些变化，而且不想每次轮询都重新获取 500 条内容时，可使用此功能。

  hackernews-pp-cli since --json
  

• controversial — 根据近期窗口内最高的评论数与得分之比为故事排序，找出争论最激烈的讨论。

  当你想找高参与度、低认可度的内容——也就是激烈辩论的信号——而非单纯追求热度时，可使用此功能。

  hackernews-pp-cli controversial --window 7d --json
  

• velocity — 根据本地快照显示某个故事排名随时间的变化趋势：上升、持平或下降。

  当 Agent 询问“这个故事还在获得关注，还是已经达到热度峰值”时，可使用此功能；只有快照才能给出有意义的答案。

  hackernews-pp-cli velocity 47998158 --json
  

• sync — 将 top/new/best/show/ask/job 列表和近期有变化的内容拉取到本地 SQLite，供离线使用并保留快照历史。

  每天运行一次（Agent 可每小时运行一次）。这是基础步骤，可将原本无法实现的 since/velocity/controversial/users-stats 查询变成一次 SQL 查询。

  hackernews-pp-cli sync --resources updates --agent
  

发挥 Algolia 的优势

• pulse — 查看过去 N 天内任意主题每天的提及次数、平均得分和评论量。

  当你想知道“这个主题是在升温还是降温”，而非“现在排名最高的故事是什么”时，可使用此功能。

  hackernews-pp-cli pulse rust --days 7 --agent
  

• repost — 检查此 URL 是否曾经发布过。列出所有以往的投稿及其得分、评论数和日期。

  提交 Show HN 前可使用此功能——重复 URL 会迅速无人问津，因此你应该先了解之前的投稿表现。

  hackernews-pp-cli repost https://example.com/article
  

• search local — 在你曾同步过的所有故事和评论中进行离线全文搜索；语料库会随着使用不断扩大。

  当你调查长尾主题或重温上季度的研究时，可使用此功能——Algolia 可能会降低其排名或将其过滤掉，但你的本地语料库不会。

  hackernews-pp-cli search local "vector database" --limit 20 --json
  

招聘帖挖掘

• hiring stats — 汇总最近 N 个月的 Who-is-Hiring 主题：热门语言、远程职位占比、热门公司、地点分布。

  当你需要了解季度或季节性招聘趋势——例如语言热度、远程职位占比变化、地点密度——而不只是本月的职位信息时，可以使用此命令。

  hackernews-pp-cli hiring stats --months 3 --agent
  

• hiring companies — 列出在最近 N 个招聘主题中有 M 个主题发布过职位的公司，并提供首次出现时间、最近出现时间和发布月份数。

  当你进行人才寻源或趋势追踪时，可以使用此命令了解哪些公司持续招聘，哪些只是偶尔发布职位，而无需抓取 HNHIRING.com。

  hackernews-pp-cli hiring companies --months 6 --min-posts 3 --agent
  

跨实体本地查询

• users stats — 统计用户所有提交的得分中位数和 p90 值，以及热度分档和按小时划分的得分分布。

  在发布自己的作品前，可以使用此命令了解自己的热度模式；也可以在互动前了解发帖者的历史表现。

  hackernews-pp-cli users stats pg --json
  

命令参考

items — 根据 ID 获取任意 HN 条目（故事、评论、招聘信息、投票）

• hackernews-pp-cli items <itemId> — 获取指定故事、评论、招聘信息或投票的详细信息

maxitem — 当前最大的条目 ID

• hackernews-pp-cli maxitem — 返回 Hacker News 当前分配的最大条目 ID

stories — 浏览 Hacker News 上的热门、最新和最佳故事

• hackernews-pp-cli stories ask — 获取最新的 Ask HN 帖子
• hackernews-pp-cli stories best — 获取 Hacker News 上得票最高的故事
• hackernews-pp-cli stories job — 获取最新的 Hacker News 招聘信息
• hackernews-pp-cli stories new — 获取 Hacker News 上最新的故事
• hackernews-pp-cli stories show — 获取最新的 Show HN 帖子
• hackernews-pp-cli stories top — 获取 Hacker News 当前的热门故事

updates — 最近有变动的条目和个人资料

• hackernews-pp-cli updates — 获取最近有变动的条目和用户个人资料

users — 查找 Hacker News 用户个人资料

• hackernews-pp-cli users <userId> — 获取用户个人资料，包括 karma 和提交历史

手写命令

• hackernews-pp-cli sync — 将热门、最新、最佳、Show、Ask、招聘列表和近期条目拉取到本地 SQLite 存储
• hackernews-pp-cli search <query> — 通过 Algolia 对 Hacker News 故事和评论进行全文搜索（离线 FTS 搜索请使用 'search local'）
• hackernews-pp-cli hiring — 挖掘 'Ask HN: Who is hiring' 主题（筛选、统计、公司）
• hackernews-pp-cli freelance — 挖掘 'Ask HN: Freelancer? Seeking freelancer?' 主题（筛选）
• hackernews-pp-cli since — 显示上次同步以来首页的变化（新增、移除、排名变动的故事）
• hackernews-pp-cli pulse <topic> — 显示 HN 对某个主题的讨论情况——每日提及次数、得分和评论量
• hackernews-pp-cli controversial — 查找评论数与得分之比最高的故事（争议性讨论）
• hackernews-pp-cli repost <url> — 检查此 URL 是否曾在 HN 发布，并列出先前的提交及其得分和日期
• hackernews-pp-cli velocity <id> — 显示故事在本地快照中的排名变化轨迹
• hackernews-pp-cli doctor — 运行自诊断：检查 API 连通性、存储可写性和配置是否正常

新鲜度约定

此打印版 CLI 仅为已注册、由存储支持的读取命令路径管理有界新鲜度。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有界刷新。--data-source local 不会刷新。--data-source live 会读取 API，且不会修改本地存储。设置 HACKERNEWS_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，而不改变数据源选择。

涵盖的路径：

• hackernews-pp-cli stories
• hackernews-pp-cli stories ask
• hackernews-pp-cli stories best
• hackernews-pp-cli stories job
• hackernews-pp-cli stories new
• hackernews-pp-cli stories show
• hackernews-pp-cli stories top
• hackernews-pp-cli updates

当 JSON 输出使用生成的来源信息封套时，新鲜度元数据位于 meta.freshness。应将其视为该命令路径的当前缓存新鲜度，而不是历史数据已完整回填或 API 特定数据已丰富的保证。

查找合适的命令

当你知道想做什么，却不知道该用哪个命令时，可以直接询问 CLI：

hackernews-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有足够可信的匹配项——请改用 --help，或使用更具体的查询。

使用示例

为 Agent 获取每日首页差异

hackernews-pp-cli sync && hackernews-pp-cli since --json --select added,removed,moved

先同步，再比较差异。--select 会将载荷缩减为仅包含变更差异——Agent 处理的是 KB，而不是 MB。

使用指定字段监控主题

hackernews-pp-cli pulse openai --days 7 --agent --select buckets.day,buckets.hits,buckets.avg_score

按天统计提及次数、平均分数和评论数量——使用 --select 仅提取深层嵌套响应中的趋势维度。

提交前检查重复内容

hackernews-pp-cli repost https://example.com/article --json

列出该 URL 过去的所有提交记录，包括分数、评论和日期——一次往返即可回答“是否有人发过这个内容”。

筛选远程 Go 职位招聘帖

hackernews-pp-cli hiring filter "(remote|REMOTE).*\\bGo\\b" --json

在最新的月度主题帖中运行正则表达式。双重转义的 \\b 是真正的正则单词边界；--json 会返回结构化行，而不是一大段匹配结果。

季度招聘趋势

hackernews-pp-cli hiring companies --months 6 --min-posts 3 --agent

列出最近 6 个月度主题帖中至少发布过 3 次的公司——首次出现时间、最后出现时间和总月数。跨月查询无法在没有本地存储的情况下完成。

身份验证设置

无需身份验证。

运行 hackernews-pp-cli doctor 验证设置。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。带点的路径可深入嵌套结构；数组会逐元素遍历。对于冗长的 API，这对缩小上下文至关重要：

  hackernews-pp-cli items 47998158 --agent --select id,name,status
  

• 可预览 — --dry-run 会显示请求，但不会发送

• 适合离线使用 — 有本地 SQLite 存储时，同步和搜索命令可以使用它

• 非交互式 — 不会发出提示，所有输入都通过标志传入

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、订购、发送或其他会修改数据的请求

响应封套

从本地存储或 API 读取的命令会将输出封装在来源信息封套中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

从 .results 解析数据，并通过 .meta.source 判断数据来自实时 API 还是本地存储。只有当 stdout 指向终端时，才会将便于人类阅读的 N results (live) 摘要输出到 stderr——通过管道使用或由 Agent 消费时，stdout 只包含纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

hackernews-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
hackernews-pp-cli feedback --stdin < notes.txt
hackernews-pp-cli feedback list --json --limit 10

记录会保存在本地的 ~/.hackernews-pp-cli/feedback.jsonl。除非设置了 HACKERNEWS_FEEDBACK_ENDPOINT，且同时传入 --send 或设置 HACKERNEWS_FEEDBACK_AUTO_SEND=true，否则不会通过 POST 发送。默认情况下仅保存在本地。

请记录让你感到意外的地方，而不是撰写错误报告。简短、具体、一行即可：这才是会不断累积价值的部分。

输出交付

每个命令都接受 --deliver <sink>。输出会发送到指定的接收目标，同时也会（或替代）输出到 stdout，因此 Agent 无需手动通过管道传递即可路由命令结果。支持三种接收目标：

接收目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 application/json；启用 --compact 时使用 application/x-ndjson）

不支持的协议会被拒绝，并返回一条结构化错误，指出支持的协议。Webhook 请求失败时会返回非零退出码，并在 stderr 中记录 URL + HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果计划任务中的 Agent 每次运行都以相同配置调用同一命令，就可以使用配置——这是 HeyGen 的“Beacon”模式。

hackernews-pp-cli profile save briefing --json
hackernews-pp-cli --profile briefing items 47998158
hackernews-pp-cli profile list --json
hackernews-pp-cli profile show briefing
hackernews-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便用于自省的 Agent 在运行时发现它们。

退出码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 hackernews-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的前置条件
3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/hackernews/cmd/hackernews-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add hackernews-pp-mcp -- hackernews-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which hackernews-pp-cli 如果未找到，则提供安装选项（参见本技能顶部的前置条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   hackernews-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，则查看子命令帮助：hackernews-pp-cli <command> --help。