docs: add PRODUCT_SURFACES peer entry contract for skill authors

2026-08-17 18:49:05 +08:00
parent 3738f0bea2
commit f221f81d4e
13 changed files with 262 additions and 44 deletions
--- a/development/CHECKLIST.md
+++ b/development/CHECKLIST.md
@@ -57,6 +57,8 @@ checklist_version: 1.0
 - [ ] S0-6 是否需要在任务中心查看进度或结果：是 / 否
 - [ ] S0-7 外部系统账号、数据、设备与操作权限的授权来源：
 - [ ] S0-8 是否包含提交、付款、删除、审批、发布、发送等不可逆副作用：是 / 否
+- [ ] S0-9 **入口定位表**（见 `PRODUCT_SURFACES.md` / `REQUIREMENTS` §0.1）：已填写 / 未填写
+- [ ] S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）

 ---

@@ -86,6 +88,8 @@ checklist_version: 1.0
 - [ ] A3-2 **P0** 缺参或非法输入时稳定失败（可读错误，不假成功）
 - [ ] A3-3 **P1** 失败可诊断：能从任务记录/提示判断失败阶段，而非只有“失败了”
 - [ ] A3-4 **P0** 同一能力从已声明的不同入口触发时，业务结果一致（不出现入口分叉成两套逻辑）
+- [ ] A3-5 **P0** `REQUIREMENTS` 入口定位表已填写；定位为「挂」的入口在 `actions.json`（及必要表元数据）中有对应声明
+- [ ] A3-6 **P1** 定位为「不挂」的入口有书面理由（不是空白遗漏）

 ---

@@ -164,7 +168,7 @@ checklist_version: 1.0

 - [ ] A9-1 **P0** 仓库默认测试套件通过（执行技能约定的一键测试命令，如 `python tests/run_tests.py -v`）
 - [ ] A9-2 **P0** 不以「仅模拟档通过」作为交活依据（有真实档要求时必须真实跑通或书面阶段性豁免）
- [ ] A9-3 **P0** **NEED_MANUAL** 已声明的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过
+- [ ] A9-3 **P0** **NEED_MANUAL** 入口定位表中定为「挂」的宿主入口（详情/Agent/工具栏/定时等）按声明抽测可通过；未在定位表中规划且未声明的入口可标 N/A（须引用定位表理由），**禁止**用「未声明」掩盖「从未做入口定位」
 - [ ] A9-4 **P1** 对外版本一致：详情、version、更新日志、发布标签能对上
 - [ ] A9-5 **P1** 开发者按平台规则能安装并测到该技能（若平台有开发者可见性要求）

--- a/development/DEVELOPMENT.md
+++ b/development/DEVELOPMENT.md
@@ -543,17 +543,20 @@ assets/actions.json             → placements / bind / executionProfile / entry
 - 打印用户提示
 - 拼接业务流程

-## 11.5 Skill Action manifest（可选）
+## 11.5 Skill Action manifest（按入口定位挂载）

-若技能需要出现在宿主**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中，提供 `assets/actions.json`。
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)：对话 / 数据管理 / 定时任务**平级**；哪个主能力出现在哪个入口，由本技能 UX 在 `REQUIREMENTS` 入口定位表中定义。

+若定位表要求出现在宿主**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中，提供 `assets/actions.json` 并写入对应 `placements`。
+
+- **产品入口与何时走哪个**见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)
 - **运行时金标准**见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)
 - 字段契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)（`placements` / `bind.tables` / `executionProfile` 正交）
 - JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)
 - 模板最小示例仅暴露 `health` / `version` / `config-path`（均显式 `executionProfile: "sync"`；**不**自动加 toolbar）；CLI 另含 `init-db` 供宿主静默建库（不必做成 Action）
 - 含 `toolbar` 的 Action：**必须**声明合法 `bind.tables`（`POLICY-SKILL-ACTION-003`）
 - 含浏览器 RPA / 长耗时的业务技能：**必须**增加至少一条 `"executionProfile": "async"` 且 `placements` 含 `agent` 的 action（`POLICY-SKILL-ACTION-001`）
