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

2026-08-31 14:18:42 +08:00
parent b5d120469b
commit 9d33c5ea2c
18 changed files with 630 additions and 85 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,12 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段

+## 1.0.100
+
+- 沉淀用户市场文档契约 `development/TUTORIAL_SURFACES.md`：**说明 Tab ≠ 教程 Tab**；教程按数据管理 ∥ 对话、定时可选三入口结构
+- 重写根 `README.md` / `TUTORIAL.md` 模板骨架；CHECKLIST 增 A2-7～A2-11；`actions.json` 准备类优先 toolbar、skill-detail 不可作教程主路径
+- 新增 `tests/test_tutorial_surfaces.py`（POLICY-TUTORIAL-001）；REQUIREMENTS §0.1 增教程章节列与用户文档对齐要求
+
 ## 1.0.99

 - 沉淀数据管理**表注册门禁**契约：存在 `_jiangchang_tables` 时，宿主仅展示注册且 `visible=1` 的表；孤儿物理表不展示（匠厂宿主 ≥6.8.25）
--- a/DEMO.md
+++ b/DEMO.md
@@ -15,9 +15,13 @@ demo_video_url: ""

 ## 建议观看顺序

-1. 如何发起一次典型任务
-2. 执行过程中会看到什么提示 / 进度
-3. 成功后的结果长什么样
+建议与 `TUTORIAL.md` 三入口结构对齐（有则拍、无则跳过）：
+
+1. 数据管理：准备数据 → 主流程按钮 → 结果表/报告
+2. 对话任务（若有）：一句自然语言触发同一能力
+3. 定时任务（若有）：到点自动跑；若本技能无定时，演示中可说明「不需要定时」
+
+成功后的结果长什么样（表、任务中心、HTML 等）

 ## 没有视频时

--- a/README.md
+++ b/README.md
@@ -1,12 +1,13 @@
 ---
-description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
+description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及边界与结果形态。"
 ---

 > **模板说明（复制后删除本段）**  
-> 本文是技能市场详情与普通用户说明，**不是** Agent 参考索引、CLI 契约或开发文档。  
-> frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约、数据结构、开发规范或 Agent 参考索引。  
-> 正文只回答用户关心的问题，**不要**把 Playwright、DOM、Python、RPA、references、development、schema 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。  
-> **复制后验收章节（标题可微调，建议保留）：**「能帮你做什么」「适合什么场景」「使用前需要准备什么」「你可以这样告诉 Agent」「执行后你会得到什么」「注意事项」「常见问题」。
+> 本文是技能市场 **「说明」** Tab（`readme_md`），**不是**使用教程。  
+> frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约或「如何开始使用」类教程承诺。  
+> **禁止**写入：分步操作（1/2/3）、Agent 示例话术块、「入口一/入口二」专章、逐步排障。这些一律写在根目录 `TUTORIAL.md`。  
+> 正文只回答：是什么、能做什么、适合谁、准备什么、得到什么、注意事项。完整契约见 `development/TUTORIAL_SURFACES.md` §1。  
+> **复制后验收章节（标题可微调）：**「能帮你做什么」「适合什么场景」「使用前需要准备什么」「怎么使用」「执行后你会得到什么」「注意事项」「常见问题」。

 # 【技能名称】

@@ -17,7 +18,7 @@ description: "用用户能理解的方式说明这个技能能做什么、适合

 ## 这个技能能帮你做什么

-用 3 到 6 条业务能力说明技能价值，例如：
+用 3 到 6 条业务能力说明技能价值（**不要**写成操作步骤），例如：

 - 【自动整理/查询/生成/同步/核对/提交】某类业务数据
 - 帮你减少重复操作，降低人工录入或核对成本
@@ -38,42 +39,33 @@ description: "用用户能理解的方式说明这个技能能做什么、适合

 ## 使用前需要准备什么

-说明用户在使用前要准备的东西，例如：
+说明**前置条件**（装什么、要不要账号、要不要外站登录），**不要**写「去哪张表点哪个按钮」：

