stitch-sdk-readme

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stitch SDK README Generator

Stitch SDK README生成工具

This skill produces the README for

@google/stitch-sdk

. It combines a structural strategy (the Bookstore Test) with instructions for sourcing the current API from the codebase — so the README stays accurate as the SDK evolves.

本工具用于为

@google/stitch-sdk

生成README文档。它结合了结构化策略（Bookstore Test）与从代码库中获取当前API的方法，确保SDK演进时README始终保持准确。

How to Source the Current API

如何获取当前API信息

Do not hard-code the API surface. Read it from the codebase at invocation time:

What you need	Where to find it
Public exports (full surface)	`packages/sdk/src/index.ts`
Domain class methods + signatures	Source files for each exported class ( `sdk.ts` , `project.ts` , `screen.ts` )
Generated method bindings	`packages/sdk/generated/domain-map.json` → `bindings[]` array
Handwritten methods	Methods in class source files that aren't in domain-map bindings (e.g. `Screen.edit` , `Screen.variants` )
AI SDK tools adapter	`packages/sdk/src/ai.ts` → subpath entry for `stitchTools()`
Generated tool definitions	`packages/sdk/generated/src/tool-definitions.ts` → JSON Schema for each tool
Tool client methods	`packages/sdk/src/client.ts`
Error codes	`packages/sdk/src/spec/errors.ts` → `StitchErrorCode`
Config options	`packages/sdk/src/spec/client.ts` → `StitchConfigSchema`
Proxy config	`packages/sdk/src/proxy/core.ts`

After reading these files, you have the complete API surface. Structure it using the Bookstore Test template below.

请勿硬编码API内容。在调用时从代码库中读取相关信息：

需要获取的内容	查找路径
公开导出内容（完整API范围）	`packages/sdk/src/index.ts`
领域类方法及签名	每个导出类的源文件（ `sdk.ts` 、 `project.ts` 、 `screen.ts` ）
生成的方法绑定	`packages/sdk/generated/domain-map.json` → `bindings[]` 数组
手写方法	类源文件中未包含在domain-map绑定中的方法（例如 `Screen.edit` 、 `Screen.variants` ）
AI SDK工具适配器	`packages/sdk/src/ai.ts` → `stitchTools()` 的子路径入口
生成的工具定义	`packages/sdk/generated/src/tool-definitions.ts` → 每个工具的JSON Schema
工具客户端方法	`packages/sdk/src/client.ts`
错误码	`packages/sdk/src/spec/errors.ts` → `StitchErrorCode`
配置选项	`packages/sdk/src/spec/client.ts` → `StitchConfigSchema`
代理配置	`packages/sdk/src/proxy/core.ts`

读取这些文件后，你将获得完整的API范围。请按照下方的Bookstore Test模板进行结构化整理。

The Bookstore Test

Bookstore Test 结构

A reader decides whether to use a library the same way a person decides to buy a book: they glance at the cover, read the inner flap, then commit to reading the book. The README must earn the reader's attention at each stage.

读者决定是否使用一个库，就像人们决定是否买一本书：先看封面，读内页导言，然后才决定阅读全书。README必须在每个阶段都能抓住读者的注意力。

The Cover

封面部分

A single sentence stating what problem this library solves — not what the library is. The reader should recognize their own situation. No taglines, no badges, no logos.

For this SDK, the cover is about generating UI from text and extracting HTML/screenshots programmatically.

Good: "Generate UI screens from text prompts and extract their HTML and screenshots programmatically." Bad: "The official TypeScript SDK for Google Stitch, a powerful AI-powered UI generation platform."

用一句话说明该库解决的问题——而非库本身是什么。读者应该能从中识别到自己的使用场景。不要标语、徽章或标识。

针对本SDK，封面部分应围绕“通过文本生成UI，并以编程方式提取HTML/截图”展开。

正面示例： “通过文本提示生成UI界面，并以编程方式提取其HTML和截图。” 反面示例： “Google Stitch官方TypeScript SDK，一款强大的AI驱动UI生成平台。”

The Inner Flap

内页导言

Immediately show the library in use. Code first, not setup.

Primary workflow — the punchline everything in the SDK exists to produce:

project(id) → generate → getHtml

Show this as the first code block, with one line noting the env var requirement. Do not show installation, imports, or config before this. Show

callTool("create_project", ...)

separately for project creation.

Secondary workflows — reveal depth progressively:

Listing and iterating over existing projects/screens
Editing a screen and generating variants
Tool access via singleton (
```
stitch.listTools()
```
,
```
stitch.callTool()
```
) — zero setup
Explicit configuration via
```
StitchToolClient
```
(custom API key, base URL)

AI SDK integration via

stitchTools()

— import from

@google/stitch-sdk/ai

, show

generateText

with

tools: stitchTools()

and

stepCountIs

Rules for this section:

No setup first. One line mentioning
```
STITCH_API_KEY
```
is enough before the first example.
Dual install paths. Show
```
npm install @google/stitch-sdk
```
first (core SDK, standalone). Then show
```
npm install @google/stitch-sdk ai
```
for AI SDK users. The
```
ai
```
package is only needed when importing from
```
@google/stitch-sdk/ai
```
.
Straightforward language. No "powerful", "seamless", "robust", "enterprise-grade".
Working examples. Every code block must be valid, runnable code — not fragments with
```
// ...
```
elisions.
Progressive complexity. Simplest invocation first, then deeper capabilities.

