# ZK Data Agent

ZK Data Agent 是面向中控数据开发流程的 Agent 服务。当前仓库包含：

- Python 后端：负责 Agent loop、工具调用、会话持久化和数据开发工具。
- Next.js 前端：提供 Web UI、会话管理、工具调用展示和数据开发交互入口。
- Skill / Tools：承载产品定义到数据生成、线上数据挖掘等数据开发链路。

## 快速部署

### 从 Git 一键部署

适合首次部署，也适合后续更新：

```bash
curl -fsSL "https://git.n.xiaomi.com/wuyang6/zk-data-agent/-/raw/main/scripts/install-from-git.sh" | bash
```

指定部署目录或分支：

```bash
curl -fsSL "https://git.n.xiaomi.com/wuyang6/zk-data-agent/-/raw/main/scripts/install-from-git.sh" | \
  bash -s -- --dir "$HOME/zk-data-agent" --branch main
```

这个入口脚本会自动完成：

- 目标目录不存在时执行 `git clone`
- 目标目录已存在时执行 `git fetch` / `git pull --ff-only`
- 进入仓库后执行 `bash scripts/deploy-ubuntu.sh`

### 仓库内一键部署/更新

如果已经在仓库目录中：

```bash
bash scripts/deploy-ubuntu.sh
```

部署指定分支：

```bash
bash scripts/deploy-ubuntu.sh main
```

强制覆盖服务器工作区：

```bash
bash scripts/deploy-ubuntu.sh main --force
```

## 部署配置

首次执行 `scripts/deploy-ubuntu.sh` 时，如果仓库根目录不存在 `.env.deploy`，脚本会交互式提示输入：

- `OPENAI_API_KEY`
- `OPENAI_BASE_URL`
- `OPENAI_MODEL`
- 后端监听地址和端口
- 前端监听地址和端口

配置会写入：

```text
.env.deploy
```

该文件包含敏感信息，只保存在部署机器本地，权限会设置为 `600`，并且已被 `.gitignore` 忽略，不会提交到 git。

如需修改模型或 key：

```bash
vim .env.deploy
```

可参考示例：

```bash
cp .env.deploy.example .env.deploy
```

## 运行方式

部署脚本会安装两个 systemd 服务：

```bash
zk-data-agent-backend
zk-data-agent-frontend
```

查看状态：

```bash
sudo systemctl status zk-data-agent-backend
sudo systemctl status zk-data-agent-frontend
```

查看日志：

```bash
sudo journalctl -u zk-data-agent-backend -f
sudo journalctl -u zk-data-agent-frontend -f
```

重启服务：

```bash
sudo systemctl restart zk-data-agent-backend zk-data-agent-frontend
```

停止服务：

```bash
sudo systemctl stop zk-data-agent-backend zk-data-agent-frontend
```

## 本地开发启动

本地调试可以使用：

```bash
bash scripts/start-webui.sh
```

默认端口：

- 前端：`http://127.0.0.1:3000`
- 后端：`http://127.0.0.1:8765`

`scripts/start-webui.sh` 会优先读取本机 `.env.deploy`，也可以直接使用当前 shell 中的环境变量。

## 环境要求

Ubuntu 部署建议准备：

- `git`
- `bash`
- `curl`
- `sudo`
- `systemd`
- `pyenv`
- Python `3.10.14`
- Node.js `20` 或 `22`
- `npm`

Python 后端依赖由部署脚本安装到项目根目录 `.venv`。

前端依赖由部署脚本在 `frontend/app` 下执行 `npm ci` 安装，并执行 `npm run build`。

## 目录说明

```text
backend/              FastAPI Web 后端
frontend/app/         Next.js 前端
src/                  Agent runtime、tools、skills
scripts/              本地启动、部署、systemd 启动脚本
deploy/systemd/       systemd service 模板
.port_sessions/       本地运行数据，禁止提交
.env.deploy           本机私有部署配置，禁止提交
```

## 注意事项

- 不要把 `OPENAI_API_KEY` 写入可提交文件。
- `.env.deploy`、`.venv`、`.port_sessions` 都是本机文件，不进入 git。
- 服务器更新优先使用 `bash scripts/deploy-ubuntu.sh`，不要手工分散执行依赖安装和服务重启。
- 生产/长期运行使用 systemd 服务；`scripts/start-webui.sh` 只用于本地调试。