Skip to main content
Glama

License

Phonebook 把你团队已有的截图变成一一个 Storybook 风格组件画廊。无需新增任何测试代码,无需手动维护设计令牌——它把你代码库里已有的内容渲染成一个设计师无需安装任何东西就能打开的静态站点。每个仓库都独立运行 Phonebook;v1 是单平台的,因此一个 Android 仓库(或一个 iOS 仓库)会产出一个 bundle 和一个站点。

功能

  • 零新增测试代码——复用你已经写好的 @Preview / #Preview

  • 无需 SaaS 账号——自托管,完全在你的 CI 或本地运行

  • MCP 优先——编码智能体可以为你检查配置、分析覆盖率、补充缺少的预览,并为你构建画廊

  • 智能组件分组——从预览名称推断出 component / state 卡片,无需任何注解

  • 跨平台——Android(Roborazzi + ComposablePreviewScanner,在 JVM 上运行,无需模拟器)和 iOS(SnapshotPreviews,在模拟器上运行)

  • 对版本敏感的准备——init/doctor 会根据项目的 Kotlin 版本解析出兼容的库版本,并会在 Kotlin/Roborazzi 元数据不匹配导致晦涩的编译器崩溃之前把它抓捕

Related MCP server: ios-agent

演示

Watch the Phonebook promo video

Phonebook gallery screenshot

从 samples/ios 生成的画廊——component / state 卡片来自该应用自己的 #Previews,没有额外注解。

浏览线上画廊 →

工作原理

  1. phonebook generate 运行你的平台的预览渲染引擎,并把输出收集成一个 bundle(manifest.json + images/)。

  2. phonebook build 把这个 bundle 变成一行式静态站点——默认情况下它直接把 index.html 写进 bundle 目录(复用其中已有的 images/,不复制),因此站点最终位于 <bundle>/index.html。传 -o <dir> 则会把所有内容复制成一个独立的网站目录(用于发布到其他位置,或稍后合并多个 bundle)。纯 HTML/CSS/JS,用 file:// 或任何静态托管都能打开。

安装

npm install -g @stag-build/phonebook
brew install stag-build/phonebook/phonebook

或者先 tap 仓库再安装:

brew tap stag-build/phonebook
brew install phonebook

Formula 来源:stag-build/homebrew-phonebook。

npx @stag-build/phonebook <cmd>

与编码智能体一起使用(推荐)

大多数人不会直接运行 CLI——Phonebook 的设计目标就是由编码智能体(Claude Code、Codex 等)通过其 MCP 服务器来驱动。智能体会为你补充修正预览,检查运行配置,并生成画廊;底层的 CLI 是它调用的引擎。

服务器通过 npx @stag-build/phonebook mcp 运行——无需安装步骤。在下面按客户端选择配置即可。

claude mcp add phonebook -- npx -y @stag-build/phonebook mcp

添加到 ~/.codex/config.toml:

[mcp_servers.phonebook]
command = "npx"
args = ["-y", "@stag-build/phonebook", "mcp"]

添加到你的 Claude Desktop 配置(macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "phonebook": {
      "command": "npx",
      "args": ["-y", "@stag-build/phonebook", "mcp"]
    }
  }
}

添加到 .cursor/mcp.json(项目级)或 ~/.cursor/mcp.json(全局级):

{
  "mcpServers": {
    "phonebook": {
      "command": "npx",
      "args": ["-y", "@stag-build/phonebook", "mcp"]
    }
  }
}

添加到项目兼容区根目录的 .codex/config.toml。Xcode 的智能体运行在极简的 PATH 下,因此这条命令把 npx 包在一个 shell 里,先用常规路径补全 Homebrew/nvm:

[mcp_servers.phonebook]
command = "/bin/zsh"
args = [
  "-lc",
  "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; npx -y @stag-build/phonebook mcp"
]
enabled = true

把 mcpServers 配置块添加到 ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json:

{
  "mcpServers": {
    "phonebook": {
      "command": "/bin/zsh",
      "args": [
        "-lc",
        "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; npx -y @stag-build/phonebook mcp"
      ]
    }
  }
}

Android Studio(Gemini 智能模式): 尚不支持——它的 MCP 集成只能连接远程 httpUrl 服务器,不是 Phonebook 这类本地 stdio 进程。请使用上面基于终端的任一客户端(Claude Code、Codex CLI)在 Android 仓库中运行。

然后,在 Android 或 iOS 仓库的对话中直接说:

"Use the phonebook MCP and create a catalog for my designer."

智能体会自然而然地处理其余的事——检查交集、补齐缺失的预览、生成并构建站点。想更精确地下指令,它还提供了:check_setup(配置诊断,与 phonebook doctor 相同)、analyze_coverage(找出缺失预览或深色变体的组件)、get_preview_catalog、run_generate 和 run_build。

