@wwkit/harness 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 macair15m3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# harness
+
+> `wwkit` monorepo 下的子包（`packages/harness`），原为 `webwork-ability`。
+
+WebWork abilities for opencode — 提供内容提取（extract）、内容创作（revise）等技能与代理，让 opencode 具备从网页提取结构化内容、基于素材二次创作等能力。
+
+## 前提
+
+技能依赖 `node` 运行辅助脚本（如 `references/validate-schema.js`）。调用 opencode 的环境需确保 `node` 在 PATH 中（opencode 的 bash 工具会继承其启动时的环境）。若用 Python 等子进程方式调用，请在 spawn 前把 node 所在目录加入 PATH：
+
+```python
+import shutil, os
+node = shutil.which("node") or os.path.expanduser("~/.nvm/versions/node/*/bin/node")
+os.environ["PATH"] = f"{os.path.dirname(node)}:{os.environ.get('PATH', '')}"
+```
+
+## 安装
+
+本包位于 `wwkit` pnpm monorepo 的 `packages/harness`。在仓库根目录安装依赖：
+
+```bash
+cd wwkit
+pnpm install
+```
+
+### 在 opencode 中使用（发布为 npm 包后）
+
+```bash
+cd ~/.config/opencode
+npm install harness
+```
+
+## 引入方式
+
+本包提供两种引入方式，按需选择一种：
+
+| 方式 | 配置 | 提供内容 | 适用 |
+|------|------|---------|------|
+| **A. 插件模式（仅技能）** | 在 `~/.config/opencode/opencode.jsonc` 注册插件 | 仅 `extract`/`revise` **技能** | 只需要技能能力 |
+| **B. 环境变量模式（完整，推荐）** | 设置 `OPENCODE_CONFIG_DIR` 指向包目录 | **代理 + 技能**（原生扫描 `agents/`、`skills/`） | 需要代理完整能力 |
+
+### 方式 A：插件模式（仅技能）
+
+在 `~/.config/opencode/opencode.jsonc` 中注册插件：
+
+```jsonc
+{
+  "plugin": ["node_modules/harness"]
+}
+```
+
+该模式仅注册技能（`extract`/`revise`）。opencode 不支持通过插件注册代理（`agents.paths` 字段不存在），因此**方式 A 不含代理**。
+
+### 方式 B：环境变量模式（完整，推荐）
+
+将 `OPENCODE_CONFIG_DIR` 指向包的安装目录，opencode 会把它当作配置目录，原生发现其中的 `agents/`、`skills/`：
+
+```bash
+echo 'export OPENCODE_CONFIG_DIR="$HOME/.config/opencode/node_modules/harness"' >> ~/.zshrc
+```
+
+说明：
+- 需在**启动 opencode 前**设置环境变量；
+- 与用户原有配置目录是**叠加**关系，不覆盖已有代理/技能；
+- 该变量为**单一路径**，同时只能指向一个目录；
+- 若之前注册过插件（方式 A），改用方式 B 时请移除 `opencode.jsonc` 中的 `plugin` 项，避免技能重复扫描。
+
+## 功能
+
+### Agents（代理）
+
+| Agent | 作用 |
+|-------|------|
+| `extract` | 从网页 HTML/文本/JSON 提取结构化内容（列表/详情/纯文本/导航），写入输出文件 |
+| `revise` | 基于原始素材二次创作（问题/文章/图集/动态），写入输出文件 |
+| `query` | 根据 prompt 生成内容，支持 source/language/output |
+
+### Skills（技能）
+
+| Skill | 作用 |
+|-------|------|
+| `extract` | 按 format（list/detail/text/navi）从 HTML/文本/JSON 提取内容 |
+| `revise` | 按 format（question/status/gallery/article）二次创作内容 |
+
+## 使用方式
+
+```bash
+# 使用 extract agent：从 HTML 或文本提取列表
+opencode run --agent extract '{"format": "list", "source": "<html/文本或路径>", "output": "/tmp/list.json"}'
+
+# 使用 extract agent：提取单条详情
+opencode run --agent extract '{"format": "detail", "source": "<html或路径>", "output": "/tmp/result.json"}'
+
+# 使用 revise agent：基于素材创作文章
+opencode run --agent revise '{"format": "article", "source": "<素材>", "output": "/tmp/article.json"}'
+
+# 使用 query agent：直接生成内容
+opencode run --agent query '{"prompt": "写一篇关于AI的文章"}'
+```
+
+未提供 `output` 时，结果直接输出到 stdout。

