v1.9.5: 工具体系重构 + Bug 修复 + 全面测试验证

🎉 v1.9.5 发布

主要变更

工具体系重构（137 → 154 工具，含 59 个别名转发）

通过 mode 参数统一 + TOOL_ALIASES 别名转发机制，将功能相近的工具合并为主工具 + 子模式，大幅降低 IDE 工具列表的视觉噪音和 AI 模型的工具选择复杂度。完全向后兼容，所有旧工具名通过别名继续可用。

Bug 修复（2 个 CRITICAL）

• Bug #116: handlers/system.js 未导入 mcpParamMissing，导致 browser_form_fill 完全无法执行
• Bug #117: hands/deep_interactor.js inferFieldType 函数对 null 值处理不当，导致多个字段填充失败

v1.9.4 修复验证

v1.9.4 修复的 4 个 CRITICAL 工具在 v1.9.5 中全部确认正常：

• browser_lighthouse_audit ✅
• browser_flow ✅
• trace_correlate ✅
• css_var_check ✅

全面测试结果

基础测试

• 154 个注册工具全面测试
• 通过率 99.4%（153/154）
• 无 BLOCKING 级问题
• 测试覆盖：ant.design、cn.bing.com、tailwindcss.com、stackoverflow.com、demoqa.com 等

深度测试

• 7 个深度场景全部通过（通过率 100%）
  • 端到端搜索业务流程（GitHub）
  • 表单完整业务流程（DemoQA）
  • 跨页面导航 + 视觉对比（Ant Design）
  • 性能 + 安全 + 错误综合审计
  • 边界条件测试（5 项全部正确处理）
  • 复杂真实网站测试（知乎、Bilibili、MDN）
  • 跨工具协同链式调用（browser_flow + chain_spec）
• 测试覆盖 8 个真实复杂互联网网站

别名转发验证

• 56 个别名转发规则全部通过（19 个 Phase，向后兼容 100%）

安装

npm install @validpilot/ai-verify-mcp@1.9.5

升级指南

v1.9.5 完全向后兼容，无需修改任何现有调用。新版本提供了 mode 参数统一的主工具，建议逐步迁移到主工具调用方式。

详细变更请查看 CHANGELOG.md。

Release v1.9.3 — Skill-MCP 协调配合能力 + 文档同步

🎯 本次发布核心

让 Skill 编排能力通过 MCP Prompts 原语内置到 MCP 服务器——用户无需安装任何 IDE 扩展包，在 Claude Desktop / Cursor / Trae 中输入 / 即可看到 7 个斜杠命令工作流，开箱即用。

✨ 新增功能

1. /submit-form MCP Prompt

补齐 form-submission Skill 的 Prompt 缺口，7/8 Skill 覆盖。7 步工具链：browser_open → browser_snapshot → browser_form_validate → browser_form_fill → browser_click → browser_assert → evidence_pack。

2. handlers/skill_map.js 模块

SKILL_TOOLS_MAP 单一数据源（显式常量，不解析 markdown），6 个纯内存计算函数：getSkillTools / getToolSkills / getAllSkillToolsMap / getReverseMap / extractToolsFromPromptMessages / validateConsistency。

3. skill_tools_map 工具

双向查询 Skill↔Tool 映射。支持 skillName（正向：返回工具链）或 toolName（反向：返回 Skill 列表）任选其一，anyOf JSON Schema 模式。

4. skill_consistency_check 工具

批量校验所有 Skill 引用工具与实际注册一致，不依赖外部文件。支持 strict（默认，缺失工具则失败）和 warn（仅警告）两种模式，含 mapDrift 字段检测 Prompt 与 SKILL_TOOLS_MAP 的漂移。

5. mcp_self_test 扩展

追加 skillConsistencyV2 字段（基于 handlers/skill_map.js，不依赖 PROJECT_ROOT 外部文件）。保留旧 skillConsistency 字段向后兼容。

📚 新增文档

