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

package/dist/{src-JRKSWJ2Q.js → src-TEBHR5I5.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export { DEPLOY_MIDDLEWARE, DeployConfigSchema, DeploymentArtifactSchema, HaiDeployError, ProviderConfigSchema, artifactChecksum, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, readDeploymentArtifact, saveDeploymentEnvironment } from './chunk-M7HN2OE3.js';
+export { DEPLOY_MIDDLEWARE, DeployConfigSchema, DeploymentArtifactSchema, HaiDeployError, ProviderConfigSchema, artifactChecksum, createDeploymentPlan, deploy, describeMiddlewareBackend, getDeployCommandState, getDeployRecovery, importDeploymentSecrets, loadDeploymentConfig, loadDeploymentEnvironment, mergeEnvironmentLayers, normalizeProjectName, readDeploymentArtifact, saveDeploymentEnvironment } from './chunk-MUHRBJSW.js';
 import './chunk-ZSDEVXZ7.js';
-//# sourceMappingURL=src-JRKSWJ2Q.js.map
-//# sourceMappingURL=src-JRKSWJ2Q.js.map
+//# sourceMappingURL=src-TEBHR5I5.js.map
+//# sourceMappingURL=src-TEBHR5I5.js.map

package/dist/src-TEBHR5I5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"src-TEBHR5I5.js"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.12.1"
   },
   "dependencies": {
-    "@h-ai/core": "1.0.0-beta.1",
+    "@h-ai/core": "1.0.0-beta.2",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,15 +41,15 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/api-client": "1.0.0-beta.1",
-    "@h-ai/cache": "1.0.0-beta.1",
-    "@h-ai/crypto": "1.0.0-beta.1",
-    "@h-ai/deploy": "1.0.0-beta.1",
-    "@h-ai/feedback": "1.0.0-beta.1",
-    "@h-ai/iam": "1.0.0-beta.1",
-    "@h-ai/reach": "1.0.0-beta.1",
-    "@h-ai/reldb": "1.0.0-beta.1",
-    "@h-ai/storage": "1.0.0-beta.1",
+    "@h-ai/api-client": "1.0.0-beta.2",
+    "@h-ai/cache": "1.0.0-beta.2",
+    "@h-ai/crypto": "1.0.0-beta.2",
+    "@h-ai/deploy": "1.0.0-beta.2",
+    "@h-ai/feedback": "1.0.0-beta.2",
+    "@h-ai/iam": "1.0.0-beta.2",
+    "@h-ai/reach": "1.0.0-beta.2",
+    "@h-ai/reldb": "1.0.0-beta.2",
+    "@h-ai/storage": "1.0.0-beta.2",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
   "name": "{{projectName}}",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",

package/templates/skills/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/admin/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/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-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 初始化复制到浏览器。
@@ -68,6 +68,8 @@ 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` 返回。
 
 #### 迁移已有项目

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 端点模板
 

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-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

@@ -60,7 +60,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 回滚不恢复它。
 
 ## 自建对象存储直连
 

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-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: ''

package/dist/cli-config-templates-RCWQMHZN.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-export { generateConfigFile, generateEnvExample, generateProductionEnvironment } from './chunk-3JCZO34U.js';
-import './chunk-ZSDEVXZ7.js';
-//# sourceMappingURL=cli-config-templates-RCWQMHZN.js.map
-//# sourceMappingURL=cli-config-templates-RCWQMHZN.js.map

package/dist/src-JRKSWJ2Q.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"src-JRKSWJ2Q.js"}