package/agents/extract.md

@@ -0,0 +1,38 @@
+---
+description: 从网页 HTML/文本源码提取结构化内容（list/detail/text/navi），
+  通过 extract 技能生成 JSON 数组并写入输出文件。
+mode: primary
+temperature: 0.2
+permission:
+  skill: allow
+  read: allow
+  edit: allow
+  webfetch: deny
+  bash:
+    "*": deny
+    "node*": allow
+    "ls*": allow
+    "cat*": allow
+    "test*": allow
+    "echo*": allow
+    "pwd*": allow
+---
+
+你是内容提取编辑。收到任务消息后，提取其中的参数执行：
+
+1. 用 `skill` 工具加载 `extract` 技能，并用 `read` 读取技能目录下的 `references/input.schema.json5`（入参字段清单）。
+2. 解析入参。任务消息可能含以下任一形态：
+   - **JSON 对象**：如 `{format, source, url}`，直接取字段值；
+   - **key=value**：如 `format=list, source=xxx`，拆分为字段；
+   - **纯文本 prose**：不做格式推断。此时用 `read` 读取技能目录下的 `references/format-aliases.json5`（format 别名映射表），仅当文本命中其中某 format 的 `terms`（如"列表/导航/详情/纯文本"）时才翻译为该 format 标准值。
+   之后的 `format`（必填，经别名表翻译；list 由技能自动检测 source 是 HTML 还是 JSON）、`source`（必填，HTML/文本或文件路径，原样透传由技能解析）、`url`（可选，相对路径转绝对）、`output`（可选）。其他参数（如 count/max_length/max_image_count/language）被技能忽略。若无法解析出必填的 `format` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**调用技能。
+3. 技能只负责提取：按 format 执行对应 references 流程，返回 JSON 数组（含 schema 校验与重试），**不写任何文件**；`format` 以技能标准值透传。
+4. `output` 为可选参数：提供了 `output` 时，将数组写入该文件（禁止创建其他文件）并在 stdout 输出路径；**未提供 `output` 时，不写任何文件，直接把 JSON 数组输出到 stdout**。
+5. 若技能校验失败未能产出数组，则不写文件/不输出数组，将错误信息输出到 stderr 并结束。
+6. 禁止访问外部网络；除技能校验/本地提取所需 node 外，禁止执行其他 shell。
+
+## 工具使用约束
+
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。
+- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成（如 `require('fs').copyFileSync(...)`、`require('fs').unlinkSync(...)`）。

package/agents/query.md

@@ -0,0 +1,54 @@
+---
+description: 根据用户要求生成内容，支持 prompt/source/language/output 参数并按 revise 风格输出。
+mode: primary
+temperature: 0.7
+permission:
+  skill: allow
+  read: allow
+  edit: allow
+  webfetch: deny
+  bash:
+    "*": deny
+    "node*": allow
+    "ls*": allow
+    "cat*": allow
+    "test*": allow
+    "echo*": allow
+    "pwd*": allow
+---
+
+你是内容生成编辑。收到任务消息后，提取其中的参数执行：
+
+## 入参字段
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `prompt` | string | 是 | - | 任务要求，包含输出格式说明 |
+| `source` | string | 否 | - | 原始素材：普通文本或文件路径（可选） |
+| `language` | string | 否 | 中文 | 输出语言 |
+| `output` | string | 否 | - | 输出文件路径（可选，未提供时输出到 stdout） |
+
+## 解析入参
+
+任务消息可能为以下任一形态：
+
+- **JSON 对象**：如 `{"prompt": "写一篇关于AI的文章", "output": "/tmp/out.txt"}`，直接取字段值；
+- **key=value**：如 `prompt=写一篇关于AI的文章, output=/tmp/out.txt`，按 `=` 拆分键值对，字段名匹配上表；
+- **自然语言**：尝试从文本中推断提取参数（如"输出到xxx"→`output`、"素材xxx"→`source`、"用英文"→`language`），剩余内容作为 `prompt`；若无法提取，整段文本作为 `prompt`。
+
+## 执行
+
+1. 若 `prompt` 为空或仅含空白字符，将错误信息输出到 stderr 并结束，**禁止**继续执行。
+2. 利用自身能力按 `prompt` 要求生成内容：
+   - `source` 非空时，若值为现有文件路径则读取文件内容，否则直接以值作为素材
+   - 输出语言使用 `language`（默认中文）
+3. 输出处理：
+   - **提供了 `output`**：将结果写入该文件（禁止创建其他文件），在 stdout 输出路径
+   - **未提供 `output`**：不写文件，直接把结果输出到 stdout
+4. 若结果为空或生成失败，将错误信息输出到 stderr 并结束。
+
+## 工具使用约束
+
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。
+- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成（如 `require('fs').copyFileSync(...)`、`require('fs').unlinkSync(...)`）。

