@songtonyli/dsh-cli 0.1.45 → 0.1.47

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.45; `dsh --version`
29
+ Requires Node `^22.19.0 || >=24.0.0`. Version 0.1.47; `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.45 (deepseek-harness 0.1.7-rc.2)')
21
+ console.log('@songtonyli/dsh-cli 0.1.47 (deepseek-harness 0.1.7-rc.2)')
22
22
  process.exit(0)
23
23
  }
24
24
 
@@ -47,10 +47,10 @@
47
47
  "micromark-extension-gfm": "^3.0.0",
48
48
  "micromark-util-sanitize-uri": "^2.0.1",
49
49
  "simple-icons": "16.31.0",
50
- "@deepseek-ai/cordis": "~4.0.4",
51
- "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
52
50
  "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
53
- "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2"
51
+ "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
52
+ "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
53
+ "@deepseek-ai/cordis": "~4.0.4"
54
54
  },
55
55
  "files": [
56
56
  "lib/index.js",
@@ -167,7 +167,7 @@ window.__ModuleLoader__.load({
167
167
  const SCROLLBAR_LINGER_MS = 2e3;
168
168
  /** Format complete-build metadata for the local brand badge. */
169
169
  function localBuildVersion() {
170
- return `0.1.7-rc.2-08040bb-dirty`;
170
+ return `0.1.7-rc.2-2020eb7` + ({}.DSH_CLIENT_GIT_DIRTY === "true" ? "-dirty" : "");
171
171
  }
172
172
  /** Each panel row subscribes only to its own selection state. */
173
173
  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/cordis": "~4.0.4",
28
- "@deepseek-ai/dsh-client-store": "0.1.7-rc.2"
27
+ "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
28
+ "@deepseek-ai/cordis": "~4.0.4"
29
29
  },
30
30
  "files": [
31
31
  "lib/index.js",
@@ -21,11 +21,11 @@
21
21
  en: be0e9f07314547a5
22
22
  zh: e55e8e668b3f703f
23
23
  /deepseek-ai-dsh-tui-app/use-this-package/the-screen:
24
- en: f46aab5ea9d40e5d
25
- zh: c2b21f7d6faa40a4
24
+ en: 28704cd17ca6b37d
25
+ zh: c091d14b798acccd
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
- en: 99188e75ab3d7d84
28
- zh: 4c1575148f12c16f
27
+ en: 86ee3c54b190bcb4
28
+ zh: c6f3fcc741afaca4
29
29
  /deepseek-ai-dsh-tui-app/use-this-package/subscription-sign-in:
30
30
  en: 7c1b0e685a3a9415
31
31
  zh: 49f3bdc3e99d6259
@@ -36,14 +36,14 @@
36
36
  en: 23ba736da2686f52
37
37
  zh: d30ce253dd934750
38
38
  /deepseek-ai-dsh-tui-app/use-this-package/configuration:
39
- en: fd5fdfa656307026
40
- zh: f9ef829fb17fcd3a
39
+ en: de84f025363b07e4
40
+ zh: 5004b1a0758c58ed
41
41
  /deepseek-ai-dsh-tui-app/understand-the-implementation:
42
42
  en: f124d406565fef39
43
43
  zh: 90344b5eec319cad
44
44
  /deepseek-ai-dsh-tui-app/understand-the-implementation/run-flow:
45
- en: 244caa693b65b28f
46
- zh: 20bd432745c5a9b1
45
+ en: 665ddb28f3987f02
46
+ zh: e8f89d93d7bc0fe9
47
47
  /deepseek-ai-dsh-tui-app/understand-the-implementation/rendering-model:
48
48
  en: 192d3daab8c51a4e
49
49
  zh: 7960dc941f40ccc5
@@ -51,8 +51,8 @@
51
51
  en: 142f04bf29e981dd
52
52
  zh: a1689297b06c9ca6
53
53
  /deepseek-ai-dsh-tui-app/understand-the-implementation/source-map:
54
- en: 6910be5a539fb133
55
- zh: b004b911c5757e6a
54
+ en: f6bd9e5b67b3652f
55
+ zh: cef041b9a91b245b
56
56
  /deepseek-ai-dsh-tui-app/understand-the-implementation/invariant-ownership:
57
57
  en: 0ddf6de8928026d5
58
58
  zh: 24feedcbb9e9d676
@@ -77,21 +77,21 @@
77
77
  /deepseek-ai-dsh-tui-app/model-experience/user-typed-shell-command/kv-cache-effect:
78
78
  en: 5b83189b640899dd
79
79
  zh: 232c1ef2f192bd4c
80
- /deepseek-ai-dsh-tui-app/model-experience/side-question:
81
- en: ac6516adff6e6ea3
82
- zh: 6ecac977743e7bee
83
- /deepseek-ai-dsh-tui-app/model-experience/side-question/what-the-model-sees:
84
- en: 87691f2e4225a1ba
85
- zh: 3b838561c2ac5fe2
86
- /deepseek-ai-dsh-tui-app/model-experience/side-question/token-effect:
87
- en: 5c6d016f2f7f1608
88
- zh: 3eb76252a08d51e9
89
- /deepseek-ai-dsh-tui-app/model-experience/side-question/kv-cache-effect:
90
- en: c3792aed799617f8
91
- zh: 4efaf1d8ae59ff5b
80
+ /deepseek-ai-dsh-tui-app/model-experience/side-agent:
81
+ en: 1c67a481715ccab3
82
+ zh: cb1ee722aa3b9201
83
+ /deepseek-ai-dsh-tui-app/model-experience/side-agent/what-the-model-sees:
84
+ en: be1f14f1a63ca2a8
85
+ zh: f5ee2a28d5f9443e
86
+ /deepseek-ai-dsh-tui-app/model-experience/side-agent/token-effect:
87
+ en: 71d22c1a8c9f5c95
88
+ zh: 53b5f823c817e09f
89
+ /deepseek-ai-dsh-tui-app/model-experience/side-agent/kv-cache-effect:
90
+ en: 1dadc4a2f1560eaa
91
+ zh: dc4697c269bc16b9
92
92
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work:
93
- en: 6f34cd31df3d1797
94
- zh: c7019e2aa9ed3dde
93
+ en: 6c5c2264668d24f7
94
+ zh: 025b0085b347b04d
95
95
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work/dev-note:
96
96
  en: 5629c6159cec997f
97
97
  zh: 17f2d7e1f96da7f1
@@ -40,9 +40,9 @@ On quit the app prints `dsh: session <id> saved; resume with: dsh --profile tui
40
40
 
41
41
  ### The screen
42
42
 
43
- Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, and each tool call is a card with a `◆` glyph coloured by status — yellow while it runs, green once done, red on failure — the bold tool name, the presenter headline in violet — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. The card appears when the model starts the call, its header first and its rows unrolling beneath it over about `toolRevealFrames` frames; the result rows unroll and float out the same way when the tool answers. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status-coloured `◆`, dim for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt and a compaction replacement are omitted. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use warm orange, links and inline code use violet, and quotes stay dim. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning and a tool card float out over the same duration: they appear at a lifted color and recede to the dim italic or palette colors they settle in; a card redrawn from persisted history carries no fade, and text that has settled is never dimmed again.
43
+ Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), and a prompt steered or injected into a turn that already had a model step draws dim on a darker band so it recedes behind the turn it joined, assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, and each tool call is a card with a status glyph — a yellow braille spinner while it runs, a green `◆` once done, a red `◆` on failure — the bold tool name, the presenter headline in violet — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. The card appears when the model starts the call, its header first and its rows unrolling beneath it over about `toolRevealFrames` frames; the result rows unroll and float out the same way when the tool answers. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status glyph, spinning while it runs and a dim `◆` for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt and a compaction replacement are omitted. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use warm orange, links and inline code use violet, and quotes stay dim. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning and a tool card float out over the same duration: they appear at a lifted color and recede to the dim italic or palette colors they settle in; a card redrawn from persisted history carries no fade, and text that has settled is never dimmed again.
44
44
 
