# 用户市场文档契约（说明 Tab / 教程 Tab）

本文给**技能开发者**与 **AI 编程助手**读：规定根目录 `README.md`（技能说明）与 `TUTORIAL.md`（使用教程）**写什么、不写什么**，以及如何与宿主三入口、入口定位表、`actions.json` 对齐。

**单一真相链：**

```text
REQUIREMENTS.md §0.1 入口定位表
        ↓
assets/actions.json（placements / label / bind）
        ↓
TUTORIAL.md（用户可读、分入口操作）
README.md（能力与边界；不写步骤）
```

产品入口「挂什么」见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。本文只管**用户市场文档怎么投影**。

---

## 0. 与四 Tab 的关系

| 文件 | 市场 Tab | 本文角色 |
|------|----------|----------|
| `README.md` | **说明** | §1：是什么 / 给谁 / 边界 |
| `TUTORIAL.md` | **教程** | §2～§6：怎么用（分入口） |
| `DEMO.md` | 演示 | 观看顺序可对齐三入口，不另造标准 |
| `CHANGELOG.md` | 更新日志 | 与文档契约无关 |

**铁律：** 说明就是说明，教程就是教程。**禁止**在 README 里写分步操作、Agent 话术块、排障「点哪里」；这些一律进 `TUTORIAL.md`。

### 0.1 标题层级（说明 / 教程共用）

宿主详情页**已经**展示技能名；「说明 / 使用教程」Tab（及数据管理右侧教程抽屉）**已经**标明文档类型。因此：

| 层级 | 用途 |
|------|------|
| `#` | **正文不要用**（会与页头/Tab 标题重复抢视觉） |
| `##` | 主分节（能帮你做什么、入口一：数据管理…） |
| `###` | 分节内步骤 |

**禁止：**

- `README.md` 文首 `# 【技能名】` / `# 审计疑点辅助` 这类与页头重复的 H1  
- `TUTORIAL.md` 文首 `# 【技能名】· 使用教程` 这类与 Tab/抽屉标题重复的 H1  

去掉重复 H1 后，**不要**把原来的 `##` 全部升成 `#`。

---

## 1. README.md（说明 Tab）

### 1.1 必须回答

| 问题 | 写法 |
|------|------|
| 这是什么 | 开篇一两句价值（**普通段落或引用**，不要再写技能名 H1） |
| 能做什么 | 3～6 条能力 bullet（**无步骤编号**） |
| 适合谁 / 场景 | 业务语言 |
| 使用前准备 | 安装、账号、权限等**前置条件**；不写「去哪张表点哪」 |
| 执行后得到什么 | 结果形态（表、报告、文件），**不教怎么生成** |
| 注意事项 | 边界、风险、人工复核 |
| 怎么使用（可选，短） | **一两句**：支持哪些入口 + **「步骤见使用教程 Tab」** |

### 1.2 禁止写入 README

- `1.` `2.` `3.` 操作步骤（如「选品任务 → 点某某按钮」）
- 「你可以这样告诉 Agent」整节或大块 `>` 示例话术
- 「入口一 / 入口二」专章结构
- 逐步排障（「先点 A 再点 B」）
- frontmatter `description` 不要写「以及如何开始使用」类教程承诺

### 1.3 FAQ 边界

- README FAQ：**概念类**（和真实系统区别、从哪开始学、是否支持定时）→ 可指向「使用教程」Tab
- **操作类**排障 → 只写在 `TUTORIAL.md`「常见卡住怎么办」

### 1.4 建议章节（标题可微调）

```text
（开篇一两句价值；不要写 # 技能名）
## 这个技能能帮你做什么
## 适合什么场景
## 使用前需要准备什么
## 怎么使用          ← 仅短摘要 + 指向教程
## 执行后你会得到什么
## 注意事项
## 常见问题          ← 概念类
```

---

## 2. TUTORIAL.md（教程 Tab）必选结构

复制业务技能后，**验收章节（标题可微调，语义不可缺）**：

```text
（开篇：数据管理与对话平行；定时有/无一句。不要写 # 技能名 · 使用教程）

## 本技能做什么      ← 业务数据流（非 CLI/SQL）
## 开始前
## 入口一：数据管理  ← §0.1 有 toolbar/row/batch/replaces 则必填
## 入口二：对话任务  ← §0.1 有 agent 则必填
## 入口三：定时任务  ← 有 cron：怎么用；无 cron：不需要 + 理由
## 主能力对照表      ← 双挂能力必填
## 常见卡住怎么办
```

### 2.1 与入口定位表的关系

| §0.1 / actions | TUTORIAL 要求 |
|----------------|---------------|
| 任一能力挂数据管理（toolbar/row/batch/replaces） | **必须**有「入口一：数据管理」专章 |
| 任一能力挂 `agent` | **必须**有「入口二：对话任务」专章（**禁止**用「或者你也可以说…」替代专章） |
| 任一能力挂 `cron` | **必须**有「入口三」且写清如何建定时、选哪个 Action |
| **无** `cron` | **必须**写「本技能不需要定时」+ 一句理由（与 §0.1 一致） |
| 某能力只挂一端 | 对照表注明「仅数据管理」或「仅对话」 |

