# @google/stitch 中文文档

规范地址：https://npmcn.com/package/%40google/stitch/

版本：0\.12\.2
npm 元数据更新时间：2026-11-09T21:37:44.368Z
中文译文更新时间：2026-11-17T06:10:11.201Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40google/stitch
原文对照：https://npmcn.com/package/%40google/stitch/?lang=original
项目主页：https://stitch.withgoogle.com/
源码仓库：https://github.com/google-labs-code/stitch-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.9 MB，101 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：typescript ^5
- 首次发布：2026-10-01T15:38:15.113Z
- 最新版本发布：2026-11-09T21:37:44.212Z
- 近 30 天下载量：5841（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Google Stitch 的第一个代理CLI 和 MCP 服务器

## 安装

```sh
npm install @google/stitch
```

也可以使用：`pnpm add @google/stitch`、`yarn add @google/stitch`、`bun add @google/stitch`

## README

# @ google/ stitch (英语)

在 Google Stitch 创建 UI 屏幕, 从一个提示, 将您运行的应用程序的页面拉到 Stitch 画布上, 然后从您的终端或编码代理上标出 .

```bash
npx @google/stitch generate screen \
  --new-project "Mobile Onboarding Flow" \
  --prompt "Sign-up step with email and phone verification" \
  --device MOBILE
```

这创建了Stitch项目,在其中生成一个移动屏幕,并打印工程和屏幕ID.

### 把已有的页面带入史地奇并重新设计它

从您的本地 Dev 服务器中抓取一条路径作为自定义的 HTML 文件, 上传为屏幕, 然后快速编辑 :

```bash
stitch capture http://localhost:3000/checkout          # saves .stitch/captures/checkout.html
stitch upload screen .stitch/captures/checkout.html --route /checkout --title Checkout
stitch edit screen <screen-id> --project <project-id> --prompt "Use a two-column layout"
```

### 探索屏幕的变体

```bash
stitch generate variants \
  --project <project-id> \
  --screen <screen-id> \
  --prompt "Try warmer colors and a denser layout" \
  --count 3 \
  --creative-range EXPLORE \
  --aspects LAYOUT,COLOR_SCHEME
```

### 本地预览工程屏幕

```bash
stitch serve -p <project-id> --port 3000
```

### 使用编码代理

每个命令都接受 `--json` 用于结构化产出, `--json '{...}'` 用于原始输入有效载荷,以及 `--schema` 打印它所接受的JSON Schema。 代理可以在不读取文件的情况下发现 API :

```bash
stitch generate --schema                 # which resources can be generated
stitch generate screen --schema          # payload schema for one resource
stitch find projects --limit 10 --json
```

或者用您的编辑器注册捆绑的 MCP 服务器 :

```bash
stitch mcp install
```

* * *

## 安装

```bash
npm install -g @google/stitch
```

要求节点.js 20或更晚. 安装两个二进制 : `stitch` 财务报告和审定财务报表 `stitch-mcp` (与 `stitch mcp start`) (中文(简体) ).

## 认证

```bash
stitch login     # Google OAuth in the browser; tokens are stored locally and refreshed automatically
stitch status    # shows which credentials are active
stitch logout    # removes stored OAuth credentials and saved API keys
```

Canvas命令(项目,屏幕,设计系统)除了OAuth之外,可能还需要一个API密钥. 如果命令失败 `MISSING_CANVAS_CREDENTIALS`,设置一个:

```bash
export STITCH_API_KEY=your-api-key
```

| 证书 | 旗帜 | 环境变量 |
| :-- | :-- | :-- |
| API 密钥 | `--api-key` | `STITCH_API_KEY` |
| OAuth 访问符 | `--access-token` | `STITCH_ACCESS_TOKEN` |

`stitch login` 选项: `--port` (左起回调端口,默认值) `8085`, (中文(简体) ), `--json`。 。 。 . `stitch status` 选项: `--flow design|loop`, (中文(简体) ), `--token` (打印出有效的无记名标志), `--json`。 。 。 .

## 配置

存储器默认值 `.stitch.json`数字 :

```bash
stitch config set project 1234567890
stitch config get project
stitch config list      # resolved values from flags, env, and config files
stitch config unset project
```