• docs/reference/skill-tools-map.md — 人工可读映射表（7 Skill 正向映射 + 30 工具反向映射 + 一致性校验说明 + AI 工作流场景）
• docs/guide/skill-usage.md — 完整 Skill 使用指南（8 章：什么是 Skill → 三种形态 → 7 个工作流 → 3 种使用方式 → 客户端兼容性 → IDE 扩展包可选增强 → 4 个 FAQ → 相关文档）

🔄 文档同步

10 个文件的工具数从 134 同步到 136：README.md / README.en.md / AGENTS.md / standalone-start.js / docs/tools/overview.md / docs/skills/index.md / docs/skills/form-submission.md / docs/reference/tool-decision-matrix.md / docs/.vitepress/config.mts / CHANGELOG.md

README.md / README.en.md 重写"Skill + MCP"段落，去掉过时的"两者缺一不可"表述，明确"Skill 编排能力已通过 MCP Prompts 内置，IDE 扩展包仅为可选增强"。

🧪 测试验证

• 单元测试：144/144 通过（prompts 13 + skill_map 29 + system_extra + handlers_network_system 14 + tools + atl）
• 真实 MCP 工具调用：3 项 run_mcp 验证通过（skill_tools_map 正反查 + skill_consistency_check passed:true 7/7）
• 文档构建：VitePress 站点构建成功（11.05s）
• 包验证：npm pack dry-run 253 文件 794.8 kB，含全部新工具和文档

📦 升级方式

# MCP 配置中使用 npx（推荐）
npx -y @validpilot/ai-verify-mcp@1.9.3

# 或全局安装
npm install -g @validpilot/ai-verify-mcp@1.9.3

# 或项目内升级
npm install @validpilot/ai-verify-mcp@1.9.3

🔗 工具数变化

类别	v1.9.2	v1.9.3
Exploration & System	7	9 (+2)
总工具数	134	136

新增 2 个工具：

• skill_tools_map — Skill↔Tool 双向映射查询
• skill_consistency_check — Skill 工具引用一致性校验

📝 Commit

• 8cf4fcf feat(v1.9.3): Skill-MCP 协调配合能力 + 文档同步（22 files, +1774/-35）

---

Full Changelog: v1.9.2...v1.9.3

v1.9.2 - Bug Fix Release

v1.9.2 - Bug Fix Release

Fixed

• 修复 5 处 logger.warn() latent bug：server.js 中 5 处 catch 块调用 logger.warn(msg, _.message)，但 Logger 类只有 log(level, message, details) 方法，没有 warn()。运行时一旦触发这些 catch 分支，会抛出 TypeError: logger.warn is not a function，导致错误处理本身失败。

  修复位置：

  • L600 buildInteractionReport: evaluate 失败
  • L931 consoleListener: 处理 console 事件失败
  • L933 setupConsoleListeners: 整体捕获异常
  • L1005 collectConsoleErrors: 收集错误失败
  • L1202 injectedConsoleErrors: 处理注入脚本错误失败

  修复方式：logger.warn(msg, data) → logger.log('WARN', msg, data)

Validation

• 1180 个单元测试全部通过（0 失败）
• c8 覆盖率：Lines 33.09%、Branches 78.54%、Functions 52.68%
• 真实项目端到端验证（192.168.8.4:8081 ValidPilot 营销网站）：
  • browser_full_audit：0 错误，页面健康
  • browser_full_regression：18 功能、26 点击、32 通过、8 失败（业务层 409 Conflict）
  • validation.log 验证：v1.9.2 重启后 0 个 TypeError、0 个 logger.warn is not a function

Stats

• server.js：4149 行（行数不变），188KB
• 纯 bug 修复，无新增/删除代码，仅 5 处单行修改
• npm 包大小：694.5 kB（233 个文件）

Full Changelog: v1.9.1...v1.9.2

v1.9.1

server.js 瘦身 Phase 4 — 提取项目质量审计

新增 hands/project_auditor.js（262 行），将 projectAudit() 函数从 server.js 迁移（原 239 行，含 JSDoc）。

函数功能

实现项目目录扫描，检测 7 类代码质量问题：

