kiyas

AI 驱动的设计保真度 — MCP 服务与 CLI
“comparison”——读作“key-AHS”

---

一款以开发者为先的 MCP 服务（也可作为 CLI 运行），用于比较 Figma 设计与渲染后的 UI 组件，并提供 AI 驱动的语义差异分析。可接入 Claude Code、Cursor、Codex CLI 及任何其他兼容 MCP 的客户端。

与像素差异工具不同，kiyas 使用视觉 AI 理解_差异是什么_以及_为何重要_，并输出可执行、易于理解的反馈，例如：

• “实现中的 border-radius 为 8px，而设计中为 12px”
• “标题与副标题之间的间距比设计紧凑 16px”

只需按名称描述组件。kiyas 会在代码库中找到它，为其截图，并与 Figma 设计进行比较。

更喜欢应用而不是终端？我们还提供桌面应用。

---

桌面应用

一款原生 macOS 应用，可通过点选操作运行相同的比较，专为设计师和不想使用终端的用户打造。选择项目，粘贴 Figma 链接（或拖入截图），描述组件，即可在应用中获取完整报告。它使用相同的引擎和基于订阅的身份验证：AI 调用通过你设备上的 Claude Code 或 Codex CLI 进行，绝不使用 API 密钥。

⬇ 下载最新版本（Apple Silicon）

1. 下载 .dmg，将 Kiyas 拖到“应用程序”中。
2. 预览版尚未经过公证——首次启动时，右键点击 →“打开”（或运行 xattr -dr com.apple.quarantine /Applications/Kiyas.app）。
3. 在任意终端中登录一次 Claude Code 或 Codex；应用会自动获取登录状态。

主要功能：带有开发服务器检测的项目侧边栏、比较前的捕获预览与裁剪、内置终端、完整深色模式，以及 macOS 26 上的 Liquid Glass 图标。

如需从源代码构建：

git clone https://github.com/saiffmirza/kiyas && cd kiyas
npm install
npm run desktop        # dev mode
# or package a .app/.dmg:
cd apps/desktop && npx electron-builder --mac

---

工作原理

                          ┌─────────────────────┐
                          │  kiyas               │
                          │  (MCP server / CLI)  │
                          │                      │
                          │  figma / design img  │
                          │  + target/component  │
                          └──────────┬───────────┘
                                     │
                      ┌──────────────┼──────────────┐
                      ▼              ▼               ▼
              ┌──────────────┐ ┌───────────┐ ┌─────────────┐
              │ 1. Auth      │ │ 2. Design │ │ 3. Resolve  │
              │              │ │  Capture  │ │  Component  │
              │ Verify       │ │           │ │             │
              │ Claude Code  │ │ Figma API │ │ AI agent    │
              │ or Codex CLI │ │ PNG export│ │ searches    │
              │ is installed │ │ — or your │ │ codebase,   │
              │ & signed in  │ │ own image │ │ finds URL + │
              │              │ │ (--design)│ │ CSS selector│
              └──────┬───────┘ └─────┬─────┘ └──────┬──────┘
                     │               │               │
                     │               ▼               ▼
                     │        ┌────────────┐  ┌────────────┐
                     │        │  Figma     │  │ Playwright │
                     │        │  design    │  │ screenshot │
                     │        │  (PNG)     │  │ (PNG)      │
                     │        └─────┬──────┘  └─────┬──────┘
                     │              │               │
                     │              └───────┬───────┘
                     │                      ▼
                     │          ┌──────────────────────┐
                     └─────────►│ 4. Vision AI Compare │
                                │                      │
                                │ Both images sent to  │
                                │ Claude Code CLI with │
                                │ a structured prompt   │
                                │                      │
                                │ Returns JSON array   │
                                │ of discrepancies     │
                                └──────────┬───────────┘
                                           │
                                           ▼
                                ┌──────────────────────┐
                                │ 5. HTML Report       │
                                │                      │
                                │ Side-by-side images  │
                                │ Severity badges      │
                                │ Interactive filters  │
                                │ HIGH / MEDIUM / LOW  │
                                │                      │
                                │ file:// link in      │
                                │ terminal output      │
                                └──────────────────────┘

