@wwkit/harness 1.0.9 → 1.0.10

package/skills/lint-config-setup/references/languages/py.md

@@ -0,0 +1,89 @@
+# Python Ruff 规则清单
+
+## 工具信息
+
+| 项 | 值 |
+|---|---|
+| 工具 | Ruff |
+| 安装 | `pip install ruff` 或 `uv add --dev ruff` |
+| 配置文件 | `ruff.toml` |
+| 检查命令 | `ruff check {target_dir} --output-format json` |
+| 修复命令 | `ruff check {target_dir} --fix` |
+| 输出格式 | JSON 数组，每元素含 code/message/filename/location |
+
+## Ruff JSON 输出解析
+
+```json
+[
+  {
+    "code": "F401",
+    "message": "'os' imported but unused",
+    "filename": "/abs/path/to/file.py",
+    "location": [10, 1],
+    "end_location": [10, 10],
+    "fix": null
+  }
+]
+```
+
+- `fix` 非 null = 可自动修复（`fixable = true`）
+- severity 映射：F 前缀 = error，E 前缀 = error，W 前缀 = warning，UP 前缀 = warning
+
+## 规则清单
+
+> 初始启用标记 ✓ 的规则在配置生成时写入 config 文件；✗ 的规则仅记录在清单中，后续可逐步放开。
+
+### Pyflakes (F)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| F401 | 未使用的 import | error | ✓ | ✓ |
+| F811 | 重定义未使用的名称 | error | ✓ | ✓ |
+| F841 | 未使用的局部变量 | error | ✓ | ✓ |
+| F501 | f-string 无占位符 | error | ✗ | ✓ |
+| F541 | f-string 无占位符 | error | ✗ | ✓ |
+| F601 | 字典字面量重复键 | error | ✗ | ✓ |
+| F621 | 参数列表解包重复 | error | ✗ | ✗ |
+| F622 | 星号后重复参数 | error | ✗ | ✗ |
+| F633 | 非法 __future__ import | error | ✗ | ✗ |
+| F701 | break 在循环外 | error | ✗ | ✗ |
+| F821 | 未定义名称 | error | ✗ | ✗ |
+| F822 | __all__ 中未定义名称 | error | ✗ | ✗ |
+
+### Pycodestyle (E/W)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| E711 | 比较使用 None 应为 is None | error | ✓ | ✓ |
+| E712 | 比较使用 True/False 应为 is | error | ✗ | ✓ |
+| E713 | not in 应替代 not ... in | error | ✗ | ✓ |
+| E714 | is not 应替代 not ... is | error | ✗ | ✓ |
+| E501 | 行过长（默认 88 字符） | warn | ✗ | ✗ |
+| E302 | 预期 2 个空行 | warn | ✗ | ✓ |
+| E303 | 函数间空行过多 | warn | ✗ | ✓ |
+| E305 | 函数/类后 2 个空行 | warn | ✗ | ✓ |
+| W291 | 行尾空格 | warn | ✗ | ✓ |
+| W292 | 文件末尾无换行 | warn | ✗ | ✓ |
+| W293 | 空行有空白字符 | warn | ✗ | ✓ |
+
+### Pyupgrade (UP)
+
+| 规则 | 描述 | 默认级别 | 初始启用 | 可 fix |
+|------|------|---------|---------|--------|
+| UP001 | 过时的 __future__ import | warn | ✗ | ✓ |
+| UP010 | 过时的 __future__ union types | warn | ✗ | ✓ |
+| UP011 | 不必要的 lru_cache 括号 | warn | ✗ | ✓ |
+| UP015 | 不必要的 open 模式 | warn | ✗ | ✓ |
+
+## 配置文件模板（ruff.toml）
+
+```toml
+[lint]
+# 初始启用规则
+select = ["F401", "F811", "F841", "E711"]
+
+[lint.fix]
+unsafe-fixes = false
+```
+
+> 仅写入初始启用 ✓ 的规则。用户已有配置文件时只追加缺失规则，不覆盖。

