207 lines
8.1 KiB
Markdown
207 lines
8.1 KiB
Markdown
# 用户市场文档契约（说明 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`。
|
||
|
||
---
|
||
|
||
## 1. README.md（说明 Tab）
|
||
|
||
### 1.1 必须回答
|
||
|
||
| 问题 | 写法 |
|
||
|------|------|
|
||
| 这是什么 | 标题 + 一两句价值 |
|
||
| 能做什么 | 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
|