CLS observability for DeepSeek Harness

tencentcloud-cls-sdk-dsh 是一个 DeepSeek Harness (DSH) 可观测插件，直接将 GenAI trace 数据上报到腾讯云日志服务 (CLS)。

它观察 DSH 原生的 session、agent loop、LLM stream 和 tool 生命周期，将其转换为 CLS 规范的 5 层 span 层级模型（entry → agent → step → chat → tool），并通过 tencentcloud-cls-sdk-js 直接上报到 CLS，无需额外部署 OTLP 收集器或 sidecar。

数据模型

DSH session/event + llm/stream
                │
                ▼
      CLS Trace Coordinator
                │
                ▼
    CLS 5-layer span model
    (entry/agent/step/chat/tool)
                │
                ▼
    tencentcloud-cls-sdk-js
                │  Protobuf upload
                ▼
    Tencent Cloud CLS

一次 DSH turn 产生的 trace 结构：

ENTRY
└── AGENT (invoke_agent)
    └── STEP (react round_N)
        ├── CHAT (chat model_name)
        └── TOOL (execute_tool tool_name)

安装

前置依赖

全局安装 DeepSeek Harness CLI：

npm install -g @deepseek-ai/dsh

安装插件

dsh plugin --profile web add tencentcloud-cls-sdk-dsh
dsh plugin --profile headless add tencentcloud-cls-sdk-dsh

本地开发：

dsh plugin --profile web add /absolute/path/to/tencentcloud-cls-sdk-dsh

注意：安装或更新插件后，需要重启 DSH 服务才能生效。

pnpm 构建脚本问题

pnpm v9+ 默认禁止依赖包运行 install 脚本。如果安装时遇到以下错误：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: [email protected]
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

请在对应 profile 目录执行：

# 方式 1：交互式选择
cd ~/.dsh/profiles/web
pnpm approve-builds
pnpm install

# 方式 2：仅允许 protobufjs（非交互）
cd ~/.dsh/profiles/web
npx json -I -f package.json -e 'this.pnpm = this.pnpm || {}; this.pnpm.onlyBuiltDependencies = ["protobufjs"]'
pnpm install

# 方式 3：允许所有包运行脚本（推荐，非交互）
cd ~/.dsh/profiles/web
echo "enable-scripts=true" >> .npmrc
pnpm install

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

卸载插件

dsh plugin --profile web remove tencentcloud-cls-sdk-dsh
dsh plugin --profile headless remove tencentcloud-cls-sdk-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/<profile>/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: false
    batchMaxSize: 32
    flushIntervalMs: 5000
    debug: false

显式插件配置优先于环境变量。

启用内容捕获

默认情况下，prompts、responses、tool arguments/results 不会附加到 span。启用内容捕获：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
dsh --profile web

或在插件配置中设置 captureContent: true。

配置项

设置	默认值	说明
enabled	true	禁用采集但不卸载插件
endpoint	CLS_ENDPOINT	CLS API 接入点
topicId	CLS_TOPIC_ID	CLS 日志主题 ID
secretId	CLS_SECRET_ID	腾讯云 SecretId
secretKey	CLS_SECRET_KEY	腾讯云 SecretKey
serviceName	deepseek-harness	服务名
captureContent	环境变量或 false	捕获 prompts/responses/tool 内容
contentMaxChars	128000	单个内容属性最大字符数
batchMaxSize	32	每批上报最大 span 数
flushIntervalMs	5000	定时刷新间隔（毫秒）
retryTimes	3	上报重试次数
debug	false	启用调试日志

隐私说明

内容捕获默认关闭。启用后，源代码、凭证、个人数据等敏感内容可能被发送到 CLS。请在启用前检查 CLS 的数据保留和访问控制策略。

兼容性

组件	支持范围
DeepSeek Harness	>=0.1.0-rc.6 <0.2.0
Node.js	>=18.0.0

开发

pnpm install
pnpm run check
pnpm test
pnpm run build

License

Apache-2.0