tencentcloud-cls-sdk-codebuddy

CLS 可观测插件 for CodeBuddy — 6 层 Span 层级模型，直接上报腾讯云 CLS。

简介

tencentcloud-cls-sdk-codebuddy 是一个 CodeBuddy AI 编码助手的可观测性插件，通过自动注入 hooks 的方式，无侵入地采集 CodeBuddy 的对话、工具调用、LLM 请求等全链路数据，并按照 6 层 Span 模型上报至腾讯云 CLS（日志服务），实现 AI Agent 的全链路可观测。

核心特性

• 🔌 无侵入接入：自动发现 CodeBuddy 并注入 hooks，不影响 CodeBuddy 正常使用
• 📊 6 层 Span 模型：entry → session → agent → step → chat/tool，完整还原 ReAct 调用链路
• 🚀 多客户端支持：同时支持 CLI 和 IDE（VSCode）两种 CodeBuddy 启动方式
• 📦 双输出模式：支持上报 CLS 和本地 JSONL 文件两种输出方式
• ⚡ 批量上报：支持批量聚合，默认每 5 秒或满 32 条自动上报
• 🔒 凭据加密：SecretId / SecretKey 加密存储，不以明文写入配置文件
• 🗂️ 日志自管理：后台服务日志单文件限制 10 MB，原地滚动，无需外部 logrotate

前置条件

| 条件 | 说明 | |------|------| | Node.js 18+ | 推荐 22（node --version 检查） | | CodeBuddy 已安装 | ~/.codebuddy 目录存在 | | 腾讯云 CLS 已开通 | 已创建日志主题，获取 Endpoint / Topic ID / SecretId / SecretKey |

平台支持：采集与上报功能支持 Linux / macOS / Windows；开机自启 目前仅支持 Linux（systemd / crontab 兜底）与 macOS（launchd），Windows 需手动将 start 加入启动项。

快速开始（推荐）

一行命令完成安装

腾讯云 CVM / 容器环境（推荐，内网加速）：

npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencentyun.com/npm/ && \
  cls-codebuddy setup \
    --endpoint     ap-guangzhou.cls.tencentcs.com \
    --topic-id     <your-topic-id> \
    --secret-id    <your-secret-id> \
    --secret-key   <your-secret-key>
    # 可选参数（无需可删除对应行）：
    # --service-name codebuddy-agent   # 服务名，默认 codebuddy-agent
    # --user-name    <your-user-name>  # 用户名
    # --user-id      <your-user-id>    # 用户 ID

腾讯云外网环境：

npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencent.com/npm/ && \
  cls-codebuddy setup \
    --endpoint     ap-guangzhou.cls.tencentcs.com \
    --topic-id     <your-topic-id> \
    --secret-id    <your-secret-id> \
    --secret-key   <your-secret-key>
    # 可选参数（无需可删除对应行）：
    # --service-name codebuddy-agent   # 服务名，默认 codebuddy-agent
    # --user-name    <your-user-name>  # 用户名
    # --user-id      <your-user-id>    # 用户 ID

默认（官方源）：

npm install -g tencentcloud-cls-sdk-codebuddy && \
  cls-codebuddy setup \
    --endpoint     ap-guangzhou.cls.tencentcs.com \
    --topic-id     <your-topic-id> \
    --secret-id    <your-secret-id> \
    --secret-key   <your-secret-key>
    # 可选参数（无需可删除对应行）：
    # --service-name codebuddy-agent   # 服务名，默认 codebuddy-agent
    # --user-name    <your-user-name>  # 用户名
    # --user-id      <your-user-id>    # 用户 ID

setup 命令会依次完成四步：

1. 配置凭据 — 加密写入 ~/.cls-codebuddy/config.json（权限 0600）
2. 注入 hooks — 修改 ~/.codebuddy/settings.json，无侵入接入 CodeBuddy
3. 后台启动 — 以守护进程方式启动采集服务，写入 PID 文件
4. 注册开机自启 — 按平台自动选择 systemd（Linux）/ launchd（macOS）+ crontab 兜底，设备重启后服务自动拉起

