终端工作台 Nexus-Aethra/Nexus-Terminal

English · 简体中文

dshell — 终端优先的 AI 工作台

一个会话就是一条终端时间线：你在真正的 shell 里敲命令，AI 在同一个屏幕上接着干活。
AI 的每一轮工作、你敲的每一条命令，按发生的先后排成一列，没有聊天气泡。

dshell 主界面

界面截图是中文的。dshell 跟随 dsh 自身的语言设置（设置 → 通用设置 → 语言），切到 English 后同一套界面也是英文。

dshell 是 dsh（DeepSeek Harness）的一组插件。它不修改 dsh 的源码，全部通过 dsh 公开的扩展点接入，所以 dsh 随时可以跟着上游升级。

目录

- 它是怎么拼起来的
- 它是什么
- 相比 0.1.14 有什么新
- 快速开始
- 界面速览
- 两种模式：$ shell 与 ✦ agent
- AI 有自己的终端
- 全屏程序
- 输入辅助：Tab、↑、→
- 多会话协作：管道与缓冲区
- SSH 设备会话
- 用量
- 设置
- 状态卡
- 手势速查
- 三个例子
- 边界与注意
- 面向开发者的文档

它是怎么拼起来的

dshell 是两层：你看着的那层界面，和真正干活的宿主。你看到的永远只是别的东西的视图——所以同一列里能同时放下你的 shell 输出和 AI 的每一轮工作；所以一个会话可以指着另一台机器，而窗口还在你眼前。

flowchart TB
subgraph WIN["界面 —— 浏览器，或桌面版"]
UI["一列：你的 shell 输出与 AI 的每一轮输入行、两侧栏"]
end
subgraph HOST["宿主 —— 一个 Node 进程"]
CORE["dsh 自己的核心会话、agent、工具注册表"]
subgraph ROWS["dshell 的插件行 —— 十一个包"]
VIEW["mode + terminal-bridge界面，以及它背后的 PTY"]
PANE["files + ssh文件面板，以及会话跑在哪"]
LINK["buffer管道，以及它们之间的缓冲区"]
end
ROOT["数据根dshell 自己那些文件的落脚处"]
end
subgraph WORLD["活儿干在哪"]
HERE["这台机器一个真的 shell，一棵真的目录树"]
THERE["一台设备一个真的 shell，一棵真的目录树"]
end
UI <-->|"一条 websocket"| CORE
CORE ---|"接在 dsh 的扩展点上"| ROWS
VIEW -->|"你的 shell，你的文件"| HERE
VIEW -->|"同一个会话，只是换了个地方"| THERE
PANE --> HERE
PANE --> THERE
LINK -.->|"按名字，跨会话传文件"| HERE LINK -.-> THERE VIEW --- ROOT PANE --- ROOT

从上到下三条带：

- 界面是浏览器或者桌面版。它画出一列——你的 shell 输出和 AI 的每一轮，按发生的先后排着；你敲的东西也从这里发出去。它自己不留状态：屏幕上的一切都来自宿主，一条 websocket 就够。
- 宿主是 dsh 自己的 Node 进程。dshell 只往里加插件行，一行 dsh 的源码都不改，所以 dsh 随时能跟上游升级。这些插件行就是本页底部列出的那十一个包；数据根（$DSH_HOME/dshell）是它们自己那些文件的落脚处。
- 活儿干在哪是一个世界：这台机器，或者一台设备。会话的命令、文件和看得见的终端都在同一个世界里跑——设备那一行是同一个会话指到了别处，不是多了一个会话。

有意思的东西都在接缝上，每条接缝下面各有一节：两个 PTY（AI 有自己的终端）、文件面板与设备路由（SSH 设备会话）、管道与缓冲区（多会话协作）。

它是什么

| 你会得到 | 说明 |
| 一个全幅终端 | 每个会话一个主 shell，直接跑真正的命令，全屏、有颜色、有光标 |
| 一条合并时间线 | shell 的输出和 AI 的工作按时间穿插；AI 的每一轮是一个可折叠的「任务块」 |
| 两个模式 | $ shell 让 Enter 执行命令，✦ agent 让 Enter 交给 AI —— 输入行里的 $ / ✦ 符号就是当前模式，点它切换 |
| AI 自己的 shell | AI 有独立的 PTY，不会被你的前台程序挡住，也不会抢你的终端 |
| 跨会话协作 | 会话之间可以建立管道，互相委派任务、按名字共享文件（缓冲区），包括隔着 SSH 设备 |
| 设备会话 | 直接把一个会话开到远程机器上；命令、文件、终端都在设备上执行 |
| 本地可读的上下文 | 切到 ✦ agent 时，AI 自动带上你终端里最近几条命令及输出，不用你复述 |

