query-payslip-default/development/PRODUCT_SURFACES.md

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

本文给技能开发者与 AI 编程助手读：说明匠厂宿主上几个平级业务入口各自干什么、什么时候走哪个、以及如何为本技能做入口定位。

字段怎么写见 ../references/ACTIONS.md、../references/SCHEMA.md；任务中心 / sync·async 见 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）。

对每个主能力（一条业务 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。运行时：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. 用户教程如何投影本文

入口定位表填完后，必须落到用户市场文档（见 TUTORIAL_SURFACES.md）：

定位结果	TUTORIAL.md	README.md
挂数据管理	「入口一」专章 + 表/按钮步骤	仅一句「支持数据管理」
挂对话	「入口二」专章 + 话术	仅一句「支持对话」；禁止话术块
挂定时	「入口三」教怎么建	可选一句边界
不挂定时	「入口三」写不需要 + 理由	可选一句「不提供定时」

准备/载入类 Action：优先 toolbar + bind.tables，避免教程写「技能详情点按钮」而宿主详情页不渲染。

---

8. 相关文档

• 需求里填定位表：REQUIREMENTS.md
• 用户说明 / 教程怎么写： TUTORIAL_SURFACES.md
• 交活怎么验：CHECKLIST.md
• 开发步骤中的 Action 挂载：DEVELOPMENT.md §11.5、§15
• Agent 侧字段契约：../references/ACTIONS.md