package/agents/revise.md

@@ -0,0 +1,40 @@
+---
+description: 基于原始素材进行二次创作（question/status/gallery/article），
+  通过 revise 技能生成 JSON 数组并写入输出文件。
+mode: primary
+temperature: 0.7
+permission:
+  skill: allow
+  read: allow
+  edit: allow
+  webfetch: deny
+  bash:
+    "*": deny
+    "node*": allow
+    "ls*": allow
+    "cat*": allow
+    "test*": allow
+    "echo*": allow
+    "pwd*": allow
+---
+
+你是内容创作编辑。收到任务消息后，提取其中的参数执行：
+
+1. 用 `skill` 工具加载 `revise` 技能，并用 `read` 读取技能目录下的 `references/input.schema.json5`（入参字段清单）。
+2. 解析入参。任务消息可能为以下任一形态：
+   - **JSON 对象**：如 `{format, source, count, language}`，直接取字段值；
+   - **key=value**：如 `format=question, source=xxx`，拆分为字段；
+   - **纯文本 prose**：不做格式推断（同一 source 可有多种 format）。此时用 `read` 读取技能目录下的 `references/format-aliases.json5`（format 别名映射表），仅当文本命中其中某 format 的 `terms`（如"问题/文章/图集/动态"）时才翻译为该 format 标准值。
+   之后的字段：
+   - `format`（必填，经别名表翻译为标准值）、`source`（必填，素材文本或文件路径，原样透传由技能解析）、`count`（可选，数值，缺省透传空由技能按默认 1 处理）、`language`（可选，缺省透传空由技能按默认 中文 处理）、`output`（输出文件路径，可选）。
+   若无法解析出必填的 `format` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**调用技能。
+3. 技能只负责执行内容：按 source/format/count/language 生成 JSON 数组（含 schema 校验与重试），**不写任何文件**；`format` 以本步骤翻译后的标准值透传。
+4. `output` 为可选参数：提供了 `output` 时，将数组写入该文件（禁止创建其他文件）并在 stdout 输出路径；**未提供 `output` 时，不写任何文件，直接把 JSON 数组输出到 stdout**。
+5. 若技能校验失败未能产出数组，则不写文件/不输出数组，将错误信息输出到 stderr 并结束。
+6. 禁止访问外部网络；除技能校验所需 node 外，禁止执行其他 shell。
+
+## 工具使用约束
+
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。
+- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成（如 `require('fs').copyFileSync(...)`、`require('fs').unlinkSync(...)`）。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@wwkit/harness",
+  "version": "1.0.4",
+  "author": "bluesliu <langcai163@163.com>",
+  "description": "WebWork abilities for opencode",
+  "type": "module",
+  "main": "plugin.js",
+  "files": [
+    "plugin.js",
+    "skills",
+    "agents",
+    "readme"
+  ],
+  "jest": {
+    "transform": {},
+    "moduleNameMapper": {},
+    "testMatch": [
+      "**/tests/unit/**/*.test.js",
+      "**/tests/e2e/**/*.test.cjs"
+    ],
+    "setupFiles": [
+      "./jest.setup.cjs"
+    ]
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@gitee.com:Nameless_2/webwork-ability.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "cheerio": "^1.0.0",
+    "json5": "^2.2.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.18",
+    "jest": "^29.7.0"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache",
+    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
+    "e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache",
+    "e2e:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/e2e",
+    "release": "pnpm version patch && pnpm publish"
+  }
+}

package/plugin.js

