@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,205 @@
+# @h-ai/cli
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+> hai Agent Framework CLI: interactive project scaffolding and code generation.
+
+## 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.
+
+- **Project creation**: guided creation of SvelteKit apps, Svelte 5 mobile/desktop frontends, and hai backends.
+- **Module addition**: incrementally enable modules in an existing project with dependency resolution.
+- **Configuration initialization**: validate completeness and create missing configuration files.
+- **Code generation**: pages, components, API endpoints, data models, and migrations.
+- **Templates**: minimal / default / full / custom project templates.
+- **Feature composition**: enable IAM, DB, AI, Storage, Crypto, and more as needed.
+- **API service scaffolding**: compose contracts/procedures with `@h-ai/api-contract` + `@h-ai/serv`, consumed through the `@h-ai/api-client` typed client.
+- **Dependency resolution**: selecting features automatically includes their dependencies (for example, IAM adds Crypto).
+
+## AI usage guidance
+
+The CLI copies complete selected skill directories from `templates/skills/` into the generated project's `.agents/skills/`. `SKILL.md` defines boundaries and task navigation; `reference.md`/`guide.md` hold on-demand examples. Do not copy only the entry file. AGENTS.md holds application constraints and Claude/Copilot bridge files reference it. Template changes must sync relevant repository skills. Generation tests verify delivery of reference files.
+
+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-specific entry points share the same guidance: Codex/Cursor use AGENTS and `.agents/skills/`; Copilot uses `.github/copilot-instructions.md` and shared skills; OpenCode uses AGENTS, opencode.json and shared skills. Claude Code uses CLAUDE.md and native `.claude/skills/<name>/SKILL.md` aliases containing discovery metadata and a link to the shared body. References stay in `.agents/skills/`, without symlink permissions or duplicated skill bodies. Sources: [Claude](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).
+
+Generated projects share `eslint-rules.js`. Lint rejects explicit `any`, console calls, unexplained suppressions, double unknown assertions, internal framework source imports and writes to known sensitive localStorage keys. A necessary third-party workaround requires a documented local exception. Static rules do not prove authorization, input safety, transaction behavior or log redaction; verify those through tests and review.
+
+For existing projects, update the CLI and run `hai init` to fill missing workflow skills, resources and entry files. Existing files are preserved, including AI rules when using `--force`. Merge existing entry files, skills, ESLint configuration and scripts against a newly generated project, and restore missing .npmrc/.gitignore files; filling missing files does not upgrade old rules. Before release, use the CLI built from this repository to create the comparison project and keep unpublished capabilities separate from installed package capabilities.
+
+Before writing AI files, the CLI resolves existing file and directory links. Shared skills, Claude aliases and project bridges must stay inside the project; external targets stop the write. Linking Claude's skill directory to the shared directory inside the project remains supported.
+
+Delivery checks cover both the package archive and generated projects. Source `.npmrc` / `.gitignore` templates use a `.hbs` suffix to avoid packaging exclusions; generation restores their normal names and preserves dependency layout and sensitive-artifact ignore rules. An archive regression verifies every template is in the `.tgz`, beyond creation from the source checkout.
+
+## Quick start
+
+Requires Node.js ≥ 22.12.0; generated root projects and workspace packages declare the same minimum.
+
+### Create a project
+
+```bash
+# 交互式创建（推荐）
+npx hai create my-admin-app
+
+# 指定模板与功能
+npx hai create my-app -t full
+npx hai create my-app -t custom -f iam,db,ai
+```
+
+Interactive steps:
+
+1. Enter the project name.
+2. Choose a template (minimal / default / full / custom).
+3. Select feature modules (custom template).
+4. Choose whether to include example code.
+5. Choose a package manager (pnpm / npm / yarn).
+6. Choose whether to install dependencies.
+7. Choose whether to initialize Git.
+
+### Add modules
+
+```bash
+# 交互式选择
+npx hai add
+
+# 指定模块
+npx hai add iam
+npx hai add storage
+```
+
+Add modules incrementally to an existing project. The CLI updates `package.json`, creates configuration, and resolves dependencies.
+
+### Initialize/validate configuration
+
+```bash
+# 校验配置完整性，补全缺失配置
+npx hai init
+
+# 强制重新生成所有配置
+npx hai init --force
+```
+
+### Code generation
+
+Names must start with a letter and contain only letters, digits, hyphens, or underscores; paths are rejected. All outputs are preflighted and overwrites rejected by default; only explicit `--force` replaces files. Outputs and symlink targets must stay in the working directory.
+
+Page/API generators target SvelteKit; components use Svelte 5 children snippets. APIs use `kit.handler` and Zod validation. Migrations export explicit `up()` / `down()`; initialize `reldb` before calling and check HaiResult afterward. This is not an automatic migration runner. `down()` deletes tables and requires application confirmation before execution.
+
+```bash
+# 交互式生成
+npx hai generate
+
+# 指定类型
+npx hai generate page users
+npx hai generate component UserCard
+npx hai generate api users
+npx hai generate model user
+npx hai generate migration add-users
+
+# 快捷命令
+npx hai g:page dashboard
+npx hai g:component StatusBadge
+npx hai g:api orders
+npx hai g:model order
+```
+
+## Project templates
+
+| Template  | Description | Included features                                         |
+| --------- | ----------- | --------------------------------------------------------- |
+| `minimal` | Minimal     | Basic SvelteKit/hai skeleton (Svelte 5 + Vite on mobile)  |
+| `default` | Default     | IAM + DB + Cache + Crypto                                 |
+| `full`    | Full        | All business modules + API Service / contract integration |
+| `custom`  | Custom      | Choose as needed                                          |
+
+## Global options
+
+| Option             | Description               |
+| ------------------ | ------------------------- |
+| `-v, --verbose`    | Verbose output            |
+| `-C, --cwd <path>` | Set the working directory |
+
+## Local development usage
+
+> For local CLI development in the monorepo before publishing to npm.
+
+### 1. Build
+
+```bash
+# 构建 CLI（生成 dist/）
+pnpm --filter @h-ai/cli build
+
+# 或启动 watch 模式（修改源码后自动重建）
+pnpm --filter @h-ai/cli dev
+```
+
+### 2. Run directly (no installation)
+
+After building, invoke `dist/index.js` directly with `node`:
+
+```bash
+# 从仓库根目录运行
+node packages/cli/dist/index.js create my-app
+node packages/cli/dist/index.js create my-app --type admin --features iam,db
+```
+
+Or invoke it by absolute path from any directory:
+
+```bash
+node /path/to/hai-framework/packages/cli/dist/index.js create my-app
+```
+
+### 3. Global linking (`pnpm link`)
+
+To use `hai` directly in a terminal, create a global link:
+
+```bash
+# 在 packages/cli 目录下执行
+cd packages/cli
+pnpm link --global
+
+# 验证
+hai --version
+hai create my-app
+```
+
+> Remove the link afterward with `pnpm unlink --global @h-ai/cli`.
+
+### 4. Use in other monorepo apps
+
+Projects in `apps/*` reference local packages through `workspace:*` and can use them directly:
+
+```bash
+# 在仓库根目录执行，对任意 app 类型生成项目
+node packages/cli/dist/index.js create ../my-new-project
+```
+
+### 5. Run tests
+
+```bash
+# 单元测试 + E2E 模板生成测试
+pnpm --filter @h-ai/cli test
+
+# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
+pnpm --filter @h-ai/cli test:e2e
+
+# watch 模式
+pnpm --filter @h-ai/cli test:watch
+
+# 覆盖率
+pnpm --filter @h-ai/cli test:coverage
+```
+
+## License
+
+Apache-2.0
+
+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.
+
+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

