# sgl_agent_bridge

**Repository Path**: madstone_thu/sgl_agent_bridge

## Basic Information

- **Project Name**: sgl_agent_bridge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SGL Agent Bridge

`sgl_agent_bridge` 是一个独立项目，用来把 OpenAI 兼容的 Agent 客户端
接到 SGLang 服务器前面，并把请求、流式输出、SGLang batch 日志和 KV
快照整理成可分析的 JSONL 痕迹。

当前项目已经同时支持两种运行模式：

- `analysis`
  纯非侵入式模式。桥只记录代理侧事实，再离线关联 SGLang 的 batch 日志。
- `audit`
  侵入式模式。SGLang 服务器经过最小 patch 后，会按请求输出结构化审计事件，
  bridge 会自动探测并升级到 `audit`。

## Agent Skills 索引

仓库内置了几份面向 agent 的工作流技能，优先放在 `.agents/skills/`：

- `.agents/skills/sgl-agent-bridge-audit-mode/SKILL.md`
  启用、验证和排查 `audit` 模式
- `.agents/skills/sgl-agent-bridge-server-diagnosis/SKILL.md`
  排查上游 SGLang 或 OpenAI-compatible 服务
- `.agents/skills/sgl-agent-bridge-tracing/SKILL.md`
  采集和串联 bridge trace
- `.agents/skills/sgl-agent-bridge-reporting/SKILL.md`
  生成 trace Markdown / HTML 报告
- `.agents/skills/sgl-agent-bridge-glm51-performance/SKILL.md`
  本地 GLM-5.1 服务提速、冷启动拆解和 API 性能验证

性能测量结果单独记录在：

- `docs/glm51-performance-results.md`

## 适用场景

- 想知道 OpenCode、OpenClaw、Hermes 或任意 OpenAI 兼容客户端到底发了哪些请求。
- 想观测请求长度、流式输出长度、prefill/decode 过程和 KV-cache 命中情况。
- 想批量收集 trace，而不是临时人工看 docker logs。
- 想在不 patch 客户端的前提下，把请求级别 attribution 尽量下沉到 server。

## 核心产物

运行后会得到这些文件：

- `request_events.jsonl`
  bridge 看到的请求开始、结束、错误、prompt 大小等事实。
- `token_progress_events.jsonl`
  bridge 看到的流式输出增长。
- `upstream_errors.jsonl`
  upstream HTTP 错误与连接错误。
- `bridge_runtime_status.json`
  bridge 启动时对 upstream 的 probe 结果，以及当前 `effective_mode`。
- `server_span_events.jsonl`
  从 SGLang 普通日志里解析出的 batch 级 prefill/decode 事件。
- `audit_request_events.jsonl`
  仅在 server patch 生效时存在或有内容。来自 server 的请求级审计事件。
- `kv_snapshot_events.jsonl`
  KV 快照归一化结果。
- `correlation_events.jsonl`
  analysis 模式下的离线关联结果。

## `analysis` 与 `audit` 的区别

`analysis` 模式能证明：

- 代理侧请求何时发出、何时结束
- 流式输出何时增长
- server 在哪些时间点做了 prefill/decode batch

但它不能在高并发下严格证明：

- 某个 batch 一定属于哪个 request
- 某个 request 的精确 prefix hit 长度
- 某个 subagent 的精确 decode token 归属

`audit` 模式额外要求 server 提供两个能力：

- `bridge_request_id_passthrough`
- `request_audit_events`

一旦 upstream `/internal/sgl_agent_bridge/status` 返回这两个能力，bridge 会把
`x-sgl-bridge-request-id` 注入到 upstream 请求，并自动把 `effective_mode`
切换为 `audit`。这时 `audit_request_events.jsonl` 会提供请求级别的：

- `request_id` / `bridge_request_id`
- `request_length_tokens`
- `prefill_new_tokens`
- `prefill_cached_tokens`
- `decode_tokens`
- `queue_time_ms`
- `run_time_ms`
- `traceparent`

## 快速开始

### 1. 准备环境

```bash
cd /home/zli/github/sglang/sgl_agent_bridge
source .env.example
uv sync
source .venv/bin/activate
```

如果要跑本机 GLM-5.1，可以直接：

```bash
source .env.glm51.local
```

### 2. 启动 bridge

```bash
uv run sgl-agent-bridge serve \
  --upstream-base-url "$SGL_AGENT_BRIDGE_UPSTREAM_BASE_URL" \
  --api-key "$SGL_AGENT_BRIDGE_API_KEY" \
  --listen-host "$SGL_AGENT_BRIDGE_LISTEN_HOST" \
  --listen-port "$SGL_AGENT_BRIDGE_LISTEN_PORT" \
  --output-dir "$SGL_AGENT_BRIDGE_OUTPUT_DIR" \
  --preferred-mode audit
```

