@tbox.cn/app-template-agent 0.1.0

package/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+dist-ssr
+.vite
+*.local
+.DS_Store
+*.log
+.pnpm-store
+
+# 环境变量（含密钥，勿提交；用 .env.example 提供模板）
+.env
+.env.*
+!.env.example

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.tbox/app.json

@@ -0,0 +1,4 @@
+{
+  "templateVersion": "7.0.0",
+  "npmModules": []
+}

package/AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md
+
+tbox-agent-app 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。客户端同时运行在浏览器和支付宝小程序 web-view 壳中。
+
+> **工作区上下文（发布态消费，005 v0.4.0）**：仓库内本目录是**根 workspace 成员子树**（无独立 `pnpm-workspace.yaml`），
+> 平台引用 `catalog:` + 根 `pnpm-workspace.yaml` `overrides: workspace:*` 回指根 `packages/` 真源；`pnpm` 命令在根上下文执行。
+> `tbox-app create` 从模板源（目录或 pack tgz）展开生成应用——**不拼接平台真源**：生成应用 `packages/` 仅业务/local 模块，
+> 平台包以 `catalog:` 引用，验证态经注入 overrides（`file:` 本地 tgz）、生产态经 registry 安装；`pnpm-workspace.yaml` 由
+> `pnpm-workspace.template.yaml` 改名生成。
+
+## 工程结构
+
+| 包 | 职责 |
+|---|---|
+| `apps/server` | Express + WS 装配入口，HTTP 路由，TTS 代理；业务工具/卡片由模块自注册（自注册闭环） |
+| `apps/client` | React/Vite 装配入口，业务页面/组件/adapters/bridge |
+| `packages/module-weather` | 示例业务模块（双端单包，本目录内源码；根 workspace 内平台真源在根 `packages/`） |
+
+## 模块开发（双端自注册闭环，逐行同构）
+
+`packages/module-*` 是双端单包，两端入口导出**模块描述对象**并自注册：
+
+- server 入口 `src/server/index.ts`：`export const serverModule = { cards, register(ctx) {...} } satisfies ServerModule`；
+  `register` 内经 `ctx.tools/cards.registerMap/handlers/routes/services/bus` 自注册；只注册不解析（resolveService 仅 handle/事件回调内）。
+- client 入口 `src/client/index.ts`：`export const clientModule = { cards, register(ctx) {...} } satisfies ClientModule`；
+  `register` 内经 `ctx.cards.registerMap(cards)` 注册卡片组件。
+- `cards` map 的 **key 约定 = meta.cardType**（server 端 meta 的 cardType；doctor 会校验），无卡片模块写 `cards: {}`；
+  模块对象必须用 `satisfies`（不能 `: ServerModule` 标注——标注会把 cards 泛化导致类型推导失效）。
+- 每个模块根目录有 `tbox.component.json`（schema v1）声明 contributes（tools/cards/handlers/routes/pages/tabs）。
+  跨模块写操作走 `ctx.services.register/resolve` + 类型化事件总线，业务代码只 import `@tbox.cn/app-contracts`（或领域契约包），不 import `apps/*`。
+
+## 装配文件（双锚点，双端逐行同构）
+
+| 文件 | 作用 |
+|---|---|
+| `apps/server/src/modules.ts` | 服务端模块装配（遍历 modules 调 `register(ctx)`） |
+| `apps/client/src/modules.ts` | 客户端模块装配（与 server 端逐行同构） |
+
+装配文件含锚点区（`@tbox:imports-begin/end` + `@tbox:register-begin/end`，由 tbox CLI 增量维护，保留非标行）和自由区（可手动编辑）。
+`CardType` 从装配数组自动推导（`InferModuleCards`）：增删模块后两端 `CardType` 自动收缩/扩展，`CardOverrides` 等消费方随之编译报错。
+客户端注册表快照在 `apps/client/src/cards/registry.ts`（createClientContext + registerAll → `ctx.cards.getAll()`）。
+
+> **模块与 app 版本配套**：双端模块描述对象为破坏性变更——新模块（serverModule/clientModule 形态）需新版 app（含对应 CLI）装配；
+> 老形态模块（registerServer 函数）add 到新版 app 会跳过装配并告警（需升级模块）。
+
+## 关键入口
+
+```text
+apps/client/src/main.tsx                      # 客户端根入口
+apps/client/src/business/App.tsx              # 业务应用入口
+apps/client/src/platform/AgentChatApp.tsx     # 默认对话运行时
+apps/client/src/modules.ts                    # 客户端模块装配（与 server 端同构）
+apps/client/src/cards/registry.ts             # 卡片注册表快照（CardType → CardComponent）
+apps/server/src/index.ts                      # 服务端入口（HTTP + WS + Vite middleware + createServerContext + createEngineFromContext）
+apps/server/src/modules.ts                    # 服务端模块装配（registerAll）
+packages/app-sdk/src/server/chat-engine.ts    # ChatEngine 工厂
+packages/app-sdk/src/server/context.ts        # ServerContext（注册表聚合 + createServerContext）
+packages/app-sdk/src/server/build-engine.ts   # createEngineFromContext / createSdkToolRuntime / buildToolCardBindings
+packages/app-sdk/src/client/chat-store.ts     # ChatStore 工厂
+packages/contracts/src/                       # 跨端类型契约
+config/                                       # chat/model/plugin 配置
+```
+
+## 常用命令
+
+```sh
+pnpm install
+pnpm dev              # 单进程 localhost:8000（API + WS + 页面 + HMR）
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm verify           # typecheck + test + build + verify:generated
+pnpm verify:generated # 装配一致 + 锚点完整 + 无裸露 import
+pnpm plugin:doctor
+pnpm plugin:inspect <pluginId> <toolId>
+```
+
+模块安装/装配由 `tbox-app` CLI（`@tbox.cn/app-cli`）管理：`create`（顶层）+ `module add --mode local|codegen|sdk --source <路径|tgz|registry包> / remove / list / sync / diff / doctor / update / publish`（模块二级组）。add/remove/sync 后需 `pnpm install`。未安装 CLI 时：`pnpm add -g @tbox.cn/app-cli`（registry 安装）。
+
+## 平台基础设施
+
+以下链路受保护，不得删除或绕过（`scripts/check-inspector.sh` 校验）：
+
+- `@tbox.cn/app-sdk/platform` 的 `installInspector`（`@infrastructure-locked`；`apps/server/src/index.ts` 从 `@tbox.cn/app-sdk/platform` import 并调用 `installInspector(app)`）
+- `apps/client/index.html` 中的 `/__vs_inspector__.js`（`RUNTIME_PATH` 约定不变）
+- `apps/client/babel-plugins/code-inspect.cjs` + `apps/client/vite.config.ts` 中 code-inspect plugin 接入
+- 单端口 8000（dev 和生产统一）
+- 生产环境由 server serve `apps/client/dist`
+
+## 双运行时与插件
+
+- 原生能力统一走 `@tbox.cn/app-sdk/client` 的 `createPlatformAdapters()`（ASR/TTS/upload/feedback；007 下沉）；业务/UI 不直接判断支付宝壳。
+- API/WS 地址由 `@tbox.cn/app-sdk/client` 的 `configureRuntime({ apiBaseUrl })` 注入（`main.tsx`），不得硬编码 host；不直接读 `import.meta.env` 之外的环境（H1）。
+- **不直接 import `@tbox-dev-js/sdk`（全禁）**——平台能力（auth/会话/TTS/LLM/插件/能力适配器/协议客户端）一律经 `@tbox.cn/app-sdk` 公开 API。
+- 平台"插件"页添加插件时只改 `config/plugins.json`。应用代码不复制插件鉴权、参数注入、runtime ID 或 SDK 客户端。
+- 插件结果出卡时按 `packages/contracts/src/cards.ts` 注册 schema，在模块包内注册 adapter 和 client 组件。
+
+## 工程边界（check-workspace 校验）
+
+- `packages/*` 业务包必须有 `tbox.component.json`；SDK/契约（`app-sdk` / `contracts*` / `shared`）豁免。
+- 装配文件不得裸 import（全部 import 行在锚区内）；模块包不得 import SDK/契约内部路径（仅公开入口 `@tbox.cn/app-sdk{/server,/client,/platform}` 与 `@tbox.cn/app-contracts`）。

