client-huashang/query-payslip-default
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
query-payslip-default/development/PRODUCT_SURFACES.md
skill-dev 3db196e49d feat: 工资查询助手首版 v1.0.105 
基于 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 测试全部通过
2026-09-07 17:02:05 +08:00

189 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 宿主产品入口（对话 / 数据管理 / 定时任务）
本文给**技能开发者**与 **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. 用户教程如何投影本文
入口定位表填完后，**必须**落到用户市场文档（见 [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)）：
| 定位结果 | `TUTORIAL.md` | `README.md` |
|----------|---------------|-------------|
| 挂数据管理 | 「入口一」专章 + 表/按钮步骤 | 仅一句「支持数据管理」 |
| 挂对话 | 「入口二」专章 + 话术 | 仅一句「支持对话」；**禁止**话术块 |
| 挂定时 | 「入口三」教怎么建 | 可选一句边界 |
| 不挂定时 | 「入口三」写不需要 + 理由 | 可选一句「不提供定时」 |
准备/载入类 Action：优先 `toolbar` + `bind.tables`，避免教程写「技能详情点按钮」而宿主详情页不渲染。
---
## 8. 相关文档
- 需求里填定位表：[`REQUIREMENTS.md`](REQUIREMENTS.md)
- **用户说明 / 教程怎么写：** [`TUTORIAL_SURFACES.md`](TUTORIAL_SURFACES.md)
- 交活怎么验：[`CHECKLIST.md`](CHECKLIST.md)
- 开发步骤中的 Action 挂载：[`DEVELOPMENT.md`](DEVELOPMENT.md) §11.5、§15
- Agent 侧字段契约：[`../references/ACTIONS.md`](../references/ACTIONS.md)
Reference in New Issue View Git Blame Copy Permalink