@gehennawu/dsh-service 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gehennawu
+
+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,136 @@
+# dsh-service
+
+[中文](./README.md)
+
+A service-control and operations plugin for self-hosted DSH Web. The current release provides safe restart and recovery, update notifications, deep health diagnostics, exact incremental model-usage charts, container liveness, backup management, and Linux file-permission maintenance.
+
+> This project is still in early development and is currently verified mainly with **Linux + Docker**. Docker, systemd, pm2, or another external process manager must restart DSH Web after the plugin exits the process.
+
+## Development status
+
+| Stage | Status | Scope |
+| --- | --- | --- |
+| Current `0.11.0` | ✅ Feature complete | Version links, latest/next update checks, model-tok breakdowns, backup import, the `/restart` command, and editability-based permission repair are implemented and tested |
+| v0.3 Safety and UX | ✅ Implemented | Restart guard, automatic post-restart recovery, update badge/details overlay, dynamic zh/en UI |
+| v0.4 Observability | ✅ Implemented | Health panel and status-code-only `/healthz` endpoint |
+| v0.5 Data and maintenance | ✅ Implemented | Session/config/plugin-manifest backups, backup listing/deletion, and controlled Linux permission inspection/repair |
+| v0.6 Panel and usage | ✅ Implemented | Version-first layout, deep health check, exact incremental model usage, provider/model and project filters, switchable charts, and collapsed maintenance details |
+| v0.7 Error statistics and UI | ✅ Implemented | Last-24-hour model/tool errors, path normalization, collapsed error details, card sections, and semantic button colors |
+| v0.8 Tabbed service control | ✅ Implemented | Overview, model statistics, backup maintenance, and restart tabs with functional-failure badges, a top summary alert, and high-contrast display surfaces |
+| v0.9 Native Settings style | ✅ Implemented | Overview, Health diagnostics, Model statistics, Backup maintenance, and Restart tabs with line navigation, a single content layer, and simplified statistics |
+| v0.10 Automatic status checks | ✅ Implemented | Separate DSH/plugin version states and release links; successful update checks cached for 10 minutes, failures for 1 minute; Health-tab diagnostics cached for 30 seconds |
+
+The plugin is currently developed and verified for **DSH `0.1.0-rc.7`** and is ready for use on that release. When newer DSH versions are published, this project will run corresponding compatibility tests and update the verified status.
+
+## Current features
+
+- **Host version**: displays the installed `@deepseek-ai/dsh` version.
+- **Automatic update status**: when Settings opens, checks the `latest` and `next` dist-tags for DSH and the plugin from fixed npm registry URLs, takes the semver maximum as the effective newest version, and displays both tags beside the version number. One package failure does not contaminate the other; each version number links to its corresponding GitHub Releases page. The Host caches successful/partial results for 10 minutes and complete failures for 1 minute.
+- **Safe restart**: checks active agents, background jobs, and terminals, reading Terminal services from each Agent-scoped realm with a shared-service fallback; it lists active work, requires an explicit force action, and then exits DSH Web with code `42`. Conversations can also use `/restart`; the command rechecks active work and refuses while work is running instead of bypassing the panel's two-step confirmation.
+- **Loopback RPC**: uses the single-level `/dsh-service` channel with `version`, `check-update`, and `web` endpoints, available only to loopback callers.
+- **Automatic recovery**: shows a global `shell.overlay` after restart, probes for a new process instance with backoff, reloads automatically, and offers manual reload after 60 seconds.
+- **Bilingual UI**: the Settings page, active-work warning, and recovery overlay switch dynamically with DSH's Chinese/English locale preference.
+- **Update badge**: silently checks for DSH updates when the Settings page mounts; shows a sidebar-footer badge when a newer version exists, and opens a global overlay with current/latest versions. Registry failures stay silent.
+- **Health panel and deep diagnostics**: shows uptime, memory RSS, live/persisted sessions, active agents, and background jobs, with lightweight metrics refreshed every 5 seconds. The first entry into Health diagnostics automatically runs the full check; returning within 30 seconds reuses the result, while a later entry refreshes it. “Run again” remains available for forced rechecking. Full diagnostics use a dedicated solid display region, check rows stay expanded, and file-permission inspection/deep scan/repair live in the same tab. Results translate internal counts into readable explanations rather than exposing formats such as `0:0`.
+- **Exact model-usage charts**: stores exact aggregates in UTC-hour buckets and lets the RPC regroup them into the browser's local calendar day, so “Today” does not incorrectly show zero after local midnight when the Host runs in UTC. It reports successful model steps, input tok, output tok, cache tok, and cache hit rate. The UI can switch between all projects and individual workspaces and displays models as `provider/model`. The first build reads historical sessions sequentially; later refreshes fold only new events using each session revision and `lastSeq`. The index stores no messages, prompts, or tool content.
+- **Resume and fork semantics**: reopening an old conversation keeps the same session ID, so newly produced tok are appended to their actual day without double counting. Forks skip the inherited prefix below `seedLength`; subagent usage is included in its actual project by default.
+- **Model error statistics**: extracts provider failures from `llm/retry` and final failed turns, groups them by `provider/model + code + HTTP status`, and retains only the rolling last 24 hours in descending count order. Cancellations, max-token endings, and tool errors are excluded. Details are collapsed by default, follow the project filter, and are grouped in Overview.
+- **Tool error statistics**: counts failures from direct Tool calls and nested calls inside `run_code`, including command, read, write, edit, and search failures. Stable `error.code` values are preferred; otherwise failures are normalized into stable categories such as `FS_NOT_OBSERVED`, `OLD_STRING_NOT_FOUND`, `PATH_NOT_FOUND`, and command exit codes. Different file paths are grouped together, while the index and UI store/display only a redacted `<path>` representative. Only the last 24 hours are retained, sorted by descending count, collapsed by default, filtered by project, and shown alongside model errors in Overview.
+- **Five-tab service control**: Settings is split into Overview, Health diagnostics, Model statistics, Backup maintenance, and Restart line-style tabs. It uses a DSH-native-like underline selection and one content layer instead of nested background cards. Surfaces, text, borders, tabs, and state colors use DSH's native light/dark theme variables. Ordinary actions use a neutral fill, primary actions such as creating a backup use the brand fill, and repair/delete/restart actions use a white-on-danger fill. Overview contains versions, update states, existing container runtime metrics, and a titled “Error information” section for last-24-hour model/tool errors; deep diagnostics and file-permission inspection/repair live in Health diagnostics.
+- **Simplified model-statistics layout**: project selection uses compact line tabs. The main chart is a fixed seven-day stacked view of input, output, and cache tok with blue/orange/teal legend colors. The chart includes a K/M-abbreviated vertical axis, a dated horizontal baseline anchored at the bottom of the chart, and low-contrast grid lines. Hovering any colored segment highlights it and shows the date, input tok, output tok, and cache-hit tok on four separate lines. Provider/model rows use the format `x times · Cache hit x% · Input xM tok · Output xM tok`, are sorted by seven-day step count, and show only the top three by default; remaining models expand with `▸` and collapse with `▾`.
+- **Functional-failure alerts**: health/permission failures, statistics RPC failures, backup-operation failures, or restart-flow failures add `⚠` to the corresponding tab and appear in a top-level summary alert. Overview itself does not inherit health failures. Having no backups is not a failure. Model and tool error records from the last 24 hours are statistics and do not trigger tab or top alerts.
+- **External liveness probe**: `GET` / `HEAD /healthz` returns an empty HTTP 200; other methods return 405, with no DSH version, counts, or other information exposed. It is intended for Uptime Kuma on another server, Docker, Kubernetes, or another monitor to verify that DSH Web and its HTTP server remain reachable. It does nothing unless an external consumer is configured and does not replace the panel's deep diagnostics. When DSH listens only on `127.0.0.1`, expose this path through the existing Nginx/Caddy/Traefik reverse proxy rather than opening port 3080 directly.
+- **Linux file editability**: Health diagnostics checks whether the current DSH/Agent process can read, write, and enter DSH_HOME and every workspace root. Manual deep scans recursively verify the same real access instead of requiring fixed 755/644 modes, so stricter 700/600 modes do not become false positives when the Agent can still edit them. Internal `.git` metadata is not a direct Agent editing target and is skipped by both scan and repair. Nested workspaces are traversed once under the outermost root. Repair still requires two-step confirmation: it restores ownership to the current process, adds only owner `rwx` to directories and owner `rw` to ordinary files, preserves execute and group/other bits, and finally fixes `$DSH_HOME/.credentials.yaml` at 600 for the DSH startup contract. The section is hidden outside Linux.
+- **Backup management**: creates archives under `$DSH_HOME/backups/` containing sessions, configuration, and plugin profile manifests; sorts records newest-first, shows up to 10 directly, and collapses only after that. Each record has a right-aligned delete button, and the panel can import a selected `.tar.gz` file; deletion still requires two-step confirmation. Backups are unlimited and never auto-pruned, so disk usage is the user's responsibility. Credentials and `node_modules` are excluded.
+- **Lifecycle cleanup**: uses the DSH `timer` service for delayed exit and recovery probes so pending work can be disposed with the plugin Fiber.
+
+## Installation
+
+### Install from GitHub
+
+```sh
+dsh plugin --profile web add github:gehennawu/dsh-service
+```
+
+Restart DSH Web after installation or updates so both the Host and Client plugin halves are reloaded:
+
+```sh
+dsh web
+```
+
+Open DSH Web Settings and select **Service Control**.
+
+### Local development install
+
+```sh
+dsh plugin --profile web add link:/path/to/dsh-service
+```
+
+## Automatic restart configuration
+
+The plugin only sends an exit signal; it does not start the process again. Without a process manager, selecting restart stops DSH Web.
+
+### Docker Compose
+
+```yaml
+services:
+  dsh:
+    restart: unless-stopped
+```
+
+### systemd
+
+```ini
+[Service]
+ExecStart=/usr/local/bin/dsh web --host 127.0.0.1
+Restart=on-failure
+RestartSec=2
+```
+
+### pm2
+
+```sh
+pm2 start "dsh web --host 127.0.0.1" --name dsh-web
+```
+
+## Platform support
+
+| Environment | Plugin features | Automatic recovery | Verification |
+| --- | --- | --- | --- |
+| Linux + Docker Compose | Supported | Supported with a restart policy | Verified |
+| Linux + systemd / pm2 | Expected to work | Managed externally | Not separately tested |
+| macOS / Windows + pm2 or similar | Not blocked by the code | Managed externally | Not tested |
+| Direct `dsh web` execution | Supported | Not supported | Expected behavior |
+
+Requirements: Node.js `>=22`, and a DSH Web installation capable of loading both Host and Client plugin halves. Update checks require access to `registry.npmjs.org`; network failures do not affect other features.
+
+> Automated coverage plus Host and real Chromium checks on the current Linux + Docker deployment are complete. The standard preset does not mount a Terminal backend, and the container exposes no root, CAP_CHOWN, Docker socket, or user namespace; those unproducible branches are covered by scoped-service regression tests and real-subprocess temporary-directory tests.
+
+## Security design
+
+- The browser cannot supply URLs, package names, commands, or file paths.
+- Update checks only access the fixed `https://registry.npmjs.org/@deepseek-ai%2Fdsh` and `https://registry.npmjs.org/@gehennawu%2Fdsh-service` endpoints.
+- npm responses are limited to 256 KiB with a 10-second timeout.
+- The RPC channel is loopback-only and does not expose control operations to external network callers.
+- The model-usage index stores session revisions/watermarks, numeric aggregates by day/project/provider/model, and stable codes, counts, timestamps, and `<path>` representatives for redacted errors from the last 24 hours. It stores no messages, prompts, tool arguments, original file paths, passwords, private keys, or other credentials; it is fixed at `$DSH_HOME/dsh-service-usage-index.json` with mode 0600.
+- Restarting interrupts active work; the plugin lists active work first and only proceeds after an explicit **Force restart** action.
+
+## Project structure
+
+- `index.js`: Host half; version/update checks, activity guard, health metrics and diagnostics, incremental usage index, liveness, backups, and permission-maintenance RPC.
+- `client.js`: Browser half; Settings layout, switchable usage charts, update badge, and global status overlays.
+- `cordis.patch.yml`: inserts the Host and Client plugin into the DSH Web profile.
+- `README.md`: Chinese documentation.
+
+Basic checks:
+
+```sh
+npm test
+node --check index.js
+node --check client.js
+npm pack --dry-run
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,136 @@
+# dsh-service
+
+[English](./README.en.md)
+
+面向自托管 DSH Web 的服务控制与运维插件。当前版本提供安全重启与自动恢复、更新提示、健康诊断、精确增量模型用量图表、容器探活、备份管理和 Linux 文件权限维护。
+
+> 项目仍处于早期开发阶段。目前主要在 **Linux + Docker** 环境验证；重启后的自动拉起必须由 Docker、systemd、pm2 等外部进程管理器负责。
+
+## 开发进度
+
+| 阶段 | 状态 | 内容 |
+| --- | --- | --- |
+| 当前版本 `0.11.0` | ✅ 功能完成 | 版本链接、latest/next 更新检查、模型 tok 展示、备份导入、/restart 命令和权限修复交互已实现并通过自动化测试 |
+| v0.3 安全与体验 | ✅ 已实现 | 重启安全网、重启后自动恢复、更新脚标与详情浮层、zh+en 动态切换 |
+| v0.4 可观测性 | ✅ 已实现 | 健康面板、仅返回状态码的 `/healthz` 探活端点 |
+| v0.5 数据与维护 | ✅ 已实现 | 会话/配置/插件清单备份、备份列表与删除、Linux 文件权限查看与受控修复 |
+| v0.6 面板与用量 | ✅ 已实现 | 版本置顶、完整健康检查、精确增量模型统计、供应商/模型与项目筛选、可切换图表、折叠维护详情 |
+| v0.7 错误统计与界面 | ✅ 已实现 | 最近 24 小时模型/工具错误、路径归一化、默认折叠错误详情、卡片分区与语义按钮颜色 |
+| v0.8 标签式服务控制 | ✅ 已实现 | 概览、模型统计、备份维护、重启四标签；功能故障标签警告、顶部汇总提醒和高对比度展示面 |
+| v0.9 原生设置页风格 | ✅ 已实现 | 概览、健康诊断、模型统计、备份维护、重启五标签；线型导航、单层内容区和简化统计布局 |
+| v0.10 自动状态检查 | ✅ 已实现 | DSH/插件独立版本状态与发布链接；更新检查成功缓存 10 分钟、失败缓存 1 分钟；健康标签自动诊断并缓存 30 秒 |
+
+目前插件已在 **DSH `0.1.0-rc.7`** 中完成开发与验证，可以正常使用。后续 DSH 发布新版本后，本项目会同步进行兼容性测试并更新验证结果。
+
+## 当前功能
+
+- **宿主版本**：显示当前安装的 `@deepseek-ai/dsh` 版本。
+- **自动更新状态**：设置页打开时从固定 npm registry 地址独立读取 DSH 与插件的 `latest` 和 `next` dist-tag，按 semver 取两者最大值作为最新版，并在版本号旁同时展示两个标签；单项失败不会污染另一项，版本号本身链接到对应 GitHub Releases。Host 对成功/部分成功结果缓存 10 分钟，对完全失败结果缓存 1 分钟。
+- **安全重启**：重启前检测活跃 agent、后台 job 和终端；Terminal 服务按 Agent scoped realm 读取并兼容共享 fallback。发现运行中工作时展示清单并要求显式强制，随后以退出码 `42` 结束当前 DSH Web 进程。对话中也可输入 `/restart`；该命令复用活动检查，检测到运行中工作时直接拒绝，不绕过面板的两段式确认。
+- **回环 RPC**：使用单层 `/dsh-service` channel，提供 `version`、`check-update`、`web` endpoint，仅接受 loopback 调用。
+- **自动恢复**：重启后通过 `shell.overlay` 显示全局状态，退避探测新的进程实例并自动刷新；60 秒未恢复时提供手动刷新。
+- **双语界面**：设置页、活动警告和恢复浮层跟随 DSH 的中文/英文语言设置动态切换。
+- **更新脚标**：设置页打开时静默检查 DSH 更新；有新版本时在侧边栏底部显示提示，点击后通过全局浮层查看当前与最新版本。registry 不可达时不打扰用户。
+- **健康面板与完整诊断**：显示 uptime、内存 RSS、存活/持久化会话、活跃 Agent 和后台任务；轻量指标每 5 秒刷新。首次进入健康诊断标签会自动运行完整诊断，30 秒内切换回来复用结果，过期后再次进入自动刷新；保留「重新诊断」用于强制复查。完整诊断结果位于独立实底展示区，检查项始终展开；文件权限查看/深检/修复也位于此标签。结果会把内部计数转换为可读说明，例如「备份目录可用，当前暂无备份」或「发现 N 个文件或目录权限异常」。
+- **精确模型用量图表**：索引按 UTC 小时保存精确聚合，RPC 根据浏览器时区重新汇总为用户本地自然日，因此 Host 运行在 UTC 时，午夜后的「今天」也不会错误显示为 0。统计包含成功模型步骤、输入 tok、输出 tok、缓存 tok 和缓存命中率，可切换全部项目或单个工作区，并以 `provider/model` 展示供应商前缀。首次索引顺序读取历史会话，以后用会话 revision 和 `lastSeq` 只折叠新增事件；索引不保存消息、Prompt 或 Tool 内容。
+- **续聊与 Fork 口径**：恢复旧会话沿用同一 session ID，因此后续产生的 tok 会按实际日期增量补入且不会重复；Fork 会跳过 `seedLength` 以内继承的父会话历史，Subagent 默认计入其实际项目。
+- **模型报错统计**：从 `llm/retry` 与最终失败回合中提取 provider 错误，按 `provider/model + code + HTTP status` 归类，只保留滚动最近 24 小时并按次数从高到低排列；取消、最大 tok 和 Tool 错误不计入。详情默认折叠、跟随项目筛选，并集中放在概览区域。
+- **工具报错统计**：统计直接 Tool 调用和 `run_code` 内子调用产生的失败，包括命令、读取、写入、编辑与搜索错误。优先使用稳定 `error.code`，缺失时归一化为 `FS_NOT_OBSERVED`、`OLD_STRING_NOT_FOUND`、`PATH_NOT_FOUND`、命令退出码等稳定口径；不同文件路径合并计数，索引和界面只保存/展示 `<path>` 级脱敏代表信息。只保留最近 24 小时、按次数降序、默认折叠、跟随项目筛选，并与模型报错一起显示在概览区域。
+- **五标签服务控制**：设置页拆分为「概览」「健康诊断」「模型统计」「备份维护」「重启」五个线型标签，采用接近 DSH 原生设置页的下划线选中态和单层内容区，减少嵌套背景框。展示面、文字、边框、标签和状态色全部使用 DSH 原生明暗主题令牌；普通操作使用中性填充，创建备份等主要操作使用品牌色填充，修复/删除/重启使用白字危险色填充。概览包含版本、更新、容器运行指标，以及带有「报错信息」标题的最近 24 小时模型/工具报错；完整诊断及文件权限检查/修复独立放入健康诊断。
+- **简化模型统计布局**：项目切换使用线型小标签，主图固定为近 7 天输入/输出/缓存 tok 堆叠柱图，并用蓝/橙/青图例区分结构。图表带有 K/M 缩写的纵轴刻度、贴近图表底部的横轴日期基线和低对比度网格线；鼠标移入任一颜色区段时，统一显示日期、输入 tok、输出 tok 和缓存命中 tok，并按四行换行。模型明细按近 7 天步骤数降序，格式为「x次· 缓存命中 x%· 输入 xM tok· 输出 xM tok」，默认只显示前三，其他模型通过 `▸` 展开并以 `▾` 收起。
+- **功能故障提醒**：健康/权限、统计 RPC、备份操作或重启流程发生功能故障时，对应标签显示 `⚠`，并在服务控制顶部汇总受影响标签。概览本身不承载健康故障标记；没有备份不算故障；最近 24 小时的模型报错和工具报错属于统计数据，也不会触发标签或顶部提醒。
+- **外部存活探针**：`GET` / `HEAD /healthz` 返回空的 HTTP 200；其他方法返回 405，不暴露版本、计数或其他 DSH 信息。它适合供另一台服务器上的 Uptime Kuma、Docker、Kubernetes 或其他监控程序检查 DSH Web 进程和 HTTP 服务是否仍可达；未配置外部消费者时不会自行产生作用，也不替代面板中的完整健康诊断。若 DSH 仅监听 `127.0.0.1`，应通过现有 Nginx/Caddy/Traefik 反向代理暴露该路径，不建议直接开放 3080 端口。
+- **备份管理**：在 `$DSH_HOME/backups/` 创建会话、配置和插件 profile 清单归档；按日期从新到旧列出，10 条以内直接展示，超过 10 条才折叠。每条记录都有右侧删除按钮，支持选择 `.tar.gz` 文件导入；删除仍需两段式确认。备份不限份数且不会自动清理，磁盘占用由用户自行管理；归档不包含凭据或 `node_modules`。
+- **Linux 文件可编辑性**：打开面板时在健康诊断中检查当前 DSH/Agent 进程能否读取、写入并进入 DSH_HOME 与全部工作区根目录；手动深检递归验证同一实际访问能力，而不是要求固定的 755/644，因此 700/600 等只要 Agent 可编辑就不会误报。`.git` 内部元数据不属于 Agent 直接编辑目标，深检与修复均跳过。嵌套工作区只随最外层根扫描一次。修复仍需两段式确认：递归恢复当前进程属主，目录只增加 owner `rwx`，普通文件只增加 owner `rw`，不会删除执行位或放宽 group/other 权限；`$DSH_HOME/.credentials.yaml` 最后固定为 600，以满足 DSH 启动契约。非 Linux 不显示此功能。
+- **生命周期清理**：优先使用 DSH `timer` 服务延迟退出与调度恢复探测，使未完成的定时动作可随插件 Fiber 清理。
+
+## 安装
+
+### 从 GitHub 安装
+
+```sh
+dsh plugin --profile web add github:gehennawu/dsh-service
+```
+
+安装或更新后重启 DSH Web，使 Host 与 Client 两半插件重新加载：
+
+```sh
+dsh web
+```
+
+打开 DSH Web 设置页，进入 **服务控制**。
+
+### 本地开发安装
+
+```sh
+dsh plugin --profile web add link:/path/to/dsh-service
+```
+
+## 自动重启配置
+
+插件只发送退出信号，不负责重新启动进程。没有进程管理器时，点击重启会直接停止 DSH Web。
+
+### Docker Compose
+
+```yaml
+services:
+  dsh:
+    restart: unless-stopped
+```
+
+### systemd
+
+```ini
+[Service]
+ExecStart=/usr/local/bin/dsh web --host 127.0.0.1
+Restart=on-failure
+RestartSec=2
+```
+
+### pm2
+
+```sh
+pm2 start "dsh web --host 127.0.0.1" --name dsh-web
+```
+
+## 平台支持
+
+| 环境 | 插件功能 | 重启后自动拉起 | 验证状态 |
+| --- | --- | --- | --- |
+| Linux + Docker Compose | 支持 | 配置 restart policy 后支持 | 已验证 |
+| Linux + systemd / pm2 | 预期支持 | 由进程管理器负责 | 未单独验证 |
+| macOS / Windows + pm2 等 | 代码未限制 | 由进程管理器负责 | 未验证 |
+| 直接运行 `dsh web` | 支持 | 不支持 | 预期行为 |
+
+运行要求：Node.js `>=22`，且 DSH Web 能加载 Host 和 Client 两半插件。检查更新需要访问 `registry.npmjs.org`；网络失败不会影响其他功能。
+
+> 自动化测试以及当前 Linux + Docker 的 Host/真实 Chromium 验证已完成。当前 standard preset 未挂载 Terminal backend，容器也不提供 root、CAP_CHOWN、Docker socket 或 user namespace，因此这两种不可制造的环境分支通过隔离服务回归测试和真实 subprocess 临时目录测试覆盖。
+
+## 安全设计
+
+- 浏览器端不能传入 URL、包名、命令或文件路径。
+- 更新检查只访问固定的 `https://registry.npmjs.org/@deepseek-ai%2Fdsh` 与 `https://registry.npmjs.org/@gehennawu%2Fdsh-service`。
+- npm 响应限制为 256 KiB，请求超时为 10 秒。
+- RPC channel 仅注册为 loopback，不对外部网络开放控制接口。
+- 模型用量索引仅保存 session revision/watermark、按日期/项目/provider/model 聚合的数字，以及最近 24 小时脱敏错误的稳定 code、计数、时间戳和 `<path>` 代表信息；不保存消息、Prompt、Tool 参数、原始文件路径、密码、私钥或其他凭据。索引固定写入 `$DSH_HOME/dsh-service-usage-index.json` 并使用 0600 权限。
+- 重启会中断正在运行的任务；插件会先展示活动清单，只有显式确认「仍要重启」才会强制执行。
+
+## 项目结构
+
+- `index.js`：Host 半；版本/更新、活动保护、健康指标与诊断、增量用量索引、探活、备份和权限维护 RPC。
+- `client.js`：Browser 半；设置页布局、可切换用量图表、更新脚标和全局状态浮层。
+- `cordis.patch.yml`：将 Host 与 Client 插件插入 DSH Web profile。
+- `README.en.md`：英文文档。
+
+基础检查：
+
+```sh
+npm test
+node --check index.js
+node --check client.js
+npm pack --dry-run
+```
+
+## 许可证
+
+[MIT](./LICENSE)