# @zhangzhian/dsh-devtools-settings 中文文档

规范地址：https://npmcn.com/package/%40zhangzhian/dsh-devtools-settings/

版本：0\.3\.1
npm 元数据更新时间：2026-11-03T00:20:37.349Z
中文译文更新时间：2026-11-03T01:00:00.887Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40zhangzhian/dsh-devtools-settings
原文对照：https://npmcn.com/package/%40zhangzhian/dsh-devtools-settings/?lang=original
源码仓库：https://codeup.aliyun.com/67617ae720a07de19c7c1633/dsh-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：462 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ~4\.0\.4，@deepseek-ai/schemastery ~3\.18\.4，@deepseek-ai/dsh-client-locale ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-slots ^0\.2\.0-rc\.2，@deepseek-ai/dsh-typert-protocol ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-renderer ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-settings ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-primitives ^0\.2\.0-rc\.2
- 首次发布：2026-10-20T03:13:42.603Z
- 最新版本发布：2026-11-03T00:20:37.199Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

dsh-devtools 的设置外壳：设置左栏的一条「开发工具」导航项 = 控制台首页（介绍 + 版本与更新 + 功能插件卡片）+ 点卡片下钻到各插件设置页（正文由组件包注册进 devtools.settings.tab）

## 安装

```sh
npm install @zhangzhian/dsh-devtools-settings
```

也可以使用：`pnpm add @zhangzhian/dsh-devtools-settings`、`yarn add @zhangzhian/dsh-devtools-settings`、`bun add @zhangzhian/dsh-devtools-settings`

## README