@@ -0,0 +1,205 @@
+# @h-ai/cli
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+> hai Agent Framework CLI：対話式のプロジェクト生成とコード生成ツール。
+
+## 主な機能
+
+`hai deploy` はモジュール・設定不足、認証情報読み込み、走査、初期化、デプロイ、終了処理の失敗で非ゼロの終了コードを返します。スクリプトは終了コードを確認し、デプロイ全体の成功を後続処理の条件にしてください。
+
+- **プロジェクト作成**：SvelteKit アプリ、Svelte 5 モバイル・デスクトップ画面、hai バックエンドを対話式で生成。
+- **モジュール追加**：既存プロジェクトに機能を追加し、依存関係を自動解決。
+- **設定初期化**：設定の完全性を検証し、不足ファイルを生成。
+- **コード生成**：ページ、コンポーネント、API endpoint、データモデル、DB マイグレーションを生成。
+- **テンプレート**：minimal / default / full / custom の 4 種類。
+- **機能の組み合わせ**：IAM、DB、AI、Storage、Crypto などを必要に応じて有効化。
+- **API サービス生成**：`@h-ai/api-contract` + `@h-ai/serv` で公開 contract / procedures を組み合わせ、`@h-ai/api-client` の型付きクライアントで利用。
+- **依存関係の自動解決**：機能選択時に依存を追加（例：IAM が Crypto を追加）。
+
+## AI 向け使用ガイド
+
+CLI は選択した skill のディレクトリー全体を `templates/skills/` から生成先の `.agents/skills/` にコピーします。`SKILL.md` は機能の境界とタスク案内、`reference.md`/`guide.md` は必要時に読む例を提供します。入口だけをコピーしてはいけません。AGENTS.md にアプリの制約を置き、Claude/Copilot のブリッジから参照します。テンプレート変更は関連するリポジトリー skill と同期し、生成テストで参照ファイルの完全な提供を確認します。
+
+通常の機能追加・変更・修正では、`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` と共有技能、OpenCode は AGENTS・opencode.json と共有技能を使用します。Claude Code は CLAUDE.md と `.claude/skills/<name>/SKILL.md` のネイティブ入口を使用し、発見用メタデータと共有本文へのリンクだけを保持します。参照ファイルは `.agents/skills/` に置き、シンボリックリンク権限や本文の複製は不要です。根拠：[Claude](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)。
+
+生成プロジェクトは `eslint-rules.js` を共有します。lint は明示的な `any`、console、説明のない抑制、unknown を介した二重アサーション、フレームワーク内部ソースの import、既知の機密 localStorage キーへの書き込みを拒否します。必要なサードパーティーの回避策は局所的な説明を付けます。権限分離・入力安全性・トランザクション・ログのマスキングは静的規則だけでは証明できないため、テストとレビューで確認します。
+
+既存プロジェクトは CLI を更新して `hai init` を実行すると、不足するワークフロー skill・参照リソース・入口ファイルが補完されます。`--force` を使っても既存の AI 規則は上書きしません。既存の入口・skills・ESLint 設定・scripts は新規生成プロジェクトと比較してマージし、不足する .npmrc/.gitignore も補完してください。ファイル補完だけで古い規則は更新されません。公開前は本リポジトリーでビルドした CLI で比較用プロジェクトを生成し、未公開の能力とインストール済みパッケージの能力を区別します。
+
+AI ファイルの書き込み前に既存のファイル・ディレクトリーリンクを解決します。共有 skill、Claude 入口、プロジェクトのブリッジはプロジェクト内に限定し、外部へのリンクでは書き込みを停止します。プロジェクト内で Claude の skill ディレクトリーを共有ディレクトリーへリンクする構成は引き続き利用できます。
+
+配布検証はパッケージアーカイブと生成プロジェクトの両方を対象にします。`.npmrc` / `.gitignore` のテンプレート源には `.hbs` を付けて梱包時の除外を避け、生成時に通常の名前へ戻します。依存配置と機密生成物の無視規則を維持し、全テンプレートが `.tgz` に含まれることを回帰検証します。
+
+## クイックスタート
+
+Node.js ≥ 22.12.0 が必要です。生成するルートプロジェクトと各 workspace パッケージも同じ最低バージョンを宣言します。
+
+### プロジェクトの作成
+
+```bash
+# 交互式创建（推荐）
+npx hai create my-admin-app
+
+# 指定模板与功能
+npx hai create my-app -t full
+npx hai create my-app -t custom -f iam,db,ai
+```
+
+対話式の手順：
+
+1. プロジェクト名を入力。
+2. テンプレートを選択（minimal / default / full / custom）。
+3. 機能モジュールを選択（custom の場合）。
+4. サンプルコードを追加するか選択。
+5. パッケージマネージャーを選択（pnpm / npm / yarn）。
+6. 依存をインストールするか選択。
+7. Git を初期化するか選択。
+
+### モジュールの追加
+
+```bash
+# 交互式选择
+npx hai add
+
+# 指定模块
+npx hai add iam
+npx hai add storage
+```
+
+既存プロジェクトにモジュールを追加します。`package.json` の更新、設定生成、依存解決を自動実行します。
+
+### 設定の初期化・検証
+
+```bash
+# 校验配置完整性，补全缺失配置
+npx hai init
+
+# 强制重新生成所有配置
+npx hai init --force
+```
+
+### コード生成
+
+名前は英字で始まり、英字・数字・ハイフン・アンダースコアのみ使用でき、パスは受け付けません。既定では全出力を事前確認して上書きを拒否し、明示的な `--force` のみで置換します。出力とシンボリックリンク先は作業ディレクトリー内に限定されます。
+
+ページ/API 生成は SvelteKit 向けで、コンポーネントは Svelte 5 の children snippet を使います。API は `kit.handler` と Zod 入力検証を使用します。マイグレーションは明示的な `up()` / `down()` を出力し、実行前に `reldb` を初期化、実行後に HaiResult を確認します。自動マイグレーションランナーではありません。`down()` はテーブルを削除するため、アプリ側の確認後に実行してください。
+
+```bash
+# 交互式生成
+npx hai generate
+
+# 指定类型
+npx hai generate page users
+npx hai generate component UserCard
+npx hai generate api users
+npx hai generate model user
+npx hai generate migration add-users
+
+# 快捷命令
+npx hai g:page dashboard
+npx hai g:component StatusBadge
+npx hai g:api orders
+npx hai g:model order
+```
+
+## プロジェクトテンプレート
+
+| テンプレート | 説明       | 含まれる機能                                              |
+| ------------ | ---------- | --------------------------------------------------------- |
+| `minimal`    | 最小構成   | 基本的な SvelteKit/hai 構成（モバイルは Svelte 5 + Vite） |
+| `default`    | 標準構成   | IAM + DB + Cache + Crypto                                 |
+| `full`       | 全機能構成 | すべての業務モジュール + API Service / contract の仕組み  |
+| `custom`     | カスタム   | 必要に応じて選択                                          |
+
+## 共通オプション
+
+| オプション         | 説明                     |
+| ------------------ | ------------------------ |
+| `-v, --verbose`    | 詳細な出力               |
+| `-C, --cwd <path>` | 作業ディレクトリーの指定 |
+
+## 開発時のローカル利用
+
+> npm 公開前に monorepo 内で CLI をローカル実行・デバッグする場合に使います。
+
+### 1. ビルド
+
+```bash
+# 构建 CLI（生成 dist/）
+pnpm --filter @h-ai/cli build
+
+# 或启动 watch 模式（修改源码后自动重建）
+pnpm --filter @h-ai/cli dev
+```
+
+### 2. 直接実行（インストール不要）
+
+ビルド後、`node` で `dist/index.js` を直接実行できます：
+
+```bash
+# 从仓库根目录运行
+node packages/cli/dist/index.js create my-app
+node packages/cli/dist/index.js create my-app --type admin --features iam,db
+```
+
+任意のディレクトリーから絶対パスでも実行できます：
+
+```bash
+node /path/to/hai-framework/packages/cli/dist/index.js create my-app
+```
+
+### 3. グローバルリンク（`pnpm link`）
+
+ターミナルで `hai` を直接使うにはグローバルリンクを作成します：
+
+```bash
+# 在 packages/cli 目录下执行
+cd packages/cli
+pnpm link --global
+
+# 验证
+hai --version
+hai create my-app
+```
+
+> 使用後は `pnpm unlink --global @h-ai/cli` でリンクを解除できます。
+
+### 4. monorepo のほかの app で使用
+
+`apps/*` は `workspace:*` でローカルパッケージを参照し、そのまま利用できます：
+
+```bash
+# 在仓库根目录执行，对任意 app 类型生成项目
+node packages/cli/dist/index.js create ../my-new-project
+```
+
+### 5. テスト実行
+
+```bash
+# 单元测试 + E2E 模板生成测试
+pnpm --filter @h-ai/cli test
+
+# 真实脚手架 E2E 门禁（生成项目后执行 install/typecheck/lint/build/test/e2e）
+pnpm --filter @h-ai/cli test:e2e
+
+# watch 模式
+pnpm --filter @h-ai/cli test:watch
+
+# 覆盖率
+pnpm --filter @h-ai/cli test:coverage
+```
+
+## License
+
+Apache-2.0
+
+失敗・縮退時の表示も国際化します。サイト API はリクエストの locale で AI 縮退・メール到達状態を表示し、未到達を受信済みと表現しません。CLI のデプロイ状態は cliM、Gallery の暗号化制限は二言語メッセージを使います。中国語・英語で未設定・失敗・成功を検証し、有料サービスの呼び出しは不要です。
+
+クラウド設定の利用：Neon は HAI_DB（PostgreSQL JSON）、Upstash は HAI_CACHE（Redis rediss URL JSON）、R2 は HAI_STORAGE（フラットな S3 JSON）を出力します。メール・SMS は HAI_REACH_PROVIDERS を出力し、deployApp が両チャネルと YAML のメッセージテンプレートを統合して元の providers 配列を置換します。Core はオブジェクト・配列全体の上書きをサポートし、親ノードを末端より優先して Schema 検証を維持します。ビルド子プロセスと対象環境は同じ値を使います。R2 は既存の S3 accessKeyId/secretAccessKey、Resend は検証済みドメインの from、Alibaba Cloud は承認済み signName・テンプレートが必要です。アプリは対応する `_db.yml` / `_cache.yml` / `_storage.yml` / `_reach.yml` を起動時に読み込み、ネットワーククライアントには Node が必要です。
+
+デプロイ失敗からの復旧：`ProvisionResult.resourceStatus` は created/reused を示します。`getDeployRecovery(result.error)` で projectName、stage、platformProjectId、リソース一覧を取得し、unknown は結果不明なので先にサービス側の管理画面で確認します。失敗リソースの ID が返った場合は保持します。復旧情報に envVars・元の例外・接続認証情報は含まれず、CLI が一覧と提案を表示します。同名の再試行は既存リソースを再利用し、自動削除しません。新規作成分も未使用を人が確認した後にのみ削除します。

