docs: sediment TUTORIAL_SURFACES contract for README vs tutorial and three entry surfaces

TUTORIAL.md

@@ -1,12 +1,34 @@
 > **模板说明（复制后删除本段）**  
 > 本文对应技能市场 **「使用教程」** Tab（发布时同步为 `tutorial_md`）。  
 > 面向普通用户写**可跟着做的步骤**，不要写 CLI、目录结构、release、开发规范。  
-> 与根 `README.md`（技能说明）分工：README 讲「是什么 / 能做什么」；本文讲「第一次怎么用完」。  
-> **复制后验收章节（标题可微调）：**「开始前」「第一步…」「第二步…」「常见卡住怎么办」。
+> 与根 `README.md`（技能说明）分工：README 讲「是什么 / 能做什么 / 边界」；本文讲「从哪个入口怎么用完」。  
+> **完整契约：** `development/TUTORIAL_SURFACES.md`（三入口结构、说明≠教程、skill-detail 不可作主路径）。  
+> **复制后验收章节（标题可微调，语义不可缺）：**「本技能做什么」「开始前」「入口一：数据管理」「入口二：对话任务」「入口三：定时任务」「主能力对照表」「常见卡住怎么办」。  
+> 若本技能 §0.1 未挂数据管理 / 对话 / 定时，对应入口节改为「不适用」并写一句理由（与 REQUIREMENTS 一致）。
 
-# 【技能名称】使用教程
+# 【技能名称】· 使用教程
 
-用最短路径带用户完成一次成功使用。步骤要具体，可用「打开匠厂 → …」这类操作语言。
+本技能有两种**平行**的使用方式（按本技能入口定位填写；未挂的入口删掉或写不适用）：
+
+- **数据管理**：在左侧表上点工具栏 / 行内按钮  
+- **对话任务**：用自然语言让 Agent 完成同一能力  
+
+两种方式触发同一套业务能力，结果一致，选你习惯的即可。  
+定时任务是否提供：见下方「入口三」（没有则写「本技能不需要定时」+ 理由）。
+
+---
+
+## 本技能做什么
+
+用业务语言画清闭环（**不要**写库表英文名或命令行），例如：
+
+```text
+【输入/准备】 → 【核心动作】 → 【结果可见处】 → 【可选报告/导出】
+```
+
+- **输入**：……  
+- **输出**：……  
+- **说明**：边界（教学/正式、是否接外站等）  
 
 ---
 
@@ -14,43 +36,105 @@
 
 确认：
 
-1. 已安装并登录匠厂客户端
-2. 已在技能市场安装本技能（或更新到最新版）
-3. 【网页自动化类技能】首次运行一般会自动登记本平台账号；也可在「账号管理」中指定登录标识。浏览器会话由系统隔离管理——**不要**用本机日常浏览器用户目录去跑真实站
-4. 【按平台】若本技能说明「需要先登录目标站」，请在弹出的有头浏览器中按提示登录或扫码；「登记账号」不等于「已登录目标站」。若说明「可不登录也能用」，仍须有可用的账号会话目录
-5. 【网页自动化类技能】已登记账号可在「数据管理 / 账号管理」查看；每个账号都有独立浏览器会话
-6. 【如需】需要的文件 / 时间范围 / 单号等已准备好
+1. 已安装并登录匠厂客户端  
+2. 已在技能市场安装本技能（建议更新到最新版）  
+3. 【网页自动化类】账号登记 / 目标站登录要求（按本技能；登记 ≠ 已登录）  
+4. 【如需】文件 / 时间范围 / 单号等已准备好  
+5. 【如需】首次须先完成「载入样例 / 导入 / 同步」等准备动作（见入口一或入口二）  
 
 ---
 
-## 第一步：打开技能并说清目标
+## 入口一：数据管理
 
-在匠厂里新建任务或打开对话，用自然语言说明要做什么，例如：
+> 若本技能无业务表、无 toolbar/row/batch：整节改为「不适用」+ 理由。
 
-> “帮我【完成某件业务事】，范围是【时间 / 对象 / 条件】。”
+适合：对照数据、喜欢点界面、机房/运营用户。
 
