feat(docs): add market four-tab materials (tutorial/demo/changelog) for v1.0.46

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+本文件对应技能市场 **「更新日志」** Tab。  
+发布 CI 会按当前 tag 版本（如 `v1.0.46` → `1.0.46`）提取匹配的 `##` 小节，写入该版本的 `changelog`。
+
+约定：
+
+- 每个正式版本一节，标题形如 `## 1.0.46` 或 `## [1.0.46] - YYYY-MM-DD`
+- 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
+- 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
+
+## 1.0.46
+
+- 模板默认增加市场材料：`TUTORIAL.md`（使用教程）、`DEMO.md`（演示）、`CHANGELOG.md`（更新日志），与根 `README.md`（技能说明）组成四 Tab 内容源
+- 发布 CI 同步 `tutorial_md` / `demo_md` / `demo_video_url` / 版本 `changelog`
+
+## 1.0.45
+
+- 沉淀通用 Agent 路由与 how-to 文档标准（见仓库提交说明）

DEMO.md

@@ -0,0 +1,24 @@
+---
+demo_video_url: ""
+---
+
+> **模板说明（复制后删除本段）**  
+> 本文对应技能市场 **「演示」** Tab。  
+> - frontmatter 的 `demo_video_url`：演示视频地址（发布时同步为 `demo_video_url`）；没有视频时保持空字符串 `""`。  
+> - 正文（发布时同步为 `demo_md`）：可选，写视频看点、时间轴或无视频时的图文演示说明。  
+> **不要**把演示链接写进 `SKILL.md`（市场材料 ≠ Agent 契约）。  
+> 复制为业务技能后：填入真实可访问的视频 URL，并删掉本提示段。
+
+# 演示说明
+
+用一两句话说明这段演示帮助用户看懂什么（例如：从发起任务到看到结果的完整过程）。
+
+## 建议观看顺序
+
+1. 如何发起一次典型任务
+2. 执行过程中会看到什么提示 / 进度
+3. 成功后的结果长什么样
+
+## 没有视频时
+
+可在此用简短图文描述关键界面与结果样例；有视频后把 `demo_video_url` 填上即可，正文可保留为补充说明。

README.md

@@ -5,7 +5,8 @@ description: "用用户能理解的方式说明这个技能能做什么、适合
 > **模板说明（复制后删除本段）**  
 > 本文是技能市场详情与普通用户说明，**不是** Agent 参考索引、CLI 契约或开发文档。  
 > frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约、数据结构、开发规范或 Agent 参考索引。  
-> 正文只回答用户关心的问题，**不要**把 Playwright、DOM、Python、RPA、references、development、schema 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。
+> 正文只回答用户关心的问题，**不要**把 Playwright、DOM、Python、RPA、references、development、schema 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。  
+> **复制后验收章节（标题可微调，建议保留）：**「能帮你做什么」「适合什么场景」「使用前需要准备什么」「你可以这样告诉 Agent」「执行后你会得到什么」「注意事项」「常见问题」。
 
 # 【技能名称】
 

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.42
+version: 1.0.46
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -25,27 +25,68 @@ allowed-tools:
 ### 架构铁律（先读）
 
 - **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
-- **`placements`**：只决定 Action 出现在哪里。
+- **`placements`**：只决定 Action **出现在哪里**（toolbar / cron / agent / skill-detail）。
 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
-- **`executionProfile`**：只决定 sync 等待还是 async Job；**必须**显式声明 `sync` 或 `async`；与 placements **正交**（任意合法组合均可）。
-- **`async`**：宿主建 Job，立即返回 `jobId`，进度见**任务中心** / Skill Run Card。
+- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**；每个 Action **必须**显式写 `sync` 或 `async`。
 - **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；特殊业务报告才另做 `export-*`。
+- **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
 
-### 编排要点
+### 如何触发（能力类型）
 
