dsh-turn-performance-meter

A turn-level performance meter for DeepSeek Harness (DSH) agent workflows. It is designed for turns that may contain multiple model invocations, tool calls, retries, shell commands, file writes/edits, and a final answer. The plugin provides two UI modes: a compact live meter during execution and a completed turn card that aggregates the whole turn.

面向 DeepSeek Harness（DSH）Agent 工作流的 turn 级性能统计插件。它适用于一个 turn 内存在多次模型调用、工具调用、 重试、shell 命令、文件写入/编辑以及最终回答的场景。插件包含两种 UI：执行过程中的紧凑实时统计，以及 turn 完成后的统计 卡片。完成态卡片按整个 turn 聚合。

Released as v0.1.5 on npm and GitHub, for DSH 0.2.0-rc.2. Version 0.1.5, published to the public npm registry. The primary distribution is the npm package dsh-turn-performance-meter; the GitHub Release asset dsh-turn-performance-meter-0.1.5.tgz is an offline fallback, and the local checkout is for development. §2.1 holds the release/runtime matrix.

已发布 npm 与 GitHub v0.1.5，面向 DSH 0.2.0-rc.2。 版本 0.1.5，已发布到公开 npm registry。主要分发方式为 npm 包 dsh-turn-performance-meter；GitHub Release 资产 dsh-turn-performance-meter-0.1.5.tgz 作为离线回退，本地检出 目录用于开发。发布与运行时对应关系见 §2.1。

1. What it does / 功能

The statistical boundary is the whole turn, not a single model step. During generation the meter shows the active attempt's phase-cumulative TPS — the current phase episode's generated token mass over the wall time since that episode began — with an ≈ marker, once the episode holds at least three samples; before that it shows the episode's elapsed counter rather than an unstable rate. When no model decode is running it shows the stopwatch of whatever is running instead (tool execution, inter-step wait, retry backoff) and never a stale rate. When the turn settles, the same seat switches to a static completed card carrying turn-level Reasoning TPS, Output TPS, Generated Tokens, TTFT, a tool summary and the model-call count; hovering the card or focusing it with the keyboard replaces the two TPS columns with the throughput curve.

统计边界是整个 turn，而不是单个模型 step。生成期间实时组件显示当前活动 attempt 的相位累计 TPS（当前相位片段自起点以来 生成的 token 量除以该片段的墙钟时间），并始终带 ≈ 近似标记；该片段累计满 3 个样本之前，组件显示该片段的计时器而不是不稳定的速率。 非模型解码阶段（工具执行、步骤间隙、重试退避）显示正在进行的那个阶段各自的计时器，绝不显示过期的速率。 turn 结束后，同一位置切换为静态完成态卡片，承载 turn 级的思考 TPS、输出 TPS、生成 Tokens、首响应、工具摘要与模型调用 次数；鼠标悬停或用键盘聚焦时，前两个 TPS 栏位被吞吐曲线替换。

The meter occupies conversation.input.dock at order: -10, above the composer card; the native chat statistics keep their own seat (conversation.composer.dock) below it. Both views are projections of settled or live evidence — the React layer never re-derives a metric.

插件挂载在 conversation.input.dock、order: -10，位于输入框卡片上方；原生聊天统计保留其在输入框下方的原位置。 两个视图都只是既有证据的投影，React 层不重新计算任何指标。

2. Support status / 支持状态

Version (working tree): 0.1.5
Development target:     DSH 0.2.0-rc.2 only
Released:               v0.1.5 -> DSH 0.2.0-rc.2
                        v0.1.4 -> DSH 0.2.0-rc.2
                        v0.1.3 -> DSH 0.2.0-rc.2
                        v0.1.2 -> DSH 0.2.0-rc.2
                        v0.1.1 -> DSH 0.1.7-rc.2
Primary distribution:   npm
Fallback distribution:  GitHub Release .tgz
Development:            link checkout
Verification:           local automated suite + real DSH browser smoke

2.1 Compatibility baseline / 兼容性基线

plugin v0.1.1  ->  DSH 0.1.7-rc.2   reference commit 477b4f420553e8a52c2fbccc464d7561b239c443
plugin v0.1.2  ->  DSH 0.2.0-rc.2   reference commit 639ed015397290b3745d163aafe02ffee4aa3f84
plugin v0.1.3  ->  DSH 0.2.0-rc.2   reference commit 639ed015397290b3745d163aafe02ffee4aa3f84
plugin v0.1.4  ->  DSH 0.2.0-rc.2   reference commit 639ed015397290b3745d163aafe02ffee4aa3f84
plugin v0.1.5  ->  DSH 0.2.0-rc.2   reference commit 639ed015397290b3745d163aafe02ffee4aa3f84