### 2.2 平行关系（数据管理 ∥ 对话）

- 两者是**平行主入口**，不是「对话主、点表辅」或反过来
- 禁止全文只有「第一步：打开对话说清目标」且无数据管理专章
- 允许用户只用其中一种；教程须写清「两种效果一致，选你习惯的」

---

## 3. 入口一：数据管理（怎么写）

适合写：

1. 左侧有哪些业务表、各干什么（业务语言）
2. 首次准备（载入/导入/新建）——**按钮必须出现在用户能看到的地方**（见 §5）
3. 主流程：进哪张表 → 是否要选中行 → 点哪个 `label` → 去哪看结果
4. 行级 / 批量操作（若有 `row` / `batch`）

按钮中文名 = `assets/actions.json` 的 `label`，不要另造别名。

---

## 4. 入口二：对话任务（怎么写）

适合写：

1. 什么时候用对话（与数据管理互补）
2. 示例话术表（与主能力一一对应）
3. Agent 可能追问什么、用户怎么答

**不要**把对话写成唯一路径；也不要把话术塞进 README。

---

## 5. 准确性铁律（用户看得见才写）

教程步骤必须对应 **宿主真实 UI**，不是只对应 manifest 声明。

| 规则 | 说明 |
|------|------|
| **placements 对齐** | 教程写的入口 ∈ `actions.json` 已挂 placement |
| **skill-detail 不可作主路径** | 声明了 `skill-detail` **不等于**详情页一定渲染出按钮；当前宿主常只显示四 Tab。**禁止**把「技能详情 → 点某某」写成用户主路径 |
| **准备/载入/导入类** | 优先挂 **数据管理 `toolbar`** + `bind.tables`（空表也可点的能力尤其如此）；可保留 `agent`；`skill-detail` 仅作可选兼容 |
| **写入后刷新** | 建议 `steps: [{ "when": "afterSuccess", "do": "refreshCatalog" }]`，避免用户点完表不刷新 |
| **对照表** | 「想做什么 \| 数据管理 \| 对话」覆盖双挂主能力；`label` 与界面一致 |

字段细节见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「用户可见性与教程准确性」。

---

## 6. 入口三：定时任务（可选）

### 6.1 何时挂 `cron`（教程教「怎么用定时」）

- 参数相对固定、按节奏重复（同步、巡检、消费队列）
- 无人值守仍安全、可幂等或可失败重试
- 与数据管理是「白天点选 + 夜里自动啃」组合

教程写：侧栏定时任务 → 新建 → 选本技能 → 选 Action → 填参 → 保存/立即运行。

### 6.2 何时不挂（教程写「不需要」）

- 一次性 / 课堂演示，对象当场指定
- 强不可逆、须当场确认
- 每次对象不同、须人指定链接或范围
- 主路径依赖验证码 / 人工介入

决策三问（与 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) §2.3 一致）：

1. 明天人不盯着、同样参数再跑一遍，业务上合理吗？  
2. 失败后自动重跑可接受吗？  
3. 有没有须人当场确认或动态指定的输入？  

①是 且 ②可接受 且 ③否 → 可挂 cron；否则不挂，§0.1 写理由，教程声明 N/A。

---

## 7. 复制后自检（发布前）

- [ ] README 无分步操作、无 Agent 话术块
- [ ] TUTORIAL 有三入口结构（定时有或 N/A）
- [ ] 对照表与 `actions.json` `label` 一致
- [ ] 准备类按钮在数据管理表顶可见（若技能有数据管理主路径）
- [ ] 教程未把 skill-detail 当唯一载入/主流程入口
- [ ] §0.1「挂」的入口在 TUTORIAL 有专章；「不挂」有理由且教程一致

交活清单见 [`CHECKLIST.md`](CHECKLIST.md) A2-7～A2-11。

---

## 8. 参考样例

已验收参考（业务技能，非模板正文）：`client-gdcm/review-sku-selection-default`  
（说明 Tab 瘦身 + 教程三入口 + 「载入课堂样例」挂 `selection_cases` toolbar。）

复制模板后**不要**照搬选品表名与样例编码；只复用**章节结构与职责划分**。

---

## 9. 相关文档

- 宿主入口何时挂：[`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)
- 入口定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md) §0.1
- Action placements / 可见性：[`../references/ACTIONS.md`](../references/ACTIONS.md)
- 市场四 Tab 同步：[`DEVELOPMENT.md`](DEVELOPMENT.md) §6 附近「用户市场四 Tab」
- 交活验收：[`CHECKLIST.md`](CHECKLIST.md) §2