package/ENV.md

@@ -0,0 +1,77 @@
+# ENV — 环境变量配置
+
+本应用的环境变量统一由外部注入,模板内不提供任何环境变量文件机制(无 `.env` 自动加载)。
+
+## 配置方式
+
+- **本地开发**:shell export 注入(每次新终端需重新执行;见文末命令块)。tbox 模板仓库根提供 `env.sh.example`(git 跟踪,无密钥)——模板仓库内开发可 `cp env.sh.example env.sh` 填值;生成应用请直接 shell export 或平台配置。
+- **生产**:建议在 tbox 平台页面上配置环境变量(平台托管 env,密钥不进代码仓库、不进 git)。
+  生产部署必须 `NODE_ENV=production`(dev-login 强制关闭 + JWT 密钥链 fail-fast 的依据)。
+- 以下变量缺失时服务可启动,但对话/会话/上传链路会 503。
+
+## 必需
+
+### 模型服务(OpenAI 兼容接口)
+
+| 变量 | 说明 |
+|---|---|
+| `APP_AI_BASE_URL` | 模型服务地址(OpenAI 兼容 `/v1`) |
+| `APP_AI_API_KEY` | API 密钥 |
+| `APP_AI_MODEL_NAME` | 模型名称;可留空:`config/llm_provider.json` 的 `modelName` 优先 |
+
+### tbox 平台凭证
+
+| 变量 | 说明 |
+|---|---|
+| `TBOX_API_KEY` | 平台 API Key:插件直接使用;语音/上传/反馈/TTS 靠它换 session。缺失时插件不加载,`GET /api/tbox/session` 返回 503 → 前端平台能力适配器建不起来 |
+| `TBOX_APP_ID` | 应用 ID |
+
+## 统一鉴权(006)
+
+| 变量 | 说明 |
+|---|---|
+| `AUTH_TOKEN_SECRET` | 自有 JWT 密钥(≥32 字节随机串),生产由平台注入。未配置回退:`TBOX_API_KEY`(须 ≥32 字节)→ dev 临时随机;prod 整链空则 fail-fast(拒绝启动)。本地一般无需设置 |
+| `AUTH_MODE` | `required`(默认,缺失 token 一律 401)/ `optional`(缺失 token → 匿名,写通道仍拒绝) |
+| `AUTH_DEV_LOGIN_DISABLED` | 非生产环境需关闭 dev-login 时设 `true`(dev-login 非 production 默认开启,生产强制关闭) |
+| `AUTH_TOKEN_TTL_MS` | token 有效期(毫秒,默认 2h) |
+| `AUTH_TOKEN_ISSUER` | token issuer(默认 `tbox-agent-app`) |
+| `AUTH_EMBED_EXTERNAL_TOKEN` | 是否把外部原始 token 内嵌进自有 JWT(external claim,默认 `true`;`false` 则上游调用需另取) |
+| `AUTH_EXTERNAL_TOKEN_MAX_BYTES` | external 原始 token 上限(bytes,默认 16KB=Node http header 上限)。external claim 使自有 JWT 膨胀 ~1.4x,生产网关 header 上限需 ≥16KB |
+| `AUTH_EXTERNAL_EXCHANGE_URL` | 外部 provider 换发地址;配置后 `/api/auth/login(platform=external)` 走 HMAC 转发换发 |
+| `AUTH_EXTERNAL_SECRET` | 外部换发 HMAC 密钥 |
+| `AUTH_EXTERNAL_PROVIDER` | 外部 provider 名(默认 `external`) |
+| `AUTH_EXTERNAL_JWT_PUBLIC_KEY` | 外部已签 JWT 验签公钥(PEM,RS256):外部返回 `{ jwt }` 且无 identity 时解 `sub`;未配置则解码 `payload.sub` |
+| `AUTH_EXTERNAL_TIMEOUT_MS` | 外部换发请求超时(毫秒,默认 3000) |
+
+## 客户端(Vite 注入)
+
+> 注意:`VITE_*` 由 Vite 在开发/构建时注入(读取 `apps/client/.env` 或启动 shell 中已 export 的环境变量),
+> 与服务端变量的注入通道不同——写在 `apps/server/.env` 或仅服务端 shell 中 export 对 `VITE_*` 无效。
+
+| 变量 | 说明 |
+|---|---|
+| `VITE_AUTH_PROVIDER` | 登录平台:外部 provider 场景设 `external`(壳内 `getAuthCode` → `/api/auth/login(platform=external)` 转发外部);缺省 `alipay`(本地换码)。消费方:`platform/agent-runtime.ts` 的 `createAuthClient({ loginPlatform })` |
+| `VITE_API_URL` | 前端 API 地址覆盖(默认同源相对路径,开发期可指向 server)。消费方:`main.tsx` 的 `configureRuntime({ apiBaseUrl })`（007：SDK 零 Vite 依赖，环境值由模板注入） |
+
+## 可选
+
+| 变量 | 说明 |
+|---|---|
+| `ALIPAY_APP_ID` / `ALIPAY_APP_PRIVATE_KEY` | 支付宝小程序 Auth(login code 换 openId;按需)。私钥为支付宝应用私钥 RSA2 PEM |
+| `WX_APP_ID` / `WX_APP_SECRET` | weapp 换码登录(本地 provider,按需) |
+| `TTS_AUTH_URL` / `TTS_APPKEY` | TTS 鉴权必需:AUTH_URL 为鉴权网关端点(POST `{appkey}` → `timestamp+digest`);APPKEY 为 TTS 应用密钥。**缺失时 TTS 播放直接 CONFIGURATION_ERROR(无「走平台」回退)**,前端报 `[TTS] server error` |
+| `HOST` | 服务监听地址(默认 `0.0.0.0`) |
+| `PORT` | 服务监听端口(默认 `8000`) |
+
+## 本地 export 命令块(必需项,可复制)
+
+```sh
+export APP_AI_BASE_URL=https://...
+export APP_AI_API_KEY=...
+export APP_AI_MODEL_NAME=...
+export TBOX_API_KEY=...
+export TBOX_APP_ID=...
+# TTS(可选;缺失时 TTS 播放报 CONFIGURATION_ERROR):
+export TTS_AUTH_URL=https://open.tbox.alipay.com/agent/v1/homepage/secret/get
+export TTS_APPKEY=your-tts-appkey   # 敏感值勿提交;本地经 shell export 或 env.sh(gitignore)注入
+```

