Devika 系统架构深度解析：Agentic 软件工程师的模块化设计、核心组件与执行流程

Devika 系统架构深度解析：Agentic 软件工程师的模块化设计、核心组件与执行流程

【免费下载链接】devikaDevika is the first open-source implementation of an Agentic Software Engineer. Initially started as an open-source alternative to Devin.项目地址: https://gitcode.com/GitHub_Trending/de/devika

导读

本文以 Devika 官方架构文档（docs/architecture/README.md、docs/architecture/ARCHITECTURE.md 与 docs/architecture/UNDER_THE_HOOD.md）为主体，结合仓库源码逐层剖析 Devika 的系统架构：从 Agent Core 的编排核心、十大子 Agent 的分工协作，到 LLM 统一抽象层、浏览器交互、项目/状态持久化、外部服务集成与工具模块。读完本文，你将掌握 Devika 的完整模块划分与调用链，能够快速定位各组件对应的源码实现，并理解如何通过sample.config.toml配置模型与搜索服务来运行这套 Agentic 软件工程师系统。

系统架构总览：九大核心组件

Devika 的整体架构由以下关键组件构成：

1. User Interface（用户界面）：基于 Web 的聊天界面，用于与 Devika 交互、查看项目文件、实时监控 Agent 状态（UI 代码位于 ui/ 目录）。
2. Agent Core（Agent 核心）：中央组件，编排 AI 规划、推理与执行全过程，负责与各子 Agent 和模块通信以完成任务。
3. Large Language Models（大语言模型）：接入 Claude、GPT-4 等闭源模型，以及通过 Ollama 运行的本地开源模型，承担自然语言理解、生成与推理。
4. Planning and Reasoning Engine（规划与推理引擎）：将高层目标拆解为可执行步骤，并基于当前上下文做出决策。
5. Research Module（研究模块）：利用关键词提取与网页浏览能力收集任务所需信息。
6. Code Writing Module（代码编写模块）：基于计划、研究结果与用户需求生成代码，支持多种编程语言。
7. Browser Interaction Module（浏览器交互模块）：驱动 Devika 浏览网页、提取信息、与网页元素交互。
8. Knowledge Base（知识库）：存储与检索项目特定信息、代码片段与学习所得知识（实现见 src/memory/knowledge_base.py 与 src/memory/rag.py）。
9. Database（数据库）：持久化项目数据、Agent 状态与配置设置（SQLite，相关实现见 src/project.py 与 src/state.py）。

需要深入细节的读者，可继续阅读仓库内的两份配套文档：

• docs/architecture/ARCHITECTURE.md：面向技术人员的系统架构详细说明；
• docs/architecture/UNDER_THE_HOOD.md：深入讲解 AI 规划推理、关键词提取、浏览器交互与代码编写的内部机理。

Agent Core：驱动 Agentic 执行循环的中枢引擎

Agent类（src/agents/agent.py）是 Devika 的中央引擎，负责驱动整个"规划-研究-编码"的 Agentic 执行循环。其构造方法在 src/agents/agent.py#L36-L67 中完成全部子 Agent、项目管理器、状态管理器的初始化，并接收base_model与search_engine两个关键参数。

首次执行流程（execute）

当用户输入一个高层级提示词时，execute方法（src/agents/agent.py#L270-L365）被调用，整个流程如下：

1. 保存用户消息并初始化状态：将用户提示写入项目会话，并调用agent_state.create_state创建初始状态（内部独白默认为 "I'm starting the work..."，步骤置为 1）。
2. Planner 生成计划：将提示词交给 Planner Agent，生成逐步计划，解析出reply（回复）、focus（关注领域）、plans（计划列表）与summary（摘要），并把计划写入会话。
3. 上下文关键词累积：调用update_contextual_keywords，使用 SentenceBERT 从focus提取关键词并累积到collected_context_keywords，供后续研究阶段复用。
4. 内部独白模拟：通过internal_monologue.execute生成 Agent 的"内心独白"，写入状态栈。
5. Researcher 提取搜索意图：Researcher 基于计划与上下文关键词产出queries（搜索查询列表）与ask_user（需要向用户确认的问题）。
6. 按需询问用户：若 Researcher 认为需要用户补充上下文，Agent 会暂停执行（set_agent_active(False)），轮询get_latest_message_from_user等待用户回复，收到后继续。
7. 执行搜索：若存在查询词，调用search_queries依次执行搜索——先通过所选搜索引擎获取结果链接，再用浏览器打开首个结果抓取原始内容，最后交给 Formatter 提取干净信息。
8. Coder 生成并落盘代码：Coder 综合逐步计划、用户上下文与搜索结果生成代码，并由save_code_to_project写入项目目录。

