从最小 Agent 循环到研发闭环：DevMind v0.1 的渐进式落地路线

先让 Agent 完成一次最小但真实的思考与执行循环，再逐步接入桌面端、本地工具、权限、Jira、GitLab、知识库和 Workflow。DevMind 的第一版不追求一次性完成全部架构，而是让每次迭代都能运行、验证，并成为下一阶段的可靠基础

前面已经完成了 DevMind 的场景梳理、MVP 需求和总体设计。真正进入编码阶段后，新的问题出现了：四套系统、八个应用、多个外部事实系统和一整条研发流程，到底应该从哪里开始？

如果直接按照最终架构同时创建八个应用，很容易花大量时间处理登录、数据库、消息、部署和页面框架，却迟迟看不到 Agent 真正工作。反过来，如果只写一个调用大模型的聊天 Demo，又可能与最终系统相距太远，后面不得不整体重构。

因此，我准备采用渐进式落地：先实现一个不依赖 Jira、GitLab、知识库和 Workflow 的最小 Agent 循环，然后围绕同一套核心对象逐步增加能力。每个阶段都必须形成可以运行、可以测试、可以演示的小闭环，而不是只完成一批孤立的接口或页面。

1. 先明确落地方法：纵向闭环，而不是横向铺系统

DevMind 最终由 Agent 主系统、用户权限系统、知识库系统和 Workflow 系统协作完成，代码层面对应四个前端和四个后端。但"最终需要八个应用"不等于"第一天就要并行开发八个应用"。

更合适的顺序是先把 Agent 主系统做成骨架，再让其他系统随着真实需求进入。最开始只运行 devmind-server；模型循环稳定后接入 devmind-desktop；当内部资源需要正式授权时再实现 Permission；当 Agent 开始产生知识资料时再接入 Knowledge；当多个阶段和人员需要确定性流转时再加入 Workflow。

这是一种纵向切片方式。每次迭代都从用户入口走到最终结果，区别只是闭环逐步变长：

arduino 复制代码

模型调用
→ 模型 + 本地测试工具
→ Desktop + Server 对话
→ 可暂停和恢复的 Agent Runtime
→ Server 远程调用 Desktop 本地工具
→ 本地代码修改与验证
→ Jira、GitLab 和发布平台 Mock
→ 知识自动沉淀
→ 固定 Workflow 驱动完整研发流程

这种顺序还有一个好处：很多设计不会停留在纸面上。比如 Checkpoint 应该保存什么、确认记录如何绑定参数、WSS 断线后怎样恢复，都可以在能力第一次需要时用真实运行结果来验证。

2. MVP 最终要跑通什么

渐进式开发并不意味着目标模糊。DevMind v0.1 最终仍然要完成一条确定的研发闭环：读取真实 Jira 需求，检索企业知识并分析前后端代码；为涉及修改的代码项目创建开发子 Jira 和需求发布单；在本地完成代码修改、自测、提交和 Push；创建 Merge Request 并合并到长期 test 分支；通过发布平台 Mock 生成测试构建记录；用户手动启动本地测试环境后，由 Agent 执行 Playwright 和接口验证；最后把正式报告写入新知识库并回写 Jira。

MVP 不接入腾讯云，不实现真实 CI/CD，也不自动执行生产发布。测试环境由用户在本地启动，Agent 负责核对环境地址和 Commit、执行自动化验证并记录结果。这样能够保留真实研发链路中的对象关系和控制边界，同时把基础设施成本控制在个人实践项目可以承受的范围内。

3. 整体迭代路线

阶段	核心目标	主要产物	完成标志
M0	建立工程基线	Monorepo、配置、日志、测试骨架	`devmind-server` 可独立启动
M1	最小 Agent 循环	模型适配、Tool Registry、手写循环	模型能自主调用本地测试工具并结束
M2	Desktop 对话闭环	Electron 页面、SSE、取消与错误展示	桌面端可完成多轮对话和流式输出
M3	持久化 Agent Runtime	Task、Thread、Run、Step、Checkpoint	Server 重启后可恢复执行上下文
M4	本地工具远程执行	WSS、设备注册、工作区和工具协议	Server 可受控调用 Desktop 工具
M5	本地代码任务闭环	项目任务、文件修改、Diff、自测	在测试仓库完成一次可审核代码改动
M6	权限与确认	登录、RBAC、授权决策、确认记录	高影响动作不能绕过授权和确认
M7	外部研发系统接入	Jira MCP、GitLab MCP、发布平台 Mock	研发对象和分支链路可以真实联动
M8	知识库接入	文档迁移、解析、检索和 Artifact 版本	历史知识可检索，新产物可自动沉淀
M9	固定 Workflow 接入	流程节点、门禁、事件和缺陷子流程	业务等待和多阶段流转可恢复
M10	端到端验收	完整演示、故障测试、可观测性	同一需求可稳定完成整个 MVP 闭环