0.2.0-rc.2 is the normative runtime for the current working tree. Phase 9.3 moved the development target to it and re-audited every DSH declaration this plugin reads — the session event envelope, the LLM stream and compact AssistantStreamRecord shapes, the session-controller event-window and settlement contracts, the conversation.input.dock slot contract, the plugin-compatibility gate, and the TodoPanel visual contract the completed card is drawn from. All fourteen declarations are byte-identical between the two reference commits, so the telemetry, stream, session and slot contracts consumed by the plugin did not change: no adapter code moved, no metric semantics moved, and no compatibility exemption is involved. The comparison is recorded in docs/DSH_API_NOTES.md §14.

The claim is bounded on purpose: it is not 0.2.0+, not 0.2.x and not "the latest DSH", because no other version has been exercised. Local evidence for the claim is the CLI (dsh --version), the installed package (npm list -g @deepseek-ai/dsh) and the composed profile tree, all recorded in docs/IMPLEMENTATION_LOG.md.

v0.1.2 is the release in which that target became the shipped one, and v0.1.3, v0.1.4 and v0.1.5 carry it forward unchanged: the working tree carries version: 0.1.5 with the same 0.2.0-rc.2 peer, while the published v0.1.4, v0.1.3, v0.1.2 and v0.1.1 artifacts are immutable — v0.1.5, v0.1.4, v0.1.3 and v0.1.2 declare 0.2.0-rc.2 and v0.1.1 still declares 0.1.7-rc.2. The releases are separately bounded rather than expressed as one range — each declares exactly one runtime, and the plugin does not claim to run on both. Multi-runtime packaging would require explicit two-runtime verification and is not part of this release. v0.1.5 is a visual continuity and lifecycle recovery release on the 0.2.0-rc.2 line: it moves no runtime target, and no earlier release is restamped.

0.2.0-rc.2 是当前工作树的规范运行时。 Phase 9.3 将开发目标迁移到该版本，并对照本机 0.2.0-rc.2 安装与上述公开 参考 commit，重新审计了本插件读取的全部 DSH 声明——会话事件信封、LLM 流与紧凑 AssistantStreamRecord 形状、 session-controller 的事件窗口与结算契约、conversation.input.dock 插槽契约、插件兼容门控，以及完成态卡片所依据的 TodoPanel 视觉契约。全部十四项声明在两个参考 commit 之间逐字节相同，因此插件消费的遥测、流、会话与插槽契约均未 变化：adapter 代码未移动，指标语义未移动，也不涉及任何兼容性豁免。对比记录见 docs/DSH_API_NOTES.md §14。

该声明有意限定范围：不写 0.2.0+、不写 0.2.x、也不写“最新 DSH”，因为其他版本均未被实际验证。本机证据来自 CLI （dsh --version）、已安装包（npm list -g @deepseek-ai/dsh）与组合后的 profile 树，均记录在 docs/IMPLEMENTATION_LOG.md。

v0.1.2 即该目标转为正式发布的那个版本，v0.1.3、v0.1.4 与 v0.1.5 原样延续该目标：工作树携带 version: 0.1.5 与同一个 0.2.0-rc.2 peer，而已发布的 v0.1.4、v0.1.3、v0.1.2 与 v0.1.1 产物不可变更——v0.1.5、v0.1.4、v0.1.3 与 v0.1.2 声明 0.2.0-rc.2，v0.1.1 仍声明 0.1.7-rc.2。各发布 版本是各自限定的，而不是写成一个范围——每个版本只声明一个运行时，插件不声称可同时运行于两者。多运行时打包需要 显式的双运行时验证，不属于本次发布范围。v0.1.5 是 0.2.0-rc.2 线上的视觉连续性与生命周期恢复发布：不移动运行时目标，也不改写任何 既有发布。

Phase 7D migrated the adapter, the client feed and the completion path to that version: tool results are identified through the first-class tool-role message (message.toolCallId, message.isError), the bare settleAssistant(attemptId) is resolved from held evidence instead of being read as an abandonment, a turn/end is terminal even when no record is open, and the session log format is v4. The field-by-field contract record is docs/DSH_API_NOTES.md §13.

Phase 7D 将 adapter、client feed 与完成态路径迁移到该版本：工具结果经一等公民的 tool-role message 识别 （message.toolCallId、message.isError）；裸 settleAssistant(attemptId) 依据已持有的证据判定，而不再一律读作 abandonment；turn/end 即使没有已打开的 record 也具终止性；会话日志格式为 v4。逐字段契约记录见 docs/DSH_API_NOTES.md §13。

