tencent cloud

日志服务

Documentation日志服务Agent 可观测接入指南接入 AI Agent 说明接入 AI Coding Agent 数据（Onesuite-Pilot）

接入 AI Coding Agent 数据（Onesuite-Pilot）

Download
Focus Mode
Font Size
Last updated: 2026-09-04 14:33:16

操作场景

Onesuite-Pilot 是一款以本地常驻服务形式运行的数据采集程序，可自动探测并接入本机已安装的 AI Coding Agent ，将 AI Coding 过程中的会话数据采集、加工后上报至日志服务（Cloud Log Service，CLS），帮助您在 CLS 中对 AI Coding 活动进行检索分析与观测。
本文介绍如何安装、配置、验证及维护 Onesuite-Pilot。Onesuite-Pilot 当前已支持接入 Codebuddy、WorkBuddy，后续将持续扩展对更多 AI 编码工具的支持。
本文提供以下两种接入方式，您可根据实际情况选择：
接入方式
说明
推荐场景
使用支持 Skill 的 AI 工具，由 AI 自动创建或复用日志主题、识别环境并完成接入与分析。
使用支持 Skill 的 AI 工具，希望一键接入、减少手动配置。
按步骤执行安装命令，手动填写地域接入点、日志主题、密钥等参数完成接入。
需要精细化控制接入参数，或所用工具不支持 Skill。

前提条件

在安装前，请确认已满足以下条件：
已开通 日志服务 CLS。
已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息请前往 API 密钥管理 获取。
操作系统为 macOS 或 Linux（Windows 请使用 PowerShell 安装脚本）。
Node.js 版本 ≥ 18（安装脚本会自动探测 node、nvm 及常见路径）。
已获取接入所需的地域接入点（endpoint）：即 Agent 应用所在地域的 CLS 接入点域名，请参见 地域和访问域名。以广州地域为例，方式一中对应填写 Region（如 ap-guangzhou）；方式二中对应填写域名，外网域名为 ap-guangzhou.cls.tencentyun.com，内网域名为 ap-guangzhou.cls.tencentcs.com。

方式一：通过 Skill 快速接入与分析

如果您使用支持 Skill 的 AI 工具，可使用 腾讯云 Agent 可观测接入助手 自动完成接入与分析。该 Skill 已合并接入与分析能力，可自动创建或复用日志主题
请使用腾讯云 Agent 可观测接入 Skill：
https://skillhub.cn/skills/tencentcloud-cls-agent-obs

帮我把当前 AI 应用接入腾讯云 Agent 可观测。

接入方式：CodeBuddy + WorkBuddy
Region：ap-guangzhou

方式二：手动配置接入

手动接入需按步骤执行安装命令，并在命令中填写前提条件中已获取的地域接入点、日志主题 ID 及密钥信息。

步骤1：执行命令

执行以下一键安装命令。请将参数值替换为您在 CLS 控制台获取的实际信息。
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- install \\
  --cls-endpoint  "<your-cls-endpoint>" \\
  --cls-topic-id  "<your-topic-id>" \\
  --cls-secret-id "<your-secret-id>" \\
  --cls-secret-key "<your-secret-key>" \\

安装参数说明：

参数
必选
说明
--cls-endpoint
是
CLS 地域接入点域名，请参见 地域和访问域名。
以广州地域为例，外网域名：ap-guangzhou.cls.tencentyun.com，内网域名：ap-guangzhou.cls.tencentcs.com。
--cls-topic-id
是
目标日志主题 ID（TopicId）。
--cls-secret-id
是
访问密钥 SecretId，需对目标主题有写入权限。云 API 密钥信息请前往 API 密钥管理 获取。
--cls-secret-key
是
访问密钥 SecretKey。云 API 密钥信息请前往 API 密钥管理 获取。
--user-id
否
数据归属用户标识，写入上报数据的 gen_ai.user.id 字段。不指定时默认取主机名。也可写作 --userId 或 --user.id。
--user-name
否
用户展示名，映射为 gen_ai.user.name，与 userId 为两个独立字段。
--agents
否
指定接入的 Agent 列表（逗号分隔）。不指定时自动接入所有探测到的 Agent。
--data-dir
否
自定义数据目录，默认 ~/.onesuite-pilot。
--auto-update
否
自动升级，建议开启。
安装脚本将依次完成：依赖检查 → 下载安装包 → 探测 AI Agent → 部署程序 → 安装 Hook 脚本 → 写入配置 → 注册并启动服务。出现 ✅ 安装完成！ 即表示部署成功。
说明：
关于 userId 的取值优先级，最终生效的 userId 按以下优先级解析：
环境变量 ONESUITE_PILOT_USER_ID → 配置文件 userId → 配置文件 user.id → 主机名（兜底）。

步骤2：验证安装

安装完成后，执行以下命令查看服务状态与配置信息：
onesuite-pilot status   # 查看服务运行状态
onesuite-pilot info     # 查看版本、配置文件路径与完整配置
正常输出应包含 ✅ onesuite-pilot v... is running (PID xxxxx)，且 autostart: enabled。
说明：
若执行命令时提示 onesuite-pilot: command not found，请重启终端，或执行 source ~/.bashrc 使环境变量生效后重试。该提示不影响 OneSuite-Pilot 服务运行。