如果 upstream 没有 patch，bridge 会自动回退到 `analysis`，不会中断服务。

### 3. 校验是否成功进入 `audit`

先看 upstream：

```bash
curl -s -H "Authorization: Bearer $SGL_AGENT_BRIDGE_API_KEY" \
  "${SGL_AGENT_BRIDGE_UPSTREAM_BASE_URL%/v1}/internal/sgl_agent_bridge/status"
```

再看 bridge：

```bash
curl -s "http://${SGL_AGENT_BRIDGE_LISTEN_HOST}:${SGL_AGENT_BRIDGE_LISTEN_PORT}/internal/sgl_agent_bridge/mode"
cat "$SGL_AGENT_BRIDGE_OUTPUT_DIR/bridge_runtime_status.json"
```

如果 patch 生效，应该同时看到：

- upstream `status == "ok"`
- `schema_version == "2026-04-17"`
- `features.request_audit_events == true`
- `features.bridge_request_id_passthrough == true`
- bridge `effective_mode == "audit"`

### 4. 让客户端走 bridge

把客户端 base URL 改成：

```text
$SGL_AGENT_BRIDGE_CLIENT_BASE_URL
```

例如 OpenCode 的 provider `baseURL` 应该指向 bridge，而不是直接指向 SGLang。

如果需要稳定区分不同 terminal 或不同 agent 分支，推荐在启动客户端前显式
设置 lineage hint，而不是只靠离线时间对齐。

bridge 当前按这个优先级读取 lineage 元数据：

1. 入站请求头
2. bridge 进程环境变量
3. 离线 client log 推断

如果不 patch 客户端源码，最小可维护做法是每个 terminal 启动一个独立
bridge 实例。每个 bridge 实例使用不同端口、不同 output dir 和不同
`SGL_AGENT_BRIDGE_SESSION_ID`：

```bash
export SGL_AGENT_BRIDGE_SESSION_ID="opencode-term-1"
export SGL_AGENT_BRIDGE_AGENT_ROLE="main"
export SGL_AGENT_BRIDGE_AGENT_MODE="primary"
export SGL_AGENT_BRIDGE_LISTEN_PORT="8121"
export SGL_AGENT_BRIDGE_OUTPUT_DIR="trace/opencode-term-1/live"
```

第二个 terminal 对应另一个 bridge 实例：

```bash
export SGL_AGENT_BRIDGE_SESSION_ID="opencode-term-2"
export SGL_AGENT_BRIDGE_AGENT_ROLE="main"
export SGL_AGENT_BRIDGE_AGENT_MODE="primary"
export SGL_AGENT_BRIDGE_LISTEN_PORT="8122"
export SGL_AGENT_BRIDGE_OUTPUT_DIR="trace/opencode-term-2/live"
```

如果你有自己的 wrapper，也可以直接在请求头注入这些字段：

- `x-sgl-bridge-session-id`
- `x-sgl-bridge-parent-request-id`
- `x-sgl-bridge-step`
- `x-sgl-bridge-agent-role`
- `x-sgl-bridge-agent-mode`

建议同时做到：

- 每个 terminal 使用独立的 bridge 端口
- 每个 terminal 使用独立的 `SGL_AGENT_BRIDGE_OUTPUT_DIR`
- 每次长任务单独建 trace 目录

这样即使不上客户端 patch，`request_events.jsonl` 和后续
`audit_request_events.jsonl` 也能按 terminal 维度稳定分组。

注意：环境变量 fallback 由 bridge 进程读取，不是由 OpenCode 进程读取。
如果多个 OpenCode terminal 共用同一个 bridge 实例，仅在客户端 terminal
里设置不同 `SGL_AGENT_BRIDGE_SESSION_ID` 不会生效。共用一个 bridge 时，
需要 wrapper 注入上面的请求头。

### 5. 收集 side-channel 证据

```bash
docker logs --since 2026-04-17T18:00:00Z "$SGL_AGENT_BRIDGE_SERVER_CONTAINER" \
  > "$SGL_AGENT_BRIDGE_SERVER_LOG_PATH" 2>&1

eval "$SGL_AGENT_BRIDGE_KV_SNAPSHOT_CMD" > "$SGL_AGENT_BRIDGE_KV_SNAPSHOT_PATH"
```

### 6. 归一化日志

```bash
uv run sgl-agent-bridge collect \
  --server-log "$SGL_AGENT_BRIDGE_SERVER_LOG_PATH" \
  --kv-snapshot "$SGL_AGENT_BRIDGE_KV_SNAPSHOT_PATH" \
  --output-dir "$SGL_AGENT_BRIDGE_OFFLINE_DIR"
```

### 7. 生成 Markdown / HTML 报告

