@songtonyli/dsh-cli 0.1.57 → 0.1.59

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.
Files changed (139) hide show
  1. package/README.md +1 -1
  2. package/bin/dsh.mjs +1 -1
  3. package/node_modules/@deepseek-ai/dsh-agent-preset/skills/cordis-composition-reference/references/packages.md +1 -0
  4. package/node_modules/@deepseek-ai/dsh-api-session-controller/lib/client.js +1 -0
  5. package/node_modules/@deepseek-ai/dsh-client-ui-primitives/package.json +2 -2
  6. package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
  7. package/node_modules/@deepseek-ai/dsh-client-ui-slots/package.json +2 -2
  8. package/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js +59 -4
  9. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.i18n.yaml +73 -0
  10. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.md +166 -0
  11. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/README.zh.md +166 -0
  12. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/exec-shim.js +227 -0
  13. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/lib/index.js +704 -0
  14. package/node_modules/@deepseek-ai/dsh-sandbox-apple-container/package.json +62 -0
  15. package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.i18n.yaml +2 -2
  16. package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.md +1 -1
  17. package/node_modules/@deepseek-ai/dsh-sandbox-policy/README.zh.md +1 -1
  18. package/node_modules/@deepseek-ai/dsh-sandbox-policy/lib/index.js +23 -0
  19. package/node_modules/@deepseek-ai/dsh-session/lib/index.js +1 -0
  20. package/node_modules/@deepseek-ai/dsh-session/lib/types/known-event-types.js +1 -0
  21. package/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/worker.cjs +1 -0
  22. package/node_modules/@deepseek-ai/dsh-system-prompt/lib/index.js +1 -0
  23. package/node_modules/@deepseek-ai/dsh-tool-cordis/lib/types/api-catalog.js +22 -0
  24. package/node_modules/@deepseek-ai/dsh-tool-fs/README.i18n.yaml +2 -2
  25. package/node_modules/@deepseek-ai/dsh-tool-fs/README.md +1 -1
  26. package/node_modules/@deepseek-ai/dsh-tool-fs/README.zh.md +1 -1
  27. package/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js +24 -0
  28. package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.i18n.yaml +4 -4
  29. package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.md +2 -2
  30. package/node_modules/@deepseek-ai/dsh-tool-fs-search/README.zh.md +2 -2
  31. package/node_modules/@deepseek-ai/dsh-tool-fs-search/lib/index.js +28 -3
  32. package/node_modules/@deepseek-ai/dsh-tool-fs-search/package.json +7 -2
  33. package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.i18n.yaml +2 -2
  34. package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.md +1 -1
  35. package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/README.zh.md +1 -1
  36. package/node_modules/@deepseek-ai/dsh-tool-str-replace-editor/lib/index.js +14 -6
  37. package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +6 -6
  38. package/node_modules/@deepseek-ai/dsh-tui-app/README.md +6 -5
  39. package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +6 -5
  40. package/node_modules/@deepseek-ai/dsh-tui-app/cordis.patch.yml +20 -0
  41. package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +42 -31
  42. package/node_modules/@deepseek-ai/dsh-tui-app/package.json +1 -0
  43. package/node_modules/@deepseek-ai/libreoffice-kit/README.md +20 -5
  44. package/node_modules/@deepseek-ai/libreoffice-kit/README.zh.md +21 -6
  45. package/node_modules/@deepseek-ai/libreoffice-kit/lib/cli.js +499 -253
  46. package/node_modules/@deepseek-ai/libreoffice-kit/lib/font-snapshot-worker.js +37 -26
  47. package/node_modules/@deepseek-ai/libreoffice-kit/lib/index.js +498 -252
  48. package/node_modules/@deepseek-ai/libreoffice-kit/lib/worker.js +39 -13
  49. package/node_modules/@deepseek-ai/libreoffice-kit/package.json +5 -3
  50. package/node_modules/@earendil-works/pi-ai/README.md +4 -3
  51. package/node_modules/@earendil-works/pi-ai/dist/api/anthropic-messages.js +117 -18
  52. package/node_modules/@earendil-works/pi-ai/dist/api/bedrock-converse-stream.js +1 -0
  53. package/node_modules/@earendil-works/pi-ai/dist/api/constrained-sampling.js +19 -8
  54. package/node_modules/@earendil-works/pi-ai/dist/api/mistral-conversations.js +1 -0
  55. package/node_modules/@earendil-works/pi-ai/dist/api/openai-completions.js +1 -0
  56. package/node_modules/@earendil-works/pi-ai/dist/api/openai-responses-shared.js +1 -0
  57. package/node_modules/@earendil-works/pi-ai/dist/api/pi-messages.js +2 -0
  58. package/node_modules/@earendil-works/pi-ai/dist/env-api-keys.js +5 -0
  59. package/node_modules/@earendil-works/pi-ai/dist/providers/anthropic.js +24 -2
  60. package/node_modules/@earendil-works/pi-ai/dist/providers/data/.manifest.json +1 -1
  61. package/node_modules/@earendil-works/pi-ai/dist/providers/data/amazon-bedrock.json +1 -1
  62. package/node_modules/@earendil-works/pi-ai/dist/providers/data/azure-openai-responses.json +1 -1
  63. package/node_modules/@earendil-works/pi-ai/dist/providers/data/baseten.json +1 -1
  64. package/node_modules/@earendil-works/pi-ai/dist/providers/data/cerebras.json +1 -1
  65. package/node_modules/@earendil-works/pi-ai/dist/providers/data/github-copilot.json +1 -1
  66. package/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json +1 -1
  67. package/node_modules/@earendil-works/pi-ai/dist/providers/data/opencode.json +1 -1
  68. package/node_modules/@earendil-works/pi-ai/dist/providers/data/openrouter.json +1 -1
  69. package/node_modules/@earendil-works/pi-ai/dist/providers/data/radius.json +1 -1
  70. package/node_modules/@earendil-works/pi-ai/dist/providers/data/vercel-ai-gateway.json +1 -1
  71. package/node_modules/@earendil-works/pi-ai/dist/utils/overflow.js +2 -1
  72. package/node_modules/@earendil-works/pi-ai/dist/utils/provider-retry.js +3 -2
  73. package/node_modules/@earendil-works/pi-ai/package.json +6 -2
  74. package/node_modules/@earendil-works/pi-telemetry/package.json +1 -1
  75. package/node_modules/@shikijs/core/dist/index.mjs +15 -12
  76. package/node_modules/@shikijs/core/package.json +4 -4
  77. package/node_modules/@shikijs/engine-javascript/dist/engine-compile.mjs +2 -4
  78. package/node_modules/@shikijs/engine-javascript/dist/engine-raw.mjs +2 -4
  79. package/node_modules/@shikijs/engine-javascript/dist/index.mjs +1 -1
  80. package/node_modules/@shikijs/engine-javascript/dist/string-TLTPtCPs.mjs +115 -0
  81. package/node_modules/@shikijs/engine-javascript/package.json +3 -3
  82. package/node_modules/@shikijs/engine-oniguruma/package.json +3 -3
  83. package/node_modules/@shikijs/langs/dist/ada.mjs +1 -1
  84. package/node_modules/@shikijs/langs/dist/ahk.mjs +1 -1
  85. package/node_modules/@shikijs/langs/dist/beancount.mjs +1 -1
  86. package/node_modules/@shikijs/langs/dist/coq.mjs +1 -1
  87. package/node_modules/@shikijs/langs/dist/csharp.mjs +1 -1
  88. package/node_modules/@shikijs/langs/dist/css.mjs +1 -1
  89. package/node_modules/@shikijs/langs/dist/dart.mjs +1 -1
  90. package/node_modules/@shikijs/langs/dist/dotenv.mjs +1 -1
  91. package/node_modules/@shikijs/langs/dist/emacs-lisp.mjs +1 -1
  92. package/node_modules/@shikijs/langs/dist/gn.mjs +1 -1
  93. package/node_modules/@shikijs/langs/dist/handlebars.mjs +1 -1
  94. package/node_modules/@shikijs/langs/dist/julia.mjs +1 -1
  95. package/node_modules/@shikijs/langs/dist/latex.mjs +1 -1
  96. package/node_modules/@shikijs/langs/dist/luau.mjs +1 -1
  97. package/node_modules/@shikijs/langs/dist/marko.mjs +1 -1
  98. package/node_modules/@shikijs/langs/dist/moonbit.mjs +1 -1
  99. package/node_modules/@shikijs/langs/dist/nextflow-groovy.mjs +1 -1
  100. package/node_modules/@shikijs/langs/dist/nextflow.mjs +1 -1
  101. package/node_modules/@shikijs/langs/dist/nushell.mjs +1 -1
  102. package/node_modules/@shikijs/langs/dist/php.mjs +1 -1
  103. package/node_modules/@shikijs/langs/dist/powershell.mjs +1 -1
  104. package/node_modules/@shikijs/langs/dist/ruby.mjs +1 -1
  105. package/node_modules/@shikijs/langs/dist/rust.mjs +1 -1
  106. package/node_modules/@shikijs/langs/dist/sql.mjs +1 -1
  107. package/node_modules/@shikijs/langs/dist/svelte.mjs +1 -1
  108. package/node_modules/@shikijs/langs/dist/twig.mjs +3 -3
  109. package/node_modules/@shikijs/langs/dist/typespec.mjs +1 -1
  110. package/node_modules/@shikijs/langs/package.json +3 -3
  111. package/node_modules/@shikijs/primitive/dist/index.mjs +2 -1
  112. package/node_modules/@shikijs/primitive/package.json +3 -3
  113. package/node_modules/@shikijs/themes/dist/monokai.mjs +1 -1
  114. package/node_modules/@shikijs/themes/dist/one-dark-pro.mjs +1 -1
  115. package/node_modules/@shikijs/themes/dist/red.mjs +1 -1
  116. package/node_modules/@shikijs/themes/dist/solarized-dark.mjs +1 -1
  117. package/node_modules/@shikijs/themes/dist/solarized-light.mjs +1 -1
  118. package/node_modules/@shikijs/themes/package.json +3 -3
  119. package/node_modules/@shikijs/types/package.json +1 -1
  120. package/node_modules/@smithy/core/dist-cjs/submodules/client/index.js +33 -11
  121. package/node_modules/@smithy/core/dist-cjs/submodules/schema/index.js +3 -0
  122. package/node_modules/@smithy/core/dist-es/submodules/client/smithy-client/exceptions.js +33 -11
  123. package/node_modules/@smithy/core/dist-es/submodules/schema/TypeRegistry.js +3 -0
  124. package/node_modules/@smithy/core/package.json +1 -1
  125. package/node_modules/node-addon-native-custom-loader/lib/index.js +23 -10
  126. package/node_modules/node-addon-native-custom-loader/package.json +6 -1
  127. package/node_modules/node-addon-require-builtin/package.json +7 -2
  128. package/node_modules/powershell-utils/index.js +40 -19
  129. package/node_modules/powershell-utils/package.json +1 -1
  130. package/node_modules/powershell-utils/readme.md +69 -13
  131. package/node_modules/shiki/package.json +10 -10
  132. package/node_modules/wsl-utils/index.js +18 -37
  133. package/node_modules/wsl-utils/package.json +2 -2
  134. package/package.json +33 -29
  135. package/node_modules/@shikijs/engine-javascript/dist/scanner-DX8LRFGE.mjs +0 -77
  136. package/node_modules/open/node_modules/powershell-utils/index.js +0 -79
  137. package/node_modules/open/node_modules/powershell-utils/license +0 -9
  138. package/node_modules/open/node_modules/powershell-utils/package.json +0 -47
  139. package/node_modules/open/node_modules/powershell-utils/readme.md +0 -209
