diff --git a/CHANGELOG.md b/CHANGELOG.md index e22813d..1ad608b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段 +## 1.0.53 + +- 宿主入口对齐：`row` / `batch` 升格为正式 placements；支持 `bind.inputMapping` 与 `readOnly`；已声明入口均须自测（含技能详情直调） +- 开发文档：自建 Gitea（git.jc2009.com）与 scaffold 双来源；`developer_ids` 示例改为占位「你的用户ID」；压缩 AI 工具章节 + ## 1.0.52 - 开发文档补齐全流程：Gitea 克隆与本地模板复制两种拿仓方式；`developer_ids` 作为开发期自测通行证（下载安装注册 → 设置复制用户 ID） diff --git a/SKILL.md b/SKILL.md index 54ee678..a0adad0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板（通用业务版） description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.52 +version: 1.0.53 author: 深圳匠厂科技有限公司 metadata: openclaw: @@ -25,7 +25,7 @@ allowed-tools: ### 架构铁律（先读） - **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。 -- **`placements`**：只决定 Action **出现在哪里**（toolbar / cron / agent / skill-detail）。 +- **`placements`**：只决定 Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail）。 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。 - **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。 - **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；特殊业务报告才另做 `export-*`。 diff --git a/assets/README.md b/assets/README.md index 0543ebb..2106efe 100644 --- a/assets/README.md +++ b/assets/README.md @@ -4,7 +4,7 @@ - `examples/`：CLI 成功输出形状示例（虚构路径与数据）。 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**；`task-log-record.schema.json` 等）。 -`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）；`row`/`batch` placements 与 `concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。 +`skill-actions.schema.json` 使用 `additionalProperties: false`。正式支持 `bind.tables`（toolbar Action 必填）与可选 `bind.inputMapping`；placements 含 `toolbar` / `row` / `batch` / `cron` / `agent` / `skill-detail`（对齐匠厂宿主）。`concurrency`/`locks` 仍为预留。`placements` 与 `executionProfile` 正交——进任务中心只看 `async`，与入口无关。表级 Action 与 Agent 契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)；开发深度规范见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。 - 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md) - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)） diff --git a/assets/schemas/skill-actions.schema.json b/assets/schemas/skill-actions.schema.json index 4fbb978..a6d9933 100644 --- a/assets/schemas/skill-actions.schema.json +++ b/assets/schemas/skill-actions.schema.json @@ -26,7 +26,7 @@ "placement": { "type": "string", "enum": ["toolbar", "row", "batch", "cron", "agent", "skill-detail"], - "description": "稳定支持 toolbar/cron/agent/skill-detail；row/batch 为预留入口，新技能示例不得使用。placements 与 executionProfile 正交，不做条件限制。" + "description": "稳定支持 toolbar/row/batch/cron/agent/skill-detail（对齐匠厂宿主）。placements 与 executionProfile 正交，不做条件限制。" }, "scalarArg": { "type": ["string", "number", "boolean"] @@ -48,7 +48,11 @@ "type": "array", "minItems": 1 }, - "sensitive": { "type": "boolean" } + "sensitive": { "type": "boolean" }, + "readOnly": { + "type": "boolean", + "description": "宿主数据管理表单只读展示该字段（仍会随提交传入 entrypoint）；用于行内/勾选预填的主键等" + } } }, "inputSchema": { @@ -110,10 +114,15 @@ "pattern": "^[a-z][a-z0-9_]*$", "description": "英文 snake_case 业务表名；须真实存在于技能 SQLite / _jiangchang_tables" }, - "description": "数据管理表级绑定：决定 toolbar Action 出现在哪些表。宿主兼容旧技能时，缺失 bind 可视为全表展示；新技能 toolbar Action 必须显式声明。" + "description": "数据管理表级绑定：决定 toolbar/row/batch Action 出现在哪些表。宿主兼容旧技能时，缺失 bind 可视为全表展示；新技能 toolbar Action 必须显式声明。" + }, + "inputMapping": { + "type": "object", + "additionalProperties": { "type": "string", "minLength": 1 }, + "description": "可选。将 $row.$pk / $row.col / $selection.ids 等映射到 inputSchema 字段名，供 row/batch 预填。" } }, - "description": "Phase 1 仅沉淀 bind.tables；不包含 selection/inputMapping/columns/row/concurrency/locks" + "description": "表级绑定；toolbar 必填。可选 inputMapping 供行内/批量预填。concurrency/locks 勿写入。" }, "action": { "type": "object", diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index 5066368..f34cacc 100644 --- a/development/DEVELOPMENT.md +++ b/development/DEVELOPMENT.md @@ -1,6 +1,6 @@ # 技能开发教程 -这份文档是给**技术人员**看的，目标不是解释概念，而是让你拿到 `skill-template` 后，可以**一步一步开发出一个新的 skill**。 +这份文档是给**技术人员**看的，目标不是解释概念，而是让你拿到**业务技能仓库**后，可以**一步一步开发出一个新的 skill**。 本文默认你开发的是当前最常见的一类业务 skill： @@ -13,65 +13,16 @@ ## 推荐 AI 开发工具 -当前 skill 开发建议尽量配合 AI 编程工具使用。这样做不是为了替代技术人员，而是为了提升以下环节的效率： +建议用 AI 编程工具辅助搭目录、补样板、写测试与排错。团队宜统一 1～2 个主力，避免协作习惯发散。 -- 搭建标准目录结构 -- 生成样板代码 -- 理解旧项目代码 -- 批量补文档、注释和测试 -- 辅助排查报错与重构代码 +| 场景 | 建议 | +|------|------| +| 一体化 IDE | Cursor 或 Windsurf | +| 终端深度代理 | Claude Code 或 Aider | +| 国内生态 | Trae / 通义灵码 | +| VS Code 插件 | GitHub Copilot 或 Cline | -建议团队统一选择 1 到 2 个主力工具长期使用，避免每个人工具链差异太大，导致协作方式不一致。 - -下面先列国外主流工具，再列国内主流工具。链接优先使用官方站点、官方文档或官方安装入口。 - -### 国外主流工具 - -| 工具 | 类型 | 适合场景 | 官方入口 | -|------|------|----------|----------| -| Cursor | 独立 AI IDE | 代码编辑、Agent 开发、整仓理解 | 官网 / 下载 | -| Windsurf | 独立 AI IDE | Agent 编程、项目生成、连续开发流 | 文档 / 下载 | -| GitHub Copilot | IDE 插件 / 编程助手 | 日常补全、解释代码、生成函数、配合 VS Code 或 JetBrains 使用 | 官网 | -| Claude Code | 终端 / IDE 编程代理 | 命令行开发、代码库分析、自动改代码、运行命令 | 官网 / 文档 | -| Codex | 终端 / IDE / Web 编程代理 | OpenAI 官方编码代理，适合代码生成、理解、调试、评审 | 官网 / 快速开始 | -| Aider | 终端 AI 编程工具 | 已有代码仓库的增量开发、终端协作、快速提交 | 官网 / 文档 | -| Cline | VS Code / JetBrains 插件 | 编辑器内 Agent 开发、命令执行、浏览器联动调试 | 官网 / 文档 / VS Code 插件 | - -### 国内主流工具 - -| 工具 | 类型 | 适合场景 | 官方入口 | -|------|------|----------|----------| -| Trae | 独立 AI IDE | AI 辅助写代码、项目搭建、对话式开发 | 官网 / 下载 | -| 通义灵码 | 独立 IDE / IDE 插件 | 国内团队日常编码、问答、补全、代码生成 | 官网 / 下载 | -| CodeGeeX | IDE 插件 / 开源助手 | 代码补全、生成、注释、跨语言辅助 | GitHub / VS Code 插件 | -| 腾讯 CodeBuddy | IDE 插件 | 代码补全、测试生成、智能问答、腾讯云开发体系协作 | 官网 / 文档 / VS Code 插件 | -| 百度文心快码（Baidu Comate） | IDE 插件 | 国内研发团队辅助编码、解释、测试、优化 | 官网 | - -### 选型建议 - -如果你们团队主要做这类 Python skill 开发，我建议这样选： - -- 想要一体化最强体验：优先试 `Cursor` 或 `Windsurf` -- 想要命令行深度协作：优先试 `Claude Code` 或 `Aider` -- 想继续基于 VS Code 插件体系：优先试 `GitHub Copilot`、`Cline`、`通义灵码`、`CodeBuddy` -- 想优先使用国内生态与中文支持：优先试 `Trae`、`通义灵码`、`CodeGeeX`、`CodeBuddy`、`文心快码` - -### 团队落地建议 - -为了减少培训成本，建议内部至少统一一套主工具方案： - -- 国外方案：`Cursor` + `Claude Code` -- 国内方案：`Trae` + `通义灵码` -- VS Code 插件方案：`GitHub Copilot` + `Cline` - -不建议每位技术人员完全自由发挥，否则后续在： - -- 提示词写法 -- 代码修改习惯 -- 调试方式 -- 提交节奏 - -这些方面会越来越不统一。 +官方下载与文档以各产品站点为准；技能开发步骤以本文与同目录规范为准，不依赖某一家工具的专有流程。 ## 1. 先理解模板的定位 @@ -81,7 +32,7 @@ | 来源 | 适用情况 | 怎么做 | |------|----------|--------| -| **A. Gitea 克隆** | 项目经理已在 [git.jc2009.com](https://git.jc2009.com/) 开好业务仓并给你权限 | `git clone` 到本地后按 [`REQUIREMENTS.md`](REQUIREMENTS.md) 开发 | +| **A. Gitea 克隆** | 项目经理已在自建 Gitea（[https://git.jc2009.com/](https://git.jc2009.com/)，**不是** Gitea 官网）开好业务仓并给你权限 | `git clone` 到本地后按 [`REQUIREMENTS.md`](REQUIREMENTS.md) 开发 | | **B. 本地模板复制** | 你本机已有 `skill-template` 源码，要新建尚未灌仓的技能目录 | **优先** [`tools/scaffold_skill.ps1`](../tools/scaffold_skill.ps1)（见 [`tools/README.md`](../tools/README.md)）；也可手工复制但必须清掉模板 `.git` | 拿到仓库后的推荐顺序： @@ -270,7 +221,7 @@ release workflow 会对 `scripts/` 下的 Python 源码做加密/打包。当前 #### 来源 A：从 Gitea 克隆（项目经理已开仓） -1. 确认项目经理已在 [https://git.jc2009.com/](https://git.jc2009.com/) 创建**本技能**仓库，并给你拉取/推送权限。 +1. 确认项目经理已在自建 Gitea（[https://git.jc2009.com/](https://git.jc2009.com/)，公司基于开源 Gitea 自建的代码仓库，**不要**访问 Gitea 官网当作业务仓地址）创建**本技能**仓库，并给你拉取/推送权限。 2. 克隆到本地（示例）： ```powershell @@ -328,7 +279,7 @@ git remote -v 目录名要和 skill slug 对齐，后面很多地方都依赖这个命名。 -### 第二步：先改 4 个最关键的标识 +### 第二步：先改关键标识与占位 拿到仓库并填好 / 更新 [`REQUIREMENTS.md`](REQUIREMENTS.md) 后，优先改下面这些地方： @@ -410,7 +361,7 @@ git remote -v #### 目的（先理解再填） -开发 / 测试阶段，技能 `release` 到匠厂后，平台侧通常为**不公开**（`access_scope = 0`）： +开发 / 测试阶段，技能 `release` 到匠厂后，平台侧**默认不公开**（`access_scope = 0`）： - 技能市场里对普通人**不可见** - **若不额外授权，连开发该技能的技术人员自己也看不见、装不了** @@ -435,7 +386,7 @@ metadata: slug: your-skill-slug category: 通用 developer_ids: - - 12580 # 换成你在匠厂「设置 → 用户信息」复制的用户 ID + - 12345 # 换成「你的用户ID」（匠厂「设置 → 用户信息」复制的正整数） ``` 约定如下（原有规则保留）： @@ -779,7 +730,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea .\release.ps1 ``` -如果你的技能使用了 `metadata.openclaw.developer_ids`，那么这一步触发的发布工作流除了同步 `skills` / `skill_versions` 外，还会在平台侧自动补开发者可见权限。测试非公开技能时，建议重点验证这部分是否生效。 +发布前 **`developer_ids` 应已配置**（见 §6）。本步触发的发布工作流除了同步 `skills` / `skill_versions` 外，还会在平台侧自动补开发者可见权限；发布后应重点确认：用本人账号能在技能市场看到并安装该技能。 这一步会自动完成标准发布动作，包括： @@ -865,23 +816,25 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - 安装后状态正常 - 不会出现缺文件、缺入口或安装失败的问题 -### 第七步：按声明做宿主多入口验收（不要只测对话） +### 第七步：按声明做宿主多入口验收（已声明的入口都要测） -安装完成后，不要只停留在“已安装”状态。宿主侧栏有多条与技能相关的入口；**按本技能 `assets/actions.json` 的 `placements` / `executionProfile` 声明逐项测**（契约细节见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)）。未声明的入口可以跳过；**已声明却测不到，视为验收失败**。 +安装完成后，不要只停留在“已安装”状态。宿主侧栏有多条与技能相关的入口；**按本技能 `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` 含 `toolbar`（须合法非空 `bind.tables`） | 左侧能看到本技能库表；表顶栏出现按钮；点按行为符合预期 | +| **数据管理 · 行内** | `placements` 含 `row`（建议 `bind.tables` + `bind.inputMapping` 预填主键） | 行内操作链接可见（需有主键列）；点按后入参/行为正确 | +| **数据管理 · 批量** | `placements` 含 `batch` | 勾选行后批量按钮可用；无勾选时禁用；批量行为正确 | | **定时任务** | `placements` 含 `cron`（创建时选「技能直调」） | 能选到本技能 Action、保存并触发；到点或「立即运行」行为正确 | -| **任务中心** | 不是 placement；由 `executionProfile: "async"` 决定是否进 Job | 长任务出现进度 / 可取消；来源标签与触发入口一致（对话 / 数据管理 / 定时等） | -| **技能市场 → 技能详情** | 安装与四 Tab 文案；`placements` 含 `skill-detail` 为契约预留 | **必验**：安装、说明 / 教程 / 演示 / 更新日志。详情页「技能直调」按钮：当前宿主 UI **尚未落地**（manifest 可写 `skill-detail`，勿仅依赖该入口做主验收） | +| **任务中心** | 不是 placement；由 `executionProfile: "async"` 决定是否进 Job | 长任务出现进度 / 可取消；来源标签与触发入口一致 | +| **技能市场 → 技能详情** | `placements` 含 `skill-detail`（详情直调） | **必验**安装与四 Tab。详情页「技能直调」按钮随宿主版本上线；**已声明则须在具备该 UI 的宿主上完成按钮自测**（与其它入口同等对待，不要只靠 Agent） | 补充说明： -- **进不进任务中心只看 `executionProfile`**，与从新建任务、数据管理还是定时任务触发无关（既有正交规则不变）。 +- **进不进任务中心只看 `executionProfile`**，与从哪个入口触发无关（既有正交规则不变）。 - 数据管理还依赖库表元数据（`_jiangchang_*` 等，见 [`../references/SCHEMA.md`](../references/SCHEMA.md)）；仅有 Action、没有可展示库表时，侧栏可能看不到表。 -- 模板对 `row` / `batch` 的约定仍见 [`../references/ACTIONS.md`](../references/ACTIONS.md)（示例请勿使用）；宿主能力以匠厂版本为准，新技能主路径仍以文档已稳定描述的 `toolbar` / `cron` / `agent` 为准。 +- `row` / `batch` / `toolbar` / `cron` / `agent` / `skill-detail` 均以**当前匠厂宿主已实现能力**为准；字段与示例见 [`../references/ACTIONS.md`](../references/ACTIONS.md)。 **新建任务（对话）最小检查：** @@ -925,7 +878,7 @@ uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-relea - [ ] 本仓库**不是** skill-template 的误复制（根目录**无** `.openclaw-skill-template`） - [ ] `git remote -v` 指向**本技能**远端，URL 不含 skill-template 仓库名 - [ ] `git log` 首条提交属于本技能（非模板历史）（来源 A 从 Gitea 克隆的已有业务仓，以该仓历史为准） -- [ ] 发布后计划在宿主按 §15 第七步验收：已声明的 **新建任务 / 数据管理 / 定时任务 / 任务中心(async)** 均已覆盖 +- [ ] 发布后计划在宿主按 §15 第七步验收：已声明的 **新建任务 / 数据管理(toolbar|row|batch) / 定时任务 / 任务中心(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/POLICY_MATRIX.md b/development/POLICY_MATRIX.md index 43c4bbc..30bd7ec 100644 --- a/development/POLICY_MATRIX.md +++ b/development/POLICY_MATRIX.md @@ -35,7 +35,7 @@ | POLICY-SKILL-ACTION-001 | 存在 `development/SKILL_ACTION_RUNTIME.md`；schema 含 `executionProfile`；业务技能（非模板占位 slug）若 service 含 `RpaVideoSession` 则 `actions.json` 须有 `executionProfile=async` 且 placements 含 `agent` 的 action | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md | hard | 文档/schema/manifest 检查 | `tests/test_development_policy_guard.py::TestPolicySkillAction001` | | POLICY-SKILL-ACTION-002 | 每个 Action 必须显式声明 `executionProfile`，且只能是 `sync` 或 `async` | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema required + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction002`；`tests/test_actions_manifest.py` | | POLICY-SKILL-ACTION-003 | toolbar Action 必须声明合法非空 `bind.tables`（snake_case、唯一） | references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | schema if/then + manifest 扫描 | `tests/test_development_policy_guard.py::TestPolicySkillAction003`；`tests/test_actions_manifest.py` | -| POLICY-SKILL-ACTION-004 | `placements` 与 `executionProfile` 正交；文档不得把数据管理入口与异步执行方式硬绑定；Schema 须接受 toolbar/cron/agent/skill-detail × sync/async 全部组合 | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 4×2 矩阵校验 + 文档禁止短语扫描 | `tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations`；`tests/test_development_policy_guard.py::TestPolicySkillAction004` | +| POLICY-SKILL-ACTION-004 | `placements` 与 `executionProfile` 正交；文档不得把数据管理入口与异步执行方式硬绑定；Schema 须接受 toolbar/row/batch/cron/agent/skill-detail × sync/async 全部组合 | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md；assets/schemas/skill-actions.schema.json | hard | Schema 6×2 矩阵校验 + 文档禁止短语扫描 | `tests/test_actions_manifest.py::test_schema_allows_all_placement_execution_profile_combinations`；`tests/test_development_policy_guard.py::TestPolicySkillAction004` | | POLICY-ARCH-CORE-001 | 同一业务能力的 Action、CLI、Agent、cron、数据管理入口复用同一业务内核（文档要求已声明） | development/DEVELOPMENT.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；真实复用靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyArchCore001`；`tests/samples/test_action_core_contract.py.sample` | | POLICY-DATA-SYNC-001 | 同步型业务须遵循幂等、事务、完整性与空结果保护（文档已声明） | references/SCHEMA.md；development/SKILL_ACTION_RUNTIME.md | hard（文档标记） / soft（语义） | 文档关键表述存在性；完整语义靠 sample/review | `tests/test_development_policy_guard.py::TestPolicyDataSync001`；`tests/samples/test_sync_contract.py.sample` | diff --git a/development/README.md b/development/README.md index beea49e..5ee5640 100644 --- a/development/README.md +++ b/development/README.md @@ -1,38 +1,37 @@ -# 开发资料入口 - -本目录面向**人类开发者**与 **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 +# 开发资料入口 + +本目录面向**人类开发者**与 **AI 编程代理**。技术人员与编程 AI **以本目录为主读路径**；`references/` 是 CLI / Action / Schema 契约细节，根目录市场四 Tab 面向最终用户。 + +## 新技能全流程（先看这张表） + +按顺序做；细节与约束见 [`DEVELOPMENT.md`](DEVELOPMENT.md) 对应章节（**不替代**下文深度规范，只作导航）。 + +| 步骤 | 做什么 | 详见 | +|------|--------|------| +| 1 | **拿到仓库**：① 项目经理在 [自建 Gitea](https://git.jc2009.com/)（`git.jc2009.com`，非 Gitea 官网）开仓并授权后 `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 | 匠厂安装后，按 `actions.json` **已声明的全部入口**自测（新建任务、数据管理含 toolbar/row/batch、定时任务、任务中心、技能详情等） | [`DEVELOPMENT.md`](DEVELOPMENT.md) §15；[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) | + +脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。业务仓也可直接从自建 Gitea clone，见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §4 来源 A。 + +## 深度规范阅读顺序 + +开始定制 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)，不要写进本目录。 diff --git a/development/REQUIREMENTS.md b/development/REQUIREMENTS.md index e26efa5..e97c2c0 100644 --- a/development/REQUIREMENTS.md +++ b/development/REQUIREMENTS.md @@ -257,8 +257,8 @@ - 命令可运行；tests/run_tests.py -v 通过 - task_logs 符合 SCHEMA -- 正式环境安装验证通过 - +- `developer_ids` 已配置为「你的用户ID」（匠厂设置中复制的正整数） +- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 自测 ## 10. 开发注意事项 - 不修改无关项目；不引入旧模板结构 diff --git a/development/SKILL_ACTION_RUNTIME.md b/development/SKILL_ACTION_RUNTIME.md index 6432cf9..0ec7109 100644 --- a/development/SKILL_ACTION_RUNTIME.md +++ b/development/SKILL_ACTION_RUNTIME.md @@ -52,7 +52,7 @@ | `health` / `version` / `config-path` / 纯统计 / 秒级查询 | `sync` | | 任意 placement（含 toolbar） | 允许 sync 或 async；以 manifest 为准 | -合法：`sync|async` × `toolbar|cron|agent|skill-detail`。 +合法：`sync|async` × `toolbar|row|batch|cron|agent|skill-detail`。 历史说明：旧文档曾错误地把数据管理按钮入口与异步执行方式绑死。该约束**已废止**；模板测试与 Schema **不得**再建立「入口位置决定 sync/async」一类硬耦合。旧版宿主曾「省略 → async」；**当前宿主为「省略 → sync」**。新技能仍须显式声明，不得依赖省略行为。 @@ -64,14 +64,16 @@ | 入口（匠厂侧栏 / 界面） | 常见 `source.kind` | 技能侧 | 开发者怎么测 | |-------------------------|-------------------|--------|--------------| -| **新建任务**（对话 Agent） | `agent` | `placements` 含 `agent`；`run_skill_action` | 侧栏「新建任务」→ 对话触发；按 manifest 的 executionProfile 执行 | -| **数据管理** | `data-management` | `placements` 含 `toolbar`；须 `bind.tables` | 侧栏「数据管理」→ 打开本技能表 → 点表顶栏技能按钮 | -| **定时任务** | `cron` | `placements` 含 `cron` | 侧栏「定时任务」→ 新建「技能直调」并选本 Action | +| **新建任务**（对话 Agent） | `agent` | `placements` 含 `agent`；`run_skill_action` | 侧栏「新建任务」→ 对话触发 | +| **数据管理 · 顶栏** | `data-management` | `toolbar` + 必填 `bind.tables` | 侧栏「数据管理」→ 表顶栏按钮 | +| **数据管理 · 行内** | `data-management` | `row`（建议 `bind.tables` + `inputMapping`） | 同行操作链接（需主键） | +| **数据管理 · 批量** | `data-management` | `batch` | 勾选行后点批量按钮 | +| **定时任务** | `cron` | `placements` 含 `cron` | 侧栏「定时任务」→「技能直调」 | | **任务中心** | （各入口触发的 Job） | `executionProfile: "async"` | 侧栏「任务中心」查看进度 / 取消；**不是** placement | -| **技能详情** | `skill-detail`（预留） | `placements` 可含 `skill-detail` | 市场详情四 Tab / 安装必验；详情页直调按钮宿主 UI **尚未落地**，主验收勿只靠此入口 | +| **技能详情** | `skill-detail` | `placements` 含 `skill-detail` | 市场详情安装/四 Tab；详情直调按钮随宿主上线后**同等自测** | 技能 **不要** 在 Python 里按 `source` / placement 写业务分叉；宿主读 manifest 分流展示与等待策略。 -发布后按入口逐项验收的操作清单见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §15 第七步。 +**已声明的入口都要自测**，不要只测对话。操作清单见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §15 第七步。 --- @@ -83,7 +85,8 @@ |-------------|-------------------------|-----------------|----------------| | 运行检查 / 版本 / 配置路径 | `sync` | `skill-detail`, `agent` | 无 | | 库 / 队列统计 | `sync` | `skill-detail`, `agent` | 无 | -| 外源 → 本地库同步 | `sync` 或 `async` | 可含 `toolbar`（须 `bind.tables`）、`cron`、`agent` | 可选 | +| 外源 → 本地库同步 | `sync` 或 `async` | 可含 `toolbar`（须 `bind.tables`）、`cron`、`agent`、`skill-detail` | 可选 | +| 单行 / 批量数据管理动作 | `sync` 或 `async` | `row` / `batch`（建议 `bind.tables`；行内常用 `inputMapping`） | 可选 | | 数据导入 / 失败重置 | `sync` 或 `async` | `skill-detail`, `agent` | 可选 | | **单条**副作用 RPA | `async`（建议） | `agent`, `skill-detail` | **建议** | | **批量顺序** RPA（pick） | `async`（建议） | `toolbar`, `cron`, `agent` | **建议** | diff --git a/references/ACTIONS.md b/references/ACTIONS.md index ab49b8c..a5d5379 100644 --- a/references/ACTIONS.md +++ b/references/ACTIONS.md @@ -80,7 +80,7 @@ Action 是**可选能力**： | 字段 / 层 | 只决定什么 | 不决定什么 | |-----------|------------|------------| -| **`placements`** | Action **出现在哪里**（toolbar / cron / agent / skill-detail …） | 不决定 sync/async | +| **`placements`** | Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail） | 不决定 sync/async | | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 | | **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口 | | **`entrypoint`** | 实际执行哪个 CLI 命令与参数 | 不写业务逻辑 | @@ -95,9 +95,9 @@ Action 是**可选能力**： | 顶层 | `schemaVersion`、`skill`、`actions` | | action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`bind`** | | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） | -| placements | `toolbar`、`skill-detail`、`agent`、`cron` | -| **bind** | `{ "tables": ["business_table"] }`（见下节） | -| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive` | +| placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron` | +| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`（行内/批量预填，见下节） | +| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly` | | confirmation | `{ "message": "..." }` | | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） | @@ -113,14 +113,16 @@ Action 是**可选能力**： 规则： -- `bind` 为 object，`additionalProperties: false`；当前只允许 `tables`。 +- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`。 - `tables` 非空数组、元素唯一、英文 **snake_case**、不得为空字符串。 - **`placements` 含 `toolbar` 时必须显式声明非空 `bind.tables`**（模板 Schema `if/then` + 自动测试强制）。 +- `row` / `batch` **建议**同样声明 `bind.tables`，避免在无关表上露出按钮；未声明时宿主可能按兼容逻辑在更多表上展示。 - 表名须真实存在于技能 SQLite 与 `_jiangchang_tables`。 - 希望出现在多张表时，显式列出所有表；**不要**依赖「无 bind 则全表展示」——那是宿主对**旧技能**的兼容，不是新技能标准。 -- 本阶段**不**扩展 `selection` / `inputMapping` / `columns` / row binding / concurrency / locks。 +- **`inputMapping`（可选）**：把行/勾选映射到 `inputSchema` 字段，例如 `"leadId": "$row.$pk"`、`"ids": "$selection.ids"`。适合 `row` / `batch`。宿主仍会提交这些字段；可用 `inputSchema.properties.*.readOnly: true` 在表单中只读展示。 +- `concurrency` / `locks` 仍未稳定，**不要**写入新技能 manifest。 -默认模板 `actions.json` 仅含 `health` / `version` / `config-path`，不放在 toolbar，故无需 `bind` 示例污染默认 manifest。业务示例： +默认模板 `actions.json` 仅含 `health` / `version` / `config-path`，不放在 toolbar/row/batch，故无需 `bind` 示例污染默认 manifest。业务示例： ```json { @@ -134,16 +136,42 @@ Action 是**可选能力**： } ``` +行内示例： + +```json +{ + "id": "retry-one", + "label": "重试本行", + "description": "对当前行执行一次业务重试。", + "placements": ["row"], + "executionProfile": "async", + "bind": { + "tables": ["business_records"], + "inputMapping": { "recordId": "$row.$pk" } + }, + "inputSchema": { + "type": "object", + "required": ["recordId"], + "properties": { + "recordId": { "type": "string", "title": "记录 ID", "readOnly": true } + } + }, + "entrypoint": { + "type": "cli", + "command": "retry", + "args": ["--id", "{{recordId}}"] + } +} +``` + ## 预留能力（当前不可当作已实现能力） | 类别 | 预留项 | 说明 | |------|--------|------| -| placements | `row`、`batch` | 行内 / 批量入口，未来扩展；新技能示例不得使用 | | action 字段 | `concurrency`、`locks` | 并发与锁控制，未稳定开放 | | inputSchema | `array`、nested `object`、`oneOf` 等 | 复杂表单，不属于当前推荐范围 | -`bind` **不是**保留字段；已作为 Phase 1 表级绑定正式能力。 - +`bind`、`row`、`batch` **不是**保留能力；已按匠厂宿主正式支持写入本规范。 ## 执行模型 宿主将 action 转为 argv，再用**共享 Python**（用户数据目录下 `python-runtime/.venv`）执行： @@ -168,7 +196,7 @@ python {skill_root}/scripts/main.py | `sync`（或省略时的宿主缺省） | 调用方等待结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 不进 | | `async`（须显式声明） | 宿主创建后台 Job，立即返回 `jobId`；用 `emit` / `checkpoint` / `finish` 报告进度与终态 | **进入** | -合法组合（全部允许）：`sync|async` × `toolbar|cron|agent|skill-detail`。 +合法组合（全部允许）：`sync|async` × `toolbar|row|batch|cron|agent|skill-detail`。 经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，用 `async`；其余默认写 `sync`。 @@ -199,26 +227,27 @@ HINT: | 值 | 含义 | |----|------| -| `toolbar` | 数据管理第一排技能按钮（须配合 `bind.tables`） | -| `skill-detail` | 技能详情或技能市场详情页 | +| `toolbar` | 数据管理表顶栏技能按钮（须配合 `bind.tables`） | +| `row` | 数据管理行内操作（建议 `bind.tables` + `inputMapping`；表需有主键） | +| `batch` | 数据管理批量操作（需勾选行；无勾选时宿主禁用按钮） | +| `skill-detail` | 技能详情页直调（与安装/四 Tab 同属技能市场详情；已声明则须自测） | | `agent` | Agent 可直接调用（`run_skill_action`） | -| `cron` | 定时任务可直接调用 | - -**预留（模板示例请勿使用）：** `row`、`batch`。 +| `cron` | 定时任务「技能直调」 | ### Action 类型 × placements（常见示例，不是限制） -下表只表示**常见用法示例**。实际 `placements` 以 manifest 配置为准；**`sync` / `async` 不影响展示入口**。 +下表只表示**常见用法示例**。实际 `placements` 以 manifest 配置为准；**`sync` / `async` 不影响展示入口**。已声明的入口都要在宿主自测，不要只测其中一条。 | Action 类型 | 常见 executionProfile | 常见 placements | confirmation | |-------------|----------------------|-----------------|--------------| | health / version / config-path | sync | skill-detail, agent | 无 | | 统计 / 只读查询 | sync | skill-detail, agent | 无 | | 数据同步（外源 → 本地库） | sync 或 async | toolbar + cron + agent + skill-detail（按需） | 可选 | +| 单行重试 / 行内处理 | sync 或 async | row（可加 agent） | 可选 | +| 批量处理勾选行 | sync 或 async | batch（可加 toolbar/cron） | 可选 | | 导入 / 重置 | sync 或 async | skill-detail, agent | 可选 | | 单条副作用 RPA | async（建议） | agent, skill-detail | **建议** | | 批量顺序 pick RPA | async（建议） | toolbar, cron, agent | **建议** | - ## 同步数据 vs 导出当前表 vs 特殊业务报告 不要混用「导出」一词： @@ -236,7 +265,7 @@ HINT: 当前宿主稳定支持： - `object` / `string` / `number` / `boolean` -- `enum` / `default` / `required` / `sensitive` +- `enum` / `default` / `required` / `sensitive` / `readOnly` - 简单模板替换（`{{fieldName}}`） 示例： @@ -281,6 +310,8 @@ HINT: - `enum` 在宿主中渲染为选择框 - `required` 字段在提交前校验 - `sensitive` 字段不得出现在低信任入口 +- `readOnly: true` 时数据管理表单只读展示该字段（仍随提交传入）；适合行内/勾选预填的主键、编号列表 +- `placements` 含 `batch` 的动作在数据管理表顶常驻，无勾选时禁用（与表删除一致） - 需要确认的副作用操作使用 `confirmation.message` - 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明 - `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null` diff --git a/scripts/util/constants.py b/scripts/util/constants.py index 19ecf69..7df6e3b 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.52" +SKILL_VERSION = "1.0.53" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.2" diff --git a/tests/test_actions_manifest.py b/tests/test_actions_manifest.py index 61afb5c..54783c8 100644 --- a/tests/test_actions_manifest.py +++ b/tests/test_actions_manifest.py @@ -15,7 +15,6 @@ from util.constants import SKILL_SLUG _TEMPLATE_PLACEHOLDER_SLUG = "your-skill-slug" _ALLOWED_PLACEMENTS = frozenset({"toolbar", "row", "batch", "cron", "agent", "skill-detail"}) -_RESERVED_PLACEMENTS = frozenset({"row", "batch"}) _RESERVED_ACTION_FIELDS = frozenset({"concurrency", "locks"}) _ALLOWED_EXECUTION_PROFILES = frozenset({"sync", "async"}) _REQUIRED_MANIFEST_KEYS = frozenset({"schemaVersion", "skill", "actions"}) @@ -275,13 +274,13 @@ class TestActionsManifest(unittest.TestCase): self.assertEqual(missing, [], msg="\n".join(missing)) def test_schema_allows_all_placement_execution_profile_combinations(self) -> None: - """POLICY-SKILL-ACTION-004：4 placements × 2 profiles 必须全部通过 Schema。""" + """POLICY-SKILL-ACTION-004：6 placements × 2 profiles 必须全部通过 Schema。""" try: import jsonschema except ImportError: self.fail("jsonschema is required to validate placement×executionProfile orthogonality") schema = _load_actions_schema() - placements = ("toolbar", "cron", "agent", "skill-detail") + placements = ("toolbar", "row", "batch", "cron", "agent", "skill-detail") profiles = ("sync", "async") for placement in placements: for profile in profiles: @@ -346,16 +345,6 @@ class TestActionsManifest(unittest.TestCase): for snippet in forbidden_snippets: self.assertNotIn(snippet, text) - def test_template_example_does_not_use_reserved_placements(self) -> None: - manifest = _load_actions_manifest() - for action in manifest["actions"]: - placements = set(action.get("placements") or []) - overlap = placements & _RESERVED_PLACEMENTS - self.assertFalse( - overlap, - msg=f"{action['id']} uses reserved placements not yet supported in template: {overlap}", - ) - def test_template_variables_have_input_schema(self) -> None: manifest = _load_actions_manifest() for action in manifest["actions"]: diff --git a/tests/test_development_policy_guard.py b/tests/test_development_policy_guard.py index 9de846f..68708c0 100644 --- a/tests/test_development_policy_guard.py +++ b/tests/test_development_policy_guard.py @@ -1211,7 +1211,7 @@ class TestPolicySkillAction004(unittest.TestCase): msg=_policy_msg( "POLICY-SKILL-ACTION-004", "tests/test_actions_manifest.py", - "missing Schema 4×2 orthogonality matrix test", + "missing Schema 6×2 orthogonality matrix test", ), ) diff --git a/tools/README.md b/tools/README.md index e59ba1c..006ce88 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,5 +1,15 @@ # skill-template 工具 +## 业务仓也可以直接 clone（来源 A） + +若项目经理已在**公司自建 Gitea**（[https://git.jc2009.com/](https://git.jc2009.com/)，基于开源 Gitea 自建，**不是** Gitea 官网）开好业务技能仓库并授权，技术人员应直接： + +```powershell +git clone https://git.jc2009.com//.git +``` + +完整说明见 [`../development/DEVELOPMENT.md`](../development/DEVELOPMENT.md) §4「来源 A」。下面脚手架用于**本地已有 skill-template、要新建尚未灌仓目录**的场景（来源 B）。 + ## 推荐：脚手架创建新技能 **不要**用资源管理器整文件夹复制 `skill-template`（会带走隐藏 `.git`，导致 push 串库）。