client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: auto release commit (2026-06-14 11:12:03)
All checks were successful
技能自动化发布 / release (push) Successful in 8s
Details

Browse Source
This commit is contained in:
chendelian
2026-06-14 11:12:04 +08:00
parent 955816c8a7
commit c7d7832749
20 changed files with 466 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/release_skill.yaml vendored
View File

@@ -5,7 +5,7 @@ on:
jobs: jobs:
release: release:
uses: admin/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@main uses: admin/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@v1.0.14
secrets: secrets:
PYARMOR_REG_B64: ${{ secrets.PYARMOR_REG_B64 }} PYARMOR_REG_B64: ${{ secrets.PYARMOR_REG_B64 }}
with: with:

119
README.md
View File

@@ -1,80 +1,77 @@
# 匠厂 技能开发模板（通用业务） ---
description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
---
这是一个**规范化的新技能模板仓库**，用于复制出新的 skill 项目；它本身**不是业务 skill**。 # 【技能名称】
## 模板目标 用一两句话说明这个技能帮助用户完成什么工作。
这里不要解释技术实现，要从用户的业务目标出发描述价值。
- 对齐当前规范 skill 的目录结构：`assets/`、`references/`、`scripts/`、`tests/`、`evals/` ## 这个技能能帮你做什么
- 对齐当前规范脚手架分层：`scripts/cli`、`scripts/db`、`scripts/service`、`scripts/util`；公共能力从共享 runtime 的 `jiangchang-platform-kit` 引用
- 提供最小可运行入口：`python scripts/main.py health` / `config-path` / `version`，以及通用任务命令骨架 `run` / `logs` / `log-get`
- 内置 **配置 bootstrap**：`.env.example` 首次落盘到 `{DATA_ROOT}/{USER_ID}/{slug}/.env`，升级后合并缺失 key（见 `scripts/util/config_bootstrap.py`）
- 内置 **隔离测试体系**：`IsolatedDataRoot`、双键环境、`OPENCLAW_TEST_TARGET` 档位与 adapter profile 策略（详见 [`references/TESTING.md`](references/TESTING.md)）
- 让新技能从一开始就按规范落地，不再沿用旧模板的 `docs/`、`optional/`、`skill_main.py` 结构
## 新技能使用步骤 用 3 到 6 条业务能力说明技能价值，例如：
1. 复制本目录为新的 skill 仓库。 - 【自动整理/查询/生成/同步/核对/提交】某类业务数据
2. 全局替换 `your-skill-slug`、`your-platform-key`、`您的技能显示名称` 等占位内容。 - 帮你减少重复操作，降低人工录入或核对成本
3. 修改 `SKILL.md`、`references/` 和 `scripts/util/constants.py`。 - 在任务完成后给出清晰的处理结果、失败原因或后续建议
4. 在 `scripts/service/task_service.py` 中实现真实业务编排与外部系统对接。
5. 运行 `python tests/run_tests.py -v`，再执行 `python scripts/main.py health`、`version` 做最小验证。
如果你的技能在平台里默认是非公开的（`access_scope = 0`），建议在 `SKILL.md` 的 `metadata.openclaw.developer_ids` 中填写开发者用户 ID 列表。这样在正式发布后，平台会为这些开发者补可见权限，避免「技能已上架但开发者自己在市场中看不到」。 ## 适合什么场景
开发教程入口： 列出典型使用场景。请使用用户熟悉的业务语言，例如：
- <a href="references/REQUIREMENTS.md" target="_blank" rel="noopener noreferrer">需求文档模板</a>：给技术人员编写和查看研发需求的标准模板 - 每天需要重复处理同一类订单、单据、报表或客户资料
- <a href="references/DEVELOPMENT.md" target="_blank" rel="noopener noreferrer">开发教程</a>：给技术人员的完整开发步骤说明 - 需要从多个系统中查询信息并汇总结果
- <a href="references/TESTING.md" target="_blank" rel="noopener noreferrer">测试开发指南</a>：默认套件、隔离数据根、档位开关与 FakeAdapter 怎么用 - 需要按固定规则检查数据是否完整、是否异常
- 需要把处理结果保存为文件、记录或任务报告
## 目录说明 ## 使用前需要准备什么
| 路径 | 用途 | 说明用户在使用前要准备的东西，例如：
|------|------|
| `SKILL.md` | 技能清单与触发说明模板 |
| `assets/` | 示例输出与轻量 schema |
| `references/` | 面向用户与编排的文档模板 |
| `scripts/` | 规范分层后的代码骨架 |
| `tests/` | 单元测试与分层测试范式（默认根目录 unittest） |
| `evals/` | 人工/半自动评估材料 |
| `requirements.txt` | 本技能 Python 三方依赖声明（由匠厂宿主安装到共享 runtime） |
| `.github/workflows/release_skill.yaml` | 标准发布工作流 |
| `release.ps1` | 对齐现有 skill 的发布脚本入口 |
## 最小命令 - 相关账号已登录，且具备查询、导出或提交权限
- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息
- 如果涉及外部系统，请确认网络、账号、验证码或审批流程可正常使用
```bash ## 你可以这样告诉 Agent
python scripts/main.py health
python scripts/main.py version
```
## 注意 用自然语言示例展示用户可以怎么发起任务，例如：
- 不要再往模板里引入旧式 `docs/` 或 `optional/` 目录。 - “帮我查询今天的【业务对象】，整理成表格。”
- 新技能若不需要某些目录，也建议先保留结构，再按实际业务填充内容。 - “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。”
- `metadata.openclaw.developer_ids` 是发布元数据，不是用户展示文案；用于非公开技能的开发者默认可见授权。 - “帮我把【时间范围】内的【业务数据】导出并生成处理报告。”
- **发起 `release.ps1` 之前**，务必确认 `python tests/run_tests.py -v` 已全部通过。 - “帮我根据这个文件里的内容，逐条完成【业务动作】。”
## Python 依赖（requirements.txt） 注意：示例应是自然语言，不要写命令行命令。
- `jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等由**宿主共享 runtime** 提供；`jiangchang_skill_core` **不在技能仓库内复制**。 ## 执行后你会得到什么
- 新技能**不得 vendored** `scripts/jiangchang_skill_core/`；复制模板后若发现该目录，应删除并改为依赖共享 venv。
- 在技能**根目录**维护 `requirements.txt`，**只声明技能特有** Python 三方包；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。
- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.13`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。`jiangchang-platform-kit>=1.0.13` 是当前 RPA 视频/旁白/背景音乐/前后缓冲等标准能力的最低版本。
- 匠厂宿主在**安装或更新**技能后，会将技能 `requirements.txt` 中的依赖安装到共享 Python runtime：
`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`（Windows 示例：`D:\jiangchang-data\python-runtime\.venv`）。
- **Skill 业务代码不得自动 `pip install`**；缺依赖时应在 `health` / preflight 中给出清晰错误。
- **系统级组件**（如 Microsoft Visual C++ Redistributable）**不要**写进 `requirements.txt`；仅在 `health` / preflight 中提示用户自行安装。
- 独立本地开发环境若缺少公共包，可手动安装；**生产/宿主运行**由共享 runtime 负责，无需在技能内 `pip install playwright`。
## 公共能力边界 说明用户会看到什么结果，例如：
以下能力均由 `jiangchang-platform-kit`（共享 runtime 的 `jiangchang_skill_core`）提供，技能只写业务逻辑与薄封装，**不要**在技能内复制实现： - 任务是否成功完成
- 处理了多少条数据
- 哪些内容成功、哪些失败
- 失败原因和建议处理方式
- 生成的文件、表格、报告或记录
- `config` — `.env` 三级优先级读取与首次落盘 ## 注意事项
- `runtime_env` — 数据根、用户 ID、兄弟技能根解析
- `unified_logging` — 统一日志与 trace 用用户能理解的方式说明边界和风险，例如：
- `rpa` — 浏览器/桌面/手机 RPA 共享库
- `media_assets` — 共享媒体资源探测与路径解析 - 请确认输入范围准确，避免处理错数据
- `video_session` — RPA 录屏成片（ffmpeg、字幕、背景音乐） - 涉及提交、付款、删除、审批等高风险动作时，技能应在执行前请求确认
- `runtime_diagnostics` — `health` 统一 runtime 诊断 - 如果外部系统登录失效、权限不足或页面变化，任务可能需要用户介入
- 不建议在未核对数据的情况下直接执行批量操作
## 常见问题
### 为什么任务没有查到数据？
可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。
### 为什么任务执行到一半需要我操作？
可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。
### 结果文件在哪里查看？
请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。

