@qilin-agent/cli 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write apps/cli/README.md
+/qilin-agent-cli:
+  en: 063f13813a8fa190
+  zh: 682d157e19163ff0
+/qilin-agent-cli/entry-modes:
+  en: cebfeaa9a9e60c00
+  zh: 652208729fa392df
+/qilin-agent-cli/app-arguments:
+  en: 979c1c9bedaf1b3e
+  zh: a77b6d9db2cfc191
+/qilin-agent-cli/profiles:
+  en: 7d717e3a016726f8
+  zh: 9ffeeb5933153c80
+/qilin-agent-cli/optional-overlays:
+  en: 55972a91e0d1d24d
+  zh: 920ae26285d8e1b6
+/qilin-agent-cli/development:
+  en: fa8d7705c54df6f5
+  zh: 8fe3f713cfe31dbf

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# `@qilin-agent/cli`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh.md)
+
+The `qilin` command is the sole supported Node application launcher: profiles are ordered stacks of plugin-bundle patch layers under the user's own overrides. SDK and ACP are profiles, not separate public bins. The Python runtime wheel packages this same command; the SDK defaults to `sdk`, and the minimal example selects `sdk-minimal`. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, and fatal configuration or boot failures exit nonzero.
+
+## Entry modes
+
+| Command | Purpose |
+|---|---|
+| `qilin <name>` / `qilin --profile <name>` | Boot the named profile under `$QILIN_HOME/profiles/<name>`. |
+| `qilin --profile <name> --from-default-profile <template>` | Create a new custom profile from a shipped template, then boot it. |
+| `qilin --profile acp` | Serve automation clients over ACP stdio until disconnect. |
+| `qilin --profile headless "job"` | Run one fresh persisted session, print the final answer, and exit. |
+| `qilin --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
+| `qilin --profile sdk-minimal` | Serve SDK clients with the standalone minimal agent tree. |
+| `qilin`, `qilin web` | Serve the deployment at one address: one isolated Web runtime per account, each serving the application's own landing page and sign-in form. The profile you already start is the deployment. |
+| `qilin tenants accounts` | List this Harness home's accounts and the tenant directory each owns. |
+| `qilin tenants add <username>` | Create an account, prompting for its password or reading `--password-stdin`. |
+| `qilin tenants passwd <username>` | Replace an account's password and retire the sessions it issued. |
+| `qilin tenants remove <username>` | Retire an account, keeping its tenant directory unless `--purge-data` is given. |
+| `qilin plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
+| `qilin plugin list` | List a profile's bundle layers in activation order; omit `--profile` for the product profile. |
+| `qilin plugin doctor <package\|directory>` | Report one plugin package's DSH-era compatibility without installing or running anything. |
+
+The browser-serving profiles — the product surface `qilin` and `qilin web` — are the deployment: one command, one address, with no second entry. The entry draws no interface of its own: it starts one Web runtime per account on demand under `$QILIN_HOME/tenants/<account id>/`, and forwards every request the browser makes — the application document, the `/api` channel, the mux upgrade, and ranged media reads — to the runtime its routing cookie names, with the runtime's own authority in place of the entry's so its session cookie stays bound to the runtime that minted it. A runtime's harness home is its own: sessions, tasks, workspaces, attachments, plugins, model settings, credentials, skills, and presets resolve there, and only the roster at `$QILIN_HOME/auth/accounts.json` is shared. Credentials are verified by the named account's own runtime: the entry forwards the sign-in submission there and relays the session cookie it issues, and the runtime admits only its own account, so a forged routing cookie reaches a runtime that does not recognize the caller. `--idle-ms` reclaims a runtime that has served no traffic for that long, and `0` disables reclamation; `--max-tenants` bounds how many runtimes live at once, reclaiming the least recently used one past that bound; `--restart-backoff-ms` sets the first wait before a runtime that failed to start is retried, doubling per consecutive failure. `--patch` composes every runtime with an extra overlay layer; `--tls-cert` and `--tls-key` serve the entry's address over HTTPS and terminate TLS in front of the loopback runtimes, so the pair is supplied together and is refused with `--per-account-ports`. The entry reads only the flags it owns: every other argument reaches each runtime's own command line, and `--host` refuses a wildcard address. One browser drives one account at a time. The application inside a runtime owns the landing page, the sign-in form, and registration. With accounts in the roster the bare address redirects to the first account's path, `/t/<account>/`, and every other account is reachable at its own. With no accounts yet, every path goes to a first-run runtime, whose layer admits whoever the roster holds, so the product's own form creates the first account and the deployment never describes what to type. `--registration open|closed` decides whether the product's form may create accounts: the default is `open` on a loopback address and `closed` on every other, so an address other machines reach creates an account only where the operator says so, with `qilin tenants add`; a name the roster does not hold, a routing cookie naming an account it no longer holds, and every other request that names no account are answered by that same runtime, so the deployment never speaks for the application. `/healthz` and `/status` stay the entry's own reads.
+
+The roster subcommands maintain the accounts that shared file holds. A tenant runtime admits exactly the account it serves and closes registration, so its own Web surface cannot create a second account; the first-run runtime carries the deployment's policy instead, which is where a deployment that accepts accounts grows through the product's own form. `add` creates an account without a browser, `passwd` re-keys one and retires its issued sessions, and `remove` retires one while keeping its Sessions on disk unless `--purge-data` is given. A runtime started for a removed account fails loud, because its overlay admits an account the file no longer holds.
+
+The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates. Create another profile at an unused, non-shipped name with `--from-default-profile`, or initialize a base-backed profile through `qilin plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it. After a successful package operation the command reconciles the profile's bundle list, and it refuses a profile whose installed dependencies include an upstream DSH-era engine package: the diagnostic names each colliding package, the QiLin package it maps onto, and the `remove` command that clears it, and the command exits 1 without changing the bundle list.
+
+`list` and `doctor` read the profile and never initialize it or run pnpm. `doctor` accepts an installed package name or a package directory and checks the four rules a plugin must satisfy to load here: whether the package builds the DSH-era home itself instead of reading `DSH_HOME`/`QILIN_HOME`, installs an engine package the harness supplies, imports an engine name it never declared as a peer, and injects client module names the compatibility layer cannot map. It prints one finding per line and exits 1 only when a finding blocks activation.
+
+`list` marks a shipped template layer with `(shipped)`: it moves with the running installation and cannot be dropped from the profile. Every other listed layer belongs to the profile — for example the retired `dsh-animations` animations skill pack installed back through `qilin plugin add` — and upgrades or removes in place without a QiLin release.
+
+Install the command itself from the published package (`npm install -g @qilin-agent/cli`) to get `qilin` on `PATH`; the manifest declares `lib/bin.js` as the `qilin` bin and ships only that bundle.
+
+## App arguments
+
+The launcher parses only its own flags and hands everything after them to the booted profile, where any injected app plugin may parse the shared immutable snapshot ([`qilin-cmdline`](../../packages/boot/cmdline/README.md)). The first token the launcher does not recognize starts the app's arguments:
+
+```sh
+qilin --profile web --port 8080       # --port is the deployment's address
+qilin --profile tui --resume <id>     # example, assuming the tui profile is installed; --resume belongs to the terminal app
+qilin --profile headless "run the tests"
+qilin --profile web --patch ./extra.cordis.yml   # the overlay every account's runtime composes with
+qilin --profile web --help            # the deployment's flags, then the app's
+qilin --help                          # the launcher's own help
+```
+
+<a id="profiles"></a>
+## Profiles
+
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `qilin.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer). `qilin-hmr`, when enabled in YAML, watches the profile manifest and both profile and home patch files, then recomposes all layers through one serialized reload. Without HMR, changes apply on restart. Edits arriving during watcher registration use the same nonfatal reload reporting as later edits. [Plugin Manager](../../packages/boot/plugin-manager/README.md) shares package operations and the profile write lock with `qilin plugin`; package updates retain disabled bundle selections. CLI package commands inherit authentication variables and terminal descriptors, including interactive build approval; service calls retain their scrubbed environment and captured diagnostics.
+
+Installation and profile startup enforce declared qilin peer ranges against the same runtime version `qilin --version` prints. Incompatible plugins require an explicitly acknowledged exact-version exemption, which `qilin plugin allow-version`, `revoke-version`, and `version-exemptions` manage for one profile. The [plugin manager's compatibility reference](../../packages/boot/plugin-manager/README.md#version-compatibility-and-exemptions) documents the commands, persistence, and risks.
+
+The tree composes over an empty root:
+- each bundle's patch in `qilin.profile.bundles` order
+- then the profile's `cordis.patch.yml`, then the home-level `$QILIN_HOME/cordis.patch.yml`
+- then `--patch` overlays
+
+Bundles named in `qilin.profile.bundles` resolve from the qilin installation first (`@qilin-agent/base`, `@qilin-agent/web-app`, `@qilin-agent/headless`, `@qilin-agent/sdk-app`, `@qilin-agent/sdk-minimal`, `@qilin-agent/acp-app`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins.
+
+Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
+
+The [CLI behavior reference](reference/README.md) owns exact layer precedence, flags, shutdown behavior, deployment defaults, and source execution. The [startup and reload failure table](../../packages/boot/app-boot/README.md#startup-and-reload-failures) compares optional and required plugin failures with configuration HMR.
+
+## Optional overlays
+
+`config/examples/` ships opt-in overlays for GitHub review webhooks, session-local Schedule, memory MCP servers, and runtime Kylin tools. They are never part of a default profile; the [user guides](../../docs/user/guide/index.md) and [developer practice guides](../../docs/user/develop/practice/index.md) own setup and safety instructions.
+
+## Development
+
+Production runs require built package and frontend artifacts. From the repository root, run `pnpm run build` separately, then use `pnpm qilin <args...>` to run the TypeScript entry and forward every argument; the [source-execution reference](reference/README.md#source-execution) owns the module-resolution contract.
+
+The `@qilin-agent/cli/profile-boot` export provides the shared profile lifecycle to the Desktop host. A resolved application profile supplies its own installation anchor for runtime package resolution while retaining the Harness home patch, proxy environment, telemetry switch, patch reload, and bounded shutdown.
+
+The [Web failure matrix](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts) runs the built CLI through startup failures and native configuration HMR with `awaitWriteFinish` enabled in `test:expected`. It verifies authenticated HTTP responses, diagnostics, recovery, process exits, and disposal without model API calls; the [startup acceptance](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts) also covers the shipped required Web dependencies and port conflicts.

package/README.zh.md

@@ -0,0 +1,79 @@
+# `@qilin-agent/cli`
+
+[English](README.md) | 中文
+
+`qilin` 是唯一受支持的 Node 应用启动器；profile 由多个插件组合包 patch 层按顺序叠加而成，其上再应用用户自己的覆盖配置。SDK 与 ACP（Agent Client Protocol）都是 profile，而不是独立的公开可执行命令。Python 运行时 wheel 包中也包含同一个命令；SDK 默认使用 `sdk`，极简示例选择 `sdk-minimal`。[`src/args.ts`](src/args.ts) 负责命令语法，[`src/bin.ts`](src/bin.ts) 只加载选中的运行器。无效命令、来自其他模式的选项，以及致命的配置或启动错误都会以非零状态退出。
+
+## 入口模式
+
+| 命令 | 用途 |
+|---|---|
+| `qilin <name>` / `qilin --profile <name>` | 启动位于 `$QILIN_HOME/profiles/<name>` 的指定 profile。 |
+| `qilin --profile <name> --from-default-profile <template>` | 从随附模板创建新的自定义 profile，然后启动它。 |
+| `qilin --profile acp` | 通过 ACP stdio 为自动化客户端提供服务，直至断开连接。 |
+| `qilin --profile headless "job"` | 运行一个全新的持久化会话，打印最终答案并退出。 |
+| `qilin --profile sdk` | 通过 JSON-RPC stdio 为 SDK 客户端提供服务，直至关闭或断开连接。 |
+| `qilin --profile sdk-minimal` | 以独立极简 agent（智能体）配置树为 SDK 客户端提供服务。 |
+| `qilin`、`qilin web` | 在一个地址上服务整套部署：每个账户一个隔离的 Web 运行时，各自服务应用自己的落地页与登录表单。你原本就在启动的那个 profile 就是整套部署。 |
+| `qilin tenants accounts` | 列出本 harness home 的账户，以及每个账户拥有的租户目录。 |
+| `qilin tenants add <用户名>` | 创建一个账户，交互式输入密码，或读取 `--password-stdin`。 |
+| `qilin tenants passwd <用户名>` | 替换某个账户的密码，并使其已签发的会话失效。 |
+| `qilin tenants remove <用户名>` | 注销某个账户，默认保留其租户目录，除非给出 `--purge-data`。 |
+| `qilin plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
+| `qilin plugin list` | 按激活顺序列出某个 profile 的 bundle 层；省略 `--profile` 时使用产品 profile。 |
+| `qilin plugin doctor <包名\|目录>` | 报告某个插件包的 DSH 时代兼容性，不安装也不运行任何东西。 |
+
+会服务浏览器的 profile——产品面 `qilin` 与 `qilin web`——就是整套部署：一条命令，一个地址，没有第二个入口。入口自己不作画：它按需在 `$QILIN_HOME/tenants/<账户 id>/` 下为每个账户启动一个 Web 运行时，并把浏览器发出的每个请求——应用文档、`/api` 通道、mux 升级与带 Range 的媒体读取——转发到它的路由 cookie 所命中的那个运行时，同时把运行时自己的 authority 顶替掉入口的，从而让它的会话 cookie 始终绑定在签发它的那个运行时上。运行时的 harness home 归它自己：会话、任务、工作区、附件、插件、模型设置、凭据、技能与预设都在其中解析，只有 `$QILIN_HOME/auth/accounts.json` 这份名册是共享的。凭据由被指名账户自己的运行时校验：入口把登录提交转发到那里，并中继它签发的会话 cookie；运行时只接纳自己的账户，因此伪造的路由 cookie 只会到达一个不认可调用者的运行时。`--idle-ms` 会回收在该时长内没有服务过任何流量的运行时，`0` 表示不回收；`--max-tenants` 限定同时存活多少个运行时，超出上限时回收最久未使用的那个；`--restart-backoff-ms` 设定启动失败的运行时第一次重试前的等待，每次连续失败翻倍。`--patch` 让每个运行时都多叠一层 overlay；`--tls-cert` 与 `--tls-key` 让入口地址以 HTTPS 服务，并在 loopback 运行时之前终止 TLS，因此两者必须成对给出，且与 `--per-account-ports` 互斥。入口只读自己拥有的 flag：其余参数一律交给每个运行时自己的命令行，而 `--host` 拒绝通配地址。同一个浏览器一次只服务一个账户。落地页、登录表单与注册都归运行时内部的应用所有。名册里有账户时，裸地址会重定向到第一个账户的路径 `/t/<账户>/`，其余账户各自在自己的路径上可达。名册为空时，每个路径都交给首启运行时，它那一层的接纳判据就是名册里有什么就接纳什么，于是由产品自己的表单创建第一个账户，入口从不说明该输入什么。`--registration open|closed` 决定产品自己的表单能否创建账户：loopback 地址上默认为 `open`，其他地址上默认为 `closed`，因此别的机器能到达的地址只在运维明说时才创建账户（用 `qilin tenants add`）；名册里没有的名字、指向一个名册已不再持有的账户的路由 cookie，以及其余任何没有指名账户的请求，都由同一个运行时回答，因此入口从不替应用说话。`/healthz` 与 `/status` 仍归入口自己读取。
+
+roster 子命令维护该共享文件中的账户。租户运行时只接纳自己服务的那个账户且关闭注册，因此它自己的 Web 界面无法创建第二个账户；首启运行时承载的则是部署自己的策略，接受新账户的部署由此通过产品自己的表单扩充账户。`add` 无需浏览器即可创建账户，`passwd` 为一个账户重新设置密码并使其已签发的会话失效，`remove` 注销一个账户，默认把它的 Session 留在磁盘上，除非给出 `--purge-data`。为已注销账户启动的运行时会明确失败，因为它的覆盖层接纳的是一个文件里已不存在的账户。
+
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化。使用 `--from-default-profile` 可以基于这些模板之一，在尚未使用的非内置名称处创建其他 profile；通过 `qilin plugin` 则可以初始化一个以 base 为基础的 profile。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI（命令行界面）会拒绝针对它的启动、配置 dump 和插件管理请求。包操作成功后命令会协调 profile 的 bundle 列表；若 profile 的已安装依赖中出现上游 DSH 时代的引擎包，命令会拒绝：诊断会指明每个冲突包、它映射到的 QiLin 包，以及清除它的 `remove` 命令，命令以退出码 1 结束且不改变 bundle 列表。
+
+`list` 与 `doctor` 只读取 profile，既不初始化它也不运行 pnpm。`doctor` 接受已安装的包名或包目录，检查插件要在此加载必须满足的四条规则：包是否自己拼出 DSH 时代的主目录而不是读取 `DSH_HOME`/`QILIN_HOME`、是否安装了 harness 已提供的引擎包、是否导入了未声明为 peer 的引擎名、以及是否注入了兼容层无法映射的客户端模块名。它每行输出一条发现，仅当某条发现会阻断激活时才以退出码 1 结束。
+
+`list` 把随附模板层标为 `(shipped)`：它随运行中的安装实例走，无法从 profile 移除。列表里其余每层都归 profile 所有——例如通过 `qilin plugin add` 装回的已退役 `dsh-animations` 动效技能包——可原地升级或移除，无需等待 QiLin 发版。
+
+命令本身从已发布的包安装（`npm install -g @qilin-agent/cli`）即可把 `qilin` 放到 `PATH`；manifest 把 `lib/bin.js` 声明为 `qilin` bin，并且只随包发布该 bundle。
+
+## 应用参数
+
+启动器只解析自身的 flag，并将其后的所有内容交给已启动的 profile；注入该 profile 的任意应用插件都可以解析这份共享的不可变快照（[`qilin-cmdline`](../../packages/boot/cmdline/README.zh.md)）。启动器无法识别的第一个 token 标志着应用参数的开始：
+
+```sh
+qilin --profile web --port 8080       # --port is the deployment's address
+qilin --profile tui --resume <id>     # example, assuming the tui profile is installed; --resume belongs to the terminal app
+qilin --profile headless "run the tests"
+qilin --profile web --patch ./extra.cordis.yml   # the overlay every account's runtime composes with
+qilin --profile web --help            # the deployment's flags, then the app's
+qilin --help                          # the launcher's own help
+```
+
+<a id="profiles"></a>
+## Profile
+
+profile 目录包含一个 `package.json`，其中记录树外插件依赖，以及 profile manifest（元数据清单）`qilin.profile`、其中按顺序排列的 `bundles` 列表；还包含一个 `cordis.patch.yml`，其中保存用户自己的 patch 层。在 YAML 中启用的 `qilin-hmr` 监视 profile manifest、profile 与 home 级 patch 文件，再通过统一串行重载重新组合所有层。未启用 HMR 时，更改在重启后生效。监听器注册期间发生的编辑与后续编辑使用相同的非致命重载错误报告。[插件管理器](../../packages/boot/plugin-manager/README.zh.md) 与 `qilin plugin` 共享包操作和 profile 写锁；更新依赖会保留已停用的组合包选择。CLI 包操作继承认证环境和终端描述符，支持交互式构建批准；service 调用保留清理后的环境并捕获诊断。
+
+安装与 profile 启动会用 `qilin --version` 打印的同一个运行时版本校验已声明的 qilin peer 范围。不兼容的插件必须显式确认精确版本豁免，`qilin plugin allow-version`、`revoke-version` 与 `version-exemptions` 按 profile 管理这些豁免。[插件管理器兼容性参考](../../packages/boot/plugin-manager/README.zh.md#version-compatibility-and-exemptions)记录了命令、持久化方式与风险。
+
+配置树以空根为起点，依次叠加以下配置层：
+- `qilin.profile.bundles` 中各组合包的 patch
+- profile 自身的 `cordis.patch.yml`，然后是 home 级的 `$QILIN_HOME/cordis.patch.yml`
+- `--patch` 指定的覆盖层
+
+`qilin.profile.bundles` 中列出的组合包先从 qilin 安装目录解析（`@qilin-agent/base`、`@qilin-agent/web-app`、`@qilin-agent/headless`、`@qilin-agent/sdk-app`、`@qilin-agent/sdk-minimal`、`@qilin-agent/acp-app`），再从 profile 自身的 `node_modules` 解析；pnpm 会将树外插件安装到该目录。
+
+使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。
+
+层的确切优先级、flag、关闭行为、部署默认值和源码执行方式，以 [CLI 行为参考](reference/README.zh.md)为准。[启动与重载失败表](../../packages/boot/app-boot/README.zh.md#startup-and-reload-failures)对比 optional、required 插件启动失败与配置 HMR 的行为。
+
+## 可选覆盖层
+
+`config/examples/` 交付 GitHub 评审 webhook、会话内 Schedule、记忆 MCP 服务器与运行时 Kylin 工具的可选覆盖层。它们绝不属于默认 profile；设置与安全说明由[用户指南](../../docs/user/guide/index.zh.md)和[开发实战指南](../../docs/user/develop/practice/index.zh.md)负责。
+
+## 开发
+
+生产运行需要已构建的包与前端产物。请在仓库根目录单独运行 `pnpm run build`，然后使用 `pnpm qilin <args...>` 运行 TypeScript 入口并转发所有参数；模块解析约定以[源码执行参考](reference/README.zh.md#source-execution)为准。
+
+`@qilin-agent/cli/profile-boot` 导出向 Desktop Host 提供共享 profile 生命周期。已解析的应用 profile 为运行时包解析指定自己的安装锚点，同时沿用 Harness home patch、代理环境、遥测开关、patch 热重载和有界关闭。
+
+[Web 失败矩阵](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts)在 `test:expected` 中通过构建后的 CLI 验证启动失败与启用 `awaitWriteFinish` 的原生配置 HMR。它不调用模型 API，而是检查经过认证的 HTTP 响应、诊断、恢复、进程退出与 dispose；[启动验收测试](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts)还覆盖随附 Web 的必需依赖与端口冲突。

package/lib/bin.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+import { StartupError, getQilinRuntimeVersion, loadLayeredEnv } from "@qilin-agent/app-boot";
+import { resolveQilinHome } from "@qilin-agent/home-paths";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { inspect } from "node:util";
+//#region lib/types/args.js
+/**
+* Commander adapter for the `qilin` command line.
+*
+* The launcher parses only what it owns — which profile to boot, which extra
+* patch overlays to apply, and the config dumps — and hands **everything after
+* its own flags** to the booted tree verbatim, where injected app plugins parse
+* their own flag families and print their own `--help` (see
+* `@qilin-agent/cmdline`). Launcher flags therefore come first: the first
+* token this parser does not recognize starts the inner arguments, so
+* `qilin --profile tui --resume abc` boots the tui profile with `--resume abc`,
+* and `qilin --profile web -h` prints the web app's help, not this one's.
+*
+* `qilin <name>` abbreviates `qilin --profile <name>`; `plugin` manages a profile's
+* plugin dependencies by forwarding to pnpm.
+* @module @qilin-agent/cli/args
+*/
+/**
+* Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
+* variadic — a variadic `--patch` would swallow the inner arguments.
+*/
+const collect = (value, previous = []) => [...previous, value];
+function selectProfile(value, previous) {
+	if (previous !== void 0) throw new InvalidArgumentError("select a profile only once");
+	return value;
+}
+function rejectReservedDesktopProfile(program, profile) {
+	if (profile.toLowerCase() === "desktop") program.error("error: profile \"desktop\" belongs to the separate QiLin desktop application, not this repository");
+}
+/**
+* Profile a bare `qilin` boots: the QiLin product surface. It is the only
+* profile a user has to know, so naming it again on the command line would
+* only repeat the product's own name.
+*/
+const PRODUCT_PROFILE = "qilin";
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  qilin                                       boot the QiLin product surface, then serve it
+  qilin --no-open                             the same, without opening a browser
+  qilin web                                   boot the unbranded web surface (same as: qilin --profile web)
+  qilin rescue --from-default-profile web
+                                            create rescue from the shipped web template, then boot it
+  qilin headless "run the tests"              answer one task, print the result, and exit
+  qilin tui --patch ./extra.yml               boot a custom profile with one extra overlay
+  qilin tui --resume <session>                arguments after the launcher flags reach the app
+  qilin web --help                            the web app's own flags and help
+  qilin plugin list                           list the product profile's plugin layers
+  qilin plugin doctor <package|directory>     report one plugin's DSH-era compatibility
+  qilin plugin add <package>                  install a plugin into the product profile
+  qilin plugin --profile tui add <package>    install a plugin into the tui profile
+  qilin plugin version-exemptions             list the profile's exact-version exemptions
+  qilin plugin allow-version <pkg@ver> --qilin-version <exact> --accept-risk
+                                              allow one rejected plugin/runtime pair
+  qilin plugin revoke-version <pkg@ver> --qilin-version <exact>
+                                              withdraw one exemption
+  qilin web --port 0                          serve the deployment; each account gets its own runtime
+  qilin tenants accounts                      list this home's accounts and their tenant directories
+  qilin tenants add alice                     create an account, prompting for its password
+  echo "$PASSWORD" | qilin tenants passwd alice --password-stdin
+                                              replace a password and retire its sessions
+  qilin tenants remove alice                  retire an account, keeping its Sessions on disk
+`;
+/**
+* Resolve a boot or dump invocation from the launcher flags and the leftover
+* inner arguments.
+* @param program - the command whose options were parsed.
+* @param profile - the profile these flags boot.
+* @param options - the launcher flags commander collected.
+* @param args - the leftover arguments, in argv order.
+* @returns the resolved invocation.
+*/
+function resolveBoot(program, profile, options, args) {
+	const patches = options.patch ?? [];
+	if (patches.includes("")) program.error("error: --patch needs a path");
+	if (options.fromDefaultProfile === "") program.error("error: --from-default-profile needs a name");
+	if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) return {
+		mode: "profile",
+		profile,
+		fromDefaultProfile: options.fromDefaultProfile,
+		patches,
+		args
+	};
+	if (options.dumpConfig === true && options.dumpDefaultConfig === true) program.error("error: --dump-config and --dump-default-config are mutually exclusive");
+	if (args.length > 0) program.error(`error: config dumps take no app arguments, got ${args.map((argument) => JSON.stringify(argument)).join(" ")}`);
+	const defaultOnly = options.dumpDefaultConfig === true;
+	if (defaultOnly && patches.length > 0) program.error("error: --dump-default-config prints the bundle layers and takes no --patch");
+	return {
+		mode: "dump-config",
+		profile,
+		fromDefaultProfile: options.fromDefaultProfile,
+		defaultOnly,
+		patches
+	};
+}
+/**
+* Resolve argv into one invocation, or print and exit for help, version, or an
+* error.
+* @param argv - arguments after the Node binary and script.
+* @param version - version string printed by `--version`.
+* @returns the resolved invocation.
+*/
+function parseQilinArgs(argv, version) {
+	const first = argv[0];
+	let resolved;
+	const program = new Command();
+	program.name("qilin").version(version, "-V, --version", "output the version number").usage("[--profile] <name> [options] [app-args...]\n       qilin plugin --profile <name> <pnpm-args...>\n       qilin web [options]").description("qilin: boot the QiLin product surface, or any profile — an ordered stack of plugin-bundle patch layers under your own overrides.").addHelpText("after", HELP_EXAMPLES).exitOverride().helpOption(false).helpCommand(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the booted profile's app (see: qilin --profile <name> --help)").option("--profile <name>", "the profile under $QILIN_HOME/profiles to boot", selectProfile).option("--from-default-profile <name>", "initialize a new custom profile from a shipped profile template").option("--patch <path>", "extra patch-list overlay applied after the profile layer (repeatable)", collect).option("--dump-config", "print the composed profile tree and exit").option("--dump-default-config", "print the profile tree without its user layer or --patch overlays and exit").action((args, options) => {
+		if (options.profile === void 0 && args.some((argument) => argument === "-h" || argument === "--help")) program.help();
+		const profile = options.profile ?? PRODUCT_PROFILE;
+		if (profile === "") program.error("error: --profile needs a name");
+		rejectReservedDesktopProfile(program, profile);
+		resolved = resolveBoot(program, profile, options, args);
+	});
+	if (first === "plugin") {
+		const plugin = program.command("plugin").description("manage a profile's plugins: list them, forward pnpm arguments, or grant an exact-version compatibility exemption");
+		plugin.option("--profile <name>", "the profile whose plugins to manage (defaults to the product profile; initialized on first use)", selectProfile).allowUnknownOption().argument("[args...]", "one of: list, doctor <name|path>, version-exemptions, allow-version <package@version> --qilin-version <exact> --accept-risk, revoke-version <package@version> --qilin-version <exact>; otherwise pnpm arguments forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)").action((args, options) => {
+			const profile = options.profile ?? PRODUCT_PROFILE;
+			if (profile === "") program.error("error: --profile needs a name");
+			rejectReservedDesktopProfile(plugin, profile);
+			if (args.length === 0) program.error("error: plugin needs a subcommand (list, doctor <name|path>, version-exemptions, allow-version <package@version>, revoke-version <package@version>) or pnpm arguments to forward (e.g. add <package>)");
+			if (args[0] === "list" && args.length > 1) program.error("error: plugin list takes no further arguments");
+			if (args[0] === "doctor" && args.length !== 2) program.error("error: plugin doctor takes exactly one installed package name or package directory");
+			resolved = {
+				mode: "plugin",
+				profile,
+				args
+			};
+		});
+	}
+	if (first === "tenants") {
+		const tenants = program.command("tenants").description("maintain the accounts every runtime under this Harness home shares; qilin web serves the deployment, one isolated runtime per account");
+		tenants.action(() => {
+			program.error("error: tenants needs a subcommand (accounts, add, passwd, remove)");
+		});
+		tenants.command("accounts").description("list the accounts of this Harness home and the tenant directory each owns").action(() => {
+			resolved = {
+				mode: "tenants",
+				request: { command: "accounts" }
+			};
+		});
+		tenants.command("add").description("create one account in this Harness home").argument("<username>", "login name: 3-32 characters of a-z, 0-9, _, ., or -, starting with a letter or digit").option("--email <address>", "address stored with the account").option("--admin", "make this the deployment's administrator: the one account that reads every account's usage ledger").option("--password-stdin", "read the password from standard input instead of prompting").action((username, options) => {
+			resolved = {
+				mode: "tenants",
+				request: {
+					command: "add",
+					username,
+					email: options.email,
+					admin: options.admin === true,
+					password: options.passwordStdin === true ? { kind: "stdin" } : { kind: "prompt" }
+				}
+			};
+		});
+		tenants.command("passwd").description("replace one account's password, retiring the sessions it issued").argument("<username>", "login name of the account to re-key").option("--password-stdin", "read the password from standard input instead of prompting").action((username, options) => {
+			resolved = {
+				mode: "tenants",
+				request: {
+					command: "passwd",
+					username,
+					password: options.passwordStdin === true ? { kind: "stdin" } : { kind: "prompt" }
+				}
+			};
+		});
+		tenants.command("remove").description("retire one account from this Harness home").argument("<username>", "login name of the account to retire").option("--purge-data", "also remove the account's tenant directory, Sessions included").action((username, options) => {
+			resolved = {
+				mode: "tenants",
+				request: {
+					command: "remove",
+					username,
+					purgeData: options.purgeData === true
+				}
+			};
+		});
+	}
+	try {
+		const expanded = first !== void 0 && !first.startsWith("-") && first !== "plugin" && first !== "tenants" ? ["--profile", ...argv] : argv;
+		program.parse(expanded, { from: "user" });
+	} catch (error) {
+		return process.exit(error instanceof CommanderError ? error.exitCode : 1);
+	}
+	/* v8 ignore next -- an action resolves or Commander throws */
+	if (resolved === void 0) throw new Error("qilin: no invocation resolved");
+	return resolved;
+}
+//#endregion
+//#region lib/types/scheduler-yield.js
+/**
+* Host fallback for the Web Scheduler API global.
+* @module @qilin-agent/cli/scheduler-yield
+*/
+/**
+* Install `globalThis.scheduler.yield` unless the host already defines a
+* `scheduler`.
+*
+* The fallback resolves on the next `setImmediate` — the API's "yield to the
+* event loop once, then continue" semantic — and a host-provided `scheduler`
+* is left untouched. Call it before importing anything that may read the
+* global; `bin.ts` calls it at the top of the entry, ahead of every mode
+* module. Rationale: [the host-shim Agent
+* Note](../../../.agents/notes/implemented/architecture/2026-10-07-web-scheduler-yield-host-shim.md).
+*
+* @returns whether this call installed the fallback.
+*/
+function installSchedulerYield() {
+	if (globalThis.scheduler !== void 0) return false;
+	Object.defineProperty(globalThis, "scheduler", {
+		value: { yield: () => new Promise((resolve) => setImmediate(resolve)) },
+		writable: true,
+		configurable: true
+	});
+	return true;
+}
+//#endregion
+//#region lib/types/startup-diagnostics.js
+/** Save original startup diagnostics while keeping the terminal report concise. */
+/** Wait for stderr to finish the write before the failed process exits. */
+function writeStderr(text) {
+	return new Promise((resolve, reject) => {
+		process.stderr.write(text, (error) => {
+			if (error) reject(error);
+			else resolve();
+		});
+	});
+}
+/**
+* Print the startup summary and save a private, uniquely named report under QILIN_HOME/logs.
+* Failed writes print the complete report to stderr instead of claiming a saved path.
+* @param error - startup audit failure retaining plugin metadata and original errors.
+* @param context - resolved Harness home, application version, and selected profile.
+* @param write - terminal output sink; awaited before returning, defaults to stderr.
+* @returns after saving or printing the report and completing terminal writes.
+*/
+async function reportStartupFailure(error, context, write = writeStderr) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const report = "WARNING: Raw diagnostics may contain configuration or credential values from plugin errors. Review before sharing.\n\n" + inspect({
+		timestamp: now,
+		qilinVersion: context.version,
+		nodeVersion: process.version,
+		platform: process.platform,
+		arch: process.arch,
+		profile: context.profile,
+		error
+	}, {
+		depth: null,
+		maxArrayLength: null,
+		maxStringLength: null,
+		showHidden: true,
+		customInspect: false,
+		getters: false,
+		colors: false
+	}) + "\n";
+	await write(`${error.message}\n`);
+	const logDir = join(context.home, "logs");
+	const logPath = join(logDir, `startup-${now.replaceAll(":", "-")}-${randomUUID()}.log`);
+	try {
+		await mkdir(logDir, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(logPath, report, {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (writeError) {
+		await write(`\nqilin: warning: could not write startup diagnostics: ${String(writeError)}\nFull diagnostics:\n${report}`);
+		return;
+	}
+	await write(`\nFull diagnostics: ${logPath}\n`);
+}
+//#endregion
+//#region lib/types/bin.js
+/**
+* Command-line entry for qilin.
+* @module @qilin-agent/cli/bin
+*/
+/* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
+installSchedulerYield();
+/**
+* Run the public qilin command-line interface.
+* @returns a promise that settles when the selected command mode finishes.
+*/
+async function runCli() {
+	const version = getQilinRuntimeVersion();
+	const invocation = parseQilinArgs(process.argv.slice(2), version);
+	switch (invocation.mode) {
+		case "profile": {
+			const { ENTRY_PROFILES, isWebEntry, runWebEntry } = await import("./web-entry-C--0C6wG.js");
+			if (ENTRY_PROFILES.includes(invocation.profile) && isWebEntry()) {
+				try {
+					process.exitCode = await runWebEntry({
+						args: invocation.args,
+						profile: invocation.profile,
+						patches: invocation.patches,
+						fromDefaultProfile: invocation.fromDefaultProfile
+					});
+				} catch (error) {
+					process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+					process.exit(1);
+				}
+				break;
+			}
+			const { runProfile } = await import("./profile-boot.js");
+			try {
+				await runProfile({
+					environment: loadLayeredEnv("qilin"),
+					profile: invocation.profile,
+					fromDefaultProfile: invocation.fromDefaultProfile,
+					patchFiles: invocation.patches,
+					args: invocation.args
+				});
+			} catch (error) {
+				if (!(error instanceof StartupError)) throw error;
+				await reportStartupFailure(error, {
+					home: resolveQilinHome(),
+					version,
+					profile: invocation.profile
+				});
+				process.exit(1);
+			}
+			break;
+		}
+		case "plugin": {
+			const { runPlugin } = await import("./plugin-BQ1sn-63.js");
+			process.exit(await runPlugin(invocation.profile, invocation.args));
+			break;
+		}
+		case "tenants": {
+			const { runTenantsRoster } = await import("./tenants-roster-Bhr9x2Jw.js");
+			process.exitCode = await runTenantsRoster(invocation.request);
+			break;
+		}
+		case "dump-config": {
+			const { runDumpConfig } = await import("./dump-config-_HRfhhWz.js");
+			runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches, invocation.fromDefaultProfile);
+			break;
+		}
+		default: throw new Error(`qilin: unhandled invocation mode ${JSON.stringify(invocation)}`);
+	}
+}
+if (import.meta.main) await runCli();
+//#endregion
+export { runCli };

package/lib/dump-config-_HRfhhWz.js

@@ -0,0 +1,53 @@
+import { a as prepareProfile, n as PROFILE_ROOT_FILENAME, r as homePatchPath } from "./profile-boot-DSy6PUHQ.js";
+import { loadOptionalPatches, loadOverlayPatches, renderConfigDump } from "@qilin-agent/app-boot";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+//#region lib/types/dump-config.js
+/**
+* Config-dump entry for `qilin --profile <name> --dump-config`: compose the
+* profile's patch layers through the include plugin's patch algorithm without
+* booting or evaluating `!!js`, with one source layer per bundle, the
+* profile's own patch file, and each `--patch` overlay.
+* @module @qilin-agent/cli/dump-config
+*/
+const NAME = "qilin";
+/* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
+/**
+* Print a profile composition with comments naming each source file and patch layer.
+* @param profile - the profile name.
+* @param defaultOnly - omit the profile's user layer and `--patch` overlays
+* (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+* never parsed).
+* @param patches - `--patch` overlay paths, in argv order.
+* @param fromDefaultProfile - shipped template used once to initialize a missing profile.
+*/
+function runDumpConfig(profile, defaultOnly, patches, fromDefaultProfile) {
+	const loaded = prepareProfile(profile, !defaultOnly, fromDefaultProfile);
+	const layers = loaded.layers.map((layer) => ({
+		label: layer.packageName,
+		patches: layer.patches
+	}));
+	if (!defaultOnly) {
+		if (existsSync(loaded.patchPath)) layers.push({
+			label: loaded.patchPath,
+			patches: loaded.patches
+		});
+		const homePatchFile = homePatchPath();
+		const homePatches = loadOptionalPatches(NAME, homePatchFile);
+		if (homePatches !== void 0) layers.push({
+			label: homePatchFile,
+			patches: homePatches
+		});
+		for (const file of patches) {
+			const absolute = resolve(file);
+			layers.push({
+				label: absolute,
+				patches: loadOverlayPatches(NAME, absolute)
+			});
+		}
+	}
+	process.stdout.write(renderConfigDump(NAME, join(loaded.dir, PROFILE_ROOT_FILENAME), layers));
+}
+/* v8 ignore stop */
+//#endregion
+export { runDumpConfig };