chore: auto release commit (2026-06-14 11:12:03)

2026-06-14 11:12:04 +08:00
parent 955816c8a7
commit c7d7832749
20 changed files with 466 additions and 254 deletions
--- 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:
--- 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 列表。这样在正式发布后，平台会为这些开发者补可见权限，避免「技能已上架但开发者自己在市场中看不到」。
+## 适合什么场景

-开发教程入口：
+列出典型使用场景。请使用用户熟悉的业务语言，例如：

- <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
-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 返回的结果说明查看生成文件、任务记录或处理报告。
--- 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/` 结构。
--- 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/)
--- a/development/ADAPTER.md
+++ b/development/ADAPTER.md
--- a/development/CONFIG.md
+++ b/development/CONFIG.md
--- a/development/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/<domain>_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 <your-command>
 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 <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、名称、描述都已替换
 - [ ] `scripts/util/constants.py` 已修改
- [ ] `references/CLI.md` 示例命令已改成真实命令
+- [ ] `../references/CLI.md` 示例命令已改成真实命令
 - [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现
 - [ ] 没有残留旧平台名
 - [ ] `health` / `version` 可运行
@@ -673,7 +673,7 @@ python scripts/main.py <your-command>

 - `task_service.py`
 - `sibling_bridge.py`
- `references/CLI.md`
+- `../references/CLI.md`

 ### 错误 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. 推荐开发顺序总结

 如果让一个新人照着做，我建议他按这个顺序：

 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 <your-command>

 - 目录结构统一
 - 入口统一为 `scripts/main.py`
- 文档统一放 `references/`
+- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
 - 业务核心逻辑统一放 `scripts/service/`
 - 不再使用旧模板历史结构

--- a/development/README.md
+++ 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)，不要写进本目录。
--- a/development/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` 对照验收标准逐项检查

--- a/development/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`。
--- a/development/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:

 `<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 诊断，**不在技能内重复实现**。典型字段：

@@ -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 节。

 ## 编码与输出

--- a/development/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) — 高风险用法
--- 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`。
--- 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"
--- 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

--- 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(
--- 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:
--- 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:
--- a/tools/highlight_answers.py
+++ 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()
--- a/tools/verify_highlight.py
+++ 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])}")