# aibis

**Repository Path**: guojongg/aibis

## Basic Information

- **Project Name**: aibis
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Aibis — AI 编码代理遥测插件

## 概述

Aibis 是一个 OpenCode 遥测插件，用于采集 AI 编码代理的 LLM 调用数据并推送至 KetaOps 平台。在每次 Agent 会话中，插件自动捕获完整的调用链路：用户输入、LLM 调用（含 Token 用量、延迟、成本）、工具调用、思考文本和回复文本。所有事件通过 `trace_id` 串联，可在 KetaOps 仪表盘中统一查询和可视化。

```
OpenCode Agent ──→ ketaops-telemetry.js ──→ POST /api/v1/data ──→ KetaOps (仪表盘 + SPL 查询 + 告警)
                      │
         用户输入 → LLM 调用 → 工具调用 → 思考/回复文本 → 会话摘要
```

### 解决的问题

| 问题 | 方案 |
|------|------|
| LLM 调用像黑盒，无法追踪每次调用的成本 | 每次调用记录 model、token 数、延迟、成本 |
| Agent 决策链路不透明，出问题难以定位 | 通过 trace_id 串联同一会话内所有事件 |
| Token 消耗增长不可控，缺乏可视化 | KetaOps 仪表盘实时展示 Token 趋势与构成 |
| 不同 Agent 角色的调用模式差异不可见 | 按 agent_type 维度聚合分析 |
| 思考文本和回复文本难以回溯分析 | 自动采集 thinking_text 和 response_text |

## 快速开始

### 前提

- KetaOps 实例（用于数据存储和仪表盘）
- OpenCode 1.17+

### 安装

将插件文件复制到 OpenCode 的插件目录：

```bash
cp ketaops-telemetry.js ~/.config/opencode/plugins/
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `KETAOPS_URL` | KetaOps 实例地址 | 必填 |
| `KETAOPS_TOKEN` | KetaOps API Token | 必填 |
| `KETAOPS_EVENTS_REPO` | 数据写入的仓库名 | `llm_logs` |

在 OpenCode 启动前设置：

```bash
export KETAOPS_URL="https://performance.ketaops.cc"
export KETAOPS_TOKEN="your-api-token"
```

插件在 KetaOps 不可达时会静默忽略错误，不影响 OpenCode 正常工作。

### 可选：使用 npm 包

Aibis 也提供 npm 包 `@aibis/opencode`。在 `opencode.json` 中配置：

```json
{
  "plugins": ["./packages/opencode-telemetry/src/index.ts"]
}
```

> ⚠️ **TODO**: npm 包当前使用旧版 opencode hook 格式 (`chat.message`, `tool.execute.after`)，与 opencode 1.17+ 的 `event` 处理器格式不兼容。建议使用 `~/.config/opencode/plugins/ketaops-telemetry.js` 方式安装。

详见 `packages/opencode-telemetry/README.md`。

## 数据模型

插件采集 6 种事件类型，统一写入 KetaOps 指定仓库。所有事件共享 `trace_id` 实现跨调用关联。

| 事件类型 | 触发时机 | 核心字段 |
|----------|----------|----------|
| `user_prompt` | 用户发送消息 | text, agent, model, provider |
| `llm_call` | LLM 调用完成 (step-finish) | model, total_tokens, input_tokens, output_tokens, reasoning_tokens, cache_tokens, cost, reason |
| `tool_call` | 工具执行完成 | tool, call_id, input, output, exit_code, duration_ms |
| `thinking_text` | LLM 返回推理文本 | text |
| `response_text` | LLM 返回回复文本 | text |
| `session_summary` | 会话结束或更新 | title, agent_type, input_tokens, output_tokens, total_cost, files_changed |

详细数据模型设计见 `designs/data-model.md`。

## 仪表盘

项目预置了一个 KetaOps 仪表盘 YAML 文件 `dashboards/agent-telemetry.yaml`，包含 14 张图表：

- **KPI 数值卡**：LLM 调用总数、总 Token 用量、总成本、平均回复文本长度
- **趋势图**：LLM 调用趋势、Token 用量趋势、成本趋势、思考/回复文本趋势
- **分布图**：模型调用分布、Agent 类型分布、工具调用分布、事件类型分布、Finish 原因分布
- **表格**：最近会话列表
- **分析图**：Token 构成分析（输入/缓存/输出/推理）、平均思考文本长度

将该 YAML 导入 KetaOps 即可使用。仪表盘支持按 model 和 agent_type 动态筛选。

## 项目结构

```
aibis/
├── packages/
│   └── opencode-telemetry/        # npm 包 @aibis/opencode (TypeScript)
│       ├── src/
│       │   ├── index.ts           # 插件入口
│       │   ├── hooks.ts           # 事件钩子
│       │   ├── config.ts          # 配置管理
│       │   ├── cost.ts            # 成本计算
│       │   ├── exporter/          # 数据导出 (HTTP / OTLP)
│       │   └── __tests__/         # 单元测试
│       ├── package.json
│       └── README.md
├── dashboards/
│   └── agent-telemetry.yaml      # KetaOps 仪表盘定义
├── docs/
│   ├── industry-analysis.md       # AI Agent 可观测性行业分析
│   ├── current-status.md          # 当前主流工具的能力与差距
│   ├── architecture-design.md     # 系统架构设计
│   └── ketaops-integration.md     # 与 KetaOps 的深度结合方案
├── designs/
│   └── data-model.md             # 统一数据模型设计
└── README.md                     # 本文件
```

## 项目状态

| 能力 | 状态 |
|------|:---:|
| OpenCode 事件监听插件 (`ketaops-telemetry.js`) | ✅ 完成 |
| 6 种事件类型推送至 KetaOps | ✅ 完成 |
| 事件间 `trace_id` 关联 | ✅ 完成 |
| KetaOps 仪表盘 (14 张图表) | ✅ 已部署 |
| `@aibis/opencode` npm 包 | ✅ 完成 — 支持 event + legacy hooks 双格式 |
| OpenCode 命名钩子格式 (`chat.message`, `tool.execute.after`) | ✅ 完成 — 向后兼容保留 |
| OTLP Trace 导出 | ✅ 完成 — JSON 格式推送至 `{KETAOPS_URL}/v1/traces`，需设置 `OTEL_ENABLED=true` |
| 其他 AI 工具适配 (Claude Code, Cursor 等) | 🚧 规划中 |

当前 Aibis 聚焦于 OpenCode 平台的遥测采集。多平台支持在规划阶段，欢迎贡献。