@@ -42,17 +42,17 @@ On quit the app prints `dsh: session <id> saved; resume with: dsh --profile tui
42
42
 
43
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 spinner in the tool family's animation 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 is omitted. A compaction, from `/compact` or automatic, draws as one context block whose accent `⬡` title names its origin and the estimated tokens it replaced and its summary costs, as in `context compacted by /compact · ~6.4k → ~0.9k tokens` or `context compacted automatically in turn 12 · …`; under the title, `compressed` names the item count and turns the summary replaced, each prompt among them (five at most, one row each), and a count of the replies, tool results by tool, context blocks, and earlier summaries, and `preserved` names the system prompt and what each later turn still holds verbatim; both stay drawn while the summary under them folds to `contextPreviewLines` rows like any context block. The checkpoint message itself is not drawn again. A `/compact` attempt the log closes with an error prints `/compact failed · <error>` when the session is redrawn, since the live command reports its own failure; a failed automatic attempt changes nothing and draws nothing, as in the browser. 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 animation follows its label, with a bright highlight sweeping across the word: braille `thinking` while the model reasons, a filling bar `writing` while visible text arrives, the named tool's own animation on `calling <tool>` while a tool is streamed or still running, or a clock while a retry waits, 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. 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 — rotating braille dots beside every label — `thinking`, `writing`, `calling <tool>`, a retry, or `compacting` — with a bright highlight sweeping across the word, 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. 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
 
49
49
  The focused block is also marked where it stands, with a two-column gutter that is dim beside the block's other lines and accented beside the focused section's own — or beside the fold marker, when the fold left that section out of the drawn rows entirely — and its content wraps two columns narrower while the mark is drawn. That mark reaches only the lines pi-tui still repaints differentially — the last `rows` lines of the last frame it wrote, a window a taller frame raises and a shorter one never lowers — because changing anything above them would clear the terminal's scrollback. A block that has scrolled past that point keeps no gutter, the inspector heading appends ` · off screen`, and the frame's own rules draw dim instead of accent, so the frame itself reports that the mark cannot be drawn where the block stands. A fade whose rows reach that edge settles them to their final colors in the frame that writes them, so nothing stays dim in the scrollback.
50
50
 
51
- `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen, one turn at a time. The reader takes the terminal rather than drawing over the conversation: it runs on the terminal's alternate screen, the screen a pager runs on, and the conversation's own screen is held off the terminal for as long as it is up. So it costs the conversation no line, leaves the repaint window where it was, fills the screen on every terminal, and cannot leave a row of itself in your scrollback; closing it restores the conversation exactly as you left it, with whatever landed meanwhile drawn underneath. Under a top rule carrying a ` ● READER ` chip and `turn <n> of <total>`, the turn being read takes most of the screen and a narrow turn list sits to its left, every body row closed by a right border. The list has one row per turn — `❯` on the turn being read, the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `◆<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away. The turn panel scrolls that turn end to end in the conversation's own glyphs, a blank row between each two sections: the prompt opens it behind `❯` on a shaded band, then `✻ Thinking` in dim italic, `¶ Reply` rendered as the conversation renders Markdown — headings, emphasis, inline code, and fenced code in syntax colour — except that unordered bullets are drawn as `•`, a call's `◆` — green once its result landed, yellow while it runs — with the tool name in bold and its headline in the link blue, `⎿ Result` indented under its call with a diff's `+ ` rows green and `- ` rows red on shaded bands and a `read` card's file rows in syntax colour, and `⬡` with the label of an injected context. The section the top row belongs to is accented and carries the conversation walk's `┃` gutter on every row, which reads with no color at all. The bands are mixed from the background color the terminal reports, so a terminal that reports none, or draws no color, draws the panel without them. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, so a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
51
+ `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen, one turn at a time. The reader takes the terminal rather than drawing over the conversation: it runs on the terminal's alternate screen, the screen a pager runs on, and the conversation's own screen is held off the terminal for as long as it is up. So it costs the conversation no line, leaves the repaint window where it was, fills the screen on every terminal, and cannot leave a row of itself in your scrollback; closing it restores the conversation exactly as you left it, with whatever landed meanwhile drawn underneath. When the turn panel scrolls below its first row, a compact tinted bar replaces the top rule with the current user prompt, collapsed to one line and ellipsized to the terminal width; scrolling back to the top restores the ` ● READER ` chip and `turn <n> of <total>`. Under that fixed header, the turn being read takes most of the screen and a narrow turn list sits to its left, every body row closed by a right border. The list has one row per turn — `❯` on the turn being read, the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `◆<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away. The turn panel scrolls that turn end to end in the conversation's own glyphs, a blank row between each two sections: the prompt opens it behind `❯` on a shaded band, then `✻ Thinking` in dim italic, `¶ Reply` rendered as the conversation renders Markdown — headings, emphasis, inline code, and fenced code in syntax colour — except that unordered bullets are drawn as `•`, a call's `◆` — green once its result landed, yellow while it runs — with the tool name in bold and its headline in the link blue, `⎿ Result` indented under its call with a diff's `+ ` rows green and `- ` rows red on shaded bands and a `read` card's file rows in syntax colour, and `⬡` with the label of an injected context. The section the top row belongs to is accented and carries the conversation walk's `┃` gutter on every row, which reads with no color at all. The bands are mixed from the background color the terminal reports, so a terminal that reports none, or draws no color, draws the panel without them. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, so a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
52
52
 
53
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. Running tool cards cycle their family's animation — commands spin the caret, reads pulse a lens, edits set a diamond, delegation dives, plan tools march corners, waits turn a clock, and tools with no family orbit the moon — folded subagent rows dive with them, the in-progress todo marches corners, and the working spinner draws its label's animation the same way, all 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.
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 cycle their family's glyphs — commands and edits set a diamond, reads pulse a lens, delegation dives, plan tools blink a filled `●`, waits turn a clock, and tools with no family orbit the moon — each glyph frame lasting `toolSpinnerMs`, 160 ms by default, while an 80 ms tick still redraws them; folded subagent rows dive with them, the in-progress todo blinks that same filled circle on the 80 ms tick, and the working spinner draws rotating braille dots beside every label on that 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
 
@@ -62,7 +62,7 @@ The subagent panel is drawn while a subagent session under the bound one is resi
62
62
 
63
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+B`, `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.
64
64
 
65
- Every key the screen names is drawn as a chip, in the accent color and underlined apart from the words around it: in the status bar, the region legends, the pickers and prompts, the transient line, fold markers, notices, `/help`, and the reader. With `mouse: true`, a left click on a chip presses that key exactly as typing it would, so `Shift+↓` in the status bar walks to the bar, `Esc` on the armed-stop line stops the turn, and each arrow of a pair such as `↑↓` presses its own key. Turning it on turns the terminal's mouse reports on, so the wheel and plain click-drag reach the application instead of scrolling the terminal's scrollback or selecting text; most terminals still scroll and select with `Shift` held (`Option` in iTerm2).
65
+ Every key the screen names is drawn as a chip, in the accent color and underlined apart from the words around it: in the status bar, the region legends, the pickers and prompts, the transient line, fold markers, notices, `/help`, and the reader. With `mouse: true`, a left click on a chip presses that key exactly as typing it would, so `Shift+↓` in the status bar walks to the bar, `Esc` on the armed-stop line stops the turn, and each arrow of a pair such as `↑↓` presses its own key. Turning it on turns the terminal's mouse reports on: the wheel opens the full-screen reader at the newest section and scrolls it up or down, but does nothing while an approval or question is open. The wheel and plain click-drag reach the application instead of scrolling the terminal's scrollback or selecting text; most terminals still scroll and select with `Shift` held (`Option` in iTerm2).
66
66
 
67
67
  While the input has the keyboard:
68
68
 
@@ -242,8 +242,9 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
242
242
  | `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` |
243
243
  | `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 |