快速入门:Android

先执行 phonebook init——它会检测你项目的 Kotlin 版本,并打印出这些步骤,且其中的库版本已解析为兼容版本(例如 Kotlin 2.0 项目会得到 Roborazzi 1.60.0,Kotlin 2.2+ 则拿到最新版)。下面的版本是当前 Kotlin 项目会得到的版本(完整可运行示例见 samples/android/app/build.gradle.kts):

// app/build.gradle.kts
plugins {
    id("io.github.takahirom.roborazzi") // root build.gradle.kts: version "1.72.0" apply false
}

roborazzi {
    generateComposePreviewRobolectricTests {
        enable = true
        packages = listOf("dev.stag.phonebook.sample") // your app's package
    }
}

dependencies {
    testImplementation("org.robolectric:robolectric:4.14.1")
    testImplementation("io.github.takahirom.roborazzi:roborazzi:1.72.0")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:1.72.0")
    testImplementation("io.github.sergio-sastre.ComposablePreviewScanner:android:0.9.3")
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose-preview-scanner-support:1.72.0")
    testImplementation("androidx.compose.ui:ui-test-junit4") // version from your Compose BOM, or pin one
}

在 settings.gradle.kts 旁添加 phonebook.config.json:

{
  "appName": "My Android App",
  "platform": "android",
  "android": { "modules": [":app"], "variant": "debug" }
}

然后,在包含 Phonebook 的仓库中执行:

npx @stag-build/phonebook generate -C /path/to/your/android/repo
npx @stag-build/phonebook build -C /path/to/your/android/repo

打开 phonebook-out/index.html。

快速入门:iOS

把 SnapshotPreviews 作为 SPM 包添加进项目,并添加一个继承 SnapshotTest 的小型 XCTest target(完整可运行示例见 samples/ios):

// PhonebookSnapshotTests.swift
import SnapshottingTests

final class PhonebookSnapshotTests: SnapshotTest {
    override class func snapshotPreviews() -> [String]? {
        return nil // record every #Preview
    }
}

在你的 .xcodeproj 旁添加 phonebook.config.json:

{
  "appName": "My iOS App",
  "platform": "ios",
  "ios": {
    "project": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "simulator": "iPhone 17 Pro"
  }
}

你的 scheme 必须配备、测试这个快照测试 target(可参考示例里的 PhonebookSample.xcscheme)。然后执行:

npx @stag-build/phonebook generate -C /path/to/your/ios/repo
npx @stag-build/phonebook build -C /path/to/your/ios/repo

打开 phonebook-out/index.html。

命名规范

Phonebook 会根据你已有的预览名字,把截图分组为 component / state 卡片——无需额外注解。完整规则与示例见 docs/naming-convention.md。

配置

phonebook.config.json:

Key

Type

Default

Notes

appName

string

—

必填。显示在画廊顶部。

platform

"android" | "ios"

—

必填。

output

string

"phonebook-out"

Bundle 输出目录,相对配置文件解析。

android.modules

string[]

[":app"]

要录制的 Gradle 模块。

android.variant

string

"debug"

构建变体;Phonebook 会运行 <module>:recordRoborazzi<Variant>。

ios.project

string

—

.xcodeproj 路径,相对配置文件。project/workspace 必须填一个。

ios.workspace

string

—

.xcworkspace 路径,相对配置文件。

ios.scheme

string

—

必填。包含 SnapshotPreviews 测试 target 的 scheme。

ios.simulator

string

"iPhone 17 Pro"

用于 -destination 的模拟器设备名。

ios.onlyTesting

string

自动检测

-only-testing: 过滤条件,让 generate 只运行快照类,而不是整个测试套件。从 SnapshotTest 子类自动推导;设 "" 表示运行全部。

generate 和 build 都接受 -C <dir>(包含 phonebook.config.json 的项目目录)。generate 可用 -o <dir> 覆盖 bundle 输出位置,用 --allow-empty 允许 不产出预览的运行。build 接受一个可选 bundle 路径——不传时使用项目的 bundle 目录——以及用于站点输出的 -o <dir>;不带 -o 时,build 会把 index.html 直接写进 bundle 目录,并就地复用它的 images/(不复制),这正是上面快速入门里所用的方式。传入 -o <dir> 则会把 bundle 的资源复制到独立的普通站点目录。

phonebook init 与 phonebook doctor

phonebook init 会检测你的平台,并搭建 phonebook.config.json 以及相关依赖/安装代码片段——库版本都针对你的 Kotlin 版本解析好,app 包名也填好了。它绝不会代你构建文件。