- 没有宿主直接操作需求时，**可以删除** `actions.json`；删除后勿保留失效引用
+- 入口定位表确认无任何宿主结构化入口需求时，**可以删除** `actions.json`；删除后勿保留失效引用
 - scaffold **不会**移除 Schema 中的 `bind` 支持，**不会**生成平台业务 Action 或业务表名；仅替换占位 slug

 宿主执行方式：
@@ -818,9 +821,14 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea
 - 安装后状态正常
 - 不会出现缺文件、缺入口或安装失败的问题

-### 第七步：按声明做宿主多入口验收（已声明的入口都要测；须看用户体验）
+### 第七步：按入口定位与声明做宿主多入口验收（须看用户体验）

-安装完成后，不要只停留在“已安装”状态，也**不要**只在本地 mock 通就认为完成。宿主侧栏有多条与技能相关的入口；**按本技能 `assets/actions.json` 的 `placements` / `executionProfile` 声明逐项自测**（契约见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。未声明的入口可以跳过；**已声明却测不到，视为验收失败**。不要只测对话、忽略其它入口。
+安装完成后，不要只停留在“已安装”状态，也**不要**只在本地 mock 通就认为完成。对话任务 / 数据管理 / 定时任务在宿主上**平级**（见 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)）。先核对本技能 `REQUIREMENTS` **入口定位表**，再按 `assets/actions.json` 的 `placements` / `executionProfile` 对「定位为挂」的入口逐项自测（字段契约见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。
+
+- 定位为「挂」却未声明或测不到 → **验收失败**
+- 定位为「不挂」且写了理由 → 可跳过该入口
+- **禁止**从未做入口定位、却用「未声明所以跳过」交差
+- 不要只测对话、忽略定位表中已挂的其它入口

 **用户体验（与功能入口并列，后台通了不算完）：**

