3db196e49d
基于 skill-template 脚手架开发，包含： - payroll_config（费率配置，可编辑）+ payslip_snapshots（解析历史，只读）2 张业务表 - 全国默认 + 北上广 4 套费率（社保/公积金/个税起征点/7 级税率表） - 5 个业务 Action：calculate-payslip-simple / calculate-payslip-full / explain-term / view-config / edit-config - 个税累计预扣法计算，支持多月历史累加 - 20 个薪资名词库（社保/公积金/个税/全勤/加班费等） - 完整市场文档（README/TUTORIAL/DEMO/CHANGELOG） - 296 测试全部通过
9.6 KiB
宿主产品入口（对话 / 数据管理 / 定时任务）
本文给技能开发者与 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 |
铁律：
- 入口平级：没有「对话主、数据管理/定时辅」。只是触发场景与交互方式不同，各自有优势。
- 同一业务能力、同一 domain service：禁止按入口复制逻辑，禁止按
source分叉业务结果。 - 同能力可挂多个入口：不是三选一；按本技能 UX 决定挂哪些。
- 可扩展：以后若宿主增加新入口，仍是「新触发场景 + 同一内核」，定位方法不变（定位表多一列即可）。
- 任务中心不是业务入口：只表示
executionProfile: async的执行壳；与从哪个入口点进来无关。
2. 什么时候走哪个入口
2.1 对话任务——「用嘴发起」
适合：
- 用户用自然语言描述意图，条件一次说清或还要追问
- 探索式：「能不能帮我……」「先看看再决定」
- 对象临时指定（贴链接、说一个范围）
- 需要 Agent 解释结果、失败原因、下一步
- 用户不想打开数据管理，只想在聊天里办完
技术自问： 用户会不会用一句话说清这件事？需要模型帮理解和确认吗？——会，就为该能力挂 agent（长任务 / RPA 必须 Action + 通常 async；短查询可用共享 Python CLI）。
注意： 若技能还有「对着表运营 / 定时啃队列」等场景，不要把对话当成唯一路径，否则传统用户与省 token 路径会丢掉。
2.2 数据管理——「用界面发起 + 看着数据做」
数据管理有两层，同等重要：
- 执行面：工具栏 / 行级 / 批量 /
replaces接管新增·编辑·删除·导入 —— 与对话一样触发同一 CLI，走完整业务闭环（传统用户可不聊天）。导入按钮的 UX 始终是宿主「导入数据」面板；有replaces:import时确认后由技能写库。 - 运营面：业务表、状态流向、配置、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 / 仅展示表（无业务按钮）（可组合）。
规则只有三条：
- 定位为「挂」的入口：必须在
actions.json（及必要元数据）中声明，且宿主可测通，并走同一内核。 - 定位为「不挂」的入口：必须有一句理由；禁止空白「忘了」。
- 未来新入口：表上多一列，方法不变。
完整 ≠ 每个命令塞满所有入口；完整 = 想清楚用户路径后，该出现的入口都挂上了，且同内核。
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