# 宿主产品入口（对话 / 数据管理 / 定时任务）

本文给**技能开发者**与 **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` 接管新增·编辑·删除·**导入** —— 与对话一样触发同一 CLI，走完整业务闭环（传统用户可不聊天）。导入按钮的 UX 始终是宿主「导入数据」面板；有 `replaces:import` 时确认后由技能写库。
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)