244
244
  | `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 |
245
+ | `toolSpinnerMs` | `160` | Milliseconds each running tool-card glyph frame lasts. The working spinner's braille dots and the in-progress todo blink stay on the 80 ms redraw tick; a value below 80 is rejected |
245
246
  | `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 |
246
- | `mouse` | `false` | Make every key chip clickable: a left click on one presses its key. It turns the terminal's mouse reports on, so the wheel and plain click-drag reach the application instead of the terminal; most terminals still scroll and select with `Shift` held |
247
+ | `mouse` | `false` | Make every key chip clickable: a left click on one presses its key. Mouse reports turn on; the wheel opens and scrolls the full-screen reader unless a prompt is open, and most terminals still scroll and select with `Shift` held |
247
248
  | `openBrowser` | `true` | Hand marked authorization pages to the local default browser |
248
249
  | `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 |
249
250
  | `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 |
@@ -42,17 +42,17 @@ dsh tui --no-open # print sign-in URLs without opening a
42
42
 
43
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` 行,快照的每一份贡献具名写在其自身各行上方;空的系统提示词则省略。一次压缩(compaction)——无论来自 `/compact` 还是自动触发——绘制为一个上下文块,其强调色 `⬡` 标题写明来源,以及被替换内容与摘要各自的估算 token 数,如 `context compacted by /compact · ~6.4k → ~0.9k tokens` 或 `context compacted automatically in turn 12 · …`;标题之下,`compressed` 写明摘要替换的条目数与轮次、其中的每条提示(最多五条,每条一行),以及回复、按工具分列的工具结果、上下文块与更早摘要的计数,`preserved` 写明系统提示词以及之后每一轮仍逐字保留的内容;这两部分始终绘出,其下的摘要则像其他上下文块一样折叠到 `contextPreviewLines` 行。检查点消息本身不再重复绘制。日志以错误结束的 `/compact` 尝试会在会话重绘时打印 `/compact failed · <error>`,因为实时运行的命令会自己报告失败;失败的自动尝试不改变任何内容,也不绘制任何内容,与浏览器一致。承载的行数多于其绘制行数的工具卡片与上下文块,结尾都是同一条标记:该块被对话记录的焦点持有时为 `… <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>`、重试或 `compacting`——标签单词上带着一道扫过的高亮,并带着当前这次模型调用的实时 `↑` 发送与 `↓` 接收 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
 
49
49
  被聚焦的块也会在原地被标记:一条两列宽的标记条,在块的其他行旁为暗色、在被聚焦小节自身的行旁为强调色——若折叠把该小节整个留在了绘出的行之外,强调色便落在那一行折叠标记旁——标记绘制期间该块的内容按窄两列换行。这个标记只能落在 pi-tui 仍以差分方式重绘的行上——也就是它写出的上一帧的最后 `rows` 行,这条边界只会被更高的帧抬高、不会被更矮的帧降低——因为改动其上方的任何一行都会清空终端的回滚区。已经滚过该位置的块不带标记条,检视面板的标题追加 ` · off screen`,其边框线也改画暗色而非强调色,于是边框本身就报告出标记无法画在该块所在之处。淡入中的各行抵达这一边界时,会在写出它们的同一帧内被结算为最终颜色,因此回滚区里不会留下暗色文字。
50
50
 
51
- 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录,一次读一个轮次。阅读器并不画在对话记录之上,而是接管终端:它运行在终端的备用屏幕(alternate screen,分页器所用的那块屏幕)上,只要它还开着,对话记录自己的屏幕就被挡在终端之外。因此它不占用对话记录的任何一行,让重绘边界保持原位,在任何终端上都铺满整屏,也不可能把自己的任何一行留在你的回滚缓冲里;关闭它会把对话记录原样恢复成你离开时的样子,期间落地的内容则绘制在其下方。在带有 ` ● READER ` 徽标与 `turn <n> of <total>` 的顶边线之下,正在阅读的轮次占据屏幕的大部分,左侧是一列窄的轮次列表,每个正文行都以右边框收口。列表每个轮次一行——正在阅读的轮次带 `❯`、轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`◆<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥。轮次面板用对话记录自己的符号把该轮次从头到尾滚动读出,相邻两个小节之间隔一空行:提示以 `❯` 开头、铺在着色背景带上,其后是暗色斜体的 `✻ Thinking`、按对话记录的方式渲染 Markdown(标题、强调、行内代码,以及带语法着色的围栏代码)但无序列表符号画成 `•` 的 `¶ Reply`、工具调用的 `◆`(结果落地后为绿色、运行中为黄色)连同粗体工具名与链接蓝色的标题、缩进在调用之下的 `⎿ Result`(diff 的 `+ ` 行为绿色、`- ` 行为红色,各铺在着色背景带上;`read` 卡片的文件行带语法着色),以及带注入上下文标签的 `⬡`。顶行所属的小节带强调色,并在每一行带上对话记录走查所用的 `┃` 标记条,无色时也能辨认。背景带由终端报告的背景色混合而成,因此没有报告背景色、或不绘制颜色的终端画出的面板不带背景带。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它在每一帧都重新读取对话记录,因此流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
51
+ 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录,一次读一个轮次。阅读器并不画在对话记录之上,而是接管终端:它运行在终端的备用屏幕(alternate screen,分页器所用的那块屏幕)上,只要它还开着,对话记录自己的屏幕就被挡在终端之外。因此它不占用对话记录的任何一行,让重绘边界保持原位,在任何终端上都铺满整屏,也不可能把自己的任何一行留在你的回滚缓冲里;关闭它会把对话记录原样恢复成你离开时的样子,期间落地的内容则绘制在其下方。轮次面板滚过首行后,紧凑的着色条会替代顶边线,将当前用户提示合并为一行,并按终端宽度以省略号截断;滚回顶部时恢复 ` ● READER ` 徽标与 `turn <n> of <total>`。在这个固定页眉之下,正在阅读的轮次占据屏幕的大部分,左侧是一列窄的轮次列表,每个正文行都以右边框收口。列表每个轮次一行——正在阅读的轮次带 `❯`、轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`◆<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥。轮次面板用对话记录自己的符号把该轮次从头到尾滚动读出,相邻两个小节之间隔一空行:提示以 `❯` 开头、铺在着色背景带上,其后是暗色斜体的 `✻ Thinking`、按对话记录的方式渲染 Markdown(标题、强调、行内代码,以及带语法着色的围栏代码)但无序列表符号画成 `•` 的 `¶ Reply`、工具调用的 `◆`(结果落地后为绿色、运行中为黄色)连同粗体工具名与链接蓝色的标题、缩进在调用之下的 `⎿ Result`(diff 的 `+ ` 行为绿色、`- ` 行为红色,各铺在着色背景带上;`read` 卡片的文件行带语法着色),以及带注入上下文标签的 `⬡`。顶行所属的小节带强调色,并在每一行带上对话记录走查所用的 `┃` 标记条,无色时也能辨认。背景带由终端报告的背景色混合而成,因此没有报告背景色、或不绘制颜色的终端画出的面板不带背景带。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它在每一帧都重新读取对话记录,因此流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
52
52
 
53
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` 则画出已稳定的活动板。运行中的工具卡片轮播各自家族的动画——命令旋转插入符、读取脉动透镜、编辑凝固菱形、委派下潜、计划工具走过四角、等待转动时钟、无家族的工具绕月——折叠的子 agent 行随之一起下潜,进行中的 todo 走过四角,工作时的旋转指示也同样画出其标签的动画,全部都在各自的 80 ms 时钟上,该时钟只在其中之一被绘制时才启动;标题行已滚动到渲染器可重绘区域之上的卡片自此画出静态的 `◆`。阅读器在自己占据的屏幕上一次性完整出现,而它新显示的内容会像工具卡片一样在同一时钟上浮出:打开它与显示另一个轮次时浮出整个轮次,在列表中步进到同一轮次的另一个小节时浮出该小节,历时 `streamFadeSteps` 拍;滚动、实时增长与重新换行都不浮出任何内容。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会把它们全部关闭,并且不为它们安排任何重绘。
55
+ 动效不止于流式文本,而且每种效果都乘着同一个淡入时钟。键盘落到对话记录、子 agent 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮十二拍(每拍一个 `streamFadeStepMs`);对话记录走查中的一步把新聚焦的标记条抬亮六拍;状态栏上的一步把所选标签抬亮八拍。活动板上新出现或状态已变的 todo 行,以及被替换的后代行,也在同一时钟上像工具卡片一样浮出;重放与 `reducedMotion` 则画出已稳定的活动板。运行中的工具卡片轮播各自家族的符号——命令与编辑凝固菱形、读取脉动透镜、委派下潜、计划工具闪烁实心 `●`、等待转动时钟、无家族的工具绕月——每个符号帧持续 `toolSpinnerMs`(默认 160 ms),而 80 ms 的时钟仍负责重绘;折叠的子 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
 