package/skills/lint-env-ensure/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: lint-env-ensure
+description: |
+  检查 lint 工具可用性，缺失时在项目内自动安装。按主语言检查对应 linter（jsts→eslint，python→ruff），
+  安装失败重试 3 次。加载配置清单供后续 skill 共享。
+  适用：lint agent 的环境检查阶段，在配置生成和规则分析前确保工具可用。
+  不适用：非 lint 场景的环境检查、系统级工具安装。
+---
+
+# Lint 环境检查
+
+## 工作流模式
+
+顺序执行，4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+
+## 输出
+
+- `linter_name`：linter 名称（`eslint` 或 `ruff`）
+- `linter_version`：linter 版本号
+- `linter_installed`：是否已安装且可用（bool）
+- `config`：从 references/config.md 加载的配置对象
+
+## 阶段一：检查工具可用性
+
+按 `primary_language` 检查对应 linter：
+
+| 主语言 | linter | 检查命令 |
+|--------|--------|---------|
+| jsts | eslint | `npx eslint --version` |
+| python | ruff | `ruff --version` |
+
+## 阶段二：自动安装（工具缺失时）
+
+工具不可用时，在项目内安装：
+
+| 主语言 | 安装命令 | 备注 |
+|--------|---------|------|
+| jsts | `cd {root_dir} && npm install -D eslint` | TS 项目额外安装 `@typescript-eslint/parser @typescript-eslint/eslint-plugin` |
+| python | `cd {root_dir} && pip install ruff` 或 `cd {root_dir} && uv add --dev ruff` | 优先用 uv，回退到 pip |
+
+安装失败时重试，最多 3 次（`install_retry` 来自 config）。
+
+## 阶段三：安装验证
+
+重新执行阶段一的检查命令，确认安装成功。
+
+| 条件 | 动作 |
+|------|------|
+| 工具可用 | 输出 linter_name/version/installed=true，继续 |
+| 工具仍不可用 | 输出 installed=false，agent 退出 |
+
+## 阶段四：加载配置
+
+读取 `references/config.md`，输出配置对象供后续 skill 使用。
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 工具已安装 | 输出结果，流程结束 |
+| 工具缺失，安装成功 | 输出结果，流程结束 |
+| 工具缺失，安装失败 | 输出 installed=false，agent 退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 检查命令执行失败 | 认为工具未安装，进入安装流程 |
+| npm install 失败 | 重试最多 3 次 |
+| pip install 失败 | 尝试 uv add，再失败则重试 |
+| 重试 3 次仍失败 | 输出 installed=false |
+
+## 一定要做
+
+1. 在项目内安装（`npm install -D`），不安装全局
+2. 安装后必须重新验证工具可用性
+3. 加载 config.md 配置供后续 skill 共享
+4. TS 项目检查是否需要 @typescript-eslint 插件
+
+## 一定不要做
+
+1. 不要全局安装工具（`npm install -g`）
+2. 不要跳过安装验证步骤
+3. 不要修改项目配置文件（package.json 等）
+4. 不要使用 webfetch 下载工具，仅通过包管理器（npm/pip/uv）安装

package/skills/lint-env-ensure/references/config.md

