# Function_Generating_Agent_V2.1

**Repository Path**: wangding1044/function_-generating_-agent_-v2.1

## Basic Information

- **Project Name**: Function_Generating_Agent_V2.1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Function Generating Agent V2.0

基于 DeepAgents 的**功能生成智能体**，通过自然语言描述自动生成统计页面（SQL 查询、数据预览、JSON 页面协议输出）。

## 项目概述

用户通过自然语言描述统计分析需求，系统自动完成：

1. **要素提取** — 从自然语言中抽取时间、空间、主题、组件等条件
2. **主题分流** — 判断进入"自由主题"或"内置模板主题"路径
3. **展示内容确认** — 确定组件、统计指标、图表类型等
4. **SQL 生成与预览** — 生成 SQL 并展示数据预览
5. **JSON 协议构建** — 输出前端可渲染的页面协议

完整设计文档见 [`docs/design/功能生成智能体详细设计-v2.0.md`](docs/design/功能生成智能体详细设计-v2.0.md)。

## 技术栈

| 类别 | 技术 |
|---|---|
| 智能体框架 | [deepagents](https://github.com/deepagents/deepagents) (基于 LangGraph) |
| 大模型接入 | LangChain OpenAI 兼容接口（默认通义千问） |
| 状态持久化 | SQLite Checkpoint（`langgraph-checkpoint-sqlite`） |
| 配置管理 | python-dotenv |
| 工具定义 | LangChain Tools |
| Python 版本 | >= 3.12 |

## 项目结构

```text
Function_Generating_Agent_V2.1/
├── main.py                                 # FastAPI/uvicorn 启动入口
├── run_with_cli.py                         # CLI 对话入口（流式对话 + HITL 审批）
├── cli_hitl.py                             # HITL 审批请求格式化与审批输入解析
├── api/
│   ├── app.py                              # FastAPI 应用装配与 `api` 命令入口
│   ├── adapters/                           # Agent 事件、SSE、旁白文案适配
│   ├── routes/                             # HTTP 路由（功能生成、运行时查询）
│   └── schemas/                            # API 请求/响应模型
├── config/
│   ├── settings.py                         # 环境变量与运行配置读取
│   └── SYSTEM_PROMPT.md                    # 系统提示词模板
├── service/
│   ├── agents/
│   │   └── react_agent.py                  # 核心智能体定义与装配
│   ├── middleware/
│   │   └── agent_logging_middleware.py     # 智能体日志中间件
│   ├── models/
│   │   └── query_artifact_models.py        # 查询产物领域模型
│   ├── services/                           # SQL 重建、时间槽位、产物存取等业务服务
│   ├── streaming/
│   │   └── custom_events.py                # 自定义流式事件封装
│   └── tools/                              # Catalog / Context / SQL / Biz 等工具
├── skills/
│   └── function-page-generation/           # 页面生成功能 Skill、参考资料与校验脚本
├── utils/
│   ├── ask_number_sdk.py                   # 察言问数服务 SDK 封装
│   ├── date_util.py                        # 日期时间工具
│   ├── deepagent_util.py                   # DeepAgents 相关辅助方法
│   ├── id_util.py                          # ID 生成工具
│   └── log.py                              # 日志初始化与公共日志能力
├── tests/                                  # unittest 测试目录
├── data/
│   ├── component-foundation/               # 组件基础数据
│   └── theme_library/                      # 主题库数据
├── docs/
│   ├── component-foundation/               # 组件基础 Skill 与参考文档
│   ├── design/                             # 设计方案、规则说明、演进文档
│   └── 备份/                               # 历史 Skill 备份
├── logs/                                   # 运行时日志目录
├── bin/                                    # 辅助脚本目录
├── pyproject.toml                          # 项目依赖、打包与脚本入口配置
├── uv.lock                                 # uv 锁定依赖
├── .env                                    # 本地环境变量（勿提交敏感信息）
├── .flake8                                 # 代码风格配置
├── .gitignore
├── .python-version                         # Python 3.12
├── AGENTS.md                               # 仓库内协作与执行规范
└── README.md
```

## 核心架构

### 智能体

`service/agents/react_agent.py` 是项目核心，基于 **deepagents** 创建：

```
用户输入
    ↓
ReAct 智能体（deepagents）
    ├─→ Tools（确定性动作）
    │     └─ current_time（自定义工具）
    │     └─ deepagents 内置工具（文件读写、执行命令等，受 HITL 控制）
    ├─→ Skills（业务推理规则）
    │     └─ langgraph-docs
    │     └─ arxiv-search
    │     └─ 扩展 Skill
    └─→ Checkpointer（SQLite 持久化）
```

### HITL（人工介入）

`cli_hitl.py` 实现了 **Human-in-the-Loop** 审批流程，智能体在执行 `write_file` 和 `edit_file` 操作时会中断，等待用户在 CLI 中：

- **`approve`** — 直接批准执行
- **`reject 原因`** — 拒绝执行并附上原因
- **`edit {"args": ...}`** — 修改参数后执行

### 状态持久化

使用 SQLite Checkpoint 保存每个 `thread_id` 的对话状态，支持断点恢复和多轮对话。

## 环境配置

### 1. 安装依赖

推荐使用 uv：

```bash
uv sync
```

或 pip：

```bash
pip install -e .
```

### 2. 配置 `.env`

直接在项目根目录配置 `.env`。

关键配置项：

| 变量 | 说明 | 示例 |
|---|---|---|
| `MODEL_SERVICE_URL` | 大模型 API 地址 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `MODEL_SERVICE_API_KEY` | 大模型 API Key | `sk-xxxxxxxx` |
| `DEFAULT_MODEL` | 默认模型名称 | `qwen3.5-397b-a17b` |
| `MODEL_PROVIDER` | 模型供应商（OpenAI 兼容） | `openai` |
| `MODEL_MAX_INPUT_TOKENS` | 最大输入 Token | `32000` |
| `CHECKPOINT_SQLITE_PATH` | SQLite 持久化路径 | `./data/langgraph_checkpoints.sqlite` |
| `ASK_NUMBER_BASE_URL` | 察言问数服务地址 | `http://127.0.0.1:8080` |
| `ASK_NUMBER_USER_ID` | SQL 生成默认用户 ID | `admin` |
| `ASK_NUMBER_AUTHORIZATION` | 察言问数鉴权头 | `Bearer xxx` |
| `DATA_PREVIEW_SERVICE_URL` | 数据预览服务地址 | `http://127.0.0.1:9000/query` |
| `DEFAULT_USER_ID` | API 默认用户 ID | `anonymous` |
| `PATH` | 系统 PATH（Windows 用户必须修改） | 见下方说明 |

#### PATH 配置（重要）

`.env` 中的 `PATH` 用于 `LocalShellBackend` 查找系统命令（node、python 等）。

- **macOS/Linux 用户**：通常无需修改，除非有特殊路径需求
- **Windows 用户**：必须替换为你的 Windows 系统 PATH

在 PowerShell 中获取：

```powershell
$env:PATH
```

将输出的一长串路径替换 `.env` 中的 `PATH=` 行。

### 3. 运行时数据目录

确保 `data/` 目录存在（SQLite Checkpoint 文件会创建在此）：

```bash
mkdir -p data
```

## 运行

### 命令行对话模式

```bash
uv run python main.py
```

启动后会输出一个 `thread_id`，此后所有对话都在同一会话中（状态由 SQLite 持久化）。

交互示例：

```
会话已启动，thread_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
输入内容开始对话，输入 exit / quit / q / :q 退出。

你：帮我生成一个页面，展示最近7天各省份的入境人数统计

助手：正在分析您的需求...
[智能体输出省略]
[若涉及文件写入，触发 HITL 审批]
等待人工审批：
1. 工具：write_file
   参数：{"file_path": "...", "content": "..."}
   可选操作：approve, reject, edit
输入 approve 直接批准。
输入 reject 原因 拒绝执行。
输入 edit {"command":"..."} 修改后执行（仅支持单个工具调用）。

审批：approve
助手：[继续执行...]
```

### 退出命令

`exit`、`quit`、`q`、`:q` 均可退出。

### API 服务模式

启动 FastAPI 服务：

```bash
uv run api
```

启动后可访问：

- Swagger UI：`http://127.0.0.1:5072/docs`
- ReDoc：`http://127.0.0.1:5072/redoc`
- 健康检查：`http://127.0.0.1:5072/health`

## API 接口文档

### 接口概览

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/health` | 健康检查 |
| `POST` | `/api/function-generation/invoke` | 非流式功能生成 |
| `POST` | `/api/function-generation/stream` | 流式功能生成（SSE） |
| `POST` | `/api/function-page/query` | 按 `artifact_id` 获取运行时 SQL |

### 通用请求体

两个功能生成接口都使用同一套请求结构：

```json
{
  "request_id": "req-001",
  "session_id": "session-001",
  "source": "web-console",
  "request_time": "2026-04-20T10:00:00+08:00",
  "request_type": "execute",
  "input_payload": {
    "text_content": "帮我生成一个页面，展示最近7天各省入境人数统计",
    "biz_params": {
      "scene": "page_generation",
      "user_id": "u-1001"
    }
  },
  "session_context": {
    "context_version": 1,
    "thread_id": "thread-001",
    "workflow_state": {}
  },
  "resource_list": [],
  "extra_params": {
    "user_id": "u-1001"
  }
}
```

字段说明：

- `input_payload.text_content`：用户自然语言输入，必填
- `request_type`：支持 `execute`、`interaction`
- `session_context.thread_id`：多轮会话线程 ID；为空时回退使用 `session_id`
- `extra_params.user_id`：优先级最高的用户 ID，其次是 `input_payload.biz_params.user_id`，最后回退到 `DEFAULT_USER_ID`

### 1. 健康检查

请求：

```http
GET /health
```

响应示例：

```json
{
  "status": "ok",
  "service": "function-generating-agent-v2"
}
```

### 2. 非流式功能生成

请求：

```http
POST /api/function-generation/invoke
Content-Type: application/json
```

响应示例：

```json
{
  "request_id": "req-001",
  "session_id": "session-001",
  "current_stage": "PREVIEWING",
  "interaction_type": null,
  "reply_text": "我已经为你完成页面协议组装。",
  "data": {
    "page_schema": {
      "pageId": "feat-10001",
      "pageTitle": "最近7天各省入境人数统计",
      "layout": "grid",
      "components": [],
      "dataSources": {}
    },
    "generated_sql_map": {},
    "sql_results": [],
    "preview_results": [],
    "save_results": [],
    "errors": [],
    "meta": {
      "message_count": 8
    }
  },
  "session_context": {
    "context_version": 1,
    "thread_id": "thread-001",
    "workflow_state": {}
  }
}
```

说明：

- `reply_text`：提取自最终 AI 文本回复
- `data.page_schema`：最终页面渲染 JSON
- `data.generated_sql_map`：按 `component_id -> sql` 聚合的 SQL 映射
- `data.page_schema.dataSources[*].sql` 返回查询工件 ID，不返回真实 SQL
- 当前默认会把真实 SQL 与运行时元数据落到 `data/query_artifacts/<artifact_id>.json`
- 当 `AIHUB_DB_ENABLED=true` 时，还会额外写入 MySQL 表 `aihub_t_quick_function_artifact`

### 3. 流式功能生成（SSE）

请求：

```http
POST /api/function-generation/stream
Content-Type: application/json
Accept: text/event-stream
```

返回格式为标准 SSE，每帧都是：

```text
data: {"request_id":"req-001","session_id":"session-001","stream_id":"...","event_seq":1,"event_time":1745114400000,"event_type":"progress","is_final":false,"event_content":{...}}
```

事件类型说明：

| `event_type` | 用途 | 说明 |
|---|---|---|
| `reasoning_delta` | 轻量思考/阶段说明 | 当前正在做什么，适合前端实时展示 |
| `progress` | 内部进度提示 | 当前执行步骤，可由 API 转换后对外输出 |
| `content_delta` | 文本增量 | 只承载自然语言输出 |
| `data_content` | 结构化数据 | 页面 JSON、SQL 结果、预览结果、保存结果 |
| `context_snapshot` | 会话快照 | 当前 `thread_id` 等轻量上下文 |
| `complete` | 正常结束 | 最后一帧 |
| `error` | 异常结束/错误提示 | 包括 API 模式不支持的 HITL 中断 |

重要约定：

- 前端若需要实时展示“思考中”状态，优先消费 `reasoning_delta`
- `content_delta` 只放自然语言文本，不放页面渲染 JSON
- 前端需要渲染页面时，请从 `data_content.event_content.data` 中读取
- `generate_page_schema` 工具输出的页面协议固定通过 `data_content` 发送，`data_type=page_schema`

`data_content` 示例：

```json
{
  "request_id": "req-001",
  "session_id": "session-001",
  "stream_id": "stream-001",
  "event_seq": 5,
  "event_time": 1745114405000,
  "event_type": "data_content",
  "is_final": false,
  "event_content": {
    "data_type": "page_schema",
    "data": {
      "pageId": "feat-10001",
      "pageTitle": "最近7天各省入境人数统计",
      "layout": "grid",
      "components": [],
      "dataSources": {}
    },
    "data_desc": "页面渲染 JSON",
    "replace": true
  }
}
```

其他常见 `data_type`：

- `page_schema`
- `sql_result`
- `preview_result`
- `save_result`

如果工具没有显式发出 `data_content`，API 层会在流结束时尝试从最终状态兜底提取结构化数据。

### 4. artifact_id 运行时查询

页面协议中的 `dataSources[*].sql` 固定为工件 ID，可通过该接口拿到当前运行时 SQL。

接口约定说明：

- 必填字段：`page_id`、`queries[].artifact_id`
- 可选字段：`queries`、`queries[].form_values`、`queries[].local_values`
- 路由显式处理的业务错误会返回统一结构：
  - `ValueError` -> `400`
  - `query_runtime_service` 未注入 -> `500`
- 请求体验证失败仍保持 FastAPI 默认 `422`

当前 V2.0 运行时行为补充：

- 当某个 `artifact_id` 没有传入任何非空查询条件时，当前会直接返回工件中的 `original_sql`，对应 `sql_mode=original`
- 当查询条件无法走 `rebuild`，但工件中存在 `runtime_field_specs` 和 `text_content` 时，会 fallback 到 `generate_json`
- 当两条路径都不可用时，当前会返回 `400`

artifact 持久化说明：

- `generate_page_schema` 会生成并持久化查询工件
- 默认持久化位置为本地文件：`data/query_artifacts/<artifact_id>.json`
- 当 `AIHUB_DB_ENABLED=true` 时，会同时写入 MySQL 表 `aihub_t_quick_function_artifact`
- 当前运行时查询读取顺序为：内存缓存 -> 本地 JSON 文件 -> MySQL 表

请求：

```http
POST /api/function-page/query
Content-Type: application/json
```

请求示例：

```json
{
  "page_id": "feat-10001",
  "queries": [
    {
      "artifact_id": "2046227653878484993",
      "form_values": {
        "date_range": {
          "start_date": "2026-04-01",
          "end_date": "2026-04-07"
        }
      },
      "local_values": {}
    }
  ]
}
```

响应示例：

```json
{
  "success": true,
  "data": {
    "page_id": "feat-10001",
    "results": {
      "2046227653878484993": {
        "artifact_id": "2046227653878484993",
        "sql_mode": "rebuild",
        "sql": "SELECT ..."
      }
    }
  },
  "error": null
}
```

空条件示例：

```json
{
  "success": true,
  "data": {
    "page_id": "feat-10001",
    "results": {
      "2046227653878484993": {
        "artifact_id": "2046227653878484993",
        "sql_mode": "original",
        "sql": "SELECT ..."
      }
    }
  },
  "error": null
}
```

### curl 调用示例

非流式：

```bash
curl -X POST "http://127.0.0.1:5072/api/function-generation/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-001",
    "session_id": "session-001",
    "source": "curl",
    "request_time": "2026-04-20T10:00:00+08:00",
    "request_type": "execute",
    "input_payload": {
      "text_content": "帮我生成一个页面，展示最近7天各省入境人数统计",
      "biz_params": {}
    },
    "session_context": null,
    "resource_list": [],
    "extra_params": {}
  }'