The eight captures under fixtures/dsh-turns/ were recorded against 0.1.5. They remain evidence for the metric arithmetic, the decoder and historical compatibility, and they are not evidence for the tool/result shape, the settle-assistant semantics, the turn completion lifecycle or the client event-window behaviour, nor are they a supported runtime contract. package.json declares an exact compatibility gate, "peerDependencies": { "@deepseek-ai/dsh": "0.2.0-rc.2" }. DSH evaluates that peer against the running runtime version before a profile starts the plugin, so an unsupported DSH is rejected instead of silently admitted. The exact range is deliberate: ^0.2.0-rc.2, ~0.2.0-rc.2, >=0.2.0-rc.2, 0.2.x and * would all admit runtimes this project has never exercised, and the dual 0.1.7-rc.2 || 0.2.0-rc.2 range would erase the evidence boundary between v0.1.1 and v0.1.2. The recorded corpora keep the version they were captured on: fixtures/dsh-turns/ is 0.1.5, fixtures/dsh-0.1.7/ is 0.1.7-rc.2, and neither is restamped.

fixtures/dsh-turns/ 下的八段录制采集自 0.1.5。它们仍是指标算术、解码器与历史兼容性的证据，但不是 tool/result 形状、settle-assistant 语义、turn 完成生命周期或客户端事件窗口行为的证据，也不构成受支持的运行时契约。package.json 声明精确兼容门控 "peerDependencies": { "@deepseek-ai/dsh": "0.2.0-rc.2" }。DSH 会在 profile 启动插件前用当前运行时 版本校验该 peer，因此不受支持的 DSH 会被拒绝，而不会被静默接受。使用精确范围是有意的：^0.2.0-rc.2、~0.2.0-rc.2、 >=0.2.0-rc.2、0.2.x 与 * 都会放行本项目从未实际验证过的运行时，而 0.1.7-rc.2 || 0.2.0-rc.2 这样的双范围会抹掉 v0.1.1 与 v0.1.2 之间的证据边界。已录制语料保留其采集时的版本：fixtures/dsh-turns/ 为 0.1.5， fixtures/dsh-0.1.7/ 为 0.1.7-rc.2，两者均未改写版本标记。

3. Install / 安装

Three installation paths. The npm package is the primary distribution; the GitHub Release tarball is an offline, immutable fallback; the checkout is only for developing the plugin itself.

安装方式有三种。npm 包是主要分发方式；GitHub Release tarball 是离线、不可变的回退方式；检出目录仅用于开发插件本身。

3.1 Prerequisite / 前置条件

The plugin declares an exact runtime peer and DSH refuses to start a plugin whose DSH peer does not match the running runtime, so the prerequisite follows §2.1: install the runtime that matches the plugin version you are installing.

| Installing | Required DSH | |---|---| | @0.1.5 (npm / GitHub Release, §3.2, §3.3) | @deepseek-ai/[email protected] | | @0.1.4 (npm / GitHub Release, historical) | @deepseek-ai/[email protected] | | @0.1.3 (npm / GitHub Release, historical) | @deepseek-ai/[email protected] | | @0.1.2 (npm / GitHub Release, historical) | @deepseek-ai/[email protected] | | @0.1.1 (npm / GitHub Release, historical) | @deepseek-ai/[email protected] | | the development checkout (§3.4) | @deepseek-ai/[email protected] |

# released v0.1.5, and the development checkout
npm install -g @deepseek-ai/[email protected]

# historical v0.1.1 only
npm install -g @deepseek-ai/[email protected]

Do not install an arbitrary latest DSH and assume the plugin runs on it: the plugin declares exact runtime compatibility only, and no DSH release other than the two named above has been exercised by this project.

插件声明精确的运行时 peer，而 DSH 会拒绝启动 DSH peer 与当前运行时不匹配的插件，因此前置条件遵循 §2.1：安装与所要 安装的插件版本相匹配的运行时。

| 安装对象 | 所需 DSH | |---|---| | @0.1.5（npm / GitHub Release，§3.2、§3.3） | @deepseek-ai/[email protected] | | @0.1.4（npm / GitHub Release，历史版本） | @deepseek-ai/[email protected] | | @0.1.3（npm / GitHub Release，历史版本） | @deepseek-ai/[email protected] | | @0.1.2（npm / GitHub Release，历史版本） | @deepseek-ai/[email protected] | | @0.1.1（npm / GitHub Release，历史版本） | @deepseek-ai/[email protected] | | 开发检出目录（§3.4） | @deepseek-ai/[email protected] |

不要安装任意“最新”DSH 并假定插件可在其上运行：本插件只声明精确的运行时兼容性，且除上述两个版本之外本项目未验证任何 DSH 版本。

3.2 npm, the default installation / npm 默认安装

dsh plugin --profile web add dsh-turn-performance-meter

Pin the version for a reproducible install:

固定版本以获得可复现的安装：

dsh plugin --profile web add [email protected]

The unversioned command resolves npm's latest dist-tag; the pinned form resolves 0.1.5 exactly. Both install a frozen copy of the published artifact.

