wuyang/zk-data-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refresh README for general agent platform

Browse Source
This commit is contained in:
武阳
2026-05-08 21:30:15 +08:00
parent 0dc900126c
commit 323ee23cd6
1 changed files with 508 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+508 -107
View File
@@ -1,67 +1,456 @@
# ZK Data Agent
ZK Data Agent 是面向中控数据开发流程的 Agent 服务。当前仓库包含：
ZK Data Agent 是基于 `claw-code-agent` 改造的团队通用 Agent 工作台。
- Python 后端：负责 Agent loop、工具调用、会话持久化和数据开发工具。
- Next.js 前端：提供 Web UI、会话管理、工具调用展示和数据开发交互入口。
- Skill / Tools：承载产品定义到数据生成、线上数据挖掘等数据开发链路。
它不是一个单点数据工具，也不是只会聊天的 Web UI。这个项目的核心目标是把“通用 Agent 能力”稳定下来：让 Agent 能理解任务、选择 Skill、调用 Tools、读写文件、执行 Python、保留会话、展示工具链路，并把团队反复使用的工作经验沉淀成可维护的能力包。
## 快速部署
数据开发、线上挖掘、ELK 查询、数据工场 SQL 查询，都是已经通过 Skill 和 Tools 落地的子能力。
### 从 Git 一键部署
## 这个项目解决什么
适合首次部署。首次安装会默认初始化 Ubuntu 系统依赖，必要时请求 sudo；应用本身仍部署在用户目录。
团队日常有很多任务不只是“问模型一句话”：
- 要读文件、查日志、跑 SQL、分析线上数据。
- 要生成中间结果、落盘文件、继续追问和修正。
- 要把某类任务的经验固化下来，下一次让 Agent 按同样的方法做。
- 要让用户看到 Agent 做了什么、调用了什么工具、文件生成在哪里。
- 要让多人共用一套平台，而不是每个人本地各跑一份零散脚本。
ZK Data Agent 做的是这层通用底座。业务能力通过 Skill 和 Tools 逐步沉淀。
## 核心设计
### Agent Loop
Agent 每轮对话不是一次性生成文本，而是一个循环：
```text
用户输入
-> 组装系统提示词、Skill 提示词、会话上下文、工具定义
-> 模型决定直接回复或返回 tool_calls
-> 后端执行对应 tool handler
-> 工具结果写入会话
-> 下一轮模型继续判断
-> 直到输出最终回复、等待用户 review 或被取消
```
这个循环让 Agent 可以边观察、边执行、边修正，而不是只能一次性回答。
### Skill
Skill 是“经验层”。它用 `SKILL.md` 描述某类任务应该怎样做、什么时候需要用户确认、可以调用哪些工具、产物应该放在哪里。
项目级 Skill 统一放在：
```text
skills/<skill-name>/SKILL.md
```
Skill 适合承载：
- 工作流程
- 业务边界
- review 门禁
- 工具调用经验
- 输入输出格式约定
- 常见错误和注意事项
Skill 不应该写成大段不可执行代码。稳定、强格式、可复用的能力应该下沉到 Tool。
### Tools
Tools 是“执行层”。工具负责稳定地做事情，例如读写文件、执行 Python、查询 parquet、转换 records、导出 JSONL。
主要位置：
```text
src/agent_tools.py
src/agent_tool_specs/
src/data_agent_records.py
src/data_agent_inputs.py
src/data_agent_router_sessions.py
```
工具适合承载：
- 强格式转换
- 数据校验
- 路径归一
- 线上数据读取
- 账号级 Python 执行环境
- 需要审计和约束的外部调用
原则是：不要长期让 Agent 手写易错脚本来完成稳定流程。能工具化的，尽量工具化。
### 会话工作区
每个用户、每个会话都有独立目录：
```text
.port_sessions/accounts/<account_id>/sessions/<session_id>/
input/ 用户输入文件
scratchpad/ 临时脚本、中间分析、草稿
output/ 最终产物
session.json 会话历史
```
会话工作区是这个项目和普通聊天机器人很不一样的地方。Agent 的产物不是散落在项目根目录，而是跟随当前会话保存，方便回看、下载和继续追问。
### Review 门禁
一些任务不能让 Agent 一步到位，例如：
- 数据生成目标还不清楚。
- 标签边界存在歧义。
- 线上候选需要人工抽样确认。
- 输出格式会影响训练、评测或对外交付。
这类流程要通过 Skill 和 Tool 实现 review 门禁。目标、计划、候选样本、最终导出都应该分阶段展示给用户确认。
### 可观测性
Web UI 会展示：
- 当前模型和上下文状态
- Skill 列表和启用状态
- 工具调用过程
- 总结版思考阶段
- 历史会话
- 当前会话输入/输出文件
- 后台运行和刷新恢复状态
目标是让用户知道 Agent 正在做什么，而不是只看到一个黑盒回复。
## 和 Claude Code 的区别
这个项目继承了 Claude Code 类工具的基本思路：Agent 可以读写文件、执行工具、维护上下文，并围绕一个工作区完成任务。
但当前项目的定位更偏团队内部 Agent 平台：
| 维度 | Claude Code 类工具 | ZK Data Agent |
|------|--------------------|---------------|
| 使用形态 | 个人本地 CLI/IDE 工作流为主 | 团队共享 Web 服务 |
| 任务范围 | 代码开发为核心 | 通用任务底座，数据开发只是能力之一 |
| 能力沉淀 | 个人 prompt、命令、脚本较多 | 项目级 Skill + Tools 统一管理 |
| 文件空间 | 通常围绕当前代码仓库 | 每个用户/会话独立 `input/scratchpad/output` |
| 可观测性 | 终端输出为主 | Web UI 展示工具链路、活动、文件、历史 |
| Python 执行 | 常用 shell 自行管理 | 优先 `python_exec`，走账号级环境和工具约束 |
| 人工确认 | 通常是权限批准或终端交互 | 更强调业务 review：目标、计划、样本、导出 |
| 内部系统 | 需要用户自行接脚本 | 可以通过 Skill/Tools 接 ELK、SQL、线上数据 |
因此，它不是要替代 Claude Code 的个人编码体验，而是把 Agent 变成团队可共享、可扩展、可治理的工作台。
## 能力目录
### 通用 Agent 能力
当前底座已经支持：
- OpenAI 兼容模型调用
- Web UI 多会话管理
- 模型选择
- Skill 发现和会话级启用
- 工具调用展示
- 文件输入和会话产物管理
- 后台 run 状态和刷新恢复
- 总结版思考过程展示
- Python 执行和包安装工具
- 用户级 systemd 部署
### 数据开发能力
Skill：`product-data`
适用于从产品定义、标签规则、手写边界或示例 query 生成数据集。
典型流程：
```text
输入定义/规则/样例
-> 抽取 generation goal
-> 用户 review
-> 生成 generation plan
-> 用户确认数量、标签、边界、路径
-> 生成 dataset draft text
-> 转换为 canonical records
-> 校验
-> 导出 records.jsonl
```
默认最终产物：
```text
当前会话/output/records.jsonl
```
### 线上挖掘能力
Skill：`online-mining`
适用于从线上 router session 中按 query 特征、domain、设备、日期等条件挖掘候选样本。
典型流程：
```text
需求/badcase/标签定义
-> 构造挖掘策略
-> profile 数据
-> search 候选
-> sample 抽样 review
-> 策略调整
-> 候选转换为 canonical records
-> 导出 records.jsonl
```
默认线上数据路径：
```text
/data/online_data/router_session_parquet/date=YYYYMMDD/
```
重要分支：
- 如果用户要“直接把线上候选作为样本”，只做转换，不生成新 query。
- 如果用户明确要“补充生成/扩写类似 case”，才切换到数据生成链路。
### 评测修复能力
Skill：`eval-repair`
用于评测错误分析、错误类型归纳和后续补数流程。目前主要是流程占位和约定沉淀，工具还会继续补齐。
### 日志查询能力
Skill：`elk-fetch`
用于按 request id 查询小米内网 ELK 日志，覆盖 NLP 主链路、拒识、免唤醒、小米汽车 OneTrack 等场景。
原则：
- 通过 `python_exec` 执行 skill 内脚本。
- 不让 Agent 直接用 `bash python ...` 绕过工具链路。
### 数据工场 SQL 能力
Skill：`data-factory-sql`
用于通过 Kyuubi HTTP API 执行 SQL、轮询状态并下载 CSV 结果。
适用于：
- 用户直接给 SQL。
- 用户要求“跑个 SQL”“数据工场查一下”。
- Agent 基于表结构和字段说明生成 SQL 草稿，再请求用户确认后执行。
## 团队公约
### 空间公约
业务任务默认在当前会话空间内工作：
```text
input/ 用户上传或指定的输入材料
scratchpad/ 临时脚本、中间文件、抽样缓存
output/ 最终交付文件
```
约定：
- 最终产物优先写入当前会话 `output/`。
- 临时脚本和中间文件写入当前会话 `scratchpad/`。
- 数据 records 默认导出到逻辑路径 `output/records.jsonl`，工具会自动路由到当前会话 output。
- 不要把业务任务产物写到项目根目录的 `output/`、`tasks/`、`src/`、`skills/`。
- 读取外部数据可以用明确路径，但写入外部路径前需要用户明确确认。
- 平台源码目录默认只读。只有用户明确要求开发平台功能时，才修改 `src/`、`frontend/`、`skills/`、`scripts/` 等项目文件。
### Skill 公约
项目级 Skill 统一放在：
```text
skills/<skill-name>/SKILL.md
```
`SKILL.md` frontmatter 至少包含：
```yaml
---
name: product-data
description: 简短说明这个 skill 做什么。
when_to_use: 说明什么场景应该触发。
aliases: optional-alias
allowed_tools: read_file, write_file, python_exec
---
```
维护规则：
- 用中文写主要流程说明，方便团队后续维护。
- Skill 写“怎么做”和“什么时候停下来问用户”。
- 不要把稳定格式转换、校验、复杂查询长期写在 Skill 里，应沉淀为 Tool。
- Skill 如果依赖脚本，脚本放在该 Skill 目录下，并通过 `python_exec` 调用。
- 新增业务 Skill 后，可以在 Web UI Skill 列表中按会话启用或关闭。
### Tool 公约
工具是稳定执行边界。
约定：
- 强格式输出必须工具化，例如 canonical records、JSONL 导出、数据校验。
- 需要持久化状态的 review 流程应由工具记录 pending/confirmed 状态。
- Python 分析优先用 `python_exec`。
- 缺 Python 包时用 `python_package`。
- 除非没有专用工具，否则不要让 Agent 通过 `bash` 绕过已有工具。
### Python 公约
Agent 执行 Python 优先使用：
```text
python_exec
python_package
```
原因：
- 可以进入账号级 Python 环境。
- 可以把临时脚本和输出放在当前会话 scratchpad。
- Web UI 能看到工具调用过程。
- 后续更容易加超时、取消、审计和资源限制。
### Git 公约
不要提交：
- `.env.deploy`
- `.venv/`
- `.port_sessions/`
- `router_session_parquet/`
- 用户数据、模型输出、临时任务产物
可以提交：
- `skills/` 下经过确认的项目级 Skill
- `src/` 下稳定工具和运行时代码
- `frontend/app/` 下 Web UI 代码
- `scripts/` 和 `deploy/` 下部署维护脚本
- README 中面向团队维护的约定
## 系统组成
```text
frontend/app/ Next.js Web UI
backend/ FastAPI Web 后端
src/ Agent runtime、提示词、工具实现、会话持久化
skills/ 项目级 Skill，使用 SKILL.md 定义
scripts/ 本地启动、服务器部署、systemd 启动脚本
deploy/systemd/ 用户级 systemd service 模板
.port_sessions/ 本地/服务端运行数据，禁止提交
.env.deploy 本机私有部署配置，禁止提交
```
前端负责账号、会话列表、模型选择、对话流式展示、活动面板和会话文件面板。
后端负责 Agent loop、OpenAI 兼容模型调用、工具执行、run 状态、会话持久化和数据开发工具。
## 本地开发启动
首次准备 Python 依赖：
```bash
pyenv install 3.10.14
pyenv local 3.10.14
python -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -e .
```
准备前端依赖：
```bash
cd frontend/app
npm install
```
本地启动 Web UI：
```bash
bash scripts/start-webui.sh
```
默认地址：
```text
前端：http://127.0.0.1:3000
后端：http://127.0.0.1:8765
```
`scripts/start-webui.sh` 会优先读取 `.env.deploy`，也可以直接使用当前 shell 里的环境变量：
```bash
export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="http://model.mify.ai.srv/v1"
export OPENAI_MODEL="xiaomi/mimo-v2-flash"
```
停止本地 Web UI：
```bash
kill $(cat .port_sessions/webui-frontend.pid) $(cat .port_sessions/webui-backend.pid)
```
## 部署和更新
### 首次部署
推荐把应用部署在用户目录，不需要把代码放到 `/opt`：
```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"
- 拉取 `main` 分支。
- 交互式生成 `.env.deploy`。
- 必要时请求 sudo 安装 Ubuntu 系统依赖。
- 用 pyenv 准备 Python `3.10.14`。
- 创建项目 `.venv`。
- 安装前端依赖并构建。
- 安装并启动用户级 systemd 服务。
`.env.deploy` 会保存：
```text
OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
CLAW_BACKEND_HOST
CLAW_BACKEND_PORT
CLAW_FRONTEND_HOST
CLAW_FRONTEND_PORT
CLAW_API_URL
```
默认部署目录是 `$HOME/zk-data-agent`，默认分支是 `main`。修改部署目录或分支时再加变量：
该文件包含敏感信息，只保存在部署机器本地，权限设置为 `600`，并已被 `.gitignore` 忽略。
### 日常更新
已经完成首次部署后，普通代码更新使用：
```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"
cd "$HOME/zk-data-agent"
bash scripts/update-server-fast.sh
```
这个命令会自动完成：
- 目标目录不存在时执行 `git clone`
- 目标目录已存在时执行 `git fetch` / `git pull --ff-only`
- 进入仓库后执行 `bash scripts/deploy-ubuntu.sh`
说明：仓库是私有仓库，`curl | bash` 拉 raw 文件时容易拿到登录页 HTML；因此推荐直接走 SSH git 权限。
### 仓库内一键部署/更新
如果已经在仓库目录中，日常更新直接执行：
如果改动包含依赖、systemd 模板或部署脚本，使用完整部署脚本：
```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
@@ -74,41 +463,11 @@ bash scripts/deploy-ubuntu.sh main
bash scripts/deploy-ubuntu.sh main --force
```
## 部署配置
### 服务管理
首次执行 `scripts/deploy-ubuntu.sh` 时，如果仓库根目录不存在 `.env.deploy`，脚本会交互式提示输入：
- `OPENAI_API_KEY`
- `OPENAI_BASE_URL`
- `OPENAI_MODEL`
- 后端监听地址和端口
- 前端监听地址和端口
配置会写入：
部署脚本会安装两个用户级 systemd 服务：
```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
```
@@ -139,24 +498,15 @@ systemctl --user restart zk-data-agent-backend zk-data-agent-frontend
systemctl --user stop zk-data-agent-backend zk-data-agent-frontend
```
## 本地开发启动
本地调试可以使用：
如果机器要求用户退出 SSH 后服务仍保持运行，可由管理员执行：
```bash
bash scripts/start-webui.sh
loginctl enable-linger <username>
```
默认端口：
- 前端：`http://127.0.0.1:3000`
- 后端：`http://127.0.0.1:8765`
`scripts/start-webui.sh` 会优先读取本机 `.env.deploy`，也可以直接使用当前 shell 中的环境变量。
## 环境要求
Ubuntu 部署建议准备：
Ubuntu 部署建议：
- `git`
- `bash`
@@ -167,35 +517,86 @@ Ubuntu 部署建议准备：
- 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 后仍保持运行，可由管理员额外执行：
首次安装如果缺 Python 编译依赖，可以执行：
```bash
loginctl enable-linger <username>
bash scripts/deploy-ubuntu.sh --bootstrap-system
```
## 目录说明
`--bootstrap-system` 会使用 `sudo apt-get` 安装系统依赖；应用代码、虚拟环境、前端依赖、运行数据和 systemd 用户服务仍然位于当前用户目录。
## 开发验证
后端基础校验：
```bash
.venv/bin/python -m compileall src backend
```
前端校验：
```bash
cd frontend/app
npm run lint
npx tsc --noEmit
npm run build
```
提交前建议确认：
```bash
git status --short
git diff --check
```
## 常见问题
### Web UI 能打开，但模型调用失败
先检查 `.env.deploy`：
```bash
cat .env.deploy
```
重点确认：
- `OPENAI_API_KEY`
- `OPENAI_BASE_URL`
- `OPENAI_MODEL`
然后看后端日志：
```bash
journalctl --user -u zk-data-agent-backend -f
```
### systemd 服务找不到 npm
重新执行完整部署脚本：
```bash
bash scripts/deploy-ubuntu.sh
```
脚本会把当前可用的 `npm` 路径写入 `.env.deploy`，避免用户级 systemd 读取不到 zsh/nvm 环境。
### 新增 Skill 后前端看不到
项目级 Skill 放在：
```text
backend/ FastAPI Web 后端
frontend/app/ Next.js 前端
src/ Agent runtime、tools、skills
scripts/ 本地启动、部署、systemd 启动脚本
deploy/systemd/ systemd service 模板
.port_sessions/ 本地运行数据，禁止提交
.env.deploy 本机私有部署配置，禁止提交
skills/<skill-name>/SKILL.md
```
## 注意事项
确保 frontmatter 至少包含 `name`、`description`、`when_to_use`。Web UI 会通过 `/api/claw/skills` 读取 Skill 列表。
- 不要把 `OPENAI_API_KEY` 写入可提交文件。
- `.env.deploy`、`.venv`、`.port_sessions` 都是本机文件，不进入 git。
- 服务器更新优先使用 `bash scripts/deploy-ubuntu.sh`，不要手工分散执行依赖安装和服务重启。
- 生产/长期运行使用 systemd 服务；`scripts/start-webui.sh` 只用于本地调试。
### Agent 产物没有出现在“聊天中的文件”
最终产物必须写入当前会话 `output/`。数据 records 推荐使用数据工具导出到逻辑路径：
```text
output/records.jsonl
```
工具会自动路由到当前会话 output 目录。