# @12-apps/desktop-shell 中文文档

规范地址：https://npmcn.com/package/%4012-apps/desktop-shell/

版本：1\.3\.0
npm 元数据更新时间：2026-11-03T21:06:33.098Z
中文译文更新时间：2026-11-05T20:02:33.756Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/desktop-shell
原文对照：https://npmcn.com/package/%4012-apps/desktop-shell/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

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

- 包体积（解压后）：161 kB，34 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：zod \>=4\.0\.0，electron \>=30\.0\.0，@aws-sdk/client-s3 \>=3\.700\.0
- 首次发布：2026-09-22T16:58:34.443Z
- 最新版本发布：2026-11-03T21:06:32.697Z
- 近 30 天下载量：32284（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

桌面 AGENT 的可重复使用的一半: 背景 Electron app, 指向主机自己的网页签名( 无第二个认证路径) , 从托盘上继续工作, 每个窗口都关闭, 并且从 Windows 、 macOS 和 Linu 的机器开始

## 安装

```sh
npm install @12-apps/desktop-shell
```

也可以使用：`pnpm add @12-apps/desktop-shell`、`yarn add @12-apps/desktop-shell`、`bun add @12-apps/desktop-shell`

## README

# @ 12- apps/ desktop- shell

背景桌面的可重用部分 **代理人**: 标志的电动app 与主机本身的网络登录页面相对应, 继续与每个窗口合作 关闭,然后从Windows,macOS和Linux上的机器开始.

```bash
pnpm add @12-apps/desktop-shell electron
```

## 问题解决

有些工作不能通过标签完成,列表短而固执:

-   到达商店本身网络上的设备(打印机、比例尺、抽屉);
-   无对话框打印;
-   关闭浏览器时继续运行;
-   机器开始.

需要这些产品中的任何一种 都会产生一个小的桌面伴奏。 那个 伴侣每次约90%相同——签入,签入,持入 连接,做工作,活下来, 说它是如何走在一个托盘图标——和 剩下的10%是应用程序的全部点。 这个包裹是90%.

## 塑造一切的规则:没有第二条路可签

桌面应用程序不能收集密码 。 产品一出现就 **两个** 认证路径:网络一——费率限制,关闭,电子邮件 校验、 OAuth 按钮、 密码重置、 每种语言的复制 在本地窗口中的文本字段没有这些字段,永远不会保留 与第一个水平.

所以,壳打开 **主机自己的登录页面** 在窗口和监视器中 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}会话饼干降落 网上添加的提供者可供 同一日的代理,而且本套件中根本没有证书处理: `grep -ri password src/` 任何回报都不是无常.

```
   tray icon ─┐
              ├─ sign-in window ──▶ the host's /sign-in page ──▶ cookie
   the work ──┘                                                   │
        ▲                                                         │
        └──────────── net.fetch bound to the same partition ◀──────┘
```

## 表面

| 导出 | 这是什么 |
| --- | --- |
| `@12-apps/desktop-shell` | 托盘绘制的状态( E)`deriveShellStatus`以及保持背景工作的主管。 纯一. |
| `…/autostart` | 横跨三个平台的"从机器开始"——一个在macOS/Windows上的登录项目,一个XDG `.desktop` 在 Linux 上的文件. |
| `…/session` | 饼干手表, 本地签注 `guardSession` 401移动了托盘 403没有. |
| `…/telemetry` | 崩溃报告显示崩溃的寿命超过:会话标记,面包屑,磁盘队列,和丢失运行 / 崩溃/ 安装失败检测. 纯一. |
| `…/updates` | 自相残杀 `electron-updater`数字 : `createUpdateManager`, (中文(简体) ), `createAutoInstall`, (中文(简体) ), `updateBanner`, (中文(简体) ), `createMenuGate`,并带有“帮助”下更新器的菜单栏(`buildAppMenu`, (中文(简体) ), `updateText`. 纯. |
| `…/electron` | 适配器:单实例,托盘,窗口-隐藏-永远不关闭,背景开始, `startDesktopShell`, (中文(简体) ), `startCrashReporting`, (中文(简体) ), `updaterFileLogger`, (中文(简体) ), `sessionCookieReader`, (中文(简体) ), `installAppMenu` 财务报告和审定财务报表 `wireUpdates` (更新器通过一个安装路径加入了菜单,窗口条,面包屑和自动安装). |
| `…/server` | 网络主机半: `serveDesktopAsset` 编号 : `serveNamedDesktopAsset` (磁盘先是,然后通过主机的存储端口进行预先签名的重定向;通道) `.yml` 流; 编码为 404 否则), `platformFor`,以及崩溃报告摄入量—— `desktopReportSchema` (zod,可选的同级), `describeDesktopReport`, (中文(简体) ), `createReportBudget`。仅节点. |
| 选项 `desktop-shell-upload-release` | 将放出的文件放入S3相容的桶中, 任何CI 跑者都配有节点—— 不 `aws` 二进制. |

