@shendeguize/remote-dsh-center 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yang Jingyu
+
+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.en.md

@@ -0,0 +1,197 @@
+# DSH Center
+
+[中文](README.md) · **English**
+
+[![CI](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/ci.yml/badge.svg)](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/ci.yml)
+[![Pages](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/pages.yml/badge.svg)](https://shendeguize.github.io/Remote_DSH_Center/)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-3c873a)](https://nodejs.org/)
+[![deps](https://img.shields.io/badge/npm%20deps-0-blue)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Open local and remote `dsh web` instances from one Hub on your machine. Local instances connect
+directly; remote instances are mapped onto local loopback through `ssh -L`. Nothing is installed
+or kept resident on remote hosts: probe, start, and stop are all one-shot SSH commands.
+
+**[▶ Live demo](https://shendeguize.github.io/Remote_DSH_Center/demo/)** — the real frontend
+against an in-browser mock manager; try start, disconnect, and recovery ·
+[Project page](https://shendeguize.github.io/Remote_DSH_Center/)
+
+![DSH Center Hub: one entry point for local and remote dsh web](site/assets/shots/dashboard.png)
+
+*Hub — every available host, current state, and entry point on one page.*
+
+## Five-minute quick start
+
+Minimum prerequisites: run the manager on macOS or Linux; source / git installs need Node ≥ 22;
+managed targets need a configured `dsh` web profile, and remotes also need key-based SSH with TCP
+forwarding. See [Requirements](#requirements) for details.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/shendeguize/Remote_DSH_Center/main/install.sh | bash
+export PATH="$HOME/.local/bin:$PATH"  # default prefix; add a custom prefix as the installer says
+dshc init      # four steps: ports → remote convention → choose local/SSH hosts → confirm
+dshc up        # start the local manager in the background
+dshc open      # open the Hub in your browser
+```
+
+By default, installation links `dshc` under `~/.local/bin`; the `export` makes it available in
+the current shell immediately. If you passed `--prefix`, use the directory printed by the
+installer instead. The installer chooses the git or macOS standalone channel automatically; the wizard probes a
+local candidate plus remotes from `~/.ssh/config`. See the [handbook](HANDBOOK.en.md) for every
+install option and first-start detail.
+
+## The problem
+
+- **One local + remote entry point.** The browser uses the actual local web port or an
+  `ssh -L` mapped port for a remote.
+- **Nothing resident or installed remotely.** Control actions use one-shot SSH. Center-managed
+  logs, patches, and temporary files stay under `~/.dsh_center_remote/`; the one explicit
+  exception is a user saving dsh configuration to `${DSH_HOME:-$HOME/.dsh}/settings.yaml`.
+- **Hub plus persistent tabs.** Start and enter a `ready` host in one click; iframe sessions
+  survive view switches without reloads.
+- **Self-healing tunnels.** A remote disconnect becomes `degraded` and retries with backoff;
+  only a genuinely dead process becomes `crashed`.
+- **Never kills the wrong process.** Stop compares the `ps` command-line fingerprint verbatim;
+  manual instances are read-only, and a mismatch refuses the kill.
+- **Zero npm dependencies.** Runtime and tests use Node ≥ 22 built-ins; the frontend is native
+  ESM with no build step.
+
+## Requirements
+
+- Source / git installs need **Node ≥ 22**; macOS standalone bundles carry official Node.
+- Every managed local or remote target needs DeepSeek Harness (`dsh`) and a configured web
+  profile. Center probes for them; it does not install `dsh`.
+- Put remote hosts in `~/.ssh/config`, enable key-based login, and allow TCP forwarding.
+  Managing the local machine is optional.
+
+## Support matrix
+
+| Platform | Install and release commitment | Verification |
+|---|---|---|
+| macOS arm64 (Apple Silicon) | First-class source / git install and standalone Release bundle | Matching bundle built and verified on real hardware |
+| macOS x64 (Intel) | First-class source / git install and standalone Release bundle | Matching bundle built and verified on real hardware |
+| Linux | Best-effort source / git installation and foreground operation; no bundle or `dshc service` | Project gates run in Ubuntu CI |
+
+**Node 22** is the tested minimum for source / git installs. Any increase is announced in the
+[CHANGELOG](CHANGELOG.md) and corresponding release notes.
+
+## Install
+
+The one-command installer is at the top of this page. See the
+[installation handbook](HANDBOOK.en.md#installation) for forced channels, pre-releases,
+install prefixes, launchd autostart, manual installation, and bundle provenance verification
+with `SHA256SUMS` plus `gh attestation verify`.
+
+## A look around
+
+Center UI screenshots come from one headless-browser capture flow. The iframe image uses an
+independent mock dsh web only to show the shape of the integration; it is not a screenshot of
+the target product's real page.
+
+| | |
+|---|---|
+| ![First-run wizard probing local and remote hosts](site/assets/shots/setup.png) | ![Host details with configuration and management actions](site/assets/shots/drawer.png) |
+| *First-run wizard — probe candidates and choose managed hosts.* | *Host details — configuration, logs, and actions in one place.* |
+| ![A mock dsh web in a persistent tab](site/assets/shots/iframe.png) | ![Recovery overlay after a remote tunnel disconnects](site/assets/shots/degraded.png) |
+| *Workspace tab — an independent mock shows the integration shape; switches do not reload.* | *Disconnect recovery — content stays while the tunnel reconnects.* |
+
+## Architecture and data flow
+
+```mermaid
+flowchart LR
+    B[Browser<br/>Hub + iframes] -->|REST + SSE| M[Local manager<br/>127.0.0.1]
+    C[dshc CLI] -->|REST| M
+    M -->|one-shot local shell| L[Local dsh web]
+    B -.->|actual loopback port| L
+    M -->|one-shot SSH control| R[Remote dsh web]
+    M --> T[ssh -L tunnel]
+    B -.->|local mapped port| T
+    T ==>|encrypted forwarding| R
+```
+
+- The manager is the single source of truth for runtime state and ports; the frontend only uses
+  the `mappedUrl` returned by the backend.
+- The control plane is REST/SSE followed by local shell or one-shot SSH. Pages, assets, and
+  WebSockets connect directly from the browser to the actual local port or remote mapped port;
+  the manager does not proxy the data plane.
+- The UI never advances state optimistically; it waits for SSE events. See
+  [architecture details](HANDBOOK.en.md#architecture-details) for the state machine and recovery.
+
+## Everyday entry points
+
+- `#/hub` is the default entry; a `ready` host starts and opens in one step, and iframe view
+  switches do not reload it.
+- `#/manage` provides probe-all, configuration reload, global defaults, events, and host details.
+
+## States and self-healing
+
+A remote disconnect becomes `degraded` and retries with 1/2/4/8/16/30-second backoff. A
+30-second sweep requires actual HTTP response bytes before deep SSH verification. A manager
+restart adopts fingerprint-matched survivors instead of relaunching them. See the
+[handbook](HANDBOOK.en.md#states-and-self-healing) for the full state machine.
+
+## Configuration and data
+
+The only runtime configuration is `~/.dsh_center/config.json` (`DSHC_HOME` relocates it). See
+[the handbook](HANDBOOK.en.md#configuration-and-data) for launch directories, dsh Workspace
+registration, concurrency-safe editing of `${DSH_HOME:-$HOME/.dsh}/settings.yaml`, and artifact
+boundaries.
+
+## Commands
+
+```text
+Lifecycle: dshc init / up / down / restart / status / logs / service install|uninstall|status
+Itself:    dshc version / update
+Hosts:     dshc ls / probe / start / stop / reconnect / log / open / config
+Exit codes: 0 success | 1 operation failed | 2 timeout/communication failure | 3 usage error | 130 Ctrl-C interrupted the wait (operation continues)
+```
+
+## Security boundary
+
+> The manager listens on `127.0.0.1` and has **no authentication**. Never expose it on
+> `0.0.0.0` or forward it to the public internet.
+
+Stop verifies the process fingerprint verbatim. Injected environment variables and arguments
+appear in `ps`, so never put secrets there. See the
+[handbook](HANDBOOK.en.md#security-boundary) for cross-site defenses, configuration credential
+handling, and artifact path restrictions.
+
+## FAQ
+
+**Does it work on Linux?** Source / git installation and foreground operation are best-effort,
+with project gates running in Ubuntu CI. There is no Linux bundle, and `dshc service` is
+unavailable because it requires macOS launchd.
+
+**Does closing the browser stop an instance?** No. `dshc down` also stops only the manager and
+transport resources; use `dshc stop <host>` to stop a managed instance. See the
+[handbook FAQ](HANDBOOK.en.md#faq) for more.
+
+## Full uninstall
+
+Follow the [handbook procedure](HANDBOOK.en.md#full-uninstallation) to stop instances, remove
+the service and CLI, and then delete manager data. Do not replace `dshc stop` with the
+unfingerprinted `pkill -f "dsh web"`; it may kill other users' matching processes.
+
+## Documentation
+
+- [English handbook](HANDBOOK.en.md) · [中文使用手册](HANDBOOK.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing and PR rules](CONTRIBUTING.md)
+- [Hard constraints before code changes](AGENTS.md)
+
+## Development
+
+This repository has zero dependencies, so there is no `npm install` step:
+
+```bash
+npm run check         # complete quality gate
+npm run site:check    # site, demo, bilingual README links and commands
+```
+
+See [development and real-machine acceptance](HANDBOOK.en.md#development-and-real-machine-acceptance)
+for test layers, site development, the code map, and acceptance commands. Branching, commits,
+PRs, releases, and review follow [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,174 @@
+# DSH Center
+
+**中文** · [English](README.en.md)
+
+[![CI](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/ci.yml/badge.svg)](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/ci.yml)
+[![Pages](https://github.com/shendeguize/Remote_DSH_Center/actions/workflows/pages.yml/badge.svg)](https://shendeguize.github.io/Remote_DSH_Center/)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-3c873a)](https://nodejs.org/)
+[![deps](https://img.shields.io/badge/npm%20deps-0-blue)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+在本机用一个 Hub 打开本机与多台远端主机上的 `dsh web`：本机实例直接连接，远端实例经
+`ssh -L` 安全映射到本机环回地址。远端无需安装 agent、无需常驻守护进程，探测、拉起与关停
+都由一次性 SSH 命令完成。
+
+**[▶ Live demo](https://shendeguize.github.io/Remote_DSH_Center/demo/)** — 真实前端 +
+浏览器内模拟 manager，可直接体验拉起、断联与恢复 ·
+[项目主页](https://shendeguize.github.io/Remote_DSH_Center/)
+
+![DSH Center Hub：统一进入本机与远端 dsh web](site/assets/shots/dashboard.png)
+
+*Hub — 所有可用主机、运行状态与入口集中在一页。*
+
+## 5 分钟上手
+
+最小前提：manager 运行在 macOS 或 Linux；源码 / git 通道需要 Node ≥ 22；受管目标已配置
+`dsh` web profile，远端还需免密 SSH 与 TCP 转发。细节见[前提](#前提)。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/shendeguize/Remote_DSH_Center/main/install.sh | bash
+export PATH="$HOME/.local/bin:$PATH"  # 默认 prefix；自定义 prefix 请按安装器提示加入 PATH
+dshc init      # 四步向导：端口 → 远端约定 → 选择本机/SSH 主机 → 确认
+dshc up        # 后台启动本机 manager
+dshc open      # 在浏览器打开 Hub
+```
+
+默认安装把 `dshc` 链接到 `~/.local/bin`，上面的 `export` 让当前 shell 立即可用；若指定了
+`--prefix`，请改为安装器提示的目录。安装器会自动选择 git 或 macOS standalone 通道；向导会探测本机候选和
+`~/.ssh/config` 中的远端候选。完整安装选项与首次启动说明见[使用手册](HANDBOOK.md)。
+
+## 它解决什么问题
+
+- **本机 + 远端统一入口**：本机浏览器直连实际 web 端口；远端页面走 `ssh -L` 映射端口。
+- **远端零常驻、零安装**：控制动作使用单条一次性 SSH；Center 管理的日志、patch 与临时文件在
+  `~/.dsh_center_remote/`。唯一显式例外是用户保存 dsh 配置时写入
+  `${DSH_HOME:-$HOME/.dsh}/settings.yaml`。
+- **Hub + 保活标签页**：`ready` 主机一步拉起并进入；切页不重载 iframe，会话状态保留。
+- **隧道自愈**：远端断联进入 `degraded` 并退避重连；进程真死才标为 `crashed`。
+- **不误杀**：关停前逐字核对 `ps` 命令行指纹；手动实例只读，指纹不符就拒杀。
+- **零 npm 依赖**：运行时与测试仅使用 Node ≥ 22 内置能力，前端是无需构建的原生 ESM。
+
+## 前提
+
+- 源码 / git / npm 安装需要 **Node ≥ 22**；macOS standalone 发布包自带官方 Node。
+- 要纳管的本机或远端已安装 DeepSeek Harness（`dsh`）并配置 web profile；Center 只探测，
+  不代装 `dsh`。
+- 远端主机已写入 `~/.ssh/config`、可免密登录，且允许 TCP 转发。本机纳管可选。
+
+## 支持矩阵
+
+| 平台 | 安装与发布承诺 | 验证 |
+|---|---|---|
+| macOS arm64（Apple Silicon） | 一等支持：源码 / git 安装与 standalone Release 包 | 对应架构发布包会构建并实机验包 |
+| macOS x64（Intel） | 一等支持：源码 / git 安装与 standalone Release 包 | 对应架构发布包会构建并实机验包 |
+| Linux | 源码 / git 安装与前台运行按 best-effort 支持；无发布包和 `dshc service` | Ubuntu CI 跑通项目闸门 |
+
+源码 / git 安装以 **Node 22** 为经过测试的最低版本；若提高，会在
+[CHANGELOG](CHANGELOG.md) 与对应 Release notes 中提前说明。
+
+## 安装
+
+一键安装命令见页首。有 Node ≥ 22 的机器也可以 `npm i -g @shendeguize/remote-dsh-center`。强制通道、
+预发布版本、安装目录、launchd 自启、手动安装，以及 `SHA256SUMS` +
+`gh attestation verify` 发布包溯源验证见[安装手册](HANDBOOK.md#安装)。
+
+## 界面速览
+
+Center 界面截图来自同一套无头浏览器生成流程。iframe 图使用独立的 mock dsh web，仅用于呈现
+Center 的嵌入集成轮廓，不是目标产品真实页面截图。
+
+| | |
+|---|---|
+| ![首启向导：探测并选择本机与远端主机](site/assets/shots/setup.png) | ![主机详情：配置与管理动作](site/assets/shots/drawer.png) |
+| *首启向导 — 探测候选并选择纳管主机。* | *主机详情 — 配置、日志与管理动作集中呈现。* |
+| ![保活标签页中的 mock dsh web](site/assets/shots/iframe.png) | ![远端隧道断联后的重连遮罩](site/assets/shots/degraded.png) |
+| *工作标签 — 独立 mock 展示嵌入轮廓；切换不重载。* | *断联恢复 — 内容保留，隧道重连后继续。* |
+
+## 架构与数据流
+
+```mermaid
+flowchart LR
+    B[浏览器<br/>Hub + iframe] -->|REST + SSE| M[本机 manager<br/>127.0.0.1]
+    C[dshc CLI] -->|REST| M
+    M -->|一次性本机 shell| L[本机 dsh web]
+    B -.->|实际环回端口| L
+    M -->|一次性 SSH 控制| R[远端 dsh web]
+    M --> T[ssh -L 隧道]
+    B -.->|本机映射端口| T
+    T ==>|加密转发| R
+```
+
+- manager 是运行状态与端口的单一真相源；前端只使用后端下发的 `mappedUrl`。
+- 控制面走 REST/SSE，再落到本机 shell 或一次性 SSH；页面、资源与 WebSocket 由浏览器直连
+  本机实际端口或远端映射端口，不经过 manager 代理。
+- UI 不乐观修改状态，只根据 SSE 事件推进。架构、状态机与恢复细节见
+  [手册的架构章节](HANDBOOK.md#架构细节)。
+
+## 日常入口
+
+- `#/hub` 是默认入口；`ready` 主机可一步拉起并进入，iframe 切页不重载。
+- `#/manage` 提供全量探测、配置重载、全局默认、事件和主机详情。
+
+## 状态与自愈
+
+远端断联进入 `degraded`，按 1/2/4/8/16/30 秒退避重连；30 秒巡检要求 HTTP 真正返回字节，
+失败后再经 SSH 深复核。manager 重启只接管指纹匹配的存活实例，不会重新拉起进程。完整状态机
+见[手册](HANDBOOK.md#状态与自愈)。
+
+## 配置与数据
+
+唯一运行配置是 `~/.dsh_center/config.json`（`DSHC_HOME` 可更换目录）。主机启动目录、
+dsh Workspace 登记、`${DSH_HOME:-$HOME/.dsh}/settings.yaml` 的并发安全编辑与落地物边界见
+[手册](HANDBOOK.md#配置与数据)。
+
+## 命令一览
+
+```text
+生命周期：dshc init / up / down / restart / status / logs / service install|uninstall|status
+自身管理：dshc version / update
+主机操作：dshc ls / probe / start / stop / reconnect / log / open / config
+退出码：0 成功｜1 操作失败｜2 超时/通信失败｜3 用法错误｜130 Ctrl-C 中断等待（操作仍继续）
+```
+
+## 安全边界
+
+> manager 只监听 `127.0.0.1` 且**没有鉴权**。不要暴露到 `0.0.0.0` 或转发到公网。
+
+停止前会逐字核对进程指纹；注入的环境变量与参数会出现在 `ps`，不要放密钥。完整跨站防护、
+配置文件凭据处理与落地路径限制见[手册](HANDBOOK.md#安全边界)。
+
+## FAQ
+
+**Linux 能用吗？** 源码 / git 安装与前台运行按 best-effort 支持，Ubuntu CI 跑项目闸门；
+不提供 Linux 发布包，依赖 macOS launchd 的 `dshc service` 也不可用。
+
+**关闭浏览器会停止实例吗？** 不会。`dshc down` 也只停止 manager 与运输资源；请用
+`dshc stop <主机>` 显式停止受管实例。更多问题见[手册 FAQ](HANDBOOK.md#faq)。
+
+## 彻底卸载
+
+按[手册的卸载顺序](HANDBOOK.md#彻底卸载)先停实例、卸载服务与 CLI，再删除 manager 数据。
+不要用未经指纹校验的 `pkill -f "dsh web"` 代替 `dshc stop`，它可能误杀其他人的实例。
+
+## 文档
+
+- [中文使用手册](HANDBOOK.md) · [English handbook](HANDBOOK.en.md)
+- [版本变化](CHANGELOG.md)
+- [参与开发与 PR 规则](CONTRIBUTING.md)
+- [改代码前的硬约束](AGENTS.md)
+
+## 开发
+
+零依赖仓库，无需 `npm install`：
+
+```bash
+npm run check         # 完整质量闸门
+npm run site:check    # 站点、demo、双语 README 链接与命令检查
+```
+
+测试分层、站点开发、代码地图与真机验收命令见[手册的开发章节](HANDBOOK.md#开发与真机验收)。
+分支、提交、PR、发布与 review 以 [CONTRIBUTING.md](CONTRIBUTING.md) 为准。
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@shendeguize/remote-dsh-center",
+  "version": "0.4.0",
+  "description": "Local manager for remote dsh web instances: ssh tunnels, single-entry iframe shell, CLI lifecycle control",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "dshc": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "scripts/install.mjs"
+  ],
+  "scripts": {
+    "start": "node src/cli.js up --foreground",
+    "check": "node scripts/check.mjs",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "test": "node --test \"tests/**/*.test.js\"",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" \"tests/**/*.test.js\"",
+    "coverage:gate": "node scripts/coverage-gate.mjs",
+    "ui:smoke": "node scripts/ui-smoke.mjs",
+    "acceptance:real": "node scripts/real-acceptance.mjs",
+    "install:cli": "node scripts/install.mjs",
+    "uninstall:cli": "node scripts/install.mjs --uninstall",
+    "site:build": "node scripts/build-site.mjs",
+    "site:dev": "node scripts/build-site.mjs --serve --port 4321",
+    "site:shots": "node scripts/site-shots.mjs",
+    "site:check": "node scripts/site-check.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "ssh-tunnel",
+    "manager"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shendeguize/Remote_DSH_Center.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shendeguize/Remote_DSH_Center/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/scripts/install.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * 把 dshc 装进 PATH（软链到本仓库/发布包，不复制）。
+ *
+ * 用软链而不是拷贝，是因为 launchd plist 里写的是入口的绝对路径
+ * （见 src/daemon.js buildPlist）——两份代码会立刻对不上。软链意味着
+ * `git pull` 即升级，不需要重装。
+ *
+ * 两种安装通道，链接指向不同：
+ *   git 仓库    → `src/cli.js`（shebang 找系统 node）
+ *   发布包      → `<包根>/bin/dshc` 启动器（exec 随包自带的 node）
+ * 发布包必须指启动器而不是 `app/src/cli.js`：装的人可能压根没装 node，
+ * 直接跑 cli.js 会找不到解释器。通道判据与 `dshc update` 共用一份
+ * （`src/updater.js` 的 resolveInstall），不在这里另写一遍。
+ *
+ * 用法：
+ *   node scripts/install.mjs                     # 装到 ~/.local/bin（不存在会建）
+ *   node scripts/install.mjs --prefix /usr/local/bin
+ *   node scripts/install.mjs --service           # 顺带 dshc service install（launchd 自启）
+ *   node scripts/install.mjs --uninstall         # 只摘链接，不动 ~/.dsh_center 的配置
+ *   node scripts/install.mjs --no-next-steps     # 收尾提示交给上游（install.sh 用）
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { isMainEntry } from '../src/lib/entry.js';
+import { resolveInstall } from '../src/updater.js';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_PREFIX = path.join(os.homedir(), '.local', 'bin');
+
+/**
+ * 该把 dshc 软链到哪个文件。
+ * @returns {{target:string, channel:string, viaShim:boolean}}
+ */
+export function linkTarget(repoRoot = REPO, deps = {}) {
+  const install = resolveInstall(repoRoot, deps);
+  if (install.channel === 'bundle') {
+    return { target: path.join(install.root, 'bin', 'dshc'), channel: 'bundle', viaShim: true };
+  }
+  return { target: path.join(repoRoot, 'src', 'cli.js'), channel: install.channel, viaShim: false };
+}
+
+/**
+ * 装之前先把链接位置的现状分类，避免把别人的 dshc 覆盖掉。
+ * @returns {{action:'create'|'relink'|'noop'|'conflict', current:string|null}}
+ */
+export function linkPlan(linkPath, target, { lstat = fs.lstatSync, readlink = fs.readlinkSync } = {}) {
+  let st;
+  try {
+    st = lstat(linkPath);
+  } catch {
+    return { action: 'create', current: null };
+  }
+  if (!st.isSymbolicLink()) return { action: 'conflict', current: '（不是软链，是真实文件）' };
+  const current = readlink(linkPath);
+  if (path.resolve(path.dirname(linkPath), current) === target) return { action: 'noop', current };
+  return { action: 'relink', current };
+}
+
+/** PATH 里有没有这个前缀——没有的话装了也调不到，得当场说清楚。 */
+export function prefixInPath(prefix, pathEnv = process.env.PATH ?? '') {
+  const norm = (p) => path.resolve(p.replace(/^~(?=$|\/)/, os.homedir()));
+  return pathEnv.split(path.delimiter).filter(Boolean).some((p) => norm(p) === path.resolve(prefix));
+}
+
+/** 给用户抄的那行（按当前 shell 猜 rc 文件）。 */
+export function pathHint(prefix, shell = process.env.SHELL ?? '') {
+  const rc = shell.endsWith('zsh') ? '~/.zshrc' : (shell.endsWith('bash') ? '~/.bash_profile' : '你的 shell rc');
+  return `echo 'export PATH="${prefix}:$PATH"' >> ${rc} && exec $SHELL -l`;
+}
+
+/**
+ * 下游不看了（`| head` 之类）属于哪种错。
+ *
+ * 管道被提前关掉时 Node 默认把 EPIPE 抛成未捕获异常，刷一屏栈——但那不是安装失败，
+ * 而且软链早在报错前就建好了，看到栈的人会误以为装坏了（issue #16）。
+ * 流被销毁后的后续写入报的是另外两个码，同源同因，一起吞。
+ */
+export function isBrokenPipe(err) {
+  return ['EPIPE', 'ERR_STREAM_DESTROYED', 'ERR_STREAM_WRITE_AFTER_END'].includes(err?.code);
+}
+
+/** 吞掉管道断裂，其余照抛（真正的写失败不该被藏起来）。 */
+export function silenceBrokenPipe(streams = [process.stdout, process.stderr]) {
+  for (const s of streams) {
+    s.on('error', (err) => {
+      if (!isBrokenPipe(err)) throw err;
+    });
+  }
+}
+
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd: REPO, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    child.on('error', (err) => resolve({ code: 127, stdout, stderr: String(err.message) }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+async function main() {
+  silenceBrokenPipe();
+  const argv = process.argv.slice(2);
+  const flag = (name) => argv.includes(`--${name}`);
+
+  // 不认识的旗标当用法错误。只挑认识的、其余不响，等于「按另一套意思照做」：
+  // 把 --service 拼成 --srevice 的人以为装了自启，实际什么都没装（issue #55）。
+  const KNOWN = new Set(['--prefix', '--service', '--uninstall', '--no-next-steps']);
+  const unknown = argv.filter((a, i) => a.startsWith('--') && !KNOWN.has(a)
+    // --prefix 的值不是旗标
+    && argv[i - 1] !== '--prefix');
+  if (unknown.length > 0) {
+    process.stderr.write(`不认识的参数：${unknown.join(' ')}\n可用：${[...KNOWN].join(' | ')}\n`);
+    process.exitCode = 3;
+    return;
+  }
+
+  const prefixArg = argv.indexOf('--prefix');
+  const prefix = path.resolve(prefixArg === -1 ? DEFAULT_PREFIX : argv[prefixArg + 1]);
+  const linkPath = path.join(prefix, 'dshc');
+  const { target: entry, viaShim } = linkTarget();
+
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < 22) {
+    process.stderr.write(`需要 Node ≥ 22（当前 ${process.versions.node}）：本项目直接用了内置测试运行器与 fetch。\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flag('uninstall')) {
+    const plan = linkPlan(linkPath, entry);
+    if (plan.action === 'create') {
+      process.stdout.write(`${linkPath} 本来就不存在，无事可做。\n`);
+      return;
+    }
+    if (plan.action === 'conflict') {
+      process.stderr.write(`${linkPath} 不是本仓库装的软链，没敢删。\n`);
+      process.exitCode = 1;
+      return;
+    }
+    fs.rmSync(linkPath);
+    process.stdout.write(`已摘除 ${linkPath}（配置与状态仍在 ~/.dsh_center，未动）。\n`);
+    process.stdout.write('如果之前装过 launchd 服务，用 dshc service uninstall 单独摘。\n');
+    return;
+  }
+
+  if (!fs.existsSync(entry)) {
+    process.stderr.write(`找不到入口：${entry}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  fs.chmodSync(entry, 0o755);
+  fs.mkdirSync(prefix, { recursive: true });
+
+  const plan = linkPlan(linkPath, entry);
+  if (plan.action === 'conflict') {
+    process.stderr.write(`${linkPath} 已存在且不是软链，请先自行处理再装。\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (plan.action === 'relink') {
+    process.stdout.write(`覆盖旧链接（原指向 ${plan.current}）。\n`);
+    fs.rmSync(linkPath);
+  }
+  if (plan.action !== 'noop') fs.symlinkSync(entry, linkPath);
+
+  const probe = await run(linkPath, ['--help']);
+  if (probe.code !== 0 || !probe.stdout.includes('dshc')) {
+    process.stderr.write(`装好了但跑不通：${linkPath}（退出码 ${probe.code}）${probe.stderr}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`dshc → ${entry}\n已链接到 ${linkPath}\n`);
+  if (viaShim) process.stdout.write('（发布包安装：启动器会用随包自带的 Node，与系统 node 无关）\n');
+
+  if (!prefixInPath(prefix)) {
+    process.stdout.write(`\n注意：${prefix} 不在 PATH 里，现在敲 dshc 还找不到。加一行：\n  ${pathHint(prefix)}\n`);
+  }
+
+  if (flag('service')) {
+    process.stdout.write('\n装 launchd 服务（开机自启 + 被杀拉回）…\n');
+    // plist 里的解释器路径来自跑这条命令的进程的 process.execPath（daemon.buildPlist）。
+    // 发布包安装必须经启动器跑，否则 plist 会写上系统 node——而那台机器可能根本没有。
+    const res = viaShim
+      ? await run(linkPath, ['service', 'install'])
+      : await run(process.execPath, [entry, 'service', 'install']);
+    process.stdout.write(res.stdout || res.stderr);
+    if (res.code !== 0) process.exitCode = res.code;
+    return;
+  }
+
+  // install.sh 调用时它自己会印一份更详细的收尾，这里就别再来一遍（issue #17）
+  if (flag('no-next-steps')) return;
+  process.stdout.write('\n下一步：dshc init（首次配置）→ dshc up → dshc open\n');
+  process.stdout.write('想开机自启：dshc service install（或重跑本脚本加 --service）\n');
+}
+
+if (isMainEntry(import.meta.url)) await main();