customware-ai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customware AI

Build AI features through the Customware AI Gateway. Use AI SDK on the Hono backend and AI Elements in the React Router SPA when a chat UI is needed.

Preflight security rule: Treat

.env

and every

.env.*

file as inaccessible. Do not read, list, search, preview, or request permission for them. Only a runtime command using

node --env-file=.env ...

may reference

.env

, and that command must not print environment values.

This is the single skill for the complete integration. Do not install or ask the agent to use a separate AI Elements skill; the relevant AI Elements guidance is adapted into this skill's references.

通过Customware AI网关构建AI功能。当需要聊天UI时，在Hono后端使用AI SDK，在React Router单页应用（SPA）中使用AI Elements。

预检安全规则： 将

.env

及所有

.env.*

文件视为不可访问。不要读取、列出、搜索、预览或请求访问这些文件的权限。仅允许使用

node --env-file=.env ...

这类运行时命令引用

.env

，且该命令不得打印环境变量值。

这是完成集成的专属Skill。请勿安装或要求Agent使用单独的AI Elements Skill；相关AI Elements指南已整合到此Skill的参考资料中。

Read First

必读内容

Always read references/gateway-backend.md.
Always read references/models.md.
For chat or other conversational UI, read references/ai-elements-ui.md.
For server tools, tool-backed chat, or any AI action that fetches live app data, read references/tool-usage.md.
For card-style AI UI, tool-rendered UI, typed message parts, or streamed custom UI state, read references/generative-ui.md.
For AI UI, read references/ai-elements-catalog.md, select the needed components, then read only those linked files under
```
references/components/
```
. Open a component's linked example files only while implementing it. Never load the entire components folder or all examples.
For JSON or other typed output, read references/structured-output.md.
When starting from bundled code, read references/examples.md.
Before finishing any implementation, read and follow references/verification.md.

务必阅读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中的要求。

Non-Negotiables

不可协商规则

Call the Customware AI Gateway only from server code. Browser code calls the app's own Hono endpoint.
Read the gateway secret only from
```
CUSTOMWARE_AI_GATEWAY_KEY
```
.
Never expose the key through
```
VITE_*
```
, browser bundles, API responses, logs, HTML, or client-side state.
Never read
```
.env
```
or any
```
.env.*
```
file with a file/tool read, and never request permission to do so. Never run
```
cat
```
,
```
head
```
,
```
tail
```
,
```
sed
```
,
```
awk
```
,
```
rg
```
,
```
grep
```
,
```
ls
```
,
```
stat
```
, or any other command against
```
.env
```
. The only allowed reference is a check command whose argument is exactly
```
node --env-file=.env ...
```
; that command must not print environment variables. Never inspect the key by printing
```
printenv
```
, request headers, or provider objects. Log only non-sensitive pass/fail evidence.
Hardcode the Customware gateway base URL in server code. Do not add a gateway URL environment variable.

Use this exact adapter base URL:

https://app.customware.ai/api/orgs/${orgId}/projects/${projectId}/ai/v1

Always use the real Customware
```
orgId
```
and
```
projectId
```
. Never use placeholders or accept them from the browser for each request.
Use
```
@openrouter/ai-sdk-provider
```
; do not use provider-specific SDKs or call OpenRouter directly.
Do not pass a preset, provider routing, fallback model list, metadata, trace id, or OpenRouter user id. The gateway owns these controls.
Default to
```
google/gemini-3-flash-preview
```
unless the user selects another model or the task clearly requires one of the documented alternatives.
Keep the chosen model id and provider options in one server-owned module/constant. Routes and services must import that value; do not duplicate model literals or add a model catalog/picker when the feature does not require user choice.
If the user names or changes a model during development, send a live
```
hi
```
request through that exact model before finishing.
If the feature generates JSON, run the one-key structured-output check before finishing.
Match the requested JSON field names and shape exactly. Define one shared Zod contract in a neutral shared module/package (for example
```
shared/contracts/
```
) that both app and server may import; the browser must never import from
```
server/
```
, and the schema/enums must never be duplicated. Product-requested limits, such as a 20,000-character input bound, are valid when documented by the feature.
Any upstream AI failure must become a generic, user-safe error at the app boundary; never render raw transport/provider errors.
Keep database access server-owned. Never execute arbitrary model-written SQL. If a feature needs database access, let the model choose a structured tool input and let the server build the read-only, parameterized query from allowlisted filters, tables, or query helpers.
AI Elements works in the React Router client-only SPA. Do not introduce Next.js or App Router route handlers. Generated
```
"use client"
```
directives are harmless React boundary markers and do not require Next.js.
Use pnpm only. Install AI Elements through the bundled installer, which runs non-interactive
```
pnpm dlx shadcn@latest add ... --yes
```
commands and isolates registry-matched primitives from the template's existing UI contracts.