-建议一次只交代一件事；范围说清楚，减少来回确认。
+### 左侧各表是干什么的
+
+| 表名（中文） | 作用 |
+|--------------|------|
+| 【表 A】 | …… |
+| 【表 B】 | …… |
+
+### 首次准备（若需要）
+
+1. 进入 **数据管理** → **【主表】**  
+2. 点击表顶 **「【准备类按钮 label】」**（若为空表可点，写明是否须选中行）  
+3. 成功后应看到：……  
+
+> **注意：** 准备/载入/导入类按钮须挂在数据管理 **toolbar**（用户看得见）。不要把「技能详情页点按钮」写成主路径——详情页常只显示四 Tab，不一定渲染 Action 按钮。
+
+### 主流程
+
+1. 进入 **【主表】**  
+2. 【是否选中行】  
+3. 点击 **「【主能力 label】」**  
+4. 到 **【结果表 / 任务中心 / 报告】** 核对结果  
+
+### 行级 / 批量（若有）
+
+| 你想做什么 | 操作 |
+|------------|------|
+| …… | **【表】** 行内 → **「【label】」** |
+| …… | 勾选多行 → **「【label】」** |
 
 ---
 
-## 第二步：按提示补充信息
+## 入口二：对话任务
 
-如果 Agent 问你缺什么（账号、文件、筛选条件），按提示补充即可。
+> 若本技能不挂 `agent`：整节改为「不适用」+ 理由。
 
-- 有文件时：按界面提示选择或拖入
-- 有账号时：确认已在对应平台登录，且具备操作权限
+适合：临时提问、要解释、不想切换表。
+
+### 什么时候用对话
+
+- ……  
+- 与入口一效果相同；习惯看表时优先用数据管理  
+
+### 示例话术
+
+| 你想做什么 | 可以这样说 |
+|------------|------------|
+| …… | 「……」 |
+| …… | 「……」 |
+
+### Agent 可能追问什么
+
+- 缺参数时：……  
+- 失败时：可改用数据管理点按钮  
 
 ---
 
-## 第三步：等待结果并核对
+## 入口三：定时任务
 
-任务结束后，请核对：
+> **有 `cron`：** 写如何新建定时、选哪个 Action、默认参数、预期结果。  
+> **无 `cron`：** 用下面「不需要」模板，删掉「如何配置」小节。
 
-- 是否成功完成
-- 处理了多少条 / 哪些失败
-- 生成的文件、表格或记录是否在预期位置
+### 本技能不需要定时时（示例文案，按需保留/改写）
 
-若失败，先看失败原因说明，再按下一节排查。
+本技能**未提供定时任务入口**，原因：【一次性 / 须人指定对象 / 须当场确认 / ……】。  
+请使用 **数据管理** 或 **对话任务**。
+
+### 本技能需要定时时（示例结构）
+
+1. 打开侧栏 **定时任务** → 新建  
+2. 选择本技能 → Action **「【label】」**  
+3. 填写参数 → 保存；可「立即运行」验证  
+4. 到点后在【结果表 / 任务中心】查看  
+
+---
+
+## 主能力对照表
+
+同一能力，两种主入口（按本技能实际填写；只挂一端的注明）：
+
+| 想做什么 | 数据管理 | 对话任务 |
+|----------|----------|----------|
+| …… | **【表】** → **「【label】」** | 「……」 |
+| …… | …… | …… |
+
+按钮名必须与 `assets/actions.json` 的 `label` 一致。
 
 ---
 
@@ -58,10 +142,10 @@
 
 | 现象 | 你可以先试 |
 |------|------------|
-| 提示未登录 / 无权限 | 确认匠厂已登录；业务账号是否在线、权限是否足够 |
-| 提示账号不存在 / 被占用 | 到「数据管理 / 账号管理」确认账号记录和状态，稍后再试；不要重复创建账号 |
-| 提示缺少必要信息 | 把时间范围、单号、文件等说完整后再试一次 |
-| 一直没有结果 | 到任务中心查看进度或失败原因；必要时重新发起 |
-| 结果不对 | 用更明确的条件再说一次，或缩小范围重试 |
+| 主表是空的 | 先做「首次准备」或对话载入/导入 |
+| 按钮点不了 | 是否须先选中行；是否装错版本 |
+| 一直没有结果 | 看任务中心 / 运行日志；async 任务看进度 |
+| 【网页自动化】未登录 / 无权限 | 确认账号在线与目标站登录状态 |
+| 结果不对 | 缩小范围重试，或改用数据管理核对表数据 |
 
-仍无法解决时，把「你说了什么 + 界面提示原文」发给支持人员，便于排查。
+仍无法解决时，把「你用的入口 + 操作步骤 + 界面提示原文」发给支持人员。