# deep_agent 2.0

基于 deepagents 的 Agent 服务，提供对话、工具调用、人工审批、会话持久化和定时任务；主接口为 `POST /api/chat`（SSE）。

支持多业务智能体注册及按名称独立执行。当前启用 `main_fan`（矿井主通风机资料核验与初步研判），
主协调智能体保留综合交互与委派。陕西局网关由对方运行，只负责 JSON 取数转发和下载鉴权；
研判结果按 `judgment.resultCode/result/reason/evidenceLink` 格式推送到独立结果平台，两套地址和凭证分别配置。
默认不连接外部服务。开发和本地双平台联调见[业务智能体说明](docs/BUSINESS_AGENTS.md)。

独立接入的算法集中放在 [`algorithms/`](algorithms/README.md)。已提供
`POST /api/algorithms/characteristic-curve-recognition`：上传图表图片，返回网格、坐标轴和曲线模型，
或下载完整结果包。调用方式见[特性曲线识别 API](algorithms/characteristic_curve_recognition/README.md)。
批量处理使用 `POST /api/algorithms/characteristic-curve-recognition/batches`，
返回任务 ID 后后台并行识别，支持查询逐图进度及下载整批结果；默认并行 2 张。

**环境：Python 3.12，独立虚拟环境。** 以下源码命令在项目根目录执行，适用于 macOS / Linux。Linux 部署要求见第 4 节。

## 1. 本地运行

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r release/requirements.lock
[ -f .env ] || cp .env.example .env
```

编辑项目根目录 `.env`，填写模型配置，并添加 SQLite 配置即可本地运行：

```dotenv
OPENAI_API_KEY=你的密钥
OPENAI_BASE_URL=https://api.deepseek.com
DEEPAGENT_MODEL=deepseek-flash
DB_DIALECT=sqlite
DB_SQLITE_PATH=data/vent_agent.sqlite
CHECKPOINTER=sqlite
CHECKPOINT_DB_PATH=data/checkpoints.sqlite
HOST=127.0.0.1
PORT=8080
```

```bash
.venv/bin/python main.py
```

浏览器打开 <http://127.0.0.1:8080>；健康检查为 <http://127.0.0.1:8080/health>。前台按 `Ctrl+C` 停止。

网页已改为 Vue 3 工作台，包含“智能体对话”和“智能体测试”。主通风机测试页以测定报告PDF、两台风机开停曲线、切换前后风量为三项输入，支持设置切换间隔和前后风量，也可分别上传时序JSON。主通风机默认由 Skill 驱动自主探索，Agent 自行编写文档解析、计算及报告生成代码，在沙箱执行并根据输出调整计划；仅保留网关取数与准备/执行/提交基础设施，不再调用固定业务计算器或七阶段。每次执行创建新会话和workspace，不继承历史记忆；结果提供JSON、报告及Excel在线预览。现有编译资源随项目提供，启动Python服务即可使用。修改前端时，在 `frontend/` 执行 `npm ci`、`npm run build`；开发热更新使用 `npm run dev`（代理到8080）。详细说明见[测试工作台](docs/TEST_LAB.md)和[主通风机自主探索](docs/MAIN_FAN.md)。

**默认使用 SQLite**，业务数据位于 `data/vent_agent.sqlite`，图状态位于 `data/checkpoints.sqlite`。
旧 MySQL 部署仍可显式设 `DB_DIALECT=mysql`；改用 SQLite 不会自动迁移原 MySQL 数据。

## 2. Debug / 调试

项目没有单独的 `DEBUG=true` 开关。使用开发数据库，在源码目录调试：

```bash
# 详细日志，前台运行
DEEP_AGENT_ENV_PRIORITY=process LOG_LEVEL=DEBUG .venv/bin/python main.py

