ZK Data Agent

ZK Data Agent 是基于 claw-code-agent 改造的团队通用 Agent 工作台。

它不是一个单点数据工具，也不是只会聊天的 Web UI。这个项目的核心目标是把“通用 Agent 能力”稳定下来：让 Agent 能理解任务、选择 Skill、调用 Tools、读写文件、执行 Python、保留会话、展示工具链路，并把团队反复使用的工作经验沉淀成可维护的能力包。

数据开发、线上挖掘、ELK 查询、数据工场 SQL 查询，都是已经通过 Skill 和 Tools 落地的子能力。

这个项目解决什么

团队日常有很多任务不只是“问模型一句话”：

• 要读文件、查日志、跑 SQL、分析线上数据。
• 要生成中间结果、落盘文件、继续追问和修正。
• 要把某类任务的经验固化下来，下一次让 Agent 按同样的方法做。
• 要让用户看到 Agent 做了什么、调用了什么工具、文件生成在哪里。
• 要让多人共用一套平台，而不是每个人本地各跑一份零散脚本。

ZK Data Agent 做的是这层通用底座。业务能力通过 Skill 和 Tools 逐步沉淀。

核心设计

Agent Loop

Agent 每轮对话不是一次性生成文本，而是一个循环：

用户输入
  -> 组装系统提示词、Skill 提示词、会话上下文、工具定义
  -> 模型决定直接回复或返回 tool_calls
  -> 后端执行对应 tool handler
  -> 工具结果写入会话
  -> 下一轮模型继续判断
  -> 直到输出最终回复、等待用户 review 或被取消

这个循环让 Agent 可以边观察、边执行、边修正，而不是只能一次性回答。

Skill

Skill 是“经验层”。它用 SKILL.md 描述某类任务应该怎样做、什么时候需要用户确认、可以调用哪些工具、产物应该放在哪里。

项目级 Skill 统一放在：

skills/<skill-name>/SKILL.md

Skill 适合承载：

• 工作流程
• 业务边界
• review 门禁
• 工具调用经验
• 输入输出格式约定
• 常见错误和注意事项

Skill 不应该写成大段不可执行代码。稳定、强格式、可复用的能力应该下沉到 Tool。

Tools

Tools 是“执行层”。工具负责稳定地做事情，例如读写文件、执行 Python、查询 parquet、转换 records、导出 JSONL。

主要位置：

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 手写易错脚本来完成稳定流程。能工具化的，尽量工具化。

会话工作区

每个用户、每个会话都有独立目录：

.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 生成数据集。

典型流程：

输入定义/规则/样例
  -> 抽取 generation goal
  -> 用户 review
  -> 生成 generation plan
  -> 用户确认数量、标签、边界、路径
  -> 生成 dataset draft text
  -> 转换为 canonical records
  -> 校验
  -> 导出 records.jsonl

默认最终产物：

当前会话/output/records.jsonl

线上挖掘能力

Skill：online-mining

适用于从线上 router session 中按 query 特征、domain、设备、日期等条件挖掘候选样本。

典型流程：

需求/badcase/标签定义
  -> 构造挖掘策略
  -> profile 数据
  -> search 候选
  -> sample 抽样 review
  -> 策略调整
  -> 候选转换为 canonical records
  -> 导出 records.jsonl

默认线上数据路径：

/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 草稿，再请求用户确认后执行。

团队公约

空间公约

业务任务默认在当前会话空间内工作：

input/       用户上传或指定的输入材料
scratchpad/  临时脚本、中间文件、抽样缓存
output/      最终交付文件

约定：

• 最终产物优先写入当前会话 output/。
• 临时脚本和中间文件写入当前会话 scratchpad/。
• 数据 records 默认导出到逻辑路径 output/records.jsonl，工具会自动路由到当前会话 output。
• 不要把业务任务产物写到项目根目录的 output/、tasks/、src/、skills/。
• 读取外部数据可以用明确路径，但写入外部路径前需要用户明确确认。
• 平台源码目录默认只读。只有用户明确要求开发平台功能时，才修改 src/、frontend/、skills/、scripts/ 等项目文件。

Skill 公约

项目级 Skill 统一放在：

skills/<skill-name>/SKILL.md

Skill 是可以独立维护、独立安装、被 Agent 读取和执行的能力包。它不只是 prompt，也不只是脚本，而是某类任务的“能力入口”：可以包含流程、知识、脚本、配置和模板，但必须清楚说明边界。

适合做成 Skill 的内容

当前项目里的 Skill 大致分为四类：