• 硬编码密码/密钥
• 硬编码绝对路径 (Windows)
• TODO/FIXME/HACK 注释
• 调试代码（console.log/debugger）
• 大文件（>1000 行）
• 重复的 require 语句
• 可疑的 eval/exec 调用

特性

• 完全自包含：只依赖 fs/path（函数内部 require），无任何 server.js 模块级依赖
• 无需工厂注入：直接 module.exports = { projectAudit }，server.js 通过 const { projectAudit } = require('./hands/project_auditor') 引入

Stats

• server.js: 4384 → 4149 行（-235 行），194KB → 184KB（-10KB）
• 新增模块：hands/project_auditor.js（262 行）
• 累计五步瘦身（v1.8.7 ~ v1.9.1）：server.js 7141 → 4149 行（-2992 行），310KB → 184KB（-126KB）

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过（Lines 33.09%、Branches 78.54%、Functions 52.68%）
• 覆盖率与 v1.9.0 完全一致（纯文件位置重组，无逻辑变更）

Full Changelog: v1.9.0...v1.9.1

v1.9.0

Changed

• server.js 瘦身 Phase 3 — 提取部署验证 + 修复 logger.warn bug：新增 hands/deploy_verifier.js（521 行），将 runDeployVerify() 函数从 server.js 迁移（原 493 行）。
  • 函数实现部署后端到端验证，包含 6 项检查：
    • HTML 可达性检查
    • 静态资源完整性检查（CSS/JS/图片/字体）
    • API 端点可用性检查（含降级硬编码列表）
    • 控制台错误监控
    • CSS 变量定义完整性检查
    • 浏览器全量回归测试（调用 runBrowserFullRegression）
  • 内部 require 路径调整：./scripts/css-var-analyzer → ../scripts/css-var-analyzer（适应 hands/ 子目录）
• 函数签名变更：runDeployVerify(args) → runDeployVerify(args, ensurePage, logger, runBrowserFullRegression)，依赖通过参数注入
• 工厂注入模式：createDeployVerifier({ ensurePage, logger, runBrowserFullRegression })，与 v1.8.7/v1.8.8/v1.8.9 一致
• 依赖顺序：runDeployVerify 定义必须放在 runBrowserFullRegression 之后（TDZ 要求）

Fixed

• 修复 logger.warn() latent bug：runDeployVerify 内调用 logger.warn('pwPage.close 失败', _.message)，但 Logger 类（core/logger.js）只有 log(level, message, data) 方法，没有 warn()。修复为 logger.log('WARN', 'pwPage.close 失败', _.message)

Stats

• server.js: 4879 → 4384 行（-495 行），218KB → 194KB（-24KB）
• 新增模块：hands/deploy_verifier.js（521 行）
• 🎉 server.js ≤200KB 目标达成（August Plan W2 目标）
• 累计四步瘦身（v1.8.7 + v1.8.8 + v1.8.9 + v1.9.0）：server.js 7141 → 4384 行（-2757 行），310KB → 194KB（-116KB）

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过（Lines 33.09%、Branches 78.59%、Functions 52.68%）
• 覆盖率与 v1.8.9 一致，纯文件位置重组 + 1 处 bug 修复

Milestone

🎉 August Plan W2 目标全部达成：

• ✅ runBrowserFullRegression() 函数拆分（v1.8.9）
• ✅ findElement()/findPage() 提取独立模块（v1.8.7）
• ✅ traverseMenu() 提取独立模块（v1.8.8）
• ✅ runDeployVerify() 提取独立模块（v1.9.0，额外完成）
• ✅ server.js ≤200KB 目标达成（194KB）

版本号升至 1.9.0 标志 August Plan W2 里程碑完成。

npm: @validpilot/ai-verify-mcp@1.9.0 (shasum: 6af80ae3b5be5176cb32247c94c468780c5ad916)

v1.8.9

Changed