@@ -0,0 +1,65 @@
+# lint 检查代理配置清单
+
+> 本文件是 lint 代理的全局配置，agent 启动时首先读取，后续所有 skill 共享。
+
+## 依赖工具
+
+### JS/TS
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| eslint | `npx eslint --version` | true | `npm install -D eslint` |
+| @typescript-eslint/parser | `npx tsc --version` 时需要 | false | `npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin` |
+
+### Python
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| ruff | `ruff --version` | true | `pip install ruff` 或 `uv add --dev ruff` |
+
+## 环境检查
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| install_retry | 3 | 工具安装失败重试次数 |
+
+## Loop 控制
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| outer_max | 3 | 外层 loop（check→fix→recheck）最大轮次 |
+| inner_max | 3 | lint-ai-fix 内部 loop 最大轮次 |
+
+## 评分模型
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| target_score | 100 | 二元制：0 违规=100，1+ 违规=0 |
+| pass_threshold | 0 | 违规数达标线（0 = 全部通过） |
+
+## 命名规则
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| report_dir_pattern | `{root_dir}/.webwork/lint/reports/{YYYYMMDD_HHMMSS}/` | 报告输出目录 |
+| report.lint_report | `lint_report.md` | 最终报告文件名 |
+
+## 语言映射
+
+| 语言 | 标识 | 扩展名 | manifest | linter | config_file |
+|------|------|--------|----------|--------|-------------|
+| JS/TS/Vue | jsts | .js .jsx .ts .tsx .vue .mjs .cjs | package.json | eslint | eslint.config.js |
+| Python | python | .py | pyproject.toml / setup.py | ruff | ruff.toml |
+
+## 排除目录
+
+```
+node_modules/ dist/ build/ .git/ __pycache__/ .venv/ venv/ .webwork/ reports/ coverage/ .next/ .nuxt/ .output/ .eggs/ eggs/
+```
+
+## 语法验证命令
+
+| 语言 | 命令 | 说明 |
+|------|------|------|
+| jsts | `node --check {file}` | Node.js 语法检查 |
+| python | `python3 -m py_compile {file}` | Python 字节码编译检查 |

package/skills/lint-language-detect/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: lint-language-detect
+description: |
+  探测工程主语言。优先检查 manifest 文件（package.json → jsts，pyproject.toml/setup.py → python），
+  无 manifest 时按源码文件扩展名计数，多者为主语言。JS/TS 视为一种语言。
+  适用：lint agent 的语言探测阶段，在环境检查和配置生成前确定主语言。
+  不适用：非 lint 场景的语言检测、混合语言项目（v1 按主语言处理，不支持混合）。
+---
+
+# 主语言探测
+
+## 工作流模式
+
+顺序执行，2 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+
+## 输出
+
+- `primary_language`：主语言标识（`jsts` 或 `python`）
+- `detection_method`：检测方式（`manifest` 或 `file_count`）
+- `file_counts`：各语言源码文件计数（仅 `file_count` 方式时有值）
+
+## 阶段一：Manifest 检测
+
+检查 `root_dir` 下的 manifest 文件：
+
+| 检查项 | 命中结果 |
+|--------|---------|
+| `package.json` 存在 | `primary_language = jsts`，`detection_method = manifest` |
+| `pyproject.toml` 存在 | `primary_language = python`，`detection_method = manifest` |
+| `setup.py` 存在 | `primary_language = python`，`detection_method = manifest` |
+
+若 manifest 命中，直接输出结果，跳过阶段二。
+
+## 阶段二：文件计数检测
+
+无 manifest 时，调用 `references/detect-language.js` 的 `detectLanguage(rootDir)` 函数扫描源码文件：
+
+1. 递归扫描 `root_dir`（最大深度 10 层）
+2. 排除目录：`node_modules/`、`dist/`、`build/`、`.git/`、`__pycache__/`、`.venv/`、`venv/`、`.webwork/`、`reports/`、`coverage/`
+3. 按扩展名分类计数：
+   - jsts：`.js`、`.jsx`、`.ts`、`.tsx`、`.vue`、`.mjs`、`.cjs`
+   - python：`.py`
+4. 文件数多者为主语言；两者都为 0 → 报错
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| manifest 命中 | 输出主语言，流程结束 |
+| 无 manifest，源码文件 > 0 | 输出计数多者为主语言 |
+| 无 manifest，源码文件 = 0 | 报错退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| root_dir 不存在 | 报错"工程根目录不存在" |
+| 无 manifest 且无源码文件 | 报错"无法检测项目主语言" |
+| 扫描权限不足 | 跳过不可读目录，继续扫描 |
+
+## 一定要做
+
+1. 优先检查 manifest 文件，避免全量扫描
+2. JS/TS 统一视为 `jsts` 一种语言
+3. 排除常见的非源码目录
+4. 无 manifest 时必须扫描文件计数
+
+## 一定不要做
+
+1. 不要返回多个语言（v1 只返回主语言）
+2. 不要扫描 `node_modules/` 等依赖目录
+3. 不要修改任何文件
+4. 不要执行网络请求