无版本号命令解析 npm 的 latest dist-tag；固定版本形式精确解析 0.1.5。两者安装的都是已发布产物的冻结副本。

3.3 GitHub Release tarball (offline fallback) / GitHub Release tarball（离线回退）

Download dsh-turn-performance-meter-0.1.5.tgz from the v0.1.5 release, then install it:

从 v0.1.5 release 下载 dsh-turn-performance-meter-0.1.5.tgz 后安装：

dsh plugin --profile web add "file:C:/path/to/dsh-turn-performance-meter-0.1.5.tgz"

This is the offline and immutable fallback, and the asset is the same tarball the npm registry serves. file: on a tarball is a frozen artifact, which is the point: the installed bytes cannot drift from the published release, and the release carries a .sha256 sidecar for verifying the download before installation.

这是离线且不可变的回退方式，该资产与 npm registry 所提供的 tarball 为同一份。对 tarball 使用 file: 得到的是一份冻结 产物，这正是目的所在：安装的字节不会相对已发布 release 漂移，且该 release 附带 .sha256 sidecar，可在安装前校验下载 内容。

Verify the download before installing:

安装前校验下载内容：

Get-FileHash .\dsh-turn-performance-meter-0.1.5.tgz -Algorithm SHA256
Get-Content .\dsh-turn-performance-meter-0.1.5.tgz.sha256

3.4 Development checkout / 开发检出

dsh plugin --profile web add "link:C:/path/to/dsh-turn-performance-meter"

link: tracks the working checkout and is intended for development only. The reason is measured rather than stylistic. pnpm installs a link: spec as a symlink to the checkout, so a later npm run build:client is picked up by the profile without reinstalling, whereas the npm and file: specs of §3.2 and §3.3 install a frozen copy. link: is therefore not a distribution form: it follows whatever the checkout contains, including uncommitted work, so it cannot represent an immutable published installation.

link: 跟踪工作检出目录，仅用于开发。其理由来自实测而非风格偏好。pnpm 把 link: 安装为指向检出目录的符号链接， 因此之后执行 npm run build:client 时 profile 会直接读到新字节，无需重装；而 §3.2 与 §3.3 的 npm 与 file: 形式安装的 是一份冻结副本。因此 link: 不是分发形式：它跟随检出目录的当前内容（包含未提交的改动），无法代表一份不可变的已发布 安装。

Every command above initializes the profile on first use and adds the package to dsh.profile.bundles automatically, because this package declares dsh.bundle.patch.

以上每种命令都会在首次使用时初始化 profile，并因为本包声明了 dsh.bundle.patch 而自动把包名加入 dsh.profile.bundles。

The reference checkout used for this project's recorded evidence is E:\Projects\DSHarness\dsh-turn-performance-meter; substitute any absolute path. Reload the page after installing, or restart the profile when the loader entry has to be re-read.

本项目的录制证据来自参考检出目录 E:\Projects\DSHarness\dsh-turn-performance-meter；实际使用时替换为任意绝对路径。 安装后刷新页面；若需要重新读取 loader 条目，则重启该 profile。

The Plugins UI in the web client can add an absolute local directory as well. Do not modify DSH core source files for this project: installation requires no patch to DSH, to any node_modules file, or to the shipped package.

Web 客户端中的插件 UI 同样可以添加绝对本地目录。本项目不需要修改 DSH 核心源码：安装过程不修改 DSH、不修改任何 node_modules 文件，也不修改已安装的包。

4. Usage / 使用

Nothing is configured per session. The meter attaches to whichever session the client is displaying and detaches on teardown.

无需按会话配置。实时组件挂载到客户端当前显示的会话，并在销毁时解除。

Diagnostics are off by default. Setting the browser local-storage key below to 1 and reloading enables lifecycle logs (console.debug) and a read-only handle — session attach, turn open/close, attempt and tool boundaries, quality downgrades, rebaselines. It is a diagnostic aid only, it is not required for normal use, and per-delta logging never happens in either mode.

诊断默认关闭。将下列浏览器 local-storage 项设为 1 并刷新，可启用生命周期日志（console.debug）与只读句柄 —— 包括会话挂载、turn 开关、attempt 与工具边界、质量降级、rebaseline。它仅是诊断辅助，正常使用不需要，且两种模式下都 不会记录逐 delta 日志。

localStorage.setItem('dsh-turn-performance-meter.debug', '1')
// window.__dshTurnPerformanceMeter.{controller,diagnostics,attachedSessions,meter}

The same switch is the only way to reach the cadence override dsh-turn-performance-meter.refreshMs, which exists so that the presentation cadence could be A/B measured in a browser. While the diagnostic switch is off the production cadence has exactly one source (src/client/live/cadence.js) and no persisted value can change it.

