vent_agent_2.0

deep_agent 2.0

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

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

1. 本地运行

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 配置即可本地运行：

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

.venv/bin/python main.py

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

未配置 DB_DIALECT 时默认是 MySQL。使用 MySQL 时设为 mysql 并填写 .env.example 中的 DB_*；数据库不存在时需账户有建库权限，或提前创建数据库。

2. Debug / 调试

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

# 详细日志，前台运行
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 节的依赖安装后执行：

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

输出到 release/dist/：

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 上传到服务器的同一目录，进入该目录执行：

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 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. 服务器运行与排查

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

~/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 日志时，先停止后台服务，再执行：

~/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 停止服务；托管配置见 发布说明。

6. 升级与回退

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

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

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

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

7. 业务扩展与开发验证

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

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

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

• 发布说明：目录、升级命令、systemd、依赖更新。
• 开发参考：API、SSE、工具/技能扩展和框架约束。
• .env.example：配置项说明。

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