开机自启默认开启。如不需要，可在安装后执行 cls-codebuddy disable 关闭。 Linux 下 enable 仅注册、不立即拉起（重启/登录后由 systemd 拉起）；macOS 下服务进程由 launchd 托管，注册即随登录加载。

启动成功后可验证：

cls-codebuddy status          # 查看运行状态
cls-codebuddy info            # 查看自启方式与 CLS 配置
tail -f ~/.cls-codebuddy/cls-codebuddy.log   # 实时查看日志

安装

根据网络环境选择合适的镜像源：

# 腾讯云 CVM / 容器环境（推荐，内网加速）
npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencentyun.com/npm/

# 腾讯云外网环境
npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencent.com/npm/

# 默认（官方源）
npm install -g tencentcloud-cls-sdk-codebuddy

提示：如需永久使用腾讯云镜像，可提前配置：

npm config set registry https://mirrors.tencentyun.com/npm/

配置后直接执行 npm install -g tencentcloud-cls-sdk-codebuddy 即可，无需每次附加 --registry 参数。

配置

方式 A：setup / configure 命令（推荐）

非交互式（适合脚本/CI）：

cls-codebuddy configure \
  --endpoint    ap-guangzhou.cls.tencentcs.com \
  --topic-id    <your-topic-id> \
  --secret-id   <your-secret-id> \
  --secret-key  <your-secret-key> \
  --service-name codebuddy-agent   # 可选，默认 codebuddy-agent
  --user-name   <your-user-name>   # 可选
  --user-id     <your-user-id>     # 可选

交互式（无参数时自动进入）：

cls-codebuddy configure
# 按提示依次输入 Endpoint、Topic ID、SecretId、SecretKey、Service Name

configure 命令写入 ~/.cls-codebuddy/config.json（权限 0600），SecretId / SecretKey 加密存储。 若后台服务正在运行，配置完成后会自动重启以使新配置立即生效。

方式 B：环境变量（适合快速验证 / 容器部署）

export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export CLS_SECRET_ID=your-secret-id
export CLS_SECRET_KEY=your-secret-key
export CLS_SERVICE_NAME=codebuddy-agent   # 可选

| 环境变量 | 说明 | 示例 | |----------|------|------| | CLS_ENDPOINT | CLS 地域域名 | ap-guangzhou.cls.tencentcs.com | | CLS_TOPIC_ID | CLS 日志主题 ID | 650de9e1-5c8b-4784-... | | CLS_SECRET_ID | 腾讯云 API 密钥 ID | AKID... | | CLS_SECRET_KEY | 腾讯云 API 密钥 Key | | | CLS_SERVICE_NAME | 服务名（用于 CLS 检索） | codebuddy-agent | | CLS_USER_NAME | 用户名（可选） | alice | | CLS_USER_ID | 用户 ID（可选） | u-12345 | | CLS_CUSTOM_TAGS | 自定义 tag，JSON 字符串格式 | '{"env":"prod","team":"infra"}' | | CLS_CODINGAGENT_ENABLED | 设为 false 或 0 可禁用插件 | false |

配置优先级：环境变量 > ~/.cls-codebuddy/config.json > 默认值

方式 C：手动编辑配置文件

创建 ~/.cls-codebuddy/config.json（注意：通过命令配置时 AKSK 为加密值，手动填写时可使用明文，程序会自动兼容）：

{
  "cls": {
    "endpoint": "ap-guangzhou.cls.tencentcs.com",
    "topicId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "secretId": "your-secret-id",
    "secretKey": "your-secret-key",
    "serviceName": "codebuddy-agent",
    "userName": "alice",
    "userId": "u-12345",
    "batchMaxSize": 32,
    "flushIntervalMs": 5000,
    "retryTimes": 3
  },
  "jsonl": {
    "enabled": true,
    "outputDir": "~/.cls-codebuddy/logs/output"
  },
  "customTags": {
    "env": "prod",
    "team": "infra"
  }
}

运维命令

