@h-ai/cli 0.1.0-alpha.64 → 0.1.0-alpha.66

package/README.en.md

@@ -4,8 +4,12 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
 
+For creation, traditional/AI-first development, compilation, packaging, deployment, and upgrades, follow the [complete usage guide](../../docs/usage/README.en.md). This page provides detailed CLI and template references.
+
 > hai Agent Framework CLI: interactive project scaffolding and code generation.
 
+`pnpm build` / `hai build` compiles source by default. Use `pnpm build --target docker` to build/export app + optional Web images (Podman first, Docker fallback), or `pnpm build --target desktop --platform windows|linux|macos` for Tauri on the matching host. Build does not select deployment environments. `hai deploy` consumes existing artifacts and uploads one Compose tar; `--bundle-only --output release.tar` generates a manual-transfer bundle without SSH. Fullstack `pnpm run deploy --env test` publishes API/Web together. See [deploy usage and offline prerequisites](../deploy/README.en.md). Test artifacts are cleaned in finally/teardown, including failures.
+
 ## Capabilities
 
 `hai deploy` exits nonzero on missing modules/configuration, credential loading, scanning, initialization, deployment, or closure failures. Scripts must check the exit code; only complete deployment success can unlock subsequent steps.
@@ -27,8 +31,12 @@ The CLI copies complete selected skill directories from `templates/skills/` into
 
 Every application type includes `hai-spec-review` to review requirements and designs before generation: completeness, ambiguity, technical/framework correctness, and consistent naming. It reports located issues with concrete corrections and declares generation readiness only when issues are resolved and evidence is sufficient. `hai init` / `hai add` also backfill this workflow skill while preserving custom files.
 
+Business behavior follows the user's current explicit requirements and designated requirements/design documents. Template AGENTS, README, skills, generated code and tests provide adjustable defaults for roles, permissions, workflows, limits and architecture. Review lists differences as template adaptations rather than requirements defects; authorized implementation updates conflicting code, tests and outdated guidance. Installed public API contracts, server authorization, resource isolation, input validation and credential protection still apply. Existing projects must merge this guidance explicitly; `hai init` preserves existing files.
+
 After review, the separate `hai-spec-implement` skill handles implementation from documents. Every application includes it, and `hai init` / `hai add` backfill its complete resources. AI splits work by independently verifiable features and actual dependencies, using `docs/task-list.md` and `docs/tasks/<id>-<slug>.md` by default. Each task uses its own Git branch, TDD, quality gates and a local merge; records are marked complete after the actual merge commit and integration checks. Rework keeps the same task ID, file and branch, adding a new cycle linked to prior evidence. This uses Markdown, Git and existing development/test skills, with no new runtime dependency or workflow engine. Requests can plan only, implement a document, execute T003, or repair and merge T002. Planning does not start implementation; selected tasks require completed dependencies, and remote actions follow the user's authorization.
 
+After committing requirements/design changes, ask: “I updated docs/requirements.md and docs/design.md; please update the implementation.” The skill records the accepted document SHA, fixed target document SHA and accepted implementation SHA separately in the existing task list. It compares the complete document set, including additions, deletions, renames and related effects, then updates existing tasks or creates new ones for branch-based testing and merging. It advances the baseline only after all differences are handled and overall acceptance passes; interrupted or partial work retains the old baseline. Missing baselines require historical evidence or a coverage review. See [document changes and baselines](templates/skills/hai-spec-implement/changes.md). `hai init` / `hai add` backfill the new reference; existing entrypoints, workflows and task templates still need to be merged against the updated templates.
+
 For everyday feature additions, changes and fixes, `AGENTS.md` routes to `hai-app-create/SKILL.md` and `development.md`. Map requirements to existing framework features, configuration and extension points before implementing against the installed package's exports and types. Reuse applicable capabilities and explain concrete gaps; do not install unrelated dependencies to increase module coverage. Codex uses `.agents/skills/` and the project root's persistent `AGENTS.md` rules.
 
 Tool entry points share one set of rules and skills: Codex/Cursor use AGENTS and `.agents/skills/`; Copilot's `.github/copilot-instructions.md` only references the shared `AGENTS.md`, with application-specific rules maintained there; OpenCode's opencode.json references the shared rules directly through `instructions: ["AGENTS.md"]`. Claude Code's root CLAUDE.md contains only `@AGENTS.md`; task navigation in the shared rules leads to skill bodies and references in `.agents/skills/` as needed. The CLI does not create `.claude/`, duplicate skills or require symlinks. This setup does not register native Claude skills or `/skill` commands; existing Claude settings and skills are preserved. Sources: [Claude project instructions](https://code.claude.com/docs/en/memory), [Claude native skills](https://code.claude.com/docs/en/skills), [Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), [OpenCode](https://docs.opencode.ai/docs/skills/), [Cursor](https://cursor.com/docs/skills).
@@ -154,21 +162,25 @@ pnpm.cmd install
 pnpm.cmd dev
 ```
 
-The CLI generates a root `.env` with a unique random strong `HAI_ADMIN_DEFAULT_PASSWORD`, so `dev` / `start` work directly. Sign in as `admin` using that password; an environment variable with the same name overrides it. Passwords follow `_iam.yml` policy, with a default minimum of 8 characters. Startup logs include the specific validation reason and error code when a password violates the policy. Once users exist, the variable does not reset accounts or passwords. Git and container builds ignore `.env`, while `.env.example` contains only a placeholder. Set a separate password in each deployment environment.
+Add `--features deploy` to install a matching project-local `@h-ai/deploy` development dependency for automated deployment. Fullstack does not install AI/ONNX/CUDA by default. Image builds download the official SQLite prebuild matching the driver version, Node ABI, architecture and libc, retry and validate it, then reuse the cache. No compiler toolchain is preinstalled; missing binaries or network failures stop the build.
+
+The CLI generates a root `.env.local` with a unique random strong `HAI_ADMIN_DEFAULT_PASSWORD`, so `dev` / `start` work directly. Sign in as `admin` using that password; an environment variable with the same name overrides it. Passwords follow `_iam.yml` policy, with a default minimum of 8 characters. Startup logs include the specific validation reason and error code when a password violates the policy. Once users exist, the variable does not reset accounts or passwords. Git and container builds ignore `.env.local`, while `.env.example` contains only a placeholder. Set a separate password in each deployment environment.
 
 - Administrators can search, paginate, create, edit, enable, disable and delete users and upload avatars. The server protects the current administrator and rechecks authorization inside a mutation lock so concurrent actions cannot remove every administrator's access.
-- Roles are fixed as `admin` / `user`. The role page shows member counts and edits descriptions; the user page assigns roles. Ordinary users only access personal settings, and the server rejects direct management API calls from them.
+- Initial roles are `admin` / `user`. The role page shows member counts and edits descriptions; the user page assigns roles. By default, ordinary users only access personal settings, and the server rejects direct management API calls from them. Adapt these business rules to actual requirements.
 - The audit page filters by action, resource and date. Successful login, logout, password changes and management writes produce audit records without passwords, tokens or avatar contents.
 - Personal settings cover profile, avatar, language, theme and password changes. Preferences are stored in IAM user metadata. Avatars accept PNG/JPEG/WebP up to 512 KiB; the server validates image contents and generates the storage key.
 
 The typed api-client and serv crypto transport encrypt JSON business requests, login and refresh in both directions. Web uses an in-memory access token and an HttpOnly refresh Cookie. Native App uses Capacitor secure TokenStorage; native Desktop stores tokens only in memory and requires login after restart. The native refresh body channel verifies the client identifier, explicit transport header and trusted Origin; browser previews use Cookie mode. Public avatars are binary image resources restricted by a whitelist.
 
-Web/App/Desktop share one `AdminWorkspace`, management store and typed client. Current-user and refresh routes use the framework's default IAM procedures; theme caching and DOM updates use `@h-ai/ui/theme`. Application code composes fixed roles, self-protection, avatars and business auditing.
+Web/App/Desktop share one `AdminWorkspace`, management store and typed client. Current-user and refresh routes use the framework's default IAM procedures; theme caching and DOM updates use `@h-ai/ui/theme`. Application code composes initial roles, self-protection, avatars and auditing as example business rules that can change with actual requirements.
 
 Default SQLite, local storage and memory cache suit a single-instance mini administration service. Management writes support one writer instance. Multiple read instances require shared database, storage, Redis cache and sticky transport sessions; all management writes must still reach the same writer. Redis alone does not provide atomic last-administrator protection across arbitrary writers. Generated root scripts provide typecheck, lint, build, test and test:e2e; Capacitor/Tauri delivery additionally requires the appropriate native build and packaging.
 
 ## Application configuration and display
 
+Each project documents its variables, enums and bounds in `.env.example`. The [root catalog](../../.env.example) covers all modules; the [environment configuration](templates/skills/hai-app-create/development.md#环境配置) explains mode loading and common scripts.
+
 Every generated `.gitignore` includes `**/data/`, covering runtime data and `.gitkeep` at every workspace depth. Runtime code creates the required directories.
 
 Fullstack always includes 13 `.yml` files in `packages/<project>-serv/config/`: `_core`, `_serv`, `_db`, `_cache`, `_iam`, `_storage`, `_audit`, `_reach`, `_ai`, `_vecdb`, `_payment`, `_scheduler`, and `_deploy`. Used modules retain working defaults; unused modules, optional fields, and alternative providers remain as comments. `.env.example` also includes commented credentials for unused modules. Module choices entered during creation are preserved.
@@ -181,16 +193,26 @@ Core environment overrides include `HAI_CORE_NAME`, `HAI_CORE_VERSION`, `HAI_COR
 
 Leaf overrides apply only to existing YAML paths: uncomment the key first, or replace the whole object with `HAI_DB`, `HAI_CACHE`, etc. CamelCase remains one segment: `connectTimeout` maps to `HAI_CACHE_CONNECTTIMEOUT`. Locale lists belong in each frontend/shared `project.inlang/settings.json`; `_core.yml` specifies only the default locale.
 
