@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/README.ja.md
CHANGED
|
@@ -1,276 +1,148 @@
|
|
|
1
1
|
# @h-ai/cli
|
|
2
2
|
|
|
3
|
-
[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md)
|
|
3
|
+
[简体中文](README.md) | [English](README.en.md) | [日本語](README.ja.md) · [ホーム](../../README.ja.md)
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
`hai` でアプリ作成、モジュール追加、コード生成、Web/API/ネイティブ成果物の構築と配布を行います。全体の手順は[利用ガイド](../../docs/usage/README.ja.md)を参照してください。
|
|
6
6
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
生成プロジェクトは既定で `zh-CN`、`en-US`、`ja-JP` を有効にします。対話設定で日本語を既定に選択でき、fullstack は `fullstack.i18n.locales` で言語を制限できます。CLI は `HAI_CORE_DEFAULTLOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG` の順で中国語・英語・日本語を選択します。
|
|
10
|
-
|
|
11
|
-
`hai` でアプリ作成、モジュール追加、ひな型生成、ビルド、配布を行います。SvelteKit、独立 API、フロントとバックを分離した工程に対応します。全体の流れは[利用ガイド](../../docs/usage/README.ja.md)を参照してください。
|
|
12
|
-
|
|
13
|
-
## 主な機能
|
|
14
|
-
|
|
15
|
-
- 管理画面、企業サイト、H5、API、モバイル、fullstack の作成。
|
|
16
|
-
- 既存アプリへのモジュール・設定・AI 指引の追加。
|
|
17
|
-
- ページ、部品、API、モデル、マイグレーションのひな型生成。
|
|
18
|
-
- 選択イメージのビルド、完全オフライン配布、サービス単位の更新。
|
|
19
|
-
|
|
20
|
-
## 使い始める
|
|
7
|
+
## クイックスタート
|
|
21
8
|
|
|
22
9
|
### CLI のインストール
|
|
23
10
|
|
|
24
|
-
Node.js は `engines`（`^22.23.4 || ^24.22.1 || ^26.12.1
|
|
25
|
-
|
|
26
|
-
公開チャネルを確認して latest をインストールします。`hai create --help` で対応オプションを確認し、未公開機能は下記のローカル開発手順で検証してください。
|
|
11
|
+
Node.js は `engines`（`^22.23.4 || ^24.22.1 || ^26.12.1`）、pnpm は12.11.2を使用します。PowerShellでは `pnpm.cmd` を使います。
|
|
27
12
|
|
|
28
13
|
```sh
|
|
29
|
-
pnpm view @h-ai/cli dist-tags
|
|
30
14
|
pnpm view @h-ai/cli@latest version
|
|
31
15
|
pnpm add -g @h-ai/cli@latest
|
|
32
16
|
hai --version
|
|
33
|
-
hai --help
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
生成したフレームワーク依存は CLI と同じ厳密バージョンに固定します。インストール失敗時はコマンド・終了コード・出力を表示し、再試行できるようファイルを残します。未公開ソースは下記のローカル開発手順で検証してください。
|
|
37
|
-
|
|
38
|
-
### アプリの作成
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
17
|
hai create my-app --type fullstack --frontends web
|
|
42
18
|
cd my-app
|
|
43
19
|
pnpm dev
|
|
44
20
|
```
|
|
45
21
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
### プロジェクトテンプレート
|
|
49
|
-
|
|
50
|
-
| 種類 | 生成内容 |
|
|
51
|
-
| -------------------------- | -------------------------------------------------------------------- |
|
|
52
|
-
| `admin` / `website` / `h5` | SvelteKit 管理画面・サイト・モバイル Web |
|
|
53
|
-
| `api` | 共通 contract と API service の pnpm workspace |
|
|
54
|
-
| `mobile-app` | Svelte + Vite + Capacitor |
|
|
55
|
-
| `fullstack` | contract、API、共通 UI、選択した Web/App/Desktop。miniapp は説明のみ |
|
|
56
|
-
|
|
57
|
-
各テンプレートは実際に使うモジュールだけを導入します。admin/h5 は認証・OTP/パスワード再設定の通知・DB・キャッシュ・暗号化、website は Core/Kit/UI、API は認証・通知・アップロード・feedback、fullstack は管理画面の認証・監査・保存・通知・スケジューラー・feedback、mobile-app はクライアント機能を使用します。AI、payment、vecdb、datapipe は既定で導入しません。全工程に完全なモジュール YAML と `.env.example` を残し、未使用項目はコメントにして公開環境の既定値から除外します。後で依存を追加し、必要な設定を有効にして初期化・終了・業務ルートを接続します。依存追加だけでは自動的に有効になりません。`--template`、`--features`、`--examples/--no-examples` は削除済みで、`create --yes/-y` は `--defaults` です。旧引数は明示的に拒否し、`deploy --yes` の意味は維持します。既存工程の依存は自動削除しません。
|
|
58
|
-
|
|
59
|
-
独立した `mobile-app` は frontend crypto と暗号化 typed client transport を含みます。既存の平文 API には `PUBLIC_API_TRANSPORT=off` を明示します。`PUBLIC_API_KEY_EXCHANGE_PATH` は公開鍵交換パスの上書きです。失敗時に平文へ切り替えず、サーバー秘密鍵はクライアントに渡しません。終了時は transport、その後に自身の crypto を解放します。
|
|
60
|
-
|
|
61
|
-
admin、website、h5、Fullstack Web はアプリケーションの読み込み前にブラウザーのバージョンを確認します。独立した更新ページに現在のバージョン、最低要件、公式の更新手順を表示します。最低要件は Chrome/Edge 111、Firefox 114、Safari 16.4、または iOS/iPadOS 16.4 です。既存プロジェクトは[起動時のブラウザーチェック](../../docs/usage/getting-started/build.md#浏览器启动检测)を参照してください。
|
|
62
|
-
|
|
63
|
-
### 静的websiteとGitHub Pages
|
|
64
|
-
|
|
65
|
-
新規 website は既定で Node SSR、依存は Core/Kit/UI のみで、下記の静的構築をそのまま利用できます。後から追加したサーバー業務依存・初期化・独自 API/actions は静的公開前に除去します。コメントの設定と環境変数の参考例は静的構築に影響しません。
|
|
66
|
-
|
|
67
|
-
websiteの既定はNode SSRです。ビルド時に`HAI_BUILD_STATIC=1`と`PUBLIC_BASE_PATH=/docs-site`（docs-siteを実際のリポジトリー名に置換。各区間はASCII英数字・_・.・-のみ、末尾/なし、ルートは空）を指定してpnpm buildを実行すると静的buildを生成します。静的フラグは0/1のみでcompile専用です。PUBLIC_BASE_PATHはDockerのWeb構築にも対応しますが、ネイティブapp/desktopでは指定できません。静的構築はサーバー業務モジュール、独自API/actions、事前描画されないページを拒否し、本番ガードを緩和せずSPAフォールバックも生成しません。既定のhealth APIは含めません。
|
|
22
|
+
入力は工程名とテンプレート種別、出力は生成工程です。依存インストールとGit初期化は既定で有効です。`--defaults` は既定値を使い、`--no-install`、`--no-git`、`--no-deploy` はそれぞれインストール、Git、デプロイ開発依存を省略します。省略項目は対話で選択します。各コマンドの引数は `hai <command> --help` で確認してください。
|
|
68
23
|
|
|
69
|
-
|
|
24
|
+
## 機能
|
|
70
25
|
|
|
71
|
-
|
|
26
|
+
### コマンドの用途・入力・出力
|
|
72
27
|
|
|
73
|
-
|
|
28
|
+
CLIは端末から実行し、フレームワークサービスの初期化は不要です。出力と終了コードで判断します。TARGET_VERSIONはpnpm viewで確認した公開済みの厳密バージョンへ置き換え、文字列をそのまま渡さないでください。
|
|
74
29
|
|
|
75
|
-
|
|
30
|
+
| コマンド | 用途・入力 | 出力と例 |
|
|
31
|
+
| -------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| create | 工程名、type、fullstackのフロント選択 | `hai create orders --type admin --defaults` で管理アプリを生成 |
|
|
33
|
+
| add | 現工程へ指定モジュールを追加 | `hai add ai` は依存・設定・skillを補完。業務ファイルは維持し、初期化・終了・ルートはアプリで接続 |
|
|
34
|
+
| init | 設定とAI入口を補完 | `hai init` は不足ファイルを追加。`--force` の設定再生成前に差分を確認 |
|
|
35
|
+
| generate / g | 種別、名前、対象workspace | `hai generate api orders --workspace orders-serv` はルートまたはcontract/procedureを生成。短縮形はg:page/g:component/g:api/g:model |
|
|
36
|
+
| build | target、イメージ/プラットフォーム、ソース | `hai build --target image --json` は今回の成果物JSONを出力。buildはデプロイ環境を受け取らない |
|
|
37
|
+
| deploy | 環境、成果物、対象サービス | `hai deploy --env prod --plan` は読取専用計画。planを外すと配布処理へ進む |
|
|
38
|
+
| upgrade | 厳密な公開版と工程 | `hai upgrade TARGET_VERSION` は依存・完全性・設定・skill差分を報告。自動インストールや上書きはしない |
|
|
39
|
+
| deploy-secrets | サーバーディレクトリと私有JSON | `hai deploy-secrets /srv/orders --import /private/orders.json --runtime docker` は既定で事前検査、明示的な `--apply` のみ保存 |
|
|
40
|
+
| feedback | action、診断ZIP、検索条件 | `hai feedback summary feedback.zip` は要約。inspect/evidence/viewはmanifest、証跡、本機ビューア |
|
|
76
41
|
|
|
77
|
-
|
|
42
|
+
共通 `--cwd/-C` は工程ディレクトリ、`--verbose/-v` は詳細診断です。CLI言語は `HAI_CORE_DEFAULTLOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG` から選び、生成アプリの言語とは独立します。
|
|
78
43
|
|
|
79
|
-
###
|
|
44
|
+
### テンプレート
|
|
80
45
|
|
|
81
|
-
|
|
46
|
+
| type | 生成内容と用途 |
|
|
47
|
+
| -------------------- | ---------------------------------------------------------------------- |
|
|
48
|
+
| admin / website / h5 | SvelteKit管理画面、紹介サイト、モバイルWeb。websiteはCore/Kit/UIで開始 |
|
|
49
|
+
| api | contractと独立Servのpnpm workspace |
|
|
50
|
+
| mobile-app | 独立APIへ接続するSvelte/Vite/Capacitorクライアント |
|
|
51
|
+
| fullstack | contract、Serv、共有UI、選択したWeb/App/Desktop。miniappは予約説明 |
|
|
82
52
|
|
|
83
|
-
|
|
53
|
+
必要なモジュールのみインストールし、任意設定のコメントと `.env.example` を残します。コメント解除だけでは業務接続は完了しません。AI/payment/vecdb/datapipeは必要時に追加し、本番では共有DB、Redis、共有ファイルバックエンドを使います。既定言語は中英日、fullstackは `fullstack.i18n.locales` で限定できます。
|
|
84
54
|
|
|
85
|
-
|
|
55
|
+
ブラウザ用テンプレートは起動前に既知の旧版を確認します。最低Chrome/Edge111、Firefox114、SafariおよびiOS/iPadOS16.4です。[ブラウザ入口](../../docs/usage/getting-started/build.md#浏览器启动检测)
|
|
86
56
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
テンプレートは `pretty` ログを既定とし、実行依存に `pino-pretty` を追加します。`HAI_CORE_LOGGING_FORMAT=json` で JSON に切り替えます。起動失敗はモジュール・エラーコード・設定項目、ポート競合は `EADDRINUSE`・アドレス・ポートを表示します。
|
|
90
|
-
|
|
91
|
-
公開設定は `.env` と `.env.<mode>`、SSH と資格情報は Git 対象外の `.env.<mode>.local`、マシン共通の秘密値は `.env.local` に保存します。構築時には配備の秘密値を読みません。 すべての `HAI_*` はプロセス > `.env.<mode>.local` > `.env.local` > `.env.<mode>` > `.env` > YAML の順です。同一ソースは JSON を基礎として個別フィールドで上書きし、高優先度ソースの全体置換は低優先度の細項を解除します。Node/Vite と配備は同じ Core 処理を使います。
|
|
92
|
-
|
|
93
|
-
### 既存工程とコード生成
|
|
94
|
-
|
|
95
|
-
`hai add ai` は reldb と vecdb も導入します。その後、アプリの入口に DB → ベクトル保存先 → AI の順の初期化と逆順の終了処理を接続し、終了処理の失敗も確認します。本番設定は有効な機能に応じて PostgreSQL（選択済み MySQL は保持）・Redis・S3・Qdrant を選び、Compose の `db/cache/storage/vecdb` を使います。パスワード・S3 認証情報・モデルキー・保護された Qdrant キーは秘密環境から注入し、Compose 外では接続先を上書きしてください。本番 Reach は空 Provider 配列で起動を拒否し、実際の `HAI_REACH_PROVIDERS` JSON の注入が必要です。`hai add` は既存本番値を保持して不足項目を追加します。既存の起動処理への接続はアプリ側で行います。
|
|
57
|
+
### ページ・部品・API・モデル・マイグレーションの生成
|
|
96
58
|
|
|
97
59
|
```sh
|
|
98
|
-
hai add storage
|
|
99
|
-
hai init
|
|
100
|
-
hai generate
|
|
101
60
|
hai generate page dashboard
|
|
102
61
|
hai generate component UserCard
|
|
103
|
-
hai generate api orders
|
|
62
|
+
hai generate api orders --workspace orders-serv
|
|
104
63
|
hai generate model order
|
|
105
64
|
hai generate migration add-orders
|
|
106
65
|
```
|
|
107
66
|
|
|
108
|
-
`
|
|
109
|
-
|
|
110
|
-
page は SvelteKit のファイルルートに対応し、api は対象アプリに応じて SvelteKit または serv の共有 contract/procedure を生成します。API/fullstack のルートでは一意なバックエンドを自動選択します。複数候補は `--workspace <パッケージ名または相対パス>` で指定するか、対象 workspace に移動してください。通常の Vite への page/api 生成は拒否します。serv は `--output` を受け付けず、SvelteKit の出力は `src/routes` 内に限定し、独自の `kit.files` は推測せず拒否します。SvelteKit API には `@h-ai/kit` と `zod` が必要です。serv は `@hai-generator` マーカーのある既存の集約入口だけを更新し、未知の構成には手動統合を要求します。名前にパスは指定できません。既存ファイルは `--force` が必要ですが、登録済み業務領域は置換しません。一括検査後に書き込み、失敗時は今回の変更を戻します。マイグレーションは up/down 関数のみ生成するため、実行前にデータへの影響を確認してください。
|
|
111
|
-
|
|
112
|
-
CLI メッセージは中国語・英語・日本語に対応します。`HAI_CORE_DEFAULTLOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG` の最初の空でない値を使い、`en`/`zh`/`ja` の地域別表記は既存辞書に対応付けます。`C`/`POSIX` は英語です。未知の言語は現在の core 言語（既定は中国語）を保持します。PowerShell では `$env:HAI_CORE_DEFAULTLOCALE='en-US'` の後に `hai generate` を実行してください。CLI 内部のコマンドも `core.i18n.setGlobalLocale('en-US')` による同一プロセス内の言語切替を反映します。種類や名前を省略すると対話入力になり、取消時はファイルを書きません。生成コードの中国語コメントとユーザー指定名は変更しません。
|
|
113
|
-
|
|
114
|
-
`create`、`add`、`init`、`generate` のプロンプト、検証、モジュール/テンプレート名、説明と完了メッセージは現在の CLI 言語を使用します。選択肢は参照時に翻訳するため、同一プロセス内の locale 変更も反映します。CLI 言語と生成アプリの `core.defaultLocale` は独立しています。生成される中国語 README、設定/コードのコメント、ユーザー入力と外部ツールの元の診断は変更しません。
|
|
115
|
-
|
|
116
|
-
### SvelteKit エンドポイントの安全設定
|
|
117
|
-
|
|
118
|
-
admin・website・h5 作成時に crypto を選ぶと `_kit.yml` の transport を有効化できます。既定値は false です。サーバーは環境ごとに生成した鍵リングを使用し、ルートレイアウトは公開 transport 設定だけをブラウザーに渡します。非公開 IP・時間条件は渡しません。db 選択時は DB registry を使用し、db なしのメモリー registry は開発・テストに限ります。静的サイトに動的 API はありません。
|
|
67
|
+
名前にパスを含めず、既存業務ファイルは既定で上書きしません。`--workspace` はパッケージ名または相対ディレクトリです。SvelteKitの `--output` はsrc/routes内、Servはこの引数を受け付けません。pageはファイルルーティング専用で、非対応の純Vite page/API組合せは拒否します。Servは `@hai-generator` 付き集約入口のみ更新します。バッチを事前検査し、書込失敗時は今回の変更を戻します。`--force` は生成ファイルのみ対象。マイグレーションはup/down関数を生成し、DB操作を実行しません。
|
|
119
68
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
### 任意の HTTPS 証明書
|
|
123
|
-
|
|
124
|
-
`pnpm run deploy` は全コンテナーテンプレートで HTTPS なし、既存 PEM 証明書・秘密鍵、Let’s Encrypt を選択できます。相対パスは工程ルート基準です。ドメイン・期限・鍵一致を検証して配布物にコピーします。版を固定した公式 Certbot イメージで申請し、12 時間ごとに更新を確認して Nginx を再読み込みします。利用規約の承認、実際のメール、公的 DNS、80 番ポート、CA 接続が必要です。隔離環境では既存証明書を使います。状態はサーバーに保持し、秘密鍵をアプリイメージに含めません。`--yes` は保存設定を使います。
|
|
125
|
-
|
|
126
|
-
`hai.json.deploy.provider.expose.https` または環境別秘密設定で指定します。既定は HTTPS 443 と HTTP リダイレクト、省略時は HTTP です。有効/無効・モード・ドメイン・ポート・持込証明書の変更は完全デプロイが必要です。[HTTPS 設定](../../docs/usage/configuration/delivery.md#可选https证书)を参照してください。計画では `root` が工程ルート、`serviceDir` がサービスのソース・設定ディレクトリです。
|
|
127
|
-
|
|
128
|
-
### ビルドとデプロイ
|
|
129
|
-
|
|
130
|
-
Windows のビルドでは標準出力とエラーの改行を統一して転送します。pnpm の取得ログは追記方式とし、警告と失敗情報を保持します。
|
|
131
|
-
|
|
132
|
-
イメージと npm の取得元を `--image-source official|cn|custom`、`--npm-source official|cn|custom` で個別に指定できます。中国本土のプリセットは Docker Hub/GHCR に毫秒镜像、npm に npmmirror を使用します。初回対話の選択は `hai.json.build.sources` に保存し、引数は今回のみ上書きします。`--yes` は既存設定を再利用し、非対話で未設定の場合は公式を使用します。プロキシは `build.proxy` と `--proxy-mode inherit|system|custom|none`、`--proxy-url`、`--proxy-bypass` で指定します。Docker と Podman のビルドに渡し、ビルドネットワークに応じてループバックを処理し、コンテナ内で接続を確認します。イメージ取得はエンジン側のプロキシ設定を使用します。カスタム対応表、システムプロキシの対応範囲、既存 Dockerfile の更新は[取得元とプロキシ](../../docs/usage/configuration/delivery.md#下载源和代理)を参照してください。
|
|
69
|
+
### ビルド・静的サイト・ネイティブ成果物
|
|
133
70
|
|
|
134
71
|
```sh
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
72
|
+
hai build --target image --images "serv,web" --concurrency 1
|
|
73
|
+
hai build --target app --platform android --runtime auto --debug
|
|
74
|
+
hai build --target desktop --platform windows --arch x64
|
|
138
75
|
```
|
|
139
76
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
PostgreSQL、MySQL、Redis、pgvector のカスタム接続では、接続 URL または個別フィールドを選びます。URL は入力中に非表示となり、保存後はスキーム、ホスト、ポートを表示します。S3 の API `endpoint` と `bucket` は別々に入力します。入力エラーには変数名と値の要件を表示します。例は[既存ミドルウェアへの接続](../../docs/usage/configuration/delivery.md#连接已有数据库缓存和对象存储)を参照してください。
|
|
143
|
-
|
|
144
|
-
Node バックエンド（Serv / SvelteKit SSR）は起動ごとに `<配備ディレクトリー>/config/.env.runtime` を読みます。管理接続も同じアプリ設定に統合します。`HAI_STORAGE_PUBLICENDPOINT` などを編集して再起動すると反映され、同じソースでは個別フィールドが親 JSON を上書きします。設定ディレクトリーを `/run/hai/config` に読み取り専用でマウントするため、ファイルのアトミック置換も次の起動で反映されます。非公開プロキシ識別と Node 起動引数は配備設定です。静的 Web、ネイティブ環境、ポート、マウント、Nginx の変更は再配備します。Web/ミドルウェアのみの更新は設定を維持し、バックエンドの部分更新は管理接続を維持、全量更新は新しい設定と既存の管理資格情報を使います。編集前にバックアップし、恒久的な値は元の環境にも反映してください。
|
|
145
|
-
|
|
146
|
-
外側の `README.txt` とアーカイブ内の `APPLY.txt` には、ファイル索引、環境設定の優先順位、今回の変数名、調査手順が含まれます。展開した `config/.env.runtime` は配備入力、配備ルートの同名ファイルは現在の実行設定、`releases/<ID>/` 内は配備記録です。外部 PostgreSQL のパスワード変更後はプロジェクトの環境設定を更新し、バックエンドを配備します。URL と個別項目のパスワードが競合する場合はパッケージ作成時に失敗します。外部と同梱の切り替えには全量配備が必要です。
|
|
77
|
+
target既定はcompile、他はimage/app/desktopです。イメージの役割はserv/webで、app/desktopはComposeサービスではありません。同時イメージビルドは最大2件。autoは使用可能なPodman→Docker、明示選択では別エンジンへ切替えません。Androidでruntime省略時は本機ツール、iOSはmacOS/Xcodeと署名が必要です。
|
|
147
78
|
|
|
148
|
-
|
|
79
|
+
成果物は `.hai/build/` の独立バッチへ保存し、アーカイブ成功後のみ相対 `latest` を更新します。イメージ `--json` のstdoutは今回の結果のみで、`artifactDir` をデプロイへ渡せます。進捗/失敗はstderr。Git出所やdirtyが不明な状態をクリーンと解釈しません。[命名・署名・自動化](../../docs/usage/getting-started/build.md)
|
|
149
80
|
|
|
150
|
-
|
|
81
|
+
静的websiteはビルドプロセスで `HAI_BUILD_STATIC=1` と実際の `PUBLIC_BASE_PATH` を設定し `pnpm build`、buildと.nojekyllだけを公開します。動的API/actions、サーバー業務初期化、私有アセット、リンクは拒否します。未接続の問い合わせフォームは説明を表示し入力を保持します。サイトパス変更は再ビルドし、APIアドレスは別設定です。[静的・子パス設定](../../docs/usage/configuration/delivery.md)
|
|
151
82
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
DB 接続は保存前に選択したバックエンドの公開 Schema で検証します。MySQL の `ssl` は `false` または厳密な TLS オブジェクトのみで、`{}` は証明書チェーンと DNS ID を検証します。PostgreSQL のモードは維持します。CLI は純粋な Schema と Zod を内包するため、検証対象アプリに DB パッケージやドライバーは不要です。アプリの実行には依存関係が必要で、デプロイ機能には解決可能な `@h-ai/deploy`（生成プロジェクトの開発依存）が必要です。
|
|
155
|
-
|
|
156
|
-
`pnpm build` はソースのコンパイルです。イメージごとの Dockerfile を `images/` に置き、`hai.json` の `build.images` で指定し、同じファイルの `deploy` に配置設定を保存します。`--images` はビルド対象、`--services` は更新サービスを選びます。自動選択は接続可能な Podman、次に Docker です。依存の取得・インストール・本番依存の収集で、パッケージと SQLite ドライバーのキャッシュを共有し、再ダウンロードを避けます。
|
|
157
|
-
|
|
158
|
-
イメージは、ビルド中に他の主体が置き換えない信頼済みcontextから作成してください。CLIは各contextの`images/dependencies/`に依存キャッシュと`.managed.json`を管理します。祖先ディレクトリにシンボリックリンクやWindows junctionを使わず、キャッシュファイルのリンクや複数ハードリンクも拒否します。排他的な一時ファイルから原子的に置き換え、内容が同じなら更新日時を維持し、古い追跡ファイルの削除はキャッシュ内に限定します。エラーの理由と診断コードに従ってリンクやアクセス権を確認してから再構築してください。 追跡マニフェストの上限は16MiBです。超過や無効なJSONは元の内容を表示せず、診断を返します。
|
|
159
|
-
|
|
160
|
-
標準コンテナーは CPU 実行またはリモート AI サービスへの接続向けで、追加の GPU ランタイムをダウンロードしません。デプロイ先の GPU を使う場合は、イメージとコンテナーの実行設定を個別に調整してください。
|
|
161
|
-
|
|
162
|
-
CLI は呼び出し元の `HAI_/PUBLIC_/VITE_` を除外し、内部で生成した `HAI_BUILD_ID/HAI_BUILD_COMMIT` のみを注入します。Docker は同じイメージバッチの識別情報をコンパイルに渡します。フィードバックはブラウザーとサーバー各自の `appVersion/buildId/commit` を使用し、バージョンは各 manifest、同じ SSR ビルドの ID は共通です。所属する Git コミットがなければ `unknown` を記録します。三項目の `build-metadata.json` とコード内の値を一致させ、API/ZIP の実際の証拠と照合します。
|
|
163
|
-
|
|
164
|
-
配布ロールは、独立 API バックエンドが `serv`、静的または SSR のブラウザーサイトが `web`、Android/iOS インストーラーが `app`、デスクトップインストーラーが `desktop` です。Fullstack は serv と任意の web、API は serv、admin/website/h5/mobile-app のブラウザーイメージは web を使用します。ネイティブ app/desktop はサーバーの Compose サービスではありません。`--images` と `--services` には serv/web、ネイティブ配布には `--target app` または `--target desktop` を指定します。API サービスのディレクトリは `apps/<project>-serv` です。イメージとコンテナーはルート `package.json.name` を共通の識別名として正規化します（scope 除去、小文字化、無効文字の連続をハイフンに変換）。名前がないか無効な場合は失敗し、ディレクトリ名へフォールバックしません。イメージは `localhost/hai-<project>-<role>:<buildId>`、コンテナーは `hai-<project>-<environment>-<role>` となり、イメージは環境間で再利用できます。
|
|
83
|
+
### デプロイ・オフライン配布・復旧
|
|
165
84
|
|
|
166
85
|
```sh
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
pnpm run deploy --env prod --build --services "serv,web"
|
|
172
|
-
pnpm run deploy --env prod --build --bundle-only
|
|
86
|
+
hai deploy --env prod --plan
|
|
87
|
+
hai deploy --env prod --plan --inspect-remote
|
|
88
|
+
hai deploy --env prod --build --bundle-only
|
|
89
|
+
hai deploy --env prod --build --services "serv,web"
|
|
173
90
|
```
|
|
174
91
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
`manifest.source.dirty` はプロジェクト、選択したイメージの context と Dockerfile の無視されていない Git 変更を確認し、context がリポジトリルートの場合は兄弟パッケージも含みます。所属リポジトリ外の入力や確認失敗は `null` で、変更なしを意味しません。この値はビルド入力内容の証明ではありません。
|
|
178
|
-
|
|
179
|
-
既定の配置名はプロジェクトルート（最も近い `hai.json` またはロックファイルのディレクトリ）の `package.json.name` を使い、未指定または無効な名前はエラーになります。明示した環境名を末尾に追加します。fullstack の `hai-delivery` で `packages/hai-delivery-serv` を走査しても、`--env test` は `/opt/hai/apps/hai-delivery-test` と `bundle-hai-delivery-test-<配置ID>-<版>.tar.gz` を生成します。接続先ディレクトリ、配布物、Compose プロジェクト、API/Web/ミドルウェアのコンテナー、ボリューム、サーバー認証状態のファイル名、増分基準で同じ名前を使います。実際のプロジェクト名に含まれる `-serv` は削除しません。
|
|
180
|
-
|
|
181
|
-
成果物形式4・5はprimaryService（serv/web）と、工程全体のブラウザー構成を示すhasWebを記録します。形式5には非ルートのwebBasePathも含まれます。同一オリジンAPIプロキシはserv + webの場合だけ生成します。形式1～3は再構築が必要です。既存デプロイをバックアップし、プロジェクト名・ボリューム・管理対象の認証情報を確認してから、新しい完全デプロイの基準を作成してください。プロジェクト間のデータ移行は自動化しません。完全デプロイでは同じComposeプロジェクトの旧サービスコンテナーを削除するため、deploy-target.json.directoryの変更だけでは移行できません。
|
|
182
|
-
|
|
183
|
-
既存工程では、hai.json の build.images 名、Dockerfile 名と参照を先に更新します。API サービスのディレクトリ、パッケージ名と依存参照を -serv に統一し、依存を再インストールして完全な成果物を再構築してください。アーカイブ名や manifest の手動変更では再構築を代替できません。
|
|
184
|
-
|
|
185
|
-
CLI の --project-name と SDK の DeployAppOptions.projectName 上書きは廃止しました。旧引数は明示的に失敗します。工程ルートの package.json.name で識別名を管理してください。
|
|
186
|
-
|
|
187
|
-
自前ミドルウェアのパスワードはサーバーの `<remoteDir>/managed-secrets.env`（権限 0600）で永続管理し、データボリュームと一緒にバックアップします。各パッケージは初回用の候補のみ生成し、ビルド端末のキャッシュに依存しません。オンライン SDK、deploy.sh、deploy.ps1、deploy-local.sh は配置ロック内でサーバー値を再利用し、アプリ接続とミドルウェア固有変数の両方へ反映します。配布 tar は変更せず、サーバーの非公開実行ファイルだけに確定値を反映します。対応するボリュームが存在し状態がない場合、サービス変更前に停止してバックアップ復元を求めます。自動的なパスワード変更やデータ削除は行わず、旧認証情報は下記の明示的な検証・導入手順で移行できます。
|
|
188
|
-
|
|
189
|
-
Docker または Podman で配置する場合は、`deploy.container.compose.services.<serv または web>.extra_hosts` でイメージごとにホスト名を設定します。変更後は再梱包して対象サービスを配置します。 [設定例](../../docs/usage/configuration/delivery.md#为容器设置主机名映射)
|
|
190
|
-
|
|
191
|
-
完全配布にはアプリと自前ミドルウェアのイメージが入ります。デプロイキャッシュ、tar と操作ディレクトリは既定でプロジェクトルートの `.hai/deploy/<環境>/` に置きます。`--output` でコマンドの作業ディレクトリを基準とする tar 出力先を指定できます。対話式の梱包では構築・ミドルウェア設定後、梱包前に SSH 設定の追加・変更を確認します。`.env.<環境>.local` に保存し、今回と次回以降の target に反映します。`--yes` またはスキップ時は既存設定を使います。配布ディレクトリには tar、deploy-local.sh、read-target.awk、README.txt、項目説明付き `deploy-target.json`、Windows PowerShell 5+ `deploy.ps1`、Linux/macOS `deploy.sh` を生成します。アップロード前に target を確認して不足項目を補います。両スクリプトともこのファイルを読み、key/agent と password に対応し、Node/pnpm は不要です。target は `passwordEnv`（既定 `HAI_DEPLOY_PROVIDER_SSH_PASSWORD`）だけを参照し、パスワードは操作 PC の環境から今回の SSH/SCP 子プロセスだけに渡します。アプリ環境や配布物には含めません。target の変更はその配布物だけに適用し、プロジェクトには書き戻しません。隔離 Linux サーバーにはディレクトリ全体をコピーし、`sh deploy-local.sh` で自動展開・配置します。アーカイブだけをコピーした場合は、展開後に `APPLY.txt` を読み、同じ場所で `sh ./apply.sh` を実行してください。初回は完全配布が必要で、部分更新は他サービスとボリュームを維持します。各手順の結果を表示し、失敗は非ゼロで終了して復元を試みます。前提・キャッシュ・版管理・復元は[デプロイ説明](../deploy/README.ja.md)を参照してください。
|
|
192
|
-
|
|
193
|
-
不足する SSH 接続・認証を初回に入力し、非表示のパスワードは空白と先頭ゼロを維持します。完全な設定は `--yes` で再利用します。 公開設定は `.env` と `.env.<mode>`、SSH と資格情報は Git 対象外の `.env.<mode>.local`、マシン共通の秘密値は `.env.local` に保存します。構築時には配備の秘密値を読みません。 すべての `HAI_*` はプロセス > `.env.<mode>.local` > `.env.local` > `.env.<mode>` > `.env` > YAML の順です。同一ソースは JSON を基礎として個別フィールドで上書きし、高優先度ソースの全体置換は低優先度の細項を解除します。Node/Vite と配備は同じ Core 処理を使います。
|
|
194
|
-
|
|
195
|
-
失敗時はローカルの管理対象プロセス終了確認と、遠隔の不明/スクリプト完了状態、結果ファイルのパスを別々に表示します。ローカル SSH 終了だけでは遠隔停止を断定しません。不明状態をサーバーで確認し、CLI は配置や復元を自動再実行しません。Windows は内嵌のシステム PowerShell/.NET Job と Add-Type を使い、失敗時は管理外でコマンドを起動しません。
|
|
196
|
-
|
|
197
|
-
通常の前景配置と同期の失敗復元は、後処理と終端結果の公開後に `.deploy.lock` を明示解放し、稼働中の背景サービスは次の配置を妨げません。HUP/INT/TERM または親 shell の強制終了時は、記述子を継承した実行中の子コマンドが全 holder の終了かサーバー再起動までロックを保持します。ロックファイルは残し、削除・置換しないでください。
|
|
198
|
-
|
|
199
|
-
デスクトップ配布は `pnpm build --target desktop --platform windows|linux|macos --arch x64|arm64` を対象 OS とツールチェーンで実行します。コンテナの Web 表示とは別にネイティブ配布を検証してください。
|
|
92
|
+
planは検査と報告のみ。inspect-remoteはSSHで基準状態を読み取り、not-inspectedは検証成功を意味しません。bundle-onlyは対象へ接続せず、アーカイブ、対象情報、転送/本機スクリプト、説明を生成します。内部APPLY.txtは手動適用手順です。初回と構成変更は完全パッケージ、部分更新は一致するサーバー成功基準が必要です。
|
|
200
93
|
|
|
201
|
-
|
|
94
|
+
根 `package.json.name` と環境接尾辞が工程IDです。サーバー認証情報、バックエンド台帳、データボリュームを一緒に保護します。失敗時に前サービスを復旧しても、データ変更、マイグレーション、通知、決済は取り消されません。SSH結果unknownは遠端事実を読取確認してから再試行します。[配布と復旧](../deploy/README.ja.md)
|
|
202
95
|
|
|
203
|
-
|
|
96
|
+
HTTPSは通常PEMファイルまたはLet's Encrypt。証明書/鍵は各1MiB以内でリンクを拒否します。ACMEにはDNS、メール、規約同意、公開80番が必要。証明書状態はサーバーに保存し、有効化/無効化や構成変更は全量配布します。[HTTPS設定](../../docs/usage/configuration/delivery.md#可选https证书)
|
|
204
97
|
|
|
205
|
-
|
|
98
|
+
### 診断・公開版検査・認証情報取込
|
|
206
99
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
hai
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
fullstack 例はアプリ設定で `admin`、`audit_admin`、`config_admin`、`business_operator` と一般 `user` を分離し、システム管理者による他職務アカウントの奪取を拒否します。CLI は既存の環境設定方式を維持し、`.env.dev.local/.env.test.local/.env.prod.local` ごとに四職務の独立した初期パスワードを作成します。ファイルは Git 対象外で、保護設定や Secret Manager により同じ環境へ配布し、既存アカウントの再設定・再割当は行いません。`_iam.yml`/`_audit.yml` の強化機能は業務ごとに選択し、生成 README を参照してください。
|
|
214
|
-
|
|
215
|
-
各スイッチ、既定値、前提条件と利用への影響は [fullstack セキュリティ設定ガイドのテンプレート](templates/apps/fullstack/docs/security-configuration.md.hbs) を参照してください。新規プロジェクトには `docs/security-configuration.md` と README のリンクを生成します。
|
|
100
|
+
```sh
|
|
101
|
+
hai feedback evidence feedback.zip --request-id request-42 --page 1 --page-size 20
|
|
102
|
+
hai feedback view feedback.zip
|
|
103
|
+
hai upgrade TARGET_VERSION
|
|
104
|
+
```
|
|
216
105
|
|
|
217
|
-
|
|
106
|
+
ZIPは通常単一リンクファイル、最大64MiBです。viewはランダムパスでloopbackのみ待受け、フレームワーク内蔵ビューアを使い同梱置換スクリプトを実行しません。検索結果だけでは証跡完全性を証明しません。
|
|
218
107
|
|
|
219
|
-
|
|
108
|
+
upgradeは実際の消費パッケージ、CLI/deploy、catalog/lock/導入状態、skillカスタマイズを比較し、マイグレーションを実行しません。deploy-secretsはLinuxサーバー側Nodeと、最大64KiBの私有通常単一リンクJSONを必要とします。取込はDBデータの復元や成功リリース基準の作成ではありません。[認証情報の条件](../deploy/docs/credential-import.ja.md)
|
|
220
109
|
|
|
221
|
-
|
|
110
|
+
### AI指引とアプリ体験
|
|
222
111
|
|
|
223
|
-
|
|
112
|
+
生成アプリはAGENTS.mdと `.agents/skills/` を共有入口にし、Claude/Copilot/OpenCodeから参照します。モジュール追加は対応skill参照を補完し、独自ファイルを維持します。契約は導入版の公開型で確認します。[テンプレート構成](templates/README.md)
|
|
224
113
|
|
|
225
|
-
|
|
114
|
+
Fullstackにはユーザー/役割、監査、フィードバック、プロフィール、テーマ、言語UIがあります。初期パスワードは私有環境/Secretで配布し、CLIは値を表示しません。不足アカウントを作成し、既存ユーザーはリセットしません。ネイティブ表示名はCore、成果物名は工程IDを使用します。
|
|
226
115
|
|
|
227
|
-
|
|
116
|
+
## 設定
|
|
228
117
|
|
|
229
|
-
|
|
118
|
+
`hai.json.build.images` は役割/context/Dockerfile/ポート、build.sources/build.proxyはダウンロード、deployは対象を選びます。ソースはofficial/cn/custom、代理はinherit/system/custom/none。コマンド引数は今回のみ上書きします。[設定手順](../../docs/usage/configuration/delivery.md)
|
|
230
119
|
|
|
231
|
-
|
|
120
|
+
HAI優先度はプロセス > 環境私有 > 共通私有 > 環境公開 > 基本env > YAML。同一出所は親JSONの後に細項を適用し、高優先の親は低優先の細項を除去します。認証/SSH設定は私有、ビルドは配布秘密を読みません。通常の後端設定は再起動、構成・プロキシ・HTTPS・公開パスは配布/再ビルドです。[実行設定](../../docs/usage/configuration/runtime.md)
|
|
232
121
|
|
|
233
|
-
|
|
122
|
+
contextは信頼でき安定していることが前提です。依存ソース/キャッシュは通常単一リンク、祖先はsymlink/junction不可。追跡ファイルは16MiB、アーカイブは64KiB単位で比較/コピーします。未変更mtimeを維持し、更新は原子的に置換。診断はパス/原因/コードのみで清単内容を表示しません。
|
|
234
123
|
|
|
235
|
-
|
|
124
|
+
pnpm工程には該当deepmerge/DaisyUI補丁ファイルとpatchedDependencies登録を保持します。npmパッケージを導入しても、この倉庫の補丁設定は自動継承しません。[補丁](../../patches/)
|
|
236
125
|
|
|
237
|
-
|
|
126
|
+
## エラー処理
|
|
238
127
|
|
|
239
|
-
|
|
128
|
+
失敗は安全な理由、パス/段階と非ゼロ終了で報告します。インストール失敗は生成ファイルを残し、ビルド失敗は成功latestを進めません。秘密を引数/ログに入れず、計画・事前検査・取込結果を配布成功と扱いません。設定、権限、前提を修正して失敗段階を再試行し、結果不明時は先に事実を確認します。
|
|
240
129
|
|
|
241
130
|
## 開発とテスト
|
|
242
131
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
フレームワークのルートで実行し、現在のソースから生成します。デプロイ検証には接続可能な Podman/Docker も必要です。
|
|
132
|
+
倉庫根で現在のソースを使います。
|
|
246
133
|
|
|
247
134
|
```sh
|
|
248
|
-
pnpm --filter @h-ai/cli build
|
|
249
|
-
node packages/cli/dist/index.js create ../my-app
|
|
250
135
|
pnpm --filter @h-ai/cli typecheck
|
|
251
136
|
pnpm --filter @h-ai/cli lint
|
|
137
|
+
pnpm --filter @h-ai/cli build
|
|
138
|
+
node packages/cli/dist/index.js create ../my-app
|
|
252
139
|
pnpm --filter @h-ai/cli test
|
|
253
140
|
pnpm check:skills
|
|
254
141
|
pnpm --filter @h-ai/cli test:scaffold-gates
|
|
255
|
-
pnpm --filter @h-ai/cli test:scaffold-gates --list --json
|
|
256
142
|
pnpm --filter @h-ai/cli test:deploy-gates
|
|
257
143
|
```
|
|
258
144
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
生成検証は実工程でインストール、typecheck、lint、build、test、ブラウザー操作に加え、生成した HTTP ルート、CLI プロセスの言語選択と環境ファイルの消費を検証します。`--generate` と `--i18n` で対象を絞って再実行できます。デプロイ検証は実リソースの所有権と動的ホストポートの分離に加え、オフライン tar、SSH/手動配布、増分更新とロールバックを扱います。当該実行が記録したコンテナー ID と専用イメージ tag だけを回収します。安全なメタデータは ignored の `tmp/validation/module-review/VERIFY-05/` に残します。生成したブラウザー画像、trace とレポートは既定で ignored の `tmp/validation/module-review/scaffold-browser/` または `deploy-browser/` に保持します。明示した証拠・HTML・出力先も尊重し、一時プロジェクト、鍵、データとプロセスは回収します。ネイティブと実クラウドは別途検証してください。
|
|
262
|
-
|
|
263
|
-
Windows インストーラーの追加検証には Rust の `x86_64-pc-windows-msvc` ターゲットと MSVC ビルドツールが必要です。`HAI_CLI_NATIVE_BUILD=1` を設定して `pnpm --filter @h-ai/cli test:scaffold-gates` を実行すると、既存の fullstack シナリオが NSIS インストーラーを構築し、アプリルートのバージョンと成果物名を照合します。`CARGO_BUILD_JOBS=2` で Rust の構築並列数を制限できます。ネイティブ UI 操作と機器機能は別途検証します。
|
|
264
|
-
|
|
265
|
-
デプロイ用 fixture は固定版の公開基盤イメージを確認し、不在を確認した場合だけ取得します。HAI_DEPLOY_E2E_MIRROR を利用でき、公開キャッシュは回収対象にしません。create 成功時のコンテナー ID を先に記録し、専用 PID namespace 内で APT/pip/sshd を非同期準備します。準備失敗、期限超過、協調的取消ではローカルクライアントの終了を待ち、記録した ID だけを削除して消失を確認します。特権を使うのはネストした Podman fixture のみです。HAI_DEPLOY_E2E_APT_MIRROR はホスト名のみを受け付け、HTTPS を維持します。所有権テストは固定公開イメージに実行専用 tag を付け、同じ内容の外部 tag、tag の付け替え、動的ポート、外部 sentinel の保護を維持します。create の応答喪失で信頼できる ID がない場合や、テストが強制終了した場合は不明状態を残し、名前や label を根拠に回収しません。
|
|
266
|
-
|
|
267
|
-
`--generate` は対象を絞ったルート検証です。インストール済み依存を再利用し、SvelteKit・serv API・fullstack バックエンドを実際に生成・ビルドして新ルートへアクセスします（transport を含む）。完全なインストールとブラウザー検証の代わりにはなりません。
|
|
268
|
-
|
|
269
|
-
`test:e2e` は各サービスに隔離されたテスト用バックエンドと絶対データパスを明示します。サービス子プロセスは外部の `HAI_*` / `PUBLIC_*` / `VITE_*` 設定やユーザーの `.env.local` を読み込みません。テスト専用の `HAI_E2E=1` は通常開発・本番の dotenv と共有バックエンド要件を変更せず、transport は毎回生成する信頼済み SM2 ring と実際の registry を使います。生成プロジェクトのブラウザー検証では独立 TCP 計数プロセスで外部 DB への接続がないことも確認します。完全な fullstack デプロイ検証では実 Redis/S3、増分更新とロールバックを維持します。
|
|
270
|
-
|
|
271
|
-
ブラウザー向けフロントエンドを持つ fullstack プロジェクトでは、1 つの `playwright.config.ts` を使います。`pnpm test:e2e` は通常の回帰テストを実行した後、別のデータディレクトリでサービスを起動し直し、ページ離脱とアイドルタイムアウトを検証します。
|
|
272
|
-
|
|
273
|
-
`--i18n` は CLI をビルドし、独立プロセスで言語の優先順位・help・生成成功・失敗を検証し、中国語/英語/日本語の入力・検証・取消と create/add/init も確認します。
|
|
145
|
+
脚手架ゲートは実際に導入、コンパイル、生成アプリのテストとブラウザ操作を行い、配布ゲートはPodman/Dockerが必要です。`--generate` と `--i18n` はルートと言語の定向検査。隔離fixtureは本番データや外部Provider検証の代わりではありません。WindowsネイティブゲートはRust/MSVCと明示的なHAI_CLI_NATIVE_BUILD=1、実機操作は別途検証します。
|
|
274
146
|
|
|
275
147
|
## ライセンス
|
|
276
148
|
|