除了所有东西 `…/electron` 财务报告和审定财务报表 `…/server` 无框架,在平地节点测试中运行—— 自动启动引用和地位排名如何在 没有显示的机器.

## 两个事实,一个字

一个会话和一个活链接分别失败并单独恢复. 一个特工 他们被粉碎了,不能告诉别人要修理,所以他们 被分开跟踪 `deriveShellStatus` 就是他们变成一个词的地方.

排名为 **接下来怎么办**,不严重:失踪 会话排序超过一个已丢弃的链接( 链接是结果) 和本地错误 排序高于链接(链接自行恢复;故障不恢复).

`degraded` 不是一个错误。 意思是现场连线断了 主持人的 倒计时的民意调查正在推动这项工作——速度较慢,没有中断。 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}一个讨厌的主持人 有人过来 `degraded` 让他们为重新连接而烦恼.

## 崩溃、更新和发布

一个托盘程序失败了,没有人在寻找, 每一个修复它会 否则,一个电话。 所以,包裹 也携带三件事 使一种剂能够从远处维护:

-   **遥测.** `startCrashReporting()` 开始时写一个会话标记 在一个干净的退出上删除它。 留下的标记只报告为坠机 当 Crashpad 写了一个垃圾箱在运行中—— Windows 关闭也留下一个, 没有垃圾。 重新启动以重新安装 报告为 `install-failed` 但只有两件 在要求重启几分钟后:在Windows上,旧的二进制可以来 在安装器关闭并启动新设备之前, 返回几秒钟 版本,然后按计划读取重新启动,不报告 (FUT-3309) (中文(简体) ). 报表队列 磁盘和 `flush(send)` 通过东道主拥有的路线运送; a 不更改的 4xx 被丢弃, 而不是屏蔽队列 .
-   **最新进展.** `createUpdateManager` 每天检查一次,每次主机检查一次 询问, 在背景中下载, 绝不允许跳过检查覆盖 一个版本已经下载或准备就绪。 宿主传出 `autoUpdater` (本软件包不依赖于 `electron-updater`) 和答案 (中文(简体) ) `settings()` 使用开关和种子 URL 检查 - `null` 设置时 未完成 。 一个有闸门的种子得到会话作为 `Cookie` 页眉通过 `sessionCookieReader`. macOS报告 `unsupported`: S. 麦克拒绝 下载后未签名更新 .
-   **释出.** `desktop-shell-upload-release <key-prefix> <file>...` 上传 与 `@aws-sdk/client-s3` 作为缓冲器,对象是 字节换字节文件大小 。 报告并跳过缺少的文件;否 配置的桶是带有注释的 0 出口 .

## 它没有文字

没有一句话,在任何语言。 托盘菜单、工具提示、窗口标题和 启动列表条目全部是副本,副本是主机的——所以 `TrayCopy` 是一个 所需包装和 `ShellState.fault` 是一个 **代码**没有留言 读者 这里有一个店主, 而字是大部分的产品.

## 收 养

见 [采用.md](https://npmcn.com/package/%4012-apps/desktop-shell/ADOPTING.md)。 。 。 .

## 常见问题

### @12-apps/desktop-shell 是什么？

桌面 AGENT 的可重复使用的一半: 背景 Electron app, 指向主机自己的网页签名\( 无第二个认证路径\) , 从托盘上继续工作, 每个窗口都关闭, 并且从 Windows 、 macOS 和 Linu 的机器开始

### 如何安装 @12-apps/desktop-shell？

在项目目录运行 npm install @12-apps/desktop-shell，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 desktop-shell-upload-release，可以用 npx desktop-shell-upload-release 直接运行。

### @12-apps/desktop-shell 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/12-apps\_\_desktop-shell 是否存在。

### @12-apps/desktop-shell 支持 ESM 还是 CommonJS？

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

### @12-apps/desktop-shell 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @12-apps/desktop-shell 可以商用吗？

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

### @12-apps/desktop-shell 的下载量有多少？

根据 npm 官方下载统计，@12-apps/desktop-shell 在 2026/10/04 – 2026/11/02 这 30 天内被下载 32,284 次，日均约 1,076 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @12-apps/desktop-shell 还在维护吗？

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