mcpField
A
amazon-kdp

amazon-kdp

github.com/joshyattridge营销与增长1649 次安装16 周前更新
代码仓库

关于 amazon-kdp

amazon-kdp 是用于 Amazon KDP 图书管理的自动化技能，通过本地 Express 服务和 Playwright 浏览器会话读取报告与书籍信息，并执行元数据、定价、内容和发布操作。它面向需要处理 KDP 书目和出版流程的 Agent，要求写入操作逐本顺序执行并验证结果。

主要功能

  1. 01同步书籍元数据并审计列表
  2. 02下载及解析版税报告
  3. 03更新详情、定价与 KDP Select
  4. 04上传内页和封面 PDF
  5. 05创建、发布及管理书目
  6. 06写入失败时自动尝试恢复

适用场景

  1. 01汇总指定日期范围的版税报告
  2. 02检查并更新图书关键词或描述
  3. 03逐本上传封面并发布新书

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/joshyattridge/amazon-kdp-skill --skill amazon-kdp

安装后在 Claude Code 中输入/amazon-kdp确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
.env.example
package.json
README.md
package-lock.json
examples/
publish-book.example.json
lib/
royaltyDate.ts
parseKdpUploaderWorkbook.ts
parseKdpWorkbook.ts
references/
metadata-fields.md
api-endpoints.md
troubleshooting.md
scripts/
add-second-category.ts
debug-categories.ts
debug-desc-no-h1.ts
approve-roulette-content.ts
debug-direct-save.ts
debug-desc-plain.ts
debug-description-fill.ts
debug-new-title-save.ts
debug-fill-and-save.ts
debug-pricing-multi.ts
debug-pricing-playwright-fill.ts
debug-pricing-save.ts
export-metadata-xlsx.mjs
debug-stock-market-save.ts
finish-roulette-final.ts
discover-kdp-apis.mjs
debug-save-persist.ts
kdp-cli.mjs

详细介绍

Amazon KDP 自动化

独立的技能仓库，包含本地 Express + Playwright 服务。Amazon 没有公开的 KDP 元数据 API——此工具使用已保存的浏览器会话 Cookie 调用 KDP 内部页面和报告端点。

Agent 职责

由你运行所有操作。 不要让用户运行终端命令。

  1. 确保已完成设置：运行 npm install；如果 .env 不存在，将 .env.example 复制为 .env。
  2. 如果服务尚未运行，则启动服务：在后台运行 npm run server:start。
  3. 在任何同步、更新或下载操作之前检查会话：运行 npm run status。
  4. 通过 npm 脚本或本地 REST API 自行执行所有 KDP 任务。
  5. 仅在 Amazon 登录期间暂停并等待用户——他们必须在可见的 Chromium 窗口中完成登录（包括 MFA）。持续轮询 npm run status，直到显示 connected: true。

会话保存在 .kdp-session/ 中（已加入 gitignore）。

顺序操作（必须遵守）

用户要求处理多本书或多个写入任务时，必须逐一处理——绝不可并行处理，也不可在单个批量请求中处理。

应当：

  • 完全处理完一本书（或一项元数据、定价或内容更新）后，再开始下一项
  • 使用单本书端点：/api/kdp/metadata/update、/api/kdp/pricing/update、/api/kdp/content/upload、/api/kdp/publish——每本书调用一次 HTTP 接口
  • 每个书名运行一次 npm run publish:book -- spec.json --live；必要时为每本书生成单独的 spec JSON
  • 等待每次调用完成（发布可能需要几分钟），并在继续之前核实结果
  • 如果某一步失败，先停止处理或修复该书，再继续——不要盲目地执行队列中的其余任务

不要：

  • 未经用户批准，不要创建在一个长时间运行进程中循环处理任务的批处理脚本
  • 不要通过批量 API 路由（/batch 端点）在单个请求中处理多个书名
  • 不要并行或同时在后台运行多个发布或上传命令
  • 不要同时为 KDP 打开多个 Playwright 浏览器会话进行写入

这样可以避免 HTTP 超时、Amazon“服务器繁忙”速率限制，以及浏览器或会话冲突。批量端点仅供高级用途；Agent 默认应逐一调用单本书接口。

子技能——操作前先阅读对应文件

任务技能文件
登录 / 会话状态skills/connect-session/SKILL.md
账户信息 + 报告目录skills/account-info/SKILL.md
下载版税报告skills/download-reports/SKILL.md
将版税 Excel 解析为 JSON 摘要skills/parse-reports/SKILL.md
获取书籍元数据（全部或单本）skills/sync-metadata/SKILL.md
将元数据导出为 Excelskills/export-metadata/SKILL.md
审核元数据（关键词、分类）skills/analyze-metadata/SKILL.md
推送商品详情页更改skills/update-metadata/SKILL.md
推送定价 / KDP Select 设置skills/update-pricing/SKILL.md
上传内文 / 封面 PDFskills/upload-content/SKILL.md
完整发布向导（创建 → 发布）skills/publish-book/SKILL.md