45
- Below the transcript sit a spinner while the agent works — its label is `thinking` while the model reasons, `writing` while visible text arrives, or `calling <tool>` while a tool is streamed or still running, plus live `↑` send and `↓` receive tokens for the current model call, as compact `k` / `M` / `B` counts, growing as the stream arrives and settling on the provider usage chunk — any open prompt, a boxed follow-ups list while messages wait, an activity board of the open turn's todos and latest descendant line while either has a row — completed todo content scratched out and status glyphs colored green, yellow, or cyan, at most four todo rows then `+<n> more`, not a focus region, gone on `turn/end` and bind — the editor, the subagent panel, and the footer: a status bar that, unfocused, is one line built from both ends inward. The editor's caret is the terminal's own blinking bar: the app asks for that shape at start, gives your default back on quit, and draws no caret at all while the status bar or the panel holds the keyboard. The model and entry keys are colored; live turn, context, and todo facts use yellow, violet, and green. The model is anchored at the left edge and is never dropped — past 20 columns it falls back to the bare model name, and only a label still too wide for that is ellipsized — and the two keys that leave the input are anchored at the right edge as `Shift+↑ read · Shift+↓ status`, or `Shift+↑ select · Shift+↓ status` while follow-ups wait, narrowing to `Shift+↑↓ nav` and dropped below 40 columns. The key facts fill whatever middle is left, in bar order: effort (`effort default` when the selection leaves reasoning to the model), the running turn's elapsed time, the context window percentage, the todo counts, and the workspace path (shortened with `~` and `…/` when long). Every segment that middle cannot hold folds into a trailing `+N`, together with the segments the unfocused line never draws — the permission preset, token usage (session totals plus the in-flight call), the goal and plan-mode markers from the projection seam, and the count of pending attachments. Compaction and model-request retries appear as notices, the same facts the browser's markers carry.
45
+ Below the transcript sit a spinner while the agent works — its label, with a bright highlight sweeping across it, is `thinking` while the model reasons, `writing` while visible text arrives, or `calling <tool>` while a tool is streamed or still running, plus live `↑` send and `↓` receive tokens for the current model call, as compact `k` / `M` / `B` counts, growing as the stream arrives and settling on the provider usage chunk — any open prompt, a boxed follow-ups list while messages wait, an activity board of the open turn's todos and latest descendant line while either has a row — completed todo content scratched out and status glyphs colored green, yellow, or cyan, the in-progress one a spinner, at most four todo rows then `+<n> more`, not a focus region, gone on `turn/end` and bind — the editor, the subagent panel, and the footer: a status bar that, unfocused, is one line built from both ends inward. The editor's caret is the terminal's own blinking bar: the app asks for that shape at start, gives your default back on quit, and draws no caret at all while the status bar or the panel holds the keyboard. The model and entry keys are colored; live turn, context, and todo facts use yellow, violet, and green. The model is anchored at the left edge and is never dropped — past 20 columns it falls back to the bare model name, and only a label still too wide for that is ellipsized — and the two keys that leave the input are anchored at the right edge as `Shift+↑ read · Shift+↓ status`, or `Shift+↑ select · Shift+↓ status` while follow-ups wait, narrowing to `Shift+↑↓ nav` and dropped below 40 columns. The key facts fill whatever middle is left, in bar order: effort (`effort default` when the selection leaves reasoning to the model), the running turn's elapsed time, the context window percentage, the todo counts, and the workspace path (shortened with `~` and `…/` when long). Every segment that middle cannot hold folds into a trailing `+N`, together with the segments the unfocused line never draws — the permission preset, token usage (session totals plus the in-flight call), the goal and plan-mode markers from the projection seam, and the count of pending attachments. Compaction and model-request retries appear as notices, the same facts the browser's markers carry.
46
46
 
47
47
  While the keyboard walks the conversation a framed inspector is docked directly above the editor, and the frame is the mode: it is drawn exactly while the conversation holds the keyboard. Its top rule carries an inverse ` ● READ ` chip and the focused section's heading — the section's position among the navigable blocks, the turn it belongs to, and what the section is — as in `╭ ● READ ─ 3/12 · turn 2 · bash git status · result ─╮`. Under it the block's parts draw as a numbered wrapping strip like `← 1 call · [2 result] →` when the block has more than one, the held label bracketed as well as accented so the selection is legible with no color at all; then the section's own source rows, each closed by a `│ ` border on both sides and wrapped four columns narrower, folded at `focusPreviewLines` for every section kind — a system prompt and an injected context included — with `… <n> more rows · Ctrl+G reads it` under them. The bottom rule carries the keys the conversation answers, `↑↓ sections · ←→ parts · Space folds · Ctrl+G reader · Esc input`, narrowed to `↑↓ ←→ · Space folds · Esc input` and then to `Esc input` as the terminal loses columns.
48
48
 
@@ -52,10 +52,12 @@ The focused block is also marked where it stands, with a two-column gutter that
52
52
 
53
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 twelve ticks of `streamFadeStepMs`; a step of the conversation walk lifts the newly focused gutter for six; and a step along the bar lifts the selected label for eight. A new or status-changed activity-board todo row, and a replaced descendant line, float out on that tick the same way a tool card does; replay and `reducedMotion` draw the settled board. The reader arrives complete on the screen it owns, and what it newly shows floats out on that tick the way a tool card does: opening it and showing another turn float out the whole turn, and stepping the list to another section of the same turn floats out that section, over `streamFadeSteps` ticks; scrolling, live growth, and a rewrap float nothing out. 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 twelve ticks of `streamFadeStepMs`; a step of the conversation walk lifts the newly focused gutter for six; and a step along the bar lifts the selected label for eight. A new or status-changed activity-board todo row, and a replaced descendant line, float out on that tick the same way a tool card does; replay and `reducedMotion` draw the settled board. Running tool cards, folded subagent rows, and the in-progress todo cycle braille spinner frames on their own 80 ms tick, armed only while one of them is drawn; a card whose header has scrolled above the part of the screen the renderer can repaint draws the static `◆` from then on. The reader arrives complete on the screen it owns, and what it newly shows floats out on that tick the way a tool card does: opening it and showing another turn float out the whole turn, and stepping the list to another section of the same turn floats out that section, over `streamFadeSteps` ticks; scrolling, live growth, and a rewrap float nothing out. 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 opens · 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. `Enter` or `Right` on a readable row, like `Enter` on a readable `/subagents` row, opens that child as a subagent view: the terminal draws the child session in place of the bound one — its transcript, live stream, conversation walk, inspector, reader, and its own subagent panel — while the session it was entered from stays open. A resident child is read live, and any other is resumed. The entry's detail rows print as notices under `subagent <label> · Ctrl+P or /parent returns to session <id>`, the header ends on `◆ subagent view ›` with one `›` per level entered and `· Ctrl+P returns`, a shaded line directly above the input reads `◆ subagent view · main › <label> · Ctrl+P back to <parent>` for as long as the view is open, whatever the transcript has scrolled to, and `Ctrl+P` or `/parent` goes back one level, redrawing the parent from its log as it stands then. `/new`, `/clear`, `/resume`, `/sessions`, and `/fork` refuse while any session in that chain runs a turn, and otherwise release every view with the session they leave; quitting releases every view and saves the root session.
58
58
 
59
+ `/btw` opens a temporary side agent as a view over the session on screen, so the user can ask questions while that session's agent keeps working. The side agent is a new Agent seeded with every event the session has logged so far, an unfinished turn included: a tool call still waiting for its result gets the fork's error result, and reply text that is still streaming is not included. It runs on the session's last logged model, else its current selection, and it can only read: its session runs in the `read-only` sandbox mode with the `never` approval policy, so a write fails and cannot be approved, and it sees only the tools named in `btwTools`, plus the command tools in `btwSandboxedTools` when the command executor confines commands. Every other tool is hidden from it and refused if called. It runs its own turns: the question after `/btw` is its first prompt, and every line typed while it is on screen goes to it, `/btw <question>` included. The view is drawn like a subagent view: the header ends on `◆ btw side agent · Ctrl+P ends it and returns`, the shaded line above the input reads `◆ btw side agent · main › btw · Ctrl+P back to main`, and the transcript starts empty instead of repeating the inherited conversation. `Ctrl+P` or `/parent` ends the side agent, cancelling a turn it is running, and redraws the session it was opened from under `btw ended · back in session <id>`. The working session is only read: nothing is appended to its log, its inbox is untouched, and neither its subagent panel, `/subagents`, nor its model-facing subagent listing shows the side agent, which also cannot message it. An approval or question that a session held behind any view raises is shown on screen after `session <id>, behind this view, asks:` instead of being refused.
60
+
59
61
  ### Keys and commands
60
62
 
61
63
  The conversation, input, subagent panel, and status bar form the vertical arrow-key walk: `Down` at the newest section, `Up` on the subagent panel's first row, and `Up` on the status bar with no subagent panel drawn all land at the caret. The follow-ups list sits above the input; `Shift+Up` enters it while it is drawn, and it joins the `Tab` walk. The activity board sits between follow-ups and the input and is not a focus region. While a region other than the editor has the keyboard, `Tab` and `Shift+Tab` walk the regions that are drawn, wrapping at both ends; in the editor, `Tab` takes the offered completion and `Shift+Tab` opens the reasoning-effort picker. A printable key pressed in any of them returns to the input and types there, so a sentence started while reading lands where it was aimed; `Space` in the conversation is the one exception, and folds the marked tool card or context block. `Ctrl+G`, `Ctrl+O`, `Ctrl+T`, `Ctrl+P`, and `Ctrl+L` mean the same thing in every one of those regions, and `Ctrl+C` and `Ctrl+D` return the keyboard to the input before they act. A prompt and the reader own their whole key stream instead, and answer `Ctrl+C` by giving the keyboard back.
@@ -68,7 +70,7 @@ While the input has the keyboard:
68
70
  | `!command` / `!!command` | Run in this terminal; `!` is next-step context the next prompt can read, `!!` stays local |
69
71
  | `Shift+Enter` | Insert a newline |
70
72
  | `Ctrl+S` | While a turn runs, steer the editor text into the running turn's next step |
71
- | `Up` / `Down` | Recall earlier prompts |
73
+ | `Up` / `Down` | Recall earlier prompts; while follow-ups wait, `Up` on an empty input removes the newest follow-up into the editor, the same revision as `E` in the follow-ups panel |
72
74
  | `Shift+Left` / `Shift+Right` | Move one word left / right with pi-tui's editor navigation; from the end of `I want to do`, `Shift+Left` lands before `do` |
73
75
  | `Tab` | Take the completion the editor offers |