相比 0.1.14 有什么新

0.1.15 这条线，是给设备会话配一块自己的面板：这台机器在跑什么、哪些容器在、谁占着端口，直接写在右侧，不用再自己开一个终端去问。npm 上是 0.1.15，需要 dsh 0.2.1-rc.3。

| | 改了什么 | 你会看到什么 |
| 右侧的设备面板 | dsh 右侧栏多了一个设备页签（dshell 自己的页签类型，不抢 dsh 内置的），开始页上多了一张卡片点开就是它 | 四页：概览 / 进程 / 容器 / 端口——先是这台机器是谁、CPU 与内存多少，然后各一张表 |
| 三张表是工具，不是流水 | 一台机器两百个进程、四十个监听端口，滚是滚不完的 | 按你知道的筛、按任意一列排（加一列当次要键）、点开一行看表里放不下的（完整命令行、属主、状态、跑了多久），点端口那一行直接跳到占用它的进程 |
| 一次往返，一个答案 | 设备是被一次 bash -c 问的，所以会话决定问哪台机器 | 宿主自己的路由说这是本机还是这台设备，这个包里没有一行代码知道 ssh 的存在 |
| 表头又真的能排序了 | 表头是用 key="cpu" 拿自己的列的，而 key 是 React 的保留 prop，在调用组件之前就被吃掉了：每个表头拿到的列都是 undefined，顺序一动不动 | 点 CPU 就重排，旁边的三角单独把这列翻过来，还不丢你刚设的次要键 |
| 概览的负载不再是破折号 | 面板读了负载那个 seat，却从不订阅它，所以负载有多新取决于别人有没有在看 | 面板开着的时候，CPU、内存、负载都是活的 |
| 列表页不再折叠 | 已经进了设备详情页，列表就是读者要看的东西 | 数量搬到了筛选框右边，筛选时写成 12 / 168 |
| 支持 dsh 0.2.1-rc.3 | dshell 声明的每个 dsh peer 版本区间都加上了它 | 插件可以装在 0.2.1-rc.3 的 dsh 上——已发布的 0.1.14 在它上面根本装不进去 |

快速开始

有两条路：把已发布的插件装进你现有的 dsh，或者从本仓库自己构建。

装进 dsh

前置：dsh 0.2.1-rc.3——桌面版，或者命令行版（npm install -g @deepseek-ai/dsh@next）；以及 PATH 上的 Node 24.21.0 与 pnpm 9.15.0（dsh plugin 是转发给 pnpm 执行的）。
npm 上 0.2.1-rc.3 是 next 标签，latest 是 0.2.0-rc.2。

装哪个 dshell 版本，取决于你手上的 dsh：

| dsh | dshell |
| 0.2.1-rc.3 | 0.1.15——npm 的 latest 标签 |
| 0.2.1-rc.2 | 0.1.14 |
| 0.2.0-rc.2、0.2.0-rc.1、0.1.7-rc.2、0.1.6-alpha.2、0.1.5-rc.2 | 0.1.13 |

dsh 会拿插件声明的每个 @deepseek-ai/dsh- peer 去校验自己的版本，只要有一个不匹配就整个
bundle 被跳过，所以 dshell 的每个发布都点名它支持的确切 dsh 版本。硬要跑某一版： dsh plugin --profile <名字> allow-version <包名@版本> --dsh-version <确切版本> --accept-risk，豁免会记在 profile 的 compatibility.json 里。

只装一个包：bundle 就是 patch 层，另外十个 dshell 包由它依赖带入， dshell-ssh 还会带上原版 profile 不带的那一个 dsh 包（@deepseek-ai/dsh-ssh，SSH 执行 provider）。
dsh plugin --profile web add -w @nexus-aethra/dshell-bundle@0.1.15

dsh web

dsh 启动后会打印一个带 token 的地址（例如 http://127.0.0.1:3080/?token=…），用浏览器打开即可。

