# One package: the bundle is the patch layer, it depends on the other ten dshell
# packages, and dshell-ssh carries the one dsh package a stock profile does not
# ship (`@deepseek-ai/dsh-ssh`, its SSH execution provider).
dsh plugin --profile web add -w @nexus-aethra/dshell-bundle@0.1.13

dsh web

dsh prints a tokenized URL (for example http://127.0.0.1:3080/?token=…). Open it in a browser.

In the desktop app, the same install is available as a window: 设置 → 插件, and give it @nexus-aethra/dshell-bundle@0.1.13 (it installs from npmjs and pins the version exactly).

Skipping step 2 is not fatal — dsh boots and reports the two rows as did not activate, and the rest of dshell works. It is listed because the SSH device sessions and the agent's terminal tool both resolve those names from the profile.

The bundle carries every dshell package and its own cordis.patch.yml, so dsh composes the dshell rows the moment the package is installed: no profile edit, no config file. dsh plugin --profile web list shows the resulting layer stack.

Build from this checkout

Prerequisites: the same Node and pnpm, plus an upstream dsh/ checkout next to this repository (it is git-ignored here).

# 1) dsh upstream (once)
cd dsh
pnpm install --no-frozen-lockfile
pnpm run build:lib && pnpm run build:web

# 2) the dshell plugins
cd ..
pnpm install
pnpm --filter "@nexus-aethra/dshell-*" run build

# 3) install into dsh's web profile (once; re-running is safe)
./scripts/install-into-dsh-profile.sh
./scripts/bootstrap-profile-client.sh

# 4) every time
cd dsh && pnpm dsh web

Check either install with curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/ — it should answer 401, which is dsh's cookie auth gate, not a failure.

The details and the troubleshooting (why the versions are pinned, how the profile gets filled in, the module-loader contract for client bundles) live in docs/dshell-setup.md.

A tour of the screen

The left sidebar holds your sessions, the middle is the terminal timeline, the status card floats in the top right, and the input line sits at the bottom.

The timeline is the point: a stretch of shell output occupies one region (a real mini terminal that scrolls horizontally), and one AI turn occupies one task block. The block's header line says what it is doing, for how long, and what it has spent; clicking it folds the block into a two-line summary.

Two modes: $ shell and ✦ agent

The $ / ✦ glyph at the left of the input line is the mode — click it to flip, hover it to read which one it is. The same switch is a slash command typed right in the input box:

In $ shell mode:

• Enter runs the line, into the foreground process of the main shell
• Ctrl+C abandons the line and interrupts the terminal
• Ctrl+Shift+V hands the clipboard to the terminal
• Anything starting with / still goes down dsh's command channel (/compact and friends are untouched)

In ✦ agent mode Enter simply sends. Switching to agent mode also attaches your last three commands and their output (2 KiB each, with the agent able to page further on demand), so you never have to explain "that command I just ran failed".

The AI has a terminal of its own

Every session has two shells:

• Your main shell — you type, you see it, rendered full width.
• The AI's shell — spawned lazily on first need, starting in the directory your shell is in.

Neither can take the other's foreground. The AI cannot type into your terminal; it can only read it (dshell_terminal_read). To watch what it does in its own shell, expand the status card's AI 终端 row: a read-only live view, with 为 AI 开启一个终端 whenever it is not running.

If dsh's bash tool spawns a persistent shell in the same session, dshell claims it as the AI's terminal, so the model's bash calls, terminal_send, and the panel you are watching all converge on one PTY — no more "the panel shows one shell while the model ran its command in another".

Full-screen programs

A program that takes the whole screen — vim, htop, less, a coding TUI such as minimax-code — gets the surface instead of the timeline. The composer steps aside, the terminal fills the column, and every key goes straight to the program: the arrows, Tab, Escape, the control chords, and the mouse reporting it asks for. This is the one case where the composer is not the input line, because a program that reads the keyboard itself cannot share it with a line editor.

dshell decides this on its own, from two readings of the session's terminal: a foreground program that is painting the screen (hiding the cursor, opening a synchronized update, enabling mouse reporting), or the alternate screen that vim and friends switch to. Either one is enough. A long command is not a full-screen program — npm install and sleep 30 keep their timeline.

Input assists: Tab, ↑, →

All three live in the $ shell input line and each can be switched off independently.

The ? in the input line shows the same legend for the current state — → 采纳一个词 · 继续 while a ghost is showing, Tab 下一个 · ↑↓ 选择 · Enter 填入 · Esc 关闭 while a list is open — and names the mode in force. Hover it (or focus it with the keyboard) to read it. Turn an assist off and its key reverts to the browser's behaviour (Tab moves focus, → moves the caret).

Cross-session collaboration: pipes and the buffer

This is what separates dshell from other terminal workbenches: sessions are not islands.

Two sessions can be joined by a pipe, after which their AIs can delegate tasks to each other and share files. A pipe can span machines — either end may be a session bound to an SSH device.

flowchart LR
  A["Session A · this machine<br/>the window you type in"] -->|"pipe: deploy"| B["Session B · build host<br/>an SSH device session"]
  A -->|"pipe: review"| C["Session C<br/>another local directory"]
  B -->|"the result"| A
  C -->|"the result"| A

Creating a pipe (only you can)

Click the link glyph at the left of the 终端 section's header (it survives the fold, being the panel's only entry). The panel has two views:

