@chatcode/chatcode-cli-test 1.0.46 → 3.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write apps/cli/README.md
+README.md: 3ff830cff37e8ab848a82c05982997c513b29b08
+README.zh.md: b3077be13064bf50e47eefb641f4739c664a0008

package/README.md

@@ -1,157 +1,63 @@
-# ChatCode-cli使用手册
+# `@chatcode/chatcode-cli`
 
-ChatCode-cli 是 ChatCode官方推出的命令行工具，让你可以在终端中直接与 ChatCode 进行交互，完成代码编写、调试、重构等任务。
+English | [中文](README.zh.md)
 
-## 安装教程
+`chatcode-cli` is the formal launcher and `cco` is its short form; both commands share one parser and start the TUI/CLI profile when invoked without arguments. The hidden `dsh` bin remains a compatibility alias. 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 the same launcher; 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.
 
-### 1. 一键安装
+## Entry modes
 
-如果本机缺少 Node.js，安装脚本会从国内 Node.js 镜像安装 Node.js，然后在安装 ChatCode CLI 与 OpenSpec 时为对应 npm 命令临时指定国内 registry。
+| Command | Purpose |
+|---|---|
+| `chatcode-cli` / `cco` | Start the default TUI/CLI profile. |
+| `chatcode-cli --profile <name>` | Boot the named profile under `$CHATCODE_CLI_HOME/profiles/<name>`. |
+| `chatcode-cli --profile <name> --from-default-profile <template>` | Create a new custom profile from a shipped template, then boot it. |
+| `chatcode-cli --profile acp` | Serve automation clients over ACP stdio until disconnect. |
+| `chatcode-cli --profile headless "job"` | Run one fresh persisted session, print the final answer, and exit. |
+| `chatcode-cli --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
+| `chatcode-cli --profile sdk-minimal` | Serve SDK clients with the standalone minimal agent tree. |
+| `chatcode-cli web` / `cco web` | Boot the Web profile. |
+| `chatcode-cli plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
+| `chatcode-cli migrate --dry-run` | Print the copy-only migration plan from legacy user homes. |
+| `chatcode-cli migrate --apply` | Revalidate and apply that plan without overwriting destination data. |
 
-如果本机已有 Node.js `>= 20`，脚本会直接复用，不会更新。检测到低于 `20` 的 Node.js 时，脚本会先询问是否升级；拒绝升级将退出安装。
+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 `chatcode-cli plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it.
 
-安装 ChatCode CLI 前，脚本会通过 `--registry=https://registry.npmmirror.com` 检查 `@chatcode/chatcode-cli` 是否为最新版本。如果已安装版本不是最新版本，会提示当前版本和最新版本，并询问是否更新；拒绝更新时会继续保留当前已安装版本。
+## App arguments
 
-Windows 会检查 Git for Windows 和 Git Bash。建议使用 Git `>= 2.21.0`；检测到更低版本时会显示 warning，但不会阻断安装。
-
-如果本机已安装 nvm，脚本会优先通过 nvm 安装和切换 Node.js。脚本不会持久写入 npm prefix，也不会设置与 nvm 冲突的 `NPM_CONFIG_PREFIX`。
-
-安装完成后，脚本会同步安装 `@fission-ai/openspec@latest`，在 `~/.chatcode-cli/openspec-workspace` 中执行 OpenSpec 初始化，并把当前 OpenSpec 版本生成的 `/opsx:*` 命令和 skills 同步到 `~/.chatcode-cli`，安装后可直接使用 `chatcode-cli` 和 `openspec`。
-
-macOS/Linux：
+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 ([`dsh-cmdline`](../../packages/boot/cmdline/README.md)). The first token the launcher does not recognize starts the app's arguments:
 
 ```sh
-curl -fsSL "http://gitlab.tianti.tg.unicom.local/kubernetesAMP/visualDesignPlatform/chatcode-cli/-/raw/dev_v1alpha/scripts/install/install.sh" | sh
+chatcode-cli --profile web --port 8080       # --port belongs to the web app
+cco --resume <id>                            # --resume belongs to the default terminal app
+chatcode-cli --profile headless "run the tests"
+chatcode-cli --profile web --help            # the web app's flags, not the launcher's
+chatcode-cli --help                          # the launcher's own help
 ```
 
