# loongsuite-pilot

**Repository Path**: alibaba/loongsuite-pilot

## Basic Information

- **Project Name**: loongsuite-pilot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LoongSuite Pilot

![LoongSuite](docs/_assets/img/loongsuite-logo.png)

**面向 AI Coding Agent 的本地遥测采集器**

[![CI](https://github.com/alibaba/loongsuite-pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/alibaba/loongsuite-pilot/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/alibaba/loongsuite-pilot)](https://github.com/alibaba/loongsuite-pilot/releases/latest)
[![License](https://img.shields.io/github/license/alibaba/loongsuite-pilot)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-enabled-4F62AD)](https://opentelemetry.io/)

[English](README.md) | **简体中文**

[概览](#概览) | [快速开始](#快速开始) | [文档](#文档) | [社区](#社区) | [参与贡献](#参与贡献)

---

## 概览

LoongSuite Pilot 是一个运行在开发者本机的 AI Coding Agent 遥测采集器。它可以发现本机已安装的支持 Agent，部署所需的 Hook 或插件，将不同 Agent 的活动数据归一化为统一的 GenAI 事件 Schema，并输出到本地日志、SLS、HTTP 或 Trace 后端。

<p align="center">
  <img src="docs/_assets/img/dashboard.png" alt="LoongSuite Pilot 本地 Dashboard" width="880">
  <br>
  <em>内置本地 Dashboard —— 一眼查看多 Agent Token、会话、请求、工具调用、模型、服务商和仓库活动。</em>
</p>

团队里常常会同时使用多个 AI Coding Agent，而每个 Agent 的本地数据格式、Hook 机制和日志结构都不一样。Pilot 提供一个统一的本机采集器，负责发现 Agent、采集活动、统一字段，并把数据送到适合分析、审计和可观测性的目标端。

Pilot 主要帮助回答这些问题：

- 当前哪些 Agent 正在被使用？
- 发生了哪些模型调用、会话、轮次和工具调用？
- 哪些 Agent 可以采集到 token 用量？
- 数据应该输出到哪里：本地文件、SLS、HTTP，还是 Trace？
- 敏感 Prompt、工具参数和密钥在上报前如何控制？

## 核心亮点

| 能力 | Pilot 做什么 |
|------|-------------|
| Agent 发现 | 通过本地路径和命令检测支持的 Agent。 |
| 采集能力部署 | 安装 Hook 或插件，并读取本地日志、会话或数据文件。 |
| 统一事件 Schema | 将 Agent 原生事件归一化为统一的 GenAI 事件字段。 |
| 多目标输出 | 支持 JSONL、阿里云 SLS、HTTP 和 OTLP Trace。 |
| 隐私控制 | 支持按 Agent 控制内容采集，并在输出前进行密钥脱敏。 |
| 本地运维 | 提供状态查看、重启、回滚和内置本地 Dashboard。 |

## 支持的 Agent

| Agent | 集成方式 | Trace 上报 | 日志上报 | Token 用量 | 对话 / 工具调用 |
|-------|----------|------------|----------|------------|----------------|
| Claude Code | Hook | Yes | Yes | Yes | Yes |
| Codex | Hook | Yes | Yes | Yes | Yes |
| Cursor | Hook | Yes | Yes | Yes | Yes |
| Cursor CLI | 复用 Cursor Hook | Yes | Yes | Yes | Yes |
| DeepSeek Harness | YAML patch 插件 + 本地 JSONL 轮询 | Yes | Yes | Yes | Yes |
| Grok Build | Hook + 本地 session 日志 | Yes | Yes | Yes | Yes |
| Hermes Agent | 原生目录插件 | Yes | Yes | Yes | Yes |
| Kiro CLI | Hook / session 轮询 | Yes | Yes | No | Yes |
| MiMo Code | 插件注入 | Yes | Yes | Yes | Yes |
| OpenClaw | 插件注入 | Yes | Yes | Yes | Yes |
| OpenCode | 插件注入 | Yes | Yes | Yes | Yes |
| Pi Coding Agent | Extension 注入 | Yes | Yes | Yes | Yes |
| Qoder | Hook | Yes | Yes | Yes | Yes |
| Qoder CN | Hook | Yes | Yes | Yes | Yes |
| Qoder for JetBrains | 自动检测 | Yes | Yes | Yes | Yes |
| Qoder CLI | Hook / session polling | Yes | Yes | Yes | Yes |
| Qoder Work | Hook / 本地数据轮询 | Yes | Yes | Yes | Yes |
| Qoder Work CN | Hook / 本地数据轮询 | Yes | Yes | Yes | Yes |
| Qwen Code CLI | Hook | Yes | Yes | Yes | Yes |
| Qwen Work CN | Hook / 本地数据轮询 | Yes | Yes | Yes | Yes |
| Wukong | CLI API 轮询 | Yes | Yes | Yes | Yes |
| WorkBuddy | Hook 唤醒 + 本地 transcript 监听/轮询兜底 | Yes | Yes | Yes | Yes |

OpenClaw 集成支持 2026.3.8 及以上版本，自动识别版本；5.12 之前的模型调用时间通过旧版 Hook 推定，详见[兼容性说明](docs/zh-CN/agents.md#openclaw-兼容性与生命周期)。

DeepSeek Harness（`dsh`）通过用户级 `cordis.patch.yml` 加载 Pilot
可观测插件，采集原生 LLM、reasoning、工具、Token 和首 Token
延迟数据。启用、原始日志、禁用和卸载行为见
[《Agent 配置》](docs/zh-CN/agents.md#deepseek-harness-采集与生命周期)。

### Windows Agent 明确支持情况

上表描述 Pilot 的总体接入能力，不代表每个 Agent 在所有操作系统上均受支持。目前文档明确说明支持 Windows 的 Agent 如下：

| Agent | Windows 集成方式 | Trace 上报 | 日志上报 | Token 用量 | 对话 / 工具调用 | 使用条件 |
|-------|------------------|------------|----------|------------|-----------------|----------|
| Claude Code | Hook | 支持 | 支持 | 支持 | 支持 | — |
| Cursor | Hook | 支持 | 支持 | 支持 | 支持 | — |
| Qoder Work | Hook / 本地数据源 | 支持 | 支持 | 不支持 | 支持 | User 版本 |
| Qoder CLI | Hook | 支持 | 支持 | 不支持 | 支持 | — |
| Qoder IDE | Hook / 本地数据源 | 支持 | 支持 | 支持 | 支持 | Qoder 1.10.0 及以上 User 版本 |
| OpenCode | 插件注入 | 支持 | 支持 | 支持 | 支持 | — |
| WorkBuddy | Hook 唤醒 + 本地 transcript | 支持 | 支持 | 支持 | 支持 | WorkBuddy Desktop 5.3.5.0；Windows 11 安装态 E2E |

未列入 Windows 表格的 Agent，表示当前没有明确的 Windows 支持声明，并不一定代表无法在 Windows 上运行。支持矩阵参考[阿里云 AI Coding Agent 接入文档](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/ai-application-access-ai-coding-agent/)，Windows 环境要求与安装方法见[安装指南](docs/zh-CN/installation.md)。

Agent 定义位于 `agents.d/`。如需接入新的 Agent，请参考 [新 Agent 接入](docs/zh-CN/agent-onboarding.md)。

## 快速开始

前置要求：

- Node.js 18 或更高版本
- `npm`
- `curl` 或 `wget`

从公开包安装：

```bash
curl -fsSL https://loongcollector-community-edition.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh -o /tmp/loongsuite-pilot-installer.sh && bash /tmp/loongsuite-pilot-installer.sh install
```

验证服务状态：

```bash
loongsuite-pilot status
loongsuite-pilot info
```

默认会开启本地 JSONL 输出，路径为 `~/.loongsuite-pilot/logs/output/`。

安装参数、卸载命令和源码运行方式见 [安装指南](docs/zh-CN/installation.md)。

## 配置 Pilot

配置优先级为：环境变量 > `~/.loongsuite-pilot/config.json` > 内置默认值。

根据你要做的事情选择文档：

| 任务 | 文档 |
|------|------|
| 选择采集哪些 Agent，控制内容采集策略 | [Agent 配置](docs/zh-CN/agents.md) |
| 自定义 Agent 名称和实例 | [自定义 `gen_ai.agent.name` 和 `agentteams.instance.id`](docs/zh-CN/custom-agent-identity.md) |
| 写入本地 JSONL 日志 | [本地 JSONL 输出](docs/zh-CN/local-jsonl-output.md) |
| 上报日志到 SLS | [SLS 输出](docs/zh-CN/sls-output.md) |
| 上报 OTLP Trace | [Trace 输出](docs/zh-CN/trace-output.md) |
| 将 Trace 上下文和资源属性传给 Claude Code 调用的 CLI | [Claude Code 下游 CLI 上下文传播](docs/zh-CN/claude-code-downstream-trace-propagation.md) |
| POST 到 HTTP 接口 | [HTTP 输出](docs/zh-CN/http-output.md) |
| 输出前进行密钥脱敏 | [数据脱敏](docs/zh-CN/masking.md) |
| 查看全局配置加载顺序和保留策略 | [配置总览](docs/zh-CN/configuration.md) |

### 上游 Trace 串联(可选)

把采集到的 agent span 挂到**上游** trace 下,使每一轮的 span 树重挂到上游 span。默认关闭,且全程 fail-open(绝不影响正常采集/上报)。

| 配置项 | 取值 | 默认 |
| ------ | ---- | ---- |
| `LOONGSUITE_PILOT_UPSTREAM_LINK`(环境变量)· `upstreamLink.enabled`(config.json) | `true` / `1` 开启;不设、`false` 或 `0` 关闭 | 关闭 |
| `LOONGSUITE_PILOT_UPSTREAM_LINK_PROPAGATE_TO_TOOLS`(环境变量)· `upstreamLink.propagateToTools`(config.json) | 将 Trace 上下文和可选资源属性传给受支持的下游 CLI 工具调用 | 关闭 |
| `LOONGSUITE_PILOT_UPSTREAM_LINK_PROPAGATE_TO_LLM`(环境变量)· `upstreamLink.propagateToLlm`(config.json) | 以 `traceparent` 请求头把 Trace 上下文转发给 LLM 网关(Claude Code) | 关闭 |
| `LOONGSUITE_PILOT_UPSTREAM_LINK_GENERATE_TRACE_WHEN_MISSING`(环境变量)· `upstreamLink.generateTraceWhenMissing`(config.json) | 没有有效上游上下文时，为每个 turn 生成本地 Trace 上下文并继续传播 | 关闭 |
| `LOONGSUITE_PILOT_UPSTREAM_LINK_TTL_MS`(环境变量)· `upstreamLink.ttlMs`(config.json) | `acp-correlate` 文件清理 TTL(毫秒) | `86400000`(24 小时) |

开启后,上游 `traceparent` 经以下两种方案之一到达 Pilot,并在采集时 stamp 到记录(turn 打 `trace_id`、用户输入事件打 `parent_span_id`):

- **关联文件**(per-turn):调用方在发送 prompt 时,把 `{sessionId, contentHash, contentPrefix, traceparent}` 写入 `~/.loongsuite-pilot/acp-correlate/<sessionId>.jsonl`。串联与协议无关——唯一要求是 `sessionId` 等于 Pilot 采集该 turn 时的 `gen_ai.session.id`,且内容(hash 或前缀)能匹配采集到的用户文本。ACP client 天然满足(`session/new` 的 id 会贯穿采集),故 ACP 是主要场景。
- **环境变量**(agent 进程上的 `TRACEPARENT`):经 agent 的 hook 作用于该会话的第一个 turn。适用于调用方无法预先拿到 per-turn `sessionId` 的情况。

对于 Claude Code，同时开启 `upstreamLink.enabled` 和 `propagateToTools` 后，Pilot 会把上下文传给主 agent 的 `Bash` 调用。`PreToolUse(Bash)` hook 会预留 TOOL span id，在 Bash 命令前注入 `TRACEPARENT`（存在有效值时也注入 `TRACESTATE`），Stop hook 构建 TOOL span 时再复用同一个 id。可选开启 `generateTraceWhenMissing`，使没有上游上下文的 turn 也生成并传播本地 Trace。用户还可在启动 Claude Code 时设置 `LOONGSUITE_PILOT_RESOURCE_ATTRIBUTES`，Pilot 会将其映射为下游 CLI 可读取的标准 `OTEL_RESOURCE_ATTRIBUTES`。建议把 `upstreamLink` 开关写入 `config.json`；环境变量只对继承它的进程生效，单独执行 `loongsuite-pilot restart` 不会修改已运行 Claude Code 的 hook 环境。下游 CLI 需要自行提取 Trace Context 并配置 trace exporter；Go 探针可直接按 OpenTelemetry 标准读取资源属性。该能力全程 fail-open，当前不覆盖 ACP-only 下游 Trace 传播、subagent、PowerShell、MCP 和非 Bash 工具。

同时开启 `upstreamLink.enabled` 和 `propagateToLlm` 后，同一条 Trace 会延伸到 **LLM 网关**：Claude Code 的 fetch preload 会在发往网关的 `/v1/messages` 请求上注入 `traceparent`，trace-id 和 flags 原样透传，parent-id 替换为该次物理请求的 span id，使网关侧 span 挂在它之下。发生重试的调用会按 attempt 各自产生一个 LLM span，每个 attempt 通告自己的 span id，网关 span 因此挂在真正发出该请求的 attempt 之下。调用方自己已设置的 `traceparent` 绝不会被覆盖，整条路径 fail-open。

## 输出数据

| 后端 | 用途 |
|------|------|
| JSONL | 本地备份和调试查看，默认开启。 |
| SLS | 上报到阿里云日志服务，支持 WebTracking、AK 和 API Key 模式。 |
| HTTP | 批量 POST 到自定义服务端。 |
| OTLP Trace | 将 GenAI 活动导出为 OpenTelemetry Trace。 |

Pilot 会对所有支持的 Agent 输出统一的 GenAI 事件 Schema。字段说明见 [输出事件 Schema](docs/zh-CN/output-event-schema.md)。

## 运行和运维

安装后可以使用 `loongsuite-pilot` 命令：

```bash
loongsuite-pilot start
loongsuite-pilot stop
loongsuite-pilot restart
loongsuite-pilot status
loongsuite-pilot info
loongsuite-pilot token-usage
loongsuite-pilot rollback
```

本地 Dashboard 会随采集服务一起启动和停止，直接打开
`http://127.0.0.1:8765/`，无需单独的 monitor 命令。页面直接读取采集服务生成的
`logs/metrics-summary.json`。

macOS 可按需执行 `loongsuite-pilot dashboard shortcut install`，创建带雷达图标的
Dashboard 网页快捷方式（`.webloc`），并添加到程序坞的文件区。普通安装和升级不会自动添加。
点击后用默认浏览器打开页面，不会启停 Pilot；修改端口后重新执行此命令即可更新网址。
详见[Dashboard 快捷方式](docs/zh-CN/installation.md#macos-dashboard-快捷方式)。

macOS 菜单栏 App：

在 macOS 上，Pilot 安装完成后会自动常驻菜单栏，无需额外命令。它实时展示 Token、会话、请求、工具调用数量，以及按 Agent 和 Provider 的分布，让你不用打开 Dashboard 也能随时掌握活动情况。

菜单栏中点击“退出”只会退出菜单栏，不会停止采集。需要重新打开时，执行：

```bash
loongsuite-pilot menubar start
```

请在 macOS 桌面用户的终端中执行，不要加 `sudo`。该命令不会重启采集服务；菜单栏已经运行时不会重复启动。采集服务需已启动。命令会向当前生效的 `config.json` 持久化 `"enableStatusBarApp": true`。

只关闭菜单栏可执行 `loongsuite-pilot menubar stop`，采集服务继续运行；菜单栏已退出时也会正常返回。命令会持久化 `"enableStatusBarApp": false`，下次启动采集服务时不会再自动打开菜单栏。

<p align="center">
  <img src="docs/_assets/img/menubar.jpg" alt="LoongSuite Pilot macOS 菜单栏 App" width="360">
</p>

环境变量 `LOONGSUITE_PILOT_ENABLE_STATUS_BAR_APP` 的优先级仍高于 `config.json`。如果它设置为禁用，需先取消或改为 `true` 才能执行 `menubar start`；如果它设置为启用，后续启动 Pilot 时仍可能覆盖 `menubar stop` 写入的配置。

## 文档

[用户手册](docs/zh-CN/README.md) - 安装、配置、运行和扩展 Pilot 的完整入口

[安装指南](docs/zh-CN/installation.md) - 安装、验证服务、卸载和源码运行

[配置参考](docs/zh-CN/configuration.md) - 全局配置加载、运行开关、保留策略和配置入口

[输出 Schema](docs/zh-CN/output-event-schema.md) - 标准事件名称、字段、Provider 和结束原因

[开发者指南](docs/zh-CN/agent-onboarding.md) - 为新的 AI Coding Agent 增加采集支持

## 开发

```bash
git clone https://github.com/alibaba/loongsuite-pilot.git
cd loongsuite-pilot
npm install
npm run build
node scripts/postinstall.js
node dist/index.js
```

本地开发：

```bash
npm install
npm run build
npm run typecheck
npm test
```

如需从本地构建包安装为后台服务，请参考 [安装指南](docs/zh-CN/installation.md)。

## 参与贡献

欢迎提交 Issue 和 Pull Request。提交变更前，请运行与 CI 一致的核心检查：

```bash
npm ci
npm run typecheck
npm test
npm run build
```

如需增加新的 AI Coding Agent 支持，请先阅读[新 Agent 接入指南](docs/zh-CN/agent-onboarding.md)。Bug 和功能建议可通过 [GitHub Issues](https://github.com/alibaba/loongsuite-pilot/issues) 提交。

## 社区

欢迎反馈和建议，扫描下方二维码加入 LoongSuite Pilot 钉钉交流群。

| LoongSuite Pilot SIG |
|----|
| <img src="docs/_assets/img/loongsuite-pilot-sig-dingtalk.jpg" height="150"> |

## LoongSuite 生态

| 项目 | 定位 |
| ---- | ---- |
| [LoongCollector](https://github.com/alibaba/loongcollector) | 面向日志、指标、Trace、事件和 Profile 的高性能采集器。 |
| [LoongSuite Java](https://github.com/alibaba/loongsuite-java) | 面向 Java instrumentation 的共享 GenAI 遥测工具库。 |
| [LoongSuite Go](https://github.com/alibaba/loongsuite-go) | 面向 Go 应用的编译期自动埋点。 |
| [LoongSuite Python](https://github.com/alibaba/loongsuite-python) | 面向 Python 和 GenAI 应用的 OpenTelemetry 自动埋点。 |
| [LoongSuite JS](https://github.com/alibaba/loongsuite-js) | 面向 JavaScript AI Agent 的 OpenTelemetry 集成。 |
| [LoongSuite Pilot](https://github.com/alibaba/loongsuite-pilot) | 面向 AI Coding Agent 的本地遥测采集器。 |

## 许可证

Apache License 2.0 - 详见 [LICENSE](LICENSE)。