From c7d78327498a2b9ee1be8c568a81ef7cc289cb4d Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Sun, 14 Jun 2026 11:12:04 +0800 Subject: [PATCH] chore: auto release commit (2026-06-14 11:12:03) --- .github/workflows/release_skill.yaml | 2 +- README.md | 119 ++++++------ SKILL.md | 47 +++-- assets/README.md | 4 +- {references => development}/ADAPTER.md | 0 {references => development}/CONFIG.md | 0 {references => development}/DEVELOPMENT.md | 131 ++++++------- development/README.md | 14 ++ {references => development}/REQUIREMENTS.md | 4 +- {references => development}/RPA.md | 4 +- {references => development}/RUNTIME.md | 9 +- {references => development}/TESTING.md | 8 +- references/README.md | 84 +-------- scripts/util/constants.py | 2 +- tests/_support.py | 2 +- tests/test_docs_standards.py | 17 +- tests/test_platform_import.py | 6 +- tests/test_template_runtime_standard.py | 16 +- tools/highlight_answers.py | 194 ++++++++++++++++++++ tools/verify_highlight.py | 57 ++++++ 20 files changed, 466 insertions(+), 254 deletions(-) rename {references => development}/ADAPTER.md (100%) rename {references => development}/CONFIG.md (100%) rename {references => development}/DEVELOPMENT.md (87%) create mode 100644 development/README.md rename {references => development}/REQUIREMENTS.md (99%) rename {references => development}/RPA.md (99%) rename {references => development}/RUNTIME.md (94%) rename {references => development}/TESTING.md (96%) create mode 100644 tools/highlight_answers.py create mode 100644 tools/verify_highlight.py diff --git a/.github/workflows/release_skill.yaml b/.github/workflows/release_skill.yaml index 270c091..c69786d 100644 --- a/.github/workflows/release_skill.yaml +++ b/.github/workflows/release_skill.yaml @@ -5,7 +5,7 @@ on: jobs: 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: PYARMOR_REG_B64: ${{ secrets.PYARMOR_REG_B64 }} with: diff --git a/README.md b/README.md index 59c19bd..a370b0b 100644 --- a/README.md +++ b/README.md @@ -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 列表。这样在正式发布后，平台会为这些开发者补可见权限，避免「技能已上架但开发者自己在市场中看不到」。 +## 适合什么场景 -开发教程入口： +列出典型使用场景。请使用用户熟悉的业务语言，例如： -- 需求文档模板：给技术人员编写和查看研发需求的标准模板 -- 开发教程：给技术人员的完整开发步骤说明 -- 测试开发指南：默认套件、隔离数据根、档位开关与 FakeAdapter 怎么用 +- 每天需要重复处理同一类订单、单据、报表或客户资料 +- 需要从多个系统中查询信息并汇总结果 +- 需要按固定规则检查数据是否完整、是否异常 +- 需要把处理结果保存为文件、记录或任务报告 -## 目录说明 +## 使用前需要准备什么 -| 路径 | 用途 | -|------|------| -| `SKILL.md` | 技能清单与触发说明模板 | -| `assets/` | 示例输出与轻量 schema | -| `references/` | 面向用户与编排的文档模板 | -| `scripts/` | 规范分层后的代码骨架 | -| `tests/` | 单元测试与分层测试范式（默认根目录 unittest） | -| `evals/` | 人工/半自动评估材料 | -| `requirements.txt` | 本技能 Python 三方依赖声明（由匠厂宿主安装到共享 runtime） | -| `.github/workflows/release_skill.yaml` | 标准发布工作流 | -| `release.ps1` | 对齐现有 skill 的发布脚本入口 | +说明用户在使用前要准备的东西，例如： -## 最小命令 +- 相关账号已登录，且具备查询、导出或提交权限 +- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息 +- 如果涉及外部系统，请确认网络、账号、验证码或审批流程可正常使用 -```bash -python scripts/main.py health -python scripts/main.py version -``` +## 你可以这样告诉 Agent -## 注意 +用自然语言示例展示用户可以怎么发起任务，例如： -- 不要再往模板里引入旧式 `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 返回的结果说明查看生成文件、任务记录或处理报告。 diff --git a/SKILL.md b/SKILL.md index f367721..85211e9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,12 +1,12 @@ --- name: 技能开发模板（通用业务版） -description: "OpenClaw 通用业务技能开发模板，覆盖任务执行、日志记录、外部系统对接、隔离测试等典型能力。复制后请按 references/DEVELOPMENT.md 完成定制。" +description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" version: 1.0.14 author: 深圳匠厂科技有限公司 metadata: openclaw: slug: your-skill-slug - platform_kit_min_version: "1.0.13" + platform_kit_min_version: "1.0.14" emoji: "📦" category: "通用" developer_ids: @@ -18,19 +18,24 @@ allowed-tools: # 技能开发模板（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`。 -- 公共能力来自共享 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，而非技能目录副本。 -- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。宿主安装/更新技能后会将技能 requirements 安装到共享 venv。 -- `metadata.openclaw.platform_kit_min_version`（当前 `1.0.13`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。`jiangchang-platform-kit>=1.0.13` 是当前 RPA 视频/旁白/背景音乐/前后缓冲等标准能力的最低版本。 +- 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。 +- `metadata.openclaw.platform_kit_min_version`（当前 `1.0.14`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。 - Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。 - `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。 -## 重要说明 +## 定制入口 -- 复制后请同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。 -- 如技能无需持久化，可保留 `db/` 目录但不主动调用。 -- `metadata.openclaw.developer_ids` 用于声明技能发布后的默认开发者可见用户 ID 列表。 -- 当技能在平台中 `access_scope = 0`（不公开）时，任务执行流程会把 `developer_ids` 中的用户自动补写到 `skill_user_access`，使这些开发者仍可在技能市场中查看该技能。 +1. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。 +2. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。 +3. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`。 +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`。 -- 面向用户与编排的文档写在 `references/`，不要再新增旧式 `docs/` / `optional/` 结构。 diff --git a/assets/README.md b/assets/README.md index d66a994..c130f28 100644 --- a/assets/README.md +++ b/assets/README.md @@ -3,4 +3,6 @@ - `examples/`：CLI 成功输出形状示例（虚构路径与数据）。 - `schemas/`：轻量 JSON Schema 示例（`additionalProperties: true` 允许扩展字段）。 -面向编排与用户文档见 `references/README.md`、`references/CLI.md`、`RUNTIME.md`、`SCHEMA.md`。 +- 用户市场说明见根目录 [`README.md`](../README.md) +- Agent 调用/编排参考见 [`references/`](../references/) +- 开发规范见 [`development/`](../development/) diff --git a/references/ADAPTER.md b/development/ADAPTER.md similarity index 100% rename from references/ADAPTER.md rename to development/ADAPTER.md diff --git a/references/CONFIG.md b/development/CONFIG.md similarity index 100% rename from references/CONFIG.md rename to development/CONFIG.md diff --git a/references/DEVELOPMENT.md b/development/DEVELOPMENT.md similarity index 87% rename from references/DEVELOPMENT.md rename to development/DEVELOPMENT.md index 49857e5..be8d6c6 100644 --- a/references/DEVELOPMENT.md +++ b/development/DEVELOPMENT.md @@ -92,6 +92,7 @@ your-skill/ ├─ .github/ ├─ assets/ +├─ development/ ├─ evals/ ├─ references/ ├─ scripts/ @@ -110,7 +111,10 @@ your-skill/ 各目录职责如下： - `assets/`：放示例输出、schema、静态说明资源 -- `references/`：放研发和编排需要长期维护的文档 +- `README.md`：面向用户的市场详情页说明 +- `SKILL.md`：面向 LLM / 平台的技能入口 +- `references/`：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA） +- `development/`：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范 - `scripts/`：放真正的代码 - `tests/`：放自动化测试 - `evals/`：放人工验收材料、评估清单、示例场景 @@ -149,13 +153,13 @@ scripts/ - `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 若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地： -1. **先读三份标准**：`references/RPA.md`（三端范式与反反爬）、`references/CONFIG.md`（`.env` 落盘与读取）、`references/ADAPTER.md`（四档 adapter）。 +1. **先读三份标准**：`RPA.md`（三端范式与反反爬）、`CONFIG.md`（`.env` 落盘与读取）、`ADAPTER.md`（四档 adapter）。 2. **从模板复制骨架**： - `scripts/service/example_adapter/` → 改名为 `scripts/service/_adapter/` - 参考 `scripts/service/example_browser_rpa.py` 写浏览器会话逻辑 @@ -175,7 +179,7 @@ scripts/ 技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能**特有** Python 三方依赖。 - **公共依赖**（`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`。 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。 - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法： @@ -223,9 +227,10 @@ scripts/ 复制后优先改下面这些地方： 1. `SKILL.md` -2. `scripts/util/constants.py` -3. `references/` 下的文案 -4. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`） +2. 根目录 `README.md`（用户市场说明） +3. `scripts/util/constants.py` +4. `references/` 与 `development/` 下的文案 +5. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`） 最先要统一的是： @@ -249,47 +254,44 @@ scripts/ 如果你的 skill 对外 CLI 需要自定义文案或别名（例如发布类对外仍叫 `publish`），通常还要替换： -- `run` 命令中的中文提示与别名策略（见 `references/CLI.md`） -- `references/CLI.md` 的命令示例 -- `references/README.md` 的用户话术 -- `references/SCHEMA.md` 的字段映射补充说明 +- `run` 命令中的中文提示与别名策略（见 `../references/CLI.md`） +- `../references/CLI.md` 的命令示例 +- `../README.md` 的用户话术 +- `../references/SCHEMA.md` 的字段映射补充说明 如需浏览器自动化，不要在模板里保留空的 `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 平台看的技能入口，**不是**用户市场详情页。 应该重点写： -- 技能名称 -- 技能描述 -- `slug` - 作用：技能的唯一英文标识，通常用于仓库名、发布包名、运行时目录名、平台主键匹配等 - 示例：`your-skill-slug`、`disburse-payroll-icbc`、`tax-invoice-verify` -- `category` - 作用：技能在平台中的分类，用于市场展示与归类，不是代码内部键 - 示例：`通用`、`内容`、`办公协作`、`物流`、`抖音`、`小红书` -- `developer_ids`（如需给非公开技能自动补开发者可见权限） - 作用：声明发布后默认拥有可见权限的开发者用户 ID 列表 -- `dependencies` - 作用：声明该技能依赖的兄弟技能或运行前置能力，便于平台或编排层识别依赖关系 - 示例（按业务填写；发布类可能会依赖账号 / 内容技能，其它领域可能完全不同）： - ```yaml - dependencies: - required: - - some-sibling-skill - ``` -- 何时使用本技能 -- 对用户的引导话术 -- CLI 使用原则 +- YAML frontmatter：`name`、`description`、`version`、`metadata.openclaw`（含 `slug`、`platform_kit_min_version`、`developer_ids` 等） +- 何时触发本技能、CLI 入口摘要、运行契约要点 +- 指向 `references/`（Agent 调用）与 `development/`（开发规范）的分工说明 + +不要在 `SKILL.md` 里写大量用户市场文案或实现细节。 + +### 根 `README.md`（用户市场说明） + +根 `README.md` 是技能市场详情页主来源（`metadata.readme_md`），面向普通用户。 + +应包含 YAML frontmatter 的 `description`（市场列表简介），正文用用户能理解的语言说明： + +- 能做什么、适合什么场景、使用前准备什么 +- 如何自然语言告诉 Agent +- 执行结果、注意事项、常见问题 + +不要在根 `README.md` 里写开发教程、目录规范、release、requirements 等技术细节。 -不要在 `SKILL.md` 里写大量实现细节。 实现细节放在： -- `references/` -- 代码注释 -- `service/` 实现里 +- `development/` +- `references/`（CLI / SCHEMA） +- 代码注释与 `service/` 实现 ### 关于 `metadata.openclaw.developer_ids` @@ -318,33 +320,31 @@ metadata: - 第一个 ID 会同步到 `skills.developer_id` - 一期只做“补授权”，不会因为你 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` - 写给技术人员的测试分层、隔离数据根与档位开关指南（详见 [`references/TESTING.md`](TESTING.md)） +- `README.md` — Agent 参考索引 +- `CLI.md` — 命令、参数、默认值、兄弟技能调用方式 +- `SCHEMA.md` — 数据库路径、核心表结构、日志表结构 +- 可按需增加 `ERRORS.md`、`INTEGRATION.md` 等编排向补充 -如果后面某个 skill 需要更细的说明，可以再加： +**`development/`**（开发者 / AI 编程代理） -- `ERRORS.md` -- `INTEGRATION.md` -- `PLATFORMS.md` +- `REQUIREMENTS.md` — 需求与验收 +- `DEVELOPMENT.md` — 开发教程（本文档） +- `TESTING.md` — 测试分层与隔离（详见 [`TESTING.md`](TESTING.md)） +- `ADAPTER.md`、`RPA.md`、`CONFIG.md`、`RUNTIME.md` — 技术规范 ## 8. `assets/` 应该放什么 @@ -359,7 +359,7 @@ metadata: 比如日志记录、机读 JSON 的 schema 不要把正式研发文档放到 `assets/`。 -文档应该进 `references/`。 +用户说明进根 `README.md`；Agent 编排资料进 `references/`；开发规范进 `development/`。 ## 9. `cli` 层怎么写 @@ -516,7 +516,7 @@ python scripts/main.py 3. **写完 service 业务后**：从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。 4. **接外部系统时**：写在 `tests/integration/`，并配合 `OPENCLAW_TEST_TARGET` 显式开启。 -详见 `references/TESTING.md`。 +详见 `TESTING.md`。 ## 15. 发布到正式环境验证 @@ -573,7 +573,7 @@ python scripts/main.py 如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如： - 发布脚本是否正常推送 -- `SKILL.md`、`scripts/`、`references/` 是否齐全 +- `SKILL.md`、根 `README.md`、`scripts/`、`references/`、`development/` 是否齐全 - 工作流文件是否存在 - 发布包结构是否符合模板规范 @@ -636,7 +636,7 @@ python scripts/main.py - [ ] 目录结构符合当前模板 - [ ] `SKILL.md` 中 slug、名称、描述都已替换 - [ ] `scripts/util/constants.py` 已修改 -- [ ] `references/CLI.md` 示例命令已改成真实命令 +- [ ] `../references/CLI.md` 示例命令已改成真实命令 - [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现 - [ ] 没有残留旧平台名 - [ ] `health` / `version` 可运行 @@ -673,7 +673,7 @@ python scripts/main.py - `task_service.py` - `sibling_bridge.py` -- `references/CLI.md` +- `../references/CLI.md` ### 错误 3：把业务逻辑写进 CLI @@ -698,16 +698,17 @@ python scripts/main.py 现在的新模板原则是： - 不做旧结构兼容 -- 统一走 `references/` + `scripts/main.py` +- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/` +- 统一走 `scripts/main.py` 作为 CLI 入口 ## 18. 推荐开发顺序总结 如果让一个新人照着做，我建议他按这个顺序： 1. 复制模板并改目录名 -2. 改 `SKILL.md` +2. 改 `SKILL.md` 与根 `README.md` 3. 改 `scripts/util/constants.py` -4. 改 `references/` +4. 改 `references/` 与 `development/` 5. 改 `scripts/cli/app.py` 6. 改 `scripts/service/` 7. 跑 `python tests/run_tests.py -v` @@ -721,7 +722,7 @@ python scripts/main.py - 目录结构统一 - 入口统一为 `scripts/main.py` -- 文档统一放 `references/` +- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/` - 业务核心逻辑统一放 `scripts/service/` - 不再使用旧模板历史结构 diff --git a/development/README.md b/development/README.md new file mode 100644 index 0000000..7764881 --- /dev/null +++ b/development/README.md @@ -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)，不要写进本目录。 diff --git a/references/REQUIREMENTS.md b/development/REQUIREMENTS.md similarity index 99% rename from references/REQUIREMENTS.md rename to development/REQUIREMENTS.md index cd3af35..b46011c 100644 --- a/references/REQUIREMENTS.md +++ b/development/REQUIREMENTS.md @@ -273,8 +273,8 @@ 建议每个新 skill 开发时，按下面顺序使用文档： -1. 先写 `references/REQUIREMENTS.md` -2. 再按 `references/DEVELOPMENT.md` 进入开发 +1. 先写 `REQUIREMENTS.md` +2. 再按 `DEVELOPMENT.md` 进入开发 3. 开发过程中补充 `CLI.md`、`SCHEMA.md`、`RUNTIME.md`、`TESTING.md` 4. 发布前回到 `REQUIREMENTS.md` 对照验收标准逐项检查 diff --git a/references/RPA.md b/development/RPA.md similarity index 99% rename from references/RPA.md rename to development/RPA.md index 28e530f..a661252 100644 --- a/references/RPA.md +++ b/development/RPA.md @@ -51,7 +51,7 @@ 6. **可以** `ignore_default_args=["--enable-automation"]`（platform-kit `launch_persistent_browser` 已处理）。 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 ``` -- `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` 对上述资源做只读诊断，不下载、不修复。 完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。 diff --git a/references/RUNTIME.md b/development/RUNTIME.md similarity index 94% rename from references/RUNTIME.md rename to development/RUNTIME.md index 8294cfd..f5e5688 100644 --- a/references/RUNTIME.md +++ b/development/RUNTIME.md @@ -2,7 +2,7 @@ ## 共享 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 依赖声明。 @@ -24,7 +24,7 @@ Windows: `` 通常位于 `{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 诊断，**不在技能内重复实现**。典型字段： @@ -42,7 +42,7 @@ Windows: - 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。 - `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。 - 配置优先级：**进程环境变量** > **用户 `.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 / 背景音乐 @@ -61,6 +61,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均 新技能建议采用以下根目录结构： - `assets/` +- `development/` - `references/` - `scripts/` - `tests/` @@ -103,7 +104,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均 退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。 -详见 `references/TESTING.md` 第 3 节。 +详见 `TESTING.md` 第 3 节。 ## 编码与输出 diff --git a/references/TESTING.md b/development/TESTING.md similarity index 96% rename from references/TESTING.md rename to development/TESTING.md index 14a4499..9a185a1 100644 --- a/references/TESTING.md +++ b/development/TESTING.md @@ -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/` = 只在人被明确要求时才启用的高风险或重量级路径。 @@ -23,7 +23,7 @@ 必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖： - 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`，防路径漂移； - 运行时：`runtime_paths` 与 **`CLAW_*` / `JIANGCHANG_*` 并发兜底； - `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` - [ ] 无 `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`（或等价诊断行） - [ ] `config-path` 可输出用户 `.env` 路径 JSON - [ ] `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) — 表格、变量与目录细则 -- [`references/DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序 +- [`DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序 - [`tests/integration/README.md`](../tests/integration/README.md) — 高风险用法 diff --git a/references/README.md b/references/README.md index a370b0b..e9458ad 100644 --- a/references/README.md +++ b/references/README.md @@ -1,77 +1,13 @@ ---- -description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。" ---- +# Agent 参考索引 -# 【技能名称】 +本目录供 Agent **运行、编排、调用** skill 时渐进式加载，不是用户市场说明。 -用一两句话说明这个技能帮助用户完成什么工作。 -这里不要解释技术实现，要从用户的业务目标出发描述价值。 +| 文档 | 用途 | +|------|------| +| 根目录 [`README.md`](../README.md) | 用户市场详情页说明 | +| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口 | +| [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 | +| [`SCHEMA.md`](SCHEMA.md) | 输入输出、数据库与字段说明 | +| [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） | -## 这个技能能帮你做什么 - -用 3 到 6 条业务能力说明技能价值，例如： - -- 【自动整理/查询/生成/同步/核对/提交】某类业务数据 -- 帮你减少重复操作，降低人工录入或核对成本 -- 在任务完成后给出清晰的处理结果、失败原因或后续建议 - -## 适合什么场景 - -列出典型使用场景。请使用用户熟悉的业务语言，例如： - -- 每天需要重复处理同一类订单、单据、报表或客户资料 -- 需要从多个系统中查询信息并汇总结果 -- 需要按固定规则检查数据是否完整、是否异常 -- 需要把处理结果保存为文件、记录或任务报告 - -## 使用前需要准备什么 - -说明用户在使用前要准备的东西，例如： - -- 相关账号已登录，且具备查询、导出或提交权限 -- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息 -- 如果涉及外部系统，请确认网络、账号、验证码或审批流程可正常使用 - -## 你可以这样告诉 Agent - -用自然语言示例展示用户可以怎么发起任务，例如： - -- “帮我查询今天的【业务对象】，整理成表格。” -- “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。” -- “帮我把【时间范围】内的【业务数据】导出并生成处理报告。” -- “帮我根据这个文件里的内容，逐条完成【业务动作】。” - -注意：示例应是自然语言，不要写命令行命令。 - -## 执行后你会得到什么 - -说明用户会看到什么结果，例如： - -- 任务是否成功完成 -- 处理了多少条数据 -- 哪些内容成功、哪些失败 -- 失败原因和建议处理方式 -- 生成的文件、表格、报告或记录 - -## 注意事项 - -用用户能理解的方式说明边界和风险，例如： - -- 请确认输入范围准确，避免处理错数据 -- 涉及提交、付款、删除、审批等高风险动作时，技能应在执行前请求确认 -- 如果外部系统登录失效、权限不足或页面变化，任务可能需要用户介入 -- 不建议在未核对数据的情况下直接执行批量操作 - -## 常见问题 - -### 为什么任务没有查到数据？ - -可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。 - -### 为什么任务执行到一半需要我操作？ - -可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。 - -### 结果文件在哪里查看？ - -请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。 +按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；运行时环境细节见 `../development/RUNTIME.md`。 diff --git a/scripts/util/constants.py b/scripts/util/constants.py index d3981f6..ba830e7 100644 --- a/scripts/util/constants.py +++ b/scripts/util/constants.py @@ -3,4 +3,4 @@ SKILL_SLUG = "your-skill-slug" SKILL_VERSION = "1.0.14" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" -PLATFORM_KIT_MIN_VERSION = "1.0.13" +PLATFORM_KIT_MIN_VERSION = "1.0.14" diff --git a/tests/_support.py b/tests/_support.py index 59fce24..4a0e285 100644 --- a/tests/_support.py +++ b/tests/_support.py @@ -39,7 +39,7 @@ def get_skill_root() -> str: 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.""" from unittest.mock import patch diff --git a/tests/test_docs_standards.py b/tests/test_docs_standards.py index 279fc60..afd5b4a 100644 --- a/tests/test_docs_standards.py +++ b/tests/test_docs_standards.py @@ -16,17 +16,17 @@ class TestDocsStandards(unittest.TestCase): return f.read() 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("closing_title", text) self.assertIn("中文", text) self.assertIn("--no-sandbox", text) self.assertIn("--disable-blink-features=AutomationControlled", 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: - text = self._read("references/ADAPTER.md") + text = self._read("development/ADAPTER.md") for marker in ( "mock", "simulator_rpa", @@ -45,18 +45,17 @@ class TestDocsStandards(unittest.TestCase): self.assertIn("uv run python", text) 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("pytest.ini", text) def test_docs_do_not_claim_1_0_11_as_current_standard(self) -> None: for rel in ( - "README.md", "SKILL.md", - "references/RUNTIME.md", - "references/RPA.md", - "references/CONFIG.md", - "references/TESTING.md", + "development/RUNTIME.md", + "development/RPA.md", + "development/CONFIG.md", + "development/TESTING.md", ): text = self._read(rel) self.assertNotIn( diff --git a/tests/test_platform_import.py b/tests/test_platform_import.py index b2a0373..a4910c2 100644 --- a/tests/test_platform_import.py +++ b/tests/test_platform_import.py @@ -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 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") with open(md_path, encoding="utf-8") as f: 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") with open(req_path, encoding="utf-8") as f: diff --git a/tests/test_template_runtime_standard.py b/tests/test_template_runtime_standard.py index 435c504..90cb07a 100644 --- a/tests/test_template_runtime_standard.py +++ b/tests/test_template_runtime_standard.py @@ -10,13 +10,15 @@ from _support import get_skill_root DOC_PATHS = ( "README.md", "SKILL.md", - "references/RUNTIME.md", + "development/RUNTIME.md", "references/CLI.md", - "references/DEVELOPMENT.md", - "references/RPA.md", - "references/CONFIG.md", + "development/DEVELOPMENT.md", + "development/RPA.md", + "development/CONFIG.md", ) +RUNTIME_DOC_PATHS = tuple(p for p in DOC_PATHS if p != "README.md") + FORBIDDEN_PHRASES = ( "scripts/jiangchang_skill_core/：运行时", "运行时与统一日志副本", @@ -32,7 +34,7 @@ FORBIDDEN_PHRASES = ( POSITIVE_MARKERS = ( "jiangchang-platform-kit", - "1.0.13", + "1.0.14", "共享 runtime", ) @@ -54,7 +56,7 @@ class TestTemplateRuntimeStandard(unittest.TestCase): ) 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: self.assertIn( marker, @@ -67,7 +69,7 @@ class TestTemplateRuntimeStandard(unittest.TestCase): ) 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) def test_cli_md_mentions_health_runtime_diagnostics(self) -> None: diff --git a/tools/highlight_answers.py b/tools/highlight_answers.py new file mode 100644 index 0000000..f45a814 --- /dev/null +++ b/tools/highlight_answers.py @@ -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() diff --git a/tools/verify_highlight.py b/tools/verify_highlight.py new file mode 100644 index 0000000..eee9a84 --- /dev/null +++ b/tools/verify_highlight.py @@ -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])}")