stripe-projects

Stripe Projects — 服务配置

使用 Stripe Projects CLI 插件配置第三方服务（数据库、身份验证、托管、分析、缓存、AI、可观测性），并获取 API 密钥／令牌。

工作流

步骤 1：确保已安装 Stripe CLI + Projects 插件

检查 Stripe CLI 是否可用：

which stripe && stripe --version

如果未安装或版本低于 1.40.0：

• macOS（Homebrew）： brew install stripe/stripe-cli/stripe（或 brew upgrade stripe/stripe-cli/stripe）
• 其他平台： 引导用户访问 https://docs.stripe.com/stripe-cli/install 查看最新说明。

然后确保已安装 Projects 插件：

stripe plugin install projects

步骤 2：搜索目录

确认所请求的提供商／服务是否存在：

stripe projects search <query> --json

如果 result_count 为 0，告知用户未找到该服务并停止。

如果用户的请求含糊不清（例如“我需要一个数据库”），浏览目录并推荐选项：

stripe projects catalog --json

步骤 3：初始化项目

检查项目是否已初始化：

stripe projects status --json

如果尚未初始化，先运行预检，一次性查看所有阻碍因素：

stripe projects init --preflight --json

如果所有预检均通过，或唯一失败项是 TOS_ACCEPTANCE_REQUIRED，则继续：

stripe projects init --accept-tos --yes

如果任何检查因 BROWSER_AUTH_REQUIRED、PROJECTS_SESSION_UNUSABLE 或 ACCOUNT_NOT_ELIGIBLE 而失败，请在此处停止。将该检查的提示信息和解决方法原样告知用户，并让用户自行处理——解决这些问题需要通过浏览器登录或访问 Dashboard，而你无法代为操作。不要自行运行 stripe projects init，也不要重新运行预检：这两种操作都无法替用户清除阻碍，因为只有用户才能完成浏览器登录或 Dashboard 操作。

请遵循失败检查打印的解决方法，不要假定运行 stripe login 就能解决问题。如果 Stripe CLI 会话已存在，stripe login 会报告你已登录，并在不做任何更改的情况下以 0 退出——登录命令的退出代码为 0，并不代表阻碍已清除。

重要： stripe projects init 会在本地 .claude/skills/stripe-projects-cli 安装 stripe-projects-cli 技能。该技能包含完整的初始化后命令参考。

步骤 4：移交给 stripe-projects-cli

验证技能是否已安装：

test -f .claude/skills/stripe-projects-cli/SKILL.md && echo "OK" || echo "MISSING"

如果结果为 MISSING：重新运行 stripe projects init --accept-tos --yes 一次——该技能随 Projects 插件打包，并在初始化时安装。如果这次重试后文件仍然缺失，或 init 以非零状态退出，请将 init 的错误信息告知用户并停止。不要反复运行 init。

如果结果为 OK：使用本地安装的 stripe-projects-cli 技能（使用名称为 stripe-projects-cli 的 Skill 工具调用），继续工作流——添加服务、管理凭据并配置项目。

步骤 5：总结并提出建议

成功添加服务后，按以下格式提供输出：

字段	值
提供商	<provider name>
服务	<service type>
层级	<tier>
环境变量	<variable names only — never values>

然后从目录中推荐 3–5 个不同类别的配套服务（例如，用户添加了数据库，则推荐身份验证、托管或可观测性服务）。仅推荐实际出现在 stripe projects catalog --json 输出中的服务——绝不要编造命令或提供商名称。

以 CLI 为准

CLI 在 .projects/ 下管理所有状态，并生成 .env 文件。不要手动编辑这些文件。如果需要检查项目状态，请使用相应的 CLI 命令：

任务	命令
查看已配置的服务	stripe projects status --json
列出环境变量名称	stripe projects env --json
检查项目运行状况	stripe projects status --json
浏览可用服务	stripe projects catalog --json

只有在用户明确要求时，才直接检查 .projects/ 或 .env——CLI 是权威来源，手动编辑可能会被覆盖。

项目变量

当用户想要存储一个并非来自已配置提供商资源的环境变量时，请使用项目变量，例如应用 URL、功能标志或自行管理的 API 密钥。

为当前环境创建或更新项目变量：

stripe projects variables set <name> --env-key <ENV_KEY> --value <value>

variables set 成功后会立即同步当前环境的输出文件。如果用户未提供值，仅在交互模式下运行不带 --value 的命令，以便 CLI 安全地提示输入。切勿在回复中打印机密值。

将现有项目变量绑定到当前环境：

stripe projects env add <name> --variable --env-key <ENV_KEY>

从当前环境移除变量绑定，但不删除已存储的变量：

stripe projects env remove <name> --variable

列出和删除项目变量：

stripe projects variables list --json
stripe projects variables delete <name> --yes

错误处理

错误代码	原因	恢复方法
BROWSER_AUTH_REQUIRED	没有 Stripe 会话，需要通过浏览器登录	告知用户自行运行 stripe projects init，并在能够完成浏览器登录的终端中执行——你无法解决此问题，自己重新运行也无法消除此问题
PROJECTS_SESSION_UNUSABLE	Stripe CLI 会话存在，但 Projects 无法从中读取实时模式凭据	原样报告消息和解决方法，然后停止。不要重试，也不要运行 stripe login——它会报告用户已登录并以状态码 0 退出
ACCOUNT_NOT_ELIGIBLE	账户尚未完成 Projects 入驻	告知用户运行 stripe projects switch-account 选择账户，或继续为此账户完成设置；报告 CLI 输出的解决方法，然后停止
TOS_ACCEPTANCE_REQUIRED	尚未接受开发者或提供商条款	使用 --accept-tos 重新运行
PROVIDER_NOT_LINKED	提供商需要通过 OAuth 关联	运行 stripe projects link <provider>——这可能会打开浏览器
PLAN_REQUIRED	可部署项需要先配置方案	配置错误中列出的方案，然后重试
UNKNOWN_ERROR	意外失败	向用户显示完整错误消息，并建议使用 --debug 运行以进行诊断
服务不在目录中	查询返回了 0 条结果	告知用户；建议运行 stripe projects catalog --json 浏览其他选项
未找到 CLI	未安装 Stripe CLI	使用 Homebrew（macOS）安装，或参阅 https://docs.stripe.com/stripe-cli/install