给某个 trace 目录生成简约 Markdown 报告：

```bash
uv run sgl-agent-bridge report-md \
  --trace-dir trace/<run>
```

给同一个 trace 目录生成单文件 HTML 可视化：

```bash
uv run sgl-agent-bridge report-html \
  --trace-dir trace/<run>
```

默认输出：

- `trace/<run>/report.md`
- `trace/<run>/report.html`

HTML 里包含两种视图：

- `x=prompt index`, `y=context length` 的堆叠柱状图
- `x=server wall clock time`, `y=event/request lane` 的时间视图

如果检测到明显的上下文断崖下降，HTML 会用启发式的 summarization
marker 标出来。

## 如何验证侵入式 patch 真的生效

只看 `/health` 不够。建议按下面四步确认：

1. upstream status endpoint 可访问。

```bash
curl -s -H "Authorization: Bearer $SGL_AGENT_BRIDGE_API_KEY" \
  "${SGL_AGENT_BRIDGE_UPSTREAM_BASE_URL%/v1}/internal/sgl_agent_bridge/status"
```

2. bridge 已经切到 `audit`。

```bash
cat "$SGL_AGENT_BRIDGE_OUTPUT_DIR/bridge_runtime_status.json"
```

3. server 原始日志里出现 `sgl_agent_bridge.audit`。

```bash
docker logs --since 5m "$SGL_AGENT_BRIDGE_SERVER_CONTAINER" 2>&1 | \
  rg 'sgl_agent_bridge\.audit'
```

4. `collect` 后能得到 `audit_request_events.jsonl`。

```bash
wc -l "$SGL_AGENT_BRIDGE_OFFLINE_DIR/audit_request_events.jsonl"
tail -n 5 "$SGL_AGENT_BRIDGE_OFFLINE_DIR/audit_request_events.jsonl"
```

如果第 1 步失败，说明 server patch 没生效。
如果第 1 步成功但第 2 步是 `analysis`，说明 bridge probe 或 schema 不匹配。
如果第 2 步成功但第 3、4 步没有内容，说明 server 没有真正输出审计日志。

## OpenCode 实测要点

本项目已经用本机 GLM-5.1 + bridge + OpenCode 做过实测：

- bridge 自动升级到 `audit`
- OpenCode `/init` 产生了多个真实请求
- server 为不同 request id 输出了独立的 `prefill_accounted` / `decode_accounted`
  事件
- `collect` 成功生成 `audit_request_events.jsonl`

需要注意的是，OpenCode 的长任务可能会持续探索仓库较久，CLI 不一定很快退出。
这不影响 audit trace 的生成；只要 bridge 和 server 产物齐全，就足以验证链路。

## 与不同 Agent 系统的兼容性

`sgl_agent_bridge` 面向 OpenAI 兼容接口，所以可以放在这些系统前面：

- OpenCode
- OpenClaw
- Hermes
- 其他 OpenAI-compatible client

客户端不需要理解 `x-sgl-bridge-request-id`。这是 bridge 在 upstream 边界自动注入的。

## 当前 Docker 镜像的兼容性注意事项

当前 `glm51-sglang:local` 镜像内置的是一份较旧的 SGLang 源码快照。

结论很重要：

- 不能直接把宿主机最新版 `python/sglang/srt/...` 整文件覆盖进容器
- 必须以镜像内源码为基线做兼容 patch

否则会出现这类版本漂移问题：

- `constants.py` 与 `http_server.py` 不匹配
- `io_struct.py` 引用了镜像里不存在的模块
- server 在 import 阶段就启动失败

因此，侵入式 patch 的维护策略应该是：

- bridge 主逻辑在 `sgl_agent_bridge` 仓库维护
- 针对具体镜像版本的 server patch，按镜像源码基线生成兼容补丁

## 测试

bridge 项目本地测试：

```bash
cd /home/zli/github/sglang/sgl_agent_bridge
source .venv/bin/activate
uv run pytest tests -q
```

当前本地结果：`41 passed`

## Agent 使用手册

面向 Agent 的操作手册放在 repo-local skills：

- [`.agents/skills/sgl-agent-bridge-tracing/SKILL.md`](.agents/skills/sgl-agent-bridge-tracing/SKILL.md)
- [`.agents/skills/sgl-agent-bridge-server-diagnosis/SKILL.md`](.agents/skills/sgl-agent-bridge-server-diagnosis/SKILL.md)
- [`.agents/skills/sgl-agent-bridge-audit-mode/SKILL.md`](.agents/skills/sgl-agent-bridge-audit-mode/SKILL.md)
- [`.agents/skills/sgl-agent-bridge-reporting/SKILL.md`](.agents/skills/sgl-agent-bridge-reporting/SKILL.md)