# Python 自带断点调试器
DEEP_AGENT_ENV_PRIORITY=process LOG_LEVEL=DEBUG .venv/bin/python -m pdb main.py
```

进入 pdb 后，用 `b 文件路径:行号` 设置断点，`c` 继续、`n` 单步、`p 变量名` 查看变量、`q` 退出。

使用 IDE 时，解释器选择 `.venv/bin/python`，入口选择 `main.py`，工作目录选择项目根目录；环境变量设置 `DEEP_AGENT_ENV_PRIORITY=process`、`LOG_LEVEL=DEBUG`，然后在源码中打断点。

- 默认 `.env` 优先；`DEEP_AGENT_ENV_PRIORITY=process` 才让命令行环境变量覆盖它。
- 保持单进程，不启用 `--reload` 或多 worker；修改代码后手动重启。
- 已安装版本的前台排查方式见第 5 节；修改源码请回到开发目录，发布包启动时会校验文件完整性。

## 3. 打包

完成第 1 节的依赖安装后执行：

```bash
.venv/bin/python -B release/build.py --version 2.0.0
```

输出到 `release/dist/`：

```text
vent-agent-2.0.0-linux.tar.gz
vent-agent-2.0.0-linux.tar.gz.sha256
```

- 不传 `--version` 时读取根目录 `VERSION`；同版本产物不覆盖，再次发布请使用新版本号，例如 `2.0.1`。
- 打包当前工作区，包含未提交修改；自动跑离线测试和自检，失败不出包。
- 包含源码、静态资源、文档和固定依赖清单；不包含 `.env`、用户数据、日志和本机虚拟环境。
- 包不绑定 ARM；安装时下载对应架构依赖。已实测 Linux ARM64，x86_64 尚未实测。

## 4. 部署到 Linux

服务器需要 **Linux 5.3+、glibc、Python 3.12（含 venv/pip）、Bash 和下载依赖的网络**。以普通用户安装到 `$HOME/vent-agent` 为例：

将压缩包和 `.sha256` 上传到服务器的同一目录，进入该目录执行：

```bash
sha256sum -c vent-agent-2.0.0-linux.tar.gz.sha256
tar -xzf vent-agent-2.0.0-linux.tar.gz
cd vent-agent-2.0.0-linux
python3.12 -B release/verify.py
bash release/install.sh --prefix "$HOME/vent-agent"
```

编辑自动生成的 **`$HOME/vent-agent/shared/.env`**，填写模型密钥和数据库配置；SQLite 可沿用第 1 节的配置。需要远程访问时将 `HOST` 设为 `0.0.0.0`，开放配置的端口。

配置完成后，在解压目录执行：

```bash
bash release/service.sh activate 2.0.0 --prefix "$HOME/vent-agent"
bash release/service.sh start --prefix "$HOME/vent-agent"
bash release/service.sh status --prefix "$HOME/vent-agent"
```

访问 `http://服务器地址:8080`。更换安装路径时，将所有 `--prefix` 和后续路径一起替换；例如 `/opt/vent-agent` 对应 `/opt/vent-agent/shared/.env`。

## 5. 服务器运行与排查

安装后，下面的脚本会自动识别部署目录：

```bash
~/vent-agent/current/release/service.sh start    # 后台启动并等待健康检查
~/vent-agent/current/release/service.sh status   # 查看状态、PID 和版本
~/vent-agent/current/release/service.sh logs     # 跟踪日志，Ctrl+C 退出查看
~/vent-agent/current/release/service.sh stop     # 停止服务
```

修改 `shared/.env` 后执行 `stop`、`start` 重启。后台日志保存在 `shared/logs/server.log`。

需要前台查看 DEBUG 日志时，先停止后台服务，再执行：

```bash
~/vent-agent/current/release/service.sh stop
DEEP_AGENT_ENV_PRIORITY=process LOG_LEVEL=DEBUG ~/vent-agent/current/release/service.sh run
```

`run` 在前台运行，按 `Ctrl+C` 停止。systemd 托管时先用 `systemctl stop vent-agent` 停止服务；托管配置见 [发布说明](release/README.md#systemd-托管)。

## 6. 升级与回退

升级顺序：**安装新版本 → 停旧服务 → 备份数据 → activate 新版本 → 启动并检查**。

新版本安装到 `releases/<版本>/`，旧版本保留；`current` 指向当前版本，配置和用户数据共用 `shared/`。安装不会覆盖已有版本或共享配置。

**目前没有自动的数据迁移、兼容性检查或备份。** 回退只切换代码和依赖，不回滚数据库或 Agent checkpoint；结构不兼容时不能直接切回旧版。完整命令见 [升级与回退](release/README.md#升级与回退)。

日志默认使用 `INFO` + `text`；设置 `LOG_FORMAT=json` 可输出结构化日志。请求与任务通过 `trace_id` 关联，任务还带 `session_id`、`run_id`、状态和耗时。健康检查、静态资源成功请求及并发位细节在 `DEBUG` 查看。配置与排查示例见 [日志说明](docs/DEVELOPMENT.md#日志与排查)。

## 7. 业务扩展与开发验证

聊天、定时任务和批处理共用 `runtime/` 执行层；HTTP 层负责 SSE 编码。独立脚本使用 `RuntimeEnvironment` 自动初始化和清理资源，默认不启动调度器。调用方式见 [执行层与入口](docs/DEVELOPMENT.md#执行层与入口)。

新增业务时，在 `extensions/<业务名>/extension.py` 编写 `setup(registry)`，统一声明工具、子 Agent、提示词、审批、共享服务和中间件。启动自动发现并校验，无需修改工厂函数；修改后重启生效。RAG/记忆接入可参考默认关闭的 `extensions/context_demo/` 离线示例。完整步骤见 [扩展方式](docs/DEVELOPMENT.md#扩展方式)。

```bash
.venv/bin/python -m pytest            # 离线测试，使用临时数据库
.venv/bin/python scripts/selfcheck.py # 结构自检，会按当前配置连接数据库并建表
```

- [发布说明](release/README.md)：目录、升级命令、systemd、依赖更新。
- [开发参考](docs/DEVELOPMENT.md)：API、SSE、工具/技能扩展和框架约束。
- [.env.example](.env.example)：配置项说明。

当前服务为单进程，尚无真实用户鉴权，适合开发和内网使用。