同一开关也是触达刷新节奏覆盖项 dsh-turn-performance-meter.refreshMs 的唯一途径；该项的存在是为了在浏览器中实测 刷新节奏的 A/B。诊断开关关闭时，生产刷新节奏只有一个来源（src/client/live/cadence.js），任何持久化值都无法改变它。

5. Metric semantics / 指标口径

These definitions are frozen. Per-step TPS values must never be arithmetically averaged; rates are always a ratio of sums over the turn.

以下口径已冻结。禁止对各 step 的 TPS 做算术平均；速率始终是 turn 级"和之比"。

| Field | Definition | Secondary line | |---|---|---| | Reasoning TPS / 思考 TPS | sum(reasoning tokens) / sum(reasoning generation time) across the turn | reasoning duration · reasoning tokens | | Output TPS / 输出 TPS | sum(non-reasoning output tokens) / sum(output generation time) across the turn | output duration · output tokens | | Generated Tokens / 生成 Tokens | sum of provider outputTokens for contributing attempts | total turn elapsed time | | TTFT / 首响应 | turn start → first non-empty reasoning/text/tool-call delta | turn status |

A footer line, not a fifth column, carries the tool summary (tools 4 · 12.8s, using the wall union) and the attempt count. A turn with no tool call hides the tool item entirely.

卡片底部（而不是第五个栏位）承载工具摘要（工具 4 · 12.8s，使用 wall union）与模型调用次数；无工具调用的 turn 直接 隐藏该项。

The live meter displays the phase-cumulative TPS of the active attempt's current phase episode: the episode's generated token mass over the wall time since that episode's first sample, published once the episode holds at least three samples, always with ≈, and never a curve. A reasoning → output transition resets the episode clock, the numerator and the sample count, so the first output rate never contains reasoning-phase elapsed time; a new model invocation after a tool call or a retry resets all of it, so unrelated calls are never mixed. No model attempt streaming means no value — never a stale rate. A stall decays hyperbolically by elapsed wall time: the numerator stops moving while the denominator advances.

实时组件显示当前活动 attempt 当前相位片段的累计 TPS：该片段自首个样本以来生成的 token 量除以片段墙钟时间，且在片段 累计满 3 个样本后才发布，始终带 ≈，且不显示曲线。reasoning → output 切换会重置片段时钟、分子与样本计数，因此首个 output 速率绝不包含 reasoning 片段的已用时间；工具返回后的新模型调用或重试会重置全部状态，禁止混合两个独立模型调用的 数据。没有 model attempt 在流式输出时即无该值，绝不显示过期速率。停滞按已流逝的墙钟时间呈双曲线衰减：分子停止增长而 分母继续推进。

Model-generated ordinary text and model-generated tool-call arguments count as model output. PowerShell commands, shell scripts, write-file payloads and edit patches therefore belong to output accounting. Tool results such as stdout, file contents returned by a tool, or API responses do not count as model output; they may become input to a later model call. reasoningTokens is already included in outputTokens, so the non-reasoning share is outputTokens - reasoningTokens and the two are never added together.

模型生成的普通文本与 tool-call arguments 均属于模型输出，因此 PowerShell 命令、shell 脚本、写文件正文与编辑 patch 都计入输出统计。工具自身返回的 stdout、文件读取结果、API 结果等不计入模型输出；它们如果随后送入模型，则属于下一次 模型调用的输入。reasoningTokens 已包含在 outputTokens 中，非思考部分为 outputTokens - reasoningTokens，两者绝不相加。

Tool latency is tracked on two axes: toolWorkMs is the sum of all completed call durations, toolWallMs is the union of tool intervals and therefore does not double-count parallel tools. The compact UI displays toolWallMs; the summed work stays in the view model for detail/debug surfaces.

工具耗时按两个轴统计：toolWorkMs 是所有已完成工具调用时长之和；toolWallMs 是工具执行区间的并集，因此不会对并行 工具重复计时。紧凑 UI 显示 toolWallMs；求和值保留在 view model 中供详细/调试界面使用。

5.1 Measurement fidelity / 测量精度

DSH stream deltas carry text/tool-argument fragments and timestamps, while authoritative provider token usage is normally reported as aggregate usage rather than an exact token count attached to every delta. The implementation therefore exposes metric quality instead of pretending every live/curve point is exact. Quality is tracked on three independent axes, because one label cannot describe a whole curve: tokenTotalQuality (how well the total is known; can reach exact), phaseSplitQuality (how well that total divides into reasoning vs non-reasoning; can reach exact, and only when the provider reports reasoningTokens), and temporalShapeQuality (how well the timing is known; its ceiling is reconstructed).

DSH 流式 delta 提供文本/工具参数片段及时间戳，而权威 provider token usage 通常是聚合值，并非每个 delta 都携带精确 token 数。因此实现显式记录指标质量，不把所有实时值和曲线点伪装成精确数据。质量在三个独立轴上记录，因为单一标签无法描述 整条曲线：token 总数质量（最高可达 exact）、reasoning/output 拆分质量（仅在 provider 报告 reasoningTokens 时可达 exact）、时间形状质量（上限为 reconstructed）。

Levels per axis: exact · calibrated · reconstructed · partial · estimated · unavailable. Only exact suppresses the ≈ marker; unavailable renders — and is never coerced to zero.

每一轴的等级为 exact · calibrated · reconstructed · partial · estimated · unavailable。仅 exact 免除 ≈ 标记；unavailable 显示 —，绝不静默归零。

5.2 Curve / 曲线

The curve is one attempt-local phase-cumulative throughput trace per model attempt: a vertex at attempt-local t reports the cumulative average of the phase episode in force at t — that episode's sample mass up to t over the wall time since its first sample — whatever its phase, which is the same estimator family the live pill publishes. The compressed x-axis joins attempts so tools and inter-attempt waits consume zero width, but each episode owns its own clock and numerator, so the trace steps down at a phase boundary and climbs again on the new phase's own evidence; a model silence inside a call retains full width as a hyperbolic decay, not as a reset to zero. Reasoning and output are colours of that one trace. The trace is sampled on a 100 ms grid, and the published series is capped at 200 points by evenly spaced nearest-sample reduction with no interpolation. The chart-wide render budget is 512 points allocated across phase-coloured runs with the global peak preserved, while peakTps is read from the published series before any render allowance is applied. The curve's magnitudes are the provider-calibrated per-delta allocation whenever authoritative usage exists, so the drawn curve and the printed token total are one magnitude system, and attemptBreakdown[].calibration.samples stays the authoritative magnitude source once a turn has settled.

曲线是每个 model attempt 各一条 attempt 局部的相位累计吞吐轨迹：局部时刻 t 的取值是 t 处生效的那个相位片段的累计 平均——该片段截至 t 的样本量除以自其首个样本以来的墙钟时间——不区分相位，与实时指示器属于同一估计器族。压缩横轴把各 attempt 首尾相接，因此工具时间与 attempt 间等待占用零宽度；但每个片段拥有自己的时钟与分子，轨迹在相位边界处下台阶， 再依据新相位自身的证据重新爬升；attempt 内部的模型静默按完整宽度绘出，表现为双曲线衰减，而不是归零。reasoning 与 output 是同一条轨迹的两种颜色。轨迹以 100 ms 网格采样，发布序列按时间等距取最近样本压缩到 200 点上限，不做插值。 图级渲染预算为 512 点，按相位色段分配并保留全局峰值；peakTps 则在应用任何渲染配额之前从发布序列读取。当存在权威 usage 时，曲线量级采用 provider 校准后的逐 delta 分配，因此曲线与卡片打印的 token 总数属于同一量级体系；turn settle 之后，attemptBreakdown[].calibration.samples 始终是量级的权威来源。

The complete contract is docs/METRICS_SPEC.md §11, with the durable/transient evidence rules in §13 and the architecture in docs/ARCHITECTURE.md.

完整口径见 docs/METRICS_SPEC.md §11，durable/transient 两类证据的规则见 §13，架构见 docs/ARCHITECTURE.md。

6. Known limitations / 已知限制

Live TPS is approximate. DSH deltas do not carry an exact per-token count, so live TPS is a heuristic delta weighting and is always marked ≈. It is not an exact measurement and must not be read as one.

实时 TPS 是近似的。 DSH 的 delta 不携带逐 token 精确计数，因此实时 TPS 属于启发式 delta 加权，且始终标 ≈。 它不是精确测量，不应被当作精确测量读取。

Completed token totals depend on provider usage. When the provider reports outputTokens and reasoningTokens, the corresponding totals and the phase split can reach exact. When it does not, the phase split is estimated or reconstructed and the card marks it ≈.

完成态 token 总量取决于 provider usage。 当 provider 报告 outputTokens 与 reasoningTokens 时，相应总量与 phase 拆分可达 exact；未报告时，phase 拆分被估计或重建，卡片以 ≈ 标记。

The temporal curve is never exact per-token timing. DSH supplies delta timestamps but no authoritative token count per delta, so the temporal-shape quality ceiling is reconstructed and no curve vertex can be exact.

时间曲线永远不是精确的逐 token 计时。 DSH 提供 delta 时间戳，但不提供每个 delta 的权威 token 数，因此时间形状质量 的上限是 reconstructed，任何曲线顶点都不可能 exact。

A missing turn/start leaves TTFT and elapsed unavailable. In terminal-tail reconstruction the record is rebuilt from the durable evidence the published window still holds. When that window never contained the turn's start boundary, startMs stays null and therefore TTFT and turn elapsed report —; only firstTokenMs may still be known from a durable sample. The plugin does not always recover TTFT, and does not invent a start boundary.