快速命令（由 Agent 运行）

npm run status                    # session connected?
npm run account:info              # catalog size, vendor code
npm run bookshelf:list            # fast title/format refs
npm run catalog:get               # all titles + ASINs from kdpreports
npm run download:report           # lifetime royalties → output/
npm run parse:report -- file.xlsx # summarize royalties
npm run sync:metadata             # full Bookshelf scrape → cache
npm run sync:book -- ID paperback # refresh one book
npm run metadata:get              # print cached JSON
npm run metadata:export           # cache → Excel
npm run metadata:analyze          # keyword/category audit
npm run update:metadata -- file.json --dry-run
npm run publish:book -- examples/publish-book.example.json

架构

Browser session (.kdp-session/amazon-kdp.json)
        ↓
Local server (server/src/index.ts) — REST API
        ↓
Playwright session cookies
        ↓
Request-first: kdpreports JSON APIs → HTML GET + parse → browser fallback
        ↓
Global rate limit (KDP_REQUEST_DELAY_MS between every request)

读取操作

操作端点 / 命令
会话状态GET /api/kdp/status
账户信息GET /api/kdp/account
报告目录GET /api/kdp/catalog
书架列表（快速）GET /api/kdp/bookshelf
元数据缓存GET /api/kdp/metadata
完整元数据同步POST /api/kdp/metadata/sync
同步单本书籍POST /api/kdp/metadata/sync/:titleId/:format
元数据审计GET /api/kdp/metadata/analyze
全部时间段版税POST /api/kdp/sync
指定日期范围的版税POST /api/kdp/reports/download

写入操作

操作端点
更新详情（关键词、描述、作者、标志）POST /api/kdp/metadata/update
批量更新元数据POST /api/kdp/metadata/update/batch
更新定价 / KDP SelectPOST /api/kdp/pricing/update
批量更新定价POST /api/kdp/pricing/update/batch
上传内文/封面POST /api/kdp/content/upload
批量上传POST /api/kdp/content/upload/batch
创建新书名POST /api/kdp/titles/create
更新分类POST /api/kdp/categories/update
完整发布向导POST /api/kdp/publish
下架已发布书名POST /api/kdp/titles/unpublish
删除草稿POST /api/kdp/titles/delete
归档书名POST /api/kdp/titles/archive
恢复经验GET /api/kdp/recovery/learnings

对其他书籍执行实时写入前，务必先对一本书进行试运行。未经用户明确确认，切勿设置 publish: true。

批量 REST 端点（/batch）仅供手动/高级用途。Agent 不得使用这些端点处理多本书——应逐次调用单本书端点，每次处理一个书名，并等待操作完成。

自动错误恢复

写入流程（保存详情、上传内容、定价、发布向导）在 KDP 阻止操作继续时，会通过恢复机制重试：

  • 内置操作手册：关闭模态框、设置发布日期、确认稿件预览、选择封面上传折叠面板、绕过 Server Busy、等待处理完成等。
  • 经验文件：.kdp-session/recovery-learnings.json——成功的“错误→操作”组合在后续运行中会获得更高优先级。
  • 发布 API 响应可能包含描述尝试过哪些操作的 recoveryLog。

如果恢复重试次数用尽，请查看 errors 和 recoveryLog，然后解决根本问题（例如，封面 PDF 尺寸无效）。

Agent 规则

  1. 同步/更新前，务必检查会话（npm run status）。如果 connected: false，请先运行登录子技能。
  2. 写入操作一次执行一项——参见顺序操作（必需）。不得使用批处理脚本、并行发布，也不得使用 /batch API 处理多个书名。
  3. 切勿提交 .kdp-session/ 或已下载的 .xlsx 文件。
  4. 速率限制：服务器会通过 KDP_REQUEST_DELAY_MS（默认值为 4s）间隔安排每次 KDP 页面加载和 API 调用。不得绕过此限制。
  5. 元数据/定价更新：先对一本书进行试运行，然后每次请求仅对一本书应用实时更改。
  6. 通过从 KDP 重新读取元数据来验证保存结果（更新流程内置了此步骤）。
  7. 分类：可通过浏览节点 ID 或模态框路径选择器进行写入（POST /api/kdp/categories/update 或发布向导）。
  8. 发布：先使用 npm run publish:book 进行试运行；实时发布需要设置 "publish": true 并获得用户确认。每次调用 publish:book 只能处理一本书。

参考资料

评论

支持 Markdown