@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/skills/hai-build/SKILL.md

@@ -1,319 +1,66 @@
 ---
 name: hai-build
-description: 应用开发入口技能。提供项目架构总览（SSR/SPA/原生 App 多端）、TDD 开发工作流、模块初始化顺序与技能导航。当用户需要了解项目结构、查找正确的技能、或开始新任务时触发。
+description: "构建或排查 hai 应用的源码、静态网站、容器镜像和桌面产物；识别工程架构、依赖与对应构建入口。"
 ---
 
-# hai-build — 应用开发入口
-
-> 本技能是 hai-framework 应用开发的起点。帮助理解项目结构、定位正确的技能、并遵循 **TDD 驱动的标准工作流**。支持 SSR Web、SPA、Android/iOS 原生 App 等多端构建。
-
----
-
-## 适用场景
-
-- 初次接触项目，需要了解整体架构与模块关系
-- 不确定应使用哪个技能来完成任务
-- 需要了解模块初始化顺序与依赖关系
-- 需要执行跨模块操作或全局配置变更
-- 多端构建切换（SSR ↔ SPA ↔ 原生 App）
-
----
-
-## 项目架构
-
-### 技术栈
-
-| 层次     | 技术                           |
-| -------- | ------------------------------ |
-| 框架     | SvelteKit 2 + Svelte 5 (Runes) |
-| 样式     | TailwindCSS 4 + DaisyUI 5      |
-| 语言     | TypeScript 5.7+ (strict)       |
-| 构建     | Vite + tsup                    |
-| 包管理   | pnpm                           |
-| 单元测试 | Vitest                         |
-| E2E 测试 | Playwright                     |
-| 原生 App | Capacitor 7                    |
-| 认证     | Bearer Token（统一）           |
-
-### 多端构建模式
-
-| 模式    | Adapter        | 认证方式              | 部署目标                |
-| ------- | -------------- | --------------------- | ----------------------- |
-| SSR Web | adapter-node   | Bearer Token + Cookie | Node.js 服务器          |
-| SPA     | adapter-static | Bearer Token          | CDN / 静态托管          |
-| Android | adapter-static | Bearer Token          | Capacitor → Android APK |
-| iOS     | adapter-static | Bearer Token          | Capacitor → iOS IPA     |
-
-**Adapter 切换**：
-
-```typescript
-// svelte.config.js — 使用 kit 提供的 createAdapter
-import { createAdapter } from '@h-ai/kit/adapter'
-
-const config = {
-  kit: {
-    adapter: createAdapter(), // 根据 VITE_ADAPTER 环境变量自动选择
-  },
-}
-```
-
-- `VITE_ADAPTER=node`（默认）→ adapter-node（SSR）
-- `VITE_ADAPTER=static` → adapter-static（SPA / 原生 App）
-
-### 目录结构
-
-```
-项目根/
-  config/                         # 模块配置（YAML）
-    _core.yml                     # Core 配置（必须）
-    _db.yml                       # DB 配置（按需）
-    _cache.yml                    # Cache 配置（按需）
-    _iam.yml                      # IAM 配置（按需）
-    _storage.yml                  # Storage 配置（按需）
-    _ai.yml                       # AI 配置（按需）
-  src/
-    app.html                      # HTML 入口
-    app.d.ts                      # 全局类型声明
-    hooks.server.ts               # 服务端 Hook（模块初始化 + 请求管道）
-    lib/
-      api.ts                      # API Client 初始化（SPA / 原生 App 使用）
-      capacitor.ts                # Capacitor 初始化（原生 App）
-      server/
-        init.ts                   # 模块初始化入口（单例，SSR）
-      paraglide/                  # i18n 生成文件（禁止手动修改）
-      components/                 # 应用组件
-    routes/
-      +layout.svelte              # 根布局
-      +page.svelte                # 首页
-      (auth)/                     # 认证相关页面组
-      api/                        # API 端点
-        v1/                       # API v1 版本
-          payment/                # 支付端点（按需）
-  static/                         # 静态资源
-  messages/                       # i18n 翻译文件
-  capacitor.config.ts             # Capacitor 配置（原生 App）
-```
-
-### 模块依赖图
-
-```
-core（基础能力：配置、日志、i18n、HaiResult）
-  ├── crypto（加密：SM2/SM3/SM4）
-  ├── db（数据库：SQLite/PostgreSQL/MySQL）
-  ├── cache（缓存：内存/Redis）
-  ├── storage（存储：本地/S3）
-  ├── ai（AI：LLM/MCP/Agent）
-  ├── iam（身份管理）← 依赖 crypto + db + cache
-  ├── payment（支付）← 依赖 db + crypto
-  ├── kit（SvelteKit 集成）← 依赖 iam + cache + storage + crypto
-  ├── api-client（HTTP 客户端）← 纯浏览器端，依赖 iam/api（类型）
-  ├── capacitor（原生能力）← 纯浏览器端
-  └── ui（UI 组件库）← 依赖 core
-```
-
-### 模块初始化顺序
-
-#### SSR 模式（hooks.server.ts）
-
-在 `src/lib/server/init.ts` 中按依赖顺序初始化：
-
-```typescript
-import { cache } from '@h-ai/cache'
-import { core } from '@h-ai/core'
-import { reldb } from '@h-ai/reldb'
-import { iam } from '@h-ai/iam'
-import { payment } from '@h-ai/payment' // 按需
-
-let initialized = false
-
-export async function initModules() {
-  if (initialized)
-    return
-
-  // 1. Core 必须最先初始化（加载配置、日志、i18n）
-  await core.init()
-
-  // 2. 基础设施层（无相互依赖，可任意顺序）
-  await reldb.init(core.config.get('db'))
-  await cache.init(core.config.get('cache'))
-
-  // 3. 业务层（依赖基础设施）
-  await iam.init({ ...core.config.get('iam'), reldb, cache })
-  // 支付模块（按需）
-  await payment.init({ ...core.config.get('payment'), reldb })
-
-  // 4. 集成层
-  // kit 无需 init，通过 createHandle 配置
-
-  initialized = true
-}
-```
-
-#### SPA / 原生 App 模式（src/lib/api.ts）
-
-```typescript
-import { api } from '@h-ai/api-client'
-
-export async function initApi() {
-  return api.init({
-    baseUrl: import.meta.env.VITE_API_BASE_URL,
-    timeout: 15_000,
-  })
-}
-
-export { api }
-```
-
-#### 原生 App 追加初始化（src/lib/capacitor.ts）
-
-```typescript
-import { capacitor } from '@h-ai/capacitor'
-
-export async function initCapacitor() {
-  await capacitor.init({ statusBar: { style: 'dark' } })
-}
-```
-
-### 配置文件格式
-
-所有模块配置使用 YAML，支持 `${ENV_VAR:default}` 环境变量语法：
-
-```yaml
-# config/_core.yml
-app:
-  name: ${HAI_APP_NAME:my-app}
-  env: ${HAI_ENV:development}
-log:
-  level: ${HAI_LOG_LEVEL:info}
-```
-
----
-
-## 技能导航
-
-根据任务类型选择正确的技能：
-
-### 模块使用（API 与集成）
-
-| 任务                  | 技能             | 触发关键词                                        |
-| --------------------- | ---------------- | ------------------------------------------------- |
-| 配置/日志/i18n/HaiResult | `hai-core`       | core.init, core.logger, core.config, HaiResult       |
-| 数据库操作            | `hai-reldb`      | reldb.init, SQL, CRUD, 事务, 分页, DDL               |
-| 缓存操作              | `hai-cache`      | cache.init, cache.get/set, TTL, Redis             |
-| 文件存储              | `hai-storage`    | storage.init, 上传, 下载, S3, 本地存储            |
-| 加密/签名/哈希        | `hai-crypto`     | crypto.init, SM2, SM3, SM4, 加密, 签名            |
-| 身份认证/授权         | `hai-iam`        | iam.init, 登录, 注册, RBAC, Token, Bearer         |
-| AI/LLM/MCP            | `hai-ai`         | ai.init, LLM, MCP, Agent, 工具调用                |
-| SvelteKit 集成        | `hai-kit`        | kit.createHandle, guard, fromContract, middleware |
-| UI 组件               | `hai-ui`         | 表单, 按钮, 表格, Modal, Toast, 移动端组件        |
-| HTTP 客户端           | `hai-api-client` | api.call, api.get, api.post, Bearer, 拦截器       |
-| 原生 App 能力         | `hai-capacitor`  | capacitor, 相机, 推送, 状态栏, 设备信息           |
-| 支付                  | `hai-payment`    | payment, 微信支付, 支付宝, Stripe, 订单           |
-
-### 开发流程
-
-| 任务                   | 技能             | 触发关键词                             |
-| ---------------------- | ---------------- | -------------------------------------- |
-| 创建页面/组件/API/模型 | `hai-app-create` | 新建页面, 添加组件, API 端点, 数据模型 |
-| 代码审查与规范化       | `hai-app-review` | 审查, review, 规范, 优化               |
-| 编写/补充测试          | `hai-app-tests`  | 测试, test, 单测, 覆盖率, TDD, E2E     |
-
----
-
-## TDD 开发工作流（强制）
-
-> 所有新功能开发必须遵循 TDD：**先写测试 → 确认失败 → 再实现 → 确认通过 → 重构**。
-
-### 完整流程
-
-```
-需求分析 → 设计测试用例 → 编写测试（Red）→ 运行测试确认失败
-    → 编写实现（Green）→ 运行测试确认通过
-    → 重构优化（Refactor）→ 运行质量门禁
-```
-
-### 按阶段使用的技能
-
-| 阶段                | 主要技能         | 说明                                       |
-| ------------------- | ---------------- | ------------------------------------------ |
-| 需求分析 + 测试设计 | `hai-app-tests`  | 拆分测试点，确定单元测试与 E2E 测试        |
-| Red：编写测试       | `hai-app-tests`  | 编写 Vitest 单元测试 + Playwright E2E 测试 |
-| Green：编写实现     | `hai-app-create` | 按照创建规范编写服务/路由/组件             |
-| Refactor：重构审查  | `hai-app-review` | 代码规范审查、分层检查、日志/i18n 合规     |
-
-### 快速指令
-
-```bash
-# Red：运行测试确认全部失败
-pnpm --filter <app-name> test
-pnpm --filter <app-name> test:e2e
-
-# Green：运行测试确认全部通过
-pnpm --filter <app-name> test
-pnpm --filter <app-name> test:e2e
-
-# Refactor：质量门禁
-pnpm typecheck && pnpm lint && pnpm test
-```
-
----
-
-## 统一编码规范
-
-### 强制规则
-
-- **禁止 `any`**：不确定类型用 `unknown`，在边界处做类型缩窄
-- **禁止 `console.log`**：使用 `core.logger`（trace/debug/info/warn/error/fatal）
-- **禁止硬编码密钥**：使用环境变量，新增变量需在 `.env` 中写入占位符
-- **禁止硬编码用户文案**：所有用户可见文本必须使用 i18n key
-- **禁止修改 `src/lib/paraglide`** 生成文件
-
-### HaiResult 模式
-
-所有 hai 模块操作均返回 `HaiResult<T>` 类型：
-
-```typescript
-const result = await reldb.sql.query('SELECT * FROM users')
-if (!result.success) {
-  // result.error: { code, message, details? }
-  core.logger.error('Query failed', { error: result.error })
-  return kit.response.internalError()
-}
-// result.data 可安全使用
-return kit.response.ok(result.data)
-```
-
-### 质量门禁
-
-每次变更后按顺序执行：
-
-```bash
-pnpm typecheck    # TypeScript 类型检查
-pnpm lint         # ESLint 检查
-pnpm test         # Vitest 单元测试
-```
-
----
-
-## 标准工作流
-
-### 变更前：需求分析 + 测试设计
-
-1. 列出将修改的文件路径
-2. 确认哪些类型/接口会变
-3. 搜索确认引用关系（避免遗漏）
-4. **设计测试用例清单**（单元测试 + E2E 测试）
-
-### 变更中：TDD 三步走
-
-1. **Red**：编写单元测试（Vitest）+ E2E 测试（Playwright），运行确认全部失败
-2. **Green**：按技能指引完成功能实现，逐步让测试通过
-3. **Refactor**：审查代码规范、重构优化
-
-### 变更后：验证
-
-1. `pnpm typecheck` 通过
-2. `pnpm lint` 通过
-3. `pnpm test` 通过（单元测试）
-4. `pnpm --filter <app-name> test:e2e` 通过（E2E 测试）
-5. 搜索确认所有引用点已更新
+# hai-build
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 定位 hai 应用架构、模块依赖、初始化顺序、构建模式和对应技能 |
+| 适用场景 | 识别应用架构、跨模块依赖或构建入口 |
+| 输入 | README、package.json、应用类型、现有 config 与目标 |
+| 输出 | 适用技能、最小修改路径和按范围选择的验证命令 |
+| 限制 | 先识别 API workspace、SvelteKit、SPA 或原生 App；不强行转换架构，不给纯函数模块添加生命周期。 |
+
+## 使用路径
+
+- 先读当前 package.json、lockfile 与 README，识别 SvelteKit / API workspace / fullstack / Vite SPA / 原生 App，按实际 scripts 验证。
+- 升级 hai-framework、比较版本差异或同步框架 skills 时，使用 [hai-framework-sync](../hai-framework-sync/SKILL.md) 完成版本发现、差异分析、选择/阻塞处理、迁移与验证。
+- 功能开发先用 [development.md](../hai-app-create/development.md) 把需求匹配到当前版本的框架能力与配置；再读取所选模块 skill 和公开类型。
+- 有生命周期的模块按真实依赖初始化、检查结果并反序清理；core、纯函数和工厂不套用相同生命周期。
+- 构建任务检查当前 engines、适配器、缓存与目标产物，不能照搬框架仓库私有构建命令。
+- 网站地址含目录时按[网站挂载目录](paths.md)区分SvelteKit基址、Vite相对资源与API地址，核对构建制品、反代、权限、健康及增量恢复。
+- 多项门禁按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先收集结果再集中修复；遵守产物依赖与资源隔离，不并行清理/重建同一输出目录，不用旧产物补成通过。
+
+## 构建与部署
+
+- website默认Node SSR；纯展示站点用`hai create <name> --type website --features none`明确不选可选业务模块，Core/Kit/UI与默认部署开发工具保留，fullstack仍保留架构必需模块。compile静态预渲染使用`HAI_BUILD_STATIC=1 PUBLIC_BASE_PATH=/docs-site`，docs-site替换为实际仓库名，各路径段仅ASCII字母、数字、_、.、-，不含末尾/、查询/片段或逃逸；省略/0保持SSR，根站路径留空。HAI_BUILD_STATIC仅用于compile；PUBLIC_BASE_PATH也支持docker网站构建，原生app/desktop拒绝网站目录。静态拒绝已选服务端业务模块、自定义API/actions和未预渲染页面，不放宽生产依赖守卫，不用SPA fallback；唯一默认健康端点不发布。构建不读根.env；static是公开目录，正常图片/字体等原样发布，禁止放私密内容，检测到.env/.env.*或符号链接会停止构建。上传build时include-hidden-files:true保留.nojekyll，验根/深链/刷新/资产与敏感哨兵。
+
+- 创建默认包含开发期部署工具，可用 --no-deploy 关闭。每个镜像使用 images/ 中独立 Dockerfile，Web 配置位于 images/web/，不使用镜像阶段 target 配置。
+- 构建器生成 images/dependencies/ 安装输入；fetch、安装和生产依赖整理共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，并复用依赖层。file: 归档、补丁、workspace 元数据必须进入下载上下文；原生依赖缓存按系统/架构/ABI 区分。基础镜像、中间件及工具指定版本，禁止 latest。
+- 默认容器面向 CPU 运行或远程 AI 服务，Dockerfile 设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=skip`，跳过额外 CUDA/TensorRT 下载；使用宿主机 GPU 时定制镜像和运行参数，不修改本机 npm 或全局 AI/GPU 配置。
+- pnpm run deploy --build 显式串联构建、打包和发布；--bundle-only 只交付完整离线包与跨平台脚本；--services 以服务器成功状态为基线只更新选中服务。完整包自动包含自建中间件镜像，服务器禁止联网拉取。
+- `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target docker` 根据 hai.json.build.images 的 dockerfile 构建并导出 serv/web 镜像（可单独或组合），可用 --images web 只构建前端，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
+- compile 交付源码编译结果，docker 交付镜像归档，desktop 交付 Tauri 系统安装包，app 交付 Capacitor 原生制品；每次选择一个 target。hai.json 的 build.images[].dockerfile 指向独立镜像文件，build.desktop/build.app 声明原生工程目录，deploy 保存整个项目的部署配置；参数和平台前置以当前 CLI 类型与工程 scripts 为准。cap:sync 只同步工程，不能作为已打包或已安装的证据。
+- Podman 的客户端代理通过预定义构建参数传递，覆盖 Windows/macOS 远程引擎的服务端默认值；代理地址必须能从构建容器访问，--no-http-proxy 禁止此传递。不要把代理写成 Dockerfile ENV 或固化进交付镜像。
+- --network 默认沿用引擎网络；只有实际构建网络无法访问依赖/代理时才显式选择网络，pasta 仅适用于 rootless Podman。build 与 run 的主机名解析可能不同，须验证构建网络中的可达性，不默认改成 host 网络。
+- 从运行build的应用根package.json.version读取版本，不能使用CLI/框架版本或服务子包版本代替。根目录清单version=4，非根目录version=5并记录webBasePath；appVersion为应用版本。servContainerPort/webContainerPort仅记录images配置显式填写的端口，部分构建也保留未选镜像端口，未填写时沿用部署默认值。镜像tar名含版本、buildId区分同版本构建，Tauri也接收根版本。不要手改清单或保留无版本的交付归档。
+- 构建不区分 dev/test/prod，不加载部署环境覆盖，不注入运行期凭据；所选镜像清单含 SHA-256，全部成功才更新本机最近构建指针（不是镜像标签）。不要让 compile、Dockerfile 或 Tauri beforeBuildCommand 递归调用自身的原生/镜像构建。
+- 运行产物的反馈标识为 appVersion/buildId/commit：CLI 过滤调用者 HAI_/PUBLIC_/VITE_ 后仅注入本次内部生成的 HAI_BUILD_ID/HAI_BUILD_COMMIT，Docker 使用镜像批次 ID 经 ARG 传入编译。每个目标的运行版本取自己的 manifest，同次 SSR 的 client/server 共用 buildId；没有所属 Git 提交时明确 unknown。模板的三字段 build-metadata.json 与代码内联共用值，验收需与 API/ZIP 的各端证据分别核对。
+- Vite 的 envDir 与 SvelteKit 的 kit.env.dir 是独立加载入口，必须同时阻止构建阶段读取工程根的 .env 文件；开发/预览由 core loader 注入，运行期由 deploy 注入。用临时 .env.local 哨兵值检查输出，避免只过滤进程变量却仍把私有文件固化进产物。
+- 静态客户端通过 runtime-config.js 或原生宿主初始化脚本获取公开地址与元数据；仅投影公开白名单，禁止将完整 process.env、服务配置或密钥序列化到浏览器。预览与容器启动均须验证真实登录，不能依赖构建期 API 地址让 E2E 通过。
+- Fullstack Capacitor App 在 `public/runtime-config.js` 提供公开 API 地址，再编译并同步原生资源；Tauri 从启动进程的 PUBLIC_API_BASE 注入。不能把开发代理的 .env 配置当作已安装原生包的运行配置。
+- `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64` 调用对应工程的 Tauri build。要求在目标系统准备 Rust target、SDK 和打包工具，不假定跨系统编译。原生安装包必须按目标系统实测。
+- deploy 默认消费已有产物，--build 显式先构建，详见 [hai-deploy](../hai-deploy/SKILL.md)。网络不通时 --bundle-only 生成 tar，按说明手工搬运；packaged 不代表部署已运行。
+- 测试临时工程、镜像、容器、辅助进程和数据必须在 finally/teardown 自动清理，失败/取消也清理；日志、截图和报告保留到分析和交付结束再清理，不得提交测试产物或删除用户既有资源。
+- 浏览器测试的数据放入本轮独立临时目录；Windows 等子进程与服务退出后再删除数据库和上传文件，不依赖下一轮测试补清理。
+
+交付角色统一为 `serv`（独立 API 后端）、`web`（静态或 SSR 浏览器站点）、`app`（Android/iOS 手机安装包）、`desktop`（桌面安装包）。Fullstack 容器为 serv + 可选 web，API 为 serv，admin/website/h5/mobile-app 的浏览器镜像为 web；原生 app/desktop 不作为服务器 Compose 服务。`--images` 与 `--services` 使用 serv/web，`--target app` 与 `--target desktop` 生成原生包。API workspace 的服务目录为 `apps/<项目>-serv`。镜像与容器共用工程根 `package.json.name` 的归一化身份（去 scope、转小写、非法字符合并为连字符）；名称缺失或无效时报错，不回退目录名。镜像为 `localhost/hai-<项目>-<角色>:<buildId>`，容器为 `hai-<项目>-<环境>-<角色>`，镜像可跨环境复用。
+
+制品格式4和5都记录primaryService（serv/web），hasWeb表示完整工程是否包含浏览器端；格式5另记录非根目录webBasePath。只有serv + web生成同源API代理；格式1至3须重新构建。CLI的--project-name与SDK的DeployAppOptions.projectName覆盖入口已移除，旧参数明确报错，请在工程根package.json.name维护身份。迁移旧工程先同步build.images、Dockerfile及API workspace的-serv包名与引用，重新安装依赖并重建完整制品。旧部署先备份、核对项目名、卷和受管凭据，再建立完整基线。工具不自动跨项目迁移数据；完整部署仍按Compose规则清理同项目旧服务，不能仅改deploy-target.json.directory完成迁移。网站目录与格式5迁移见[网站挂载目录](paths.md)。
+
+## 按需参考
+
+按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
+
+- 适用场景
+- 项目架构
+- 技能导航
+- 行为开发工作流
+- 统一编码规范
+- 标准工作流
+
+原生 App：hai build --target app --platform android|ios 使用 hai.json.build.app；cap:sync 只同步，不是 APK/IPA。先安装平台与 SDK/JDK 或 macOS/Xcode、配置签名；缺工程/工具链/本次产物必须失败。发布过滤 CAPACITOR_SERVER_URL，并核验同步后的原生配置；默认 package/发行别名走同一验证入口。构建身份统一 128 字符，显式非法 HAI_BUILD_ID/HAI_BUILD_COMMIT 报错且不回显原值。

package/templates/skills/hai-build/paths.md

@@ -0,0 +1,30 @@
+# 网站挂载目录
+
+部署地址含`/yyy/`等目录时，先识别SvelteKit与Vite，再检查资源、路由、API及服务器守卫。配置说明与当前运行截图见[网站构建与部署手册](https://hai-series.github.io/hai-framework/docs/configuration/delivery/)。
+
+## SvelteKit
+
+启用 transport 时，服务端 `crypto.transport.basePath` 和浏览器 `installBrowserTransport(config, { crypto, basePath: base })` 均取 `$app/paths.base`；独立 Kit client 同步 `transport.basePath`。默认空字符串为域名根目录，不在 YAML 另维护一份挂载目录。交换/排除/容量路径仍用完整路径。目录验收须检查带前缀 API 的加密标记和缺协议拒绝，页面、登录成功不能替代协议验证。
+
+- admin、h5和website从构建进程的PUBLIC_BASE_PATH设置kit.paths.base，默认空字符串。根目录保持空，子目录如`/yyy`无末尾斜杠；构建不读取私有dotenv中的这个控制值。
+- 组件链接用`$app/paths`的resolve；认证动作使用带base的api/auth地址。守卫匹配实际URL，protectedPaths/publicPaths/loginUrl都应带base。新模板已接好，旧应用与自定义路由须同步核对。
+- 重新构建后，外部网关保留此前缀交给Node服务。开发、编译和预览使用同一目录值；生产还要满足共享后端、密钥与公开源配置。
+- 实际验证匿名私有API返回401、页面跳转到该目录登录、注册/登录、业务深链刷新、JS/CSS/图标和当前导航标记。
+
+## Vite与前后端分离
+
+- 模板默认base为`./`，运行配置和入口脚本使用相对引用，业务页面使用hash导航。直接挂载根目录静态服务时，外部网关剥离挂载目录，并将无末尾斜杠的入口规范到`/yyy/`。
+- Web及独立mobile浏览器端可通过PUBLIC_BASE_PATH显式固定基址；Vite开发/预览的运行配置插件跟随该base。引入history路由时同时处理basename和服务器回退。
+- API地址独立于网站目录。直接托管Web时核对显式baseUrl、runtime-config.js、构建PUBLIC_API_BASE及当前origin的生效顺序；公开配置不含密钥。SDK托管Fullstack时，同源API由_serv.http.apiPrefix生成，额外网关也要转发此前缀。
+- 原生App/Desktop使用相对资源，原生构建目标不接受网站PUBLIC_BASE_PATH；API仍按设备宿主配置。
+
+## SDK容器交付
+
+- `PUBLIC_BASE_PATH=/yyy`用于compile或docker网站构建；HAI_BUILD_STATIC仍只用于website的compile静态预渲染。
+- 根目录制品沿用格式4，非根目录制品使用格式5并记录webBasePath。使用支持格式5的CLI/Deploy；旧工具拒绝新格式，不能手改编号绕过。
+- SDK生成匹配的Nginx目录、运行配置入口、健康检查和访问URL。外部网关转发到此入口时保留目录，避免再次剥离。
+- 每次完整或部分构建保持同一PUBLIC_BASE_PATH，即使只构建serv。目录变化须全量部署；遗漏或改变目录的增量包会在替换前拒绝。失败恢复使用旧发布的健康路径；容器恢复不撤销业务数据。
+
+## 验收与同步
+
+核对根路径回归、带目录的加载/刷新/认证/权限、公开配置无缓存、API目标与390px布局；确认所有真实前置已成功，区分浏览器、Nginx和服务器恢复证据。修改目录能力时同步构建清单、部署读取方、健康检查、回滚、模板、用例、三语说明和使用截图。