# ZK Data Agent

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

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

## 快速部署

### 从 Git 一键部署

适合首次部署。首次安装会默认初始化 Ubuntu 系统依赖，必要时请求 sudo；应用本身仍部署在用户目录。

```bash
git clone git@git.n.xiaomi.com:wuyang6/zk-data-agent.git "$HOME/zk-data-agent" || true
bash "$HOME/zk-data-agent/scripts/install-from-git.sh"
```

后续更新不需要安装系统依赖，可以使用：

```bash
bash "$HOME/zk-data-agent/scripts/install-from-git.sh"
```

默认部署目录是 `$HOME/zk-data-agent`，默认分支是 `main`。修改部署目录或分支时再加变量：

```bash
git clone git@git.n.xiaomi.com:wuyang6/zk-data-agent.git "$HOME/zk-data-agent-test" || true
APP_DIR="$HOME/zk-data-agent-test" bash "$HOME/zk-data-agent-test/scripts/install-from-git.sh"
```

这个命令会自动完成：

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

说明：仓库是私有仓库，`curl | bash` 拉 raw 文件时容易拿到登录页 HTML；因此推荐直接走 SSH git 权限。

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

如果已经在仓库目录中，日常更新直接执行：

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

已完成首次部署后，如果只是普通代码更新，可以使用快速更新：

```bash
bash scripts/update-server-fast.sh
```

快速更新只会拉取代码、构建前端并重启用户服务；如果本次改动包含依赖、systemd 模板或部署脚本变化，请使用 `scripts/deploy-ubuntu.sh`。

如果是全新 Ubuntu 机器，首次安装可以让脚本顺手安装系统依赖：

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

`--bootstrap-system` 会使用 `sudo apt-get` 安装 Python 编译依赖、`git`、`curl` 等系统包；应用代码、`.venv`、前端依赖、运行数据和 systemd 用户服务仍然都在当前用户目录下。

部署指定分支：

```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 服务，不需要 sudo：

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

查看状态：

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

查看日志：

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

重启服务：

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

停止服务：

```bash
systemctl --user 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`
- `systemd`
- `pyenv`
- Python `3.10.14`
- Node.js `20` 或 `22`
- `npm`

如果机器缺少 Python 编译依赖，首次执行时可加 `--bootstrap-system`，脚本会请求 sudo 安装系统包。日常部署和更新不需要 sudo。

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

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

部署脚本会把当前 shell 中可用的 `npm` 路径写入 `.env.deploy`，避免用户级 systemd 服务启动时读取不到 zsh/nvm 环境。

默认部署使用用户级 systemd，不需要 sudo。若机器要求服务在用户退出 SSH 后仍保持运行，可由管理员额外执行：

```bash
loginctl enable-linger <username>
```

## 目录说明

```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` 只用于本地调试。