package/LEGAL.md

@@ -0,0 +1,7 @@
+Legal Disclaimer
+
+Within this source code, the comments in Chinese shall be the original, governing version. Any comment in other languages are for reference only. In the event of any conflict between the Chinese language version comments and other language version comments, the Chinese language version shall prevail.
+
+法律免责声明
+
+关于代码注释部分，中文注释为官方版本，其它语言注释仅做参考。中文注释可能与其它语言注释存在不一致，当中文注释与其它语言注释存在不一致时，请以中文注释为准。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# tbox-agent-app
+
+tbox AI Agent 全栈模板（npm 包名 `@tbox.cn/app-template-agent`），多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。
+客户端同时支持浏览器和支付宝小程序 web-view；平台能力（鉴权/会话/TTS/ASR/上传/反馈）经 `@tbox.cn/app-sdk` 统一提供（007 下沉）。
+
+## 快速开始
+
+```sh
+pnpm install
+pnpm dev          # 单进程 http://localhost:8000（API + WS + 页面 + HMR）
+pnpm verify       # typecheck + test + build
+```
+
+> 环境变量：本地开发用 shell export 注入（见 `ENV.md`，含必需变量命令块；每次新终端需重新执行），
+> 生产建议在 tbox 平台页面上配置（平台托管 env，密钥不进代码仓库）。
+
+> 平台包消费（005 v0.4.0 发布态）：生成应用以 `catalog:` 引用 `@tbox.cn/{app-sdk,contracts,contracts-mall}`——
+> 生产（registry 已发布）直接 `pnpm install`；平台包未发布 npm 时，由 `tbox-app create --local-deps <平台 tgz 目录>`
+> 注入 overrides（`file:` 本地发布态产物）后 install 离线可用。
+>
+> 依赖链说明（007）：`@tbox.cn/app-sdk` 新增 dependencies `@tbox-dev-js/sdk`（平台能力客户端）、`@ai-sdk/openai`（LLM）——
+> 生成应用 install 时由 pnpm 自动解析（`@tbox-dev-js/sdk` 已发布 npm；内网/离线环境需 registry 镜像或 store 缓存兜底）。
+
+> 🔐 鉴权（006）：非 production 默认开启 dev-login（浏览器 H5 测试登录，开箱即用）；
+> 生产部署必须 `NODE_ENV=production`（dev-login 强制关闭）。非生产环境如需关闭设
+> `AUTH_DEV_LOGIN_DISABLED=true`。
+
+## 工程结构
+
+```text
+tbox-agent-app/
+  apps/
+    client/                    React/Vite 装配端（业务页面/组件/hooks/样式；平台能力经 @tbox.cn/app-sdk/client）
+    server/                    Express + WS 装配端（~120 行装配：auth 中间件 + 模块挂载 + 平台路由面/TTS/WS）
+  packages/
+    module-weather/            示例业务模块（双端单包）
+  config/                      chat/model/plugin 配置
+  scripts/                     构建、检查和平台脚本
+  pnpm-workspace.template.yaml 应用 workspace 模板（create 生成应用 pnpm-workspace.yaml 的来源）
+```
+
+## 平台能力定制（007 扩展点）
+
+平台轴（安全管道/能力管道/协议客户端）已下沉 `@tbox.cn/app-sdk`，模板保留 3 个注入点 + 模板源码扩展：
+
+| 口子 | 位置 | 场景 |
+|---|---|---|
+| `createAuthRuntime(readAuthConfig(), { exchanges })` | `@tbox.cn/app-sdk/server` | 自定义/覆盖登录 provider（注入优先于内置 alipay/weapp） |
+| `createPlatformAdapters(session, overrides)` | `@tbox.cn/app-sdk/client` | 自定义 ASR/TTS/upload/feedback 实现（contracts 接口，UI 零改动） |
+| `createAuthClient({ loginPlatform, devUser })` | `@tbox.cn/app-sdk/client` | 客户端登录配置（`main.tsx`/`platform/agent-runtime.ts`）；**应用级单例**——重复调用幂等返回首建实例，首建选项生效 |
+| `configureRuntime({ apiBaseUrl })` | `@tbox.cn/app-sdk/client` | API/WS 地址注入（`main.tsx`；对应 `VITE_API_URL`） |
+| bridge 透传 | `@tbox.cn/app-sdk/client` 的 `callJsapi` | 业务新能力（扫码/导航/分享等，壳子补 JSAPI 白名单） |
+
+UI 表现与编排（组件/hooks/容器/样式/id 前缀约定）、业务意图表、演示工具、配置数据留模板源码（源码即扩展点）。
+
+> **发布态消费（005 v0.4.0）**：仓库内本模板是根 workspace 成员子树（无独立 `pnpm-workspace.yaml`/lock），
+> 平台引用 `catalog:` + 根 `pnpm-workspace.yaml` `overrides: workspace:*` 回指根 `packages/` 真源；
+> `tbox-app create` 从模板源（目录、pack tgz 或 registry 包 `@tbox.cn/app-template-agent[@version]`）展开生成应用——
+> 生成应用**不含平台成员**，平台包经注入 overrides（`file:` 本地 tgz，验证态）或 registry（生产态）安装；
+> `pnpm-workspace.yaml` 由 `pnpm-workspace.template.yaml` 改名生成。CLI 未安装时：`pnpm add -g @tbox.cn/app-cli`。
+
+开发规则见 `AGENTS.md`。

