customware-ai

Customware AI

通过 Customware AI Gateway 构建 AI 功能。在 Hono 后端使用 AI SDK，并在 React Router SPA 中需要聊天 UI 时使用 AI Elements。

预检安全规则： 将 .env 和所有 .env.* 文件视为不可访问。不得读取、列出、搜索、预览这些文件，也不得请求访问许可。只有使用 node --env-file=.env ... 的运行时命令可以引用 .env，且该命令不得打印环境变量值。

这是完整集成的唯一技能。不要安装或要求 Agent 使用单独的 AI Elements 技能；相关的 AI Elements 指引已整合到本技能的参考资料中。

首先阅读

• 始终阅读 references/gateway-backend.md。
• 始终阅读 references/models.md。
• 对于聊天或其他对话式 UI，请阅读 references/ai-elements-ui.md。
• 对于服务端工具、工具支持的聊天，或任何会获取实时应用数据的 AI 操作，请阅读 references/tool-usage.md。
• 对于卡片式 AI UI、工具渲染的 UI、类型化消息部分或流式自定义 UI 状态，请阅读 references/generative-ui.md。
• 对于 AI UI，请阅读 references/ai-elements-catalog.md，选择所需组件，然后仅阅读 references/components/ 下链接到的文件。仅在实现组件时打开该组件链接的示例文件。切勿加载整个 components 文件夹或所有示例。
• 对于 JSON 或其他类型化输出，请阅读 references/structured-output.md。
• 从捆绑代码开始时，请阅读 references/examples.md。
• 完成任何实现之前，请阅读并遵循 references/verification.md。

不可妥协事项

• 只能在服务端代码中调用 Customware AI Gateway。浏览器代码应调用应用自身的 Hono 端点。
• 只能从 CUSTOMWARE_AI_GATEWAY_KEY 读取网关密钥。
• 绝不可通过 VITE_*、浏览器捆绑包、API 响应、日志、HTML 或客户端状态暴露密钥。
• 绝不可使用文件／工具读取 .env 或任何 .env.* 文件，也绝不可请求这样做的权限。绝不可对 .env 运行 cat、head、tail、sed、awk、rg、grep、ls、stat 或任何其他命令。唯一允许的引用是参数恰好为 node --env-file=.env ... 的检查命令；该命令不得打印环境变量。绝不可通过打印 printenv、请求头或提供方对象来检查密钥。日志中只能记录不敏感的通过／失败证据。
• 在服务端代码中硬编码 Customware 网关基础 URL。不要添加网关 URL 环境变量。
• 使用此确切的适配器基础 URL： https://app.customware.ai/api/orgs/${orgId}/projects/${projectId}/ai/v1
• 始终使用真实的 Customware orgId 和 projectId。绝不可使用占位符，也绝不可接受浏览器为每个请求传入这些值。
• 使用 @openrouter/ai-sdk-provider；不要使用特定提供方的 SDK，也不要直接调用 OpenRouter。
• 不要传入预设、提供方路由、备用模型列表、元数据、跟踪 ID 或 OpenRouter 用户 ID。这些控制项由网关管理。
• 默认使用 google/gemini-3-flash-preview，除非用户选择其他模型，或任务明确需要使用有文档说明的替代模型。
• 将选定的模型 ID 和提供方选项放在一个由服务端管理的模块／常量中。路由和服务必须导入该值；当功能不需要用户选择时，不要重复定义模型字面值，也不要添加模型目录／选择器。
• 如果用户在开发期间指定或更改了模型，完成前应通过该确切模型发送一条实时 hi 请求。
• 如果功能会生成 JSON，完成前应运行单键结构化输出检查。
• 必须严格匹配所请求的 JSON 字段名称和结构。在中立的共享模块／包（例如 shared/contracts/）中定义一个共享的 Zod 合约，供应用和服务端导入；浏览器绝不可从 server/ 导入，架构／枚举也绝不可重复定义。功能文档中明确说明的产品需求限制（例如 20,000 字符的输入上限）是有效的。
• 任何上游 AI 故障都必须在应用边界转换为通用且对用户安全的错误；绝不可呈现原始传输／提供方错误。
• 数据库访问必须由服务端管理。绝不可执行模型编写的任意 SQL。如果功能需要访问数据库，应让模型选择结构化工具输入，再由服务端根据允许列表中的筛选条件、表或查询助手构建只读参数化查询。
• AI Elements 可用于 React Router 的仅客户端 SPA。不要引入 Next.js 或 App Router 路由处理程序。生成的 "use client" 指令只是无害的 React 边界标记，不需要 Next.js。
• 只能使用 pnpm。通过捆绑安装程序安装 AI Elements；该程序会运行非交互式 pnpm dlx shadcn@latest add ... --yes 命令，并将与注册表匹配的原语和模板现有的 UI 合约隔离开来。

