@songtonyli/dsh-cli 0.1.45 → 0.1.46

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.46; `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.46 (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-code-language": "0.1.7-rc.2",
52
+ "@deepseek-ai/dsh-util-workspace-path": "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-641e6a1` + ({}.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
@@ -56,6 +56,8 @@ Motion reaches past streamed text, and every effect rides the same fade tick. Th
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.
@@ -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.
@@ -233,6 +235,8 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
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
236
  | `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 |
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,8 +284,7 @@ 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 |
@@ -302,7 +305,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
302
305
  | [`src/queue-panel.ts`](src/queue-panel.ts) | The follow-ups list: pending-row glyphs, hanging wrap, and the enter-steer legend |
303
306
  | [`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
307
  | [`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 |
308
+ | [`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
309
  | [`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
310
  | [`cordis.patch.yml`](cordis.patch.yml) | The terminal patch over `dsh-base` |
308
311
  | — | No runtime invariant companion is published; the app registers listeners on one Agent and holds no mutable relation another observer could contradict. |
@@ -381,19 +384,19 @@ Conditional and retained: each `!` notice stays in conversation history for late
381
384
 
382
385
  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
386
 
384
- ### Side question
387
+ ### Side agent
385
388
 
386
389
  #### What the model sees
387
390
 
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.
391
+ 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
392
 
390
393
  #### Token effect
391
394
 
392
- One additional model request per `/btw`. Nothing from that request or its answer is retained in later agent requests.
395
+ 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
396
 
394
397
  #### KV Cache effect
395
398
 
396
- The side request does not change the agent loop's system prompt, tool catalog, or conversation prefix.
399
+ 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
400
 
398
401
  ## Known Limitations and Deferred Work
399
402
 
@@ -418,7 +421,7 @@ These limits describe the terminal surface as shipped; they are not a general CL
418
421
  - **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
422
  - **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
423
  - **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.
424
+ - **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
425
  - **`!` 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
426
 
424
427
  <a id="dev-note"></a>
@@ -56,6 +56,8 @@ dsh tui --no-open # print sign-in URLs without opening a
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`。
@@ -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` 与插件命令的行为和浏览器中一致。
@@ -233,6 +235,8 @@ follow-ups 面板持有键盘时:
233
235
  | `toolRevealFrames` | `6` | 工具卡片出现或其结果落下时,其各行展开所用的帧数,每帧展开隐藏行的一份。展开卡片,以及正在展开的行已位于渲染器可重绘范围之上的卡片,都会一次画出所有行;`0` 与 `reducedMotion` 一样,一次画出所有行 |
234
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,8 +284,7 @@ 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) | 流式文本淡入与浮出:基于挂钟的尾部追踪器、块时钟与注册表、淡入亮度级别、浮出混合,以及对已渲染行的重新着色 |
@@ -302,7 +305,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
302
305
  | [`src/queue-panel.ts`](src/queue-panel.ts) | follow-ups 列表:待处理行符号、悬挂换行与 enter-steer 图例 |
303
306
  | [`src/activity-board.ts`](src/activity-board.ts) | activity board:todo 状态符号、已完成内容划掉、行数上限,以及一行后代摘要 |
304
307
  | [`src/catalog.ts`](src/catalog.ts) | `/settings`、`/plugins`、`/subagents`、`/deliverables`、`/changes` 与 `/outline` 的行,以及 `/plugins` 的管理动作 |
305
- | [`src/view-banner.ts`](src/view-banner.ts) | 输入框上方标明已打开的子 agent 视图及返回按键的一行 |
308
+ | [`src/view-banner.ts`](src/view-banner.ts) | 输入框上方标明已打开的子 agent 视图或 `/btw` 旁路 agent 及返回按键的一行 |
306
309
  | [`src/todos.ts`](src/todos.ts) | todo 列表:状态符号、已完成内容划掉的选择器行与单个条目的详情行 |
307
310
  | [`cordis.patch.yml`](cordis.patch.yml) | 基于 `dsh-base` 的终端 patch |
308
311
  | — | 不发布运行时不变量伴随模块;应用只在一个 Agent 上注册监听器,不持有其他观察者可能与之矛盾的可变关系。 |
@@ -381,19 +384,19 @@ The user ran `<command>` in the terminal.
381
384
 
382
385
  在可复用的请求前缀之后只做追加式增长。该通知不改变系统提示或工具目录。`/model` 切换像在浏览器中一样开始新的请求序列。
383
386
 
384
- ### 旁边问题
387
+ ### 旁路 agent
385
388
 
386
389
  #### 模型看到什么
387
390
 
388
- `/btw <question>` 经 `ctx.llm.stream` 多发一次请求,且不写入会话。系统文本是固定的:模型回答一个旁边问题,不是对话里的那个 agent,也不能调用工具或继续该 agent 的任务。消息是已绑定会话的派生历史、仍在流式输出的可见回复(若有),以及作为最后一条用户消息的问题。不声明工具。正在进行的轮次不会被导向、入队或取消。答案画在备用屏幕上。主 agent 下一步看到的文本不变。
391
+ `/btw` 不改变工作中 agent 的请求。旁路 agent 的请求只声明它被允许的工具,并以工作会话继承来的历史开头,包括分叉为没有已记录结果的工具调用产生的错误结果,以及未结束轮次的收尾事件。随后是一条摘要为 `btw · side agent` 的 `tui-app` 通知,文本固定:上面的对话属于一个仍在运行的工作 agent;回答用户的问题;它的工具是只读的,命令在只读沙箱中运行,每次写入都会被拒绝且无法获批,因此它描述改动而不是尝试改动;不继续工作 agent 的任务,也不给它发消息;以分叉错误结束的继承工具调用可能已在工作会话中完成。用户的问题随后作为普通提示出现,之后的各行都是旁路 agent 会话的普通提示。
389
392
 
390
393
  #### Token 影响
391
394
 
392
- 每次 `/btw` 多一次模型请求。该请求及其答案都不会留在之后的 agent 请求中。
395
+ 旁路 agent 的每次请求都携带继承的历史、该通知以及旁路 agent 自己的轮次。旁路 agent 的任何内容都不会进入工作 agent 的请求。
393
396
 
394
397
  #### KV Cache 影响
395
398
 
396
- 旁边请求不改变 agent 循环的系统提示、工具目录或对话前缀。
399
+ 旁路 agent 使用工作会话最后记录的 provider 与模型,但它的工具目录是只读子集,因此把工具声明缓存在历史之前的 provider 会在第一次旁路请求时重新计算继承的历史;之后的旁路请求追加在该前缀之后。工作 agent 的请求前缀不变。
397
400
 
398
401
  ## 已知限制与延期工作
399
402
 
@@ -418,7 +421,7 @@ The user ran `<command>` in the terminal.
418
421
  - **淡入需要终端的应答**——其亮度级别由终端对启动时发出的查询所报告的背景色构建,因此保持沉默、或既不编码真彩色也不编码 256 色的终端只会得到两级的暗淡模式;`NO_COLOR`、被禁用的调色板、`TERM=dumb` 与 `reducedMotion` 会完全关闭每一种淡入与每一种边框抬亮,临时提示行届时在保持结束时直接消失,而不是淡出。
419
422
  - **终端自身的光标可能闪烁**——编辑器不绘制自己的光标,应用打开终端光标,而 pi-tui 会在其重绘的各行之间移动它;不支持 pi-tui 为一帧包裹的同步输出序列的终端可能显示出这种移动。
420
423
  - **通过 `dsh` 启动器运行**——以其他方式启动该 profile 会在启动时失败,因为只有启动器能请求进程退出。
421
- - **`/btw` 是终端页面,不是一轮**——答案不写入会话,Web 没有 `/btw`,请求看到的是派生历史加上仍在流式输出的可见回复。尚未写入日志的工具参数不在其中。该页面不能运行工具。
424
+ - **`/btw` 旁路 agent 靠工具名称与沙箱保持只读**——`btwTools` 只能列出读取类工具,因为旁路 agent 与工作 agent 共享工作区;命令工具可以读取 `read-only` 沙箱模式允许的任何内容,而没有会约束命令的执行器时命令工具会被隐藏。它只继承工作会话已记录的内容:仍在流式输出的回复文本不在其中。它的日志像子 agent 会话一样被存储,并在 `/resume` 与 `/sessions` 中隐藏,Web 没有 `/btw`。
422
425
  - **`!` 是一次性的,也不是 TTY**——每一行都是一次新的 `ctx.shell.run`;没有持久 shell,也不能跑交互式程序。Web 编辑器不拦截 `!`。命令行上的可选首条提示始终是用户消息。
423
426
 
424
427
  <a id="dev-note"></a>