docs(deploy): 部署方案——开发机构建 + 服务器轻构建（Caddy）

按熟悉的工作流调整：构建在开发机完成（四绿验证后的 dist 才是部署物），SFTP 上传 dist/Caddyfile/compose.yaml/Dockerfile 四件到服务器，服务器上 docker build 仅做 COPY（无构建工具链需求，秒级）。单阶段 Dockerfile；.dockerignore 不再排除 dist（部署必需品）且继续排除 .env*；README 部署章节重写为三步流程（本机构建/SFTP/服务器 compose）。compose 文件采用 Compose 规范标准名 compose.yaml（docker-compose.yml 仅为向后兼容保留）。

.dockerignore

@@ -0,0 +1,11 @@
+# 服务器轻构建的上下文:只需 dist + Caddyfile(新部署模式,产物在开发机构建)
+# 注意:dist 是部署必需品,不再排除
+node_modules
+.git
+.eslintcache
+*.tsbuildinfo
+
+# 环境变量文件绝不能进镜像层(真实网关地址在 .env.local 里)
+.env
+.env.local
+.env.*.local

.gitignore

@@ -32,6 +32,11 @@ coverage
 /cypress/videos/
 /cypress/screenshots/
 
+# 环境变量文件绝不能提交(真实网关地址)
+.env
+.env.*
+!.env.example
+
 # Vitest
 __screenshots__/
 

AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md
+
+面向 AI 编码工具（Claude / Cursor / Codex 等）的项目协作说明。项目概述、运行方式、架构说明见 [README.md](./README.md)，本文件只记录 README 没有的协作规范与经验教训。
+
+## 运行时：Bun
+
+- 运行时与包管理器是 **Bun**（依赖锁是 `bun.lock`）。安装依赖用 `bun install`，跑脚本用 `bun run <script>`（如 `bun run dev` / `bun run test`）。
+- **不要引入 npm/pnpm/yarn 的产物**：不提交 `package-lock.json` / `pnpm-lock.yaml`，不建议任何需要 lockfile 迁移的依赖操作。
+
+## 常用验证命令
+
+```bash
+bun run test       # vitest 全量（单元 + 组件 + 集成冒烟）
+bun run type-check # vue-tsc
+bun run lint       # oxlint + eslint
+bun run build      # type-check + vite build
+```
+
+改动完成后按此顺序验证，全绿才算完成。prettier 不在 lint 链里，涉及 `.vue`/`.ts` 文件改动后需另跑 `bunx prettier --write <文件>`。
+
+## 命名规范
+
+- 代码文件名一律 **kebab-case 且语义化完整，宁长勿缩写**：`json-text-view.vue` 而非 `jtv.vue`；变量同理（`endpointList` 优于 `epList`）。
+- 模板中引用组件转大驼峰：`import SideNav from '@/components/side-nav.vue'` → `<SideNav />`。
+- 项目文档用**中文命名**（`bench实施计划.md`）；README.md / AGENTS.md 等约定俗成者除外。
+
+## Vue SFC 书写规范
+
+- **块注释必须写在 `<script setup>` 内部顶部**（import 之前），不能写在 SFC 顶层（块标签之外）——SFC 顶层不是 prettier 认识的注释位置，JSDoc 块会被拍平重排。
+- composable（`useXxx`）必须在 `<script setup>` 顶层调用，不能在事件回调/异步函数内调用（provide/inject 失效）。
+
+## 测试经验（防踩坑）
+
+- **jsdom 下容器高度恒为 0**：涉及视口尺寸的组件测试必须 stub `useElementSize`（见 `json-text-view.spec.ts` 顶部的 `vi.mock`），否则虚拟滚动窗口恒空、断言失效。
+- **断言"实际渲染内容"，不要只断言"结构存在"**。曾发生 script 层重构后模板漏改、结构断言全绿而页面全空的事故。
+- **测试有效性的判据是"能杀死 bug"**：修 bug 后可用 `git stash` 对照验证——旧代码下新测试应当失败。
+- 测试需要 TanStack Query 时要提供 `QueryClient`（挂载 `EndpointPanel` 一类的组件必须包 `VueQueryPlugin`）。
+
+## 架构红线
+
+- **滚动/选区等交互状态放 model 层**（`json-text-view.vue` 的行号锚点），DOM 只是投影。不要把选区状态存在 DOM Selection 里——虚拟滚动跨窗口边界会卸载 DOM，原生选区必丢。
+- **不要往 t-tabs 的 panel 里塞内容**。tabs 采用"纯导航模式"（list 不传 panel，面板外置渲染，`v-show` 切换），面板显隐/布局完全自有。仅存的一条样式钩子（隐藏空 panel 壳）写在 `request-tabs.vue` 样式区，注释里有依赖类名与版本记录。
+- **节流连续高频事件（滚动条拖拽）必须开 trailing**：`useThrottleFn(fn, ms, true)`——默认 false 会丢弃节流窗口内的全部事件（白屏事故的根因）。
+- **rAF/循环 + 外部输入**：输入必须在循环体内每帧重读，闭包捕获只是快照（自动滚动速度漂移事故的根因）。
+
+## 已知边界（不要当 bug 修）
+
+- build 产物 >500kB（TDesign 全量引入），按需引入留作后续优化，见 README「已知边界」。
+- 生产部署无 Vite 代理，网关路径需反向代理；`GATEWAY` 只从环境变量读取，代码不写死默认值。
+- 选区随滚动重建会丢失 DOM 层可见选区（model 高亮保留）——虚拟滚动固有行为，非 bug。