• 列表 — + 建立管道, pick two sessions, give it a name (such as "build host") and a purpose — one line saying what travels over this pipe and why — then 建立管道.
• 图 — sessions are nodes and pipes are edges. Drag from a node's dot onto another node to create one; click an edge to see its detail or 解除.

A pipe joins terminal sessions — the ones the sidebar's 终端 section lists. A plain conversation is not offered as an endpoint, and the host refuses one: the file pane, the device routing and the section all key off the terminal identity, so a session that is not a terminal could not serve a request anyway.

The purpose is the part the other side reads: it travels in the peer's standing prompt next to that pipe, so a peer's model can tell whether an incoming request belongs there. Either end can write it — you from the panel, an agent with dshell_buffer action="describe" — and the panel says when the words are the other session's rather than yours (由 … 填写).

The panel says 只有你能建立管道；agent 没有建连的工具 — connecting is always your move; an AI can only use pipes that already exist.

What one delegation looks like

Delegation is asynchronous. A busy peer simply queues the request, and the requester does not block: its turn ends, and it is woken up again when the answer comes back.

sequenceDiagram
  participant U as You
  participant A as Session A (local)
  participant B as Session B (build host)
  U->>A: deploy this directory to the build host
  A->>A: check that the pipe is live
  A->>B: delegate the task, granting read on "src"
  Note over A: this turn ends<br/>status card shows ⏸ waiting for B
  B->>B: claim the ticket, read /src/… in its own world
  B->>B: run the build
  B-->>A: finish, report the result
  Note over A: [pipe report] arrives<br/>A wakes up and continues
  A-->>U: reports back to you

The peer sees only what you send it: not your other files, not your other sessions. Tickets have a deadline; a watchdog settles an unanswered one as 已超时 and tells the requester, who can delegate again or carry on alone.

flowchart LR
  Q["queued"] --> P["in progress"] --> D["done"]
  P --> F["failed"]
  P --> T["timed out"]
  Q --> X["cancelled"]

The buffer: handing files over by name

A delegation can open files or directories from your own world to the peer, each with a name and read and/or write rights. That name becomes the peer's buffer path; the buffer is a tree rooted at /, one per session:

flowchart LR
  subgraph W["Session A: real disk"]
    D1["/srv/app/README.md"]
    D2["/srv/app/releases/"]
  end
  subgraph B["Session B: the buffer at /"]
    P1["/readme"]
    P2["/app/releases/v0.4.2.tar"]
  end
  D1 -->|"grant as=readme, read-only"| P1
  D2 -->|"grant as=app, read+write"| P2

