query-payslip-default/development/TUTORIAL_SURFACES.md

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

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

单一真相链：

REQUIREMENTS.md §0.1 入口定位表
        ↓
assets/actions.json（placements / label / bind）
        ↓
TUTORIAL.md（用户可读、分入口操作）
README.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 建议章节（标题可微调）

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

---

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

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

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

## 本技能做什么      ← 业务数据流（非 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「用户可见性与教程准确性」。

---

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

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

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

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

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

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

决策三问（与 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 A2-7～A2-11。

---

8. 参考样例

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

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

---

9. 相关文档

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