-- **长耗时 / RPA / 浏览器任务**：必须通过宿主 **Skill Action**（`run_skill_action`）调用 `assets/actions.json` 中的 action；建议 `executionProfile: "async"`。
-- **禁止**对长任务使用 `exec python …/scripts/main.py run` 或 `process poll` 干等 CLI 返回。
-- 只读查询（`health` / `stats` 等）可用 `"sync"`，立即返回结果。
-- 批量处理用参数化 `pickCount` / `--pick N` 顺序消费队列，**不要并发**同一 Profile。
-- 详细契约：`development/SKILL_ACTION_RUNTIME.md`、`references/ACTIONS.md`、`references/SCHEMA.md`。
-- 模板源仓库本身仅示范 `health` / `version` / `config-path` / `init-db`（运维/诊断 CLI）；定制后按业务增加 Action，**一个能力一个 Action + 多 placements**。
+| 你要做什么 | Agent 怎么做 | 进任务中心？ |
+|------------|--------------|--------------|
+| 短查询 / 只读 / 秒级（`health` / `version` / `stats` / `list` / `get` / `logs` 等） | OpenClaw bash/exec + **共享 Python** 跑 CLI（见下方「共享 Python」） | 否（CLI 当场结束） |
+| 已在 `actions.json` 声明且 `executionProfile: "sync"` 的能力 | 可用 `run_skill_action`，或同等效果的短 CLI（同一内核） | 否 |
+| 长耗时 / RPA / 浏览器 / 需要进度或取消；或 `executionProfile: "async"` | **必须** `run_skill_action`（先 `list_skill_actions` / `get_skill_action`） | **是**（仅因为该 Action 是 async） |
+| 用户只问用法 / 能做什么 | 读根目录 `README.md`；逐步操作再读 `TUTORIAL.md`；**不要**为答用法去列目录或默认打开 `references/` | — |
+
+### 用户意图路由表（业务技能复制后必改）
+
+复制为业务技能后，**必须**用本技能真实意图改写下表（保留三列结构）。格子写清：短 CLI 子命令，或 `run_skill_action` → **具体 action id**（及主要 `input`）。勿留模板占位语上线。
+
+| 用户意图（本技能自填） | Agent 怎么做 | 进任务中心？ |
+|------------------------|--------------|--------------|
+| （例）查询 / 统计 / 列表 | 短 CLI：`<your-read-commands>` | 否 |
+| （例）写入 / 导入 / 改本地状态 | 短 CLI：`<your-prep-commands>` | 否 |
+| （例）长副作用 / RPA / 需进度 | `run_skill_action` → `<your-async-action-id>`，`input.…` | 是（因该 Action 为 async） |
+
+有长任务 / RPA 时：上表至少一行指向真实的 async action id，且该 id 须出现在 `assets/actions.json`；细节分流见 `references/CLI.md`。
+
+**硬规则：**
+
+1. **禁止**对长任务使用 `exec`/`bash` 跑 `…/scripts/main.py run`（或等价业务命令）再 `process poll` 干等。
+2. **禁止**用 `uv run python …` 跑技能脚本（会建临时环境，缺 `jiangchang_skill_core`）。
+3. **禁止** Agent 自行 `pip install`。
+4. Action **可选**：无数据管理 / 定时 / Agent 结构化调用需求时可不提供 `actions.json`；有长任务 / RPA 时**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 Action。
+5. **一个业务能力一个 Action**，用多个 `placements` 挂入口；底层仍是同一 `scripts/main.py` CLI。
+6. 是否进任务中心**只**看该 Action 的 `executionProfile`，与数据管理 / 定时 / Agent 入口无关。
+
+Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`（不要把 `development/` 当 Agent 主读路径）。
+
+## 共享 Python（必读）
+
+宿主共享 runtime 在 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`，并已前置到 PATH（同时设 `VIRTUAL_ENV`）。短 CLI 一条命令直接跑：
+
+```bash
+python {baseDir}/scripts/main.py health
+python {baseDir}/scripts/main.py version
+python {baseDir}/scripts/main.py config-path
+python {baseDir}/scripts/main.py init-db
+```
+
+- 公共库来自共享 venv 的 `jiangchang-platform-kit>=1.2.0`（包名路径 `jiangchang_skill_core`）；**不要 vendor** `scripts/jiangchang_skill_core/`。
+- 根目录 `requirements.txt` **只声明技能特有**依赖；不要写 `jiangchang-platform-kit` / `playwright`。
+- `metadata.openclaw.platform_kit_min_version` 是宿主兼容声明，**不是** pip 依赖。
+- `health` 用 `collect_runtime_diagnostics` 做只读诊断。
+
+配置：仓库 `.env.example` 为模板；用户 `.env` 在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`。优先级：进程环境变量 > 用户 `.env` > `.env.example`。
 
 ## 面向用户问答（LLM 规则）
 
 - 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
-- 根目录 `README.md` 是面向普通用户的说明。
+- 根目录市场材料面向普通用户（见下方「文档分工」），**不是** Agent 调用契约。
 
-当用户询问以下问题时，**必须优先读取**根目录 `README.md`，并用用户能理解的业务语言回答：
+当用户询问以下问题时，**必须优先读取**根目录 `README.md`（能力说明）与 `TUTORIAL.md`（逐步用法），并用用户能理解的业务语言回答：
 
 - 这个技能是做什么的
 - 这个技能怎么用
@@ -54,20 +95,31 @@ allowed-tools:
 - 执行后会得到什么
 - 能不能帮我完成某个业务任务
 
+**回答「怎么用 / 能做什么」时的要求：**
+
+1. 「能做什么 / 场景 / FAQ」以 `README.md` 为主；「第一次怎么用完」以 `TUTORIAL.md` 为主。
+2. **禁止**在回答中粘贴 `python …/scripts/main.py …` 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
+3. **禁止**为答用法而去 `dir` / `ls` / 列技能目录，或默认打开 `references/`、`development/`；仅当用户明确问命令、参数、集成或排错时再读 `references/`。
+4. **不要**向普通用户暴露 Playwright、DOM、Python、RPA、库表名、`error_code` 等实现细节，除非用户明确询问技术实现。
+
+**文档读取边界：**
+
 - **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
-- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/` 或 `development/`。
-- 若 `README.md` 与 `SKILL.md` / `references` 表述冲突：对用户展示与市场说明以 `README.md` 为准；对执行契约、CLI、schema、运行约束以 `SKILL.md` / `references` 为准。
-- 回答用户时**不要**暴露 Playwright、DOM、Python、RPA 等实现细节，除非用户明确询问技术实现。
+- **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/`；`development/` 主要给开发者 / 编码助手，对话 Agent **不必**默认打开。
+- 若市场材料与 `SKILL.md` / `references` 表述冲突：对用户展示以 `README.md` / `TUTORIAL.md` 为准；对执行契约以 `SKILL.md` / `references` 为准。
 - 用户未问技术实现时，**不要**讨论 slug 命名规则；开发者问命名或 slug 时，读取 `development/NAMING.md`。
 
 ## 文档分工
 
 | 文档 | 读者 | 用途 |
 |------|------|------|
-| 根目录 `README.md` | 普通用户 | 技能市场详情页说明（`metadata.readme_md` 主来源） |
+| 根目录 `README.md` | 普通用户 | 市场 **说明** Tab（`readme_md`） |
+| 根目录 `TUTORIAL.md` | 普通用户 | 市场 **教程** Tab（`tutorial_md`） |
+| 根目录 `DEMO.md` | 普通用户 | 市场 **演示** Tab（`demo_video_url` + `demo_md`） |
+| 根目录 `CHANGELOG.md` | 普通用户 | 市场 **更新日志** Tab（按版本小节 → `changelog`） |
 | `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
-| `references/` | Agent 编排/调用 | 渐进式加载：CLI 契约、字段 schema 等 |
-| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、技术规范 |
+| `references/` | Agent 编排 / 调用 | CLI、Action、schema 契约（Agent 主读） |
+| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、深度技术规范 |
 
 ## 目录约定
 
@@ -77,36 +129,15 @@ allowed-tools:
 - CLI 入口固定为 `scripts/main.py`
 - 业务逻辑按 `cli / db / service / util` 分层
 