@@ -62,7 +62,7 @@ dsh tui --no-open # print sign-in URLs without opening a
62
62
 
63
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+B`、`Ctrl+T`、`Ctrl+P` 与 `Ctrl+L` 在这些区域中含义完全相同,而 `Ctrl+C` 与 `Ctrl+D` 会先把键盘交还编辑器再行动。提示与阅读器则各自持有整条按键流,并以交还键盘的方式应答 `Ctrl+C`。
64
64
 
65
- 屏幕上写出的每个按键都画成一枚徽标,以强调色加下划线与周围文字区分开:出现在状态栏、各区域的按键提示、选择器与提示、临时提示行、折叠标记、通知、`/help` 与阅读器中。设置 `mouse: true` 后,左键点击一枚徽标就按下该键,与键入它完全相同:点击状态栏中的 `Shift+↓` 会走到状态栏,点击已布防的停止提示行中的 `Esc` 会停止轮次,`↑↓` 这类成对箭头中的每个箭头各自按下自己的键。开启它会打开终端的鼠标报告,因此滚轮与普通的点击拖动交给应用,而不再滚动终端的回滚缓冲区或选择文本;大多数终端在按住 `Shift`(iTerm2 中为 `Option`)时仍可滚动与选择。
65
+ 屏幕上写出的每个按键都画成一枚徽标,以强调色加下划线与周围文字区分开:出现在状态栏、各区域的按键提示、选择器与提示、临时提示行、折叠标记、通知、`/help` 与阅读器中。设置 `mouse: true` 后,左键点击一枚徽标就按下该键,与键入它完全相同:点击状态栏中的 `Shift+↓` 会走到状态栏,点击已布防的停止提示行中的 `Esc` 会停止轮次,`↑↓` 这类成对箭头中的每个箭头各自按下自己的键。开启它会打开终端的鼠标报告:滚轮在最新小节打开全屏阅读器并向上或向下滚动,但审批或提问打开期间不响应滚轮。滚轮与普通的点击拖动交给应用,而不再滚动终端的回滚缓冲区或选择文本;大多数终端在按住 `Shift`(iTerm2 中为 `Option`)时仍可滚动与选择。
66
66
 
67
67
  编辑器持有键盘时:
68
68
 
@@ -242,8 +242,9 @@ follow-ups 面板持有键盘时:
242
242
  | `streamFadeStepMs` | `16` | 一帧的时长:淡入或浮出的一拍、仍在变化时的重绘周期,也是逐帧绘制流式文字的周期;总时长为 `streamFadeSteps × streamFadeStepMs` |
243
243
  | `streamPaceFrames` | `8` | 积压的流式回复文字或工具参数要经过多少帧才全部上屏。思考块结束时,或回复文字或工具调用开始时,仍在队列中的思考立即画出;`0` 与 `reducedMotion` 一样,收到即绘制 |
244
244
  | `toolRevealFrames` | `6` | 工具卡片出现或其结果落下时,其各行展开所用的帧数,每帧展开隐藏行的一份。展开卡片,以及正在展开的行已位于渲染器可重绘范围之上的卡片,都会一次画出所有行;`0` 与 `reducedMotion` 一样,一次画出所有行 |
245
+ | `toolSpinnerMs` | `160` | 运行中的工具卡片每个符号帧持续的毫秒数。工作旋转指示的盲文点与进行中 todo 的闪烁仍走 80 ms 重绘时钟;小于 80 的值会被拒绝 |
245
246
  | `reducedMotion` | `false` | 以稳定颜色绘制流式文本、流式推理、工具卡片与应用自身的边框装饰,不做淡入、不做抬亮、没有旋转符号或扫光,也不重复重绘 |
246
- | `mouse` | `false` | 让每枚按键徽标都可点击:左键点击其中一枚即按下它的键。它会打开终端的鼠标报告,因此滚轮与普通的点击拖动交给应用而非终端;大多数终端在按住 `Shift` 时仍可滚动与选择 |
247
+ | `mouse` | `false` | 让每枚按键徽标都可点击:左键点击其中一枚即按下它的键。鼠标报告会打开;滚轮会打开并滚动全屏阅读器,提示打开时除外,大多数终端在按住 `Shift` 时仍可滚动与选择 |
247
248
  | `openBrowser` | `true` | 把被标记的授权页面交给本地默认浏览器 |
248
249
  | `btwTools` | `read`、`read_image`、`glob`、`grep`、`web_search`、`web_fetch`、`session_*` 查询工具、`skill`、MCP 资源读取工具、`ask_user_question` | `/btw` 旁路 agent 可以调用的全局工具;本组合未注册的名称会被跳过 |
249
250
  | `btwSandboxedTools` | `bash`、`pwsh` | 仅当命令执行器会约束命令时 `/btw` 旁路 agent 才可调用的命令工具;它们在 `read-only` 沙箱模式下运行 |
@@ -16,7 +16,27 @@
16
16
  # Keep the same temporary process-wide PTC mode opt-in as the Web surface.
17
17
  mode: !!js process.env.DSH_TOOLS_MODE
18
18
 
19
+ # The terminal confines commands with the Apple container backend below
20
+ # instead of the base local sandbox row.
21
+ - id: sandbox
22
+ disabled: true
23
+
19
24
  - insert:
25
+ # `auto` runs confined commands in an Apple container VM on macOS on Apple
26
+ # silicon when the `container` CLI is installed, and through the inherited
27
+ # local sandbox chain elsewhere; `/sandbox` switches one session. Skill
28
+ # roots are mounted read-only so loaded skills can read their resources.
29
+ - id: sandbox-apple-container
30
+ name: '@deepseek-ai/dsh-sandbox-apple-container'
31
+ config:
32
+ backend: auto
33
+ readOnlyMounts: !!js >-
34
+ process.platform !== 'darwin' ? [] : [
35
+ `${process.env.DSH_HOME ?? `${process.env.HOME}/.dsh`}/skills`,
36
+ `${process.env.DSH_AGENTS_HOME ?? `${process.env.HOME}/.agents`}/skills`,
37
+ ...(process.env.DSH_BUNDLED_SKILL_DIR ? [process.env.DSH_BUNDLED_SKILL_DIR] : []),
38
+ ]
39
+
20
40
  # The model-facing question tool; the terminal runner answers its
21
41
  # `user-questions/request` waterfall in the same process.
22
42
  - id: tool-ask-user
@@ -4804,12 +4804,8 @@ function floatingOutSpans(fade) {
4804
4804
  //#endregion
4805
4805
  //#region lib/types/spinner.js
4806
4806
  /**
4807
- * Working indicators: one single-column animation per scenario, so the
4808
- * glyph itself names the work — reasoning churns, streaming text blooms,
4809
- * commands and edits set a diamond, reads pulse a lens,
4810
- * delegation dives, todo items blink a dot, waits turn a clock, and tools
4811
- * with no family orbit the moon — plus the shimmer the working spinner's
4812
- * activity word carries.
4807
+ * Working indicators: rotating braille dots above the prompt, tool-family
4808
+ * glyphs on running cards, and a shimmer across the working activity word.
4813
4809
  *
4814
4810
  * Pure. Frame lookups read a wall-clock instant the caller passes in, so
4815
4811
  * every surface drawing at the same moment draws the same frame, and the
@@ -4883,8 +4879,8 @@ const SPINNER_FRAMES = {
4883
4879
  "⠇",
4884
4880
  "⠃"
4885
4881
  ],
4886
- /** Todo progress: a dot blinking in place. */
4887
- todo: ["·", " "],
4882
+ /** Todo progress: a filled circle blinking in place, one column and larger than a middle dot. */
4883
+ todo: ["●", " "],
4888
4884
  /** Waiting on a retry delay or a human answer: a clock turning. */
4889
4885
  waiting: [
4890
4886
  "◷",
@@ -4961,22 +4957,19 @@ const TOOL_PREFIXES = [
4961
4957
  ["team_task_", "subagent"],
4962
4958
  ["schedule_", "todo"]
4963
4959
  ];
4964
- /** The word that opens the working spinner's tool-call label. */
4965
- const CALLING_WORD = "calling ";
4966
- /** The word that opens a scheduled model-request retry notice. */
4967
- const RETRYING_WORD = "retrying";
4968
4960
  /** The working spinner's label while a compaction condenses history. */
4969
4961
  const COMPACTING_ACTIVITY = "compacting";
4970
4962
  /**
4971
4963
  * The spinner frame drawn at one instant.
4972
4964
  * @param now - the current time in milliseconds.
4973
4965
  * @param kind - the scenario whose frames are drawn; `thinking` draws the braille circle.
4966
+ * @param intervalMs - how long each frame lasts, in milliseconds; positive.
4974
4967
  * @returns one frame of that scenario.
4975
4968
  */
4976
- function spinnerFrame(now, kind = "thinking") {
4969
+ function spinnerFrame(now, kind = "thinking", intervalMs = 80) {
4977
4970
  const frames = SPINNER_FRAMES[kind];
4978
4971
  /* v8 ignore next -- the modulo keeps the index inside the frame list */
4979
- return frames[Math.floor(now / 80) % frames.length] ?? frames[0];
4972
+ return frames[Math.floor(now / intervalMs) % frames.length] ?? frames[0];
4980
4973
  }
4981
4974
  /**
4982
4975
  * The animation a running tool card draws for `name`.
@@ -4994,19 +4987,11 @@ function spinnerKindForTool(name) {
4994
4987
  return "calling";
4995
4988
  }
4996
4989
  /**
4997
- * The animation the working spinner draws for its activity word.
4998
- * @param activity - `thinking`, `writing`, `calling` / `calling <name>`, `compacting`, or a retry notice.
4999
- * @returns the activity's animation; a `calling <name>` label mirrors the
5000
- * named tool's card, and anything unrecognized draws `thinking` like the
5001
- * loader's initial word.
4990
+ * The shared rotating-dot animation above the prompt, independent of its label.
4991
+ * @param _activity - the working activity label; every label draws the same dots.
4992
+ * @returns `thinking` for every activity, keeping the dot cycle continuous as labels change.
5002
4993
  */
5003
- function spinnerKindForActivity(activity) {
5004
- if (activity === "thinking") return "thinking";
5005
- if (activity === "writing") return "writing";
5006
- if (activity === "calling") return "calling";
5007
- if (activity.startsWith(CALLING_WORD)) return spinnerKindForTool(activity.slice(8));
5008
- if (activity.startsWith(RETRYING_WORD)) return "waiting";
5009
- if (activity === "compacting") return "compacting";
4994
+ function spinnerKindForActivity(_activity) {
5010
4995
  return "thinking";
5011
4996
  }
5012
4997
  /**
@@ -10051,8 +10036,9 @@ function readerRows(state, groups, render) {
10051
10036
  for (let row = 0; row < geometry.body; row += 1) body.push(frameRow(columns, row, palette, width));
10052
10037
  const report = readout(state, groups, geometry, totalTurns);
10053
10038
  const legendRoom = ruleRoom(width) - visibleWidth(report) - 1;
10039
+ const prompt = group?.sections.map((section) => blocks[section.block]?.parts()[section.part]).find((part) => part?.kind === "user");
10054
10040
  return [
10055
- topRule({
10041
+ (geometry.pane > 0 && state.offset > 0 && prompt !== void 0 ? bandRow(palette, truncateToWidth(` ${PROMPT_GLYPH} ${prompt.rows.join(" ").replaceAll(/\s+/gu, " ").trim()} `, width, ELLIPSIS$1), width) : void 0) ?? topRule({
10056
10042
  chip: chip(palette, READER_CHIP),
10057
10043
  title: palette.bold(palette.accent(`turn ${String(place(selected, groups.length))} of ${String(groups.length)}`)),
10058
10044
  width,
@@ -10139,14 +10125,15 @@ function isLeftButton(report) {
10139
10125
  /**
10140
10126
  * The terminal the tree renders into, with clicks reported on top of it.
10141
10127
  *
10142
- * A click is a left press and a left release on the same cell; any other
10143
- * report, a wheel tick included, is consumed without effect, so no mouse
10128
+ * A click is a left press and a left release on the same cell; wheel ticks
10129
+ * reach the optional scroll callback. Other reports are consumed, so no mouse
10144
10130
  * report ever reaches the editor as typed text. Every other method is the
10145
10131
  * wrapped terminal's own.
10146
10132
  */
10147
10133
  var PointerTerminal = class {
10148
10134
  terminal;
10149
10135
  onClick;
10136
+ onScroll;
10150
10137
  /** The callback pi-tui gave {@link PointerTerminal.start}, which a pressed key reaches. */
10151
10138
  deliver;
10152
10139
  /** Where the left button went down, until it comes up again. */
@@ -10156,10 +10143,12 @@ var PointerTerminal = class {
10156
10143
  /**
10157
10144
  * @param terminal - the terminal to report clicks on.
10158
10145
  * @param onClick - called with the cell of each click.
10146
+ * @param onScroll - called with -1 for wheel up and 1 for wheel down; omitted ignores scrolling.
10159
10147
  */
10160
- constructor(terminal, onClick) {
10148
+ constructor(terminal, onClick, onScroll) {
10161
10149
  this.terminal = terminal;
10162
10150
  this.onClick = onClick;
10151
+ this.onScroll = onScroll;
10163
10152
  }
10164
10153
  get columns() {
10165
10154
  return this.terminal.columns;
@@ -10237,6 +10226,12 @@ var PointerTerminal = class {
10237
10226
  * @param report - one parsed mouse report.
10238
10227
  */
10239
10228
  onReport(report) {
10229
+ const button = report.button & -29;
10230
+ if (!report.release && (button === 64 || button === 65)) {
10231
+ this.pressed = void 0;
10232
+ this.onScroll?.(button === 64 ? -1 : 1);
10233
+ return;
10234
+ }
10240
10235
  if (!isLeftButton(report)) return;
10241
10236
  if (!report.release) {
10242
10237
  this.pressed = {
@@ -12507,6 +12502,8 @@ var TuiApp = class {
12507
12502
  if (palette.clickableKeys) {
12508
12503
  const pointer = new PointerTerminal(deps.terminal, (cell) => {
12509
12504
  this.onClick(pointer, cell);
12505
+ }, (step) => {
12506
+ this.onScroll(step);
12510
12507
  });
12511
12508
  terminal = pointer;
12512
12509
  }
@@ -13873,6 +13870,18 @@ var TuiApp = class {
13873
13870
  return this.onAction(action, data);
13874
13871
  }
13875
13872
  /**
13873
+ * Scroll the reader, opening it at the newest section on the first wheel tick.
13874
+ * Modal prompts retain the terminal and ignore the wheel.
13875
+ * @param step - -1 for up, 1 for down.
13876
+ */
13877
+ onScroll(step) {
13878
+ if (this.modals.isActive() || this.queuedModals > 0) return;
13879
+ if (this.reader === void 0) this.openReader();
13880
+ if (!this.readerScreen.active) return;
13881
+ this.reader?.pane.handleInput(step === -1 ? "\x1B[A" : "\x1B[B");
13882
+ this.queueReaderPaint();
13883
+ }
13884
+ /**
13876
13885
  * Press the key whose chip a click landed on, exactly as typing it would.
13877
13886
  *
13878
13887
  * The reader's screen is addressed by row. The main screen is drawn from
@@ -15720,7 +15729,7 @@ var TuiApp = class {
15720
15729
  */
15721
15730
  spinBlock(block) {
15722
15731
  if (this.replaying || this.deps.reducedMotion) return;
15723
- block.setSpinner(() => spinnerFrame(this.deps.now(), spinnerKindForTool(block.name)));
15732
+ block.setSpinner(() => spinnerFrame(this.deps.now(), spinnerKindForTool(block.name), this.deps.toolSpinnerMs));
15724
15733
  this.spinners.add(block);
15725
15734
  this.updateSpinTicker();
15726
15735
  }
@@ -16538,6 +16547,7 @@ const Config = z.object({
16538
16547
  streamFadeStepMs: z.natural().min(16).default(16),
16539
16548
  streamPaceFrames: z.natural().default(8),
16540
16549
  toolRevealFrames: z.natural().default(6),
16550
+ toolSpinnerMs: z.natural().min(80).default(160),
16541
16551
  reducedMotion: z.boolean().default(false),
16542
16552
  mouse: z.boolean().default(false),
16543
16553
  openBrowser: z.boolean().default(true),
@@ -16813,6 +16823,7 @@ async function run(ctx, config, host) {
16813
16823
  fadeStepMs: config.streamFadeStepMs,
16814
16824
  streamPaceFrames: config.streamPaceFrames,
16815
16825
  toolRevealFrames: config.toolRevealFrames,
16826
+ toolSpinnerMs: config.toolSpinnerMs,
16816
16827
  reducedMotion: config.reducedMotion,
16817
16828
  env: process.env,
16818
16829
  now: () => Date.now(),
@@ -49,6 +49,7 @@
49
49
  "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
50
50
  "@deepseek-ai/dsh-native-command": "0.2.0-rc.2",
51
51
  "@deepseek-ai/dsh-plugin-manager": "0.2.0-rc.2",
52
+ "@deepseek-ai/dsh-sandbox-apple-container": "0.2.0-rc.2",
52
53
  "@deepseek-ai/dsh-session": "0.2.0-rc.2",
53
54
  "@deepseek-ai/dsh-session-log-export": "0.2.0-rc.2",
54
55
  "@deepseek-ai/dsh-session-reference": "0.2.0-rc.2",
@@ -6,14 +6,14 @@ Convert, recalculate, and directly render local Office documents with prebuilt L
6
6
 
7
7
  Binary `.doc`, `.xls`, and `.ppt` inputs must be OLE compound documents, such as Office 97–2003 files. Renamed RTF/HTML and `.wps` inputs are unsupported. `missingFonts` is empty for binary inputs because their font tables are interpreted by LibreOffice rather than the OOXML inspector.
8
8
 
9
- The Node API version is independent of its platform engine versions. Version 0.1.2 uses Windows engines 0.1.2 and retains macOS/WASM engines 0.1.1. `ENGINE_VERSION` and `discoverRuntime().version` identify the Node API; `ENGINE_VERSIONS` lists the exact compatible engine versions.
9
+ The Node API version is independent of its platform engine versions. Version 0.1.3 uses macOS, Windows and WASM engines 0.1.3. `ENGINE_VERSION` and `discoverRuntime().version` identify the Node API; `ENGINE_VERSIONS` lists the exact compatible engine versions.
10
10
 
11
11
  ## Installation and usage
12
12
 
13
13
  Install with Node.js 22.19.0 or newer:
14
14
 
15
15
  ```sh