这里的编号表示能力依赖，不是固定工期。某个阶段如果不能稳定运行，就不进入依赖它的下一阶段。页面美化、通用化和高级 Agent 能力也不能代替当前阶段的完成标准。

4. M0：先建立不会阻碍试验的工程基线

第一步只创建当前真正会运行的项目：Monorepo 根目录、apps/devmind-server 和必要的工程配置。devmind-desktop 可以在 M2 再创建，其余六个应用在能力进入对应阶段时加入。README 中先固定八个应用的最终命名和职责，不需要用空项目提前占位。

devmind-server 使用 Python、FastAPI 和 Pydantic Settings，先建立统一配置、结构化日志、异常格式、Trace ID、健康检查和测试目录。模型密钥只从环境变量或本地安全配置读取，不写入仓库，也不进入普通日志。

这个阶段不启动 PostgreSQL、Redis、MinIO、Elasticsearch 或 Neo4j，也不接入任何公司系统。目标只是确保开发命令、测试命令和配置方式稳定，让后面的 Agent 实验不会建立在混乱的工程脚手架上。

完成标准： 新环境按照 README 可以启动 Server；健康检查可用；缺少模型配置时返回清晰错误；最小单元测试和代码检查能够执行。

5. M1：实现第一个不依赖其他系统的 Agent Loop

这一阶段是整个项目真正的起点。它不接 Jira、不查知识库、不操作代码仓库，只验证 Agent 最核心的运行机制：模型收到上下文后决定直接回答还是调用工具；程序执行工具并把结果放回上下文；模型基于新结果继续判断，直到给出最终答案或达到停止条件。

sql 复制代码

用户消息
  ↓
组装模型输入
  ↓
调用大模型
  ├── 返回最终文本 → 结束
  └── 返回 Tool Call
          ↓
      校验工具和参数
          ↓
      执行工具并记录结果
          ↓
      把 Tool Result 放回消息列表
          └────────────→ 再次调用模型

最开始可以使用 LangChain 提供的模型与 Tool 抽象，但循环本身先手写。这样能够真正理解消息、Tool Call、Tool Result、停止条件和异常之间的关系，而不是一开始就把行为隐藏在复杂框架中。工具只准备少量无外部依赖的测试能力，例如计算器、当前时间和读取固定示例文本。

代码至少拆成四个边界：ModelGateway 负责模型调用，ToolRegistry 负责工具注册与参数 Schema，AgentLoop 负责循环和停止条件，RunContext 保存本次执行所需的消息与元数据。业务代码只依赖这些内部接口，不直接散落具体模型厂商的 SDK 调用。

第一个循环就要有最大步数、模型超时、工具超时、取消信号和统一错误，而不是用一个没有退出保护的 while true。工具参数必须经过 Schema 校验；不存在的工具、非法参数和工具异常都应转换为结构化 Tool Result，让模型可以解释失败，但不能自行修改安全规则。

完成标准： 至少用自动化测试覆盖直接回答、一次工具调用、多次工具调用、非法参数、工具失败、模型失败和达到最大步数七种路径；同一问题的完整执行过程可以通过 Run ID 查询。

6. M2：把最小循环接入 DevMind Desktop

Server 中的 Agent Loop 稳定后，再创建 devmind-desktop。Desktop 使用 Electron、React 和 TypeScript，第一版只实现会话列表、消息区、输入框、运行状态、停止按钮和错误展示，不急着加入项目、流程、排期和复杂工作台。

Renderer 只负责界面，Electron Main 负责窗口、系统能力和安全边界，Preload 通过受控 IPC 暴露最小接口。不要为了开发方便在 Renderer 开启任意 Node.js 能力。即使此时还没有本地文件工具，也应从第一天保持 contextIsolation 和 IPC 白名单。

Desktop 通过 HTTP 创建 Run，通过 SSE 接收模型文本、Tool Call、Tool Result、完成和错误事件。SSE 适合 Server 向界面单向推送 Agent 输出；双向本地工具调用暂时不进入这一阶段，后续单独通过 WSS 实现。

完成标准： 用户可以在 Desktop 创建普通对话任务，看到流式输出和工具执行过程，能够主动停止 Run；刷新窗口后至少可以重新读取当前会话记录。

7. M3：从聊天循环升级为可恢复的 Agent Runtime

