@wwkit/harness 1.0.15 → 1.0.17

package/commands/pytest.md

@@ -0,0 +1,11 @@
+---
+description: Python 测试（单元/集成），传入 test_type 和目标模块路径（如 /pytest unit src/mymodule 或 /pytest integration src/mymodule）
+agent: general
+---
+
+对目标模块执行完整的 Python 测试流程。第一个参数为 test_type（unit 或 integration），第二个为源码路径 $2，第三个为可选测试目录 $3。
+
+请用 skill 工具加载 pytest 技能（name=pytest），将以下参数传给它执行：
+- test_type: $1（unit 或 integration）
+- source: $2
+- test_dir: $3（可选，未指定时自动推导）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/harness",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "author": "bluesliu <langcai163@163.com>",
   "description": "WebWork abilities for opencode",
   "type": "module",

package/readme/development.md

@@ -17,7 +17,7 @@ wwkit/
 
 ```
 plugin.js                 # 包入口（"main"），仅把 skills/ 注册进 config.skills.paths
-agents/*.md               # 主代理（extract / revise / query），frontmatter 含权限块
+agents/*.md               # 主代理（work / query / lint），frontmatter 含权限块；extract / revise / pytest 现为纯 skill（pytest 合并原 pyut+pyit）
 skills/<name>/SKILL.md    # 技能定义
 skills/<name>/references/ # 工作流：*.md（LLM 指令）、*.js（ESM 辅助脚本）、*.json5（schema）
 commands/*.md             # opencode 命令（/tl 翻译）

package/skills/extract/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: extract
 description: |
-  从网页 HTML/文本源码/结构化 JSON 中提取内容，按 format 分发到 references/ 对应流程。
-  format=list/detail/text/navi。返回 JSON 数组，不写入任何文件。
-  禁止使用 WebFetch 或任何网络请求获取内容。
+  自包含内容提取 skill：解析入参（JSON/key=value/prose）→ 按 format 分发到 references/ 流程 → schema 校验 → 写 output 文件或 stdout。
+  format=list/detail/text/navi。调用方直接传原始任务消息，skill 自解析自包含。
+  内部用 todowrite 管理 6 步。禁止 WebFetch/网络请求。
   适用：列表页/详情页/纯文本/结构化 JSON 列表/导航 XPath 等各类网页内容提取。
 license: MIT
 metadata:
@@ -12,43 +12,93 @@ metadata:
 
 # extract 技能
 
+## 核心约束（最高优先级）
+
+- **MUST**：收到任务消息后，先 todowrite 落单 6 步，再逐步执行。
+- **MUST**：每步完成立即 todowrite 勾单。
+- **禁止**：使用 WebFetch 或任何网络请求获取内容。
+- **禁止**：写入 output 以外的任何文件；中间产物用临时文件，完成后清理。
+- **禁止**：以任何形式使用未声明字段（count/max_length/max_image_count/language 等）。
+
+## 第一步硬指令（自检）
+
+解析入参前，强制自检：
+> 我是否已用 todowrite 落单 6 步？
+> - 未落单 → 立即 todowrite 创建清单。
+> - 已落单 → 继续。
+
 ## 输入参数
 
-入参来自调用方（agent）已规整后的字段，字段清单（字段/类型/必填）见 `references/input.schema.json5`。
+入参为调用方传入的**原始任务消息**，可能是以下任一形态：
+- **JSON 对象**：如 `{format, source, url, output}`，直接取字段值；
+- **key=value**：如 `format=list, source=xxx`，按 `,` 和 `=` 拆分为字段；
+- **纯文本 prose**：不做格式推断。仅当文本命中 `references/format-aliases.json5` 中某 format 的 `terms`（如"列表/导航/详情/纯文本"）时才翻译为该 format 标准值，`source` 取文本本身。
+
+字段清单（字段/类型/必填）见 `references/input.schema.json5`。本技能仅使用 `source`、`format`、`url`、`output` 四个字段，忽略所有其他字段（如 `count`、`max_length`、`max_image_count`、`language`），不得读取、写入或据此推断任何行为。
 
 ## 输出
 
-返回符合 `references/{{ format }}.schema.json5` 的 JSON **数组**，**不写入任何文件**。
+- 提供 `output` 参数：将 JSON 数组用 `write` 工具写入该文件，stdout 输出文件路径。
+- 未提供 `output` 参数：将 JSON 数组直接输出到 stdout，**不写任何文件**。
+- 校验失败未能产出数组：不写文件、不输出数组，将错误信息输出到 stderr 并结束。
 
 ## 工作流程
 
-### 阶段 1：输入处理
+### 阶段 0：todowrite 落单
 
-- `{{ source }}`：输入内容。若值是现有文件路径，读取文件内容；否则直接以值作为输入。
-- `{{ format }}`：提取类型。当 `format=list` 时，判断 `{{ source }}` 类型：
-  - 若能解析为 JSON 数组，使用 `list_from_json` 流程
-  - 否则若包含 HTML 标签（形如 `<tag`），作为 HTML 源码，使用 `list_from_html` 流程
-  - 否则作为纯文本，使用 `list_from_text` 流程
-- `{{ url }}`：按需透传给对应 format 流程（相对路径转绝对）。
+收到任务消息后，**先**用 `todowrite` 创建 6 步清单（status=pending）：
+
+1. 解析入参（JSON/key=value/prose → format/source/url/output）
+2. 加载 references（format 流程文件 + schema 文件）
+3. 按 format 执行提取
+4. Schema 校验
+5. 校验失败修复重试（≤3 次）
+6. 输出（写 output 文件或 stdout）
+
+每步完成立即 todowrite 勾单（status=completed）。
+
+### 阶段 1：解析入参
+
+将第 1 步标记为 in_progress，解析原始任务消息：
+
+- **JSON 对象**：直接取 `format`/`source`/`url`/`output` 字段值。
+- **key=value**：按 `,` 分割、按 `=` 拆分为键值对，取上述四字段。
+- **纯文本 prose**：用 `read` 读取 `references/format-aliases.json5`，仅当文本命中某 format 的 `terms` 时翻译为该 format 标准值，`source` 取文本本身；未命中则 `format` 视为未提供。
 
-本技能仅使用 `source`、`format`、`url` 三个字段。忽略传入的所有其他字段（如 `count`、`max_length`、`max_image_count`、`language`、`output` 等），不得读取、写入或据此推断任何行为。
+解析后得到：
+- `format`（必填，经别名表翻译为标准值；`list` 由阶段 2 自动检测 source 是 HTML 还是 JSON）
+- `source`（必填，HTML/文本或文件路径，原样透传由后续阶段解析）
+- `url`（可选，相对路径转绝对）
+- `output`（可选）
 
-若 `{{ source }}` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+**必填校验**：若无法解析出 `format` 或 `source`，将错误信息输出到 stderr 并结束，**禁止**继续执行。
 
-若 `{{ format }}` 为空或对应 references 文件不存在：直接输出 `[]` 并结束。
+**空 source 短路**：若 `source` 为空、null 或仅含空白：直接输出 `[]` 并结束，**禁止**继续执行。
+
+完成后 todowrite 勾单第 1 步。
 
 ### 阶段 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=list` 时，先检测 `source` 类型：若值是现有文件路径则读取文件内容；否则以值作为输入。再判断内容类型：