[英语](https://npmcn.com/package/%40zhangzhian/dsh-devtools-settings/#readme-english) | 简体中文

# @zhangzhian / dsh-devtools-settings

`dsh-devtools` 的**设置外壳**：设置左栏里的**一条**「开发工具」导航项。点进去是一个 **控制台首页**（一句话介绍 + 版本与更新 + 功能插件卡片），点一张卡片就**下钻**到那个 插件的设置页 —— 像跳一个路由，而不是在一个常驻菜单里切页签。

它自己只有控制台这一页 —— 其余页面正文由其它组件包注册进 `devtools.settings.tab`。

## 安装

```sh
dsh plugin add @zhangzhian/dsh-devtools
```

`@zhangzhian/dsh-devtools` 是清单包，装它会带齐所有组件（包括这个）。只想装外壳：

```sh
dsh plugin add @zhangzhian/dsh-devtools-settings
```

## 提供什么

-   **设置左栏的一条「开发工具」导航项**（`settings.section`，`id: devtools`， `order: 30`），带自己的图标。
-   **控制台首页**（`devtools-home`，`order: 10`，默认打开的第一页）：标题 + 一句介绍 + 配套软件入口 + 「版本与更新」卡（当前版本 / 最新版本 / **升级** / 右上角刷新）+「功能 插件」卡片网格。卡片跟着账本**自动长**：任何包往 `devtools.settings.tab` 注册页面， 控制台就多一张卡。
-   **配套软件入口**(**上面**、介绍之后 —— 左侧“DSH远程/专属配套软件”+三个卖点,右侧浅蓝胶囊”官网下载”(悬停转实心品牌 \[r\]；整条是一个 `<a>`（[官网下载](https://dshremote.cn/download)、 `target="_blank"`、`rel="noopener noreferrer"`），`position: sticky; top: 0`：默认普通 一条，超一屏滚动时钉在顶部。
-   **下钻视图**：点一张卡切到那一页；页头是「返回控制台 + 图标 + 名字 + 一句话说明」，正文 全宽，**返回控制台**按钮和 **Esc** 都能回来。页头**吸顶** —— 正文往下滚时钉在顶部不动 【翻译】：【翻译】 页头高度写成自定义属性 `--dsh-devtools-page-bar-h`(91px `min-height` 钉住：正文里 (1)、(1)、(1)、(1)、(2)、(3)
-   **版本与更新（真能升级）**：宿主半身提供 `dshDevtoolsUpdate` 远程的； （`status` / `check` / `upgrade`）。**自动检查默认执行**（打开卡片时若从没查过 / 距上次 超过 6 小时就查一次），面板上没有开关。判据只有一条：**NPM注册表 装的更新吗**；；；； `pnpm add @zhangzhian/dsh-devtools@<版本> --config.minimum-release-age=0`（回读版本一致 才算成功，见 `src/update-service.ts` 顶部）。`link:` 安装**同样**NPM 发布版，只多一句提醒（升级会把依赖换成发布版）。所有包**锁步同版本**，所以"当前版本"读 自己那份 `package.json` 就等于读聚合包。
-   **子槽 `devtools.settings.tab`**：其它包把设置页注册进来，就会出现在控制台的卡片网格里 （`{ kind: 'list', scope: 'root' }`）。
-   **“碗碟”**：宿主半身在 `$DSH_HOME/devtools/bin/` 包装器 （`dsh-shell`)+ rc垫 `shellCandidates` —— **1 .壳 `dsh-shell`**。选了它的终端里就有 DSH；`DSH_HOME` / `DSH_PROFILE` / `DSH_PROFILE_DIR`，以及和宿主 同一套的 `dsh` / `pnpm` / `node`（路径www.缀），http://www.chinesewordword.com `dsh plugin add/remove`、升级 碗碟 `pnpm`。

**它是自家配套软件的固定入口，不是广告位。** 远程DSH 「推广」字样、没有第三方免责声明；不来自页签账本、不随插件增减变化、不参与下钻；地址写死在 `PROMO_URL`【中文译文 `promo.*` 键。

**为什么需要这个终端。** 【中文翻译 `{ DSH_SESSION_ID }`，而子进程环境是 `scrubbedParentEnv()` 的产物 —— **所有 `DSH_*` 都被剥掉**“驾驭身份。 永远不会隐式泄露”)。所以不选这一项时，在终端里敲 `dsh plugin --profile web add ...` 会去操作 `~/.dsh`/ / home/profile。中文：bash 注册表，终端这条链路没接它。

**它影响不到宿主机。** “笨笨”，“笨笨” `process.env` 不被写回，别的终端拿不到，也没有任何文件级环境（`/etc/profile`、 `~/.zshrc`）被修改。**Rc垫**shell**自己的** `~/.zshrc` / `~/.bashrc`( 前缀**强制挪回最前** -- -⚠️ `export PATH="$HOME/xxx/bin:$PATH"` 不删前缀、只把它挤到后面，`node` / `pnpm` 就变成你 自己那套了（真机上发现的）。前缀不会重复出现。

**三个已知边界。** ①包装 `bash`/`zsh`，平台的活动探测 （`prepareShellActivity`）不生效：它**不会**被"未看管 72 小时"自动清理误杀，代价只是 空闲判定不准。②包装**静默少一项**（平台把"可执行文件不存在"当跳过）， 所以 `dshShell: false` 或宿主半身没起来时不报错。③Windows包装器POSIX )。

**配置**（这一行的 `config:` 段）：`dshShell`（默认 `true`，关掉就不生成、下拉里也没了）、 `shell`（留空 = 按 `zsh` → `bash` → `sh` 探测）、`inheritShellRc`（默认 `true`；设 `false` 就是 `zsh -f -i` / `bash --noprofile --norc -i`，环境确定但没有你的补全与别名）、`env`（额外 注入的变量，保留键被丢弃）、`pathExtra`（网址：缀）。不想让下拉出现这一项， 文件 `cordis.patch.yml` 【中文译文 `terminal-controller` 行把 `shellCandidates` 盖回默认值。

**交互与无障碍。** 控制台的插件菜单是一组**按钮**（整卡可点，悬停/聚焦有反馈）；下钻页是 `role="region"` + `aria-label`。**不再是** `role="tablist"`：两屏互斥、点卡片就是"跳转"， 硬套标签页语义会念出屏幕上不存在的控件（见 `src/client/index.tsx`）。焦点跟着路由：下钻进新页面、返回回到那张卡；只挂载 **访问过**保持活力。

**导航图标是怎么换上的。** 平台的设置导航**【中文译文**1、《中国日报》 而 `settings.section` 只有 `id` / `order` / `label` —— 没有"贡献图标"的槽。所以本包**不改 平台界面**：给自己的那一行打 `data-dsh-devtools-nav`；；；；`::before` + CSS掩码 `IconApiOutlineMedium`，颜色跟导航行文字走，选中/悬停变主 色）。整段包在 `@supports` 【中文译文】平台哪天长出图标槽， 这段可以删掉。

## 要求

-   近年来 `0.2.0-rc.2` 或更新。
-   没有别的依赖。没有贡献方时控制台显示空态。
-   “近年来管理终端”需要POSIX系统(macOS / Linux)和带终端控制器的配置文件 (web对，就是这样 `terminal-controller` 一捆一捆的 `@deepseek-ai/dsh-web-app` **之后**（`dsh plugin add` 的追加顺序就是如此）。

* * *

## 英语

# @zhangzhian / dsh-devtools-settings

这个 **设置shell** 的 `dsh-devtools`： **一个** 设置中的“开发工具”条目 侧边栏。它打开一个 **控制台回家** (一行介绍，版本和更新，插件 卡);点击卡片 **训练成** 该插件的设置页面-路由，而不是 永久菜单中的选项卡。

shell只发送控制台页面——其他所有页面主体都注册到 `devtools.settings.tab` 通过组件包。

## 安装

```sh
dsh plugin add @zhangzhian/dsh-devtools
```

`@zhangzhian/dsh-devtools` 是舱单包裹；安装它会把每一个 组件，包括这个。单独安装shell：

```sh
dsh plugin add @zhangzhian/dsh-devtools-settings
```

## 它提供了什么

-   **一个“开发工具”条目** 在侧边栏(`settings.section`， `id: devtools`， `order: 30`)，有自己的图标。
-   **控制台主页** （`devtools-home`， `order: 10`，你登陆的第一页 (1)：标题+一行介绍+伴侣应用程序栏+“版本和更新”卡片 (安装/最新/ **升级** / refresh) +一个“插件”卡网格。网格 **自己生长**：任何注册到的包裹 `devtools.settings.tab` 获得一个 卡。
-   **伴侣应用吧** （63px，在控制台内）：右 **以上** 版本& “更新”卡，之后介绍“DSH远程/伴侣应用”加上三个销售 左边是点，右边是一个淡蓝色的“官方下载”药丸（固体品牌） 悬停时蓝色，键盘焦点时聚焦环)。条是1 `<a>` （[下载](https://dshremote.cn/download)， `target="_blank"`， `rel="noopener noreferrer"`)， `position: sticky; top: 0` - - - - - - 默认情况下是普通的，一旦内容滚动就固定在顶部。
-   **向下钻取视图**：点击卡片打开该页；它的标题是 “返回控制台+图标+名称+一行描述”，正文全宽。两个 这个 **返回控制台** 按钮, **Esc** 回报你。标题是 **粘性的** - - - - - - 在主体滚动时固定(滚动条是平台的设置窗格 头文件位于其中 `position: sticky` 不透明背景的包装器)。它的 高度公布为 `--dsh-devtools-page-bar-h` （91px），用 `min-height`：身体有自己的粘性东西（两个远程访问标签） 并且必须知道标题结束在哪里。
-   **这个 `devtools.settings.tab` 孩子槽**：任何将页面注册到其中的包 出现在控制台的网格中(`{ kind: 'list', scope: 'root' }`）。
-   **“天线管理终端”**：主机生成一个包装器(`dsh-shell`） 再加上一个环境文件和rc垫片 `$DSH_HOME/devtools/bin/`，以及bundle补丁 将其路径附加到控制器的路径 `shellCandidates` ——所以 **下拉壳 获取另一个条目， `dsh-shell`**。这个 **一个** 终端你 选择它，因为它携带DSH运行时环境： `DSH_HOME` / `DSH_PROFILE` / `DSH_PROFILE_DIR` 同样的 `dsh` / `pnpm` / `node` 主机使用（PATH）运行 前缀)-你可以 `dsh plugin add/remove`，升级DSH或运行 `pnpm`.

**我们自己的配套应用的固定入口，而不是广告位。** DSH遥控器就是这个 插件的专用配套应用程序-没有“推广”的措辞，没有第三方 免责声明。它从不来自于标签分类账，也不参与向下挖掘； URL是硬编码的 `PROMO_URL`，副本保存在7页 `promo.*` 钥匙。

**为什么需要它。** 平台生成一个终端PTY `{ DSH_SESSION_ID }` 只有，和孩子的环境来自 `scrubbedParentEnv()` - - - - - - **每一个 `DSH_*` 变量被剥离** （“线束身份永远不会隐式泄露”）。没有这个 条目, `dsh plugin --profile web add ...` 在终端上操作 `~/.dsh`,而不是 此DSH使用的主/配置文件。模型的bash工具使用平台的可信工具 注册表;这条终端路径从未连接到它。

**不能影响主机。** 羡慕对象是该终端的每子映射 主机的 `process.env` 是永远不回写的，其他终端看不到它，没有吗 文件级环境(`/etc/profile`， `~/.zshrc`，…)被修改。这个 **rc垫片** 解决了相反的问题：一个交互式shell源 **你的** `~/.zshrc` / `~/.bashrc` 首先，然后是shim源环境文件和 **强制路径 前缀回到前面** -⚠️“只在缺少的情况下添加”是不够的：一个常见的 `export PATH="$HOME/xxx/bin:$PATH"` 不删除前缀，而是将其推回， 和 `node` / `pnpm` 这是你的，而不是主人的 机)。前缀不会出现两次。

**三条已知的边。** (1)包装器没有命名 `bash`/`zsh`，所以这个平台 活动探针(`prepareShellActivity`)不适用：它是永远不会被收获的 “72小时无人值守”的规定，只有闲置状态变得不精确。(2)包装时 是缺失的，下拉菜单会无声地丢失该条目(平台将“可执行的？ Not found”作为跳过)，所以 `dshShell: false` 或者一个失败的主机从来都不是一个错误。 (3)在Windows上不生成任何内容（包装器是POSIX sh脚本）。

**配置** (这一行的 `config:`): `dshShell` (默认 `true`;关闭=否 生成，没有下拉入口)， `shell` （空=探针） `zsh` → `bash` → `sh`)， `inheritShellRc` (默认 `true`； `false` ＝ `zsh -f -i` / `bash --noprofile --norc -i`（确定的，但没有你的完成和别名）， `env` (额外的 变量;保留键被删除)和 `pathExtra` （额外的路径前缀dirs）。保持 它从下拉菜单中，添加一个 `terminal-controller` 中具有相同id的行 概要文件的 `cordis.patch.yml` 恢复平台默认值。

-   **版本和更新（实际上是升级）**：主机半暴露a `dshDevtoolsUpdate` 远程服务(`status` / `check` / `upgrade`）。 **默认情况下运行自动检查** (打开，如果它从未检查过或最后一次检查是 6小时以上)；面板上没有开关。一个规则: **是NPM吗？ 注册表最新比安装的新？** -一个动作： `pnpm add @zhangzhian/dsh-devtools@<version> --config.minimum-release-age=0` 在简介中， 然后 **读取已安装的版本**;只有一个匹配计数（见顶部） `src/update-service.ts`）. 一个 `link:` Install遵循相同的规则并安装 NPM也发布了，但有一点需要注意(升级取代了 `link:` 依赖与 已发布的包)。这里的每个包共享一个版本，所以是它自己的 `package.json` 等于集合包。故障时，面板显示 失败的步骤的 **原始输出**.

**交互和可访问性。** 控制台的插件菜单是一组 **按钮** （整张卡片可点击，带有悬停/焦点反馈）；下钻页面 是一个 `role="region"` 与一个 `aria-label`． 它是 **不再** 一个 `role="tablist"`： 屏幕是相互排斥的，点击卡片是导航，所以是TAB 语义将宣布不在屏幕上的控件(参见 `src/client/index.tsx`）. 专注遵循这条路线：向内钻入将焦点移至 新的一页，返回时把它放回原来的卡上；只有 **参观了** 页面停留 安装(点火电极)。

**导航图标是如何到达那里的。** 平台按节对导航图标进行硬编码 Id和回落到一个齿轮为未知Id，而 `settings.section` 只接受 `id` / `order` / `label` -没有图标槽位。所以这个包永远不会接触到平台 UI：它用 `data-dsh-devtools-nav`，通过CSS和隐藏平台SVG 将它的图标绘制成 `::before` 加上一个CSS蒙版(形状从 `IconApiOutlineMedium`， 颜色骑行文本的颜色)。如果平台增长一个图标槽，这个块 可以删除。

## 要求

-   近年来 `0.2.0-rc.2` 或更新。
-   什么都没有。如果没有贡献者，控制台将显示其空状态。
-   “dsh管理终端”需要POSIX系统（macOS / Linux）和配置文件 与终端控制器（网页形状）。它修补了 `terminal-controller` 穿过bundle补丁，所以这个bundle必须出现 **后** `@deepseek-ai/dsh-web-app` ——就像 `dsh plugin add` 附加它。

## 常见问题

### @zhangzhian/dsh-devtools-settings 是什么？

dsh-devtools 的设置外壳：设置左栏的一条「开发工具」导航项 = 控制台首页（介绍 \+ 版本与更新 \+ 功能插件卡片）\+ 点卡片下钻到各插件设置页（正文由组件包注册进 devtools\.settings\.tab）

### 如何安装 @zhangzhian/dsh-devtools-settings？

在项目目录运行 npm install @zhangzhian/dsh-devtools-settings，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（~4\.0\.4）、@deepseek-ai/schemastery（~3\.18\.4）、@deepseek-ai/dsh-client-locale（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-slots（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-typert-protocol（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-renderer（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-settings（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-primitives（^0\.2\.0-rc\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @zhangzhian/dsh-devtools-settings 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @zhangzhian/dsh-devtools-settings 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @zhangzhian/dsh-devtools-settings 可以商用吗？

@zhangzhian/dsh-devtools-settings 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @zhangzhian/dsh-devtools-settings 还在维护吗？

最新版本 0\.3\.1 发布于 2026/11/03（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。