当系统只有一次性对话时，一个内存消息数组就够了；但后面会出现人工确认、Desktop 离线、外部系统等待和 Server 重启，必须把执行过程正式建模。此时再引入 PostgreSQL、LangGraph 和 Checkpoint，比在第一天就设计所有状态更容易把边界想清楚。

核心对象包括 Task、Thread、Message、Run、Step、Tool Call、Checkpoint、Confirmation 和 Artifact。Task 表示用户长期任务，Thread 保存对话，Run 表示一次智能执行，Step 和 Tool Call 记录执行过程。Workflow 的业务节点不属于 Agent Runtime，后面由独立 Workflow Service 管理。

LangGraph 在这里开始发挥价值：它负责显式状态、节点、条件边、Interrupt 和恢复；Checkpoint 保存可恢复的图状态。已经存在的 ModelGateway 和 ToolRegistry 继续复用，避免为了使用框架重写全部业务代码。

恢复不能简单地从异常位置再次调用工具。每个有副作用的动作都要有幂等键和核验逻辑；恢复前先读取执行记录和目标事实，再判断上一步是未执行、已成功、失败还是结果未知。

完成标准： 在模型调用前后、工具执行前后和等待确认时主动中断 Server，重新启动后能够恢复；已经成功的测试工具不会被重复执行。

8. M4：建立 Server 到 Desktop 的本地工具通道

DevMind 与普通 Web Agent 的主要区别，是它需要在用户电脑上操作真实代码、文件、终端和浏览器。因此本地工具不能直接放在 Server，也不能让模型生成任意 Shell 后无条件执行。

Desktop 登录后通过 WSS 注册设备、客户端版本、可用工具和工作区。Server 发出带 Task ID、Run ID、Tool Call ID、幂等键、超时和参数的调用；Desktop 校验工具白名单和工作区边界后执行，并持续回传开始、进度、结果、失败或取消事件。

第一批本地工具只做只读能力：列出工作区、读取文件、搜索文本、查看 Git 状态和获取 Diff。协议稳定后再加入 Patch、测试命令、Commit 等写操作。所有路径都必须经过真实路径解析，最终目标必须位于任务绑定的工作区根目录内。

断线时 Server 把调用标记为 UNKNOWN，不能直接重试。Desktop 重连后根据 Tool Call ID 查询本地 SQLite 执行记录并回报结果，Server 再决定继续、失败或要求人工处理。

完成标准： Server 可以调用指定 Desktop 的只读工具；伪造路径、工作区外路径和未注册工具会被拒绝；WSS 断开再连接后不会重复执行同一个调用。

9. M5：先在本地仓库完成一次代码研发闭环

外部系统接入之前，先用两个本地测试仓库验证真实代码任务：一个前端项目和一个后端项目。它们可以来自 FastAPI 官方全栈模板的前后端部分，也可以是为 DevMind 演示准备的简化业务系统。

Desktop 新增项目任务，绑定仓库和本地目录。Agent 读取任务描述，搜索代码，生成修改方案；用户确认后执行 Patch，运行格式检查、类型检查、单元测试和构建，再展示 Diff、自测结果和建议的 Commit Message。第一轮可以只生成 Commit 而不 Push，把风险限定在本地可恢复范围内。

这个阶段必须开始区分"模型建议"和"实际结果"。模型说测试通过不算通过，必须以真实命令退出码和测试报告为准；模型说文件已经修改也不算完成，必须重新读取文件和 Git Diff 核验。

完成标准： 从一条自然语言需求开始，Agent 能在绑定工作区内完成代码分析、方案确认、文件修改、自测、Diff 审核和本地 Commit；失败时可以清楚指出失败步骤，不破坏工作区外文件。

10. M6：在开放外部写操作前补齐权限和确认

M5 已经在单用户开发模式下使用工作区白名单、Diff 确认和本地执行记录约束代码修改；但在开放多人登录，或启用 Jira 创建、GitLab Push、Merge Request 与合并等跨系统写操作前，必须实现最小 Permission 系统。安全边界应当随着能力风险一起前移，不能等全部功能完成后再补。

这一阶段加入 permission-server 和最小 permission-web，实现本地账号、不可删除的管理员、RBAC、系统与接口权限、Agent 工具权限、项目绑定权限、Desktop 工作区权限和审计。Jira 与 GitLab 的 Issue、项目、仓库及分支权限仍由各自系统校验，Permission Service 不复制这些外部权限。

高影响动作统一使用"计划---预览---确认---执行---核验"。确认只针对当前参数快照，参数、目标资源或内容发生变化后必须重新确认；人工确认也不代表获得 Jira 或 GitLab 权限。