分步说明：

1. 身份验证 — kiyas 将 AI 调用委托给 Claude Code 或 Codex CLI。现有订阅即可处理所有操作，无需 API 密钥。
2. 获取设计图像 — 解析 Figma URL，调用 Figma REST API 将画板导出为 PNG（缩放比例与截图相同——自适应，参见 --scale），并获取节点元数据（颜色、字体、间距）。也可以完全跳过 Figma：传入 --design <path-or-url> 和自己的设计图像，无需 Figma 令牌。
3. 解析组件 — AI Agent 扫描你的代码库（文件树、路由、组件），将自然语言描述映射到开发服务器上的 URL 和 CSS 选择器。
4. 为实现截图 — Playwright 启动无头 Chromium，导航到解析出的 URL，并捕获组件。
5. AI 比较 — 将两张 PNG 传给 Claude Code CLI，并附上结构化提示词。AI 会识别所有差异，并指出具体的 CSS 属性和值。
6. 生成报告 — 将结果整理为 HTML 报告，其中包含并排图像比较、严重程度徽标和交互式筛选器。终端中会打印文件链接，方便访问。

---

用作 MCP 服务

kiyas 通过 stdio 将其比较引擎作为 MCP 服务公开。提供三个工具，输入架构均由 Zod 类型定义：

工具	描述	必填输入
compare	执行一次全新的设计与实现比较；返回 reportId 和摘要	(figma 或 designImage) + (target 或 component)
get_diff_report	获取已存储报告的 HTML 或 JSON 内容	reportId
list_issues	列出已存储报告中的差异，可按严重程度筛选	reportId

报告会保存在项目目录下的 .kiyas/reports/<reportId>/ 中，因此同一个 reportId 在后续调用以及 CLI/MCP 使用中都会保持有效。

安装

npm install -g kiyas-cli
npx playwright install chromium

配置

Claude Code

claude mcp add kiyas -- npx -y kiyas-cli@latest mcp

# with a Figma token (only needed for Figma-URL comparisons):
claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx -y kiyas-cli@latest mcp

kiyas 也已收录在官方 MCP Registry 中，名称为 io.github.saiffmirza/kiyas，因此支持 Registry 的客户端可以直接从其 MCP 目录安装。

Cursor — 编辑 ~/.cursor/mcp.json：

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

Codex CLI — 编辑 ~/.codex/config.toml：

[mcp_servers.kiyas]
command = "npx"
args    = ["kiyas-cli@latest", "mcp"]

保持更新

上述配置使用 kiyas-cli@latest，因此 npx 会在每次启动时获取最新版本 — 代价是每次启动都要检查 Registry，且离线时可能无法启动。如果你更愿意固定版本（[email protected]）或使用全局安装，也完全没问题：kiyas 会在启动时检查一次 npm（非阻塞），并在有更新版本时向 stderr 输出通知。

MCP 用户的 Figma 访问权限

只有在传入 figma URL 时，compare 工具才需要 Figma 访问权限。可通过以下三种方式提供：

1. 通过服务配置传入令牌（推荐）：

claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=<your-token> -- npx -y kiyas-cli@latest mcp

或在 .mcp.json / mcp.json / config.toml 中添加 env 块：

{
  "mcpServers": {
    "kiyas": {
      "command": "npx",
      "args": ["kiyas-cli@latest", "mcp"],
      "env": { "FIGMA_ACCESS_TOKEN": "your-token" }
    }
  }
}

2. 在项目根目录或主目录中放置 .kiyasrc 文件：{ "figmaAccessToken": "..." }