| 命令 | 说明 | |------|------| | cls-codebuddy setup [flags] | 一键安装：配置凭据 + 注入 hooks + 后台启动 + 注册开机自启（推荐首次使用） | | cls-codebuddy configure [flags] | 配置 CLS 凭据（无参数时交互式引导） | | cls-codebuddy start | 后台启动采集服务（守护进程） | | cls-codebuddy stop | 停止服务 | | cls-codebuddy restart | 重启服务（未运行则直接启动） | | cls-codebuddy status | 查看运行状态 | | cls-codebuddy info | 查看 CodeBuddy 发现情况 + CLS 配置 | | cls-codebuddy install | 注入 hooks 到 CodeBuddy 配置文件 | | cls-codebuddy uninstall | 从 CodeBuddy 配置文件移除 hooks | | cls-codebuddy uninstall-all | 一键卸载：停止服务 + 移除 hooks + 清理数据目录 + 取消开机自启 | | cls-codebuddy enable | 注册开机自启（systemd / launchd / crontab，按平台自动选择） | | cls-codebuddy disable | 取消开机自启 |

setup / configure 参数说明

| 参数 | 说明 | 是否必填 | |------|------|----------| | --endpoint <host> | CLS 地域域名 | 首次必填，更新时可省略 | | --topic-id <id> | CLS 日志主题 ID | 首次必填，更新时可省略 | | --secret-id <id> | 腾讯云 SecretId | 首次必填，更新时可省略 | | --secret-key <key> | 腾讯云 SecretKey | 首次必填，更新时可省略 | | --service-name <name> | 服务名，默认 codebuddy-agent | 可选 | | --user-name <name> | 用户名 | 可选 | | --user-id <id> | 用户 ID | 可选 | | --custom-tag <k=v> | 自定义 tag，可多次指定，注入到所有 span 的 attribute（agent.custom.<k>） | 可选 |

启动与验证

1. 服务生命周期

setup / uninstall-all 之外的日常运维使用以下命令，start 以守护进程方式在后台运行（Linux），PID 写入 ~/.cls-codebuddy/cls-codebuddy.pid，日志写入 ~/.cls-codebuddy/cls-codebuddy.log（上限 10 MB，自动原地滚动）：

cls-codebuddy start     # 后台启动（若已运行则跳过）
cls-codebuddy stop      # 停止
cls-codebuddy restart   # 重启（未运行则直接启动）
cls-codebuddy status    # 查看运行状态

setup 已在最后一步自动启动服务（Linux 通过 start 守护进程，macOS 通过 launchd 托管），无需再手动 start。 若进程意外退出，Linux 下 systemd 会按 Restart=on-failure 自动拉起；macOS 下 launchd 按 KeepAlive 自动拉起。

2. 触发数据采集

启动 CodeBuddy，进行任意一次 AI 对话（GUI / CLI / 插件均可），插件会自动采集。

3. 验证本地数据

# 查看本地 JSONL 输出
ls ~/.cls-codebuddy/logs/output/
cat ~/.cls-codebuddy/logs/output/spans-*.jsonl | head -1 | python3 -m json.tool

# 实时查看服务日志
tail -f ~/.cls-codebuddy/cls-codebuddy.log

# 查看服务状态
cls-codebuddy status

4. 在 CLS 控制台检索

登录 CLS 控制台，在日志主题中检索：

service:codebuddy-agent

建议在日志主题中开启 attribute 字段的 JSON 解析，这样 gen_ai.* 子字段可以单独检索和聚合。

采集的数据

6 层 Span 模型

| Span 类型 | 说明 | 触发时机 | 父子关系 | |-----------|------|----------|----------| | entry | 应用入口 | 每种客户端启动一次（CLI/IDE 各一个） | 根节点，无父 | | session | 会话 | 新建对话窗口 | 父 = entry | | agent | Agent 调用 | 每次用户提问 | 父 = session | | step | ReAct 轮次 | 每轮 LLM 调用（思考-行动-观察） | 父 = agent | | chat | LLM 调用 | 每次调用大模型 | 父 = step | | tool | 工具调用 | 每次执行工具 | 父 = step |