| 设置 | 旗帜 | 环境变量 |
| :-- | :-- | :-- |
| 项目 | `-p, --project` | `STITCH_PROJECT_ID` |
| 工作空间 | `-w, --workspace` | `STITCH_WORKSPACE` |
| API 基础 URL | `--base-url` | `STITCH_BASE_URL` |

## 全球旗帜

| 旗帜 | 说明 |
| :-- | :-- |
| `--format json|ndjson|table|markdown` | 输出格式。 默认为 `table` 在终端. |
| `--json [payload]` | 以JSON格式输出. 双模式命令( O)`create`, (中文(简体) ), `edit`, (中文(简体) ), `get`, (中文(简体) ), `find`, (中文(简体) ), `api`),也接受JSON原始输入有效载荷. |
| `--schema` | 打印JSON Schema(草案2020-12)用于命令或资源. |
| `--dry-run` | 在突变命令上,验证和预览时不拨打后端. |

## 图标

### `generate`

以双子座生成屏幕或变体.

```bash
stitch generate screen --project <project-id> --prompt "Analytics dashboard with revenue chart" --device DESKTOP
```

| 选项 | 说明 |
| :-- | :-- |
| `-p, --project` | 目标项目 ID |
| `--new-project [title]` | 创建新工程 |
| `--prompt` | 艺术指导提示 |
| `-d, --device` | `DESKTOP` 或者说 `MOBILE` |
| `--model` | `GEMINI_3_8_FLASH` 或者说 `GEMINI_3_5_FLASH_LITE` |
| `--title` | 屏幕标题、最佳工作(项目名称: `--new-project`(中文(简体) ) |
| `--screen` | 源屏幕( 变量) |
| `--count` | 变种数量, 1–5 |
| `--creative-range` | `REFINE`, (中文(简体) ), `EXPLORE`,或 `REIMAGINE` |
| `--aspects` | 逗号分隔 : `LAYOUT`, (中文(简体) ), `COLOR_SCHEME`, (中文(简体) ), `IMAGES`, (中文(简体) ), `TEXT_FONT`, (中文(简体) ), `TEXT_CONTENT` |
| `--dry-run` | 不生成预览 |

### `edit`

更改已有资源 。 对于屏幕,这个以快取再生.

```bash
stitch edit screen <screen-id> --project <project-id> --prompt "Add a dark mode toggle to the header"
```

| 选项 | 说明 |
| :-- | :-- |
| `--prompt` | 艺术指导提示 |
| `--device` | `DESKTOP` 或者说 `MOBILE` |
| `--model` | 生成模式 |
| `--design-system` | 应用的设计系统ID |
| `--json '{...}'` | 原始补丁有效载荷(例如: `design-system`(中文(简体) ) |
| `--dry-run` | 预览不更改任何内容 |

资源: `screen`, (中文(简体) ), `design-system`。 。 。 .

### `capture`

将页面保存为单个自成一体的 HTML 文件,准备上传为屏幕.

```bash
stitch capture http://localhost:3000/library
```

| 选项 | 说明 |
| :-- | :-- |
| `-o, --output` | 输出路径 。 默认 `.stitch/captures/<route>.html`· ; `-` 用于 stdout 的 |
| `--tab [id]` | 抓取打开的 Chrome DevTools 标签为- is, 不重新装入 |
| `--auth` | 剧作家 `storageState` JSON 注册路线 |
| `--origin` | 当抓取本地文件时, 源头为其根相干资产服务 |
| `--allow-redirect` | 即使页面重定向到不同的路由, 也要保存 |

子命令 : `routes` (在代码库中找到的路由列表),以及 `browser`, (中文(简体) ), `port`, (中文(简体) ), `file` 用于明确的捕获模式.

### `upload`

上传屏幕或设计文件到工程中.

```bash
stitch upload screen .stitch/checkout.html --route /checkout --title Checkout
stitch upload design DESIGN.md --project <project-id>
```

子命令 : `screen` (HTML或图像), `design` (DESIGN.md) (英语).

### `serve`

为项目屏幕运行本地预览服务器 .

```bash
stitch serve -p <project-id>
```

| 选项 | 说明 |
| :-- | :-- |
| `-p, --project` | 要预览的工程 |
| `--port` | 默认端口 `3000` |
| `--dry-run` | 检查配置和退出 |

### `find`

列表资源.

```bash
stitch find projects --limit 10
```

| 选项 | 说明 |
| :-- | :-- |
| `--limit` | 最大结果 |
| `--page-size`, (中文(简体) ), `--page-token` | 倾斜 |
| `--filter` | 过滤表达式 |

资源: `project`, (中文(简体) ), `screen`, (中文(简体) ), `design-system`。 。 。 .

### `get`

通过 ID 获取一个资源 .

```bash
stitch get project <project-id> --json
stitch get screen <screen-id> --project <project-id> --json
```

### `create`

从旗帜或JSON有效载荷创建资源.

```bash
stitch create project --title "Customer Dashboard Redesign"
stitch create project --json '{"title":"Customer Dashboard Redesign"}'
```

选项 : `--title`, (中文(简体) ), `--json`, (中文(简体) ), `--dry-run`。 。 。 .

### `delete`

删除资源 .

```bash
stitch delete project --id <project-id> --dry-run
```

选项 : `--id`, (中文(简体) ), `--dry-run`, (中文(简体) ), `-y, --yes` (skip确认).

### `open` 财务报告和审定财务报表 `url`

在 Stitch 画布上打开工程或屏幕, 或打印其 URL .

```bash
stitch open project <project-id>
stitch url screen <screen-id> --project <project-id>
```

`open --url` 打印而不是启动浏览器( 也尊重) `STITCH_NO_BROWSER`) (中文(简体) ).

### `mcp`

把史迪奇作为MCP服务器运行在stdio上.

```bash
stitch mcp install   # register with your AI editor
stitch mcp start     # start the server (what the editor runs)
```

### `agent-skills`

安装 a `SKILL.md` 它教编码代理 如何使用这个CLI.

```bash
stitch agent-skills add      # writes to .agents/skills
stitch agent-skills list
stitch agent-skills update   # resync after upgrading the CLI
```

### `api`

直接调用 Stitch REST 端点 .

```bash
stitch api workspaces
stitch api workspaces/<id>/priorities --schema
```

选项 : `-X, --method` (默认) `GET`, (中文(简体) ), `--json`, (中文(简体) ), `--schema`, (中文(简体) ), `-y, --yes`。 。 。 .

### `privacy`

显示或接受 Stitch 隐私通知和服务条件 : `stitch privacy status | show | accept`。 。 。 .

## 实验:循环工作空间

循环对齐带有 Stitch 的 GitHub 仓库 **工作空间**。你给工作空间 **优先事项**,这些是诸如"减少离职摩擦"之类的长期目标. Stitch对照每个优先级读取代码库和报告 **见解**:与路线挂钩的具体机会. 对于每一个见解,它可以提出 **解决方案**,这是具体的改变.

循环默认关闭 。 命令和API在发布之间可能会有变化.

### 工作流程

```bash
# 1. Turn Loop on and sign in to Google and GitHub
stitch enable loop
stitch login
stitch github login
stitch github configure          # grant the Stitch GitHub App access to your repositories
stitch github repos              # list repositories you can attach to a workspace

# 2. Create a workspace for a repository and make it this directory's default
stitch create workspace --name Storefront --json '{"repositories":["https://github.com/org/storefront"]}'
stitch find workspaces
stitch config set workspace <workspace-id>

# 3. Add a priority, either from a starter template or written from scratch
stitch create priority --templates
stitch create priority --objective "Reduce checkout friction"

# 4. Generate insights and wait for the run to finish
stitch generate insights --priority <priority-id> --watch --notify

# 5. Review the insights, then generate solutions or dismiss them
stitch find insights --priority <priority-id>
stitch generate solutions --insight <insight-id>
stitch find solutions --priority <priority-id>
stitch dismiss insights <insight-id>
```

`stitch status --flow loop` 报告你在登机阶梯 下一步要跑什么.

### 概念

| 资源 | 这是什么 |
| :-- | :-- |
| `workspace` | 和斯迪奇对齐的仓库 它具有优先事项、见解和背景. |
| `priority` | 史迪奇一直反对的目标. |
| `insight` | 从密码库的开采中 找到一个有路可走的机会. |
| `solution` | 提议的改动回应了一个见解. |
| `context` | 外部材料,如docs或specs,附后,因此斯地奇可以超越代码进行推理. |
| `file` | 上传到工作区的文件 . |
| `skill` | 指示如何塑造 Stitch 代理阅读工作空间。 这些是分开的 `stitch agent-skills`。 。 。 . |
| `webhook` | HTTP在工作空间事件上发射回调. |
| `connection` | 与GitHub或Slack等外部工具的集成. |

所有这些工作都与 `find`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `edit`,以及 `delete`。并非所有资源都支持每个动词;运行 `stitch <verb> --schema` 看看他们会做什么.

### 循环命令

**`generate insights`**: 将密码库与一个或多个优先事项相抗衡.

| 选项 | 说明 |
| :-- | :-- |
| `--priority` | 优先ID,或逗号分隔的ID |
| `--watch` | 挡住直到跑道结束 退出代码 `0` 表示已完成, `1` 失败, `124` 超时 |
| `--notify` | 与 `--watch`,在运行结束时发送桌面通知 |
| `--interval` | 投票间隔( 默认) ms `2000`(中文(简体) ) |
| `--timeout` | 等待秒( 默认值) `3600`(中文(简体) ) |
| `--delay` | 延迟透视生成执行 |

**`generate solutions`**:提出修改意见以了解情况。 选项 : `--insight` (ID或逗号分隔的ID),, `--replace-existing` (替换未指定的解决方案).

**`create priority`**: 选项 `--objective`, (中文(简体) ), `--description`, (中文(简体) ), `--templates` (列表启动模板), `-t, --template <id|title|index>`, (中文(简体) ), `-i, --interactive`。 。 。 .

**`dismiss insights <id>`**:从建议中隐藏见解。 选项 : `--concurrency` (默认) `5`, (中文(简体) ), `--dry-run`。 。 。 .

**`edit workspace <id>`**: 选项 `--add-repo`, (中文(简体) ), `--remove-repo` (乌拉圭, `owner/repo`或身份证).

**`upload code [dir]`** 上传编码库归档(a) `.zip` 工作空间. **`upload file <path>`** 上传一个文件.

**`connect [tool]`**:通过提供者的OAuth流量连接一个集成.

```bash
stitch connect --list
stitch connect slack --no-browser --timeout 180
```

选项 : `-l, --list`, (中文(简体) ), `-s, --search`, (中文(简体) ), `--connected`, (中文(简体) ), `--all`, (中文(简体) ), `--no-browser`, (中文(简体) ), `--timeout` (默认) `120`) (中文(简体) ).