3. 不提供令牌 — 与 Figma MCP 服务搭配使用。 如果 Agent 已连接 Figma 自己的 MCP 服务，它可以自行将画布导出为图像，并将文件路径（或图像 URL）作为 designImage 传入，而不是传入 figma URL。在此模式下，kiyas 不会调用 Figma API：

将 Figma 文件中的节点 1:234 导出为 PNG，然后使用 kiyas 将其与登录页面上的主按钮进行比较。

如果使用了 figma URL，但未配置令牌，工具会立即失败并显示相关说明，而不会一直等待。

连接后，你可以向 Agent 提出如下请求：

将 <url> 处的 Figma 画布与登录页面上的主按钮进行比较，然后只列出高严重程度的问题。

Agent 会调用 compare 生成 reportId，然后针对该 ID 调用 list_issues 并传入 severity: "high"。

---

快速入门（CLI）

前置条件

• Node.js 20+
• 已安装并登录 Claude Code（Pro、Max 或 Team 订阅），或使用 OpenAI 的 Codex
• Figma 个人访问令牌（在此生成）— 仅 --figma 需要；使用 --design 与本地截图进行比较无需令牌

安装

npm install -g kiyas-cli
npx playwright install chromium

设置

kiyas setup

此过程会引导你完成：

1. Figma 令牌 — 创建只读个人访问令牌并保存到 .env
2. AI 提供商 — 检查是否已安装 Claude Code 或 Codex，并设置默认项

运行

# Describe the component by name — kiyas finds it automatically
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "eventHeader on the redemption screen"

# Or provide a direct URL if you already know it
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --target "http://localhost:3000/redemption" \
  --selector ".event-header"

# Save the report to a specific path
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --output report.html

# Output as JSON (for CI pipelines)
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --format json

# Compare against a design screenshot instead of Figma (no Figma token needed)
kiyas --design ./design.png \
  --component "primary button" \
  --output report.html

# Use OpenAI instead of Claude
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "nav bar" \
  --model openai

---

CLI 参考

标志	描述	必填
--figma <url>	Figma 画板/组件 URL	是**
--design <path>	设计图片（本地路径或 URL），用于替代 Figma	是**
--component <description>	要查找的组件的自然语言描述	是*
--target <url>	渲染后组件的直接 URL（跳过 AI 查找）	是*
--dev-server <url>	开发服务基础 URL（默认：自动检测 3000/5173/8080/4200）	否
--model <provider>	AI 提供商：claude（默认）或 openai	否
--output <path>	报告保存路径（默认：kiyas-report-<timestamp>.html）	否
--format <type>	输出格式：html（默认）或 json	否
--viewport <size>	截图视口大小（默认：1280x720）	否
--scale <n>	Figma 导出和截图的渲染比例。默认自适应：组件大小的截图（选择器或视口 ≤ 1000px）为 2，大型整页截图为 1	否
--no-full-page	仅截取视口，而非整个可滚动页面	否
--selector <css>	用于截取特定元素的 CSS 选择器	否
--wait <ms>	截图前等待的时间（毫秒）（用于动画/加载）	否
--auth-state <path>	用于已认证截图的 Playwright storageState JSON 文件	否
--config <path>	批量比较所用 JSON 配置文件的路径	否
--threshold <level>	严重级别筛选：all、medium、high（默认：all）	否

*请提供 --component 或 --target。使用 --component 时，kiyas 会使用 AI 在代码库中查找组件并解析其 URL。

**请提供 --figma 或 --design。使用 --design 时，会完全跳过 Figma 导出，且无需 Figma 令牌。

---

已认证截图

大多数真实设计都需要登录才能访问。kiyas 接受 Playwright storageState JSON 文件（cookies + localStorage），并在截图会话中复用该文件；它与 Playwright 测试使用的格式相同，因此测试已生成的任何认证状态文件都可以直接使用。

