# ShellBench

**Repository Path**: newpc/shell-bench

## Basic Information

- **Project Name**: ShellBench
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ShellBench

[![star](https://gitee.com/newpc/shell-bench/badge/star.svg?theme=dark)](https://gitee.com/newpc/shell-bench/stargazers)
[![fork](https://gitee.com/newpc/shell-bench/badge/fork.svg?theme=dark)](https://gitee.com/newpc/shell-bench/members)

**AI Agent 驱动的远程服务器工作台**，Windows / Linux 桌面单机应用。

在一个窗口里管理 SSH 会话、浏览远程文件、查看服务器指标，并用一句自然语言让 AI Agent 在远端服务器上完成多步运维任务——每一步工具调用都经过审批门禁与审计。

> **Shell**（SSH 会话与终端）+ **Bench**（工作台／工位，兼有 bench work「动手实操」之意）

- 技术栈：Electron + TypeScript + React 19，主进程即引擎（无 sidecar、无本地 HTTP 监听）
- 执行目标：Agent 的每个工具都**按调用**解析目标，命令在目标机上执行——SSH 主机与**本机 / WSL 会话**都是合法目标
- 安全边界：审批门禁（审核 / 全自动）、红线阻断、工具调用级审计、凭据仅存主进程；**本机写入逐次人工批准**
- 当前版本：`0.1.11`（开发计划里的 M0–M7 里程碑全部落地，未做项见「已知限制」）

## 下载与安装

当前构建是 `0.1.11`，两个渠道：

- **内网网盘**（给同事，最新）：`egova / 工具` 目录放四份**完整产物**与一份《安装说明》（含 sha256）——网盘上是完整文件、不分卷，直接下载即可。目前最新为 **0.1.11**。
- **[Gitee Releases](https://gitee.com/newpc/shell-bench/releases)**（公开渠道）：单文件上限 100 MB，四个产物（105–141 MiB）按 95 MiB **分卷**存放——同一产物的两个 `part` 都下齐后合并，顺序不能反。公开渠道已发布的是 **v0.1.3**（0.1.4–0.1.11 尚未上传，见下方「已知限制」）。

| 平台 | 合并后的产物（`<版本>` 为 0.1.11） | 大小 | 安装 / 运行 |
|---|---|---|---|
| Windows 10/11（x64） | `ShellBench-0.1.11-setup-x64.exe` | 129 MiB | 双击安装，可改安装目录；卸载走「应用和功能」 |
| Windows 便携版 | `ShellBench-0.1.11-portable-x64.exe` | 129 MiB | 免安装，双击即用（每次启动解压到临时目录，不支持自动更新） |
| Linux（x64） | `ShellBench-0.1.11.AppImage` | 141 MiB | `chmod +x` 后直接运行 |
| Debian / Ubuntu（x64） | `shellbench_0.1.11_amd64.deb` | 105 MiB | `sudo dpkg -i`（提示缺依赖时 `sudo apt -f install`） |

```bat
:: Windows：在分卷所在目录执行（cmd），文件名按需替换
copy /b ShellBench-<版本>-setup-x64.exe.part-00 + ShellBench-<版本>-setup-x64.exe.part-01 ShellBench-<版本>-setup-x64.exe
```

```bash
# Linux / macOS
cat ShellBench-<版本>.AppImage.part-* > ShellBench-<版本>.AppImage
chmod +x ShellBench-<版本>.AppImage && ./ShellBench-<版本>.AppImage
```

合并后建议校验 sha256（四个产物的正确值写在 Release 说明里）：Windows 用 `certutil -hashfile <文件> SHA256`，Linux 用 `sha256sum <文件>`。

- **产物未做代码签名**：Windows 首次运行 SmartScreen 会提示「未知发布者」，选「更多信息 → 仍要运行」。应用内「检查更新」在出厂状态下显示「未配置更新源」，这是预期行为（发布源属部署期配置，见[打包文档](docs/packaging.md) §6）。
- **数据只落在本机**：`%APPDATA%\shellbench`（Windows）／`~/.config/shellbench`（Linux）——`data\shellbench.db` 存主机、会话、对话、Agent 运行记录与**定时任务及其运行记录**，`credentials.bin` 存加密后的凭据（经系统安全存储，只在主进程解密）。卸载不会删数据，手动删该目录即可清空。Linux 保存密码 / API Key 依赖系统钥匙串（GNOME 的 gnome-keyring、KDE 的 kwallet），没有钥匙串服务的环境（比如不带桌面的服务器）保存不了凭据，用私钥 / SSH agent 认证更省事。
- **Linux 桌面条目与停靠栏图标**：deb 安装时自带；AppImage 可另装一份桌面条目（`npm run linux:desktop -- --exe <解出来的路径>`），细节见[打包文档](docs/packaging.md) §4.1。
- 想从源码跑：见下面「快速开始」。


## 界面预览

> 截图取自**隔离实例**（临时 profile + 本机回环靶机 + 回环桩 provider），图中的主机都是示例记录（`127.0.0.1` 与本机内网地址），不含真实服务器信息。想要自己复现这套图：`node tools/readme-shots.mjs`（见 [tools/MODULE.md](tools/MODULE.md)）。

**主机管理** —— 分组、颜色标记、收藏与 known_hosts 指纹台账，每台主机的连接方式与凭据状态一屏可见（凭据本身只在主进程）。

![主机管理：列表、分组与详情](docs/images/hosts.webp)

**工作台（终端）** —— 一条真实 SSH 会话。关键字高亮把日志里的错误 / 警告 / 成功 / 状态词挑出来（默认四组规则，可改）；下面那段是 AI 的任务执行轨迹，**本地回显**带语义色（`✔ 成功` 绿 / `✘ 失败` 红 / `⏸ 等待批准` 黄 / `★ 任务结束` 青），不占用交互 shell。

![工作台：终端关键字高亮 + AI 执行轨迹](docs/images/workbench.webp)

**关键字高亮设置** —— 终端右键菜单进入：色槽、区分大小写、整词、增删规则与实时预览；保存后立刻作用于正在跑的终端。

![关键字高亮设置对话框](docs/images/keyword-highlight.webp)

**Agent 审批门禁** —— 高风险工具调用挂起等批准（图中是一条删除命令），批准 / 拒绝在**引擎层**生效；同一时刻终端轨迹里有 `⏸ AI 等待批准`。

![Agent 运行：高风险调用挂起等批准](docs/images/agent-approval.webp)

**浅色主题** —— 8 套内置主题（深色 / 浅色 / 午夜蓝 / 石墨 / 暖夜 / 高对比 / 暖纸 / 樱雾）＋一套自定义，同一屏换配色。

![浅色主题下的工作台](docs/images/workbench-light.webp)

**应用内使用说明** —— 活动栏最后一项，15 节：左目录、右正文，从连接第一台主机讲到 Agent 审批门禁、批量运维与本机文件读写；功能不熟时先看这里。

![应用内使用说明页：左侧目录、右侧正文](docs/images/guide.webp)

## 功能特性

**SSH 与终端**

- 主机管理（分组与折叠、置顶、颜色标记、导入 / 导出、描述备注）；主机类型覆盖 **SSH**（密码 / 私钥 / SSH agent / 跳板机一跳）与**本机 / WSL**（本机 PTY 或 `wsl.exe` 起会话，shell 可选平台默认 / cmd / PowerShell / pwsh / bash；WSL 用发行版自己的默认 shell）
- 会话页左栏是**服务器树**（可收起成窄条），机器行压成一行高；连接状态、延迟与流量速率都在行上
- **左栏是"一列面板"**：服务器 / 远程文件 / 命令历史 / 收藏**默认四栏同开**（最上面那块是主面板，其余按顺序堆在下面），要哪几栏点页头标题（「服务器 ▾」）在清单里勾选、不想要的单块 ✕ 关掉；**按住标题行拖动换位——把当时常用的那一块拖到最上面当主面板**（键盘用标题行左边的拖柄 `↑`/`↓`）；每块高度可拖（120–520px，上限按当下空间现算，压不没主面板）；**每一页各记一份排布**，重启后还是你摆好的样子。块间用更亮的分隔线分层、标题带识别色
- 多会话标签：新建 / 切换 / 关闭 / 重连 / `F2` 重命名；右键菜单按范围**批量关闭**（当前 / 其他 / 右侧 / 全部，一次要关 ≥2 个标签先弹确认，单项直接关）；终端基于 `@xterm/xterm`（搜索 `Ctrl+Shift+F`、resize、缓存重放）
- 终端关键字高亮：默认四组规则（错误 / 警告 / 成功 / 状态），色槽、区分大小写、整词与规则都可改，保存后**正在跑的终端立刻生效**
- **双击一个词 = 直接进系统剪贴板**（命名 / IP / 整条路径 / URL 按词边界一次取全，右下角轻提示写出复制内容）；右键菜单给复制 / 粘贴 / 全选 / 查找 / 清屏
- host key 校验三策略（`accept-new` 落盘 / `strict` 命中 / 拒绝篡改指纹），known_hosts 读写与 OpenSSH 指纹逐字节一致

**工作台**

- 远程文件：左栏目录树 + 主区**终端 / 详细列表 / 编辑器**三选一；上传 / 下载（分片续传）——**文件可以直接从系统文件管理器拖进来**（落在当前目录，拖到目录行上就进那个文件夹；文件夹暂不支持上传，会当场说明），队列里每条都写着**已传 / 总大小（百分比）+ 速率 + 预估剩余时长**；**整目录递归下载**（右键目录，进度进传输队列）、CodeMirror 6 编辑器改后回写；**打开的文件按会话隔离**（同一台机器开多个终端，编辑面互不串，也不占终端区域）
- **文件区键盘操作**：点过列表就有落点——`↑↓` 换行、直接打字定位、`Enter` 打开，树与表格同一套；路径可手输（`~` 按远端家目录展开）
- **目录内搜索**（两档）：默认**只筛当前目录**已列出的条目（本地即时收窄，不打搅远端）；要翻子目录就在「系统设置 → 连接与数据 → 文件搜索」切到**递归搜索子目录**，回车发起远程搜索，命中行标出它所在的子目录，条数 / 深度到上限会如实说明
- **文件区 ⇄ 终端双向跳转**：右键目录「在终端中打开」；终端里 `cd` 之后用「定位到终端目录」跳回；**每台主机各记一份当前目录**（关软件重开也在，切标签回原处；最多记 50 台）
- **关掉再打开还是离开时的样子**：窗口大小 / 位置 / 是否最大化、启动落在哪一页（活动栏主菜单）、每台主机上次所在的远端目录都会记；上次的位置在当前显示器上放不下时回默认居中，不会把窗口甩到屏幕外
- **详细列表**：大小 / 权限 / 修改时间，可按名称或时间排序；长文件名截断显示、不撑歪列宽（列宽随界面字号联动）
- 服务器指标：CPU / 内存 / 磁盘 / 负载 / 网络等一屏概览，跨平台（Linux / Windows）解析；状态行给**实时速率**，悬浮看本会话与逐网口明细
- 命令历史、运行日志（内存环形缓冲 + 日志文件）、主机导入导出（可选带凭据，加密）

**AI 能力**

- 模型配置：OpenAI 兼容 / Anthropic 两类 provider；密钥经 Electron safeStorage 加密，渲染层只拿得到「是否已配置」
- **模型请求超时可调**（30–900 秒，默认 180）：服务端在这段时间内没有任何响应就中断本次请求，**两套内核（Pi / 自研）共用这一个值**；失败卡片写明实际等了多久——「服务端在 3 分 5 秒内没有任何响应（请求超时，不是主机或命令的问题）」，避免把模型服务卡住误认成机器或命令出错
- 流式对话：思考内容分离展示、Markdown 渲染（含 GFM 表格）、对话持久化到 SQLite、随时取消
- 命令预测（ghost text）：按终端尾部上下文与最近历史给出候选，`Tab` 采纳、`Esc` 取消；可关闭思考提速

**Agent 任务执行**

- 在**会话右栏**发起与观察（输入区钉在栏底，执行完接着写下一条），不开新视图就能盯住任务
- 活动栏另有独立的「**AI 对话**」页：左边是库里的**对话台账**（可新建 / 重命名 / 删除，每条写着它挂着哪些目标），右边是**对话内容**摊开成轮次，适合离开终端专心跟 Agent 聊；页头会**自动用一句话起好标题**（也可以自己改，改过的不被覆盖）
- **不强制先选目标**（2026-10-06）：可以直接说一件事，Agent 先**零连接**列出配置里的主机与已授权目录（`list_hosts`），自己决定分析哪几台，连哪台就按需连哪台（不需要你先开终端）；点名了不存在的机器会**明确失败**而不是换一台
- **对话是库里的实体**（迁移 v13）：一条对话 = 一串连续任务，左栏可新建 / 重命名 / 删除，对话头显示它当前挂着哪些执行目标（主机 / 本机目录），上下文按**对话**接续
- **三类主机都是执行目标**（2026-10-13 起）：SSH 主机、**本机 / WSL 会话**都能当目标；打在本机会话上的命令由引擎在**独立本地进程**里跑——不占用你正在用的终端，取消 / 超时会终止整棵进程树；WSL 会话只有命令通道（文件能力不给，文件在发行版里）
- **运行可导出**：任一轮次都能导出 Markdown / HTML（右栏标题栏常驻入口，长任务输出贴底滚动也点得到）
- **输入框可以直接贴图**（2026-10-16）：右栏任务描述、收尾后的「继续执行」、放大编辑框三处都能 `Ctrl+V` 贴截图（右键菜单也有「粘贴图片」），缩略图排在输入框上方、**点开放大看整张**（`Esc` / 点图片外面 / ✕ 三种关法）、单张可单独撤掉；一次最多 4 张、单张 5 MB（PNG / JPEG / WebP / GIF）。**图片只随当次任务发给模型**：库里只记元数据（几张 / 多大 / 什么格式），接续上文与导出记录里换成一行「附图 N 张…」，下一轮不再重传
- **本机文件**：`local_list_dir` / `local_read_file` / `local_write_file` 让 Agent 读、改你**显式授权**的本地文件夹（分析项目、改配置）；授权分只读 / 可写两档，**每次写入都要你点批准**（与审核 / 全自动模式无关）、写前自动备份、审批栏给出行级 diff
- **10 个工具**：5 个命令 / 文件工具（`exec` / `list_dir` / `read_file` / `write_file` / `search_files`，目标可以是 SSH 主机，也可以是本机 / WSL 会话）+ `list_hosts`（零连接清单）+ 3 个本机文件工具 + `propose_schedule`（定时任务的**起草**——只写草稿卡，建不建由你点），全部经 JSON Schema 校验与风险分级；每一步的卡片上标明这次调用打到了哪台主机 / 哪个目录
- 审批门禁：**审核模式**下高风险调用挂起等批准（超时 300s 按拒绝收口）；**全自动模式**按策略放行并单独记审计；红线命令（如 `rm -rf /`）任何模式都不执行
- **运行中还能说话、也能随时停**（2026-10-20）：运行中栏底常驻「停止」；补充消息按 `Enter` **排队**（当前这轮忙完就发）、按 `Ctrl+Enter` / `Cmd+Enter` **立即插入**（在下一个模型调用前发），排队中的消息列在输入区上方，可单条删除或提为「立即插入」；发送被拒时草稿原样留着
- 审计：提议 / 批准 / 开始 / 完成 / 失败 / 超时 / **已中断（用户停止）** / **用户补充输入** / 阻断 / 跳过等 14 类阶段落 SQLite，可按运行回读
- 执行轨迹**本地回显**进目标会话的终端（看得见一步步执行；不发往远端、不占用交互 shell，可关）
- 两条可选内核：默认 **Pi 内核**（`pi-coding-agent` 的循环编排，2026-10-05 起为默认），可切**自研 tool loop**；两条内核共用同一套工具契约、门禁与审计实现
- **运行中可停止**：点「取消任务」立刻不再等待在飞的远端命令（已收到的输出保留，那一步记「已中断」而不是失败）；随后在栏底补一句说明就能接续同一段对话继续执行——觉得思路不对不必等它跑完
- 任务可继续执行（同一会话接续上文，结论按 Markdown 渲染），运行中可实时切换审核 / 全自动

**批量运维**

- 主机列表**多选**（分组三态勾选）→ 底部「批量运维（N 台）」：一句任务发给一批主机（一批最多 20 台）
- **两阶段执行**：每台先**只读侦察**出方案（引擎强制，改不动系统）→ 人看过、可排除 / 重新侦察后**批准** → 有界并发（1–5）执行
- 批次审批策略（**逐台确认 / 整批确认 / 只读自动**）与失败处理（失败继续 / 失败即停）都在引擎层生效；红线命令任何策略都不执行
- 全过程可暂停 / 停止 / 排除 / 重试；一台算不算失败由「模型自述 + 机械事实」共同判定（运行结束 ≠ 做成了）
- 引擎汇总（逐台计数与摘录）与方案 / 报告两种 Markdown 导出；批次落库（迁移 v10），历史可回看

**常用任务**

- 任务模板清单（标题 + 任务内容），可新建 / 置顶 / 编辑 / 删除 / 拖动排序；存在本机数据库（迁移 v12），不绑主机也不执行命令
- Agent 右栏两处输入区与批量任务卡上「常用任务」一键填入**任务内容**（填入后仍走原有链路：Agent 侧过审批门禁、批量侧先侦察再批准）
- **AI 生成**：填一段说明（下载地址、补丁说明…）+ 选一台服务器 → Agent 在**那台机器上真跑一遍**（就是普通运行，审批 / 审计 / 终端轨迹 / 取消一个不少）→ **跑的过程就在这个框里**（与会话右栏同一套步骤卡片：展开看命令全文与执行结果、高风险命令就地批准）→ 把结论整理成任务草稿（解析不出结构化块时降级并在界面上提醒）→ 你改完确认才保存进清单，之后换别的服务器或选进批量运维继续用

**定时任务**

- 活动栏「**定时任务**」= 到点自己干活：左＝任务清单（开关 / 计划 / 下次运行 / 风险徽章）、右＝详情与最近运行记录
- **两类任务**：命令型（人写定最多 20 条命令，SSH 主机 / 本机 / WSL 会话都能当目标，逐条执行、失败即停或继续可选、单条超时 10–300 秒）与 **AI 型**（一句任务描述，**只允许 SSH 主机**，到点把任务交给 Agent 自己判断怎么做）
- **一条任务可挂多台主机**（按勾选顺序，最多 20 台）：命令型逐台执行、运行明细按主机分组；AI 型只起一条运行，把主机清单写进提示词，由模型在每次调用里指定目标
- **AI 型的三档无人值守权限**：**只读**（默认，改动类调用直接拒绝）/ **除红线外**（改动可以执行，红线仍拦）/ **全自动**（连红线命令也放行，建任务时必须再勾一次风险确认）；三档都不会挂起等批准，也都**不写本机文件**
- **计划四档**：一次 / 每隔 N 分钟 / 每天 N 个时刻 / 每周 N 个时刻 + 星期几；**不做 cron**，时刻是本地时间、分钟精度，对话框里改计划当场预览「下次运行」
- **无人值守的硬约束**：定时触发的 AI 运行里，`readonly` / `no-redline` 档需要批准的调用由引擎**直接拒绝**（不是挂起等人批），也不写终端轨迹；**红线命令保存期与运行期各判一次**（唯一例外是任务显式选了「全自动」，且审计里留 `approved` 出处）
- **AI 只能起草**：在「AI 对话」页说需求（只读侦察后给出草稿卡）或在新建对话框点「用 AI 起草」——两条走同一份草稿结构与校验，卡上「审核并创建」把草稿回填进表单，**建不建永远由你点**；AI 起草的命令型任务含中 / 高风险命令时，保存前必须逐条勾选核对
- 运行记录落库（迁移 v16）：状态 / 触发方式（到点 / 手动 / 补跑）/ 逐条命令输出与退出码（多主机时带主机）/ 跳过原因；同一个计划时刻只落一条（进程重启、tick 抖动、手动撞车都不会跑两遍）
- **应用不运行就不跑**：调度在主进程里（20 秒一跳），关掉应用即停，没有常驻服务、也不开任何本地端口；错过的班次靠**补跑**交代（默认开、窗口 1 小时可调到 24 小时，超出窗口记一条「跳过」写明原因）

**其它**

- 主题 **8 套内置 + 1 套自定义 + 跟随系统**（标题栏与左栏底部各有一颗按钮打开同一个快捷弹层；跟随系统的两侧选择与自定义调色在「系统设置 → 外观」）、全局快捷键（`Ctrl+/` 帮助浮层）、中英双语
- **应用内「使用说明」页**（活动栏最后一项）：16 节讲清每件功能在哪儿做、会发生什么、边界在哪——左侧目录点哪节看哪节，正文跟随界面语言
- **系统设置页**（左分组 + 右内容，改完即时生效、没有保存按钮）：五组内容见下节[「系统设置」](#系统设置)
- **破坏性操作有应用内确认框**（删除主机 / 清空历史 / 覆盖远端文件…）：`Esc`、点确认框外面、点「取消」都是取消；危险操作的默认焦点在「取消」，直接回车**不会**误删
- **字号可调**：界面字号四档（紧凑 / 标准 / 舒适 / 大）、终端 10–20px（改完正开着的终端立刻按新字号重排并通知远端）、文件与编辑器字号（跟随界面 / 跟随终端 / 单独指定）
- 内置 **16 项环境自检**：无界面 `--selfcheck` 与界面「全部运行」两种入口，输出 JSON 报告与退出码
- 自动更新框架（未配置发布源时零网络动作）

## 系统设置

活动栏「系统设置」是**左分组 + 右内容**的配置页：改完**即时生效、没有保存按钮**；左栏每行行尾的小圆点一直显示这一组的状态（模型配好没有、有新版可更新时会亮），切到别的组也看得见。五组各管一块：

| 分组 | 里面有什么 |
|---|---|
| **外观** | 主题（深 / 浅 / 跟随系统）、语言（中文 / English）、**字号**（界面四档 / 终端 10–20px / 文件与编辑器三选一，带「恢复默认」）、**终端关键字高亮**（总开关 + 四组规则可增删改，保存后正在跑的终端立刻生效） |
| **AI 与模型** | 模型配置（OpenAI 兼容 / Anthropic、密钥、模型名、上下文窗口、**模型请求超时** 30–900 秒默认 180、思考开关）+ 右栏**现场验证**：一段纯对话当场试答 + Agent 运行历史与审计回读——"填了一堆字段到底通不通"在这里立刻能看出来 |
| **Agent 与安全** | **运行参数**（新任务默认接续上文、执行轨迹写进终端、**执行预算**：最多轮数 / 工具调用数 / 自动继续段数 / 预算用尽自动继续、**单条输入上限**）、**可用性测试**（在你当前会话上跑一个只读任务，走与正式任务相同的启动 / 审批 / 审计链路）、**工具集**（已加载的 10 个工具）、**本机目录授权**（只读 / 可读写两档）、**红线**（永不执行清单）。审批门禁、红线阻断与审计在引擎层，这一页改不动它们 |
| **连接与数据** | SSH 靶机（自检用）、**数据位置**（数据库 / 凭据 / 日志 / 备份落在哪，只读）、主机与分组入口、**文件搜索档位**（只筛当前目录 / 递归搜索子目录）。前三块只指路、不重复放编辑器；文件搜索是这一组里唯一的控件 |
| **关于与更新** | 版本与运行环境、检查更新（更新源属部署期配置，这里只读展示）、快捷键帮助入口、**技术自检**（16 项） |

常用快捷键（完整清单在标题栏 `?` 或 `Ctrl+/` 打开的应用内帮助里，与代码里的注册表一一对应）：

| 按键 | 作用 |
|---|---|
| `Ctrl+T` | 快速连接 / 新建会话：选中主机直接连，只有一台主机时直接连 |
| `Ctrl+/` | 打开 / 关闭快捷键帮助 |
| `Ctrl+Shift+F` | 终端内查找；`F3` / `Shift+F3` 跳到下一个 / 上一个匹配 |
| `Esc` | 关闭对话框、取消命令预测候选（查找条打开时先关查找条） |
| `F2` | 重命名当前会话标签 |
| `Shift+Enter` | 对话输入框内换行（`Enter` 发送） |
| `Ctrl+Enter` | Agent 任务描述框直接发送（`Enter` 只换行） |
| `Tab` | 终端里采纳命令预测候选（写入不含回车） |

`Ctrl` 在 macOS 上显示为 `⌘`（只影响帮助浮层里的写法，行为一致）。

## 快速开始

上一节是给**使用者**的；这一节是**从源码运行 / 打包**（开发视角）。

环境要求：**Windows 10/11 或 Ubuntu 24.04**、**Node.js ≥ 22**；完整打包需要 `node_modules/electron/dist`（离线打包方式见[打包文档](docs/packaging.md)）。

```bash
npm install

npm run dev            # 开发模式启动界面
npm run gate           # 提交前门禁：类型检查 + 单测 + 文件体量检查
npm run selfcheck      # 16 项环境自检（无界面，打印报告与退出码）
```

本地 SSH 靶机（仅环回、仅公钥、不随产品分发，用于自检与冒烟）：

```bash
npm run sshd:setup     # 首次：下载便携 OpenSSH 并生成本机 host key / 测试密钥
npm run sshd           # 启动靶机 127.0.0.1:2222
npm run sshd:verify    # 校验靶机可用
```

常用命令：

| 命令 | 用途 |
|---|---|
| `npm run dev` | 开发模式（Electron + Vite HMR） |
| `npm run build` | 构建到 `out/` |
| `npm run gate` | typecheck（node + web）+ vitest + 文件体量门禁 |
| `npm run pack` | 目录产物 `release/win-unpacked/` |
| `npm run dist` | 安装包 + 便携版（`release/`） |
| `npm run selfcheck` | 在开发构建上跑 16 项自检 |
| `node tools/selfcheck-run.mjs [exe]` | 隔离跑自检：克隆非秘密配置到临时目录，不碰正在运行的实例 |
| `npm run smoke:gui:m4` | Agent 黑盒冒烟（CDP 驱动真实界面点击，自带回环桩 provider） |
| `node tools/agent-live.mjs --all` | 真实模型 + 真实 SSH 的分阶段联调（需先配好模型与主机） |

打包与验收（推荐用一键脚本，内含离线打包参数）：

```powershell
powershell -ExecutionPolicy Bypass -File build.ps1               # 构建 + 目录产物 + 产物摘要
powershell -ExecutionPolicy Bypass -File build.ps1 -Target dist  # 安装包 + 便携版
release\win-unpacked\ShellBench.exe --selfcheck                  # 打包后自检
```

注意顺序：NSIS / portable 阶段会重写 `win-unpacked`，冒烟与自检要跑在**安装包构建之后**的最终产物上。

## 技术栈

| 层次 | 选型 |
|---|---|
| 桌面壳 | Electron（主进程即引擎） |
| 语言 | TypeScript（单一语言贯穿主进程 / 渲染进程 / 共享契约） |
| 前端 | React 19 + Vite |
| 终端 | `@xterm/xterm` + `addon-fit` + `addon-search` |
| 编辑器 | CodeMirror 6 |
| SSH / SFTP | `ssh2`（纯 JS，无原生模块） |
| 本地 PTY | `node-pty` |
| 存储 | `node:sqlite`（Electron 内置 Node 24，免原生模块） |
| 凭据 | Electron `safeStorage` |
| 打包 | `electron-builder` |

## 目录结构

```
src/
  main/              主进程
    domain/          业务域：hosts / session / terminal / files / metrics / history / ai / chat / agent / selfcheck
    infra/           SSH、SFTP、SQLite、日志、设置、AI provider、安全工具
    transport/       IPC 注册（preload 契约的实现端）
  preload/           contextBridge 暴露面（渲染进程唯一入口）
  renderer/          React 界面（components / hooks / i18n / lib / styles）
  shared/            两端共享的契约（工具表、审计阶段、自检清单、IPC 频道名…）
tools/               开发与验收工具：自检运行器、CDP 黑盒冒烟、真机抽测、长稳、桩 provider
docs/                验证记录、开发计划、模块索引、用户指南、打包文档
```

各目录的职责、接口与验证方式见[模块索引](docs/MODULE_INDEX.md)与各目录下的 `MODULE.md`。

## 安全边界（设计事实）

- **执行目标是显式的**：每个工具按调用解析目标（`host` 参数 → 运行自身会话 → 对话目标），**三类主机（SSH 主机 / 本机 / WSL 会话）都是合法目标**（2026-10-13 起）；打在本机会话上的命令由引擎在**独立本地进程**里执行——不占用用户的交互终端，取消 / 超时终止整棵进程树，与 SSH 目标的 `exec` 语义一致（同一条命令、同一套门禁与审计）。
- **本机写入逐次人工批准**：`local_write_file` 与打在本机会话上的 `write_file` 都要你点批准（与审核 / 全自动模式无关，渲染层无法代批），审批栏给出行级 diff、写前自动备份；`local_*` 三个工具只读写**用户显式授权**的目录，路径经 `realpath` 解开软链接后做包含性判定（系统目录 / 盘根 / 家目录根不许授权）。
- **审批是执行链路的一部分，不是界面装饰**：高风险调用必须经门禁（用户批准 / 策略放行），渲染层无法自行放行；红线命令直接阻断，不产生执行记录。
- **两条内核共用同一实现**：`runToolInvocation` 是门禁与审计的唯一实现点，切换内核不改变安全语义。
- **凭据永不出主进程**：渲染进程只能读到「是否已配置」；日志、数据库与界面都不含明文，审计不记录凭据字段。
- **终端轨迹是展示层**：工具调用的本地回显不增加远端出流量，关掉不影响任何门禁。
- **定时触发的运行也走同一套门禁**：AI 型定时任务按任务的 `unattended` 三档执行（只读 / 除红线 / 全自动）；`readonly` / `no-redline` 下需要批准的调用由守卫**直接拒绝**（不执行也不询问），本机写入三档都拒；`readonly` 的发起处另以审核模式 + 关终端轨迹 + 不自动继续兜第二道；红线的唯一例外是显式选择「全自动」的 AI 任务。**AI 只能起草**：`propose_schedule` 只写对话里的草稿，"创建"这一步永远由人点（库条数可作为机器判据）。
- **无网络监听**：没有 HTTP 服务端、没有浏览器访问、没有登录体系（硬边界，见[开发计划](docs/development-plan.md) §1.1）。

## 已知限制

- **发行侧**：代码签名未做（产物 NotSigned）、更新发布源未配置；Windows（x64）与 Linux（x64）产物已构建，最新一版（0.1.11）发在**内网共享盘**，公开渠道 [Gitee Releases](https://gitee.com/newpc/shell-bench/releases) 目前到 `v0.1.3`（0.1.4–0.1.11 未上传）。Windows 打包产物自检 **16/16 通过**；Linux 产物在 **WSL Ubuntu 24.04 里构建**（electron-builder 不支持 deb / AppImage 跨平台构建），能正常启动并跑完自检，但该环境没有系统钥匙串，`safeStorage` 一项失败（凭据无法加密保存，依赖它的检查随之跳过）——桌面 Linux 需要 gnome-keyring / kwallet 之类的钥匙串服务。**未在独立 Linux 真机上做过完整人工验收**；macOS 未构建。
- **AI 侧**：真实模型服务下的预测可用率 / 延迟无成体系数据；**Agent 贴图这条链路只在回环桩 provider 上验过**——"图真的发出去了"由请求体（content 数组 + 图片块 + 字节指纹）证明，**没有用支持视觉的真实模型跑过**；Pi 内核把图透传给 pi，遇到不支持看图的内核 / 模型时怎么降级由 pi 自己决定；Provider 层 `tool_calls` 只验过 OpenAI 兼容路径；Pi 内核无量化对比；**「本地文件里找到线索 → 自动去连对应服务器」这种混合场景没有用真实模型跑过**（回环桩 + 单测保证链路正确，`node tools/agent-live.mjs --phase agent` 可补测）。
- **本机文件侧**：只有「列目录 / 读文件 / 写文件」，**没有删除、移动、重命名**；单文件读取上限 200 000 字符、目录列举上限 500 条、二进制文件拒绝读取（只回「是二进制」）；写入备份按文件名保留最近 3 份；授权目录上限 20 个、单条对话的执行目标上限 12 个。
- **本机会话当执行目标**（2026-10-13 起）：目标解析与「本机写入不分模式」语义有单测钉住（`execute-target.test.ts`），解释器选择 / 超时 / 取消（整棵进程树终止）有 `localexec.test.ts`，系统提示词有负向守卫保证不再宣称「本机不执行命令」——但**没有真实模型或界面黑盒的端到端记录**（回环桩也没跑过这一档）；WSL 会话只给命令通道（文件能力不给，文件在发行版里）。
- **定时任务侧**：**应用不运行时不跑任务**（无常驻服务、不开端口，错过的班次靠补跑口径交代）；**不做 cron**、**v1 不支持对话式修改既有任务**；**AI 型定时任务没有用真实模型跑过**（链路由回环桩 provider 与单测保证"能走通"，"模型面对守卫的拒绝会不会反复重试"只在桩侧验过）；活动栏的「任务在跑」角标未做。
- **其它**：SSH agent 认证未端到端验证、跳板机只支持一跳；**停止运行会立刻不再等待在飞的远端命令**（已收到的输出保留、按「已中断」记账），但远端进程是否随之终止不是 SSH 协议保证——本机 Win32-OpenSSH 靶机实测通道关闭后 `ping` 仍在跑；需要确定性终止的远端操作请自带超时或事后核对（证据见 [M4 验证记录](docs/M4-verification.md)，复现命令 `node tools/agent-interrupt-verify.mjs`）。

逐条的验证证据、限制与复现命令见下表各里程碑验证记录。

## 文档索引

| 文档 | 内容 |
|---|---|
| [开发计划](docs/development-plan.md) | 目标、范围、里程碑与门禁、关键决策与风险 |
| [模块索引](docs/MODULE_INDEX.md) | 全部模块的职责、代码入口与文档入口 |
| [用户指南](docs/user-guide.md) | 面向使用者的操作说明（安装、主机、会话、AI、Agent、批量运维、常用任务、定时任务） |
| [打包文档](docs/packaging.md) | 打包流程、离线打包、产物与版本、数据与升级 |
| [i18n](docs/i18n.md) | 命名空间划分与迁移约定 |
| 验证记录 | [M0](docs/M0-verification.md) 骨架与可行性 ／ [M1](docs/M1-verification.md) SSH 闭环 ／ [M2](docs/M2-verification.md) 工作台 ／ [M3](docs/M3-verification.md) AI 能力 ／ [M4](docs/M4-verification.md) Agent 任务执行 ／ [M5](docs/M5-verification.md) 打磨与发布 ／ [M6](docs/M6-verification.md) 批量运维 ／ [M7](docs/M7-verification.md) 自主目标与本地文件 ／ [M8](docs/M8-verification.md) 定时任务 |
| [AGENTS.md](AGENTS.md) | 项目规则、边界与验证命令（给协作者与 AI 助手） |

## 许可

本项目以 **MIT** 发布（全文见 [LICENSE](LICENSE)，`package.json` 的 `license` 字段同为 `MIT`）。

MIT 是使用最广的宽松许可：可以自由使用、修改、商用、再发布，唯一的义务是**保留版权与许可声明**；软件按"原样"提供，不含任何担保。

随产物分发的第三方组件（Electron、node-pty、ssh2、xterm.js 等）不适用上述声明，各自仍归原作者所有、遵循其原有许可（依赖树里没有 GPL / AGPL 这类 copyleft），声明随依赖与产物一并保留。