Isoso CLI：为 React 与 TypeScript 开发者提供 WCAG/A11y 无障碍合规检查

面向发布 React & TypeScript 的开发者进行无障碍测试

终端中的静态 WCAG 导向规则 · 自动修复 codemod · 可选 AI 审查 · 适配 CI 的 JSON 报告

在进入生产环境之前，捕获 alt 文本缺失、键盘陷阱和未标记的控件。

目录

• Isoso 的功能
• 安装
• 快速开始
• Commands
  • isoso scan
  • isoso fix
  • isoso rules
  • isoso explain
• 内置规则
• 静态扫描 vs AI 扫描
• CI 集成
• 安全与合规
• Monorepo 布局
• 开发 Isoso
• Isoso Cloud
• 许可证

Isoso 的功能

Isoso 读取你的 .tsx / .jsx 源代码（而非实时 DOM），并标记出通常会违反 WCAG 预期的模式——缺少 alt 文本、没有角色的可点击 <div>、未标记的输入框等等。

flowchart LR
  subgraph input [Your repo]
    JSX[.tsx / .jsx files]
  end
  subgraph isoso [Isoso CLI]
    Parse[Babel JSX extract]
    Static[57 static rules]
    AI[Optional AI pass]
    Report[Text or JSON report]
  end
  subgraph output [Outcomes]
    Term[Terminal]
    CI[Exit code for CI]
    Artifact[JSON artifact]
  end
  JSX --> Parse
  Parse --> Static
  Parse --> AI
  Static --> Report
  AI --> Report
  Report --> Term
  Report --> CI
  Report --> Artifact

加载中

注意：Isoso 是源代码级分析。它补充——而非替代——浏览器工具（axe、Lighthouse）、屏幕阅读器测试和手动 QA。

Isoso Cloud（仪表盘、组织分析、GitHub 连接的扫描、策略）是独立产品。本仓库是开源 CLI 和规则引擎（第一阶段）。

安装

npm 包：@isoso.dev/isoso（带作用域）。npm 上没有不带作用域的 isoso 包——该名称已被保留/屏蔽。CLI 命令仍然是 isoso。

要求：Node.js 18+

运行一次（不修改 package.json）

将带作用域的名称与 npx 一起使用：

npx @isoso.dev/isoso scan
npx @isoso.dev/isoso rules
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 12

在关注可复现性时固定版本：

npx @isoso.dev/isoso@0.3.3 scan

添加到你要扫描的仓库（典型做法）

将其安装为你要扫描的应用中的开发依赖，而非无关项目：

npm install -D @isoso.dev/isoso

然后从该项目运行 isoso 二进制文件（本地安装或 npm 脚本）：

npx isoso scan
isoso rules

npx isoso … 在安装后使用 node_modules/.bin/isoso。npm @isoso.dev/isoso 无效——npm 期望的是像 install 这样的子命令，而不是包名。

全局安装（可选）

npm install -g @isoso.dev/isoso@latest
isoso scan
isoso --version

全局 isoso 在发布新版本时不会自动更新。在 npm 上升级后，再次运行 npm install -g @isoso.dev/isoso@latest（或继续使用 npx @isoso.dev/isoso@latest …）。

快速开始

# Scan the current directory (AI if ISOSO_AI_KEY is in .env, else static rules)
npx @isoso.dev/isoso scan

# Or, after npm install -D @isoso.dev/isoso in this repo:
npx isoso scan

# Scan a sample app in this monorepo (after clone + build)
npx isoso scan examples/sample-app

# Static only—no API calls
npx @isoso.dev/isoso scan --static

# JSON for pipelines + fail the job on serious+ findings
npx @isoso.dev/isoso scan --format json -o isoso-report.json --fail-on serious

# See every rule id and WCAG mapping (57 rules; fixable rules tagged in output)
npx @isoso.dev/isoso rules

# Auto-fix static findings (preview first, then apply)
npx @isoso.dev/isoso fix --dry-run
npx @isoso.dev/isoso fix

# Explain one rule (AI when a key is set)
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 12

