@songtonyli/dsh-cli 0.1.25 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -26,7 +26,7 @@ workspace and no build step. Native packages that ship one build per platform
26
26
  ripgrep, the PTY backend's addons, sharp, koffi, and the Landlock launcher — are
27
27
  ordinary optional dependencies, so npm resolves the right one for your machine.
28
28
 
29
- Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.25; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.27; `dsh --version`
30
30
  also reports the harness build the package was assembled from.
31
31
 
32
32
  ## License
package/bin/dsh.mjs CHANGED
@@ -18,7 +18,7 @@ const argv = process.argv.slice(2)
18
18
  // version this package publishes. Reporting only one of the two would make an
19
19
  // ordinary `npm install @songtonyli/dsh-cli@x` look like it installed something else.
20
20
  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
21
- console.log('@songtonyli/dsh-cli 0.1.25 (deepseek-harness 0.1.6-alpha.2)')
21
+ console.log('@songtonyli/dsh-cli 0.1.27 (deepseek-harness 0.1.6-alpha.2)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -160,7 +160,7 @@ window.__ModuleLoader__.load({
160
160
  const SCROLLBAR_LINGER_MS = 2e3;
161
161
  /** Format complete-build metadata for the local brand badge. */
162
162
  function localBuildVersion() {
163
- return `0.1.6-alpha.2-26160b0` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
163
+ return `0.1.6-alpha.2-df9469c` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
164
164
  }
165
165
  /** Each panel row subscribes only to its own selection state. */
166
166
  function PanelRow({ id, label, wide, usePanelInfo, selectPanel, renderSlot }) {
@@ -24,8 +24,8 @@
24
24
  "license": "MIT",
25
25
  "devDependencies": {
26
26
  "@types/react": "~18.3.1",
27
- "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2",
28
- "@deepseek-ai/cordis": "^4.0.2"
27
+ "@deepseek-ai/cordis": "^4.0.2",
28
+ "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2"
29
29
  },
30
30
  "files": [
31
31
  "lib/index.js",
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/bundle/tui-app/README.md
5
- README.md: 804426a98ae3b7b8392a4b3619c5700cab7d3824
6
- README.zh.md: 221d3b06d7cde8d3f2c8fb6d288e431edd91a519
5
+ README.md: 7d184af56b51a5a0bf5c162e3a84f66966abb85c
6
+ README.zh.md: c591d843f5683f15fc55c0789604b9229a5cdfd1
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: "Interactive terminal mode for dsh: talk to the agent in your terminal with streamed replies, tool cards, keyboard navigation over the conversation, a full-screen two-panel reader for turns, approvals, questions, slash commands, @-references, attachments, and session switching."
2
+ description: "Interactive terminal mode for dsh: talk to the agent in your terminal with streamed replies, tool cards, keyboard navigation over the conversation, a full-screen two-panel reader for turns, approvals, questions, slash commands, ! shell lines, @-references, attachments, and session switching."
3
3
  kind: "package-bundle"
4
4
  ---
5
5
 
@@ -48,11 +48,11 @@ While the keyboard walks the conversation a framed inspector is docked directly
48
48
 
49
49
  The focused block is also marked where it stands, with a two-column gutter that is dim beside the block's other lines and accented beside the focused section's own — or beside the fold marker, when the fold left that section out of the drawn rows entirely — and its content wraps two columns narrower while the mark is drawn. That mark reaches only the lines pi-tui still repaints differentially — the last `rows` lines of the last frame it wrote, a window a taller frame raises and a shorter one never lowers — because changing anything above them would clear the terminal's scrollback. A block that has scrolled past that point keeps no gutter, the inspector heading appends ` · off screen`, and the frame's own rules draw dim instead of accent, so the frame itself reports that the mark cannot be drawn where the block stands. A fade whose rows reach that edge settles them to their final colors in the frame that writes them, so nothing stays dim in the scrollback.
50
50
 
51
- `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen. The reader is an overlay composited into the viewport, so it costs the conversation no line and leaves the repaint window where it was; where a frame that has since shrunk put the top of the viewport out of the renderer's reach, blank rows at the foot of the frame give it back and the reader covers the whole terminal. It draws two panels under a top rule carrying a ` ● READER ` chip and `turn <n> of <total>`: the left panel lists one row per turn — the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `⚒<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away; the right panel scrolls that turn end to end, its sections stacked under `── <label> · turn <n> ` headers with the section the top row belongs to accented. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, so a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
51
+ `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen. The reader takes the terminal rather than drawing over the conversation: it runs on the terminal's alternate screen, the screen a pager runs on, and the conversation's own screen is held off the terminal for as long as it is up. So it costs the conversation no line, leaves the repaint window where it was, fills the screen on every terminal, and cannot leave a row of itself in your scrollback; closing it restores the conversation exactly as you left it, with whatever landed meanwhile drawn underneath. It draws two panels under a top rule carrying a ` ● READER ` chip and `turn <n> of <total>`: the left panel lists one row per turn — the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `⚒<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away; the right panel scrolls that turn end to end, its sections stacked under `── <label> · turn <n> ` headers with the section the top row belongs to accented. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, so a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
52
52
 
53
- Transient key feedback floats as a dim framed line in the top-right corner of the viewport: `press Esc again to stop turn <n>`, `press Ctrl+C again to quit`, `nothing in the transcript to read yet`, and `above the repaint window · opened in the reader`. It holds at full strength for `toastMs`, fades out, costs the conversation no row of its own, and takes no keyboard; where the renderer can no longer repaint the top of the viewport it is printed into the conversation instead, which keeps it. Facts worth keeping are notices in the conversation: `stopping the turn…`, `wait for the session switch to finish`, and every command result.
53
+ Transient key feedback floats as a dim framed line in the top-right corner of the viewport: `press Esc again to stop turn <n>`, `press Ctrl+C again to quit`, and `nothing in the transcript to read yet`. It holds at full strength for `toastMs`, fades out, costs the conversation no row of its own, and takes no keyboard; where the renderer can no longer repaint the top of the viewport it is printed into the conversation instead, which keeps it. Facts worth keeping are notices in the conversation: `stopping the turn…`, `wait for the session switch to finish`, `above the repaint window · opened in the reader`, and every command result.
54
54
 
55
- Motion reaches past streamed text, and every effect rides the same fade tick. The keyboard landing on the conversation, the subagent panel, or the status bar lifts that surface's frame, its chip, and the mark it holds for six ticks; a step of the conversation walk lifts the newly focused gutter for three; a step along the bar lifts the selected label for four; the reader grows into place over six ticks and shrinks away over four, drawn from its bottom rule up so no line it draws ever slides. No lift changes how many lines anything draws, and `reducedMotion` — like `NO_COLOR`, a disabled palette, and `TERM=dumb` — turns every one of them off and arms no repaint for them.
55
+ Motion reaches past streamed text, and every effect rides the same fade tick. The keyboard landing on the conversation, the subagent panel, or the status bar lifts that surface's frame, its chip, and the mark it holds for six ticks; a step of the conversation walk lifts the newly focused gutter for three; and a step along the bar lifts the selected label for four. The reader animates nothing: it arrives complete on the screen it owns. No lift changes how many lines anything draws, and `reducedMotion` — like `NO_COLOR`, a disabled palette, and `TERM=dumb` — turns every one of them off and arms no repaint for them.
56
56
 
57
57
  The subagent panel is drawn while a subagent session under the bound one is resident, or the listing carries a candidate it could not read. Unfocused it is one summary line with the listed count and the first child's key label; focused, its heading counts what it lists and ends on the keys it answers, `↑↓ children · Enter details · Tab regions · Esc input`, narrowed to `↑↓ children · Esc input` and then to `Esc input` on a terminal that cannot hold them, and each row gives the child's depth indent, its label or id, its mode (`one-shot` or `continuable`), `resident`, whether its agent is `running` or `idle`, its elapsed time — the open turn's, else the total its settled turns took — and its token usage, as far as this process's own view of that child and the composed projections carry them. Six rows are drawn at most, with `+<n> more · /subagents lists them all` under them; a candidate the listing could not interpret draws as `unreadable: <reason>` and opens nothing, and a failed listing keeps the rows the last good one produced with `listing failed: <reason>` beneath. The panel disappears with its last row.
58
58
 
@@ -65,6 +65,7 @@ While the input has the keyboard:
65
65
  | Key | Effect |
66
66
  |---|---|
67
67
  | `Enter` | Send the editor text; while a turn runs it waits for the next turn in the framed `QUEUE` panel above the editor until the loop claims it, entering the conversation then |
68
+ | `!command` / `!!command` | Run in this terminal; `!` is next-step context the next prompt can read, `!!` stays local |
68
69
  | `Shift+Enter` | Insert a newline |
69
70
  | `Ctrl+S` | While a turn runs, steer the editor text into the running turn's next step |
70
71
  | `Up` / `Down` | Recall earlier prompts |
@@ -75,11 +76,11 @@ While the input has the keyboard:
75
76
  | `Shift+Down` | Focus the queued-prompt panel's first row while prompts wait, otherwise the subagent panel's first row while it is drawn, and the status bar otherwise |
76
77
  | `Ctrl+G` | Read the conversation full screen, on its newest section |
77
78
  | `Ctrl+O` | Expand or collapse every tool card and context row |
78
- | `Esc` | Arm the stop and say so; a second press while that line is on screen stops the running turn, and queued messages stay queued |
79
+ | `Esc` | Cancel a running `!`; with a leading `!` draft and no turn running, clear the editor; otherwise arm the stop, and a second press while that line is on screen stops the running turn |
79
80
  | `Ctrl+C` | Clear the editor; a second press within 600 ms quits |
80
81
  | `Ctrl+D` | Quit when the editor is empty |
81
82
 
82
- An `Esc` that only handed the keyboard back — leaving a region, closing a page, a picker, or the reader — opens a 750 ms window in which an `Esc` reaching the input does nothing at all, so a habitual double press stops no turn. With no turn running, `Esc` closes the completion list while one is open and is silent otherwise. A session with nothing to read yet answers `Shift+Up` and `Ctrl+G` with `nothing in the transcript to read yet` and leaves the keyboard in the input.
83
+ An `Esc` that only handed the keyboard back — leaving a region, closing a page, a picker, or the reader — opens a 750 ms window in which an `Esc` reaching the input does nothing at all, so a habitual double press stops no turn. With no turn running, `Esc` closes the completion list while one is open, clears a draft that starts with `!`, and is silent otherwise. A session with nothing to read yet answers `Shift+Up` and `Ctrl+G` with `nothing in the transcript to read yet` and leaves the keyboard in the input.
83
84
 
84
85
  While the queued-prompt panel has the keyboard:
85
86
 
@@ -103,7 +104,7 @@ While the conversation has the keyboard:
103
104
  | `Home` / `End` | The oldest / newest section |
104
105
  | `Left` / `Right` | The previous / next part of the held block, stopping at its ends |
105
106
  | `Shift+Left` / `Shift+Right` | The first / last part of the held block |
106
- | `Space` | Fold or unfold the marked tool card or context block; a block the renderer can no longer rewrite opens in the reader instead, under the line `above the repaint window · opened in the reader` |
107
+ | `Space` | Fold or unfold the marked tool card or context block; a block the renderer can no longer rewrite opens in the reader instead, under the notice `above the repaint window · opened in the reader` |
107
108
  | `Enter` | Read this section full screen |
108
109
  | `Tab` / `Shift+Tab` | The next / previous region that is drawn |
109
110
  | `Esc` | Return to the input |
@@ -154,7 +155,7 @@ Every other key reaching the reader is consumed, and closing it opens the same 7
154
155
 
155
156
  Every focused segment expands its most important facts on the second line. `Enter` prints those facts into the transcript for every segment except `todo`, stating what they are and what changes them: the model segment names `/model`, the effort segment names the picker shared by `Shift+Tab` and `/effort`, and the permission segment names its preset, the `turn` segment — drawn as `turn <elapsed>` between the permission and usage segments, and only while a turn runs — gives the turn number, its start time, its elapsed time, and the queued-message counts, while the usage, context, goal, and plan segments print the matching sections of the `/status` report, the workspace segment the full path, and the attachments segment the pending attachments. The `todo` segment expands the counts by status and the item being worked on, or the next pending item when none is in progress, and `Enter` opens the agent's todo list, the same list `/todos` opens.
156
157
 
157
- Typing `/` at the start of the editor completes the terminal's own commands and the shared registry's; `@` anywhere completes references.
158
+ Typing `/` at the start of the editor completes the terminal's own commands and the shared registry's; `@` anywhere completes references. A nonempty `!command` or `!!command` line runs through `ctx.shell` in the session cwd at `danger-full-access`; the transcript shows `$ command` and the output. `!` injects a plugin notice for the next admitted step; `!!` does not. A lone `!` is an ordinary prompt.
158
159
 
159
160
  | Command | Effect |
160
161
  |---|---|
@@ -218,7 +219,7 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
218
219
  | `liveRefreshMs` | `1000` | Period of the redraw that advances the `turn` segment and the panel's elapsed values and re-reads a stale subagent listing |
219
220
  | `streamFadeSteps` | `12` | How many ticks a fade lasts: reply text fades in, reasoning and tool cards float out, over `streamFadeSteps × streamFadeStepMs` |
220
221
  | `streamFadeStepMs` | `33` | One fade tick, and the repaint period while anything is still moving; duration is `streamFadeSteps × streamFadeStepMs` |
221
- | `reducedMotion` | `false` | Draw streamed text, streamed reasoning, tool cards, and the chrome in their settled colors, with no fade, no lift, no reader reveal, and no repeating repaint |
222
+ | `reducedMotion` | `false` | Draw streamed text, streamed reasoning, tool cards, and the chrome in their settled colors, with no fade, no lift, and no repeating repaint |
222
223
  | `openBrowser` | `true` | Hand marked authorization pages to the local default browser |
223
224
 
224
225
  `prompt`, `resume`, and `openBrowser` come from the command line through the startup provider; the generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tui-app) is the exhaustive source for every accepted field.
@@ -235,7 +236,7 @@ The runner is a direct driver over the core API carrier, like `dsh-headless`, th
235
236
 
236
237
  ### Run flow
237
238
 
238
- The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with three operations: `create` makes one fresh persisted Agent with the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` reads the persisted log in pages through a read handle of `ctx.sessionPersistence` and resumes the Agent through the registry, and `fork` observes the source through `ctx.sessionQuery`, cuts after the chosen (by default the last) `turn/end` up to the next `turn/start`, and creates a seeded Agent with `parentSession` and `isSeeded` metadata. Every operation installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request. The terminal application starts on the session `--resume` or a fresh `create` yields, subscribes to `session/event`, `agent/assistant-stream`, and `agent/status`, answers the `approval/request` and `user-questions/request` waterfalls for the bound Agent only, and switches sessions by binding the next one and disposing the previous handle; while the host opens the next session the editor refuses input, and a quit during that wait releases the session that arrives afterwards. Quitting cancels any running turn, waits for quiescence, flushes the bound Session, disposes its handle, and requests exit 0; a driver failure writes `dsh: <message>` to stderr and requests exit 1. `/resume` and `/sessions` share the persisted-session chooser. Editor `Shift+Tab` dispatches empty `/effort` to open its current-model picker, and editor `Shift+Left` / `Shift+Right` use pi-tui's word navigation. `/login` starts `authorization.begin` with only subscription methods (every method except a key-collecting `api-key` login). A notice the flow marks with `openInBrowser` is handed to the default browser through `dsh-native-command`'s credential-scrubbed helper while the URL stays printed; the handoff is suppressed when `openBrowser` is false, the launch came through SSH, or the host has no desktop, and an opener failure becomes a notice beside the URL rather than a sign-in failure.
239
+ The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with three operations: `create` makes one fresh persisted Agent with the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` reads the persisted log in pages through a read handle of `ctx.sessionPersistence` and resumes the Agent through the registry, and `fork` observes the source through `ctx.sessionQuery`, cuts after the chosen (by default the last) `turn/end` up to the next `turn/start`, and creates a seeded Agent with `parentSession` and `isSeeded` metadata. Every operation installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request. The terminal application starts on the session `--resume` or a fresh `create` yields, subscribes to `session/event`, `agent/assistant-stream`, and `agent/status`, answers the `approval/request` and `user-questions/request` waterfalls for the bound Agent only, and switches sessions by binding the next one and disposing the previous handle; while the host opens the next session the editor refuses input, and a quit during that wait releases the session that arrives afterwards. Quitting cancels any running turn, waits for quiescence, flushes the bound Session, disposes its handle, and requests exit 0; a driver failure writes `dsh: <message>` to stderr and requests exit 1. `/resume` and `/sessions` share the persisted-session chooser. Editor `Shift+Tab` dispatches empty `/effort` to open its current-model picker, and editor `Shift+Left` / `Shift+Right` use pi-tui's word navigation. `/login` starts `authorization.begin` with only subscription methods (every method except a key-collecting `api-key` login). A notice the flow marks with `openInBrowser` is handed to the default browser through `dsh-native-command`'s credential-scrubbed helper while the URL stays printed; the handoff is suppressed when `openBrowser` is false, the launch came through SSH, or the host has no desktop, and an opener failure becomes a notice beside the URL rather than a sign-in failure. A nonempty `!` or `!!` line submitted in the editor runs through `ctx.shell` in this process; `!` injects a next-step notice and `!!` stays local.
239
240
 
240
241
  ### Rendering model
241
242
 
@@ -251,7 +252,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
251
252
  |---|---|
252
253
  | [`src/index.ts`](src/index.ts) | The `tui-app` plugin: the session host (create, resume, fork), history read, quit flow, exit mapping |
253
254
  | [`src/startup.ts`](src/startup.ts) | The `tui-app-startup` provider: prompt positional, `--resume`, `--no-open`, and `--help` |
254
- | [`src/app.ts`](src/app.ts) | The terminal application: layout, the key router, commands, session binding, seams, log and stream folding, the stop arm, and the overlays it mounts |
255
+ | [`src/app.ts`](src/app.ts) | The terminal application: layout, the key router, commands, session binding, seams, log and stream folding, the stop arm, the transient line it mounts, the terminal handover the reader runs on, and prefix-on-submit `!` / `!!` |
255
256
  | [`src/keys.ts`](src/keys.ts) | The key model: the focus regions, what one press means in each, the legends they degrade through, the entry keys, the `/help` lines, and the handoff window |
256
257
  | [`src/sessions.ts`](src/sessions.ts) | The persisted-session list and picker rows shared by `/resume` and `/sessions` |
257
258
  | [`src/effort.ts`](src/effort.ts) | Reasoning-effort names and picker rows shared by `/model`, `/effort`, and editor `Shift+Tab` |
@@ -263,10 +264,11 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
263
264
  | [`src/inspector.ts`](src/inspector.ts) | The docked inspector: the framed pane with its mode chip, the section heading, the numbered wrapping parts strip, the folded rows, and its mounted component |
264
265
  | [`src/frame.ts`](src/frame.ts) | Pure box drawing: the rounded rules, the inverse mode chip, body rows, and the legend step a width holds |
265
266
  | [`src/reader.ts`](src/reader.ts) | The reader as plain data: its state, the intents keys become, its geometry, and the lines it draws |
266
- | [`src/reader-overlay.ts`](src/reader-overlay.ts) | The mounted reader pane: its key map, its reveal, and where it leaves the keyboard |
267
- | [`src/screen.ts`](src/screen.ts) | The main screen with the settle passes between building a frame and writing it, the repaint window each pass is judged against, and the per-block repaint floor |
267
+ | [`src/reader-screen.ts`](src/reader-screen.ts) | The reader pane drawn on the alternate screen: its key map, and where it leaves the keyboard |
268
+ | [`src/screen.ts`](src/screen.ts) | The main screen with the settle passes between building a frame and writing it, the repaint window each pass is judged against, the per-block repaint floor, and the suspension that holds the conversation off the terminal |
269
+ | [`src/alt-screen.ts`](src/alt-screen.ts) | The terminal's alternate screen: taking it, drawing absolutely addressed rows on it, and giving the conversation's own screen back |
268
270
  | [`src/fade.ts`](src/fade.ts) | The streamed-text fade: the wall-clock tail tracker, the block-fade clock and registry, the fade-in ramp, the float-out mix, and the recolor of rendered lines |
269
- | [`src/motion.ts`](src/motion.ts) | The chrome motion clock and the three-level lift its call sites draw with: the landing, the section step, the bar walk, and the reader's reveal |
271
+ | [`src/motion.ts`](src/motion.ts) | The chrome motion clock and the three-level lift its call sites draw with: the landing, the section step, and the bar walk |
270
272
  | [`src/prompts.ts`](src/prompts.ts) | Approval, question, picker, and read-only detail prompts plus the modal queue |
271
273
  | [`src/toast.ts`](src/toast.ts) | The transient key-feedback line: its overlay, its clock, and the lines it carries |
272
274
  | [`src/transcript.ts`](src/transcript.ts) | Pure text folding of presentation views, usage, and turn-end reasons, and the one fold grammar every marker is written in |
@@ -275,6 +277,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
275
277
  | [`src/highlight.ts`](src/highlight.ts) | Syntax colour for fenced code: the grammars a fence may load, the theme the background picks, and the SGR one token is drawn with |
276
278
  | [`src/completion.ts`](src/completion.ts) | Slash-command and `@`-reference completion for the editor |
277
279
  | [`src/editor.ts`](src/editor.ts) | The prompt editor's terminal caret and its `Shift+Left` / `Shift+Right` mapping to pi-tui word navigation |
280
+ | [`src/shell-line.ts`](src/shell-line.ts) | Parse a `!` / `!!` line and format the transcript rows and model-facing notice |
278
281
  | [`src/status.ts`](src/status.ts) | Projection-seam facts and the sections the `/status` report and the segment details share; compaction and retry notices |
279
282
  | [`src/footer.ts`](src/footer.ts) | The status bar: the ordered segments, each segment's detail rows, the unfocused line built from both ends, and the focused sliding window |
280
283
  | [`src/subagent-panel.ts`](src/subagent-panel.ts) | The live subagent panel: one descendant listing plus sampled live facts become its rows, the unfocused summary line, and the focused listing |
@@ -289,11 +292,13 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
289
292
  | [`tests/motion.spec.ts`](tests/motion.spec.ts) | The motion clock's levels, its repaint demand, and the lift each level draws |
290
293
  | [`tests/toast.spec.ts`](tests/toast.spec.ts) | The transient line's box, its hold, its fade, and its early settlement |
291
294
  | [`tests/reader.spec.ts`](tests/reader.spec.ts) | The reader's geometry, its state machine, its filter, and the rows it returns |
292
- | [`tests/reader-overlay.spec.ts`](tests/reader-overlay.spec.ts) | The mounted pane: its key map, its reveal, its re-anchoring, and its exit |
295
+ | [`tests/reader-screen.spec.ts`](tests/reader-screen.spec.ts) | The reader pane: its key map, the screen it fills, its re-anchoring, and its exit |
296
+ | [`tests/alt-screen.spec.ts`](tests/alt-screen.spec.ts) | The alternate screen: its balanced switches, its per-row drawing, and the rows a shorter frame clears |
293
297
  | [`tests/commands.spec.ts`](tests/commands.spec.ts) | The `/resume` and `/sessions` picker, attachments, queues, skills, sign-in, export, references, the picker shared by `/effort` and `Shift+Tab`, and `Ctrl+S` in the model list over scripted services |
298
+ | [`tests/shell.spec.ts`](tests/shell.spec.ts) | Prefix-on-submit `!` / `!!` dispatch, next-step inject, Esc cancel, and the missing-shell notice |
294
299
  | [`tests/effort.spec.ts`](tests/effort.spec.ts) | Shared effort names, picker rows, the current-effort hint, and typed argument matching |
295
300
  | [`tests/panels.spec.ts`](tests/panels.spec.ts) | Status footer and report, the navigable subagent and todo lists, catalog commands, command hints, and the approval detail |
296
- | [`tests/transcript-focus.spec.ts`](tests/transcript-focus.spec.ts) | Walking the conversation, the region stack, the inspector, the reader over a live session, and the in-place gutter inside the repaint window |
301
+ | [`tests/transcript-focus.spec.ts`](tests/transcript-focus.spec.ts) | Walking the conversation, the region stack, the inspector, the reader over a live session with the terminal it takes and gives back, and the in-place gutter inside the repaint window |
297
302
  | [`tests/context.spec.ts`](tests/context.spec.ts) | Projection of system prompts and injected context into transcript sections |
298
303
  | [`tests/index.spec.ts`](tests/index.spec.ts) | Creation, resume paging, fork cut, session switching, quit flow, and failure reporting |
299
304
  | [`tests/startup.spec.ts`](tests/startup.spec.ts) | Command-line parsing over a real Loader tree |
@@ -327,11 +332,25 @@ Read these pages when you want to go deeper into the shared core, the sibling su
327
332
  <a id="model-experience"></a>
328
333
  ## Model Experience
329
334
 
330
- None, as the runner submits typed text as ordinary user messages and the composed base and terminal rows own the prompts and tools.
335
+ ### User-typed shell command
336
+
337
+ #### What the model sees
338
+
339
+ A nonempty `!command` line injects one plugin notice after the command finishes (`source.kind: plugin`, `plugin: tui-app`, `form: notice`). The next admitted step includes this wrapper; `<command>` and the fenced body are data-dependent. An empty run uses the exact line `(no output)` instead of a fence. A cancelled run appends a blank line and `(command cancelled)`. A nonzero exit appends a blank line and `Command exited with code <n>`. `!!command` and a lone `!` add no notice.
340
+
341
+ ##### User shell notice prefix
342
+
343
+ ```markdown
344
+ The user ran `<command>` in the terminal.
345
+ ```
346
+
347
+ #### Token effect
348
+
349
+ Conditional and retained: each `!` notice stays in conversation history for later requests; `!!` and a lone `!` add none.
331
350
 
332
351
  #### KV Cache effect
333
352
 
334
- The runner adds nothing to the request prefix; a `/model` switch starts a new request series exactly as it does from the browser.
353
+ Append-only conversation growth after the reusable request prefix. The notice does not change the system prompt or tool catalog. A `/model` switch starts a new request series exactly as it does from the browser.
335
354
 
336
355
  ## Known Limitations and Deferred Work
337
356
 
@@ -346,8 +365,8 @@ These limits describe the terminal surface as shipped; they are not a general CL
346
365
  - **Deliverables are named, not opened** — `/deliverables` lists the presented paths and `/changes` shows line comparisons; the browser previews the files.
347
366
  - **Terminal scrollback owns history** — the keyboard walks every block and part of the conversation, tool cards and context blocks fold, and the reader's `/` filter narrows this session's turns; searching the text of a turn, and the history of other sessions, belong to the browser surface.
348
367
  - **A focused block that scrolled away is marked only in the inspector** — pi-tui repaints differentially just the last `rows` lines of the last frame it wrote and clears the terminal's scrollback to change anything above them, so a block further back gains no gutter, the inspector heading says `off screen`, its frame goes dim, and `Space` on it opens the reader rather than rewriting it; `Ctrl+O` is the one key that does rewrite those lines, and on a conversation taller than the terminal it makes pi-tui redraw in full.
349
- - **A frame that shrank leaves the top of the viewport out of reach** — the repaint window rises with the tallest frame written so far and never falls, so after read mode closes or the spinner leaves, the reader draws that many rows short of full screen with the conversation showing above it, and a transient line is printed into the conversation instead of floating; both recover as the conversation grows.
350
- - **The reader covers the input while it sinks** — `Esc`, `Ctrl+G`, and `Ctrl+C` hand the keyboard back at once and the pane then shrinks away over four fade ticks, 132 ms at the default, during which the terminal's caret is hidden; any key that moves the keyboard, and any prompt or session change, takes the pane down immediately.
368
+ - **A frame that shrank leaves the top of the viewport out of reach** — the repaint window rises with the tallest frame written so far and never falls, so after read mode closes or the spinner leaves, a transient line is printed into the conversation instead of floating; it recovers as the conversation grows. The reader is unaffected: it draws on the terminal's other screen, where every row is its own.
369
+ - **The conversation is not drawn while the reader is up** — its screen is held off the terminal, so a turn that runs, a tool result that lands, and a notice that is printed are all drawn in one frame when the reader closes. The reader itself shows them as they arrive, because it re-reads the conversation on every drawing.
351
370
  - **The reader shows source text** — an assistant reply reads as the Markdown the model wrote, not the rendering the transcript draws, so tables and headings read as their source.
352
371
  - **The panel lists residency, not the tree** — a child joins it while its session record is resident in this process, so a subagent run by an out-of-process provider, which owns no session here, never appears; `/subagents` remains the way to every durable descendant.
353
372
  - **Residency is not work** — the listing's `activity: 'running'` says the child's record is resident, which is what the row's `resident` reports; whether the child is working is the separate `running` / `idle` word beside it, read from that child's Agent in this process.
@@ -356,6 +375,7 @@ These limits describe the terminal surface as shipped; they are not a general CL
356
375
  - **The fade needs an answer from the terminal** — its ramp is built from the background color the terminal reports to the query sent at startup, so a terminal that stays silent, or that encodes neither truecolor nor 256 colors, gets the two-level faint mode instead; `NO_COLOR`, a disabled palette, `TERM=dumb`, and `reducedMotion` turn every fade and every chrome lift off entirely, and a transient line then disappears at the end of its hold instead of fading out.
357
376
  - **The terminal's own caret can flicker** — the editor draws no caret of its own and the app turns the terminal cursor on, which pi-tui then moves across the lines it repaints; a terminal that does not honor the synchronized-output sequences pi-tui wraps a frame in can show that movement.
358
377
  - **Runs through the `dsh` launcher** — starting the profile another way fails at startup, because only the launcher can request the process exit.
378
+ - **`!` is one-shot and not a TTY** — each line is a fresh `ctx.shell.run`; there is no persistent shell or interactive program. The Web composer does not intercept `!`. An optional first prompt on the command line is always a user message.
359
379
 
360
380
  <a id="dev-note"></a>
361
381
  ### Dev Note
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: "dsh 的交互式终端模式:在你的终端里与 agent(智能体)对话,带流式回复、工具卡片、用键盘浏览对话记录、双面板全屏阅读器、审批、提问、斜杠命令、@ 引用、附件与会话切换。"
2
+ description: "dsh 的交互式终端模式:在你的终端里与 agent(智能体)对话,带流式回复、工具卡片、用键盘浏览对话记录、双面板全屏阅读器、审批、提问、斜杠命令、! 本地命令、@ 引用、附件与会话切换。"
3
3
  kind: "package-bundle"
4
4
  ---
5
5
 
@@ -48,11 +48,11 @@ dsh tui --no-open # print sign-in URLs without opening a
48
48
 
49
49
  被聚焦的块也会在原地被标记:一条两列宽的标记条,在块的其他行旁为暗色、在被聚焦小节自身的行旁为强调色——若折叠把该小节整个留在了绘出的行之外,强调色便落在那一行折叠标记旁——标记绘制期间该块的内容按窄两列换行。这个标记只能落在 pi-tui 仍以差分方式重绘的行上——也就是它写出的上一帧的最后 `rows` 行,这条边界只会被更高的帧抬高、不会被更矮的帧降低——因为改动其上方的任何一行都会清空终端的回滚区。已经滚过该位置的块不带标记条,检视面板的标题追加 ` · off screen`,其边框线也改画暗色而非强调色,于是边框本身就报告出标记无法画在该块所在之处。淡入中的各行抵达这一边界时,会在写出它们的同一帧内被结算为最终颜色,因此回滚区里不会留下暗色文字。
50
50
 
51
- 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录。阅读器是合成进视口的浮层,因此不占用对话记录的任何一行,也让重绘边界保持原位;若某一帧此后变短,使视口顶部落到渲染器够不着的地方,帧尾的若干空行会把它还回来,于是阅读器铺满整个终端。它在带有 ` ● READER ` 徽标与 `turn <n> of <total>` 的顶边线之下画两个面板:左面板每个轮次一行——轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`⚒<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥;右面板把该轮次从头到尾滚动读出,各小节堆叠在 `── <label> · turn <n> ` 标题之下,顶行所属的那个小节带强调色。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它在每一帧都重新读取对话记录,因此流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
51
+ 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录。阅读器并不画在对话记录之上,而是接管终端:它运行在终端的备用屏幕(alternate screen,分页器所用的那块屏幕)上,只要它还开着,对话记录自己的屏幕就被挡在终端之外。因此它不占用对话记录的任何一行,让重绘边界保持原位,在任何终端上都铺满整屏,也不可能把自己的任何一行留在你的回滚缓冲里;关闭它会把对话记录原样恢复成你离开时的样子,期间落地的内容则绘制在其下方。它在带有 ` ● READER ` 徽标与 `turn <n> of <total>` 的顶边线之下画两个面板:左面板每个轮次一行——轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`⚒<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥;右面板把该轮次从头到尾滚动读出,各小节堆叠在 `── <label> · turn <n> ` 标题之下,顶行所属的那个小节带强调色。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它在每一帧都重新读取对话记录,因此流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
52
52
 
53
- 临时按键反馈以一行暗色带框文字浮在视口右上角:`press Esc again to stop turn <n>`、`press Ctrl+C again to quit`、`nothing in the transcript to read yet` 与 `above the repaint window · opened in the reader`。它以全亮度保持 `toastMs`、随后淡出,不占用对话记录自身的任何一行,也不接管键盘;渲染器已无法重绘视口顶部时,它改为打印进对话记录,从而被保留下来。值得留存的事实则是对话记录中的通知:`stopping the turn…`、`wait for the session switch to finish` 以及每一条命令结果。
53
+ 临时按键反馈以一行暗色带框文字浮在视口右上角:`press Esc again to stop turn <n>`、`press Ctrl+C again to quit` 与 `nothing in the transcript to read yet`。它以全亮度保持 `toastMs`、随后淡出,不占用对话记录自身的任何一行,也不接管键盘;渲染器已无法重绘视口顶部时,它改为打印进对话记录,从而被保留下来。值得留存的事实则是对话记录中的通知:`stopping the turn…`、`wait for the session switch to finish`、`above the repaint window · opened in the reader` 以及每一条命令结果。
54
54
 
55
- 动效不止于流式文本,而且每种效果都乘着同一个淡入时钟。键盘落到对话记录、子 agent 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮六拍;对话记录走查中的一步把新聚焦的标记条抬亮三拍;状态栏上的一步把所选标签抬亮四拍;阅读器用六拍长出、用四拍缩回,并自其底边线向上绘制,因此它画出的每一行都不会滑动。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会把它们全部关闭,并且不为它们安排任何重绘。
55
+ 动效不止于流式文本,而且每种效果都乘着同一个淡入时钟。键盘落到对话记录、子 agent 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮六拍;对话记录走查中的一步把新聚焦的标记条抬亮三拍;状态栏上的一步把所选标签抬亮四拍。阅读器没有任何动效:它在自己占据的屏幕上一次性完整出现。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会把它们全部关闭,并且不为它们安排任何重绘。
56
56
 
57
57
  子 agent 面板在绑定会话之下有常驻的子 agent 会话、或列表中带有无法读取的候选者时绘制。未聚焦时它是一行摘要,含列出的数量与第一个子会话的关键标签;聚焦时其标题统计所列出的条目,并以它所应答的按键 `↑↓ children · Enter details · Tab regions · Esc input` 结尾,在容纳不下时收缩为 `↑↓ children · Esc input`,再收缩为 `Esc input`;每一行给出该子会话的层级缩进、其标签或 id、其模式(`one-shot` 或 `continuable`)、`resident`、其 agent 处于 `running` 还是 `idle`、其已用时间——进行中轮次的用时,否则是已结束轮次的合计——以及其 token 用量,以本进程对该子会话的可见程度与已组合的投影所能提供的为限。最多绘制六行,其下是 `+<n> more · /subagents lists them all`;列表无法解读的候选者绘制为 `unreadable: <reason>` 且打不开任何页面,读取失败的列表则保留上一次成功读取产生的各行,并在其下写出 `listing failed: <reason>`。面板随其最后一行一同消失。
58
58
 
@@ -65,6 +65,7 @@ dsh tui --no-open # print sign-in URLs without opening a
65
65
  | 按键 | 效果 |
66
66
  |---|---|
67
67
  | `Enter` | 发送编辑器文本;轮次进行中时它在编辑器上方的带框 `QUEUE` 面板中等待下一轮次,直到循环领取它后才进入对话 |
68
+ | `!command` / `!!command` | 在本终端运行;`!` 会作为下一步上下文供下一条提示阅读,`!!` 只留在本地 |
68
69
  | `Shift+Enter` | 插入换行 |
69
70
  | `Ctrl+S` | 轮次进行中时,把编辑器文本引导(steer)进当前轮次的下一步 |
70
71
  | `Up` / `Down` | 调出先前的提示 |
@@ -75,11 +76,11 @@ dsh tui --no-open # print sign-in URLs without opening a
75
76
  | `Shift+Down` | 有提示等待时把焦点放到待处理提示面板第一行,否则在子 agent 面板已绘制时放到其第一行,再否则放到状态栏 |
76
77
  | `Ctrl+G` | 整屏读出对话记录,停在其最新小节 |
77
78
  | `Ctrl+O` | 展开或折叠所有工具卡片与上下文行 |
78
- | `Esc` | 装填停止并给出提示;该提示仍在屏幕上时再按一次会停止正在进行的轮次,已排队的消息保持排队 |
79
+ | `Esc` | 取消正在运行的 `!`;在没有轮次进行且草稿以 `!` 开头时清空编辑器;否则装填停止,该提示仍在屏幕上时再按一次会停止正在进行的轮次 |
79
80
  | `Ctrl+C` | 清空编辑器;600 ms 内再按一次则退出 |
80
81
  | `Ctrl+D` | 编辑器为空时退出 |
81
82
 
82
- 仅仅交还了键盘的 `Esc`——离开某个区域、关闭页面、选择器或阅读器——会打开一个 750 ms 的窗口,其间到达编辑器的 `Esc` 完全不做任何事,因此习惯性的连按停不掉任何轮次。没有轮次进行时,`Esc` 在补全列表打开时关闭它,其余情况保持沉默。尚无可读内容的会话对 `Shift+Up` 与 `Ctrl+G` 回以 `nothing in the transcript to read yet`,并把键盘留在编辑器。
83
+ 仅仅交还了键盘的 `Esc`——离开某个区域、关闭页面、选择器或阅读器——会打开一个 750 ms 的窗口,其间到达编辑器的 `Esc` 完全不做任何事,因此习惯性的连按停不掉任何轮次。没有轮次进行时,`Esc` 在补全列表打开时关闭它,清空以 `!` 开头的草稿,其余情况保持沉默。尚无可读内容的会话对 `Shift+Up` 与 `Ctrl+G` 回以 `nothing in the transcript to read yet`,并把键盘留在编辑器。
83
84
 
84
85
  待处理提示面板持有键盘时:
85
86
 
@@ -103,7 +104,7 @@ dsh tui --no-open # print sign-in URLs without opening a
103
104
  | `Home` / `End` | 最早 / 最新的小节 |
104
105
  | `Left` / `Right` | 被持有块的上一个 / 下一个部分,到该块两端即停 |
105
106
  | `Shift+Left` / `Shift+Right` | 被持有块的第一个 / 最后一个部分 |
106
- | `Space` | 折叠或展开被标记的工具卡片或上下文块;渲染器已无法重写的块改为在阅读器中打开,并附上一行 `above the repaint window · opened in the reader` |
107
+ | `Space` | 折叠或展开被标记的工具卡片或上下文块;渲染器已无法重写的块改为在阅读器中打开,并附上通知 `above the repaint window · opened in the reader` |
107
108
  | `Enter` | 整屏读出该小节 |
108
109
  | `Tab` / `Shift+Tab` | 已绘制区域中的下一个 / 上一个 |
109
110
  | `Esc` | 回到编辑器 |
@@ -154,7 +155,7 @@ dsh tui --no-open # print sign-in URLs without opening a
154
155
 
155
156
  每个聚焦的分段都在第二行展开其最重要的事实。除 `todo` 之外,`Enter` 把这些事实打印到对话记录,并指出改变它们的方式:模型分段指出 `/model`,推理强度分段指出 `Shift+Tab` 与 `/effort` 共用的选择器,权限分段指出其预设;`turn` 分段——绘制在权限与用量分段之间、形如 `turn <elapsed>`,且只在轮次进行时出现——给出轮次编号、其开始时间、已用时间与排队消息数量;用量、上下文、目标与计划分段打印 `/status` 报告中对应的小节,workspace 分段显示完整路径,附件分段列出待发送的附件。`todo` 分段展开按状态统计的计数以及正在进行的条目(若无正在进行的条目则为下一条待办),`Enter` 打开 agent 的 todo 列表,与 `/todos` 打开的是同一个列表。
156
157
 
157
- 在编辑器开头输入 `/` 会补全终端自身的命令与共享注册表的命令;任意位置的 `@` 补全引用。
158
+ 在编辑器开头输入 `/` 会补全终端自身的命令与共享注册表的命令;任意位置的 `@` 补全引用。非空的 `!command` 或 `!!command` 行经 `ctx.shell` 在会话 cwd 以 `danger-full-access` 运行;对话记录显示 `$ command` 与输出。`!` 会注入一条插件通知供下一步领取;`!!` 不会。单独的 `!` 仍是普通提示。
158
159
 
159
160
  | 命令 | 效果 |
160
161
  |---|---|
@@ -218,7 +219,7 @@ dsh tui --no-open # print sign-in URLs without opening a
218
219
  | `liveRefreshMs` | `1000` | 重绘周期:推进 `turn` 分段与面板中的已用时间,并重新读取已过期的子 agent 列表 |
219
220
  | `streamFadeSteps` | `12` | 一次淡入或浮出持续多少拍:回复文字淡入,推理与工具卡片浮出,时长为 `streamFadeSteps × streamFadeStepMs` |
220
221
  | `streamFadeStepMs` | `33` | 一拍淡入或浮出的时长,也是仍在变化时的重绘周期;总时长为 `streamFadeSteps × streamFadeStepMs` |
221
- | `reducedMotion` | `false` | 以稳定颜色绘制流式文本、流式推理、工具卡片与应用自身的边框装饰,不做淡入、不做抬亮、不做阅读器展开,也不重复重绘 |
222
+ | `reducedMotion` | `false` | 以稳定颜色绘制流式文本、流式推理、工具卡片与应用自身的边框装饰,不做淡入、不做抬亮,也不重复重绘 |
222
223
  | `openBrowser` | `true` | 把被标记的授权页面交给本地默认浏览器 |
223
224
 
224
225
  `prompt`、`resume` 与 `openBrowser` 经启动提供方来自命令行;生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tui-app)是所有可接受字段的完整来源。
@@ -235,7 +236,7 @@ runner 与 `dsh-headless` 一样是核心 API 载体之上的直接驱动器,
235
236
 
236
237
  ### 运行流程
237
238
 
238
- runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含三个操作的会话宿主:`create` 用共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 通过 `ctx.sessionPersistence` 的只读句柄分页读取持久化日志并经注册表恢复 Agent,`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent。每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求。终端应用从 `--resume` 或一次新的 `create` 产生的会话开始,订阅 `session/event`、`agent/assistant-stream` 与 `agent/status`,只为绑定的 Agent 应答 `approval/request` 与 `user-questions/request` waterfall,并通过绑定下一个会话、dispose 先前句柄来切换会话;宿主打开下一个会话期间编辑器拒绝输入,等待期间退出会释放随后到达的会话。退出时取消任何进行中的轮次、等待完全停稳、flush 绑定的会话、dispose 其句柄并请求以 0 退出;驱动器失败会向 stderr 写入 `dsh: <message>` 并请求以 1 退出。`/resume` 与 `/sessions` 共用持久化会话选择器。编辑器中的 `Shift+Tab` 会派发空参数 `/effort` 以打开当前模型的推理强度选择器,而编辑器中的 `Shift+Left` / `Shift+Right` 使用 pi-tui 的词导航。`/login` 只带着订阅方法(除收集密钥的 `api-key` 登录外的每一种方法)启动 `authorization.begin`。flow 用 `openInBrowser` 标记的 notice 会经 `dsh-native-command` 的凭据擦除辅助进程交给默认浏览器,URL 同时保持打印;当 `openBrowser` 为 false、启动经过 SSH 或宿主没有桌面时抑制该交接,打开器失败则成为 URL 旁的一条通知,而非登录失败。
239
+ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含三个操作的会话宿主:`create` 用共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 通过 `ctx.sessionPersistence` 的只读句柄分页读取持久化日志并经注册表恢复 Agent,`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent。每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求。终端应用从 `--resume` 或一次新的 `create` 产生的会话开始,订阅 `session/event`、`agent/assistant-stream` 与 `agent/status`,只为绑定的 Agent 应答 `approval/request` 与 `user-questions/request` waterfall,并通过绑定下一个会话、dispose 先前句柄来切换会话;宿主打开下一个会话期间编辑器拒绝输入,等待期间退出会释放随后到达的会话。退出时取消任何进行中的轮次、等待完全停稳、flush 绑定的会话、dispose 其句柄并请求以 0 退出;驱动器失败会向 stderr 写入 `dsh: <message>` 并请求以 1 退出。`/resume` 与 `/sessions` 共用持久化会话选择器。编辑器中的 `Shift+Tab` 会派发空参数 `/effort` 以打开当前模型的推理强度选择器,而编辑器中的 `Shift+Left` / `Shift+Right` 使用 pi-tui 的词导航。`/login` 只带着订阅方法(除收集密钥的 `api-key` 登录外的每一种方法)启动 `authorization.begin`。flow 用 `openInBrowser` 标记的 notice 会经 `dsh-native-command` 的凭据擦除辅助进程交给默认浏览器,URL 同时保持打印;当 `openBrowser` 为 false、启动经过 SSH 或宿主没有桌面时抑制该交接,打开器失败则成为 URL 旁的一条通知,而非登录失败。编辑器里提交的非空 `!` 或 `!!` 行经本进程的 `ctx.shell` 运行;`!` 注入一条下一步通知,`!!` 只留在本地。
239
240
 
240
241
  ### 渲染模型
241
242
 
@@ -251,7 +252,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
251
252
  |---|---|
252
253
  | [`src/index.ts`](src/index.ts) | `tui-app` 插件:会话宿主(创建、恢复、fork)、历史读取、退出流程、退出码映射 |
253
254
  | [`src/startup.ts`](src/startup.ts) | `tui-app-startup` 提供方:提示位置参数、`--resume`、`--no-open` 与 `--help` |
254
- | [`src/app.ts`](src/app.ts) | 终端应用:布局、按键路由、命令、会话绑定、接缝、日志与流的折叠、停止装填,以及它挂载的各浮层 |
255
+ | [`src/app.ts`](src/app.ts) | 终端应用:布局、按键路由、命令、会话绑定、接缝、日志与流的折叠、停止装填、它挂载的临时提示行、阅读器所依托的终端交接,以及提交时解析的 `!` / `!!` |
255
256
  | [`src/keys.ts`](src/keys.ts) | 按键模型:各焦点区域、一次按键在每个区域中的含义、它们逐级收缩的按键提示、进入用的按键、`/help` 的各行,以及交接窗口 |
256
257
  | [`src/sessions.ts`](src/sessions.ts) | `/resume` 与 `/sessions` 共用的持久化会话列表及选择器行 |
257
258
  | [`src/effort.ts`](src/effort.ts) | `/model`、`/effort` 与编辑器 `Shift+Tab` 共用的推理强度名称及选择器行 |
@@ -263,10 +264,11 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
263
264
  | [`src/inspector.ts`](src/inspector.ts) | 停靠的检视面板:带模式徽标的边框面板、小节标题、带编号且会折行的各部分选择行、折叠后的各行,及其挂载的组件 |
264
265
  | [`src/frame.ts`](src/frame.ts) | 纯粹的画框:圆角边框线、反白的模式徽标、正文行,以及某个宽度容纳得下的按键提示级别 |
265
266
  | [`src/reader.ts`](src/reader.ts) | 作为纯数据的阅读器:其状态、按键变成的各个意图、其几何布局,以及它画出的各行 |
266
- | [`src/reader-overlay.ts`](src/reader-overlay.ts) | 挂载的阅读器面板:其按键映射、其展开动效,以及它把键盘留在何处 |
267
- | [`src/screen.ts`](src/screen.ts) | 在构建一帧与写出该帧之间带若干次结算的主屏幕、每次结算所依据的重绘窗口,以及每个块的重绘下界 |
267
+ | [`src/reader-screen.ts`](src/reader-screen.ts) | 画在备用屏幕上的阅读器面板:其按键映射,以及它把键盘留在何处 |
268
+ | [`src/screen.ts`](src/screen.ts) | 在构建一帧与写出该帧之间带若干次结算的主屏幕、每次结算所依据的重绘窗口、每个块的重绘下界,以及把对话记录挡在终端之外的挂起 |
269
+ | [`src/alt-screen.ts`](src/alt-screen.ts) | 终端的备用屏幕:接管它、在其上按绝对行址绘制,以及把对话记录自己的屏幕交还 |
268
270
  | [`src/fade.ts`](src/fade.ts) | 流式文本淡入与浮出:基于挂钟的尾部追踪器、块时钟与注册表、淡入亮度级别、浮出混合,以及对已渲染行的重新着色 |
269
- | [`src/motion.ts`](src/motion.ts) | 边框装饰的动效时钟与其调用点所绘的三级抬亮:落键、小节步进、状态栏走查与阅读器的展开 |
271
+ | [`src/motion.ts`](src/motion.ts) | 边框装饰的动效时钟与其调用点所绘的三级抬亮:落键、小节步进与状态栏走查 |
270
272
  | [`src/prompts.ts`](src/prompts.ts) | 审批、提问、选择器与只读详情提示以及模态队列 |
271
273
  | [`src/toast.ts`](src/toast.ts) | 临时按键提示行:其浮层、其时钟,以及它承载的各条文字 |
272
274
  | [`src/transcript.ts`](src/transcript.ts) | 呈现视图、用量与轮次结束原因的纯文本折叠,以及每条标记共用的那一套折叠措辞 |
@@ -275,6 +277,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
275
277
  | [`src/highlight.ts`](src/highlight.ts) | 围栏代码的语法高亮:某个围栏可能加载的语法、由背景选定的配色主题,以及一个 token 所用的 SGR |
276
278
  | [`src/completion.ts`](src/completion.ts) | 编辑器的斜杠命令与 `@` 引用补全 |
277
279
  | [`src/editor.ts`](src/editor.ts) | 提示编辑器的终端光标,以及把 `Shift+Left` / `Shift+Right` 映射到 pi-tui 词导航的逻辑 |
280
+ | [`src/shell-line.ts`](src/shell-line.ts) | 解析 `!` / `!!` 行,并格式化对话记录行与面向模型的通知 |
278
281
  | [`src/status.ts`](src/status.ts) | 投影接缝的事实,以及 `/status` 报告与分段详情共享的小节;压缩与重试通知 |
279
282
  | [`src/footer.ts`](src/footer.ts) | 状态栏:有序的各分段、每个分段的详情行、未聚焦时由两端向内构建的一行,以及聚焦时的滑动窗口 |
280
283
  | [`src/subagent-panel.ts`](src/subagent-panel.ts) | 实时子 agent 面板:一次后代列表加上采样到的实时事实构成其各行、未聚焦时的摘要行,以及聚焦时的列表 |
@@ -289,11 +292,13 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
289
292
  | [`tests/motion.spec.ts`](tests/motion.spec.ts) | 动效时钟的各个级别、它对重绘的要求,以及每一级所绘的抬亮 |
290
293
  | [`tests/toast.spec.ts`](tests/toast.spec.ts) | 临时提示行的方框、其保持、其淡出与其提前结算 |
291
294
  | [`tests/reader.spec.ts`](tests/reader.spec.ts) | 阅读器的几何布局、其状态机、其过滤,以及它返回的各行 |
292
- | [`tests/reader-overlay.spec.ts`](tests/reader-overlay.spec.ts) | 挂载的面板:其按键映射、其展开动效、其重新锚定与其退出 |
295
+ | [`tests/reader-screen.spec.ts`](tests/reader-screen.spec.ts) | 阅读器面板:其按键映射、它铺满的屏幕、其重新锚定与其退出 |
296
+ | [`tests/alt-screen.spec.ts`](tests/alt-screen.spec.ts) | 备用屏幕:其成对的切换、其逐行绘制,以及更短的一帧所清除的行 |
293
297
  | [`tests/commands.spec.ts`](tests/commands.spec.ts) | 基于脚本化服务的 `/resume` 与 `/sessions` 选择器、附件、队列、技能、登录、导出、引用、`/effort` 与 `Shift+Tab` 共用的选择器,以及模型列表中的 `Ctrl+S` |
298
+ | [`tests/shell.spec.ts`](tests/shell.spec.ts) | 提交时解析的 `!` / `!!` 分发、下一步 inject、Esc 取消,以及缺少 shell 时的通知 |
294
299
  | [`tests/effort.spec.ts`](tests/effort.spec.ts) | 共用的推理强度名称、选择器行、当前强度提示与输入参数匹配 |
295
300
  | [`tests/panels.spec.ts`](tests/panels.spec.ts) | 状态页脚与报告、可导航的子 agent 与 todo 列表、目录命令、命令提示与审批详情 |
296
- | [`tests/transcript-focus.spec.ts`](tests/transcript-focus.spec.ts) | 走遍对话记录、区域序列、检视面板、实时会话上的阅读器,以及重绘窗口内的原地标记条 |
301
+ | [`tests/transcript-focus.spec.ts`](tests/transcript-focus.spec.ts) | 走遍对话记录、区域序列、检视面板、实时会话上的阅读器连同它接管与交还的终端,以及重绘窗口内的原地标记条 |
297
302
  | [`tests/context.spec.ts`](tests/context.spec.ts) | 把系统提示词与注入上下文投影为对话记录小节 |
298
303
  | [`tests/index.spec.ts`](tests/index.spec.ts) | 创建、恢复分页、fork 切割、会话切换、退出流程与失败报告 |
299
304
  | [`tests/startup.spec.ts`](tests/startup.spec.ts) | 基于真实 Loader 配置树的命令行解析 |
@@ -327,11 +332,25 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
327
332
  <a id="model-experience"></a>
328
333
  ## 模型体验
329
334
 
330
- 无,因为 runner 把键入的文本作为普通用户消息提交,提示与工具由已组合的 base 与终端配置行持有。
335
+ ### 用户键入的 shell 命令
336
+
337
+ #### 模型看到什么
338
+
339
+ 非空的 `!command` 行在命令结束后注入一条插件通知(`source.kind: plugin`,`plugin: tui-app`,`form: notice`)。下一步领取时会带上此包装;`<command>` 与围栏正文依数据而定。没有输出时使用精确一行 `(no output)` 而不是围栏。取消的运行会再追加一个空行和 `(command cancelled)`。非零退出会再追加一个空行和 `Command exited with code <n>`。`!!command` 与单独的 `!` 不添加通知。
340
+
341
+ ##### 用户 shell 通知前缀
342
+
343
+ ```markdown
344
+ The user ran `<command>` in the terminal.
345
+ ```
346
+
347
+ #### Token 影响
348
+
349
+ 有条件且保留:每条 `!` 通知留在之后请求的对话历史中;`!!` 与单独的 `!` 不增加任何内容。
331
350
 
332
351
  #### KV Cache 影响
333
352
 
334
- runner 不向请求前缀添加任何内容;`/model` 切换像在浏览器中一样开始新的请求序列。
353
+ 在可复用的请求前缀之后只做追加式增长。该通知不改变系统提示或工具目录。`/model` 切换像在浏览器中一样开始新的请求序列。
335
354
 
336
355
  ## 已知限制与延期工作
337
356
 
@@ -346,8 +365,8 @@ runner 不向请求前缀添加任何内容;`/model` 切换像在浏览器中
346
365
  - **交付物只列名、不打开**——`/deliverables` 列出交付路径,`/changes` 显示逐行对比;浏览器会预览这些文件。
347
366
  - **历史由终端回滚区持有**——键盘可以走遍对话记录的每个块与每个部分,工具卡片与上下文块可以折叠,阅读器的 `/` 过滤可以收窄本会话的各轮次;搜索一个轮次的文本以及其他会话的历史,属于浏览器表层。
348
367
  - **滚走的聚焦块只在检视面板中被标记**——pi-tui 只对它写出的上一帧的最后 `rows` 行做差分重绘,要改动其上方的内容就得清空终端回滚区,因此更靠前的块得不到标记条,检视面板标题写出 `off screen`,其边框转为暗色,在它上面按 `Space` 会打开阅读器而不是重写它;`Ctrl+O` 是唯一仍会重写那些行的按键,在高于终端的对话记录上它会让 pi-tui 整屏重绘。
349
- - **缩过的帧会让视口顶部脱离可及范围**——重绘窗口随迄今写出的最高一帧上升且不会回落,因此在读取模式关闭或旋转指示离开之后,阅读器会比整屏少画那么多行、其上方露出对话记录,临时提示行也改为打印进对话记录;两者都会随对话记录增长而恢复。
350
- - **阅读器下沉期间遮住输入行**——`Esc`、`Ctrl+G` 与 `Ctrl+C` 会立刻交还键盘,随后该面板用四拍淡入时钟缩回,默认即 132 ms,其间终端光标不可见;任何移动键盘的按键,以及任何提示或会话变更,都会立即撤下该面板。
368
+ - **缩过的帧会让视口顶部脱离可及范围**——重绘窗口随迄今写出的最高一帧上升且不会回落,因此在读取模式关闭或旋转指示离开之后,临时提示行改为打印进对话记录;它会随对话记录增长而恢复。阅读器不受影响:它画在终端的另一块屏幕上,那里的每一行都归它所有。
369
+ - **阅读器开着时不绘制对话记录**——对话记录的屏幕被挡在终端之外,因此期间跑完的轮次、落地的工具结果与打印的通知,都在阅读器关闭时的同一帧里绘出。阅读器自身仍会随它们到达而显示,因为它在每一次绘制时都重新读取对话记录。
351
370
  - **阅读器显示的是源文本**——assistant 回复读到的是模型写下的 Markdown,而不是对话记录绘制出的渲染结果,因此表格与标题以源码形式呈现。
352
371
  - **面板列出的是常驻,而不是整棵树**——子会话在其会话记录常驻于本进程期间加入面板,因此由进程外提供方运行、在此没有自己会话的子 agent 永远不会出现;`/subagents` 仍是到达每一个持久后代的途径。
353
372
  - **常驻不等于正在工作**——列表的 `activity: 'running'` 表示该子会话的记录常驻,这正是行内 `resident` 所报告的内容;子会话是否在工作则是它旁边单独的 `running` / `idle`,读自本进程中该子会话的 Agent。
@@ -356,6 +375,7 @@ runner 不向请求前缀添加任何内容;`/model` 切换像在浏览器中
356
375
  - **淡入需要终端的应答**——其亮度级别由终端对启动时发出的查询所报告的背景色构建,因此保持沉默、或既不编码真彩色也不编码 256 色的终端只会得到两级的暗淡模式;`NO_COLOR`、被禁用的调色板、`TERM=dumb` 与 `reducedMotion` 会完全关闭每一种淡入与每一种边框抬亮,临时提示行届时在保持结束时直接消失,而不是淡出。
357
376
  - **终端自身的光标可能闪烁**——编辑器不绘制自己的光标,应用打开终端光标,而 pi-tui 会在其重绘的各行之间移动它;不支持 pi-tui 为一帧包裹的同步输出序列的终端可能显示出这种移动。
358
377
  - **通过 `dsh` 启动器运行**——以其他方式启动该 profile 会在启动时失败,因为只有启动器能请求进程退出。
378
+ - **`!` 是一次性的,也不是 TTY**——每一行都是一次新的 `ctx.shell.run`;没有持久 shell,也不能跑交互式程序。Web 编辑器不拦截 `!`。命令行上的可选首条提示始终是用户消息。
359
379
 
360
380
  <a id="dev-note"></a>
361
381
  ### 开发备注