- **网页自动化类：** 首次运行可由技能自动登记平台账号（浏览器会话由系统隔离管理）。也可在「账号管理」里指定登录标识。登记账号 ≠ 已登录目标站
- **账号在哪里看：** 已登记账号可在「数据管理 / 账号管理」中查看；每个账号使用独立浏览器会话，批量或多账号任务不会共用登录状态
- **是否要登录目标站：** 按本技能说明（有的平台必须登录，有的公开页可不登录）；与「是否有账号记录」不是一回事
+- **网页自动化类：** 可能需要在账号管理中登记平台账号；登记账号 ≠ 已登录目标站（细节见使用教程）
 - 相关业务权限（查询、导出、提交等）已具备
- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息
- 如果涉及验证码或人工确认，请保证能及时在弹出的浏览器窗口中操作
+- 需要处理的文件、时间范围、单号等信息（若适用）
+- 若涉及验证码或人工确认，使用时请能及时在弹出窗口中操作

 ---

-## 你可以这样告诉 Agent
+## 怎么使用

-用自然语言示例展示用户可以怎么发起任务，例如：
+本技能支持哪些宿主入口，用**一两句话**概括即可，例如：

-> “帮我查询今天的【业务对象】，整理成表格。”
->
-> “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。”
->
-> “帮我把【时间范围】内的【业务数据】导出并生成处理报告。”
->
-> “帮我根据这个文件里的内容，逐条完成【业务动作】。”
+- 支持 **数据管理**（点表操作）与 **对话任务**（自然语言）；是否提供定时任务按本技能说明。

-> 注意：示例应是自然语言，不要写命令行命令。
+**逐步操作、示例话术与排障，请查看技能市场「使用教程」Tab。**  
+（完整写法见 `development/TUTORIAL_SURFACES.md`。）

 ---

 ## 执行后你会得到什么

-说明用户会看到什么结果，例如：
+说明用户会看到什么**结果形态**（不要教如何点出来），例如：

 - 任务是否成功完成
- 处理了多少条数据
- 哪些内容成功、哪些失败
- 失败原因和建议处理方式
- 生成的文件、表格、报告或记录
+- 处理了多少条数据；哪些成功、哪些失败
+- 生成的文件、表格、报告或业务表记录

 ---

@@ -90,18 +82,16 @@ description: "用用户能理解的方式说明这个技能能做什么、适合

 ## 常见问题

-### 为什么任务没有查到数据？
+> FAQ 写**概念与边界**；需要「点哪里」的排障写到「使用教程」。

-> 可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。
+### 这个技能适合我吗？

-### 为什么任务执行到一半需要我操作？
+> 若你的场景与上文「适合什么场景」一致，可以安装后按「使用教程」完成第一次操作。

-> 可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。
+### 我不会操作，从哪里开始？

-### 结果文件在哪里查看？
-
-> 请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。
+> 请打开技能市场 **「使用教程」** Tab，按「入口一：数据管理」或「入口二：对话任务」任选一种跟做。

 ### 已经登记的账号在哪里查看？

-> 请到匠厂的「数据管理 / 账号管理」查看账号记录和状态。若任务仍提示账号异常，请把账号编号、任务时间和界面提示原文提供给支持人员；不要发送密码、Cookie 或验证码。
+> 请到匠厂的「数据管理 / 账号管理」查看账号记录和状态。不要发送密码、Cookie 或验证码。
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.99
+version: 1.0.100
 author: 深圳匠厂科技有限公司
 metadata:
  openclaw:
@@ -109,10 +109,11 @@ python {baseDir}/scripts/main.py init-db

 **回答「怎么用 / 能做什么」时的要求：**

-1. 「能做什么 / 场景 / FAQ」以 `README.md` 为主；「第一次怎么用完」以 `TUTORIAL.md` 为主。
+1. 「能做什么 / 场景 / 概念类 FAQ」以 `README.md`（说明 Tab）为主；「点哪里 / 说什么 / 排障」以 `TUTORIAL.md`（教程 Tab）为主。说明 Tab **不应**含分步操作；若 README 仍有旧式步骤，以教程为准并提示开发者按 `development/TUTORIAL_SURFACES.md` 修正。
 2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
 3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
 4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
+5. 用户问「怎么用」时：**优先读 `TUTORIAL.md`**；不要只根据 README 臆造按钮路径。

 **文档读取边界：**