@@ -0,0 +1,19 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const WebWorkAbilityPlugin = async () => {
+  const root = path.resolve(__dirname);
+
+  return {
+    config: async (config) => {
+      const skillsDir = path.join(root, 'skills');
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+      if (!config.skills.paths.includes(skillsDir)) {
+        config.skills.paths.push(skillsDir);
+      }
+    }
+  };
+};

package/readme/development.md

@@ -0,0 +1,37 @@
+# 开发
+
+## Monorepo 结构
+
+本包位于 `wwkit` pnpm monorepo 下：
+
+```
+wwkit/
+├── package.json           # 仓库根，聚合脚本（pnpm -r --filter ./packages/**）
+├── pnpm-workspace.yaml    # 工作区声明（packages/*）+ allowBuilds
+├── pnpm-lock.yaml
+└── packages/
+    └── harness/           # 本包（原 webwork-ability，opencode 插件）
+```
+
+## 仓库结构（packages/harness 内）
+
+```
+plugin.js                 # 包入口（"main"），仅把 skills/ 注册进 config.skills.paths
+agents/*.md               # 主代理（extract / revise / query），frontmatter 含权限块
+skills/<name>/SKILL.md    # 技能定义
+skills/<name>/references/ # 工作流：*.md（LLM 指令）、*.js（ESM 辅助脚本）、*.json5（schema）
+tests/unit/               # 单元测试（ESM）
+tests/e2e/                # E2E 测试（CommonJS，真实调用 opencode run）
+readme/                   # 分模块文档（发布 / 测试 / 开发）
+```
+
+## 约定
+
+- 开发与改动约定的权威说明见 `AGENTS.md`（文件格式 ESM/CJS 边界、技能工作流、schema 校验、无网络等约束）。
+- 两种引入方式：**插件模式**仅注册技能（`plugin.js` 经 `config.skills.paths`）；**环境变量模式**（`OPENCODE_CONFIG_DIR` 指向包目录）原生发现代理与技能。两者二选一，避免技能重复扫描。
+- 新增技能只需在 `skills/` 添加目录，新增代理只需在 `agents/` 添加 `.md` 文件，均无需改 `plugin.js`。
+- 新增 `revise`/`extract` 的 format 需同时提供 `<format>.md` 与 `<format>.schema.json5`（schema 为数组，`minItems: 1`）。
+
+## 测试
+
+测试命令见 [`readme/testing.md`](./testing.md)，发布步骤见 [`readme/publish.md`](./publish.md)。

package/readme/publish.md

@@ -0,0 +1,38 @@
+# 发布 npm 包
+
+发布配置已就绪：`package.json` 的 `files` 白名单（仅发布 `plugin.js`、`skills/`、`agents/`）、`prepublishOnly`（发布前自动跑单元测试）、`publishConfig.registry`（发布强制官方源，安装仍走国内镜像）。
+
+发布需在包目录 `packages/harness` 下执行 pnpm 命令：
+
+```bash
+# 0. 一键发布（升 patch 版本 + 发布，等价于 pnpm version patch && pnpm publish）
+pnpm run release
+
+# 1. 检查将发布的内容（应为 40 个文件左右，不含 tests/ 等）
+pnpm pack --dry-run
+
+# 2. 升级版本（patch/minor/major 按需）
+pnpm version patch
+
+# 3. 认证：将 npmjs 的 Access Token 写入用户级 ~/.npmrc
+#    //registry.npmjs.org/:_authToken=npm_xxxxx
+#    若账号开启了 2FA，token 需在创建时勾选 "Bypass 2FA"，否则发布时需加 --otp=<动态码>
+
+# 4. 发布（自动先跑 pnpm run test:all）
+pnpm publish
+
+# 5. 验证
+#    默认走仓库 .npmrc 的国内镜像（同步快，一般即可确认）
+npm view harness version dist-tags.latest
+#    显式指定官方源确认发布成功
+npm view harness version dist-tags.latest --registry=https://registry.npmjs.org/
+#    查看已发布的所有版本
+npm view harness versions
+```
+
+## 注意事项
+
+- token 只写入 `~/.npmrc`（用户级），不要写进仓库的 `.npmrc` 或提交到 git。
+- 仓库 `.npmrc` 指向国内镜像（淘宝 npmmirror），只影响安装；发布由 `publishConfig.registry` 强制走官方源。
+- 包名在官方源首次发布前需未被占用；之后每次发布必须先 `pnpm version` 升版本（npm 不允许重复发布相同版本）。
+- 在 monorepo 内发布单个子包，务必在包目录（而非仓库根）执行 `pnpm publish`。

