@h-ai/cli 0.1.0-alpha.61 → 0.1.0-alpha.62

package/templates/base/e2e/app.spec.ts.hbs

@@ -1,10 +1,15 @@
-{{#if features.iam}}
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
-{{/if}}
 import process from 'node:process'
 import { expect, test } from '@playwright/test'
 
+{{#if_eq appType 'h5'}}
+test.use({ viewport: { width: 390, height: 844 } })
+{{/if_eq}}
+{{#if isCapacitorApp}}
+test.use({ viewport: { width: 390, height: 844 } })
+{{/if}}
+
 /** 首页从真实浏览器页面发起，覆盖基础渲染链路。 */
 test('home page renders from browser', async ({ page }) => {
 {{#if_eq appType 'h5'}}
@@ -24,12 +29,11 @@ test('home page renders from browser', async ({ page }) => {
   await nav.getByRole('button', { name: /首页|Home/i, exact: true }).click()
   await expect(page).toHaveURL(/\/$/)
   expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
-{{#if features.iam}}
+{{/if_eq}}
   const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
   await mkdir(evidence, { recursive: true })
-  await page.screenshot({ path: path.join(evidence, '{{projectName}}-home.png'), fullPage: true })
-{{/if}}
-{{/if_eq}}
+  await page.evaluate(() => document.fonts.ready)
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-home.png'), fullPage: true, animations: 'disabled' })
 })
 {{#if features.iam}}
 

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.61",
+  "version": "0.1.0-alpha.62",
   "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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@ Fullstack 多包工程入口。先读 README、根 workspace 脚本与相关 pac
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

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

@@ -4,6 +4,12 @@
 
 ## 行为契约
 
+需求/设计文档审查或从文档生成代码时，读取 [hai-spec-review](.agents/skills/hai-spec-review/SKILL.md)，严格确认完备性、歧义、技术正确性与命名一致性；影响行为的问题未解决前不判定文档可生成。普通小改动不重审无关文档。
+
+升级 hai-framework 到最新/指定版本、比较版本差异或同步框架 skills 时，先读 [框架升级与同步 Skill](.agents/skills/hai-framework-sync/SKILL.md)，执行版本发现、差异分析、用户选择/阻塞处理、迁移与验证；仅要求比较时不修改应用。
+
+根据文档规划、实施、继续或返修任务时，读取 [hai-spec-implement](.agents/skills/hai-spec-implement/SKILL.md)：审查后按可验收功能和依赖拆分，维护 docs 下的清单及 docs/tasks 下的任务信息，每项独立分支 TDD、验证并本地合并；返修复用原任务与分支。仅规划不实施，指定任务先核验依赖。
+
 普通新增、修改、修复任务开始前，先读 [应用开发 Skill](.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](.agents/skills/hai-app-create/development.md)；再按任务读取模块 Skill 及其相邻参考文件。架构/构建、审查、测试分别读取 hai-build、hai-app-review、hai-app-tests，不加载整个 skill 树。
 
 - 对当前需求逐项检索 hai-framework 能力和已有实现，确认适用的公开 API 后优先复用；未安装模块先核对依赖与配置，不能因 Skill 已存在就假定已启用。框架不适用时说明具体限制与选用方案，不为覆盖清单引入无关模块。

package/templates/skills/copilot-instructions.md

@@ -1,11 +1,5 @@
-# GitHub Copilot 项目指令
+# GitHub Copilot 入口
 
-> 本文件作为 Copilot 项目级指引；当缺少 appType 专属桥接时，使用本文件作为 generic fallback。详细用法按需读取 `.agents/skills/`。
+先读取共享入口 [AGENTS.md](../AGENTS.md)，按其中的项目架构、行为契约、质量门禁和完成条件执行任务。模块与工作流按需读取 `.agents/skills/` 的正文和相邻参考文件。
 
-共享规则见项目根 [AGENTS.md](../AGENTS.md)；若未自动加载，先读取该文件。模块/流程按需读取项目根 .agents/skills/<name>/SKILL.md 及其相邻参考文件。
-
-## 质量门禁
-
-按 AGENTS.md 和实际 package.json 选择 typecheck、lint、build、test、test:e2e；最终说明已执行结果、未运行原因及同步文档/依赖方。
-
-普通新增、修改、修复任务先读 [应用开发 Skill](../.agents/skills/hai-app-create/SKILL.md) 和 [开发规范与框架能力路由](../.agents/skills/hai-app-create/development.md)，依照 AGENTS.md 的默认规则复用框架并完成安全与质量验证。
+项目规则统一在 `AGENTS.md` 维护；本文件仅提供工具入口。

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

@@ -17,6 +17,10 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 
 ## 使用路径
 
+从需求/设计文档开始生成项目或功能前，使用 [hai-spec-review](../hai-spec-review/SKILL.md) 检查文档是否足以确定实现；修正影响行为的缺项、歧义和技术错误后再进入生成。普通小改动按本次范围确认规则，不要求重审无关文档。
+
+需要按文档规划/执行任务或返修已交付任务时，使用 [hai-spec-implement](../hai-spec-implement/SKILL.md) 管理 docs 清单、任务记录、TDD 和任务分支；本 skill 负责其中的具体应用实现，复用记录中的范围与验收。
+
 需要新建项目、添加模块、补齐配置或生成代码时，先按 [CLI 安装与命令](development.md#cli-安装与命令) 全局安装 `@h-ai/cli`，再执行 `hai` 命令。
 
 1. 读取 [development.md](development.md)：先按真实需求匹配框架能力、已安装版本与应用架构，再确定改动。适用能力包括同一模块已有 feature、配置和扩展点，不以导入包作为复用完成的证据。
@@ -26,6 +30,8 @@ description: "在 hai 应用中新增、修改或修复功能，按需求复用
 
 ## 按需参考
 
+新增新手引导或帮助说明时读取 [UI 引导指南](../hai-ui/guide.md)，复用 fullstack 默认的共享 guide-store、locale 和稳定 data-guide 锚点。
+
 详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
 
 - 适用场景

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

@@ -4,10 +4,12 @@
 
 ## 先确认应用与版本
 
+- 新手引导与帮助中心使用 `@h-ai/ui/guide`，按 [UI 引导指南](../hai-ui/guide.md) 接入。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 初始化复制到浏览器。
 - 从所属 workspace 的依赖与 lockfile 确认 `@h-ai/*` 实际解析版本和 npm/local 模式。模板 skill 提供导航，**当前安装包的 `package.json.exports`、公开 `.d.ts` 与随包文档决定可用 API**；本地框架源码只在版本匹配或显式联调时作实现证据。
-- 若 skill 与安装版本不符，以公开类型和实际行为核验。先使用已支持能力；任务确需新版本时列明版本变更、调用方与验证范围。不能直接复制未发布源码的 API，也不能为绕过差异添加虚构兼容层。
+- 若 skill 与安装版本不符，以公开类型和实际行为核验。先使用已支持能力；任务要求升级时按 [hai-framework-sync](../hai-framework-sync/SKILL.md) 发现目标、比较差异并完成迁移验证。不能直接复制未发布源码的 API，也不能为绕过差异添加虚构兼容层。
 
 ## CLI 安装与命令
 
@@ -28,7 +30,7 @@ hai create my-app
 
 应用元信息只有一份配置来源：名称、版本、环境、默认语言与日志设置来自 `_core.yml`，使用 `core.config` 与 `core.logger`；Node 启动时不通过固定 `logging` 覆盖 YAML。SvelteKit 服务端 layout 和 fullstack `app.info` 仅公开必要元信息，不能下发整个 core 或模块配置。独立 Vite mobile-app 在 Node 构建阶段经 core 加载 YAML/环境覆盖并注入公开字段，配置变化需重新构建。环境覆盖使用 `HAI_CORE_NAME`、`HAI_CORE_VERSION`、`HAI_CORE_ENV`、`HAI_CORE_LOGGING_LEVEL` 等既有规则；容器明确配置生产环境，不能用另一个状态来源代替 `core.env`。
 
-开发前，对本次涉及的需求简述“需求 → 现有应用实现/框架能力 → 版本与契约依据 → 修改位置与验收”。简单任务可用几句话；跨模块任务用表格。查找顺序：已有应用实现 → 框架公开能力和配置 → 最小业务补充。
+开发前，对本次涉及的需求简述“需求 → 现有应用实现/框架能力 → 已安装版本与公开契约依据 → 最小业务补充/修改位置 → 成功、权限与失败验收”。简单任务可用几句话；跨模块任务用表格。查找顺序：已有应用实现 → 框架公开能力和配置 → 最小业务补充。
 
 下表技能名用于能力导航；先确认 `.agents/skills/<name>/SKILL.md` 存在再读取。CLI 按应用类型/已选模块交付技能，缺目录不代表框架没有该能力：继续查已安装包的公开 exports/types；确需补充模块/技能时按当前 CLI 帮助和项目依赖策略处理，不能跳过需求匹配或猜测不存在的 API。
 
@@ -37,20 +39,20 @@ hai create my-app
 | 配置、日志、ID、结果/错误、i18n | `hai-core` | getter、logger、ID 是直接值；ID 不作为密钥 |
 | 数据库查询、CRUD、事务、分页 | `hai-reldb` | 先检查现有 CRUD/Repository 与事务支持，不另建 DB 连接层 |
 | 缓存、TTL、共享锁 | `hai-cache` | 区分 memory 与共享后端；单进程状态不能承担跨节点防重 |
-| 注册、登录、会话、角色/权限 | `hai-iam` | 优先配置内置认证能力；业务资源/租户授权仍由应用检查 |
+| 注册、登录、会话、角色/权限 | `hai-iam` | 优先配置内置认证能力；受保护请求使用 iam.auth.verifyToken，serv 注入 IAM 时自动使用；批量用户与角色筛选复用公开 API；业务资源/租户授权仍由应用检查 |
 | SvelteKit Hook、守卫、校验、响应 | `hai-kit` | 只用于 SvelteKit；沿用已有认证/transport 管道 |
 | 共享输入输出和 HTTP contract | `hai-api-contract` | 扩展已有 contract 与 schema，不维护第二份业务路径 |
 | API 运行时、内置 feature、route guard | `hai-serv` | 先检查内置 procedures/features 与 route auth/permission；不另写平行服务器 |
 | 浏览器/原生 API、刷新会话 | `hai-api-client` | 已支持接口复用 typed client、认证与 transport；额外 fetch/刷新封装需有缺口依据 |
 | 页面、表单、表格、弹窗、移动 UI | `hai-ui` | 按实际导出选择场景/组合/原子组件；应用补业务交互 |
-| 文件上传、下载、元数据、预签名 URL | `hai-storage` | 检查已有 storage feature；资源授权、大小/类型/路径限制不可省略 |
+| 文件上传、下载、元数据、预签名 URL | `hai-storage` | 检查已有 storage feature；大文件用流式读写，checksum 按实际字节计算，ifNoneMatch 拒覆盖；资源授权、大小/类型/路径限制不可省略 |
 | 加密、签名、哈希 | `hai-crypto` | 复用公开 API 与密钥配置，不自创加密或硬编码密钥 |
 | LLM、流式、Embedding、RAG、Agent/MCP | `hai-ai` | 先检查内置能力与 provider 配置，再补应用编排 |
 | 文本清洗、分块、管线 | `hai-datapipe` | 纯函数无生命周期；分块不代表已经生成向量 |
 | 向量集合与检索 | `hai-vecdb` | 后端、维度与过滤条件使用实际契约 |
-| 邮件/短信/通知触达 | `hai-reach` | 复用已有 provider；投递状态不等于 HTTP 成功 |
+| 邮件/短信/通知触达 | `hai-reach` | 模板已绑定 provider 时只传 template/to/vars；直接发送才指定 provider；投递状态不等于 HTTP 成功 |
 | 支付、订单、订阅、回调 | `hai-payment` | 验签、金额/订单绑定、幂等与状态迁移仍需业务验收 |
-| 操作审计 | `hai-audit` | 复用审计记录/查询；应用决定脱敏、保留期及失败策略 |
+| 操作审计 | `hai-audit` | 复用审计记录/查询与 PaginatedResult 元数据；应用决定脱敏、保留期及失败策略 |
 | cron、持久任务、重试、手工触发 | `hai-scheduler` | 复用任务模型；明确取消、幂等、共享锁及可信代码边界 |
 | 原生设备与安全 token 存储 | `hai-capacitor` | 仅在适用平台启用；桌面/小程序依当前项目适配 |
 
@@ -62,6 +64,8 @@ Fullstack 创建时在被 Git 与容器构建忽略的根 `.env` 写入独立随
 
 ## 落实契约与安全边界
 
+沿现有服务层按顺序落实 schema → 当前授权与操作权限 → 从资源 ID 查所有者/范围 → 需要时核验对应操作凭据 → 存储/通知等副作用 → HaiResult 与审计。框架身份授权不能替代业务资源范围，数据库实体/存储 key 不交给客户端决定。文件失败、checksum 不匹配、不可覆盖冲突及通知失败/延迟分别向调用方反馈，并按业务一致性要求事务回滚或补偿；不能静默返回成功。
+
 按本次真实输入、资源和副作用选取下面检查，并把适用项变成可观察验收。不能用“已遵循安全规范”或 lint 通过替代行为证据。
 
 | 边界 | 实现要求 | 验收证据 |

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

@@ -83,7 +83,7 @@ if (!closeResult.success) {
 | 方法                  | 签名                                                                                | 说明                 |
 | --------------------- | ----------------------------------------------------------------------------------- | -------------------- |
 | `audit.log`           | `(input: CreateAuditLogInput) => Promise<HaiResult<AuditLog>>`             | 记录审计日志         |
-| `audit.list`          | `(options?: ListAuditLogsOptions) => Promise<HaiResult<{ items, total }>>` | 分页查询（含用户名） |
+| `audit.list`          | `(options?: ListAuditLogsOptions) => Promise<HaiResult<PaginatedResult<AuditLogWithUser>>>` | 分页查询（items/total/page/pageSize，含用户名；使用返回的规范化元数据，默认 pageSize 20） |
 | `audit.getUserRecent` | `(userId: string, limit?: number) => Promise<HaiResult<AuditLog[]>>`       | 用户最近活动         |
 | `audit.cleanup`       | `(olderThanDays?: number) => Promise<HaiResult<number>>`                   | 清理旧日志           |
 | `audit.getStats`      | `(days?: number) => Promise<HaiResult<AuditStatItem[]>>`                   | 操作统计             |

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

@@ -18,6 +18,7 @@ description: "定位 hai 应用架构、模块依赖、初始化顺序、构建
 ## 使用路径
 
 - 先读当前 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、适配器、环境变量、缓存与目标产物，不能照搬框架仓库私有构建命令。

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

@@ -243,7 +243,7 @@ logging:
 | 编写/补充测试          | `hai-app-tests`  | 测试, test, 单测, 覆盖率, TDD, E2E     |
 | CI/CD 与质量门禁       | `hai-ci`         | CI, CD, GitHub Actions, workflow, secret scan |
 | PR / Issue 交付审查    | `hai-pr-review`  | PR, pull request, issue, CODEOWNERS, 自动 Review, AI Review |
-| hai-framework 同步     | `hai-framework-sync` | hai-framework, skills 同步, framework:use:local, framework:watch |
+| hai-framework 升级与同步 | `hai-framework-sync` | 升级框架, 最新版本, 版本差异, skills 同步, npm/local 漂移 |
 
 ## 行为开发工作流
 

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

@@ -107,6 +107,6 @@ lint/typecheck 只能执行已配置的规则。新增开发规范时区分可
 - `hai-app-tests` — Vitest / Playwright 测试规范
 - `hai-pr-review` — PR 审查与 AI Review 策略
 - `hai-deploy` — 应用部署与云服务开通
-- `hai-framework-sync` — hai-framework 与应用仓库同步策略
+- `hai-framework-sync` — 框架版本升级、差异分析与 npm/本地同步
 
 涉及发布时按本应用实际 registry/镜像/部署目标核验精确版本与提交，不以 tag 或 CI 绿灯代替发布产物；未经授权不发布。原生/容器交付按当前项目入口单独构建与启动验收，保存产物、平台和行为证据；缺平台写未验证，Web E2E 不代替原生验收。

package/templates/skills/hai-framework-sync/SKILL.md

@@ -1,106 +1,103 @@
 ---
 name: hai-framework-sync
-description: "同步 hai-framework 通用 skills、AI 入口与应用依赖，排查 npm/本地联调漂移。"
+description: "升级应用的 hai-framework 到最新或指定发布版本：分析版本差异、提示用户选择与阻塞、迁移依赖/代码/配置并同步 skills；排查 npm/本地漂移。"
 ---
 
-# hai-framework-sync — hai-framework 与应用仓库同步规范
+# hai-framework-sync — 框架升级与同步
 
 ## 能力契约
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 同步 hai-framework 通用 skills、AI 入口与应用依赖，排查 npm/本地联调漂移 |
-| 适用场景 | 有明确源/目标仓库的模板或版本同步 |
-| 输入 | 框架源目录、应用目录、版本、现有本地覆盖 |
-| 输出 | 同步后的完整 skill 目录、入口及版本验证结果 |
-| 限制 | 仅操作授权仓库；保留应用私有规则。先查 scripts，不假定 framework:* 联调命令存在；未发布行为不能当 npm 已支持。 |
+| 能力 | 发现最新发布版本，比较当前到目标的累计差异，处理选择与阻塞，完成应用升级及 skills/AI 入口同步 |
+| 适用场景 | “升级 Hai-framework 到最新版本”、指定版本升级、版本差异审查、模板同步或 npm/本地联调漂移排查 |
+| 输入 | 当前应用、升级目标及已有约束；当前版本、registry、架构与本地覆盖从项目读取，不要求用户预先提供框架源目录 |
+| 输出 | 当前/目标版本及来源、差异与处理清单、迁移后的依赖/代码/配置/skills、验证结果；未完成时给出选择或阻塞及恢复步骤 |
+| 限制 | 仅操作授权项目，保留已有改动、架构和私有规则；以实际发布产物为准，未确认选择或未解除阻塞不得越过 |
 
-> hai-framework 是能力与 skill 模板源头；应用仓库消费这些能力，并可以有少量项目本地覆盖。同步的目标是减少漂移，而不是把两个仓库混成一个仓库。
+## 任务入口
 
-## 适用场景
+- 用户说“升级 Hai-framework 到最新版本”时，直接从当前应用执行下方升级流程。该请求已授权常规依赖更新、必要兼容迁移、skills 合并和本地验证；不为每个文件修改重复确认，也不只输出升级建议后结束。
+- 用户仅要求审查/比较版本时，完成现状、目标与差异分析，不安装或修改应用。
+- 仅同步通用规范、AI 入口或联调两个仓库时，按需读取 [同步与本地联调](sync.md)；普通应用升级不要求框架仓库可写。
+- 先识别当前目录是否为目标应用；确实无法确定目标项目时才询问。应用升级不包含 npm 发布、部署、生产数据迁移或系统级工具安装，已有明确授权时按其范围执行。
 
-- 修改 `.agents/skills/**`，且内容应成为所有 hai-framework 应用通用规范
-- 修改 `packages/cli/templates/skills/**`
-- 调整 `AGENTS.md`、`CLAUDE.md`、`opencode.json`、Copilot 指令模板
-- 使用 `framework:use:local` / `framework:watch` 联调本地 hai-framework
-- 排查应用仓库与 hai-framework npm 版本不一致
-- 规划双仓 PR 或同步发布
+## 升级流程
 
-## 同步原则
+### 1. 确认现状
 
-1. **通用规范先改 hai-framework**：可复用的 skill、模板、AI 工作流从 `packages/cli/templates/skills/` 起源。
-2. **应用仓库只保留项目差异**：业务上下文、项目私有路径、产品决策可以留在应用仓库。
-3. **默认 CI 使用 npm 依赖**：确保 PR 能代表真实安装环境；本地路径联调必须显式开启。
-4. **双仓改动要成套**：framework 模板、应用本地 `.agents/skills`、AGENTS/Copilot 路由同时更新。
-5. **不复制敏感聊天记录**：只同步脱敏后的团队规则和流程。
+读取 AGENTS、README、package.json、workspace 配置、lockfile 与相关初始化/调用点，用 `rg` 搜索实现、引用、测试和版本配置。记录 Git 状态及已有改动；工作区有改动本身不构成阻塞，不清空、覆盖或自动 stash 用户工作。
 
-## 标准同步流程
+- 识别包管理器、Node/包管理器版本、实际 scripts，以及 SvelteKit、API workspace、fullstack、Vite SPA 或原生端架构。
+- 盘点全部 workspace 实际消费的 `@h-ai/*`：记录声明位置、lockfile 解析版本、已安装版本及 npm/local 模式。核对 `catalog`/命名 catalogs、overrides、patchedDependencies、file/link/workspace 映射和联调脚本，不能只看根 package.json。
+- 混用多个版本时分别保留基线；未安装依赖时标明已安装版本不可得，以 lockfile 为比较基线，安装后补验。关联代码、配置、环境变量名及 AI 入口，记录已有质量问题；不输出凭据或完整私有配置。
 
-### 1. 判断来源
+### 2. 发现并固定目标
 
-先读取当前应用入口与 package.json/lockfile，记录实际 npm/local 模式及解析版本。同步 skill 不能证明新 API 已安装或可用：以目标依赖的公开 exports/types 验证示例与配置，未发布框架能力仅用于已授权本地联调。
+使用项目有效 registry（包含 scope registry）在线查询；无法访问时诊断网络/镜像/权限，不把缓存或记忆中的版本说成“最新”。
 
-CLI 生成的 `@h-ai/*` 依赖固定为 CLI 对应版本，pnpm catalog 也使用精确版本。统一升级所有框架包后检查 lockfile 与已安装 exports。
+```bash
+# 查询示例；PowerShell 使用 npm.cmd / pnpm.cmd。
+npm view @h-ai/core dist-tags --json
+npm view @h-ai/core@latest version engines dist --json
+npm view @h-ai/cli dist-tags --json
+```
 
-| 变更类型 | 首选位置 |
-| --- | --- |
-| 通用 hai 模块用法 | `hai-framework/packages/cli/templates/skills/hai-*/SKILL.md` |
-| 通用 CI/PR/Issue/AI 协作流程 | `hai-framework/packages/cli/templates/skills/` |
-| 应用私有业务规则 | 应用仓库 `AGENTS.md` 或本地 skill |
-| Copilot/Claude/OpenCode 入口模板 | hai-framework 模板 + 应用仓库入口文件 |
+- 未指定版本/通道时，以 `@h-ai/core` 的 `latest` 为候选；`latest` 即使指向预发布版也应说明并按该通道分析。用户指定版本、稳定版或其他 dist-tag 时遵循其目标；没有满足条件的发布版时提示处理，不擅自替换。
+- 对每个已用框架包及用于模板同步的 `@h-ai/cli`，逐一查询候选**精确版本**的存在性、deprecated、engines、dependencies/peerDependencies 和 dist 信息。新增的必要框架依赖同样核验；不能因 core 或 CLI 已发布就假定整组已发布。
+- 记录查询时间、registry、每包当前/目标版本与发布产物来源，固定本次目标。发布不齐、镜像滞后、目标被弃用或应用实际采用比候选更晚的发布版时，说明差异并让用户选择等待、指定可用版本/来源或取消相关升级，不静默降级或混装。判断发布先后结合官方发布序列，不能因旧命名 `alpha9` 的 SemVer 排序就认定它更晚。
+- 使用精确版本；不能用 `versions` 的字典序、最大 SemVer 或 `pnpm update --latest` 代替 dist-tag 决策。旧命名 `alpha9` 可能在 SemVer 中高于 `alpha.58`，`^`/`~` 范围不保证选中本次目标。
 
-### 2. 修改源头
+### 3. 比较累计差异并关联应用
 
-先在 hai-framework 模板中修改或新增 skill。
+在修改依赖前，读取当前到目标版本之间的 Release/CHANGELOG、迁移说明及官方提交差异，覆盖中间版本；混版本逐包比较。上游仓库从包元数据或官方 README 确认，按发布 tag/commit 定位，不能把 main 分支的未发布能力归到目标版本。
 
-### 3. 同步到应用仓库
+没有本地框架源码也应继续：在临时目录用 `npm pack <包名>@<精确版本> --ignore-scripts --pack-destination <临时目录>` 获取当前/目标包，比较 package.json.exports、公开 `.d.ts`、配置 schema/默认值、实现与随包文档；从同版本 CLI 的 `templates/skills/` 获取完整技能目录及入口模板。占位参数先替换为已确认值；只读比较产物，不覆盖应用或执行其中脚本。命令依据：[npm view](https://docs.npmjs.com/cli/commands/npm-view)、[npm pack](https://docs.npmjs.com/cli/commands/npm-pack)。
 
-通过已发布 CLI 补齐缺失文件时，先按 [CLI 安装与命令](../hai-app-create/development.md#cli-安装与命令) 安装或更新 `@h-ai/cli`，再从应用根目录运行 `hai init`。它只补齐缺失内容，不覆盖已有 AI 规则和 skills；已有文件仍需对照模板合并。未发布的模板修正需从框架源目录同步，不能假定已安装 CLI 包含这些修正。
+发布说明不足时以产物、对应源码和测试补充证据；关键兼容差异无法核实时标为待核实/阻塞，不能推断“无破坏性变更”。
 
-把源头完整 skill 目录（含 reference.md 等被引用资源）复制到应用仓库 `.agents/skills/<skill>/`，并同步入口引用：
+逐项检查并关联实际文件/调用点：
 
-- `AGENTS.md`
-- `.github/copilot-instructions.md`
-- `CLAUDE.md`（如存在，通过 `@AGENTS.md` 复用共享规则；不另复制 `.claude/skills/`，保留用户已有规则和技能）
-- `opencode.json`（如结构变化）
+- 公开入口、API/类型/错误码、HaiResult 与流/抛错语义、初始化依赖和关闭行为。
+- 配置 schema、默认行为、环境覆盖、认证/安全策略、DB schema/迁移、外部服务与引擎要求。
+- 构建/运行/发布脚本、第三方 peer 依赖、原生/容器集成，以及版本绑定的补丁是否仍必要。
+- skills 及相邻资源、AGENTS/Claude/Copilot/OpenCode 路由；新能力是否可替换本次相关的自定义实现或配置。按 [能力选择规则](../hai-app-create/development.md) 判断适用性，不为升级强行安装无关模块或转换架构。
 
-新增/修改/修复任务入口必须能到达 `hai-app-create` 与其 `development.md`；审查入口能到达 `hai-app-review`。按目标架构/依赖交付所需模块技能，不把 SvelteKit 指令套到 API/Vite 项目。复制前比对应用私有覆盖，合并通用修正并保留差异，不能直接覆盖业务规则。
+先给出可追踪的差异清单，再执行迁移：
 
-### 4. 验证
+| 差异/证据 | 应用位置与影响 | 处理类别 | 迁移或选项 | 验收与状态 |
+| --- | --- | --- | --- | --- |
+| 当前 → 目标及发布/产物位置 | 具体调用、配置、依赖或“不适用”的依据 | 自动处理 / 用户选择 / 阻塞 / 不适用 | 必要修正或带取舍的方案 | 可观察验收、待处理/已解决/待用户 |
 
-按变更类型选择验证方式：
+### 4. 处理用户选择与阻塞
 
-- 仅模板 / skill 变更：检查 diff、目标中实际存在的入口/相邻资源及其相对引用，确认没有框架仓库私有路径/命令；本地能力导航对可选 skill 先检查存在，不把目录缺失当成能力缺失。
-- 同步到应用仓库：按 `hai-ci` 定义的质量门禁运行。
-- 涉及 framework runtime 时，先确认应用 package.json 已定义下列脚本；没有时按 README 的本地联调方式操作：
+| 类别 | 处理方式 |
+| --- | --- |
+| 自动处理 | 目标明确、可保持现有行为的依赖更新、兼容性修正、无冲突的 skills 合并和验证，直接执行 |
+| 用户选择 | 存在多个有意义的方案且影响产品行为、架构、成本、Provider 或运维方式，展示证据、选项、推荐与取舍，等待回答 |
+| 阻塞 | 无法取得必要产物、依赖不兼容、无法无损合并、必要工具/服务/授权缺失或关键验证失败，先诊断并修复可自行解决的原因；仍无法推进时说明具体处理步骤 |
+| 不适用 | 当前应用未使用且不影响其依赖/运行的变化，记录依据；不要求用户逐项确认 |
 
-```bash
-pnpm framework:status
-pnpm framework:use:local <package>
-pnpm framework:watch <package>
-```
+- 尽量合并相互独立的选择，明确每个回答控制哪项改动；已给出的目标、授权和选择持续有效，不重复询问。
+- 提问时给出问题位置、事实、影响、可选路径及推荐。用户未回答时保持选择待定，可继续独立分析/验证；不能以等待超时替用户选择，也不能先安装一部分框架包造成混版本。
+- 阻塞报告包含失败命令、退出码、脱敏关键错误、受影响步骤、已尝试处理、用户最小操作和解除后的验证方式。不要求在聊天中粘贴密钥，不通过关闭检查、忽略 engines 或无依据覆盖依赖掩盖失败。
+- 涉及不可逆数据迁移、删除私有覆盖或外部发布时，先准备可审查方案及备份/恢复步骤，再取得该操作所需授权。等待期间不执行依赖该决定的操作；恢复后沿已固定目标和清单继续。
 
-## 漂移检查清单
+### 5. 执行升级与同步
 
-- [ ] framework 模板和应用 `.agents/skills` 对同名 skill 内容一致，除非 PR 明确说明本地覆盖
-- [ ] 普通功能修改/修复也路由到能力匹配与安全/质量自查，不仅“创建项目”或手工调用 skill 才生效
-- [ ] 技能示例与目标实际依赖版本、架构、公开 API 一致；没有把模板更新当成 runtime 升级
-- [ ] `AGENTS.md` 的 skill 列表包含新增/重命名 skill
-- [ ] Copilot/Claude/OpenCode 入口能找到新增 skill
-- [ ] CI 默认不依赖 `/home/.../hai-framework` 本地路径
-- [ ] 本地联调结束后可恢复 npm 模式
-- [ ] README 或 PR 描述说明双仓改动顺序
+必要选择和安装阻塞解除后，按既有包管理方式更新所有已用框架包的精确版本，统一修改相关 package.json/catalogs/overrides。保留应用 workspace 协议及无关依赖；必要 peer 更新须来自目标契约，禁止无差别升级全部依赖。
 
-## 禁止事项
+1. 按差异清单迁移调用方、类型、配置、环境变量说明、初始化和构建入口，保留应用行为与架构。新默认行为改变须显式核对；只对生命周期模块遵循 init → use → close，不给 core/serv/纯函数套用生命周期。
+2. 用目标版本回归核验已有补丁/本地覆盖：仍必要则针对目标重建并说明依据；只有上游已修复且回归通过时移除。npm 升级遇到本地联调映射时，明确恢复 npm 或继续本地验证的选择，不能只改版本号却继续运行旧源码。
+3. 使用当前包管理器安装并更新 lockfile，保留失败诊断；不手改 lockfile 的解析字段。安装后从**各消费 workspace**核对真实版本、公开 exports/类型及框架传递依赖，检查残留旧版/重复解析和本地路径。
+4. 按 [同步规则](sync.md) 合并目标 CLI 中适配本架构的完整 skill 目录及 AI 入口。对“旧发布模板、应用现有文件、新发布模板”比较，保留私有规则/自定义技能，冲突转为选择；没有旧模板时先辨识私有内容，不直接覆盖。同步版本必须与目标运行时一致。
+5. 同步受影响的 README、配置样例、skill 与测试，逐项更新差异清单状态。即使已处于目标版本，也核验解析/配置/skills 漂移；一致时报告无需升级，不制造改动。
 
-- ❌ 只改应用 `.agents/skills`，忘记更新 hai-framework 模板中的通用规范
-- ❌ 在 CI 默认路径中依赖本机绝对路径
-- ❌ 把 unpublished framework 行为当成已发布 npm 行为
-- ❌ 把聊天记录原文、token、私有 URL 写入模板
-- ❌ 双仓 PR 没有关联 issue 或同步说明
+### 6. 验证与交付
 
-## 相关 Skills
+按应用实际 scripts 和 [hai-ci](../hai-ci/SKILL.md) 执行 `typecheck → lint → build → test`，优先受影响 workspace；跨包契约验证所有消费者。按 [hai-app-tests](../hai-app-tests/SKILL.md) 选择受影响的集成/E2E，覆盖启动/关闭、变更 API、认证、持久化等实际路径。
 
-- `hai-ci` — CI 对 npm/local framework 模式的验证策略
-- `hai-pr-review` — 双仓 PR 审查要点
-- `hai-build` — 应用开发入口
+- 依赖升级后另核对 lockfile 与安装版本、公开入口、配置加载和关键业务流程；build 通过不能替代 typecheck 或运行验收。
+- 检查同步后的全部相邻资源、相对引用和各工具入口；目标存在 `check:skills` 时运行，不假定应用具有框架仓库私有脚本。
+- 修复本次引入的失败，区分升级前已有失败。必要验收缺服务/凭证/平台时提示阻塞；额外平台或未涉及的真实 Provider 验证明确标为未执行及原因，不能用 mock/Web 结果冒充真实/原生验证。
+- 最终报告当前 → 目标及来源、差异处理结果、用户选择、变更文件与同步入口、实际门禁和未验证边界、恢复方法。依赖与必要迁移完成、选择/阻塞已解除且必要验证通过才称“升级完成”；否则报告当前进度与下一步，用户处理后继续完成。

package/templates/skills/hai-framework-sync/sync.md

@@ -0,0 +1,49 @@
+# 通用规范同步与本地联调
+
+从 [hai-framework-sync](SKILL.md) 进入。仅同步 skills/AI 入口、修改通用模板或联调两个仓库时读取本文件；应用版本升级先执行入口中的版本发现与差异流程。
+
+## 来源与边界
+
+hai-framework 是通用能力和 skill 模板的源头；应用仓库消费这些能力，并保留项目私有规则。
+
+| 任务 | 来源与修改范围 |
+| --- | --- |
+| 框架仓库开发规范与 skills | 框架根 `AGENTS.md`、`.agents/instructions/`、`.agents/skills/`；仓库私有路径不复制到应用模板 |
+| 应用消费某发布版的 skills/AI 入口 | 对应精确版本 `@h-ai/cli` 的 `templates/skills/`；合并到当前授权应用，不要求修改框架仓库 |
+| 修正可复用模块用法或工作流 | 在已授权框架仓库的 `packages/cli/templates/skills/` 修改源头，再同步受影响应用；核对相关仓库 skills 的公共契约 |
+| 应用私有业务规则、产品决策与路径 | 留在应用 AGENTS 或本地 skill，不复制到通用模板 |
+| 未发布模板/运行时联调 | 使用明确版本/提交的已授权本地框架来源，报告与 npm 发布版的差异 |
+
+先确认目标应用的入口、实际目录、package.json/lockfile 和 npm/local 模式；有本地框架来源时再确认该仓库的入口与版本/提交。模板同步不证明新 API 已安装；示例必须符合目标依赖的公开 exports/types。通用内容不含敏感聊天记录、token 或私有地址。
+
+## 同步完整技能与入口
+
+通过 CLI 补齐缺失文件时，先按 [CLI 安装与命令](../hai-app-create/development.md#cli-安装与命令) 安装所需精确版本的 `@h-ai/cli` 并检查 `hai --version` / `hai --help`，再从应用根运行 `hai init`。临时使用 CLI 可隔离安装到临时目录；不为读取模板要求全局安装或改变系统级工具。
+
+`hai init` 只补缺失内容，即使 `--force` 也不覆盖已有 AI 规则和 skills，不能用它代替旧版本规则合并。未发布模板修正从明确本地来源同步，不能假定已发布 CLI 已包含。
+
+1. 比较来源与应用的同名完整目录，包括 SKILL、reference/guide、脚本和资产；升级时结合旧发布模板识别应用私有覆盖。无冲突部分合并，冲突列出位置、双方意图和可选方案。
+2. 按目标架构选择需要的模块技能与桥接模板；不将 SvelteKit 指令套到 API/Vite 项目。保留自定义技能；上游重命名/删除的旧目录先检查调用与私有内容，不能整树覆盖或删除。
+3. 项目规则合并到 AGENTS，`.github/copilot-instructions.md` 只引用共享入口；CLAUDE 如存在，通过 `@AGENTS.md` 复用共享规则，保留用户额外规则及现有 `.claude/`，不另复制技能正文。OpenCode 的 `instructions` 直接引用 `AGENTS.md`；配置有变化时合并已有字段，不整体替换。
+4. 确保新增/修改/修复任务能到达 `hai-app-create` 与其 `development.md`，审查到达 `hai-app-review`，框架升级到达 `hai-framework-sync`。只引用目标实际交付的可选技能，不把目录缺失当成运行时能力缺失。
+
+Codex 原生读取根 `AGENTS.md` 并发现 `.agents/skills/`，可用 `$hai-app-create` 等名称调用；不复制额外的 `.codex/skills`。同步后验证技能列表和按需参考文件可达；列表尚未刷新时重新打开项目或开始新会话。
+
+## npm 与本地联调
+
+默认 CI 验证 lockfile 中的已发布 npm 依赖，不依赖本机路径。先查应用实际 scripts；仅在存在时使用相应 `framework:*` 命令，否则遵循本项目 README，不凭空新增联调脚本：
+
+```bash
+pnpm framework:status
+pnpm framework:use:local <package>
+pnpm framework:watch <package>
+```
+
+PowerShell 使用 `pnpm.cmd`；占位包名替换后执行。本地来源先验证其版本/提交、构建产物与 exports，再开启联调；记录依赖映射/overrides 的恢复方式。联调结束按项目已有机制恢复 npm 并重装验证，不能把本地通过报告为发布版通过。
+
+## 验证与交付
+
+- 仅 skills/入口变更：检查 diff、完整目录、目标实际存在的入口及相邻资源、相对引用；排除框架仓库私有绝对路径/命令。
+- 框架模板维护：运行已有 `check:skills` 和 CLI `test:scaffold-gates`，确认资源与路由在生成项目中可达。
+- 同步应用依赖或运行时：按入口升级流程和 [hai-ci](../hai-ci/SKILL.md) 选择应用门禁，不以模板已同步代替运行验收。
+- 双仓改动时说明来源版本/提交、改动顺序、应用私有覆盖和双方验证；涉及 PR 时按 [hai-pr-review](../hai-pr-review/SKILL.md) 关联同步说明。仅授权一个仓库时记录另一方待同步，不擅自修改。

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

@@ -21,6 +21,8 @@ description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key
 - 角色资料与 permissionIds 一次保存：未传保持、空数组清空、未知 ID 失败；人数查询失败不能显示为 0。
 - IAM 服务端是 iam.auth；typed HTTP client 的路径是 apiClient.iam.auth。
 - OTP/API Key 等先核对 login 开关；不把未启用能力的 NOT_INITIALIZED 当认证失败。
+- API Key 的配置、scope 交集示例表与创建→登录→操作授权→撤销代码见参考中的 API Key 小节。不要以 `checkPermission(userId)` 绕过请求 scope；ID/code/name 分别用于关联、守卫与展示。
+- API Key scopes 与主体权限取交集，默认空数组无操作权限；受限 key 无角色授权，使用 permission 守卫。显式 * 仍受主体限制，派生会话读取/刷新检查 key，撤销/禁用/到期立即拒绝。
 
 - 认证页面使用 iam.publicConfig + AuthPanel，协议用弹窗，表单通过 header/extraFields/footer 或 AuthPanel 的 login*/register* snippet 扩展；Kit 使用 kit.auth.createApi/publicPaths + kit.client.createAuthActions，HTTP 客户端使用 apiClient.createAuthActions。
 - LDAP/Reach 均可选：基础认证无需安装；默认 LDAP 关闭，选用默认客户端才安装 ldapts 并设置 login.ldap + ldap。OTP 邮件/短信由 otp.email/sms 控制，选择 Reach 标准模板或自定义发送回调；具体签名与失败处理见参考中的“可选 LDAP 与通知”。
@@ -28,6 +30,9 @@ description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key
 
 - 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
+- 受保护请求使用 `iam.auth.verifyToken`：当前用户状态 + 角色 JOIN + 批量权限读取，失败即拒绝；`iam.session.verifyToken` 仅验证会话快照。serv 内置 IAM 注入默认使用当前授权入口，无需手动补查。
+- 用户批量读取用 `iam.user.getUsers(ids, { include: ['roles'] })`（最多 1000，去重保留输入顺序，缺失省略）；角色筛选用 `listUsers({ roleCode })`，在分页前执行，避免 N+1 和分页后过滤。
+
 ## 按需参考
 
 详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。