类型	代表	适合承载
流程编排型	product-data、online-mining、eval-repair	分阶段流程、review 门禁、工具调用顺序、产物规范
工具封装型	elk-fetch、data-factory-sql	外部系统调用脚本、CLI 参数、依赖说明、返回格式
知识增强型	model-iteration/knowledge/*，后续标签知识 Skill	标签定义、边界规则、案例、决策依据
混合工程型	model-iteration	复杂工程闭环：流程 + 知识 + 脚本 + 配置

判断一件事放在哪里：

• Skill：告诉 Agent 怎么做、什么时候停、读哪些知识、如何组织流程。
• Knowledge / references：放大段业务知识、规则、案例和字段说明。
• Scripts：放可重复、确定性、容易写错的执行逻辑。
• Tools：放平台级、强约束、需要长期稳定维护的能力，例如 records 转换、校验、线上 parquet 检索。

推荐目录结构

skills/<skill-name>/
  SKILL.md          必须，Agent 触发和执行该能力的入口
  README.md         可选，给维护者看的说明
  scripts/          可选，确定性脚本或 CLI
  knowledge/        可选，业务知识、标签规则、案例
  references/       可选，长文档、字段说明、API 说明
  assets/           可选，模板、静态资源
  config.yaml       可选，默认参数

不建议提交：

• __pycache__/
• .venv/
• 临时运行结果
• 用户私有 token、key、cookie
• 大体积产物或线上原始数据

SKILL.md frontmatter

SKILL.md frontmatter 至少包含：

---
name: skill-name
description: 简短说明这个 skill 做什么，尽量覆盖触发关键词。
when_to_use: 说明什么场景应该触发，包含用户常见说法。
aliases: optional-alias
allowed_tools: read_file, write_file, python_exec
---

字段约定：

• name：短横线命名，稳定、可读，例如 online-mining、data-factory-sql。
• description：面向模型召回，说明能力范围和典型触发词。
• when_to_use：面向模型决策，说明什么场景应该使用。
• aliases：兼容旧名字、团队口头叫法。
• allowed_tools：列出该 Skill 合理使用的工具，避免能力越界。

命名建议：

• 用“能力名”而不是项目临时代号，例如 model-iteration 优于 zk-model。
• 工具封装型可以用系统名，例如 elk-fetch、data-factory-sql。
• 知识型可以用知识域名，例如 label-master。
• 不要用过泛的名字，例如 helper、tools、data。

维护规则：

• 用中文写主要流程说明，方便团队后续维护。
• Skill 写“怎么做”和“什么时候停下来问用户”。
• 不要把稳定格式转换、校验、复杂查询长期写在 Skill 里，应沉淀为 Tool。
• Skill 如果依赖脚本，脚本放在该 Skill 目录下，并通过 python_exec 调用。
• 新增业务 Skill 后，可以在 Web UI Skill 列表中按会话启用或关闭。

SKILL.md 内容结构

推荐顺序：

1. 这个 Skill 解决什么问题
2. 输入假设
3. 必要工作流
4. 需要用户 review 的门禁
5. 输出目录和产物约束
6. 可用脚本或知识文件
7. 常见错误和禁止事项

如果 SKILL.md 超过几百行，优先拆分：

• 长业务规则放 knowledge/
• 长 API/字段说明放 references/
• 可执行逻辑放 scripts/
• SKILL.md 只保留导航、流程和关键门禁

脚本型 Skill 约定

脚本型 Skill 典型如 elk-fetch、data-factory-sql、model-iteration。

约定：

• Python 脚本优先放在 scripts/，少量历史 Skill 可保留根目录脚本，但新 Skill 优先使用 scripts/。
• Agent 调用脚本优先使用 python_exec，不要让模型直接 bash python xxx.py。
• 依赖缺失时使用 python_package 安装到账号级 Python 环境。
• 脚本参数要稳定，输出尽量给 JSON 或结构化摘要，方便 Agent 继续分析。
• 不要在脚本里硬编码 API key、token、个人路径。优先读取环境变量或用户 home 下配置。
• 长耗时脚本必须考虑超时、分页、采样或断点，不要默认全量扫描。

脚本调用示例：

{
  "script_path": "skills/example/scripts/run_task.py",
  "args": ["--input", "xxx"],
  "timeout_seconds": 120,
  "max_output_chars": 20000
}

知识型 Skill 约定

知识型 Skill 适合承载标签体系、业务规则、字段定义、案例库。

约定：

• SKILL.md 只写“什么时候读哪些知识文件”。
• knowledge/ 下按主题拆文件，文件名语义化。
• 每个知识文件开头写清楚适用范围。
• 不要把所有知识一次性塞进 SKILL.md。
• 面向标签、路由、复杂度等判断时，鼓励输出“候选、依据、排除项、不确定点”，不要过早封装成黑盒单步分类。

例如后续中控标签知识可以先设计为：

skills/label-master/
  SKILL.md
  knowledge/
    agents.md
    functions.md
    complex_rules.md
    boundary_cases.md
    examples.md
  scripts/
    build_index.py

外部 Skill 仓库安装约定

允许同事把能力打包为独立 git 仓库维护，再安装到本项目：

skills/<skill-name>/

安装或迁移时需要检查：

• 是否有合法 SKILL.md frontmatter。
• skill 名是否符合项目命名风格。
• 是否包含不该提交的缓存、运行产物、私钥、token。
• 脚本是否能通过 python_exec 调用。
• 依赖是否写清楚，缺包时能通过 python_package 安装。
• 输出目录是否遵守当前会话 output/ / scratchpad/ 公约。
• 高风险动作是否有用户确认门禁。

外部仓库可以保留自己的 README，但真正影响 Agent 行为的是 SKILL.md。

高风险动作门禁

Skill 中只要涉及下面动作，必须先展示计划并等待用户确认：

• 批量修改训练数据或标签定义。
• 提交训练、部署模型、启动 CML job。
• 写入外部路径或覆盖已有产物。
• 推送 git、改远端配置。
• 导出包含敏感线上字段的数据。

用户明确说“开始评测”“查一下”“分析一下”时，可以执行只读分析；不要自动升级成训练、部署或批量改数据。

Tool 公约

工具是稳定执行边界。

约定：

• 强格式输出必须工具化，例如 canonical records、JSONL 导出、数据校验。
• 需要持久化状态的 review 流程应由工具记录 pending/confirmed 状态。
• Python 分析优先用 python_exec。
• 缺 Python 包时用 python_package。
• 除非没有专用工具，否则不要让 Agent 通过 bash 绕过已有工具。

Python 公约

Agent 执行 Python 优先使用：

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 中面向团队维护的约定

系统组成

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 依赖：

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 .

准备前端依赖：

cd frontend/app
npm install

本地启动 Web UI：

bash scripts/start-webui.sh

默认地址：

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

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

export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="http://model.mify.ai.srv/v1"
export OPENAI_MODEL="tongyi/deepseek-v4-pro"

停止本地 Web UI：

kill $(cat .port_sessions/webui-frontend.pid) $(cat .port_sessions/webui-backend.pid)

部署和更新

首次部署

推荐把应用部署在用户目录，不需要把代码放到 /opt：

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"

首次部署会：

• 拉取 main 分支。
• 交互式生成 .env.deploy。
• 必要时请求 sudo 安装 Ubuntu 系统依赖。
• 用 pyenv 准备 Python 3.10.14。
• 创建项目 .venv。
• 安装前端依赖并构建。
• 安装并启动用户级 systemd 服务。

.env.deploy 会保存：

OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
OPENAI_TIMEOUT_SECONDS
CLAW_BACKEND_HOST
CLAW_BACKEND_PORT
CLAW_FRONTEND_HOST
CLAW_FRONTEND_PORT
CLAW_API_URL
CLAW_NPM_BIN
CLAW_NPX_BIN
CLAW_NODE_BIN
CLAW_NODE_BIN_DIR

其中 Node.js 相关路径会在部署时自动记录，供 systemd 后端/前端服务以及飞书 MCP 等 Node 生态能力使用。该文件包含敏感信息，只保存在部署机器本地，权限设置为 600，并已被 .gitignore 忽略。

日常更新

已经完成首次部署后，普通代码更新使用：

cd "$HOME/zk-data-agent"
bash scripts/update-server-fast.sh

如果改动包含依赖、systemd 模板或部署脚本，使用完整部署脚本：

bash scripts/deploy-ubuntu.sh

部署指定分支：

bash scripts/deploy-ubuntu.sh main

强制覆盖服务器工作区：

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

服务管理

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

zk-data-agent-backend
zk-data-agent-frontend

查看状态：

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

查看日志：

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

重启服务：

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

停止服务：

systemctl --user stop zk-data-agent-backend zk-data-agent-frontend

如果机器要求用户退出 SSH 后服务仍保持运行，可由管理员执行：

loginctl enable-linger <username>

环境要求

Ubuntu 部署建议：

• git
• bash
• curl
• systemd
• pyenv
• Python 3.10.14
• Node.js 20 或 22
• npm

首次安装如果缺 Python 编译依赖，可以执行：

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

--bootstrap-system 会使用 sudo apt-get 安装系统依赖；应用代码、虚拟环境、前端依赖、运行数据和 systemd 用户服务仍然位于当前用户目录。

开发验证

后端基础校验：

.venv/bin/python -m compileall src backend

前端校验：

cd frontend/app
npm run lint
npx tsc --noEmit
npm run build

提交前建议确认：

git status --short
git diff --check

常见问题

Web UI 能打开，但模型调用失败

先检查 .env.deploy：

cat .env.deploy

重点确认：

• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MODEL
• OPENAI_TIMEOUT_SECONDS

然后看后端日志：

journalctl --user -u zk-data-agent-backend -f

systemd 服务找不到 npm

重新执行完整部署脚本：

bash scripts/deploy-ubuntu.sh

脚本会把当前可用的 npm 路径写入 .env.deploy，避免用户级 systemd 读取不到 zsh/nvm 环境。

新增 Skill 后前端看不到

项目级 Skill 放在：

skills/<skill-name>/SKILL.md

确保 frontmatter 至少包含 name、description、when_to_use。Web UI 会通过 /api/claw/skills 读取 Skill 列表。

Agent 产物没有出现在“聊天中的文件”

最终产物必须写入当前会话 output/。数据 records 推荐使用数据工具导出到逻辑路径：

output/records.jsonl

工具会自动路由到当前会话 output 目录。