pp-kdpnichefinder

KDP Niche Finder — Printing Press 命令行工具

前置条件：安装命令行工具

此技能依赖 kdpnichefinder-pp-cli 二进制文件。**在调用此技能中的任何命令之前，必须确认命令行工具已安装。**如果尚未安装，请先安装：

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

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

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

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）。此方式会将程序安装到 $GOPATH/bin（默认值为 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/marketing/kdpnichefinder/cmd/kdpnichefinder-pp-cli@latest

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

KDP Niche Finder 是一款点击浏览式网页工具，一次显示一个精选利基类别，不保留历史记录，也不支持导出。此命令行工具会将全部四个类别镜像到本地 SQLite 数据库，让你可以跨类别按机会对利基进行排名（rank）、查看自上次刷新以来哪些利基正在兴起或衰退（drift）、发现同时出现在多个类别中的书籍（dupes）、评估出版商饱和度，并导出适用于 KDP 的 CSV——整个过程均可离线进行，并且原生适配 Agent。

何时使用此命令行工具

当 Agent 或高级用户需要以编程方式研究 Amazon KDP 利基时，可使用此命令行工具：跨所有类别对机会进行排名、跟踪利基收入趋势随时间的变化、研究出版商竞争，或导出候选清单。它将 KDP Niche Finder 只能浏览的网页界面转变为可查询的本地数据库。

不适用场景

请勿在以下场景使用此命令行工具：

• 请勿使用此命令行工具生成书籍封面或内页——这属于 Artistly 的生成套件，而非此利基工具的功能。
• 请勿用它查询任意 ASIN 的 Amazon 实时 BSR——它仅涵盖 KDP Niche Finder 精选的类别。
• 请勿将它用于美国以外的市场——源数据以美国市场为主。

独特功能

此 API 的其他工具均不具备以下功能。

可持续积累的本地状态

• rank — 根据预估收入、销量和价格的综合指标，一次性为所有四个类别中的利基进行排名。

  当 Agent 需要找到机会最大的单一利基，而不是逐个类别浏览时，选择此功能。

  kdpnichefinder-pp-cli rank --max-price 9.99 --sort value --agent
  

• drift — 显示已同步利基的预估收入相较于较早快照是在上升还是下降。

  当你需要做出时机决策（立即发布还是跳过），而源工具完全无法回答此问题时，选择此功能。

  kdpnichefinder-pp-cli drift --since 7d --sort rising --agent
  

• keywords — 对已同步书籍的书名进行分词，并统计关键词频率，以发掘某个利基的热门词语。

  如果要根据实际畅销情况为 KDP 后台关键词字段提供种子词，请选择此功能。

  kdpnichefinder-pp-cli keywords --type evergreen --min-count 3 --agent
  

跨类别分析

• dupes — 查找出现在多个利基类别中的书籍（ASIN 相同），并显示其所属类别。

  当你想发现同时出现在多个类别中的利基——这是强有力的交叉验证信号时，选择此功能。

  kdpnichefinder-pp-cli dupes --agent
  

• saturation — 按类别显示预估收入在各出版商之间的集中程度（巨鲸型还是分散型）。

  当你想判断一个利基是否开放，还是已被单一出版商主导时，选择此功能。

  kdpnichefinder-pp-cli saturation --type hidden_gems --agent
  

• competitors — 对于指定的图书，根据提取出的 ASIN 列出同一出版商和同一价格区间的竞品。

  当你想在投入某个特定利基之前，研究其他赢家时，选择此功能。

  kdpnichefinder-pp-cli competitors 2584 --agent
  

Agent 原生工具链

• export — 将书名、ASIN、价格、预估销量和收入导出为 CSV，用于 KDP 后台关键词和封面工作。

  如果要将候选清单交给关键词／封面工具处理，而不必重新输入书名，请选择此功能。

  kdpnichefinder-pp-cli export --csv
  

发现信号

此 CLI 根据浏览器观察到的流量上下文生成。