桌面版里同样的事情有一个窗口入口：设置 → 插件，填 @nexus-aethra/dshell-bundle@0.1.15（它从 npmjs 安装，并精确锁定版本）。

跳过第 2 步不会致命——dsh 照样启动，只是那两行报 did not activate，其余功能都在。之所以列出来，是因为 SSH 设备会话与 AI 的终端工具都要从 profile 里解析这两个包名。

bundle 里带着全部 dshell 包和它自己的 cordis.patch.yml，所以包装好的那一刻 dsh 就把它组装进去了：不用改 profile、不用写配置文件。dsh plugin --profile web list 能看到最终的层叠结果。

从这份检出构建

前置：同样的 Node 与 pnpm，外加一份 dsh/ 上游检出（放在本仓库旁即可，.gitignore 已忽略它）。

1) dsh 上游（一次性）
cd dsh
pnpm install --no-frozen-lockfile
pnpm run build:lib && pnpm run build:web

2) dshell 插件
cd ..
pnpm install
pnpm --filter "@nexus-aethra/dshell-" run build

3) 装进 dsh 的 web profile（一次性；重复执行是安全的） ./scripts/install-into-dsh-profile.sh ./scripts/bootstrap-profile-client.sh

4) 每次启动
cd dsh && pnpm dsh web

两种装法都可以这样验收：curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/ 应当返回 401（那是 dsh 的 cookie 鉴权门，不是错误）。

细节和排错（版本为何这样钉、profile 是怎么被填充的、客户端 bundle 的加载约定）都在 docs/dshell-setup.md。

界面速览

主视图：左侧是会话列表，中间是终端时间线，右上角是状态卡，底部是输入行。

| 区域 | 你能做什么 |
| 左侧边栏 | 新建会话、在会话间切换；归档 收起到「已归档」分组；多选 后可批量 恢复 / 删除；删除的会话先进入「待删除 · 重启后清除」 |
| 「终端」区栏 | 工作区列表下方独立一节：节头最左侧的链接图标开合「跨会话管道」面板（由 dshell-buffer 提供，折叠时它也在，因为这是面板唯一的入口），+ 新建终端会话；每行末尾的胶囊写明它跑在哪（本机 或设备名）；双击标题、或行内 ⋯，可 重命名 / 归档；节头还带搜索与「显示/隐藏已归档」 |
| 右侧文件浏览器 | 「文件」页签列出会话工作目录，可前进后退；双击目录把它设为根；把目录拖到终端上就等于在这个终端里 cd 过去；设备会话还有「打开文件传输」 |
| 状态卡 | 常驻右上角，折叠成一行；展开可见 AI 终端、子智能体、后台任务、缓冲区传输、委派回信等 |
| 输入行 | $ / ✦ 符号就是当前模式（点它切换，悬停写明是哪一个）；? 悬停时写明当前可用的手势 |

时间线：shell 的输出占一段（一个真正的小终端，可横向滚动），AI 的一轮占一个任务块。
任务块的头部一行告诉你它现在在干什么、干了多久、花了多少 token；点一下可折叠成两行摘要。

任务块

两种模式：$ shell 与 ✦ agent

输入行左侧的 $ / ✦ 符号就是当前模式 —— 点它切换，悬停它会写明是哪一个。同一个切换也是输入框里的斜杠命令：

| 输入 | 效果 |
| /shell <命令> | 切到 shell 模式并把命令立刻执行（/terminal 是它的别名） |
| /agent <话> | 切到 agent 模式并把这句话发给 AI |
| /fullscreen | 把整块画面交给终端上的那个程序（读数漏掉时的手动入口） |
| /new | 新建会话，沿用当前会话的工作目录 |

在 $ shell 模式下：

- Enter 执行这一行（进入主 shell 的前台进程）
- Ctrl+C 放弃这一行并向终端发中断
- Ctrl+Shift+V 把剪贴板内容交给终端
- 以 / 开头的内容仍然走 dsh 的命令通道（/compact 等原样保留）

在 ✦ agent 模式下 Enter 就是「发消息」，和普通对话一样。切到 agent 模式时，dshell 会自动附带你终端里最近三条命令及输出（每条最多 2 KiB，超长可让 AI 用工具按需翻页），所以你不必解释「我刚才跑的那条为什么失败了」。