package/README.md

@@ -1,5 +1,9 @@
 # @h-ai/cli
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
 > hai Agent Framework CLI — 交互式项目脚手架与代码生成工具。
 
 ## 支持的能力
@@ -19,6 +23,18 @@
 
 CLI 从 `templates/skills/` 将所选 skill 的完整目录复制到生成项目 `.agents/skills/`。`SKILL.md` 提供能力边界和任务导航，`reference.md`/`guide.md` 保留按需范本；同步时不能只复制入口。AGENTS.md 保存应用约束，Claude/Copilot 桥接文件引用它；修改模板需同步相关仓库 skills。模板生成测试会核对参考文件的完整交付。
 
+日常新增、修改、修复功能由 `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` 与共享技能；OpenCode 使用 AGENTS、opencode.json 与共享技能。Claude Code 使用 CLAUDE.md 和 `.claude/skills/<name>/SKILL.md` 原生入口，该入口仅保留发现元数据并指向共享正文，参考文件仍只维护在 `.agents/skills/`。无需符号链接权限，也不为每个工具复制完整正文。依据：[Claude](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)。
+
+生成项目共享 `eslint-rules.js`，lint 拦截显式 `any`、console、无理由抑制、双重 unknown 断言、框架内部源码导入及明确的 localStorage 敏感键写入；合理的第三方 workaround 需局部说明。静态规则不能证明权限隔离、输入安全、事务或日志脱敏，相关行为仍需测试与审查。
+
+已有项目先更新 CLI，再运行 `hai init` 补齐缺失的流程 skill、参考资源和入口；该操作保留现有文件，即使 `--force` 也不覆盖 AI 规则。旧入口、已存在的 skills、ESLint 配置与脚本需要对照新生成项目合并，缺失的 .npmrc/.gitignore 也需补齐；只补文件不会自动升级旧规则。模板变更未发布前可通过本仓库构建的 CLI 生成对照项目，不要把未发布能力当作已安装包能力。
+
+AI 文件写入前会解析已有文件和目录链接；共享技能、Claude 入口与项目桥接文件均限制在当前项目内。链接指向项目外时停止写入；项目内 Claude 目录链接到共享技能的用法仍受支持。
+
+交付验证同时检查发布归档和生成项目。`.npmrc` / `.gitignore` 在模板源中使用 `.hbs` 后缀，避免打包时被排除；生成时仍恢复正常文件名，保留依赖布局与敏感产物忽略规则。归档回归检查全部模板都进入 `.tgz`，不能仅验证源码目录中的 create。
+
 ## 快速开始
 
 要求 Node.js ≥ 22.12.0；生成的根项目和工作区包均声明相同最低版本。