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 测试全部通过
This commit is contained in:
skill-dev
188
development/PRODUCT_SURFACES.md
Normal file
188
development/PRODUCT_SURFACES.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 宿主产品入口（对话 / 数据管理 / 定时任务）
|
||||
|
||||
本文给**技能开发者**与 **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
Block a user