# g-agent

**Repository Path**: ryven/g-agent

## Basic Information

- **Project Name**: g-agent
- **Description**: 个人agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# g-agent

这是一个按 `GUIDE.md` 思路落地的最小 Agent 骨架，但核心边界做了一个关键调整：

- `GUIDE.md` 原始设计偏向 `db/crud`
- 当前实现改成 `app/services/backend.py` 统一调用外部 HTTP 业务接口
- Agent 本身只负责消息接入、会话、ReAct 循环、工具注册和回复格式化

这样更适合参考 openclaw 做可控执行流，而不是把业务数据强耦合在 agent 进程里。

## 当前结构

- `app/main.py`
  FastAPI 入口，仅保留健康检查
- `app/feishu/`
  飞书长连接接入、消息发送
- `app/queue/`
  Celery 异步消费
- `app/session/`
  Redis 会话状态与焦点单据
- `app/agent/`
  Prompt、Context Builder、LLM 调用、ReAct 主循环
- `app/tools/`
  工具 schema、注册表、执行器、业务工具实现
- `app/services/backend.py`
  唯一业务数据入口，所有订单/运单/回单查询和写入都从这里走 HTTP

## 推荐后端接口契约

当前工具层默认对接以下接口：

- `POST /orders`
- `GET /orders`
- `GET /carriers/available`
- `POST /orders/{order_id}/assign-carrier`
- `POST /waybills`
- `GET /waybills/{waybill_no}/tracking`
- `POST /waybills/{waybill_no}/receipt`
- `POST /waybills/{waybill_no}/exception`
- `GET /documents/search`

建议返回统一 JSON 结构，例如：

```json
{
  "items": [],
  "message": "ok"
}
```

或单对象：

```json
{
  "id": 1,
  "order_no": "ORD-001"
}
```

## 启动

1. 创建虚拟环境并安装依赖
2. 复制 `.env.example` 为 `.env`
3. 先启动 Redis
4. 启动 Celery worker
5. 启动飞书长连接进程
6. 如需健康检查，再启动 FastAPI

示例命令：

```bash
celery -A app.queue.celery_app.celery_app worker -l info
python -m app.feishu.ws_runner
python -m uvicorn app.main:app --reload
```

## Docker Compose

如果你希望避开本机 Python / 证书环境干扰，可以直接用 Docker 运行。

1. 准备 `.env`
2. 确认 `.env` 里的 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 已填写
3. 如果业务 HTTP 服务不在 compose 网络里，确认 `BACKEND_BASE_URL` 能从容器访问
4. 启动：

```bash
docker compose up --build
```

默认会启动 4 个服务：

- `redis`
- `app`
- `worker`
- `ws`

说明：

- `app` 提供健康检查，端口是 `8000`
- `worker` 负责 Celery 异步任务
- `ws` 负责飞书长连接收消息
- compose 会自动把 Redis 地址覆盖成容器内的 `redis://redis:6379/...`

查看长连接日志：

```bash
docker compose logs -f ws
```

如果只想单独重启长连接服务：

```bash
docker compose up -d --build ws
```

## Jenkins 部署

如果公司流水线和 `viewer` 项目一样通过 `jenkins-local.sh` 构建并启动单个镜像，可以直接使用：

```bash
./deploy.sh --env dev
./deploy.sh --env prod
```

这个模式下 Docker 镜像入口是 `python -m scripts.prod_run`，会在同一个容器内启动三个进程：

- `api`: FastAPI 健康检查和监控接口
- `worker`: Celery 异步任务消费
- `ws`: 飞书长连接收消息

项目内置了环境配置文件：

- `config/environments/.env.local`
- `config/environments/.env.dev`
- `config/environments/.env.prod`

Jenkins 只需要配置 `APP_ENV` 来选择环境：

```bash
APP_ENV=dev
```

或：

```bash
APP_ENV=prod
```

当前三个环境文件的业务配置先保持一致，Redis 分库为：

- `REDIS_URL`: DB 4
- `CELERY_BROKER_URL`: DB 5
- `CELERY_RESULT_BACKEND`: DB 6

系统环境变量优先级最高，可以覆盖环境文件里的任意配置。本地 `.env` 只用于在未设置系统环境变量时选择默认 `APP_ENV`。

健康检查地址仍是：

```bash
GET /healthz
```

## 监控和日志追踪

项目集成了完整的监控和日志追踪功能：

### 功能特性

- **Trace ID**: 每个请求自动生成唯一trace_id，贯穿整个调用链
- **结构化日志**: 统一日志格式，包含trace_id、用户ID、会话ID等关键信息
- **对话记录**: 自动存储用户对话和Agent响应，支持查询和分析
- **工具调用监控**: 记录工具调用性能和结果
- **HTTP API**: 提供RESTful接口查询监控数据

### 监控API

启动应用后，可通过以下接口查询监控数据：

```bash
# 根据trace_id查询对话记录
GET /monitoring/conversations/{trace_id}

# 查询用户对话记录
GET /monitoring/users/{user_id}/conversations?limit=50&offset=0

# 搜索对话记录
GET /monitoring/conversations/search?user_id=xxx&session_id=xxx&start_time=2024-01-01T00:00:00
```

### 命令行工具

使用 `monitor.py` 脚本快速查询监控数据：

```bash
# 查询特定对话记录
python monitor.py get-conversation tr-abc123...

# 查询用户对话历史
python monitor.py user-conversations ou_xxx --limit 10

# 搜索最近24小时的对话
python monitor.py search --user-id ou_xxx --hours 24
```

### 日志格式

所有监控日志采用JSON格式，包含以下字段：

```json
{
  "event": "conversation|tool_call",
  "trace_id": "tr-abc123...",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "user_id": "ou_xxx",
  "session_id": "oc_xxx",
  // ... 其他业务字段
}
```

## 下一步建议

1. 先把真实业务后端的 HTTP contract 定死
2. 然后给 `BackendClient` 增加鉴权、trace_id、重试和超时分类
3. 最后再补写操作确认机制与更完整的集成测试