Trace 树结构

entry (CLI 启动) ─── gen_ai.entry.type="cli"
 └─ session ─── 新建会话
     ├─ agent ─── 第 1 次提问
     │   ├─ step round_1 ─── ReAct 轮 1
     │   │   ├─ chat ─── LLM 调用
     │   │   └─ tool ─── 工具调用
     │   └─ step round_2 ─── ReAct 轮 2
     │       └─ chat ─── LLM 最终回复
     └─ agent ─── 第 2 次提问
         └─ step round_1 ─── ...

entry (IDE 启动) ─── gen_ai.entry.type="ide"
 └─ session ─── GUI 新建会话
     └─ agent ─── ...

按客户端类型区分 Entry

| client 字段 | entry.type | entry.platform | |-------------|-----------|----------------| | CLI | cli | terminal | | CodeBuddyIDE | ide | vscode |

自定义 Tag

自定义 Tag 允许你向所有 span 的 attribute 层级注入业务维度字段，用于在 CLS 中按项目、环境、团队等维度过滤和聚合数据。

字段格式

所有自定义 Tag 统一使用 agent.custom. 前缀，与系统字段（gen_ai.*、telemetry.* 等）命名空间隔离：

setCustomTag('env', 'prod')  →  attribute['agent.custom.env'] = 'prod'

自定义 Tag 会注入到 全部 6 层 span（entry / session / agent / step / chat / tool），无需额外配置。

配置方式

方式 A：配置文件（静态，推荐）

在 ~/.cls-codebuddy/config.json 中添加 customTags 字段：

{
  "cls": { "..." : "..." },
  "customTags": {
    "env": "prod",
    "team": "infra",
    "project_id": "proj-123"
  }
}

方式 B：CLI 参数

configure 命令支持 --custom-tag key=value，可多次指定：

cls-codebuddy configure \
  --custom-tag env=prod \
  --custom-tag team=infra \
  --custom-tag project_id=proj-123

多次调用会合并到现有配置，不会清除已有的其他 tag。

方式 C：环境变量

export CLS_CUSTOM_TAGS='{"env":"prod","team":"infra"}'

方式 D：运行时动态更新（程序内调用）

通过 Orchestrator 实例的 API 随时更新，下一批 span 即生效，无需重启服务：

import { createOrchestrator } from 'tencentcloud-cls-sdk-codebuddy';

const orchestrator = await createOrchestrator(config);

// 设置单个 tag（同名 key 覆盖旧值）
orchestrator.setCustomTag('project_id', 'proj-456');

// 批量设置
orchestrator.setCustomTags({
  env: 'prod',
  team: 'infra',
  project_id: 'proj-456',
});

// 删除单个 tag
orchestrator.removeCustomTag('team');

// 清空所有自定义 tag
orchestrator.clearCustomTags();

// 查看当前所有 tag（返回带前缀的副本）
console.log(orchestrator.getCustomTags());
// 输出：{ 'agent.custom.env': 'prod', 'agent.custom.project_id': 'proj-456' }

API 说明

| 方法 | 说明 | |------|------| | setCustomTag(key, value) | 设置单个 tag，同名 key 覆盖旧值 | | setCustomTags(tags) | 批量设置，{ key: value } 格式 | | removeCustomTag(key) | 删除单个 tag | | clearCustomTags() | 清空所有自定义 tag | | getCustomTags() | 获取当前所有 tag（返回带 agent.custom. 前缀的副本） |

key 规范：只允许字母、数字、下划线、连字符（[a-zA-Z0-9_-]），非法 key 会打印 warn 并跳过，不会抛出异常。

生效时机

setCustomTag / setCustomTags / removeCustomTag / clearCustomTags
         ↓
    内存 Map 立即更新
         ↓
    下一次 buildSpans() 调用时
         ↓
    注入到每个 span.attribute（所有 6 层 span 均携带）

修改是实时的，只对之后产生的 span 生效，已上报的 span 不受影响。

在 CLS 中检索自定义 Tag

