---
name: kkapi-knowledge
title: 亚马逊实战指南
description: "亚马逊实战知识读写技能。凡对话涉及亚马逊选品、上架、广告、库存、账号、合规、术语等业务的『经验/教训/复盘/SOP/踩坑』的『记住/存入/调取/查询』意图时自动触发，把可复用结论沉淀进知识库，或检索通用亚马逊实战经验回答当前问题。通用经验全员共享，个性化内容（产品/listing）租户隔离。无需配置 MCP，只需首次填入一次 API Key。"
when_to_use: "当用户表达以下意图时自动触发：『记住这个』『存到知识库』『查一下之前』『上次怎么处理』『经验』『教训』『复盘』『SOP』『踩坑』；或提到亚马逊业务场景如『选品』『上架』『广告 ACOS』『库存』『账号』『合规』『listing』并希望沉淀或检索；或用户明确提到『知识库』『KKAPI』『亚马逊实战指南』。也适用于把本次对话的关键结论、踩坑记录、最佳实践写入知识库，或从库检索历史经验回答当前问题的场景。"
---

# 亚马逊实战指南

免 MCP 配置，装好即用。沉淀亚马逊选品、上架、广告、库存、账号、合规等实战经验，任何 Agent（豆包、千问、Claude、Hermes 等）接入即拥有通用亚马逊常识。通用经验全员共享，个性化内容（产品信息、listing）自己存、租户内多 Agent 共享。

## When to use

见到以下任一信号，**先触发本技能**做一次「读取或写入」判断：

- **写入类**：用户说「记住这个」「存到知识库」「把结论存下来」「以后要能搜到」「这条经验入库」「保存这份 SOP/话术/复盘」。
- **读取类**：用户问「之前有没有遇到过」「上次这种客户怎么处理」「查一下库里有没有……」「之前谁踩过这个坑」。
- **隐含类**：提供一段经验性结论、踩坑复盘、SOP、话术，且上下文表明这是可复用资产，希望长期留存。
- 用户直接提到「知识库」「KKAPI」「多 Agent 共享」。

> ⚠️ 判断口径：仅当内容**确实是可复用的经验/结论/规范/事实**时才写入。日常闲聊、一次性寒暄、临时数据不要入库，避免污染。

## Runtime requirements

- Browser login required: no
- Sandbox required: yes（脚本运行 + 本地 config 持久化 Key）
- MCP required: **no**（本技能通过 `scripts/kkapi.py` 直接调用 KKAPI HTTP 端点，外部无需配置任何 MCP 服务）
- Page script required: no
- User local folder required: no
- 依赖：Python 3.8+，仅标准库，无第三方库。

## 首次接入：三步引导（务必先做）

用户首次接入本 Skill 时，**不要急着直接回答运营问题**，先按下面三步引导，把个性化产品知识建起来。用户想跳过就跳过（后续慢慢补），但要先主动引导一次。

### 第一步：确认并配置 KKAPI Key

先问用户：「**你有 KKAPI 的 API Key 吗？**」

- **没有** → 一步步给出申请路径：
  1. 打开 https://www.kkapi.me/#apply 填写企业信息提交申请，自动开通；
  2. 用用户名/密码登录 https://www.kkapi.me/mcp/admin/（Agent 管理后台）；
  3. 添加自己的 Agent，拿到该 Agent 专属 API Key（形如 sk_kkapi_...）；
  4. 把 Key 发给我，我帮你写入配置。
- **有** → 让用户把 Key 发给你，写入配置并验证：
  ```bash
  python scripts/kkapi.py config --key sk_kkapi_用户给的Key
  python scripts/kkapi.py whoami
  ```

> ⚠️ **如果你（Agent）没有终端执行权限**（无法运行 shell 命令，如部分网页版/纯对话型 Agent），不要假装执行。改为引导用户在本地终端手动运行 `curl -fsSL https://www.kkapi.me/skill/install.sh | bash`，或让用户手动下载 3 个文件放到 skills 目录（SKILL.md → kkapi-knowledge/SKILL.md，kkapi.py → kkapi-knowledge/scripts/kkapi.py，api.md → kkapi-knowledge/references/api.md）。

### 第二步：引导建立个性化产品知识

Key 配好后，主动问用户（这是让 Agent「越用越懂你」的关键）：

「你现在亚马逊**正在卖、或打算卖的什么产品**？有没有产品资料可以发给我？比如产品的特点、卖点、竞品情况、listing 文案、目标人群等，发给我后我帮你自动整理，存进你的专属知识库。」

- 用户发来产品资料后：用 `create` 整理成结构化文档存库。标题如「产品档案：<产品名>」，正文含「产品特点 / 卖点 / 竞品 / 目标人群 / listing」等，tags 带产品名+品类，source-type 用 `product`。
- 用户暂时没有 / 不想填 → 不勉强，跳过并告知「后续随时可以把产品资料发我，我再帮你补上」。

### 第三步：转入正常问答

前两步完成后，告诉用户：「**搞定！现在你可以问我任何亚马逊运营问题**，比如选品、广告 ACOS、库存、上架、账号合规等，我会结合通用经验和你的产品资料来回答。」

