flows-install

Flows 安装

此技能会自动检测用户项目使用的框架，然后完成 Flows 的完整安装。

步骤 0：检查是否已安装

开始任何操作之前，请检查项目中的任意 package.json 是否已包含 @flows/react 或 @flows/js。如果找到，请告知用户：“此项目已安装 Flows。您想重新安装还是重新配置？”除非用户确认，否则停止操作。

步骤 1：检测安装位置

分析项目结构，以确定 Flows 的安装位置。判断项目是单体仓库还是单个应用项目。请查找以下指标：

单体仓库指标

• 存在 packages/、apps/ 或 libs/ 目录
• 子目录中有多个 package.json 文件
• 使用 Lerna、Nx 或 Turborepo 等单体仓库工具
• 根目录的 package.json 中定义了工作区

单个应用指标

• 项目根目录只有一个 package.json
• 子目录中没有自己的 package.json
• 具有 src/、public/ 和其他常见应用目录的典型结构

步骤 1.1：检测到单体仓库时

询问用户：“我检测到这是单体仓库结构。您要在哪些包中安装 Flows？”并列出检测到的应用包。

步骤 2：检测框架和包管理器

检测包管理器

检查目标目录中的锁文件，以确定包管理器。如果是单体仓库，请检查根目录中的锁文件。

锁文件	包管理器
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lock	bun
bun.lockb	bun
package-lock.json	npm

如果未找到锁文件，默认使用 npm。

检测框架

按以下顺序搜索 package.json 的 dependencies 和 devDependencies，查找这些指标：

框架	package.json 中的指标
Next.js	next
Nuxt	nuxt
React	react、react-dom
Angular	@angular/core
Svelte / SvelteKit	svelte
Solid	solid-js
Vue	vue
Astro	astro
Ember	ember-source

顺序很重要——先检查 Next.js，再检查 React；先检查 Nuxt，再检查 Vue，因为前者涵盖后者的功能。

**Next.js 的额外检测：**如果检测到 next，请检查项目使用的是 App Router 还是 Pages Router：

• App Router：存在包含 layout.tsx 或 layout.js 的 app/ 目录
• Pages Router：存在包含 _app.tsx 或 _app.js 的 pages/ 目录
• 如果两者都存在，优先使用 App Router。

**Svelte 的额外检测：**如果检测到 svelte，请检查 package.json 中的 Svelte 版本，以确定使用 <slot />（Svelte 4 及以下版本）还是 {@render children()}（Svelte 5+）。

文件检测回退方案

如果未匹配到任何包，请搜索框架特定文件：

框架	项目文件中的指标
Next.js	next.config.*
React	.jsx、.tsx
Angular	带有 @Component 的 .ts 文件
Vue	.vue
Svelte	.svelte
Solid	.jsx、.tsx
Astro	astro.config.*
Ember	.gjs、.gts

TypeScript 检测

检查目标包是否有 tsconfig.json。将结果保存为 IS_TYPESCRIPT。此结果决定文件扩展名（.tsx / .ts 或 .jsx / .js），以及是否包含类型注解。

如果未检测到框架

询问用户：“我未能检测到特定框架。你使用的是哪个框架？”

• React
• Next.js (App Router)
• Next.js (Pages Router)
• Angular
• Nuxt
• Vue (不使用 Nuxt)
• Solid
• Svelte / SvelteKit
• Astro
• Ember
• JavaScript (不使用框架)

第 3 步：询问组织 ID

询问用户：

“要安装 Flows，我需要你的 Organization ID——可在 Flows 控制面板的 Settings > General 中找到。”

保存为 ORGANIZATION_ID。

第 4 步：安装 Flows

第 4.1 步：安装软件包

使用检测到的包管理器，在目标目录中运行安装命令。

React 和 Next.js：

npm i @flows/react @flows/react-components

所有其他框架（Angular、Vue、Nuxt、Svelte、Solid、Astro、Ember、JavaScript）：

npm i @flows/js @flows/js-components

将 npm i 替换为检测到的包管理器对应命令（pnpm add、yarn add、bun add）。

第 4.2 步：添加 SDK 初始化代码

将 YOUR_ORGANIZATION_ID 替换为 ORGANIZATION_ID，并将 YOUR_USER_ID 保留为占位注释，供开发者填写。当 IS_TYPESCRIPT 为 true 时，使用 .tsx/.ts 扩展名和类型注解；否则使用 .jsx/.js，并省略类型注解。

按照检测到的框架所对应的参考文件进行操作：

框架	参考文件
React	references/react.md
Next.js (App Router)	references/nextjs-app-router.md
Next.js (Pages Router)	references/nextjs-pages-router.md
Angular	references/angular.md
Nuxt	references/nuxt.md
Svelte / SvelteKit	references/svelte.md
Solid	references/solid.md
Vue (不使用 Nuxt)	references/vue.md
Astro	references/astro.md
Ember	references/ember.md
JavaScript	references/javascript.md

---

第 5 步：验证安装

1. 确认 Flows 软件包已出现在 package.json 的依赖项中。
2. 确认所有文件均已正确创建或修改。
3. 如果 IS_TYPESCRIPT 为 true，运行类型检查命令（例如 tsc --noEmit），并在报告成功之前修复所有类型错误。

第 6 步：提供设置身份验证

身份验证可防止第三方冒充应用用户、代表他们发送事件，以及虚增账户的 MTU 账单。强烈建议在投入生产前完成设置。

询问用户：“你现在要我设置身份验证吗？这需要从 Flows 控制面板获取一个密钥，并在后端提供一个用于计算签名的位置。你也可以跳过，稍后再设置。”

如果用户同意，请按照 references/identity-verification.md 中的说明操作。

如果用户拒绝，或者项目没有可用于计算签名的后端，则跳过此步骤，并在下方的摘要输出中保留该建议。

绝不要在客户端代码中计算签名，也不要将密钥放入浏览器可见的环境变量中。 这样做会暴露密钥，并使保护机制完全失效。

步骤 7：安装 Flows 最佳实践技能

检查此项目中是否已安装 flows-best-practices 技能（查找本地技能文件夹下的 flows-best-practices 目录，例如 skills/ 或 .claude/skills/）。如果不存在，请安装：

npx skills add RBND-studio/flows.sh --skill flows-best-practices

该技能涵盖安装后构建和调试 Flows 功能（工作流、区块、引导、调查、定制组件、SDK 参考），因此它应始终与 flows-install 一同存在。如果已安装，请跳过此步骤。

摘要输出

完成安装后，请提供所做操作的摘要：

# Flows is installed

**Framework:** {framework}
**Files changed:** {list of files modified or created}

**Next steps:**

1. Replace the `YOUR_USER_ID` placeholder with the current user's ID from your auth system.
2. Start your development server to verify everything is working. When on localhost you will see a Flows logo in the bottom right corner - click it to see debug information.
3. Visit your Flows dashboard to create your first workflow: https://app.flows.sh

如果在步骤 6 中设置了身份验证，请在后续步骤中添加：检查浏览器控制台是否存在 User identity verification issue 警告，确认没有警告后，在 Settings > Environments 中强制启用身份验证。

如果跳过了此步骤，请改为添加以下内容：

4. **Recommended before production:** set up [identity verification](https://flows.sh/docs/sdk/identity-verification) so third parties cannot impersonate your users. Ask me to do it whenever you are ready.