# ZK Data Agent 技术架构说明

这组文档先服务于技术 review 和后续讲解材料沉淀，不做宣传表达，不做产品比较。
每个章节尽量对应当前代码里的真实模块、函数和 Skill 实现，后续 `/doc` 页面可以从这里抽取内容做视觉化呈现。

## 阅读顺序

1. [基座 Runtime 架构](01-base-runtime.md)
2. [Agent Loop 执行机制](02-agent-loop.md)
3. [工具体系和 Tool Handler](03-tools.md)
4. [Skill 体系和能力包约定](04-skills.md)
5. [会话工作区、运行态和记忆](05-workspace-memory-observability.md)
6. [product-data Skill 实现](06-product-data.md)
7. [online-mining-v2 Skill 实现](07-online-mining-v2.md)
8. [label-master Skill 实现](08-label-master.md)
9. [外部系统 Skill：ELK、SQL、模型迭代](09-external-skills.md)
10. [Agent 记忆机制调研与对比](10-memory-research.md)
11. [运行中输入队列与 Runtime Guidance 注入](12-runtime-guidance-queue.md)
12. [Skill 评测实验台设计](13-skill-evaluation-workbench.md)

## 一句话定位

ZK Data Agent 的基座是一个 Web 化、多用户、可观测的 Agent runtime。
业务能力通过 `skills/<skill-name>/SKILL.md`、`knowledge/` 和 `scripts/` 组织；稳定执行能力通过 Tool handler 或 Skill 内 portable scripts 承载；每次运行通过 Agent loop 让模型在“判断、调用工具、观察结果、继续判断”之间循环。

## 当前技术主线

```text
Web UI
  -> backend/api/server.py
  -> LocalCodingAgent
  -> agent_prompting 组装系统提示词和 Skill 列表
  -> OpenAICompatClient 调模型
  -> 模型返回文本或 tool_calls
  -> agent_tools 执行 handler
  -> session workspace 保存 input/scratchpad/output/session.json
  -> run_state_store / event stream 推给前端活动区
  -> personal_memory 后台异步整理用户记忆和 Skill 记忆
```

## 代码入口速查

| 主题 | 主要代码 |
|------|----------|
| Agent runtime | `src/agent_runtime.py` |
| 系统提示词 | `src/agent_prompting.py` |
| Tool registry / handler | `src/agent_tools.py`、`src/agent_tool_specs/` |
| Skill loader | `src/bundled_skills.py` |
| 模型兼容层 | `src/openai_compat.py` |
| Web 后端 | `backend/api/server.py` |
| 会话持久化 | `src/agent_session.py`、`src/session_store.py` |
| 记忆后台 | `src/personal_memory.py` |
| 数据生成 Skill | `skills/product-data/` |
| 线上挖掘 Skill | `skills/online-mining-v2/` |
| 标签知识 Skill | `skills/label-master/` |

## 后续维护原则

- 如果是在讲“基座怎么运行”，优先改 01-05。
- 如果是在讲“某个 Skill 怎么做事”，优先改 06-09。
- 如果代码实现发生变化，先更新对应章节，再考虑同步 README 或 `/doc` 页面。
- 页面表达、图形素材、演示脚本不写在这里；这里只保留技术事实和设计边界。