--- a/development/PRODUCT_SURFACES.md
+++ b/development/PRODUCT_SURFACES.md
@@ -0,0 +1,172 @@
+# 宿主产品入口（对话 / 数据管理 / 定时任务）
+
+本文给**技能开发者**与 **AI 编程助手**读：说明匠厂宿主上几个**平级**业务入口各自干什么、**什么时候走哪个**、以及如何为本技能做入口定位。
+
+字段怎么写见 [`../references/ACTIONS.md`](../references/ACTIONS.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)；任务中心 / sync·async 见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)。
+
+**与其它分类正交：**
+
+| 文档维度 | 回答的问题 |
+|----------|------------|
+| 本文（产品入口） | 用户从宿主哪条路径触发同一能力 |
+| Type A–D / 目录分层 | 技能有没有库、会不会调兄弟技能 |
+| RPA 四象限 | 外部系统怎么接 |
+
+不要把三者合并成一个大枚举。
+
+---
+
+## 1. 入口是什么（先立规矩）
+
+技能跑在**匠厂宿主**上，不是独立软件。宿主侧栏里的入口，是同一技能能力的不同**触发场景**：
+
+| 今日常见入口 | 触发方式 | 底层 |
+|--------------|----------|------|
+| **对话任务**（新建任务） | 自然语言 → Agent | 短 CLI，或 `run_skill_action`（`placements` 含 `agent`） |
+| **数据管理** | 点工具栏 / 行 / 批量 / 表单（UI） | `run_skill_action`（`source=data-management`）→ **同一 CLI** |
+| **定时任务** | 到点「技能直调」或定时 Agent | `run_skill_action`（`cron` / `cron-agent`）→ **同一 CLI** |
+
+**铁律：**
+
+1. **入口平级**：没有「对话主、数据管理/定时辅」。只是触发场景与交互方式不同，各自有优势。
+2. **同一业务能力、同一 domain service**：禁止按入口复制逻辑，禁止按 `source` 分叉业务结果。
+3. **同能力可挂多个入口**：不是三选一；按本技能 UX 决定挂哪些。
+4. **可扩展**：以后若宿主增加新入口，仍是「新触发场景 + 同一内核」，定位方法不变（定位表多一列即可）。
+5. **任务中心不是业务入口**：只表示 `executionProfile: async` 的执行壳；与从哪个入口点进来无关。
+
+---
+
+## 2. 什么时候走哪个入口
+
+### 2.1 对话任务——「用嘴发起」
+
+**适合：**
+
+- 用户用自然语言描述意图，条件一次说清或还要追问
+- 探索式：「能不能帮我……」「先看看再决定」
+- 对象临时指定（贴链接、说一个范围）
+- 需要 Agent 解释结果、失败原因、下一步
+- 用户不想打开数据管理，只想在聊天里办完
+
+**技术自问：** 用户会不会用一句话说清这件事？需要模型帮理解和确认吗？——会，就为该能力挂 `agent`（长任务 / RPA 必须 Action + 通常 `async`；短查询可用共享 Python CLI）。
+
+**注意：** 若技能还有「对着表运营 / 定时啃队列」等场景，**不要把对话当成唯一路径**，否则传统用户与省 token 路径会丢掉。
+
+### 2.2 数据管理——「用界面发起 + 看着数据做」
+
+数据管理有两层，**同等重要**：
+
+1. **执行面**：工具栏 / 行级 / 批量 / `replaces` 接管 CRUD —— 与对话一样触发同一 CLI，走完整业务闭环（传统用户可不聊天）。
+2. **运营面**：业务表、状态流向、配置、input/output、日志、HTML —— 看清数据从哪来、到哪去、卡在哪。
+
+**适合：**
+
+- 在业务数据上操作：看队列、选一行重试、勾选批量、顶栏「处理 N 条 / 同步」
+- 已知流程、参数结构化（表单 / 确认 / 一点即跑）——**省 token**，不必每次过模型
+- 准备与执行拆开：表里先准备，再在表上点执行
+- 服务不愿用 AI 对话的用户
+
+**技术自问：** 用户会不会打开这张表，靠点选就把主流程跑完？——要，就挂 `toolbar` / `row` / `batch` / `replaces`，并做好 `_jiangchang_*` 中文元数据。
+
+**不要：** 把数据管理理解成「只给开发者看 SQLite」；也不要在完全没有结构化操作对象时硬造空表按钮。
+
+### 2.3 定时任务——「到点自动发起」
+
+**适合：**
+
+- 同一能力需按节奏重复：消费队列、定期同步、巡检
+- 无人值守：默认参数即可跑，人不在场也正确、安全
+- 与对话 / 数据管理挂**同一个** Action，只改触发方式
+
+**技术自问：** 这件事明天能不能在人不盯着时自动再跑一遍？——能，挂 `cron`；不能，定位表写明不挂及理由。
+
+**慎挂：** 每次对象都不同须人指定；强不可逆且须当场确认；主路径依赖验证码 / 人工介入。
+
+### 2.4 场景对照（贴需求用）
+
+| 若用户场景是… | 优先考虑 | 说明 |
+|---------------|----------|------|
+| 「帮我处理这个……」（临时、口语） | 对话 | 灵活、可追问 |
+| 「对着表点一下就跑」 | 数据管理 | 结构化、省 token、传统用户 |
+| 「每天自动跑，不用我管」 | 定时 | 无人值守 |
+| 「偶尔对话下发，平时表上运营，夜里自动啃队列」 | **多个入口都挂同一能力** | 平级互补，不是重复开发 |
+| 「只看结果，从不在表上触发」 | 表可仅展示；执行挂对话/定时 | 由本技能 UX 定 |
+
+---
+
+## 3. 如何为本技能做入口定位（必做）
+
+模板**不**规定「某类技能必须三入口都挂满」。由技术按**本技能干什么 + 用户体验**填写定位表（写入 [`REQUIREMENTS.md`](REQUIREMENTS.md)）。
+
+对每个**主能力**（一条业务 CLI / 一个 Action）填一行：
+
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|--------------------|
+| （例）`download-run-pick` | 挂 | toolbar | 挂 | — |
+| （例）`download-video` | 挂 | 不挂 | 不挂 | 对象每次不同，须人指定链接 |
+
+**数据管理列怎么写：** `不挂` / `toolbar` / `row` / `batch` / `replaces` / `仅展示表（无业务按钮）`（可组合）。
+
+**规则只有三条：**
+
+1. 定位为「挂」的入口：必须在 `actions.json`（及必要元数据）中声明，且宿主可测通，并走同一内核。
+2. 定位为「不挂」的入口：必须有一句理由；禁止空白「忘了」。
+3. 未来新入口：表上多一列，方法不变。
+
+完整 ≠ 每个命令塞满所有入口；完整 = **想清楚用户路径后，该出现的入口都挂上了，且同内核**。
+
+---
+
+## 4. 怎么挂（最小路径）
+
+| 我想让用户… | 主要改什么 |
+|-------------|------------|
+| 能在对话里触发 | `SKILL.md` 意图路由 + `actions.json` 的 `placements` 含 `agent`（长任务 `async`） |
+| 能在数据管理看见结果 / 过程 | 业务表 + `init-db` + `_jiangchang_*`（见 SCHEMA） |
+| 能在表上点按钮走闭环 | `placements` 含 `toolbar`/`row`/`batch`，`toolbar` 须 `bind.tables` |
+| 能设定时自动跑 | 同一 Action 的 `placements` 含 `cron`；参数适合无人值守 |
+
+细节与 Schema：[`../references/ACTIONS.md`](../references/ACTIONS.md)。运行时：[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)。
+
+---
+
+## 5. 反例（不要这样做）
+
+- 只做对话 Action，从未填写入口定位表，也未考虑数据管理 / 定时用户路径
+- 为 toolbar / cron / agent 复制三套业务实现，或按 `source` 分叉结果
+- 把数据管理当成只读调试窗，主闭环只能聊天完成（若 UX 上本应支持 UI）
+- 不可逆、须确认的主路径默认挂 `cron` 且无产品确认
+- 用「Action 可选 / 定时以后再说」当作「可以不思考入口」
+
+---
+
+## 6. 附录：定位表示例（参考，非强制）
+
+### 示例 A：队列消费类（对话 + 表上处理 + 定时）
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 入队 / 准备 | 挂 | 可 replaces 或表新增 | 不挂 | 准备态由人或对话写入 |
+| 处理 N 条 pending | 挂 | toolbar | 挂 | 运营点选与无人值守同一内核 |
+| 单条立即执行 | 挂 | 可选 row | 不挂 | 对象临时指定 |
+
+### 示例 B：单次确认发布类
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 发布一条 | 挂 | 按是否落草稿表决定 | 不挂 | 不可逆，需人确认；不做无人值守 |
+
+### 示例 C：无库短查询
+
+| 主能力 | 对话 | 数据管理 | 定时 | 理由摘要 |
+|--------|------|----------|------|----------|
+| 查询 | 挂（或短 CLI） | 不挂 | 不挂 | 无本地业务表与重复批跑需求 |
+
+---
+
+## 7. 相关文档
+
+- 需求里填定位表：[`REQUIREMENTS.md`](REQUIREMENTS.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
@@ -9,13 +9,14 @@
 | 步骤 | 做什么 | 详见 |
 |------|--------|------|
 | 1 | **拿到仓库**：① 项目经理在 [自建 Gitea](https://git.jc2009.com/)（`git.jc2009.com`，非 Gitea 官网）开仓并授权后 `git clone`；或 ② 本地已有 `skill-template` 时用 scaffold / 复制出新目录（遵守 Git 红线） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §1、§4 |
-| 2 | **先读 AI + RPA 总纲**；界面技能先完成元素拾取/element map，再按浏览器、桌面或手机读分端手册 | [`AI_RPA.md`](AI_RPA.md)、[`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) |
-| 3 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)，再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) |
-| 4 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 |
-| 5 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 |
-| 6 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 |
-| 7 | 匠厂安装后，按已声明入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) |
-| 8 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) |
+| 2 | **先读宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；为本技能填入口定位表 | [`PRODUCT_SURFACES.md`](PRODUCT_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 |
+| 6 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂默认不公开；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 |
+| 7 | 本地单测（mock）通过后，按业务默认 **`real_rpa`** 真实跑通；再 `release.ps1`；看 Gitea CI。**mock 通 ≠ 完成** | [`ADAPTER.md`](ADAPTER.md)；[`DEVELOPMENT.md`](DEVELOPMENT.md) §15 |
+| 8 | 匠厂安装后，按**入口定位表已挂**的入口自测，并看**用户体验**（进度、失败提示、有头 RPA 等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) |
+| 9 | **交活验收（第三方）**：对照 [`CHECKLIST.md`](CHECKLIST.md) 验收；报告写入仓库根目录 [`acceptance-reports/`](../acceptance-reports/) | [`CHECKLIST.md`](CHECKLIST.md) |

 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。业务仓也可直接从自建 Gitea clone，见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §4 来源 A。

@@ -25,23 +26,24 @@

 开始定制 skill 前，建议按以下顺序阅读：

-1. [`AI_RPA.md`](AI_RPA.md) — **AI Agent + RPA 总纲**：职责边界、合规红线、风控、操作节奏与完整闭环
-2. [`ACCOUNT_MANAGER.md`](ACCOUNT_MANAGER.md) — **浏览器账号标准**：一账号一 Profile、租约、多账号、数据查看、验收与排障
-3. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展）
-4. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准
-5. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读）
-6. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
-7. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
-8. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**）
-9. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
-10. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时的会话、风控和工程总纲
-11. [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) — **所有界面技能必读**：真实拾取、element map、唯一性、降级和 AI 编程约束
-12. 按执行端选读：[`RPA_BROWSER.md`](RPA_BROWSER.md) / [`RPA_DESKTOP.md`](RPA_DESKTOP.md) / [`RPA_MOBILE.md`](RPA_MOBILE.md)
-13. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
-14. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读）
-15. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读）
-16. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
-17. [`CHECKLIST.md`](CHECKLIST.md) — **交活验收清单（第三方视角）**；报告输出到 [`../acceptance-reports/`](../acceptance-reports/)
+1. [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) — **宿主产品入口**：对话 / 数据管理 / 定时任务平级；何时走哪个；入口定位表
+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 等，可扩展）
+5. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准（含入口定位表）
+6. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读）
+7. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
+8. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
+9. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**）
+10. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
+11. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时的会话、风控和工程总纲
+12. [`RPA_ELEMENT_LOCATING.md`](RPA_ELEMENT_LOCATING.md) — **所有界面技能必读**：真实拾取、element map、唯一性、降级和 AI 编程约束
+13. 按执行端选读：[`RPA_BROWSER.md`](RPA_BROWSER.md) / [`RPA_DESKTOP.md`](RPA_DESKTOP.md) / [`RPA_MOBILE.md`](RPA_MOBILE.md)
+14. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
+15. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读）
+16. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读）
+17. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
+18. [`CHECKLIST.md`](CHECKLIST.md) — **交活验收清单（第三方视角）**；报告输出到 [`../acceptance-reports/`](../acceptance-reports/)

 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。  
 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。
--- a/development/REQUIREMENTS.md
+++ b/development/REQUIREMENTS.md
@@ -31,7 +31,23 @@
  - **登记 ≠ 登录**：ensure/add-web 只建账号与 Profile；站点登录由本技能在有头浏览器中完成
  - **反模式**：把「需要登录态才能采到数据」的需求写成 `optional`，再省略 `ensure_logged_in`

-## 0.1 AI + RPA 协作与授权边界（涉及外部系统时必填）
+## 0.1 宿主入口定位（必填）
+
+先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)。对话任务 / 数据管理 / 定时任务在宿主上**平级**；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。
+
+对每个主能力填一行（可增行；「不挂」必须写理由）：
+
+| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
+|---------------------------|------|----------|------|--------------------|
+| （例）`<action-or-cli>` | 挂 / 不挂 | 不挂 / toolbar / row / batch / replaces / 仅展示表 | 挂 / 不挂 | |
+
+说明：
+
+- 数据管理列可写组合（如 `toolbar + row`）
+- 「仅展示表」= 用户要看过程/结果，但不在表上触发该能力
+- 定位为「挂」的入口须在 `assets/actions.json`（及必要表元数据）中落实，并与对话路径共用同一 domain service
+
+## 0.2 AI + RPA 协作与授权边界（涉及外部系统时必填）

 ### Agent 设计

@@ -131,12 +147,13 @@
 - 支持 `python scripts/main.py <your-main-command>`
 - 支持核心业务编排（HTTP / 批处理 / 可选 RPA，按四档 adapter 选型）
 - 支持失败可诊断（统一文件日志 + 任务中心 `finish`）
+- 完成 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md) 入口定位表，并按表落实已挂入口（对话 / 数据管理 / 定时按本技能 UX）

 ### 可后续扩展

- 支持定时批跑
 - 支持失败自动重试
 - 支持多 `<目标系统>` 轮询
+- 入口定位表中已标明「本期不挂」且写了理由的能力（例如暂不挂定时）

 ## 5. 非功能要求

@@ -214,7 +231,7 @@
 - 真实联调样例仍放 `tests/integration/`，默认套件不包含真实外联（与业务 `.env` 默认 `real_rpa` 不冲突）
 - `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID（开发期不公开时，否则本人无法在市场安装自测；取 ID 步骤见 `development/DEVELOPMENT.md` §6）
 - 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
- 安装后按本技能 `actions.json` 声明完成宿主多入口验收（见 `development/DEVELOPMENT.md` §15）；**须看用户体验**（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
+- 安装后按本技能入口定位表与 `actions.json` 声明完成宿主多入口验收（见 `development/DEVELOPMENT.md` §15、`PRODUCT_SURFACES.md`）；**须看用户体验**（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
 - 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号或其他规避平台限制的实现
 - RPA 真实主路径已验证状态等待、`1～3` 秒正常操作节奏、有限重试、账号 / 设备串行、人工介入、结果核验和结束存证
 - RPA 关键元素已在真实界面拾取并登记 element map；关键动作唯一定位，重启会话后复测通过
@@ -304,7 +321,7 @@
 - 命令可运行；tests/run_tests.py -v 通过
 - 业务表（若有）符合 SCHEMA；过程看运行日志，进度看任务中心
 - `developer_ids` 已配置为「你的用户ID」（匠厂设置中复制的正整数）
- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 自测
+- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 与入口定位表自测
 ## 10. 开发注意事项

 - 不修改无关项目；不引入旧模板结构
--- a/development/SKILL_ACTION_RUNTIME.md
+++ b/development/SKILL_ACTION_RUNTIME.md
@@ -2,6 +2,8 @@

 本文是匠厂宿主 **Skill Action / 任务中心** 的技能侧金标准。涉及浏览器 RPA、长耗时任务、数据管理按钮、定时任务或 Agent 直接调用时**必读**。

+**产品入口（平级关系、何时挂哪个）**先读 [`PRODUCT_SURFACES.md`](PRODUCT_SURFACES.md)；本文管 sync/async、任务中心与编排。
+
 **边界：**

 | 文档 | 职责 |