Compare Html

compare-html

一个用于结构化 HTML 比较的工具包，可查找两个 HTML 文档之间的变化，并可控制元素、属性和子节点的匹配方式。

为什么选择它

大多数 HTML 差异工具要么输出非结构化文本，要么隐藏重要信息（例如元素在哪里被添加、数组差异在于顺序还是内容）。compare-html 会将 HTML 解析为结构化表示，并返回差异列表——每个条目都包含路径、所属方（base / contrast / both）和变化类型（added、deleted、valueChanged）——因此你可以据此进行渲染、筛选或编程处理。

功能

• 对 HTML 元素、属性、数组和文本值进行深度比较。
• 三种子节点比较策略：byIndex（默认）、lcs（通过最长公共子序列实现最小差异）和 unordered（多重集匹配）。
• 对标签/属性名称和/或文本/属性值进行不区分大小写的匹配。
• 路径跟踪，同时支持片段数组和点号表示形式。
• CLI 支持表格或 JSON 输出，可读取内联字符串或文件。
• 内置 MCP 服务——可将 CLI 接入任何支持 MCP 的 AI 助手。
• Agent Skill——一个技能即可用于 Claude Code、OpenAI Codex CLI 和 OpenCode。
• 完整的 TypeScript 类型。

软件包

这是一个 pnpm 工作区：

软件包	描述
@compare-html/core	核心比较库（编程 API）。
@compare-html/cli	命令行工具和 MCP 服务，基于 core 构建。

快速入门

库

npm install @compare-html/core

import { compareHTML } from '@compare-html/core';

const differences = compareHTML({
  baseHTML: '<user><name>Alice</name><age>30</age></user>',
  contrastHTML: '<user><name>Bob</name><age>30</age><email>[email protected]</email></user>',
});

// [
//   { pathString: 'user.name',  pathBelongsTo: 'both',     diffType: 'valueChanged', ... },
//   { pathString: 'user.email', pathBelongsTo: 'contrast', diffType: 'added',        ... },
// ]

完整 API 请参阅 core README。

CLI

npm install -g @compare-html/cli

compare-html base.html contrast.html

┌──────────────┬──────────────┐
│ Key          │ Change Type  │
├──────────────┼──────────────┤
│ (Base) a     │ valueChanged │
│ (Base) b     │ deleted      │
│ (Contrast) c │ added        │
└──────────────┴──────────────┘

使用 --json-export 输出机器可读的结果，或使用 --mcp 启动 MCP 服务。所有标志和 MCP 工具架构请参阅 CLI README。

MCP

{
  "mcpServers": {
    "compare-html": {
      "command": "npx",
      "args": ["@compare-html/cli@latest", "--mcp"]
    }
  }
}

技能

单个 SKILL.md 文件即可教会 AI 编码助手如何按需调用 CLI。该文件遵循开放的 Agent Skills 格式，可用于 Claude Code、OpenAI Codex CLI、OpenCode、Cursor 及其他 50 多种工具。

最快的安装方式是使用 npx skills——它会自动检测你安装的所有 Agent，并将技能安装到每个 Agent 中：

npx skills add unitstack/compare-html

开发

需要 Node.js ≥ 20 和 pnpm。

# install dependencies
pnpm install

# build all packages
pnpm -r build

# run tests across the workspace
pnpm -r test

# lint
pnpm -r lint

仓库结构：

packages/
├── compare-html-core/     # @compare-html/core — library
├── compare-html-cli/      # @compare-html/cli  — CLI + MCP server
└── internal/             # shared eslint/tsconfig (not published)
skills/
└── compare-html/          # SKILL.md for Claude Code / Codex CLI / OpenCode

许可证

MIT