dsh-axonhub-tracing
English | 中文
本插件用于为 DeepSeek Harness(简称 DSH)发出的模型请求附加 AxonHub 可识别的身份标识请求头。
安装并启用后,AxonHub 的追踪页面可以按对话线程与问答轮次清晰归类每一次模型调用,不再将所有请求混作零散记录。对话标题生成与自动审批请求不会混入正常对话时间线,上下文压缩摘要会标记独立类型,子代理任务也会归入各自独立的追踪位置。
它解决什么问题
在默认情况下,DSH 发送模型请求时不携带任何会话标识。AxonHub 网关收到请求后,只能将其视为彼此孤立的单次调用,无法判断哪些请求属于同一段对话,也无法区分正常对话回复、生成对话标题、自动审批或上下文压缩等不同用途的请求。
本插件通过 DSH 的 llm-pi-ai/request-headers 接口,在请求发出前向 HTTP 请求头注入三个字段,供 AxonHub 识别并归类请求:
AH-Thread-Id:对话线程编号。同一段对话内的相关请求共用同一个线程值。AH-Trace-Id:单轮对话或单项任务的追踪编号。在同一轮对话中,无论模型调用了多少次工具或触发了多少次重试,该值都保持不变。AH-Kind:请求类型标识,用于向网关标明当前请求属于正常对话、子代理、标题生成、自动审批还是压缩摘要。
AxonHub 收到请求后,会根据 AH-Thread-Id 建立对话线程,根据 AH-Trace-Id 建立单次追踪记录。AH-Kind 会随请求一起写入请求头记录,便于事后按类型区分调用。
装法
可以在 DSH 的插件管理界面中直接添加本插件包,也可以在命令行中执行 dsh plugin --profile desktop add <路径>(将 <路径> 替换为插件目录的实际位置):
dsh plugin --profile desktop add /path/to/dsh-axonhub-tracing
安装完成后重启一次 DSH,插件列表中即会显示「AxonHub 追踪」。
设置
打开 DSH 设置中的插件页面,找到「AxonHub 追踪」即可配置各项参数。
页面顶部为插件总开关。关闭总开关后,从下一次请求开始将不再附加上述三个请求头,无需卸载插件即可立即停用追踪功能。
总开关下方是渠道选择的默认范围设置。默认范围用于控制未单独设置手动开关的渠道,共有三种模式:
- 自动:仅对名称或接口地址中包含
axon的渠道附加请求头。 - 全部:对所有受支持的渠道附加请求头。
- 全关:默认不对任何渠道附加请求头。
默认范围下方是渠道列表,逐个渠道的手动开关优先于默认范围。勾选某个渠道后,该渠道将始终附加请求头;取消勾选后,该渠道将始终不附加请求头。每个渠道旁边会注明当前状态是来自默认范围的自动命中,还是来自用户的手动开关。如果某个渠道被手动修改过,右侧会显示「恢复默认」按钮,点击即可清除手动设置并恢复按默认范围计算。通过这种设计,后续新增渠道时无需重新调整插件配置,新渠道会自动按默认范围归类,仅在需要单独特殊处理时再手动调整。
页面底部展示最近二十条已附加请求头的调用记录,可直接查看请求时间、类型、渠道和追踪号。插件刚安装完成时该列表为空,发送一条对话消息后即会生成记录。
所有设置保存在以下本地文件中,支持直接手动编辑:
~/.dsh/axonhub-tracing/settings.json
该设置文件由单个 DSH 进程持有。如果同时开启两个 DSH 进程并分别修改设置,文件内容以最后一次写入为准,另一个进程需要重启后才会读取到新值。当设置文件损坏时,插件不会自行恢复默认值并继续附加请求头,而是会自动停用,待用户修复该文件或将其删除重建后再恢复工作。
分组规则
线程代表一段对话,追踪代表一轮交互或一项具体任务。默认情况下,所有请求都以当前会话本身作为线程,只有特定类型的请求会按配置拆分到独立线程。具体分组规则如下:
- 普通对话与轮次追踪:普通对话默认开启「轮次追踪」,每轮对话生成一条独立追踪,每轮追踪号格式为
<会话>:t<轮次>。在同一轮对话中,无论调用多少次工具或重试多少次,追踪号均保持不变。关闭设置中的「轮次追踪」后,整段会话共用同一个追踪号,便于查看整段会话的总开销,但不再区分每一轮。该开关仅控制追踪号的轮次后缀,不改变线程编号,因此开启或关闭都不会影响会话粘性。 - 压缩摘要:上下文压缩摘要始终与当前轮次共用同一条追踪。压缩请求与正常对话使用同一段上下文,归入同一条追踪便于保持上下文记录连续,同时仍可通过类型标识将其与普通调用区分开。
- 标题与审批:生成标题和自动审批各有一个独立开关,默认均为独立模式。处于独立模式时,它们的线程分别为
<会话>#title和<会话>#review,追踪分别为<会话>:title和<会话>:review,不会占用主会话的时间线。由于标题和审批的上下文与主对话不同,原本就不共享缓存前缀,拆分独立线程不会造成缓存损失。如果希望将它们并回主会话,将对应的开关切换为跟主会话即可,两个开关互不影响。 - 子代理:子代理默认使用独立线程,追踪号格式为
<父会话>:c<名字>.<短码>:t<轮次>,在后台展开即可识别出父会话、子代理名称与轮次。其中的<短码>由子会话编号计算得出,因此同一个父会话同时启动两个同名子代理也不会发生编号冲突。子代理的父子关系由 DSH 自动记录在子会话上,插件直接读取该信息,无需用户额外配置。子代理设为独立线程后,可能会根据上游配置被分配到其他渠道;如果更看重与父会话共享前缀缓存,可以在设置中将子代理改为跟父会话。
和缓存的关系
本插件只负责在请求头中发送身份标识,不会直接提高缓存命中率。真正决定渠道固定分配的是 AxonHub 的渠道粘性设置 trace_sticky_mode。
当网关开启 trace_sticky_mode 后,网关会先查看同一追踪上一次使用了哪个渠道,未命中时再查看同一线程上一次使用了哪个渠道,两级映射记录均缓存三十分钟。分配到同一个渠道意味着使用同一个上游账号,只有在同一个上游账号下,前缀缓存才有可能命中。
根据插件与网关粘性的开启组合,共有三种情况:
- 仅安装插件,网关未开启粘性:可以在 AxonHub 中进行追踪和记账,但网关的选路方式与安装前一致。
- 仅开启网关粘性,未安装插件:对 DSH 不起作用,因为 DSH 默认不发送追踪号与线程号,网关没有可用于保持粘性的标识。
- 同时启用插件与网关粘性:网关选路会跟随请求携带的身份标识保持稳定。
这套机制的关键在于第二级回退。因为同一段主对话共用同一个线程,即使开启轮次追踪使每一轮更换了追踪号,新一轮请求仍然会通过同一线程找到上一次使用的渠道,轮次后缀不影响会话粘性,默认的轮次追踪不会把同一段对话拆分到不同渠道。真正可能切换渠道的是被拆分出去的独立线程,例如独立模式下的标题、审批和子代理。标题和审批与主对话的缓存前缀原本就不同,切换渠道影响不大;如果子代理与父会话共享缓存前缀,将其改为跟父会话会更加稳定。
哪些渠道能打标签
插件走 llm-pi-ai/request-headers 接口,只覆盖走 pi-ai 适配器的渠道。例如本机的 AxonHub 主渠道,以及手动配置指向本机网关的 anthropic、google、openai、kimi 等渠道,都属于这一类。
DSH 原生 DeepSeek 接口和订阅账号接口不支持。这两类接口只发送自身的鉴权请求头,底层链路上没有接入 llm-pi-ai/request-headers 扩展接口,因此插件无法向其添加请求头。
如果某些渠道原本就不属于支持范围,无需特意在插件中关闭,它们本身就不会被附加请求头;对于需要追踪的受支持渠道,在设置中按默认范围匹配或手动勾选即可。
怎么验证
安装完成后,可以按以下步骤核验功能是否正常生效:
- 发送一条普通的对话消息,等待回复结束。
- 打开 AxonHub 的追踪页面,确认能看到当前轮次对应的记录,点击进入后能看到该轮对话包含的所有模型调用。
- 查看 AxonHub 的线程页面,确认同一段对话的多个轮次都挂在同一个线程下面。
- 新开一段对话并触发自动生成标题,查看线程列表,确认多出一条名称带
#title的独立线程,内部请求类型为标题,且没有混入正常对话。 - 启动一个子代理执行任务,随后查看线程列表,确认多出一条属于子代理的线程,且能从追踪号中看出父会话和子代理名称。
- 关闭插件总开关后再发送一条消息,使用抓包工具或查看网关日志检查请求头,确认请求中不再包含任何以
AH开头的请求头。
此外,插件设置页面最下方的最近请求列表也可用于快速自查,列表中会显示每一条已附加请求头的调用所使用的请求类型和追踪号。
开发与测试
本仓库没有运行时依赖,克隆后可直接运行测试:
npm test
测试覆盖身份编号推导、渠道选择、设置迁移、请求头原子写入、最近请求列表和多进程设置合并。
卸载
可以在 DSH 的插件管理界面中移除本插件,也可以在命令行中执行以下 remove 命令:
dsh plugin --profile desktop remove dsh-axonhub-tracing
插件不写数据库,也不修改渠道配置。卸载后,模型请求头会立即恢复原状,本地仅保留设置文件 ~/.dsh/axonhub-tracing/settings.json,可根据需要手动删除,保留不删也不会产生影响。
已知边界
- 渠道支持范围:插件走
llm-pi-ai/request-headers,只覆盖走pi-ai的渠道,DSH 原生 DeepSeek 接口和订阅账号接口不支持,插件无法介入这些请求。 - 外部后端子代理:如果子代理使用的是 Claude Code 或 Codex 等外部后端,这类请求不经过 DSH 的模型层,因此也不会带有本插件的请求头,这属于预期行为。
- 隐私与标识处理:追踪号中包含会话编号和子代理名称,这些均属于本机结构标识,不会携带对话内容。如果不希望网关看到原始标识,可以将设置文件中的
hashIds改为true,开启后所有编号都会替换为十六进制短串,但用户自己在后台也无法直接从编号读出原始含义。需要说明的是,模型库在某些协议下可能自行发送会话标识,那部分标识并非由本插件写入,hashIds无法控制那一部分内容。
排查
- 设置页显示「还没有读到渠道列表」:说明宿主尚未完成渠道注册,先发送一条消息后再返回设置页查看。
- 设置页显示错误:通常是宿主插件未加载成功,重启一次 DSH,再检查插件列表中是否存在本插件。
- AxonHub 中能看到请求但未分组:先确认请求头中是否包含
AH-Trace-Id;如果请求头已包含该字段但仍不分组,请检查网关的追踪配置是否将trace_header修改成了其他名称。 - 追踪号与轮次对不上:先检查设置中的「轮次追踪」是否已关闭;关闭后整段对话共用一个追踪号,在后台看起来就是未按轮次拆分的状态。
No comments yet. Be the first to write one.