-- 按自定义 tag 过滤
attribute['agent.custom.env']:"prod" AND attribute['agent.custom.team']:"infra"

-- 按项目统计 token 消耗
spanKind:"chat" | SELECT attribute['agent.custom.project_id'] as project,
  SUM(CAST(attribute['gen_ai.usage.input_tokens'] as BIGINT)) as input_tokens,
  SUM(CAST(attribute['gen_ai.usage.output_tokens'] as BIGINT)) as output_tokens
  GROUP BY project

CLS 控制台检索示例

按服务过滤

service:"codebuddy-agent"

按 Span 类型统计

* | SELECT spanKind, COUNT(*) as cnt GROUP BY spanKind

查看工具调用耗时

spanKind:"tool" | SELECT name, durationMs, attribute['gen_ai.tool.name'] as tool ORDER BY durationMs DESC LIMIT 20

查看模型 Token 消耗

spanKind:"chat" | SELECT attribute['gen_ai.request.model'] as model,
  SUM(CAST(attribute['gen_ai.usage.input_tokens'] as BIGINT)) as input_tokens,
  SUM(CAST(attribute['gen_ai.usage.output_tokens'] as BIGINT)) as output_tokens
  GROUP BY model

查看错误工具调用

spanKind:"tool" AND statusCode:"ERROR"

以上检索语句需要 CLS 日志主题开启 attribute 字段的 JSON 解析。

开机自启

setup 流程会默认注册开机自启，设备重启（或用户重新登录）后服务自动拉起，无需手动启动。

平台支持

| 平台 | 实现方式 | 崩溃自重启 | 无需 root | 用户未登录自启 | |------|----------|-----------|-----------|----------------| | Linux（systemd，如 CentOS/TencentOS/Ubuntu） | systemd user service | ✅ Restart=on-failure | ✅ | ⚠️ 需 loginctl enable-linger（可选） | | macOS | launchd LaunchAgent | ✅ KeepAlive | ✅ | ✅ 登录后自启 | | Linux（无 systemd，兜底） | crontab @reboot | ❌ | ✅ | — |

自动选择逻辑：Linux 优先 systemd，不可用时回退 crontab；macOS 使用 launchd。全部为用户级机制，不写入系统目录、不要求 root。

命令

cls-codebuddy enable    # 注册开机自启（按平台自动选择实现；仅注册，不立即拉起）
cls-codebuddy disable   # 取消开机自启
cls-codebuddy info      # 查看当前自启方式（Autostart 段：Method / Enabled）

enable 只写入注册项并启用，不会立即启动服务（避免与已运行的守护进程冲突）。

• Linux（systemd）：systemctl --user enable，重启/登录后由 systemd 自动拉起；运行中进程退出按 Restart=on-failure 自愈。
• macOS（launchd）：注册即随用户登录加载（RunAtLoad），由 launchd 托管进程生命周期。
• 安装完成后用 cls-codebuddy info 确认 Autostart → Enabled: ✓ registered。

说明

• systemd（Linux）：服务文件写入 ~/.config/systemd/user/cls-codebuddy.service，使用 Type=forking + PIDFile，与现有 start / stop 守护机制完全兼容。 如需用户未登录时也保持运行，执行一次：

  loginctl enable-linger $USER

• launchd（macOS）：plist 写入 ~/Library/LaunchAgents/com.tencentcloud.cls-codebuddy.plist，由 launchctl 托管进程生命周期。
• crontab（兜底）：写入 @reboot ... cls-codebuddy start 条目（带 cls-codebuddy autostart 标记，便于识别与清理）。仅作兜底，不支持崩溃自重启。

更新插件

重新执行 npm install -g 即可完成更新，无需手动重启服务：

# 腾讯云 CVM / 容器环境（推荐，内网加速）
npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencentyun.com/npm/

# 腾讯云外网环境
npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencent.com/npm/

# 默认（官方源）
npm install -g tencentcloud-cls-sdk-codebuddy

更新完成后，postinstall 脚本会自动检测服务是否正在运行：