The holder of a grant works through five actions:

Two rules are worth remembering:

• The mapping is the contract. Paths can only land under a name you were granted; absolute paths, .., and symlink escapes are refused. The AI never needs to know your real paths, and cannot touch anything else.
• The grant holder acts. To give someone a file, grant read and let them download it. To receive one, have them grant write and upload it yourself.

Grants are reference counted: settling a ticket revokes its grants, and a grant at zero is gone — nobody has to remember to clean up.

Big files

Above 32 MiB, download and upload switch to a chunked relay: 16 MiB slices moved one at a time, then verified end to end by a whole-file sha256. A mismatch is a hard failure and keeps the intermediate data (1 GiB by default, 4 GiB hard ceiling). Progress shows up live in the status card's ⇅ 缓冲区传输 row, with a percentage and a bar per transfer, even with the panel closed.

What the detail page shows

Clicking a pipe opens its detail page:

• 缓冲区 — a walkable tree with the same feel as the right sidebar's file browser (crumbs, 刷新, hover highlight); each row says where it came from and with which rights.
• 进行中的请求 / 已结束 — every ticket's state, direction, subject and full reply.
• 生效中的授权 — the grants that are live right now, and the real path each one maps.

The screenshot above is a pipe after its task settled: the grants have already been reclaimed, so the buffer is empty again. That is by design.

SSH device sessions

In the 新会话 dialog, switch 运行位置 to SSH 设备, pick a device and a remote directory. Creating the session proves the connection with a real ssh round trip first; if it fails, no session is created.

Devices themselves are registered on the Plugins panel — 插件 in the sidebar → @nexus-aethra/dshell-bundle → the dshell-ssh row's 配置 — with a name, host, port, user, remote working directory, and either 密钥 (an OpenSSH private key; leave it empty to use your local ssh agent / ~/.ssh/config) or 密码.

• Connections use IdentitiesOnly=yes, carrying only that device's own key;
• Passwords go through OpenSSH's askpass hook, never onto a command line;
• Keys and passwords live in $DSH_HOME/dshell/ssh/keys/, mode 0600;
• Host keys are trusted into dshell's own known_hosts, leaving your personal file alone. A successful 测试 reports 已连接 user@host（system）· N ms and, when a host key is trusted, 主机密钥 SHA256:…（首次信任，请与服务器管理员核对 | 已信任）.

Once bound to a device, that session's commands, files and terminal all live on the device:

flowchart LR
  subgraph L["Your machine"]
    S["the session's terminal UI"]
    M["a mount stand-in directory<br/>mnt/device/remote-dir"]
  end
  subgraph R["The remote device"]
    T["a real shell<br/>(your visible terminal)"]
    F["the real file tree"]
  end
  S <-->|"ws /dshell/pty"| T
  M -.->|"mirrored view"| F

Such sessions wear an SSH badge in the sidebar. Their right sidebar gains 打开文件传输: two panes, 本机 and 设备, and dragging a file or folder from one to the other starts the copy — with per-item progress, chunk counts, skip counts, and an 覆盖 / 移除 question when something already exists. (32 MB per file, 20 000 entries or 2 GiB per plan.)

Token usage

Settings → 用量 charts what the models have cost, from an index dshell keeps in its own data directory:

• 每日热力 — a fixed 26-week calendar of daily totals, filled top-to-bottom and left-to-right, so the newest day is always the bottom-right cell. It reads all time on purpose: the range chips move the charts, never the calendar.
• 合计 / 未缓存输入 / 输出 / 缓存读 / 调用 / 缓存命中率 — the window's headline numbers. The hit rate is the one to watch: cache reads over all input.
• 每日消耗（按模型） and 模型占比 — one line per model over the window, and each one's share.
• 按模型明细 — input, output, cache read, cache write, calls and total per model.