• 捕获覆盖率：273 条网络记录中，有 60 条 API 记录
• 协议：rest_json（置信度 75%）、html_scrape（置信度 55%）
• 候选命令创意：create_folders — 根据观察到的 POST /api/folders 流量推导得出。；create_toggle_save — 根据观察到的 POST /api/books/{book_id}/toggle-save 流量推导得出。；list_categories — 根据观察到的 GET /api/categories 流量推导得出。；list_evergreen — 根据观察到的 GET /app/category/evergreen 流量推导得出。；list_folders — 根据观察到的 GET /api/folders 流量推导得出。；list_fresh_money — 根据观察到的 GET /app/category/fresh_money 流量推导得出。；list_hidden_gems — 根据观察到的 GET /app/category/hidden_gems 流量推导得出。；list_high_ticket — 根据观察到的 GET /app/category/high_ticket 流量推导得出。
• 注意事项：empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看起来像 API 的请求返回了空或 null 负载；架构置信度较低。

命令参考

books — 收藏和取消收藏细分图书

• kdpnichefinder-pp-cli books <book_id> — 切换图书的收藏状态；也可选择将其放入文件夹

categories — 细分领域类别元数据

• kdpnichefinder-pp-cli categories — 列出细分领域类别（键、名称、描述）

folders — 将已收藏的细分领域整理到文件夹中

• kdpnichefinder-pp-cli folders create — 创建文件夹
• kdpnichefinder-pp-cli folders list — 列出你的文件夹

niches — 浏览精选的 KDP 细分领域分类（真实的 Amazon 图书，含预估销量和收入）

• kdpnichefinder-pp-cli niches <type> — 浏览细分领域分类：evergreen、fresh_money、hidden_gems 或 high_ticket

saved — 你收藏的细分领域图书

• kdpnichefinder-pp-cli saved — 列出你收藏的图书

user — 已认证的账户

• kdpnichefinder-pp-cli user — 显示已认证用户

查找合适的命令

知道自己想做什么，但不知道该用哪个命令时，可以直接向 CLI 提问：

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

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

用法示例

找出所有分类中价格最低的细分领域

kdpnichefinder-pp-cli rank --max-price 9.99 --sort value --agent

按每美元收入对所有已同步图书进行排名，让价格低、回报高的细分领域优先显示。

从冗长的细分领域列表中筛选出关键信息

kdpnichefinder-pp-cli niches hidden_gems --search journal --agent --select title,estimated_monthly_revenue,amazon_url

使用带点号的 --select 路径，从分页的分类响应中仅提取标题、收入和 Amazon 链接。

找出逐周增长的细分领域

kdpnichefinder-pp-cli drift --since 7d --sort rising --agent

将最新快照与一周前的快照进行比较，显示预估收入有所增长的细分领域。

导出用于关键词研究的收藏清单

kdpnichefinder-pp-cli export --csv

将标题/ASIN/价格/销量/收入导出为 CSV，用于 KDP 后台关键词和封面工具。

身份验证设置

KDP Niche Finder 使用 Laravel 会话登录（无需 API 密钥）。运行 kdpnichefinder-pp-cli auth login --chrome，捕获已登录的 kdpnichefinder.com 浏览器会话；读取操作使用会话 Cookie，保存和文件夹操作还会发送 CLI 为你生成的 CSRF 令牌。

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

Agent 模式

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

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

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

  kdpnichefinder-pp-cli categories --agent --select id,name,status
  

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

• 支持离线 — 有本地 SQLite 存储时，同步/搜索命令可使用该存储

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

• 明确重试 — 仅当已存在的创建操作也应视为成功时，才使用 --idempotent

响应封装

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

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

使用 .results 解析数据，并通过 .meta.source 判断数据来自实时来源还是本地来源。只有当 stdout 是终端，且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到 stderr — 管道/Agent 使用者以及显式指定格式的运行会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

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

条目会本地存储在 ~/.local/share/kdpnichefinder-pp-cli/feedback.jsonl。除非设置了 KDPNICHEFINDER_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 KDPNICHEFINDER_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认行为仅在本地存储。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是能够持续积累价值的内容。

输出传递

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

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

不支持的方案会被拒绝，并返回列出受支持方案的结构化错误。Webhook 失败时会返回非零状态码，并将 URL 和 HTTP 状态码记录到 stderr。

命名配置文件

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

kdpnichefinder-pp-cli profile save briefing --json
kdpnichefinder-pp-cli --profile briefing categories
kdpnichefinder-pp-cli profile list --json
kdpnichefinder-pp-cli profile show briefing
kdpnichefinder-pp-cli profile delete briefing --yes

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

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/marketing/kdpnichefinder/cmd/kdpnichefinder-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add kdpnichefinder-pp-mcp -- kdpnichefinder-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

4. 如果有歧义，请查看子命令帮助：kdpnichefinder-pp-cli <command> --help。