client-huashang/query-payslip-default
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
query-payslip-default/development/TUTORIAL_SURFACES.md
skill-dev 3db196e49d feat: 工资查询助手首版 v1.0.105 
基于 skill-template 脚手架开发，包含：
- payroll_config（费率配置，可编辑）+ payslip_snapshots（解析历史，只读）2 张业务表
- 全国默认 + 北上广 4 套费率（社保/公积金/个税起征点/7 级税率表）
- 5 个业务 Action：calculate-payslip-simple / calculate-payslip-full / explain-term / view-config / edit-config
- 个税累计预扣法计算，支持多月历史累加
- 20 个薪资名词库（社保/公积金/个税/全勤/加班费等）
- 完整市场文档（README/TUTORIAL/DEMO/CHANGELOG）
- 296 测试全部通过
2026-09-07 17:02:05 +08:00

223 lines
8.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 用户市场文档契约（说明 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
Reference in New Issue View Git Blame Copy Permalink