search_queries的实现细节位于 src/agents/agent.py#L79-L116：它按engine参数选择BingSearch、GoogleSearch或DuckDuckGoSearch，对每个查询打开第一条结果链接，抓取页面截图（通过 WebSocket 实时推送到 UI），并将正文交给 Formatter 处理。

后续执行流程（subsequent_execute）

当用户继续追问时，subsequent_execute方法（src/agents/agent.py#L179-L268）被调用，其核心是意图路由：

1. 保存用户新消息，读取完整会话与项目代码（ReadCode().code_set_to_markdown()）。
2. Action Agent 判定动作：将用户消息映射为answer（回答）、run（运行）、deploy（部署）、feature（加功能）、bug（修 Bug）、report（生成报告）等动作关键字。
3. 按动作分派：
   • answer→ Answer Agent 结合会话与代码直接回答；
   • run→ Runner Agent 在项目目录中以沙箱方式执行代码；
   • deploy→ 调用 Netlify 服务部署并返回部署 URL；
   • feature→ Feature Agent 修改代码新增功能并落盘；
   • bug→ Patcher Agent 分析代码与报错信息修复 Bug；
   • report→ Reporter Agent 生成 Markdown 报告并导出 PDF。
4. 结束时将 Agent 标记为非活跃与任务完成。

此外，make_decision方法（src/agents/agent.py#L128-L177）处理不适合其他 Agent 的特殊指令，例如git_clone（克隆仓库）、generate_pdf_document（生成 PDF）、browser_interaction（浏览器交互会话）与coding_project（组合调用规划、研究、编码全链路）。

子 Agent 体系：模块化的认知能力集合

Devika 的认知能力由一组专门化的子 Agent 提供，每个 Agent 是独立的 Python 类（位于 src/agents/ 目录），通过 Jinja2 格式的提示模板与底层 LLM 通信。主要 Agent 及其职责如下：

每个 Agent 遵循统一的工作模式（源码模式详见各 Agent 实现，例如 Runner 在 src/agents/runner/runner.py#L23-L53 的模板渲染）：

1. 用当前上下文渲染 Jinja2 模板，准备提示词；
2. 查询 LLM 获取响应；
3. 校验并解析 LLM 响应，提取结构化输出；
4. 执行额外处理或副作用（如写盘）；
5. 将结果返回 Agent Core 继续推进。

Agent 的设计目标是尽量无状态、幂等——状态与会话历史由 Agent Core 统一管理并作为参数传入，从而保证整个系统模块化、可组合。

语言模型层：统一抽象与多供应商接入

Devika 的自然语言处理能力由多个大语言模型驱动，LLM类（src/llm/llm.py）为不同模型提供统一接口。从 src/llm/llm.py#L33-L69 可见，当前内置支持的供应商与模型包括：

• Claude（Anthropic）：Claude 3 Opus、Sonnet、Haiku 等；
• OpenAI：GPT-4o-mini、GPT-4o、GPT-4 Turbo、GPT-3.5 Turbo；
• Google：Gemini 1.0 Pro、Gemini 1.5 Flash、Gemini 1.5 Pro；
• Mistral：Mistral 7b、8x7b、Medium、Small、Large；
• Groq：LLaMA3 8B/70B、LLaMA2 70B、Mixtral、GEMMA 7B；
• Ollama：本地自托管开源模型，运行时通过http://127.0.0.1:11434动态拉取模型列表；
• LM Studio：本地模型（local-model）。

LLM类提供的能力包括：list_models()列出可用模型、inference()基于提示词生成补全、update_global_token_usage()使用 tiktoken（cl100k_base编码）跟踪并累计 token 消耗并实时推送到 UI。

