@h-ai/cli 1.0.0-beta.19 → 1.0.0-beta.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +69 -197
- package/README.ja.md +69 -197
- package/README.md +69 -197
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/metafile-esm.json +1 -1
- package/package.json +14 -14
- package/templates/README.md +40 -35
- package/templates/apps/api/apps/{{projectName}}-contract/README.md.hbs +8 -0
- package/templates/apps/api/apps/{{projectName}}-serv/README.md.hbs +3 -1
- package/templates/apps/fullstack/apps/{{projectName}}-app/README.md.hbs +5 -7
- package/templates/apps/fullstack/apps/{{projectName}}-desktop/README.md.hbs +6 -8
- package/templates/apps/fullstack/apps/{{projectName}}-miniapp/README.md.hbs +2 -0
- package/templates/apps/fullstack/apps/{{projectName}}-web/README.md.hbs +6 -8
- package/templates/apps/fullstack/packages/{{projectName}}-contract/README.md.hbs +7 -5
- package/templates/apps/fullstack/packages/{{projectName}}-serv/README.md.hbs +9 -0
- package/templates/apps/fullstack/packages/{{projectName}}-shared/README.md.hbs +48 -68
- package/templates/base/package.json.hbs +1 -1
- package/templates/skills/hai-ai/guide.md +3 -1
- package/templates/skills/hai-ai/reference.md +2 -2
- package/templates/skills/hai-deploy/SKILL.md +2 -0
- package/templates/skills/hai-ui/SKILL.md +1 -1
- package/templates/skills/hai-ui/reference.md +1 -0
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@h-ai/cli",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "1.0.0-beta.
|
|
4
|
+
"version": "1.0.0-beta.20",
|
|
5
5
|
"description": "Hai Framework CLI for project scaffolding and code generation.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"keywords": [
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"node": "^22.23.4 || ^24.22.1 || ^26.12.1"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@h-ai/core": "1.0.0-beta.
|
|
33
|
+
"@h-ai/core": "1.0.0-beta.20",
|
|
34
34
|
"cac": "^7.1.0",
|
|
35
35
|
"chalk": "^6.0.1",
|
|
36
36
|
"fast-wrap-ansi": "^0.2.2",
|
|
@@ -41,18 +41,18 @@
|
|
|
41
41
|
"yaml": "^2.9.1"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
-
"@h-ai/api-client": "1.0.0-beta.
|
|
45
|
-
"@h-ai/cache": "1.0.0-beta.
|
|
46
|
-
"@h-ai/crypto": "1.0.0-beta.
|
|
47
|
-
"@h-ai/deploy": "1.0.0-beta.
|
|
48
|
-
"@h-ai/feedback": "1.0.0-beta.
|
|
49
|
-
"@h-ai/iam": "1.0.0-beta.
|
|
50
|
-
"@h-ai/kit": "1.0.0-beta.
|
|
51
|
-
"@h-ai/payment": "1.0.0-beta.
|
|
52
|
-
"@h-ai/reach": "1.0.0-beta.
|
|
53
|
-
"@h-ai/reldb": "1.0.0-beta.
|
|
54
|
-
"@h-ai/storage": "1.0.0-beta.
|
|
55
|
-
"@h-ai/vecdb": "1.0.0-beta.
|
|
44
|
+
"@h-ai/api-client": "1.0.0-beta.20",
|
|
45
|
+
"@h-ai/cache": "1.0.0-beta.20",
|
|
46
|
+
"@h-ai/crypto": "1.0.0-beta.20",
|
|
47
|
+
"@h-ai/deploy": "1.0.0-beta.20",
|
|
48
|
+
"@h-ai/feedback": "1.0.0-beta.20",
|
|
49
|
+
"@h-ai/iam": "1.0.0-beta.20",
|
|
50
|
+
"@h-ai/kit": "1.0.0-beta.20",
|
|
51
|
+
"@h-ai/payment": "1.0.0-beta.20",
|
|
52
|
+
"@h-ai/reach": "1.0.0-beta.20",
|
|
53
|
+
"@h-ai/reldb": "1.0.0-beta.20",
|
|
54
|
+
"@h-ai/storage": "1.0.0-beta.20",
|
|
55
|
+
"@h-ai/vecdb": "1.0.0-beta.20",
|
|
56
56
|
"@types/fs-extra": "^11.0.4",
|
|
57
57
|
"@types/node": "^26.6.6",
|
|
58
58
|
"@types/prompts": "^2.4.9",
|
package/templates/README.md
CHANGED
|
@@ -1,65 +1,70 @@
|
|
|
1
1
|
# CLI 项目模板
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
本目录供 `hai create/add/init` 组合应用源码、配置、脚本和AI指引；维护者在这里修改生成源，接入应用使用生成后的工程。模板不承担应用自身的业务授权和数据恢复。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 快速开始
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
在框架根构建CLI，再生成独立工程检查模板效果：
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- 后台工作区随窗口扩展；手机壳支持宽屏，表格在内部滚动，文章与认证表单保留阅读宽度。
|
|
14
|
-
- 默认部署工具、独立镜像 Dockerfile、环境示例和可复制的 AI 技能。
|
|
9
|
+
```sh
|
|
10
|
+
pnpm --filter @h-ai/cli build
|
|
11
|
+
node packages/cli/dist/index.js create ../template-probe --type website --defaults --no-install --no-git
|
|
12
|
+
```
|
|
15
13
|
|
|
16
|
-
|
|
14
|
+
输入模板种类与工程名，输出新目录中的源码、README、配置、Dockerfile及适用技能。随后在该工程安装并验证；仅检查 `.hbs` 语法不能证明生成结果能运行。
|
|
15
|
+
|
|
16
|
+
## 功能
|
|
17
17
|
|
|
18
18
|
### 文件如何组合
|
|
19
19
|
|
|
20
|
-
| 目录
|
|
21
|
-
|
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
20
|
+
| 目录 | 场景、输入与输出 |
|
|
21
|
+
| ------------------- | ------------------------------------------------------------------------------------- |
|
|
22
|
+
| base/ | 普通应用共享基础；输入渲染上下文，输出配置、脚本和入口 |
|
|
23
|
+
| apps/ | 按admin/website/h5/api/mobile-app/fullstack选择骨架；API/fullstack有独立workspace结构 |
|
|
24
|
+
| features/ | 叠加实际模块所需路由与页面；不把Serv套成SvelteKit文件路由 |
|
|
25
|
+
| i18n/ | 生成Paraglide工程与应用消息；默认中英日文 |
|
|
26
|
+
| shared/ | 原生显示名、Tauri入口及跨模板文件约定，避免各模板复制不同规则 |
|
|
27
|
+
| skills/ 与 bridges/ | 输出完整 `.agents/skills/` 及根AGENTS入口，工具配置只桥接共享规则 |
|
|
28
|
+
|
|
29
|
+
普通文件复制，`.hbs` 由Handlebars渲染并去后缀。`cli-template-engine.ts` 选择目录/条件，`cli-create.ts` 编排配置、镜像与README生成。例如website输出Core/Kit/UI展示站，fullstack输出contract、Serv、共享UI及所选Web/App/Desktop；miniapp仅为预留说明。
|
|
30
|
+
|
|
31
|
+
### 生成上下文与配置
|
|
27
32
|
|
|
28
|
-
|
|
33
|
+
上下文含 `projectName/appType/features/hasUi/hasI18n/versions` 和 `api/fullstack` 形状，定义见[CLI类型](../src/cli-types.ts)。模块YAML使用 `moduleConfig` helper，字段和默认值由[配置生成器](../src/commands/cli-config-templates.ts)共同维护。
|
|
29
34
|
|
|
30
|
-
|
|
35
|
+
输入启用模块后，输出对应依赖、有效配置及公共环境默认；未使用模块保留注释示例。新功能仍须接入校验、初始化、关闭和业务路由，不能仅取消YAML注释。`hai add/init` 补缺失项并保留自定义文件。
|
|
31
36
|
|
|
32
|
-
|
|
37
|
+
### 构建、原生名称与部署
|
|
33
38
|
|
|
34
|
-
|
|
39
|
+
部署工具默认是开发依赖，`--no-deploy` 可省略。`hai.json.build.images` 指向images内独立Dockerfile，Web资源在images/web。构建器生成images/dependencies，根gitignore忽略该缓存、运行数据和私有环境。
|
|
35
40
|
|
|
36
|
-
|
|
41
|
+
Dockerfile使用全局HAI_NODE_IMAGE/HAI_NGINX_IMAGE及构建阶段HAI_NPM_REGISTRY接收下载设置，代理只用于构建，不进入运行镜像。pnpm下载采用追加日志，Windows转发保留警告、错误和统一换行。[下载源契约](skills/hai-build/reference.md#下载源与代理)
|
|
37
42
|
|
|
38
|
-
|
|
43
|
+
产物使用工程标识，批次名为 `build-<工程>-<目标>-YYYYMMDD-HHmmss-<随机串>-<版本>`，latest保存相对批次名。输入一个Core展示名后，Capacitor的appName和Tauri产品/主窗口名使用该值；Fullstack读取Serv的Core，独立mobile读取自身Core。只投影名称，不下发完整配置。辅助窗口及后续显式Tauri配置保持自身优先级。[名称与构建](../../../docs/usage/getting-started/build.md#原生应用名称)
|
|
39
44
|
|
|
40
|
-
|
|
45
|
+
### 服务端边界与页面
|
|
41
46
|
|
|
42
|
-
|
|
47
|
+
SvelteKit服务端固定加载Kit配置，根load只投影公开transport。选择crypto后，hooks从私有环境装配密钥环和registry；共享DB用于共享registry，内存仅开发/测试。纯客户端不生成服务端私钥。输入冲突路径策略或缺少required加密依赖时，创建宿主应失败。
|
|
43
48
|
|
|
44
|
-
|
|
49
|
+
页面文字走应用messages，认证复用AuthPanel及公开IAM配置，表单使用Form/FormLayout/FormField。输入无效表单时保留草稿、显示安全Toast和可访问错误关联；默认角色、流程和限额由业务决定，并在服务端授权。宽屏工作区可扩展，窄屏表格内部滚动，阅读内容保留合适宽度。
|
|
45
50
|
|
|
46
|
-
|
|
51
|
+
### AI指引
|
|
47
52
|
|
|
48
|
-
|
|
53
|
+
复制skill完整目录及其相对参考文件，并按应用架构排除不适用能力；引用不得回到框架私有目录。输入website或fullstack两种架构时，输出应各自形成可独立使用的引用闭包。Claude/Copilot/OpenCode仅引用AGENTS和共享规范，不复制长正文。调整公共契约时同步实现、配置、示例、调用方与skills。
|
|
49
54
|
|
|
50
|
-
|
|
55
|
+
## 配置
|
|
51
56
|
|
|
52
|
-
`
|
|
57
|
+
模板参数在生成阶段消费，生成应用通过自身 `config/`、环境与宿主参数配置运行。环境公共值与私有秘密分开，版本固定到CLI对应框架发布；pnpm补丁注册必须连同实际patch文件复制。[应用配置手册](../../../docs/usage/configuration/README.md)
|
|
53
58
|
|
|
54
|
-
|
|
59
|
+
维护 `shared/.gitattributes`，使Dockerfile、dockerignore和POSIX脚本输出LF。原生工程名、API公开地址、网站basepath与服务器私密配置职责独立，不将完整服务端配置投影到浏览器或原生打包工具。
|
|
55
60
|
|
|
56
|
-
|
|
61
|
+
## 错误处理
|
|
57
62
|
|
|
58
|
-
|
|
63
|
+
模板渲染失败应指出文件/步骤并停止，不以部分产物当成功。生成后的校验或构建失败回到所属模板修复，不能只手工修一份测试工程。私钥、凭据和完整用户数据不进入错误正文。缺失依赖、非法路径、引用不完整和不支持的架构组合要明确拒绝。
|
|
59
64
|
|
|
60
65
|
## 开发测试
|
|
61
66
|
|
|
62
|
-
|
|
67
|
+
在仓库根按实际影响选择：
|
|
63
68
|
|
|
64
69
|
```sh
|
|
65
70
|
pnpm --filter @h-ai/cli typecheck
|
|
@@ -71,7 +76,7 @@ pnpm --filter @h-ai/cli test:scaffold-gates
|
|
|
71
76
|
pnpm --filter @h-ai/cli test:deploy-gates
|
|
72
77
|
```
|
|
73
78
|
|
|
74
|
-
|
|
79
|
+
脚手架门禁真实安装、类型/lint、构建、测试和浏览器流程；部署门禁需可用Podman/Docker，并验证实际镜像、SSH/手工适用及部分更新。原生设备和第三方线上服务另需对应环境。仅文案改动不代表重跑过所有运行场景。
|
|
75
80
|
|
|
76
81
|
## 许可证
|
|
77
82
|
|
|
@@ -14,6 +14,14 @@
|
|
|
14
14
|
|
|
15
15
|
### 包含内容
|
|
16
16
|
|
|
17
|
+
输入输出约定由Schema共享，客户端先检查 `success` 再取 `data`：
|
|
18
|
+
|
|
19
|
+
| 功能 | 输入示例 | 成功输出与边界 |
|
|
20
|
+
| --- | --- | --- |
|
|
21
|
+
| app.info | 无业务参数 | name/version/env/defaultLocale/uptimeMs/transportEnabled；只返回公开元信息 |
|
|
22
|
+
| app.echo | `{ message: 'hello' }`，1–2000字符 | 同一message及requestId/timestamp，可含userId；演示回显，不写业务数据 |
|
|
23
|
+
| 工程contract | 聚合应用与已启用模块契约 | Serv与typed client使用同一输入/输出类型；声明不替代服务端授权 |
|
|
24
|
+
|
|
17
25
|
- `app-contract.ts`：应用级接口定义，业务 path 与一次性输出 Schema 就近内联
|
|
18
26
|
- `app-schemas.ts`：跨接口、跨层复用的输入/数据 Zod Schema
|
|
19
27
|
- `{{projectName}}-contract.ts`：工程级 contract 聚合入口
|
|
@@ -19,10 +19,12 @@ pnpm --filter {{api.servPackageName}} dev
|
|
|
19
19
|
pnpm --filter {{api.servPackageName}} test
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
+
启动读取本服务配置并校验依赖。默认健康入口 `GET /health` 返回可达状态，`POST /api/v1/app/info` 返回公开服务信息；路径按 `_serv.yml` 调整。`app.echo` 输入 `{ message: 'hello' }`，成功输出相同message、请求编号和时间；按已装配客户端/传输协议调用，不把curl明文当启用加密后的通用调用方式。启用的认证/反馈/存储等模块按根目录及对应skill接入。
|
|
23
|
+
|
|
22
24
|
### 容器运行
|
|
23
25
|
|
|
24
26
|
|
|
25
|
-
- 配置默认打包自本目录 `config
|
|
27
|
+
- YAML配置默认打包自本目录 `config/`，镜像内位于 `/app/config`；SDK部署的私有 `.env.runtime` 另通过 `/run/hai/config` 只读挂载并在启动时读取。修改普通运行配置后重启，端口/网关/挂载变化需重新部署。
|
|
26
28
|
{{#if features.iam}}- 受控内网或 VPN 的生产 HTTP 入口可设置 `HAI_SERV_REFRESH_COOKIE_SECURE=false` 和实际 `HAI_SERV_CORS_ORIGIN`，重新部署后端后重新登录。刷新凭据会经 HTTP 明文传输。
|
|
27
29
|
{{/if}}
|
|
28
30
|
|
|
@@ -20,6 +20,8 @@ App/H5 前端工程，复用 shared 的响应式 mini 后台，使用 Svelte 5 +
|
|
|
20
20
|
|
|
21
21
|
### i18n 与 shared 协同
|
|
22
22
|
|
|
23
|
+
先从工程根安装依赖并启动Serv。浏览器预览输入有效账号应进入共享界面，原生包还要配置设备真实可达API。上传头像的输入为允许类型且不超过512KiB的图片，输出为服务端生成资源标识和展示结果；不把本机任意路径当上传key。主题/语言改变后应在重新登录时恢复。
|
|
24
|
+
|
|
23
25
|
- 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
|
|
24
26
|
- 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
|
|
25
27
|
- 语言切换通过 shared runtime 与本端 `src/lib/paraglide/runtime.js` 同步。
|
|
@@ -49,15 +51,11 @@ pnpm build --target app --platform ios
|
|
|
49
51
|
|
|
50
52
|
Android 容器会安装依赖、编译 workspace 并打包。调试时可临时生成缺失的 Android 工程。发布时使用已有 Android 工程和私有签名配置，见 [Android 容器打包](../../.agents/skills/hai-capacitor/reference.md#android-容器打包)。iOS 使用 macOS/Xcode 和相应签名。`CAPACITOR_SERVER_URL` 仅供开发热更新。成功后 CLI 打印 `.hai/build/app/<平台>/<构建类型>/build-{{projectName}}-app-<平台>-<类型>-YYYYMMDD-HHmmss-<随机串>-<版本>/` 中的安装包路径；APK 如 `{{projectName}}-android-debug-<版本>.apk`，使用工程标识，显示名仍取 Core。
|
|
51
53
|
|
|
52
|
-
###
|
|
53
|
-
|
|
54
|
-
服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
|
|
55
|
-
|
|
56
|
-
LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
|
|
54
|
+
### 认证与模块导航
|
|
57
55
|
|
|
58
|
-
|
|
56
|
+
认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
|
|
59
57
|
|
|
60
|
-
|
|
58
|
+
所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
|
|
61
59
|
|
|
62
60
|
启用反馈时，shared SDK 负责图片预览/比例标注/导出轮询；原生保存使用 Filesystem 缓存与 Share，完成/取消清理临时文件。首次添加 iOS 平台后按 Filesystem 插件要求配置 PrivacyInfo.xcprivacy。
|
|
63
61
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
## 简介
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Tauri v2 + Svelte 5 + Vite桌面工程，前端通过共享contract调用 `{{fullstack.servPackageName}}`。
|
|
8
8
|
|
|
9
9
|
## 核心功能清单
|
|
10
10
|
|
|
@@ -16,6 +16,8 @@
|
|
|
16
16
|
|
|
17
17
|
### i18n 与 shared 协同
|
|
18
18
|
|
|
19
|
+
先从工程根安装依赖、启动Serv并配置实际API地址，再运行tauri:dev。有效账号登录后使用相同共享管理界面；输入受权限允许的管理操作，输出与Web一致。关闭并重启原生程序后内存凭据不保留，需要重新登录；外观/语言属于服务器偏好，登录后恢复。
|
|
20
|
+
|
|
19
21
|
- 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
|
|
20
22
|
- 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
|
|
21
23
|
- 个人设置保存语言与风格偏好到 IAM 元数据，并同步 shared 和本端 Paraglide runtime
|
|
@@ -46,15 +48,11 @@ pnpm build --target desktop --platform windows --arch x64
|
|
|
46
48
|
|
|
47
49
|
加 `--debug` 生成调试安装包。成功后 CLI 打印 `.hai/build/desktop/<平台>/<构建类型>/build-{{projectName}}-desktop-<平台>-<架构>-<类型>-YYYYMMDD-HHmmss-<随机串>-<版本>/` 中的归档路径。Windows 文件名如 `{{projectName}}-windows-x64-release-<版本>-setup.exe`；使用工程标识，产品显示名仍取 Core。
|
|
48
50
|
|
|
49
|
-
###
|
|
50
|
-
|
|
51
|
-
服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
|
|
52
|
-
|
|
53
|
-
LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
|
|
51
|
+
### 认证与模块导航
|
|
54
52
|
|
|
55
|
-
|
|
53
|
+
认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
|
|
56
54
|
|
|
57
|
-
|
|
55
|
+
所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
|
|
58
56
|
|
|
59
57
|
启用反馈时使用 SDK 原生保存对话框，Tauri dialog/fs 插件只允许选择路径后写入。CSP 允许图片和视频 blob 预览、沙箱回放，脚本和网络来源限制保持明确；Web 浏览器验证不代替系统 WebView/安装包验收。
|
|
60
58
|
|
|
@@ -15,6 +15,8 @@
|
|
|
15
15
|
|
|
16
16
|
选定小程序框架后再实现页面、请求适配和认证。小程序文案放本目录 `messages/`，跨端通用内容放 `packages/{{fullstack.sharedPackageName}}`；消息格式插件使用工程根已安装的依赖。
|
|
17
17
|
|
|
18
|
+
例如在messages加入一条中英日文业务提示，当前输出只是可供后续接入的消息资源，不会生成页面或安装包。引用contract只获得输入输出类型，不能自动获得请求传输、登录、安全存储或平台权限。建立真正的小程序工程后再加入workspace、运行脚本和发布流程。
|
|
19
|
+
|
|
18
20
|
## 开发测试
|
|
19
21
|
|
|
20
22
|
本目录不参与 workspace 构建、单元测试或 E2E。接入实际框架后增加对应命令，并在目标平台验证登录、请求、导航与发布包。
|
|
@@ -16,6 +16,8 @@
|
|
|
16
16
|
|
|
17
17
|
### i18n 与 shared 协同
|
|
18
18
|
|
|
19
|
+
从根目录安装依赖并启动Serv，再执行本页dev命令。输入有效测试账号后进入共享管理界面；普通用户只能看到被授权的功能。修改个人资料成功才结束编辑，失败保留输入。个人设置的主题/语言保存后，刷新并重新登录应能恢复。
|
|
20
|
+
|
|
19
21
|
- 本端页面文案：`messages/{locale}.json` + `project.inlang/settings.json`
|
|
20
22
|
- 共享 Shell/主题/语言/API：`packages/{{fullstack.sharedPackageName}}`
|
|
21
23
|
- 个人设置保存语言与风格偏好到 IAM 元数据，并同步 shared 和本端 Paraglide runtime
|
|
@@ -36,19 +38,15 @@ pnpm --filter {{projectName}}-web build
|
|
|
36
38
|
|
|
37
39
|
从工程根运行 `pnpm build --target image` 导出镜像。默认带部署工具，可运行 `pnpm run deploy --env test --build` 一次完成构建发布，或 `pnpm run deploy --env prod --bundle-only` 交付已有镜像及跨平台脚本。完整包包含自建中间件，人工部署与按服务更新见工程根 README。
|
|
38
40
|
|
|
39
|
-
###
|
|
40
|
-
|
|
41
|
-
服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。Memory 仅用于本地开发和显式测试；生产环境即使只有一个实例，也须使用框架支持的共享数据库与 Redis，并按工程根 README 配置写入路由和传输会话。
|
|
42
|
-
|
|
43
|
-
LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise；回调第三参数 context 提供 expiresAt/idempotencyKey，发送服务按稳定键持久化去重，异常/超时为结果未知且不自动重发。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
|
|
41
|
+
### 认证与模块导航
|
|
44
42
|
|
|
45
|
-
|
|
43
|
+
认证方式、注册、密码策略、协议与品牌由Serv的 `_iam.yml` 控制。前端只接收安全公开配置，使用共享AuthPanel和加密typed client；服务端再次核验权限。LDAP、通知回调、用途证明和会话限制在服务端接入，不把私密配置复制到客户端。
|
|
46
44
|
|
|
47
|
-
|
|
45
|
+
所有前端共用的偏好、认证存储、表单、审计与帮助行为见[共享工作区](../../packages/{{fullstack.sharedPackageName}}/README.md)，详细配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。
|
|
48
46
|
|
|
49
47
|
## 开发测试
|
|
50
48
|
|
|
51
|
-
从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e
|
|
49
|
+
从工程根执行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test` 和 `pnpm test:e2e`。浏览器通过后仍需在实际公开地址验证部署、认证与持久数据。
|
|
52
50
|
|
|
53
51
|
## 许可证
|
|
54
52
|
|
|
@@ -14,6 +14,13 @@
|
|
|
14
14
|
|
|
15
15
|
### 骨架说明
|
|
16
16
|
|
|
17
|
+
| 功能 | 输入示例 | 成功输出与边界 |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| app.info | 无业务参数 | notice、名称/版本/环境、语言、启动时间及frontends；只返回公开元信息 |
|
|
20
|
+
| app.echo | `{ message: 'hello' }`，1–200字符 | 相同message、echoedAt、requestId；演示回显，不持久化 |
|
|
21
|
+
| admin契约 | 用户、角色、审计、公告或个人设置操作参数 | 受当前身份/权限与资源范围约束的HaiResult；先检查success再读data |
|
|
22
|
+
| 工程聚合 | app/admin及框架模块contract | Serv和所有前端共用类型，契约声明不会自动授予权限 |
|
|
23
|
+
|
|
17
24
|
- `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
|
|
18
25
|
- `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
|
|
19
26
|
- `src/admin-schemas.ts` / `src/admin-contract.ts`：示例管理员用户、系统/审计/配置/业务操作员及基础成员角色、账号生命周期、邀请、用户列表服务端排序、审计分类/列头排序/统计/备份、业务公告和个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
|
|
@@ -23,11 +30,6 @@
|
|
|
23
30
|
API 前缀、健康检查与跨端 Header 等传输配置位于 serv 包的 `config/_serv.yml`。
|
|
24
31
|
`SUPPORTED_LOCALES` 为生成时实际编译的语言列表；`app.info` 中名称、版本、环境、默认语言来自后端 core 配置。更新公开契约时同时更新 serv、shared typed API client、各端 UI 与测试。
|
|
25
32
|
|
|
26
|
-
### 开发
|
|
27
|
-
|
|
28
|
-
- `pnpm --filter {{fullstack.contractPackageName}} typecheck`
|
|
29
|
-
- `pnpm --filter {{fullstack.contractPackageName}} test`
|
|
30
|
-
|
|
31
33
|
## 开发测试
|
|
32
34
|
|
|
33
35
|
```sh
|
|
@@ -14,6 +14,15 @@
|
|
|
14
14
|
|
|
15
15
|
### 默认功能与配置
|
|
16
16
|
|
|
17
|
+
| 操作场景 | 输入示例 | 可观察结果 |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| 服务元信息 | 客户端app.info() | 公告、Core名称/版本/环境及启用前端列表，不下发服务端秘密 |
|
|
20
|
+
| Echo演示 | app.echo({ message: 'hello' }) | 原消息、echoedAt和requestId，不写业务表 |
|
|
21
|
+
| 用户/角色/个人资料 | 已认证身份及对应contract参数 | 服务端核验权限与目标，失败保持客户端草稿，成功返回明确结果 |
|
|
22
|
+
| 审计/公告/反馈 | 各职责允许的筛选或处理参数 | 持久记录、私有备份回执或反馈处理状态；通知受理不等于送达 |
|
|
23
|
+
|
|
24
|
+
从工程根启动本服务后，再启动所需客户端。接口地址、认证与传输按实际 `_serv.yml/_iam.yml` 配置，通过shared typed client调用并检查success。
|
|
25
|
+
|
|
17
26
|
以下是可运行示例的初始实现，角色/权限、管理流程、头像限额、分页、审计策略及部署方案均可按用户需求调整。需求与代码或模板规则不一致时，以需求为业务基线同步实现、测试与过期说明；实际框架 API 契约和服务端安全校验仍需满足。
|
|
18
27
|
|
|
19
28
|
- `config/_core.yml`：应用元信息（名称 / 版本 / 环境 / 语言），启动时由 `core.config` 加载。
|
|
@@ -1,99 +1,79 @@
|
|
|
1
1
|
# {{fullstack.sharedPackageName}}
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
供{{projectName}}的Web、Capacitor App和Tauri Desktop复用的前端工作区，提供AdminWorkspace、AppShell、typed API、管理状态、语言主题、引导和帮助。它不单独部署，也不在浏览器中初始化服务端数据库/IAM。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 运行与接入
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
从工程根安装依赖，启动Serv，再启动所选前端。各端已经接入此共享包；增加页面优先复用现有状态和组件。公开入口包含AdminWorkspace/AppShell、initializeManagementApi/managementApi、AVAILABLE_THEMES/themeStore及语言消息与runtime。
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- Typed encrypted API client and platform-specific token storage.
|
|
11
|
-
- Themes, language preferences, onboarding and help.
|
|
9
|
+
以下示例用于已有前端宿主，地址替换为实际API；原有宿主已初始化时直接复用，不重复执行初始化：
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
```ts
|
|
12
|
+
import { initializeManagementApi, managementApi } from '{{fullstack.sharedPackageName}}'
|
|
14
13
|
|
|
15
|
-
|
|
14
|
+
const ready = await initializeManagementApi({ baseUrl: 'https://api.example.invalid/api/v1' })
|
|
15
|
+
if (!ready.success) throw new Error(ready.error.message)
|
|
16
|
+
const info = await managementApi.app.info()
|
|
17
|
+
if (!info.success) throw new Error(info.error.message)
|
|
18
|
+
// info.data包含后端Core名称/版本、环境、语言、公告及前端清单。
|
|
19
|
+
```
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
输入为可信API基址，输出为统一HaiResult。初始化装配认证刷新和传输加密，不能把请求结束当成功；应用入口统一处理安全错误与生命周期，退出时先停止当前身份的后台操作，再清凭据和关闭客户端。
|
|
18
22
|
|
|
19
|
-
|
|
20
|
-
- By default, ordinary users update their own profile, avatar, language, appearance and password. The server enforces the actual business permissions on every request.
|
|
21
|
-
- The workspace uses the available window width. Tables scroll within their own area; settings panels form two columns on large screens and stack on phones.
|
|
22
|
-
- `ManagementStore` owns API calls and business state; components render the state and forward user interactions.
|
|
23
|
-
- Application name, version, environment and default locale come from the backend `app.info` contract, which reads `core` configuration. Do not duplicate these values in translations or frontend constants.
|
|
24
|
-
- Requests, token refresh and JSON responses use the same `@h-ai/api-client` + `@h-ai/crypto` transport. Avatar uploads use encrypted JSON and validate PNG/JPEG/WebP content, with a 512 KiB limit.
|
|
25
|
-
- Read metadata through the same initialized `managementApi.app.info()` client; inspect `success` before using `data`.
|
|
23
|
+
## 功能与输入输出
|
|
26
24
|
|
|
27
|
-
|
|
25
|
+
| 功能 | 用户输入/调用场景 | 可观察输出与限制 |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| 元信息 | managementApi.app.info() | 后端Core名称、版本、环境及语言；不在前端重复硬编码 |
|
|
28
|
+
| 用户/角色管理 | 当前职责允许的列表、筛选、排序与修改 | 服务端授权后的数据与明确结果；隐藏按钮不代替服务端检查 |
|
|
29
|
+
| 个人资料/头像 | 资料值、允许的PNG/JPEG/WebP（不超过512KiB） | 成功保存后更新；失败保留草稿。头像key由服务端生成 |
|
|
30
|
+
| 审计 | 分类、结果、等级、排序或备份条件 | 当前权限范围内记录、近7天统计、私有备份key/数量/SHA256回执；不公开备份对象 |
|
|
31
|
+
| 公告 | 配置人员的受限正文输入 | 公告与审计同事务提交，失败回滚，不把客户端编辑当已发布 |
|
|
32
|
+
| 主题/语言 | 个人设置选择已编译主题/语言 | 保存到IAM用户metadata，登录后恢复，并同步shared与宿主runtime |
|
|
33
|
+
| 引导/帮助 | 首次使用邀请、稍后、关闭、完成或重播 | 按用户及引导版本保存偏好，帮助入口可再次打开，不作为业务完成证明 |
|
|
34
|
+
| 表单/提示 | 输入、失焦、提交与失败重试 | 统一Toast显示安全说明，控件保留错误边框和读屏关联；成功信号决定退出编辑 |
|
|
28
35
|
|
|
29
|
-
|
|
36
|
+
默认示例职责为系统管理、审计、配置、业务操作员和普通成员，实际规则由应用维护。临时账号、生命周期、邀请、敏感操作再认证及密码/会话限制通过服务端策略实现；取消再认证不发送对应敏感业务请求。
|
|
30
37
|
|
|
31
|
-
|
|
38
|
+
工作区按窗口扩展，表格内部滚动，宽屏表单可两列，窄屏收拢。FormField.colSpan可明确占列。页面和数据逻辑分别维护在组件与ManagementStore，错误恢复保留用户输入。
|
|
32
39
|
|
|
33
|
-
|
|
40
|
+
## 配置与扩展
|
|
34
41
|
|
|
35
|
-
###
|
|
42
|
+
### API地址、认证与平台存储
|
|
36
43
|
|
|
37
|
-
|
|
44
|
+
initializeManagementApi接受baseUrl、fetchFn、clientName、terminalType、tokenStorage、headers、requireApiBase和onSessionExpired。基址顺序为显式baseUrl→公开runtime-config→PUBLIC_API_BASE→当前origin；只给origin时补/api/v1，自定义http.apiPrefix必须明确包含。
|
|
38
45
|
|
|
39
|
-
|
|
46
|
+
- Web/浏览器预览使用内存access token和服务端HttpOnly刷新Cookie，刷新恢复会话；认证token不放localStorage。
|
|
47
|
+
- Capacitor原生使用createCapacitorTokenStorage及受信原生通道。编译/同步前在App的public/runtime-config.js设置公开API地址，不放服务端秘密。
|
|
48
|
+
- Tauri原生凭据只在内存，重启重新登录。启动安装程序前设置进程PUBLIC_API_BASE，Rust宿主注入地址；缺省http://localhost:3000/api/v1只适合本机服务。
|
|
49
|
+
- 原生请求声明clientName及body通道头，服务端还核验可信Origin；仅声明头不获得原生权限。
|
|
40
50
|
|
|
41
|
-
|
|
51
|
+
仅配置地址不证明设备可达。代理、HTTPS、凭据传递与认证状态恢复应在对应平台验证。
|
|
42
52
|
|
|
43
|
-
###
|
|
53
|
+
### IAM与通知
|
|
44
54
|
|
|
45
|
-
|
|
55
|
+
Serv的config/_iam.yml控制登录/注册/重置、协议与ui品牌，AuthPanel只使用安全公开配置。密码、验证码、LDAP及发送回调的完整配置见[生成应用IAM技能](../../.agents/skills/hai-iam/reference.md)。协议正文Markdown优先于URL并安全渲染；邮件/短信投递未知需查回执，不能自动重复发送。
|
|
46
56
|
|
|
47
|
-
|
|
57
|
+
页面离开撤销为可选且尽力而为；生产仍用共享数据库/Redis、闲置与绝对期限。管理写入路由和最后管理员边界按根README的实际部署方案执行。
|
|
48
58
|
|
|
49
|
-
###
|
|
59
|
+
### 消息、主题、组件与引导
|
|
50
60
|
|
|
51
|
-
|
|
61
|
+
共享文案在messages，前端专属文案放各端messages；启用语言及baseLocale一致后执行根 `pnpm i18n:compile`，不手改生成文件。插件来自已安装workspace依赖，不在编译时从CDN获取。
|
|
52
62
|
|
|
53
|
-
|
|
63
|
+
AVAILABLE_THEMES只暴露已编译CSS主题，eye-care为可选护眼主题；默认主题和显式白名单由宿主决定。外观缓存可保存theme，认证token不能复用该存储。修改AppShell、相邻管理组件或ManagementStore时同步三语与键盘/窄屏恢复流程。
|
|
54
64
|
|
|
55
|
-
|
|
65
|
+
引导定义在src/lib/stores/guide-store.ts，组件提供稳定data-guide属性；Web引导偏好用Cookie，App/Desktop用按当前用户与版本划分的localStorage，不存认证信息。设计、实现和复核分别使用根skills中的hai-ui-design、hai-ui、hai-ui-review。
|
|
56
66
|
|
|
57
|
-
|
|
67
|
+
{{#if features.feedback}}
|
|
68
|
+
### 用户反馈
|
|
58
69
|
|
|
59
|
-
|
|
70
|
+
反馈页面复用shared SDK预览、标注、保存草稿与导出轮询；提交受理编号不表示材料和通知全部完成。服务端 `_feedback.yml` 配置采集预算/业务采集超时/Webhook，密钥仅在服务端私有环境。退出身份清理草稿与观察器，导出文件通过受授权私有通道交付。App/Desktop按平台安全保存文件并清理临时资源。
|
|
71
|
+
{{/if}}
|
|
60
72
|
|
|
61
|
-
|
|
73
|
+
## 验证
|
|
62
74
|
|
|
63
|
-
|
|
75
|
+
从根目录运行 `pnpm typecheck`、`pnpm lint`、`pnpm build`、`pnpm test`、`pnpm test:e2e`。核对管理员与普通用户、跨资源拒绝、资料失败保留、头像、偏好恢复、密码/会话失效及窄屏布局。所有已选择前端共用流程，但浏览器测试不替代原生壳、设备权限或miniapp验收。
|
|
64
76
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
|
|
68
|
-
|
|
69
|
-
LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Their third context argument supplies expiresAt/idempotencyKey; senders durably deduplicate that key, and errors/timeouts mean unknown delivery with no automatic resend. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
|
|
70
|
-
|
|
71
|
-
Agreements accept Markdown text or a URL. Markdown takes precedence and opens in a safely rendered dialog.
|
|
72
|
-
|
|
73
|
-
See `.agents/skills/hai-iam/reference.md` in the generated application for the complete contract.
|
|
74
|
-
|
|
75
|
-
### Operation feedback
|
|
76
|
-
|
|
77
|
-
Operation results use the shared `toast` queue from the lightweight `@h-ai/ui/toast` entry. `AdminWorkspace` mounts one `ToastContainer` for Web, App and Desktop: notifications float at the bottom right by default, use UI-owned semantic colors for information, success, warning and error, with a soft tinted background, a narrow color border and a distinct icon, close automatically or manually, and appear one at a time in FIFO order. Waiting notifications do not expire before being shown. Set `position` in `toast.add` for any of the six supported positions. Field validation and persistent business state stay inline.
|
|
78
|
-
|
|
79
|
-
### Form layouts
|
|
80
|
-
|
|
81
|
-
The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings fill the available width and use two columns on wide screens, with stacked labels and a single avatar editor. Narrow containers automatically stack cards, fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
|
|
82
|
-
|
|
83
|
-
## 界面设计与验收
|
|
84
|
-
|
|
85
|
-
共享管理界面的 Web/App/Desktop 使用同一套 UI 组件和状态。设计、实现、审查分别参考根目录 `.agents/skills/hai-ui-design/`、`hai-ui/`、`hai-ui-review/`；正常、加载、空态、错误恢复、键盘、语言/主题和窄容器均按实际场景验收。组件的筛选、排序和分页仍由业务数据回调接入。
|
|
86
|
-
|
|
87
|
-
## 反馈现场与交付检查
|
|
88
|
-
|
|
89
|
-
feedback.init(config, { collectEvidence }) 支持等待业务 text/data 与文本/ZIP/GZIP 附件；_feedback.yml 提供业务采集超时和 Webhook URL/签名密钥/请求超时。密钥仅放服务端私有环境。Webhook 持久重试，详情展示状态并允许管理员重试。
|
|
90
|
-
|
|
91
|
-
反馈的 console/disabled/reach 独立选择；SDK getView/ratio/saveDraft 与 createFeedbackReview 统一预览、标注、保存及轮询。退出身份清理草稿和观察器。宿主生命周期由 core.module.createRuntime 处理，框架表升级前备份停旧写入并运行各模块 dryRun 预检。
|
|
92
|
-
|
|
93
|
-
## Development and testing
|
|
94
|
-
|
|
95
|
-
Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Browser checks cover shared workflows; test native shells on their target platforms separately.
|
|
96
|
-
|
|
97
|
-
## License
|
|
77
|
+
## 许可证
|
|
98
78
|
|
|
99
79
|
Apache-2.0
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"engines": { "node": "^22.23.4 || ^24.22.1 || ^26.12.1" },
|
|
3
3
|
"name": "{{projectName}}",
|
|
4
|
-
"version": "1.0.0-beta.
|
|
4
|
+
"version": "1.0.0-beta.20",
|
|
5
5
|
"private": true,
|
|
6
6
|
"packageManager": "pnpm@12.11.2",
|
|
7
7
|
"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}}",
|
|
@@ -298,7 +298,7 @@ const answer = await ai.knowledge.ask('核心架构是什么？')
|
|
|
298
298
|
|
|
299
299
|
共享单活动生成租约为存储端时钟30秒，每10秒续租，最终 CAS 同时检查版本、owner 和截止时间。过期生成仅 interrupted，不自动重放 LLM/工具/记忆；manual pending 持久保存，可跨节点/重启按 turnId 提交。相同终态与真实文本重复提交幂等，内容冲突失败。queue 可取消轮询，不保证FIFO。reset 更换共享纪元，删除保留永久墓碑且 scope 不复用。外部 LLM/工具/本地后台记忆不与上下文跨系统原子提交；崩溃后的未知副作用必须由应用核对。
|
|
300
300
|
|
|
301
|
-
自定义
|
|
301
|
+
自定义 Store 接入遵守[Context 持久化约束](reference.md#context)，包括最终提交时的版本、存储端时钟和截止条件；不能用一次续租或读前检查替代最终原子判断。
|
|
302
302
|
|
|
303
303
|
```ts
|
|
304
304
|
const managerResult = ai.context.createManager({
|
|
@@ -400,6 +400,8 @@ if (!playable.success)
|
|
|
400
400
|
|
|
401
401
|
hai-framework 源码仓库提供 `pnpm model <name> --device cpu` 与 `pnpm model:run <name>`，默认优先使用 Podman，可构建/启动 `faster-whisper-large-v3`、`indextts-2.5`、`qwen3-4b`。三套权重均优先从清单锁定的 ModelScope revision 下载并复用容器 volume，Hugging Face 只作回退。Whisper/IndexTTS 仍配置为 `audio.models[].baseUrl`，Qwen3-4B 仍配置为 OpenAI-compatible `llm.models[].baseUrl`；部署位置不进入 Provider 名称。离线部署使用准备权重后的 bundled 镜像。
|
|
402
402
|
|
|
403
|
+
`model:run` 只发布宿主 `127.0.0.1`；宿主设置 `HAI_MODEL_API_KEY` 时通过引擎环境变量名传入，客户端使用匹配 Bearer，Qwen在进程内映射到 `VLLM_API_KEY`，不能在额外参数中填写密钥。IndexTTS构建每轮需从固定HTTPS端点取得源码树元数据，源码文件可按摘要复用；仓库/缓存父目录须可信，离线目标运行预先完成的镜像。对外生产服务另行配置网络、HTTPS、认证和资源限额。
|
|
404
|
+
|
|
403
405
|
## 文生图（Image）
|
|
404
406
|
|
|
405
407
|
`ai.image` 只暴露稳定的提示词、模型别名、像素尺寸、可选参考图和图片字节；OpenAI、Google、Qwen、Seedream 与 Pollinations 的请求结构、鉴权、响应解析和临时 URL 下载均封装在内部 Provider。
|
|
@@ -169,9 +169,9 @@ Knowledge `retrieve/ask` 与默认 DB Store 的 filter 透传向量 Provider，
|
|
|
169
169
|
|
|
170
170
|
共享单活动生成租约为存储端时钟30秒，每10秒续租，最终 CAS 同时检查版本、owner 和截止时间。过期生成仅 interrupted，不自动重放 LLM/工具/记忆；manual pending 持久保存，可跨节点/重启按 turnId 提交。相同终态与真实文本重复提交幂等，内容冲突失败。queue 可取消轮询，不保证FIFO。reset 更换共享纪元，删除保留永久墓碑且 scope 不复用。外部 LLM/工具/本地后台记忆不与上下文跨系统原子提交；崩溃后的未知副作用必须由应用核对。
|
|
171
171
|
|
|
172
|
-
自定义 `AIRelStore` 必须提供版本化读取、原子 CAS 和存储端 `currentTime()`；普通 save/saveMany 也推进版本。CAS
|
|
172
|
+
自定义 `AIRelStore` 必须提供版本化读取、原子 CAS 和存储端 `currentTime()`；普通 save/saveMany 也推进版本。CAS 缺失版本只允许创建，`notAfter` 在最终持久化时用存储端时钟严格检查，存储故障抛错不能当空数据，外层业务边界转为 HaiResult 失败。默认关系存储含 `version` 列；SQLite 仅用于开发/测试，生产使用 PostgreSQL/MySQL 与共享向量服务。
|
|
173
173
|
|
|
174
|
-
`ai.context.createManager(options)`
|
|
174
|
+
`ai.context.createManager(options)` 同步返回 `HaiResult<ContextManager>`，适合多轮对话；先判断 `success`，再通过 `data` 使用有状态管理器。`restoreManager(scope, options?)` 为异步恢复入口，同样先检查结果。
|
|
175
175
|
|
|
176
176
|
常用选项：
|
|
177
177
|
|
|
@@ -18,6 +18,8 @@ description: "构建并发布或交付已有镜像：完整离线包、按服务
|
|
|
18
18
|
| 输出 | 含 tar、清单、配置和跨平台入口的单一交付目录与分步结果，或经过 HTTP 检查的部署结果 |
|
|
19
19
|
| 限制 | SDK 只消费产物；CLI --build 显式先构建。首次安装必须完整交付，packaged 不代表服务器 ready。云资源需要外网。 |
|
|
20
20
|
|
|
21
|
+
Vercel API/文件上传只请求官方入口，拒绝重定向，每次请求和完整 JSON 读取共用 30 秒期限；超时先查询平台实际状态，不无条件重复发布。此期限没有配置开关。
|
|
22
|
+
|
|
21
23
|
--plan 和 --inspect-remote 从 CLI 完整透传，只读失败不得退回部署。target.runtime 只表示远端配置。旧凭据用服务器本机 `hai deploy-secrets <directory> --import <private.json>` 预检，--apply 才导入；SDK importDeploymentSecrets 默认 dryRun:true，验证项目/卷/实际凭据、共享 flock、v2 状态特殊字符与原子 0600 写入，缺状态的普通部署仍拒绝。完整格式和恢复步骤见 [凭据导入](credentials.md)。
|
|
22
24
|
|
|
23
25
|
## 操作流程
|