diff --git a/CHANGELOG.md b/CHANGELOG.md index 17cd344..6006d55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,18 +9,16 @@ - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段 +## 1.0.94 + +- 修正 1.0.93 更新日志重复小节 + ## 1.0.93 - 沉淀 Lookup **多选**契约：同一 `lookup` / `options_json` 对象上加 `multiple: true`（平行扩展单选，不另造 display_type） - 多选存 `TEXT` 逗号分隔 id；列表展示映射为多个 label；控件由宿主按选项数量选择（短列表勾选 / 长列表 Chip+下拉） - 更新 SCHEMA / ACTIONS / skill-actions.schema / lookup 示例与 options_json 校验 -## 1.0.93 - -- 沉淀 Lookup **多选**契约：同一 `lookup` / `options_json` 对象加 `multiple: true`，不另造类型 -- 多选存 `TEXT` 逗号分隔 id；短列表勾选 / 长列表 Chip+下拉为宿主渲染策略 -- ACTIONS / SCHEMA / schema / 示例与文档守护对齐 - ## 1.0.92 - 沉淀数据管理 `replaces: import`：导入 UI 统一宿主面板，确认后由技能写库 diff --git a/SKILL.md b/SKILL.md index 9159200..d26b7e2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板（通用业务版） description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.93 +version: 1.0.94 author: 深圳匠厂科技有限公司 metadata: openclaw: diff --git a/references/ACTIONS.md b/references/ACTIONS.md index fb59b7c..5433720 100644 --- a/references/ACTIONS.md +++ b/references/ACTIONS.md @@ -29,6 +29,7 @@ 3. 有可感知副作用时：提供 `confirmation.message` 4. 需要用户/Agent 入参时：简单 `inputSchema` + entrypoint 中的 `{{fieldName}}` 5. `SKILL.md`「用户意图路由表」与 `CLI.md`「Action 强制黑名单」**出现同一 action id / 命令** +6. 若处理的是**业务队列表中的一行**：遵守 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)——默认只捞**可操作**角色；开始抢占为**进行中**；结束回写成功/失败（失败带原因）；确认文案写清仅可操作态可处理 默认模板 `assets/actions.json` 仅含诊断类 sync Action，**不要**为通过本 checklist 而塞假业务 Action；业务技能按需添加。完整字段见下文 Phase 1。 @@ -936,8 +937,12 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展 "pickCount": { "type": "number", "title": "处理数量", - "description": "从队列选取 pending 记录条数", - "default": 1, + "description": "从队列选取「可操作」状态记录的条数（具体状态名由本技能定义，见 WORK_ITEM_STATUS）" + } +} +``` + +默认**不要**把失败/成功/跳过混进该 pick；重做靠人工改回可操作态。详见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)。 "default": 1, "minimum": 1 } } diff --git a/references/README.md b/references/README.md index 45c9dbd..8b2b020 100644 --- a/references/README.md +++ b/references/README.md @@ -21,6 +21,7 @@ | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 | | [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） | | [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理单元格呈现：语义 tone 标色/强调（用途不限；多数技能 P0 不配） | +| [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md) | 业务行生命周期：处理队列的可操作/进行中/终态角色与重做规则（有处理行 Action 时适用） | | [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） | -按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子标色读 `CELL_PRESENTATION.md`。 +按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。 diff --git a/references/SCHEMA.md b/references/SCHEMA.md index 9e1cc6c..2131734 100644 --- a/references/SCHEMA.md +++ b/references/SCHEMA.md @@ -525,6 +525,19 @@ readonly = 0 模板**默认不建**此类审计表。过程看 `jiangchang.log`，进度/终态看任务中心，业务结果看业务表。 +### 业务行生命周期（处理队列） + +若技能对某一业务行做「生成 / 触达 / 私信 / 发布」等有副作用处理，状态字段须遵守 **角色模型**（可操作 / 进行中 / 成功·失败·跳过类终态），**不要**把某一技能的状态名当成全平台唯一枚举。默认只处理可操作态；重做靠人工改回可操作。完整规则见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)。 + +建议： + +| 项 | 说明 | +|----|------| +| 状态列 | `options_json` 列出本技能全部业务状态（含进行中与各类终态） | +| 失败原因 | 失败类终态应有用户可读的原因字段（勿写密钥） | +| 可编辑 | 终态/进行中建议可改回可操作，或提供等价 Action | +| `grid_help` | 可一句话说明「仅某某状态可处理」 | + 表级 `readonly = 1` 时，宿主数据管理只读展示；技能 repository 仍可写入。 ### 通用示例：`demo_items`（测试 fixture 参考） diff --git a/references/WORK_ITEM_STATUS.md b/references/WORK_ITEM_STATUS.md new file mode 100644 index 0000000..4943162 --- /dev/null +++ b/references/WORK_ITEM_STATUS.md @@ -0,0 +1,157 @@ +# 业务行生命周期契约（Work Item Lifecycle） + +> **状态：正式契约 v1.0。** +> **目标：** 冻结「对某一行做有副作用处理」时的**状态角色与操作权**规则，使队列型技能（生成、触达、私信、发布等）行为一致、可验收。 +> **非目标：** 规定某一技能的具体状态码或状态个数；强制所有表都有 status；替代任务中心 / 运行日志；规定 Data Policy 授权。 +> **适用范围：** 有「处理业务行」类 Action 的技能。纯配置表、目录表、只读展示表标 N/A。 + +相关正交轴：[`ACTIONS.md`](ACTIONS.md)（入口与 sync/async）、[`SCHEMA.md`](SCHEMA.md)（表与展示）、[`POLICY.md`](POLICY.md)（谁能点）、任务中心（宿主 Job）。 + +--- + +## 0. 为什么需要本契约 + +若「处理这一行」的按钮对**任意状态**都可点，会出现： + +- 已成功的行被重复执行（重复发信、重复生成、覆盖产物） +- 失败行被默认批量静默重试，运营无法区分「未做」与「做过但失败」 +- 任务中心显示成功，业务表仍停在初始态（结果未回写） + +本契约要求：**默认可自动操作的只有「可操作」角色；其它角色须人工改回可操作后再处理。** + +--- + +## 1. 状态角色（通用，不绑死枚举） + +技能自己定义业务状态字符串与中文标签；契约只认**角色**。一个角色可对应**一个或多个**业务状态。 + +| 角色 | 含义 | 默认可被处理 Action 捞起？ | +|------|------|---------------------------| +| **operable（可操作）** | 尚未成功处理、允许自动或行操作启动处理 | **是（默认唯一）** | +| **in_progress（进行中）** | 已抢占，正在处理 | **否**（防双跑） | +| **terminal_success（成功类终态）** | 已按业务定义完成 | **否** | +| **terminal_failure（失败类终态）** | 已尝试且失败；通常带失败原因 | **否** | +| **terminal_skipped（跳过类终态）** | 人工放弃或不处理 | **否** | + +### 1.1 举例（仅对照，不是规范枚举） + +| 角色 | 技能 A（内容队列）可能叫 | 技能 B（线索触达）可能叫 | +|------|--------------------------|--------------------------| +| operable | 待生成、新建 | 新建、私信未发 | +| in_progress | 生成中 | 触达中 | +| terminal_success | 已生成 | 已私信 | +| terminal_failure | 失败 | 触达失败 | +| terminal_skipped | 已跳过 | 已忽略 | + +技能可以有更多业务状态（审核中、待确认、部分成功等）：须在需求里写明各自映射到哪一角色，或声明「不属于处理队列、本契约 N/A」。 + +### 1.2 技能必须声明映射 + +复制模板后，在 `development/REQUIREMENTS.md`（或等价需求）中写清： + +```text +处理队列表： +状态字段： +可操作：, , … +进行中： +成功类终态：… +失败类终态：…（失败原因字段：…） +跳过类终态：… +``` + +未声明映射的「处理队列」技能，交活 Checklist 不得标 PASS。 + +--- + +## 2. 硬规则（技能实现必须遵守） + +1. **默认只认 operable** + 行操作 / 批量 / 定时 / Agent 触发的「处理」类 Action，pick 与 claim **默认**只包含可操作状态。 + 不得把成功、失败、跳过、进行中混进默认捞取集合（除非另做**显式命名**的「重试失败」类 Action，且确认文案写清范围——仍推荐不如人工改回可操作简单）。 + +2. **开始即原子抢占 → in_progress** + 在真正产生副作用前，用「仅当当前为 operable 时 UPDATE 为进行中」的方式抢占。抢占失败 → 跳过或返回明确错误（如「当前不是可操作状态」），**禁止**继续副作用。 + +3. **结束必须回写业务表** + - 成功 → 对应成功类终态，并写入产物路径/摘要等业务字段（若有） + - 失败 → 对应失败类终态，并写入**失败原因**（用户可读；勿塞密钥） + - 禁止「任务中心成功、业务行仍停在可操作/进行中」而不回写 + +4. **重做靠人工改回 operable** + 成功 / 失败 / 跳过 / 卡住的进行中，默认不能再点处理。运营在数据管理把状态改回可操作后，方可再次处理。 + +5. **任务中心 ≠ 业务状态** + Job「进行中 / 成功 / 失败」是宿主任务态。业务「进行中」必须写在业务表。进度 `emit` 不替代状态回写。 + +6. **过程与结果分工**（延续既有约定） + 过程 → 运行日志 / 任务中心 Activity；业务结果 → 业务表。**不要**靠新建 `task_logs` 一类审计表充当状态机。 + +--- + +## 3. Action 与文案约定 + +- 处理类 Action 的 `description` / `confirmation.message` 应写明：**仅处理「可操作」状态**（用本技能用户能懂的词，如「仅待生成」「仅新建」）。 +- 对非可操作行触发时：返回明确失败码与中文说明，提示「请先改回 xxx」。 +- 长任务（`async`）：除任务中心进度外，业务行应尽快进入进行中，避免界面长时间仍显示可操作导致连点。 + +正交提醒： + +| 轴 | 管什么 | 不管什么 | +|----|--------|----------| +| 本契约 | 什么**状态**能处理 | 谁有权点按钮 | +| Data Policy | 谁有权 | 状态机 | +| executionProfile | sync/async 通道 | 业务终态 | + +--- + +## 4. 数据管理展示建议 + +- 状态列：`options_json` 枚举完整业务状态（含进行中与各类终态）。 +- 失败原因列：失败类终态可见；成功后宜清空或保留末次原因（技能自定，须一致）。 +- 终态与进行中的状态字段建议 **可编辑**（或提供「改回可操作」Action），以便人工重做；**不要**只能靠删行重建。 +- `grid_help` 可一句话写清：「仅某某状态可处理；其它状态请改回后再操作。」 + +详见 [`SCHEMA.md`](SCHEMA.md)。 + +--- + +## 5. 可观测性（与 ACTIONS / 日志约定对齐） + +推荐阶段（名称可自定，须能对应到开始 / 关键节点 / 结束）： + +1. 已抢占（业务 → 进行中） +2. 处理中关键步骤（可 `emit`） +3. 回写成功或失败 + +故意失败一条时：业务表应为失败类终态 + 原因；任务中心为失败；日志含 `task_failed` / `error_code=`。 + +--- + +## 6. 非目标与常见误区 + +| 误区 | 正确做法 | +|------|----------| +| 把「新建/成功/失败/跳过」写成全平台唯一枚举 | 只用角色；各技能自定状态名 | +| 默认批量包含失败「方便自动重试」 | 默认不含；重试改回可操作或单独显式 Action | +| 只有任务成功、不改业务状态 | 必须回写业务表 | +| 用进行中替代任务中心 | 两者都要：业务防双跑，任务轨看进度 | +| 所有表都套本契约 | 无「处理行」副作用的表标 N/A | + +--- + +## 7. 验收摘要（完整条目见 CHECKLIST） + +有处理队列时至少验证： + +1. 成功类终态再点处理 → 拒绝或跳过，不产生重复副作用 +2. 可操作行处理中 → 先见进行中，结束后见成功或失败+原因 +3. 失败行改回可操作后 → 可以再次处理 +4. 任务中心有过程（长任务）且业务表状态与结果一致 + +--- + +## 8. 版本 + +| 版本 | 说明 | +|------|------| +| v1.0 | 首版：角色模型 + 硬规则 + 需求映射 + 与 Action/SCHEMA/任务中心边界 | diff --git a/scripts/util/constants.py b/scripts/util/constants.py index ceb0929..9d4601f 100644 --- a/scripts/util/constants.py +++ b/scripts/util/constants.py @@ -1,6 +1,6 @@ """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。""" SKILL_SLUG = "your-skill-slug" -SKILL_VERSION = "1.0.93" +SKILL_VERSION = "1.0.94" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.11"