值得注意的实现细节：inference方法（src/llm/llm.py#L92-L156）通过model_enum将显示名称映射到供应商枚举，再按枚举分发到对应客户端（Claude、OpenAi、Gemini、MistralAi、Groq、Ollama、LMStudio，见 src/llm/ 目录）；同时使用ThreadPoolExecutor异步执行推理并轮询，超过配置的超时时间（TIMEOUT.INFERENCE）即报错退出。选择何种模型取决于对质量、速度与成本的权衡，模块化设计使替换模型非常容易。

研究模块：关键词提取 + 搜索引擎 + 网页抓取

研究模块负责为编码任务收集信息，由三部分协作完成。

关键词提取（Keyword Extraction）

正如 docs/architecture/UNDER_THE_HOOD.md 所述，关键词提取流程包含：预处理（去除停用词、分词、归一化）→关键词识别（利用 BERT 模型捕捉语义关系，理解词在上下文中的重要性）→关键词排序（使用 TF-IDF 与 TextRank 等技术为关键词打分）→关键词选择（选取最相关、信息量最大的关键词以引导研究）。其实现为 src/bert/sentence.py 中的SentenceBert类，Agent.update_contextual_keywords（src/agents/agent.py#L118-L126）负责跨 Agent 提示词累积上下文关键词。

搜索引擎接入

src/browser/search.py 提供了三种搜索引擎实现，均以search(query)发起查询、以get_first_link()返回首个结果链接：

• BingSearch：调用 Bing Web Search API（https://api.bing.microsoft.com/v7.0/search），使用Ocp-Apim-Subscription-Key请求头鉴权；
• GoogleSearch：调用 Google Custom Search JSON API（https://www.googleapis.com/customsearch/v1），通过key与cx（搜索引擎 ID）参数鉴权；
• DuckDuckGoSearch：直接请求 DuckDuckGo 页面接口并解析结果，无需 API Key（源码注释提示当前与现有环境不完全兼容）。

网页抓取与信息整理

研究流程在Agent.search_queries中完成：对每个查询词，打开搜索结果的第一条链接（Playwright 无头浏览器），截取整页截图并提取正文文本，再交给 Formatter Agent 清洗为结构化信息，最终作为search_results传入 Coder。搜索过程中页面截图会通过emit_agent("screenshot", ...)实时推送到前端。

搜索引擎的 API Key 配置方式可参考 docs/Installation/search_engine.md。

浏览器交互模块：Playwright 驱动的网页自动化

Devika 的网页交互能力由Browser与Crawler类提供。

Browser 类

Browser（src/browser/browser.py）基于 Playwright 封装了高层级的网页自动化原语：

• 启动浏览器实例：start()使用async_playwright().start()启动 Chromium（headless 模式，见 src/browser/browser.py#L21-L25）；
• 导航：go_to(url)打开指定 URL（20 秒超时）；
• DOM 查询：get_html()、extract_text()分别获取页面 HTML 与document.body.innerText；
• 内容提取：get_markdown()通过 markdownify 将 HTML 转 Markdown，get_pdf()保存页面为 PDF，pdf_to_text()使用 pdfminer 提取 PDF 文本；
• 截图：screenshot()模拟媒体类型并截取全页截图，同时将 URL 与截图路径写入 Agent 状态（内部独白设为 "Browsing the web right now..."）。

Crawler 与浏览器交互循环

Crawler定义了一个能依据自然语言指令与网页交互的 Agent，它结合预定义的浏览器动作（滚动、点击、输入等）、示范动作用法的提示模板，以及 LLM 对当前页面内容与目标的分析来决定下一步动作。start_interaction函数建立如下循环（见 docs/architecture/ARCHITECTURE.md 的 Browser Interaction 一节）：

1. 将当前页面内容与目标传给 LLM；
2. LLM 返回最优下一步动作（例如CLICK 12或TYPE 7 machine learning）；
3. Crawler 在真实页面上执行该动作；
4. 基于更新后的页面状态重复上述过程。

这使 Devika 能完成一系列动作以达成高层目标，例如调研主题、填写表单、与应用交互等。

代码编写模块：从计划到可落盘的代码

代码编写遵循 docs/architecture/UNDER_THE_HOOD.md 中描述的五个阶段：