-The automatically generated fullstack `.env` enables only the initial administrator password and `PUBLIC_API_BASE`. Module overrides remain commented so YAML supplies defaults. Explicitly uncomment environment overrides when needed, and check existing overrides when editing YAML.
+The automatically generated fullstack `.env.local` enables only the initial administrator password and `PUBLIC_API_BASE`. Module overrides remain commented so YAML supplies defaults. Explicitly uncomment environment overrides when needed, and check existing overrides when editing YAML.
 
 SvelteKit server layouts expose only whitelisted public metadata such as name, version, environment and default locale. Standalone mobile-app Vite configuration parses YAML through core in the Node build process and injects public values plus browser logging level/format; YAML or override changes require a rebuild. Fullstack frontends obtain public server metadata through encrypted `app.info`. No template exposes complete core/module configuration, secrets or log-redaction context to the browser.
 
+## Environment-specific deployment
+
+Run `hai deploy --env test` to check `.env.test` first, then choose defaults, custom connections or keep unchanged for each middleware. `--yes` keeps complete target settings and otherwise uses the current backend defaults; `--env-dir` selects the environment directory. Specify the service directory explicitly, for example `hai deploy packages/my-app-serv --env test`; workspace layouts are not guessed. Startup scripts carry the selected environment. Public connections go to the target file; credentials go to `.env.local` with redacted output.
+
+Choose “deploy directly” in the wizard, or run `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`, to skip all middleware prompts, configuration writes and provisioning when your environment is complete. Missing deployment targets are guided through SSH/Vercel setup. Host, ports, key paths, remote directory and tokens are saved only in Git-ignored `.env.local` and reused on later runs. Edit `HAI_DEPLOY_PROVIDER` there to change the target; supply private key paths only.
+
 ## Global options
 
-| Option             | Description               |
-| ------------------ | ------------------------- |
-| `-v, --verbose`    | Verbose output            |
-| `-C, --cwd <path>` | Set the working directory |
+See the [usage guide](../../docs/usage/README.en.md) for build/deploy meanings, defaults, and examples. Deliverables use the application root package.json version, not the CLI version.
+
+| Option             | Description       | Default           | Example                       |
+| ------------------ | ----------------- | ----------------- | ----------------------------- |
+| `-v, --verbose`    | Verbose output    | false             | `hai create my-app --verbose` |
+| `-C, --cwd <path>` | Working directory | Current directory | `hai build --cwd ../my-app`   |
+| `-h, --help`       | Command help      | false             | `hai build --help`            |
+| `-V, --version`    | CLI version       | false             | `hai --version`               |
 
 ## Local development usage
 
@@ -277,7 +299,7 @@ Successful screenshots default to the CLI's `test-results/scaffold-evidence/`. S
 
 Failures and degraded-state messages must also be localized: website APIs use the request locale for AI fallback and email delivery status; undelivered messages must not be described as received. CLI deployment status uses cliM, and Gallery encryption limitations use bilingual messages. Verify unconfigured, failed, and successful paths in Chinese and English without paid service calls.
 
-Provisioned configuration: Neon emits HAI_DB (PostgreSQL JSON), Upstash HAI_CACHE (Redis rediss URL JSON), and R2 HAI_STORAGE (flat S3 JSON). Email/SMS emit HAI_REACH_PROVIDERS; deployApp merges both channels while preserving YAML message templates, replacing the original providers array. Core supports whole-object/array overrides, with parents preceding leaves and schema validation retained. Build subprocesses and target runtimes share provisioned values. R2 needs existing S3 accessKeyId/secretAccessKey, Resend a verified-domain from address, and Alibaba Cloud approved signName/templates. Applications need matching `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` loaded at startup; network clients require Node.
+Provisioned configuration: Neon emits HAI_DB (PostgreSQL JSON), Upstash HAI_CACHE (Redis rediss URL JSON), and R2 HAI_STORAGE (flat S3 JSON). Email/SMS emit HAI_REACH_PROVIDERS; deployApp merges both channels while preserving YAML message templates, replacing the original providers array. Core supports whole-object/array overrides, with parents preceding leaves and schema validation retained. Provisioned values are runtime-only and are never passed to build subprocesses. R2 needs existing S3 accessKeyId/secretAccessKey, Resend a verified-domain from address, and Alibaba Cloud approved signName/templates. Applications need matching `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` loaded at startup; network clients require Node.
 
 Deployment recovery: `ProvisionResult.resourceStatus` marks created/reused. `getDeployRecovery(result.error)` reads projectName, stage, platformProjectId, and resource lists; unknown means an uncertain request result that must first be checked in the provider console. Preserve returned IDs for failed resources. Recovery excludes envVars, raw exceptions, and credentials; the CLI shows resources and advice. Same-name retries reuse resources. Reused resources are never deleted automatically; clean up newly created resources only after manually confirming they are unused.
 

package/README.ja.md

@@ -4,8 +4,12 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
+作成、手作業・AI first 開発、コンパイル、パッケージ、デプロイ、更新の流れは[完全ガイド](../../docs/usage/README.ja.md)を参照してください。本ページでは CLI コマンドとテンプレートの詳細を説明します。
+
 > hai Agent Framework CLI：対話式のプロジェクト生成とコード生成ツール。
 
+`pnpm build` はソースをコンパイルします。`pnpm build --target docker` は API/Web イメージをビルドして書き出し、Podman、Docker の順に選択します。Desktop は対応 OS 上で `pnpm build --target desktop --platform windows|linux|macos` から Tauri を実行します。ビルド時に環境は選択しません。deploy は既存成果物から Compose tar を作成して転送します。`--bundle-only --output release.tar` は SSH 接続せず手動配布用の tar のみを生成します。[利用方法とオフライン準備](../deploy/README.ja.md)を参照してください。テストの一時成果物は失敗時も finally/teardown で削除します。
+
 ## 主な機能
 
 `hai deploy` はモジュール・設定不足、認証情報読み込み、走査、初期化、デプロイ、終了処理の失敗で非ゼロの終了コードを返します。スクリプトは終了コードを確認し、デプロイ全体の成功を後続処理の条件にしてください。
@@ -27,8 +31,12 @@ CLI は選択した skill のディレクトリー全体を `templates/skills/`
 
 すべてのアプリ種別に `hai-spec-review` を提供します。生成前に要件・設計の完全性、曖昧さ、技術・フレームワーク利用の正確性、命名の一貫性を厳密に確認し、箇所と具体的な修正案を報告します。問題が解決され、証拠が十分な場合のみ AI 生成に進めると判定します。`hai init` / `hai add` は既存のカスタムファイルを保持してこの skill も補完します。
 