+  - 若能解析为 JSON 数组，使用 `list_from_json` 流程
+  - 否则若包含 HTML 标签（形如 `<tag`），作为 HTML 源码，使用 `list_from_html` 流程
+  - 否则作为纯文本，使用 `list_from_text` 流程
+  - schema 统一使用 `references/list.schema.json5`
 - 其他 format 直接使用 `references/{{ format }}.md` 和 `references/{{ format }}.schema.json5`
 
-用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若任一文件不存在，则输出 `[]` 并结束。
+用 `read` 工具读取两个文件内容，并**记录 schema 文件的绝对路径**（阶段 4 校验时需要）。若 `format` 为空或对应 references 文件不存在：直接输出 `[]` 并结束。
+
+`url` 按需透传给对应 format 流程（相对路径转绝对）。
+
+完成后 todowrite 勾单第 2 步。
 
 ### 阶段 3：按 format 执行提取
 
-按 `references/` 下对应流程文件的步骤执行提取（`list` 格式使用阶段 1 检测的 `list_from_html`/`list_from_json`/`list_from_text`），得到 JSON 数组。**禁止使用 WebFetch 或任何网络请求获取内容。**
+按 `references/` 下对应流程文件的步骤执行提取（`list` 格式使用阶段 2 检测的 `list_from_html`/`list_from_json`/`list_from_text`），得到 JSON 数组。**禁止使用 WebFetch 或任何网络请求获取内容。**
+
+完成后 todowrite 勾单第 3 步。
 
 ### 阶段 4：Schema 校验
 