flowchart TB
IN["输入行 —— 一次按键，两种模式"] --> S["$ shellEnter 在这个会话的 shell 里执行这一行Ctrl+C 放弃这一行"]
IN --> A["✦ agentEnter 把这一行发给 AI顺带带上你最近三条命令"]
S -->|"点那个符号，或 /agent"| A
A -->|"点那个符号，或 /shell"| S

AI 有自己的终端

每个会话里有两个 shell：

- 你的主 shell —— 你敲，你看见，全幅渲染。
- AI 的 shell —— 第一次需要时才启动，启动目录跟着你的 shell 走。

两者互不抢前台。AI 不能往你的终端里打字，只能读（dshell_terminal_read）；你想看它在自己那个 shell 里干了什么，展开状态卡的 AI 终端 行，那里是一条只读的实时画面，可随时 为 AI 开启一个终端。

如果 dsh 的 bash 工具在同一个会话里另开了一个持久 shell，dshell 会把它认领成 AI 的终端，让模型的 bash 调用、terminal_send 和你看到的这块画面收敛到同一个 PTY 上 —— 不会出现「面板里一个 shell、模型命令跑在另一个 shell」的错位。

flowchart LR
YOU["你的主 shell前台，全幅渲染"] -.->|"AI 只能读它(dshell_terminal_read)"| AI["AI 自己的 PTY第一次需要时才启动"]
AI -->|"它自己的命令"| OUT["它自己的输出在状态卡里"]

全屏程序

吃掉整块屏幕的程序 —— vim、htop、less，以及 minimax-code 这类编码 TUI —— 拿到的是画面本身，而不是时间线。输入框让位，终端铺满整列，每一个按键都直接交给程序：方向键、Tab、Escape、各种 Ctrl 组合，以及它自己开启的鼠标上报。这是输入框唯一不是「输入行」的情形，因为一个自己读键盘的程序没法跟一个读整行的编辑器共用键盘。

dshell 自己判断这件事，依据是对该会话终端的两个读数：一个正在绘制屏幕的前台程序（隐藏光标、开启同步刷新、打开鼠标上报），或者 vim 这类程序切换过去的备用屏幕。两者满足其一即可。长命令不算全屏程序 —— npm install、sleep 30 都照旧留在时间线上。

flowchart TB
T["时间线"] -->|"程序拿走整块画面(vim、htop、less、TUI)"| F["程序自己的屏幕每一个按键都直接交给它"]
F -->|"它退出，或点「退出全屏」"| T
F -.->|"它的重绘被刻意挡在时间线之外"| L["会话的原始日志"]

| 怎么退出 | 程序画面右上角小条上的 退出全屏 按钮 —— 或者直接退出程序，时间线会自己回来 |
| 手动进入 | 输入 /fullscreen，用于读数漏掉的程序 |
| 全屏期间 | 会话记录不再渲染，程序的输出也被刻意挡在时间线之外：它的重绘会在时间线上堆成一片画到一半的屏幕。字节仍在会话的原始日志里，所以重连能重放这块画面 |
| 设备会话 | 那里只读备用屏幕（本地进程是 ssh），其余情况用 /fullscreen 进入 |

输入辅助：Tab、↑、→

三个手势都在 $ shell 模式的输入行里生效，每个都可以单独关掉。

flowchart TB
W["光标下那个词"] --> P{"这一行说这个词是什么"}
P -->|"命令位（sudo 之后、; 之后同样算）"| C["命令名来自会话自己的 PATH"]
P -->|"cd 之后"| D["目录"]
P -->|"其余位置"| F["路径"]
C --> R["唯一候选直接落地多个候选弹出浮层"]
D --> R
F --> R

| 手势 | 行为 |
| Tab | 按这一行说这个词是什么来补全：命令位补命令名（dock + Tab，sudo dock + Tab、pwd; host + Tab 同样），cd 之后只补目录，其余位置补路径（重定向的目标也算），以及本会话自己的 shell 才知道的子命令与选项（docker r + Tab 给出 rename/rm/run，apt list -- + Tab 给出长选项）。名字来自会话自己的世界——本地会话是本机 PATH，SSH 会话是设备上的，所以两边给出的名字并不相同。大小写不折叠地比较，但补出来的是真实拼写：cd nexus-sh + Tab 会补成 Nexus-shell/，顺手把这一行改对。唯一候选直接落地，多个候选弹出浮层（Tab/↑/↓ 切换、Enter 填入、Esc 关闭） |
| ↑ | 打开本会话历史（↑↓ 选择、Enter 填入），只列与当前草稿同前缀的命令 |
| → | 光标后显示虚影提示：最近一条与草稿完全同前缀的命令，按 → 逐词采纳，采完即消失 |