-## 最小命令
-
-```bash
-python {baseDir}/scripts/main.py health
-python {baseDir}/scripts/main.py config-path
-python {baseDir}/scripts/main.py version
-python {baseDir}/scripts/main.py init-db
-```
-
-配置：仓库 `.env.example` 为模板；用户 `.env` 在 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`，启动时自动 bootstrap。优先级：进程环境变量 > 用户 `.env` > `.env.example`。
-
-## 运行依赖
-
-- Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
-- 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.2.0`（`jiangchang_skill_core` 包）；**不要 vendor** `scripts/jiangchang_skill_core/`，新技能不得在仓库内保留该目录副本。
-- config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。
-- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
-- `metadata.openclaw.platform_kit_min_version`（当前 `1.2.0`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。
-- Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。
-- `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。
-
 ## 定制入口
 
 1. 从本模板创建新业务技能时，**不得保留模板 `.git`**；优先使用 [`tools/scaffold_skill.ps1`](tools/scaffold_skill.ps1)（见 [`tools/README.md`](tools/README.md)）。
 2. 业务技能仓库中**不得**存在 `.openclaw-skill-template`（仅 template 源仓库保留）。
 3. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。
 4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。
-5. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`；长任务 / 任务中心见 `development/SKILL_ACTION_RUNTIME.md`。
+5. 用户市场四 Tab 材料写入根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`。
 6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
-7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`（元数据表 `_jiangchang_*` + `CREATE TABLE` 物理顺序）。
+7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`。
 
 ## 技能命名与 slug
 

TUTORIAL.md

@@ -0,0 +1,63 @@
+> **模板说明（复制后删除本段）**  
+> 本文对应技能市场 **「使用教程」** Tab（发布时同步为 `tutorial_md`）。  
+> 面向普通用户写**可跟着做的步骤**，不要写 CLI、目录结构、release、开发规范。  
+> 与根 `README.md`（技能说明）分工：README 讲「是什么 / 能做什么」；本文讲「第一次怎么用完」。  
+> **复制后验收章节（标题可微调）：**「开始前」「第一步…」「第二步…」「常见卡住怎么办」。
+
+# 【技能名称】使用教程
+
+用最短路径带用户完成一次成功使用。步骤要具体，可用「打开匠厂 → …」这类操作语言。
+
+---
+
+## 开始前
+
+确认：
+
+1. 已安装并登录匠厂客户端
+2. 已在技能市场安装本技能（或更新到最新版）
+3. 【如需】相关账号已登录、权限可用；需要的文件 / 时间范围 / 单号等已准备好
+
+---
+
+## 第一步：打开技能并说清目标
+
+在匠厂里新建任务或打开对话，用自然语言说明要做什么，例如：
+
+> “帮我【完成某件业务事】，范围是【时间 / 对象 / 条件】。”
+
+建议一次只交代一件事；范围说清楚，减少来回确认。
+
+---
+
+## 第二步：按提示补充信息
+
+如果 Agent 问你缺什么（账号、文件、筛选条件），按提示补充即可。
+
+- 有文件时：按界面提示选择或拖入
+- 有账号时：确认已在对应平台登录，且具备操作权限
+
+---
+
+## 第三步：等待结果并核对
+
+任务结束后，请核对：
+
+- 是否成功完成
+- 处理了多少条 / 哪些失败
+- 生成的文件、表格或记录是否在预期位置
+
+若失败，先看失败原因说明，再按下一节排查。
+
+---
+
+## 常见卡住怎么办
+
+| 现象 | 你可以先试 |
+|------|------------|
+| 提示未登录 / 无权限 | 确认匠厂已登录；业务账号是否在线、权限是否足够 |
+| 提示缺少必要信息 | 把时间范围、单号、文件等说完整后再试一次 |
+| 一直没有结果 | 到任务中心查看进度或失败原因；必要时重新发起 |
+| 结果不对 | 用更明确的条件再说一次，或缩小范围重试 |
+
+仍无法解决时，把「你说了什么 + 界面提示原文」发给支持人员，便于排查。

assets/README.md

@@ -4,8 +4,8 @@
 - `examples/`：CLI 成功输出形状示例（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**；`task-log-record.schema.json` 等）。
 
-`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）；`row`/`batch` placements 与 `concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交。表级 Action 示例见 [`references/ACTIONS.md`](../references/ACTIONS.md)；运行时见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
+`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）；`row`/`batch` placements 与 `concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 
-- 用户市场说明见根目录 [`README.md`](../README.md)
+- 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)
 - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)）
 - 开发规范见 [`development/`](../development/)

development/DEVELOPMENT.md

@@ -106,6 +106,9 @@ your-skill/
 ├─ tests/
 ├─ .gitignore
 ├─ README.md
+├─ TUTORIAL.md
+├─ DEMO.md
+├─ CHANGELOG.md
 ├─ requirements.txt
 ├─ release.ps1
 └─ SKILL.md
@@ -114,7 +117,10 @@ your-skill/
 各目录职责如下：
 
 - `assets/`：放示例输出、schema、静态说明资源
-- `README.md`：面向用户的市场详情页说明
+- `README.md`：市场 **说明** Tab（`readme_md`）
+- `TUTORIAL.md`：市场 **教程** Tab（`tutorial_md`）
+- `DEMO.md`：市场 **演示** Tab（`demo_video_url` + `demo_md`）
+- `CHANGELOG.md`：市场 **更新日志** Tab（按版本小节同步 `changelog`）
 - `SKILL.md`：面向 LLM / 平台的技能入口
 - `references/`：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA）
 - `development/`：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范
@@ -305,7 +311,7 @@ git remote -v
 复制后优先改下面这些地方：
 
 1. `SKILL.md`
-2. 根目录 `README.md`（用户市场说明）
+2. 根目录市场四 Tab：`README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`
 3. `scripts/util/constants.py`
 4. `references/` 与 `development/` 下的文案
 5. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`）
@@ -339,7 +345,7 @@ git remote -v
 
 如需浏览器自动化，不要在模板里保留空的 `platform_playwright.py`；请按业务新建 `xxx_playwright.py`（命名自定），并在 `task_service.py` 中按需引用。
 
-## 6. `SKILL.md` 与根 `README.md` 应该怎么写
+## 6. `SKILL.md` 与市场四 Tab 材料应该怎么写
 
 ### `SKILL.md`（LLM / 平台入口）
 
@@ -351,19 +357,26 @@ git remote -v
 - 何时触发本技能、CLI 入口摘要、运行契约要点
 - 指向 `references/`（Agent 调用）与 `development/`（开发规范）的分工说明
 
-不要在 `SKILL.md` 里写大量用户市场文案或实现细节。
+不要在 `SKILL.md` 里写大量用户市场文案或实现细节；**不要**把演示视频 URL 写进 `SKILL.md`（放 `DEMO.md` frontmatter）。
 
-### 根 `README.md`（用户市场说明）
+### 市场四 Tab（根目录，面向普通用户）
 
-根 `README.md` 是技能市场详情页主来源（`metadata.readme_md`），面向普通用户。
+发布 CI 会把下列文件同步到技能市场详情 Tabs（有文件才更新对应字段）：
 
-应包含 YAML frontmatter 的 `description`（市场列表简介），正文用用户能理解的语言说明：
+| 文件 | 市场 Tab | 同步字段 |
+|------|----------|----------|
+| `README.md` | 说明 | `readme_md`（frontmatter `description` 作列表简介） |
+| `TUTORIAL.md` | 教程 | `tutorial_md` |
+| `DEMO.md` | 演示 | `demo_md` + frontmatter `demo_video_url` |
+| `CHANGELOG.md` | 更新日志 | 匹配当前 tag 版本的 `##` 小节 → `changelog` |
 
