# 产品研究知识库规则

## 目标

这个知识库积累 Amazon 产品研究的所有数据和分析，
支持跨项目、跨品类的知识复用。

## 素材规则

- `raw/` 是原始素材的存放目录，只增不改
- 原始素材来自 scout CLI 命令缓存（`~/.scout/cache/` 中的 JSON 文件）
- 文件名格式：`YYYY-MM-DD-<命令>-<参数摘要>.json`
- 收录时保留完整 meta 头（command、args、timestamp、source）
- `wiki/` 保存从原始数据中提炼的结构化知识
- 重要结论必须能追溯到 source 页

## 数据来源类型

本 KB 的 raw source 主要来自 scout CLI 命令缓存：

| 来源命令 | 数据类型 | 应创建/更新的页面 |
|---------|---------|----------------|
| scout search | Amazon 搜索结果 | sources/ + overview/market-{project} |
| scout product | 产品详情 | sources/ + entities/products/{ASIN} |
| scout reviews | 产品评论 | sources/ + overview/pain-points-{project} |
| scout keepa product | 历史趋势 | sources/ + entities/products/{ASIN} + overview/trends-{project} |
| scout keepa search/bestsellers/deals | Keepa 筛选/榜单 | sources/ + overview/market-{project} |
| scout keepa seller | 卖家信息 | sources/ + entities/brands/{name} |
| scout sp keywords | ASIN 流量关键词 | sources/ + entities/products/{ASIN} |
| scout sp keywords-mine | 关键词搜索量 | sources/ + overview/market-{project} |
| scout sp keywords-order | ASIN 出单关键词 | sources/ + entities/products/{ASIN} |
| scout sp keywords-research/trends | 关键词市场分析 | sources/ + overview/market-{project} |
| scout sp predict | ASIN 销量预测 | sources/ + entities/products/{ASIN} |
| scout sp competitors | 竞品列表 | sources/ + overview/competition-{project} |
| scout sp coupon | 优惠趋势 | sources/ + entities/products/{ASIN} |
| scout sp brands | 品牌集中度 | sources/ + entities/brands/* + overview/competition-{project} |
| scout sp sellers/seller-countries/seller-types | 卖家分布 | sources/ + overview/competition-{project} |
| scout sp market/market-stats/demand/prices/ratings/listing-* | 类目市场数据 | sources/ + entities/categories/{name} + overview/market-{project} |
| scout sp ebc/products | 类目 Listing 分布 | sources/ + overview/competition-{project} |
| scout sp google-trend | 谷歌趋势 | sources/ + overview/market-{project} |
| scout sp aba-weekly/monthly/trend | ABA 数据 | sources/ + overview/market-{project} |
| scout sp category | 类目树 | sources/ + entities/categories/{name} |
| scout supplier-search/supplier-search-image | 1688 供应商 | sources/ + entities/suppliers/* + overview/suppliers-{project} |
| scout tiktok/reddit/twitter/instagram | 社交趋势 | sources/ + overview/market-{project} |
| scout douyin/xhs/taobao | 中国平台 | sources/ + overview/market-{project} |
| scout shein-search/temu-search | 竞品平台 | sources/ + overview/market-{project} |

**兜底规则**：未在上表列出的 scout 命令，默认只创建 sources/ 页，不自动创建 entity。

## Entity 类型

| 类型 | 路径 | 创建方式 | 包含什么 |
|------|------|---------|---------|
| 卖家画像 | entities/seller-profile.md | 手动（首次初始化时创建） | 目标市场、价位、预算、决策标准 |
| 研究项目 | entities/projects/{slug}.md | 手动（立项时创建） | IPD 阶段、checklist、SPAN、FAN、决策记录 |
| 品牌 | entities/brands/{name}.md | ingest 自动创建 | 品牌信息、ASIN 列表、市场份额、跨项目出现 |
| 竞品 | entities/products/{ASIN}.md | ingest 自动创建 | 产品详情、评论摘要、关键词、历史趋势 |
| 供应商 | entities/suppliers/{name}.md | ingest 自动创建 | 价格、MOQ、能力、合作记录 |
| 品类 | entities/categories/{name}.md | ingest 自动创建 | 品类概况、子品类、市场规模 |

## Overview 类型

| 类型 | 路径 | 包含什么 |
|------|------|---------|
| 产品路标 | overview/roadmap.md | 品类机会池、优先级排序、时间线 |
| 能力货架 | overview/cbb.md | 跨项目可复用的供应商/物流/知识 |
| 市场分析 | overview/market-{project}.md | 市场概况、子品类分布、需求验证 |
| 竞争格局 | overview/competition-{project}.md | 品牌集中度、卖家构成、Listing 能力 |
| 痛点分析 | overview/pain-points-{project}.md | 差评聚类、好评亮点、差异化方向 |
| 趋势分析 | overview/trends-{project}.md | Keepa BSR、季节性、生命周期 |
| 供应商分析 | overview/suppliers-{project}.md | 供应商对比、成本测算 |

## Analysis 类型

| 类型 | 路径 | 包含什么 |
|------|------|---------|
| 产品立项书 | analyses/{project}-charter.md | CDCP Gate 产出 |
| 商业计划书 | analyses/{project}-business-case.md | PDCP Gate 产出 |
| SPAN 定位 | analyses/{project}-span.md | 战略定位分析 |
| FAN 财务模型 | analyses/{project}-fan.md | 单元经济 + 场景分析 |
| 品类分析报告 | analyses/mm-{topic}.md | MM 阶段产出 |
| Portfolio 分析 | analyses/portfolio-{date}.md | 跨项目对比 |

## 工作流

### Ingest（收录）

1. 将 `~/.scout/cache/{project}/` 中的缓存文件复制到 `raw/`
2. 在 `wiki/sources/` 创建来源页（结构化摘要，不是原始 JSON 复制）
3. 根据"数据来源类型"表，创建/更新相关 entity 和 overview 页面：
   - scout search 数据 → 提取每个 ASIN 的基础信息，已有 entity 页则更新，否则仅记录在 source 页
   - scout product 数据 → 必须创建/更新 entities/products/{ASIN}.md
   - scout sp brands 数据 → 为每个头部品牌创建/更新 entities/brands/{name}.md
   - scout supplier-search 数据 → 为报价合理的供应商创建 entities/suppliers/{name}.md
   - 社交趋势数据 → 不创建 entity，仅 source + overview
4. 更新 `index.md` 索引
5. 在 `log.md` 追加记录（日期 + 收录了什么 + 更新了哪些页面）
6. git commit

### Query（查询）

1. 先查 `index.md` 定位相关页面
2. 读取相关 wiki 页面回答问题
3. 如果 wiki 页面信息不足，查 `raw/` 原始 JSON 补充
4. 如果知识库内无答案，建议执行 scout 命令获取新数据

### Lint（检查）

1. 检查页面是否符合命名约定
2. 检查 entity 页面是否聚焦（一个 ASIN 一页，一个品牌一页）
3. 检查 `index.md` 是否与实际文件一致
4. 检查 overview 页面是否有过时数据（对比 raw/ 中最新来源日期）
5. 检查是否有孤立页面（无 source 引用的 entity）

## 编辑规则

- 事实性内容必须标注来源（source 页文件名或 raw/ 文件路径）
- 冲突数据并列呈现，标注各自来源和日期
- entity 页面保持聚焦：一个 ASIN 一个页面，一个品牌一个页面
- overview 页面按项目分：market-{project}.md 只包含该项目的市场分析
- 品牌和供应商的 entity 页面可以被多个项目引用（跨项目复用）
- 页面开头用一句话概括本页内容

## 命名约定

| 目录 | 格式 | 示例 |
|------|------|------|
| sources/ | `YYYY-MM-DD-<命令>-<参数>.md` | `2026-05-08-search-3d-printed-toys.md` |
| entities/products/ | `<ASIN>.md` | `B0DTJD9939.md` |
| entities/brands/ | `<kebab-case-品牌名>.md` | `rapean.md` |
| entities/suppliers/ | `<kebab-case-供应商名>.md` | `shenzhen-aori.md` |
| entities/categories/ | `<kebab-case-品类名>.md` | `3d-printed-toys.md` |
| entities/projects/ | `<kebab-case-项目名>.md` | `3d-printed-toys.md` |
| overview/ | `<类型>-<项目名>.md` | `market-3d-printed-toys.md` |
| analyses/ | `<项目名>-<类型>.md` | `3d-printed-toys-charter.md` |

## 何时新建页面

- 一个 ASIN 在 2 个以上 source 中出现 → 建 entities/products/ 页
- 一个品牌在品牌集中度数据中占份额 ≥ 5% → 建 entities/brands/ 页
- 一个供应商报价合理且有差异化能力 → 建 entities/suppliers/ 页
- 一个页面超过 300 行 → 拆分
- 新的 scout 命令缓存文件 → 建 sources/ 页

## 输出要求

Agent 修改知识库后须：
1. 更新 `index.md`（如有新增/删除/重命名页面）
2. 在 `log.md` 追加一行记录（日期 + 操作摘要）
3. 确保新内容与已有页面不冲突或已标注冲突
4. git commit