DeepSeek Harness (DSH) 在规模化应用中常面临耗时分布不清、Token成本难控及失败链路难追溯的痛点。本文详解如何通过腾讯云 Agent 可观测插件，将 DSH 事件还原为五层调用链，实现跨会话聚合与长期留存。通过配置环境变量或修改插件文件，即可在控制台查看端到端耗时、模型推理与工具执行占比，并快速定位失败根因。

查看完整的 DeepSeek Harness 调用链与耗时分布

准备说明：环境要求与前置条件

在开始接入之前，请确保您的开发环境满足以下要求，以保证插件正常运行：

• DeepSeek Harness (DSH)：版本需在 >=0.1.0-rc.6 且 <0.2.0 区间内。
• Node.js 环境：插件运行环境要求 Node.js 版本为 18.0.0 或更高（官方推荐 >=22.19.0）。
• 腾讯云日志服务 (CLS)：已开通日志服务，并准备好具备日志写入权限的访问凭证（建议使用 CAM 子账号或临时密钥）。

操作正文：接入腾讯云 Agent 可观测

第1步：创建 Agent 可观测应用并获取配置信息

首先需要在腾讯云控制台创建应用，以获取后续插件上报数据所需的日志主题 ID。

1. 登录 日志服务控制台。
2. 在左侧导航栏选择 Agent 可观测，单击 应用接入 创建应用。
3. 在接入方式中选择 DeepSeek Harness。

   

4. 进入应用详情，在日志主题列表中找到名称为 {应用名称}-trace-topic 的日志主题。
5. 复制该 日志主题 ID（即 topicId），用于后续配置。

第2步：安装 DeepSeek Harness 插件

通过 DSH 的插件管理命令，将腾讯云 Agent 可观测插件安装到对应的 Profile 中。安装或更新插件后，必须重启 DSH 服务才能生效。

根据您使用的 DSH 形态（web / headless / harness），执行对应的安装命令：

dsh plugin --profile web add tencentcloud-agentobs-sdk-dsh
dsh plugin --profile headless add tencentcloud-agentobs-sdk-dsh
dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh

注意 pnpm 构建脚本问题：如果您使用 pnpm v9+，默认会禁止依赖包运行 install 脚本。若安装时遇到 [ERR_PNPM_IGNORED_BUILDS] 错误，请在对应 profile 目录执行一次以下命令（后续安装/更新不再需要）：

cd ~/.dsh/profiles/web
echo "enable-scripts=true" >> .npmrc
pnpm install

（headless / harness profile 同理，将路径改为 ~/.dsh/profiles/headless 或 ~/.dsh/profiles/harness）。

第3步：配置连接信息（环境变量或配置文件）

插件需要知道将数据上报到哪个 CLS 日志主题。推荐使用环境变量方式，避免将敏感信息硬编码在配置文件中。

方式一：通过环境变量（推荐）

在启动 DSH 前，导出以下环境变量：

export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=your-topic-id
export CLS_SECRET_ID=your-secret-id
export CLS_SECRET_KEY=your-secret-key
export CLS_SERVICE_NAME=dsh-agent    # 可选，用于区分实例或业务

dsh --profile web

方式二：手动调整插件配置文件

编辑 $DSH_HOME/profiles//cordis.patch.yml（未设置 DSH_HOME 时默认为 ~/.dsh/profiles//cordis.patch.yml）：

- id: cls-observability
  config:
    endpoint: ap-guangzhou.cls.tencentcs.com
    topicId: your-topic-id
    secretId: your-secret-id
    secretKey: your-secret-key
    serviceName: dsh-agent
    captureContent: true
    batchMaxSize: 32
    flushIntervalMs: 5000
    debug: false

安全提醒：显式插件配置优先于环境变量。访问凭证属于敏感信息，建议通过环境变量或密钥管理工具注入，不要将真实 SecretId 与 SecretKey 提交到代码仓库。

第4步：启动服务并验证数据上报

完成配置后，启动 DSH 服务并发起一次测试任务，确保至少触发一次模型调用。

dsh --profile web

启动后，您可以在腾讯云 Agent 可观测控制台中查看到对应的 Trace 数据。如果未看到数据，请检查 debug: true 开启后的调试日志，或确认网络是否能访问 CLS 端点。

完成结果：查看耗时、成本与失败定位

接入成功后，DSH 的每一次任务都会形成一条完整链路，并在控制台按会话、模型、工具等维度汇总。您可以查看以下关键信息：

• 完整调用链：entry / agent / step / chat / tool 五层逐层展开，父子关系与各层耗时占比清晰可见。
• 耗时分布：端到端与单轮耗时、模型推理与工具执行各自的占用，以及首 Token 延迟与 P95 分位数。
• Token 与成本：输入、输出分别统计，可下钻到单次模型调用，也可按会话、模型聚合排行。
• 失败定位：每层 Span 带独立状态并支持错误类型自定义，可用于区分模型侧失败、工具侧失败与循环中断。

问题与调整：常见问题排查

Q1：插件安装后，控制台没有数据上报怎么办？

表现：启动 DSH 后，控制台应用列表无新增数据或 Token 数为 0。

原因与解决：

• 检查 topicId 是否正确，以及 secretId/secretKey 是否具有日志写入权限。
• 确认 captureContent 是否被误设为 false（默认应为 true）。
• 检查网络防火墙是否允许访问 ap-guangzhou.cls.tencentcs.com 端点。
• 将配置中的 debug 设为 true，查看控制台输出的调试日志是否有报错。

Q2：如何关闭敏感内容（Prompt/Response）的捕获？

默认情况下，prompts、responses、tool arguments/results 会附加到 Span 中。如需关闭以节省存储或保护隐私：

设置环境变量：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
dsh --profile web

或在插件配置文件中设置 captureContent: false。

Q3：如何卸载或禁用插件？

卸载插件：

dsh plugin --profile web remove tencentcloud-agentobs-sdk-dsh

禁用采集（不卸载）：

在配置文件或环境变量中设置 enabled: false，即可禁用采集但不卸载插件。

总结

DeepSeek Harness 原生的轨迹视图与事件流落盘，解决的是本机、单会话、实时的调试问题；而通过接入腾讯云 Agent 可观测插件，将同一批运行时事件还原为结构化的五层调用链，补充了跨会话聚合、跨机汇聚、长期留存与告警能力。这帮助用户快速搭建针对 DeepSeek Harness 的运维观测体系，精准定位耗时、成本与失败根因。

项目 GitHub：
https://github.com/TencentCloud/tencentcloud-agentobs-sdk-dsh

相关接入指南：
https://cloud.tencent.com/document/product/614/133517
https://cloud.tencent.com/document/product/614/135910
https://cloud.tencent.com/document/product/614/133518

以上就是 DeepSeek Harness 规模化踩坑实录：耗时、成本、失败到底该怎么查的详细内容，更多关于 DeepSeek Harness 可观测的资料请关注本站其它相关文章！