# chat-bi2

**Repository Path**: ddgetget/chat-bi2

## Basic Information

- **Project Name**: chat-bi2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目使用说明

## 环境准备
- 环境变量统一放在项目根目录 `.env`。
- 所有 Python 命令建议使用 `uv run` 执行。

## 启动服务
- 启动 HTTP 服务（默认 8000 端口）：
  - `bash scripts/http_run.sh -p 8000`
- 或直接使用：
  - `uv run python src/main.py -m http -p 8000`

## HTTP 接口说明

### `POST /run`
- 用途：同步执行一次完整流程，返回 JSON 结果。
- 示例：
```bash
curl -X POST "http://127.0.0.1:8000/run" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "query",
    "session_id": "1",
    "message": "帮我生成查询订单的SQL"
  }'
```

### `POST /stream_run`
- 用途：流式执行，返回 `text/event-stream`（SSE）。
- 示例：
```bash
curl -N -X POST "http://127.0.0.1:8000/stream_run" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "query",
    "session_id": "1",
    "message": "流式生成SQL"
  }'
```

### `POST /node_run/{node_id}`
- 用途：仅执行指定节点（用于节点调试）。
- 示例：
```bash
curl -X POST "http://127.0.0.1:8000/node_run/node_name" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好"
  }'
```

## 命令行模式（local_run.sh）

### flow 模式
- 命令：
  - `bash scripts/local_run.sh -m flow -i '{"text":"帮我生成查询包裹SQL"}'`
- 说明：本地单次执行完整流程，等价于调用 `/run`，会走完整的 Agent 编排（模型 + 工具调用），最终输出 JSON。
- 适用场景：
  - 日常提问与 SQL 生成
  - 验证完整链路行为（检索、工具调用、最终回答）
- 入参建议：
  - 推荐直接用 `{"text":"..."}`（系统会自动规范化）
  - 也支持标准 `content.query.prompt` 协议

### node 模式
- 命令：
  - `bash scripts/local_run.sh -m node -n node_name -i '{"text":"测试节点输入"}'`
- 说明：本地仅执行指定节点，`-n` 必填。等价于调用 `/node_run/{node_id}`。
- 适用场景：
  - 只调试某个节点，不跑完整流程
  - 排查某个节点输入/输出是否符合预期
- `node_name` 怎么来（重点）：
  - `node_name` 就是图中的节点 ID，必须和运行图里节点名完全一致。
  - 当前这个项目（Agent 图）可用节点通常是：
    - `model`
    - `tools`
  - `__start__` 和 `__end__` 是系统边界节点，不建议作为 `node_name` 调试业务逻辑。
- 如何查看当前可用 `node_name`：
```bash
set -a && source .env && set +a && \
PYTHONPATH=src uv run python -c "from agents.agent import build_agent; g=build_agent(); print(sorted(list(g.get_graph().nodes.keys())))"
```
- 运行示例（调试 model 节点）：
```bash
bash scripts/local_run.sh -m node -n model -i '{"text":"帮我生成查询订单SQL"}'
```
- 运行示例（调试 tools 节点）：
```bash
bash scripts/local_run.sh -m node -n tools -i '{"text":"查询包裹相关表结构"}'
```

## 输入协议说明（重要）
- 当前已统一输入规范化：如果传入 `{"text":"..."}`，系统会自动转换为标准 `content.query.prompt` 协议。
- 因此以下两种写法都可用：
  - 简写：`{"text":"..."}`
  - 标准：
    - `{"type":"query","session_id":"1","content":{"query":{"prompt":[{"type":"text","content":{"text":"..."}}]}}}`

## flow 与 node 的区别
- `flow`：执行整条链路（推荐默认使用），结果更接近真实线上行为。
- `node`：只执行单节点（推荐调试时使用），适合定位某个节点内部问题。