@@ -125,13 +126,13 @@ python {baseDir}/scripts/main.py init-db

 | 文档 | 读者 | 用途 |
 |------|------|------|
-| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`） |
-| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`） |
+| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`）：能力/场景/边界；**非教程** |
+| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`）：分入口操作；结构见 `development/TUTORIAL_SURFACES.md` |
 | 根目录 `DEMO.md` | 普通用户 | 市场 **演示** Tab（`demo_video_url` + `demo_md`） |
 | 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab（按版本小节 → `changelog`） |
 | `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
 | `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
-| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md` |
+| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范；**产品入口**见 `development/PRODUCT_SURFACES.md`；**用户文档契约**见 `development/TUTORIAL_SURFACES.md` |

 ## 目录约定

--- a/TUTORIAL.md
+++ b/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 任务看进度 |
+| 【网页自动化】未登录 / 无权限 | 确认账号在线与目标站登录状态 |
+| 结果不对 | 缩小范围重试，或改用数据管理核对表数据 |

-仍无法解决时，把「你说了什么 + 界面提示原文」发给支持人员，便于排查。
+仍无法解决时，把「你用的入口 + 操作步骤 + 界面提示原文」发给支持人员。
--- a/assets/README.md
+++ b/assets/README.md
@@ -1,12 +1,13 @@
 # assets

 - `actions.json`：Skill Action manifest 最小示例（按入口定位表决定是否保留/扩展；见 `development/PRODUCT_SURFACES.md`）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
+- **业务技能注意：** 若主路径在数据管理，准备/载入/导入类 Action 应挂 `toolbar` + `bind.tables`（用户看得见），**不要**只挂 `skill-detail` 却在教程里写成「技能详情点按钮」。见 `development/TUTORIAL_SURFACES.md` §5、`references/ACTIONS.md`「用户可见性」。
 - `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；含数据管理 iframe 预览布局基线（流体铺满、禁横向滚动）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
 - `examples/`：CLI 成功输出形状示例、以及 `render-html.action.example.json`（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**）。

 `skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）与可选 `bind.inputMapping`；placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。可选 `hoverHint` 为数据管理工具栏悬停（省略不显示，不回退）。`concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。

- 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)
+- 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)；写法契约见 [`development/TUTORIAL_SURFACES.md`](../development/TUTORIAL_SURFACES.md)
 - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)）
 - 开发规范见 [`development/`](../development/)
--- a/development/CHECKLIST.md
+++ b/development/CHECKLIST.md
@@ -77,10 +77,15 @@ checklist_version: 1.0

 - [ ] A2-1 **P0** 市场「说明」能让非开发者理解：做什么、给谁用、开始前准备什么
 - [ ] A2-2 **P0** 「说明/教程」不以开发目录、内部实现细节作为用户主路径
- [ ] A2-3 **P1** 「教程」可按真实顺序跟做（准备 → 步骤 → 失败怎么办）
+- [ ] A2-3 **P1** 「教程」可按真实顺序跟做（准备 → 分入口步骤 → 失败怎么办）；结构见 `TUTORIAL_SURFACES.md`
 - [ ] A2-4 **P1** 「演示」结构完整（有演示信息位；无视频则标明暂无，不假装有）
 - [ ] A2-5 **P0** 「更新日志」能对应到当前交付版本
 - [ ] A2-6 **P0** 平台/Agent 侧说明中，常见用户意图的触发方式与真实能力一致（短操作 vs 长任务不混淆）
+- [ ] A2-7 **P0** 「说明」Tab（`README.md`）**不含**分步操作（1/2/3）、Agent 话术块、「入口一/二」专章；操作指引指向「使用教程」
+- [ ] A2-8 **P0** 「教程」Tab 覆盖 `REQUIREMENTS` §0.1 / `actions.json` 中所有「挂」的入口（数据管理 / 对话；结构见 `TUTORIAL_SURFACES.md`）
+- [ ] A2-9 **P0** 无 `cron` 时教程有「不需要定时」+ 理由；有 `cron` 时教程写清如何配置
+- [ ] A2-10 **P1** 教程主能力对照表与 `actions.json` 的 `label` 一致
+- [ ] A2-11 **P1** 若有数据管理主路径：准备/载入/导入类能力在对应表 **toolbar** 可见；教程**不以** skill-detail 为唯一主路径

 ---