phonebook doctor 检查 generate 需要的所有系统是否都已就绪:插件与测试依赖(使用 Gradle 版本目录时也会一并解析)、扫描器的 packages 值、Kotlin/Roborazzi 兼容性,以及工具链(JDK/Xcode/模拟器)。加一个 --deep 还会额外编译测试源码——更慢,但当静态检查与真实状况不符时更有权威。在 iOS 上,如果已链接 SnapshotPreviews 但还没有 SnapshotTest 的子类,doctor 会指出该加在哪个 target、哪个文件夹(从 .pbxproj 中解析出来),所以绝不会只被告诉“你自己加个类”却不知道加在哪。

phonebook init --write-snapshot-class 是 init 不写文件的唯一例外:当 doctor 在 iOS 上找到链接 target,并且该 target 的源码目录属于 Xcode 的 filesystem-synchronized groups 之一时,它会直接写好 <folder>/PhonebookSnapshots.swift——这样做是安全的,因为同步目录会被 Xcode 自动收录,不需要改 project.pbxproj。其他情况一律拒绝(并给出原因):Snapshots/photo 流程还没接好、项目不是同步组,或子类已存在。

phonebook mcp 启动 MCP 服务器——配置与示例关键词,见上面的“与编码智能体一起使用”。

系统要求

Android:需要 JDK 17+。无需模拟器 — Roborazzi 通过 Robolectric 在 JVM 上渲染,因此 generate 可以在 Linux CI 上运行。

iOS:需要已安装 Xcode 的 macOS,外加一个已启动或可启动的模拟器(generate 会针对指定的模拟器目标运行 xcodebuild test)。CI 中需要一个 macOS runner。

CI 配置方案请参见 docs/ci.md,命名规则请参见 docs/naming-convention.md。

路线图

v1 之后(M5),尚未实现:

  • 在生成的图库中支持搜索和筛选

  • 多 bundle 合并与并排视图(跨平台站点)

  • 两次运行之间的版本差异对比(manifest 中已包含 commit 与图片哈希,可用来支持此功能)

  • 更多 CI 配置方案文档

许可证

MIT — 参见 LICENSE。

Available Tools

5 tools
analyze_coverageA

Scan the codebase for UI components and the previews that cover them, and report what each component is missing: states implied by its parameters, environment objects no preview supplies, dark theme, large text, and localization when the project ships one. Read-only — it reports the gaps, it does not write previews. After editing, pass changed: true (or paths) to hear only about what you touched; the whole project is always scanned either way, so the answers stay correct.

Inputs: dir, paths, changed.

check_setupA

Check that the project is correctly set up for phonebook generate (same checks as phonebook doctor): libraries wired, test target present, JDK/Xcode/simulator available.

Inputs: dir.

get_preview_guidanceA

Return the preview naming convention plus a ready-to-paste preview code template for a component, so any agent writes consistent previews.

Inputs: platform (required), states, component.

run_buildA

Build the static gallery site from a bundle, same as phonebook build <bundle>.

Inputs: bundle (required), output.

run_generateA

Run the platform engine to render all previews and produce a bundle (manifest + images), same as phonebook generate. When previews crash, keeps what rendered and says which previews did not, by file and line. Pass changed or files to render only the previews declared in those files, for a faster loop while iterating.

Inputs: dir, files, changed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool addresses a distinct step in the preview workflow: guidance, setup, coverage analysis, generation, and building. The only adjacent pair (run_generate and run_build) is clearly separated by bundle output versus static-site output.

    Naming Consistency4/5

    Most names are imperative snake_case with a clear object (get_preview_guidance, analyze_coverage, check_setup). run_build and run_generate are a minor deviation because they use a run_ prefix around CLI command names rather than a pure verb_noun structure.

    Tool Count5/5

    Five tools is well-scoped for a focused preview-generation workflow. Each tool earns its place by covering a separate phase from setup to final build, with no redundant or padding tools.

    Completeness5/5

    The tool set covers the full core loop: check setup, get authoring guidance, analyze coverage gaps, generate previews, and build the gallery site. The absence of a write-preview tool is fine because editing code happens outside the server, and the guidance plus coverage tools support that workflow.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables AI agents to render and screenshot isolated UI components instantly across multiple browsers without a dev server or Storybook.
      22
      660 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to review Swift code, scaffold new iOS apps, and build, test, and preview them in the Xcode Simulator using local Apple guides and source references.
      36
      41
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding assistants to inspect frontend projects, search a curated design and motion recipe catalog, prepare and preview structured design plans, apply changes with backups and rollback, capture previews, audit UI accessibility and performance, and monitor activity via a web dashboard.
      24 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables coding agents to ground UI work in real product screens by finding concrete references, materials, and design-system details through a catalogue. It also provides bundled workflow resources, command prompts, and local diagnostics so agents can build and verify interfaces.
      -