package/apps/client/STYLE_GUIDE.md

@@ -0,0 +1,81 @@
+# STYLE_GUIDE.md — `client/`
+
+纯 web（Vite + React + Less）的 CSS 约定。只列对本项目仍适用的几条；本项目是 web-view H5、不是原生小程序，**没有小程序 CSS 限制**。
+
+## 1. 大写 `PX` 跳过 px→rem 转换
+
+`postcss-pxtorem` 把 `px` 自动转 `rem`（写设计稿 px 即可）。当某个值需要**固定屏幕像素、不随 rem 缩放**时（典型：PC 端内容区限宽），用**大写 `PX`** —— 转换器大小写敏感，`PX` 不会被转。
+
+```less
+.box {
+  max-width: 800PX;   /* 固定 800px，不转 rem */
+  padding: 24px;      /* 24px → 0.24rem，随屏缩放 */
+}
+```
+
+内容区最大宽度统一用 token，别到处写 `800PX`：
+
+```less
+max-width: var(--tbox-content-max-width);   /* = 800PX */
+```
+
+> `1px` 边框默认不转（`minPixelValue`）。本项目无 stylelint，无需 `unit-case` 注释。
+
+## 2. flex 里图标 / 图片别被压扁或溢出
+
+flex 容器里，固定尺寸的图标 / 图片若不约束，会在同行文本触发 `text-overflow: ellipsis` 时被压缩变形，或撑开布局。
+
+**规则：固定尺寸的 flex 子项加 `flex-shrink: 0` + 显式宽高。**
+
+```less
+/* 标题行：右侧箭头图标别被长标题挤压 */
+.title-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+
+  .icon { flex-shrink: 0; }   /* Phosphor / img 都加 */
+}
+
+/* 列表项左侧图标：固定尺寸 + 不收缩 + 裁切 */
+.item-icon {
+  width: 72px;
+  height: 72px;
+  flex-shrink: 0;
+  overflow: hidden;
+
+  img { width: 72px; height: 72px; object-fit: contain; }
+}
+```
+
+## 3. 隐藏滚动条（移动端观感）
+
+应用为移动端设计，滚动容器在 PC / web-view 里会冒出滚动条，与设计不符。
+
+**规则：可滚动容器隐藏滚动条。**
+
+```less
+.scroll-container {
+  -ms-overflow-style: none;     /* IE/Edge */
+  scrollbar-width: none;        /* Firefox */
+
+  &::-webkit-scrollbar {        /* Chrome/Safari/WebKit */
+    display: none;
+    width: 0;
+    height: 0;
+  }
+}
+```
+
+## 4. 颜色用 `rgba()` 传统语法（web-view 兼容）
+
+CSS Color 4 的空格分隔 `rgb(r g b / a)` 语法在**部分旧机型的支付宝 web-view（旧 WebKit）**可能不支持，导致**整条属性失效**（不是降级，是消失）。新写代码优先用 `rgba()`：
+
+```less
+/* ✅ 安全 */
+box-shadow: 0 3px 8px rgba(1, 112, 254, 0.04);
+color: rgba(31, 59, 99, 0.85);
+
+/* ⚠️ 旧 web-view 风险：整条可能失效 */
+box-shadow: 0 3px 8px rgb(1 112 254 / 3.92%);
+```