--- a/development/DEVELOPMENT.md
+++ b/development/DEVELOPMENT.md
@@ -352,9 +352,9 @@ git remote -v
 | `DEMO.md` | 演示 | `demo_md` + frontmatter `demo_video_url` |
 | `CHANGELOG.md` | 更新日志 | 匹配当前 tag 版本的 `##` 小节 → `changelog` |

-**`README.md`**：能力与场景说明。含 frontmatter `description`；写能做什么、场景、准备、如何告诉 Agent、结果、注意事项、FAQ。不要写开发教程、目录规范、release、requirements。
+**`README.md`（说明 Tab）**：能力、场景、前置条件、结果形态、注意事项、概念类 FAQ。含 frontmatter `description`（**不要**写「如何开始使用」）。**禁止**分步操作、Agent 话术块、「入口一/二」专章、逐步排障——这些属教程。完整契约见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) §1。

-**`TUTORIAL.md`**：第一次怎么用完的逐步操作。写「开始前 → 步骤 → 卡住怎么办」；不要写 CLI / 目录 / 开发规范。
+**`TUTORIAL.md`（教程 Tab）**：按 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) 写三入口结构（数据管理 ∥ 对话；定时有则教、无则 N/A）+ 主能力对照表 + 常见卡住。步骤必须与 `REQUIREMENTS` §0.1、`actions.json` 及宿主真实 UI 对齐；**禁止**把仅 `skill-detail` 的 Action 写成用户主路径。不要写 CLI / 目录 / 开发规范。

 **`DEMO.md`**：演示视频与补充说明。frontmatter 必须含 `demo_video_url`（无视频时用 `""`）；正文可选。

@@ -837,7 +837,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 - 长任务（async）是否有可见进度，能否取消或等待说明
 - 网页 RPA 是否有头运行；需登录/验证码时是否停下等人，而不是静默失败
 - 数据管理：表名/字段中文、按钮文案是否清楚；结果是否写回用户看得见的地方
- 市场说明 / 教程是否与真实行为一致
+- 市场说明 / 教程是否与真实行为一致；**说明 Tab 不含分步操作**，教程覆盖已挂入口（见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)）

 | 宿主入口（侧栏 / 界面） | 技能侧如何挂上 | 建议验收什么 |
 |-------------------------|----------------|--------------|
--- a/development/POLICY_MATRIX.md
+++ b/development/POLICY_MATRIX.md
@@ -41,6 +41,7 @@
 | POLICY-SKILL-ACTION-002 | 每个 Action 必须显式声明 `executionProfile`，且只能是 `sync` 或 `async` | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema required + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction002`；`tests/test_actions_manifest.py` |
 | POLICY-SKILL-ACTION-003 | toolbar Action 必须声明合法非空 `bind.tables`（snake_case、唯一） | references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema if/then + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction003`；`tests/test_actions_manifest.py` |
 | POLICY-SKILL-ACTION-004 | `placements` 与 `executionProfile` 正交；文档不得把数据管理入口与异步执行方式硬绑定；Schema 须接受 toolbar/row/batch/cron/agent/skill-detail × sync/async 全部组合 | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 6×2 矩阵校验 + 文档禁止短语扫描 | `tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations`；`tests/test_development_policy_guard.py::TestPolicySkillAction004` |
+| POLICY-TUTORIAL-001 | 存在 `development/TUTORIAL_SURFACES.md`；`TUTORIAL.md` 须含数据管理/对话/定时/对照表骨架；`README.md` 禁止「告诉 Agent」专章与入口专章；业务技能教程与 `actions.json` placements 对齐（无 cron 须声明不需要定时） | development/TUTORIAL_SURFACES.md；development/CHECKLIST.md A2-7～A2-11 | hard | 文档存在性 + 章节/反模式扫描 + placements 对齐 | `tests/test_tutorial_surfaces.py`；`tests/test_docs_standards.py::test_tutorial_surfaces_contract_doc_and_checklist` |
 | POLICY-ARCH-CORE-001 | 同一业务能力的 Action、CLI、Agent、cron、数据管理入口复用同一业务内核（文档要求已声明） | development/DEVELOPMENT.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；真实复用靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyArchCore001`；`tests/samples/test_action_core_contract.py.sample` |
 | POLICY-DATA-SYNC-001 | 同步型业务须遵循幂等、事务、完整性与空结果保护（文档已声明） | references/SCHEMA.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；完整语义靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyDataSync001`；`tests/samples/test_sync_contract.py.sample` |