+業務動作はユーザーの現在の明示的な要求と、指定された要件・設計文書を基準にします。テンプレートの AGENTS、README、skills、生成コードとテストにあるロール・権限・フロー・上限・構成は変更可能な初期案です。レビューでは相違をテンプレートの適応項目として扱い、要件の誤りとは判定しません。実装の権限内で競合するコード・テスト・古い規則を同期します。実際のバージョンの公開 API 契約、サーバー認可、リソース分離、入力検証、認証情報の保護は引き続き必要です。既存プロジェクトには明示的にマージしてください。`hai init` は既存ファイルを上書きしません。
+
 審査後の文書からの実装は、独立した `hai-spec-implement` が担当します。全アプリに提供し、`hai init` / `hai add` でも関連リソース全体を補完します。AI は独立して検証できる機能と実際の依存関係に基づいて分割を判断し、既定では `docs/task-list.md` と `docs/tasks/<id>-<slug>.md` を使います。各タスクは専用 Git ブランチで TDD と品質チェックを行い、ローカルでマージして実際のコミットと統合検証を記録してから完了にします。修正時は元の番号・ファイル・ブランチを再利用し、以前の証拠に関連付けた新しい実施回を追加します。Markdown、Git、既存の開発・テスト skills を使い、新しいランタイム依存やワークフローエンジンは不要です。「文書からタスク一覧だけ作成」「文書から実装」「T003 を実行」「T002 を修正してマージ」のように指定できます。計画だけの依頼では実装せず、指定タスクは依存を確認し、リモート操作はユーザーの許可範囲に従います。
 