-- 能做什么、适合什么场景、使用前准备什么
-- 如何自然语言告诉 Agent
-- 执行结果、注意事项、常见问题
+**`README.md`**：能力与场景说明。含 frontmatter `description`；写能做什么、场景、准备、如何告诉 Agent、结果、注意事项、FAQ。不要写开发教程、目录规范、release、requirements。
 
-不要在根 `README.md` 里写开发教程、目录规范、release、requirements 等技术细节。
+**`TUTORIAL.md`**：第一次怎么用完的逐步操作。写「开始前 → 步骤 → 卡住怎么办」；不要写 CLI / 目录 / 开发规范。
+
+**`DEMO.md`**：演示视频与补充说明。frontmatter 必须含 `demo_video_url`（无视频时用 `""`）；正文可选。
+
+**`CHANGELOG.md`**：每个正式版本一节（如 `## 1.0.46`）。打 tag 前为即将发布的版本新增小节；用户可读的变化，少写内部实现。
 
 实现细节放在：
 
@@ -402,9 +415,12 @@ metadata:
 
 当前规范 skill 的文档按读者拆分：
 
-**根 `README.md`**
+**根市场材料（四 Tab）**
 
-- 用户市场详情页说明（含 frontmatter `description`）
+- `README.md` — 说明（含 frontmatter `description`）
+- `TUTORIAL.md` — 使用教程
+- `DEMO.md` — 演示（`demo_video_url` + 正文）
+- `CHANGELOG.md` — 按版本更新日志
 
 **`SKILL.md`**
 
@@ -442,7 +458,7 @@ metadata:
   比如 `skill-actions.schema.json`、日志记录、机读 JSON 的 schema
 
 不要把正式研发文档放到 `assets/`。
-用户说明进根 `README.md`；Agent 编排资料进 `references/`；开发规范进 `development/`。
+用户市场四 Tab 进根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；Agent 编排资料进 `references/`；开发规范进 `development/`。
 
 ## 9. `cli` 层怎么写
 
@@ -628,11 +644,20 @@ cmd_stats()                 # 只读 sync：JSON，无 job_context
 
 ### 1. 验证入口
 
+本地验证请优先使用宿主共享 Python（与 Agent CLI 相同契约），例如：
+
 ```bash
 python scripts/main.py health
 python scripts/main.py version
 ```
 
+**禁止**对技能脚本使用 `uv run python`。
+
+```bash
+python scripts/main.py -h
+python scripts/main.py <your-command> -h
+```
+
 ### 2. 验证 CLI 路由
 
 ```bash
@@ -702,6 +727,8 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 
 在执行 `release.ps1` 之前，必须先在本地确认 `python tests/run_tests.py -v` 通过。测试不通过不得发起正式发布。
 
+**发布前必须**将 `SKILL.md` 的 `version:` 与 `scripts/util/constants.py` 的 `SKILL_VERSION` 调整为将打出的版本（例如下一 patch），再执行 `release.ps1`。`release.ps1` **不会**自动改这两个字段；漏改会造成 git tag 与技能版本号不一致。
+
 `release.ps1` 会在 **auto commit 之前**、推送 tag 之前，对**当前工作区**自动执行默认测试（`python tests/run_tests.py -v`）；失败则中止 release，不会留下失败状态的自动提交。仅紧急排障可使用 `-SkipTests` 跳过（会打印黄色警告）。`-DryRun` 预览发布时**仍会实际运行**默认测试，便于在不打 tag 的情况下验证门禁。
 
 新增或调整开发规范时，须同步 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md) 与 [`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py)（或注明由既有测试覆盖）。
@@ -757,7 +784,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如：
 
 - 发布脚本是否正常推送
-- `SKILL.md`、根 `README.md`、`scripts/`、`references/`、`development/` 是否齐全
+- `SKILL.md`、根市场四 Tab（`README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`）、`scripts/`、`references/`、`development/` 是否齐全
 - 工作流文件是否存在
 - 发布包结构是否符合模板规范
 
@@ -892,7 +919,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 现在的新模板原则是：
 
 - 不做旧结构兼容
-- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
+- 用户市场四 Tab 在根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`，Agent 资料在 `references/`，开发规范在 `development/`
 - 统一走 `scripts/main.py` 作为 CLI 入口
 
 ### 错误 5：平台放 slug 最前
@@ -954,7 +981,7 @@ git remote add origin <新技能仓库 URL>
 如果让一个新人照着做，我建议他按这个顺序：
 
 1. 按 [`NAMING.md`](NAMING.md) 确定 slug，复制模板并改目录名
-2. 改 `SKILL.md` 与根 `README.md`
+2. 改 `SKILL.md` 与根市场四 Tab（`README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`）
 3. 改 `scripts/util/constants.py`
 4. 改 `references/` 与 `development/`
 5. 改 `scripts/cli/app.py`
@@ -970,7 +997,7 @@ git remote add origin <新技能仓库 URL>
 
 - 目录结构统一
 - 入口统一为 `scripts/main.py`
-- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
+- 用户市场四 Tab 在根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`，Agent 资料在 `references/`，开发规范在 `development/`
 - 业务核心逻辑统一放 `scripts/service/`
 - 不再使用旧模板历史结构
 

development/POLICY_MATRIX.md

@@ -7,6 +7,8 @@
 | POLICY-STRUCTURE-001 | 标准 `scripts/` 分层：`main.py`、`cli/`、`service/`、`db/`、`util/` 必须存在 | development/DEVELOPMENT.md §2 新 skill 的标准目录结构；development/RUNTIME.md §目录结构 | hard | 目录存在性检查 | `tests/test_development_policy_guard.py::TestPolicyStructure001` |
 | POLICY-RUNTIME-001 | 不得 vendored `scripts/jiangchang_skill_core/` | development/RUNTIME.md §共享 Python Runtime、§明确禁止 | hard | 目录不存在检查 | `tests/test_development_policy_guard.py::TestPolicyRuntime001`（另见 `tests/test_platform_import.py`） |
 | POLICY-RUNTIME-002 | `requirements.txt` 非注释依赖行不得声明 `jiangchang-platform-kit` / `playwright` | development/RUNTIME.md §共享 Python Runtime；development/DEVELOPMENT.md §3.1 requirements.txt 依赖规范 | hard | 解析依赖行 | `tests/test_development_policy_guard.py::TestPolicyRuntime002`（另见 `tests/test_platform_import.py`） |