1. 语言选择：识别用户指定的语言，或依据项目上下文推断；
2. 代码结构生成：基于计划与语言特定模式生成高层结构（类、函数、模块）；
3. 代码填充：填入具体逻辑、算法与数据操作语句，融合研究结论、知识库代码片段与自身的编程理解；
4. 代码格式化：按语言惯例与最佳实践格式化，保证可读性与可维护性；
5. 代码审查与优化：检查语法错误、逻辑不一致与潜在改进点，基于自分析与用户反馈迭代优化。

在编排层面，Coder 由Agent.execute在第 9 步触发（src/agents/agent.py#L349-L357），输入为逐步计划、用户上下文与搜索结果，产出代码后经save_code_to_project写入项目目录，随后 Agent 标记任务完成。

项目与状态管理：基于 SQLite 的持久化

项目管理（ProjectManager）

ProjectManager（src/project.py）负责项目的创建、更新与查询，关键功能包括：

• 创建/删除项目并初始化目录结构（create_project/delete_project）；
• 向会话追加用户/Devika 消息（add_message_from_user/add_message_from_devika，均实时推送server-message事件）；
• 检索会话消息、最新用户/Devika 消息（get_messages/get_latest_message_from_user/get_latest_message_from_devika）；
• 列出全部项目（get_project_list）；
• 将项目文件打包为 Zip 用于导出（project_to_zip）。

项目元数据持久化在 SQLite 中，使用SQLModel定义Projects表（src/project.py#L11-L15），字段包括：项目名project与 JSON 序列化的会话历史message_stack_json。ProjectManager.__init__从Config读取数据库路径并调用SQLModel.metadata.create_all自动建表。多项目并行与跨会话的历史保留由此得到保障。

Agent 状态管理（AgentState）

AgentState（src/state.py）负责跟踪并展示 Agent 执行过程中的动态状态，核心 API 包括：

• 初始化状态（create_state）；
• 追加/更新项目状态（add_to_current_state/update_latest_state）；
• 查询最新状态或完整状态历史（get_latest_state/get_current_state）；
• 标记 Agent 活跃/非活跃、任务完成/未完成（set_agent_active/set_agent_completed）；
• 累计与查询 token 用量（update_token_usage/get_latest_token_usage）。

状态数据结构（new_state，src/state.py#L25-L45）包含：

• internal_monologue：Agent 当前的"想法"；
• browser_session：浏览器会话信息（访问 URL、截图路径）；
• terminal_session：终端会话信息（执行命令、输出、标题）；
• step：当前步骤序号；
• token_usage：累计 token 消耗；
• completed/agent_is_active：任务完成与活跃标记。

Agent 状态同样持久化于 SQLite，表名agent_state（AgentStateModel，src/state.py#L10-L16），字段为项目名与 JSON 序列化的状态列表。状态日志的价值在于：向用户提供实时可见性、支持行为审计与调试、以及在中断或失败后恢复执行。每次状态变更都会通过emit_agent("agent-state", ...)实时同步到前端界面。

服务集成：GitHub 与 Netlify 封装

Devika 通过轻量级封装对接外部服务以增强能力：

• GitHub（src/services/github.py）：执行 git 操作（clone/pull）、列出仓库/提交/文件等；
• Netlify（src/services/netlify.py）：无缝部署 Web 应用与站点。

两类封装均处理认证、HTTP 请求与响应解析。通过它们，Devika 可以克隆 GitHub 仓库、列出用户仓库、创建 Netlify 站点、部署目录并将站点 URL 返回给用户（部署动作在 src/agents/agent.py#L219-L229 中触发）。集成采用模块化方式实现，便于新增其他服务。认证所需的 API Key 在 sample.config.toml 的[API_KEYS]段配置。

支撑模块与配置详解

工具模块

• Config（src/config.py）：加载并提供配置访问（API Keys、目录路径等），采用单例模式；若config.toml不存在则自动从sample.config.toml复制，并自动补齐缺失键；
• Logger（src/logger.py）：配置控制台与文件日志，支持日志级别与彩色输出；
• ReadCode（src/filesystem/read_code.py）：递归读取目录中的代码文件并转换为 Markdown 格式（供 Answer/Reporter 等 Agent 理解项目全貌）；
• SentenceBERT（src/bert/sentence.py）：利用 SentenceBERT 嵌入从文本中提取关键词与语义信息；
• Experts（src/experts/）：一组领域专用知识库（web-design、physics、chemistry、math、medical、game-dev、stackoverflow 等），为特定领域提供辅助；
• Documenter（src/documenter/）：UML 图（graphwiz/uml）与 PDF 导出（pdf）。