建议的 package.json 脚本：

{
  "scripts": {
    "a11y": "isoso scan --static --fail-on serious",
    "a11y:report": "isoso scan --format json -o isoso-report.json",
    "a11y:fix": "isoso fix --dry-run"
  }
}

命令

isoso scan

扫描项目树中 JSX/TSX 的无障碍问题。

isoso scan [path] [options]

扫描范围

• Glob：**/*.{tsx,jsx}
• 忽略： node_modules、dist、build、.next、coverage

示例文本输出（节选）

Isoso accessibility scan
Engine: static rules
Root: /app
Files scanned: 42
Findings: 3

  critical: 1
  serious: 2

[critical] img-missing-alt — src/Hero.tsx:18:7
  <img> is missing an alt attribute.
  Fix: Add alt="..." describing the image, or alt="" if decorative.

Completed in 124ms

isoso fix

对静态规则引擎发现的问题应用自动 codemod。每个可修复的规则 id 在 isoso rules 中标记为 [fixable]。修复运行在与 scan 相同的 .tsx / .jsx 文件上（AI 发现的问题不会自动修复）。

isoso fix [path] [options]

典型工作流

isoso scan --static
isoso fix --dry-run    # review proposed edits
isoso fix              # apply to disk

合并前在 git 中审查差异——codemod 能处理常见模式，但无法替代对每个组件的判断。

isoso rules

打印所有静态规则，包含 id、人类可读名称、严重级别以及 WCAG 成功标准引用。

isoso rules

将这些 id 与 --rules 或 isoso explain --rule <id> 一起使用。

isoso explain

将发现的问题展开为 摘要、影响和修复建议。

isoso explain --rule <id> [options]

环境：ISOSO_AI_KEY 位于 .env（见下文）。可选 ISOSO_AI_MODEL、ISOSO_AI_BASE_URL 或 ISOSO_AI_CHAT_URL 用于你的提供商。

@isoso/core 自带 57 项静态检查（图片、表单、键盘、地标、媒体、表格、焦点、文档结构、自动完成、字幕和视口）。严重级别驱动 --fail-on 和 CI 门禁。

列出每个规则 id、WCAG 引用和严重级别：

npx @isoso.dev/isoso rules

类别包括：文本替代（img-missing-alt、svg-missing-accessible-name、role-img-missing-label……）、键盘与焦点（click-without-keyboard-handler、tabindex-zero-without-role、outline-none-utility……）、表单（input-missing-label、label-without-htmlfor、fieldset-needs-legend……）、链接与按钮、地标（nav-missing-label、multiple-main-landmarks……）、媒体和文档（html-missing-lang、multiple-h1）。

运行子集：

npx @isoso.dev/isoso scan --static --rules img-missing-alt,button-missing-name

静态扫描与 AI 扫描

自动行为

1. 如果设置了 ISOSO_AI_KEY → AI 扫描（除非 --static）。
2. 如果没有密钥 → 静态规则（CLI 会打印黄色提示）。
3. --ai → 如果没有密钥则快速失败。

设置

1. 在此仓库或运行 isoso 的应用中，将 .env.example 复制为 .env。
2. 设置 ISOSO_AI_KEY=...（你的提供商的 API 密钥）
3. 运行 npx @isoso.dev/isoso scan（省略 --static），或在本地安装后运行 isoso scan。

CLI 会从当前工作目录向上查找 .env。

cp .env.example .env
# edit .env, then:
npx @isoso.dev/isoso explain --rule img-missing-alt --file src/App.tsx --line 24

当你希望零网络调用时，在 explain 上使用 --builtin。

自定义 AI 提供商（chat completions JSON API）：

CI 集成

在任何 CI 流水线（GitHub Actions、GitLab CI 等）中运行 isoso scan。当发现的问题达到或超过 --fail-on 时，退出码为 1。

# Example GitHub Actions step
- run: npx @isoso.dev/isoso scan --static --format json --fail-on serious -o isoso-report.json

严重级别门禁：--fail-on serious 会在严重和高危发现上失败。使用 --fail-on critical 获得更宽松的门禁，或使用 --fail-on moderate 获得更严格的门禁。

提示

• 在 CI 中优先使用 --static，以获得速度和可预测的成本。
• 仅当你有意在流水线中运行 AI 时，才将 ISOSO_AI_KEY 存储在 CI 密钥中。
• GitHub 组织集成（连接仓库、PR 扫描、仪表盘历史记录）仅属于 Isoso Cloud——不属于此 CLI。

安全与合规

在发布门禁、发布合规声明或将扫描输出视为无障碍性证明之前，请先阅读本文。

不提供 WCAG 或法律合规保证

Isoso 不认证、审计或保证你的应用程序符合 WCAG 2.x（任何级别）、ADA、Section 508、EN 301 549、EAA 或任何其他无障碍标准或法律。

isoso rules 中的规则 id 和 WCAG 引用描述的是某个模式为何有风险，而非判定你的产品合规或违法。你仍需对产品的无障碍性和法律义务负责。

仅限源码级分析

CLI 分析的是 .tsx / .jsx 源文件——而非实时 DOM、运行时 CSS、来自 CMS/API 的内容、PDF、原生应用或第三方嵌入内容。发现结果可能是误报（安全模式被标记）或漏报（仅在运行时或生产构建中才可见的问题）。

当合规性至关重要时，请将 Isoso 与浏览器工具（例如 axe DevTools、Lighthouse）、手动测试、辅助技术检查以及专业审计结合使用。

自动修复（isoso fix）风险

Codemod 会应用机械式编辑。它们可能改变行为、破坏测试或忽略上下文（装饰性图片与信息性图片、自定义组件、设计系统包装器）。合并前务必审查 git diff；未经审查，不要在生产线分支上无人值守地运行 fix。

AI 扫描与解释

当设置 ISOSO_AI_KEY 时，文件片段和规则上下文可能会发送到你配置的 AI 提供商。你需要对提供商条款、数据处理负责，并绝不将 API 密钥提交到 git。

• 当你希望零外部数据传输时，在 CI 中优先使用 --static。
• 在 explain 上使用 --builtin，仅用于离线、精选副本。
• AI 输出可能因模型而异，且并非确定性的法律或合规建议。

密钥与环境

CLI 通过从当前工作目录向上查找来加载 .env——除你的 shell 和提供商所做的之外，它不会加密或存储密钥。

严重性门禁是策略，不是法律

--fail-on 控制你的流水线的退出码（例如在 serious 及以上时失败）。那是你的质量标准，而非对 WCAG 符合性级别或法律安全港的映射。

Isoso Cloud

isoso.dev 上的仪表板扫描、策略和 GitHub 连接的运行受单独的条款和隐私政策约束。云端存储发现结果并不意味着你的应用程序合规。

报告安全问题

如果您认为在 Isoso CLI 中发现了安全漏洞（而非您应用中的无障碍问题），请通过 info@isoso.dev 负责任地报告（主题：security）。在协调之前，请勿公开带有漏洞利用细节的 issue。

Monorepo 布局

已发布的 @isoso.dev/isoso 捆绑包内置了 @isoso/core 和 @isoso/scanner，实现单次安装。

开发 Isoso

从 monorepo 根目录：

npm install
npm run build
npm test                    # @isoso/core unit tests
npx isoso scan examples/sample-app

示例违规：examples/sample-app/BadExample.tsx 故意违反若干规则——用它来在本地验证扫描。

Isoso Cloud

需要组织级仪表盘、GitHub 连接的仓库扫描、团队、策略和计费？这些功能位于 Isoso Web / Cloud，而非此 CLI 仓库。CLI 仍然是开源本地和 CI 方案；在适用静态启发式规则的地方，云端扫描与 CLI 对齐相同的规则 ID。

许可证

MIT — 参见 LICENSE。

更早交付无障碍 UI。在您的应用上运行 npx @isoso.dev/isoso scan，然后运行 npx @isoso.dev/isoso fix 进行安全的自动编辑。