Caddyfile

@@ -0,0 +1,24 @@
+# bench 的 Caddy 配置:静态托管 + 网关反向代理
+#
+# :80 表示监听 80 端口、禁用自动 HTTPS(容器场景由外层决定 TLS;
+# 若将来直接暴露公网域名,把 :80 换成域名,Caddy 会自动签发证书)
+#
+# GATEWAY 由 docker run -e / compose environment 注入(Caddyfile 支持 {$GATEWAY} 环境变量占位)
+# 未注入时 Caddy 启动会因空地址报错——与 vite dev 行为一致:不写死默认值
+
+:80 {
+	# 静态站点:根目录 + SPA fallback(不存在的路径回退 index.html)
+	root * /usr/share/caddy
+	encode gzip
+
+	# 接口代理:与 vite.config.ts 的 dev 代理语义一致,转发到网关
+	@api path /api/* /v1/*
+	handle @api {
+		reverse_proxy {$GATEWAY}
+	}
+
+	handle {
+		try_files {path} /index.html
+		file_server
+	}
+}

Dockerfile

@@ -0,0 +1,6 @@
+# bench 运行镜像:仅把本机构建好的 dist 打进 Caddy(构建在开发机完成,见 README 部署章节)
+# 服务器上 docker build 只做 COPY,秒级完成,不需要任何构建工具链
+FROM caddy:2-alpine
+
+COPY Caddyfile /etc/caddy/Caddyfile
+COPY dist /usr/share/caddy

README.md

@@ -50,10 +50,36 @@ bun run build      # type-check + vite build（dist/）
 
 ## 已知边界
 
-- 生产部署（`bun run build`）无 Vite 代理，需为网关路径配置反向代理
 - `useClipboard` 在非 https 环境（如 http://localhost）自动降级 `execCommand`
 - `/v1/models/:model` 单模型详情接口未纳入（数据源是硬编码静态表，与 `/v1/models` 不一致，无调试价值）
 
+## 部署（开发机构建 + 服务器轻构建运行）
+
+构建在开发机完成（四绿验证后的 dist 才是部署物），服务器只做镜像 COPY + 起容器，
+不需要任何构建工具链。
+
+```bash
+# —— 开发机 ——
+bun run build                        # 得到 dist/（此时已过 test/type-check/lint）
+# SFTP 上传四个部署物到服务器同一目录：
+#   dist/  Caddyfile  compose.yaml  Dockerfile
+#   （.env 不上传，GATEWAY 在服务器上以 .env 或环境变量提供）
+
+# —— 服务器（目录内需有 .env，内容为 GATEWAY=https://…）——
+docker compose up -d --build         # 首次：拉 caddy 镜像 + COPY 产物起容器，秒级
+# 浏览器打开 http://<服务器IP>:8080
+
+# —— 常规更新（开发机）——
+bun run build                        # 重新构建
+# SFTP 覆盖 dist/
+docker compose up -d --build         # 服务器上重新 COPY + 替换容器
+```
+
+- Caddy 承担与 dev 代理相同的职责：静态文件 + `/api`、`/v1` 转发到 `$GATEWAY` + SPA fallback
+- 换网关：改服务器上的 `.env` 后 `docker compose up -d --force-recreate`（无需重新 build）
+- 暴露公网时把 `Caddyfile` 的 `:80` 改为域名，Caddy 自动签发 HTTPS 证书
+- `compose.yaml`（Compose 规范标准文件名）里 `GATEWAY` 为必填（未设置时启动即报错，不会带错误配置运行）
+
 ## 文档
 
 - 交互与技术决策：`docs/bench交互设计文档.md`

compose.yaml

@@ -0,0 +1,21 @@
+# bench 部署编排:服务器上 docker compose up -d 即起
+# 前置:开发机已 bun run build 得到 dist/,并把 dist/ Caddyfile/ compose.yaml/ Dockerfile/
+#      四项经 SFTP 上传到服务器同一目录(见 README 部署章节)
+#
+# 常规更新流程(开发机):
+#   1. bun run build
+#   2. SFTP 覆盖上传 dist/ 目录
+#   3. 服务器上 docker compose up -d --build   # 重新 COPY 产物进镜像并滚动替换容器
+
+services:
+  bench:
+    build:
+      context: .
+    image: new-api-key-bench
+    container_name: bench
+    ports:
+      - "8080:80"
+    environment:
+      # 必填:NewAPI 网关地址(Caddyfile 的 {$GATEWAY} 占位由此注入)
+      GATEWAY: ${GATEWAY:?请在 .env 或环境中设置 GATEWAY,例如 GATEWAY=https://your-gateway.example.com}
+    restart: unless-stopped