47
SKILL.md
View File

@@ -1,12 +1,12 @@
--- ---
name: 技能开发模板（通用业务版） name: 技能开发模板（通用业务版）
description: "OpenClaw 通用业务技能开发模板，覆盖任务执行、日志记录、外部系统对接、隔离测试等典型能力。复制后请按 references/DEVELOPMENT.md 完成定制。" description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
version: 1.0.14 version: 1.0.14
author: 深圳匠厂科技有限公司 author: 深圳匠厂科技有限公司
metadata: metadata:
openclaw: openclaw:
slug: your-skill-slug slug: your-skill-slug
platform_kit_min_version: "1.0.13" platform_kit_min_version: "1.0.14"
emoji: "📦" emoji: "📦"
category: "通用" category: "通用"
developer_ids: developer_ids:
@@ -18,19 +18,24 @@ allowed-tools:
# 技能开发模板（skill-template） # 技能开发模板（skill-template）
这是一个**用于复制的新技能模板**，不是业务技能本身。新建技能时，应复制本仓库结构，再把占位内容替换成你的真实业务实现。 这是一个**用于复制的新技能模板**，不是业务 skill 本身。复制后请替换占位内容，实现你的真实业务逻辑。
## 模板使用方式 ## 文档分工
1. 复制目录为你的新 skill 仓库。 | 文档 | 读者 | 用途 |
2. 全局替换 `your-skill-slug`、`技能开发模板（通用业务版）` 等占位词。 |------|------|------|
3. 按 `references/CLI.md`、`scripts/` 分层与 `README.md` 的说明补业务逻辑。 | 根目录 `README.md` | 普通用户 | 技能市场详情页说明（`metadata.readme_md` 主来源） |
| `SKILL.md`（本文） | LLM / OpenClaw 平台 | 技能入口、触发与运行契约摘要 |
| `references/` | Agent 编排/调用 | 渐进式加载：CLI 契约、字段 schema 等 |
| `development/` | 开发者 / AI 编程代理 | 需求、开发教程、测试、技术规范 |
## 目录约定 ## 目录约定
- 根目录结构参考现有规范技能：`assets/`、`references/`、`scripts/`、`tests/`、`evals/`。 复制后建议保留：
- CLI 入口固定为 `scripts/main.py`。
- 业务逻辑按 `cli / db / service / util` 分层；公共能力从 `jiangchang-platform-kit` 提供的 `jiangchang_skill_core` 引用。 - `assets/`、`development/`、`evals/`、`references/`、`scripts/`、`tests/`
- CLI 入口固定为 `scripts/main.py`
- 业务逻辑按 `cli / db / service / util` 分层
## 最小命令 ## 最小命令
@@ -45,18 +50,22 @@ python {baseDir}/scripts/main.py version
## 运行依赖 ## 运行依赖
- Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 - Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.0.13`（`jiangchang_skill_core` 包）；**新技能不得**在仓库内保留 `scripts/jiangchang_skill_core/` 副本。 - 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.0.14`（`jiangchang_skill_core` 包）；**不要 vendor** `scripts/jiangchang_skill_core/`，新技能不得在仓库内保留该目录副本。
- config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。 - config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。
- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。宿主安装/更新技能后会将技能 requirements 安装到共享 venv。 - 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
- `metadata.openclaw.platform_kit_min_version`（当前 `1.0.13`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。`jiangchang-platform-kit>=1.0.13` 是当前 RPA 视频/旁白/背景音乐/前后缓冲等标准能力的最低版本。 - `metadata.openclaw.platform_kit_min_version`（当前 `1.0.14`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。
- Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。 - Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。
- `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。 - `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。
## 重要说明 ## 定制入口
- 复制后请同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。 1. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。
- 如技能无需持久化，可保留 `db/` 目录但不主动调用。 2. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。
- `metadata.openclaw.developer_ids` 用于声明技能发布后的默认开发者可见用户 ID 列表。 3. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`。
- 当技能在平台中 `access_scope = 0`（不公开）时，任务执行流程会把 `developer_ids` 中的用户自动补写到 `skill_user_access`，使这些开发者仍可在技能市场中查看该技能。 4. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
## 平台元数据
- `metadata.openclaw.developer_ids`：技能发布后的默认开发者可见用户 ID 列表。
- 当 `access_scope = 0`（不公开）时，平台会把 `developer_ids` 中的用户自动补写到 `skill_user_access`。
- `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。 - `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。
- 面向用户与编排的文档写在 `references/`，不要再新增旧式 `docs/` / `optional/` 结构。

4
assets/README.md
View File

@@ -3,4 +3,6 @@
- `examples/`：CLI 成功输出形状示例（虚构路径与数据）。 - `examples/`：CLI 成功输出形状示例（虚构路径与数据）。
- `schemas/`：轻量 JSON Schema 示例（`additionalProperties: true` 允许扩展字段）。 - `schemas/`：轻量 JSON Schema 示例（`additionalProperties: true` 允许扩展字段）。
面向编排与用户文档见 `references/README.md`、`references/CLI.md`、`RUNTIME.md`、`SCHEMA.md`。 - 用户市场说明见根目录 [`README.md`](../README.md)
- Agent 调用/编排参考见 [`references/`](../references/)
- 开发规范见 [`development/`](../development/)

0
references/ADAPTER.md → development/ADAPTER.md
View File

0
references/CONFIG.md → development/CONFIG.md
View File

131
references/DEVELOPMENT.md → development/DEVELOPMENT.md
View File

@@ -92,6 +92,7 @@
your-skill/ your-skill/
├─ .github/ ├─ .github/
├─ assets/ ├─ assets/
├─ development/
├─ evals/ ├─ evals/
├─ references/ ├─ references/
├─ scripts/ ├─ scripts/
@@ -110,7 +111,10 @@ your-skill/
各目录职责如下： 各目录职责如下：
- `assets/`：放示例输出、schema、静态说明资源 - `assets/`：放示例输出、schema、静态说明资源
- `references/`：放研发和编排需要长期维护的文档 - `README.md`：面向用户的市场详情页说明
- `SKILL.md`：面向 LLM / 平台的技能入口
- `references/`：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA）
- `development/`：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范
- `scripts/`：放真正的代码 - `scripts/`：放真正的代码
- `tests/`：放自动化测试 - `tests/`：放自动化测试
- `evals/`：放人工验收材料、评估清单、示例场景 - `evals/`：放人工验收材料、评估清单、示例场景
@@ -149,13 +153,13 @@ scripts/
- `util/` - `util/`
作用：常量、日志、路径、时间工具、通用帮助函数 作用：常量、日志、路径、时间工具、通用帮助函数
公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.13` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。 公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.14` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
## 3.2 开发 RPA 类 skill ## 3.2 开发 RPA 类 skill
若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地： 若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地：
1. **先读三份标准**：`references/RPA.md`（三端范式与反反爬）、`references/CONFIG.md`（`.env` 落盘与读取）、`references/ADAPTER.md`（四档 adapter）。 1. **先读三份标准**：`RPA.md`（三端范式与反反爬）、`CONFIG.md`（`.env` 落盘与读取）、`ADAPTER.md`（四档 adapter）。
2. **从模板复制骨架**： 2. **从模板复制骨架**：
- `scripts/service/example_adapter/` → 改名为 `scripts/service/<domain>_adapter/` - `scripts/service/example_adapter/` → 改名为 `scripts/service/<domain>_adapter/`
- 参考 `scripts/service/example_browser_rpa.py` 写浏览器会话逻辑 - 参考 `scripts/service/example_browser_rpa.py` 写浏览器会话逻辑
@@ -175,7 +179,7 @@ scripts/
技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能**特有** Python 三方依赖。 技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能**特有** Python 三方依赖。
- **公共依赖**（`jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等）由**宿主共享 runtime** 提供，**不要**写入技能 `requirements.txt`。 - **公共依赖**（`jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等）由**宿主共享 runtime** 提供，**不要**写入技能 `requirements.txt`。
- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.13`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。 - `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.14`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
- 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。 - 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
- **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法： - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
@@ -223,9 +227,10 @@ scripts/
复制后优先改下面这些地方： 复制后优先改下面这些地方：
1. `SKILL.md` 1. `SKILL.md`
2. `scripts/util/constants.py` 2. 根目录 `README.md`（用户市场说明）
3. `references/` 下的文案 3. `scripts/util/constants.py`
4. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`） 4. `references/` 与 `development/` 下的文案
5. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`）
最先要统一的是： 最先要统一的是：
@@ -249,47 +254,44 @@ scripts/
如果你的 skill 对外 CLI 需要自定义文案或别名（例如发布类对外仍叫 `publish`），通常还要替换： 如果你的 skill 对外 CLI 需要自定义文案或别名（例如发布类对外仍叫 `publish`），通常还要替换：
- `run` 命令中的中文提示与别名策略（见 `references/CLI.md`） - `run` 命令中的中文提示与别名策略（见 `../references/CLI.md`）
- `references/CLI.md` 的命令示例 - `../references/CLI.md` 的命令示例
- `references/README.md` 的用户话术 - `../README.md` 的用户话术
- `references/SCHEMA.md` 的字段映射补充说明 - `../references/SCHEMA.md` 的字段映射补充说明
如需浏览器自动化，不要在模板里保留空的 `platform_playwright.py`；请按业务新建 `xxx_playwright.py`（命名自定），并在 `task_service.py` 中按需引用。 如需浏览器自动化，不要在模板里保留空的 `platform_playwright.py`；请按业务新建 `xxx_playwright.py`（命名自定），并在 `task_service.py` 中按需引用。
## 6. `SKILL.md` 应该怎么写 ## 6. `SKILL.md` 与根 `README.md` 应该怎么写
`SKILL.md` 是技能清单，不是设计文档。 ### `SKILL.md`（LLM / 平台入口）
`SKILL.md` 是给 LLM 与 OpenClaw 平台看的技能入口，**不是**用户市场详情页。
应该重点写： 应该重点写：
- 技能名称 - YAML frontmatter：`name`、`description`、`version`、`metadata.openclaw`（含 `slug`、`platform_kit_min_version`、`developer_ids` 等）
- 技能描述 - 何时触发本技能、CLI 入口摘要、运行契约要点
- `slug` - 指向 `references/`（Agent 调用）与 `development/`（开发规范）的分工说明
作用：技能的唯一英文标识，通常用于仓库名、发布包名、运行时目录名、平台主键匹配等
示例：`your-skill-slug`、`disburse-payroll-icbc`、`tax-invoice-verify` 不要在 `SKILL.md` 里写大量用户市场文案或实现细节。
- `category`
作用：技能在平台中的分类，用于市场展示与归类，不是代码内部键 ### 根 `README.md`（用户市场说明）
示例：`通用`、`内容`、`办公协作`、`物流`、`抖音`、`小红书`
- `developer_ids`（如需给非公开技能自动补开发者可见权限） 根 `README.md` 是技能市场详情页主来源（`metadata.readme_md`），面向普通用户。
作用：声明发布后默认拥有可见权限的开发者用户 ID 列表
- `dependencies` 应包含 YAML frontmatter 的 `description`（市场列表简介），正文用用户能理解的语言说明：
作用：声明该技能依赖的兄弟技能或运行前置能力，便于平台或编排层识别依赖关系
示例（按业务填写；发布类可能会依赖账号 / 内容技能，其它领域可能完全不同）： - 能做什么、适合什么场景、使用前准备什么
```yaml - 如何自然语言告诉 Agent
dependencies: - 执行结果、注意事项、常见问题
required:
- some-sibling-skill 不要在根 `README.md` 里写开发教程、目录规范、release、requirements 等技术细节。
```
- 何时使用本技能
- 对用户的引导话术
- CLI 使用原则
不要在 `SKILL.md` 里写大量实现细节。
实现细节放在： 实现细节放在：
- `references/` - `development/`
- 代码注释 - `references/`（CLI / SCHEMA）
- `service/` 实现里 - 代码注释与 `service/` 实现
### 关于 `metadata.openclaw.developer_ids` ### 关于 `metadata.openclaw.developer_ids`
@@ -318,33 +320,31 @@ metadata:
- 第一个 ID 会同步到 `skills.developer_id` - 第一个 ID 会同步到 `skills.developer_id`
- 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权 - 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权
## 7. `references/` 应该放什么 ## 7. 文档目录分工
`references/` 是当前规范 skill 的文档中心，建议至少有这些： 当前规范 skill 的文档按读者拆分：
- `README.md` **根 `README.md`**
面向内部说明和技能作用介绍
- `CLI.md` - 用户市场详情页说明（含 frontmatter `description`）
写清楚命令、参数、默认值、兄弟技能调用方式
- `RUNTIME.md` **`SKILL.md`**
写清楚运行时目录、环境变量、入口约定
- `SCHEMA.md` - LLM / OpenClaw 平台技能入口
写清楚数据库路径、核心表结构、日志表结构
- `DEVELOPMENT.md` **`references/`**（Agent 运行/编排/调用时渐进加载）
写给技术人员的开发教程，也就是本文档
- `TESTING.md` - `README.md` — Agent 参考索引
写给技术人员的测试分层、隔离数据根与档位开关指南（详见 [`references/TESTING.md`](TESTING.md)） - `CLI.md` — 命令、参数、默认值、兄弟技能调用方式
- `SCHEMA.md` — 数据库路径、核心表结构、日志表结构
- 可按需增加 `ERRORS.md`、`INTEGRATION.md` 等编排向补充
如果后面某个 skill 需要更细的说明，可以再加： **`development/`**（开发者 / AI 编程代理）
- `ERRORS.md` - `REQUIREMENTS.md` — 需求与验收
- `INTEGRATION.md` - `DEVELOPMENT.md` — 开发教程（本文档）
- `PLATFORMS.md` - `TESTING.md` — 测试分层与隔离（详见 [`TESTING.md`](TESTING.md)）
- `ADAPTER.md`、`RPA.md`、`CONFIG.md`、`RUNTIME.md` — 技术规范
## 8. `assets/` 应该放什么 ## 8. `assets/` 应该放什么
@@ -359,7 +359,7 @@ metadata:
比如日志记录、机读 JSON 的 schema 比如日志记录、机读 JSON 的 schema
不要把正式研发文档放到 `assets/`。 不要把正式研发文档放到 `assets/`。
文档应该进 `references/`。 用户说明进根 `README.md`；Agent 编排资料进 `references/`；开发规范进 `development/`。
## 9. `cli` 层怎么写 ## 9. `cli` 层怎么写
@@ -516,7 +516,7 @@ python scripts/main.py <your-command>
3. **写完 service 业务后**：从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。 3. **写完 service 业务后**：从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。
4. **接外部系统时**：写在 `tests/integration/`，并配合 `OPENCLAW_TEST_TARGET` 显式开启。 4. **接外部系统时**：写在 `tests/integration/`，并配合 `OPENCLAW_TEST_TARGET` 显式开启。
详见 `references/TESTING.md`。 详见 `TESTING.md`。
## 15. 发布到正式环境验证 ## 15. 发布到正式环境验证
@@ -573,7 +573,7 @@ python scripts/main.py <your-command>
如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如： 如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如：
- 发布脚本是否正常推送 - 发布脚本是否正常推送
- `SKILL.md`、`scripts/`、`references/` 是否齐全 - `SKILL.md`、根 `README.md`、`scripts/`、`references/`、`development/` 是否齐全
- 工作流文件是否存在 - 工作流文件是否存在
- 发布包结构是否符合模板规范 - 发布包结构是否符合模板规范
@@ -636,7 +636,7 @@ python scripts/main.py <your-command>
- [ ] 目录结构符合当前模板 - [ ] 目录结构符合当前模板
- [ ] `SKILL.md` 中 slug、名称、描述都已替换 - [ ] `SKILL.md` 中 slug、名称、描述都已替换
- [ ] `scripts/util/constants.py` 已修改 - [ ] `scripts/util/constants.py` 已修改
- [ ] `references/CLI.md` 示例命令已改成真实命令 - [ ] `../references/CLI.md` 示例命令已改成真实命令
- [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现 - [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现
- [ ] 没有残留旧平台名 - [ ] 没有残留旧平台名
- [ ] `health` / `version` 可运行 - [ ] `health` / `version` 可运行
@@ -673,7 +673,7 @@ python scripts/main.py <your-command>
- `task_service.py` - `task_service.py`
- `sibling_bridge.py` - `sibling_bridge.py`
- `references/CLI.md` - `../references/CLI.md`
### 错误 3：把业务逻辑写进 CLI ### 错误 3：把业务逻辑写进 CLI
@@ -698,16 +698,17 @@ python scripts/main.py <your-command>
现在的新模板原则是： 现在的新模板原则是：
- 不做旧结构兼容 - 不做旧结构兼容
- 统一走 `references/` + `scripts/main.py` - 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
- 统一走 `scripts/main.py` 作为 CLI 入口
## 18. 推荐开发顺序总结 ## 18. 推荐开发顺序总结
如果让一个新人照着做，我建议他按这个顺序： 如果让一个新人照着做，我建议他按这个顺序：
1. 复制模板并改目录名 1. 复制模板并改目录名
2. 改 `SKILL.md` 2. 改 `SKILL.md` 与根 `README.md`
3. 改 `scripts/util/constants.py` 3. 改 `scripts/util/constants.py`
4. 改 `references/` 4. 改 `references/` 与 `development/`
5. 改 `scripts/cli/app.py` 5. 改 `scripts/cli/app.py`
6. 改 `scripts/service/` 6. 改 `scripts/service/`
7. 跑 `python tests/run_tests.py -v` 7. 跑 `python tests/run_tests.py -v`
@@ -721,7 +722,7 @@ python scripts/main.py <your-command>
- 目录结构统一 - 目录结构统一
- 入口统一为 `scripts/main.py` - 入口统一为 `scripts/main.py`
- 文档统一放 `references/` - 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
- 业务核心逻辑统一放 `scripts/service/` - 业务核心逻辑统一放 `scripts/service/`
- 不再使用旧模板历史结构 - 不再使用旧模板历史结构

14
development/README.md Normal file
View File

@@ -0,0 +1,14 @@
# 开发资料入口
本目录面向**人类开发者**与 **AI 编程代理**。开始定制 skill 前，建议按以下顺序阅读：
1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准
2. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
3. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
4. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
5. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
6. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
7. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径与诊断约定
Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)。
用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。

4
references/REQUIREMENTS.md → development/REQUIREMENTS.md
View File

@@ -273,8 +273,8 @@
建议每个新 skill 开发时，按下面顺序使用文档： 建议每个新 skill 开发时，按下面顺序使用文档：
1. 先写 `references/REQUIREMENTS.md` 1. 先写 `REQUIREMENTS.md`
2. 再按 `references/DEVELOPMENT.md` 进入开发 2. 再按 `DEVELOPMENT.md` 进入开发
3. 开发过程中补充 `CLI.md`、`SCHEMA.md`、`RUNTIME.md`、`TESTING.md` 3. 开发过程中补充 `CLI.md`、`SCHEMA.md`、`RUNTIME.md`、`TESTING.md`
4. 发布前回到 `REQUIREMENTS.md` 对照验收标准逐项检查 4. 发布前回到 `REQUIREMENTS.md` 对照验收标准逐项检查

4
references/RPA.md → development/RPA.md
View File

@@ -51,7 +51,7 @@
6. **可以** `ignore_default_args=["--enable-automation"]`（platform-kit `launch_persistent_browser` 已处理）。 6. **可以** `ignore_default_args=["--enable-automation"]`（platform-kit `launch_persistent_browser` 已处理）。
7. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。 7. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。
指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.0.13**）。 指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.0.14**）。
**拟人操作**（必做）： **拟人操作**（必做）：
@@ -105,7 +105,7 @@ from jiangchang_skill_core.rpa import (
from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
``` ```
- `RpaVideoSession` 来自 platform-kit **>= 1.0.13**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。 - `RpaVideoSession` 来自 platform-kit **>= 1.0.14**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
- `health` 对上述资源做只读诊断，不下载、不修复。 - `health` 对上述资源做只读诊断，不下载、不修复。
完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。 完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。

9
references/RUNTIME.md → development/RUNTIME.md
View File

@@ -2,7 +2,7 @@
## 共享 Python Runtime ## 共享 Python Runtime
**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.13` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。 **skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.14` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。 技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。
@@ -24,7 +24,7 @@ Windows:
`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `CLAW_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。 `<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `CLAW_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
## Runtime 诊断（platform-kit 1.0.13+） ## Runtime 诊断（platform-kit 1.0.14+）
`health` 命令通过 **`jiangchang_skill_core.collect_runtime_diagnostics`** 输出共享 runtime 诊断，**不在技能内重复实现**。典型字段： `health` 命令通过 **`jiangchang_skill_core.collect_runtime_diagnostics`** 输出共享 runtime 诊断，**不在技能内重复实现**。典型字段：
@@ -42,7 +42,7 @@ Windows:
- 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。 - 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。
- `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。 - `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。
- 配置优先级：**进程环境变量** > **用户 `.env`** > **`.env.example` 默认值**。 - 配置优先级：**进程环境变量** > **用户 `.env`** > **`.env.example` 默认值**。
- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.13`，**不得** vendored `scripts/jiangchang_skill_core/`。 - 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.14`，**不得** vendored `scripts/jiangchang_skill_core/`。
## media-assets / ffmpeg / 背景音乐 ## media-assets / ffmpeg / 背景音乐
@@ -61,6 +61,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
新技能建议采用以下根目录结构： 新技能建议采用以下根目录结构：
- `assets/` - `assets/`
- `development/`
- `references/` - `references/`
- `scripts/` - `scripts/`
- `tests/` - `tests/`
@@ -103,7 +104,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。 退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。
详见 `references/TESTING.md` 第 3 节。 详见 `TESTING.md` 第 3 节。
## 编码与输出 ## 编码与输出

8
references/TESTING.md → development/TESTING.md
View File

@@ -1,6 +1,6 @@
# 测试开发指南 # 测试开发指南
面向复制 `skill-template` 后的新业务 skill：**如何把自动化测试当作一等公民**，而不是等业务写完再补文档级别的空话。本文串起模板自带的 unittest 入口、`tests/` 目录分层与安全档位约定；**更细的开关取值、表格字段与环境变量组合仍以 [`tests/README.md`](../tests/README.md) 为权威来源**。建议你随手开一个编辑器分页：`references/TESTING.md`（本篇）、[`references/DEVELOPMENT.md`](DEVELOPMENT.md)（整体节奏）、[`tests/README.md`](../tests/README.md)（落地细则）。 面向复制 `skill-template` 后的新业务 skill：**如何把自动化测试当作一等公民**，而不是等业务写完再补文档级别的空话。本文串起模板自带的 unittest 入口、`tests/` 目录分层与安全档位约定；**更细的开关取值、表格字段与环境变量组合仍以 [`tests/README.md`](../tests/README.md) 为权威来源**。建议你随手开一个编辑器分页：`TESTING.md`（本篇）、[`DEVELOPMENT.md`](DEVELOPMENT.md)（整体节奏）、[`tests/README.md`](../tests/README.md)（落地细则）。
默认心智模型可以用一句话概括：**根目录 `test_*.py` = CI / 本地每次提交都应能通过的无外联套件**；`*integration*`、`*.sample`、`desktop/` = 只在人被明确要求时才启用的高风险或重量级路径。 默认心智模型可以用一句话概括：**根目录 `test_*.py` = CI / 本地每次提交都应能通过的无外联套件**；`*integration*`、`*.sample`、`desktop/` = 只在人被明确要求时才启用的高风险或重量级路径。
@@ -23,7 +23,7 @@
必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖： 必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖：
- CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟； - CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟；
- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.13` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）； - 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.14` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
- **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移； - **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移；
- 运行时：`runtime_paths` 与 **`CLAW_*` / `JIANGCHANG_*` 并发兜底； - 运行时：`runtime_paths` 与 **`CLAW_*` / `JIANGCHANG_*` 并发兜底；
- `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)； - `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)；
@@ -218,7 +218,7 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t
- [ ] `requirements.txt` **不含** `jiangchang-platform-kit` / `playwright` - [ ] `requirements.txt` **不含** `jiangchang-platform-kit` / `playwright`
- [ ] 无 `scripts/jiangchang_skill_core/` vendored 副本 - [ ] 无 `scripts/jiangchang_skill_core/` vendored 副本
- [ ] `platform_kit_min_version` **>= 1.0.13**（`SKILL.md` + `constants.py`） - [ ] `platform_kit_min_version` **>= 1.0.14**（`SKILL.md` + `constants.py`）
- [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行） - [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行）
- [ ] `config-path` 可输出用户 `.env` 路径 JSON - [ ] `config-path` 可输出用户 `.env` 路径 JSON
- [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py` - [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py`
@@ -228,5 +228,5 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t
--- ---
- [`tests/README.md`](../tests/README.md) — 表格、变量与目录细则 - [`tests/README.md`](../tests/README.md) — 表格、变量与目录细则
- [`references/DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序 - [`DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序
- [`tests/integration/README.md`](../tests/integration/README.md) — 高风险用法 - [`tests/integration/README.md`](../tests/integration/README.md) — 高风险用法

84
references/README.md
View File

@@ -1,77 +1,13 @@
--- # Agent 参考索引
description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
---
# 【技能名称】 本目录供 Agent **运行、编排、调用** skill 时渐进式加载，不是用户市场说明。
用一两句话说明这个技能帮助用户完成什么工作。 | 文档 | 用途 |
这里不要解释技术实现，要从用户的业务目标出发描述价值。 |------|------|
| 根目录 [`README.md`](../README.md) | 用户市场详情页说明 |
| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口 |
| [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 |
| [`SCHEMA.md`](SCHEMA.md) | 输入输出、数据库与字段说明 |
| [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） |
## 这个技能能帮你做什么 按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；运行时环境细节见 `../development/RUNTIME.md`。
用 3 到 6 条业务能力说明技能价值，例如：
- 【自动整理/查询/生成/同步/核对/提交】某类业务数据
- 帮你减少重复操作，降低人工录入或核对成本
- 在任务完成后给出清晰的处理结果、失败原因或后续建议
## 适合什么场景
列出典型使用场景。请使用用户熟悉的业务语言，例如：
- 每天需要重复处理同一类订单、单据、报表或客户资料
- 需要从多个系统中查询信息并汇总结果
- 需要按固定规则检查数据是否完整、是否异常
- 需要把处理结果保存为文件、记录或任务报告
## 使用前需要准备什么
说明用户在使用前要准备的东西，例如：
- 相关账号已登录，且具备查询、导出或提交权限
- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息
- 如果涉及外部系统，请确认网络、账号、验证码或审批流程可正常使用
## 你可以这样告诉 Agent
用自然语言示例展示用户可以怎么发起任务，例如：
- “帮我查询今天的【业务对象】，整理成表格。”
- “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。”
- “帮我把【时间范围】内的【业务数据】导出并生成处理报告。”
- “帮我根据这个文件里的内容，逐条完成【业务动作】。”
注意：示例应是自然语言，不要写命令行命令。
## 执行后你会得到什么
说明用户会看到什么结果，例如：
- 任务是否成功完成
- 处理了多少条数据
- 哪些内容成功、哪些失败
- 失败原因和建议处理方式
- 生成的文件、表格、报告或记录
## 注意事项
用用户能理解的方式说明边界和风险，例如：
- 请确认输入范围准确，避免处理错数据
- 涉及提交、付款、删除、审批等高风险动作时，技能应在执行前请求确认
- 如果外部系统登录失效、权限不足或页面变化，任务可能需要用户介入
- 不建议在未核对数据的情况下直接执行批量操作
## 常见问题
### 为什么任务没有查到数据？
可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。
### 为什么任务执行到一半需要我操作？
可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。
### 结果文件在哪里查看？
请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。

2
scripts/util/constants.py
View File

@@ -3,4 +3,4 @@
SKILL_SLUG = "your-skill-slug" SKILL_SLUG = "your-skill-slug"
SKILL_VERSION = "1.0.14" SKILL_VERSION = "1.0.14"
LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
PLATFORM_KIT_MIN_VERSION = "1.0.13" PLATFORM_KIT_MIN_VERSION = "1.0.14"

2
tests/_support.py
View File

@@ -39,7 +39,7 @@ def get_skill_root() -> str:
return _SKILL_ROOT return _SKILL_ROOT
def platform_kit_version_patch(version: str = "1.0.13"): def platform_kit_version_patch(version: str = "1.0.14"):
"""Mock installed jiangchang-platform-kit version for health/diagnostics tests.""" """Mock installed jiangchang-platform-kit version for health/diagnostics tests."""
from unittest.mock import patch from unittest.mock import patch

17
tests/test_docs_standards.py
View File

@@ -16,17 +16,17 @@ class TestDocsStandards(unittest.TestCase):
return f.read() return f.read()
def test_rpa_md_covers_video_and_playwright_standards(self) -> None: def test_rpa_md_covers_video_and_playwright_standards(self) -> None:
text = self._read("references/RPA.md") text = self._read("development/RPA.md")
self.assertIn("title", text) self.assertIn("title", text)
self.assertIn("closing_title", text) self.assertIn("closing_title", text)
self.assertIn("中文", text) self.assertIn("中文", text)
self.assertIn("--no-sandbox", text) self.assertIn("--no-sandbox", text)
self.assertIn("--disable-blink-features=AutomationControlled", text) self.assertIn("--disable-blink-features=AutomationControlled", text)
self.assertIn("RpaVideoSession", text) self.assertIn("RpaVideoSession", text)
self.assertIn("1.0.13", text) self.assertIn("1.0.14", text)
def test_adapter_md_covers_four_tiers_and_allow_flags(self) -> None: def test_adapter_md_covers_four_tiers_and_allow_flags(self) -> None:
text = self._read("references/ADAPTER.md") text = self._read("development/ADAPTER.md")
for marker in ( for marker in (
"mock", "mock",
"simulator_rpa", "simulator_rpa",
@@ -45,18 +45,17 @@ class TestDocsStandards(unittest.TestCase):
self.assertIn("uv run python", text) self.assertIn("uv run python", text)
def test_testing_md_mentions_pytest_txt_collection_guard(self) -> None: def test_testing_md_mentions_pytest_txt_collection_guard(self) -> None:
text = self._read("references/TESTING.md") text = self._read("development/TESTING.md")
self.assertIn(".txt", text) self.assertIn(".txt", text)
self.assertIn("pytest.ini", text) self.assertIn("pytest.ini", text)
def test_docs_do_not_claim_1_0_11_as_current_standard(self) -> None: def test_docs_do_not_claim_1_0_11_as_current_standard(self) -> None:
for rel in ( for rel in (
"README.md",
"SKILL.md", "SKILL.md",
"references/RUNTIME.md", "development/RUNTIME.md",
"references/RPA.md", "development/RPA.md",
"references/CONFIG.md", "development/CONFIG.md",
"references/TESTING.md", "development/TESTING.md",
): ):
text = self._read(rel) text = self._read(rel)
self.assertNotIn( self.assertNotIn(

6
tests/test_platform_import.py
View File

@@ -83,16 +83,16 @@ class TestPlatformImportSource(unittest.TestCase):
) )
) )
def test_platform_kit_min_version_is_1_0_13(self) -> None: def test_platform_kit_min_version_is_1_0_14(self) -> None:
from jiangchang_skill_core import version_ge from jiangchang_skill_core import version_ge
from util.constants import PLATFORM_KIT_MIN_VERSION from util.constants import PLATFORM_KIT_MIN_VERSION
self.assertEqual(PLATFORM_KIT_MIN_VERSION, "1.0.13") self.assertEqual(PLATFORM_KIT_MIN_VERSION, "1.0.14")
md_path = os.path.join(get_skill_root(), "SKILL.md") md_path = os.path.join(get_skill_root(), "SKILL.md")
with open(md_path, encoding="utf-8") as f: with open(md_path, encoding="utf-8") as f:
md = f.read() md = f.read()
self.assertEqual(_parse_platform_kit_min_version(md), "1.0.13") self.assertEqual(_parse_platform_kit_min_version(md), "1.0.14")
req_path = os.path.join(get_skill_root(), "requirements.txt") req_path = os.path.join(get_skill_root(), "requirements.txt")
with open(req_path, encoding="utf-8") as f: with open(req_path, encoding="utf-8") as f:

16
tests/test_template_runtime_standard.py
View File

@@ -10,13 +10,15 @@ from _support import get_skill_root
DOC_PATHS = ( DOC_PATHS = (
"README.md", "README.md",
"SKILL.md", "SKILL.md",
"references/RUNTIME.md", "development/RUNTIME.md",
"references/CLI.md", "references/CLI.md",
"references/DEVELOPMENT.md", "development/DEVELOPMENT.md",
"references/RPA.md", "development/RPA.md",
"references/CONFIG.md", "development/CONFIG.md",
) )
RUNTIME_DOC_PATHS = tuple(p for p in DOC_PATHS if p != "README.md")
FORBIDDEN_PHRASES = ( FORBIDDEN_PHRASES = (
"scripts/jiangchang_skill_core/：运行时", "scripts/jiangchang_skill_core/：运行时",
"运行时与统一日志副本", "运行时与统一日志副本",
@@ -32,7 +34,7 @@ FORBIDDEN_PHRASES = (
POSITIVE_MARKERS = ( POSITIVE_MARKERS = (
"jiangchang-platform-kit", "jiangchang-platform-kit",
"1.0.13", "1.0.14",
"共享 runtime", "共享 runtime",
) )
@@ -54,7 +56,7 @@ class TestTemplateRuntimeStandard(unittest.TestCase):
) )
def test_guarded_docs_promote_shared_runtime_standard(self) -> None: def test_guarded_docs_promote_shared_runtime_standard(self) -> None:
combined = "\n".join(self._read(p) for p in DOC_PATHS) combined = "\n".join(self._read(p) for p in RUNTIME_DOC_PATHS)
for marker in POSITIVE_MARKERS: for marker in POSITIVE_MARKERS:
self.assertIn( self.assertIn(
marker, marker,
@@ -67,7 +69,7 @@ class TestTemplateRuntimeStandard(unittest.TestCase):
) )
def test_runtime_md_mentions_collect_runtime_diagnostics(self) -> None: def test_runtime_md_mentions_collect_runtime_diagnostics(self) -> None:
text = self._read("references/RUNTIME.md") text = self._read("development/RUNTIME.md")
self.assertIn("collect_runtime_diagnostics", text) self.assertIn("collect_runtime_diagnostics", text)
def test_cli_md_mentions_health_runtime_diagnostics(self) -> None: def test_cli_md_mentions_health_runtime_diagnostics(self) -> None:

194
tools/highlight_answers.py Normal file
View File

@@ -0,0 +1,194 @@
#!/usr/bin/env python3
"""Highlight correct answer options in Excel quiz file."""
import re
import sys
from pathlib import Path
import openpyxl
from openpyxl.cell.rich_text import CellRichText, InlineFont, TextBlock
# Option letter to index mapping
LETTER_TO_IDX = {"A": 0, "B": 1, "C": 2, "D": 3}
IDX_TO_LETTER = {0: "A", 1: "B", 2: "C", 3: "D"}
# Regex to find option boundaries: A/B/C/D followed by separator
OPTION_MARKER_RE = re.compile(
r"(?=[A-D](?:[\.．、:：\)）]|\s))"
)
NORMAL_FONT = InlineFont(b=False, color="000000")
RED_BOLD_FONT = InlineFont(b=True, color="FF0000")
def parse_answer(answer_raw) -> set[int]:
"""Parse answer column into set of option indices (0=A, 1=B, ...)."""
if answer_raw is None:
return set()
s = str(answer_raw).strip()
if not s:
return set()
indices = set()
# Pure digits like "13" -> 1 and 3 (not 13)
if re.fullmatch(r"[1-4]+", s):
for ch in s:
indices.add(int(ch) - 1)
return indices
# Split by common separators
parts = re.split(r"[,，;；\s|]+", s)
for part in parts:
part = part.strip().upper()
if not part:
continue
if part in LETTER_TO_IDX:
indices.add(LETTER_TO_IDX[part])
elif re.fullmatch(r"[1-4]", part):
indices.add(int(part) - 1)
return indices
def find_option_spans(text: str) -> list[tuple[int, int, str]]:
"""Find spans for each A/B/C/D option in the options text."""
if not text or not isinstance(text, str):
return []
markers = []
for m in OPTION_MARKER_RE.finditer(text):
letter = text[m.start()]
markers.append((m.start(), letter))
if not markers:
return []
spans = []
for i, (start, letter) in enumerate(markers):
end = markers[i + 1][0] if i + 1 < len(markers) else len(text)
spans.append((start, end, letter))
return spans
def build_rich_text(options_text: str, answer_indices: set[int]) -> CellRichText | str:
"""Build rich text with correct options in red bold."""
spans = find_option_spans(options_text)
if not spans:
return options_text
parts = []
pos = 0
for start, end, letter in spans:
if start > pos:
parts.append(TextBlock(NORMAL_FONT, options_text[pos:start]))
idx = LETTER_TO_IDX.get(letter)
font = RED_BOLD_FONT if idx is not None and idx in answer_indices else NORMAL_FONT
parts.append(TextBlock(font, options_text[start:end]))
pos = end
if pos < len(options_text):
parts.append(TextBlock(NORMAL_FONT, options_text[pos:]))
return CellRichText(*parts)
def load_workbook_from_xls(xls_path: Path) -> openpyxl.Workbook:
"""Load .xls file, converting via pandas/xlrd if needed."""
try:
import pandas as pd
xls_data = pd.read_excel(xls_path, sheet_name=None, header=None, dtype=str)
wb = openpyxl.Workbook()
# Remove default sheet
wb.remove(wb.active)
for sheet_name, df in xls_data.items():
ws = wb.create_sheet(title=str(sheet_name))
for r_idx, row in enumerate(df.itertuples(index=False), start=1):
for c_idx, val in enumerate(row, start=1):
if val is not None and str(val) != "nan":
ws.cell(row=r_idx, column=c_idx, value=str(val))
return wb
except Exception as e:
raise RuntimeError(f"Failed to read .xls file: {e}") from e
def find_header_columns(ws) -> tuple[int, int, int] | None:
"""Find header row and column indices for 题目选项 and 题目答案."""
for row_idx in range(1, min(ws.max_row + 1, 20)):
options_col = None
answer_col = None
for col_idx in range(1, ws.max_column + 1):
val = ws.cell(row=row_idx, column=col_idx).value
if val is None:
continue
s = str(val).strip()
if s == "题目选项":
options_col = col_idx
elif s == "题目答案":
answer_col = col_idx
if options_col is not None and answer_col is not None:
return row_idx, options_col, answer_col
return None
def process_sheet(ws, stats: dict) -> bool:
"""Process a single worksheet. Returns True if processed."""
header_info = find_header_columns(ws)
if header_info is None:
return False
header_row, options_col, answer_col = header_info
stats["sheets"] += 1
sheet_rows = 0
sheet_matches = 0
for row_idx in range(header_row + 1, ws.max_row + 1):
options_cell = ws.cell(row=row_idx, column=options_col)
answer_cell = ws.cell(row=row_idx, column=answer_col)
options_text = options_cell.value
if options_text is None:
continue
options_text = str(options_text).strip()
if not options_text:
continue
answer_indices = parse_answer(answer_cell.value)
if not answer_indices:
continue
sheet_rows += 1
sheet_matches += len(answer_indices)
rich = build_rich_text(options_text, answer_indices)
options_cell.value = rich
stats["rows"] += sheet_rows
stats["matches"] += sheet_matches
return True
def main():
src = Path(r"D:\下载\安全知识竞赛题库(1).xls")
dst = Path(r"D:\下载\安全知识竞赛题库_答案标红.xlsx")
if not src.exists():
print(f"ERROR: Source file not found: {src}")
sys.exit(1)
print(f"Reading: {src}")
wb = load_workbook_from_xls(src)
stats = {"sheets": 0, "rows": 0, "matches": 0}
for ws in wb.worksheets:
process_sheet(ws, stats)
wb.save(dst)
print(f"Saved: {dst}")
print(f"处理结果: {stats['sheets']} 个工作表, {stats['rows']} 行, {stats['matches']} 个匹配选项")
if __name__ == "__main__":
main()

57
tools/verify_highlight.py Normal file
View File

@@ -0,0 +1,57 @@
#!/usr/bin/env python3
"""Verify highlighted answer output file."""
from pathlib import Path
import openpyxl
dst = Path(r"D:\下载\安全知识竞赛题库_答案标红.xlsx")
src = Path(r"D:\下载\安全知识竞赛题库(1).xls")
print(f"Source exists: {src.exists()}")
print(f"Output exists: {dst.exists()}")
wb = openpyxl.load_workbook(dst, rich_text=True)
ws = wb.active
print(f"Sheet: {ws.title}, rows={ws.max_row}, cols={ws.max_column}")
# Find header columns
header_row = None
options_col = None
answer_col = None
for row_idx in range(1, 20):
for col_idx in range(1, ws.max_column + 1):
val = ws.cell(row=row_idx, column=col_idx).value
if val and str(val).strip() == "题目选项":
options_col = col_idx
if val and str(val).strip() == "题目答案":
answer_col = col_idx
if options_col and answer_col:
header_row = row_idx
break
print(f"Header row={header_row}, options_col={options_col}, answer_col={answer_col}")
# Sample verification for first 5 rows with answers 1,2,3
samples = []
for row_idx in range(header_row + 1, ws.max_row + 1):
answer = ws.cell(row=row_idx, column=answer_col).value
if answer in ("1", "2", "3", 1, 2, 3):
cell = ws.cell(row=row_idx, column=options_col)
val = cell.value
runs = []
if hasattr(val, "__iter__") and not isinstance(val, str):
for block in val:
font = block.font
bold = font.b if font else None
color = font.color if font else None
runs.append((block.text, bold, color))
samples.append((row_idx, answer, runs))
if len(samples) >= 5:
break
for row_idx, answer, runs in samples:
print(f"\nRow {row_idx}, answer={answer}:")
for text, bold, color in runs:
marker = "RED_BOLD" if bold and color == "FF0000" else "normal"
print(f" [{marker}] {repr(text[:50])}")