From 0073d6aaa19ee569056183cf827e4cc6f24874c7 Mon Sep 17 00:00:00 2001 From: Yif <877193178@qq.com> Date: Wed, 5 Aug 2026 13:54:46 +0800 Subject: [PATCH 01/15] feat(web): turn speed metrics and composer context meter Assistant footers and the stats line gain TTFT/tok-per-second readings folded from step timings; context occupancy moves off the stats line onto a composer ring whose panel shows a heuristic system/tools/messages breakdown from the new token-meter contextBreakdown session projection. --- ...4-web-latency-throughput-metrics.i18n.yaml | 6 + ...26-08-04-web-latency-throughput-metrics.md | 29 +++ ...08-04-web-latency-throughput-metrics.zh.md | 29 +++ ...composer-context-meter-breakdown.i18n.yaml | 6 + ...-08-05-composer-context-meter-breakdown.md | 31 +++ ...-05-composer-context-meter-breakdown.zh.md | 31 +++ docs/cordis-catalog/services.md | 7 +- docs/core-data-structures/session.i18n.yaml | 4 +- docs/core-data-structures/session.md | 11 +- docs/core-data-structures/session.zh.md | 11 +- .../client/session-history/history-fold.ts | 46 +---- .../src/client/sessions/assistant-timing.ts | 84 ++++++++ .../src/client/sessions/transcript-adapter.ts | 11 +- .../runtime/tests/transcript-adapter.spec.ts | 44 ++++ .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 4 +- packages/client/ui-conversation/README.zh.md | 4 +- .../src/client/chat/AssistantMarkdown.tsx | 8 +- .../src/client/chat/ChatView.tsx | 7 + .../src/client/chat/MessageIconActions.tsx | 20 +- .../src/client/chat/StatsLine.tsx | 84 ++++++-- .../src/client/chat/message-chrome.ts | 21 ++ .../src/client/chat/turn-metrics.ts | 97 +++++++++ .../ui-conversation/src/client/locales.ts | 14 ++ .../client/skeleton/ContextMeter.module.css | 141 +++++++++++++ .../src/client/skeleton/ContextMeter.tsx | 131 ++++++++++++ .../src/client/skeleton/InputBar.tsx | 2 + .../tests/chat-branch-tails.spec.tsx | 9 + .../tests/chat-stats-bash-sample.spec.tsx | 122 +++++++---- .../ui-conversation/tests/chat-view.spec.tsx | 39 ++++ .../tests/context-meter.spec.tsx | 93 +++++++++ .../tests/gate-branch-tails.spec.tsx | 15 +- .../tests/turn-metrics.spec.ts | 154 ++++++++++++++ .../cordis/tool-cordis/src/api-catalog.ts | 2 +- packages/core/session/src/index.ts | 51 +---- packages/core/session/src/surface.ts | 51 +++++ packages/llm/token-meter/README.i18n.yaml | 4 +- packages/llm/token-meter/README.md | 6 +- packages/llm/token-meter/README.zh.md | 6 +- .../token-meter/src/breakdown-projection.ts | 87 ++++++++ packages/llm/token-meter/src/estimate.ts | 87 ++++++++ packages/llm/token-meter/src/index.ts | 66 +----- packages/llm/token-meter/src/projection.ts | 19 ++ packages/llm/token-meter/src/types.ts | 2 +- .../context-breakdown-projection.spec.ts | 195 ++++++++++++++++++ 45 files changed, 1654 insertions(+), 241 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md create mode 100644 .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md create mode 100644 .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md create mode 100644 .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md create mode 100644 packages/client/runtime/src/client/sessions/assistant-timing.ts create mode 100644 packages/client/ui-conversation/src/client/chat/turn-metrics.ts create mode 100644 packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css create mode 100644 packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx create mode 100644 packages/client/ui-conversation/tests/context-meter.spec.tsx create mode 100644 packages/client/ui-conversation/tests/turn-metrics.spec.ts create mode 100644 packages/llm/token-meter/src/breakdown-projection.ts create mode 100644 packages/llm/token-meter/src/estimate.ts create mode 100644 packages/llm/token-meter/tests/context-breakdown-projection.spec.ts diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml new file mode 100644 index 0000000000..1cf49844ab --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md +2026-08-04-web-latency-throughput-metrics.md: f891ce8d2f772c66d5affba2d89694d0eeb681b6 +2026-08-04-web-latency-throughput-metrics.zh.md: e62f5ad6341cffe052118871b57e27f5380c2fd1 diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md new file mode 100644 index 0000000000..f891ce8d2f --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md @@ -0,0 +1,29 @@ +# Agent Note: Web turn and window latency/throughput metrics + +Status: implemented + +English | [中文](2026-08-04-web-latency-throughput-metrics.zh.md) + +## Problem + +The Web chat records per-step LLM timing (`stepStartTime` / `firstTokenTime` / `completedTime`) and per-step usage, and the trajectory view exposes them per step, but the chat surface answers neither "how responsive was this turn" nor "how fast is this session going": the assistant footer shows only the turn wall time, and the stats line folds only wall-time totals. + +## Decision + +A package-local fold, `ui-conversation`'s `chat/turn-metrics.ts`, is the single derivation from assistant nodes to latency/throughput readings. `assistantStepReading` turns one node into a step reading: TTFT needs both `stepStartTime` and `firstTokenTime`, decode span needs `firstTokenTime`, negative spans clamp to zero, and output tokens come from the untrusted `usage` value only when they are finite and non-negative. `deriveTurnMetrics` folds readings per turn: the lowest-numbered step owns the turn's TTFT slot, and throughput divides the summed output tokens by the summed decode spans over exactly the steps carrying both, so an unsampled step drops out instead of skewing the ratio; a turn with neither figure emits no entry. + +The assistant footer appends the readings to the existing hover-revealed time chrome after `Ran for`, as `TTFT {s}s · {tps} tok/s`, each omitted independently when unrecorded. ChatView shows a turn's readings only when that turn's `turnTimings` entry has an `endTime`: the loaded window is a contiguous log suffix, so an in-window settled turn carries every one of its steps and the first-step TTFT is genuine rather than a window artifact. `formatLatencySeconds` is unit-less so each locale template owns its second suffix (`TTFT {seconds}s` / `首 token {seconds}秒`). + +The stats line reuses the same step reading in its window fold: `deriveStats` accumulates TTFT sum/count and decode span/tokens, rendering a `TTFT avg … · … tok/s` group beside the LLM/tool wall times. Like those wall times the group is window-scoped and folds no billing; token accounting stays on the token-meter projections. + +## Alternatives considered + +**A durable session projection (token-meter shape).** A `ProjectionDefinition` folding step timings host-side would survive compaction and window paging and cover the whole log. Deferred, not rejected: projection state must stay O(1) (averages, not percentiles), it needs a host change plus a schema, and the chat stats line is already documented as window-scoped for its duration facts — the new group joins that scope. A later PR can add the durable projection without moving these readings. + +**Per-step footer chrome.** Showing each assistant message its own TTFT would attach chrome to mid-turn narration nodes, which the footer design deliberately keeps chrome-free; the trajectory view already exposes per-step timing detail. + +**Gating footer metrics on node presence instead of `turn/end` timing.** Rendering whatever steps happen to be loaded would show a plausible-looking TTFT that is actually the first *loaded* step after paging. The `endTime` gate plus the suffix-window invariant makes the displayed figure the turn's true first-step latency or nothing. + +## Consequences + +A settled in-window turn's footer reveals `TTFT`/`tok/s` on hover after the wall time, and the stats line shows window-average latency and throughput beside its wall times, all without new session events or host changes. Metrics degrade by omission: providers or steps without timing or usage samples drop individual figures rather than rendering zeros. Older history outside the loaded window stays uncounted, recorded in the package README's stats-line limitation. diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md new file mode 100644 index 0000000000..e62f5ad634 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md @@ -0,0 +1,29 @@ +# Agent Note: Web 轮次与窗口级延迟/吞吐指标 + +Status: implemented + +[English](2026-08-04-web-latency-throughput-metrics.md) | 中文 + +## 问题 + +Web 聊天已经记录了逐步骤的 LLM 计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。 + +## 决策 + +包内折算 `ui-conversation` 的 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长收敛为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。 + +assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、`用时` 之后，形如 `首 token {s}秒 · {tps} tok/s`，未记录的数字各自省略。ChatView 仅在该轮次的 `turnTimings` 条目带有 `endTime` 时才显示读数：已加载窗口是日志的连续后缀，因此窗口内已结算的轮次必然带着它的全部步骤，首步 TTFT 是真实值而非窗口截断的产物。`formatLatencySeconds` 不带单位，各语言模板各自拥有秒后缀（`TTFT {seconds}s`／`首 token {seconds}秒`）。 + +统计行在其窗口折算中复用同一份步骤读数：`deriveStats` 累计 TTFT 总和/计数与解码时长/token 数，在 LLM／工具墙钟时间旁渲染 `TTFT avg … · … tok/s` 分组。与那些墙钟时间一样，该分组是窗口作用域的，不折算任何计费；token 账目仍归 token-meter 投影。 + +## 考虑过的替代方案 + +**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR 可以在不挪动这些读数的情况下补上持久投影。 + +**逐步骤页脚附属元素。** 让每条 assistant 消息显示自己的 TTFT，会给轮次中段的叙述节点挂上附属元素，而页脚设计刻意让它们保持无 chrome；trajectory 视图已经暴露逐步骤计时细节。 + +**用节点是否在场而非 `turn/end` 计时做页脚门控。** 直接渲染碰巧加载到的步骤，会展示一个貌似合理、实为分页后「首个已加载步骤」的 TTFT。`endTime` 门控加上后缀窗口不变量，使显示的数字要么是该轮次真实的首步延迟，要么什么都不显示。 + +## 后果 + +窗口内已结算轮次的页脚在 hover 时于实际耗时之后显示 `首 token`／`tok/s`，统计行在墙钟时间旁显示窗口平均延迟与吞吐，全程不新增会话事件、不改 host。指标以省略的方式退化：没有计时或 usage 采样的提供方或步骤只是丢掉对应数字，而不会渲染成零。已加载窗口之外的更早历史仍不计入，已记录在包 README 的统计行限制中。 diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml new file mode 100644 index 0000000000..c0727e7f3b --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md +2026-08-05-composer-context-meter-breakdown.md: 2879030aa7859385b2e6026fbf87da4548c392bd +2026-08-05-composer-context-meter-breakdown.zh.md: 3aeff68ebd157c4104fc085ad19e1738ead8f983 diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md new file mode 100644 index 0000000000..2879030aa7 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md @@ -0,0 +1,31 @@ +# Agent Note: Composer context meter with heuristic composition breakdown + +Status: implemented + +English | [中文](2026-08-05-composer-context-meter-breakdown.zh.md) + +## Problem + +The Web chat's stats line showed context occupancy as one inline figure (`Context N% of X`) among its billing groups. That answers "how full" but not "what fills it": nothing showed how the window divides between the system prompt, tool schemas, and conversation, and the one-line row has no room for that detail. The available numbers also live in two vocabularies — the provider-exact billed prompt size from `contextPressure` versus the token-meter's fixed character heuristic — and no existing surface could present composition without conflating them. + +## Decision + +Three cooperating pieces, one per package boundary: + +`dsh-session` exports the pure `deriveEventMessage(event)` (previously reachable only as a `Session` method, which now delegates to it) so a host-side fold can price surface nodes without a `Session` instance. + +`dsh-token-meter` extracts its pricing heuristic into `src/estimate.ts` — shared verbatim by the measurement service — and registers a third session projection, `contextBreakdown`, carrying `systemTokens` / `toolsTokens` / `messageTokens`. Envelope figures reprice last-wins on each `request/header` through `canonicalHeader`; the message figure folds surface appends and positional replacements over a per-node `{seq, tokens}` list, so compaction shrinks it the same way it shrinks the next request. A replace range absent from the folded surface throws: committed logs are surface-validated at append time, so an unresolvable range is log corruption, not a skippable event. + +`ui-conversation` moves context occupancy off the stats line (one home per fact) onto a composer-trailing `ContextMeter`: a 14px occupancy ring after the model seat fed by `contextPressure`, click-opening a panel that pairs the provider-exact percent and `~used / capacity` header with a 4px color-segmented bar and `~`-prefixed composition rows. The two vocabularies deliberately never reconcile — the ring, header, and bar length stay provider-exact while the heuristic shares only proportion the bar's colored segments and rows, each marked `~` because the fixed 4-chars-per-token heuristic systematically underprices CJK text and code. + +## Alternatives considered + +**Deriving composition client-side from the loaded window.** The window is a contiguous log suffix: the `request/header` events carrying the system prompt and tool schemas may sit outside it, and paging would silently change the figures. Only a durable host-side projection survives paging and compaction, which is why the data crosses the wire as a third projection rather than a chat-window fold. + +**Scaling the heuristic rows to sum to `pressureTokens`.** Forced reconciliation fabricates precision: pressure lags one request, includes provider envelope overhead the estimator never models, and would make the rows move when nothing in the composition changed. Showing the estimator's real vocabulary with an explicit `~` was chosen instead. + +**Finer categories (rules, skills, MCP tools) as in Claude Code's `/context`.** Not separable here: the harness folds those contributions into the system text and the tools list before the request header exists, so three categories are the honest resolution. + +## Consequences + +Token-meter now registers three projection keys; unloading removes all three, and `contextBreakdown` restores from JSON checkpoints (`stateVersion` 1). The stats line dropped its Context group and the ring is the sole context UI. The panel's heuristic rows visibly disagree with the provider-exact header — accepted and signposted by the `~` prefix; improving estimate accuracy (for example CJK-aware weighting) is localized to `estimate.ts` and changes no seam. The legend's purple segment tint is a literal color because the design platform ships no purple static token. diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md new file mode 100644 index 0000000000..3aeff68ebd --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md @@ -0,0 +1,31 @@ +# Agent Note: composer 上下文占用圆环与启发式组成明细 + +Status: implemented + +[English](2026-08-05-composer-context-meter-breakdown.md) | 中文 + +## 问题 + +Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费 prompt 规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。 + +## 决定 + +三个协作部分，每个包边界一个： + +`dsh-session` 导出纯函数 `deriveEventMessage(event)`（此前只能通过 `Session` 方法访问，该方法现在委托给它），使 host 侧 fold 无需 `Session` 实例即可为表层节点计价。 + +`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`（与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字用逐节点 `{seq, tokens}` 列表折叠表层追加与位置替换，因此压缩会像缩小下一个请求那样缩小它。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。 + +`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题，与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——圆环、标题与进度条总长保持提供方精确值，启发式占比只用于切分进度条的彩色分段与明细行，且每个启发式数字都标 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。 + +## 备选方案 + +**在客户端从已加载窗口推导组成。** 窗口是日志的连续后缀：携带系统提示词与工具 schema 的 `request/header` 事件可能在窗口之外，翻页还会让数字悄悄变化。只有持久的 host 侧投影能在翻页与压缩后幸存，这正是数据以第三个投影而非聊天窗口 fold 的形式过线的原因。 + +**把启发式明细行按比例缩放到与 `pressureTokens` 相加一致。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。 + +**更细的类别（rules、skills、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。 + +## 后果 + +token-meter 现在注册三个投影键；卸载会移除全部三个，`contextBreakdown` 可从 JSON 检查点恢复（`stateVersion` 为 1）。统计行删除了 Context 分组，圆环成为唯一的上下文 UI。面板的启发式明细行与提供方精确的标题数字肉眼可见地不一致——已接受并以 `~` 前缀标示；提升估算精度（例如按 CJK 加权）只需改动 `estimate.ts`，不涉及任何 seam。图例的紫色分段色值是字面量，因为设计平台没有紫色静态 token。 diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index cb8cb3b3b2..77ab7ffbe0 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -1681,7 +1681,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) -Source: [`packages/core/session/src/index.ts:767`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:726`](../../packages/core/session/src/index.ts) ## `ctx.sessionTitle` — `SessionTitleService` @@ -2307,7 +2307,8 @@ Replay owner for one service-wide estimator and isolated per-session folds. measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement /** - * Heuristically price one model-visible message. + * Heuristically price one model-visible message (instance face of the pure + * {@link estimateMessage}). * @param message - message to price without mutation. * @returns content and role-framing tokens under the fixed service heuristic. */ @@ -2316,7 +2317,7 @@ estimateMessage(message: Message): number Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md) -Source: [`packages/llm/token-meter/src/index.ts:85`](../../packages/llm/token-meter/src/index.ts) +Source: [`packages/llm/token-meter/src/index.ts:78`](../../packages/llm/token-meter/src/index.ts) ## `ctx.toolResultPrune` — `ToolResultPruneService` diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml index 773df07254..fd0e1e9d9b 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/docs/core-data-structures/session.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/session.md -session.md: 6369c956df03c0d786db696c208b000300d5bfbc -session.zh.md: c39382b7e6c9b14f91c311cc80526a6fd8898e4c +session.md: 0d32b47585e01dd992167b6580245c5444f3891b +session.zh.md: ad3fb474c4f9c68ef33bf9f1ddea0a1a64b31de6 diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index 6369c956df..0d32b47585 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -487,15 +487,8 @@ declare class Session { */ deriveMessages(): Message[]; /** - * Project a single event into the LLM message it derives to, or null when - * it produces none — a non-surface event (chunk, boundary, log-only record) - * or an empty-content assistant/message (which exists only to host usage). - * The per-node pure function {@link deriveMessages} folds over the surface; - * an external reconstructor (or the dev invariant) folds the same function - * over a log prefix's surface to rebuild the exact messages any request was - * built from (the reconstructability Agent Note). The returned message is - * the already frozen message nested in the event wrapper and shared by - * delivery, durable history, and model requests. + * Instance face of the pure per-node projection rule + * {@link deriveEventMessage} (see its contract in `surface.ts`). * @param event - the event to project. * @returns the derived message, or null when the event produces none. */ diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md index c39382b7e6..ad3fb474c4 100644 --- a/docs/core-data-structures/session.zh.md +++ b/docs/core-data-structures/session.zh.md @@ -489,15 +489,8 @@ declare class Session { */ deriveMessages(): Message[]; /** - * Project a single event into the LLM message it derives to, or null when - * it produces none — a non-surface event (chunk, boundary, log-only record) - * or an empty-content assistant/message (which exists only to host usage). - * The per-node pure function {@link deriveMessages} folds over the surface; - * an external reconstructor (or the dev invariant) folds the same function - * over a log prefix's surface to rebuild the exact messages any request was - * built from (the reconstructability Agent Note). The returned message is - * the already frozen message nested in the event wrapper and shared by - * delivery, durable history, and model requests. + * Instance face of the pure per-node projection rule + * {@link deriveEventMessage} (see its contract in `surface.ts`). * @param event - the event to project. * @returns the derived message, or null when the event produces none. */ diff --git a/packages/client/runtime/src/client/session-history/history-fold.ts b/packages/client/runtime/src/client/session-history/history-fold.ts index c4bc6ed9b5..c52bc17794 100644 --- a/packages/client/runtime/src/client/session-history/history-fold.ts +++ b/packages/client/runtime/src/client/session-history/history-fold.ts @@ -16,6 +16,8 @@ import type { } from '../sessions/conversation-context.ts' import type { ConversationPromptSnapshot } from '../sessions/request-inspection.ts' import { PartialAccumulator } from '../sessions/partial.ts' +import type { AssistantStepMetadata } from '../sessions/assistant-timing.ts' +import { indexAssistantStepTiming, settledAssistantTiming } from '../sessions/assistant-timing.ts' interface CallIndexEntry { name: string @@ -30,11 +32,6 @@ interface FoldedContext { originSeq?: number } -interface AssistantStepMetadata { - stepStartTime: number | null - firstTokenTime: number | null -} - /** Immutable conversation projections derived only from the history source. */ export interface ConversationHistoryProjection { eventNodes: readonly ConversationNode[] @@ -45,10 +42,6 @@ export interface ConversationHistoryProjection { codeDispatches: ReadonlyMap } -function assistantStepKey(turn: number, step: number): string { - return `${turn}\u0000${step}` -} - // Trajectory owns surface-window reconstruction so its immutable ledger does // not depend on Chat's live fold adapter or Session's mutable state. /* jscpd:ignore-start */ @@ -72,18 +65,6 @@ function contextOriginKind(event: SessionEvent | undefined): ConversationContext return 'rewrite' } -function isTokenDelta(chunk: SessionEvent<'assistant/chunk'>['data']['chunk']): boolean { - switch (chunk.type) { - case 'text-delta': - case 'reasoning-delta': - return chunk.text !== '' - case 'tool-call-delta': - return chunk.argumentsDelta !== '' || chunk.name !== undefined - default: - return false - } -} - function foldContexts(events: readonly SessionEvent[]): readonly FoldedContext[] { const replay: SessionEvent[] = [] const surface = new SurfaceManager(replay) @@ -362,6 +343,7 @@ export function projectConversationHistory( contextGeneration++ if (activePrompt !== undefined) promptsByContext.set(contextGeneration, activePrompt) } + indexAssistantStepTiming(assistantSteps, event) if (event.type === 'request/header') { activeRequestConfig = event.data.header.config activePrompt = { @@ -370,30 +352,10 @@ export function projectConversationHistory( tools: event.data.header.tools ?? [], } promptsByContext.set(contextGeneration, activePrompt) - } else if (event.type === 'step/start') { - assistantSteps.set( - assistantStepKey(event.data.turn, event.data.step), - { stepStartTime: event.time, firstTokenTime: null }, - ) - } else if (event.type === 'assistant/chunk' && isTokenDelta(event.data.chunk)) { - const key = assistantStepKey(event.data.turn, event.data.step) - const current = assistantSteps.get(key) ?? { - stepStartTime: null, - firstTokenTime: null, - } - if (current.firstTokenTime === null) { - assistantSteps.set(key, { ...current, firstTokenTime: event.time }) - } } else if (event.type === 'assistant/message') { assistantTimings.set( event.seq, - { - ...(assistantSteps.get(assistantStepKey(event.data.turn, event.data.step)) ?? { - stepStartTime: null, - firstTokenTime: null, - }), - completedTime: event.time, - }, + settledAssistantTiming(assistantSteps, event.data.turn, event.data.step, event.time), ) if (activeRequestConfig !== undefined) { assistantRequestConfigs.set(event.seq, activeRequestConfig) diff --git a/packages/client/runtime/src/client/sessions/assistant-timing.ts b/packages/client/runtime/src/client/sessions/assistant-timing.ts new file mode 100644 index 0000000000..021c679d04 --- /dev/null +++ b/packages/client/runtime/src/client/sessions/assistant-timing.ts @@ -0,0 +1,84 @@ +// Shared assistant step-timing fold: both transcript projections (the live +// window adapter and the trajectory history fold) derive AssistantTiming from +// the same step/start -> first token delta -> assistant/message sequence, so +// the derivation lives once here instead of drifting per projection. + +import type { SessionEvent } from '@deepseek-ai/dsh-session/types' +import type { AssistantTiming } from './conversation.ts' + +/** Pre-finalize timing boundaries for one assistant step (start + first token). */ +export interface AssistantStepMetadata { + stepStartTime: number | null + firstTokenTime: number | null +} + +/** + * Composite map key for one assistant step. + * @param turn - turn number from the event payload. + * @param step - step number from the event payload. + * @returns collision-free `turn`/`step` key (NUL separator). + */ +export function assistantStepKey(turn: number, step: number): string { + return `${turn}\u0000${step}` +} + +/** + * Whether a chunk carries visible model output (first-token boundary). Empty + * deltas (heartbeats, empty tool-call frames) do not count as a first token. + * @param chunk - the assistant/chunk payload. + * @returns true when the chunk contains a non-empty text/reasoning/tool delta. + */ +export function isTokenDelta(chunk: SessionEvent<'assistant/chunk'>['data']['chunk']): boolean { + switch (chunk.type) { + case 'text-delta': + case 'reasoning-delta': + return chunk.text !== '' + case 'tool-call-delta': + return chunk.argumentsDelta !== '' || chunk.name !== undefined + default: + return false + } +} + +/** + * Fold one event into the per-step timing index: step/start opens the entry, + * the first non-empty token delta stamps first-token time once. Other event + * types are no-ops. + * @param steps - the mutable per-step index, keyed by {@link assistantStepKey}. + * @param event - the raw window event. + */ +export function indexAssistantStepTiming(steps: Map, event: SessionEvent): void { + if (event.type === 'step/start') { + steps.set( + assistantStepKey(event.data.turn, event.data.step), + { stepStartTime: event.time, firstTokenTime: null }, + ) + } else if (event.type === 'assistant/chunk' && isTokenDelta(event.data.chunk)) { + const key = assistantStepKey(event.data.turn, event.data.step) + const current = steps.get(key) ?? { stepStartTime: null, firstTokenTime: null } + if (current.firstTokenTime === null) { + steps.set(key, { ...current, firstTokenTime: event.time }) + } + } +} + +/** + * Settle one finalized assistant message's timing from its step entry; a step + * whose start or first token fell outside the window yields null boundaries. + * @param steps - the per-step index built by {@link indexAssistantStepTiming}. + * @param turn - the assistant/message turn number. + * @param step - the assistant/message step number. + * @param completedTime - the assistant/message event timestamp (epoch ms). + * @returns the node-ready timing record. + */ +export function settledAssistantTiming( + steps: ReadonlyMap, + turn: number, + step: number, + completedTime: number, +): AssistantTiming { + return { + ...(steps.get(assistantStepKey(turn, step)) ?? { stepStartTime: null, firstTokenTime: null }), + completedTime, + } +} diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts index 05ac3cb067..a59abd03f5 100644 --- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts +++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts @@ -22,6 +22,8 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client' import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts' import { toAssistantBlocks } from './conversation.ts' +import type { AssistantStepMetadata } from './assistant-timing.ts' +import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts' /** * The compaction seam's checkpoint plugin, pinned to the seam's own declaration @@ -50,6 +52,7 @@ function materializeNode( event: SessionEvent, callIndex: ReadonlyMap, resultView: ToolResultView | null, + stepTimings: ReadonlyMap, ): ConversationNode { switch (event.type) { case 'user/message': @@ -71,6 +74,7 @@ function materializeNode( kind: 'assistant', seq: event.seq, time: event.time, turn: event.data.turn, step: event.data.step, blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage, + timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time), } case 'steering/message': return { @@ -177,6 +181,8 @@ export class TranscriptAdapter { /** Transcript nodes in log order; copy-on-write so a published array never mutates. */ private projected: ConversationNode[] = [] private callIdx = new Map() + /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */ + private stepTimings = new Map() /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */ private resultViews = new Map() /** @@ -207,6 +213,7 @@ export class TranscriptAdapter { this.callIdx = new Map() this.resultViews.clear() this.commandIdx = new Map() + this.stepTimings = new Map() for (let i = 0; i < events.length; i++) { const event = events[i] /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */ @@ -214,6 +221,7 @@ export class TranscriptAdapter { this.eventIndex.set(event.seq, event) this.indexCall(event, views?.[i]) this.indexCommand(event) + indexAssistantStepTiming(this.stepTimings, event) } // Indexes first, then project: a tool/result materializes against the // complete call index, and a checkpoint against the complete event index. @@ -236,6 +244,7 @@ export class TranscriptAdapter { append(event: SessionEvent, view?: ToolEventView): void { this.eventIndex.set(event.seq, event) this.indexCall(event, view) + indexAssistantStepTiming(this.stepTimings, event) if (this.indexCommand(event)) this.rev++ if (!isTranscriptEvent(event)) return this.projected = [...this.projected, this.materialize(event)] @@ -274,7 +283,7 @@ export class TranscriptAdapter { private materialize(event: SessionEvent): ConversationNode { return isCompactCheckpoint(event) ? materializeCompaction(event, this.eventIndex) - : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null) + : materializeNode(event, this.callIdx, this.resultViews.get(event.seq) ?? null, this.stepTimings) } /** diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts index cc03d349b8..352f85cee1 100644 --- a/packages/client/runtime/tests/transcript-adapter.spec.ts +++ b/packages/client/runtime/tests/transcript-adapter.spec.ts @@ -415,4 +415,48 @@ describe('TranscriptAdapter', () => { expect(nodes[1]).toMatchObject({ name: 'compact', outcome: { kind: 'success', text: '已压缩' } }) }) }) + + describe('assistant timing', () => { + const base = 1_700_000_000_000 + + it('derives step timing across a window rebuild (start + first token + completion)', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ + ev.turnStart(0, 0), + ev.user(1, '问'), + ev.stepStart(2, 0), + ev.chunkStart(3, 0), + ev.chunkText(4, 0, '答'), + ev.chunkText(5, 0, '案'), + ev.assistant(6, 0, '答案'), + ev.turnEnd(7, 0), + ]) + const assistant = adapter.nodes().find(n => n.kind === 'assistant') + expect(assistant).toMatchObject({ + timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 }, + }) + }) + + it('derives the same timing on the live append path, first token winning once', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.user(0, '问')]) + adapter.append(ev.stepStart(1, 0)) + adapter.append(ev.chunkText(2, 0, '首')) + adapter.append(ev.chunkText(3, 0, '次')) + adapter.append(ev.assistant(4, 0, '首次')) + const assistant = adapter.nodes().find(n => n.kind === 'assistant') + expect(assistant).toMatchObject({ + timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 }, + }) + }) + + it('soft-falls to null boundaries when the step opening fell outside the window', () => { + const adapter = new TranscriptAdapter() + adapter.reset([ev.assistant(100, 0, '被切窗的答案')]) + const assistant = adapter.nodes().find(n => n.kind === 'assistant') + expect(assistant).toMatchObject({ + timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 }, + }) + }) + }) }) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index bf1e21a541..7401962fea 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 7d3a4b5fe07cc8858c2f2059e6f65b6e27602b4d -README.zh.md: d93af91381157bb4e8e4b6a14ad00edecd505246 +README.md: 737a53da1fa4541f81d89b41945cacd2b415ef4a +README.zh.md: 800d2b3e762d410100c8c9eb64bfbcdb22cda62a diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 7d3a4b5fe0..737a53da1f 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -46,7 +46,7 @@ Per-session UI state for selection and the active view lives in the declared cha The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists. -The chat stats line takes its token accounting from two generic token-meter projections read through the standard-kit `useProjection`: `tokenUsage` for full-log billing (billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total) and `contextPressure` for context occupancy. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. A deployment without token-meter drops the token groups, and occupancy stays hidden until both provider pressure and route capacity are known. Occupancy is deliberately an approximation — its numerator and capacity are independent last-wins projection fields, not one atomic request observation ([rationale](../../llm/token-meter/README.md)). The inline stats row remains the sole context UI; the model selector has no circle or accessory. +The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a `TTFT avg … · … tok/s` group; a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both provider pressure and route capacity are known, that click-opens a panel pairing the provider-exact `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection — the exact and heuristic vocabularies deliberately do not reconcile. Occupancy is deliberately an approximation — its numerator and capacity are independent last-wins projection fields, not one atomic request observation ([rationale](../../llm/token-meter/README.md)). `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath). @@ -61,7 +61,7 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work - **Compaction markers show no scale** — the row does not yet report how many messages or which range the checkpoint replaced. -- **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted. +- **Stats-line durations and speeds cover the in-window flow only** — LLM and tool wall times plus the TTFT and throughput averages fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted. - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly. - **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / clock / branch) ships under the last content-text assistant of each turn only; mid-turn narration and Think-only nodes stay chrome-free. Branch stays disabled unless that message is also the last transcript node of a completed turn; when enabled, it forks through that turn, increments the inherited title on the client, and opens the child. A fork or rename failure leaves the source selected ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)). - **Sent user messages cannot be edited** — user bubbles retain clock, copy, and branch; branch stays disabled unless a completed turn's transcript ends at that user message. Editing returns with the capability behind it: a client mutation over a settled user message, plus the host behavior for the turn that already consumed it ([decision](../../../.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md)). diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index d93af91381..800d2b3e76 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -46,7 +46,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。 -聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的两个通用 token-meter 投影：`tokenUsage` 提供完整日志计费用量（计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量），`contextPressure` 提供上下文占用率。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。未组合 token-meter 的部署会整组省略 token 分组；只有提供方压力与路由容量都已知时才显示占用率。占用率是刻意为之的近似值：它的分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测（[原理](../../llm/token-meter/README.md)）。行内统计行仍是唯一的上下文 UI；模型选择器不增加圆环或附属控件。 +聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到 `TTFT avg … · … tok/s` 分组；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当提供方压力与路由容量都已知时才渲染；点击弹出的面板把提供方精确的「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列——精确口径与启发式口径刻意不做对账。占用率是刻意为之的近似值：它的分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测（[原理](../../llm/token-meter/README.md)）。 `src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。 @@ -61,7 +61,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu ## 已知限制与暂缓事项 - **压缩标记不显示规模**：该行尚不报告检查点替换了多少条消息或哪段范围。 -- **统计行的耗时只覆盖窗口内消息流**：LLM 与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 +- **统计行的耗时与速率只覆盖窗口内消息流**：LLM 与工具墙钟时间以及 TTFT 与吞吐平均值由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。 - **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／时钟／分支）只挂在每个轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述与纯 Think 节点不带 chrome。除非该消息同时也是已完成轮次的最后一个 transcript 节点，否则分支保持禁用；启用后，它会 fork 到该轮次末尾，在 client 端递增继承标题并打开子会话。fork 或改名失败时源会话保持选中（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)）。 - **已发送的 user 消息无法编辑**：user 气泡保留时钟、复制和分支；除非已完成轮次的 transcript 结束于该 user 消息，否则分支保持禁用。编辑功能要与其背后的能力一起回归：既需要针对已定稿 user 消息的 client 变更，也需要 host 侧对已经消费过它的轮次给出行为（[决策](../../../.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md)）。 diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx index de882e8bb2..5b3b9fa821 100644 --- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx +++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx @@ -30,6 +30,10 @@ export interface AssistantMarkdownProps { /** Turn wall time in ms for the IconActions run-time label; omitted when the * turn's triggering input is outside the loaded window. */ runMs?: number | undefined + /** Turn first-step TTFT in ms for the IconActions label; omitted when unrecorded. */ + ttftMs?: number | undefined + /** Turn decode throughput for the IconActions label; omitted when unrecorded. */ + tokensPerSecond?: number | undefined /** Event sequence used as the fork boundary; omitted while streaming. */ seq?: number | undefined /** Fork the session through this finalized message's completed turn when eligible. */ @@ -82,7 +86,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass } export const AssistantMarkdown = memo(function AssistantMarkdown({ - blocks, streaming, interrupted, time, runMs, seq, onFork, forkUnavailable, t, + blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, t, }: AssistantMarkdownProps) { // Stable per locale revision (t identity changes on switch): a fresh object // per render would rebuild MarkdownText's component table every chunk. @@ -125,6 +129,8 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({ text={copyText(blocks)} time={time} runMs={runMs} + ttftMs={ttftMs} + tokensPerSecond={tokensPerSecond} clock="end" onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }} branchUnavailable={forkUnavailable} diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx index 3320eb0f69..c852161240 100644 --- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx +++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx @@ -36,6 +36,7 @@ import { GenericCommandCard } from './GenericCommandCard.tsx' import { GenericToolCard } from './GenericToolCard.tsx' import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx' import { formatRunDuration } from './message-chrome.ts' +import { deriveTurnMetrics } from './turn-metrics.ts' import css from './ChatView.module.css' const FOLLOW_THRESHOLD = 24 @@ -362,6 +363,7 @@ export function ChatView({ const actionSeqs = useMemo(() => assistantActionsSeqs(nodes), [nodes]) const branchSeqs = useMemo(() => messageBranchSeqs(nodes, turnEnds), [nodes, turnEnds]) const runningTurnStart = useMemo(() => runningTurnStartTime(turnTimings), [turnTimings]) + const turnMetrics = useMemo(() => deriveTurnMetrics(nodes), [nodes]) const listRef = useRef(null) const columnRef = useRef(null) @@ -599,6 +601,9 @@ export function ChatView({ const node: ConversationNode = item.node if (node.kind === 'assistant') { const timing = actionSeqs.has(node.seq) ? turnTimings.get(node.turn) : undefined + // Metrics gate on the settled in-window timing: turn/start loaded means + // every step of the turn is loaded, so first-step TTFT is genuine. + const metrics = timing?.endTime === undefined ? undefined : turnMetrics.get(node.turn) return ( )} + {ttftMs !== undefined && ( + <> + · + {t('message.ttft', { seconds: formatLatencySeconds(ttftMs) })} + + )} + {tokensPerSecond !== undefined && ( + <> + · + {t('message.tokensPerSecond', { tps: formatTokensPerSecond(tokensPerSecond) })} + + )} ) return ( diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx index ceffffb59a..d30c8dbf0e 100644 --- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx +++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx @@ -2,10 +2,13 @@ // Mounted on 'conversation.composer.dock' so it sticks with the composer in the // active conversation scrollport (see ConversationRoot data-conversation-scroll). -import { Fragment, memo, useMemo } from 'react' +import { Fragment, memo, useLayoutEffect, useMemo, useRef, useState } from 'react' +import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives' import type { ConversationSnapshot, UseProjection } from '@deepseek-ai/dsh-client-runtime/client' import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots' import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client' +import { formatTokensPerSecond } from './message-chrome.ts' +import { assistantStepReading } from './turn-metrics.ts' import css from './StatsLine.module.css' interface WindowStats { @@ -15,6 +18,14 @@ interface WindowStats { llmMs: number /** Summed tool wall time (tool/call → tool/result); 0 when no pair is in-window. */ toolMs: number + /** Summed first-token latency over `ttftSteps`; 0 when no step records it. */ + ttftMs: number + /** Steps carrying a recorded TTFT. */ + ttftSteps: number + /** Summed decode wall time over steps that also report output tokens. */ + decodeMs: number + /** Summed output tokens over the same decode-timed steps. */ + decodeTokens: number } /** @@ -32,6 +43,10 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats { let steps = 0 let llmMs = 0 let toolMs = 0 + let ttftMs = 0 + let ttftSteps = 0 + let decodeMs = 0 + let decodeTokens = 0 for (const node of nodes) { if (node.kind === 'tool-result') { if (node.callTime !== null) toolMs += Math.max(0, node.time - node.callTime) @@ -43,8 +58,17 @@ export function deriveStats(nodes: ConversationSnapshot['nodes']): WindowStats { if (node.timing !== undefined && node.timing.stepStartTime !== null) { llmMs += Math.max(0, node.timing.completedTime - node.timing.stepStartTime) } + const reading = assistantStepReading(node) + if (reading.ttftMs !== null) { + ttftMs += reading.ttftMs + ttftSteps += 1 + } + if (reading.decodeMs !== null && reading.outputTokens !== null) { + decodeMs += reading.decodeMs + decodeTokens += reading.outputTokens + } } - return { turns: turns.size, steps, llmMs, toolMs } + return { turns: turns.size, steps, llmMs, toolMs, ttftMs, ttftSteps, decodeMs, decodeTokens } } /** @@ -84,13 +108,18 @@ export function cacheHitPercent(usage: TokenUsageProjection): number | null { : Math.round(usage.cacheReadTokens / denominator * 100) } -/** Sum the three disjoint prompt-side billing buckets. */ -function billedInputTokens(usage: TokenUsageProjection): number { +/** + * Sum the three disjoint prompt-side billing buckets. + * @param usage - the session's token-usage projection value. + * @returns billed input tokens. + */ +export function billedInputTokens(usage: TokenUsageProjection): number { return usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens } interface ContextOccupancy { percent: number + pressureTokens: number contextWindow: number } @@ -100,7 +129,7 @@ interface ContextOccupancy { * fields, so this is a reference figure rather than an exact measurement of one * request (see the token-meter README). * @param pressure - the session's context-pressure projection value. - * @returns occupancy and its denominator, or null until both values are known. + * @returns occupancy with its numerator and denominator, or null until both values are known. */ export function contextOccupancy( pressure: ContextPressureProjection | undefined, @@ -108,6 +137,7 @@ export function contextOccupancy( if (pressure?.pressureTokens === undefined || pressure.contextWindow === undefined) return null return { percent: Math.min(100, Math.round(pressure.pressureTokens / pressure.contextWindow * 100)), + pressureTokens: pressure.pressureTokens, contextWindow: pressure.contextWindow, } } @@ -121,7 +151,6 @@ export interface StatsLineProps { export const StatsLine = memo(function StatsLine({ useSession, useProjection }: StatsLineProps) { const nodes = useSession(s => s.nodes) const usage = useProjection('tokenUsage') - const pressure = useProjection('contextPressure') const stats = useMemo(() => deriveStats(nodes), [nodes]) // Pipe-separated groups (figma stats strip); a group with no data drops out whole. const groups: string[] = [] @@ -131,11 +160,14 @@ export const StatsLine = memo(function StatsLine({ useSession, useProjection }: if (stats.llmMs > 0) durations.push(`LLM ${formatDuration(stats.llmMs)}`) if (stats.toolMs > 0) durations.push(`Tool call ${formatDuration(stats.toolMs)}`) if (durations.length > 0) groups.push(durations.join(' · ')) + // Window-scoped like the wall times above: averages describe loaded steps. + const speeds: string[] = [] + if (stats.ttftSteps > 0) speeds.push(`TTFT avg ${formatDuration(stats.ttftMs / stats.ttftSteps)}`) + if (stats.decodeMs > 0) speeds.push(`${formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000))} tok/s`) + if (speeds.length > 0) groups.push(speeds.join(' · ')) } - const context = contextOccupancy(pressure) - if (context !== null) { - groups.push(`Context ${context.percent}% of ${formatTokens(context.contextWindow)}`) - } + // Context occupancy deliberately lives on the composer's ContextMeter ring, + // not here — one home per fact. // Billing rides the durable projection, so these survive paging and // compaction. Suppress the empty projection on a brand-new session. if (usage !== undefined @@ -147,15 +179,31 @@ export const StatsLine = memo(function StatsLine({ useSession, useProjection }: + ` · Output ${formatTokens(usage.outputTokens)} tok`, ) } + const line = groups.join(' | ') + // The row elides with ellipsis when overlong; a delayed hover tooltip carries + // the full line, enabled only while content is actually clipped. + const rootRef = useRef(null) + const [truncated, setTruncated] = useState(false) + useLayoutEffect(() => { + const el = rootRef.current + if (el === null) return + const measure = () => { setTruncated(el.scrollWidth > el.clientWidth) } + measure() + const observer = new ResizeObserver(measure) + observer.observe(el) + return () => { observer.disconnect() } + }, [line]) if (groups.length === 0) return null return ( -
- {groups.map((group, i) => ( - - {i > 0 && <>|{' '}} - {group} - - ))} -
+ +
+ {groups.map((group, i) => ( + + {i > 0 && <>|{' '}} + {group} + + ))} +
+ ) }) diff --git a/packages/client/ui-conversation/src/client/chat/message-chrome.ts b/packages/client/ui-conversation/src/client/chat/message-chrome.ts index 5837957011..a3658853c9 100644 --- a/packages/client/ui-conversation/src/client/chat/message-chrome.ts +++ b/packages/client/ui-conversation/src/client/chat/message-chrome.ts @@ -48,6 +48,27 @@ export function formatRunDuration(ms: number, t: RunDurationTranslate): string { : t('duration.seconds', { seconds }) } +/** + * Sub-turn latency figure: one decimal under ten seconds, whole seconds + * beyond. Unit-less so the locale template owns the second suffix. + * @param ms - Latency in milliseconds (negatives clamp to zero). + * @returns Display number in seconds without unit. + */ +export function formatLatencySeconds(ms: number): string { + const s = Math.max(0, ms) / 1000 + return s < 10 ? String(Math.round(s * 10) / 10) : String(Math.round(s)) +} + +/** + * Decode-throughput figure: whole tokens from ten up, one decimal below. + * @param tps - Tokens per second. + * @returns Display number without unit. + */ +export function formatTokensPerSecond(tps: number): string { + const clamped = Math.max(0, tps) + return clamped >= 10 ? String(Math.round(clamped)) : String(Math.round(clamped * 10) / 10) +} + /** * Compact local timestamp for message IconActions. Same calendar day → * `HH:mm`; earlier this year → the `clock.md` date template + clock; other diff --git a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts new file mode 100644 index 0000000000..156a4c0e9d --- /dev/null +++ b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts @@ -0,0 +1,97 @@ +// Latency/throughput folds shared by the settled turn footer and StatsLine. + +import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client' + +/** Latency and decode-throughput readings for one turn's footer. */ +export interface TurnMetrics { + /** First-step TTFT in ms; absent when that step carries no recorded timing. */ + ttftMs?: number + /** Decode throughput over steps carrying both timing and provider usage. */ + tokensPerSecond?: number +} + +/** One assistant step's derivable latency facts; null marks an unrecorded part. */ +export interface StepReading { + /** step/start → first token delta, in ms. */ + ttftMs: number | null + /** First token delta → final message, in ms. */ + decodeMs: number | null + /** Provider-reported completion tokens. */ + outputTokens: number | null +} + +interface UsageLike { + outputTokens?: number +} + +type AssistantNode = Extract + +function usageOutputTokens(usage: unknown): number | null { + if (typeof usage !== 'object' || usage === null) return null + const value = (usage as UsageLike).outputTokens + return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null +} + +/** + * Read one assistant node's TTFT, decode wall time, and output tokens. + * @param node - A settled assistant node. + * @returns Per-part readings with `null` for unrecorded values. + */ +export function assistantStepReading(node: AssistantNode): StepReading { + const timing = node.timing + const ttftMs = timing !== undefined && timing.stepStartTime !== null && timing.firstTokenTime !== null + ? Math.max(0, timing.firstTokenTime - timing.stepStartTime) + : null + const decodeMs = timing !== undefined && timing.firstTokenTime !== null + ? Math.max(0, timing.completedTime - timing.firstTokenTime) + : null + return { ttftMs, decodeMs, outputTokens: usageOutputTokens(node.usage) } +} + +interface TurnFold { + firstStep: number + firstStepTtftMs: number | null + decodeMs: number + outputTokens: number + sampled: boolean +} + +/** + * Fold assistant nodes into per-turn footer metrics. + * + * TTFT is the turn's lowest-step reading — the user-perceived wait before + * output appeared — so it is only meaningful when the turn's start is inside + * the loaded window (the caller gates on `turnTimings`, which shares that + * window). Throughput divides summed output tokens by summed decode wall time, + * counting only steps that carry both. + * @param nodes - Snapshot nodes of the loaded window. + * @returns Turn number → available metrics; turns with none are absent. + */ +export function deriveTurnMetrics(nodes: ConversationSnapshot['nodes']): Map { + const folds = new Map() + for (const node of nodes) { + if (node.kind !== 'assistant') continue + const reading = assistantStepReading(node) + let fold = folds.get(node.turn) + if (fold === undefined) { + fold = { firstStep: node.step, firstStepTtftMs: reading.ttftMs, decodeMs: 0, outputTokens: 0, sampled: false } + folds.set(node.turn, fold) + } else if (node.step < fold.firstStep) { + fold.firstStep = node.step + fold.firstStepTtftMs = reading.ttftMs + } + if (reading.decodeMs !== null && reading.outputTokens !== null) { + fold.decodeMs += reading.decodeMs + fold.outputTokens += reading.outputTokens + fold.sampled = true + } + } + const metrics = new Map() + for (const [turn, fold] of folds) { + const entry: TurnMetrics = {} + if (fold.firstStepTtftMs !== null) entry.ttftMs = fold.firstStepTtftMs + if (fold.sampled && fold.decodeMs > 0) entry.tokensPerSecond = fold.outputTokens / (fold.decodeMs / 1000) + if (entry.ttftMs !== undefined || entry.tokensPerSecond !== undefined) metrics.set(turn, entry) + } + return metrics +} diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts index a9a4f9544e..344b2b64c7 100644 --- a/packages/client/ui-conversation/src/client/locales.ts +++ b/packages/client/ui-conversation/src/client/locales.ts @@ -23,6 +23,11 @@ export const zh = { 'input.stop': '停止生成', 'input.send': '发送消息', 'input.accessMode': '访问模式，当前：{name}', + 'context.aria': '上下文已用 {percent}%', + 'context.used': '上下文已用', + 'context.system': '系统提示词', + 'context.tools': '工具', + 'context.messages': '对话消息', 'settings.enter.title': '繁忙时 Enter 键行为', 'settings.enter.description': '仅在智能体运行时生效；Cmd/Ctrl+Enter 使用另一行为', 'settings.enter.queue': '排队发送', @@ -71,6 +76,8 @@ export const zh = { 'message.retry.failure': '失败原因：', 'message.turnError': '本轮运行失败', 'message.ranFor': '用时 {duration}', + 'message.ttft': '首 token {seconds}秒', + 'message.tokensPerSecond': '{tps} tok/s', 'duration.seconds': '{seconds}秒', 'duration.minutes': '{minutes}分{seconds}秒', 'command.running': '执行中…', @@ -136,6 +143,11 @@ export const en = { 'input.stop': 'Stop generating', 'input.send': 'Send message', 'input.accessMode': 'Access mode, current: {name}', + 'context.aria': '{percent}% of context used', + 'context.used': 'of context used', + 'context.system': 'System prompt', + 'context.tools': 'Tools', + 'context.messages': 'Messages', 'settings.enter.title': 'Enter behavior while busy', 'settings.enter.description': 'Busy only; Cmd/Ctrl+Enter uses the other behavior', 'settings.enter.queue': 'Queue', @@ -184,6 +196,8 @@ export const en = { 'message.retry.failure': 'Failure reason: ', 'message.turnError': 'This turn failed', 'message.ranFor': 'Ran for {duration}', + 'message.ttft': 'TTFT {seconds}s', + 'message.tokensPerSecond': '{tps} tok/s', 'duration.seconds': '{seconds}s', 'duration.minutes': '{minutes}m {seconds}s', 'command.running': 'Running…', diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css new file mode 100644 index 0000000000..9ded4d91c2 --- /dev/null +++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.module.css @@ -0,0 +1,141 @@ +/* Context-occupancy ring beside the send button plus its click-open breakdown + panel (menu surface: r12, inverted hairline, shadow-lv3). */ + +.root { + position: relative; + display: inline-flex; +} + +/* Same 28px circular hit target family as the composer's attach button. */ +.trigger { + display: grid; + place-items: center; + flex: none; + width: 28px; + height: 28px; + border: none; + border-radius: 999px; + background: transparent; + color: var(--dsw-alias-label-secondary); + cursor: pointer; +} + +.trigger:hover { + background: var(--dsw-alias-interactive-bg-hover); +} + +.track { + fill: none; + stroke: var(--dsw-alias-border-l3); + stroke-width: 2; +} + +.fill { + fill: none; + stroke: var(--dsw-alias-label-tertiary); + stroke-width: 2; + stroke-linecap: round; +} + +.panel { + position: absolute; + bottom: calc(100% + 8px); + right: 0; + z-index: 100; + box-sizing: border-box; + width: 264px; + padding: 12px; + border: 1px solid var(--dsw-alias-border-inverted); + border-radius: 12px; + background: var(--dsw-specific-menu); + box-shadow: var(--dsw-shadow-lv3); + font-size: 12px; + line-height: 20px; + color: var(--dsw-alias-label-secondary); + cursor: default; +} + +.header { + display: flex; + align-items: center; + gap: 6px; +} + +.figures { + margin-left: auto; + font-weight: 500; + font-variant-numeric: tabular-nums; + color: var(--dsw-alias-label-primary); +} + +.percent { + font-weight: 500; + color: var(--dsw-alias-label-primary); +} + +.headline { + color: var(--dsw-alias-label-tertiary); +} + +.bar { + display: flex; + gap: 1px; + margin: 10px 0 12px; + height: 4px; + border-radius: 999px; + background: var(--dsw-alias-interactive-bg-hover); + overflow: hidden; +} + +.segment { + flex: none; + min-width: 2px; + height: 100%; + border-radius: 1px; + background: var(--meter-tint, var(--dsw-alias-label-tertiary)); +} + +.swatch { + display: inline-block; + margin-right: 6px; + width: 8px; + height: 8px; + border-radius: 2px; + background: var(--meter-tint); + vertical-align: baseline; +} + +.colorSystem { + --meter-tint: var(--dsw-static-neutral-bluish-400); +} + +.colorTools { + /* The design platform ships no purple static token; violet-400 literal. */ + --meter-tint: rgb(167, 139, 250); +} + +.colorMessages { + --meter-tint: var(--dsw-static-blue-450); +} + +.rows { + margin: 6px 0 0; +} + +.row { + display: flex; + align-items: center; + justify-content: space-between; + gap: 12px; + padding: 2px 0; +} + +.row dt { + color: var(--dsw-alias-label-secondary); +} + +.row dd { + margin: 0; + font-variant-numeric: tabular-nums; + color: var(--dsw-alias-label-primary); +} diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx new file mode 100644 index 0000000000..1ce40d3e87 --- /dev/null +++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx @@ -0,0 +1,131 @@ +/** Composer context-occupancy meter: a ring beside the send button fed by the + * `contextPressure` projection, with a click-open panel of the heuristic + * `contextBreakdown` composition (system prompt, tools, conversation). + * Renders nothing until a provider reports both pressure and a route capacity + * (same gate as the stats row used). */ + +import { useEffect, useRef, useState } from 'react' +import type { UseProjection } from '@deepseek-ai/dsh-client-runtime/client' +// Type-only: the `contextPressure` / `contextBreakdown` projection key merges. +import type {} from '@deepseek-ai/dsh-token-meter/client' +import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives' +import type { ComposerBarProps } from '../contract/slots.ts' +import { contextOccupancy, formatTokens } from '../chat/StatsLine.tsx' +import css from './ContextMeter.module.css' + +/** Ring geometry: 14px viewBox, 2px stroke. */ +const RADIUS = 5.5 +const CIRCUMFERENCE = 2 * Math.PI * RADIUS + +/** Panel legend rows, in bar-segment order; each color class carries the shared swatch/segment tint. */ +const ROWS = [ + { key: 'systemTokens', label: 'context.system', color: css.colorSystem }, + { key: 'toolsTokens', label: 'context.tools', color: css.colorTools }, + { key: 'messageTokens', label: 'context.messages', color: css.colorMessages }, +] as const + +export interface ContextMeterProps { + useProjection: UseProjection + /** The owning bar's locale seat, passed down as a plain prop. */ + t: ComposerBarProps['t'] +} + +export function ContextMeter({ useProjection, t }: ContextMeterProps) { + const pressure = useProjection('contextPressure') + const breakdown = useProjection('contextBreakdown') + const [open, setOpen] = useState(false) + const rootRef = useRef(null) + + // Outside click / Escape close, one document listener while open (Menu's pattern). + useEffect(() => { + if (!open) return + const onPointerDown = (e: PointerEvent): void => { + if (e.target instanceof Node && rootRef.current?.contains(e.target) === true) return + setOpen(false) + } + const onKeyDown = (e: KeyboardEvent): void => { + if (e.key === 'Escape') setOpen(false) + } + document.addEventListener('pointerdown', onPointerDown) + document.addEventListener('keydown', onKeyDown) + return () => { + document.removeEventListener('pointerdown', onPointerDown) + document.removeEventListener('keydown', onKeyDown) + } + }, [open]) + + const context = contextOccupancy(pressure) + if (context === null) return null + const percent = context.percent + + // The bar's overall length stays the provider-exact percent; the heuristic + // breakdown only proportions its colored segments. + const breakdownTotal = breakdown === undefined + ? 0 + : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens + const segments = breakdown === undefined || breakdownTotal === 0 + ? null + : ROWS.map(row => ({ key: row.key, color: row.color, share: breakdown[row.key] / breakdownTotal })) + + return ( + + + + + {open && ( +
+
+ {`${percent}%`} + {t('context.used')} + + {`~${formatTokens(context.pressureTokens)} / ${formatTokens(context.contextWindow)}`} + +
+
+ {segments === null + ?
+ : segments.map(segment => ( +
+ ))} +
+ {breakdown !== undefined && ( +
+ {ROWS.map(row => ( +
+
+ + {t(row.label)} +
+
{`~${formatTokens(breakdown[row.key])}`}
+
+ ))} +
+ )} +
+ )} + + ) +} diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx index 5f09e7315a..131f63c49d 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx @@ -19,6 +19,7 @@ import type { Translate } from '@deepseek-ai/dsh-client-ui-slots' import type { ComposerBarProps } from '../contract/slots.ts' import { deriveDecorations } from '../input/decorations.ts' import type { DraftDecorations } from '../input/decorations.ts' +import { ContextMeter } from './ContextMeter.tsx' import { PermissionSelect } from './PermissionSelect.tsx' import css from './InputBar.module.css' @@ -512,6 +513,7 @@ export function InputBar({
{rightItems} {renderSlot('conversation.input.model', { locked })} + {/* {machineBusy && } */}