package/skills/lint-language-detect/references/detect-language.js

@@ -0,0 +1,65 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+const JSTS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.vue', '.mjs', '.cjs']);
+const PY_EXTENSIONS = new Set(['.py']);
+const MAX_SCAN_DEPTH = 10;
+const EXCLUDE_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', '__pycache__',
+  '.venv', 'venv', '.webwork', 'reports', 'coverage',
+  '.next', '.nuxt', '.output', 'eggs', '.eggs',
+]);
+
+export function detectLanguage(rootDir) {
+  if (existsSync(join(rootDir, 'package.json'))) {
+    return 'jsts';
+  }
+  if (existsSync(join(rootDir, 'pyproject.toml')) || existsSync(join(rootDir, 'setup.py'))) {
+    return 'python';
+  }
+
+  const counts = { jsts: 0, python: 0 };
+  _countFiles(rootDir, counts, 0);
+
+  if (counts.jsts === 0 && counts.python === 0) {
+    throw new Error(
+      'No lintable source files found: no package.json, pyproject.toml, or .js/.ts/.py files detected'
+    );
+  }
+
+  return counts.jsts >= counts.python ? 'jsts' : 'python';
+}
+
+function _countFiles(dir, counts, depth) {
+  if (depth > MAX_SCAN_DEPTH) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      if (!EXCLUDE_DIRS.has(entry)) {
+        _countFiles(fullPath, counts, depth + 1);
+      }
+    } else {
+      const ext = extname(entry).toLowerCase();
+      if (JSTS_EXTENSIONS.has(ext)) {
+        counts.jsts++;
+      } else if (PY_EXTENSIONS.has(ext)) {
+        counts.python++;
+      }
+    }
+  }
+}