package/readme/testing.md

@@ -0,0 +1,36 @@
+# 测试
+
+Jest 需要 `--experimental-vm-modules` 和 `--no-cache`。请使用 pnpm 脚本，不要直接跑裸 `jest`。本包位于 `wwkit` monorepo 的 `packages/harness`，以下命令需在该目录下执行（或在仓库根用 `pnpm --filter harness run ...`）。
+
+## 单元测试（tests/unit/）
+
+```bash
+# pnpm 命令
+pnpm test -- tests/unit/build-xpath.test.js   # 指定单个测试文件
+pnpm run test:all                             # 整个 tests/unit/ 目录
+
+# 直接使用 jest（需 ESM 支持标志；pnpm 下 jest bin 是 shell shim，须指向实际 JS 入口）
+node --experimental-vm-modules node_modules/jest/bin/jest.js tests/unit/build-xpath.test.js --no-cache  # 单个文件
+node --experimental-vm-modules node_modules/jest/bin/jest.js tests/unit --no-cache                       # 整个目录
+```
+
+单元测试为 ESM（`.js`），直接 import `skills/*/references/*.js` 的导出函数。
+
+## E2E 测试（tests/e2e/，调用 opencode run 实际执行）
+
+```bash
+# pnpm 命令
+pnpm run e2e -- tests/e2e/query/print.test.cjs   # 指定单个测试文件
+pnpm run e2e:all                                  # 整个 tests/e2e/ 目录
+
+# 直接使用 jest
+node --experimental-vm-modules node_modules/jest/bin/jest.js tests/e2e/query/print.test.cjs --no-cache  # 单个文件
+node --experimental-vm-modules node_modules/jest/bin/jest.js tests/e2e --no-cache                       # 整个目录
+```
+
+E2E 要点（完整约定见 `tests/e2e/README.md`）：
+
+- E2E 测试为 **CommonJS（`.cjs`）**，禁止写成 ESM `.js`（会触发 jest 的 "Cannot log after tests are done" 异步问题）。
+- 执行真实 `opencode run --auto --pure`，**无断言**，只打印结果需人工判断；`opencode` 必须在 PATH 上。
+- `jest.setup.cjs` 设置 `OPENCODE_CONFIG_DIR=process.cwd()`（加载本仓库插件）与全局 300s 超时；`tests/e2e/helper.cjs` 对子进程有超时 kill 清理。
+- 输出文件一律写入 `tmpdir()`，不污染仓库。