仅从服务器代码调用Customware AI网关。浏览器代码需调用应用自身的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/
```
导入，且切勿重复模式/枚举。功能文档中记录的产品要求限制（例如20000字符的输入限制）是有效的。
任何上游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契约隔离。

Workflow

工作流程

Inspect the generated app and identify its package manager, Hono entry point, React Router structure, and real Customware org/project ids.
Read the relevant references listed above.
Add
```
ai
```
,
```
@ai-sdk/react
```
,
```
@openrouter/ai-sdk-provider
```
, and
```
zod
```
with pnpm only when missing. Complete this dependency install before running the AI Elements installer or any live check.
Add a focused server provider helper using
```
CUSTOMWARE_AI_GATEWAY_KEY
```
and the fixed gateway URL.
Add the Hono endpoint before static-file serving and SPA fallback routes. In this React Router SPA, do not export
```
HydrateFallback
```
from a non-root route; use the template’s existing root fallback only.
Keep the model and its reasoning configuration server-owned. If the UI offers model selection, validate it against the small allow-list in references/models.md.
For chat, install only the selected AI Elements with
```
scripts/install-ai-elements.mjs
```
, then connect
```
useChat
```
to the app's Hono endpoint.
For structured output, use the current AI SDK
```
generateText
```
with
```
Output.object
```
and a Zod schema.
For tool calling, define the tool on the server with
```
tool({ inputSchema, execute })
```
, keep the action boundary server-owned, and use a bounded multi-step setting such as
```
stopWhen: stepCountIs(5)
```
when the model must answer after the tool result.
For
```
PromptInputSubmit
```
, allow the Stop action while status is
```
submitted
```
or
```
streaming
```
; do not pass an input-empty disabled condition that disables Stop after the submitted input is cleared.
Run the mandatory live checks and browser-level UI verification in references/verification.md from the target project, then run the app's normal type/check/build command. If interactive verification fails, inspect the actual page/console from the project-local script before claiming the app is broken.
Lazy-load client AI UI with
```
React.lazy
```
/dynamic import at the route or pane boundary. Keep server-only AI SDK calls (
```
streamText
```
,
```
generateText
```
, tools) and the gateway provider server-only;
```
DefaultChatTransport
```
is the supported client transport for
```
useChat
```
. Do not lazy-load server code into the browser. Treat a large AI UI bundle warning as a real performance issue and isolate heavy Streamdown/AI Elements code from the initial chunk.

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

Version-aware API usage

版本感知的API使用

Package APIs can change. When usage is uncertain, inspect the installed packages in the target project's

node_modules/

before coding:

Read
```
.d.ts
```
files for the type contract and available props/returns.
Read the actual
```
.js
```
/
```
.mjs
```
implementation for runtime behavior and defaults.
Apply this to
```
ai
```
,
```
@ai-sdk/react
```
,
```
@openrouter/ai-sdk-provider
```
, and installed AI Elements components. The installed version and source take precedence over copied examples or stale docs.

包API可能会变化。当不确定用法时，在编码前检查目标项目

node_modules/

中已安装的包：

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

Copy-Ready Examples

可直接复制的示例

Use
```
assets/ai-chat/
```
for a minimal streaming chat.
Use
```
assets/sql-tool-chat/
```
for tool-backed chat with visible tool state and a safe read-only SQL pattern.
Use
```
assets/generative-ui-chat/
```
for tool-driven end-user card UI inside chat.
Use
```
assets/email-parser/
```
for internal server-only typed JSON generation.
Copy only the files needed by the target feature, adapt their import paths, and supply the real org/project ids where the route or service is mounted.
Treat assets as starting code, not files to execute inside the skill repository.

使用
```
assets/ai-chat/
```
获取最小化流式聊天示例。
使用
```
assets/sql-tool-chat/
```
获取带可见工具状态和安全只读SQL模式的基于工具的聊天示例。
使用
```
assets/generative-ui-chat/
```
获取聊天内部由工具驱动的终端用户卡片UI示例。
使用
```
assets/email-parser/
```
获取仅服务器端内部使用的类型化JSON生成示例。
仅复制目标功能所需的文件，调整其导入路径，并在挂载路由或服务的位置提供真实的组织/项目ID。
将assets视为起始代码，而非要在Skill仓库内执行的文件。

Boundaries

边界规则

Use
```
customware-support-widget
```
instead when the request is only to embed the existing support agent widget.
Do not build a second browser-to-gateway path alongside the Hono path.
Do not silently replace an unavailable user-selected model with another model.
Do not create a second key, per-project key, or direct OpenRouter key in the generated app.
Do not display, mask, copy, or otherwise surface
```
CUSTOMWARE_AI_GATEWAY_KEY
```
in the UI. It is not an AI Elements environment-variable display use case.

若请求仅为嵌入现有支持Agent小部件，请使用
```
customware-support-widget
```
。
请勿在Hono路径之外构建第二条浏览器到网关的路径。
请勿在用户选择的模型不可用时自动替换为其他模型。
请勿在生成的应用中创建第二个密钥、每个项目专属密钥或直接的OpenRouter密钥。
请勿在UI中显示、掩码、复制或以其他方式暴露
```
CUSTOMWARE_AI_GATEWAY_KEY
```
。这不属于AI Elements环境变量显示的使用场景。",