74
76
  | `Shift+Tab` | Open the current model's reasoning-effort picker for the next request, the same picker as empty `/effort` |
@@ -77,7 +79,7 @@ While the input has the keyboard:
77
79
  | `Ctrl+G` | Read the conversation full screen, on its newest section |
78
80
  | `Ctrl+O` | Expand or collapse every tool card and context row |
79
81
  | `Ctrl+T` | Browse the agent's todo list, the same list `/todos` opens |
80
- | `Ctrl+P` | Return from a subagent view to the session it was entered from, like `/parent` |
82
+ | `Ctrl+P` | Return from a subagent view to the session it was entered from, or end a `/btw` side agent, like `/parent` |
81
83
  | `Ctrl+L` | Redraw the whole screen from scratch |
82
84
  | `?` | On an empty input, list the commands and keys, like `/help`; inside a draft it is typed |
83
85
  | `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 |
@@ -188,12 +190,12 @@ Typing `/` at the start of the editor completes the terminal's own commands and
188
190
  | `/deliverables` | The files the agent presented, grouped by turn |
189
191
  | `/changes [turn]` | Browse the files the latest turn changed, or turn `turn`, with their line counts; `Enter` opens one file's turn-start to turn-end comparison |
190
192
  | `/subagents` | Browse the subagent sessions under this session; `Enter` opens a readable one as a subagent view and an unreadable one's details |
191
- | `/parent` | Return from a subagent view to the session it was entered from, like `Ctrl+P` |
193
+ | `/parent` | Return from a subagent view to the session it was entered from, or end a `/btw` side agent, like `Ctrl+P` |
192
194
  | `/settings [ns [path value]]` | List namespaces, show one, or set one field; `/settings reset <ns>` restores defaults |
193
195
  | `/plugins` | The composed plugins with enablement and lifecycle phase; `/plugins bundles` lists the profile's bundles, `/plugins enable <id>` and `/plugins disable <id>` switch a plugin entry or a bundle, `/plugins add <spec>` installs a bundle, `/plugins remove <name>` removes one |
194
196
  | `/tools` | Expand or collapse every tool card and context row, like `Ctrl+O` |
195
197
  | `/turns` | Read the conversation full screen, turns side by side, like `Ctrl+G` |
196
- | `/btw <question>` | Ask one side question about this session. The answer opens on its own page and is not added to the conversation; the running turn keeps going, and the question cannot use tools |
198
+ | `/btw <question>` | Open a temporary side agent with this session's context and ask it the question; it can use read-only tools, the session keeps working and never sees it, and `Ctrl+P` ends it. Inside the side agent, `/btw <question>` asks it another question |
197
199
  | `/quit`, `/exit` | Save the session and exit |
198
200
 
199
201
  Every other `/name` line goes to the shared command registry, so `/compact`, `/goal`, and plugin commands work as they do in the browser.
@@ -231,8 +233,10 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
231
233
  | `streamFadeStepMs` | `16` | One frame: the fade tick, the repaint period while anything is still moving, and the period paced stream text is drawn at; duration is `streamFadeSteps × streamFadeStepMs` |
232
234
  | `streamPaceFrames` | `8` | Frames a backlog of streamed reply text or tool arguments takes to reach the screen. Thinking still queued when its block ends, or when reply text or a tool call starts, is drawn at once; `0`, like `reducedMotion`, draws each delta as it arrives |
233
235
  | `toolRevealFrames` | `6` | Frames the rows of a tool card take to unroll when the card appears or its result lands, a share of the hidden rows per frame. Unfolding a card, and a card whose unrolling rows are above the part of the screen the renderer can repaint, draw every row at once; `0`, like `reducedMotion`, draws every row at once |
234
- | `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 |
236
+ | `reducedMotion` | `false` | Draw streamed text, streamed reasoning, tool cards, and the chrome in their settled colors, with no fade, no lift, no spinner glyph or shimmer, and no repeating repaint |
235
237
  | `openBrowser` | `true` | Hand marked authorization pages to the local default browser |
238
+ | `btwTools` | `read`, `read_image`, `glob`, `grep`, `web_search`, `web_fetch`, the `session_*` query tools, `skill`, the MCP resource readers, `ask_user_question` | Global tools a `/btw` side agent may call; names this composition does not register are skipped |
239
+ | `btwSandboxedTools` | `bash`, `pwsh` | Command tools a `/btw` side agent may call only when the command executor confines commands; they run in the `read-only` sandbox mode |
236
240
 
237
241
  `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.
238
242
 
@@ -248,7 +252,7 @@ The runner is a direct driver over the core API carrier, like `dsh-headless`, th
248
252
 
249
253
  ### Run flow
250
254
 
251
- The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with four operations: `create` makes one fresh persisted Agent with the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` takes the Agent write handle first and then observes the live Session through `ctx.sessionQuery` so bind draws every persisted event including resume closers, 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, and `observe` opens a subagent session without releasing the bound one — a resident subagent Agent is read live and its release does nothing, and any other session is resumed. Every operation except a resident `observe` installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request; `resume` passes the launch default as AgentOptions so assemble has a `{{model}}` value, then overlays the log's last request header onto the selection when one exists, else keeps that default. 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.
255
+ The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with five operations: `create` makes one fresh persisted Agent with the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` takes the Agent write handle first and then observes the live Session through `ctx.sessionQuery` so bind draws every persisted event including resume closers, 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, and `observe` opens a subagent session without releasing the bound one — a resident subagent Agent is read live and its release does nothing, and any other session is resumed, and `aside` creates a `/btw` side agent seeded through `buildForkSeed` with the bound session's whole log as `ctx.sessionQuery` observes it, recording `parentSession`, `isSeeded`, and `origin: 'subagent'` but passing no parent Agent and appending no catalog event to the parent, then in its setup appends the `read-only` sandbox mode and the `never` approval policy and restricts its global tools to the configured names. Every operation except a resident `observe` installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request; `resume` passes the launch default as AgentOptions so assemble has a `{{model}}` value, then overlays the log's last request header onto the selection when one exists, else keeps that default. 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 and for every session a view is held open over, 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.
252
256
 
253
257
  ### Rendering model
254
258
 
@@ -280,18 +284,18 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
280
284
  | [`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 |
281
285
  | [`src/reader.ts`](src/reader.ts) | The reader as plain data: its state, the intents keys become, its geometry, and the lines it draws |