package/skills/extract/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: extract
+description: |
+  从网页 HTML/文本源码/结构化 JSON 中提取内容，按 format 分发到 references/ 对应流程。
+  format=list/detail/text/navi。返回 JSON 数组，不写入任何文件。
+  禁止使用 WebFetch 或任何网络请求获取内容。
+  适用：列表页/详情页/纯文本/结构化 JSON 列表/导航 XPath 等各类网页内容提取。
+license: MIT
+metadata:
+  workflow: sequential
+---
+
+# extract 技能
+
+## 输入参数
+
+入参来自调用方（agent）已规整后的字段，字段清单（字段/类型/必填）见 `references/input.schema.json5`。
+
+## 输出
+
+返回符合 `references/{{ format }}.schema.json5` 的 JSON **数组**，**不写入任何文件**。
+
+## 工作流程
+
+### 阶段 1：输入处理
+
+- `{{ source }}`：输入内容。若值是现有文件路径，读取文件内容；否则直接以值作为输入。
+- `{{ format }}`：提取类型。当 `format=list` 时，判断 `{{ source }}` 类型：
+  - 若能解析为 JSON 数组，使用 `list_from_json` 流程
+  - 否则若包含 HTML 标签（形如 `<tag`），作为 HTML 源码，使用 `list_from_html` 流程
+  - 否则作为纯文本，使用 `list_from_text` 流程
+- `{{ url }}`：按需透传给对应 format 流程（相对路径转绝对）。
+
+本技能仅使用 `source`、`format`、`url` 三个字段。忽略传入的所有其他字段（如 `count`、`max_length`、`max_image_count`、`language`、`output` 等），不得读取、写入或据此推断任何行为。
+
+若 `{{ source }}` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+
+若 `{{ format }}` 为空或对应 references 文件不存在：直接输出 `[]` 并结束。
+
+### 阶段 2：加载 references
+
+从技能目录的 `references/` 加载流程文件和 schema 文件：
+
+- `format=list` 时，流程文件根据阶段 1 检测结果使用 `references/list_from_html.md`、`references/list_from_json.md` 或 `references/list_from_text.md`；schema 统一使用 `references/list.schema.json5`
+- 其他 format 直接使用 `references/{{ format }}.md` 和 `references/{{ format }}.schema.json5`
+
+用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若任一文件不存在，则输出 `[]` 并结束。
+
+### 阶段 3：按 format 执行提取
+
+按 `references/` 下对应流程文件的步骤执行提取（`list` 格式使用阶段 1 检测的 `list_from_html`/`list_from_json`/`list_from_text`），得到 JSON 数组。**禁止使用 WebFetch 或任何网络请求获取内容。**
+
+### 阶段 4：Schema 校验
+
+用 `write` 工具将待校验的 JSON 数组写入临时文件，再用 `write` 工具将 `{"data": <JSON 数组>, "schema_path": "<schema 绝对路径>"}` 写入 JSON 输入文件，stdin 重定向交给 Node.js 校验：
+
+```bash
+node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
+```
+
+- 若校验通过，进入阶段 6
+- 若校验失败，进入阶段 5 进行修复重试（最多 3 次）
+
+### 阶段 5：校验失败时修复重试
+
+当 Schema 校验失败时，将错误信息反馈，重新执行阶段 3 提取并再次校验。**最多重试 3 次**，超过则将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
+
+### 阶段 6：输出
+
+**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
+
+**若校验通过：** 将最终 JSON **数组**作为结果返回。**禁止写入任何文件**；文件写入由调用方（agent）负责。
+
+## 约束
+
+- 只处理已声明字段（source/format/url），忽略所有其他传入参数（如 `count`、`max_length`、`max_image_count`、`language`、`output`），**禁止**以任何形式使用它们。
+- 本技能不读取、不写入任何输出文件；仅返回 JSON 数组。
+- **禁止使用 WebFetch 或任何网络请求获取内容**；`{{ source }}` 无正文或为空时必须输出 `[]`，绝不自行获取内容。
+- 忽略参数中除已声明字段之外的所有字段。
+- 内部重试步骤的中间产物禁止写入任何文件。
+
+## 资源目录
+
+```
+references/
+├── build-xpath.js              # navi 的 XPath 构造脚本
+├── clean-html.js               # HTML 清洗
+├── extract-detail.js           # 详情页正文提取（按 img 切分）
+├── extract-sample.js           # 列表页样本截取
+├── extract-regex.js            # 正则批量提取
+├── validate-schema.js          # Schema 校验
+├── input.schema.json5
+├── list.schema.json5
+├── list_from_html.md
+├── list_from_json.md
+├── list_from_text.md
+├── detail.md + detail.schema.json5
+├── text.md + text.schema.json5
+└── navi.md + navi.schema.json5
+```

package/skills/extract/references/build-xpath.js

@@ -0,0 +1,31 @@
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+
+const QUOTE_PATTERN = /[\u201c\u201d\u2018\u2019"'"]+/;
+
+export function buildXpath(title) {
+  const fragments = title.split(QUOTE_PATTERN).map(s => s.trim()).filter(Boolean);
+  if (!fragments.length) fragments.push(title);
+  const conditions = fragments.map(f =>
+    `contains(.,'${f.replace(/'/g, "'")}')`
+  ).join(' and ');
+  return `//text()[${conditions} and not(ancestor::script)]/..`;
+}
+
+function main() {
+  const rl = createInterface({ input: process.stdin });
+  let raw = '';
+  rl.on('line', line => { raw += line; });
+  rl.on('close', () => {
+    try {
+      const items = JSON.parse(raw);
+      if (!Array.isArray(items)) { console.log('[]'); return; }
+      const result = items
+        .filter(item => item.title)
+        .map(item => ({ selector: buildXpath(item.title), title: item.title }));
+      console.log(JSON.stringify(result, null, 2));
+    } catch { console.log('[]'); }
+  });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();