zk-data-agent/docs/technical-architecture

ZK Data Agent 技术架构说明

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

阅读顺序

1. 基座 Runtime 架构
2. Agent Loop 执行机制
3. 工具体系和 Tool Handler
4. Skill 体系和能力包约定
5. 会话工作区、运行态和记忆
6. product-data Skill 实现
7. online-mining-v2 Skill 实现
8. label-master Skill 实现
9. 外部系统 Skill：ELK、SQL、模型迭代
10. Agent 记忆机制调研与对比
11. 运行中输入队列与 Runtime Guidance 注入
12. Skill 评测实验台设计

一句话定位

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

当前技术主线

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 页面。
• 页面表达、图形素材、演示脚本不写在这里；这里只保留技术事实和设计边界。