wuyang6
62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 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)
|
|
|
|
## 一句话定位
|
|
|
|
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` 页面。
|
|
- 页面表达、图形素材、演示脚本不写在这里；这里只保留技术事实和设计边界。
|