16
- npm install @deepseek-ai/libreoffice-kit@0.1.2
16
+ npm install @deepseek-ai/libreoffice-kit@0.1.3
17
17
  ```
18
18
 
19
19
  npm installs the matching native engine on macOS/Windows ARM64 or x64, and the shared WASM engine on Linux. macOS and Windows require their native package; a missing or invalid package rejects `createConverter` with `unavailable`, without switching to WASM. Linux uses WASM unless a compatible development native package was installed explicitly. Conversion failures never switch engines.
@@ -41,10 +41,25 @@ Converters created through the compatibility `createConverter(options)` API tran
41
41
 
42
42
  For a long-lived service that wants one explicit lifecycle owner for concurrent conversion slots, create one `createConverterFactory(options)` and obtain converters through `factory.create()`. Those converters use a factory-private cache while retaining separate Workers, native helpers, profiles, and output ownership. Dispose the factory to stop and join every converter it created.
43
43
 
44
- `convert()` exports the format named by the output suffix, `recalculate()` refreshes spreadsheet formula results before saving, and `renderImages()` writes a fresh directory containing PNG tiles plus `manifest.json`. Office images are painted directly from one loaded model; PDF images use PDFium. The CLI exposes the same operations through `libreoffice-kit capabilities|convert|recalculate|render`.
44
+ `convert()` exports the format named by the output suffix, `recalculate()` refreshes spreadsheet formula results before saving, and `renderImages()` writes a fresh directory containing PNG tiles plus `manifest.json`. Office images are painted directly from one loaded model; PDF images use PDFium. The CLI exposes the same operations through `dsoffice capabilities|convert|recalculate|render`. Worksheet names are exact: a missing image-render selection rejects with `invalid-document`, and a missing CSV selection rejects with `failed`; neither leaves output behind. Recalculation applies to the entire workbook and rejects `--sheet`. A rejected selection leaves the converter available for subsequent operations.
45
+
46
+ ```sh
47
+ npm exec -- dsoffice render --input report.docx --output-dir report-pages --pages 1
48
+ npm exec -- dsoffice render --input budget.xlsx --output-dir budget-preview --sheet Summary --range A1:D20
49
+ npm exec -- dsoffice convert --input report.docx --output report.pdf
50
+ npm exec -- dsoffice recalculate --input budget.xlsx --output recalculated.xlsx
51
+ ```
52
+
53
+ Right-to-left worksheets produce readable PNG text with column A on the right. A1 ranges and manifest rectangles retain logical column coordinates; each split tile is independently oriented for display.
45
54
 
46
55
  Conversion workers run the package's shipped JavaScript with an empty `execArgv`; consumer launch flags such as `--input-type=module` are not inherited.
47
56
 
57
+ Windows native helpers use anonymous stdio pipes and inherit the caller's token and Job restrictions. Pipe polling does not occupy libuv worker threads while a helper waits for commands. Cancellation and rejected worksheet selections wait for process exit and pipe closure, including when the protocol reader has paused stdout; this transport does not grant additional filesystem or network access.
58
+
59
+ Native conversion and image-rendering helpers disable printer enumeration and default-printer lookup with `SAL_DISABLE_PRINTERLIST=1` and `SAL_DISABLE_DEFAULTPRINTER=1`. Document previews and exports do not need a physical printer; these child-process settings prevent printer-driver dialogs and network-printer connection waits without changing the system's printer settings.
60
+
61
+ On Windows, an engine executable or program path of 260 or more characters uses a temporary helper copy and a junction to the installed resources inside the private operation directory. Resources stay in their installation, and the junction remains until the helper closes. A renderer that exits before returning a protocol response rejects with its exit status and captured diagnostics.
62
+
48
63
  On Linux, the native child searches the selected engine's program directory before system paths for shared libraries. Caller-provided `LD_LIBRARY_PATH` and `LD_PRELOAD` are not inherited.
49
64
 
50
65
  The caller authorizes input access and owns private input/output directories; paths must be absolute and remain unchanged during conversion. Input files must be regular Office files within the configured byte limits. ZIP entry and uncompressed-size limits apply to OOXML; binary DOC/XLS/PPT files use OLE compound containers validated by the LibreOffice importer. Binary formats retain the same conversion deadline and input/output limits. Output creation uses exclusive mode and permissions `0600`; an existing output is never overwritten. Failed or cancelled renders remove newly created outputs. `maxOutputBytes` limits the returned PDF and its read buffer; native temporary disk files can grow until export completes, then oversized PDFs are rejected and deleted before Node reads them. The caller owns successful PDFs and may send their bytes to a browser PDF viewer.
@@ -53,7 +68,7 @@ The caller authorizes input access and owns private input/output directories; pa
53
68
 
54
69
  ## Engines, fonts, and runtime behavior
55
70
 
56
- The Node API and engine packages share the kit release version. `ENGINE_VERSION` pins both WASM and native optional dependencies to the exact engine version. npm installs prepared engines; installation and conversion never compile LibreOffice or download additional engine payloads. Each engine includes its matching source recipes, patches, build information, and third-party license notices under `sources/` and `licenses/`.
71
+ The Node API reports its release version through `ENGINE_VERSION`; `ENGINE_VERSIONS` pins each platform engine independently. npm installs prepared engines; installation and conversion never compile LibreOffice or download additional engine payloads. Each engine includes its matching source recipes, patches, build information, and third-party license notices under `sources/` and `licenses/`.
57
72
 
58
73
  Defaults and all options are documented in the shipped TypeScript declarations in `lib/types/index.d.ts`. Font directories use conventional system/user paths for the selected OS. Indexing skips missing or protected sources and propagates other filesystem errors. `fontkit` indexes original font files and selects installed faces and glyph coverage; it does not rewrite fonts. Each operation discovers font candidates again and revalidates cached file identities. It uses one ordered metadata snapshot; matching entries are invalidated when that snapshot changes. A detected font change during conversion rejects the operation and removes its output. Original font bytes and decoded glyph coverage remain conversion-local. `missingFonts` contains absent families declared in readable document XML, excluding unrelated engine defaults. Missing glyphs without a named missing family are not a complete document accessibility report.
59
74
 
@@ -66,7 +81,7 @@ Both `createConverter()` and `createConverterFactory()` accept:
66
81
  | `fontMetadataCacheDirectory` | User system cache directory | Absolute directory path, or `false` to disable disk caching. |
67
82
  | `maxFontMetadataCacheBytes` | 32 MiB | Positive safe integer limiting each cache file read/write and retained per-file metadata per shared configuration. |
68
83
 
69
- The default directory is `~/Library/Caches/libreoffice-kit` on macOS, `%LOCALAPPDATA%/libreoffice-kit/Cache` on Windows (falling back to the user's `AppData/Local`), and `$XDG_CACHE_HOME/libreoffice-kit` on Linux (falling back to `~/.cache`). The single `font-metadata.json` file contains canonical file paths, device/inode, size, modification/change times, and all face metadata, including empty parse results. It contains no font bytes, glyph coverage, parsed font objects, document text, or document matching entries. Keep this user-local file private.
84
+ The default directory is `~/Library/Caches/libreoffice-kit` on macOS, `%LOCALAPPDATA%/libreoffice-kit/Cache` on Windows (falling back to the user's `AppData/Local`), and `$XDG_CACHE_HOME/libreoffice-kit` on Linux (falling back to `~/.cache`). The single `font-metadata.json` file contains canonical file paths, exact decimal device/inode identifiers, size, modification/change times, and all face metadata, including empty parse results. It contains no font bytes, glyph coverage, parsed font objects, document text, or document matching entries. Keep this user-local file private.
70
85
 
71
86
  A first run without reusable metadata performs the full original font inspection. Later processes skip inspection only for discovered files with matching identities. Each operation re-enumerates sources, including supplemental Office sources, so additions, deletions, replacements, and directory changes do not require a restart. Candidate order, file budgets, Office filtering, fallback matching, glyph queries, and original font import remain unchanged. A corrupted, incompatible, oversized, or inaccessible cache falls back to source inspection; unreadable source files never reuse stale records. Format, extractor, and pinned fontkit versions must match.
72
87
 
@@ -6,17 +6,19 @@
6
6
 
7
7
  二进制 `.doc`、`.xls`、`.ppt` 输入必须是 OLE 复合文档,例如 Office 97–2003 文件。不支持改后缀的 RTF/HTML 和 `.wps`。二进制输入的 `missingFonts` 为空,因为其字体表由 LibreOffice 读取,而不是由 OOXML 检查器读取。
8
8
 
9
- Node API 与各平台引擎独立指定版本。0.1.2 使用 Windows 引擎 0.1.2,保留 macOS/WASM 引擎 0.1.1。`ENGINE_VERSION` 和 `discoverRuntime().version` 表示 Node API 版本;`ENGINE_VERSIONS` 列出各平台兼容的精确引擎版本。
9
+ Node API 与各平台引擎独立指定版本。0.1.3 使用 macOS、Windows 和 WASM 引擎 0.1.3。`ENGINE_VERSION` 和 `discoverRuntime().version` 表示 Node API 版本;`ENGINE_VERSIONS` 列出各平台兼容的精确引擎版本。
10
10
 
11
11
  ## 安装与使用
12
12
 
13
13
  使用 Node.js 22.19.0 或更新版本安装:
14
14
 
15
15
  ```sh
