# bondman

**Repository Path**: leonscript/bondman

## Basic Information

- **Project Name**: bondman
- **Description**: Who will read the files and report the dangerous information to the headquarters。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-01-18
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: tail, 告警, 短信

## README

# bondman
🕶️Who will read the files and report the dangerous information to the headquarters?

## 工具介绍

这是一个用于监控指定日志文件的工具，当发现文件中出现错误级别日志时，会通过 **AI 分析** 生成错误报告，并推送到 **飞书**；同时保留原有的 **阿里云短信** 通知能力作为兜底通道。

<br>

### 核心能力

- **日志监控**：`tail -f` 实时读取日志文件，支持文件滚动
- **AI 分析**：基于阿里云百炼 `qwen3.7-max` 模型，自动分析错误原因
- **多源上下文**：Agent 可调用以下 Tool 辅助分析
  - `jaeger_query_tool`：查询链路追踪信息，获取 span、service、错误 tags 和关键 attributes
  - `log_query_tool`：查询相同 traceID 的日志上下文
  - `access_log_query_tool`：查询相同 traceID 的接口访问记录
  - `params_query_tool`：查询相同 traceID 的请求参数（需配置 `paramsLogPath`）
- **飞书推送**：将精简后的 Markdown 分析报告直接推送到飞书
- **短信兜底**：保留阿里云短信通道，可在配置中独立开启/关闭

## 日志格式

工具要求日志必须以 JSON 的格式输出，如：

```json
{
  "@timestamp": "2026-06-25T01:11:59.301Z",
  "caller": "agent-gateway/agentgateway.go:82",
  "content": "gateway request error",
  "level": "error",
  "method": "POST",
  "path": "/api/contracts/inst_6a641dc3-ce87-4e8c-9a33-3b39f7c79a70/confirm-ledger",
  "span": "6442c1a567867c7e",
  "trace": "2830f509ff5dfd898c7742e763038ce3",
  "service": "agent-gateway",
  "module": "shared/agentobs",
  "logger": "eino-callback",
  "source_type": "callback",
  "attributes": {
    "error.message": "connection refused",
    "status.code": "ERROR"
  },
  "params": {
    "inst_id": "inst_6a641dc3-ce87-4e8c-9a33-3b39f7c79a70"
  }
}
```

下面几个字段，是日志 json 中必须包含的：

| 字段名        |            枚举值             |     类型 |                       说明 |
|:-----------|:--------------------------:|-------:|:-------------------------|
| level      | error:错误；fatal:致命错误（panic） | string |                     日志等级 |
| content    |             /              | string |                   日志详细内容（兼容旧字段 `msg`） |
| @timestamp |             /              | string |                     输出时间（兼容旧字段 `time`） |
| trace      |             /              | string | 链路追踪ID，用于方便追踪日志的上下文，建议使用（兼容旧字段 `trace_id`） |

推荐补充的字段：

| 字段名      | 类型   | 说明 |
|:-----------|:------|:-------------------------|
| span       | string | 触发告警的 Span ID |
| method     | string | HTTP 方法 |
| path       | string | 请求路径 |
| service    | string | 服务名，如 agent-gateway / contract-management |
| module     | string | 模块/库名，如 shared/agentobs |
| logger     | string | logger 标识，如 gin / eino-callback / business |
| source_type| string | 来源类型：manual / framework / middleware / callback |
| attributes | object | 触发告警的 attribute key/value |
| params     | object | 请求参数（建议脱敏） |

- **如果启用了 trace 字段，短信内容会使用 trace；如果没启用，短信内容会截取 content/msg 中的前 30 个字符。**
- **AI 分析会优先使用 trace 调用 Jaeger、日志查询、access log 查询等 Tool。**
- **未在上方列出的字段会被收集到 Extra 中供 AI 参考，不会丢失。**

## 配置说明

参考 `config.yml`：