package/skills/lint-rules-analyze/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: lint-rules-analyze
+description: |
+  执行 linter 检查并解析 JSON 输出，产出违规清单。按主语言调用对应 linter（eslint/ruff），
+  解析输出为统一的 violations 结构。二元制评分：0 违规=100，1+违规=0。
+  适用：lint agent 的规则分析阶段，用于基线检查和轮尾独立验证。
+  不适用：修复违规（使用 lint-tool-fix / lint-ai-fix）、非 lint 场景的代码分析。
+---
+
+# Lint 规则分析
+
+## 工作流模式
+
+顺序执行，4 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target_dir | 是 | string | 检查目标目录路径 |
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+| config_file_path | 是 | string | lint 配置文件路径 |
+
+## 输出
+
+- `violation_count`：违规总数
+- `violations`：违规列表，每条含 `{ file, line, column, rule, severity, message, fixable }`
+- `score`：评分（100 或 0）
+
+## 阶段一：执行 linter
+
+按主语言执行 linter，输出 JSON 格式：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --format json` |
+| python | `cd {root_dir} && ruff check {target_dir} --output-format json` |
+
+## 阶段二：解析 JSON 输出
+
+### ESLint JSON 解析
+
+ESLint 输出 JSON 数组，每元素含 `filePath` 和 `messages[]`：
+
+```
+对每条 message 提取：
+- file: filePath（转为相对 root_dir 的相对路径）
+- line: message.line
+- column: message.column
+- rule: message.ruleId
+- severity: message.severity === 2 ? 'error' : 'warning'
+- message: message.message
+- fixable: message.fix != null
+```
+
+### Ruff JSON 解析
+
+Ruff 输出 JSON 数组，每元素含 `code`、`filename`、`location`：
+
+```
+对每条 violation 提取：
+- file: filename（转为相对 root_dir 的相对路径）
+- line: location[0]
+- column: location[1]
+- rule: code
+- severity: code.startsWith('F') || code.startsWith('E') ? 'error' : 'warning'
+- message: message
+- fixable: fix != null
+```
+
+## 阶段三：评分计算
+
+| 条件 | score |
+|------|-------|
+| violation_count = 0 | 100 |
+| violation_count > 0 | 0 |
+
+## 阶段四：输出报告
+
+输出违规清单和评分。
+
+```
+## Lint 检查结果
+
+- 违规总数: X
+- 评分: 100|0
+- error 数: X
+- warning 数: X
+- 可修复数: X
+
+### 违规明细
+| # | 文件 | 行号 | 规则 | 严重级别 | 描述 | 可修复 |
+|---|------|------|------|---------|------|--------|
+| 1 | src/foo.js | 10 | no-unused-vars | error | 'x' is defined but never used | ✗ |
+```
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| violation_count = 0 | score=100，agent 判断达标 |
+| violation_count > 0 | score=0，agent 判断需修复 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| linter 未安装 | 报错"linter 不可用，请先运行环境检查" |
+| linter exit code 1（有违规） | 正常行为，解析 JSON 输出违规清单 |
+| linter exit code 2（配置错误） | 报错"linter 配置错误" |
+| linter 执行超时 | 报错"检查超时" |
+| JSON 解析失败 | 报错"linter 输出解析失败" |
+| target_dir 不存在 | 报错"检查目录不存在" |
+| 无违规（exit code 0） | 输出 violation_count=0, score=100 |
+
+## 一定要做
+
+1. 使用 JSON 格式输出，便于解析
+2. 将文件路径转为相对 root_dir 的相对路径
+3. 统一 violations 数据结构（file/line/column/rule/severity/message/fixable）
+4. 二元制评分：0 违规=100，1+违规=0
+
+## 一定不要做
+
+1. 不要修复任何违规（只检查）
+2. 不要修改源码文件
+3. 不要省略 warning 级别的违规
+4. 不要执行网络请求

package/skills/lint-suitability-check/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: lint-suitability-check
+description: |
+  扫描目标目录，筛选出可 lint 的源码文件列表。按主语言扩展名过滤，排除依赖/构建/缓存目录。
+  适用：lint agent 的适用性检查阶段，在环境检查前确定可检查的文件范围。
+  不适用：非 lint 场景的文件筛选、语言检测（使用 lint-language-detect）。
+---
+
+# 可 Lint 文件筛选
+
+## 工作流模式
+
+顺序执行，3 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| root_dir | 是 | string | 工程根目录路径 |
+| target_dir | 是 | string | 检查目标目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+
+## 输出
+
+- `lintable_files`：可 lint 文件路径列表（相对 root_dir 的相对路径）
+- `file_count`：文件数量
+- `excluded_count`：被排除的文件数量
+
+## 阶段一：确定扩展名过滤集
+
+| 主语言 | 匹配扩展名 |
+|--------|-----------|
+| jsts | `.js`、`.jsx`、`.ts`、`.tsx`、`.vue`、`.mjs`、`.cjs` |
+| python | `.py` |
+
+## 阶段二：递归扫描
+
+递归扫描 `target_dir`，排除以下目录：
+
+| 排除目录 | 原因 |
+|---------|------|
+| `node_modules/` | 依赖目录 |
+| `dist/`、`build/`、`.output/` | 构建产物 |
+| `.git/` | 版本控制 |
+| `__pycache__/`、`.eggs/` | Python 缓存 |
+| `.venv/`、`venv/` | 虚拟环境 |
+| `.webwork/` | 工具输出目录 |
+| `reports/`、`coverage/` | 报告目录 |
+| `.next/`、`.nuxt/` | 框架缓存 |
+
+最大扫描深度 10 层。
+
+## 阶段三：输出文件清单
+
+将匹配的文件路径转为相对 `root_dir` 的相对路径，输出列表。
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| file_count > 0 | 输出文件清单，agent 继续 |
+| file_count = 0 | 输出空列表，agent 退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| target_dir 不存在 | 报错"检查目录不存在" |
+| target_dir 是文件 | 对该单文件检查 |
+| 扫描权限不足 | 跳过不可读目录 |
+
+## 一定要做
+
+1. 按主语言扩展名精确过滤
+2. 排除所有依赖/构建/缓存目录
+3. 输出相对路径而非绝对路径
+4. 统计 file_count 供 agent 判断
+
+## 一定不要做
+
+1. 不要扫描 node_modules 等排除目录
+2. 不要返回非目标语言的文件
+3. 不要修改任何文件
+4. 不要执行网络请求

package/skills/lint-tool-fix/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lint-tool-fix
+description: |
+  执行 linter 的 --fix 自动修复，然后内部复跑 linter 获取剩余违规清单。
+  只处理 linter 可自动修复的规则，不可修复的规则交由 lint-ai-fix 处理。
+  适用：lint agent 的工具修复阶段，在 AI 修复前先自动修复可修复项。
+  不适用：AI 语义修复（使用 lint-ai-fix）、规则检查（使用 lint-rules-analyze）。
+---
+
+# Lint 工具自动修复
+
+## 工作流模式
+
+顺序执行，3 个阶段。
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target_dir | 是 | string | 检查目标目录路径 |
+| root_dir | 是 | string | 工程根目录路径 |
+| primary_language | 是 | string | 主语言（`jsts` 或 `python`） |
+| config_file_path | 是 | string | lint 配置文件路径 |
+
+## 输出
+
+- `tool_fixed_count`：自动修复的违规数
+- `remaining_violations`：修复后剩余的违规列表（结构同 lint-rules-analyze 的 violations）
+
+## 阶段一：执行 --fix
+
+按主语言执行 linter 的自动修复命令：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --fix` |
+| python | `cd {root_dir} && ruff check {target_dir} --fix` |
+
+`--fix` 会自动修复所有可自动修复的违规。不可自动修复的规则不受影响。
+
+## 阶段二：复跑 linter 获取剩余违规
+
+修复后重新执行 linter 检查（同 lint-rules-analyze 的命令），获取剩余违规：
+
+| 主语言 | 命令 |
+|--------|------|
+| jsts | `cd {root_dir} && npx eslint {target_dir} --format json` |
+| python | `cd {root_dir} && ruff check {target_dir} --output-format json` |
+
+解析 JSON 输出为 `remaining_violations`（结构与 lint-rules-analyze 一致）。
+
+## 阶段三：输出
+
+```
+## 工具修复结果
+
+- 自动修复数: X
+- 剩余违规数: X
+- 剩余可修复数: X（理论上应为 0，--fix 已尽力修复）
+- 剩余不可修复数: X（需 AI 修复）
+
+### 剩余违规明细
+| # | 文件 | 行号 | 规则 | 严重级别 | 描述 | 可修复 |
+|---|------|------|------|---------|------|--------|
+| 1 | src/foo.js | 10 | no-unused-vars | error | ... | ✗ |
+```
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| remaining_violations 为空 | agent 回到轮尾评分（final_count 应为 0 → 达标） |
+| remaining_violations 非空 | agent 进入 AI 修复（Step 8） |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| --fix 执行失败 | 报错，agent 跳过工具修复直接进入 AI 修复 |
+| 复跑 linter 失败 | 报错，remaining_violations 设为空列表，agent 将在轮尾独立验证中获取真实违规数 |
+| linter 未安装 | 报错退出 |
+
+## 一定要做
+
+1. --fix 后必须复跑 linter 获取剩余违规
+2. 输出 remaining_violations 的数据结构与 lint-rules-analyze 一致
+3. 统计 tool_fixed_count（修复前违规数 - 修复后违规数）
+
+## 一定不要做
+
+1. 不要执行 AI 语义修复（那是 lint-ai-fix 的职责）
+2. 不要修改 linter 配置文件
+3. 不要跳过复跑 linter 步骤
+4. 不要执行网络请求