**`github`**: 管理 GitHub 连接. 子命令 : `login`, (中文(简体) ), `configure`, (中文(简体) ), `repos`, (中文(简体) ), `status`。 。 。 .

**`api <path>`**: 直接调用工作空间终点, 例如 `stitch api workspaces/<id>/priorities`。 。 。 .

关闭循环 `stitch disable loop`。 。 。 .

## 图书馆

软件包导出一个配置代码库摄取的模块:

```ts
import { defineIngest } from '@google/stitch/ingest';
```

## 已知的限制

-   一些帆布操作需要 `STITCH_API_KEY` 甚至在和OAuth签约的时候.
-   循环是实验性的。 它的资源和旗帜可能会变化而不会出现大的版本起伏.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @google/stitch 是什么？

Google Stitch 的第一个代理CLI 和 MCP 服务器

### 如何安装 @google/stitch？

在项目目录运行 npm install @google/stitch，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 stitch、stitch-mcp，可以用 npx stitch 直接运行。

### @google/stitch 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @google/stitch 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @google/stitch 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @google/stitch 可以商用吗？

@google/stitch 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @google/stitch 的下载量有多少？

根据 npm 官方下载统计，@google/stitch 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,841 次，日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @google/stitch 还在维护吗？

最新版本 0\.12\.2 发布于 2026/11/10（7 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