# 1. Record a session — log in, then close the browser. Playwright writes auth.json.
npx playwright codegen --save-storage=auth.json https://app.example.com

# 2. Use it for kiyas screenshots
kiyas \
  --figma "https://www.figma.com/design/.../?node-id=1:234" \
  --target "https://app.example.com/dashboard" \
  --auth-state ./auth.json

MCP compare 工具提供相同的选项 authState — 传入路径后，Agent 无需进一步设置即可截取已认证页面。

---

身份验证

kiyas 利用你现有的 AI 订阅，无需单独的 API 密钥。它会将所有 AI 调用委托给 Claude Code 或 Codex CLI，由它们自行处理身份验证。

Claude（默认）： 需要安装 Claude Code，并使用 Pro、Max 或 Team 订阅登录。kiyas 会启动 claude CLI 来调用 AI，因此用量会计入你现有的订阅额度。

# Install Claude Code if you haven't already
npm install -g @anthropic-ai/claude-code

# Sign in
claude auth login

OpenAI（替代方案）： 需要安装 Codex 并登录。使用 --model openai 选择它。

codex auth login

如果未找到 CLI，kiyas 会提示你安装并登录：

Claude Code is not installed or not signed in.

kiyas uses your existing Claude Code subscription — no API keys needed.

To fix this, either:

  1. Install and sign into Claude Code:
     npm install -g @anthropic-ai/claude-code
     claude auth login

  2. Or switch kiyas to use OpenAI instead:
     kiyas set model openai
     (requires signing into Codex: codex auth login)

Figma： 需要具有 File content → Read only 权限范围的个人访问令牌。运行 kiyas setup 进行配置，或手动在 .env 中设置 FIGMA_ACCESS_TOKEN。

---

准确性与可复现性

kiyas 是一个围绕视觉 AI 构建的测试框架，而测试框架只有在结果一致时才有用。它会控制以下内容：

• 固定模型 — 比较模型和解析器模型均已固定（claude --model / codex -m），不会随 CLI 默认值变化。使用 kiyas set claudeModel <id> / kiyas set codexModel <id> 进行配置。
• 隔离 AI 上下文 — 比较在空工作目录中运行，因此项目的 CLAUDE.md/AGENTS.md、钩子和 MCP 服务不会影响输出。
• 固定截图环境 — 禁用动画和过渡效果，等待字体加载完成，使用 UTC 时区和固定区域设置，截取整页屏幕截图，并确保 Figma 导出比例始终与屏幕截图的设备缩放系数一致。组件尺寸的截图默认使用 2x；在评估集上测得，这使细微变更的召回率从 75% 提升到了 90%。
• 验证输出 — 对模型响应进行架构验证（格式错误的发现会被丢弃并发出警告；如果无效响应占多数，则运行会失败，而不是生成看似正常但实际错误的报告）。
• 运行清单 — 每份报告的 JSON 都会记录视口、缩放比例、阈值、固定模型、CLI 版本、提示词版本哈希，以及如何解析 --component 描述，因此可以对任意两份报告进行有效比较。
• 多次运行投票 — --runs 3 会并发运行三次比较，并仅保留多数票通过的发现；每项发现都会标注置信度分数。以 N 倍成本换取更高的一致性；默认关闭。
• 基于测量，而非凭感觉 — npm run eval（仅限仓库，不随包发布）会运行一组基准评估：包含已知注入 CSS 变更的测试页面，以及无变更页面对，并通过确定性方式评估召回率、精确率、严重程度一致性、误报下限和多次运行间的稳定性。提示词和流水线变更都会据此进行验证。

---

配置文件

对于需要重复进行比较的团队，可以创建一个 kiyas.config.json：

{
  "figmaAccessToken": "env:FIGMA_ACCESS_TOKEN",
  "model": "claude",
  "viewport": "1280x720",
  "comparisons": [
    {
      "name": "Primary Button",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=1:234",
      "target": "primary button on the login page"
    },
    {
      "name": "Event Card",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=5:678",
      "target": "http://localhost:6006/iframe.html?id=card--event",
      "selector": ".event-card"
    }
  ]
}