282
286
  | [`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 |
283
- | [`src/btw.ts`](src/btw.ts) | `/btw`: one tool-free request built from the bound session's derived history, never logged |
284
- | [`src/btw-screen.ts`](src/btw-screen.ts) | The `/btw` answer page drawn on the alternate screen |
287
+ | [`src/btw.ts`](src/btw.ts) | `/btw`: the side agent's seed from the working session's whole log, its read-only tool and sandbox restriction, and its opening notice |
285
288
  | [`src/screen.ts`](src/screen.ts) | The main screen with the page margins every frame is laid out and drawn inside, 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 |
286
289
  | [`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 |
287
290
  | [`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 |
288
291
  | [`src/pace.ts`](src/pace.ts) | The stream pacer: the ordered queue between the assistant stream and the transcript, drained a backlog share per frame; and the row reveal that unrolls a tool card the same way |
289
292
  | [`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 |
293
+ | [`src/spinner.ts`](src/spinner.ts) | The braille spinner frames running glyphs cycle through and the shimmer the working spinner's label carries |
290
294
  | [`src/prompts.ts`](src/prompts.ts) | Approval, question, picker, and read-only detail prompts plus the modal queue |
291
295
  | [`src/toast.ts`](src/toast.ts) | The transient key-feedback line: its overlay, its clock, and the lines it carries |
292
296
  | [`src/transcript.ts`](src/transcript.ts) | Pure text folding of presentation views, usage, and turn-end reasons, the `$ command` span, and the one fold grammar every marker is written in |
293
297
  | [`src/diff.ts`](src/diff.ts) | Line diff, hunk selection, and the addition and removal marks diff cards box |
294
- | [`src/style.ts`](src/style.ts) | The palette, including the cool dark-mode heading and link hues a Markdown reply uses, the strikethrough role completed todo content uses, the background band a prompt is drawn on, the green and red fills and sign colours of a diff card's changed rows, and the derived pi-tui themes |
298
+ | [`src/style.ts`](src/style.ts) | The palette, including the cool dark-mode heading and link hues a Markdown reply uses, the strikethrough role completed todo content uses, the background band a prompt is drawn on and the darker one a steered or injected prompt is drawn on, the green and red fills and sign colours of a diff card's changed rows, and the derived pi-tui themes |
295
299
  | [`src/highlight.ts`](src/highlight.ts) | Syntax colour for fenced code, file rows, and shell commands: the grammars a block may load, the theme the background picks, and the SGR one token is drawn with |
296
300
  | [`src/completion.ts`](src/completion.ts) | Slash-command and `@`-reference completion for the editor |
297
301
  | [`src/editor.ts`](src/editor.ts) | The prompt editor's terminal caret, its `Shift+Left` / `Shift+Right` mapping to pi-tui word navigation, and syntax colour on a `!` / `!!` draft |
@@ -302,7 +306,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
302
306
  | [`src/queue-panel.ts`](src/queue-panel.ts) | The follow-ups list: pending-row glyphs, hanging wrap, and the enter-steer legend |
303
307
  | [`src/activity-board.ts`](src/activity-board.ts) | The activity board: todo glyphs, the completed scratch-out, the row cap, and the one-line descendant summary |
304
308
  | [`src/catalog.ts`](src/catalog.ts) | Rows for `/settings`, `/plugins`, `/subagents`, `/deliverables`, `/changes`, and `/outline`, and the `/plugins` management verbs |
305
- | [`src/view-banner.ts`](src/view-banner.ts) | The line above the input that names an open subagent view and the key back |
309
+ | [`src/view-banner.ts`](src/view-banner.ts) | The line above the input that names an open subagent view or `/btw` side agent and the key back |
306
310
  | [`src/todos.ts`](src/todos.ts) | The todo list: the status glyphs, the picker rows with completed content scratched out, and one item's detail rows |
307
311
  | [`cordis.patch.yml`](cordis.patch.yml) | The terminal patch over `dsh-base` |
308
312
  | — | No runtime invariant companion is published; the app registers listeners on one Agent and holds no mutable relation another observer could contradict. |
@@ -312,6 +316,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
312
316
  | [`tests/editor.spec.ts`](tests/editor.spec.ts) | The terminal caret, `Shift+Left` / `Shift+Right` word navigation, and `!` / `!!` draft colour against pi-tui's editor behavior |
313
317
  | [`tests/frame.spec.ts`](tests/frame.spec.ts) | The rules, the chip, the body rows, and the legend a width holds |
314
318
  | [`tests/motion.spec.ts`](tests/motion.spec.ts) | The motion clock's levels, its repaint demand, and the lift each level draws |
319
+ | [`tests/spinner.spec.ts`](tests/spinner.spec.ts) | Spinner frame steps and the shimmer's sweep, rest, and disabled-palette output |
315
320
  | [`tests/pace.spec.ts`](tests/pace.spec.ts) | The pacer's per-frame share, grapheme cuts, arrival order, flush, per-channel flush, and clear, and the row reveal's per-frame share, settle, and clamp |
316
321
  | [`tests/stream-pace.spec.ts`](tests/stream-pace.spec.ts) | Paced reply text and tool arguments in stream order, thinking drawn when its block ends, the flush at stream end and before a logged event, reduced motion, and tool cards unrolling on the frame tick |
317
322
  | [`tests/view-banner.spec.ts`](tests/view-banner.spec.ts) | The subagent-view line's trail, back target, width, and absence at the main session |
@@ -381,19 +386,19 @@ Conditional and retained: each `!` notice stays in conversation history for late
381
386
 
382
387
  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.
383
388
 
384
- ### Side question
389
+ ### Side agent
385
390
 
386
391
  #### What the model sees
387
392
 
388
- `/btw <question>` sends one extra request through `ctx.llm.stream` and does not append it to the session. The system text is fixed: the model answers one side question, is not the agent in the conversation, and cannot call tools or continue that agent's task. The messages are the bound session's derived history, the visible reply still streaming when there is one, and the question as the last user message. No tools are declared. The running turn is not steered, queued, or cancelled. The answer is drawn on the alternate screen. Text the main agent sees on its next step is unchanged.
393
+ The working agent's requests are unchanged by `/btw`. The side agent's requests declare only its allowed tools. They start with the working session's inherited history, including the fork's error results for tool calls without a logged result and the closers of an unfinished turn. A `tui-app` notice summarized as `btw · side agent` follows with fixed text: the conversation above belongs to a working agent that is still running; answer the user's questions; its tools are read-only, commands run in a read-only sandbox, and every write is refused and cannot be approved, so it describes a change instead of attempting it; do not continue the working agent's task or message it; and inherited tool calls that end in the fork's error may have finished in the working session. The user's question follows as an ordinary prompt, and later lines are ordinary prompts of the side agent's session.
389
394
 
390
395
  #### Token effect
391
396
 
392
- One additional model request per `/btw`. Nothing from that request or its answer is retained in later agent requests.
397
+ Each side agent request carries the inherited history plus the notice and the side agent's own turns. Nothing from the side agent reaches the working agent's requests.
393
398
 
394
399
  #### KV Cache effect
395
400
 
396
- The side request does not change the agent loop's system prompt, tool catalog, or conversation prefix.
401
+ The side agent uses the working session's last logged provider and model, but its tool catalog is the read-only subset, so a provider that caches the tool declarations ahead of the history recomputes the inherited history on the first side request; later side requests append to that prefix. The working agent's request prefix is unchanged.
397
402
 
398
403
  ## Known Limitations and Deferred Work
399
404
 
@@ -418,7 +423,7 @@ These limits describe the terminal surface as shipped; they are not a general CL
418
423
  - **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.
419
424
  - **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.
420
425
  - **Runs through the `dsh` launcher** — starting the profile another way fails at startup, because only the launcher can request the process exit.
421
- - **`/btw` is a terminal page, not a turn** — the answer is not stored in the session, Web has no `/btw`, and the request sees derived history plus the visible reply still streaming. Tool arguments that are not logged yet are absent. The page cannot run tools.
426
+ - **A `/btw` side agent is read-only by tool name and sandbox** — `btwTools` must name only tools that read, because the side agent shares the workspace with the working agent; a command tool can read anything the `read-only` sandbox mode allows, and without a confining command executor command tools are hidden. It inherits only what the working session has logged: reply text still streaming is absent. Its log is stored like a subagent session's and hidden from `/resume` and `/sessions`, and Web has no `/btw`.
422
427
  - **`!` 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.
423
428
 
424
429
  <a id="dev-note"></a>
@@ -40,9 +40,9 @@ dsh tui --no-open # print sign-in URLs without opening a
40
40
 
41
41
  ### 屏幕布局
42
42
 
43
- 每一帧都从终端左右两边各内缩一列绘制,因此对话记录与停靠的界面组件都不会有任何一行贴到两侧边缘。页眉在标题生成或设置后以标题命名会话,并在旁边显示 id。对话记录在终端自身的回滚区中增长:你的提示以 `❯` 开头,启用颜色时铺在一条通栏的着色背景带上(附件列在其下),assistant 的推理以暗色斜体显示在 `✻ Thinking` 标题之下、Markdown 回复上方,每次工具调用是一张卡片,含按状态着色的 `◆` 符号(运行中为黄色、完成为绿色、失败为红色)、粗体工具名、以紫色显示的呈现器标题(去掉呈现器重复写出的工具名,因此 `Read src/app.ts` 画成 `read src/app.ts`;shell 卡片取该次调用自身的摘要,绝不取命令,命令只由卡片的 `$` 行绘制一次)、运行中的一行加载标记,以及折叠到 `toolPreviewLines` 行的正文。卡片在模型开始调用时出现,先画标题,其下各行在约 `toolRevealFrames` 帧内逐行展开;工具回答后,结果行也以同样方式展开并浮出。`edit` 或 `write` diff 卡片把每一新增行整行铺满绿色背景、每一删除行整行铺满红色背景,删除的旧行在上、新增的新行在下,并把 `+` 与 `-` 画成各自更亮的颜色,使符号从填充色中读得出来;折行续行只延续填充色,不再画第二个符号;工具应用变更后,已应用的 hunk 取代调用时携带的 diff,并在每行前标出文件行号,新增行与未变行用新文件的行号,删除行用旧文件的行号。`subagent` 与 `subagent_*` 卡片折叠时只画一行,行首是同样按状态着色的 `◆`,交给后台的子 agent 则为暗色:运行中显示工具名、任务描述,以及调用指定的模型与 `background`;结束后描述变暗,右端标出 `[done]`,交给后台的子 agent 标 `[started]`,失败标 `[failed]`。在被标记的行上按 `Space`,或按 `Ctrl+O`,即可展开完整卡片。非空的系统提示词与每一条注入的上下文——instructions、catalogs、snapshots、notices、relays 与 recalls——绘制为暗色 `⬡` 标题,其下是面向模型文本的前 `contextPreviewLines` 行,快照的每一份贡献具名写在其自身各行上方;空的系统提示词与压缩替换则省略。承载的行数多于其绘制行数的工具卡片与上下文块,结尾都是同一条标记:该块被对话记录的焦点持有时为 `… <n> more rows · Space expands`,否则为 `… <n> more rows · Ctrl+O expands`。回复中的围栏代码、`read` 卡片的文件行、`edit` 或 `write` diff 卡片的变更行——其中 `+` 新增项标为绿色、`-` 删除项标为红色,符号后的源文本按文件扩展名对应的语言绘制——以及 `!` / `!!` 草稿、用户 shell 的 `$ command` 行(其 `$` 用强调色)与终端工具卡片中的 shell 命令,都使用语法高亮,配色主题由终端自身的背景在明暗之间选定;某种语言的语法会在第一个用到它的代码块出现时才加载,因此该块先以纯文本绘制、随后被重绘为彩色;这里没有对应语法的语言、既不支持 24 位也不支持 256 色的终端,以及 `codeHighlight: false`,都会把每个代码块画成纯文本。标题与列表标记使用暖橙色,链接与行内代码使用紫色,引用保持暗色。流式推理、回复文字与工具参数到达时先入队,再按帧(默认约每秒 60 帧)分批绘制,因此一次网络突发会分摊到 `streamPaceFrames` 帧里,而不是一次落下,队列也从不拖慢模型调用。流式回复文字会淡入,而且每个词各走各的时钟:一个词以接近终端背景色的亮度出现,并经 `streamFadeSteps` 次、每次 `streamFadeStepMs` 提亮到它最终稳定的颜色,因此流得更快只会留下更长的一串正在提亮的词,而不会更暗。流式推理与工具卡片在同一时长内浮出:它们以抬高的颜色出现,再退回到稳定时的暗色斜体或调色板颜色;从持久化历史重绘的卡片不带淡入,已经稳定下来的文字也不会再被调暗。
43
+ 每一帧都从终端左右两边各内缩一列绘制,因此对话记录与停靠的界面组件都不会有任何一行贴到两侧边缘。页眉在标题生成或设置后以标题命名会话,并在旁边显示 id。对话记录在终端自身的回滚区中增长:你的提示以 `❯` 开头,启用颜色时铺在一条通栏的着色背景带上(附件列在其下),而在已有模型步骤的轮次中被引导或注入的提示以暗色文字铺在更深的背景带上,退到它所加入的轮次之后,assistant 的推理以暗色斜体显示在 `✻ Thinking` 标题之下、Markdown 回复上方,每次工具调用是一张卡片,含状态符号(运行中为黄色的盲文旋转指示、完成为绿色 `◆`、失败为红色 `◆`)、粗体工具名、以紫色显示的呈现器标题(去掉呈现器重复写出的工具名,因此 `Read src/app.ts` 画成 `read src/app.ts`;shell 卡片取该次调用自身的摘要,绝不取命令,命令只由卡片的 `$` 行绘制一次)、运行中的一行加载标记,以及折叠到 `toolPreviewLines` 行的正文。卡片在模型开始调用时出现,先画标题,其下各行在约 `toolRevealFrames` 帧内逐行展开;工具回答后,结果行也以同样方式展开并浮出。`edit` 或 `write` diff 卡片把每一新增行整行铺满绿色背景、每一删除行整行铺满红色背景,删除的旧行在上、新增的新行在下,并把 `+` 与 `-` 画成各自更亮的颜色,使符号从填充色中读得出来;折行续行只延续填充色,不再画第二个符号;工具应用变更后,已应用的 hunk 取代调用时携带的 diff,并在每行前标出文件行号,新增行与未变行用新文件的行号,删除行用旧文件的行号。`subagent` 与 `subagent_*` 卡片折叠时只画一行,行首是同样的状态符号,运行中旋转,交给后台的子 agent 则为暗色 `◆`:运行中显示工具名、任务描述,以及调用指定的模型与 `background`;结束后描述变暗,右端标出 `[done]`,交给后台的子 agent 标 `[started]`,失败标 `[failed]`。在被标记的行上按 `Space`,或按 `Ctrl+O`,即可展开完整卡片。非空的系统提示词与每一条注入的上下文——instructions、catalogs、snapshots、notices、relays 与 recalls——绘制为暗色 `⬡` 标题,其下是面向模型文本的前 `contextPreviewLines` 行,快照的每一份贡献具名写在其自身各行上方;空的系统提示词与压缩替换则省略。承载的行数多于其绘制行数的工具卡片与上下文块,结尾都是同一条标记:该块被对话记录的焦点持有时为 `… <n> more rows · Space expands`,否则为 `… <n> more rows · Ctrl+O expands`。回复中的围栏代码、`read` 卡片的文件行、`edit` 或 `write` diff 卡片的变更行——其中 `+` 新增项标为绿色、`-` 删除项标为红色,符号后的源文本按文件扩展名对应的语言绘制——以及 `!` / `!!` 草稿、用户 shell 的 `$ command` 行(其 `$` 用强调色)与终端工具卡片中的 shell 命令,都使用语法高亮,配色主题由终端自身的背景在明暗之间选定;某种语言的语法会在第一个用到它的代码块出现时才加载,因此该块先以纯文本绘制、随后被重绘为彩色;这里没有对应语法的语言、既不支持 24 位也不支持 256 色的终端,以及 `codeHighlight: false`,都会把每个代码块画成纯文本。标题与列表标记使用暖橙色,链接与行内代码使用紫色,引用保持暗色。流式推理、回复文字与工具参数到达时先入队,再按帧(默认约每秒 60 帧)分批绘制,因此一次网络突发会分摊到 `streamPaceFrames` 帧里,而不是一次落下,队列也从不拖慢模型调用。流式回复文字会淡入,而且每个词各走各的时钟:一个词以接近终端背景色的亮度出现,并经 `streamFadeSteps` 次、每次 `streamFadeStepMs` 提亮到它最终稳定的颜色,因此流得更快只会留下更长的一串正在提亮的词,而不会更暗。流式推理与工具卡片在同一时长内浮出:它们以抬高的颜色出现,再退回到稳定时的暗色斜体或调色板颜色;从持久化历史重绘的卡片不带淡入,已经稳定下来的文字也不会再被调暗。
44
44
 
45
- 对话记录下方依次是 agent 工作时的旋转指示——其标签在模型推理时为 `thinking`,可见文本到达时为 `writing`,工具正在流出或仍在执行时为 `calling <tool>`,并带着当前这次模型调用的实时 `↑` 发送与 `↓` 接收 token,以紧凑的 `k` / `M` / `B` 计数,随数据流入增长,并在提供方的 usage 块到达后落定——任何打开的提示、有消息等待时的带框 follow-ups 列表、本轮 todo 与最新后代行的 activity board(有行时才绘制;已完成内容划掉,状态符号以绿色、黄色或青色显示,todo 最多四行其后 `+<n> more`,不是焦点区域,在 `turn/end` 与 bind 时消失)、编辑器、子 agent 面板,以及页脚:未聚焦时是一行由两端向内构建的状态栏。编辑器的光标是终端自身的闪烁竖条:应用在启动时请求这一形状,退出时把你的默认形状还回去,而状态栏或面板持有键盘期间完全不绘制光标。模型与入口按键带有颜色;进行中的轮次、上下文与 todo 信息分别使用黄色、紫色与绿色。模型锚定在左端且永不丢弃——超过 20 列时退回到裸模型名,只有仍然过宽的标签才会被省略号截断——离开编辑器的那两个按键则锚定在右端,写作 `Shift+↑ read · Shift+↓ status`,有 follow-ups 等待时则写作 `Shift+↑ select · Shift+↓ status`,窄到一定程度收缩为 `Shift+↑↓ nav`,不足 40 列时整体丢弃。关键事实填满剩下的中间部分,按状态栏顺序排列:推理强度(选择把推理交给模型时标为 `effort default`)、进行中轮次的已用时间、上下文窗口百分比、todo 计数,以及 workspace 路径(过长时以 `~` 与 `…/` 缩短)。中间部分容纳不下的每个分段都折进末尾的 `+N`,未聚焦行从不绘制的那些分段也一并折入——权限预设、token 用量(会话合计加上进行中的这次调用)、来自投影接缝的目标与计划模式标记,以及待发送附件的数量。压缩与模型请求重试以通知形式出现,与浏览器标记承载的事实相同。
45
+ 对话记录下方依次是 agent 工作时的旋转指示——其标签带着一道扫过的高亮,在模型推理时为 `thinking`,可见文本到达时为 `writing`,工具正在流出或仍在执行时为 `calling <tool>`,并带着当前这次模型调用的实时 `↑` 发送与 `↓` 接收 token,以紧凑的 `k` / `M` / `B` 计数,随数据流入增长,并在提供方的 usage 块到达后落定——任何打开的提示、有消息等待时的带框 follow-ups 列表、本轮 todo 与最新后代行的 activity board(有行时才绘制;已完成内容划掉,状态符号以绿色、黄色或青色显示,进行中的那一项为旋转指示,todo 最多四行其后 `+<n> more`,不是焦点区域,在 `turn/end` 与 bind 时消失)、编辑器、子 agent 面板,以及页脚:未聚焦时是一行由两端向内构建的状态栏。编辑器的光标是终端自身的闪烁竖条:应用在启动时请求这一形状,退出时把你的默认形状还回去,而状态栏或面板持有键盘期间完全不绘制光标。模型与入口按键带有颜色;进行中的轮次、上下文与 todo 信息分别使用黄色、紫色与绿色。模型锚定在左端且永不丢弃——超过 20 列时退回到裸模型名,只有仍然过宽的标签才会被省略号截断——离开编辑器的那两个按键则锚定在右端,写作 `Shift+↑ read · Shift+↓ status`,有 follow-ups 等待时则写作 `Shift+↑ select · Shift+↓ status`,窄到一定程度收缩为 `Shift+↑↓ nav`,不足 40 列时整体丢弃。关键事实填满剩下的中间部分,按状态栏顺序排列:推理强度(选择把推理交给模型时标为 `effort default`)、进行中轮次的已用时间、上下文窗口百分比、todo 计数,以及 workspace 路径(过长时以 `~` 与 `…/` 缩短)。中间部分容纳不下的每个分段都折进末尾的 `+N`,未聚焦行从不绘制的那些分段也一并折入——权限预设、token 用量(会话合计加上进行中的这次调用)、来自投影接缝的目标与计划模式标记,以及待发送附件的数量。压缩与模型请求重试以通知形式出现,与浏览器标记承载的事实相同。
46
46
 
47
47
  键盘在对话记录中移动时,编辑器正上方停靠着一个带边框的检视面板,边框即模式:它恰好在对话记录持有键盘时绘制。其顶边线带有一个反白的 ` ● READ ` 徽标与当前聚焦小节的标题——该小节在可导航块中的位置、所属轮次,以及这是哪一种小节——例如 `╭ ● READ ─ 3/12 · turn 2 · bash git status · result ─╮`。其下在块含多个部分时,把这些部分绘制成形如 `← 1 call · [2 result] →` 的带编号、会折行的选择行,被持有的标签除强调色外还加上方括号,因此完全无颜色时选择仍然可读;再往下是该小节自身的源文本行,每行左右两侧都由 `│ ` 边框闭合并按窄四列换行,对每一种小节——含系统提示词与注入的上下文——都折叠到 `focusPreviewLines` 行,其下写出 `… <n> more rows · Ctrl+G reads it`。底边线列出对话记录所应答的按键 `↑↓ sections · ←→ parts · Space folds · Ctrl+G reader · Esc input`,随着终端列数减少收缩为 `↑↓ ←→ · Space folds · Esc input`,再收缩为 `Esc input`。
48
48
 
@@ -52,10 +52,12 @@ dsh tui --no-open # print sign-in URLs without opening a
52
52
 
53
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 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮十二拍(每拍一个 `streamFadeStepMs`);对话记录走查中的一步把新聚焦的标记条抬亮六拍;状态栏上的一步把所选标签抬亮八拍。活动板上新出现或状态已变的 todo 行,以及被替换的后代行,也在同一时钟上像工具卡片一样浮出;重放与 `reducedMotion` 则画出已稳定的活动板。阅读器在自己占据的屏幕上一次性完整出现,而它新显示的内容会像工具卡片一样在同一时钟上浮出:打开它与显示另一个轮次时浮出整个轮次,在列表中步进到同一轮次的另一个小节时浮出该小节,历时 `streamFadeSteps` 拍;滚动、实时增长与重新换行都不浮出任何内容。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会把它们全部关闭,并且不为它们安排任何重绘。
55
+ 动效不止于流式文本,而且每种效果都乘着同一个淡入时钟。键盘落到对话记录、子 agent 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮十二拍(每拍一个 `streamFadeStepMs`);对话记录走查中的一步把新聚焦的标记条抬亮六拍;状态栏上的一步把所选标签抬亮八拍。活动板上新出现或状态已变的 todo 行,以及被替换的后代行,也在同一时钟上像工具卡片一样浮出;重放与 `reducedMotion` 则画出已稳定的活动板。运行中的工具卡片、折叠的子 agent 行与进行中的 todo 在各自的 80 ms 时钟上轮播盲文旋转帧,该时钟只在其中之一被绘制时才启动;标题行已滚动到渲染器可重绘区域之上的卡片自此画出静态的 `◆`。阅读器在自己占据的屏幕上一次性完整出现,而它新显示的内容会像工具卡片一样在同一时钟上浮出:打开它与显示另一个轮次时浮出整个轮次,在列表中步进到同一轮次的另一个小节时浮出该小节,历时 `streamFadeSteps` 拍;滚动、实时增长与重新换行都不浮出任何内容。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会把它们全部关闭,并且不为它们安排任何重绘。
56
56
 
57
57
  子 agent 面板在绑定会话之下有常驻的子 agent 会话、或列表中带有无法读取的候选者时绘制。未聚焦时它是一行摘要,含列出的数量与第一个子会话的关键标签;聚焦时其标题统计所列出的条目,并以它所应答的按键 `↑↓ children · Enter opens · 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>`。面板随其最后一行一同消失。在可读的行上按 `Enter` 或 `Right`,与在可读的 `/subagents` 行上按 `Enter` 一样,会把该子会话作为子 agent 视图打开:终端在已绑定会话的位置绘制子会话——其对话记录、实时流、对话记录走查、检查器、阅读器以及它自己的子 agent 面板——而进入它之前的会话保持打开。常驻的子会话被实时读取,其他子会话则被恢复。条目的详情行作为通知打印在 `subagent <label> · Ctrl+P or /parent returns to session <id>` 之下,页眉以 `◆ subagent view ›`(每进入一层一个 `›`)与 `· Ctrl+P returns` 结尾,只要视图打开,输入框正上方就有一条着色行写着 `◆ subagent view · main › <label> · Ctrl+P back to <parent>`,无论对话记录滚动到哪里,`Ctrl+P` 或 `/parent` 返回上一层,并按父会话此刻的日志重绘它。只要这条链中任一会话正在运行轮次,`/new`、`/clear`、`/resume`、`/sessions` 与 `/fork` 都会拒绝,否则它们会随所离开的会话释放每一个视图;退出会释放每一个视图并保存根会话。
58
58
 
59
+ `/btw` 在屏幕上的会话之上打开一个临时的旁路 agent 视图,让用户在该会话的 agent 继续工作时提问。旁路 agent 是一个新的 Agent,以该会话迄今记录的全部事件为种子,包括尚未结束的轮次:仍在等待结果的工具调用会得到分叉产生的错误结果,仍在流式输出的回复文本不包含在内。它使用该会话最后记录的模型(否则使用其当前选择),并且只能读取:它的会话运行在 `read-only` 沙箱模式与 `never` 审批策略下,因此写入会失败且无法获批;它只看得到 `btwTools` 中列出的工具,以及在命令执行器会约束命令时 `btwSandboxedTools` 中的命令工具。其他工具对它隐藏,被调用时也会被拒绝。它运行自己的轮次:`/btw` 之后的问题是它的第一条提示,它在屏幕上时输入的每一行都交给它,`/btw <question>` 也一样。该视图的绘制方式与子 agent 视图相同:页眉以 `◆ btw side agent · Ctrl+P ends it and returns` 结尾,输入框上方的着色行写着 `◆ btw side agent · main › btw · Ctrl+P back to main`,对话记录从空开始,而不是重复继承来的对话。`Ctrl+P` 或 `/parent` 结束旁路 agent(取消它正在运行的轮次),并在 `btw ended · back in session <id>` 之下重绘打开它之前的会话。工作中的会话只被读取:不向其日志追加任何内容,不触碰其收件箱,其子 agent 面板、`/subagents` 与面向模型的子 agent 列表都不显示旁路 agent,旁路 agent 也不能给它发消息。被任一视图挡在后面的会话发起的审批或提问,会在 `session <id>, behind this view, asks:` 之后显示在屏幕上,而不是被拒绝。
60
+
59
61
  ### 按键与命令
60
62
 
61
63
  对话记录、编辑器、子 agent 面板与状态栏构成垂直方向键走查:在最新小节上按 `Down`、在子 agent 面板第一行上按 `Up`、在没有绘制子 agent 面板时于状态栏上按 `Up`,都会落到光标处。follow-ups 列表位于输入框上方;绘制该列表时,`Shift+Up` 会进入它,它也加入 `Tab` 走查。activity board 位于 follow-ups 与输入之间,不是焦点区域。编辑器以外的区域持有键盘时,`Tab` 与 `Shift+Tab` 走遍已绘制的各区域,并在两端环绕;在编辑器中,`Tab` 采用给出的补全,`Shift+Tab` 打开推理强度选择器。在其中任何一个区域按下可打印键都会回到编辑器并在那里输入,因此在阅读时开始写的句子会落在它所指向的地方;对话记录中的 `Space` 是唯一的例外,它折叠被标记的工具卡片或上下文块。`Ctrl+G`、`Ctrl+O`、`Ctrl+T`、`Ctrl+P` 与 `Ctrl+L` 在这些区域中含义完全相同,而 `Ctrl+C` 与 `Ctrl+D` 会先把键盘交还编辑器再行动。提示与阅读器则各自持有整条按键流,并以交还键盘的方式应答 `Ctrl+C`。
@@ -68,7 +70,7 @@ dsh tui --no-open # print sign-in URLs without opening a
68
70
  | `!command` / `!!command` | 在本终端运行;`!` 会作为下一步上下文供下一条提示阅读,`!!` 只留在本地 |
69
71
  | `Shift+Enter` | 插入换行 |
70
72
  | `Ctrl+S` | 轮次进行中时,把编辑器文本引导(steer)进当前轮次的下一步 |
71
- | `Up` / `Down` | 调出先前的提示 |
73
+ | `Up` / `Down` | 调出先前的提示;有 follow-ups 等待时,在空输入上按 `Up` 会把最新的 follow-up 从队列移入编辑器,与 follow-ups 面板中的 `E` 是同一种修订 |
72
74
  | `Shift+Left` / `Shift+Right` | 用 pi-tui 的编辑器导航向左 / 右移动一个词;在 `I want to do` 末尾按 `Shift+Left` 会落在 `do` 之前 |
73
75
  | `Tab` | 采用编辑器给出的补全 |
74
76
  | `Shift+Tab` | 打开当前模型的推理强度选择器,从下一次请求生效;与空参数 `/effort` 打开的是同一个选择器 |
@@ -77,7 +79,7 @@ dsh tui --no-open # print sign-in URLs without opening a
77
79
  | `Ctrl+G` | 整屏读出对话记录,停在其最新小节 |
78
80
  | `Ctrl+O` | 展开或折叠所有工具卡片与上下文行 |
79
81
  | `Ctrl+T` | 浏览 agent 的 todo 列表,与 `/todos` 打开的是同一个列表 |
80
- | `Ctrl+P` | 从子 agent 视图返回进入它之前的会话,与 `/parent` 相同 |
82
+ | `Ctrl+P` | 从子 agent 视图返回进入它之前的会话,或结束 `/btw` 旁路 agent,与 `/parent` 相同 |
81
83
  | `Ctrl+L` | 从头重绘整个屏幕 |
82
84
  | `?` | 输入为空时列出命令与按键,与 `/help` 相同;在草稿中则作为文字输入 |
83
85
  | `Esc` | 取消正在运行的 `!`;在没有轮次进行且草稿以 `!` 开头时清空编辑器;否则装填停止,该提示仍在屏幕上时再按一次会停止正在进行的轮次 |
@@ -188,12 +190,12 @@ follow-ups 面板持有键盘时:
188
190
  | `/deliverables` | agent 交付的文件,按轮次分组 |
189
191
  | `/changes [turn]` | 浏览最近一轮(或第 `turn` 轮)改动的文件及其行数;`Enter` 打开某个文件从轮次开始到结束的对比 |
190
192
  | `/subagents` | 浏览本会话之下的子 agent 会话;`Enter` 把可读的会话作为子 agent 视图打开,对无法读取的会话则打开其详情 |
191
- | `/parent` | 从子 agent 视图返回进入它之前的会话,与 `Ctrl+P` 相同 |
193
+ | `/parent` | 从子 agent 视图返回进入它之前的会话,或结束 `/btw` 旁路 agent,与 `Ctrl+P` 相同 |
192
194
  | `/settings [ns [path value]]` | 列出命名空间、显示某一个或设置某个字段;`/settings reset <ns>` 恢复默认 |
193
195
  | `/plugins` | 已组合的插件及其启用状态与生命周期阶段;`/plugins bundles` 列出 profile 的组合包,`/plugins enable <id>` 与 `/plugins disable <id>` 切换某个插件条目或组合包,`/plugins add <spec>` 安装组合包,`/plugins remove <name>` 移除组合包 |
194
196
  | `/tools` | 像 `Ctrl+O` 一样展开或折叠所有工具卡片与上下文行 |
195
197
  | `/turns` | 像 `Ctrl+G` 一样整屏读出对话记录,各轮次并排 |
196
- | `/btw <question>` | 就本会话提一个旁边问题。答案打开在自己的页面上,不进入对话记录;正在进行的轮次继续,该问题也不能使用工具 |
198
+ | `/btw <question>` | 打开一个带有本会话上下文的临时旁路 agent 并向它提问;它可以使用只读工具,本会话继续工作且看不到它,`Ctrl+P` 结束它。在旁路 agent 中,`/btw <question>` 向它再提一个问题 |
197
199
  | `/quit`、`/exit` | 保存会话并退出 |
198
200
 
199
201
  其他每条 `/name` 行都交给共享命令注册表,因此 `/compact`、`/goal` 与插件命令的行为和浏览器中一致。
@@ -231,8 +233,10 @@ follow-ups 面板持有键盘时:
231
233
  | `streamFadeStepMs` | `16` | 一帧的时长:淡入或浮出的一拍、仍在变化时的重绘周期,也是逐帧绘制流式文字的周期;总时长为 `streamFadeSteps × streamFadeStepMs` |
232
234
  | `streamPaceFrames` | `8` | 积压的流式回复文字或工具参数要经过多少帧才全部上屏。思考块结束时,或回复文字或工具调用开始时,仍在队列中的思考立即画出;`0` 与 `reducedMotion` 一样,收到即绘制 |
233
235
  | `toolRevealFrames` | `6` | 工具卡片出现或其结果落下时,其各行展开所用的帧数,每帧展开隐藏行的一份。展开卡片,以及正在展开的行已位于渲染器可重绘范围之上的卡片,都会一次画出所有行;`0` 与 `reducedMotion` 一样,一次画出所有行 |
234
- | `reducedMotion` | `false` | 以稳定颜色绘制流式文本、流式推理、工具卡片与应用自身的边框装饰,不做淡入、不做抬亮,也不重复重绘 |
236
+ | `reducedMotion` | `false` | 以稳定颜色绘制流式文本、流式推理、工具卡片与应用自身的边框装饰,不做淡入、不做抬亮、没有旋转符号或扫光,也不重复重绘 |
235
237
  | `openBrowser` | `true` | 把被标记的授权页面交给本地默认浏览器 |
238
+ | `btwTools` | `read`、`read_image`、`glob`、`grep`、`web_search`、`web_fetch`、`session_*` 查询工具、`skill`、MCP 资源读取工具、`ask_user_question` | `/btw` 旁路 agent 可以调用的全局工具;本组合未注册的名称会被跳过 |
239
+ | `btwSandboxedTools` | `bash`、`pwsh` | 仅当命令执行器会约束命令时 `/btw` 旁路 agent 才可调用的命令工具;它们在 `read-only` 沙箱模式下运行 |
236
240
 
237
241
  `prompt`、`resume` 与 `openBrowser` 经启动提供方来自命令行;生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tui-app)是所有可接受字段的完整来源。
238
242
 
@@ -248,7 +252,7 @@ runner 与 `dsh-headless` 一样是核心 API 载体之上的直接驱动器,
248
252
 
249
253
  ### 运行流程
250
254
 
251
- runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含四个操作的会话宿主:`create` 用共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 先拿到 Agent 写句柄,再经 `ctx.sessionQuery` 观察实时 Session,使 bind 画出每条持久化事件(包括恢复时的闭合事件),`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent,`observe` 打开子 agent 会话而不释放已绑定的会话——常驻的子 agent Agent 被实时读取、释放它什么也不做,其他会话则被恢复。除常驻会话的 `observe` 外,每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求;`resume` 把启动默认作为 AgentOptions 传入,使组装时 `{{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` 运行;`!` 注入一条下一步通知,`!!` 只留在本地。
255
+ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含五个操作的会话宿主:`create` 用共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 先拿到 Agent 写句柄,再经 `ctx.sessionQuery` 观察实时 Session,使 bind 画出每条持久化事件(包括恢复时的闭合事件),`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent,`observe` 打开子 agent 会话而不释放已绑定的会话——常驻的子 agent Agent 被实时读取、释放它什么也不做,其他会话则被恢复,`aside` 创建 `/btw` 旁路 agent:它以 `buildForkSeed` 用 `ctx.sessionQuery` 观察到的已绑定会话完整日志作种子,记录 `parentSession`、`isSeeded` 与 `origin: 'subagent'`,但不传入父 Agent,也不向父会话追加目录事件,随后在其 setup 中追加 `read-only` 沙箱模式与 `never` 审批策略,并把它的全局工具限制为配置的名称。除常驻会话的 `observe` 外,每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求;`resume` 把启动默认作为 AgentOptions 传入,使组装时 `{{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` 运行;`!` 注入一条下一步通知,`!!` 只留在本地。
252
256
 
253
257
  ### 渲染模型
254
258
 
@@ -280,18 +284,18 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
280
284
  | [`src/frame.ts`](src/frame.ts) | 纯粹的画框:圆角边框线、反白的模式徽标、正文行,以及某个宽度容纳得下的按键提示级别 |
281
285
  | [`src/reader.ts`](src/reader.ts) | 作为纯数据的阅读器:其状态、按键变成的各个意图、其几何布局,以及它画出的各行 |
282
286
  | [`src/reader-screen.ts`](src/reader-screen.ts) | 画在备用屏幕上的阅读器面板:其按键映射,以及它把键盘留在何处 |
283
- | [`src/btw.ts`](src/btw.ts) | `/btw`:用已绑定会话的派生历史构造一次不带工具的请求,且不写入日志 |
284
- | [`src/btw-screen.ts`](src/btw-screen.ts) | 画在备用屏幕上的 `/btw` 答案页 |
287
+ | [`src/btw.ts`](src/btw.ts) | `/btw`:以工作会话的完整日志构造旁路 agent 的种子、其只读工具与沙箱限制,以及开场通知 |
285
288
  | [`src/screen.ts`](src/screen.ts) | 每一帧据以排版与绘制的页边距、在构建一帧与写出该帧之间带若干次结算的主屏幕、每次结算所依据的重绘窗口、每个块的重绘下界,以及把对话记录挡在终端之外的挂起 |
286
289
  | [`src/alt-screen.ts`](src/alt-screen.ts) | 终端的备用屏幕:接管它、在其上按绝对行址绘制,以及把对话记录自己的屏幕交还 |
287
290
  | [`src/fade.ts`](src/fade.ts) | 流式文本淡入与浮出:基于挂钟的尾部追踪器、块时钟与注册表、淡入亮度级别、浮出混合,以及对已渲染行的重新着色 |
288
291
  | [`src/pace.ts`](src/pace.ts) | 流式节拍器:助手流与对话记录之间的有序队列,每帧释放积压的一份;以及以同样方式展开工具卡片的逐行展开器 |
289
292
  | [`src/motion.ts`](src/motion.ts) | 边框装饰的动效时钟与其调用点所绘的三级抬亮:落键、小节步进与状态栏走查 |
293
+ | [`src/spinner.ts`](src/spinner.ts) | 运行中符号轮播的盲文旋转帧,以及工作旋转指示标签所带的扫光 |
290
294
  | [`src/prompts.ts`](src/prompts.ts) | 审批、提问、选择器与只读详情提示以及模态队列 |
291
295
  | [`src/toast.ts`](src/toast.ts) | 临时按键提示行:其浮层、其时钟,以及它承载的各条文字 |
292
296
  | [`src/transcript.ts`](src/transcript.ts) | 呈现视图、用量与轮次结束原因的纯文本折叠、`$ command` 的 span,以及每条标记共用的那一套折叠措辞 |
293
297
  | [`src/diff.ts`](src/diff.ts) | diff 卡片的行 diff、hunk 选择,以及卡片加框所依据的新增与删除标记 |
294
- | [`src/style.ts`](src/style.ts) | 调色板(含 Markdown 回复所用的暗色冷色阶标题与链接色、已完成 todo 内容所用的划线角色、提示所铺的背景带、diff 卡片变更行的绿色与红色填充及符号颜色)与派生的 pi-tui 主题 |
298
+ | [`src/style.ts`](src/style.ts) | 调色板(含 Markdown 回复所用的暗色冷色阶标题与链接色、已完成 todo 内容所用的划线角色、提示所铺的背景带与被引导或注入的提示所铺的更深背景带、diff 卡片变更行的绿色与红色填充及符号颜色)与派生的 pi-tui 主题 |
295
299
  | [`src/highlight.ts`](src/highlight.ts) | 围栏代码、文件行与 shell 命令的语法高亮:某个块可能加载的语法、由背景选定的配色主题,以及一个 token 所用的 SGR |
296
300
  | [`src/completion.ts`](src/completion.ts) | 编辑器的斜杠命令与 `@` 引用补全 |
297
301
  | [`src/editor.ts`](src/editor.ts) | 提示编辑器的终端光标、把 `Shift+Left` / `Shift+Right` 映射到 pi-tui 词导航的逻辑,以及 `!` / `!!` 草稿上的语法高亮 |
@@ -302,7 +306,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
302
306
  | [`src/queue-panel.ts`](src/queue-panel.ts) | follow-ups 列表:待处理行符号、悬挂换行与 enter-steer 图例 |
303
307
  | [`src/activity-board.ts`](src/activity-board.ts) | activity board:todo 状态符号、已完成内容划掉、行数上限,以及一行后代摘要 |
304
308
  | [`src/catalog.ts`](src/catalog.ts) | `/settings`、`/plugins`、`/subagents`、`/deliverables`、`/changes` 与 `/outline` 的行,以及 `/plugins` 的管理动作 |
305
- | [`src/view-banner.ts`](src/view-banner.ts) | 输入框上方标明已打开的子 agent 视图及返回按键的一行 |
309
+ | [`src/view-banner.ts`](src/view-banner.ts) | 输入框上方标明已打开的子 agent 视图或 `/btw` 旁路 agent 及返回按键的一行 |
306
310
  | [`src/todos.ts`](src/todos.ts) | todo 列表:状态符号、已完成内容划掉的选择器行与单个条目的详情行 |
307
311
  | [`cordis.patch.yml`](cordis.patch.yml) | 基于 `dsh-base` 的终端 patch |
308
312
  | — | 不发布运行时不变量伴随模块;应用只在一个 Agent 上注册监听器,不持有其他观察者可能与之矛盾的可变关系。 |
@@ -312,6 +316,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
312
316
  | [`tests/editor.spec.ts`](tests/editor.spec.ts) | 对照 pi-tui 编辑器行为验证终端光标、`Shift+Left` / `Shift+Right` 词导航,以及 `!` / `!!` 草稿着色 |
313
317
  | [`tests/frame.spec.ts`](tests/frame.spec.ts) | 边框线、徽标、正文行,以及某个宽度容纳得下的按键提示 |
314
318
  | [`tests/motion.spec.ts`](tests/motion.spec.ts) | 动效时钟的各个级别、它对重绘的要求,以及每一级所绘的抬亮 |
319
+ | [`tests/spinner.spec.ts`](tests/spinner.spec.ts) | 旋转帧的步进,以及扫光的扫过、停顿与调色板禁用时的输出 |
315
320
  | [`tests/pace.spec.ts`](tests/pace.spec.ts) | 节拍器的每帧份额、按字素切分、到达顺序、flush、按通道 flush 与 clear,以及逐行展开器的每帧份额、settle 与 clamp |
316
321
  | [`tests/stream-pace.spec.ts`](tests/stream-pace.spec.ts) | 按流顺序分批绘制的回复文字与工具参数,思考块结束时画出思考,流结束时与已记录事件前的 flush,reducedMotion,以及在帧节拍上展开的工具卡片 |
317
322
  | [`tests/view-banner.spec.ts`](tests/view-banner.spec.ts) | 子 agent 视图行的路径、返回目标、宽度,以及在主会话时不绘制 |
@@ -381,19 +386,19 @@ The user ran `<command>` in the terminal.
381
386
 
382
387
  在可复用的请求前缀之后只做追加式增长。该通知不改变系统提示或工具目录。`/model` 切换像在浏览器中一样开始新的请求序列。
383
388
 
384
- ### 旁边问题
389
+ ### 旁路 agent
385
390
 
386
391
  #### 模型看到什么
387
392
 
388
- `/btw <question>` 经 `ctx.llm.stream` 多发一次请求,且不写入会话。系统文本是固定的:模型回答一个旁边问题,不是对话里的那个 agent,也不能调用工具或继续该 agent 的任务。消息是已绑定会话的派生历史、仍在流式输出的可见回复(若有),以及作为最后一条用户消息的问题。不声明工具。正在进行的轮次不会被导向、入队或取消。答案画在备用屏幕上。主 agent 下一步看到的文本不变。
393
+ `/btw` 不改变工作中 agent 的请求。旁路 agent 的请求只声明它被允许的工具,并以工作会话继承来的历史开头,包括分叉为没有已记录结果的工具调用产生的错误结果,以及未结束轮次的收尾事件。随后是一条摘要为 `btw · side agent` 的 `tui-app` 通知,文本固定:上面的对话属于一个仍在运行的工作 agent;回答用户的问题;它的工具是只读的,命令在只读沙箱中运行,每次写入都会被拒绝且无法获批,因此它描述改动而不是尝试改动;不继续工作 agent 的任务,也不给它发消息;以分叉错误结束的继承工具调用可能已在工作会话中完成。用户的问题随后作为普通提示出现,之后的各行都是旁路 agent 会话的普通提示。
389
394
 
390
395
  #### Token 影响
391
396
 
392
- 每次 `/btw` 多一次模型请求。该请求及其答案都不会留在之后的 agent 请求中。
397
+ 旁路 agent 的每次请求都携带继承的历史、该通知以及旁路 agent 自己的轮次。旁路 agent 的任何内容都不会进入工作 agent 的请求。
393
398
 
394
399
  #### KV Cache 影响
395
400
 
396
- 旁边请求不改变 agent 循环的系统提示、工具目录或对话前缀。
401
+ 旁路 agent 使用工作会话最后记录的 provider 与模型,但它的工具目录是只读子集,因此把工具声明缓存在历史之前的 provider 会在第一次旁路请求时重新计算继承的历史;之后的旁路请求追加在该前缀之后。工作 agent 的请求前缀不变。
397
402
 
398
403
  ## 已知限制与延期工作
399
404
 
@@ -418,7 +423,7 @@ The user ran `<command>` in the terminal.
418
423
  - **淡入需要终端的应答**——其亮度级别由终端对启动时发出的查询所报告的背景色构建,因此保持沉默、或既不编码真彩色也不编码 256 色的终端只会得到两级的暗淡模式;`NO_COLOR`、被禁用的调色板、`TERM=dumb` 与 `reducedMotion` 会完全关闭每一种淡入与每一种边框抬亮,临时提示行届时在保持结束时直接消失,而不是淡出。
419
424
  - **终端自身的光标可能闪烁**——编辑器不绘制自己的光标,应用打开终端光标,而 pi-tui 会在其重绘的各行之间移动它;不支持 pi-tui 为一帧包裹的同步输出序列的终端可能显示出这种移动。
420
425
  - **通过 `dsh` 启动器运行**——以其他方式启动该 profile 会在启动时失败,因为只有启动器能请求进程退出。
421
- - **`/btw` 是终端页面,不是一轮**——答案不写入会话,Web 没有 `/btw`,请求看到的是派生历史加上仍在流式输出的可见回复。尚未写入日志的工具参数不在其中。该页面不能运行工具。
426
+ - **`/btw` 旁路 agent 靠工具名称与沙箱保持只读**——`btwTools` 只能列出读取类工具,因为旁路 agent 与工作 agent 共享工作区;命令工具可以读取 `read-only` 沙箱模式允许的任何内容,而没有会约束命令的执行器时命令工具会被隐藏。它只继承工作会话已记录的内容:仍在流式输出的回复文本不在其中。它的日志像子 agent 会话一样被存储,并在 `/resume` 与 `/sessions` 中隐藏,Web 没有 `/btw`。
422
427
  - **`!` 是一次性的,也不是 TTY**——每一行都是一次新的 `ctx.shell.run`;没有持久 shell,也不能跑交互式程序。Web 编辑器不拦截 `!`。命令行上的可选首条提示始终是用户消息。
423
428
 
424
429
  <a id="dev-note"></a>