配置示例说明

以 sample.config.toml 为模板，关键配置段如下：

[STORAGE] SQLITE_DB = "data/db/devika.db" # SQLite 数据库路径（项目与会话状态） SCREENSHOTS_DIR = "data/screenshots" # 浏览器截图保存目录 PDFS_DIR = "data/pdfs" # PDF 报告保存目录 PROJECTS_DIR = "data/projects" # 项目代码落盘目录 LOGS_DIR = "data/logs" # 日志目录 REPOS_DIR = "data/repos" # 克隆仓库目录 [API_KEYS] BING = "<YOUR_BING_API_KEY>" # Bing 搜索 API Key GOOGLE_SEARCH = "<YOUR_GOOGLE_SEARCH_API_KEY>" # Google 搜索 API Key GOOGLE_SEARCH_ENGINE_ID = "<YOUR_GOOGLE_SEARCH_ENGINE_ID>" # Google 自定义搜索引擎 ID CLAUDE = "<YOUR_CLAUDE_API_KEY>" OPENAI = "<YOUR_OPENAI_API_KEY>" GEMINI = "<YOUR_GEMINI_API_KEY>" MISTRAL = "<YOUR_MISTRAL_API_KEY>" GROQ = "<YOUR_GROQ_API_KEY>" NETLIFY = "<YOUR_NETLIFY_API_KEY>" [API_ENDPOINTS] BING = "https://api.bing.microsoft.com/v7.0/search" GOOGLE = "https://www.googleapis.com/customsearch/v1" OLLAMA = "http://127.0.0.1:11434" # 本地 Ollama 服务地址 LM_STUDIO = "http://localhost:1234/v1" # LM Studio 兼容端点 OPENAI = "https://api.openai.com/v1" [LOGGING] LOG_REST_API = "true" # 是否记录 REST API 调用 LOG_PROMPTS = "false" # 是否记录提示词内容（调试用） [TIMEOUT] INFERENCE = 60 # LLM 推理超时（秒），超过则报错重试

上述每一项配置都与源码中的读取方法一一对应（见 src/config.py 的get_*系列方法）：例如BING/GOOGLE_SEARCH/GOOGLE_SEARCH_ENGINE_ID供 src/browser/search.py 中的搜索引擎使用；OLLAMA/LM_STUDIO/OPENAI端点由 src/llm/ 各客户端消费；TIMEOUT.INFERENCE控制 src/llm/llm.py#L111-L139 中的推理超时逻辑。

模型与运行前提

• 选择不同 LLM 供应商时，需在配置中填入对应 API Key；使用 Ollama 本地模型的安装与模型拉取说明见 docs/Installation/ollama.md。
• 项目运行入口为 devika.py，服务端默认监听127.0.0.1:1337（PDF 下载接口、WebSocket 推送等均基于该端口，见 src/socket_instance.py）。
• 配置的读取依赖工作目录下的config.toml，首次运行会自动从sample.config.toml生成。

设计原则与总结

Devika 通过组合多种 AI 与自动化技术，构建了一个智能编程助手。其架构设计遵循四项核心原则：

• 模块化（Modularity）：将功能拆分为专门化的子 Agent 与服务，各组件独立实现、统一编排；
• 灵活性（Flexibility）：以可插拔方式支持不同 LLM、搜索引擎与外部服务；
• 持久化（Persistence）：项目与会话状态落库 SQLite，支持暂停/恢复与审计；
• 透明性（Transparency）：实时向用户呈现 Agent 的思考过程（内部独白）、浏览器会话与终端输出。

从 src/agents/agent.py 的编排入口，到 src/llm/llm.py 的模型抽象，再到 src/project.py 与 src/state.py 的持久化支撑，Devika 的 Agent 化架构为承担越来越复杂的软件工程任务提供了坚实基础。理解各组件如何协同工作，是扩展、优化与规模化 Devika 能力的起点。

【免费下载链接】devikaDevika is the first open-source implementation of an Agentic Software Engineer. Initially started as an open-source alternative to Devin.项目地址: https://gitcode.com/GitHub_Trending/de/devika