• server.js 瘦身 Phase 2 完成 — 提取浏览器全量回归测试：新增 hands/full_regression.js（1398 行），将 runBrowserFullRegression() 函数从 server.js 迁移。这是本次 Phase 2 瘦身中最大的一次提取（原 1362 行，占 server.js 的 21%）。
  • 函数实现浏览器全量回归测试，包含 8 个内部辅助函数：
    • isApiUrl(url)：过滤静态资源，只保留 API 请求
    • installListeners()：Playwright + CDP + JS 拦截器 + Performance API 多层监听（约 220 行）
    • snapshotLocalLogs() / deltaAndClear(sinceTime)：本地日志快照与增量
    • captureErrors(sinceTs)：合并多层数据源捕获错误
    • resetLogs()：清空 localLogs（permanentErrors 永不清除）
    • tryClick(selOrText, isSelector)：三级点击策略
    • resolveUrl(href) / isSameOriginNav(href)：URL 解析辅助
  • 测试阶段：BFS 遍历导航链接 → 首页非导航功能点击（含 SPA 检测）→ select 状态变更独立测试（含深度探索）→ Performance API + permanentErrors 最终扫描 → 假阳性过滤（429 限流、IP 中假 5xx、去重）
• 函数签名变更：runBrowserFullRegression(args) → runBrowserFullRegression(args, ensurePage, deepInteractor)，依赖通过参数注入
• 工厂注入模式：与 v1.8.7/v1.8.8 一致，createFullRegression({ ensurePage, deepInteractor }) 返回绑定依赖的函数

Stats

• server.js: 6235 → 4879 行（-1356 行），282KB → 218KB（-64KB）
• 新增模块：hands/full_regression.js（1398 行）
• 累计三步瘦身（v1.8.7 + v1.8.8 + v1.8.9）：server.js 7141 → 4879 行（-2262 行），310KB → 218KB（-92KB）

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过（Lines 33.09%、Branches 78.54%、Functions 52.68%）
• 覆盖率与 v1.8.8 基本一致（Lines -0.16%、Branches -0.46%、Functions -1.92%），纯文件位置重组，无逻辑变更

Milestone

August Plan W2 任务完成：

• ✅ runBrowserFullRegression() 函数拆分（拆为独立模块）
• ✅ findElement()/findPage() 提取独立模块（v1.8.7）
• ✅ traverseMenu() 提取独立模块（v1.8.8）
• ⚠️ server.js ≤200KB 目标：218KB（接近但未达，后续可通过提取 callTool 调度逻辑或 handlers 进一步瘦身）

npm: @validpilot/ai-verify-mcp@1.8.9 (shasum: e1cff0b678e318fce1b842f66c21f84a7f838d50)

v1.8.8

Changed

• server.js 瘦身 Phase 2 — 提取菜单遍历器：新增 hands/menu_traverser.js（352 行），将 traverseMenu() 函数从 server.js 迁移。该函数实现菜单遍历（最多 3 层深度、支持子菜单展开、SPA 按钮导航），包含 4 个内部辅助函数：
  • smartClick(text, href)：evaluate 内联点击 + selector 回退
  • discoverNavItems()：发现导航项（30+ 选择器，含 antd/element-ui/iview 等）
  • clickAndCheck(text, href, level)：点击 + 错误检查 + URL 变化检测
  • discoverChildren(parentText)：发现子菜单项
• 工厂注入模式：traverseMenu 依赖 ensurePage 和 postActionErrorCheck，通过 createMenuTraverser({ ensurePage, postActionErrorCheck }) 注入

Stats

• server.js: 6553 → 6235 行（-318 行），286KB → 282KB（-13KB）
• 新增模块：hands/menu_traverser.js（352 行）
• 累计两步瘦身（v1.8.7 + v1.8.8）：server.js 7141 → 6235 行（-906 行），310KB → 282KB（-44KB）

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过（Lines 33.25%、Branches 79.00%、Functions 54.60%）
• 覆盖率与 v1.8.7 一致（纯文件位置重组，无逻辑变更）

npm: @validpilot/ai-verify-mcp@1.8.8 (shasum: 70560af769cf28bab6c59574c128cd22ab4f78f9)

v1.8.7 — server.js 瘦身 Phase 2（提取智能页面发现模块）