常用操作

完成接入后，您可参考本节内容对 Onesuite-Pilot 进行升级、配置变更、日常管理与卸载等运维操作。

常用命令

命令
说明
onesuite-pilot status
查看服务运行状态、PID、自启状态。
onesuite-pilot info
查看版本、配置文件路径、数据目录及完整配置。
onesuite-pilot restart
重启服务。修改配置后须执行，重启时会强制刷出缓冲区数据。
onesuite-pilot stop / start
停止 / 启动服务。

修改配置

若已完成安装，无需重跑安装脚本。直接编辑配置文件 ~/.onesuite-pilot/config.json，修改后重启服务即可生效。配置文件为标准 JSON，核心结构如下：
{
  "enabled": true,
  "dataDir": "/Users/you/.onesuite-pilot",
  "userId": "122855467",
  "userName": "helloworld",
  "flushers": {
    "cls": {
      "endpoint":  "ap-guangzhou.cls.tencentyun.com",
      "topicId":  "<your-topic-id>",
      "secretId": "<your-secret-id>",
      "secretKey": "<your-secret-key>"
    }
  }
}
修改前请务必备份配置文件，手动编辑 config.json 时若出现 JSON 格式错误或误改字段，可能导致服务无法启动或上报异常，保留备份可在出问题时可还原。
cp ~/.onesuite-pilot/config.json ~/.onesuite-pilot/config.json.bak
场景一：新增/修改 userId / userName
场景二：切换 CLS 上报目标（地域 / 主题）
在配置文件顶层（与 dataDir 同级）加入 userId 与 userName 两个字段，然后重启服务。
1. 编辑 config.json，新增以下字段：
"userId": "122855467",
"userName": "helloworld",
2. 重启服务使配置生效：
onesuite-pilot restart
修改 flushers.cls 下的 endpoint（地域接入点）与 topicId（目标主题），重启后生效。例如切换到 ap-guangzhou-open 地域的新主题：
  "flushers": {
    "cls": {
-     "endpoint": "ap-guangzhou.cls.tencentyun.com",
+     "endpoint": "ap-guangzhou-open.cls.tencentyun.com",
-     "topicId":  "9263b751-9b29-4931-aeb9-4405cf69a2ea",
+     "topicId":  "3189f2f4-1f03-4f4a-b4c5-b139d037df61",
      ...
    }
  }
注意：
切换主题时，请确认当前 SecretId / SecretKey 对新主题具备写入权限。日志写入权限由访问管理 CAM 控制（对应操作 cls:UploadLog，可精确到单个日志主题），配置方法参见 CLS 权限管理 与 CLS 访问策略模板。若新主题属于不同账号，须同步更新密钥，否则上报将因鉴权失败而被拒绝。

升级

Onesuite-Pilot 会持续迭代。以下情况建议升级到最新版本：
发布了新版本，您需要使用新功能或获取问题修复。
安装时未开启 --auto-update，需要手动更新到最新版本。
说明：
安装时已开启 --auto-update 的用户，程序会自动升级，通常无需手动执行本命令。升级不会覆盖已有的 ~/.onesuite-pilot/config.json 配置。
直接执行以下命令即可完成升级：
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- upgrade
升级完成后，可执行 onesuite-pilot info 确认版本已更新。

卸载

如需卸载，重新执行安装脚本并附加 --purge 参数（或按服务管理脚本提示操作），即可停止服务、移除 Hook 与自启项。数据目录 ~/.onesuite-pilot 可按需手动清理。
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- uninstall --purge

常见问题

安装后上报的 userId 是主机名，如何改成自定义值？

参见 修改配置中的场景一，在 config.json 顶层加入 userId 字段后重启即可，无需重装。

修改配置后是否需要重装？

不需要。直接编辑 config.json 并执行 onesuite-pilot restart 即可。重装会覆盖现有配置，仅在需要全新部署时使用。

日志文件里为什么还是旧的 userId / 旧主题？

本地日志文件（如 logs/ 下的 metrics 文件）仅在有数据流入时刷新，空闲期保留的是历史残留值。以 config.json 与 onesuite-pilot info 的输出为准，二者即为当前实际生效配置。

如何确认配置真正生效？

执行 onesuite-pilot info 查看服务加载的配置；待下一次有 Agent 活动产生数据后，检查 ~/.onesuite-pilot/logs/<agent>/*.jsonl 中最新记录的 gen_ai.user.id 字段即可确认。

为什么上报后 CLS 控制台暂时看不到新数据？

这通常是上报节奏所致，而非故障。数据采集仅在有 AI Agent 实际编码活动时发生；服务空闲时不产生新数据。新采集的数据会先在本地缓冲，待满足触发条件后统一上报。为降低网络开销、提升吞吐，Onesuite-Pilot 采用攒批上报（batch flush）机制，而非每产生一条数据即实时发送。触发一次上报需满足以下任意条件：
累积达到一定条数
到达时间间隔
积累到一定字节数
Previous Topic: Onesuite-Pilot 版本说明Next Topic: Agent Trace 字段定义说明

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation