izz-BLUE/dsh-devtools

dsh-devtools

面向 DeepSeek Harness agent 的元数据优先运行时性能分析器。

GitHub： · Issues：

一个社区（community）插件：把会话的持久化事件日志折叠成 Agent Runtime Profiler，
在 Web GUI 的会话视图里以 DevTools 标签页展示每次模型调用（Step）与回合（Turn）的
执行事实——模型归属、延迟、工具调用、重试与回合结局。只读、不拦截、不修改任何请求。

本插件不是 DeepSeek 官方发布的插件；它基于官方 NPM SDK
（@deepseek-ai/*）开发，通过 DSH 的 cordis patch + profile 机制挂载。

1. 功能说明

公开版 0.1 提供的能力（全部来自对持久化会话事件的只读折叠）：

- Runtime Profiler：一眼看出 agent 做了什么、哪里最慢、哪里异常
- Agent Turn / Step runtime trace：按回合与步骤还原 agent 执行时间线
- Step runtime timeline：同一回合内的 model / tool 时长条按同一时间轴缩放；
并行工具调用分 lane 表达并行，极短工具保留最小可见宽度（tooltip 显示真实值），
运行中的活动带 running 状态，失败工具带 error 标记
- Turn collapse / expand：进行中的 Turn 与最新 Turn 默认展开，较早 Turn 默认折叠；
折叠摘要展示 Turn 号、状态、步骤数、工具数与耗时；2 秒轮询刷新不会重置手动折叠状态
- Summary 三组：
- Execution：Turns / Steps（含 completed · running 计数）/ Tool Calls / Retries /
Errors（step / turn / tool 三类错误独立统计）/ Interrupted / Aborted
- Performance：Model Wall / Tool Wall / Avg First Activity / Wall Time / Decode / Throughput
- Tokens：Input / Output / Cache Read / Reasoning / Cache Reuse
- model / provider attribution：每个 Step 标注调用当时的模型与提供商
- TTFT / first-activity：由 step/start 到首个持久化 block-start 的时间戳派生
（UI 简称 Avg First Activity，tooltip 说明与 TTFT 的关系，不冒充 Provider 官方上报值）
- Model Wall / Tool Wall：assistantAt - startAt 的模型侧 Wall 时间；
tool/call -> tool/result 的工具 Wall 时间（tooltip 说明含调用与结果之间的全部等待）
- tool errors：结构化失败码（如 FS_NOT_FOUND、ABORTED）标记在单个工具上
- retry trace：llm/retry 事件出现时，按 Step 归属展示 retry/maxRetries/delay/code
- provider-reported usage：input / output / cacheRead / reasoning tokens；
cache reuse = cacheRead / (input + cacheRead)（内部派生指标，非 Provider 官方缓存命中率）
- 回合结局：completed / aborted / interrupted / error / max-tokens / blocked
等 turn/end.reason 的正确映射；Turn 级结局与 Step 状态、工具错误分开统计
- trace completeness：顶部状态指示显示 Trace complete（低调绿色圆点）；
发生 ring 淘汰时升级为橙色 Partial trace · N earlier steps omitted，
不把截断后的页面伪装成完整历史
- live session 与 cold/history session：内存日志增量折叠；持久化会话从落盘日志重建
- subagent metadata：subagent 会话的 label / mode / agentModel
- hook trace：hook/invoked|hook/result 事件存在时展示执行耗时与错误标记；
无 producer 时显示语义准确的空状态（不暗示“没有执行任何 Hook”）

以下能力不属于公开版 0.1，本版本不实现：mutation provenance、request diff、
prompt diff、context composition / context inspector、tool dispatch breakdown、
plugin token attribution。

2. 架构

Durable Session Event Log
|
v
Pure Fold
|
v
Runtime Trace Snapshot
|
v
/dsh-devtools RPC
|
v
conversation.view / DevTools

- read-only：插件只消费已提交的会话事件，不注入、不拦截、不修改任何请求
- zero behavior modification：不改变 agent 的输入、输出或执行路径
- no request interception / no request mutation
- durable-events-first：live 会话直接折叠内存日志（增量、无克隆）；
cold 会话经 sessionQuery 从持久化日志重建并缓存（日志不再增长）
3. 隐私 / 安全

以 metadata 优先为设计原则：默认不读取、不保存、不通过 RPC 返回——

- prompt / system prompt 正文
- user message content
- assistant message content
- tool arguments
- tool result text
- API key / secret

RPC wire 只携带运行时 metadata：类型、时间戳、ID、名称、状态、usage 计数等必要字段。

有自动隐私测试（tests/fold.spec.ts 的 privacy 用例），并经过真实会话 E2E 的
RPC + DOM privacy audit（对 wire JSON 与渲染页面全量扫描 prompt / tool args /
tool result / API key 模式，无泄漏）。

4. UI

DevTools 通过 conversation.view slot 注册，位于标签页环的最右侧：

Chat | Trajectory | Context | DevTools

DevTools 拥有独立宽布局（不受聊天阅读宽度限制，自适应桌面/窄窗，小窗口自动单列），
并在高细节背景皮肤上使用主题 token 的半透明遮罩 + blur 保证可读性。

DevTools overview

- Sticky runtime status bar：Turns / Steps / 当前 Turn·Step / Model Wall /
Tool Wall / Avg First Activity / Throughput / Cache Reuse；窄屏自动隐藏次要指标
- Summary 三组：Execution / Performance / Tokens（见 What it does）
- 逐 Turn 卡片：结局徽章 + 步骤数 + 工具数 + 耗时，可折叠/展开
- Turn-level sticky timeline ruler：展开长 Turn 滚动时时间刻度保持可见，
与每 Step 的全局时间网格严格对齐（自适应 nice interval + tick 标签）
- 逐 Step 行：状态、模型、TTFT / model / decode / wall、usage、
runtime timeline 时长条、工具 chips、retry chips
- hook 执行表：有事件时展示，无事件时显示语义空状态

5. 安装

npm 发布后（推荐）

一条命令安装（无需 clone 仓库、无需构建、无需手改 profile）：

dsh plugin --profile web add dsh-devtools

其他 profile：

dsh plugin --profile  add dsh-devtools

启动：

dsh web

本地开发 / 本地安装

从本仓库以 file: 依赖安装（仅限开发调试）：

1. 在仓库内构建
pnpm install
pnpm build

2. 加入 web profile（file: 依赖）
cd ~/.dsh/profiles/web
pnpm add "dsh-devtools@file:"
并在 package.json 的 dsh.profile.bundles 追加 "dsh-devtools"

3. 重启 dsh web

6. 开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack

7. 已知限制

- hook/invoked | hook/result：当前验证环境没有 producer，真实 hook 数据路径
未做 E2E；fold 对缺失与未配对事件做了防御性处理并有自动测试
- real-world LLM retry E2E 尚未覆盖（需要 API 层故障才能真实触发）；
自动测试已覆盖 retry 归属与字段展示语义
- droppedSteps ring truncation（默认保留最近 1000 个 Step）未做真实超长会话
E2E；自动测试覆盖裁剪与上报语义，UI 以 partial-trace 横幅如实展示
- TTFT 定义为 step/start -> 首个持久化 block-start chunk 的时间差
（非 Provider 官方上报的 TTFT）
- Tool Wall 本质为 tool/call -> tool/result 的 wall time，包含调用与结果之间
的全部等待；不拆分 queue / dispatch / execution（属未来版本）
- cache reuse 为内部派生指标 cacheRead / (input + cacheRead)，
不是 Provider 官方缓存命中率
- 公开版 0.1 不做 request mutation provenance / tool dispatch breakdown（属未来版本）

8. 兼容性

已验证兼容 DeepSeek Harness v0.1.0-rc.6（npm 版，web profile 挂载实测；
真实会话 E2E 通过）。其他版本未验证。

License

BSD-3-Clause（见 LICENSE）。