输入行里的 ? 会按当前状态给出同一份图例 —— 虚影显示时是 → 采纳一个词 · 继续，列表打开时是 Tab 下一个 · ↑↓ 选择 · Enter 填入 · Esc 关闭 —— 并写明当前模式。悬停（或用键盘聚焦）即可看到。
把某个开关关掉后，那个键就回到浏览器默认行为（Tab 移动焦点、→ 移动光标）。

多会话协作：管道与缓冲区

这是 dshell 与其他终端工作台区别最大的部分：会话不是孤岛。

两个会话之间可以拉一条管道，然后各自的 AI 就能互相委派任务、共享文件。链路可以跨机器 ——其中一端完全可以是绑在 SSH 设备上的会话。

flowchart LR
A["会话 A · 本机你在的窗口"] -->|"管道「部署」"| B["会话 B · 构建机SSH 设备会话"]
A -->|"管道「评审」"| C["会话 C · 另一个本机目录"]
B -->|"结果回信"| A
C -->|"结果回信"| A

建立管道（只有你能建）

点 终端 区栏标题最左侧的链接图标（折叠时也在，它是面板唯一的入口）。面板有两个视图：

- 列表 —— + 建立管道，选两个会话，填名称（例如「构建机」）和用途（一句话说明这条管道传什么、为什么），然后 建立管道。
- 图 —— 会话是节点，管道是连线。从节点边缘的圆点拖到另一个节点就建好了；点连线可看详情或 解除。

管道连接的是终端会话（侧边栏 终端 区栏里列的那些）。普通对话会话既不会被列为端点，宿主也会拒绝：文件面板、设备路由和区栏都依赖「终端会话」这个身份，非终端会话本来也承接不了请求。

「用途」是给对方读的：它出现在对端每次组装提示词时那条管道旁边，对端的模型据此判断一个请求是否该走这里。两端都能写 —— 你在面板里写，agent 用 dshell_buffer action="describe" 写；是对方写的时候面板会标出来（由 … 填写）。

面板上写着 只有你能建立管道；agent 没有建连的工具 —— 建连始终是你的动作，AI 只能使用已存在的管道。

管道图

一次委派的全过程

委派是异步的：被委派方在忙也没关系，请求会排队；发起方不会阻塞等待，它可以结束本轮，对方回报后自动被唤醒继续。

sequenceDiagram
participant U as 你 participant A as 会话 A（本机） participant B as 会话 B（构建机） U->>A: 把这个目录部署到构建机上 A->>A: 确认管道在线 A->>B: delegate 委派 · 附带授权「src 只读」 Note over A: 本轮结束状态卡显示 ⏸ 等待 B 回信 B->>B: 领取工单，在自己的机器上读 /src/…
B->>B: 执行构建
B-->>A: finish 回报结果
Note over A: 【管道回报】送达A 自动醒来继续
A-->>U: 汇报结果

被委派方只看得到你发给它的内容：它不知道你的其他文件、其他会话。工单有期限，超时会被看门狗判为 已超时，发起方会收到通知，可以重新委派或自己继续。

flowchart LR
Q["排队中"] --> P["处理中"] --> D["已完成"]
P --> F["已失败"]
P --> T["已超时"]
Q --> X["已取消"]

缓冲区：把文件按名字交给对方

委派时可以把自己世界里的文件或目录开放给对面，每份授权带一个名字和读/写权限。
这个名字就变成对方的缓冲区路径，缓冲区是一棵以 / 为根的树，一个会话一棵：

flowchart LR
subgraph W["会话 A 的真实磁盘"]
D1["/srv/app/README.md"]
D2["/srv/app/releases/"]
end
subgraph B["会话 B 看到的缓冲区 /"]
P1["/readme"]
P2["/app/releases/v0.4.2.tar"]
end
D1 -->|"授权 as=readme 只读"| P1
D2 -->|"授权 as=app 读写"| P2

拿到授权的一方用五个动作在缓冲区里干活：