package/apps/client/VISUAL_RESTORE.md

@@ -0,0 +1,90 @@
+# VISUAL_RESTORE.md — 视觉还原 / 图片驱动开发
+
+用户给一张设计图 / 截图 / 原型图,要你照着改本模版时读这份。先解析、出设计指南、用户确认,再写代码——**禁止跳过解析直接开发**。
+
+## 流程
+
+1. **解析图片** → 按下方「设计指南输出模板」产出完整文档(颜色给 `#xxxxxx`、文案给完整原文、尺寸给具体 px)。
+2. **用户确认** → 等确认或调整。
+3. **按指南开发** → 遵守下方「还原硬规则」+ `client/AGENTS.md`(组件/图标/图片策略)+ `server/src/cards/AGENTS.md`(卡片)。
+
+---
+
+## 还原硬规则(确定性,必须遵守 —— 这些有明确对错、最值钱)
+
+1. **模块顺序 / 位置 1:1**：解析先产出"自上而下的模块清单 + 每块位置(左/右/居中)和层级",落地严格按清单顺序和位置写 DOM。**禁止重排模块、改上下顺序、把"左立绘右文字"改成"上下排列"。**
+2. **文案 1:1 完整**：可见文字逐字照搬,**不截断 / 不省略 / 不用"示例 / xx / xxxx"占位**;卡片的 `sampleData` 和 dataSchema 的 `.default(...)` 都填**真实文案**(default 尤其不能是占位词,它是兜底展示值)。长文案换行容纳,别截短。
+3. **截断不补全(红线)**：截图边缘被裁、半露、折叠态的区块是**不完整信息**。**唯一允许**保留完整可见的折叠态(只渲染「标题 + 箭头」,到此为止);**严禁**补全 / 展开 / 推测内容,**严禁**拿其它元素(尤其快捷指令 chip)填充充数。口诀:**看不全,就不做。**
+4. **网格用 CSS Grid**：固定列数一律 `grid-template-columns: repeat(N, 1fr)` + `gap`(grid 自动处理间距、任意列数不溢出);**不要用 `flex + width: 25%`**(忘减 gap 会换行成 N-1 列、还会横向溢出)。
+5. **热区 ≠ 视觉高度**：设计规范里"可点击热区 ≥ 44px"指**点击范围**,不是视觉高度。热区不足用**透明 padding** 扩,**不要用 `min-height` 把 tab / 小标签撑高**(content-box 下还会叠加 padding,撑出 64px)。
+6. **高度与留白贴合**：模块间距、整体高度照设计稿,**不无脑拉长、不挤扁**。
+7. **不溢出**：放可变长文本的 flex 子项加 `min-width: 0`,文本用 `overflow-wrap` / `-webkit-line-clamp` 换行或省略——别让长文本撑爆、把按钮 / 步进器挤出。
+8. **富文本分色**：部分高亮 / 分色的文字(如满赠文案里某几个字是橙色)拆成独立 `<span>` 分别上色,别整段一个颜色。
+
+## 平台固定组件:不碰、不另画、不挪位
+
+对话基础设施是平台封装好的——**识别到就跳过,只还原它们之间的业务内容区**:
+- `ChatInput`(输入框/上传/语音)、`MessageBubble`(气泡/Markdown/思考)、`ActionBar`(朗读/复制/赞踩/调试)、`ChatHeader`、`ScrollToBottomButton` / `PullDownIndicator`、`CardRenderer`。
+- **快捷指令 = `QuickCommands`**:不管设计稿里它在哪个位置、标题叫什么(千问/推荐/常见问题),**都只配 `client/config/chat.json` 的 `quickCommands`,绝不在页面里再画一份**(否则和底部重复成两排);`label` 只写纯文字、图案走 `icon` 字段(别把 ✦/emoji 写进 label)。
+- 详见 `client/AGENTS.md`「平台标准组件」。
+
+## 技术路线判断(判错全盘皆错)
+
+- **整屏 App 页**(带状态栏 / 导航 / 输入框的一整屏,如智能体首页)→ 改 `client/src/pages/index`,**复用现成模块**(欢迎/轮播/宫格/猜你想问)改数据,**禁止做成卡片**。
+- **对话气泡里的一块结构化内容**(点单/天气/确认/推荐)→ 走**卡片(C 方案)**:server `cards/<type>/meta.ts` 数据契约 + client `cards/<type>/index.tsx` React 渲染。见 `server/src/cards/AGENTS.md`。
+
+## 素材
+
+- **图标**:`@phosphor-icons/react`——**线性用默认、设计稿是实心图标就 `weight="fill"`**(别再退回 `<img>`);具名导出,名字按语义猜、拼错会编译报错。`size` 偏大就取小(16–24、宫格/导航 28)。只有**品牌/插画/定制图标**(图库字体都给不了的)才用 `<img>` 素材槽位。
+- **图片**:除 icon 外(含品牌 / 立绘 / logo 等,不区分)一律**先取一张 Unsplash 真图**(有 key 走 API、无 key 拼 `images.unsplash.com/photo-<id>?w=800&q=80`;精确词不行就用泛词、示意到位即可)、**必须 `curl` 验证 `200 + image/ + 体积` 通过才用**,验不过换 id/换词、多次不行才降级成渐变块——**完整规则见 `client/AGENTS.md`「图片素材策略」**。**别用孤零零小 emoji 充当主视觉**。
+
+## 卡片还原(C 方案的落地路线)
+
+判断为卡片后(见上「技术路线判断」),按这条链走,各步细节指向真源、不在此复述:
+
+1. **拆解** → 按下面「图片解析」「设计指南输出模板」出设计指南。含 tab / 步进 / 表单 / 派生值的交互卡,额外列 **source / derived / emit**:source→`useState`、derived→渲染时由 state 算、emit→`sendUiAction(cardId, …)` 的 payload 读当前 state(完整见 `server/src/cards/AGENTS.md`「交互卡片的设计纪律」)。
+2. **落地** → 严格按 `server/src/cards/AGENTS.md`「新增卡片步骤」:server `meta.ts`(dataSchema 字段全 `.default` / `.optional`)+ 两端 `registry` 注册 + 触发 tool 接 `TOOL_CARD_MAP`;client `index.tsx`(`data` 用 `import type` 从 meta 推导)。
+3. **数据** → 还原出的文案 **1:1 落进 `sampleData` 和 dataSchema `.default`**(真实文案,default 不能是占位词——它是兜底展示值)。
+4. **样式** → 字号按 2x 梯度;圆角 / 阴影 / 默认白底走 `.tbox-card` 卡框(已裁圆角)、**内边距和宽度自己写**;整卡换底色 / 出血图就在卡片 root 设 `background` / 铺满图(会裁进圆角、不出白边),**别再套一层带圆角容器**;宽度占满整列。详见 `server/src/cards/AGENTS.md`。
+5. **图片** → 除 icon 外先取 Unsplash 直链(有 key 走 API、无 key 拼 `images.unsplash.com/photo-<id>`)+ `curl` 验证 `200 + image/ + 体积` 通过才用,`<img>` 加 `onError` 占位(见上「素材」与 `client/AGENTS.md`「图片素材策略」)。
+
+**收尾自检**:模块 / 文案 1:1?折叠区没补全?字号已 ×2(没照抄 1x 截图)?容器没重画?图片都校验过 + 带 `onError`?`sampleData` / `.default` 是真实文案?server `build` 与 client `typecheck` / `build` 通过?
+
+---
+
+## 图片解析基础要求(出设计指南前)
+
+- **深度拆解**:不要只描述整体外观,**逐层拆解内部结构**——子元素组成、排列(水平/垂直/网格)、对齐、嵌套。如一张卡:左图标+右文字还是上图下文?文字有无主标题+副标题层级?有无右侧箭头/标签?
+- **尺寸精度**:所有尺寸给**具体 px**(以屏宽 375 或设计稿标注宽为基准按比例反推),禁止"较大/适中/紧凑"。必标:整体宽高、内边距(上右下左)、子元素间距 gap、圆角、图标/头像尺寸、行高。判断不准的给估计值并标"(估计值)"。
+  - ⚠️ **量出来的是屏上(1x)px**;写进卡片 `.less` 时是 **2x 源码 px(CSS px 会折半渲染),一律 ×2**;字号别自定、直接用 `server/src/cards/AGENTS.md` 的 2x 字号梯度。图标 `size`(屏幕 px)与热区 44 不折半、不 ×2。
+- **完整文案提取**:所有可见文字逐字抄录(标题/副标题/按钮/placeholder/提示/标签/声明),不可"类似 xxx"。
+
+## 设计指南输出模板(每节必填,占位符替换成真实值)
+
+```
+1. 品牌定位：应用名称 / 类型 / 设计风格(3-4 关键词) / 目标用户 / 核心价值(3-5 项)
+2. 配色方案：
+   - 主色 Primary / PrimaryDark / PrimaryLight: #xxxxxx
+   - 辅助：成功 / 警告 / 错误: #xxxxxx
+   - 中性：标题文本 / 正文 / 辅助 / 边框 / 背景 / 纯白: #xxxxxx
+   - 渐变：完整 linear-gradient(...) 值
+3. 字体规范：H1/H2/H3/正文/辅助/小字 各 xxpx + 字重
+4. 间距与圆角：左右安全边距 / 顶部底部 / 区块间距 / 同级间距 / 组件内 padding(上右下左) / 行高 / 各处圆角 各 xxpx
+5. 业务内容区组件：对每个组件按"外观(尺寸/底色/边框/圆角/阴影/外距) → 内部结构(子元素排列/对齐/间距/各自尺寸色字号) → 状态(默认/按下/禁用)"三层描述。
+   （卡片**最外层容器**的圆角/阴影/默认白底由 `.tbox-card` 卡框提供并裁圆角,**内边距自己写**;整卡换底色就在卡片 root 设 `background`(会裁进圆角、不出白边)、别再套一层带圆角容器;平台固定组件——气泡/输入框/操作栏/导航/快捷指令——只标注"复用平台组件"，不解析其内部、不重造。）
+6. 页面结构：ASCII 线框图 + 各模块自上而下顺序与位置。
+7. 交互规范：发送 / 快捷问题点击行为 / 滚动行为 / 其它可见交互。
+8. Agent 人设：角色定义 / 核心能力 / 能力边界 / 回复风格 / 特殊规则(写进 system instructions)。
+```
+
+> 所有 `xxpx` / `#xxxxxx` 必须替换为从图中提取的实际值;某区域不可见就显式写"图中未体现,建议 xxx"并给合理默认。
+
+---
+
+## 还原边界(避免过度抠像素)
+
+- 字体度量、leading 留白不强行消除;颜色精度差 1-2 hex 视为 OK。
+- 完成后简要说明哪些细节做了让步、原因。
+
+## 一句话
+**先解析出完整设计指南 → 用户确认 → 严格按"模块 1:1 / 文案 1:1 / 看不全不做 / Grid / 热区非视觉高 / 平台组件不碰 / 整屏走 pages、内容块走卡片"开发。** Web 端 CSS 细节(大写 PX / 滚动条 / rgba)见 `client/STYLE_GUIDE.md`。

