From 8570d5803dfbce3114871edadd58cc3fb56a4749 Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Mon, 20 Jul 2026 09:20:38 +0800 Subject: [PATCH] docs(development): clarify onboarding, developer_ids self-test, host multi-entry QA --- CHANGELOG.md | 5 ++ SKILL.md | 5 +- development/DEVELOPMENT.md | 123 ++++++++++++++++++++-------- development/README.md | 58 ++++++++----- development/REQUIREMENTS.md | 15 ++-- development/SKILL_ACTION_RUNTIME.md | 16 ++-- scripts/util/constants.py | 2 +- 7 files changed, 155 insertions(+), 69 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d8df1a1..e22813d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段 +## 1.0.52 + +- 开发文档补齐全流程：Gitea 克隆与本地模板复制两种拿仓方式；`developer_ids` 作为开发期自测通行证（下载安装注册 → 设置复制用户 ID） +- 发布后宿主验收明确覆盖新建任务、数据管理、定时任务与任务中心；`development/README` 增加步骤索引 + ## 1.0.51 - 沉淀网页 RPA 首启标准：业务技能默认 `ensure-web`（有则用、无则登记）；登记账号 ≠ 已登录目标站；租约全忙返回占用错误且不重复建号 diff --git a/SKILL.md b/SKILL.md index b700fe2..54ee678 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板（通用业务版） description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.51 +version: 1.0.52 author: 深圳匠厂科技有限公司 metadata: openclaw: @@ -150,6 +150,7 @@ python {baseDir}/scripts/main.py init-db ## 平台元数据 -- `metadata.openclaw.developer_ids`：技能发布后的默认开发者可见用户 ID 列表。 +- `metadata.openclaw.developer_ids`：技能发布后的默认开发者可见用户 ID 列表（ID 来自匠厂宿主「设置 → 用户信息」）。 +- 开发期技能常为不公开：不加本人 ID，开发者自己也无法在市场安装自测。取 ID 与写入步骤见 `development/DEVELOPMENT.md` §6。 - 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。 - `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。 diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index bc8e4fe..5066368 100644 --- a/development/DEVELOPMENT.md +++ b/development/DEVELOPMENT.md @@ -77,13 +77,21 @@ `skill-template` 不是业务 skill，它只是一个**新 skill 仓库模板**。 -你不应该直接在这个仓库里开发业务，而应该： +你不应该直接在这个仓库里开发业务。新技能仓库有**两种合法来源**（详见 §4「第一步」）： -0. 按 [`NAMING.md`](NAMING.md) 确定 slug（`{verb}-{noun-phrase}-{platform}`） -1. **优先**用 [`tools/scaffold_skill.ps1`](../tools/scaffold_skill.ps1) 创建新目录（见 [`tools/README.md`](../tools/README.md)） -2. 在新目录内 `git init` 并绑定**本技能**远端（**不得**保留模板 `.git`） -3. 把占位内容替换掉 -4. 再开始写业务逻辑 +| 来源 | 适用情况 | 怎么做 | +|------|----------|--------| +| **A. Gitea 克隆** | 项目经理已在 [git.jc2009.com](https://git.jc2009.com/) 开好业务仓并给你权限 | `git clone` 到本地后按 [`REQUIREMENTS.md`](REQUIREMENTS.md) 开发 | +| **B. 本地模板复制** | 你本机已有 `skill-template` 源码，要新建尚未灌仓的技能目录 | **优先** [`tools/scaffold_skill.ps1`](../tools/scaffold_skill.ps1)（见 [`tools/README.md`](../tools/README.md)）；也可手工复制但必须清掉模板 `.git` | + +拿到仓库后的推荐顺序： + +0. 按 [`NAMING.md`](NAMING.md) 确定 / 核对 slug（`{verb}-{noun-phrase}-{platform}`） +1. **先填写**本仓 [`REQUIREMENTS.md`](REQUIREMENTS.md)（范围与验收），再写业务代码 +2. 来源 B：在新目录内 `git init` 并绑定**本技能**远端（**不得**保留模板 `.git`） +3. 把占位内容替换掉；**尽早**配置 `developer_ids`（见 §6，开发期宿主自测必做） +4. 再实现 `scripts/service/` 等业务逻辑 +5. 本地测试通过 → `release.ps1` → Gitea CI → 匠厂多入口验收（§15） > **Git 红线**：禁止资源管理器整文件夹复制后保留模板 `.git`；`git remote -v` 必须指向新技能仓库，不能仍是 skill-template。 @@ -256,13 +264,26 @@ release workflow 会对 `scripts/` 下的 Python 源码做加密/打包。当前 下面这套顺序建议严格按步骤做，不要一上来就直接写 `service`。 -### 第一步：复制模板并改目录名 +### 第一步：拿到新技能仓库（两种来源） -例如你要开发 `disburse-payroll-icbc` 一类领域 skill（目录名 = slug）： +例如你要开发 `disburse-payroll-icbc` 一类领域 skill（目录名 = slug）。下列两种来源**同等合法**，按你实际拿到仓库的方式选一条。 -#### 推荐方式（首选） +#### 来源 A：从 Gitea 克隆（项目经理已开仓） -在 **skill-template 仓库根目录**执行： +1. 确认项目经理已在 [https://git.jc2009.com/](https://git.jc2009.com/) 创建**本技能**仓库，并给你拉取/推送权限。 +2. 克隆到本地（示例）： + +```powershell +git clone https://git.jc2009.com//.git +cd +git remote -v # 确认 origin 指向本技能仓，不是 skill-template +``` + +3. 若仓内已是从本模板 scaffold 好的结构，直接进入「第二步」与 [`REQUIREMENTS.md`](REQUIREMENTS.md)；**不要**再整仓复制 `skill-template` 覆盖，以免冲掉已有提交或串 Git 历史。 + +#### 来源 B：本地已有 skill-template 时复制 / scaffold + +在 **skill-template 仓库根目录**执行（推荐）： ```powershell .\tools\scaffold_skill.ps1 -Slug disburse-payroll-icbc -Destination D:\OpenClaw\client-gdcm\disburse-payroll-icbc @@ -276,7 +297,7 @@ git remote -v # 确认 origin 不是 skill-template 脚手架会排除 `.git`、缓存与 `.env`，并删除 `.openclaw-skill-template` 标记；**不会**自动 `git init`。 -#### 禁止方式 +##### 禁止方式（来源 B） | 做法 | 后果 | |------|------| @@ -284,7 +305,7 @@ git remote -v # 确认 origin 不是 skill-template | ❌ 保留模板 `.git` 只改 `remote url` | 历史、分支、对象库仍属 template | | ❌ 未删 `.git` 就 `git init` | 嵌套/混乱仓库，难以排查 | -#### 若已手工复制（补救） +##### 若已手工复制（补救） ```powershell cd <新技能目录> @@ -296,7 +317,7 @@ git remote add origin <新技能仓库 URL> git remote -v ``` -#### AI / 编程代理复制红线 +##### AI / 编程代理复制红线 | 禁止 | 说明 | |------|------| @@ -309,7 +330,7 @@ git remote -v ### 第二步：先改 4 个最关键的标识 -复制后优先改下面这些地方： +拿到仓库并填好 / 更新 [`REQUIREMENTS.md`](REQUIREMENTS.md) 后，优先改下面这些地方： 1. `SKILL.md` 2. 根目录市场四 Tab：`README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md` @@ -325,7 +346,7 @@ git remote -v - 平台内部键 - 日志 logger 名 -此外，如果该技能发布后默认不公开（`access_scope = 0`），建议一开始就把 `SKILL.md` 中的 `metadata.openclaw.developer_ids` 配好。这样后续发布到平台时，开发者本人仍能在技能市场中看到并验证该技能。 +**开发 / 联调阶段务必尽早**配置 `SKILL.md` 中的 `metadata.openclaw.developer_ids`（完整目的与取 ID 步骤见 §6「关于 developer_ids」）。开发期技能在匠厂常为不公开；不加本人用户 ID，**技术人员自己也无法在技能市场看到并安装自测**。 ## 5. 哪些占位内容必须替换 @@ -385,14 +406,28 @@ git remote -v - `references/`（CLI / SCHEMA） - 代码注释与 `service/` 实现 -### 关于 `metadata.openclaw.developer_ids` +### 关于 `metadata.openclaw.developer_ids`（开发自测必做） -这是一个平台发布元数据字段，用于解决下面这个问题： +#### 目的（先理解再填） -- 技能发布后若平台记录中的 `access_scope = 0`，技能默认不公开 -- 如果不额外授权，连开发者自己也可能在技能市场里看不到这个技能 +开发 / 测试阶段，技能 `release` 到匠厂后，平台侧通常为**不公开**（`access_scope = 0`）： -因此可以在 `SKILL.md` 中声明： +- 技能市场里对普通人**不可见** +- **若不额外授权，连开发该技能的技术人员自己也看不见、装不了** +- 看不见 → 无法安装 → 无法在宿主做 §15 的多入口验收（新建任务、数据管理、定时任务等） + +因此 `developer_ids` 不是可有可无的装饰字段，而是**开发期自测通行证**：把本人（及需要一起验收的同事）的匠厂**用户 ID** 写进 `SKILL.md`，发布时平台将这些用户补进可见 / 可访问范围，使开发者能在「对其他人仍不可见」的前提下完成安装与测试。 + +#### 如何获取匠厂用户 ID（完整步骤） + +1. **下载并安装**匠厂客户端：[https://jc2009.com/product.html](https://jc2009.com/product.html) +2. **注册并登录**（使用将用于开发自测的账号） +3. 打开客户端左下角头像旁的**设置**（齿轮） +4. 在 **用户信息** 中查看 **用户 ID**（正整数），点击旁边的 **复制** +5. 将该 ID 写入本技能 `SKILL.md` 的 `metadata.openclaw.developer_ids`（见下例） +6. **必须替换**模板里的示例 ID（如 `10032`、`12428` 等占位），不要原样留着模板作者的 ID 却指望自己账号能看见技能 + +#### 在 `SKILL.md` 中声明 ```yaml metadata: @@ -400,17 +435,17 @@ metadata: slug: your-skill-slug category: 通用 developer_ids: - - 1032 - - 12428 + - 12580 # 换成你在匠厂「设置 → 用户信息」复制的用户 ID ``` -约定如下： +约定如下（原有规则保留）： -- 只允许填写正整数用户 ID +- 只允许填写正整数用户 ID（来自匠厂宿主，不是 Gitea / Git 账号名） - 推荐使用数组，即使当前只有 1 个开发者 - 发布时平台会把这些用户自动补写到 `skill_user_access` - 第一个 ID 会同步到 `skills.developer_id` - 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权 +- **首次正式 release 前**就应配好；配错或漏配时，CI 可能成功，但你在技能市场仍找不到技能 ## 7. 文档目录分工 @@ -789,9 +824,11 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - 工作流文件是否存在 - 发布包结构是否符合模板规范 -### 第四步：进入匠厂平台下载安装包 +### 第四步：进入匠厂客户端（用于安装验收） -当工作流成功后，就可以进入匠厂平台验证最终安装效果。 +当工作流成功后，就可以进入匠厂客户端验证最终安装效果。 + +若你已按 §6 为 `developer_ids` 安装并登录过匠厂，**直接使用同一客户端、同一账号**即可，无需重复下载。若尚未安装： 匠厂产品下载地址： @@ -803,11 +840,13 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea 匠厂产品页可从这里进入：[产品下载 - 匠厂](https://jc2009.com/product.html) -### 第五步：安装匠厂后，在技能市场检查最新 skill +> 取用户 ID 写入 `developer_ids` 的完整步骤见 §6；此处侧重发布后的安装验收。 -安装并启动匠厂后，进入左侧“技能市场”，搜索或查找刚刚发布的 skill，确认以下内容： +### 第五步：在技能市场检查最新 skill -- 技能可以被正常检索到 +使用已写入 `developer_ids` 的账号登录并启动匠厂后，进入左侧“技能市场”，搜索或查找刚刚发布的 skill，确认以下内容： + +- 技能可以被正常检索到（开发期不公开时，**仅** `developer_ids` 内账号可见） - 技能名称、说明、版本信息正确 - 最新版本已经同步出来 - 可以正常安装或更新 @@ -826,11 +865,25 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - 安装后状态正常 - 不会出现缺文件、缺入口或安装失败的问题 -### 第七步：在“新建任务”中实际使用该 skill +### 第七步：按声明做宿主多入口验收（不要只测对话） -安装完成后，不要只停留在“已安装”状态，还需要进入“新建任务”页面，真正调用一次该 skill，完成最终验证。 +安装完成后，不要只停留在“已安装”状态。宿主侧栏有多条与技能相关的入口；**按本技能 `assets/actions.json` 的 `placements` / `executionProfile` 声明逐项测**（契约细节见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。未声明的入口可以跳过；**已声明却测不到，视为验收失败**。 -建议至少验证： +| 宿主入口（侧栏 / 界面） | 技能侧如何挂上 | 建议验收什么 | +|-------------------------|----------------|--------------| +| **新建任务**（对话 Agent） | `placements` 含 `agent`；或短查询走共享 Python CLI | 自然语言能触发主流程；长任务 / RPA 须走 `run_skill_action`，禁止 bash 干等 | +| **数据管理** | `placements` 含 `toolbar`（须合法非空 `bind.tables`）；表数据来自技能本地库 / `init-db` | 左侧能看到本技能库表；表顶栏出现对应按钮；点按后行为符合预期 | +| **定时任务** | `placements` 含 `cron`（创建时选「技能直调」） | 能选到本技能 Action、保存并触发；到点或「立即运行」行为正确 | +| **任务中心** | 不是 placement；由 `executionProfile: "async"` 决定是否进 Job | 长任务出现进度 / 可取消；来源标签与触发入口一致（对话 / 数据管理 / 定时等） | +| **技能市场 → 技能详情** | 安装与四 Tab 文案；`placements` 含 `skill-detail` 为契约预留 | **必验**：安装、说明 / 教程 / 演示 / 更新日志。详情页「技能直调」按钮：当前宿主 UI **尚未落地**（manifest 可写 `skill-detail`，勿仅依赖该入口做主验收） | + +补充说明： + +- **进不进任务中心只看 `executionProfile`**，与从新建任务、数据管理还是定时任务触发无关（既有正交规则不变）。 +- 数据管理还依赖库表元数据（`_jiangchang_*` 等，见 [`../references/SCHEMA.md`](../references/SCHEMA.md)）；仅有 Action、没有可展示库表时，侧栏可能看不到表。 +- 模板对 `row` / `batch` 的约定仍见 [`../references/ACTIONS.md`](../references/ACTIONS.md)（示例请勿使用）；宿主能力以匠厂版本为准，新技能主路径仍以文档已稳定描述的 `toolbar` / `cron` / `agent` 为准。 + +**新建任务（对话）最小检查：** - 新任务中可以正常选择或触发该 skill - skill 能被正确唤起 @@ -841,6 +894,8 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea ![新建任务中使用技能](../assets/screenshots/new-task-usage.png) +若第五步在技能市场**搜不到**本技能：先核对登录账号的用户 ID 是否已写入 `developer_ids` 并随本次 release 发布（见 §6）；不要只反复重装客户端。 + ## 16. 发布前检查清单 每个新 skill 发布前，建议技术人员逐条确认： @@ -849,6 +904,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - [ ] slug 符合 [`NAMING.md`](NAMING.md)（verb-noun-platform） - [ ] 目录名、`SKILL.md` slug、`constants.SKILL_SLUG` 三者一致 - [ ] `SKILL.md` 中 slug、名称、描述都已替换 +- [ ] `SKILL.md` 的 `developer_ids` 已换成**本人**匠厂用户 ID（设置 → 用户信息 → 复制），不是模板示例 ID - [ ] `scripts/util/constants.py` 已修改 - [ ] `../references/CLI.md` 示例命令已改成真实命令 - [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现 @@ -868,7 +924,8 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - [ ] 如有 integration 测试需求，已写在 `tests/integration/` 下并保持 `.sample` 后缀 - [ ] 本仓库**不是** skill-template 的误复制（根目录**无** `.openclaw-skill-template`） - [ ] `git remote -v` 指向**本技能**远端，URL 不含 skill-template 仓库名 -- [ ] `git log` 首条提交属于本技能（非模板历史） +- [ ] `git log` 首条提交属于本技能（非模板历史）（来源 A 从 Gitea 克隆的已有业务仓，以该仓历史为准） +- [ ] 发布后计划在宿主按 §15 第七步验收：已声明的 **新建任务 / 数据管理 / 定时任务 / 任务中心(async)** 均已覆盖 - [ ] 网页 RPA：`ensure-web` 取得 `profile_dir` 再开浏览器；`.env` 默认有头；REQUIREMENTS 写明登录策略（required/optional/not_needed，会话依赖型勿抄 optional）；用户 README/TUTORIAL 区分「登记账号」与「站点登录」（`RPA.md` §0.2 / `POLICY-RPA-004`）；依赖 kit 空值解析等修复时上调 `platform_kit_min_version` ## 17. 常见错误 diff --git a/development/README.md b/development/README.md index 4e7fd40..beea49e 100644 --- a/development/README.md +++ b/development/README.md @@ -1,20 +1,38 @@ -# 开发资料入口 - -本目录面向**人类开发者**与 **AI 编程代理**。开始定制 skill 前，建议按以下顺序阅读： - -1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准 -2. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读） -3. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范 -4. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关 -5. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**） -6. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时 -7. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时 -8. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制 -9. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读） -10. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读） -11. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定 - -脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。 - -Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。 -用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。 +# 开发资料入口 + +本目录面向**人类开发者**与 **AI 编程代理**。技术人员与编程 AI **以本目录为主读路径**；`references/` 是 CLI / Action / Schema 契约细节，根目录市场四 Tab 面向最终用户。 + +## 新技能全流程（先看这张表） + +按顺序做；细节与约束见 [`DEVELOPMENT.md`](DEVELOPMENT.md) 对应章节（**不替代**下文深度规范，只作导航）。 + +| 步骤 | 做什么 | 详见 | +|------|--------|------| +| 1 | **拿到仓库**：① 项目经理在 [Gitea](https://git.jc2009.com/) 开仓并授权后 `git clone`；或 ② 本地已有 `skill-template` 时用 scaffold / 复制出新目录（遵守 Git 红线） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §1、§4 | +| 2 | 按 [`NAMING.md`](NAMING.md) 确认 slug；**先填** [`REQUIREMENTS.md`](REQUIREMENTS.md)，再写业务代码 | [`REQUIREMENTS.md`](REQUIREMENTS.md)、[`NAMING.md`](NAMING.md) | +| 3 | 替换标识与占位，按四象限 / examples 实现 `scripts/service/` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §4～§14 | +| 4 | **配置 `developer_ids`（开发自测必做）**：开发期技能在匠厂常不可见；不加则开发者自己也装测不了。从宿主设置复制用户 ID 写入 `SKILL.md` | [`DEVELOPMENT.md`](DEVELOPMENT.md) §6「关于 developer_ids」 | +| 5 | 本地 `python tests/run_tests.py -v` 通过后执行 `release.ps1`；看 Gitea CI | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15 | +| 6 | 匠厂技能市场安装后，按声明测：**新建任务(Agent)** / **数据管理** / **定时任务** / **任务中心**(async) | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；契约见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) | + +脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。 + +## 深度规范阅读顺序 + +开始定制 skill 前，建议按以下顺序阅读： + +1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准 +2. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读） +3. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范 +4. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关 +5. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**） +6. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时 +7. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时 +8. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制 +9. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读） +10. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读） +11. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定 + +Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。 +用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。 + \ No newline at end of file diff --git a/development/REQUIREMENTS.md b/development/REQUIREMENTS.md index 7cce087..e26efa5 100644 --- a/development/REQUIREMENTS.md +++ b/development/REQUIREMENTS.md @@ -171,14 +171,16 @@ - 字段展示顺序与 `PRAGMA table_info(task_logs)` 的 cid 一致；不依赖 `display_order` - `tests/test_display_metadata.py` 通过 - 真实联调（如有）放在 `tests/integration/`，且默认套件不包含真实外联 -- 发布后 Gitea 工作流成功；匠厂技能市场可见最新版本；安装后可在“新建任务”中调用 +- `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID（开发期不公开时，否则本人无法在市场安装自测；取 ID 步骤见 `development/DEVELOPMENT.md` §6） +- 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装 +- 安装后按本技能 `actions.json` 声明完成宿主多入口验收：至少覆盖已声明的「新建任务(Agent)」；若声明了 `toolbar` / `cron` / `async`，还须分别验收数据管理、定时任务、任务中心（见 `development/DEVELOPMENT.md` §15 第七步） ## 10. 开发注意事项 - 只修改当前 skill 仓库，不要改动无关兄弟项目 - 先判断四象限类型（`real_browser_rpa` / `real_api` / `simulator_browser_rpa` / `simulator_api`），再读对应 `examples/*/README.md` - `cli` 只做参数解析；核心逻辑在 `service`；兄弟 skill 调用集中封装（见 `ADAPTER.md`） -- 发布前完成本地验证、工作流验证和正式环境安装验证 +- 发布前完成本地验证、工作流验证和正式环境安装验证（含 `developer_ids` 与宿主多入口） ## 11. 变更记录 @@ -190,10 +192,11 @@ ## 建议使用方式 -1. 先写 `REQUIREMENTS.md` -2. 再按 `DEVELOPMENT.md` 进入开发 -3. 开发过程中补充 `references/CLI.md`、`references/SCHEMA.md` 及 `development/` 技术规范 -4. 发布前对照第 9 节验收标准逐项检查 +1. 拿到业务技能仓库（Gitea clone，或本地从 `skill-template` scaffold / 复制；见 `DEVELOPMENT.md` §4） +2. 先写 / 填全本文件 `REQUIREMENTS.md` +3. 再按 `DEVELOPMENT.md` 进入开发（含尽早配置 `developer_ids`） +4. 开发过程中补充 `references/CLI.md`、`references/SCHEMA.md` 及 `development/` 技术规范 +5. 发布前对照第 9 节验收标准逐项检查；release 后按 `DEVELOPMENT.md` §15 做宿主多入口验收 ## 最小模板示例 diff --git a/development/SKILL_ACTION_RUNTIME.md b/development/SKILL_ACTION_RUNTIME.md index 7f82163..6432cf9 100644 --- a/development/SKILL_ACTION_RUNTIME.md +++ b/development/SKILL_ACTION_RUNTIME.md @@ -62,14 +62,16 @@ 多个入口统一走 `POST /api/skill-actions/run`，可能带 `source.kind`： -| 入口 | 常见 `source.kind` | 说明 | -|------|-------------------|------| -| **Agent** | `agent` | `run_skill_action`；按 manifest 的 executionProfile 执行 | -| **数据管理** | `data-management` | toolbar 按钮；须 `bind.tables` | -| **定时任务** | `cron` | Cron 配置参数后调用同一 Action | -| **技能详情** | （依宿主） | 与上同一 CLI / 同一业务内核 | +| 入口（匠厂侧栏 / 界面） | 常见 `source.kind` | 技能侧 | 开发者怎么测 | +|-------------------------|-------------------|--------|--------------| +| **新建任务**（对话 Agent） | `agent` | `placements` 含 `agent`；`run_skill_action` | 侧栏「新建任务」→ 对话触发；按 manifest 的 executionProfile 执行 | +| **数据管理** | `data-management` | `placements` 含 `toolbar`；须 `bind.tables` | 侧栏「数据管理」→ 打开本技能表 → 点表顶栏技能按钮 | +| **定时任务** | `cron` | `placements` 含 `cron` | 侧栏「定时任务」→ 新建「技能直调」并选本 Action | +| **任务中心** | （各入口触发的 Job） | `executionProfile: "async"` | 侧栏「任务中心」查看进度 / 取消；**不是** placement | +| **技能详情** | `skill-detail`（预留） | `placements` 可含 `skill-detail` | 市场详情四 Tab / 安装必验；详情页直调按钮宿主 UI **尚未落地**，主验收勿只靠此入口 | -技能 **不要** 在 Python 里按 `source` / placement 写业务分叉；宿主读 manifest 分流展示与等待策略。 +技能 **不要** 在 Python 里按 `source` / placement 写业务分叉；宿主读 manifest 分流展示与等待策略。 +发布后按入口逐项验收的操作清单见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §15 第七步。 --- diff --git a/scripts/util/constants.py b/scripts/util/constants.py index b6ba12c..19ecf69 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.51" +SKILL_VERSION = "1.0.52" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.2"