| 动作 | 作用 |
| ls | 不带路径时列出自己拿到的所有映射区（名字、权限、来自谁）；带路径则列目录 |
| read | 读一个文件的文本，可按行翻页 |
| edit | 在原位改授权方世界里的那个文件（不产生副本） |
| download | 把缓冲区里的文件搬到自己的世界（可指定落点） |
| upload | 把自己世界的文件推进缓冲区 |

两条规则值得记住：

- 映射就是合同：路径只能落在被授权的名字之下，绝对路径、..、软链接逃逸都会被拒绝。
AI 不需要知道你机器上的真实路径，也改不了别的地方。
- 持有授权的一方动手：要给别人文件，就开只读授权、让对方 download；要收文件，就由对方开写权限、由你 upload。

授权按引用计数回收：工单结算时自动撤销，计数归零就失效 —— 不需要谁记得去清理。

大文件

download / upload 超过 32 MiB 时自动切换成分块中继：按 16 MiB 切片、逐块搬运，落地后按整个文件的 sha256 校验，校验不过就算失败并保留中间数据（默认上限 1 GiB，硬上限 4 GiB）。
进度实时出现在状态卡的 ⇅ 缓冲区传输 行里，带百分比和进度条，面板关着也照常显示。

面板里能看到什么

点开一条管道，就是它的详情页：

管道详情与缓冲区浏览器

- 缓冲区 —— 一棵可以走的树，和右侧文件浏览器同一套操作手感（面包屑、刷新、悬停高亮）；每一行都写着它来自谁、什么权限。
- 进行中的请求 / 已结束 —— 每张工单的状态、方向、主题和回报全文。
- 生效中的授权 —— 当前活着的授权，以及每份授权映射了哪个真实路径。

上图这份详情是任务结算之后的样子：授权已经自动回收，所以缓冲区又是空的 —— 这是设计如此。

SSH 设备会话

在 新会话 对话框里把 运行位置 切到 SSH 设备，选设备、填远端目录，创建时 dshell 会用一次真实的 ssh 往返先验证连通性，验证不过不会把会话建出来。

设备本身在插件面板上登记：侧边栏 插件 → @nexus-aethra/dshell-bundle → dshell-ssh 那一行的 配置（名称、host、端口、用户名、远端工作目录；登录方式可选 密钥（OpenSSH 私钥）或 密码，两者都存在保险箱的分组里）。

- 连接用内置的 SSH 客户端（ssh2），只带这台设备自己的钥匙——不依赖宿主 ssh 程序、不读 ~/.ssh/config、不走 ssh agent；
- 密码直接交给这个客户端，不出现在命令行里；
- 密钥与密码写在 $DSH_HOME/dshell/ssh/keys/，权限 0600；
- 主机密钥记到 dshell 自己的 known_hosts，不动你个人的那份。测试 成功时会显示 已连接 user@host（系统）· N ms 和 主机密钥 SHA256:…（首次信任，请与服务器管理员核对 | 已信任）。

暂不支持：硬件密钥（sk- / FIDO / PKCS#11）、~/.ssh/config 里的 ProxyJump / ProxyCommand 等指令、以及 agent 转发。跳板机后面的设备，需要把跳板机本身作为设备登记。

绑定设备后，这个会话的命令、文件和终端都在设备上：

flowchart LR
subgraph L["本机"]
S["会话的终端界面"]
M["挂载替身目录mnt/设备/远端目录"]
end
subgraph R["远端设备"]
T["真正的 shell（你的可见终端）"]
F["真实的文件树"]
end
S <-->|"ws /dshell/pty"| T
M -.->|"镜像视图"| F

你终端里看到的提示符是设备自己的提示符 —— 这个会话是 root@VM-0-6-ubuntu，它的命令就在那里跑：

设备会话的终端

侧边栏里这类会话带一个 SSH 徽章。设备会话的右侧文件浏览器会多出 打开文件传输：左右两栏分别是 本机 和 设备，把文件或文件夹从一侧拖到另一侧即开始复制，逐项显示进度、分块、跳过计数，遇到同名会问你 覆盖 还是 移除。（单文件上限 32 MB，单次计划上限 20 000 项 / 2 GiB。）

那个 文件 页签列的是设备上的目录树，不是本机的 —— 面包屑写的是设备自己的路径：

设备会话的文件浏览器：设备的 /root

用量

设置 → 用量 把模型花掉的钱画出来，数据来自 dshell 自己数据目录里的一个索引：