+要件・設計文書の変更をコミットした後は、「docs/要件.md と docs/設計.md を変更したので、実装を更新してください」と依頼できます。Skill は既存の一覧に、受入済み文書 SHA、固定した目標文書 SHA、検証済み実装 SHA を分けて記録します。文書全体の追加・削除・改名と関連影響を比較し、既存タスクの更新または新規作成を行い、対応ブランチでテスト・マージします。全差分の処理と全体の受入検証が完了してから基準を更新し、中断・部分完了では旧基準を保持します。基準がない場合は履歴の根拠または実装との照合が必要です。[文書差分と基準の手順](templates/skills/hai-spec-implement/changes.md) を参照してください。`hai init` / `hai add` は新しい参照ファイルを補完しますが、既存の入口・実行手順・タスク雛形は更新版と照合してマージしてください。
+
 通常の機能追加・変更・修正では、`AGENTS.md` が `hai-app-create/SKILL.md` と `development.md` に案内します。要件を既存のフレームワーク機能・設定・拡張点に対応付け、インストール済みバージョンの exports と型を確認して実装します。適用できる機能を優先して再利用し、不足する能力を具体的に説明します。利用率のために無関係な依存を追加しません。Codex は `.agents/skills/` とプロジェクトルートの `AGENTS.md` を使用します。
 
 各ツールの入口は一つの規則と skill を共有します。Codex/Cursor は AGENTS と `.agents/skills/` を使用します。Copilot の `.github/copilot-instructions.md` は共通の `AGENTS.md` のみを参照し、アプリ種別の規則もそこに集約します。OpenCode の opencode.json は `instructions: ["AGENTS.md"]` で共通規則を直接参照します。Claude Code のルート CLAUDE.md は `@AGENTS.md` のみを含み、共有規則のタスク案内から `.agents/skills/` の本文と参照ファイルを必要時に読みます。CLI は `.claude/` を生成せず、skill の複製やシンボリックリンクも不要です。この構成では Claude のネイティブ skill 自動検出や `/skill` コマンドは登録されません。既存の Claude 設定と skill は保持します。根拠：[Claude プロジェクト指針](https://code.claude.com/docs/en/memory)、[Claude ネイティブ skills](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)、[OpenCode](https://docs.opencode.ai/docs/skills/)、[Cursor](https://cursor.com/docs/skills)。
@@ -154,21 +162,25 @@ pnpm.cmd install
 pnpm.cmd dev
 ```
 
-CLI はルート `.env` にプロジェクトごとに異なるランダムな強い `HAI_ADMIN_DEFAULT_PASSWORD` を生成するため、`dev` / `start` を直接実行できます。初回ログインは `admin` とそのパスワードを使います。同名の環境変数で上書きできます。パスワードは `_iam.yml` のポリシーに従い、既定では 8 文字以上です。違反すると起動ログに具体的な理由とエラーコードを表示します。ユーザーが存在する場合、この変数でアカウントやパスワードはリセットされません。`.env` は Git とコンテナビルドから除外され、`.env.example` はプレースホルダーのみです。デプロイ先ごとに別のパスワードを設定してください。
+自動デプロイには `--features deploy` を追加し、対応する `@h-ai/deploy` をプロジェクトの開発依存としてインストールします。fullstack は既定で AI/ONNX/CUDA をインストールしません。SQLite はドライバー版、Node ABI、アーキテクチャー、libc に一致する公式バイナリーをダウンロードし、再試行・読み込み検証後にキャッシュを再利用します。コンパイラーを事前インストールせず、対応バイナリーや通信が使えなければビルドを停止します。
+
+CLI はルート `.env.local` にプロジェクトごとに異なるランダムな強い `HAI_ADMIN_DEFAULT_PASSWORD` を生成するため、`dev` / `start` を直接実行できます。初回ログインは `admin` とそのパスワードを使います。同名の環境変数で上書きできます。パスワードは `_iam.yml` のポリシーに従い、既定では 8 文字以上です。違反すると起動ログに具体的な理由とエラーコードを表示します。ユーザーが存在する場合、この変数でアカウントやパスワードはリセットされません。`.env.local` は Git とコンテナビルドから除外され、`.env.example` はプレースホルダーのみです。デプロイ先ごとに別のパスワードを設定してください。
 
 - 管理者はユーザーの検索、ページング、作成、編集、有効・無効化、削除、アバター更新を行えます。サーバーは現在の管理者を保護し、更新ロック内で認可を再確認するため、同時操作で全管理者の権限を失うことを防ぎます。
-- ロールは `admin` / `user` の 2 種類です。ロール画面は人数表示と説明編集、ユーザー画面はロール割り当てを担当します。一般ユーザーは個人設定のみ利用でき、管理 API への直接アクセスもサーバーで拒否します。
+- 初期ロールは `admin` / `user` の 2 種類です。ロール画面は人数表示と説明編集、ユーザー画面はロール割り当てを担当します。既定では一般ユーザーは個人設定のみ利用でき、管理 API への直接アクセスもサーバーで拒否します。これらの業務規則は実際の要件に合わせて変更できます。
 - 監査画面は操作、リソース、日付で記録を検索します。ログイン成功、ログアウト、パスワード変更、管理の書き込みを監査に記録し、パスワード、token、アバター内容は含めません。
 - 個人設定はプロフィール、アバター、言語、テーマ、パスワード変更を提供します。設定は IAM ユーザー metadata に保存します。アバターは PNG/JPEG/WebP、最大 512 KiB で、サーバーが画像内容を検証して storage key を生成します。
 
 型付き api-client と serv の crypto transport が、JSON 業務リクエスト、ログイン、更新を双方向に暗号化します。Web はメモリー内 access token と HttpOnly refresh Cookie を使います。App のネイティブ版は Capacitor の安全な TokenStorage、Desktop のネイティブ版はメモリーのみを使い、再起動後は再ログインします。ネイティブの refresh body 通路はクライアント識別子、明示的な通信ヘッダー、信頼する Origin を検証し、ブラウザープレビューは Cookie モードを使います。公開アバターはホワイトリスト内のバイナリー画像リソースです。
 
-Web/App/Desktop は同じ `AdminWorkspace`、management store、型付き client を使います。現在のユーザーと refresh はフレームワーク標準 IAM procedures、テーマの保存と DOM 更新は `@h-ai/ui/theme` を使い、アプリは固定ロール、自己保護、アバター、業務監査を組み合わせます。
+Web/App/Desktop は同じ `AdminWorkspace`、management store、型付き client を使います。現在のユーザーと refresh はフレームワーク標準 IAM procedures、テーマの保存と DOM 更新は `@h-ai/ui/theme` を使います。アプリの初期ロール、自己保護、アバター、監査は業務の例であり、実際の要件に合わせて変更できます。
 
 既定の SQLite、ローカル storage、memory cache は単一インスタンスの mini 管理サービス向けです。管理の書き込みは単一 writer のみ対応します。複数の読み取りインスタンスには共有 DB、storage、Redis cache と transport セッションの固定ルーティングが必要で、管理の書き込みは同じ writer に送ります。Redis への変更だけでは任意の複数 writer 間で最後の管理者を原子的に保護できません。生成するルート scripts は typecheck、lint、build、test、test:e2e を提供し、Capacitor/Tauri の配布には対応するネイティブビルドとパッケージ作成も必要です。
 
 ## アプリ設定と表示
 
+各プロジェクトの `.env.example` に用途、列挙値と範囲を記載します。[全変数一覧](../../.env.example) と [環境設定](templates/skills/hai-app-create/development.md#环境配置) に読み込み順序と共通コマンドをまとめています。
+
 生成されるすべての `.gitignore` に `**/data/` を含め、ルートと各 workspace の実行データおよび `.gitkeep` を除外します。必要なディレクトリは実行時に作成します。
 
 Fullstack の `packages/<project>-serv/config/` は `_core`、`_serv`、`_db`、`_cache`、`_iam`、`_storage`、`_audit`、`_reach`、`_ai`、`_vecdb`、`_payment`、`_scheduler`、`_deploy` の 13 個の `.yml` を常に生成します。使用するモジュールは既定値を有効にし、未使用のモジュール、任意項目、代替 Provider はコメントとして残します。`.env.example` も未使用モジュールの認証情報をコメントで示し、作成時に指定した設定値を保持します。
@@ -183,14 +195,24 @@ SvelteKit のサーバー layout は名称、バージョン、環境、既定
 
 葉の環境変数は YAML に存在するパスだけを上書きします。コメントの項目は先に有効にするか、`HAI_DB`、`HAI_CACHE` などでオブジェクト全体を置き換えます。camelCase は分割せず、`connectTimeout` は `HAI_CACHE_CONNECTTIMEOUT` に対応します。言語一覧は各フロントエンド/shared の `project.inlang/settings.json` で管理し、`_core.yml` は既定言語のみを指定します。
 
-Fullstack が自動生成する `.env` は初期管理者パスワードと `PUBLIC_API_BASE` のみ有効にします。モジュールの環境変数上書きはコメントとして残し、YAML を既定値の元にします。必要な環境変数だけを明示的に有効にし、YAML 編集時は既存の上書きも確認します。
+Fullstack の `.env` は選択したモジュールの実行パラメーターを有効にします。YAML は同名の変数を参照し、ローカル既定値を保持します。未使用モジュールと任意フィールドはコメントとして残します。環境の切り替えは dev:test / dev:prod、start:test / start:prod を使用します。
+
+## 環境別デプロイ
+
+`hai deploy --env test` で先に `.env.test` を確認し、各ミドルウェアに既定設定・カスタム接続・変更しないを選択します。`--yes` は完全な対象設定を維持し、それ以外は現在のバックエンド既定値を使います。`--env-dir` で保存先を指定できます。対象サービスのディレクトリーを明示します（例：hai deploy packages/my-app-serv --env test）。workspace 構成を推測せず、起動スクリプトに環境を明示します。公開接続値は対象環境、認証情報は `.env.local` に保存し、表示をマスクします。
+
+設定済みの環境ではウィザードで「直接デプロイ」を選ぶか、`hai deploy packages/my-app-serv --env prod --yes --skip-middleware` を実行すると、すべてのミドルウェア設定・書き込み・リソース作成を省略できます。不足する SSH/Vercel 接続情報は対話で補完し、ホスト、ポート、鍵のパス、リモートディレクトリー、Token を Git 対象外の `.env.local` にのみ保存して再利用します。接続先は `HAI_DEPLOY_PROVIDER` で更新できます。秘密鍵は内容ではなくパスを指定します。
 
 ## 共通オプション
 
-| オプション         | 説明                     |
-| ------------------ | ------------------------ |
-| `-v, --verbose`    | 詳細な出力               |
-| `-C, --cwd <path>` | 作業ディレクトリーの指定 |
+ビルド/デプロイ引数の意味、既定値、例は[使用ガイド](../../docs/usage/README.ja.md)を参照してください。成果物には CLI の版ではなく、アプリルートの package.json の版を使います。
+
+| オプション         | 説明               | 既定値               | 例                            |
+| ------------------ | ------------------ | -------------------- | ----------------------------- |
+| `-v, --verbose`    | 詳細出力           | false                | `hai create my-app --verbose` |
+| `-C, --cwd <path>` | 作業ディレクトリー | 現在のディレクトリー | `hai build --cwd ../my-app`   |
+| `-h, --help`       | コマンドヘルプ     | false                | `hai build --help`            |
+| `-V, --version`    | CLI の版           | false                | `hai --version`               |
 
 ## 開発時のローカル利用
 

package/README.md

@@ -4,8 +4,12 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
+从创建、手工/AI first 开发到编译、打包、部署与升级，见[完整使用指南](../../docs/usage/README.md)。本页提供 CLI 命令与模板的详细参考。
+
 > hai Agent Framework CLI — 交互式项目脚手架与代码生成工具。
 
+`pnpm build` 默认编译源码；`pnpm build --target docker` 构建并导出 API/可选 Web 镜像，优先 Podman、其次 Docker。启用 Desktop 时用 `pnpm build --target desktop --platform windows|linux|macos` 在对应系统调用 Tauri。构建不选择部署环境。`hai deploy` 消费已有产物并上传一个 Compose tar；`--bundle-only --output release.tar` 仅生成包供手工搬运。fullstack 的 `pnpm run deploy --env test` 一并发布 API/Web。见 [部署用法与离线准备](../deploy/README.md)。测试临时产物由 finally/teardown 清理，失败也执行。
+
 ## 支持的能力
 
 `hai deploy` 的缺失模块/配置、凭证加载、扫描、初始化、部署和关闭失败均以非零退出码结束；脚本必须检查退出码。只有完整部署成功才可作为后续步骤的成功条件。
@@ -23,10 +27,14 @@
 
 CLI 从 `templates/skills/` 将所选 skill 的完整目录复制到生成项目 `.agents/skills/`。`SKILL.md` 提供能力边界和任务导航，`reference.md`/`guide.md` 保留按需范本；同步时不能只复制入口。AGENTS.md 保存应用约束，Claude/Copilot 桥接文件引用它；修改模板需同步相关仓库 skills。模板生成测试会核对参考文件的完整交付。
 
+业务以用户当前明确要求及其指定的需求/设计文档为准。模板 AGENTS、README、skills、生成代码及测试中的角色/权限、流程、限额和架构是可调整的初始方案。审查将差异列为模板适配项，不因偏离模板判定需求错误；实施按授权同步修改冲突代码、测试和过期规则。框架 API 仍以安装版本公开契约为准，服务端授权、资源隔离、输入校验和凭据保护仍需落实。已有项目需显式合并这些规则，`hai init` 不覆盖现有文件。
+
 所有应用类型均交付 `hai-spec-review`：生成前严格检查需求/设计文档的完备性、歧义、技术及框架使用错误、命名一致性，给出带位置和修正建议的问题清单；问题解决且证据充分后才判定可以进入 AI 生成。`hai init` / `hai add` 同时为已有项目补齐该工作流 skill，保留自定义文件。
 
 审查后的文档实施使用独立的 `hai-spec-implement`，同样交付到所有应用并由 `hai init` / `hai add` 补齐。AI 按可独立验收的功能和实际依赖决定是否拆分，默认写入 `docs/task-list.md` 与 `docs/tasks/<编号>-<slug>.md`；每项在独立 Git 分支走 TDD、门禁、本地合并，记录真实合并提交后更新清单。返修复用原任务编号、文件和分支，追加轮次并关联此前证据。流程复用 Markdown、Git 和已有开发/测试 skills，无新增运行依赖或工作流引擎。可以请求“只根据 docs/需求.md 拆分任务”“根据该文档生成代码”“执行 T003”或“T002 返修后合并”；仅规划时不实施，指定任务先核验依赖，远端操作依实际授权。
 
+需求/设计文档提交后，可以请求“我修改了 docs/需求.md、docs/设计.md，请帮我更新实现”。Skill 在原清单中区分已验收文档 SHA、固定目标文档 SHA 与已验收实现 SHA，比较完整文档集合的净差异（含增删、重命名及关联影响），更新原任务或新建任务，逐项在对应分支测试、合并。全部差异处理且整体验收通过后，才提交新的已验收基线；部分完成或中断保留旧基线。旧项目缺少可信基线时先追溯/核验，不猜测版本。详见 [文档差异与基线流程](templates/skills/hai-spec-implement/changes.md)。`hai init` / `hai add` 会补齐新增参考文件，已存在的入口、执行流程和任务范本仍须对照模板合并。
+
 日常新增、修改、修复功能由 `AGENTS.md` 引导读取 `hai-app-create/SKILL.md` 与 `development.md`：先把需求映射到框架现成功能、配置和扩展点，再依据当前安装版本的 exports/类型实现。适用能力优先复用；能力不足时说明具体缺口，不为模块覆盖率安装无关依赖。Codex 使用 `.agents/skills/`，仍需遵循项目根 `AGENTS.md` 的常驻规则。
 
 工具入口共享同一份规则与技能：Codex/Cursor 使用 AGENTS 与 `.agents/skills/`；Copilot 的 `.github/copilot-instructions.md` 只引用共享 `AGENTS.md`，不另保存各应用类型规则；OpenCode 的 opencode.json 通过 `instructions: ["AGENTS.md"]` 直接引用共享规则。Claude Code 的根 CLAUDE.md 仅包含 `@AGENTS.md`，通过共享规则的任务导航按需读取 `.agents/skills/` 正文和参考文件。CLI 不创建 `.claude/`，无需重复技能或符号链接。此模式不提供 Claude 原生技能自动发现或 `/skill` 命令；项目已有的 Claude 设置与技能保留。依据：[Claude 项目指引](https://code.claude.com/docs/en/memory)、[Claude 原生 skills](https://code.claude.com/docs/en/skills)、[Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)、[OpenCode](https://docs.opencode.ai/docs/skills/)、[Cursor](https://cursor.com/docs/skills)。
@@ -154,26 +162,30 @@ pnpm.cmd install
 pnpm.cmd dev
 ```
 
-CLI 自动生成根目录 `.env`，其中 `HAI_ADMIN_DEFAULT_PASSWORD` 是每个项目独立的随机强密码；直接运行 `dev` / `start` 即可。首次登录使用 `admin` 和 `.env` 中的密码，同名环境变量可以覆盖它。密码遵循 `_iam.yml` 策略，默认至少 8 位；不符合策略时启动日志显示具体校验原因与错误码。已有用户后，该变量不会重设账号或密码。`.env` 被 Git 和容器构建忽略，`.env.example` 仅保留占位；部署时设置目标环境自己的密码。
+需要自动部署时添加 `--features deploy`，在工程根安装对应版本的 `@h-ai/deploy` 开发依赖，部署命令会使用项目本地版本。fullstack 默认不安装 AI/ONNX/CUDA；SQLite 在镜像构建时下载匹配版本、Node ABI、架构和 libc 的官方预编译包，重试并加载校验后复用缓存；不预装编译工具链，缺包或网络失败时明确停止。
+
+CLI 自动生成根目录 `.env.local`，其中 `HAI_ADMIN_DEFAULT_PASSWORD` 是每个项目独立的随机强密码；直接运行 `dev` / `start` 即可。首次登录使用 `admin` 和 `.env.local` 中的密码，同名环境变量可以覆盖它。密码遵循 `_iam.yml` 策略，默认至少 8 位；不符合策略时启动日志显示具体校验原因与错误码。已有用户后，该变量不会重设账号或密码。`.env.local` 被 Git 和容器构建忽略，`.env.example` 仅保留占位；部署时设置目标环境自己的密码。
 
 - 管理员可搜索、分页、新增、编辑、启禁用、删除用户并上传头像；服务端保护当前管理员，管理写操作在锁内重新鉴权，防止并发操作使管理员全部失权。
-- 角色固定为 `admin` / `user`，角色页显示人数并编辑说明，用户页分配角色。普通用户仅进入个人设置，直接请求管理接口也会被服务端拒绝。
+- 初始角色为 `admin` / `user`，角色页显示人数并编辑说明，用户页分配角色。默认普通用户仅进入个人设置，直接请求管理接口也会被服务端拒绝；这些业务规则可按实际需求调整。
 - 审计页按操作、资源与日期查询记录；成功登录、退出、密码变更和管理写操作写入审计，记录不含密码、token 或头像内容。
 - 个人设置提供资料、头像、语言、主题和密码修改；偏好保存到 IAM 用户 metadata。头像接受 PNG/JPEG/WebP，最大 512 KiB，服务端验证图片内容并生成 storage key。
 
 前端 typed api-client 与 serv 的 crypto transport 统一加解密 JSON 业务、登录与刷新。Web 使用内存 access token 和 HttpOnly refresh Cookie；App 原生端使用 Capacitor 安全 TokenStorage，Desktop 原生端仅在内存保存 token，重启后重新登录。原生刷新 body 通道校验客户端标识、显式传输头和受信 Origin；浏览器预览沿用 Cookie。公开头像是白名单内的二进制图片资源。
 
-Web/App/Desktop 复用同一个 `AdminWorkspace`、management store 和 typed client。当前用户与刷新直接选用框架默认 IAM procedures，主题缓存与 DOM 更新复用 `@h-ai/ui/theme`；应用只编排固定角色、自我保护、头像与审计等业务规则。
+Web/App/Desktop 复用同一个 `AdminWorkspace`、management store 和 typed client。当前用户与刷新直接选用框架默认 IAM procedures，主题缓存与 DOM 更新复用 `@h-ai/ui/theme`；应用编排初始角色、自我保护、头像与审计等示例业务，这些规则可按实际需求调整。
 
 默认 SQLite、本地 storage 与 memory cache 适用于单实例 mini 后台。管理写入仅支持单写实例；多实例读取需要共享数据库、存储、Redis cache 和传输会话粘性路由，管理写请求仍须路由至同一实例。仅更换 Redis 不能保证任意多写副本的最后管理员原子保护。生成后的根脚本提供 typecheck、lint、build、test、test:e2e；Capacitor/Tauri 交付另执行对应原生构建和打包。
 
 ## 应用配置与显示
 
+配置字段使用显式 `HAI_<配置名>_<路径>` 引用。每个项目的 `.env.example` 包含已启用参数和可选字段的用途、枚举、范围；框架根 [`.env.example`](../../.env.example) 是完整总表。分环境加载和命令见 [环境配置](templates/skills/hai-app-create/development.md#环境配置)。
+
 所有生成项目的 `.gitignore` 都包含 `**/data/`，忽略根目录及嵌套 workspace 的运行数据，包括 `.gitkeep`；运行时会创建需要的数据目录。
 
 Fullstack 的 `packages/<project>-serv/config/` 始终保留 13 份配置：`_core`、`_serv`、`_db`、`_cache`、`_iam`、`_storage`、`_audit`、`_reach`、`_ai`、`_vecdb`、`_payment`、`_scheduler`、`_deploy`（均为 `.yml`）。已用模块保留有效默认值，未启用模块整份注释，各模块的可选字段和替代 Provider 也以注释保留。`.env.example` 同时提供未启用模块的注释凭据示例。创建时填写的模块选项会保留。
 
-扩展时先在服务端 workspace 安装所需模块，在 `src/server/runtime.ts` 按公开 Schema 校验配置、初始化并反序关闭，再取消所需配置的注释。整份注释的文件先去掉一层外层注释，可选块继续按需开启；配置文件存在并不等于业务能力已接入。切换 SQLite/Redis/S3 或 Reach Provider 时替换原连接块，同名 Provider 只保留一个。`crypto.init()` 无配置参数，datapipe 是纯函数，不生成虚构的 YAML 配置。
+扩展时先在服务端 workspace 安装所需模块，在 `src/server/runtime.ts` 按公开 Schema 校验配置、初始化并反序关闭，再取消所需配置的注释。整份注释的文件先去掉一层外层注释，可选块继续按需开启；配置文件存在并不等于业务能力已接入。数据库、缓存和存储可通过环境变量切换 Provider 并填写连接字段；Reach Provider 使用标准配置数组，同名 Provider 只保留一个。`crypto.init()` 无配置参数，datapipe 是纯函数，不生成虚构的 YAML 配置。
 
 所有模板从 `_core.yml` 统一读取 `name`、`version`、`env`、`defaultLocale` 和 `logging`，通过 `core.config` 获取元信息并使用 `core.logger`。单应用配置在 `config/`；API workspace 在 `apps/<project>-service/config/`；fullstack 在 `packages/<project>-serv/config/`。日志级别与格式由 YAML 决定，不在初始化时另写固定 `logging` 覆盖。
 
@@ -181,16 +193,20 @@ Fullstack 的 `packages/<project>-serv/config/` 始终保留 13 份配置：`_co
 
 叶子环境变量只覆盖 YAML 中已有的路径；注释掉的键须先取消注释，或使用 `HAI_DB`、`HAI_CACHE` 等整体对象覆盖。camelCase 不拆词，例如 `connectTimeout` 对应 `HAI_CACHE_CONNECTTIMEOUT`。语言列表由各前端与 shared 的 `project.inlang/settings.json` 维护，`_core.yml` 只配置默认语言。
 
-Fullstack 自动生成的 `.env` 默认只启用初始管理员密码和 `PUBLIC_API_BASE`；模块环境覆盖全部保留注释，以 YAML 为默认值来源。需要环境覆盖时显式取消对应变量的注释，修改 YAML 时同步核对已有环境覆盖。
+Fullstack 的 `.env` 启用当前模块的运行参数；YAML 引用同名变量并保留本地回退。未启用模块的变量和可选 Schema 字段保留注释。使用 `dev:test` / `dev:prod` 与服务端 `start:test` / `start:prod` 加载环境覆盖。
 
 SvelteKit 的服务端 layout 只下发名称、版本、环境和默认语言等公开白名单。独立 mobile-app 的 Vite 配置在 Node 构建阶段通过 core 解析 YAML，再注入公开值及浏览器日志级别/格式；修改 YAML 或覆盖变量后需要重新构建。Fullstack 前端通过加密的 `app.info` 获取服务端公开元信息。任何模板都不能把完整 core/模块配置、密钥或日志脱敏上下文注入浏览器。
 
 ## 全局选项
 
-| 选项               | 说明         |
-| ------------------ | ------------ |
-| `-v, --verbose`    | 显示详细输出 |
-| `-C, --cwd <path>` | 指定工作目录 |
+构建和部署参数的含义、默认值与示例见[使用指南](../../docs/usage/README.md)。交付文件使用应用根 package.json 的版本，CLI 版本不会代替应用版本。
+
+| 选项               | 说明          | 默认值   | 示例                          |
+| ------------------ | ------------- | -------- | ----------------------------- |
+| `-v, --verbose`    | 显示详细输出  | false    | `hai create my-app --verbose` |
+| `-C, --cwd <path>` | 指定工作目录  | 当前目录 | `hai build --cwd ../my-app`   |
+| `-h, --help`       | 显示命令帮助  | false    | `hai build --help`            |
+| `-V, --version`    | 显示 CLI 版本 | false    | `hai --version`               |
 
 ## 开发阶段本地使用
 
@@ -247,7 +263,19 @@ monorepo 内的 `apps/*` 项目已通过 `workspace:*` 协议引用本地包，
 node packages/cli/dist/index.js create ../my-new-project
 ```
 
-## 5. 配置驱动认证页面
+## 分环境部署
+
+运行 `hai deploy --env test`，先检查 `.env.test`，再逐项选择中间件默认配置、自定义连接或保持不变。`--yes` 保留目标环境的完整配置并为其余项采用当前后端默认值，`--env-dir` 指定环境文件目录。明确传入目标服务目录，如 `hai deploy packages/my-app-serv --env test`，不猜测 workspace 布局；容器启动脚本保留明确环境标识。公共连接项写目标环境文件，凭据写 `.env.local` 并脱敏显示。
+
+配置已完备时可在向导中选择“直接部署”，或执行 `hai deploy packages/my-app-serv --env prod --yes --skip-middleware`，跳过全部中间件提示、配置写入和资源开通。部署目标缺失时引导填写 SSH/Vercel 参数；SSH 地址、端口、密钥路径、远程目录及 Token 只保存到被 Git 忽略的 `.env.local`，下次自动复用。可编辑其中的 `HAI_DEPLOY_PROVIDER` 更新目标；私钥只填写路径。
+
+失败与降级提示也必须国际化：官网 API 按请求 locale 生成 AI 降级/邮件送达状态；未送达不能称为已接收。CLI 部署状态使用 cliM，Gallery 加密能力限制使用双语消息。中文与英文分别验证未配置、失败和成功路径，无需调用付费服务。
+
+云资源配置消费：Neon 输出 HAI_DB（PostgreSQL JSON），Upstash 输出 HAI_CACHE（Redis rediss URL JSON），R2 输出 HAI_STORAGE（扁平 S3 JSON）。邮件/短信输出 HAI_REACH_PROVIDERS 数组，deployApp 合并两个渠道并保留 YAML 中的消息模板；此覆盖替换原 providers 数组。Core 支持整体对象/数组覆盖，父节点优先于叶子变量，仍执行 Schema 校验；开通结果只进入目标运行环境，不传入构建进程。R2 必须提供已有 S3 accessKeyId/secretAccessKey；Resend 必须提供已验证域名的 from；阿里云必须提供已审核 signName/模板。应用须已有相应\_db/\_cache/\_storage/\_reach.yml 并在启动时加载，网络客户端需要 Node 运行时。
+
+部署失败恢复：`ProvisionResult.resourceStatus` 标记 created/reused；`getDeployRecovery(result.error)` 读取 projectName、stage、platformProjectId 和资源清单，unknown 表示请求结果不确定，必须先在服务商控制台核对。失败资源已返回 ID 时保留该 ID。恢复结果不含 envVars、原始异常或连接凭证，CLI 会展示清单和建议。同名重试复用现有资源；不自动删除复用资源，新建资源仅在人工确认未被使用后清理。
+
+## 配置驱动认证页面
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
@@ -275,12 +303,6 @@ Admin 与 fullstack 门禁还用实际安装的本地 tarball 验证公开类型
 
 成功截图默认保存在 CLI 的 `test-results/scaffold-evidence/`，可通过 `HAI_AUTH_EVIDENCE_DIR` 指定独立目录，生成项目清理后仍保留。fullstack E2E 启动所有已选 Web/App/Desktop 浏览器预览，并验证各端的登录、导览、帮助与个人设置；小程序和原生壳仍需要对应平台验收。
 
-失败与降级提示也必须国际化：官网 API 按请求 locale 生成 AI 降级/邮件送达状态；未送达不能称为已接收。CLI 部署状态使用 cliM，Gallery 加密能力限制使用双语消息。中文与英文分别验证未配置、失败和成功路径，无需调用付费服务。
-
-云资源配置消费：Neon 输出 HAI_DB（PostgreSQL JSON），Upstash 输出 HAI_CACHE（Redis rediss URL JSON），R2 输出 HAI_STORAGE（扁平 S3 JSON）。邮件/短信输出 HAI_REACH_PROVIDERS 数组，deployApp 合并两个渠道并保留 YAML 中的消息模板；此覆盖替换原 providers 数组。Core 支持整体对象/数组覆盖，父节点优先于叶子变量，仍执行 Schema 校验；构建子进程与目标运行环境使用相同开通结果。R2 必须提供已有 S3 accessKeyId/secretAccessKey；Resend 必须提供已验证域名的 from；阿里云必须提供已审核 signName/模板。应用须已有相应\_db/\_cache/\_storage/\_reach.yml 并在启动时加载，网络客户端需要 Node 运行时。
-
-部署失败恢复：`ProvisionResult.resourceStatus` 标记 created/reused；`getDeployRecovery(result.error)` 读取 projectName、stage、platformProjectId 和资源清单，unknown 表示请求结果不确定，必须先在服务商控制台核对。失败资源已返回 ID 时保留该 ID。恢复结果不含 envVars、原始异常或连接凭证，CLI 会展示清单和建议。同名重试复用现有资源；不自动删除复用资源，新建资源仅在人工确认未被使用后清理。
-
 ## 生成项目的表单布局
 
 website 联系页与 fullstack 管理界面复用 UI 的 FormLayout/FormField：支持一列/双列、标签独立成行/同行、自动跨列和窄容器回落。用户编辑、资料与密码表单使用同组参数，校验提示由 UI 内置中英文处理；完整配置随生成项目的 hai-ui skill 提供。

package/dist/{chunk-X3RSYNBG.js → chunk-FWN5B54L.js}

@@ -41,7 +41,52 @@ var en_US_default = {
   cli_deploy_id: "  ID: {id}",
   cli_deploy_env: "  Env: {names}",
   cli_deploy_command_failed: "Deploy command failed",
-  cli_adminPasswordSaved: "  Administrator: admin; the random initial password is saved as HAI_ADMIN_DEFAULT_PASSWORD in .env"
+  cli_adminPasswordSaved: "  Administrator: admin; the random initial password is saved as HAI_ADMIN_DEFAULT_PASSWORD in .env.local",
+  cli_deploy_environment: "Deployment environment (test / prod / other)",
+  cli_deploy_cancelled: "Deployment cancelled.",
+  cli_deploy_environment_hint: "Specify --env <environment>; non-interactive calls also require --yes, or use a terminal to select middleware.",
+  cli_deploy_middleware: "{service}: current default {backend}; {purpose}. Source: {source}",
+  cli_deploy_action: "How should {service} be configured?",
+  cli_deploy_default: "Use default configuration",
+  cli_deploy_custom: "Use custom configuration",
+  cli_deploy_keep: "Keep unchanged",
+  cli_deploy_backend: "Select the backend for {service}",
+  cli_deploy_field: "{name} ({description}; {constraint})",
+  cli_deploy_required: "This value is required",
+  cli_deploy_invalid_value: "The value does not satisfy the field constraints",
+  cli_deploy_cloud_unsupported: "No cloud provisioner is available for {backend}; use a custom connection or select a supported backend.",
+  cli_deploy_saved: "Configured {name}={value} (public values in the target environment file; credentials in .env.local)",
+  cli_deploy_secret: "[redacted]",
+  cli_deploy_missing_keep: "The target environment has no complete {service} configuration to keep.",
+  cli_deploy_s3_engine: "Select the S3 service implementation (application type remains s3)",
+  cli_deploy_target_reused: "Reusing deployment target {target}. Update connection settings in HAI_DEPLOY_PROVIDER in .env.local.",
+  cli_deploy_target_missing: "Deployment target is incomplete: {fields}. Set HAI_DEPLOY_PROVIDER in .env.local, or run interactively to complete setup.",
+  cli_deploy_target_platform: "Select the deployment platform",
+  cli_deploy_target_ssh: "SSH server (Docker / Podman Compose)",
+  cli_deploy_target_field: "{name} (saved only in .env.local)",
+  cli_deploy_target_ssh_hint: "Enter connection and port settings. Enter a private key file path, or leave blank for ssh-agent/default keys. Leave known_hosts blank for the OpenSSH default. New host fingerprints are trusted on first connection; changed fingerprints are rejected.",
+  cli_deploy_target_runtime: "Remote container runtime (auto prefers Podman)",
+  cli_deploy_target_saved: "Deployment target saved to Git-ignored .env.local and reused on subsequent runs.",
+  cli_deploy_middleware_plan: "Do you need to configure middleware for this deployment?",
+  cli_deploy_middleware_configure: "Review and configure each middleware service",
+  cli_deploy_middleware_skip: "Environment is complete; deploy directly",
+  cli_deploy_middleware_skipped: "Skipped all middleware configuration and provisioning. Deploying with current environment settings and existing services.",
+  cli_build_failed: "Build command {command} failed (exit {code}).",
+  cli_build_use_pnpm: "Run via pnpm build to use the project pnpm executable.",
+  cli_build_target_invalid: "target must be compile, docker or desktop.",
+  cli_build_options_invalid: "runtime, network, sqlite-prebuild-mirror and no-http-proxy require docker; platform and arch require desktop.",
+  cli_build_version_invalid: "Set a valid three-part version in the application root package.json (for example 1.2.3 or 1.2.3-beta.1; at most 80 characters).",
+  cli_build_native_host: "Build Tauri on the matching OS (windows/linux/macos), with x64 or arm64 architecture. Install the Rust target, system SDK and packaging tools first.",
+  cli_build_desktop_missing: "No desktop directories in hai.build.json. Generate a desktop frontend or add an existing Tauri project.",
+  cli_build_images_missing: "hai.build.json requires one app image and at most one web image.",
+  cli_build_runtime_missing: "Install and start Podman or Docker. auto prefers a reachable Podman engine.",
+  cli_build_mirror_invalid: "SQLite mirror must use HTTP(S) without credentials, query or fragment.",
+  cli_build_ready: "Build ready ({runtime}): {path}. Reuse these images across deployment environments.",
+  cli_build_native_ready: "Tauri build ready: {target}. Installers are under src-tauri/target/{target}/release/bundle in each project.",
+  cli_deploy_bundle_provider: "--bundle-only requires the docker-ssh Compose provider.",
+  cli_deploy_bundle_local: "Generate bundle only; no server connection",
+  cli_deploy_bundle_ready: "Deployment bundle ready; the server has not been deployed.",
+  cli_deploy_bundle_path: "Deployment bundle: {path}"
 };
 
 // messages/zh-CN.json
@@ -80,7 +125,52 @@ var zh_CN_default = {
   cli_deploy_id: "  \u6807\u8BC6\uFF1A{id}",
   cli_deploy_env: "  \u73AF\u5883\u53D8\u91CF\uFF1A{names}",
   cli_deploy_command_failed: "\u90E8\u7F72\u547D\u4EE4\u5931\u8D25",
-  cli_adminPasswordSaved: "  \u7BA1\u7406\u5458\uFF1Aadmin\uFF1B\u968F\u673A\u521D\u59CB\u5BC6\u7801\u5DF2\u4FDD\u5B58\u5230 .env \u7684 HAI_ADMIN_DEFAULT_PASSWORD"
+  cli_adminPasswordSaved: "  \u7BA1\u7406\u5458\uFF1Aadmin\uFF1B\u968F\u673A\u521D\u59CB\u5BC6\u7801\u5DF2\u4FDD\u5B58\u5230 .env.local \u7684 HAI_ADMIN_DEFAULT_PASSWORD",
+  cli_deploy_environment: "\u8BF7\u8F93\u5165\u90E8\u7F72\u73AF\u5883\uFF08test / prod \u7B49\uFF09",
+  cli_deploy_cancelled: "\u90E8\u7F72\u5DF2\u53D6\u6D88\u3002",
+  cli_deploy_environment_hint: "\u8BF7\u6307\u5B9A --env <\u73AF\u5883>\uFF1B\u975E\u4EA4\u4E92\u8C03\u7528\u8FD8\u9700 --yes\uFF0C\u6216\u5728\u4EA4\u4E92\u7EC8\u7AEF\u9010\u9879\u9009\u62E9\u4E2D\u95F4\u4EF6\u3002",
+  cli_deploy_middleware: "{service}\uFF1A\u5F53\u524D\u9ED8\u8BA4 {backend}\uFF1B{purpose}\u3002\u6765\u6E90\uFF1A{source}",
+  cli_deploy_action: "\u5982\u4F55\u5904\u7406 {service}\uFF1F",
+  cli_deploy_default: "\u4F7F\u7528\u9ED8\u8BA4\u914D\u7F6E",
+  cli_deploy_custom: "\u4F7F\u7528\u81EA\u5B9A\u4E49\u914D\u7F6E",
+  cli_deploy_keep: "\u4FDD\u6301\u4E0D\u53D8",
+  cli_deploy_backend: "\u8BF7\u9009\u62E9 {service} \u7684\u540E\u7AEF",
+  cli_deploy_field: "{name}\uFF08{description}\uFF1B{constraint}\uFF09",
+  cli_deploy_required: "\u6B64\u9879\u5FC5\u586B",
+  cli_deploy_invalid_value: "\u53D6\u503C\u4E0D\u6EE1\u8DB3\u5B57\u6BB5\u7EA6\u675F",
+  cli_deploy_cloud_unsupported: "{backend} \u6CA1\u6709\u53EF\u7528\u7684\u4E91\u81EA\u52A8\u5F00\u901A\u5668\uFF0C\u8BF7\u9009\u62E9\u81EA\u5B9A\u4E49\u8FDE\u63A5\u6216\u5207\u6362\u53D7\u652F\u6301\u7684\u540E\u7AEF\u3002",
+  cli_deploy_saved: "\u5DF2\u914D\u7F6E {name}={value}\uFF08\u516C\u5171\u503C\u5199\u76EE\u6807\u73AF\u5883\u6587\u4EF6\uFF0C\u51ED\u636E\u5199 .env.local\uFF09",
+  cli_deploy_secret: "[\u5DF2\u9690\u85CF]",
+  cli_deploy_missing_keep: "\u76EE\u6807\u73AF\u5883\u5C1A\u65E0 {service} \u7684\u5B8C\u6574\u914D\u7F6E\uFF0C\u4E0D\u80FD\u4FDD\u6301\u4E0D\u53D8\u3002",
+  cli_deploy_s3_engine: "\u9009\u62E9\u81EA\u5EFA S3 \u670D\u52A1\u5B9E\u73B0\uFF08\u5E94\u7528\u4ECD\u4F7F\u7528 type: s3\uFF09",
+  cli_deploy_target_reused: "\u590D\u7528\u90E8\u7F72\u76EE\u6807 {target}\u3002\u53EF\u5728 .env.local \u7684 HAI_DEPLOY_PROVIDER \u4E2D\u66F4\u65B0\u8FDE\u63A5\u53C2\u6570\u3002",
+  cli_deploy_target_missing: "\u90E8\u7F72\u76EE\u6807\u914D\u7F6E\u4E0D\u5B8C\u6574\uFF1A{fields}\u3002\u8BF7\u5728 .env.local \u4E2D\u914D\u7F6E HAI_DEPLOY_PROVIDER\uFF0C\u6216\u4F7F\u7528\u4EA4\u4E92\u7EC8\u7AEF\u5B8C\u6210\u5F15\u5BFC\u3002",
+  cli_deploy_target_platform: "\u9009\u62E9\u90E8\u7F72\u5E73\u53F0",
+  cli_deploy_target_ssh: "SSH \u670D\u52A1\u5668\uFF08Docker / Podman Compose\uFF09",
+  cli_deploy_target_field: "{name}\uFF08\u4EC5\u4FDD\u5B58\u5728 .env.local\uFF09",
+  cli_deploy_target_ssh_hint: "\u8F93\u5165\u670D\u52A1\u5668\u8FDE\u63A5\u53CA\u7AEF\u53E3\u53C2\u6570\u3002\u79C1\u94A5\u586B\u5199\u6587\u4EF6\u8DEF\u5F84\uFF1B\u7559\u7A7A\u4F7F\u7528 ssh-agent \u6216\u9ED8\u8BA4\u5BC6\u94A5\u3002known_hosts \u8DEF\u5F84\u7559\u7A7A\u4F7F\u7528 OpenSSH \u9ED8\u8BA4\u503C\u3002\u9996\u6B21\u8FDE\u63A5\u4FE1\u4EFB\u4E3B\u673A\u6307\u7EB9\uFF0C\u540E\u7EED\u62D2\u7EDD\u6307\u7EB9\u53D8\u66F4\u3002",
+  cli_deploy_target_runtime: "\u8FDC\u7A0B\u5BB9\u5668\u8FD0\u884C\u65F6\uFF08auto \u4F18\u5148\u4F7F\u7528 Podman\uFF09",
+  cli_deploy_target_saved: "\u90E8\u7F72\u76EE\u6807\u5DF2\u4FDD\u5B58\u5230 .env.local\uFF08\u5DF2\u52A0\u5165 Git \u5FFD\u7565\uFF09\uFF0C\u4E0B\u6B21\u81EA\u52A8\u590D\u7528\u3002",
+  cli_deploy_middleware_plan: "\u662F\u5426\u9700\u8981\u914D\u7F6E\u672C\u6B21\u90E8\u7F72\u7684\u4E2D\u95F4\u4EF6\uFF1F",
+  cli_deploy_middleware_configure: "\u9010\u9879\u68C0\u67E5\u5E76\u914D\u7F6E\u4E2D\u95F4\u4EF6",
+  cli_deploy_middleware_skip: "\u73AF\u5883\u914D\u7F6E\u5DF2\u5B8C\u5907\uFF0C\u76F4\u63A5\u90E8\u7F72",
+  cli_deploy_middleware_skipped: "\u5DF2\u8DF3\u8FC7\u5168\u90E8\u4E2D\u95F4\u4EF6\u914D\u7F6E\u4E0E\u8D44\u6E90\u5F00\u901A\uFF0C\u4F7F\u7528\u5F53\u524D\u73AF\u5883\u914D\u7F6E\u53CA\u5DF2\u6709\u670D\u52A1\u76F4\u63A5\u90E8\u7F72\u3002",
+  cli_build_failed: "\u6784\u5EFA\u547D\u4EE4 {command} \u5931\u8D25\uFF08\u9000\u51FA\u7801 {code}\uFF09\u3002",
+  cli_build_use_pnpm: "\u8BF7\u901A\u8FC7 pnpm build \u8FD0\u884C\u6784\u5EFA\uFF0C\u786E\u4FDD\u4F7F\u7528\u5F53\u524D\u9879\u76EE\u7684 pnpm\u3002",
+  cli_build_target_invalid: "target \u5FC5\u987B\u4E3A compile\u3001docker \u6216 desktop\u3002",
+  cli_build_options_invalid: "runtime\u3001network\u3001sqlite-prebuild-mirror\u3001no-http-proxy \u4EC5\u7528\u4E8E docker\uFF1Bplatform\u3001arch \u4EC5\u7528\u4E8E desktop\u3002",
+  cli_build_version_invalid: "\u8BF7\u5728\u5E94\u7528\u6839 package.json \u4E2D\u8BBE\u7F6E\u6709\u6548\u7684\u4E09\u6BB5\u5F0F\u7248\u672C\uFF08\u5982 1.2.3 \u6216 1.2.3-beta.1\uFF0C\u6700\u957F 80 \u5B57\u7B26\uFF09\u3002",
+  cli_build_native_host: "Tauri \u9700\u8981\u5728\u5BF9\u5E94\u7CFB\u7EDF\u4E0A\u6784\u5EFA\uFF08windows/linux/macos\uFF09\uFF0C\u67B6\u6784\u4E3A x64 \u6216 arm64\uFF1B\u8BF7\u5148\u5B89\u88C5\u5BF9\u5E94 Rust target\u3001\u7CFB\u7EDF SDK \u548C\u6253\u5305\u5DE5\u5177\u3002",
+  cli_build_desktop_missing: "hai.build.json \u672A\u914D\u7F6E desktop \u76EE\u5F55\u3002\u8BF7\u751F\u6210 desktop \u524D\u7AEF\u6216\u6DFB\u52A0\u5DF2\u6709\u7684 Tauri \u5DE5\u7A0B\u3002",
+  cli_build_images_missing: "hai.build.json \u5FC5\u987B\u5305\u542B\u4E00\u4E2A app \u955C\u50CF\u548C\u81F3\u591A\u4E00\u4E2A web \u955C\u50CF\u3002",
+  cli_build_runtime_missing: "\u8BF7\u5B89\u88C5\u5E76\u542F\u52A8 Podman \u6216 Docker\u3002auto \u4F18\u5148\u9009\u62E9\u53EF\u7528\u7684 Podman\u3002",
+  cli_build_mirror_invalid: "SQLite \u955C\u50CF\u5730\u5740\u5FC5\u987B\u4E3A HTTP(S)\uFF0C\u4E0D\u80FD\u5305\u542B\u51ED\u636E\u3001\u67E5\u8BE2\u6216\u7247\u6BB5\u3002",
+  cli_build_ready: "\u6784\u5EFA\u5B8C\u6210\uFF08{runtime}\uFF09\uFF1A{path}\u3002\u6B64\u955C\u50CF\u53EF\u7528\u4E8E\u4E0D\u540C\u90E8\u7F72\u73AF\u5883\u3002",
+  cli_build_native_ready: "Tauri \u6784\u5EFA\u5B8C\u6210\uFF1A{target}\uFF0C\u5B89\u88C5\u5305\u4F4D\u4E8E\u5BF9\u5E94\u5DE5\u7A0B src-tauri/target/{target}/release/bundle\u3002",
+  cli_deploy_bundle_provider: "--bundle-only \u4EC5\u9002\u7528\u4E8E docker-ssh\uFF0C\u8BF7\u9009\u62E9 Compose \u90E8\u7F72\u76EE\u6807\u3002",
+  cli_deploy_bundle_local: "\u4EC5\u751F\u6210\u90E8\u7F72\u5305\uFF0C\u4E0D\u8FDE\u63A5\u670D\u52A1\u5668",
+  cli_deploy_bundle_ready: "\u90E8\u7F72\u5305\u5DF2\u751F\u6210\uFF1B\u670D\u52A1\u5668\u5C1A\u672A\u90E8\u7F72\u3002",
+  cli_deploy_bundle_path: "\u90E8\u7F72\u5305\uFF1A{path}"
 };
 
 // src/cli-i18n.ts
@@ -374,5 +464,5 @@ async function generateProjectAiSupport(projectPath, skillNames, options = {}) {
 }
 
 export { cliM, generateModuleSkillFile, generateProjectAiSupport, generateSkillFiles, resolveCompatibleSkillNames, resolveSkillNamesForPackages };
-//# sourceMappingURL=chunk-X3RSYNBG.js.map
-//# sourceMappingURL=chunk-X3RSYNBG.js.map
+//# sourceMappingURL=chunk-FWN5B54L.js.map
+//# sourceMappingURL=chunk-FWN5B54L.js.map