16
- npm install @deepseek-ai/libreoffice-kit@0.1.2
16
+ npm install @deepseek-ai/libreoffice-kit@0.1.3
17
17
  ```
18
18
 
19
- npm 在 macOS/Windows ARM64 或 x64 上安装匹配的原生引擎,在 Linux 上安装共享 WASM 引擎。macOS 和 Windows 必须具有对应原生包;包缺失或无效时,`createConverter` 以 `unavailable` 拒绝,不会切换到 WASM。Linux 使用 WASM,除非显式安装了兼容的原生开发包。转换失败不会切换引擎。
19
+ npm 在 macOS/Windows ARM64 或 x64 上安装匹配的原生引擎,Windows 上,引擎可执行文件或程序目录路径达到 260 个字符时,在私有操作目录中使用 helper 临时副本和指向已安装资源的 junction。资源保留在安装目录,junction 在 helper 关闭后清理。渲染器若在返回协议响应前退出,会携带退出状态和捕获的诊断信息拒绝操作。
20
+
21
+ 在 Linux 上安装共享 WASM 引擎。macOS 和 Windows 必须具有对应原生包;包缺失或无效时,`createConverter` 以 `unavailable` 拒绝,不会切换到 WASM。Linux 使用 WASM,除非显式安装了兼容的原生开发包。转换失败不会切换引擎。
20
22
 
21
23
  ```js