```

流式：

```bash
curl -N -X POST "http://127.0.0.1:5072/api/function-generation/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "request_id": "req-002",
    "session_id": "session-002",
    "source": "curl",
    "request_time": "2026-04-20T10:00:00+08:00",
    "request_type": "execute",
    "input_payload": {
      "text_content": "帮我生成一个页面，展示最近7天各省入境人数统计",
      "biz_params": {}
    },
    "session_context": null,
    "resource_list": [],
    "extra_params": {}
  }'
```

## 扩展

### 添加自定义 Tool

在 `service/tools/custom_tool.py` 中使用 LangChain `@tool` 装饰器定义，然后在 `service/agents/react_agent.py` 的 `create_deep_agent(..., tools=[...])` 中注册即可。

### 添加自定义 Skill

在 `skills/` 下新建目录，放入 `SKILL.md` 工作说明书（参考 `skills/arxiv-search/SKILL.md` 格式），deepagents 会自动扫描并加载。

### 修改 HITL 行为

在 `service/agents/react_agent.py` 的 `interrupt_on` 参数中配置：

```python
interrupt_on={
    "write_file": True,   # 写文件需要审批
    "read_file": False,   # 读文件不需要审批
    "edit_file": True,    # 编辑文件需要审批
    "execute": False,     # 执行命令不需要审批
},
```

## 依赖说明

| 依赖 | 用途 |
|---|---|
| `deepagents>=0.5.2` | 智能体框架（封装 LangGraph + ReAct + Skills） |
| `langchain-openai>=1.1.13` | OpenAI 兼容模型接入 |
| `langgraph-checkpoint-sqlite>=3.0.3` | SQLite 状态持久化 |
| `dotenv>=0.9.9` | .env 配置读取 |
| `pydantic` | 数据校验（deepagents 自带） |
| `langgraph` | 图结构智能体（deepagents 自带） |