--- a/development/PRODUCT_SURFACES.md
+++ b/development/PRODUCT_SURFACES.md
@@ -164,9 +164,25 @@

 ---

-## 7. 相关文档
+## 7. 用户教程如何投影本文
+
+入口定位表填完后，**必须**落到用户市场文档（见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)）：
+
+| 定位结果 | `TUTORIAL.md` | `README.md` |
+|----------|---------------|-------------|
+| 挂数据管理 | 「入口一」专章 + 表/按钮步骤 | 仅一句「支持数据管理」 |
+| 挂对话 | 「入口二」专章 + 话术 | 仅一句「支持对话」；**禁止**话术块 |
+| 挂定时 | 「入口三」教怎么建 | 可选一句边界 |
+| 不挂定时 | 「入口三」写不需要 + 理由 | 可选一句「不提供定时」 |
+
+准备/载入类 Action：优先 `toolbar` + `bind.tables`，避免教程写「技能详情点按钮」而宿主详情页不渲染。
+
+---
+
+## 8. 相关文档

 - 需求里填定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md)
+- **用户说明 / 教程怎么写：** [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)
 - 交活怎么验：[`CHECKLIST.md`](CHECKLIST.md)
 - 开发步骤中的 Action 挂载：[`DEVELOPMENT.md`](DEVELOPMENT.md) §11.5、§15
 - Agent 侧字段契约：[`../references/ACTIONS.md`](../references/ACTIONS.md)