+| POLICY-RUNTIME-003 | Agent/CLI 文档须要求共享 Python（python-runtime / PATH 上的 `python` + `{baseDir}`）；须明确**禁止**对技能脚本使用 `uv run python` | development/RUNTIME.md；references/CLI.md；SKILL.md | hard | 文档标记扫描 | `tests/test_docs_standards.py::test_cli_md_requires_shared_python_not_uv_run`；`tests/test_docs_standards.py::test_skill_md_requires_shared_python_not_uv_run` |
+| POLICY-AGENT-001 | `SKILL.md` 须含「用户意图路由表」结构；`CLI.md` 须含短 CLI 白名单 / Action 强制黑名单表；用法回答须禁止无故粘贴 CLI、禁止为答用法列目录挖 references | SKILL.md；references/CLI.md | hard | 文档标记扫描 | `tests/test_docs_standards.py::test_skill_md_has_intent_routing_table`；`tests/test_docs_standards.py::test_cli_md_has_agent_routing_tables`；`tests/test_docs_standards.py::test_skill_md_how_to_forbids_cli_paste` |
 | POLICY-INSTALL-001 | 交付执行文件不得含 `pip install` / `python -m pip install` / `uv pip install` / `playwright install` | development/RUNTIME.md §共享 Python Runtime；development/RPA.md §1.4 Playwright 与安装边界；development/DEVELOPMENT.md §3.1 | hard | 扫描 `scripts/**/*.py`、`*.ps1`、`*.sh`、`requirements.txt`、`.github/workflows/*`（不扫 `development/*.md`） | `tests/test_development_policy_guard.py::TestPolicyInstall001` |
 | POLICY-CONFIG-001 | 仓库根目录必须存在 `.env.example` | development/CONFIG.md §核心原则、§标准配置项 | hard | 文件存在性 | `tests/test_development_policy_guard.py::TestPolicyConfig001` |
 | POLICY-CONFIG-002 | `.gitignore` 必须忽略 `.env` 与 `*.env.local` | development/CONFIG.md §红线：敏感信息不进 .env | hard | 解析 `.gitignore` 行 | `tests/test_development_policy_guard.py::TestPolicyConfig002` |

development/README.md

@@ -17,4 +17,4 @@
 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。
 
 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。  
-用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。
+用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。

development/REQUIREMENTS.md

@@ -98,7 +98,7 @@
 
 - 目录结构必须符合当前 `skill-template` 规范
 - 入口必须统一为 `scripts/main.py`
-- 用户说明写在根 `README.md`；LLM/运行契约写在 `SKILL.md`；开发规范在 `development/`
+- 用户市场四 Tab 写在根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；LLM/运行契约写在 `SKILL.md`；开发规范在 `development/`
 - 输出格式应尽量机读友好；错误前缀统一为 `ERROR:`
 - Windows 环境下需保证 UTF-8 输出兼容
 - 必须具备基本日志能力；敏感字段脱敏

development/RUNTIME.md

@@ -8,21 +8,24 @@
 
 | 场景 | 推荐做法 |
 |------|----------|
-| 日常运行 | 由宿主匠厂触发技能 |
-| 手工排查 / 测试机 | 使用共享 runtime 的 `python.exe` 执行 `scripts/main.py` |
-| **不推荐** | 在技能目录内 `uv run python …` — 可能创建临时 venv，加载不到宿主共享 runtime |
+| 日常运行（宿主 / Agent） | 使用 PATH 上的共享 venv `python`（`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`） |
+| 手工排查 / 测试机（环境未注入时） | `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/.../python` 执行 `scripts/main.py` |
+| **禁止** | 在技能目录内 `uv run python …` — 会创建临时 venv，加载不到宿主共享 runtime |
 
 占位命令（路径因环境而异，勿写死本机目录）：
 
 ```text
-Windows:
+推荐（已注入环境时）:
+  python {baseDir}/scripts/main.py health
+
+Windows（未注入时）:
   {JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health
 
-通用:
-  <shared-python> {baseDir}/scripts/main.py health
+Unix（未注入时）:
+  {JIANGCHANG_DATA_ROOT}/python-runtime/.venv/bin/python3 {baseDir}/scripts/main.py health
 ```
 
-`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `JIANGCHANG_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
+共享解释器通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入（见 `jiangchang_skill_core.runtime_env`）。
 
 ## Runtime 诊断（platform-kit 1.2.0+）
 

development/SKILL_ACTION_RUNTIME.md

@@ -20,8 +20,8 @@
 1. **宿主管调度，技能管业务** — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
 2. **单业务内核、多入口** — 数据管理、定时任务、Agent、技能详情与直接 CLI 复用同一 domain service；禁止按入口复制业务逻辑。
 3. **五职责正交** — `placements` / `bind.tables` / `executionProfile` / `entrypoint` / domain service 各管一事（见 ACTIONS.md）。
-4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是选择建议，**不**限制可以出现在哪些 placement。
-5. **Agent 禁止 `exec` 直跑长任务 CLI** — 必须 `run_skill_action`；禁止 `exec python main.py run` + `process poll` 干等。
+4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是对**方法**的选择，**不**限制可以出现在哪些 placement / 入口。
+5. **Agent：短 CLI / 长 Action** — 短查询可用共享 Python bash CLI；长任务 / RPA **禁止** `exec` + `process poll`，必须 `run_skill_action`。
 6. **进度走 Journal** — `emit` / `video.add_step` → Run Journal；UI / Skill Run Card / 任务中心展示；**不靠 stdout 流**。
 7. **显式声明 `executionProfile`** — 每个 action **必须**写明 `sync` 或 `async`；禁止依赖宿主缺省；禁止第三种模糊模式（`auto` / `background` / `deferred` 等）。
 
@@ -160,15 +160,15 @@ cmd_stats()                 # 只读 sync：JSON stdout，无 job_context
 
 ## 8. Agent / SKILL.md 契约（复制后必改）
 
-业务技能 `SKILL.md` 应明确：
+业务技能 `SKILL.md` / `references/` 应明确（Agent 主读，勿只写在本文）：
 
-1. 副作用任务必须通过宿主 **Skill Action**（`run_skill_action`）调用。
-2. **禁止**对长任务使用 `exec` + `process poll`。
+1. 短查询：共享 Python（PATH 上的 `python`）跑 CLI；**禁止** `uv run`。
+2. 长任务 / RPA / async Action：必须通过宿主 **Skill Action**（`run_skill_action`）；**禁止** `exec` + `process poll`。
 3. 单条 vs 批量 action id 与参数（如 `url` / `pickCount`）。
