docs: add technical architecture guide

2026-05-18 19:28:02 +08:00
parent c4b935692c
commit 3054b3bc6b
53 changed files with 6692 additions and 2234 deletions
@@ -0,0 +1,197 @@
+# 01. 基座 Runtime 架构
+
+![基座 Runtime 架构](assets/01-base-runtime.png)
+
+## 1. 基座解决的问题
+
+基座不绑定某一个业务流程。它提供的是通用 Agent runtime：
+
+- 多用户 Web 入口。
+- 多会话状态管理。
+- 模型选择和 OpenAI-compatible 调用。
+- Tool registry 和 tool handler 执行。
+- Skill 发现、启用和提示词注入。
+- 当前会话工作区。
+- 运行态、事件流、活动区和刷新恢复。
+- 用户记忆和 Skill 记忆后台。
+
+业务能力例如 `product-data`、`online-mining-v2`、`label-master` 都跑在这个基座上。
+
+## 2. 文字架构图
+
+```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 注入
+```
+
+## 3. 关键代码入口
+
+### 3.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
+```
+
+### 3.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(...)
+```
+
+### 3.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
+```
+
+## 4. 基座的分层职责
+
+```text
+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/` 下。