• 服务运行中：自动执行 restart，新版本代码立即生效，原有配置（凭据、hooks、开机自启注册）全部保留，无需重新配置
• 服务未运行：静默退出，不影响安装流程；下次手动 cls-codebuddy start 时即使用新版本

注意：更新不会影响已注册的开机自启（systemd / launchd / crontab），设备重启后仍会自动拉起新版本。

如果执行后版本未更新

可通过以下命令确认当前安装方式：

npm ls -g tencentcloud-cls-sdk-codebuddy

若输出中包含 -> 符号（如 -> /path/to/local/dir），说明当前安装的是本地软链接（通常由 npm install -g . 产生），npm 不会从镜像源更新它。

解决方法：先卸载本地链接版本，再从镜像源重新安装：

# 先卸载本地链接版本
npm uninstall -g tencentcloud-cls-sdk-codebuddy

# 再从镜像源安装
npm install -g tencentcloud-cls-sdk-codebuddy \
  --registry https://mirrors.tencentyun.com/npm/

卸载

cls-codebuddy uninstall-all

uninstall-all 会依次完成五步：

1. 停止服务 — 终止后台守护进程
2. 移除 hooks — 恢复 ~/.codebuddy/settings.json 原始配置
3. 清理数据目录 — 删除 ~/.cls-codebuddy（含配置、日志、PID 文件）
4. 取消开机自启 — 清理对应平台（systemd / launchd / crontab）的注册项
5. 卸载 npm 包 — 自动执行 npm uninstall -g tencentcloud-cls-sdk-codebuddy

常见问题

Q: hooks 会影响 CodeBuddy 正常使用吗？

不影响。 Hook 脚本以 fail-open 模式运行——即使采集失败也不会阻塞 CodeBuddy 执行。每个 hook 超时 10 秒自动放行。

Q: 启动后提示 "CodeBuddy not detected"？

确认 CodeBuddy 已安装且 ~/.codebuddy 目录存在。运行 cls-codebuddy info 查看检测结果。安装 CodeBuddy 后可执行 cls-codebuddy install 补充注入 hooks。

Q: CLS 控制台看不到数据？

按以下步骤排查：

1. cls-codebuddy info — 确认 CLS 凭据已配置（显示 CLS ready: ✓）
2. cls-codebuddy status — 确认服务运行中
3. ls ~/.cls-codebuddy/logs/codebuddy/ — 确认 hook 写入了 JSONL 事件
4. ls ~/.cls-codebuddy/logs/output/ — 确认 span 已生成
5. 检查 ~/.codebuddy/settings.json — 确认 hooks 配置已注入

Q: 如何更新 CLS 凭据？

支持只传需要更新的字段，未传入的字段自动沿用现有配置：

# 只更新 Topic ID
cls-codebuddy configure --topic-id <new-topic-id>

# 只更新 SecretId / SecretKey
cls-codebuddy configure --secret-id <new-id> --secret-key <new-key>

# 只更新 service-name / user-name / user-id
cls-codebuddy configure --service-name my-service --user-name alice --user-id u-123

# 全量更新（含所有可选字段）
cls-codebuddy configure \
  --endpoint     ap-guangzhou.cls.tencentcs.com \
  --topic-id     <new-topic-id> \
  --secret-id    <new-secret-id> \
  --secret-key   <new-secret-key> \
  --service-name codebuddy-agent \
  --user-name    <your-user-name> \
  --user-id      <your-user-id>

或无参数运行 cls-codebuddy configure 进入交互式引导（全量填写）。更新后服务会自动重启，无需手动操作。

Q: 服务日志在哪里？

日志文件：~/.cls-codebuddy/cls-codebuddy.log

• 单文件，上限 10 MB，超出后自动原地滚动（保留最新 5 MB），不产生额外文件
• 实时查看：tail -f ~/.cls-codebuddy/cls-codebuddy.log

Q: 数据上报有延迟吗？

• Hook 事件每 2 秒轮询读取一次
• Span 每 5 秒或满 32 条批量上报 CLS
• 对话结束后（Stop 事件）约 7 秒内数据到达 CLS 控制台

License

Apache-2.0