zk-data-agent/frontend/app/public/doc-assets/technical-docs/01-base-runtime.md

01. 基座 Runtime 架构

1. 基座解决的问题

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

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

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

2. 文字架构图

浏览器 / 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 注入

3. 关键代码入口

3.1 Web 后端入口

主要文件：

backend/api/server.py

关键职责：

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

关键函数和位置：

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

3.2 Agent Runtime

主要文件：

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。

关键函数和位置：

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(...)

3.3 系统提示词

主要文件：

src/agent_prompting.py

关键职责：

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

关键函数和位置：

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

4. 基座的分层职责

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

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

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

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

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

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

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

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

5. 设计边界

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

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

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