@h-ai/cli 1.0.0-beta.1 → 1.0.0-beta.3

package/templates/skills/bridges/api/AGENTS.md

@@ -11,6 +11,8 @@
 
 ## 行为契约
 
+涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
+
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。

package/templates/skills/bridges/fullstack/AGENTS.md.hbs

@@ -11,6 +11,8 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 ## 行为契约
 
+涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
+
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。

package/templates/skills/bridges/h5/AGENTS.md

@@ -11,6 +11,8 @@
 
 ## 行为契约
 
+涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
+
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。

package/templates/skills/bridges/mobile-app/AGENTS.md

@@ -11,6 +11,8 @@
 
 ## 行为契约
 
+涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
+
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。

package/templates/skills/bridges/website/AGENTS.md

@@ -11,6 +11,8 @@
 
 ## 行为契约
 
+涉及框架结构、配置、核心流程或模块边界变更时，先按 [变更影响与方案确认](.agents/skills/hai-change-plan/SKILL.md) 说明影响并等待用户决定；已确认且未扩大的方案继续执行。
+
 需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
 
 升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。

package/templates/skills/hai-ai/guide.md

@@ -80,16 +80,18 @@ await ai.close()
 
 ## 配置要点
 
+LLM 协议使用 `llm.protocol`、`llm.models[].protocol` 和 `tempModel.protocol`，值为 `chat | responses | anthropic`；环境变量使用 `HAI_AI_LLM_PROTOCOL`、`HAI_AI_LLM_MODELS_0_PROTOCOL` 等。旧 `api` 字段及旧协议变量会报迁移错误，密钥字段 `apiKey` 不变。
+
 ```yaml
 llm:
   apiKey: ''
   baseUrl: https://api.openai.com/v1
   model: gpt-4o-mini
-  api: chat # chat（默认）| responses | anthropic——底层协议，对使用方透明
+  protocol: chat # chat（默认）| responses | anthropic——底层协议，对使用方透明
   timeout: 60000
   tempModelCacheTtl: 600000 # 临时模型客户端缓存 TTL（毫秒，默认 10 分钟）
   models: # 可为单个模型指定协议（responses / anthropic）
-    - {id: claude, model: claude-3-5-sonnet-latest, api: anthropic}
+    - {id: claude, model: claude-3-5-sonnet-latest, protocol: anthropic}
   scenarios:
     chat: fast
     reasoning: strong
@@ -125,7 +127,7 @@ memory:
 | ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 非流式对话    | `ai.llm.chat({ messages })`                                                                                    | OpenAI 兼容 Chat Completion                                                                                                                                  |
 | 流式对话      | `ai.llm.chatStream({ messages })`                                                                              | 返回 `AsyncIterable`                                                                                                                                         |
-| 多协议        | 模型 `api: chat/responses/anthropic`                                                                           | 底层走 Chat Completions / Responses / Anthropic，公共形状不变                                                                                                |
+| 多协议        | 模型 `protocol: chat/responses/anthropic`                                                                           | 底层走 Chat Completions / Responses / Anthropic，公共形状不变                                                                                                |
 | 请求取消      | `ai.llm.chat({ messages, signal })`                                                                            | 传 `AbortSignal`，`abort()` 立即停上游生成                                                                                                                   |
 | 临时模型      | `ai.llm.chat({ messages, tempModel })`                                                                         | 单次请求级临时端点，客户端按 TTL 缓存                                                                                                                        |
 | 工具定义      | `ai.tools.define(...)`                                                                                         | Zod schema 转 JSON Schema；`handler(input, ctx)` 第二参为执行上下文                                                                                          |

package/templates/skills/hai-app-create/SKILL.md

@@ -38,7 +38,7 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 
 界面新建或明显改变信息结构时先用已交付的 hai-ui-design 确定页面模式、状态和组件映射；使用 hai-ui 的当前版本契约实现，以 hai-ui-review 的真实页面检查收尾。窄范围修复直接复用既有设计。界面方案与最终实现的差异需回写适用设计记录。
 
-新增新手引导或帮助说明时读取 [UI 引导指南](../hai-ui/guide.md)，复用 fullstack 默认的共享 guide-store、locale 和稳定 data-guide 锚点。
+带前端的工程新增引导或帮助时，读取本工程 `hai-ui` Skill 中的 `guide.md`，复用 fullstack 的共享 guide-store、locale 与稳定 data-guide 锚点；纯 API 工程不需要 UI 指引。
 
 按任务读取 [reference.md](reference.md) 的对应小节；签名以当前源码或安装版本的公开类型为准，不默认加载全部资料。示例中的业务变量由应用提供。
 

package/templates/skills/hai-app-create/collaboration.md

@@ -12,19 +12,22 @@
 
 ## 修改前与交付前的同步检查
 
+框架增删改涉及数据结构、配置/环境变量、核心流程或模块边界时，先执行[变更影响与方案确认](../hai-change-plan/SKILL.md)，用清楚简短的语言说明改变什么、影响谁、怎样同步与验证，等待用户决定后实施。既有具体确认不重复要求；新发现的重要影响只确认增量。普通业务私有实现不因此升级成框架改造。
+
 框架相关任务先从四个视角提出可检验的要求，再查找差距：维护者需要稳定契约、清楚职责、失败可定位和同步成本可控；框架使用者需要可运行示例、可理解配置、明确环境边界和可恢复的调用流程；生成应用的最终用户需要清楚的信息层级、完整状态反馈、语言一致及键盘/窄屏可用；安全审查员关注服务端身份与资源权限、输入和外部地址边界、密钥与诊断材料保护，以及并发、重试和恢复中的权限绕过或重复副作用。每项问题说明触发条件、实际影响和验证办法，同一根因合并记录；不把四个视角机械扩展为本次范围外的大改造，也不把推测写成已确认漏洞。
 
 按实际影响逐项作出“需同步 / 已同步 / 不适用及原因”的判断，不能机械要求每次全部修改：
 
 | 对象 | 何时需要同步 | 应确认的结果 |
 | --- | --- | --- |
-| 使用文档 | 操作路径、环境前提、公开能力或故障恢复变化 | 更新 docs/usage 或项目既有使用指南；步骤可执行，限制清楚 |
+| 使用文档与网站 | 操作路径、环境前提、公开能力或故障恢复变化 | 更新相关 README、docs/usage 或既有指南；同步 GitHub Pages 内容源、导航与图片，验证构建和链接，不手改生成产物 |
 | 配置与示例 | 配置名、默认值、校验、优先级或安全策略变化 | 核对 Schema 与消费点，区分框架默认、模板默认和建议值；示例能通过当前版本校验 |
 | 截图 | 界面/交互或使用说明中的画面变化 | 当前版本实际操作后截图，记录场景、语言、尺寸；去除凭据与私人数据，不用旧图冒充新结果 |
 | 测试 | 行为、权限、异常、并发或恢复边界变化 | 补最小合适层的行为回归；关键跨层流程保留 E2E，按影响定向运行 |
 | CLI 模板 | 公共组件、配置、初始化或应用规范变化 | 新生成应用继承改进，验证复制后的文件、引用与核心流程；生成应用无框架仓库时不伪造仓库检查命令 |
 | 调用方 | API、类型、错误码或共享默认变化 | 搜索直接及关键间接消费者；同步框架包、示例与模板，说明必要迁移 |
 | README / Skills / AI 入口 | 使用方式或后续工作流程变化 | 共用正文与链接维护，已提供的多语言版本保持一致；不向应用复制仓库私有路径 |
+| 注释与类型说明 | 字段、默认值、约束、调用顺序或错误行为变化 | 同步 JSDoc、源码注释和示例，说明实际契约，不保留旧语义 |
 
 ## 使用文档与证据
 
@@ -34,6 +37,8 @@
 
 使用指南由理解源码和实际操作后人工编写，不用脚本将 Schema/API 表直接生成正文。自动化只做示例、链接、翻译键和截图采集等验证工作。截图解释“做了什么、看到什么变化”，优先展示操作前后和失败恢复，不能堆放无关图片。
 
+安装说明与“最新版”介绍使用 npm 注册表链接、动态徽标、`@latest` 与 `pnpm view <包名>@latest version`，不写死当前框架发布号。需要固定依赖时引导使用查询结果；运行环境的最低依赖版本和历史验收来源按事实记录，不能改写成动态最新。
+
 统一提示的术语、语气和动作名称。面向用户说明发生了什么及下一步，开发定位用错误码和追踪标识连接日志；5xx/未知异常不显示内部细节。业务失败保留完整 HaiError，确需转换为异常时通过 Error.cause 保留来源。审查可见正文、占位符、按钮、校验、空状态、提示和辅助技术标签，不只检查翻译字典的键数；演示页和模板同样适用。
 
 所有警告、错误及即时操作结果统一经 ToastContainer；不新增行内警告框、红色错误段落或页面私有提示浮层。字段保留错误标记、aria-invalid 和读屏关联说明，恢复动作留在原操作区域。默认仅显示可读说明，不显示 traceId；有编号时使用容器内“查看排查信息”图标，展开后显示“问题追踪编号”、复制入口及联系客户支持或开发人员时提供编号的说明。展开、悬停和聚焦期间暂停计时；验证复制失败的手动复制路径、键盘、弹窗和窄屏。中英日文同步，不把内部异常或敏感上下文放入排查面板。

package/templates/skills/hai-app-create/development.md

@@ -12,7 +12,7 @@ README 编辑先读章节，把功能说明与示例合并到对应章节；新
 
 ## 先确认应用与版本
 
-- 新手引导与帮助中心使用 `@h-ai/ui/guide`，按 [UI 引导指南](../hai-ui/guide.md) 接入。fullstack 的共享管理界面已有默认帮助入口；业务内容放共享 guide-store，使用应用 i18n 和稳定 data-guide 锚点，不重复实现浮层。
+- 带前端的工程新增引导与帮助时使用 `@h-ai/ui/guide`，读取随前端交付的 `hai-ui` Skill 中的 `guide.md`；纯 API 工程不需要该 UI 指引。fullstack 共享管理界面已有帮助入口，业务内容放共享 guide-store，使用应用 i18n 和稳定 data-guide 锚点。
 
 - 读取当前 `AGENTS.md`、README、`package.json`、lockfile、初始化入口和已有相似功能；用 `rg` 查实现、引用、测试。保留已有改动，沿用项目分层、命名、ESLint、i18n 与测试入口。
 - 确认架构：SvelteKit 使用 `kit` 和文件路由；API workspace 使用 contract/service；fullstack 使用 contract/serv/shared 与所选前端；Vite SPA/原生端通过 typed API 客户端调用服务。不要把服务端目录、DB、密钥或 Node 初始化复制到浏览器。
@@ -22,7 +22,9 @@ README 编辑先读章节，把功能说明与示例合并到对应章节；新
 
 ### 页面与布局
 
-纯展示官网可用website模板加`--features none`明确空选择，默认模板行为不变；none不能与其他模块/空项混用。静态发布使用`HAI_BUILD_STATIC=1`及公开`PUBLIC_BASE_PATH`（如/hai-framework，无末尾/），先确认没有服务端业务模块/API/actions。它不启用数据库/IAM、不放宽生产守卫，也不赋予静态联系表单发送能力；构建和实际子路径验证按[hai-build](../hai-build/SKILL.md)。
+新建工程统一采用适用的完整模块和示例，服务端包含 AI、向量库、反馈等依赖；客户端仍按类型隔离服务端模块。安装体积相应增加，示例需按实际业务替换。`--template`、`--features`、`--examples/--no-examples` 已删除，`create --yes/-y` 改为 `--defaults`，旧参数明确报错；`deploy --yes` 保持原义。已有工程的模块选择不受影响。
+
+website默认SSR；静态发布须先移除服务端业务依赖、初始化及API/actions。静态构建与实际路径验证按[hai-build](../hai-build/SKILL.md)。
 
 网站挂载到`/yyy/`等目录时，按[网站挂载目录](../hai-build/paths.md)同步资源、链接、认证端点和服务端守卫。SvelteKit在编译时固定base，Vite默认相对资源加hash导航；API基址单独配置。SDK子目录制品使用格式5，健康与增量检查随制品处理，不手工修改旧格式清单来代替重新构建。
 
@@ -68,11 +70,15 @@ YAML 使用 `${HAI_DB_TYPE:sqlite}` 等显式引用，冒号后是未配置时
 
 `prod` 是文件模式名，对应 `HAI_CORE_ENV=production`；环境枚举为 `development | test | production | staging`。SvelteKit adapter-node 产物使用 `node --env-file=.env --env-file=.env.prod --env-file-if-exists=.env.local build/index.js`。文件路径相对进程工作目录，公共文件随项目提交；容器通过部署平台或 `--env-file` 注入目标环境值。浏览器只接收公开白名单，构建产物和镜像不包含 `.env.local`。
 
+Compose `env_file` 的变量在创建容器时固定，改文件后 `restart` 不会更新，应沿用原项目名/文件列表重新创建容器，通常无需重建镜像。请求策略可固定引用只读挂载 YAML，后续改文件并重启服务实例重新读取；运行中不监视文件、不逐请求读盘。完整 `HAI_SERV` / `HAI_KIT` 优先于叶子变量，不叠加覆盖。SDK 交付的 `.env.runtime` 与策略快照不可手改；运维外部文件和 Compose override 必须另行备份、纳入后续发布，SDK 自动回滚不恢复外部文件。
+
 Fullstack 的环境文件在工程根；service 脚本通过 `../../.env*` 加载，Web/App/Desktop 的 Vite 自动 dotenv 加载关闭（`envDir: false`），开发和预览由 `core.config.loadEnvFiles` 从工程根读取，构建不读取部署环境文件。API workspace 的环境文件在 `apps/<name>-serv/`。独立应用在各自根目录加载。静态 Web 通过 `runtime-config.js` 获取公开地址，部署环境覆盖无需重建镜像；原生包在复制静态资源前配置该入口。修改编译进客户端的默认值时仍需重新构建；fullstack 的公开应用元数据由 service `app.info` 返回。
 
+Node后端的当前部署包默认重读发布.env.runtime，修改后restart容器即可；托管连接优先级不变，布局/Node参数与中间件仍需重新部署。长期修改同步回源环境；见[部署指引](../hai-deploy/SKILL.md#后端运行配置重载)。
+
 #### 迁移已有项目
 
-先把原来被忽略的 `.env` 私有值迁入 `.env.local`，再提交公共基础和环境文件。本机文件只保留需要覆盖的值，避免整份复制示例后固定开发环境。旧的 `HAI_AI_LLM_API_KEY` / `HAI_AI_LLM_BASE_URL` 改为 `HAI_AI_LLM_APIKEY` / `HAI_AI_LLM_BASEURL`；音频和图像厂商回退变量同样使用 `APIKEY` 后缀。Reach 和 deploy 凭据按当前 YAML 路径命名，以项目 `.env.example` 为准，同步迁移部署平台变量和本机文件。
+先把原来被忽略的 `.env` 私有值迁入 `.env.local`，再提交公共基础和环境文件。本机文件只保留需要覆盖的值，避免整份复制示例后固定开发环境。旧的 `HAI_AI_LLM_PROTOCOL_KEY` / `HAI_AI_LLM_BASE_URL` 改为 `HAI_AI_LLM_APIKEY` / `HAI_AI_LLM_BASEURL`；音频和图像厂商回退变量同样使用 `APIKEY` 后缀。Reach 和 deploy 凭据按当前 YAML 路径命名，以项目 `.env.example` 为准，同步迁移部署平台变量和本机文件。
 
 原 `HAI_AI_ANTHROPIC_API_KEY` / `HAI_AI_ANTHROPIC_BASE_URL` 不再使用。默认协议为 `anthropic` 时改用标准 LLM 变量；混合模型池中有独立凭据或端点时，将 `apiKey` / `baseUrl` 配置在对应模型项。厂商回退 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 保留，优先级以 AI 模块说明为准。
 
@@ -90,7 +96,7 @@ Fullstack 的环境文件在工程根；service 脚本通过 `../../.env*` 加
 | `HAI_CACHE_TYPE` / `HAI_CACHE_DB`                                 | `memory \| redis`；DB 为整数 0–15；memory 仅单进程使用                                 |
 | `HAI_STORAGE_TYPE`                                                | `local \| s3`；local 要求 root，s3 要求 bucket、region、accessKeyId、secretAccessKey   |
 | `HAI_SERV_SERVER_HOST` / `HAI_SERV_SERVER_PORT`                   | HTTP 主机和整数端口 1–65535；部署平台 HOST/PORT 可覆盖                                 |
-| `HAI_AI_LLM_API` / `HAI_AI_LLM_TEMPERATURE`                       | `chat \| responses \| anthropic`；temperature 为数字 0–2                               |
+| `HAI_AI_LLM_PROTOCOL` / `HAI_AI_LLM_TEMPERATURE`                       | `chat \| responses \| anthropic`；temperature 为数字 0–2                               |
 | `HAI_AI_LLM_APIKEY` / `HAI_AI_LLM_BASEURL` / `HAI_AI_LLM_MODEL`   | 厂商密钥、服务 URL、实际可用模型名；启用时满足厂商要求                                 |
 | `HAI_ADMIN_DEFAULT_PASSWORD`                                      | 首次创建管理员的密码，满足 IAM 密码策略；CLI 为 fullstack 的 `.env.dev/.env.test/.env.prod` 分别生成独立随机值 |
 | `PUBLIC_API_BASE`                                                 | 可公开的 API 地址，不得包含用户名、密码或 token                                        |

package/templates/skills/hai-app-create/reference.md

@@ -145,7 +145,9 @@ export const load: PageServerLoad = async ({ locals }) => {
 
 ## 创建 API 端点
 
-API workspace/fullstack 先检查 [hai-api-contract](../hai-api-contract/SKILL.md) 的内置领域 contract 与 [hai-serv](../hai-serv/SKILL.md) 的 feature procedures；应用私有接口通过现有 contract → procedure → typed client 扩展。身份/权限守卫用 serv route 的 auth/permission/role，业务资源归属在服务层检查；不添加 `+server.ts` 或 kit.validate。
+API workspace/fullstack 读取本工程随模板交付的 `hai-api-contract` 与 `hai-serv` Skills，先检查内置领域 contract 和 feature procedures。应用私有接口通过现有 contract → procedure → typed client 扩展，serv route 使用 auth/permission/role，资源归属在服务层检查，不添加 `+server.ts` 或 kit.validate。
+
+同源 SvelteKit 工程读取其 `hai-kit` Skill，沿用文件路由与既有 guard。各架构只读取实际提供的技能。
 
 ### SvelteKit RESTful 端点模板
 
@@ -337,7 +339,7 @@ core.init() → crypto.init() → reldb.init() → cache.init() → iam.init()
 
 - 保持脚手架 `images/*.Dockerfile`、`.dockerignore` 与 `package.json` 中 `build` / `compile` 命令与 hai.json 的 build/deploy 配置同步。保留 `.gitattributes`，让 `.dockerignore`、Dockerfile 和 POSIX 脚本统一使用 LF，保持跨平台输入一致并确保 Linux 脚本可运行。
 - Podman 多阶段构建保持 `--format docker --jobs=1`；前者保留 `HEALTHCHECK`，后者避免部分 Podman 5.8/Buildah 组合在并行 stage 构建时触发内部 semaphore panic。
-- 先复制 lockfile、workspace 配置与构建器准备的 `images/dependencies/` 安装输入执行 `pnpm fetch --ignore-scripts`，再复制源码并离线安装、构建；fetch、安装和 `pnpm pm deploy` 共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，避免重复下载，兼容新增 workspace、本地归档与补丁。
+- 先复制 lockfile、workspace 配置与构建器准备的 `images/dependencies/` 安装输入执行 `pnpm fetch --ignore-scripts`，再离线安装、复制源码并构建；fetch、安装和 `pnpm pm deploy` 共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，使源码变化复用下载与安装层，兼容新增 workspace、本地归档与补丁。
 - 默认容器面向 CPU 运行或远程 AI 服务，Dockerfile 设置 `ONNXRUNTIME_NODE_INSTALL_CUDA=skip`，跳过额外 CUDA/TensorRT 下载；使用宿主机 GPU 时定制镜像和运行参数，不修改本机 npm 或全局 AI/GPU 配置。
 - SvelteKit 服务使用 Node adapter；纯 Vite 前端使用带 SPA fallback 的静态镜像；fullstack 的 Service 与 Web 分别交付，Service 直接监听且不增加转发进程。
 - Web 的 `PUBLIC_*` 部署配置在容器启动时生成静态运行时配置，不作为 build arg 烘焙，确保同一镜像可跨环境部署。

package/templates/skills/hai-app-review/SKILL.md

@@ -17,6 +17,8 @@ description: "审查 hai 应用的框架复用、安全边界、返回契约、
 
 ## 审查路径
 
+涉及框架结构、配置、核心流程或模块边界的修复，先按 [变更影响与方案确认](../hai-change-plan/SKILL.md) 提案并等待用户决定；普通业务私有实现沿当前授权处理。
+
 发现表达、状态区分与同步检查遵循[沟通与同步维护](../hai-app-create/collaboration.md)。审查范围内核对使用文档、配置示例、截图、测试、模板和调用方是否需要更新。
 
 对代码差异读取 [差异审查](differential.md)：固定 base/head，先核对需求符合性，再按真实风险检查历史约束、直接与关键间接调用方。完整应用审查使用同样的需求追踪与发现复核，说明实际覆盖范围。发现、修复和验收沿 [工作交接契约](../hai-spec-implement/handoff.md) 记录。

package/templates/skills/hai-app-tests/SKILL.md

@@ -17,6 +17,8 @@ description: "为 hai 应用编写或修复 Vitest/Playwright 测试，组织分
 
 ## 使用路径
 
+测试或排错发现需要改变框架结构、配置、核心流程、模块边界时，先按 [变更影响与方案确认](../hai-change-plan/SKILL.md) 说明原因、影响与验证办法，待用户决定后改实现。不能通过修改断言把未确认的契约变化变成既定行为。
+
 测试增删、问题表达及同步检查遵循[沟通与同步维护](../hai-app-create/collaboration.md)。合并或删除用例前核对独有风险覆盖，交付说明新增、删除、调整的原因；界面与文档示例使用当前运行证据。
 
 先复用 [工作交接契约](../hai-spec-implement/handoff.md) 中的验收编号和本轮范围。结果关联提交与未提交差异、命令/操作、依赖与环境、退出码和证据位置；源码/配置/依赖或环境变化后按影响使旧结果失效并复测。测试通过只是相应验收的证据，整体验收仍逐项核对需求。

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

@@ -27,14 +27,14 @@ description: "构建或排查 hai 应用的源码、静态网站、容器镜像
 
 ## 构建与部署
 
-- 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，验根/深链/刷新/资产与敏感哨兵。
+- 新建website包含完整模块与示例，默认Node SSR；静态发布须先移除服务端业务依赖、初始化及API/actions，保留Core/Kit/UI。compile静态预渲染使用`HAI_BUILD_STATIC=1 PUBLIC_BASE_PATH=/docs-site`，docs-site替换为实际仓库名，各路径段仅ASCII字母、数字、_、.、-，无末尾/；省略/0保持SSR，根站路径留空。HAI_BUILD_STATIC仅用于compile，PUBLIC_BASE_PATH也支持image网站构建。静态拒绝服务端业务模块、自定义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。
+- 构建器生成 images/dependencies/ 安装输入；fetch、安装和生产依赖整理共用 pnpm store，安装与生产依赖整理共用 SQLite 驱动缓存，并复用依赖层；依赖安装在源码COPY前，前后端仅复制各自需要的源码。运行镜像去掉应用自身声明、source map和README。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 只同步工程，不能作为已打包或已安装的证据。
+- `pnpm build` 默认仅编译源码（调用 compile）；`pnpm build --target image` 根据 hai.json.build.images 的 dockerfile 构建并导出 serv/web 镜像（可单独或组合），可用 --images web 只构建前端，默认最多两项并行，--concurrency 1可串行，auto 优先可达 Podman、其次 Docker，可用 --runtime 显式指定。
+- compile 交付源码编译结果，image 交付镜像归档，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也接收根版本。不要手改清单或保留无版本的交付归档。
@@ -44,7 +44,7 @@ description: "构建或排查 hai 应用的源码、静态网站、容器镜像
 - 静态客户端通过 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 不代表部署已运行。
+- deploy 默认消费已有产物，--build 显式先构建，详见 [hai-deploy](../hai-deploy/SKILL.md)。网络不通时 --bundle-only 默认生成 tar.gz（显式--output release.tar保留未压缩格式），按说明手工搬运；packaged 不代表部署已运行。
 - 测试临时工程、镜像、容器、辅助进程和数据必须在 finally/teardown 自动清理，失败/取消也清理；日志、截图和报告保留到分析和交付结束再清理，不得提交测试产物或删除用户既有资源。
 - 浏览器测试的数据放入本轮独立临时目录；Windows 等子进程与服务退出后再删除数据库和上传文件，不依赖下一轮测试补清理。
 

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

@@ -20,7 +20,7 @@
 
 ## SDK容器交付
 
-- `PUBLIC_BASE_PATH=/yyy`用于compile或docker网站构建；HAI_BUILD_STATIC仍只用于website的compile静态预渲染。
+- `PUBLIC_BASE_PATH=/yyy`用于compile或image网站构建；HAI_BUILD_STATIC仍只用于website的compile静态预渲染。
 - 根目录制品沿用格式4，非根目录制品使用格式5并记录webBasePath。使用支持格式5的CLI/Deploy；旧工具拒绝新格式，不能手改编号绕过。
 - SDK生成匹配的Nginx目录、运行配置入口、健康检查和访问URL。外部网关转发到此入口时保留目录，避免再次剥离。
 - 每次完整或部分构建保持同一PUBLIC_BASE_PATH，即使只构建serv。目录变化须全量部署；遗漏或改变目录的增量包会在替换前拒绝。失败恢复使用旧发布的健康路径；容器恢复不撤销业务数据。

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

@@ -46,7 +46,7 @@ pnpm 专属配置放在 `pnpm-workspace.yaml`，`.npmrc` 仅用于注册表与
 
 ### SvelteKit Adapter 模式
 
-CLI website模板默认Node SSR。纯展示站点通过`--features none`创建，在compile时使用`HAI_BUILD_STATIC=1`与可选`PUBLIC_BASE_PATH`切换完整静态预渲染，边界见本skill的静态网站说明；该模板没有使用下方VITE_ADAPTER工厂。静态产物用preview本机检查，上传build到Pages/CDN；生成的start/Docker配置属于普通SSR模式，不能用于运行静态HTML。切回SSR只需清除静态开关并重建，PUBLIC_BASE_PATH仍可按实际网站目录用于SSR或Docker；SvelteKit/Vite差异、制品格式和健康检查见[网站挂载目录](paths.md)。
+CLI website模板默认Node SSR。新建工程包含完整模块和示例，静态发布须先移除服务端业务依赖、初始化和API/actions；在compile时使用`HAI_BUILD_STATIC=1`与可选`PUBLIC_BASE_PATH`切换完整静态预渲染，边界见本skill的静态网站说明；该模板没有使用下方VITE_ADAPTER工厂。静态产物用preview本机检查，上传build到Pages/CDN；生成的start/Docker配置属于普通SSR模式，不能用于运行静态HTML。切回SSR只需清除静态开关并重建，PUBLIC_BASE_PATH仍可按实际网站目录用于SSR或Docker；SvelteKit/Vite差异、制品格式和健康检查见[网站挂载目录](paths.md)。
 
 仅在项目实际使用 SvelteKit 和 `@h-ai/kit/adapter` 时使用；Vite SPA 不配置 SvelteKit adapter，fullstack 各前端按自身 scripts 构建。
 

package/templates/skills/hai-change-plan/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: hai-change-plan
+description: "框架增删改涉及数据结构、配置、核心流程或模块边界时，先说明方案与影响，等待用户决定后实施。"
+---
+
+# 变更影响与方案确认
+
+## 能力契约
+
+| 项目 | 契约 |
+| --- | --- |
+| 能力 | 将框架变更整理成维护者看得懂、能作决定的方案，并跟踪同步与验证 |
+| 适用场景 | 新增、修改、删除框架功能，或修复中发现需要改变结构、配置、核心流程、模块边界 |
+| 输入 | 用户目标、当前实现与调用方、现有配置和文档、已确认方案及授权 |
+| 输出 | 简明方案、具体影响、用户决定、同步清单和验证结果 |
+| 限制 | 未确认的重要变更先停在方案；普通业务私有实现不因此扩大成框架改造，已确认且未扩大的方案不重复确认 |
+
+## 何时先提方案
+
+发现以下任一实际变化，在修改对应实现、配置或模板之前说明方案，**等待用户明确同意推进**：
+
+- `type`、`interface`、Schema 等结构的字段、形状或语义改变，包括新增、删除及会改变执行方式的内部结构。
+- 模块配置或环境变量的名称、位置、默认值、可选/必填、校验、优先级、安全含义改变。
+- 初始化/关闭、请求处理、认证授权、数据读写、并发重试、部署/恢复等核心流程改变。
+- 模块职责、依赖关系、公开入口、调用方式或跨模块返回值/错误契约改变。
+
+先查源码、调用方和运行证据，给出足以决定的具体方案；不要只说“重构一下”“优化架构”。只读分析、现状复现及不改变上述边界的准备工作可以继续，不能先落地再要求追认。已有“修复”“按最佳方案”等一般授权，不代替尚未说明的重要方案；用户已明确指定并同意的具体方案无需重问。执行中出现新的重要影响，只确认新增部分。
+
+纯格式、注释纠错、翻译修正，或不改变上述结构与边界的内部修复，按已有授权继续；先简述实际影响即可。拿不准时说明具体不确定项，不为假设风险引入审批。
+
+## 怎样说明
+
+先用一两句话说明结论，再按实际复杂度交代：
+
+1. **为什么改、改成什么**：当前场景有什么问题，使用前后有什么变化。
+2. **影响谁**：涉及哪些模块、应用、CLI 模板和调用方；旧配置、数据、部署是否需要调整。
+3. **如何同步与验证**：需要更新哪些文档、注释、示例与测试；如何确认生效，失败如何恢复。
+4. **请用户决定**：给出推荐方案；确有取舍时列少量可行选项，并说明代价。
+
+技术名词和必要路径用于支持判断，避免堆文件清单与过程日志。简单变化一小段即可，复杂变化再分层。区分已确认事实、待验证假设、拟实施及已完成；明确哪些部分尚未获准，不把等待写成完成。
+
+## 确认后成套维护
+
+在当前任务记录中保存决定和影响范围，不额外创建重复台账。按[沟通与同步维护](../hai-app-create/collaboration.md)逐项核对相关 README（已有中英日版同步）、环境变量与模块配置项、`docs/` 使用说明、GitHub Pages 的内容源/导航/图片、注释与类型说明、调用方、测试和 CLI 模板。每项注明已同步，或不适用及原因。
+
+GitHub Pages 由文档源构建时修改源文件，不手改生成产物；配置示例按真实默认值与覆盖顺序核对，界面截图来自当前实际操作。按受影响范围验证，报告实际执行、复用与未验证边界。若实现与获准方案不同，先说明差异并重新确认新增影响。

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

@@ -41,14 +41,26 @@ description: "构建并发布或交付已有镜像：完整离线包、按服务
 
 成功后手工回退使用**当前 CLI**、旧应用 build 制品和匹配配置，省略 `--build`、`--services` 生成新全量 ID；离线也须重新打包，不能运行旧 bundle 或旧工具绕过账本。旧制品通常只保留 serv/web 镜像，中间件仍按当前 CLI 固定版本规划，不承诺精确回退全部中间件版本、DDL 或业务数据。确认主版本、Schema、拓扑和数据兼容并准备备份，再发布和验证。
 
+## 可选 HTTPS
+
+所有容器模板共用deploy.provider.expose.https，省略时HTTP。files指定domain、certificateFile、privateKeyFile（相对工程根），校验域名/期限/密钥并复制到私有包。letsencrypt指定domain、email、acceptTerms:true，HTTP hostPort必须80，公网DNS、80入站及CA出站须可达。固定版本官方Certbot申请并每12小时检查续期，Nginx自动重载。仅单域名HTTP-01，无DNS/通配符。HTTPS默认443、redirectHttp默认true；--yes复用配置。启停或改模式/域名/端口/本地证书需全量。状态在服务器https/acme及按域名隔离的https/certificates目录，需备份；续期失败保留旧证书并须及时处理，隔离目标用已有证书。打包/plan不申请证书。
+
+默认.tar.gz，显式--output release.tar为未压缩，README仅外层。镜像从解包目录导入，release只留配置/恢复状态；成功后清理本次incoming，失败保留诊断。中间件归档按镜像内容ID缓存且复用前验摘要。
+
+## 后端运行配置重载
+
+Node 后端（Serv / SvelteKit SSR）默认在每次启动时重读发布目录的 `.env.runtime`，修改后 `docker restart <容器名>` 或 `podman restart <容器名>` 即可，无需重建镜像或额外 override。旧部署先用新版 CLI 发布一次。删除的字段不会从旧 Compose 注入中复活；服务器托管连接的 `middleware.env` 保持原有更高优先级，私有代理标记和 Node 启动参数仍由部署装配管理。静态 Web、中间件、端口/挂载和 Nginx 限额不在该重载范围。手工修改需备份；下一次后端发布会从工程环境重新生成，需要长期保留的配置同步回源环境。
+
+运行文件在后端实际挂载的releases/<后端发布ID>/.env.runtime；仅更新Web/中间件后current可能指向新记录，不能据此猜测后端文件，按容器Mounts中/run/hai/.env.runtime的Source确认。只读文件挂载，上级目录0700，容器非root可读，宿主所有者可修改。dotenv字面解析不执行shell；双引号支持JSON转义。单文件≤1MiB，缺失/不可读/超限在应用导入前失败。父HAI_SERV/HAI_KIT仍优先于叶字段。重启后验健康与配置影响的业务，失败恢复文件再重启。
+
 ## CLI
 
 ```sh
 pnpm run deploy --env prod --build
-pnpm build --target docker
+pnpm build --target image
 pnpm run deploy --env prod --artifact-dir .hai/build/docker/<buildId>
 pnpm run deploy --env prod --bundle-only
-pnpm build --target docker --images web
+pnpm build --target image --images web
 pnpm run deploy --env prod --services web
 ```
 
@@ -60,7 +72,7 @@ pnpm run deploy --env prod --services web
 
 ## 请求访问策略
 
-请求策略的文件快照、只读挂载、环境覆盖、入口代理信任和增量保留见[请求访问控制](../hai-core/request-access.md#部署与公共边界)。策略更新要重新交付，恢复使用原成功发布文件，不把新文件覆盖到旧发布目录。
+Serv/SvelteKit 后端的策略快照、只读挂载、环境覆盖、代理信任和增量保留见[请求访问配置手册](https://hai-series.github.io/hai-framework/docs/configuration/request-access/)，也可读取工程交付的 `hai-core/request-access.md`；纯客户端由实际后端管理这些设置。默认快照模式通过新包更新，恢复使用原成功发布文件，不覆盖旧发布目录。需要运维文件重启加载时，先按变更方案确认流程说明启动方式和优先级变化；独立外部文件需另行备份，SDK 回滚不恢复它。
 
 ## 自建对象存储直连
 
@@ -84,7 +96,7 @@ Linux 预备 Docker/Podman、支持 --pull never 的 Compose（Docker Compose v2
 
 按 [分轮验证与集中修复](../hai-app-tests/validation.md) 收集适用的 typecheck、lint、build、test、scaffold gates 和 test:deploy-gates，汇总后集中修复、再验证。实际验证无 registry 网络的首次部署、登录刷新、同版本重发、只更新 Web/API、停止/down 后增量恢复、缺密码隐藏输入、上传进度、损坏归档、缺基线、健康失败与恢复。Windows/Linux/macOS 上传入口分别执行验收；原生安装包在对应 OS 验证。测试临时工程、容器、镜像、数据和进程在 finally/teardown 清理，只清理测试拥有的资源；日志、截图和报告保留到分析和交付结束再清理。
 
-部署前可 hai deploy --env prod --plan，只读校验真实制品和执行范围，显示项目/环境、版本/构建、配置文件及键名、保留范围、基线要求和恢复目录；不构建、不创建凭据、不连接或改变目标。远端 current 未读取标 not-inspected；不得把计划或本地打包当真实基线成功。数据库与业务数据不随 Compose 恢复回退。
+部署前可 hai deploy --env prod --plan，只读校验真实制品和执行范围，显示工程根root、服务源码/配置目录serviceDir、项目/环境、版本/构建、配置文件及键名、保留范围、基线要求和恢复目录；不构建、不创建凭据、不连接或改变目标。远端 current 未读取标 not-inspected；不得把计划或本地打包当真实基线成功。数据库与业务数据不随 Compose 恢复回退。
 
 需要核对目标真实基线时加 --inspect-remote（必须配合 --plan），仅 SSH 读取 current/成功发布目录，按 verified/missing/unavailable 与真实发布 ID 报告，不写目标；不能把未检查当作成功。
 

package/templates/skills/hai-deploy/middleware.md

@@ -4,9 +4,9 @@
 
 ## 环境先行
 
-自建 S3 还要区分内部 endpoint 和浏览器 publicEndpoint；后者是 HTTP(S) origin，无默认、不含桶或网站目录。全栈 Web Nginx 或 SSR/API gateway 将桶路径直接转至 storage，存储端口与控制台不直接发布。外层入口保持 Host/URI/query 并转发桶路径，精确 CORS 在实际 S3 设置。增加网关或改变自建访问配置需全量基线，应用增量仅复用原配置；外部 S3 不生成本地路由，local 不公开目录。操作与验证见 [Storage skill](../hai-storage/SKILL.md)。
+自建 S3 还要区分内部 endpoint 和浏览器 publicEndpoint；后者是 HTTP(S) origin 或带代理目录的入口，无默认且不含桶名。全栈 Web Nginx 或 SSR/API gateway 将桶路径直接转至 storage，存储端口与控制台不直接发布。外层入口保持 Host/URI/query，仅生成网关移除代理目录，精确 CORS 在实际 S3 设置。增加网关或改变自建访问配置需全量基线，应用增量仅复用原配置；外部 S3 不生成本地路由，local 不公开目录。操作与验证见 [Storage skill](../hai-storage/SKILL.md)。
 
-默认部署名取工程根（最近的 `hai.json` 或锁文件所在目录）的 `package.json.name`，缺失时报错，再附加显式环境后缀。例如 fullstack 工程 `hai-delivery` 扫描 `packages/hai-delivery-serv`，`--env test` 生成 `/opt/hai/apps/hai-delivery-test` 和 `bundle-hai-delivery-test-<部署ID>-<版本>.tar`。远端目录、交付包、Compose 项目、API/Web/中间件容器、数据卷、服务器凭据状态及增量基线统一使用该名称；不会按字符串删除真实项目名中的 `-serv`。
+默认部署名取工程根（最近的 `hai.json` 或锁文件所在目录）的 `package.json.name`，缺失时报错，再附加显式环境后缀。例如 fullstack 工程 `hai-delivery` 扫描 `packages/hai-delivery-serv`，`--env test` 生成 `/opt/hai/apps/hai-delivery-test` 和 `bundle-hai-delivery-test-<部署ID>-<版本>.tar.gz`。远端目录、交付包、Compose 项目、API/Web/中间件容器、数据卷、服务器凭据状态及增量基线统一使用该名称；不会按字符串删除真实项目名中的 `-serv`。
 
 资源身份和制品格式沿用[构建技能](../hai-build/SKILL.md)及[网站挂载目录](../hai-build/paths.md)：根目录格式4，非根目录格式5，两者都有primaryService/hasWeb；webBasePath仅格式5。旧工程同步镜像角色、Dockerfile、-serv包名与引用后重建，不手改清单。旧部署先核对项目名、卷和受管凭据，再建立完整基线；工具不跨项目迁移数据，改target目录不能完成迁移。
 
@@ -35,6 +35,8 @@ Podman 部署会主动执行容器已有的 healthcheck 并重新核对状态，
 
 ## 识别与逐项选择
 
+默认和自定义模式均从同后端的有效配置继续，不能按表单重建对象而丢掉未展示项。自建/云开通保留连接池、操作日志、公开端点/前缀、Redis 重试、向量检索、SMTP 发件人及 LDAP 属性映射，仅由实际服务定稿地址与认证；旧 URL、TLS/集群选择器不能覆盖新服务。切换后端清除不兼容字段。若旧向导已写出缺字段父 JSON，先从原配置/备份恢复最高优先级 `HAI_STORAGE` 的 `publicEndpoint` 等字段，再用修复版重建部署包；父 JSON 仍优先于 YAML 和叶变量，不自动猜测丢失值。
+
 框架 `HAI_*` 连接配置与镜像原生变量分开：PostgreSQL/MySQL/RustFS/MinIO/LDAP 的原生键必须按镜像契约命名，只写私有 `middleware-runtime.env`、只让中间件加载。不得改成镜像不识别的 HAI 前缀，也不得写回工程 `.env.<mode>` / 私有覆盖或注入应用 `.env.runtime`。应用的增量覆盖文件 `middleware.env` 只含 `HAI_*`。旧工程原生字段不自动删除，新应用环境忽略框架曾生成的已知原生键；不要批量过滤其他业务变量。
 
 数据库连接保存前复用所选后端的公开配置 Schema；MySQL `ssl` 仅 `false` 或严格对象，`{}` 默认验证证书链和 DNS 身份，`ca/cert/key` 为 PEM 内容且 `cert/key` 必须成对；私钥仅进入私有环境。PostgreSQL 保留其布尔值/字符串模式/对象契约。CLI 内联 `@h-ai/reldb/schemas` 与 Zod，无需为配置校验给目标应用额外安装数据库包或驱动；部署本身仍需已安装的 `@h-ai/deploy`，实际运行应用仍需其数据库依赖。

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

@@ -72,7 +72,7 @@ Web 不导入原生插件。原生入口分别为 @h-ai/feedback/tauri 与 /capa
 
 - 已安装包的 README 和公开 /client、/bundle、api-contract/feedback、serv/features/feedback 类型。
 - 数据库、对象存储和通知分别读取 [hai-reldb](../hai-reldb/SKILL.md)、[hai-storage](../hai-storage/SKILL.md)、[hai-reach](../hai-reach/SKILL.md)。
-- UI 复用 [hai-ui](../hai-ui/SKILL.md)，验证遵循 [分轮流程](../hai-app-tests/validation.md)。
+- 带前端的工程按其 `hai-ui` Skill 复用界面组件；纯 API 只接入服务端能力。验证遵循[分轮流程](../hai-app-tests/validation.md)。
 
 反馈交互：当前截图优先；FeedbackModal.oncapture 连接 captureScreenshot(id?)，选择时隐藏弹窗，允许换页后补图/替换并保留输入。FeedbackForm.evidence 展开实际脱敏内容，不能把全部事件数量称作日志。onfileschange 接入后支持用户主动无声短录屏（60秒/5 MiB），视频不自动遮挡，必须支持预览/删除；停止共享、取消、超时和销毁释放流。WebM/MP4 的私有读授权、容器字节/checksum 校验、上传和离线查看须一并验证。
 

package/templates/skills/hai-pr-review/SKILL.md

@@ -17,6 +17,8 @@ description: "审查 PR、提交或分支的实际差异、调用影响、需求
 
 ## 审查路径
 
+框架重要变更按 [变更影响与方案确认](../hai-change-plan/SKILL.md) 核对方案、用户决定与实际差异。缺少确认时说明具体缺口；新增修复影响先提方案，不把已有一般修复授权当成所有结构/流程改动的确认。
+
 按[沟通与同步维护](../hai-app-create/collaboration.md)核对使用文档、配置示例、截图、测试、模板及调用方，结论区分已确认问题与待验证事项。
 
 1. 读取仓库入口和 PR/任务目标，确认比较对象。按 [差异审查](../hai-app-review/differential.md) 固定 base/head、列全文件与重命名，说明 staged/unstaged 和截断限制。

package/templates/skills/hai-serv/reference.md

@@ -18,7 +18,7 @@
 - 使用 Node listener，或在满足包 Node 依赖的宿主/测试中注入标准 fetch handler
 - 自定义 `ServContext`（注入 session、tenant 等请求级数据）
 - 生成 OpenAPI 3.1 文档供外部工具消费
-- 通过 `config/_serv.yml` 管理 API 前缀、OpenAPI、docs、health、rpc 等 HTTP 挂载配置
+- 通过 `config/_serv.yml` 管理 API 前缀、OpenAPI、docs、health 等 HTTP 挂载配置
 - 通过 `serv.createRuntimeSecurityPolicy(...)` 对生产 CORS Origin、原生 WebView Origin、Secure Cookie 与 API 文档暴露执行 fail-closed 策略
 - 启用传输加密：`serv.createApp({ transport: { crypto, serverKeyRing, keyStore } })`
 - 高级场景通过 `createApp({ middlewares })` 自定义 HTTP middleware，通过 `createContext` 注入请求级业务字段
@@ -276,7 +276,6 @@ http:
   health:
     path: /health
     readyPath: /ready
-  rpc: false
 
 transport:
   keyExchangePath: /_hai/key-exchange
@@ -483,7 +482,7 @@ const app = serv.createApp({
 })
 ```
 
-执行顺序为：`securityHeaders` → 内置 CORS 响应包装/握手和预检策略 → `transport`（若启用）/请求策略 → 普通 `middlewares` → health/refresh-cookie/OpenAPI/RPC/docs/oRPC routes。
+执行顺序为：`securityHeaders` → 内置 CORS 响应包装/握手和预检策略 → `transport`（若启用）/请求策略 → 普通 `middlewares` → health/refresh-cookie/OpenAPI/docs/oRPC routes。
 
 - 普通 `middlewares` 在解密和策略之后执行，提前响应仍受访问策略和响应加密约束。二进制端点显式加入 transport.excludePaths；内置 CORS 预检和密钥交换也执行策略。
 - 公开只读文件优先使用 `serv.storageAssets(...)`；应用仍须显式提供 key/MIME 白名单、缓存与跨域策略，框架不内置头像等业务概念。
@@ -549,7 +548,7 @@ HTTP 审计、限流、CORS、租户头校验等跨 route 能力继续放在
 | oRPC contract 输入 schema 校验失败（handler 之前） | 400       | 本地化失败体，`error.httpStatus=400` 与字段错误                           |
 | handler 内 `serv.validateInputOrFail(...)` 失败    | 200       | 失败 HaiResult，`error.httpStatus=400` 与字段错误                         |
 
-HTTP middleware、自定义 Response、refresh-cookie、OpenAPI/RPC 入口权限和 transport 协议错误分别按自身响应契约处理，可返回真实 HTTP 4xx/5xx。`@h-ai/api-client` 在真实 HTTP 401 或 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`）后自动刷新，成功后只重试一次；内置登录、注册和配置的刷新路径除外，403/500 不刷新。启用 transport 时刷新和重试复用加密链路，不能手写明文刷新请求。
+HTTP middleware、自定义 Response、refresh-cookie、OpenAPI 入口权限和 transport 协议错误分别按自身响应契约处理，可返回真实 HTTP 4xx/5xx。`@h-ai/api-client` 在真实 HTTP 401 或 HTTP 200 的有效失败 HaiResult（`success=false`、字符串 `error.code/message`、`error.httpStatus=401`）后自动刷新，成功后只重试一次；内置登录、注册和配置的刷新路径除外，403/500 不刷新。启用 transport 时刷新和重试复用加密链路，不能手写明文刷新请求。
 
 SvelteKit 的 `kit.response.fromError` 根据 `error.httpStatus` 生成 HTTP Response；`kit.response.fromResult` 使用显式错误码映射，未命中默认 400。这些响应转换规则不能套用到 serv 普通 procedure。
 
@@ -584,7 +583,7 @@ const procedures = serv
 
 ### `serv.parseRequestContext` — 默认 Context 解析器
 
-默认忽略转发头，缺少运行时对端时 IP 为 undefined。XFF 从右向左停在首个不可信地址，忽略左侧；可信链无效/过长时保留 IP 未知，不能回退为代理身份。Fetch 使用 `app.fetch(request, { remoteAddress: platformPeerAddress })`，对端必须来自可信平台 API。自定义 context 传递完整 input，保留已解析的 ip；内部 RPC 使用连接对端，转发头不能放宽来源限制。
+默认忽略转发头，缺少运行时对端时 IP 为 undefined。XFF 从右向左停在首个不可信地址，忽略左侧；可信链无效/过长时保留 IP 未知，不能回退为代理身份。Fetch 使用 `app.fetch(request, { remoteAddress: platformPeerAddress })`，对端必须来自可信平台 API。自定义 context 传递完整 input，保留已解析的 ip。
 
 从 HTTP 请求头自动解析：
 
@@ -615,8 +614,7 @@ const spec = await serv.generateSpec(contract, {
 | `apiPrefix` | `'/api/v1'`                                | oRPC OpenAPI handler 挂载前缀                                                                          |
 | `health`    | `{ path: '/health', readyPath: '/ready' }` | 健康与就绪检查端点                                                                                     |
 | `openapi`   | `false`                                    | OpenAPI JSON endpoint，显式开启                                                                        |
-| `docs`      | `false`                                    | Scalar 文档页，显式开启；启用后自动挂载 `/_hai/scalar.js` 本地脚本路由                                 |
-| `rpc`       | `false`                                    | 内部 RPC endpoint，显式开启；`loopback` / `private-network` 基于真实连接 IP，网关场景用 `gateway-only` |
+| `docs`      | `false`                                    | Scalar 文档页，显式开启；在文档目录下挂载 `_hai/scalar.js`，页面使用相对脚本和 spec 地址；认证仍在后端执行 |
 | `transport` | `undefined`                                | 顶层配置；启用后默认挂载 `{apiPrefix}/_hai/key-exchange`                                               |
 
 ```ts
@@ -627,7 +625,6 @@ const http: ServHttpConfigInput = {
   openapi: { path: '/openapi.json' },
   docs: { path: '/docs' },
   health: { path: '/health', readyPath: '/ready' },
-  rpc: false,
 }
 ```
 

package/templates/skills/hai-spec-implement/SKILL.md

@@ -17,6 +17,8 @@ description: "从需求或设计文档规划、执行、返修 hai 应用，或
 
 ## 使用路径
 
+涉及框架结构、配置、核心流程或模块边界的计划与返修，先按 [变更影响与方案确认](../hai-change-plan/SKILL.md) 获取具体决定，再实施对应部分。已有确认且范围未扩大时继续；文档中的宽泛目标不等于具体架构方案已获确认。
+
 先按 [工作交接契约](handoff.md) 选择本次路径，复用既有需求和决策，传递同一组验收与证据。skills 明显变动后的行为回放见 [evaluation.md](evaluation.md)，结构门禁与实际决策分别验证。
 
 先区分本次请求是 **规划 / 执行 / 返修 / 文档变更实施**。仅要求分析或列清单时停在规划；要求按文档生成或“已修改文档，请更新实现”时，在已授权范围内完成规划并依次实施，无需每个任务重复确认。指定任务只执行该任务，依赖未完成时说明具体阻塞，不自行扩展执行范围。普通小改动仍使用 [hai-app-create](../hai-app-create/SKILL.md)。

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

@@ -18,12 +18,12 @@ description: "实现本地/S3 文件与目录操作、流式读写、checksum
 ## 使用路径
 
 1. Node 端配置 Local/S3，校验并检查 init；MinIO/RustFS 使用 s3 类型。S3 `createBucket` 默认 false，需自动建桶时设 true（YAML 用 `${HAI_STORAGE_CREATEBUCKET:false}`）；初始化只在 HeadBucket 明确 404 时创建，权限/网络/建桶失败会阻止就绪。默认自建 S3 部署通过环境启用此项。
-2. 从 file/dir/presign 选择操作，检查 HaiResult。流与 checksum 按真实签名处理，checksum 在 Node 无需 init。S3 内部 endpoint 与浏览器 publicEndpoint 分开：publicEndpoint 无默认，缺省仍用 endpoint 签名；仅 HTTP(S) origin，不含桶、网站目录、凭据或查询。publicUrl 仅用于公开资源 URL。签名后不能改 Host/URI/query，GET 签名不能用于 HEAD；跨源 CORS 在实际 S3 配置。
+2. 从 file/dir/presign 选择操作，检查 HaiResult。流与 checksum 按真实签名处理，checksum 在 Node 无需 init。S3 内部 endpoint 与浏览器 publicEndpoint 分开：publicEndpoint 无默认，缺省仍用 endpoint；可带 /delivery/files 等安全代理目录，不含桶、凭据或查询。含目录时外部签名用桶路径，返回 URL 已加前缀，代理去前缀后须保留原始 S3 URI/Host/query；调用方不能自行改签名地址。publicUrl 仅拼接公开资源，GET 签名不能用于 HEAD；跨源 CORS 在实际 S3 配置。
 3. 客户端经受保护 API 或预签名 URL，服务端校验路径、内容、大小及资源权限；putUrl 不强制 maxSize。
    进度上传使用原生 XHR；预取消不发送，取消/错误一次结算并清理监听，完成后取消不影响旧请求。取消不回滚远端对象，先核对状态再授权删除。
 4. 不覆盖上传使用 ifNoneMatch；冲突/checksum 失败不能伪装成功。验证取消、流错误和文件清理，最后 close。
 5. 批量删除核对逐项进度，S3 每批最多 1000 项；HTTP 200 不能代替成功判断。unknown 结果先核对业务状态，避免重删并发新对象；dir.delete 不保证隔离并发写入或清除 S3 历史版本。
-6. 自建 Compose 的桶路径由 Web Nginx 或 SSR/API gateway 直达 storage，下载/Range 不经过 Serv，存储端口和控制台不直接公开。先配置真实 publicEndpoint；新增网关、变更桶/对外访问配置需全量基线，应用增量及回滚保持原配置。外部 S3 不生成本地路由，Local 不开放目录。验证实际大文件、Range、过期/篡改/匿名拒绝和增量代理 DNS 刷新；签名 URL 不进入日志或截图。
+6. 自建 Compose 的桶路径由 Web Nginx 或 SSR/API gateway 直达 storage，下载/Range 不经过 Serv，存储端口和控制台不公开。publicEndpoint 可含入口前缀，Nginx 用原始 request_uri 去前缀且保留编码、Host、签名查询，外层代理不能再剥离；入口可在网站目录内，拒绝 API/资源/健康冲突。新增网关、变更桶/公开地址需全量基线，增量及回滚保持原配置。外部 S3 不生成本地路由，Local 不开放目录。验证大文件、Range、过期/篡改/匿名拒绝、根/前缀路径和增量代理 DNS 刷新；签名 URL 不进入日志或截图。
 7. 同源对象可能包含不可信 HTML；默认代理返回 CSP sandbox/default-src none、nosniff、no-referrer、private/no-store，不用于执行网站脚本。外部 S3/CDN 须配置等价策略。自建 bucket/region 为空时由部署补 hai/us-east-1，不能误写成 Storage Schema 默认值。
 
 ## 按需参考

package/templates/skills/hai-storage/reference.md

@@ -25,7 +25,7 @@ type: local # local | s3
 root: ./data/storage
 # S3 存储（type=s3 时生效）
 # endpoint: ''
-# publicEndpoint: https://app.example.com # 预签名访问 origin；不含桶或网站目录
+# publicEndpoint: https://app.example.com/delivery/files # 可含代理目录，不含桶；网关去此前缀后直达 S3
 # region: us-east-1
 # accessKeyId: ''
 # secretAccessKey: ''