-4. 长任务进度看**任务中心** / Skill Run Card，不等 CLI stdout。
-5. 多入口复用同一业务内核；异步 Action 进入任务中心。
+4. `executionProfile: async` → 进度看**任务中心** / Skill Run Card；`sync` → 当场结果。与入口无关。
+5. 多入口复用同一业务内核。
 
-模板源仓库的 `SKILL.md` 含占位段落；scaffold 后按业务改写。
+模板源仓库的 `SKILL.md` / `references/ACTIONS.md` 含占位段落；scaffold 后按业务改写。
 
 ---
 

references/ACTIONS.md

@@ -1,10 +1,39 @@
 # Skill Action Manifest（匠厂宿主）
 
-本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。
+本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 **Agent 编排**与宿主 **Skill Action Runtime** 使用。这是 Agent 侧关于 Action / 任务中心的**主契约**；实现细节与开发规范见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 
-**权威运行时契约（sync/async、任务中心、单内核编排）见 [`../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)；CLI 参数见 [`CLI.md`](CLI.md)。
 
-**边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。
+## Agent 何时用 Action（与 CLI 的分工）
+
+| 场景 | 做法 |
+|------|------|
+| 短查询 / 只读 / 秒级 | bash + 共享 Python CLI（见 [`CLI.md`](CLI.md)）；**不必**强行走 Action |
+| 数据管理按钮 / 定时任务 / 技能详情按钮 | **必须**在 `actions.json` 声明对应 Action |
+| 长耗时 / RPA / 需要进度与取消 | **必须** `run_skill_action`；对应 Action 一般为 `executionProfile: "async"` |
+| 已声明的 `sync` Action | `run_skill_action` 当场返回结果，**不进**任务中心 |
+| 已声明的 `async` Action | `run_skill_action` 立即返回 `jobId`，**进入**任务中心 |
+
+**进不进任务中心只取决于该 Action 的 `executionProfile`，与从数据管理、定时任务还是 Agent 触发无关。**
+
+禁止对长任务 `exec`/`bash` + `process poll` 干等 CLI。禁止 `uv run python` 跑技能脚本。
+
+## async 副作用 Action 最小组合（复制验收 checklist）
+
+对每个「会开浏览器 / 长耗时 / 需进度或取消」的 Action，声明时建议同时满足：
+
+1. `executionProfile: "async"`（进入任务中心）
+2. 若要让 Agent 触发：`placements` **含** `agent`
+3. 有可感知副作用时：提供 `confirmation.message`
+4. 需要用户/Agent 入参时：简单 `inputSchema` + entrypoint 中的 `{{fieldName}}`
+5. `SKILL.md`「用户意图路由表」与 `CLI.md`「Action 强制黑名单」**出现同一 action id / 命令**
+
+默认模板 `assets/actions.json` 仅含诊断类 sync Action，**不要**为通过本 checklist 而塞假业务 Action；业务技能按需添加。完整字段见下文 Phase 1。
+
+## 可选：域前缀 CLI（嵌套子命令）
+
+小技能可继续扁平：`entrypoint.command = "run"`。  
+命令变多时，可采用**域前缀**：`command` 为域（如 `<domain>`），业务动词与参数放在 `args` 数组（如 `["<verb>", "--flag", "{{field}}"]`）。与扁平入口等价，须仍指向同一 domain service。
 
 ## 模板严格规范 vs 宿主向后兼容
 
@@ -117,7 +146,7 @@ Action 是**可选能力**：
 
 ## 执行模型
 
-宿主将 action 转为 argv，再执行：
+宿主将 action 转为 argv，再用**共享 Python**（用户数据目录下 `python-runtime/.venv`）执行：
 
 ```text
 python {skill_root}/scripts/main.py <command> <args...>
@@ -132,7 +161,7 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 ### `executionProfile`（仅 sync / async）
 
-模板与新技能**只允许**这两种值；禁止发明 `auto` / `background` / `deferred` 等第三种模式。
+模板与新技能**只允许**这两种值；每个 Action **必须**显式写出；禁止发明 `auto` / `background` / `deferred`；**禁止**依赖宿主「省略字段时的兼容默认」。
 
 | 值 | 宿主行为 | 任务中心 |
 |----|----------|----------|
@@ -141,9 +170,9 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 合法组合（全部允许）：`sync|async` × `toolbar|cron|agent|skill-detail`。
 
-经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，建议用 `async`。
+经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，用 `async`。
 
-直接执行 CLI 时，终端自然等待进程结束；宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。
+直接执行短 CLI 时，终端自然等待进程结束。宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。
 
 ### CLI 输出契约
 

references/CLI.md

@@ -1,6 +1,33 @@
 # 通用业务技能模板 CLI 标准
 
-将 `{baseDir}` 替换为技能根目录（含 `SKILL.md`、`scripts/` 的目录）。所有命令通过 `python {baseDir}/scripts/main.py` 调用。
+将 `{baseDir}` 替换为技能根目录（含 `SKILL.md`、`scripts/` 的目录）。
+
+## 解释器（必读）
+
+必须使用宿主**共享 Python runtime**（`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`，已在 PATH / `VIRTUAL_ENV`）。一条命令直接跑，不要先探系统 Python。
+
+```bash
+python {baseDir}/scripts/main.py <command> …
+```
+
+| 场景 | 写法 |
+|------|------|
+| **推荐（Agent）** | `python {baseDir}/scripts/main.py <command> …` |
+| 手工排查（环境未注入时） | `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv/Scripts/python.exe`（Windows）或 `…/.venv/bin/python3`（Unix） |
+
+**禁止**对技能脚本使用 `uv run python …`（会创建临时环境，加载不到 `jiangchang-platform-kit` / `jiangchang_skill_core`）。  
+**禁止** Agent 自行 `pip install` / `uv pip install` 往临时环境塞依赖。
+
+## Agent 分流（业务技能复制后必改）
+
+用本表列出**本技能**哪些子命令可走短 CLI，哪些必须走 Skill Action。默认：短查询/只读写本地可用短 CLI；长耗时 / RPA / 需进度取消进**黑名单**。有 async/RPA 的技能：**黑名单不得为空**，且黑名单命令须映射到 `actions.json` 中的 async Action。
+
+| 类型 | 本技能命令（自填） | Agent |
+|------|--------------------|-------|
+| **短 CLI 白名单** | （例）`health` / `version` / `logs` / `<your-read-or-prep>` | 可用 bash/exec + 共享 `python` |
+| **Action 强制黑名单** | （例）`<your-long-or-rpa-command>` | **禁止** bash + `process poll`；必须 `run_skill_action` |
+
+细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。
 
 ## 最小命令
 
@@ -18,13 +45,13 @@ python {baseDir}/scripts/main.py init-db
 - **`config-path`**：输出 JSON，包含 `skill`、`env_path`、`example_path`。
 - **`version`**：输出 JSON（`version`、`skill`）。
 - **`init-db`**：幂等创建/迁移本地 SQLite（含 `_jiangchang_*` 展示元数据）。成功输出一行 JSON（`ok` / `skill` / `db_path`），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
-- **`run`**：长时间无 stdout **不代表卡死**；RPA / 外部调用期间应通过 Activity 或 Run Journal 看进度。
+- **`run` / RPA / 长任务**：CLI 仍是同一内核；**Agent 禁止**用 bash 干等长任务结束。须走宿主 Skill Action（`run_skill_action`），且该 Action 一般为 `executionProfile: "async"` → **任务中心**。长时间无 stdout **不代表卡死**；进度看任务中心 / Run Journal。
 - **排查顺序**（由快到慢）：
   1. `python {baseDir}/scripts/main.py logs`
   2. `python {baseDir}/scripts/main.py log-get <log_id>`
   3. 统一日志文件 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log`（含 `trace_id`、`task_failed` 等）
   4. Run Journal `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl`
-  5. RPA artifacts / `video_log` / 失败截图（见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
+  5. RPA artifacts / `video_log` / 失败截图（开发规范见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
 - **录屏默认关闭**：模板 `.env.example` 为 `OPENCLAW_RECORD_VIDEO=0`；若未开启录屏，任务**可能不会**打印录屏路径。
 - 需要录屏时在用户 `.env` 或进程环境变量中设置 **`OPENCLAW_RECORD_VIDEO=1`**；开启后任务完成时 CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`），且 `result_summary` 含 video 字段。
 
@@ -42,7 +69,7 @@ python {baseDir}/scripts/main.py init-db
 
 `health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，典型字段：
 
-- `python_executable` — 当前 Python 解释器路径
+- `python_executable` — 当前 Python 解释器路径（应落在共享 python-runtime）
 - `platform_kit_version` / `platform_kit_min_version` / `platform_kit_version_ok`
 - `jiangchang_skill_core_file` — 公共库加载来源（若来自技能目录副本会报 warning）
 - `media_assets_root`、`ffmpeg_path`、`ffmpeg_available`、`background_music_mp3_count`
@@ -59,38 +86,7 @@ python {baseDir}/scripts/main.py logs --task-type demo --status failed
 python {baseDir}/scripts/main.py log-get <log_id>
 ```
 
-| 命令 | 用途 |
-|------|------|
-| `run` | 执行一次任务 |
-| `logs` | 列出最近 N 条任务日志 |
-| `log-get` | 按 log_id 查看单条任务日志（JSON） |
-
-## 查询/导出类（可选）
-
-复制后按需增加，例如：`contacts`、`contact-get`、`export` 或业务等价命令。
-
-## 若你的技能依赖兄弟技能
-
-使用 `service.sibling_bridge.call_sibling_json(skill_slug, args)`，不要硬编码兄弟技能名到 `sibling_bridge.py` 自身；并在 `SKILL.md` 声明 `dependencies.required`。
-
-## 手工排查命令（推荐）
-
-**建议使用宿主共享 python-runtime**，避免技能目录内临时 venv 加载不到公共库：
-
-```text
-Windows:
-  {JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health
-
-通用:
-  <shared-python> {baseDir}/scripts/main.py health
-```
-
-`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
-
-**不建议**在生产/测试机使用技能目录内 `uv run python`，以免加载不到共享 runtime 中的 `jiangchang-platform-kit` / `playwright`。
-
-## 模板约定
-
-- 最小模板至少保留 `health` / `config-path` / `version`
-- 通用业务技能建议使用 `run` / `logs` / `log-get`
-- 不要再用旧模板的 `publish` / `--account-id` / `--article-id` 命名
+| 命令 | 用途 | Agent 注意 |
+|------|------|------------|
+| `run` | 执行一次任务（常为长任务 / RPA） | **走 `run_skill_action`**，不要 bash poll |
+| `logs` / `log-get` | 查任务日志 | 可用短 CLI |

references/README.md

@@ -5,17 +5,20 @@
 **边界规则：**
 
 - 本文**不得**包含 YAML frontmatter，**不得**包含 `description` 字段。
-- 技能市场详情与普通用户说明**必须**放在根目录 [`README.md`](../README.md)。
-- 本目录只保留运行时引用资料（如 `CLI.md`、`SCHEMA.md`）；开发规范放在 [`../development/`](../development/)。
+- 技能市场四 Tab 材料**必须**放在根目录：[`README.md`](../README.md)、[`TUTORIAL.md`](../TUTORIAL.md)、[`DEMO.md`](../DEMO.md)、[`CHANGELOG.md`](../CHANGELOG.md)。
+- **Agent 主读本目录**（`CLI.md` / `ACTIONS.md` / `SCHEMA.md`）与根 [`SKILL.md`](../SKILL.md)。
+- [`../development/`](../development/) 是开发者 / 编码助手深度规范，**不是**对话 Agent 的默认读盘路径。
 
 | 文档 | 用途 |
 |------|------|
-| 根目录 [`README.md`](../README.md) | 用户市场详情页说明 |
-| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口 |
-| [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 |
+| 根目录 [`README.md`](../README.md) | 市场说明 Tab（`readme_md`） |
+| 根目录 [`TUTORIAL.md`](../TUTORIAL.md) | 市场教程 Tab（`tutorial_md`） |
+| 根目录 [`DEMO.md`](../DEMO.md) | 市场演示 Tab（`demo_video_url` + `demo_md`） |
+| 根目录 [`CHANGELOG.md`](../CHANGELOG.md) | 市场更新日志 Tab（版本小节 → `changelog`） |
+| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
+| [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
+| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口（可选能力） |
 | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
-| [`ACTIONS.md`](ACTIONS.md) | Skill Action manifest（**可选**能力）与宿主入口契约 |
-| [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md) | sync/async、任务中心、Agent 禁令、编排与队列 pick（长任务必读） |
-| [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） |
+| [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
 
-按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；配置宿主按钮/定时任务/Agent 入口时读 `ACTIONS.md` + `SKILL_ACTION_RUNTIME.md`；运行时环境细节见 `../development/RUNTIME.md`。
+按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`。

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.42"
+SKILL_VERSION = "1.0.46"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.0"

tests/test_development_policy_guard.py

@@ -24,6 +24,7 @@ POLICY_IDS = (
     "POLICY-STRUCTURE-001",
     "POLICY-RUNTIME-001",
     "POLICY-RUNTIME-002",
+    "POLICY-RUNTIME-003",
     "POLICY-INSTALL-001",
     "POLICY-CONFIG-001",
     "POLICY-CONFIG-002",

tests/test_docs_standards.py

@@ -141,6 +141,47 @@ class TestDocsStandards(unittest.TestCase):
             msg="SKILL.md must state README.md is user-facing documentation",
         )
 
+    def test_market_tab_docs_exist(self) -> None:
+        root = get_skill_root()
+        for name in ("README.md", "TUTORIAL.md", "DEMO.md", "CHANGELOG.md"):
+            path = os.path.join(root, name)
+            self.assertTrue(os.path.isfile(path), msg=f"{name} must exist at skill root")
+
+    def test_demo_md_frontmatter_has_demo_video_url(self) -> None:
+        text = self._read("DEMO.md")
+        self.assertTrue(text.startswith("---"), "DEMO.md must start with YAML frontmatter")
+        frontmatter = self._parse_frontmatter(text)
+        self.assertIn(
+            "demo_video_url:",
+            frontmatter,
+            "DEMO.md frontmatter must include demo_video_url",
+        )
+
+    def test_changelog_has_section_for_skill_version(self) -> None:
+        skill_fm = self._parse_frontmatter(self._read("SKILL.md"))
+        match = re.search(r"(?m)^version:\s*[\"']?([0-9]+\.[0-9]+\.[0-9]+)", skill_fm)
+        self.assertIsNotNone(match, "SKILL.md must declare semver version")
+        version = match.group(1)
+        changelog = self._read("CHANGELOG.md")
+        self.assertRegex(
+            changelog,
+            rf"(?m)^##\s*\[?v?{re.escape(version)}\]?",
+            msg=f"CHANGELOG.md must include a ## section for version {version}",
+        )
+
+    def test_skill_md_documents_market_four_tabs(self) -> None:
+        text = self._read("SKILL.md")
+        for name in ("TUTORIAL.md", "DEMO.md", "CHANGELOG.md", "readme_md", "tutorial_md"):
+            self.assertIn(name, text, msg=f"SKILL.md must document market material {name}")
+
+    def test_development_md_documents_market_four_tabs(self) -> None:
+        text = self._read("development/DEVELOPMENT.md")
+        self.assertIn("TUTORIAL.md", text)
+        self.assertIn("DEMO.md", text)
+        self.assertIn("CHANGELOG.md", text)
+        self.assertIn("demo_video_url", text)
+        self.assertIn("tutorial_md", text)
+
     def test_naming_md_exists_and_covers_standards(self) -> None:
         text = self._read("development/NAMING.md")
         self.assertIn("verb-noun-platform", text)
@@ -302,10 +343,71 @@ class TestDocsStandards(unittest.TestCase):
         self.assertNotIn("ALLOW_" + "REAL_" + "API", text)
         self.assertNotIn("ALLOW_WRITE_ACTIONS", text)
 
-    def test_cli_md_mentions_shared_python_runtime(self) -> None:
+    def test_cli_md_requires_shared_python_not_uv_run(self) -> None:
         text = self._read("references/CLI.md")
         self.assertIn("python-runtime", text)
+        self.assertIn("python {baseDir}/scripts/main.py", text)
+        self.assertNotIn("JIANGCHANG_PYTHON_EXE", text)
+        self.assertIn("禁止", text)
         self.assertIn("uv run python", text)
+        self.assertNotRegex(
+            text,
+            r"(?m)^(?!\*\*禁止\*\*).*\*\*建议\*\*.*uv run python",
+            msg="CLI.md must not recommend uv run for skill scripts",
+        )
+
+    def test_cli_md_has_agent_routing_tables(self) -> None:
+        text = self._read("references/CLI.md")
+        self.assertIn("短 CLI 白名单", text)
+        self.assertIn("Action 强制黑名单", text)
+        self.assertIn("run_skill_action", text)
+
+    def test_skill_md_requires_shared_python_not_uv_run(self) -> None:
+        text = self._read("SKILL.md")
+        self.assertIn("python {baseDir}/scripts/main.py", text)
+        self.assertNotIn("JIANGCHANG_PYTHON_EXE", text)
+        self.assertIn("uv run python", text)
+        self.assertIn("禁止", text)
+        self.assertIn("run_skill_action", text)
+        self.assertIn("executionProfile", text)
+        self.assertTrue(
+            "任务中心" in text and "无关" in text,
+            msg="SKILL.md must state Task Center is independent of entry point",
+        )
+
+    def test_skill_md_has_intent_routing_table(self) -> None:
+        text = self._read("SKILL.md")
+        self.assertIn("用户意图路由表", text)
+        self.assertIn("用户意图", text)
+        self.assertIn("准备 vs 执行", text)
+
+    def test_skill_md_how_to_forbids_cli_paste(self) -> None:
+        text = self._read("SKILL.md")
+        self.assertIn("回答「怎么用", text)
+        self.assertIn("禁止", text)
+        self.assertTrue(
+            "粘贴" in text and "python" in text,
+            msg="SKILL.md must forbid pasting python CLI when answering how-to",
+        )
+        self.assertTrue(
+            "dir" in text or "列" in text,
+            msg="SKILL.md must discourage directory probing for how-to answers",
+        )
+
+    def test_actions_md_has_async_side_effect_checklist(self) -> None:
+        text = self._read("references/ACTIONS.md")
+        self.assertIn("最小组合", text)
+        self.assertIn("confirmation.message", text)
+        self.assertIn("用户意图路由表", text)
+
+    def test_actions_md_states_profile_not_entry_for_task_center(self) -> None:
+        text = self._read("references/ACTIONS.md")
+        self.assertIn("executionProfile", text)
+        self.assertIn("任务中心", text)
+        self.assertTrue(
+            "无关" in text or "orthogonal" in text.lower() or "正交" in text,
+            msg="ACTIONS.md must keep placements orthogonal to Task Center",
+        )
 
     def test_testing_md_mentions_pytest_txt_collection_guard(self) -> None:
         text = self._read("development/TESTING.md")