zk-data-agent/docs/technical-architecture/01-base-runtime.md

# 01. 基座 Runtime 架构

![基座 Runtime 架构](assets/01-base-runtime.png)

## 1. 项目定位

ZK Data Agent 的定位不是通用聊天机器人，也不是单人本地 IDE Agent，而是面向团队业务流程的 Web Agent 工作台。

它基于已有的本地工程 Agent 能力继续往上搭：

- `LocalCodingAgent` 提供多轮 Agent Loop。
- OpenAI-compatible client 提供模型调用适配。
- Tool registry 和 handler 提供可控执行能力。
- Session workspace 提供每个会话独立的输入、中间文件和产物目录。
- Skill system 把流程协议、业务知识、脚本和样例打包成可复用能力。
- Memory worker 把用户偏好和 Skill 使用经验异步整理为可编辑记忆。

这个项目要解决的核心痛点是：团队里的数据开发、线上挖掘、标签判断等流程，往往散在口头经验、临时 prompt、个人脚本、聊天记录和本地文件里。每个人都能临时做一次，但很难让别人稳定复用、持续维护、形成可审计的产物链。

当前已经验证过的主要业务场景包括：

- `product-data`：从产品定义、标签边界、样例 query 或 badcase 出发，生成 canonical records，并导出流转 CSV、训练 JSONL、评测 CSV。
- `online-mining-v2`：基于 ELK 日志挖掘线上样本，保留 request_id、timestamp、session、模型 prompt、模型输出、domain 等信息，并接入后续数据规范。
- `label-master`：把复杂度、多指令、自动任务、标签定义、function 输出和边界经验整理为可检索知识体系。
- 外部系统 Skill：ELK、SQL、模型迭代、飞书在线文档转换等能力以 Skill 方式接入，不侵入基座。

因此，基座 Runtime 的目标不是把某一条业务链路写死，而是提供一套稳定的承载层，让不同业务能力都能以 Skill 的方式运行、交付、沉淀和更新。

## 2. 基座解决的问题

基座不绑定某一个业务流程。它提供的是通用 Agent runtime：

- 多用户 Web 入口。
- 多会话状态管理。
- 模型选择和 OpenAI-compatible 调用。
- Tool registry 和 tool handler 执行。
- Skill 发现、启用和提示词注入。
- 当前会话工作区。
- 运行态、事件流、活动区和刷新恢复。
- 用户记忆和 Skill 记忆后台。

业务能力例如 `product-data`、`online-mining-v2`、`label-master` 都跑在这个基座上。

## 3. 文字架构图

```text
浏览器 / Web UI
  |
  | 用户消息、模型选择、Skill 启用、文件面板、停止运行
  v
frontend/app
  |
  | /api/chat、/api/claw/*、/admin
  v
backend/api/server.py
  |
  | 账号配置、会话目录、run manager、run_state_store、memory_manager
  v
LocalCodingAgent
  |
  | build_session、prompt sections、tool_specs、Agent loop
  v
OpenAICompatClient
  |
  | messages + tools -> model backend
  v
模型
  |
  | assistant text 或 tool_calls
  v
Tool Runtime
  |
  | read/write/python_exec/data_agent/MCP/search/bash
  v
session workspace
  |
  | input / scratchpad / output / session.json
  v
前端活动区和文件面板

运行结束后：

AgentRunResult
  -> session_store 持久化
  -> memory_manager.enqueue_interaction
  -> memory worker 异步整理
  -> 下一轮 render_injection 注入
```

## 4. 关键代码入口

### 4.1 Web 后端入口

主要文件：

```text
backend/api/server.py
```

关键职责：

- 维护账号和会话配置。
- 创建或复用 `LocalCodingAgent`。
- 给 Agent 注入 `runtime_context`、记忆、Jupyter 上下文。
- 记录 run event，并通过 NDJSON streaming 返回前端。
- 运行结束后写入 elapsed、标题、memory event。

关键函数和位置：

```text
backend/api/server.py:691  enabled_skill_names(...)
backend/api/server.py:822  _build_agent(...)
backend/api/server.py:853  agent_for(...)
backend/api/server.py:866  run_lock_for(...)
backend/api/server.py:1720 /api/chat 运行链路开始
backend/api/server.py:1739 memory_manager.render_injection(...)
backend/api/server.py:1751 emit_agent_event(...)
backend/api/server.py:1897 序列化运行结果和 elapsed
backend/api/server.py:1920 memory_manager.enqueue_interaction(...)
backend/api/server.py:2034 StreamingResponse NDJSON
```

### 4.2 Agent Runtime

主要文件：

```text
src/agent_runtime.py
```

关键职责：

- 初始化 tool registry、plugin runtime、MCP runtime、search runtime 等。
- 新会话用 `run(...)`，旧会话用 `resume(...)`。
- 在 `_run_prompt(...)` 中执行完整 Agent loop。
- 维护 usage、cost、tool_calls、events、file_history。
- 在结束时持久化 session。

关键函数和位置：

```text
src/agent_runtime.py:158  class LocalCodingAgent
src/agent_runtime.py:195  __post_init__
src/agent_runtime.py:413  run(...)
src/agent_runtime.py:441  resume(...)
src/agent_runtime.py:520  _run_prompt 主链路
src/agent_runtime.py:552  tool_specs = [tool.to_openai_tool() ...]
src/agent_runtime.py:619  for turn_index in range(...)
src/agent_runtime.py:1008 遍历模型返回的 tool_calls
src/agent_runtime.py:1490 _query_model(...)
```

### 4.3 系统提示词

主要文件：

```text
src/agent_prompting.py
```

关键职责：

- 定义中控 Agent 身份。
- 注入工具使用策略。
- 注入工作空间边界。
- 注入 Skill 列表。
- 注入 ask_user 等 runtime 指导。

关键函数和位置：

```text
src/agent_prompting.py:135 get_intro_section
src/agent_prompting.py:155 get_doing_tasks_section
src/agent_prompting.py:182 get_actions_section
src/agent_prompting.py:196 get_workspace_boundary_section
src/agent_prompting.py:210 get_using_your_tools_section
src/agent_prompting.py:274 get_skill_guidance_section
src/agent_prompting.py:414 get_ask_user_guidance_section
```

## 5. 基座的分层职责

```text
Web UI
  负责交互、展示、文件面板、活动区、Skill 勾选、管理后台。

Backend API
  负责账号、会话、模型配置、运行态、服务端事件流。

Agent Runtime
  负责 Agent loop、模型调用、工具调用、预算和持久化。

Prompting
  负责把规则、工具、公约、Skill 列表转成模型可见上下文。

Tool Runtime
  负责稳定执行动作，并把结果结构化回传给模型。

Skill System
  负责让业务流程、知识、脚本可被 Agent 发现和使用。

Workspace
  负责隔离每个用户和每个会话的输入、临时文件和交付产物。

Memory Worker
  负责从交互历史中异步整理长期偏好和 Skill 使用经验。
```

## 6. 设计边界

基座只应该承载跨业务复用的稳定能力，例如：

- 工具执行。
- 会话状态。
- 运行态事件。
- 工作区路径。
- Skill 发现和启用。
- 模型适配。
- 记忆后台。

业务流程不应该写死在基座里。数据生成、线上挖掘、标签判断等变化快的流程应该沉到 Skill；确定性脚本应该放在对应 Skill 的 `scripts/` 下。