用量页

- 每日热力 —— 固定 26 周日历，从上到下、从左到右填充，所以最近一天永远在右下角。它读的是 全部时间：时间范围只挪动下面的图，不动日历。
- 合计 / 未缓存输入 / 输出 / 缓存读 / 调用 / 缓存命中率 —— 当前窗口的总账。缓存命中率最值得看：缓存读占全部输入的比例。
- 每日消耗（按模型） 与 模型占比 —— 窗口内每条模型一条线、以及各自占比。
- 按模型明细 —— 每个模型的输入、输出、缓存读、缓存写、调用次数与合计。

索引是增量的：dsh 把 provider 上报的用量挂在每条 assistant/message 上，扫描只读「日志变长了的」会话。打开页面时扫一次，也可以点 重新聚合。读不了的会话会被记为跳过，页面会明说合计是残缺的以及原因，而不是悄悄少算。

设置

dshell 的设置都在 dsh 的插件面板上，挂在各自所属的那一行：侧边栏 插件 → 选 @nexus-aethra/dshell-bundle → 用对应行上的 配置。

| 行 | 内容 |
| dshell-mode | 终端配色 —— 午夜（默认）、柔和、神秘、森林，选择立即生效；输入辅助 —— Tab 补全、历史列表、智能提示、子命令与选项 四个开关；数据目录 —— dshell 自己文件的存放位置，下次启动时迁移 |
| dshell-ssh | 设备清单，每行可 测试 / 编辑 / 删除 |

用量（上面那页）是设置里独立的一栏，和 通用设置、模型 并列 —— 它是报表，不是插件配置。

设置保存在主机上，同一主机的所有浏览器共用（关掉某个辅助键，换台浏览器也一样）。

状态卡

常驻右上角，平时折叠成一行，点开才展开细节。它只在有内容时才显示对应行：

| 行 | 出现时机 |
| 计划 | AI 列了待办，显示完成度与当前阶段 |
| AI 终端 | AI 的 shell 开起来了，展开是只读实时画面 |
| 智能体 | 派生了子智能体，可点进某一个 |
| 后台任务 | 有长任务在跑 |
| 缓冲区传输 | 有文件在跨世界搬运，带进度条 |
| 中断点 | 你这一轮把活交给了别人、正在等回信（⏸ 等待 <对方> 回信），可 撤回 |
| 管道任务 | 别的会话派活给你，列出了待处理工单 |
| 连接 | 与主机的 ws 断了，可 重新连接 |
Windows 上集成终端跑不起来：它需要一台 POSIX shell，宿主上没有。所以终端视图会直接说明这件事，并给出出路 —— 绑一台设备，终端就跑在那台机器上。已绑定设备的会话不受影响，而且在 Windows 上不需要装任何东西：连接用的是 dshell 自己的 SSH 客户端，不是操作系统的。

点开状态卡时，最上面是这个会话跑在哪台机器：CPU 与内存各带一条进度条，条上画满绿→黄→橙→红的整条渐变，再按占用裁出已填充那段，所以条边缘的颜色就是这个负载该有的颜色。下面是核数、负载和内存的确切数值。绑到设备的会话报的是那台设备的数并标出设备名，设备不可达时直接说不可达，不会拿本机的数顶上。会话接过第一次输入之前不显示——在那之前设备还是你说了算。

设备会话的状态卡：设备自己的 CPU 与内存

多久读一次由你定，在设置 → 插件 → dshell → 资源读数：2 秒 / 5 秒 / 10 秒 / 30 秒 / 1 分钟。本机上一次轮询只是一次文件读取；绑到设备时每一次都是一趟 ssh。

手势速查

| 位置 | 操作 | 效果 |
| 输入行 | 点 $ / ✦（或 /shell、/agent） | 切换模式 |
| 输入行 | 悬停 ? | 当前状态下的按键图例 |
| 输入行 | Tab | 补全：命令位补命令名、cd 后补目录、其余位置补路径（大小写不敏感比较，按真实拼写落地） |
| 输入行 | ↑ | 历史命令列表 |
| 输入行 | → | 采纳一格虚影提示 |
| 输入行 | Ctrl+C / Ctrl+Shift+V | 中断 / 粘贴到终端 |
| 输入行 | /fullscreen | 把整块画面交给一个全屏程序 |
| 终端 | 把目录拖进来 | 在这个终端里 cd 过去 |
| 时间线 | 点任务块头部 | 折叠 / 展开 |
| 时间线 | 右侧书签轨 | 跳到某一轮 AI 的工作 |
| 侧边栏 | 管道 | 打开跨会话管道面板 |
| 侧边栏 | 行上悬停 | 归档；已归档行还有 恢复 / 删除 |
| 状态卡 | 点 ▾ | 展开细节 |