缺少 turn/start 时 TTFT 与耗时为不可用。 终末 tail 重建会从发布窗口仍持有的 durable 证据复原 record。若该窗口 从未包含该 turn 的起始边界，则 startMs 保持 null，TTFT 与 turn elapsed 显示 —；仅 firstTokenMs 可能仍能由 durable 样本得知。插件并非总能恢复 TTFT，也不会编造 start 边界。

Retained durable evidence is bounded. The window-generation reconstruction budget is MAX_RETAINED_TURNS = 32, evicted least-recently-updated, and it holds evidence bytes only — durable identity is generation-wide and survives eviction. This is a memory bound on reconstruction, not a statement that only 32 turns are supported.

保留的 durable 证据是有界的。 窗口代际重建预算为 MAX_RETAINED_TURNS = 32，按最久未更新淘汰，且只保存证据 字节 —— durable 身份是全代际的，淘汰不会遗忘。这是重建过程的内存上界，不代表"只支持 32 个 turn"。

Fixture evidence is bounded. The 0.1.7 real recorded corpus currently contains two files, fixtures/dsh-0.1.7/index.json and fixtures/dsh-0.1.7/t01-sequential-tools.json. The settle-assistant retirement/abandonment contract is covered by a synthetic contract test against the ported fold algebra, not by a host-recorded 0.1.7 fixture.

Fixture 证据是有界的。 0.1.7 的真实录制语料目前只有两个文件：fixtures/dsh-0.1.7/index.json 与 fixtures/dsh-0.1.7/t01-sequential-tools.json。settle-assistant 的 retirement/abandonment 契约由针对移植后 fold 代数的合成契约测试覆盖，而非由 host 录制的 0.1.7 fixture 覆盖。

Browser evidence is bounded. The Phase 7D.1 terminal-tail case — turn/start already slid out of the window when turn/end arrives — was not constructed directly in a browser. It is established by real recorded durable bytes, a real feed/controller replay, and the DSH bounded-window contract. It is not a browser reproduction.

浏览器证据是有界的。 Phase 7D.1 的终末 tail 场景（turn/end 到达时 turn/start 已滑出窗口）并未在浏览器中直接 构造。它由真实录制的 durable 字节、真实的 feed/controller 回放，以及 DSH 有界窗口契约共同确立，不属于浏览器复现。

Verification is local. This repository has no GitHub CI runner, so every npm run verify result quoted anywhere in this repository is a local test result, not CI. The implementation log keeps the full evidence.

验证是本地进行的。 本仓库没有 GitHub CI runner，因此本仓库中引用的所有 npm run verify 结果都是本地测试结果， 而非 CI 结果。完整证据保留在 implementation log 中。

7. Repository map / 项目结构

