前言¶
在使用 DeepSeek Harness (DSH) 构建工作流时，除了关注对话本身的内容（transcript），开发者通常还需要监控工具调用的实际表现，例如耗时是否异常、参数与结果消耗了多少 Token。传统的日志方式往往将大量数据注入上下文，不仅难以检索，也缺乏聚合统计能力。本插件提供了一种“零模型可见面”的透视镜，仅记录关键指标，不干扰上下文。
插件介绍¶
dsh-plugin-tool-trace 是一个 DeepSeek Harness (dsh) 插件。它的核心职责是追踪每次工具调用的耗时、参数量与结果量（仅记录大小，不记录内容）。数据按月生成 JSONL 文件落盘，并提供 /tools-stats 命令生成慢工具排行榜。
- 维护者：121212165
- 许可证：MIT
核心功能¶
- 慢工具排行榜：访问
/tools-stats，系统会按累计耗时排序，展示每个工具的调用次数、累计耗时、平均耗时、最慢耗时、平均结果量以及错误计数。 - 零模型可见面：所有追踪数据仅写入本地文件，不进入对话上下文。这既保护了隐私，也使得数据纯粹用于人眼分析。
- 容错处理：如果进程崩溃导致写入中断，半行数据会被自动跳过并计数。对于中途死掉的调用（只有开始没有结束），在聚合统计时会自然被忽略。
安装与启用¶
安装过程需要通过 DSH 的插件命令将包添加到指定 Profile，并修改配置文件。
1、执行安装命令（需确保 pnpm 在 PATH 上）：
dsh plugin --profile web add github:121212165/dsh-plugin-tool-trace
此命令会通过 pnpm 自动运行 prepare 脚本构建插件。
2、配置补丁文件。
找到本插件仓库根目录的 cordis.patch.yml，将其内容合并到 $DSH_HOME/profiles/web/cordis.patch.yml 中。
注意：该文件默认为空数组 []。请将补丁内容并进数组，不要直接追加。追加会导致 YAML 解析错误（报错 failed to parse overlay ... end of the stream or a document separator is expected）。
3、重启 dsh。
配置层与客户端都需要重启才能生效（客户端基于启动时的内容 rev 下发，硬刷新浏览器无效）。
配置¶
插件支持以下配置项：
| 字段 | 默认值 | 说明 |
|---|---|---|
dataDir |
~/.dsh/tool-trace |
JSONL 日志落盘目录 |
captureArgsSize |
true |
是否记录参数 JSON 的长度 |
典型用法¶
1、查看统计：在 DSH 界面或终端使用 /tools-stats 命令，查看慢工具排行榜。
2、查看日志：进入 dataDir（默认 ~/.dsh/tool-trace），查看按月分割的 JSONL 文件，了解具体的调用指标。
注意事项¶
1、结果量精度：结果体大小的提取依赖下游结果的数据形状。如果 content 为字符串，大小计算是精确的；如果是其他形状（如数组、对象），则通过序列化估算大小。
2、Live Mount 未验证：插件未在正在运行中的 dsh 实例上进行 live mount 验证。
3、生效条件：必须重启 dsh 进程，插件才能生效。
结尾¶
本插件通过文件落盘和聚合统计，帮助开发者从“说了什么”转向“做了什么、慢在哪”。更多细节与源码，请访问 GitHub 或 社区目录。
