stitch-sdk-readme

Stitch SDK README 生成器

此技能用于生成 @google/stitch-sdk 的 README。它结合了结构策略（书店测试）与从代码库获取当前 API 的说明，确保 README 随 SDK 演进而保持准确。

---

如何获取当前 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 表面。请使用下方的书店测试模板来组织内容。

---

书店测试

读者决定是否使用一个库，就像决定是否买一本书：先看封面，再读封底内页，然后决定是否开始阅读。README 必须在每个阶段赢得读者的关注。

封面

用一句话说明这个库解决什么问题，而不是说明这个库_是什么_。读者应该能从中认出自己的处境。不要使用标语、徽章或标志。

对于此 SDK，封面应围绕如何从文本生成 UI，以及如何以编程方式提取 HTML 和屏幕截图。

好例子：“根据文本提示生成 UI 屏幕，并以编程方式提取其 HTML 和屏幕截图。” 坏例子：“Google Stitch 的官方 TypeScript SDK。Google Stitch 是一个强大的 AI 驱动 UI 生成平台。”

内页

立即展示如何使用该库。先写代码，不要先讲设置。

主要工作流——SDK 中所有功能最终都要实现的核心用途：

project(id) → generate → getHtml

将此内容作为第一个代码块，并用一行说明需要设置环境变量。不要在此之前展示安装、导入或配置。单独展示用于创建项目的 callTool("create_project", ...)。

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

1. 列出并遍历现有项目／屏幕
2. 编辑屏幕并生成多个变体
3. 通过单例访问工具（stitch.listTools()、stitch.callTool()）——无需设置
4. 通过 StitchToolClient 显式配置（自定义 API 密钥、基础 URL）
5. 通过 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 包。
• 语言直白。 不要使用“强大”“无缝”“健壮”“企业级”等词语。
• 示例可运行。 每个代码块都必须是有效、可运行的代码，不要用 // ... 省略代码片段。
• 循序渐进。 先展示最简单的调用，再介绍更深入的功能。

阅读手册

读者已经决定使用该库。请将完整 API 编写为参考文档。

按类依次组织：Stitch → Project → DesignSystem → Screen → StitchToolClient → toolDefinitions / toolMap → stitchTools()（AI SDK）→ StitchProxy → stitch 单例。

每个条目都应包含：

• 功能说明（一行）
• 用法示例（精简、可运行）
• 参数（表格）
• 返回类型和错误行为

在这里介绍设置、身份验证和配置——此时读者已经认定这个库值得使用。

语气

像向另一位工程师介绍自己的工作那样写。直截了当，具体明确。不要推销，只需说明情况。如果功能有限制，请如实说明。如果设置复杂，也请明说。

---

验证

生成 README 后，请确认：

• 读者能否在 10 秒内了解这个库的用途？
• 首屏内是否有可运行的代码示例？
• 设置／配置是否出现在第一个代码示例之后？
• 每个代码块是否都是有效、可复制粘贴的代码？
• 语言是否以描述为主，而非宣传？
• 参考文档是否涵盖 index.ts 中导出的所有公共内容？
• 示例中的每个方法名是否都存在于对应类的源文件中？
• 示例中的每个导入是否都与 index.ts 中的导出相符？
• 是否记录了全部三种用法：领域类（脚本）、StitchToolClient（Agent）、stitchTools()（AI SDK）？

反面模式

反面模式	失败原因
开篇就放徽章、Logo 或状态标识	读者还不知道库的用途，就先看到视觉噪声
将“快速开始”作为第一节	还没展示价值，就要求读者先进行设置
只列出功能而不提供代码	只说不示范
使用“易于使用”“简单”“开箱即用”	自我吹捧的说法容易引起怀疑
展示用法之前先给出冗长的安装／配置说明	还没展示回报，就要求读者投入精力
折叠隐藏核心 API 文档	读者费心阅读此文档所要找的内容被藏了起来
文档中硬编码 API，却不基于源码核实	添加工具后，文档内容就会过时