target 字段既接受组件描述（由 AI 解析），也接受直接 URL。每次比较都需要将 figma（URL）或 design（本地图片路径）作为设计来源。运行方式如下：

kiyas --config ./kiyas.config.json

---

项目结构

kiyas/  (npm workspaces monorepo)
├── packages/
│   ├── core/                       # @kiyas/core — the engine (private, bundled into the CLI)
│   │   └── src/
│   │       ├── index.ts            # Public API barrel (runComparison, resolveComponent, …)
│   │       ├── config.ts           # Config file loading + Figma token resolution
│   │       ├── settings.ts         # Persisted user settings
│   │       ├── auth/
│   │       │   ├── index.ts        # Auth resolver (picks best available auth)
│   │       │   ├── claude-oauth.ts # Verify Claude Code CLI is available
│   │       │   └── openai-auth.ts  # Verify Codex CLI is available
│   │       ├── resolve/
│   │       │   └── component.ts    # AI agent: finds component in codebase → URL + selector
│   │       ├── capture/
│   │       │   ├── figma.ts        # Figma REST API: export frame as PNG + metadata
│   │       │   └── playwright.ts   # Playwright: headless screenshot of rendered component
│   │       ├── compare/
│   │       │   ├── index.ts        # Orchestrator: sends images to vision AI
│   │       │   ├── pipeline.ts     # Pure runComparison() + report persistence (shared by CLI + MCP)
│   │       │   ├── claude.ts       # Claude comparison via Claude Code CLI
│   │       │   ├── openai.ts       # OpenAI comparison via Codex CLI
│   │       │   └── prompt.ts       # The comparison prompt (shared across providers)
│   │       ├── report/
│   │       │   └── html.ts         # Generate self-contained HTML report with embedded images
│   │       └── utils/
│   │           ├── parse-figma-url.ts  # Extract file key + node ID from Figma URL
│   │           └── logger.ts       # Minimal logging utility
│   └── cli/                        # kiyas-cli — the published npm package
│       ├── src/
│       │   ├── index.ts            # CLI entry point (argument parsing, orchestration)
│       │   ├── setup.ts            # Interactive first-time setup
│       │   └── mcp/
│       │       ├── server.ts       # MCP server bootstrap (stdio transport)
│       │       └── tools.ts        # Zod schemas + handlers (compare, get_diff_report, list_issues)
│       ├── package.json
│       └── tsup.config.ts
├── apps/
│   └── desktop/                    # @kiyas/desktop — Electron app (macOS)
│       ├── src/
│       │   ├── main/               # Main process: IPC, capture flow, pty terminal
│       │   ├── preload/            # Typed context bridge (window.kiyas)
│       │   └── renderer/           # React UI (cream/navy/gold theme, dark mode)
│       ├── build/kiyas.icon        # Icon Composer bundle (Liquid Glass icon source)
│       ├── scripts/gen-icon.mjs    # Renders all icon variants from the Farisi kāf
│       └── electron-builder.yml
├── eval/                           # Golden eval set + scoring harness
├── .env.example
├── .kiyasrc.example
├── package.json                    # Workspace root
└── tsconfig.json

---

技术栈

层级	工具
运行时	Node.js（TypeScript）
MCP	@modelcontextprotocol/sdk、Zod（stdio 传输）
屏幕截图捕获	Playwright（无头 Chromium）
Figma 导出	Figma REST API
AI 比较	Claude Code CLI 或 Codex CLI（视觉）
组件解析	Claude Code CLI / Codex CLI（Agent）
输出	HTML（默认）、JSON
桌面应用	Electron、electron-vite、React、node-pty + xterm
构建	tsup、electron-builder
包管理器	npm

---

许可证

MIT