The index is incremental: dsh attaches provider-reported usage to each assistant/message, and a scan reads only the sessions whose logs have grown since last time. It runs when you open the page, and on 重新聚合. A session whose log dsh cannot decode is reported as skipped — the page shows that the totals are partial, and why, instead of quietly counting less.

Settings

dshell configures itself on dsh's Plugins panel, on the row each setting belongs to: open 插件 in the sidebar, pick @nexus-aethra/dshell-bundle, then use the 配置 control on a row.

用量 (the token-usage page above) is a section of its own in Settings, beside 通用设置 and 模型 — it is a report rather than a plugin setting.

Settings are stored on the host and shared by every browser on it — turn an assist off here and it is off in the other browser too.

The status card

Pinned to the top right, collapsed to a single line until you expand it. Rows appear only when they have something to say:

Gesture cheat sheet

Three examples

1. Edit locally, build on a build host

1. Register the build host in Settings; 新会话 → 运行位置: SSH 设备 → pick it → remote directory /srv/order-gateway.
2. Create a pipe from your local session to that one, labelled "build host".
3. Tell the local session: "deploy this change to the build host and verify it." It delegates, the build-host session runs the work on its own machine, and the local session wakes up with the answer. Your terminal's foreground is never occupied.

2. Two sessions review each other (the screenshots above)

1. Create two sessions, demo (the code) and demo-peer (the release notes), and pipe them together with the label "review".
2. In demo, say: "delegate this to demo-peer — map my README.md as readme (read-only), have it read the file and report a review."
3. demo confirms the pipe, sends delegate (with a read-only grant named readme), and its turn ends.
4. demo-peer wakes up, reads /readme, writes the review, and finishes the ticket.
5. demo receives the [pipe report] and continues on its own. The pipe's detail page shows the ticket, the full reply, and the grant that was reclaimed once it settled.

This is exactly what produced the two screenshots above — the run is real, not staged.

3. Move a large file between machines

1. One session on each end (local and device), joined by a pipe.
2. Have whichever side holds the file upload it, or have the side that needs it download it, to a path in the buffer (say /app/releases/v0.4.2.tar).
3. Anything above 32 MiB is chunked and sha256-verified automatically; the status card's ⇅ 缓冲区传输 row tracks it, and both sides clean up their temporary slices when it is done.

Limits worth knowing

• A restart keeps the scrollback but not the PTY process. Restarting dsh spawns a fresh shell; earlier output is restored from the on-disk log ($DSH_HOME/dshell-pty/, files 0600 in a 0700 directory).
• That transcript records what you type. Both output and input are captured, so anything typed at an interactive prompt — a password included — lands in the file. It stays on this machine with owner-only permissions, but treat it as recorded.
• A session's working directory is immutable. The terminal may cd freely; the session's own root is fixed. A different directory means /new.
• Deleting a session takes two steps. After 删除 it sits in 待删除, and its log is cleared at the next dsh start; 取消 reverses it until then.
• One browser connection per session. A second websocket binding to the same session is refused.
• Archived is not deleted. An archived session stays in the pipe graph (it can still be a valid endpoint); only deletion removes it.
• Browser and desktop control are local-session only. A device session gets neither, on purpose: both would act on this machine while the session works on another. The install note above lists the two upstream packages that make the desktop half available at all.
• Full-screen mode reads the foreground on this machine only. A device session is detected by the alternate screen alone, so a full-screen program that does not switch buffers needs /fullscreen there. The reading is Linux's: dsh web on macOS or Windows has the reading and nothing else.
• The pipe panel refreshes by polling (about every 3 seconds) — there is no push channel. In-flight transfers refresh the status card once a second.

Docs for developers

Eleven packages (@nexus-aethra/dshell-*), published together: std (contracts), storage (storage engines), bundle (the single patch layer), conversation, terminal-bridge, mode, commands, files, ssh, buffer and usage (the token-usage page).

License

MIT, see LICENSE.