v1.8.7 — server.js 瘦身 Phase 2（提取智能页面发现模块）

Changed

• server.js 瘦身 Phase 2 — 提取智能页面发现模块：覆盖 8 月计划 W2 任务 "findElement()/findPage() 提取独立模块"。新增 hands/locator_helpers.js（630 行），将以下内容从 server.js 迁移：
  • PAGE_PATTERNS 常量（12 种页面类型的 URL/选择器/文本/标题匹配模式：login/signup/home/dashboard/admin/settings/profile/search/cart/checkout/forgot-password/logout）
  • findPage() 函数（274 行）：智能页面发现，支持 URL/Hash/DOM 三层匹配 + SPA 按钮导航
  • findElement() 函数（241 行）：智能元素查找，7 种匹配策略（精确/包含/placeholder/aria-label/title-alt/role-fuzzy）
• 工厂注入模式：findPage 依赖 ensurePage，通过 createLocatorHelpers({ ensurePage }) 工厂函数注入，避免循环依赖。findElement 为纯函数无外部依赖，直接导出

Stats

• server.js: 7141 → 6553 行（-588 行），310KB → 286KB（-24KB）
• 新增模块：hands/locator_helpers.js（630 行）
• 无功能变更，无 API 变更，仅文件位置重组

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过，覆盖率小幅提升：Lines 33.11% → 33.25%、Branches 78.59% → 79.00%、Functions 52.68% → 54.60%
• 新模块被 handlers/locator.js 测试间接覆盖

Full Changelog: v1.8.6...v1.8.7

v1.8.6 — 空 catch 块规范化

v1.8.6 — 空 catch 块规范化

Fixed

• 空 catch 块规范化：覆盖 8 月计划任务"逐个审查 78 处空 catch，至少添加日志"。共审查并修复 91 个空 catch 块，分布于 5 个源文件：
  • server.js：77 处（45 处补描述性注释、32 处原 log('WARN', '操作失败') 替换为更精准的描述性注释；其中约 5 处位于浏览器注入代码内 target.evaluate() 上下文，Node.js log() 不可用，必须使用注释而非日志调用）
  • orchestrator/dual_chain_orchestrator.js：5 处（双击探测、敏感路径单点探测、API 详情解析、HAR 导出、error_summary_md 调用）
  • hands/deep_interactor.js：5 处（networkidle 等待、提交后 UI 状态、表单截图、流程步骤截图、提交后状态评估）
  • core/logger.js：3 处（日志轮转、stat 检查、appendFileSync 写入 —— 避免递归日志记录）
  • hands/memory_analyzer.js：1 处（getEventListeners Chrome DevTools 专有方法浏览器侧回退）

修复原则

每处 catch 补充 1 行中文注释，说明"为何可忽略 + 后果"，便于后续维护与审查。不引入新日志调用以避免：

1. 浏览器注入代码上下文（target.evaluate()）中 Node.js log() 不可用
2. core/logger.js 内部失败再写日志会递归

Coverage

• 1180 个单元测试全部通过（0 失败）
• c8 阈值全部通过（Lines 33.11%、Functions 52.68%、Branches 78.59%）
• 覆盖率与 v1.8.5 一致（catch 块注释改动不影响逻辑路径覆盖）

Full Changelog: v1.8.5...v1.8.6

v1.8.5

Fixed

• server.js 全局严格模式：在文件顶部添加 'use strict';，对齐项目代码风格规范（core/trace.js 等模块已遵循）。同时清除文件开头的 33 个冗余 UTF-8 BOM 字符
• 工具数文档一致性：standalone-start.js 启动提示从 128 更正为 134（与实际 tools/ 目录下的 134 个 JSON schema 文件及 README/AGENTS 文档对齐）

Coverage

• 1180 个单元测试全部通过，c8 阈值全部通过（Lines 33.11%、Functions 52.68%、Branches 78.59%）
• 'use strict' 未引入任何严格模式违规（全量测试 0 失败）

npm: @validpilot/ai-verify-mcp@1.8.5