dsh-turn-performance-meter/
├─ README.md
├─ CHANGELOG.md                      Release history (0.1.5)
├─ LICENSE                           MIT
├─ package.json                      version 0.1.5, published to npm, scripts: test / build:client / verify
├─ cordis.patch.yml                  Bundle row insertion; the only DSH composition this plugin adds
├─ index.js                          host entry (no-op by design; telemetry is client-side)
├─ client.js                         GENERATED browser bundle (npm run build:client)
├─ lib/client.js                     same bytes; the layout the local injector validates
├─ docs/
│  ├─ ARCHITECTURE.md
│  ├─ METRICS_SPEC.md
│  ├─ MIMO_RUNTIME_METRICS.md
│  ├─ UI_SPEC.md
│  ├─ DSH_API_NOTES.md
│  ├─ TASKS.md
│  ├─ TEST_PLAN.md
│  ├─ DIRECTORY_TREE.md
│  ├─ START_PROMPT.md
│  ├─ IMPLEMENTATION_LOG.md
│  └─ assets/                        four reference-layout screenshots
├─ fixtures/            recorded DSH turn evidence (offline; no DSH required)
│  ├─ README.md
│  ├─ index.json
│  ├─ dsh-0.1.7/        the rc.2 corpus: index.json + t01-sequential-tools.json
│  ├─ dsh-turns/        eight real recorded turns (0.1.5), durable + transient planes verbatim
│  └─ derived/          four declared synthetic mutations of those recordings
├─ src/
│  ├─ core/             pure metric engine — zero @deepseek-ai/* imports (15 modules)
│  ├─ dsh/              DSH rc.2 raw evidence -> normalized events (+ client-feed)
│  ├─ host/             TurnTelemetryStore (session+turn keyed)
│  └─ client/           main.js entry + presentation
│     ├─ live/          state machine, presenter, scheduler, controller, MeterRoot,
│     │                 React pill, locale, CSS
│     └─ completed/     completed-card view tree + React binding + card CSS
├─ test/                65 test files + helpers/ (core / dsh / live / completed / bundle)
└─ scripts/             verify-structure, bundle-client, build-client,
                        sanitize-fixtures, verify-sanitization

dev/                    dev-only tooling, not part of the bundle
├─ fixture-recorder/    injected host recorder: session/event + agent/assistant-stream
├─ capture-scenario.ps1 live scenario driver (launch / interrupt)
├─ harvest-fixtures.mjs raw recording -> fixtures/dsh-turns/*
├─ mutate-fixtures.mjs  deterministic synthetic derivatives with provenance
├─ measure-generation-tail.mjs
├─ inspect-recording.mjs
└─ recordings/          launch receipts + captured model catalog

dev/screenshots/ and fixtures/raw/ are git-ignored local evidence directories: the first holds browser captures, the second the pre-sanitization fixture originals. Neither is part of the repository or the installed bundle.

dev/screenshots/ 与 fixtures/raw/ 是 git 忽略的本地证据目录：前者存放浏览器截图，后者存放脱敏前的 fixture 原件。 两者都不属于仓库内容，也不属于安装后的 bundle。

The pure metric engine and the DSH adapter both have tests that run without a DSH process; the recorded fixtures make the adapter layer verifiable offline.

纯指标引擎与 DSH adapter 层都有无需 DSH 进程即可运行的测试；已录制的 fixture 使 adapter 层可以离线验证。

8. Development and verification / 开发与验证

The project uses Node's built-in test runner; no test dependency, bundler or network access is required. After editing src/client/**, rebuild before verifying — scripts/verify-structure.mjs fails on a bundle that is stale relative to src/, so npm run verify on unbuilt client sources is expected to fail:

本项目使用 Node 内置测试运行器；不需要测试依赖、打包器或网络访问。修改 src/client/** 之后应先构建再验证—— scripts/verify-structure.mjs 会在 bundle 相对 src/ 过期时失败，因此对未构建的 client 源码直接运行 npm run verify 预期会失败：

npm run build:client     # rewrites client.js and mirrors the same bytes to lib/client.js
npm run verify           # structure check + full test suite
node scripts/verify-sanitization.mjs

npm run verify runs node scripts/verify-structure.mjs && node --test test/*.test.js. The structure check asserts that the required files exist, that every src/core module has a matching test, that every local import under src/ resolves, that client.js is fresh relative to src/, and that lib/client.js is byte-identical to client.js. npm test runs the test suite alone.

npm run verify 执行 node scripts/verify-structure.mjs && node --test test/*.test.js。结构检查断言：必需文件存在、 每个 src/core 模块都有对应测试、src/ 下每个本地 import 均可解析、client.js 相对 src/ 是新的、且 lib/client.js 与 client.js 逐字节相同。仅运行测试套件使用 npm test。

Do not add a frontend React dependency solely for the DSH client module; DSH supplies React through its browser module table. Because a DSH client bundle is a single classic script whose factory require resolves only module-table words, scripts/bundle-client.mjs deterministically bundles the src/client/main.js graph into client.js (verified by test/client-bundle.test.js; no bundler dependency is installed).

不要仅为 DSH Client 模块而安装额外 React 副本；DSH 会通过浏览器模块表提供 React。由于 DSH 客户端 bundle 是单个 classic script（factory 的 require 只解析模块表词汇），scripts/bundle-client.mjs 将 src/client/main.js 依赖图 确定性地打包进 client.js（由 test/client-bundle.test.js 验证，不引入任何打包器依赖）。

To capture new DSH evidence (only needed when recording new fixtures, in a DSH host with dsh-super-injector):

如需重新采集证据（仅在抓取新 fixture 时需要，且须在装有 dsh-super-injector 的 DSH host 内）：

dsh --version
# inject dev/fixture-recorder, then:
powershell -File dev/capture-scenario.ps1 -Name A1
node dev/harvest-fixtures.mjs
node dev/mutate-fixtures.mjs --write
node dev/measure-generation-tail.mjs

See fixtures/README.md for the fixture shape and dev/fixture-recorder/README.md for the recorder. The recorder is dev-only and never part of the plugin bundle.

fixture 结构见 fixtures/README.md，录制器见 dev/fixture-recorder/README.md。录制器仅供开发使用，不属于插件 bundle。

The executable task list and acceptance gates are in docs/TASKS.md; the implementation log with per-phase evidence is in docs/IMPLEMENTATION_LOG.md; the prompt that starts DeepSeek V4.1 Flash is in docs/START_PROMPT.md.

可执行任务列表与验收门槛见 docs/TASKS.md；逐阶段证据见 docs/IMPLEMENTATION_LOG.md；启动 DeepSeek V4.1 Flash 的 提示词见 docs/START_PROMPT.md。

9. License / 许可证

This project is licensed under the MIT License. See LICENSE.

本项目采用 MIT 许可证，详见 LICENSE。