package/apps/client/assets/keyboard-circle.svg

@@ -0,0 +1,12 @@
+<svg width="44px" height="44px" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
+  <g fill="currentColor" fill-rule="evenodd">
+    <path d="M22,0 C34.1502645,0 44,9.8497355 44,22 C44,34.1502645 34.1502645,44 22,44 C9.8497355,44 0,34.1502645 0,22 C0,9.8497355 9.8497355,0 22,0 Z M22,3 C11.5065898,3 3,11.5065898 3,22 C3,32.4934102 11.5065898,41 22,41 C32.4934102,41 41,32.4934102 41,22 C41,11.5065898 32.4934102,3 22,3 Z"/>
+    <circle cx="14" cy="15" r="2"/>
+    <circle cx="22" cy="15" r="2"/>
+    <circle cx="30" cy="15" r="2"/>
+    <circle cx="14" cy="22" r="2"/>
+    <circle cx="22" cy="22" r="2"/>
+    <circle cx="30" cy="22" r="2"/>
+    <rect x="12" y="28" width="20" height="4" rx="2"/>
+  </g>
+</svg>

package/apps/client/assets/more-circle.svg

@@ -0,0 +1,3 @@
+<svg width="44" height="44" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
+  <path d="M22,0 C34.15,0 44,9.85 44,22 C44,34.15 34.15,44 22,44 C9.85,44 0,34.15 0,22 C0,9.85 9.85,0 22,0 Z M22,3 C11.507,3 3,11.507 3,22 C3,32.493 11.507,41 22,41 C32.493,41 41,32.493 41,22 C41,11.507 32.493,3 22,3 Z M23.5,11.7 L23.499,20.5 L32.3,20.5 L32.3,23.5 L23.499,23.5 L23.5,32.3 L20.5,32.3 L20.499,23.5 L11.7,23.5 L11.7,20.5 L20.499,20.5 L20.5,11.7 L23.5,11.7 Z" fill="currentColor"/>
+</svg>

