dsh-devtools

Metadata-first runtime profiler for DeepSeek Harness agents.

GitHub: https://github.com/izz-BLUE/dsh-devtools · Issues: https://github.com/izz-BLUE/dsh-devtools/issues

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

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

1. What it does

公开版 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. Architecture

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. Privacy / Security

metadata-first by design：默认不读取、不保存、不通过 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 保证可读性。

• 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. Installation

After npm publication (recommended)

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

dsh plugin --profile web add dsh-devtools

其他 profile：

dsh plugin --profile <name> add dsh-devtools

启动：

dsh web

Local development / local installation

从本仓库以 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. Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack

7. Known limitations

• 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. Compatibility

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

License

BSD-3-Clause（见 LICENSE）。