完成标准： 用户不能通过直接调用 API 绕过页面限制；模型不能改变授权结果；文件写入、Commit、Push、创建 Jira 和合并 MR 等动作都有独立的授权、确认和审计记录。

11. M7：按真实研发顺序接入 Jira、GitLab 和发布平台 Mock

外部系统不要一次全部接完，而应按照真实业务链逐段延长闭环。

先接 Jira。 实现读取主需求、附件与评论，以及创建开发子 Jira、回写评论和资料链接。先完成只读，再开放写入；写入使用幂等键，超时后先查询实际结果，不能直接重试创建。

再接 GitLab。 实现项目查询、分支与 Commit 查询、创建 Merge Request 和合并。Clone、Fetch、Checkout、Commit 和 Push 仍在 Desktop 执行；GitLab MCP 负责服务端 API。所有调用使用当前用户绑定的凭证，401 和 403 转换为可处理错误，不切换到更高权限账号。

最后接发布平台 Mock。 发布平台 Mock 作为 devmind-server 的内部模块，保存需求发布单、长期测试发布单和模拟 Build Execution。创建需求发布单时由 Mock 返回需求分支；触发测试发布只生成构建记录，不运行真实 CI/CD。用户手动启动本地测试环境并提交地址和实际 Commit 后，Agent 才开始 Playwright 与接口验证。

完成标准： 同一主 Jira 能关联前端、后端开发子 Jira，两个代码项目各自关联需求发布单和需求分支；代码可以经过人工确认 Push、创建 MR、合并到长期 test 分支，并生成对应的模拟测试构建记录。

12. M8：让知识在产生价值时进入

知识库不是最小 Agent Loop 的前置条件，但当 Agent 开始生成需求理解、开发方案、自测方案和测试报告时，知识的版本、引用和归属就成为真实需求。此时加入 knowledge-server 和 knowledge-web，先实现文档上传、原文件保存、解析、全文与向量检索、引用返回和版本管理。

项目正式上线新知识库之前，通过旧知识库 MCP 统一导入并解析原有文档；上线后，Agent 生成或更新知识型 Artifact 时自动创建 DRAFT 版本并触发解析。用户确认某个不可变版本后，将其提升为 FORMAL，再把链接回写 Jira。新知识库不复制 Jira、GitLab、Workflow 和发布平台中的实时事实数据。

完成标准： Agent 能检索带来源的知识片段，历史文档迁移结果可追踪，正式 Artifact 能自动入库、解析并保留不可变版本。

13. M9：用固定 Workflow 管理业务等待

当一次研发任务需要跨多个阶段等待、流转和恢复时，再加入 workflow-server 与 workflow-web。MVP 只实现固定流程模板、节点状态、参与者、门禁、事件和独立缺陷修复子流程，不实现通用拖拽式流程设计器。

Agent Run 与 Workflow Node 必须分开：Run 可以在几分钟内成功、失败或取消，Workflow 节点可能等待人员或环境数天。等待期间结束当前 Run，由 Workflow 保存业务状态；条件满足后创建新的 Run 继续处理。

完成标准： 固定 Workflow 能驱动需求分析、方案确认、开发自测、等待环境、测试验证和产物归档；单个缺陷回归失败只重新打开对应缺陷，不回退整个主流程。

14. M10：用一条真实需求完成端到端验收

最后一个阶段不再增加大模块，而是用一条真实需求反复验证所有系统之间的契约。验收主线应同时涉及前端和后端，并覆盖需求理解、代码修改、分支、发布记录、测试环境和知识产物。

从 Jira 读取主需求，并结合新知识库生成带引用的需求理解。
分析前端、后端仓库，输出涉及项目、影响范围和开发方案。
确认后为每个项目创建开发子 Jira 和需求发布单，取得需求分支。
Desktop 拉取分支，在受控工作区修改代码并完成自测。
人工确认 Diff 后 Commit、Push、创建 MR，并合并到长期 test 分支。
调用长期测试发布单生成模拟 Build Execution。
用户启动本地前后端环境，提交地址和实际 Commit。
Agent 核对 Commit，执行 Playwright、接口测试和回归检查。
将需求理解、开发方案、自测报告和测试报告形成正式知识版本，并把链接回写 Jira。

除了成功路径，还要主动验证模型超时、工具超时、Desktop 离线、Server 重启、重复点击确认、Jira 写入响应丢失、GitLab 权限不足、MR 冲突、环境 Commit 不一致、知识解析失败和 Workflow 重复事件等故障。只有失败结果可观察、可恢复且不会重复产生副作用，MVP 才算真正闭环。

