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

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

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

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

@@ -0,0 +1,243 @@
+# hai 应用开发决策
+
+README 编辑先读章节，把功能说明与示例合并到对应章节；新增功能章节放在开发测试之前，不能机械堆到许可证上方。许可证只能保留一节且位于最后，正文只放声明或链接，禁止在其后追加功能段落。已有中英日版本同步内容和章节位置，模板文档同步核对；交付前通读顺序并执行项目已有的文档门禁。
+
+日常新增、修改和修复功能时读取本文件；专项模块 API 只读取下表匹配的 skill。这里的“应用尽用”是让每项真实需求优先使用适用框架能力，并检查已有 feature、配置和扩展点；不要求所有项目安装或启用全部模块。
+
+## 需求与模板的关系
+
+业务规则以用户当前明确要求和指定的需求/设计文档为准。模板 AGENTS、README、skills、示例、生成逻辑和测试提供初始方案，不固定角色/权限、流程、字段、限额、偏好存储或部署架构。需求明确时直接在已授权范围内适配，不为保留模板而修改需求或重复要求选择；仅审查时列出适配项，不写业务代码。
+
+实现证据用于确认当前行为，不能推翻目标业务规则。同步修改冲突的 schema、服务端授权、初始化/种子数据、迁移、UI、配置、测试与过期规则；未改变的行为继续回归。API 是否可用由安装版本的公开契约决定，服务端授权、资源隔离、输入校验和凭据保护仍需满足；确有不可行或安全问题时举证并给出替代方案。
+
+## 先确认应用与版本
+
+- 带前端的工程新增引导与帮助时使用 `@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 初始化复制到浏览器。
+- 独立 mobile 模板选择 IAM/crypto 时包含前端 crypto，默认启用 typed client 加密 transport；无 crypto 的客户端保留明确的明文 API 模式。只有匹配的明文服务才设置 `PUBLIC_API_TRANSPORT=off`；`PUBLIC_API_KEY_EXCHANGE_PATH` 只覆盖公开协商子路径。握手失败不降级，关闭时先销毁 client transport，再关闭自身初始化的 crypto；服务端 ring 私钥不进入客户端。
+- 从所属 workspace 的依赖与 lockfile 确认 `@h-ai/*` 实际解析版本和 npm/local 模式。模板 skill 提供导航，**当前安装包的 `package.json.exports`、公开 `.d.ts` 与随包文档决定可用 API**；本地框架源码只在版本匹配或显式联调时作实现证据。
+- 若 skill 与安装版本不符，以公开类型和实际行为核验。先使用已支持能力；任务要求升级时按 [hai-framework-sync](../hai-framework-sync/SKILL.md) 发现目标、比较差异并完成迁移验证。不能直接复制未发布源码的 API，也不能为绕过差异添加虚构兼容层。
+
+### 页面与布局
+
+纯展示官网可用website模板加`--features none`明确空选择，默认模板行为不变；none不能与其他模块/空项混用。静态发布使用`HAI_BUILD_STATIC=1`及公开`PUBLIC_BASE_PATH`（如/hai-framework，无末尾/），先确认没有服务端业务模块/API/actions。它不启用数据库/IAM、不放宽生产守卫，也不赋予静态联系表单发送能力；构建和实际子路径验证按[hai-build](../hai-build/SKILL.md)。
+
+网站挂载到`/yyy/`等目录时，按[网站挂载目录](../hai-build/paths.md)同步资源、链接、认证端点和服务端守卫。SvelteKit在编译时固定base，Vite默认相对资源加hash导航；API基址单独配置。SDK子目录制品使用格式5，健康与增量检查随制品处理，不手工修改旧格式清单来代替重新构建。
+
+页面共用根布局的 header/footer。独立移动应用的页面放在 `src/lib/pages/**/*.svelte`，Fullstack 放在 `packages/<name>-shared/src/lib/pages/**/*.svelte`，由 `HashRouter` 和 `import.meta.glob` 自动发现；新增页面无需修改路由表，菜单按业务配置入口。SvelteKit 保留 `src/routes/**/+page.svelte` 自动文件路由、服务端鉴权和刷新定位。
+
+### 环境配置
+
+应用运行参数集中在各项目的环境文件。公共文件只保存可公开的值，凭据写入本机覆盖或由部署平台注入。
+
+| 文件           | 用途                                                   | Git    |
+| -------------- | ------------------------------------------------------ | ------ |
+| `.env.example` | 所有可用字段的示例、用途、枚举和范围；可选字段保留注释 | 提交   |
+| `.env`         | 所有环境共用的公共基础配置                             | 提交   |
+| `.env.dev`     | 开发环境公共覆盖                                       | 提交   |
+| `.env.test`    | 测试环境公共覆盖                                       | 提交   |
+| `.env.prod`    | 生产环境公共覆盖                                       | 提交   |
+| `.env.local`   | 当前机器的私有配置，覆盖公共配置                       | 不提交 |
+
+YAML 使用 `${HAI_DB_TYPE:sqlite}` 等显式引用，冒号后是未配置时的本地默认值。应用仍通过 `core.config.validate(name, ModuleConfigSchema)` 和模块初始化校验类型、枚举、范围和必填项；插值本身不能代替校验。只开启实际使用的模块，未启用模块的整份 YAML 保留注释。
+
+生产禁止使用进程内或节点本地状态。CLI 的 `.env.prod` 按已启用模块选择 PostgreSQL（保留明确选择的 MySQL）、Redis、S3、Qdrant，默认 Compose DNS 为 `db/cache/storage/vecdb`，容器外运行用私有环境覆盖连接地址。必须私有注入密码、S3/模型凭据及受保护 Qdrant 的 API Key。AI 硬依赖 reldb+vecdb，按数据库→向量库→AI 初始化，失败逆序释放并检查关闭结果，清理失败保留重试义务。生产 Reach 必须私有注入真实 `HAI_REACH_PROVIDERS` JSON；公共空数组有意拒绝启动，不能沿用 console。`hai add ai` 补包与配置，但现有业务入口仍须接入相同生命周期。
+
+#### 命名和类型
+
+- `HAI_<配置名>_<字段路径>`：`_db.yml` 的 `type` 对应 `HAI_DB_TYPE`；`_ai.yml` 的 `llm.apiKey` 对应 `HAI_AI_LLM_APIKEY`。camelCase 不拆词，数组使用从零开始的索引，如 `HAI_AI_AUDIO_MODELS_0_BASEURL`。
+- 框架配置统一采用路径命名，如 `HAI_REACH_PROVIDERS_0_PASS`。第三方 SDK 自身读取的 `OPENAI_API_KEY` 等外部变量保留厂商约定；应用 YAML 使用框架标准名。
+- 完整变量引用按 YAML 标量还原类型：布尔用 `true/false`，数字不带单位；要保留看似数字/布尔的字符串，在环境值中保留 YAML 引号，例如 dotenv 中 `HAI_AI_LLM_APIKEY='"123456"'`。空字符串保持为空字符串。
+- `HAI_DB` 等父级变量可用 JSON/YAML 整体替换对象，优先于子级变量；非必要不整体覆盖，避免遗漏字段。
+- `PUBLIC_` / `VITE_` 只用于浏览器可见的 API 地址和非敏感参数。业务正文、模板 ID、表名/列名及数据结构留在代码/YAML；环境参数不能改变固定表结构契约。
+
+#### 加载与启动
+
+| 入口             | 开发       | 测试环境                 | 生产环境                                      |
+| ---------------- | ---------- | ------------------------ | --------------------------------------------- |
+| Vite / SvelteKit | `pnpm dev` | `pnpm dev:test`          | `pnpm dev:prod` 预览；build 不选择环境 |
+| Node service     | `pnpm dev` | 构建后 `pnpm start:test` | 构建后 `pnpm start:prod`                      |
+
+`hai create` 为 fullstack 在 `.env.dev/.env.test/.env.prod` 各自生成不同的 `HAI_ADMIN_DEFAULT_PASSWORD` 和 `HAI_CRYPTO_TRANSPORT_SERVERKEYRING`；API 启用 crypto 时也分别生成 ring。提交这些环境文件后，克隆用户共享对应环境的初始凭据；`.env.local` 默认只保留覆盖说明，进程环境仍最高。运行时不生成或轮换 ring，所有同环境节点使用同一 ring。模板默认 `pretty` 并声明运行依赖 `pino-pretty`，需要 JSON 时覆盖 `HAI_CORE_LOGGING_FORMAT`。启动失败检查模块、错误码和字段路径；监听冲突检查 `EADDRINUSE` 的地址与端口。
+
+所有入口优先级一致：**进程环境 > `.env.local` > `.env.<dev|test|prod>` > `.env`**。Vite 配置在 Node 阶段通过 `core.config.loadEnvFiles({ mode, envDir })` 读取，检查 `success` 后注入进程；`development`/`production` 分别映射到 `dev`/`prod`。Node 服务按 `.env`、环境文件、`.env.local` 的顺序传入 `--env-file`，后者覆盖前者，已有进程环境最高。`core.init` 只读取已注入的变量，不自行读取 dotenv。
+
+托管 `test:e2e` 是明确的隔离测试入口：服务子进程使用本轮绝对数据目录和完整模块配置，不继承 ambient 模块变量，也不读取用户 `.env.local`。Svelte 仅在 `HAI_E2E=1` 的测试分支跳过 dotenv；API 测试直接执行已构建产物。普通开发与生产的上述优先级和共享后端守卫保持不变，transport 使用测试独立可信 ring 与实际 registry。
+
+`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` 返回。
+
+#### 迁移已有项目
+
+先把原来被忽略的 `.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` 为准，同步迁移部署平台变量和本机文件。
+
+原 `HAI_AI_ANTHROPIC_API_KEY` / `HAI_AI_ANTHROPIC_BASE_URL` 不再使用。默认协议为 `anthropic` 时改用标准 LLM 变量；混合模型池中有独立凭据或端点时，将 `apiKey` / `baseUrl` 配置在对应模型项。厂商回退 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 保留，优先级以 AI 模块说明为准。
+
+#### 常用变量及约束
+
+| 变量                                                              | 说明与取值约束                                                                         |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `HAI_CORE_ENV`                                                    | `development \| test \| production \| staging`                                         |
+| `HAI_CORE_LOGGING_LEVEL`                                          | `trace \| debug \| info \| warn \| error \| fatal`                                     |
+| `HAI_CORE_LOGGING_FORMAT`                                         | `json \| pretty`                                                                       |
+| `HAI_DB_TYPE`                                                     | `sqlite \| postgresql \| mysql`                                                        |
+| `HAI_DB_DATABASE`                                                 | SQLite 文件路径或 `:memory:`；网络数据库为数据库名                                     |
+| `HAI_DB_HOST` / `HAI_DB_PORT` / `HAI_DB_USER` / `HAI_DB_PASSWORD` | 主机、整数端口 1–65535、用户名、敏感密码；PostgreSQL 常用 5432，MySQL 常用 3306        |
+| `HAI_DB_URL` / `HAI_DB_SSL`                                       | 非空连接 URL 优先于拆分字段；MySQL TLS 仅 false 或严格对象（{} 默认验证证书链和 DNS 身份）；PostgreSQL 接受其布尔/字符串模式或对象    |
+| `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_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                                        |
+
+其余变量逐项见对应 `.env.example` 及模块公开 Schema；可选块启用后也应使用相同命名、显式引用与逐项说明。
+
+#### 跨环境切换数据库
+
+保持 `_db.yml` 不变，在公共 `.env.test` 设置：
+
+```dotenv
+HAI_DB_TYPE=sqlite
+HAI_DB_DATABASE=:memory:
+```
+
+在公共 `.env.prod` 设置非敏感连接参数，密码由生产进程或目标机器 `.env.local` 注入：
+
+```dotenv
+HAI_DB_TYPE=postgresql
+HAI_DB_DATABASE=my_app
+HAI_DB_HOST=db.internal
+HAI_DB_PORT=5432
+HAI_DB_USER=my_app
+# 在目标环境注入 HAI_DB_PASSWORD，或提供完整 HAI_DB_URL。
+HAI_DB_SSL=require
+```
+
+切换到 MySQL 时相应设置 `HAI_DB_TYPE=mysql`、端口和凭据，并把 `HAI_DB_SSL=require` 改为严格 TLS 对象，例如 `HAI_DB_SSL='{}'`（默认校验证书链和 DNS 身份）；自签 CA 使用 `ca` PEM，mTLS 的 `cert` / `key` PEM 必须成对。私钥仅放被忽略的 `.env.local` 或目标进程环境。确保项目已安装所选 Provider 的驱动；数据库数据迁移另行执行，切换配置不会搬迁数据。缓存切到 Redis、存储切到 S3 时同样填写对应连接字段。
+
+## CLI 安装与命令
+
+CLI 的 npm 包名是 `@h-ai/cli`，安装后提供 `hai` 命令。使用脚手架前先全局安装并确认版本；PowerShell 中使用 `pnpm.cmd` 执行 pnpm 命令。
+
+```bash
+pnpm add -g @h-ai/cli
+hai --version
+hai --help
+
+# 新建项目
+hai create my-app
+```
+
+已有项目先进入项目根目录，再按需要执行 `hai add <module>`、`hai init` 或 `hai generate <type> <name>`。已安装 CLI 时，相同安装命令可更新到当前发布版本；需要指定版本时使用 `@h-ai/cli@<version>`。命令和模板以实际安装的 CLI 为准，不能把未发布的框架源码能力当作已安装包能力。
+
+`hai generate page` 只写 SvelteKit 文件路由；`api` 按目标应用生成 SvelteKit 端点或 serv 的共享 contract/procedure 并接入已有聚合入口。API/fullstack 根自动选择唯一后端，多个候选用 `--workspace <包名或相对路径>`，也可进入目标 workspace。纯 Vite 不生成虚假文件路由；serv 不接受 `--output`，SvelteKit 输出限定 `src/routes` 内，定制 `kit.files` 时拒绝猜测；SvelteKit API 目标须已安装 `@h-ai/kit` 与 `zod`。不要删除模板 `@hai-generator` 聚合标记；自定义入口没有标记时手动沿现有架构接入。生成前统一校验路径和覆盖冲突，失败回滚本次修改；`--force` 不能覆盖已有业务领域注册。
+
+CLI 用户消息通过现有中英字典输出。初始语言按非空的 `HAI_CORE_DEFAULTLOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG` 选择，`en`/`zh` 地区变体映射到现有语言，`C`/`POSIX` 为英文；未知语言保留 core 当前语言（默认中文）。CLI 内部命令响应 `core.i18n.setGlobalLocale('en-US')` 的同进程切换；包入口仍为命令行入口，不提供库调用 API。`hai generate` 省略类型/名称会交互，取消不写文件；生成源码的中文注释与用户名称不翻译。
+
+`create` / `add` / `init` 的校验、选择项、模块/模板名称与描述、错误前缀及完成提示也使用当前 CLI locale；目录标签延迟求值。CLI 语言不修改生成应用的 `core.defaultLocale`。生成的中文 README、YAML/源码注释与外部工具原始错误保留原样；不要把这些正文机械替换成终端翻译。
+
+## 将需求映射到现有能力
+
+应用元信息只有一份配置来源：名称、版本、环境、默认语言与日志设置来自 `_core.yml`，使用 `core.config` 与 `core.logger`；Node 启动时不通过固定 `logging` 覆盖 YAML。SvelteKit 服务端 layout 和 fullstack `app.info` 仅公开必要元信息，不能下发整个 core 或模块配置。独立 Vite 客户端经 Node/core 加载 YAML 默认值，Web 部署通过 `runtime-config.js` 应用公开白名单覆盖；只修改部署覆盖无需重建，修改构建默认值则须重新构建。环境覆盖使用 `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。
+
+| 需求 | 优先检查的能力与 skill | 使用边界 |
+| --- | --- | --- |
+| 配置、日志、ID、结果/错误、i18n | `hai-core` | getter、logger、ID 是直接值；ID 不作为密钥 |
+| 数据库查询、CRUD、事务、分页 | `hai-reldb` | 先检查现有 CRUD/Repository 与事务支持，不另建 DB 连接层 |
+| 缓存、TTL、共享锁 | `hai-cache` | 区分 memory 与共享后端；单进程状态不能承担跨节点防重 |
+| 注册、登录、会话、角色/权限 | `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；大文件用流式读写，checksum 按实际字节计算，ifNoneMatch 拒覆盖；资源授权、大小/类型/路径限制不可省略 |
+| 加密、签名、哈希 | `hai-crypto` | 复用公开 API 与密钥配置，不自创加密或硬编码密钥 |
+| LLM、流式、Embedding、RAG、Agent/MCP | `hai-ai` | 先检查内置能力与 provider 配置，再补应用编排 |
+| 文本清洗、分块、管线 | `hai-datapipe` | 纯函数无生命周期；分块不代表已经生成向量 |
+| 向量集合与检索 | `hai-vecdb` | 后端、维度与过滤条件使用实际契约 |
+| 邮件/短信/通知触达 | `hai-reach` | 模板已绑定 provider 时只传 template/to/vars；直接发送才指定 provider；投递状态不等于 HTTP 成功 |
+| 支付、订单、订阅、回调 | `hai-payment` | 验签、金额/订单绑定、幂等与状态迁移仍需业务验收 |
+| 操作审计 | `hai-audit` | 复用审计记录/查询与 PaginatedResult 元数据；应用决定脱敏、保留期及失败策略 |
+| cron、持久任务、重试、手工触发 | `hai-scheduler` | 复用任务模型；明确取消、幂等、共享锁及可信代码边界 |
+| 原生设备与安全 token 存储 | `hai-capacitor` | 仅在适用平台启用；桌面/小程序依当前项目适配 |
+
+已有能力满足需求时使用它；已导入模块但仍手写其已有认证、缓存、上传、分页或 UI 功能，需要修正。确有缺口时记录缺失的具体能力、当前版本和最小补充方案，按需求增加依赖或应用代码；不为凑模块覆盖率增加服务和抽象。
+
+独立 fullstack 默认后台的 Web/App/Desktop 共用管理组件、状态与 typed client。`@h-ai/serv/features/iam` 默认 procedures 可按需选用并与 contract 对齐；有业务缺口时覆写必要路由。主题的 DOM 更新和安全缓存使用 `@h-ai/ui/theme`（`applyTheme` / `getSavedTheme`），应用保留响应式状态与已编译主题白名单。初始 admin/user、管理员自我保护、头像限额、分页和审计策略都是应用示例，可按需求替换；实际权限、资源范围和写入一致性按目标业务落实。
+
+Fullstack 创建时在根 `.env.dev/.env.test/.env.prod` 分别写入独立随机 `HAI_ADMIN_DEFAULT_PASSWORD`，提交后克隆共享，`.env.example` 保留空占位。`dev` / `start` 自动读取；已有用户不重设密码。启动边界保留模块错误的具体说明与错误码，失败后反序清理。不能把环境凭据复制到前端配置、日志、源码或镜像。
+
+## 落实契约与安全边界
+
+沿现有服务层按顺序落实 schema → 当前授权与操作权限 → 从资源 ID 查所有者/范围 → 需要时核验对应操作凭据 → 存储/通知等副作用 → HaiResult 与审计。框架身份授权不能替代业务资源范围，数据库实体/存储 key 不交给客户端决定。文件失败、checksum 不匹配、不可覆盖冲突及通知失败/延迟分别向调用方反馈，并按业务一致性要求事务回滚或补偿；不能静默返回成功。
+
+按本次真实输入、资源和副作用选取下面检查，并把适用项变成可观察验收。不能用“已遵循安全规范”或 lint 通过替代行为证据。
+
+| 边界 | 实现要求 | 验收证据 |
+| --- | --- | --- |
+| 输入与输出 | 外部输入在请求/contract 边界 schema 校验，限制长度、分页、大小与合法枚举；从公开类型推导共享结构 | 非法/超限输入被拒绝，未触发写入或外部副作用；输出符合 contract |
+| 身份与资源 | 使用对应架构守卫；另查资源所有者、租户、角色/权限；不能信任客户端传来的 userId/tenantId | 未登录、缺权限、跨用户/租户访问失败；正常路径可用 |
+| SQL、文件、URL、内容 | SQL 值参数化，动态标识符白名单；文件防路径逃逸；用户控制的服务端请求 URL 限制目的地；HTML/AI 内容按不可信输入处理 | 相关注入/逃逸/越界目的地被拒绝；正常输入仍可用 |
+| 凭据与会话 | 密钥仅服务端配置/环境，`.env.example` 只放占位；PUBLIC/VITE 配置不含密钥。沿用 Cookie/内存 token，原生用安全 TokenStorage；检查 CORS、Cookie、CSRF 与现有管道 | 浏览器产物/日志无敏感内容；登录/退出/刷新及适用的跨域攻击失败路径可验证 |
+| HaiResult 与错误 | HaiResult 型业务 API 先判断 `success`，服务层保留错误；HTTP 边界沿实际包络/状态契约并隐藏内部敏感细节。显式抛错、流迭代与 SvelteKit 控制流按各自契约 | 依赖失败不回退为空列表/成功消息；流失败与业务状态失败有反馈，用户输入得到保留 |
+| 初始化与清理 | 只对有生命周期的模块按依赖 init → use → close；检查每次结果，关键依赖失败停止启动，清理已创建资源，关闭反序 | 初始化失败不能继续执行业务；关闭/取消后连接、监听器与任务退出 |
+| 写入与重试 | 多步一致性用事务或明确补偿；重试/回调/任务定义幂等；跨节点业务状态使用共享存储 | 中途失败无不一致写入；重复请求/回调不产生重复副作用 |
+| 风格与可维护性 | 禁止 `any`、无说明的 `as unknown as T`、`console.log`、硬编码密钥；注释中文、日志英文且脱敏；文案使用现有 i18n 并同步中英日文；遵循项目实际 lint 配置 | typecheck/lint 通过；人工核对脱敏、文本、分层与不受 lint 覆盖的规则 |
+
+不把所有函数改成 HaiResult：纯工具、getter、工厂、客户端/流及控制流按实际签名。不把所有模块加上 init/close。应用服务根据已有业务契约返回 HaiResult，HTTP/UI 层做适当转换。
+
+serv/oRPC 普通 procedure 返回的失败 HaiResult 可以位于 HTTP 200 包络，`error.httpStatus` 是错误元数据，不等于响应状态；输入 schema 校验、传输错误、路由中间件及 kit 的 Response 各有状态契约。验收同时检查响应体 `success/error.code` 和真实 HTTP 状态，不照搬另一架构的 401/500 断言，也不以 HTTP 200 判为业务成功。
+
+## JSDoc 注释
+
+所有导出函数、核心业务流程、表/列、接口/type/schema 及字段提供中文 JSDoc，说明用途、约束、单位、关联及失败行为，并包含 `@example`。函数用实际的 `@param` / `@returns`，仅会抛错的契约写 `@throws`；数据结构给合法数据，数据库表说明主外键、可空性、默认值、唯一约束和典型行。核心逻辑解释决策与边界，避免重复代码字面含义。
+
+```ts
+/**
+ * 分页输入；page 从 1 开始，pageSize 为 1–100。
+ * @example const query: PageQuery = { page: 1, pageSize: 20 }
+ */
+export interface PageQuery {
+  /** 当前页，最小为 1。 */
+  page: number
+  /** 每页记录数，最大为 100。 */
+  pageSize: number
+}
+
+/**
+ * 将已校验的分页参数转换为数据库偏移量。
+ * @param query - 已通过边界 Schema 校验的分页参数
+ * @returns 从零开始的偏移量
+ * @example pageOffset({ page: 2, pageSize: 20 }) // 20
+ */
+export function pageOffset(query: PageQuery): number {
+  return (query.page - 1) * query.pageSize
+}
+```
+
+## 验证与交付
+
+测试临时工程、镜像、容器、辅助进程与数据须在 finally/teardown 自动清理，成功、失败和取消均执行；只清理本次创建的资源。日志、截图与报告保留到分析和交付结束再清理，不提交验收产物。
+
+- 对新增/改变行为按 [hai-app-tests](../hai-app-tests/SKILL.md) 写有意义的测试；目标用例先因行为缺失失败，既有回归保持通过。UI/路由改动覆盖真实流程、异步失败与权限路径；纯文案/文档按影响验证。
+- 从当前 `package.json` 选择实际脚本，优先 workspace filter，PowerShell 使用 `pnpm.cmd`。多项门禁按 [分轮验证与集中修复](../hai-app-tests/validation.md) 先脚本化收集结果和日志，再集中修复、复测失败及受影响项；普通失败不立即从头重跑。不能调用框架仓库私有命令替代应用检查。
+- typecheck/lint 只覆盖部分质量规则；权限、事务、降级、真实 provider、浏览器、容器和原生交付各自需要适用行为证据。缺环境或密钥时报告未验证，不能用 mock 冒充真实集成。
+- 完成说明：实际复用能力与自定义缺口、修改路径、已执行命令/行为结果、同步的 contract/调用方/配置/i18n/文档、未验证项及原因。无需无关模块的“覆盖率”清单。
+
+`_core.yml` 只接受 name/version/env/defaultLocale 元数据与 logging；不提供 debug、全局ID设置、features或supportedLocales。业务开关放app.yml并用业务Schema校验；语言列表按实际翻译工程维护，日志用logging.level。core默认语言字段不会自动注册翻译。Logger导入保留LANG/LC_ALL/PYTHONIOENCODING，终端语言优先级不能被编码初始化覆盖。
+
+框架环境目录从真实入口生成；JS/TS（含 Svelte script）中的 JSDoc 示例不构成新运行变量。Schema 字段注释仍生成用途说明，YAML/模板可选注释和字符串内生成代码引用继续保留；不能只在示例里写变量就声称已被实现消费。
+
+公开导入以安装版本的 package.json.exports 为准：只使用已声明且有真实产物的根/子路径，不导入 src/dist 或内部 Provider/Deps。条件入口可以只提供配置和类型；IAM 浏览器入口不含服务端 iam 对象。Svelte 默认组件和明确的 selective/type-only 导出均合法，不能为形式统一扩大公共 API。