Metadata-Version: 2.4
Name: tencentcloud-cls-sdk-hermes
Version: 1.0.5
Summary: Tencent Cloud CLS observability plugin for Hermes
Author: Tencent Cloud
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: tencentcloud-cls-sdk-python<2,>=1.0.8

# tencentcloud-cls-sdk-hermes

腾讯云 CLS 可观测插件 for Hermes Agent。

自动上报 Trace、Audit、Gateway 事件到腾讯云日志服务（CLS），无需修改 Hermes 核心代码。

## 功能

- Trace：会话/对话轮次/LLM API 调用/工具调用
- Audit：LLM 输出/工具结果/终端命令/审批
- Gateway：网关入口消息
- 客户端 TTFT（首 Token 延迟）
- Token 用量（含 cache 命中）
- Skill 加载事件
- 值级脱敏（自动隐藏内联密钥）
- 实时上报（5 秒定时 flush）

## 一键安装

```bash
curl -fsSL https://tencentcloud-cls-sdk-hermes-1254139626.cos.ap-guangzhou.myqcloud.com/tencentcloud-cls-sdk-hermes-install.sh | bash -s -- install \
  --endpoint "ap-guangzhou.cls.tencentyun.com" \
  --topic-id "<your-topic-id>" \
  --secret-id "<your-secret-id>" \
  --secret-key "<your-secret-key>"
```

### 可选参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--service-name` | 服务名 | hermes-agent |
| `--env` | 环境标签 | prod |
| `--version` | 指定版本 | latest |

## 一键卸载

```bash
curl -fsSL https://tencentcloud-cls-sdk-hermes-1254139626.cos.ap-guangzhou.myqcloud.com/tencentcloud-cls-sdk-hermes-install.sh | bash -s -- uninstall
```

## 环境变量说明

安装脚本会自动写入 `~/.hermes/.env`，也可手动配置：

| 变量 | 必填 | 说明 |
|------|------|------|
| `HERMES_CLS_ENDPOINT` | ✅ | CLS 接入点 |
| `HERMES_CLS_TOPIC_ID` | ✅ | 日志主题 ID |
| `HERMES_CLS_SECRET_ID` | ✅ | 腾讯云 SecretId |
| `HERMES_CLS_SECRET_KEY` | ✅ | 腾讯云 SecretKey |
| `HERMES_CLS_SERVICE_NAME` | | 服务名（默认 hermes-agent） |
| `HERMES_CLS_ENV` | | 环境（默认 prod） |
| `HERMES_CLS_SAMPLE_RATE` | | 采样率 0.0~1.0（默认 1.0） |
| `HERMES_CLS_BATCH_SIZE` | | 批量大小（默认 32） |
| `HERMES_CLS_DEBUG` | | 调试模式（默认 false） |
| `HERMES_CLS_CAPTURE_TRACE` | | 采集 Trace（默认 true） |
| `HERMES_CLS_CAPTURE_AUDIT` | | 采集 Audit（默认 true） |
| `HERMES_CLS_CAPTURE_GATEWAY` | | 采集 Gateway（默认 true） |

## License

MIT