package/apps/client/assets/new-chat.svg

@@ -0,0 +1,3 @@
+<svg width="44" height="44" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
+  <path d="M22,2.75 C26.737,2.74 31.309,4.484 34.837,7.645 L35.002,7.803 C35.259,8.103 35.42,8.488 35.42,8.914 C35.42,9.578 35.019,10.176 34.405,10.428 C33.79,10.68 33.084,10.535 32.619,10.061 L32.674,10.094 C29.981,7.669 26.539,6.239 22.92,6.043 L21.93,6.017 C17.686,6.018 13.619,7.719 10.637,10.74 C5.72,15.726 4.605,23.325 7.883,29.513 L8.078,29.872 L8.078,35.922 L14.128,35.922 L14.491,36.117 C16.493,37.175 18.695,37.799 20.955,37.95 L22,37.987 C25.817,37.987 29.429,36.663 32.303,34.236 L32.736,33.851 C33.335,33.311 34.233,33.271 34.877,33.755 C35.512,34.232 35.699,35.105 35.31,35.798 L35.152,36.08 C31.868,39.164 27.599,40.985 23.1,41.221 L21.912,41.25 C18.928,41.232 15.988,40.527 13.321,39.189 L6.791,39.189 C5.697,39.189 4.811,38.303 4.811,37.209 L4.811,30.683 C1.093,23.283 2.502,14.338 8.316,8.441 C11.638,5.079 16.086,3.065 20.805,2.787 L22,2.75 Z M33.755,13.845 C34.657,13.845 35.387,14.579 35.387,15.477 L35.387,20.368 L40.007,20.368 C40.908,20.368 41.639,21.099 41.639,22 C41.639,22.901 40.908,23.632 40.007,23.632 L35.383,23.632 L35.383,28.424 C35.383,29.325 34.653,30.056 33.752,30.056 C32.851,30.056 32.12,29.325 32.12,28.424 L32.12,23.632 L27.588,23.632 C27.005,23.632 26.466,23.321 26.175,22.816 C25.883,22.311 25.883,21.689 26.175,21.184 C26.466,20.679 27.005,20.368 27.588,20.368 L32.124,20.368 L32.124,15.477 C32.124,14.575 32.857,13.845 33.755,13.845 Z" fill="#4E6688"/>
+</svg>

package/apps/client/assets/quick-command-star.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" fill="none">
+  <path d="M16 2C16.8 8.4 23.6 15.2 30 16C23.6 16.8 16.8 23.6 16 30C15.2 23.6 8.4 16.8 2 16C8.4 15.2 15.2 8.4 16 2Z" fill="#4E6688"/>
+</svg>

package/apps/client/assets/send-gradient.svg

@@ -0,0 +1,14 @@
+<svg width="56" height="56" viewBox="0 0 56 56" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient x1="-22%" y1="14.7%" x2="90.1%" y2="75.2%" id="sendGrad">
+      <stop stop-color="#AE94FF" offset="0%"/>
+      <stop stop-color="#2388FF" offset="100%"/>
+    </linearGradient>
+  </defs>
+  <circle fill="url(#sendGrad)" cx="28" cy="28" r="28"/>
+  <g transform="translate(28,28) rotate(-90) translate(-28,-28) translate(10,10)" fill="#FFF">
+    <g transform="translate(16.68,17.1) scale(-1,1) translate(-16.68,-17.1) translate(1.86,4.5)">
+      <path d="M27.914,10.908 L5.868,10.908 C5.865,10.908 5.862,10.9 5.865,10.9 L14.18,2.908 C14.615,2.49 14.794,1.871 14.649,1.284 C14.504,0.698 14.057,0.234 13.477,0.066 C12.896,-0.101 12.271,0.054 11.836,0.472 L0.518,11.349 C0.187,11.668 0,12.108 0,12.567 C0,13.027 0.187,13.467 0.518,13.785 L11.898,24.725 C12.22,25.037 12.654,25.208 13.103,25.2 C13.551,25.191 13.978,25.004 14.288,24.679 C14.934,24.005 14.913,22.936 14.241,22.289 L5.927,14.297 C5.923,14.294 5.927,14.289 5.931,14.289 L27.95,14.289 C28.849,14.289 29.583,13.585 29.637,12.702 C29.695,11.723 28.891,10.908 27.913,10.908 L27.914,10.908 Z"/>
+    </g>
+  </g>
+</svg>

package/apps/client/assets/voice-circle.svg

@@ -0,0 +1,3 @@
+<svg width="44" height="44" viewBox="0 0 44 44" xmlns="http://www.w3.org/2000/svg">
+  <path d="M22,0 C34.15,0 44,9.85 44,22 C44,34.15 34.15,44 22,44 C9.85,44 0,34.15 0,22 C0,9.85 9.85,0 22,0 Z M22,3 C11.507,3 3,11.507 3,22 C3,32.493 11.507,41 22,41 C32.493,41 41,32.493 41,22 C41,11.507 32.493,3 22,3 Z M24.654,8.334 L25.784,9.32 C29.433,12.502 31.568,17.097 31.568,22.034 C31.568,26.932 29.467,31.493 25.87,34.674 L24.746,35.667 L22.759,33.42 L23.883,32.426 C26.843,29.809 28.568,26.063 28.568,22.034 C28.568,17.973 26.814,14.199 23.812,11.58 L22.682,10.594 L24.654,8.334 Z M19.79,13.769 L20.92,14.755 C23.004,16.572 24.224,19.198 24.224,22.018 C24.224,24.815 23.024,27.422 20.969,29.238 L19.845,30.232 L17.858,27.985 L18.982,26.991 C20.399,25.738 21.224,23.946 21.224,22.018 C21.224,20.074 20.385,18.269 18.948,17.016 L17.818,16.03 L19.79,13.769 Z M16.289,19.962 C16.841,19.962 17.289,20.409 17.289,20.962 L17.289,23.038 C17.289,23.591 16.841,24.038 16.289,24.038 L14.212,24.038 C13.66,24.038 13.212,23.591 13.212,23.038 L13.212,20.962 C13.212,20.409 13.66,19.962 14.212,19.962 L16.289,19.962 Z" fill="currentColor"/>
+</svg>