15. 技术应该在什么时候引入

技术	建议引入阶段	在 DevMind 中的作用
FastAPI	M0	提供 Server API、依赖注入、配置、错误处理和健康检查。
LangChain	M1	统一模型、消息和 Tool 适配，降低模型厂商差异。
LangGraph	M3	在需要状态、分支、Interrupt、Checkpoint 和恢复时管理 Agent Runtime。
Deep Agents	MVP 主闭环稳定后	用于更长任务的规划、上下文管理和受控子 Agent；不作为第一个循环的前置条件。
SSE	M2	Server 向 Desktop 流式推送文本和运行事件。
WSS	M4	Server 与 Desktop 双向通信，远程调用本地工具并回传进度。
MCP	M7	统一封装 Jira、GitLab、发布平台和知识库等 HTTP 能力。
PostgreSQL	M3	保存 Agent Runtime、Checkpoint 和后续业务服务数据。
Redis	M9 或出现真实异步需求时	承载跨服务事件、短期状态和通知，不为"架构完整"提前加入。

这里最重要的原则不是排斥框架，而是让框架在问题真实出现时解决问题。先理解最小循环，再使用 LangGraph 管理复杂状态；先跑通单 Agent，再判断是否需要 Deep Agents。这样学到的不只是 API，而是每项技术为什么存在。

16. 每个阶段都遵守同一套工程约束

所有外部内容都不可信。 Jira 描述、知识片段、仓库文件、网页文本和工具输出只能作为数据，不能覆盖系统策略、权限和工具规则。

模型判断不等于事实。 文件是否修改、测试是否通过、分支是否合并、发布是否成功，都必须重新读取对应事实源核验。

有副作用的动作必须可识别。 工具契约声明执行位置、副作用、风险、鉴权方式、确认策略和幂等能力；高风险动作绑定参数快照。

日志与业务产物分开。 大模型消息、工具日志、截图、测试报告和正式知识文档使用不同的保存与展示方式，敏感信息在进入日志和模型上下文前脱敏。

每个阶段必须有测试。 核心循环优先单元测试，Server 与 Desktop 使用协议和集成测试，外部 MCP 使用契约测试，最终流程使用端到端测试。不能把最后一次人工演示当成唯一验证方式。

17. 第一轮真正开始编码的任务清单

完成这份路线后，第一轮开发只聚焦 M0 和 M1，不创建其他六个系统，也不接入 Jira 和 GitLab。具体任务如下：

初始化 Monorepo 和 apps/devmind-server。
建立 FastAPI、配置、日志、Trace ID、错误格式和健康检查。
定义 ModelGateway、ToolRegistry、AgentLoop 和 RunContext。
接入一个模型提供方，并隔离模型厂商配置。
实现计算器、当前时间和固定文本读取三个无副作用工具。
实现最大步数、超时、取消和结构化错误。
补齐七条核心执行路径的自动化测试。
提供一个临时命令行入口或最小 HTTP 接口，用来演示完整循环。

这一轮结束时，界面可以不存在，数据库也可以不存在，但 Agent Loop 必须真实可运行、执行过程可观察、失败路径可解释。第二轮再把这套能力接入 Desktop，而不是在循环尚未稳定时同时调试 Electron、网络和模型。

18. 后续文章拆分

手写一个最小 Agent Loop：模型、工具与停止条件
Electron 与 FastAPI 如何完成流式 Agent 对话
用 LangGraph 和 Checkpoint 构建可恢复的 Agent Runtime
通过 WSS 让 Server 安全调用 Desktop 本地工具
从自然语言需求到本地代码修改与自测
给 Agent 补上 RBAC、人工确认、幂等和审计
接入 Jira、GitLab 和发布平台 Mock
让研发知识自动入库、解析、检索和版本化
用固定 Workflow 串起研发流程与缺陷子流程
用一条真实需求验收 DevMind v0.1

19. 结语

DevMind 的最终架构很大，但第一行代码不应该从"搭完八个系统"开始，而应该从"让一次 Agent 执行真正闭环"开始。

最小循环让我理解模型和工具如何协作；Desktop 让我面对本地执行和安全边界；Checkpoint 让我处理暂停与恢复；权限、MCP、知识库和 Workflow 则在业务链逐步变长时自然出现。它们不是为了凑齐一张架构图，而是为了解决上一阶段已经暴露出的真实问题。

接下来，我会先实现 M0 和 M1：在 devmind-server 中完成一个不依赖任何企业系统、可以调用本地测试工具、具有停止与错误边界的最小 Agent Loop。等这个最小核心稳定后，再让它进入 DevMind Desktop。