22
24
  import { createConverter } from '@deepseek-ai/libreoffice-kit';
@@ -41,10 +43,23 @@ try {
41
43
 
42
44
  长驻服务如果需要为多个并发转换槽提供一个显式生命周期所有者,可创建 `createConverterFactory(options)`,再通过 `factory.create()` 建立转换器。这些转换器使用 factory 私有缓存,同时仍分别拥有 Worker、原生 helper、配置目录和输出。释放 factory 会停止并等待它创建的全部转换器。
43
45
 
44
- `convert()` 按输出后缀导出格式,`recalculate()` 在保存前刷新电子表格公式结果,`renderImages()` 在全新目录中写入 PNG tile 和 `manifest.json`。Office 图像直接从一次加载的模型绘制,PDF 使用 PDFium。CLI 通过 `libreoffice-kit capabilities|convert|recalculate|render` 提供相同行为。
46
+ `convert()` 按输出后缀导出格式,`recalculate()` 在保存前刷新电子表格公式结果,`renderImages()` 在全新目录中写入 PNG tile 和 `manifest.json`。Office 图像直接从一次加载的模型绘制,PDF 使用 PDFium。CLI 通过 `dsoffice capabilities|convert|recalculate|render` 提供相同行为。工作表名称按精确名称匹配:图像渲染指定不存在的工作表时返回 `invalid-document`,CSV 导出返回 `failed`,两者均不保留输出。重算作用于整个工作簿并拒绝 `--sheet`。选择失败后仍可复用转换器。
47
+
48
+ ```sh
49
+ npm exec -- dsoffice render --input report.docx --output-dir report-pages --pages 1
50
+ npm exec -- dsoffice render --input budget.xlsx --output-dir budget-preview --sheet Summary --range A1:D20
51
+ npm exec -- dsoffice convert --input report.docx --output report.pdf
52
+ npm exec -- dsoffice recalculate --input budget.xlsx --output recalculated.xlsx
53
+ ```
54
+
55
+ 从右向左排列的工作表会生成文字可正常阅读、A 列位于右侧的 PNG。A1 范围和 manifest 中的矩形仍使用逻辑列坐标;拆分后的每张 tile 均独立调整像素方向。
45
56
 
46
57
  转换 worker 以空的 `execArgv` 运行包内发布的 JavaScript;`--input-type=module` 之类的调用方启动参数不会被继承。
47
58
 
59
+ Windows 原生 helper 使用匿名标准输入输出管道,继承调用方的令牌和 Job 限制。helper 等待命令时,管道轮询不会占用 libuv 工作线程。取消及工作表选择失败均会等待进程退出和管道关闭,包括协议读取器已暂停 stdout 的情况;此传输方式不授予额外的文件系统或网络权限。
60
+
61
+ 原生转换和图片渲染 helper 设置 `SAL_DISABLE_PRINTERLIST=1` 与 `SAL_DISABLE_DEFAULTPRINTER=1`,禁用打印机枚举和默认打印机查询。文档预览和导出不需要实体打印机;这些子进程设置可避免打印机驱动弹窗及网络打印机连接等待,不会修改系统打印机设置。
62
+
48
63
  在 Linux 上,原生子进程会先在所选引擎的 program 目录中查找共享库,然后才查找系统路径。调用方提供的 `LD_LIBRARY_PATH` 和 `LD_PRELOAD` 不会被继承。
49
64
 
50
65
  调用方负责授权输入访问并拥有私有输入/输出目录;路径必须是绝对路径,并在转换期间保持不变。输入文件必须是常规 Office 文件,且在配置的字节限制之内。ZIP 条目数和解压大小限制适用于 OOXML;二进制 DOC/XLS/PPT 使用 OLE 复合容器,内部结构由 LibreOffice 导入器验证。二进制格式仍遵守相同的转换超时和输入/输出限制。输出创建使用独占模式和 `0600` 权限;已存在的输出绝不会被覆盖。失败或取消的渲染会删除新建的输出。`maxOutputBytes` 限制返回的 PDF 及其读取缓冲区;原生临时磁盘文件在导出完成前可能继续增长,随后过大的 PDF 会在 Node 读取之前被拒绝并删除。成功的 PDF 归调用方所有,调用方可以将其字节发送给浏览器 PDF 阅读器。
@@ -53,7 +68,7 @@ try {
53
68
 
54
69
  ## 引擎、字体与运行行为
55
70
 
56
- Node API 与引擎包使用相同的 kit 发布版本。`ENGINE_VERSION` 将 WASM 和原生可选依赖固定到精确的引擎版本。npm 安装预编译引擎;安装和转换阶段均不会编译 LibreOffice 或额外下载引擎资源。每个引擎包的 `sources/` 和 `licenses/` 保留匹配的源码配方、补丁、构建信息和第三方许可声明。
71
+ Node API 通过 `ENGINE_VERSION` 报告其发布版本;`ENGINE_VERSIONS` 独立固定各平台的引擎版本。npm 安装预编译引擎;安装和转换阶段均不会编译 LibreOffice 或额外下载引擎资源。每个引擎包的 `sources/` 和 `licenses/` 保留匹配的源码配方、补丁、构建信息和第三方许可声明。
57
72
 
58
73
  默认值和所有选项记录在随包发布的 `lib/types/index.d.ts` 类型声明中。字体目录使用所选操作系统的常规系统/用户路径。索引会跳过缺失或受保护的来源,并传播其他文件系统错误。`fontkit` 索引原始字体文件并选择已安装的字面和字形覆盖;它不重写字体。每次操作都会重新发现字体候选并验证缓存中的文件身份。一次操作使用一份有序元数据快照;快照变化后字体匹配条目失效。检测到转换期间字体变化时,操作会失败并删除其输出。原始字体字节和解码后的字形覆盖都只在本次转换内有效。精确的 family 匹配优先于 `fontFallbacks`。`missingFonts` 包含可读文档 XML 中声明但缺失的 family,不包含无关的引擎默认值。未命名缺失 family 的缺字并不构成完整的文档可访问性报告。
59
74
 
@@ -66,7 +81,7 @@ Node API 与引擎包使用相同的 kit 发布版本。`ENGINE_VERSION` 将 WAS
66
81
  | `fontMetadataCacheDirectory` | 用户系统缓存目录 | 目录的绝对路径,或用 `false` 关闭磁盘缓存。 |
67
82
  | `maxFontMetadataCacheBytes` | 32 MiB | 正安全整数,限制单个缓存文件的读取、写入及每份共享配置保留的逐文件元数据。 |
68
83
 
69
- macOS 默认使用 `~/Library/Caches/libreoffice-kit`,Windows 使用 `%LOCALAPPDATA%/libreoffice-kit/Cache`(缺省时回退到用户的 `AppData/Local`),Linux 使用 `$XDG_CACHE_HOME/libreoffice-kit`(缺省时回退到 `~/.cache`)。单个 `font-metadata.json` 文件保存规范文件路径、设备/inode、大小、修改/变更时间及全部 face 元数据,包括解析结果为空的记录。它不保存字体字节、字形覆盖、解析对象、文档文本或文档匹配条目。请将此用户级文件保持私有。
84
+ macOS 默认使用 `~/Library/Caches/libreoffice-kit`,Windows 使用 `%LOCALAPPDATA%/libreoffice-kit/Cache`(缺省时回退到用户的 `AppData/Local`),Linux 使用 `$XDG_CACHE_HOME/libreoffice-kit`(缺省时回退到 `~/.cache`)。单个 `font-metadata.json` 文件保存规范文件路径、以十进制字符串精确保留的设备/inode 标识、大小、修改/变更时间及全部 face 元数据,包括解析结果为空的记录。它不保存字体字节、字形覆盖、解析对象、文档文本或文档匹配条目。请将此用户级文件保持私有。
70
85
 
71
86
  没有可复用元数据的首次运行仍执行原来的完整字体 inspect。后续进程只跳过已发现且文件身份完全匹配的字体。每次操作重新枚举来源,包括 Office 补充字体,因此新增、删除、替换和目录变化无需重启。候选顺序、文件预算、Office 过滤、fallback 匹配、字形查询和原字体导入保持原有行为。缓存损坏、版本不兼容、超限或不可访问时回退到字体源计算;不可读的源字体不会复用旧记录。缓存格式、提取逻辑和固定的 fontkit 版本均须匹配。
72
87