立即展示库的使用方式。先放代码，而非安装配置步骤。

核心工作流——SDK所有功能最终要实现的核心目标：

project(id) → generate → getHtml

将此作为第一个代码块展示，仅用一行说明所需的环境变量。在此之前不要展示安装、导入或配置步骤。项目创建的

callTool("create_project", ...)

单独展示。

次要工作流——逐步展示更多功能：

列出并遍历现有项目/界面
编辑界面并生成变体
通过单例访问工具（
```
stitch.listTools()
```
、
```
stitch.callTool()
```
）——无需配置
通过
```
StitchToolClient
```
进行显式配置（自定义API密钥、基础URL）

通过

stitchTools()

集成AI SDK——从

@google/stitch-sdk/ai

导入，展示带有

tools: stitchTools()

和

stepCountIs

的

generateText

本节规则：

不要先讲配置。第一个示例前只需用一行提及
```
STITCH_API_KEY
```
即可。
两种安装路径。先展示
```
npm install @google/stitch-sdk
```
（核心SDK，独立使用）。再为AI SDK用户展示
```
npm install @google/stitch-sdk ai
```
。只有从
```
@google/stitch-sdk/ai
```
导入时才需要
```
ai
```
包。
语言直白。不要使用“强大的”“无缝的”“健壮的”“企业级”这类词汇。
可运行示例。每个代码块必须是有效的、可运行的代码——不要带
```
// ...
```
省略的片段。
复杂度递进。先展示最简单的调用方式，再逐步深入更复杂的功能。

Reading the Book

正文内容

The reader is committed. Document the full API as a reference.

Structure by class in this order:

Stitch

→

Project

→

Screen

→

StitchToolClient

→

toolDefinitions

toolMap

→

stitchTools()

(AI SDK) →

StitchProxy

→

stitch

singleton.

Each entry should have:

What it does (one line)
Usage example (minimal, runnable)
Parameters (table)
Return type and error behavior

Setup, authentication, and configuration go here — after the reader has already decided the library is worth using.

读者已决定使用该库。此时提供完整的API参考文档。

按以下类别的顺序组织：

Stitch

→

Project

→

Screen

→

StitchToolClient

→

toolDefinitions

toolMap

→

stitchTools()

（AI SDK） →

StitchProxy

→

stitch

单例。

每个条目应包含：

功能说明（一句话）
使用示例（极简、可运行）
参数（表格形式）
返回类型及错误处理

安装、认证和配置内容放在这里——在读者已经决定使用该库之后。

Tone

语气

Write like a colleague explaining their work to another engineer. Be direct. Be specific. Don't sell — inform. If a feature has limitations, state them. If setup is complex, say so.

以同事向工程师讲解工作的语气写作。直接、具体。不要推销，只做说明。如果功能有局限性，直接说明。如果配置复杂，如实告知。

Validation

验证环节

After generating the README, verify:

Can a reader understand what the library does in under 10 seconds?
Is there a runnable code example within the first scroll?
Does setup/config appear after the first code example?
Is every code block valid, copy-pasteable code?
Is the language descriptive rather than promotional?
Does the reference section cover every public export from
```
index.ts
```
?
Every method name in examples exists in its class source file
Every import in examples matches an export in
```
index.ts
```
All three modalities are documented: domain classes (scripts),
```
StitchToolClient
```
(agents),
```
stitchTools()
```
(AI SDK)

生成README后，需验证以下内容：

读者能否在10秒内理解该库的用途？
首次滚动页面内是否有可运行的代码示例？
安装/配置内容是否在第一个代码示例之后出现？
每个代码块是否都是可复制粘贴的有效代码？
语言是否为描述性而非宣传性？
参考部分是否覆盖了
```
index.ts
```
中的所有公开导出内容？
示例中的每个方法名在其类源文件中都存在
示例中的每个导入都与
```
index.ts
```
中的导出匹配
是否记录了三种使用方式：领域类（脚本）、
```
StitchToolClient
```
（Agent）、
```
stitchTools()
```
（AI SDK）

Anti-patterns

反模式

Anti-pattern	Why it fails
Leading with badges, logos, or status shields	Visual noise before the reader knows what the library does
"Getting Started" as the first section	Forces setup before demonstrating value
Feature bullet lists without code	Tells instead of shows
"Easy to use", "simple", "just works"	Self-congratulatory claims that invite skepticism
Long install/config blocks before any usage	Asks for investment before demonstrating return
Collapsible sections hiding core API docs	Buries the content committed readers came for
Hard-coding the API in docs without sourcing	Goes stale when tools are added

反模式	失败原因
以徽章、标识或状态图标开头	在读者了解库的用途前，这些都是视觉干扰
第一个章节是“快速开始”	强迫读者先完成配置，再了解库的价值
仅用功能列表而不带代码	只做告知，不做演示
使用“易于使用”“简单”“开箱即用”这类词汇	自我夸赞的表述容易引发质疑
在展示任何用法前先放冗长的安装/配置步骤	要求读者先投入精力，却未展示价值
用折叠区域隐藏核心API文档	将目标读者需要的内容深埋
不从代码库获取API，而是在文档中硬编码	新增工具时文档会过时