--- a/development/README.md
+++ b/development/README.md
@@ -10,6 +10,7 @@
 |------|--------|------|
 | 1 | **拿到仓库**：① 项目经理在 [自建 Gitea](https://git.jc2009.com/)（`git.jc2009.com`，非 Gitea 官网）开仓并授权后 `git clone`；或 ② 本地已有 `skill-template` 时用 scaffold / 复制出新目录（遵守 Git 红线） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §1、§4 |
 | 2 | **先读宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；为本技能填入口定位表 | [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) |
+| 2b | **用户市场文档**：说明 Tab ≠ 教程 Tab；教程按三入口写；与 §0.1 / actions 对齐 | [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) |
 | 3 | **先读 AI + RPA 总纲**；界面技能先完成元素拾取/element map，再按浏览器、桌面或手机读分端手册 | [`AI_RPA.md`](AI_RPA.md)、[`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) |
 | 4 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)（含入口定位表），再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) |
 | 5 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 |
@@ -27,6 +28,7 @@
 开始定制 skill 前，建议按以下顺序阅读：

 1. [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) — **宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；入口定位表
+1b. [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md) — **用户说明 / 教程契约**：README≠TUTORIAL；三入口结构；skill-detail 不可作主路径
 2. [`AI_RPA.md`](AI_RPA.md) — **AI Agent + RPA 总纲**：职责边界、合规红线、风控、操作节奏与完整闭环
 3. [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) — **浏览器账号标准**：一账号一 Profile、租约、多账号、数据查看、验收与排障
 4. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展）
--- a/development/REQUIREMENTS.md
+++ b/development/REQUIREMENTS.md
@@ -33,19 +33,26 @@

 ## 0.1 宿主入口定位（必填）

-先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。用户文档如何写见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)。

 对每个主能力填一行（可增行；「不挂」必须写理由）：

-| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
-|---------------------------|------|----------|------|--------------------|
-| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | |
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|----------|--------------------|
+| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | 入口一 / 入口二 / 入口三 / N/A | |

 说明：

 - 数据管理列可写组合（如 `toolbar + row`）
 - 「仅展示表」= 用户要看过程/结果，但不在表上触发该能力
 - 定位为「挂」的入口须在 `assets/actions.json`（及必要表元数据）中落实，并与对话路径共用同一 domain service
+- **教程章节**：该能力在 `TUTORIAL.md` 中落在哪一节；整技能无定时时，入口三仍须写「不需要 + 理由」
+
+### 0.1.1 用户市场文档（与入口表一致）
+
+- `README.md`（说明 Tab）：只写能力 / 场景 / 边界；**禁止**分步操作与 Agent 话术（见 `TUTORIAL_SURFACES.md` §1）
+- `TUTORIAL.md`（教程 Tab）：覆盖 §0.1 中所有「挂」的入口；准备/载入类优先数据管理 toolbar，**不要**把 skill-detail 当主路径
+- 定位为「不挂」定时：教程须有 N/A 声明，与本表理由一致

 ## 0.2 AI + RPA 协作与授权边界（涉及外部系统时必填）

--- a/development/TUTORIAL_SURFACES.md
+++ b/development/TUTORIAL_SURFACES.md
@@ -0,0 +1,206 @@
+# 用户市场文档契约（说明 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
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -644,6 +644,18 @@ HINT: <next step>
 | `agent` | Agent 可直接调用（`run_skill_action`） |
 | `cron` | 定时任务「技能直调」 |

+### 用户可见性与教程准确性
+
+`placements` 决定 Action **可以**出现在哪；教程只能写用户在宿主里**实际能点到**的路径。完整用户文档契约见 [`../development/TUTORIAL_SURFACES.md`](../development/TUTORIAL_SURFACES.md)。
+
+| 规则 | 说明 |
+|------|------|
+| **skill-detail ≠ 一定可见** | 声明 `skill-detail` 不保证详情页渲染出按钮；当前宿主详情常只有说明/教程/演示/更新日志四 Tab。**禁止**把「技能详情 → 点某某」写成用户主路径或教程唯一入口 |
+| **准备 / 载入 / 导入 / 重置** | 若技能以数据管理为主路径，此类能力优先 `toolbar` + 非空 `bind.tables`（空表也可点的准备动作尤其如此）；可同时挂 `agent`；`skill-detail` 仅作可选兼容 |
+| **写入后刷新** | 会写入业务表的 Action 建议 `steps: [{ "when": "afterSuccess", "do": "refreshCatalog" }]`，避免用户点完表不更新 |
+| **教程按钮名** | 必须等于本文件 `label`；对照表与数据管理顶栏/行内文案一致 |
+| **README vs 教程** | 说明 Tab 不写分步；操作步骤只写 `TUTORIAL.md` |
+
 ### 行级入口 `row`（宿主呈现契约）

 - **技能决定有什么**：`placements` 含 `"row"`（且通过 `bind.tables` / policy 等过滤）的 Action，构成该表行的技能菜单项集合；配什么就出现什么。
@@ -689,7 +701,7 @@ HINT: <next step>
 | 数据同步（外源 → 本地库） | sync 或 async | toolbar + cron + agent + skill-detail（按需） | 可选 |
 | 单行重试 / 行内处理 | sync 或 async | row（可加 agent） | 可选 |
 | 批量处理勾选行 | sync 或 async | batch（可加 toolbar/cron） | 可选 |
-| 导入 / 重置 | sync 或 async | skill-detail, agent | 可选 |
+| 导入 / 重置 | sync 或 async | **优先** toolbar（须 `bind.tables`）+ agent；skill-detail 仅可选 | 可选 |
 | 单条副作用 RPA | async（建议） | agent, skill-detail | **建议** |
 | 批量顺序 pick RPA | async（建议） | toolbar, cron, agent | **建议** |
 ## 同步数据 vs 导出当前表 vs 特殊业务报告 vs HTML 页面
--- a/scripts/util/constants.py
+++ b/scripts/util/constants.py
@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""

 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.98"
+SKILL_VERSION = "1.0.100"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"
--- a/tests/test_development_policy_guard.py
+++ b/tests/test_development_policy_guard.py
@@ -57,6 +57,7 @@ POLICY_IDS = (
    "POLICY-SKILL-ACTION-002",
    "POLICY-SKILL-ACTION-003",
    "POLICY-SKILL-ACTION-004",
+    "POLICY-TUTORIAL-001",
    "POLICY-ARCH-CORE-001",
    "POLICY-DATA-SYNC-001",
 )
--- a/tests/test_docs_standards.py
+++ b/tests/test_docs_standards.py
@@ -181,6 +181,17 @@ class TestDocsStandards(unittest.TestCase):
        self.assertIn("CHANGELOG.md", text)
        self.assertIn("demo_video_url", text)
        self.assertIn("tutorial_md", text)
+        self.assertIn("TUTORIAL_SURFACES.md", text)
+
+    def test_tutorial_surfaces_contract_doc_and_checklist(self) -> None:
+        surfaces = self._read("development/TUTORIAL_SURFACES.md")
+        self.assertIn("说明", surfaces)
+        self.assertIn("教程", surfaces)
+        self.assertIn("skill-detail", surfaces)
+        checklist = self._read("development/CHECKLIST.md")
+        self.assertIn("A2-7", checklist)
+        self.assertIn("A2-8", checklist)
+        self.assertIn("TUTORIAL_SURFACES.md", checklist)

    def test_naming_md_exists_and_covers_standards(self) -> None:
        text = self._read("development/NAMING.md")
--- a/tests/test_tutorial_surfaces.py
+++ b/tests/test_tutorial_surfaces.py
@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+"""用户市场文档契约：README≠教程、TUTORIAL 三入口结构、与 actions.json 对齐。
+
+契约全文：development/TUTORIAL_SURFACES.md
+- 模板占位 slug（your-skill-slug）：只检查骨架与契约文档存在
+- 业务技能：按 actions.json placements 硬校验教程章节与 README 反模式
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import unittest
+
+from _support import get_skill_root
+from util.constants import SKILL_SLUG
+
+TEMPLATE_PLACEHOLDER_SLUG = "your-skill-slug"
+
+_SECTION_DATA_MGMT = re.compile(r"(?m)^##\s*.*数据管理")
+_SECTION_DIALOG = re.compile(r"(?m)^##\s*.*(对话任务|对话)")
+_SECTION_CRON = re.compile(r"(?m)^##\s*.*定时任务")
+_SECTION_COMPARE = re.compile(r"(?m)^##\s*.*(对照表|主能力)")
+_SECTION_STUCK = re.compile(r"(?m)^##\s*.*(常见卡住|卡住怎么办)")
+_SECTION_WHAT = re.compile(r"(?m)^##\s*.*(本技能做什么|做什么)")
+_NO_CRON_HINT = re.compile(r"不需要定时|未提供定时|不提供定时|不适用.*定时|定时.*不适用")
+
+# README 反模式：分步操作 / Agent 话术专章（说明 Tab 禁止）
+_README_HOWTO_AGENT = re.compile(r"(?m)^##\s*.*告诉\s*Agent")
+_README_ENTRY_CHAPTER = re.compile(r"(?m)^##\s*入口[一二三]")
+_README_NUMBERED_DM_PATH = re.compile(
+    r"(?m)^\d+[\.、]\s*.*(数据管理|选品任务|表顶).{0,40}(点击|点\s*「)"
+)
+
+
+def _read(rel: str) -> str:
+    path = os.path.join(get_skill_root(), rel)
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def _load_actions() -> list[dict]:
+    path = os.path.join(get_skill_root(), "assets", "actions.json")
+    if not os.path.isfile(path):
+        return []
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return list(data.get("actions") or [])
+
+
+def _placement_sets(actions: list[dict]) -> tuple[bool, bool, bool]:
+    has_dm = False
+    has_agent = False
+    has_cron = False
+    dm_tokens = frozenset({"toolbar", "row", "batch"})
+    for action in actions:
+        placements = set(action.get("placements") or [])
+        if placements & dm_tokens:
+            has_dm = True
+        if "agent" in placements and str(action.get("id") or "") not in (
+            "health",
+            "version",
+            "config-path",
+        ):
+            has_agent = True
+        if "cron" in placements:
+            has_cron = True
+    return has_dm, has_agent, has_cron
+
+
+class TestTutorialSurfacesContract(unittest.TestCase):
+    def test_tutorial_surfaces_doc_exists(self) -> None:
+        path = os.path.join(get_skill_root(), "development", "TUTORIAL_SURFACES.md")
+        self.assertTrue(
+            os.path.isfile(path),
+            msg="development/TUTORIAL_SURFACES.md must exist (user market doc contract)",
+        )
+        text = _read("development/TUTORIAL_SURFACES.md")
+        for marker in (
+            "README.md",
+            "TUTORIAL.md",
+            "数据管理",
+            "对话",
+            "定时",
+            "skill-detail",
+            "对照表",
+        ):
+            self.assertIn(marker, text, msg=f"TUTORIAL_SURFACES.md missing {marker!r}")
+
+    def test_development_md_points_to_tutorial_surfaces(self) -> None:
+        text = _read("development/DEVELOPMENT.md")
+        self.assertIn(
+            "TUTORIAL_SURFACES.md",
+            text,
+            msg="DEVELOPMENT.md must reference TUTORIAL_SURFACES.md for market docs",
+        )
+
+    def test_template_or_business_tutorial_has_required_skeleton(self) -> None:
+        tutorial = _read("TUTORIAL.md")
+        self.assertRegex(
+            tutorial,
+            _SECTION_WHAT,
+            msg="TUTORIAL.md must have a '本技能做什么' (or equivalent) section",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_DATA_MGMT,
+            msg="TUTORIAL.md must have a 数据管理 section (or 不适用 placeholder)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_DIALOG,
+            msg="TUTORIAL.md must have a 对话 section (or 不适用 placeholder)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_CRON,
+            msg="TUTORIAL.md must have a 定时任务 section (teach or N/A)",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_COMPARE,
+            msg="TUTORIAL.md must have a 主能力对照表 section",
+        )
+        self.assertRegex(
+            tutorial,
+            _SECTION_STUCK,
+            msg="TUTORIAL.md must have a 常见卡住 section",
+        )
+        # 禁止旧「对话单线」作为唯一主结构标题
+        self.assertNotRegex(
+            tutorial,
+            r"(?m)^##\s*第一步：打开技能并说清目标\s*$",
+            msg="TUTORIAL.md must not use legacy dialogue-only first step as sole structure",
+        )
+
+    def test_readme_has_no_legacy_agent_howto_chapter(self) -> None:
+        readme = _read("README.md")
+        self.assertIsNone(
+            _README_HOWTO_AGENT.search(readme),
+            msg="README.md must not have '告诉 Agent' howto chapter (belongs in TUTORIAL)",
+        )
+        self.assertIsNone(
+            _README_ENTRY_CHAPTER.search(readme),
+            msg="README.md must not have 入口一/二/三 chapters (belongs in TUTORIAL)",
+        )
+
+    def test_business_skill_tutorial_aligns_with_actions(self) -> None:
+        if SKILL_SLUG == TEMPLATE_PLACEHOLDER_SLUG:
+            self.skipTest("template placeholder slug: skip actions alignment hard checks")
+
+        actions = _load_actions()
+        has_dm, has_agent, has_cron = _placement_sets(actions)
+        tutorial = _read("TUTORIAL.md")
+        readme = _read("README.md")
+
+        if has_dm:
+            self.assertRegex(
+                tutorial,
+                _SECTION_DATA_MGMT,
+                msg="business skill with data-management placements must document 数据管理 in TUTORIAL",
+            )
+            # 准备类若挂了 toolbar，教程不应把 skill-detail 当唯一主路径
+            self.assertNotRegex(
+                tutorial,
+                r"(?m)^\d+[\.、]\s*.*技能详情.{0,30}点击",
+                msg="TUTORIAL must not use 技能详情点击 as primary numbered path when DM exists",
+            )
+
+        if has_agent:
+            self.assertRegex(
+                tutorial,
+                _SECTION_DIALOG,
+                msg="business skill with agent placements must document 对话 in TUTORIAL",
+            )
+
+        if has_cron:
+            self.assertRegex(
+                tutorial,
+                _SECTION_CRON,
+                msg="with cron placements, TUTORIAL must have 定时任务 section",
+            )
+        else:
+            self.assertRegex(
+                tutorial,
+                _NO_CRON_HINT,
+                msg="without cron placements, TUTORIAL must declare 不需要/未提供定时",
+            )
+
+        # README 不应出现「数据管理 → … → 点击」式编号步骤
+        self.assertIsNone(
+            _README_NUMBERED_DM_PATH.search(readme),
+            msg="README.md must not contain numbered data-management click steps",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()