-Windows PowerShell：
+<a id="profiles"></a>
+## Profiles
 
-```powershell
-irm "http://gitlab.tianti.tg.unicom.local/kubernetesAMP/visualDesignPlatform/chatcode-cli/-/raw/dev_v1alpha/scripts/install/install-windows.ps1" | iex
-```
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer). `dsh-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 `chatcode-cli 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.
 
-安装前可以审阅 `scripts/install/install.sh`、`scripts/install/install-macos.sh`、`scripts/install/install-linux.sh` 和 `scripts/install/install-windows.ps1`。
+The tree composes over an empty root:
+- each bundle's patch in `dsh.profile.bundles` order
+- then the profile's `cordis.patch.yml`, then the home-level `$CHATCODE_CLI_HOME/cordis.patch.yml`
+- then `--patch` overlays
 
-验证安装成功：
-
-```
-node --version
-chatcode-cli --version
-openspec --version
-```
+Bundles named in `dsh.profile.bundles` resolve from the ChatCode CLI installation first (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`, `@deepseek-ai/dsh-sdk-app`, `@deepseek-ai/dsh-sdk-minimal`, `@deepseek-ai/dsh-acp-app`), then from the profile's own `node_modules`, where pnpm installs DSH-compatible plugins.
 
-Windows 安装后如果新打开标签页仍提示 `node` 或 `chatcode-cli` 不存在，请关闭所有 Windows Terminal 窗口后重新打开 PowerShell。
+Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
 
-### 2. 已有 Node.js 时手动安装
+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.
 
-方式1：外部安装
+## Optional overlays
 
-```bash
-npm install -g @chatcode/chatcode-cli@latest
-```
-
-方式2：内部仓库安装
-
-```bash
-npm install -g @chatcode/chatcode-cli@latest --registry http://ccp.tianti.tg.unicom.local/artifactory/api/npm/ckp-npm-virtual/
-```
-
-### 3. 配置ChatCode CLI设置
-
-创建或编辑 `~/.chatcode-cli/settings.json`，添加以下配置，注意需要配置您自己的 OPENAI 地址 URL、密钥 APIKEY 和使用的模型名。
-
-```json
-{
-  "env": {
-    "OPENAI_API_KEY": "[您的OPENAI密钥APIKEY]",
-    "OPENAI_BASE_URL": "[您的OPENAI地址URL]",
-    "CHATCODE_CLI_MAX_OUTPUT_TOKENS": "[按照您模型的最大token数]",
-    "CHATCODE_CLI_DISABLE_NONESSENTIAL_TRAFFIC": "1",
-    "OPENAI_MODEL": "[您的模型名]"
-  },
-  "permissions": {
-    "allow": [],
-    "deny": []
-  },
-  "model": "[您的模型名]"
-}
-```
+`config/examples/` ships opt-in overlays for GitHub review webhooks, session-local Schedule, memory MCP servers, and runtime Cordis 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.
 
-DeepSeek V4 users can configure external OpenAI-compatible models with `"model": "deepseek-v4-pro"` or `"model": "deepseek-v4-flash"`. These model names now use the same generic OpenAI-compatible path as other external models; the DeepSeek V4-specific adapter code is retained in the source tree but disabled at the entry point. The built-in ChatCode default remains `DeepSeek-V3`.
-
-### 4. 启动ChatCode CLI
-
-```bash
-chatcode-cli
-```
-
-### 5. 首次启动配置
-
-首次启动需要配置信任当前文件夹，直接回车即可。
-
-
-
-## 卸载和重新安装
-
-如果遇到问题需要重新安装 ChatCode CLI:
-
-```bash
-# 卸载
-npm uninstall -g @chatcode/chatcode-cli
-
-# 重新安装
-# 方式1：外部安装
-npm install -g @chatcode/chatcode-cli@latest 
-# 方式2：内部仓库安装
-npm install -g @chatcode/chatcode-cli@latest --registry http://ccp.tianti.tg.unicom.local/artifactory/api/npm/ckp-npm-virtual/
-```
+## Development
 
+Production runs require built package and frontend artifacts. From the repository root, run `pnpm run build` separately, then use `pnpm cco <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 `@chatcode/chatcode-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 ChatCode CLI home patch, proxy environment, telemetry switch, patch reload, and bounded shutdown.
 
-## 常用内置命令
-
-ChatCode CLI 中可用的内置命令的参考。
-
-在 ChatCode CLI 中输入 `/` 可以查看所有可用命令，或输入 `/` 后跟任何字母来筛选。ChatCode CLI 还包括捆绑的 skills，如 `/simplify`、`/batch`、`/debug` 和 `/loop`，当您输入 `/` 时会与内置命令一起显示。
-
-部分常用命令如下表，在下表中，`<arg>` 表示必需的参数，`[arg]` 表示可选参数。
-
-| 命令                                 | 用途                                                         |
-| :----------------------------------- | :----------------------------------------------------------- |
-| `/add-dir <path>`                    | 向当前会话添加新的工作目录                                   |
-| `/agents`                            | 管理 agent 配置                                              |
-| `/btw <question>`                    | 提出快速[附加问题]，无需添加到对话中                         |
-| `/clear`                             | 清除对话历史记录并释放上下文。别名：`/reset`、`/new`         |
-| `/color [color|default]`             | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置 |
-| `/compact [instructions]`            | 压缩对话，可选择性地提供焦点说明                             |
-| `/config`                            | 打开[设置]界面以调整主题、模型、[输出样式]和其他偏好设置。别名：`/settings` |
-| `/context`                           | 将当前上下文使用情况可视化为彩色网格。显示上下文密集型工具、内存膨胀和容量警告的优化建议 |
-| `/copy [N]`                          | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |
-| `/cost`                              | 显示令牌使用统计信息。                                       |
-| `/diff`                              | 打开交互式差异查看器，显示未提交的更改和每轮差异。使用左/右箭头在当前 git 差异和单个轮次之间切换，使用上/下浏览文件 |
-| `/doctor`                            | 诊断并验证您的安装和设置                                     |
-| `/effort [low|medium|high|max|auto]` | 设置模型工作量级别。`low`、`medium` 和 `high` 在会话间保持。`max` 仅适用于当前会话，需要支持的模型。`auto` 重置为模型默认值。不带参数时，显示当前级别。立即生效，无需等待当前响应完成 |
-| `/exit`                              | 退出 CLI。别名：`/quit`                                      |
-| `/export [filename]`                 | 将当前对话导出为纯文本。使用文件名时，直接写入该文件。不使用文件名时，打开对话框以复制到剪贴板或保存到文件 |
-| `/fast [on|off]`                     | 切换快速模式开启或关闭                                       |
-| `/branch [name]`                     | 在此点创建当前对话的分支。别名：`/fork`                      |
-| `/help`                              | 显示帮助和可用命令                                           |
-| `/hooks`                             | 查看工具事件的 hook 配置                                     |
-| `/init`                              | 使用 `AGENTS.md` 指南初始化项目。                            |
-| `/insights`                          | 生成报告，分析您的 ChatCode 会话，包括项目领域、交互模式和摩擦点 |
-| `/keybindings`                       | 打开或创建您的快捷键配置文件                                 |
-| `/login`                             | 登录到您的  账户（暂未支持）                                 |
-| `/logout`                            | 从您的 账户登出（暂未支持）                                  |
-| `/model [model]`                     | 选择或更改 AI 模型。对于支持的模型，使用左/右箭头[调整工作量级别]。更改立即生效，无需等待当前响应完成 |
-| `/plan [description]`                | 直接从提示进入计划模式。传递可选描述以进入计划模式并立即开始该任务，例如 `/plan fix the auth bug` |
-| `/plugin`                            | 管理 ChatCode Plugins                                           |
-| `/rename [name]`                     | 重命名当前会话并在提示栏上显示名称。不使用名称时，从对话历史记录自动生成一个 |
-| `/resume [session]`                  | 按 ID 或名称恢复对话，或打开会话选择器。别名：`/continue`    |
-| `/rewind`                            | 将对话和/或代码倒回到上一个点，或从选定的消息进行总结。别名：`/checkpoint` |
-| `/security-review`                   | 分析当前分支上的待处理更改以查找安全漏洞。审查 git 差异并识别注入、身份验证问题和数据泄露等风险 |
-| `/skills`                            | 列出可用的 skills                                            |
-| `/stats`                             | 可视化每日使用情况、会话历史记录、连续记录和模型偏好         |
-| `/status`                            | 打开设置界面（状态选项卡），显示版本、模型、账户和连接性。在 ChatCode响应时工作，无需等待当前响应完成 |
-| `/tasks`                             | 列出并管理后台任务                                           |
-| `/theme`                             | 更改颜色主题。包括浅色和深色变体、色盲友好（道尔顿化）主题和使用您终端颜色调色板的 ANSI 主题 |
-| `/vim`                               | 在 Vim 和普通编辑模式之间切换                                |
+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,63 @@
+# `@chatcode/chatcode-cli`
+
+[English](README.md) | 中文
+
+`chatcode-cli` 是正式启动命令，`cco` 是其简写；两者共用同一解析器，且无参数时都启动 TUI/CLI profile。隐藏的 `dsh` bin 仅作为兼容别名保留。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) 只加载选中的运行器。无效命令、来自其他模式的选项，以及致命的配置或启动错误都会以非零状态退出。
+
+## 入口模式
+
+| 命令 | 用途 |
+|---|---|
+| `chatcode-cli` / `cco` | 启动默认 TUI/CLI profile。 |
+| `chatcode-cli --profile <name>` | 启动位于 `$CHATCODE_CLI_HOME/profiles/<name>` 的指定 profile。 |
+| `chatcode-cli --profile <name> --from-default-profile <template>` | 从随附模板创建新的自定义 profile，然后启动它。 |
+| `chatcode-cli --profile acp` | 通过 ACP stdio 为自动化客户端提供服务，直至断开连接。 |
+| `chatcode-cli --profile headless "job"` | 运行一个全新的持久化会话，打印最终答案并退出。 |
+| `chatcode-cli --profile sdk` | 通过 JSON-RPC stdio 为 SDK 客户端提供服务，直至关闭或断开连接。 |
+| `chatcode-cli --profile sdk-minimal` | 以独立极简 agent（智能体）配置树为 SDK 客户端提供服务。 |
+| `chatcode-cli web` / `cco web` | 启动 Web profile。 |
+| `chatcode-cli plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
+| `chatcode-cli migrate --dry-run` | 输出旧版用户目录的只复制迁移计划。 |
+| `chatcode-cli migrate --apply` | 重新校验并应用计划，绝不覆盖目标数据。 |
+
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化。使用 `--from-default-profile` 可以基于这些模板之一，在尚未使用的非内置名称处创建其他 profile；通过 `chatcode-cli plugin` 则可以初始化一个以 base 为基础的 profile。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI（命令行界面）会拒绝针对它的启动、配置 dump 和插件管理请求。
+
+## 应用参数
+
+启动器只解析自身的 flag，并将其后的所有内容交给已启动的 profile；注入该 profile 的任意应用插件都可以解析这份共享的不可变快照（[`dsh-cmdline`](../../packages/boot/cmdline/README.zh.md)）。启动器无法识别的第一个 token 标志着应用参数的开始：
+
+```sh
+chatcode-cli --profile web --port 8080       # --port belongs to the web app
+cco --resume <id>                            # --resume belongs to the default terminal app
+chatcode-cli --profile headless "run the tests"
+chatcode-cli --profile web --help            # the web app's flags, not the launcher's
+chatcode-cli --help                          # the launcher's own help
+```
+
+<a id="profiles"></a>
+## Profile
+
+profile 目录包含一个 `package.json`，其中记录树外插件依赖，以及 profile manifest（元数据清单）`dsh.profile`、其中按顺序排列的 `bundles` 列表；还包含一个 `cordis.patch.yml`，其中保存用户自己的 patch 层。在 YAML 中启用的 `dsh-hmr` 监视 profile manifest、profile 与 home 级 patch 文件，再通过统一串行重载重新组合所有层。未启用 HMR 时，更改在重启后生效。监听器注册期间发生的编辑与后续编辑使用相同的非致命重载错误报告。[插件管理器](../../packages/boot/plugin-manager/README.zh.md) 与 `chatcode-cli plugin` 共享包操作和 profile 写锁；更新依赖会保留已停用的组合包选择。CLI 包操作继承认证环境和终端描述符，支持交互式构建批准；service 调用保留清理后的环境并捕获诊断。
+
+配置树以空根为起点，依次叠加以下配置层：
+- `dsh.profile.bundles` 中各组合包的 patch
+- profile 自身的 `cordis.patch.yml`，然后是 home 级的 `$CHATCODE_CLI_HOME/cordis.patch.yml`
+- `--patch` 指定的覆盖层
+
+`dsh.profile.bundles` 中列出的组合包先从 ChatCode CLI 安装目录解析（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-sdk-app`、`@deepseek-ai/dsh-sdk-minimal`、`@deepseek-ai/dsh-acp-app`），再从 profile 自身的 `node_modules` 解析；pnpm 会将 DSH 兼容插件安装到该目录。
+
+使用 `--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 服务器与运行时 Cordis 工具的可选覆盖层。它们绝不属于默认 profile；设置与安全说明由[用户指南](../../docs/user/guide/index.zh.md)和[开发实战指南](../../docs/user/develop/practice/index.zh.md)负责。
+
+## 开发
+
+生产运行需要已构建的包与前端产物。请在仓库根目录单独运行 `pnpm run build`，然后使用 `pnpm cco <args...>` 运行 TypeScript 入口并转发所有参数；模块解析约定以[源码执行参考](reference/README.zh.md#source-execution)为准。
+
+`@chatcode/chatcode-cli/profile-boot` 导出向 Desktop Host 提供共享 profile 生命周期。已解析的应用 profile 为运行时包解析指定自己的安装锚点，同时沿用 ChatCode CLI 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,302 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { StartupError, loadLayeredEnv } from "@deepseek-ai/dsh-app-boot";
+import { resolveChatCodeCliHome } from "@deepseek-ai/dsh-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 ChatCode CLI launcher.
+*
+* 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
+* `@deepseek-ai/dsh-cmdline`). Launcher flags therefore come first: the first
+* token this parser does not recognize starts the inner arguments, so
+* `chatcode-cli --profile cli --resume abc` boots the cli profile with
+* `--resume abc`, and `chatcode-cli --profile web -h` prints the web app's
+* help, not this one's.
+*
+* `chatcode-cli <name>` abbreviates `chatcode-cli --profile <name>`; `plugin`
+* manages a profile's plugin dependencies by forwarding to pnpm. A bare
+* public launcher boots `$CHATCODE_CLI_DEFAULT_PROFILE`, then legacy
+* `$DSH_DEFAULT_PROFILE`, else the builtin `cli` profile.
+* @module @chatcode/chatcode-cli/args
+*/
+/** Environment variables controlling the bare-launcher default profile. */
+const DEFAULT_PROFILE_ENV = "CHATCODE_CLI_DEFAULT_PROFILE";
+const LEGACY_DEFAULT_PROFILE_ENV = "DSH_DEFAULT_PROFILE";
+/** Resolve the bare-launcher profile with canonical-before-legacy precedence. */
+function resolveDefaultProfile(env = process.env) {
+	const canonical = env[DEFAULT_PROFILE_ENV]?.trim();
+	if (canonical !== void 0 && canonical !== "") return canonical;
+	const legacy = env[LEGACY_DEFAULT_PROFILE_ENV]?.trim();
+	return legacy !== void 0 && legacy !== "" ? legacy : "cli";
+}
+/**
+* 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 rejectElectronProfile(program, profile) {
+	if (profile.toLowerCase() === "desktop") program.error("error: profile \"desktop\" is managed exclusively by the Electron application");
+}
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  chatcode-cli                              boot the default CLI profile (short: cco)
+  chatcode-cli web                         boot the web profile (short: cco web)
+  chatcode-cli rescue --from-default-profile web
+                                            create rescue from the shipped web template, then boot it
+  chatcode-cli headless "run the tests"     answer one task, print the result, and exit
+  chatcode-cli cli --patch ./extra.yml      boot the CLI profile with one extra overlay
+  chatcode-cli cli --resume <session>       arguments after launcher flags reach the app
+  chatcode-cli web --help                   the web app's own flags and help
+  chatcode-cli plugin --profile cli add <package>
+                                            install a plugin into the CLI profile
+  chatcode-cli migrate --dry-run            print a safe ~/.dsh migration plan
+  chatcode-cli migrate --apply              apply the reviewed copy-only plan
+
+The bare-command default comes from ${DEFAULT_PROFILE_ENV} when set.
+${LEGACY_DEFAULT_PROFILE_ENV} is accepted only when the canonical variable is unset.
+`;
+/**
+* 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 parseChatCodeCliArgs(argv, version) {
+	const first = argv[0];
+	let resolved;
+	const program = new Command();
+	program.name("chatcode-cli").version(version, "-V, --version", "output the version number").usage("[--profile] [name] [options] [app-args...]\n       chatcode-cli plugin --profile <name> <pnpm-args...>\n       chatcode-cli migrate [--dry-run|--apply] [--json]").description("ChatCode CLI: start a profile-backed coding agent. A bare command starts the TUI/CLI profile.").addHelpText("after", HELP_EXAMPLES).exitOverride().helpOption(false).helpCommand(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the booted profile's app (see: chatcode-cli --profile <name> --help)").option("--profile <name>", `the profile under $CHATCODE_CLI_HOME/profiles to boot (default: $${DEFAULT_PROFILE_ENV} or cli)`, 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) {
+			if (args.some((argument) => argument === "-h" || argument === "--help")) program.help();
+			if (options.fromDefaultProfile !== void 0) program.error("error: --from-default-profile requires --profile <name>");
+			options.profile = resolveDefaultProfile();
+		}
+		const profile = options.profile;
+		if (profile === "") program.error("error: --profile needs a name");
+		rejectElectronProfile(program, profile);
+		resolved = resolveBoot(program, profile, options, args);
+	});
+	if (first === "plugin") {
+		const plugin = program.command("plugin").description("manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory");
+		plugin.requiredOption("--profile <name>", "the profile whose plugins to manage (initialized on first use)", selectProfile).allowUnknownOption().argument("[args...]", "pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)").action((args, options) => {
+			if (options.profile === "") program.error("error: --profile needs a name");
+			rejectElectronProfile(plugin, options.profile);
+			if (args.length === 0) program.error("error: plugin needs pnpm arguments to forward (e.g. add <package>)");
+			resolved = {
+				mode: "plugin",
+				profile: options.profile,
+				args
+			};
+		});
+	}
+	if (first === "migrate") {
+		const migrate = program.command("migrate").description("plan or apply non-destructive migration from legacy Harness and TUI homes");
+		migrate.option("--dry-run", "print the migration plan without writing (the default)").option("--apply", "apply the reviewed copy-only migration plan").option("--json", "print machine-readable JSON").action((options) => {
+			if (options.apply === true && options.dryRun === true) migrate.error("error: --apply and --dry-run are mutually exclusive");
+			resolved = {
+				mode: "migrate",
+				apply: options.apply === true,
+				json: options.json === true
+			};
+		});
+	}
+	try {
+		const expanded = first !== void 0 && !first.startsWith("-") && first !== "plugin" && first !== "migrate" ? ["--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("ChatCode CLI: no invocation resolved");
+	return resolved;
+}
+//#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 DSH_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,
+		dshVersion: 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(`\ndsh: 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 ChatCode CLI and its compatibility aliases.
+* @module @chatcode/chatcode-cli/bin
+*/
+/* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
+function readVersion() {
+	const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+	return typeof manifest.version === "string" ? manifest.version : "0.0.0";
+}
+/**
+* Set the canonical process identity shared by all launcher aliases.
+*/
+function initializeProcessIdentity() {
+	process.title = "chatcode-cli";
+}
+/**
+* Run the public ChatCode CLI command-line interface.
+* @returns a promise that settles when the selected command mode finishes.
+*/
+async function runCli() {
+	initializeProcessIdentity();
+	const version = readVersion();
+	const invocation = parseChatCodeCliArgs(process.argv.slice(2), version);
+	switch (invocation.mode) {
+		case "profile": {
+			const legacyHome = process.env.DSH_HOME?.trim();
+			if (process.env.CHATCODE_CLI_HOME?.trim() || legacyHome === void 0 || legacyHome === "") {
+				const { detectPendingHomeMigrations, resolveHomeMigrationRoots } = await import("./home-migration-BejD6LQn.js");
+				if ((await detectPendingHomeMigrations(resolveHomeMigrationRoots())).length > 0) process.stderr.write("ChatCode CLI detected legacy user data. Preview the non-destructive migration with \"chatcode-cli migrate --dry-run\"; nothing is migrated automatically.\n");
+			}
+			const { runProfile } = await import("./profile-boot.js");
+			try {
+				await runProfile({
+					environment: loadLayeredEnv("ChatCode CLI"),
+					profile: invocation.profile,
+					fromDefaultProfile: invocation.fromDefaultProfile,
+					patchFiles: invocation.patches,
+					args: invocation.args
+				});
+			} catch (error) {
+				if (!(error instanceof StartupError)) throw error;
+				await reportStartupFailure(error, {
+					home: resolveChatCodeCliHome(),
+					version,
+					profile: invocation.profile
+				});
+				process.exit(1);
+			}
+			break;
+		}
+		case "migrate": {
+			const { applyHomeMigration, formatHomeMigrationPlan, planHomeMigration, resolveHomeMigrationRoots } = await import("./home-migration-BejD6LQn.js");
+			const roots = resolveHomeMigrationRoots();
+			const migrations = [[roots.source, roots.destination], [roots.tuiSource, roots.tuiDestination]];
+			if (!invocation.apply) {
+				const plans = await Promise.all(migrations.map(([source, destination]) => planHomeMigration(source, destination)));
+				process.stdout.write(invocation.json ? `${JSON.stringify({ plans }, null, 2)}\n` : `${plans.map(formatHomeMigrationPlan).join("\n\n")}\n`);
+				break;
+			}
+			const results = [];
+			for (const [source, destination] of migrations) {
+				const plan = await planHomeMigration(source, destination);
+				process.stderr.write(`${formatHomeMigrationPlan(plan)}\n\n`);
+				results.push(await applyHomeMigration(plan));
+			}
+			process.stdout.write(invocation.json ? `${JSON.stringify({ results }, null, 2)}\n` : `Applied: copied ${results.reduce((sum, result) => sum + result.copied.length, 0)} files; skipped ${results.reduce((sum, result) => sum + result.skipped.length, 0)}.\nMigration records: ${results.flatMap((result) => result.recordPath ?? []).join(", ") || "not written"}\n`);
+			break;
+		}
+		case "plugin": {
+			const { runPlugin } = await import("./plugin-DrWxOiv2.js");
+			process.exit(await runPlugin(invocation.profile, invocation.args));
+			break;
+		}
+		case "dump-config": {
+			const { runDumpConfig } = await import("./dump-config-Bn-CzGIR.js");
+			runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches, invocation.fromDefaultProfile);
+			break;
+		}
+		default: throw new Error(`ChatCode CLI: unhandled invocation mode ${JSON.stringify(invocation)}`);
+	}
+}
+if (import.meta.main) await runCli();
+//#endregion
+export { initializeProcessIdentity, runCli };