三个例子

例 1：本机改代码，构建机上跑构建

1. 设置里登记构建机；新会话 → 运行位置: SSH 设备 → 选它 → 远端目录 /srv/order-gateway。
2. 在本地会话里建一条到构建机会话的管道，标签「构建机」。
3. 对本地会话说：「把这次改动部署到构建机上验证」。它会委派出去，构建机会话在自己的机器上执行，结果回信后本地会话自动醒来汇报。整个过程你的终端前台不会被占用。

例 2：两个会话互相评审（本文截图的场景）

1. 建两个会话 demo（代码）和 demo-peer（发布说明），拉一条管道，标签「评审」。
2. 在 demo 里说：「把这个任务委派给 demo-peer：我这边 README.md 映射成 readme（只读），让它读完后写一份评审意见回报。」
3. demo 确认管道在线 → delegate 发出（附带 as=readme 的只读授权）→ 本轮结束。
4. demo-peer 被唤醒，用 /readme 读到文件，写下意见，finish 回报。
5. demo 收到 【管道回报】 自动继续。你在管道详情页能看到工单、回报全文，以及结算后自动回收的授权。

这正是上面那两张截图发生的过程。

例 3：跨机器搬一个大文件

1. 两端各一个会话（本机 + 设备），中间拉一条管道。
2. 让持有文件那侧 upload，或让需要文件那侧 download，目标路径写在缓冲区里（例如 /app/releases/v0.4.2.tar）。
3. 文件超过 32 MiB 会自动分块 + sha256 校验；状态卡的 ⇅ 缓冲区传输 行显示进度，完成后两侧的临时分片都会被清掉。

边界与注意

- 重启不保留 PTY 进程，但保留回滚缓冲。 重启 dsh 会重新起一个 shell，之前的输出会从磁盘日志里恢复出来（$DSH_HOME/dshell-pty/，权限 0600，目录 0700）。
- 终端转录包含你键入的内容。 日志既记录输出也记录输入，因此在交互式提示符里输入的密码等敏感内容也会落进这份文件。它只在本机、权限是 owner-only，但请按「这里会被记下来」来使用。
- 会话的工作目录不可变。 终端可以随便 cd，但会话本身的根目录固定；换目录就 /new。
- 删除会话是两步的。 删除 之后会话进入「待删除」，日志在下次启动 dsh 时才真正清除，期间可以 取消 撤销。
- 一个会话一个浏览器连接。 同时开两个 ws 连同一个会话会被拒绝。
- 归档 ≠ 删除。 归档的会话仍在管道图里（它可能还是一条合法管道的一端），删除才会把它摘掉。
- 全屏模式只在本机读前台进程。 设备会话只能靠备用屏幕判断，所以不切备用屏幕的全屏程序在那里要用 /fullscreen 进入。这个读数也只适用于 Linux：在 macOS 或 Windows 上跑 dsh web 只有读数可用。
- 管道面板靠轮询刷新（约 3 秒一次），没有推送通道；正在传输的文件会以 1 秒的节奏刷新状态卡。

面向开发者的文档

| 文档 | 什么时候读 |
| docs/dshell-design.md | 目标、非目标与十一条设计决策（含为什么不是一个聊天窗口） |
| docs/dshell-architecture.md | 写代码前：ws 协议、Cordis 扩展点、包布局、CSS 约定 |
| docs/dshell-packages.md | 查某个功能属于哪个插件 |
| docs/dshell-roadmap.md | 阶段计划与每个阶段的验收标准 |
| docs/dshell-setup.md | 搭环境、排错、构建顺序 |
| docs/README.md | 文档索引与更新规则 |

插件共 11 个包（@nexus-aethra/dshell-），一起发布：std（契约）、storage（存储引擎）、 bundle（唯一的 patch 层）、conversation、terminal-bridge、mode、commands、 files、ssh、buffer 与 usage（用量页）。

许可

MIT，见 LICENSE。