@@ -58,26 +108,38 @@ metadata:
 node '<技能目录>/references/validate-schema.js' < <临时 JSON 输入文件>
 ```
 
-- 若校验通过，进入阶段 6
-- 若校验失败，进入阶段 5 进行修复重试（最多 3 次）
+- 若校验通过，todowrite 勾单第 4 步，跳过阶段 5，进入阶段 6
+- 若校验失败，todowrite 勾单第 4 步，进入阶段 5 进行修复重试（最多 3 次）
 
 ### 阶段 5：校验失败时修复重试
 
 当 Schema 校验失败时，将错误信息反馈，重新执行阶段 3 提取并再次校验。**最多重试 3 次**，超过则将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
 
+重试成功后 todowrite 勾单第 5 步，进入阶段 6。
+
 ### 阶段 6：输出
 
-**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束。
+**若校验未通过（重试耗尽）：** 将最后一次重试的 schema 校验错误信息及「重试 {N} 次后 schema 校验仍然失败」输出到 stderr 并结束，**不写任何文件**。
+
+**若校验通过：**
+- 提供 `output` 参数：用 `write` 工具将最终 JSON 数组写入 `output` 指定文件（**禁止创建其他文件**），stdout 输出该文件路径。
+- 未提供 `output` 参数：将最终 JSON 数组直接输出到 stdout，**不写任何文件**。
 
-**若校验通过：** 将最终 JSON **数组**作为结果返回。**禁止写入任何文件**；文件写入由调用方（agent）负责。
+完成后 todowrite 勾单第 6 步。
+
+## 工具使用约束
+
+- 写文件一律用 `write` 工具；读文件用 `read` 工具。
+- 需要中间数据时，用 `write` 工具写入临时文件，再以 stdin 重定向传给 node。
+- 禁止使用未授权的 `cp`/`rm`/`mv` 等命令；需要复制、移动或删除临时文件时，一律用允许的 `node -e` 的 fs 模块完成。
+- 除技能校验/本地提取所需 node 外，禁止执行其他 shell。
 
 ## 约束
 
-- 只处理已声明字段（source/format/url），忽略所有其他传入参数（如 `count`、`max_length`、`max_image_count`、`language`、`output`），**禁止**以任何形式使用它们。
-- 本技能不读取、不写入任何输出文件；仅返回 JSON 数组。
-- **禁止使用 WebFetch 或任何网络请求获取内容**；`{{ source }}` 无正文或为空时必须输出 `[]`，绝不自行获取内容。
-- 忽略参数中除已声明字段之外的所有字段。
-- 内部重试步骤的中间产物禁止写入任何文件。
+- 只处理已声明字段（source/format/url/output），忽略所有其他传入参数（如 `count`、`max_length`、`max_image_count`、`language`），**禁止**以任何形式使用它们。
+- **禁止使用 WebFetch 或任何网络请求获取内容**；`source` 无正文或为空时必须输出 `[]`，绝不自行获取内容。
+- 内部重试步骤的中间产物用临时文件，完成后清理，禁止写入 output 以外的任何持久文件。
+- 禁止访问外部网络。
 
 ## 资源目录
 
@@ -97,4 +159,4 @@ references/
 ├── detail.md + detail.schema.json5
 ├── text.md + text.schema.json5
 └── navi.md + navi.schema.json5
-```
+```