工作流

1. 检查生成的应用，确定其包管理器、Hono 入口、React Router 结构，以及真实的 Customware 组织 ID 和项目 ID。
2. 阅读上文列出的相关参考资料。
3. 仅在缺少依赖时，使用 pnpm 添加 ai、@ai-sdk/react、@openrouter/ai-sdk-provider 和 zod。在运行 AI Elements 安装程序或任何实时检查之前，先完成依赖安装。
4. 使用 CUSTOMWARE_AI_GATEWAY_KEY 和固定的网关 URL，添加一个专用的服务端提供程序辅助模块。
5. 将 Hono 端点添加到静态文件服务和 SPA 回退路由之前。在此 React Router SPA 中，不要从非根路由导出 HydrateFallback；只使用模板中已有的根级回退。
6. 模型及其推理配置由服务端管理。如果 UI 提供模型选择，则根据 references/models.md 中的小型允许列表进行验证。
7. 对于聊天，仅使用 scripts/install-ai-elements.mjs 安装所选的 AI Elements，然后将 useChat 连接到应用的 Hono 端点。
8. 对于结构化输出，使用当前 AI SDK 的 generateText、Output.object 和 Zod 架构。
9. 对于工具调用，在服务端使用 tool({ inputSchema, execute }) 定义工具，将操作边界保留在服务端管理，并在模型必须根据工具结果作答时，使用 stopWhen: stepCountIs(5) 之类的有界多步设置。
10. 对于 PromptInputSubmit，当状态为 submitted 或 streaming 时，允许使用 Stop 操作；不要传入输入为空时禁用的条件，否则提交的输入清空后会导致 Stop 被禁用。
11. 从目标项目运行 references/verification.md 中的强制实时检查和浏览器级 UI 验证，然后运行应用常规的类型检查／检查／构建命令。如果交互式验证失败，在声称应用损坏之前，先通过项目本地脚本检查实际页面和控制台。
12. 在路由或面板边界使用 React.lazy／动态导入延迟加载客户端 AI UI。将仅限服务端的 AI SDK 调用（streamText、generateText、工具）和网关提供程序保留在服务端；DefaultChatTransport 是 useChat 支持的客户端传输方式。不要将服务端代码延迟加载到浏览器中。将大型 AI UI 包警告视为实际性能问题，并将体积较大的 Streamdown／AI Elements 代码与初始代码块隔离。

版本感知的 API 用法

软件包 API 可能会发生变化。如果不确定用法，请在编码前检查目标项目 node_modules/ 中已安装的软件包：

• 阅读 .d.ts 文件，了解类型约定以及可用的属性／返回值。
• 阅读实际的 .js／.mjs 实现，了解运行时行为和默认值。
• 对 ai、@ai-sdk/react、@openrouter/ai-sdk-provider 以及已安装的 AI Elements 组件均执行此操作。已安装的版本和源代码优先于复制的示例或过时文档。

可直接复制的示例

• 使用 assets/ai-chat/ 实现最简流式聊天。
• 使用 assets/sql-tool-chat/ 实现带有可见工具状态和安全只读 SQL 模式的工具驱动聊天。
• 使用 assets/generative-ui-chat/ 实现聊天中由工具驱动的终端用户卡片 UI。
• 使用 assets/email-parser/ 实现仅限服务端的内部类型化 JSON 生成。
• 仅复制目标功能所需的文件，调整其导入路径，并在挂载路由或服务时填入真实的组织／项目 ID。
• 将这些资源视为起始代码，而不是要在技能仓库中执行的文件。

边界

• 如果请求仅是嵌入现有的支持 Agent 小组件，则改用 customware-support-widget。
• 不要在 Hono 路径之外另建一条浏览器直连网关的路径。
• 如果用户所选的模型不可用，不要悄悄替换成其他模型。
• 不要在生成的应用中创建第二个密钥、项目专属密钥或直接的 OpenRouter 密钥。
• 不要在 UI 中显示、遮盖、复制或以其他方式暴露 CUSTOMWARE_AI_GATEWAY_KEY。这不属于 AI Elements 环境变量显示的适用场景。