diff --git a/CHANGELOG.md b/CHANGELOG.md index 43c1d74..3eaa6e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ - 小节正文写用户能看懂的变化(新能力、修复、注意事项),避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节;找不到匹配小节时,本次发布不会更新 changelog 字段 +## 1.0.96 + +- 在 `references/ACTIONS.md` 沉淀数据管理技能按钮中文名(`label`)参考表:同类通用动作用同一动词,不是白名单 +- 打开类改为「打开目录 / 打开浏览器」,一点即开、成功不弹「执行成功」;示例不再使用「打开文件位置」 +- 交活 Checklist A7-7;POLICY_MATRIX 软规则:不扫描 label 关键字 + ## 1.0.95 - 正式沉淀「业务行生命周期」通用契约(`references/WORK_ITEM_STATUS.md`):用可操作/进行中/成功·失败·跳过类终态等**角色**约束处理队列,不绑死某一技能的状态名 diff --git a/SKILL.md b/SKILL.md index 11f1b8f..1c7457f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板(通用业务版) description: "OpenClaw 通用业务技能开发模板,供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.95 +version: 1.0.96 author: 深圳匠厂科技有限公司 metadata: openclaw: diff --git a/development/CHECKLIST.md b/development/CHECKLIST.md index afb9233..3951e21 100644 --- a/development/CHECKLIST.md +++ b/development/CHECKLIST.md @@ -145,6 +145,7 @@ checklist_version: 1.0 - [ ] A7-4 **P1** 关键步骤有据可查(能对应到开始/关键节点/结束;RPA 宜有多个 `stage=`) - [ ] A7-5 **P1** 若宣称支持录屏或截图存证:打开开关后关键步骤或失败能留下可查看产物;宣称支持却完全无产物 → **FAIL** - [ ] A7-6 **P2** 用户可见文案偏业务语言,而非大段开发黑话 +- [ ] A7-7 **P2** 数据管理技能按钮(toolbar / row / batch)中文名对照 `references/ACTIONS.md`「Action 按钮中文名」;不与宿主「查看 / 编辑 / 删除」抢名;打开类成功不弹成功条。行业专有按钮名可自创 --- diff --git a/development/POLICY_MATRIX.md b/development/POLICY_MATRIX.md index fed04c6..1c34bfa 100644 --- a/development/POLICY_MATRIX.md +++ b/development/POLICY_MATRIX.md @@ -67,6 +67,7 @@ | `SKILL.md` / `constants.SKILL_SLUG` 一致性 | development/DEVELOPMENT.md §16 | 已有 `tests/test_skill_metadata.py` | | platform_kit_min_version >= 1.2.11 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` | | 宿主按 `bind.tables` 过滤 toolbar 按钮 | references/ACTIONS.md | 待宿主升级后完整生效;模板侧已强制显式绑定 | +| 数据管理技能按钮中文名(`label`)对照 ACTIONS.md 建议表;打开类成功静默 | references/ACTIONS.md「Action 按钮中文名」 | 参考非白名单;行业词允许自创;勿做 label 关键字扫描 | | Data Policy 未启用(L0)时宿主不得拉 Snapshot / 不得改按钮与行列行为 | references/POLICY.md | soft;宿主实现契约 | | Data Policy 启用后 fail-closed(禁止回退 L0 全开);写路径 domain 必须再鉴权 | references/POLICY.md §6–§7 | soft;`POLICY-SKILL-AUTHZ-*` 硬门禁可后续加 | | `actions.mode` 仅 allowlist/open;`hostCapabilities` 省略=不限制;scope `valueFrom` 仅 `actor.userId` | references/POLICY.md §0.1 | soft;Schema 已约束 | diff --git a/development/SKILL_ACTION_RUNTIME.md b/development/SKILL_ACTION_RUNTIME.md index 6e08632..2d8dec1 100644 --- a/development/SKILL_ACTION_RUNTIME.md +++ b/development/SKILL_ACTION_RUNTIME.md @@ -9,7 +9,7 @@ | 文档 | 职责 | |------|------| | 本文 | sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出 | -| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen` | +| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen`、**按钮中文名 `label` 参考** | | [`LOGGING.md`](LOGGING.md) | `job_context` / `emit` / `finish` / Run Journal | | [`DATA_PATHS.md`](DATA_PATHS.md) | 下载/导入等落盘路径 | diff --git a/references/ACTIONS.md b/references/ACTIONS.md index 0ca8bc2..d47b067 100644 --- a/references/ACTIONS.md +++ b/references/ACTIONS.md @@ -329,16 +329,16 @@ Action 是否提供、挂哪些 `placements`,由本技能 **入口定位表** | 值 | 数据管理体验 | 典型场景 | |----|--------------|----------| -| `direct` | **一点即跑**,无弹窗 | 打开文件位置、无参只读、行内主键已映射 | -| `confirm` | 轻量确认弹窗(无参数区;文案优先 `confirmation.message`) | 打开浏览器、有副作用但无可编辑入参 | +| `direct` | **一点即跑**,无弹窗 | 打开目录、打开浏览器、无参只读、行内主键已映射 | +| `confirm` | 轻量确认弹窗(无参数区;文案优先 `confirmation.message`) | 处理待发送、删除前确认、有副作用但无可编辑入参 | | `form` | 完整参数表单(现状默认路径) | 导入、查询条件、需用户改写的字段 | | `auto` / 省略 | 宿主推断:有**可编辑**参数 → `form`;仅有 `confirmation` → `confirm`;否则 → `direct` | 旧技能兼容;新技能建议显式写出 | ```json { "id": "reveal-profile", - "label": "打开文件位置", - "description": "在资源管理器中打开 Profile 目录。", + "label": "打开目录", + "description": "打开该账号的浏览器 Profile 目录。", "placements": ["row"], "executionProfile": "sync", "interaction": "direct", @@ -365,10 +365,10 @@ Action 是否提供、挂哪些 `placements`,由本技能 **入口定位表** { "id": "open-browser", "label": "打开浏览器", + "description": "用该账号持久化 Profile 打开系统浏览器,仅供肉眼核对。", "placements": ["row"], - "executionProfile": "async", - "interaction": "confirm", - "confirmation": { "message": "将用该账号 Profile 打开浏览器,仅供查看。" }, + "executionProfile": "sync", + "interaction": "direct", "bind": { "tables": ["accounts"], "inputMapping": { "accountId": "$row.$pk" } @@ -377,7 +377,7 @@ Action 是否提供、挂哪些 `placements`,由本技能 **入口定位表** "type": "object", "required": ["accountId"], "properties": { - "accountId": { "type": "number", "readOnly": true } + "accountId": { "type": "number", "title": "账号 ID", "readOnly": true } } }, "entrypoint": { @@ -396,6 +396,39 @@ Action 是否提供、挂哪些 `placements`,由本技能 **入口定位表** - **cron 触发 / agent**:忽略 `interaction`(无人值守 / 模型填参);`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`;显式 `direct` + 可编辑字段时参数取 default/预填,作者须自觉。 +## Action 按钮中文名(`label`,参考) + +`label` 是数据管理 **toolbar / row / batch** 以及技能详情直调上用户看见的短按钮名。本节是**参考契约,不是白名单**:行业专有动作(私信、审单、报关登记等)按业务起名。同类通用动作尽量用同一动词,避免每个技能一套叫法。 + +**写法:** 短中文,动词或「动词 + 对象」(约 2~8 字)。同一能力用**一个** Action 换 `placements`,不要为入口复制同义按钮。 + +以后增补:在下表加行,并在模板 `CHANGELOG.md` 记一笔。废弃说法挪到「不要叫」,不要直接删行。 + +### 宿主已有,技能不要再做一套同义按钮 + +数据管理宿主已提供:**查看 / 编辑 / 删除 / 新增 / 导入 / 导出 / 刷新**。 + +技能要用 CLI 接管增删改导入时用 `replaces`(见上文),**不要**再把同义按钮挂到 `placements: ["row"]` 或 `toolbar`(例如「编辑平台」「删除 Key」与底下宿主「编辑」「删除」叠两套)。用户仍点宿主那几个字。 + +### 建议动词(有则用之) + +| 类型 | 建议 `label` | 不要叫 | 说明 | +|------|----------------|--------|------| +| 基础设施 | 运行检查、查看版本、查看配置位置、初始化数据 | 健康检查、版本信息、配置路径、初始化数据库 | 多挂 `skill-detail` | +| 打开 | 打开浏览器、打开目录、打开文件 | 打开文件位置、在资源管理器中打开、用浏览器打开 | 见下节静默成功 | +| 改库 | 新增…、编辑…、删除…、启用/停用、设置默认…、加入待…、重置为待… | 表记录用「添加」;无必要拆成「启用」「停用」两个按钮 | 对象名可带,如「新增账号」 | +| 外源入库 | 同步数据、全量同步、采集…、扫描… | 把宿主「刷新」叫成同步;把导出 CSV 叫成同步 | 默认用「同步数据」;全量才写「全量同步」 | +| 队列与探测 | 处理待…、测试 API、测试网页、抽检本条、抽检所选、批量抽检 | 行 / 勾选 / 工具栏三个入口都叫「抽检」 | 行=本条,勾选=所选,不管勾选的批量=批量 | +| 生成发布 | 生成 HTML、生成…、发布到… | 用「导出」代替宿主表导出 | 固定 id `render-html` 的 label 用「生成 HTML」 | + +### 打开类:一点即开,成功不提示 + +打开目录 / 打开浏览器 / 打开文件:`interaction: "direct"`,`executionProfile` 通常 `"sync"`。 + +- **成功**:不要输出用户可见成功文案。若打印 JSON,令 `"message": ""`(宿主据此不弹「执行成功」)。操作系统已经弹出目录或浏览器,就是反馈。 +- **失败**:仍 `ERROR::`(可加 `HINT:`)。 +- **不要**用宿主「查看」表示打开目录或浏览器——「查看」是只读详情。 + ## `hoverHint`(工具栏悬停,可选) 与 `label` / `description` / `confirmation.message` **独立**。只决定数据管理**顶栏技能按钮**鼠标悬停时显示什么。 @@ -584,6 +617,7 @@ python {skill_root}/scripts/main.py - 使用稳定的退出码 - 成功时输出可解析的结构化结果 +- **例外(打开类)**:打开目录 / 打开浏览器 / 打开文件成功时不要输出用户可见成功文案;若打印 JSON,令 `"message": ""`。失败仍走下一款错误约定 - 失败时输出稳定错误信息 - 对可预期错误提供稳定错误码 - 对用户可处理的问题提供 `HINT` diff --git a/references/README.md b/references/README.md index 8b2b020..8619000 100644 --- a/references/README.md +++ b/references/README.md @@ -17,7 +17,7 @@ | 根目录 [`CHANGELOG.md`](../CHANGELOG.md) | 市场更新日志 Tab(版本小节 → `changelog`) | | [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 | | [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 | -| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口(按入口定位表挂载;先读 `development/PRODUCT_SURFACES.md`) | +| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口、按钮中文名 `label` 参考(按入口定位表挂载;先读 `development/PRODUCT_SURFACES.md`) | | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 | | [`POLICY.md`](POLICY.md) | Data Policy:可选身份授权、Snapshot、行 scope(多数技能 L0 不配) | | [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理单元格呈现:语义 tone 标色/强调(用途不限;多数技能 P0 不配) | diff --git a/scripts/util/constants.py b/scripts/util/constants.py index 8e3b752..2141baf 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.95" +SKILL_VERSION = "1.0.96" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.11"