```yaml
# 项目信息
project: 项目名称
mode: 环境类型

# 阿里短信配置
aliSms:
  enabled: false
  accessKeyId: id
  accessKeySecret: secrect
  endpoint: aliyuncs.com
  signNames:
    - enterprise
  templateCode: 短信模板编码
  phoneNumbers:
    - 123456789

# AI 分析配置（兼容 OpenAI 接口规范，示例为阿里云百炼）
ai:
  enabled: true
  openai:
    apiKey: your-api-key
    baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen3.7-max

# Jaeger 查询配置
jaeger:
  enabled: true
  endpoint: http://localhost:16686

# 飞书推送配置
feishu:
  enabled: true
  webhookUrl: https://open.feishu.cn/open-apis/bot/v2/hook/xxx
  secret: your-secret

# 日志查询配置
log:
  accessLogPath: ./access.log
  paramsLogPath: ./params.log  # 请求参数日志路径（可选）

# 同样错误日志发送的频率(Minute)
interval: 10

# 要监控的日志文件路径
logPath: ./run.log
```

### 配置项说明

| 配置块 | 字段 | 说明 |
|--------|------|------|
| `aliSms` | `enabled` | 是否启用短信通知 |
| `ai` | `enabled` | 是否启用 AI 分析和飞书推送 |
| `ai.openai` | `apiKey` | 模型服务 API Key（如百炼、DeepSeek 等） |
| `ai.openai` | `baseURL` | 模型服务 OpenAI 兼容端点 |
| `ai.openai` | `model` | 模型名称，示例 `qwen3.7-max` |
| `jaeger` | `enabled` | 是否启用 Jaeger Tool |
| `jaeger` | `endpoint` | Jaeger Query HTTP 地址 |
| `feishu` | `enabled` | 是否启用飞书推送 |
| `feishu` | `webhookUrl` | 飞书机器人 Webhook 地址 |
| `feishu` | `secret` | 飞书签名密钥（可选） |
| `log` | `accessLogPath` | access.log 文件路径 |
| `log` | `paramsLogPath` | 请求参数日志文件路径（可选，配置后 AI 可调用 params_query_tool） |

## 飞书消息格式

飞书通过 interactive card 推送结构化 Markdown 分析报告，按区块组织：

- **头部**：项目名/环境 + 错误等级 + 业务路径/摘要
- **📍 定位信息**：
  - 服务/模块（service/module）
  - 来源类型与 logger（source_type/logger）
  - 代码位置（caller）
  - Span ID
  - 触发 Attribute key
  - 请求方法/路径
- **🤖 AI 分析**：
  - 严重程度（P0/P1/P2）
  - 错误摘要（不超过 50 字）
  - 精简 Markdown 分析报告（不超过 300 字）
- **📋 上下文**：
  - TraceID 和 Jaeger 查询链接
  - 请求参数摘要
  - 关键 Attributes
- **📝 原始日志**：折叠展示原始日志内容

## 短信格式

保留原有阿里云短信模板，变量：

| 变量名 | 说明 |
|--------|------|
| project | 项目名称 + 环境 |
| content | 短信包含的日志内容 |

## 运行方式

```bash
# 编译
go build ./...

# 运行（使用 ./config.yml）
go run .

# 测试
go test ./...
```

## 本地手动测试

1. 在 `.env` 中配置 `AI_OPENAI_API_KEY` 和 `FEISHU_SECRET`，并通过 `make build` 编译；`config.yml` 中保留其他非敏感配置
2. 指向 `logPath` 到一个测试日志文件
3. 运行 `go run .`
4. 向日志文件追加 JSON 错误日志：

```bash
echo '{"level":"error","content":"test error","@timestamp":"2024-02-21T00:00:00Z","trace":"2830f509ff5dfd898c7742e763038ce3"}' >> run.log
```

5. 观察飞书是否收到 AI 分析报告

## 注意事项

- 不要提交真实的 API Key、手机号、Webhook 地址等敏感信息
- Jaeger/access log 查询失败时会自动降级，不影响主流程
- LLM 输出会做结构化解析，解析失败时会兜底推送原始日志