然后进入下方正常的「读 or 写」工作流。

## Files in this skill

| 文件 | 作用 |
|------|------|
| `scripts/kkapi.py` | 核心客户端。封装 MCP streamable HTTP JSON-RPC 协议，直接调 KKAPI 端点；提供 search/get/list/create/update/delete/whoami/config 子命令。仅标准库。 |
| `references/api.md` | KKAPI 端点与各工具参数、字段、示例的参考手册（供 Agent 在需要精确参数时查阅）。 |

## Capability routing

| 意图 | 执行方式 |
|------|----------|
| 写入一条经验/结论 | `scripts/kkapi.py create "<标题>" "<内容>" --tags <标签> --space <space> --source-agent <谁> --source-type <类型>` |
| 检索历史经验回答当前问题 | `scripts/kkapi.py search "<问题>"` 然后取结果 |
| 读某篇详情 | `scripts/kkapi.py get <doc_id>` |
| 列出/浏览库 | `scripts/kkapi.py list --limit 20` |
| 更新已有文档 | `scripts/kkapi.py update <doc_id> --content "..."` |
| 删除文档 | `scripts/kkapi.py delete <doc_id>` |
| 校验 Key | `scripts/kkapi.py whoami` |

## 工作流（读 or 写）

### 第一步：判断「写」还是「读」

- **写**：对话产生了一个**可复用、有长期价值的结论**（经验、教训、复盘、SOP、话术、踩坑记录、最佳实践、决策依据）。用户明确要求保存，或明显希望沉淀。
- **读**：用户想基于历史经验回答当前问题，或检索「之前有没有处理过」。此时用 `search` 检索，再把命中的内容作为回答依据，并在回答中说明「引用自知识库」。

### 第二步：执行

**写入执行**：
1. 提炼标题（简洁、可检索，含主体 + 主题，如「广告ACOS飙升处理复盘」「RZW窗帘类目上架checklist」）。
2. 正文用结构化的 Markdown（含背景 / 问题 / 处理 / 结论 / 可复用要点），保持原创完整。
3. 打标签 `--tags`：建议带项目/品类/主题，如 `广告,复盘`、`HGS,上架`、`RZW,质检`，便于后续按标签检索。
4. 视情况 `--space`（默认 `aurvera_global`）、`--source-agent`（谁贡献的）、`--source-type`（`experience`/`review`/`sop`/`lessons`）。
5. 写完直接读取脚本返回的 `doc_id` 作为「已写入」的验证，并记入 `plan_track`。

**读取执行**：
1. `search "<用户问题的关键短语>"`，从返回结果挑选最相关 1~3 篇。
2. 若需要细节，`get <doc_id>` 读全文。
3. 用命中内容回答，并标注来源；若检索不到，诚实说明「知识库暂无该资料」，不要编造。

### 第三步：验证并记账

- 写入：确认返回的 `doc_id`/`title` 存在（脚本打印 JSON 即为成功）。
- 读取：确认拿到了可引用的正文，而不是空结果。
- 将关键动作与结果记入 `plan_track`（子目标状态、doc_id、检索命中数），便于多轮任务追踪。

## Output contract

- **写入**：报告「已存入知识库」，附 `doc_id`、`title`、打标签。
- **读取**：直接给出基于库内容的回答，并注明「来源：KKAPI 知识库《标题》」；无命中则说明暂无。
- 脚本统一输出 JSON（`ensure_ascii=False`，中文可读），便于直接读取字段。

## Failure handling

| 场景 | 处理 |
|------|------|
| 无 Key / Key 无效 | 脚本自动打印申请引导或「Key无效」提示；引导用户去 kkapi.me 申请/重置，不编造结果 |
| 网络/端点异常 | 提示重试 1 次；仍失败则告知「知识库暂不可用」，不阻断主流程 |
| 检索无结果 | 诚实说明「库中暂无」，可建议换个关键词再搜 |
| 用户不希望入库 | 尊重用户，不写入 |
| 内容重复度高 | 若明显与已有文档重复，优先 `update` 追加或提示用户，避免重复入库 |

## 多 Agent 共享说明

知识集中存储在 KKAPI 服务端；本技能只是统一的「读写规范 + 客户端」。团队内只要都用这个 Skill（同一套触发词、同一套写入格式），多个 Agent 就会读写同一个库，从而共享经验。建议在 SKILL.md / 命名 / 标签上统一，例如固定 space、约定标签前缀，避免口径冲突。

## 最佳实践

1. **可复用才入**：只沉淀有长期价值的内容，避免闲聊污染。
2. **标题可检索**：用「主体+主题+（可选）结论」命名，如「窗帘上架 质检 高频问题清单」。
3. **结构清晰**：正文用「背景/问题/处理/结论/可复用要点」。
4. **标签规范**：统一标签利于跨 Agent 检索，如 `项目名,品类,主题`。
5. **来源可溯**：写入时带 `--source-agent`，回答时标注引用来源，减少幻觉。