@hagicode/hagiscript 0.1.6-dev.47.1.59c65fa → 0.1.7

package/README.md

@@ -1,231 +1,356 @@
-# Hagiscript Runtime Guide
+# Hagiscript
 
 [![npm version](https://img.shields.io/npm/v/%40hagicode%2Fhagiscript?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/hagiscript)
 [![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fhagiscript?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/hagiscript)
 [![license](https://img.shields.io/badge/license-MIT-ffd43b)](./LICENSE)
 
-`@hagicode/hagiscript` is the runtime management CLI behind the `hagicode-runtime` contract. Use it to install, inspect, update, remove, and operate a managed HagiCode runtime without depending on system Node.js, system PM2, or host-global npm packages.
+`@hagicode/hagiscript` is the scoped npm package foundation for future Hagiscript language tooling. This initial package intentionally keeps runtime behavior small: it exposes version metadata, a baseline runtime-info API, and an executable CLI placeholder that can be built, tested, packed, and published safely.
 
-## Install
+## Installation Assumptions
 
-```bash
-npm install -g @hagicode/hagiscript
-```
+- Node.js 20 or newer is required.
+- npm is the package manager for this standalone repository.
+- The npm package name is `@hagicode/hagiscript`.
+- GitHub Actions publishing uses `npm publish --provenance`. Local manual publishing should use plain `npm publish` unless you are inside a supported trusted publishing environment.
 
-Primary entrypoints:
+## Usage
 
-- `hagiscript`
-- `hagicode-runtime` (`hagiscript runtime ...` wrapper)
+Install the package from npm:
 
-Node.js 20 or newer is required to run the package itself.
+```bash
+npm install @hagicode/hagiscript
+```
 
-## Runtime Model
+The installed CLI command remains `hagiscript`.
 
-By default, Hagiscript loads `runtime/manifest.yaml` and manages the runtime under `~/.hagicode/runtime`.
+Run the CLI locally during development:
 
-```text
-<runtime-root>/
-  program/
-    bin/
-    npm/
-    components/
-  runtime-data/
-    config/
-    logs/
-    data/
-    components/
-    state.json
+```bash
+npm run dev -- --help
+npm run dev -- info
+npm run dev -- install-node --target .tmp/node-runtime
+npm run dev -- check-node --target .tmp/node-runtime
+npm run dev -- npm-sync --runtime .tmp/node-runtime --manifest manifest.json
 ```
 
-The split is intentional:
-
-- `program/` holds managed executables, vendored payloads, wrappers, and the managed npm prefix.
-- `runtime-data/` holds mutable config, logs, state, PM2 data, and component-specific writable files.
-
-The packaged manifest currently manages:
+After building, run the compiled CLI:
 
-- `node` - managed Node.js runtime
-- `dotnet` - managed .NET runtime
-- `npm-packages` - managed npm prefix, including `pm2`
-- `omniroute` - vendored bundled runtime
-- `code-server` - vendored bundled runtime
+```bash
+npm run build
+node dist/cli.js --version
+node dist/cli.js info
+node dist/cli.js install-node --target .tmp/node-runtime
+node dist/cli.js check-node --target .tmp/node-runtime
+node dist/cli.js npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
 
-## Core Runtime Commands
+### Managed Node.js Runtime Commands
 
-Install the full runtime:
+`install-node` downloads an official Node.js archive from `https://nodejs.org/dist`, extracts it into the target directory, and verifies both `node` and `npm` before reporting success.
 
 ```bash
-hagiscript runtime install
+hagiscript install-node --target /opt/hagiscript/node
+hagiscript install-node --target /opt/hagiscript/node20 --version 20
+hagiscript install-node --target /opt/hagiscript/lts --version lts
 ```
 
-Install selected components only:
+When `--version` is omitted, Hagiscript installs the latest available Node.js 22 release. Supported selectors are `lts`, `latest`, `current`, a major version such as `22`, an exact version such as `22.12.0`, or an exact version with a `v` prefix such as `v22.12.0`.
 
-```bash
-hagiscript runtime install --components node,npm-packages
-```
+The target path must be missing or empty. Hagiscript refuses to install into a non-empty target directory and does not delete existing user files. During installation, temporary staging files are created beside the target directory and cleaned up after success or failure.
 
-Preview planned changes without mutating files:
+Example success output:
 
-```bash
-hagiscript runtime install --dry-run
-hagiscript runtime update --check-only
+```text
+Installing Node.js 22 into /opt/hagiscript/node
+Download progress: 100%
+Node.js runtime installed successfully.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
 ```
 
-Inspect the canonical runtime state:
+`check-node` validates an existing runtime directory and exits with code `0` only when both `node --version` and `npm --version` succeed.
 
 ```bash
-hagiscript runtime state
-hagiscript runtime state --json
+hagiscript check-node --target /opt/hagiscript/node
 ```
 
-Update or remove managed components:
+Example valid output:
 
-```bash
-hagiscript runtime update
-hagiscript runtime remove --components code-server --purge
+```text
+Node.js runtime is valid.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
 ```
 
-Override the runtime root or manifest when needed:
+Example invalid output exits non-zero and includes the failure reason:
 
-```bash
-hagiscript runtime install --runtime-root /srv/hagicode/runtime
-hagiscript runtime state --from-manifest /path/to/runtime-manifest.yaml --json
+```text
+Node.js runtime is invalid.
+Target: /opt/hagiscript/node
+Reason: missing executable
 ```
 
-If you prefer the runtime-oriented wrapper:
+### npm Global Package Synchronization
+
+`npm-sync` aligns npm global packages inside a HagiScript-managed Node.js runtime with a JSON manifest. By default, it verifies or installs the managed runtime at `~/.hagiscript/node-runtime` and uses that runtime's `npm`; it does not use or mutate npm from the ambient shell `PATH`. Existing automation can keep passing `--runtime` to use an explicit runtime directory.
 
 ```bash
-hagicode-runtime install --runtime-root /srv/hagicode/runtime
+hagiscript npm-sync --manifest ./manifest.json
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+hagiscript npm-sync --manifest ./manifest.json --force
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/ --mirror-only
+```
+
+Compatibility manifest schema:
+
+```json
+{
+  "registryMirror": "https://registry.npmmirror.com/",
+  "packages": {
+    "<npm-package-name>": {
+      "version": "<semver range>",
+      "target": "<optional npm install selector>"
+    }
+  }
+}
 ```
 
-## Runtime State and Maintenance
+The required `version` field accepts package.json-style semver ranges such as `^1.2.0`, `>=1.0.0 <2.0.0`, or `1.0.0 || 2.0.0`. The optional `target` field controls the selector used for `npm install -g`; when omitted, Hagiscript installs `<package>@<version>`.
 
-`hagiscript runtime state --json` is the canonical inspection surface for automation. It reports:
+By default, `npm-sync` plans installed packages that already satisfy the requested range as `noop` and skips `npm install -g` for them. Use `--force` to skip that installed-package satisfaction check and re-run sync for matching packages. `--force` does not upgrade packages to the latest version and does not change semver selection; it only turns an otherwise skipped `noop` action into an executable `sync` action.
 
-- resolved runtime root
-- `program/` and `runtime-data/` locations
-- per-component install status
-- per-component runtime data homes
-- derived PM2 homes for managed services
-- program/data path separation
+The optional top-level `registryMirror` field configures the npm registry used for both inventory and install commands. It must be a non-empty absolute `http:` or `https:` URL. When present, HagiScript first appends `--registry <registryMirror>` to `npm list -g --depth=0 --json` and `npm install -g <package>@<selector>` without changing package selection. If that mirror-backed npm command fails, HagiScript automatically retries the same inventory or install command once against the official npm registry `https://registry.npmjs.org/`. This mirror-first retry scope is intentionally limited to npm inventory and package mutation commands; runtime validation, manifest validation, and package planning do not retry. This is useful for public mirrors such as `https://registry.npmmirror.com/` or enterprise registries such as `https://npm.company.example/repository/npm/`.
 
-Use it before and after maintenance work to confirm the expected component set and writable paths.
+Product-managed tool sync can use the expanded `tools` manifest shape. Mandatory tools are always included using internally pinned versions from `src/runtime/tool-sync-catalog.config.json`: OpenSpec skills (`skills@1.5.1`), OmniRoute (`omniroute@3.6.9`), and code-server (`code-server@4.117.0`). Optional agent CLI sync is enabled explicitly; selected built-in CLIs or custom npm packages are added when provided.
 
-Typical maintenance flow:
+```json
+{
+  "registryMirror": "https://npm.company.example/repository/npm/",
+  "tools": {
+    "optionalAgentCliSyncEnabled": true,
+    "selectedOptionalAgentCliIds": ["codex", "claude-code", "fission-openspec", "opencode"],
+    "customAgentClis": [
+      {
+        "packageName": "@scope/agent-cli",
+        "version": "^1.0.0"
+      }
+    ]
+  }
+}
+```
 
-1. Check current state: `hagiscript runtime state --json`
-2. Apply changes: `hagiscript runtime install`, `update`, or `remove`
-3. Re-check state to confirm the final layout
-4. Operate services through `hagiscript pm2 ...`
+The first built-in optional agent CLI IDs are `codex` (`@openai/codex@0.125.0`), `claude-code` (`@anthropic-ai/claude-code@2.1.119`), `fission-openspec` (`@fission-ai/openspec@1.3.1`), `qoder` (`@qoder-ai/qodercli@0.1.48`), and `opencode` (`opencode-ai@1.14.24`). These built-in package versions are pinned in `src/runtime/tool-sync-catalog.config.json`. HagiScript validates unknown tool IDs, npm package names, and version selectors before `npm list` or `npm install` runs.
 
-Lifecycle commands print the resolved manifest, managed root, changed component count, skipped entries, and log file path when a log is generated.
+Use `--registry-mirror <url>` when automation needs to override the manifest registry for a single run. Precedence is CLI override first, manifest `registryMirror` second, and npm's default registry behavior third. If neither the CLI nor manifest provides a mirror, HagiScript does not add `--registry` and existing npm defaults, `.npmrc`, or environment configuration continue to apply.
 
-## Managed PM2 Services
+Use `--mirror-only` when a run must stay on the configured mirror and must not retry against `https://registry.npmjs.org/`. When omitted, automatic official-registry fallback remains enabled by default for mirror-backed npm inventory and install commands.
 
-Hagiscript manages runtime-scoped PM2 services for:
+For simple product-managed requests, optional CLI selections can be provided directly without writing a manifest:
 
-- `omniroute`
-- `code-server`
+```bash
+hagiscript npm-sync --selected-agent-cli codex
+hagiscript npm-sync --selected-agent-cli codex --custom-agent-cli @scope/agent-cli@^1.0.0
+```
 
-Supported actions:
+Example manifest for openspec and skills tooling:
+
+```json
+{
+  "packages": {
+    "@openspec/cli": {
+      "version": "^1.0.0"
+    },
+    "@hagicode/skills": {
+      "version": ">=0.5.0 <1.0.0",
+      "target": "0.5.4"
+    }
+  }
+}
+```
 
-- `start`
-- `stop`
-- `status`
+During execution, Hagiscript validates the manifest and runtime before any npm install command runs, lists global packages with `/opt/hagiscript/node/bin/npm list -g --depth=0 --json`, plans no-op, install, upgrade, downgrade, or sync actions, and then runs `npm install -g <package>@<selector>` only for packages that need changes. With `--force`, packages that already satisfy the requested range are replanned from `noop` to `sync`, so the same selector is installed again to re-sync the existing target.
 
-Examples:
+Example output:
 
-```bash
-hagiscript pm2 omniroute status
-hagiscript pm2 omniroute start
-hagiscript pm2 code-server stop
+```text
+Manifest validated: ./manifest.json (2 packages, mode=packages)
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Runtime validated: /opt/hagiscript/node
+node: /opt/hagiscript/node/bin/node (v22.12.0)
+npm: /opt/hagiscript/node/bin/npm (10.9.0)
+Detected global packages: 4
+Plan: @openspec/cli noop installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
+Skip: @openspec/cli already satisfies range
+Plan: @hagicode/skills upgrade installed=0.4.0 required=>=0.5.0 <1.0.0 selector=@hagicode/skills@0.5.4
+Install: @hagicode/skills using @hagicode/skills@0.5.4
+Synced: @hagicode/skills (upgrade)
+npm-sync complete.
+Runtime: /opt/hagiscript/node
+Manifest: ./manifest.json
+Mode: packages
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Fallback used: no
+Packages: 2
+No-op: 1
+Changed: 1
 ```
 
-The PM2 flow is runtime-scoped:
+Forced re-sync example:
 
-- PM2 is installed into the managed npm prefix, not the host environment.
-- Hagiscript resolves the runtime manifest before every PM2 action.
-- PM2 runs with the managed Node runtime and managed PATH ordering.
-- `PM2_HOME` is derived from the managed runtime layout, so service state stays inside the runtime data boundary.
+```text
+$ hagiscript npm-sync --manifest ./manifest.json --force
+Plan: @openspec/cli sync installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
+Install: @openspec/cli using @openspec/cli@^1.0.0
+Synced: @openspec/cli (sync)
+```
 
-This means maintenance scripts should call `hagiscript pm2 ...` instead of a system `pm2` binary.
+When fallback is triggered, HagiScript logs `Fallback used: ...` during execution and records `Fallback detail: ...` in the final summary so CI or desktop automation can see which mirror failed, which official registry retry was used, and whether that retry succeeded.
 
-## Runtime Environment Contract
+### Runtime Package Management
 
-Runtime lifecycle scripts and managed services receive a stable environment contract:
+`hagiscript runtime` adds a manifest-driven package manager for the broader `hagicode-runtime` contract. By default it loads `runtime/manifest.yaml` from the installed package, resolves the managed runtime root to `~/.hagicode/runtime`, then splits that managed runtime into a program home and a mutable runtime-data home unless `--runtime-root <path>` overrides the base location for a specific install, deployment mode, or automation run.
 
-- `HAGICODE_RUNTIME_HOME` - runtime program home
-- `HAGICODE_RUNTIME_DATA_HOME` - writable runtime data home for the current component
-- `PM2_HOME` - PM2 state directory for the current managed service
-- `PATH` - rebuilt so managed Node, managed npm, and managed wrappers come first
+```bash
+hagiscript runtime install
+hagiscript runtime install --components node,npm-packages --dry-run
+hagiscript runtime update --runtime-root /opt/hagicode/runtime --check-only
+hagiscript runtime remove --components code-server --purge
+hagiscript runtime state --json
+```
 
-This contract is what keeps installs, updates, wrappers, and PM2-managed services aligned to the same runtime root.
+The packaged runtime manifest aligns its default component boundaries with HagiCode Desktop:
 
-## Manifest Customization
+- Node is governed as a Desktop-aligned Node 22 toolchain component.
+- `.NET` is modeled as a Desktop-aligned 10.0 runtime component.
+- Mutable npm packages, including the managed `pm2` binary, are installed into a managed prefix under the runtime program home instead of the immutable Node payload or host-global npm locations.
+- `code-server` and `omniroute` stay grouped as vendored bundled-runtime components rather than npm-managed packages.
 
-`runtime/manifest.yaml` controls the runtime shape. Common override points:
+The runtime layout is explicit and stable for downstream consumers:
 
-- `paths.runtimeRoot`
-- `paths.runtimeHome`
-- `paths.runtimeDataRoot`
-- `paths.componentDataRoot`
-- `paths.defaultPm2Home`
-- component `runtimeDataDir`
-- service `pm2.appName`
-- service `pm2.cwd`
-- service `pm2.script`
-- service `pm2.args`
-- service `pm2.env`
-- service `pm2.pm2Home`
+```text
+<runtime-root>/
+  program/
+    bin/
+    npm/
+    components/
+  runtime-data/
+    config/
+    logs/
+    data/
+    components/
+    state.json
+```
+
+`hagiscript runtime state --json` is the canonical contract for install, update, remove, and downstream inspection. It reports the resolved runtime home, runtime data root, per-component runtime data homes, and derived PM2 homes so Desktop, local bootstrap flows, or automation does not need to probe files directly.
 
-For deployment-specific behavior, keep the packaged manifest as the baseline and pass `--from-manifest` with an override manifest rather than mutating the installed package in place.
+Runtime lifecycle scripts and managed PM2 services receive the same public runtime environment contract:
 
-## Related Runtime Tooling
+- `HAGICODE_RUNTIME_HOME` points to the runtime program home.
+- `HAGICODE_RUNTIME_DATA_HOME` points to the current component's writable runtime data home.
+- `PM2_HOME` defaults to a child directory beneath `HAGICODE_RUNTIME_DATA_HOME`.
+- `PATH` is rebuilt so the managed Node runtime, managed npm prefix, and managed wrappers take precedence over the ambient shell environment.
 
-### Managed Node Runtime
+### Managed PM2 Service Commands
 
-Install a standalone managed Node.js runtime:
+`hagiscript pm2` manages the runtime-scoped `omniroute` and `code-server` services through the PM2 binary installed by `hagiscript runtime install`.
 
 ```bash
-hagiscript install-node --target /opt/hagiscript/node
-hagiscript install-node --target /opt/hagiscript/node22 --version 22
+hagiscript pm2 omniroute start
+hagiscript pm2 omniroute status
+hagiscript pm2 code-server stop
 ```
 
-Validate an existing managed Node.js runtime:
+Each PM2 command resolves the runtime manifest first, loads the canonical runtime homes, derives a component-scoped `PM2_HOME`, and executes the managed PM2 binary from `<runtime-home>/npm`. It does not rely on a system PM2 or a system Node on the ambient shell `PATH`.
 
-```bash
-hagiscript check-node --target /opt/hagiscript/node
-```
+The packaged `runtime/manifest.yaml` can override:
 
-### Managed npm Package Sync
+- runtime-level `paths.runtimeHome`, `paths.runtimeDataRoot`, `paths.componentDataRoot`, and `paths.defaultPm2Home`
+- component-level `runtimeDataDir`
+- service-level `pm2.appName`, `pm2.cwd`, `pm2.script`, `pm2.args`, `pm2.env`, and `pm2.pm2Home`
 
-Sync npm global packages into a managed runtime instead of the host environment:
+The package also ships a thin `hagicode-runtime` wrapper binary that delegates to `hagiscript runtime ...` for automation that prefers a runtime-oriented entrypoint:
 
 ```bash
-hagiscript npm-sync --manifest ./manifest.json
-hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+hagicode-runtime install --runtime-root /srv/hagicode/runtime
 ```
 
-This is mainly useful when runtime maintenance also needs a controlled agent CLI or package inventory inside the managed runtime.
+Use the library API from ESM consumers:
 
-## Development
+```ts
+import { createRuntimeInfo, getPackageMetadata } from "@hagicode/hagiscript";
 
-Run from `repos/hagiscript/`:
+console.log(getPackageMetadata());
+console.log(createRuntimeInfo());
+```
+
+## Development Commands
+
+Run all commands from `repos/hagiscript/`:
 
 ```bash
 npm install
+npm run lint
+npm run format:check
 npm test
 npm run build
 npm run pack:check
 ```
 
-Useful runtime-focused checks:
+Additional commands:
+
+```bash
+npm run clean
+npm run format
+npm run test:watch
+npm run publish:prepare-dev-version
+npm run publish:verify-release -- v0.1.0
+```
+
+## Build Outputs
+
+`npm run build` compiles TypeScript with strict NodeNext settings into `dist/`. Expected entry points include:
+
+- `dist/index.js`
+- `dist/index.d.ts`
+- `dist/index.js.map`
+- `dist/cli.js`
+- `dist/cli.d.ts`
+- `dist/cli.js.map`
+
+The package `exports` field points consumers to `dist/index.js` and `dist/index.d.ts`. The published package name is `@hagicode/hagiscript`, and the `bin.hagiscript` entry points to `dist/cli.js`.
+
+## Package Verification
+
+`npm run pack:check` runs a dry-run package inspection and fails if required runtime files are missing or source-only files are accidentally included. The published package should contain generated `dist` files and documentation, not raw tests, scripts, coverage, or temporary files.
+
+## Release Automation
+
+GitHub Actions provide three automation paths:
+
+- `ci.yml` installs dependencies with `npm ci`, then runs tests, build, and package verification.
+- `npm-publish.yml` resolves a unique prerelease version from `main`, stamps both `package.json` and `package-lock.json` with `npm version --no-git-tag-version`, then publishes to the `dev` dist-tag.
+- `npm-publish.yml` also publishes stable GitHub releases tagged as `vX.Y.Z` to the `latest` dist-tag after validating the tag format, rejecting tags older than the repository base version, and stamping the stable version the same way.
+- `release-drafter.yml` keeps a categorized release draft using `.github/release-drafter.yml`.
+
+Before the first publish, make sure the npm organization or user scope `hagicode` exists on npm and grant publish access for `@hagicode/hagiscript`. For GitHub Actions releases, configure npm trusted publishing with package `@hagicode/hagiscript`, owner `HagiCode-org`, repository `hagiscript`, and workflow filename `npm-publish.yml`. Do not enter the full workflow path as the filename; leave the npm environment field empty unless the workflow job explicitly declares an environment. If the scope is missing or the workflow identity cannot create packages under it, npm returns `E404 Not Found` during the final `PUT https://registry.npmjs.org/@hagicode%2fhagiscript` publish request.
+
+Run the publish prerequisite check before retrying a failed release:
 
 ```bash
-npm run integration:runtime-management
-npm run integration:installed-runtime
+npm run publish:check-prereqs
 ```
 
+For local manual releases, run plain `npm publish` after logging in with an npm account that can publish under `@hagicode`.
+
 ## License
 
 MIT. See [LICENSE](./LICENSE).

package/README_cn.md

@@ -0,0 +1,321 @@
+# Hagiscript
+
+`@hagicode/hagiscript` 是 Hagiscript 语言工具链的作用域 npm 包基础工程。本次初始化只提供最小运行能力：版本元数据、基础运行时信息 API，以及一个可构建、可测试、可打包、可发布的 CLI 占位入口。
+
+## 安装假设
+
+- 需要 Node.js 20 或更高版本。
+- 该独立仓库使用 npm 作为包管理器。
+- npm 包名为 `@hagicode/hagiscript`。
+- GitHub Actions 发布使用 `npm publish --provenance`。本地手动发布时，应直接使用普通 `npm publish`，除非当前环境本身就是受支持的 trusted publishing 环境。
+
+## 使用方式
+
+先从 npm 安装该包：
+
+```bash
+npm install @hagicode/hagiscript
+```
+
+安装后的 CLI 命令仍然是 `hagiscript`。
+
+开发时运行 CLI：
+
+```bash
+npm run dev -- --help
+npm run dev -- info
+npm run dev -- install-node --target .tmp/node-runtime
+npm run dev -- check-node --target .tmp/node-runtime
+npm run dev -- npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+构建后运行编译产物：
+
+```bash
+npm run build
+node dist/cli.js --version
+node dist/cli.js info
+node dist/cli.js install-node --target .tmp/node-runtime
+node dist/cli.js check-node --target .tmp/node-runtime
+node dist/cli.js npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+### 托管 Node.js 运行时命令
+
+`install-node` 会从 `https://nodejs.org/dist` 下载官方 Node.js 归档包，解压到目标目录，并在成功前验证 `node` 与 `npm` 都可执行。
+
+```bash
+hagiscript install-node --target /opt/hagiscript/node
+hagiscript install-node --target /opt/hagiscript/node20 --version 20
+hagiscript install-node --target /opt/hagiscript/lts --version lts
+```
+
+省略 `--version` 时，Hagiscript 默认安装最新可用的 Node.js 22 版本。支持的选择器包括 `lts`、`latest`、`current`、类似 `22` 的主版本号、类似 `22.12.0` 的精确版本，以及类似 `v22.12.0` 的带 `v` 精确版本。
+
+目标路径必须不存在或为空目录。Hagiscript 会拒绝安装到非空目标目录，也不会删除已有用户文件。安装期间，临时 staging 文件会创建在目标目录旁边，并在成功或失败后清理。
+
+成功输出示例：
+
+```text
+Installing Node.js 22 into /opt/hagiscript/node
+Download progress: 100%
+Node.js runtime installed successfully.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+`check-node` 会验证已有运行时目录；只有 `node --version` 和 `npm --version` 都成功时才以退出码 `0` 结束。
+
+```bash
+hagiscript check-node --target /opt/hagiscript/node
+```
+
+有效运行时输出示例：
+
+```text
+Node.js runtime is valid.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+无效运行时会以非零退出码结束，并输出失败原因：
+
+```text
+Node.js runtime is invalid.
+Target: /opt/hagiscript/node
+Reason: missing executable
+```
+
+### npm 全局包同步
+
+`npm-sync` 会根据 JSON manifest，把 HagiScript 托管 Node.js 运行时中的 npm 全局包版本同步到约束范围内。默认情况下，它会验证或安装 `~/.hagiscript/node-runtime`，并使用该运行时内的 `npm`；它不会使用或修改当前 shell `PATH` 中的 npm。已有自动化仍可继续传入 `--runtime` 使用显式运行时目录。
+
+```bash
+hagiscript npm-sync --manifest ./manifest.json
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/ --mirror-only
+```
+
+兼容模式 manifest 结构：
+
+```json
+{
+  "packages": {
+    "<npm-package-name>": {
+      "version": "<semver range>",
+      "target": "<optional npm install selector>"
+    }
+  }
+}
+```
+
+必填的 `version` 字段使用 package.json 风格的 semver 范围，例如 `^1.2.0`、`>=1.0.0 <2.0.0` 或 `1.0.0 || 2.0.0`。可选的 `target` 字段用于指定实际执行 `npm install -g` 时使用的选择器；如果省略，Hagiscript 会安装 `<package>@<version>`。
+
+可选的顶层 `registryMirror` 字段用于指定 npm 检测与安装命令所使用的镜像地址，必须是非空的绝对 `http:` 或 `https:` URL。配置后，Hagiscript 会先对 `npm list -g --depth=0 --json` 和 `npm install -g <package>@<selector>` 追加 `--registry <registryMirror>` 并优先走镜像；如果镜像对应的 npm 命令失败，则会把同一条 inventory 或 install 命令自动重试一次到官方源 `https://registry.npmjs.org/`。这个自动降级只作用于 npm inventory 与包变更命令，不会重试运行时校验、manifest 校验或同步计划计算。
+
+产品托管的工具同步可使用扩展后的 `tools` manifest。必选工具始终会按 `src/runtime/tool-sync-catalog.config.json` 中的内部固定版本纳入同步：OpenSpec skills（`skills@1.5.1`）、OmniRoute（`omniroute@3.6.9`）和 code-server（`code-server@4.117.0`）。可选 agent CLI 同步需要显式启用；如果传入内置 CLI 或自定义 npm 包选择，它们会被加入同步。
+
+```json
+{
+  "tools": {
+    "optionalAgentCliSyncEnabled": true,
+    "selectedOptionalAgentCliIds": ["codex", "claude-code", "fission-openspec", "opencode"],
+    "customAgentClis": [
+      {
+        "packageName": "@scope/agent-cli",
+        "version": "^1.0.0"
+      }
+    ]
+  }
+}
+```
+
+首批内置可选 agent CLI ID 为 `codex`（`@openai/codex@0.125.0`）、`claude-code`（`@anthropic-ai/claude-code@2.1.119`）、`fission-openspec`（`@fission-ai/openspec@1.3.1`）、`qoder`（`@qoder-ai/qodercli@0.1.48`）和 `opencode`（`opencode-ai@1.14.24`）。这些内置包版本固定在 `src/runtime/tool-sync-catalog.config.json` 中。HagiScript 会在执行 `npm list` 或 `npm install` 前校验未知工具 ID、npm 包名和版本选择器。
+
+使用 `--registry-mirror <url>` 可以在单次运行中覆盖 manifest 中的镜像地址，优先级依次为 CLI 覆盖、manifest 的 `registryMirror`、以及 npm 默认注册表行为。如果 CLI 与 manifest 都没有提供镜像，Hagiscript 就不会附加 `--registry`，现有的 npm 默认设置、`.npmrc` 或环境变量行为会保持不变。
+
+如果某次同步必须严格停留在镜像源且不能自动切回官方源，请添加 `--mirror-only`。省略该选项时，只要配置了镜像，Hagiscript 默认就会在镜像失败后自动回退到 `https://registry.npmjs.org/` 一次。
+
+简单的产品托管请求也可以直接通过 CLI 选项传入可选 CLI，而不必先写 manifest：
+
+```bash
+hagiscript npm-sync --selected-agent-cli codex
+hagiscript npm-sync --selected-agent-cli codex --custom-agent-cli @scope/agent-cli@^1.0.0
+```
+
+openspec 和 skills 工具同步示例：
+
+```json
+{
+  "packages": {
+    "@openspec/cli": {
+      "version": "^1.0.0"
+    },
+    "@hagicode/skills": {
+      "version": ">=0.5.0 <1.0.0",
+      "target": "0.5.4"
+    }
+  }
+}
+```
+
+执行时，Hagiscript 会先验证 manifest 和运行时，再执行任何 npm install 操作；它会用 `/opt/hagiscript/node/bin/npm list -g --depth=0 --json` 检测全局包，生成 no-op、install、upgrade、downgrade 或 sync 计划，然后只对需要变更的包执行 `npm install -g <package>@<selector>`。
+
+输出示例：
+
+```text
+Manifest validated: ./manifest.json (2 packages, mode=packages)
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Runtime validated: /opt/hagiscript/node
+node: /opt/hagiscript/node/bin/node (v22.12.0)
+npm: /opt/hagiscript/node/bin/npm (10.9.0)
+Detected global packages: 4
+Plan: @openspec/cli noop installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
+Skip: @openspec/cli already satisfies range
+Plan: @hagicode/skills upgrade installed=0.4.0 required=>=0.5.0 <1.0.0 selector=@hagicode/skills@0.5.4
+Install: @hagicode/skills using @hagicode/skills@0.5.4
+Synced: @hagicode/skills (upgrade)
+npm-sync complete.
+Runtime: /opt/hagiscript/node
+Manifest: ./manifest.json
+Mode: packages
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Fallback used: no
+Packages: 2
+No-op: 1
+Changed: 1
+```
+
+如果触发了回退，Hagiscript 会在执行期间输出 `Fallback used: ...`，并在最终摘要中记录 `Fallback detail: ...`，这样 CI 或桌面端自动化就能明确知道哪个镜像失败了、是否切到了官方源，以及官方源重试是否成功。
+
+### Runtime 包管理
+
+`hagiscript runtime` 提供了面向 `hagicode-runtime` 的 manifest 驱动包管理能力。默认情况下，它会加载安装包内置的 `runtime/manifest.yaml`，把托管运行时根目录解析为 `~/.hagicode/runtime`，然后在该根目录下拆分出只读程序目录和可写运行时数据目录；如果某次部署或自动化需要独立路径，可通过 `--runtime-root <path>` 覆盖基础位置。
+
+```bash
+hagiscript runtime install
+hagiscript runtime install --components node,npm-packages --dry-run
+hagiscript runtime update --runtime-root /opt/hagicode/runtime --check-only
+hagiscript runtime remove --components code-server --purge
+hagiscript runtime state --json
+```
+
+默认运行时布局如下：
+
+```text
+<runtime-root>/
+  program/
+    bin/
+    npm/
+    components/
+  runtime-data/
+    config/
+    logs/
+    data/
+    components/
+    state.json
+```
+
+`hagiscript runtime state --json` 是安装、更新、删除与下游诊断的标准状态接口。它会输出解析后的运行时程序目录、运行时数据根目录、组件级 `HAGICODE_RUNTIME_DATA_HOME`，以及派生出的 `PM2_HOME`，下游工具不需要再自己探测文件系统。
+
+运行时脚本和 PM2 托管服务会共享同一套公开环境变量约定：
+
+- `HAGICODE_RUNTIME_HOME`：运行时程序目录
+- `HAGICODE_RUNTIME_DATA_HOME`：当前组件的可写运行时数据目录
+- `PM2_HOME`：默认位于 `HAGICODE_RUNTIME_DATA_HOME` 下的独立子目录
+- `PATH`：优先注入托管 Node 运行时、托管 npm 前缀和托管 wrapper，再继承当前 shell 的 PATH
+
+### PM2 托管服务命令
+
+`hagiscript pm2` 用于管理运行时作用域内的 `omniroute` 和 `code-server` 服务，底层始终调用 `hagiscript runtime install` 安装到托管 npm 前缀中的 PM2。
+
+```bash
+hagiscript pm2 omniroute start
+hagiscript pm2 omniroute status
+hagiscript pm2 code-server stop
+```
+
+每次 PM2 命令都会先解析运行时 manifest，计算规范化的运行时目录和组件数据目录，再以组件级 `PM2_HOME` 和托管 Node-first PATH 调用 `<runtime-home>/npm` 下的 PM2；它不会依赖系统预装的 PM2 或系统 Node。
+
+`runtime/manifest.yaml` 现在支持以下覆盖项：
+
+- 运行时级别：`paths.runtimeHome`、`paths.runtimeDataRoot`、`paths.componentDataRoot`、`paths.defaultPm2Home`
+- 组件级别：`runtimeDataDir`
+- 服务级别：`pm2.appName`、`pm2.cwd`、`pm2.script`、`pm2.args`、`pm2.env`、`pm2.pm2Home`
+
+在 ESM 项目中使用库 API：
+
+```ts
+import { createRuntimeInfo, getPackageMetadata } from "@hagicode/hagiscript";
+
+console.log(getPackageMetadata());
+console.log(createRuntimeInfo());
+```
+
+## 开发命令
+
+所有命令都应在 `repos/hagiscript/` 下执行：
+
+```bash
+npm install
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run pack:check
+```
+
+其他常用命令：
+
+```bash
+npm run clean
+npm run format
+npm run test:watch
+npm run publish:prepare-dev-version
+npm run publish:verify-release -- v0.1.0
+```
+
+## 构建输出
+
+`npm run build` 会使用严格的 NodeNext TypeScript 配置编译到 `dist/`。预期入口文件包括：
+
+- `dist/index.js`
+- `dist/index.d.ts`
+- `dist/index.js.map`
+- `dist/cli.js`
+- `dist/cli.d.ts`
+- `dist/cli.js.map`
+
+`package.json` 的 `exports` 字段指向 `dist/index.js` 和 `dist/index.d.ts`。发布到 npm 后的包名是 `@hagicode/hagiscript`，`bin.hagiscript` 指向 `dist/cli.js`。
+
+## 包内容校验
+
+`npm run pack:check` 会执行 dry-run 打包检查。如果缺少必要运行文件，或错误包含源码测试、脚本、覆盖率、临时目录等只应存在于开发环境的文件，脚本会失败。
+
+## 发布自动化
+
+GitHub Actions 提供三类自动化流程：
+
+- `ci.yml` 使用 `npm ci` 安装依赖，并执行测试、构建和包内容校验。
+- `npm-publish.yml` 在 `main` 分支解析唯一预发布版本，用 `npm version --no-git-tag-version` 同步 `package.json` 和 `package-lock.json`，再发布到 `dev` dist-tag。
+- `npm-publish.yml` 也会在非草稿、非 prerelease 的 GitHub Release 发布时，校验 `vX.Y.Z` 标签格式，拒绝早于仓库基础版本的标签，并用同样方式写入稳定版本再发布到 `latest` dist-tag。
+- `release-drafter.yml` 通过 `.github/release-drafter.yml` 维护分类清晰的发布草稿。
+
+首次发布前，需要先确保 npm 上已经存在组织或用户 scope `hagicode`，并且 `@hagicode/hagiscript` 已授权当前发布主体。GitHub Actions 发布时，需要在 npm trusted publishing 中配置：package `@hagicode/hagiscript`、owner `HagiCode-org`、repository `hagiscript`、workflow filename `npm-publish.yml`。不要把 workflow filename 填成完整路径；如果 npm 表单有 environment 字段，除非 workflow job 显式声明了 environment，否则保持为空。如果 scope 不存在，或 workflow 身份无权在该 scope 下创建包，npm 会在最后的 `PUT https://registry.npmjs.org/@hagicode%2fhagiscript` 发布请求中返回 `E404 Not Found`。
+
+重试失败的发布前，先运行发布前置检查：
+
+```bash
+npm run publish:check-prereqs
+```
+
+本地手动发布时，先登录一个有权发布到 `@hagicode` scope 的 npm 账号，再直接执行普通 `npm publish`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagiscript",
-  "version": "0.1.6-dev.47.1.59c65fa",
+  "version": "0.1.7",
   "description": "Scoped npm package foundation for Hagiscript language tooling.",
   "license": "MIT",
   "homepage": "https://github.com/HagiCode-org/hagiscript#readme",
@@ -27,7 +27,8 @@
     "dist",
     "bin",
     "runtime",
-    "README.md"
+    "README.md",
+    "README_cn.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",