设置 AI

安装与配置

在执行任何步骤之前，请阅读开始之前 和终端基础知识。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 本地Web服务器打开apps/web/.env.local，提供商选择打开apps/web/src/agent-runtime.ts； .env.example 是支持的设置名称列表。

2. 保留 AI_PROVIDER=fake 用于本地接口工作，除非您有自己的提供商帐户并想要测试真实生成；切勿将提供程序密钥放入 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 设置中。

3. 使用 corepack pnpm --filter @supastack/web dev 从存储库根启动 Web 应用程序。预期：无需配置付费提供商即可探索本地屏幕；实际生成需要有效的服务器提供程序并在数据库目录中启用模型选择。

默认的 AI_PROVIDER=fake 支持本地确定性工作。真实供应商配置属于服务端环境。.env.example 中列出的供应商密钥包括 OpenAI、Anthropic 与一个 OpenAI 兼容端点。

AI_MODEL_POLICY 包含 cheap、fast、smart 别名的有序模型 ID。空的别名列表会禁用该选项。模型 ID 必须对应数据库目录中已启用且带有有效不可变价格的条目。

AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk    # ai-sdk | mastra | langgraph | openai-agents

要复制的命令

按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。

corepack pnpm --filter @supastack/web dev

实现流程

接受生产任务之前，先配置目录与工作区策略。浏览器拿到的是已启用的别名；能力匹配、模型选择、权限检查与预算执行都留在服务端。

凭证不要放进 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 变量。自带密钥模式使用现有的加密信封与服务端解密边界；绝不要把已存的供应商密钥返回给界面。

验证与排障

如果应用程序报告没有可用的AI模型，请检查服务器的AI_PROVIDER、管理目录中启用的模型和价格以及便宜/快速/智能别名策略。如果真实提供者返回身份验证错误，请检查 apps/web/.env.local 中的密钥并重新启动服务器。前缀为 NEXT_PUBLIC_ 的密钥对浏览器可见，必须删除。

验证禁用别名、缺失能力、失效权限与耗尽预算。真实生成使用单独授权的供应商冒烟运行。如果没有别名可用，检查服务端策略与目录配置，而不是暴露一个原始模型选择器。