先让 Agent 完成一次最小但真实的思考与执行循环，再逐步接入桌面端、可恢复 Runtime 与安全本地工具。DevMind MVP v0.1 到 WSS 调用 Desktop 本地工具为止；Knowledge、Permission 与 Jira MCP 从 MVP v0.2 开始。
前面已经完成了 DevMind 的场景梳理、MVP 需求和总体设计。真正进入编码阶段后，新的问题出现了：四套系统、八个应用、多个外部事实系统和一整条研发流程，到底应该从哪里开始？
如果直接按照最终架构同时创建八个应用，很容易花大量时间处理登录、数据库、消息、部署和页面框架，却迟迟看不到 Agent 真正工作。反过来，如果只写一个调用大模型的聊天 Demo，又可能与最终系统相距太远，后面不得不整体重构。
因此，我准备采用渐进式落地：先实现一个不依赖 Jira、GitLab、知识库和 Workflow 的最小 Agent 循环，然后围绕同一套核心对象逐步增加能力。每个阶段都必须形成可以运行、可以测试、可以演示的小闭环，而不是只完成一批孤立的接口或页面。
1. 先明确落地方法：纵向闭环，而不是横向铺系统
DevMind 最终由 Agent 主系统、用户权限系统、知识库系统和 Workflow 系统协作完成，代码层面对应四个前端和四个后端。但“最终需要八个应用”不等于“第一天就要并行开发八个应用”。
更合适的顺序是先把 Agent 主系统做成骨架，再让其他系统随着真实需求进入。最开始只运行 devmind-server；模型循环稳定后接入 devmind-desktop；当内部资源需要正式授权时再实现 Permission；当 Agent 开始产生知识资料时再接入 Knowledge；当多个阶段和人员需要确定性流转时再加入 Workflow。
这是一种纵向切片方式。每次迭代都从用户入口走到最终结果，区别只是闭环逐步变长：
MVP v0.1
→ 模型调用与最小 Agent Loop
→ Desktop + Server 流式对话
→ 可暂停和恢复的 Agent Runtime
→ Server 安全调用 Desktop 本地工具
MVP v0.2
→ Permission 与 Knowledge
→ 只读 Jira MCP 与权限感知知识检索
后续版本
→ 代码研发、GitLab、发布平台与 Workflow
这种顺序还有一个好处：很多设计不会停留在纸面上。比如 Checkpoint 应该保存什么、确认记录如何绑定参数、WSS 断线后怎样恢复，都可以在能力第一次需要时用真实运行结果来验证。
2. MVP v0.1 最终要跑通什么
DevMind v0.1 的目标收敛为一条 Agent 运行基础闭环：用户从 Electron Desktop 发起对话，FastAPI Server 运行 Agent Loop；界面通过 AG-UI 持续显示文本、工具调用和运行状态；LangGraph 与 PostgreSQL Checkpoint 支持中断、人工确认和 Server 重启恢复；当模型需要读取本地工作区时，Server 通过经过认证的 WSS 通道调用指定 Desktop 的受控只读工具。
v0.1 不读取 Jira、不建设知识库、不实现独立 Permission 和 Workflow，也不完成代码修改、Push、Merge Request 或发布。它的完成标志是 Agent 执行底座稳定、协议边界清楚、本地工具不会越界或重复执行，并能为 v0.2 的 Knowledge、RBAC 与 Jira MCP 提供可靠基础。
3. 整体迭代路线
| 阶段 | 核心目标 | 主要产物 | 完成标志 |
|---|---|---|---|
| M0 | 建立工程基线 | Monorepo、配置、日志、测试骨架 | devmind-server 可独立启动 |
| M1 | 最小 Agent 循环 | 模型适配、Tool Registry、手写循环 | 模型能自主调用无副作用工具并结束 |
| M2 | Desktop 对话闭环 | Electron、AG-UI、流式消息与工具卡片 | Desktop 可完成真实多轮 Agent 对话 |
| M3 | 可恢复 Agent Runtime | LangGraph、PostgreSQL Checkpoint、Interrupt/Resume | Server 重启后可恢复原 Thread |
| M4 | 本地工具远程执行 | Ticket、WSS、设备、工作区、只读工具和幂等 | Server 可安全调用指定 Desktop，v0.1 完成 |
编号表示能力依赖，不是固定工期。M1～M4 分别对应本路线下面已经完成的四篇实践文档；子文档继续作为实现事实，本路线只负责说明它们共同组成的版本边界。
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 最核心的运行机制：模型收到上下文后决定直接回答还是调用工具；程序执行工具并把结果放回上下文；模型基于新结果继续判断，直到给出最终答案或达到停止条件。
用户消息
↓
组装模型输入
↓
调用大模型
├── 返回最终文本 → 结束
└── 返回 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. MVP v0.2 及后续演进
M4 完成后，DevMind 已拥有 Agent Loop、Desktop 交互、LangGraph Runtime、Checkpoint 和本地工具安全通道。下一步进入独立的 MVP v0.2，而不是继续把 Knowledge、Permission、Jira、GitLab 和 Workflow 塞进 v0.1。
v0.2 从零实现 knowledge-web、knowledge-server、permission-web 与 permission-server。知识库覆盖文档管理、版本、审核发布、多格式解析、全文检索、向量检索、混合召回、AI 问答、引用、知识图谱和统计；Permission 先实现登录、用户、角色、权限和知识资源访问控制。完成基础系统后，现有 Agent 接入 Knowledge MCP 与只读 Jira MCP，验证“读取 Jira—提取检索条件—按当前用户权限检索知识—生成带引用分析”的闭环。
GitLab、代码自动修改、发布平台、固定 Workflow 和完整研发流程继续放到 v0.2 之后，避免知识与权限底座尚未稳定时再次扩大范围。
10. 技术应该在什么时候引入
| 技术 | 引入阶段 | 在 DevMind 中的作用 |
|---|---|---|
| FastAPI | M0 | Server API、配置、错误处理和健康检查 |
| LangChain | M1 | 统一模型、消息和 Tool 适配 |
| AG-UI | M2 | Agent 与 Desktop 的标准流式交互 |
| LangGraph | M3 | 状态、条件边、Interrupt、Checkpoint 和恢复 |
| PostgreSQL | M3 | Checkpoint 与 Runtime 领域数据；v0.2 继续承载知识和权限元数据 |
| WSS / RPC | M4 | Server 安全调用 Electron Main 本地工具 |
| Redis | v0.2 出现异步解析与跨服务协调时 | 缓存、任务协调、事件和短期状态 |
| pgvector | v0.2 | Knowledge Chunk 的向量存储与语义检索 |
| Elasticsearch | v0.2 | 文档级与 Chunk 级关键词检索 |
| Neo4j | v0.2 | 实体、关系和图谱查询 |
| MCP | v0.2 | 标准化 Knowledge 与 Jira 等服务端能力 |
| Deep Agents | 主闭环稳定后 | 更长任务的规划与受控子 Agent，不作为 MVP 前置条件 |
框架只在问题真实出现时进入。v0.1 先证明 Agent 可以稳定、安全地运行；v0.2 再证明它可以在身份与权限约束下使用企业知识。
11. 每个阶段都遵守的工程约束
所有外部内容都不可信。模型判断不等于事实，工具结果必须核验；有副作用的动作必须声明风险、确认和幂等能力；Checkpoint 不替代外部事实核验；日志、执行产物和正式知识文档分开保存；每个阶段都必须有自动化测试和可重复验收步骤。
12. v0.1 编码与验收清单
- M1 完成 ModelGateway、ToolRegistry、AgentLoop、RunContext 和核心测试。
- M2 完成 AG-UI Mock、真实 Agent Adapter、Electron Renderer 和工具展示。
- M3 完成 LangGraph、PostgreSQL Checkpoint、Interrupt/Resume 和重启恢复。
- M4 完成短期 Ticket、WSS、设备注册、只读工具、路径安全和本地执行记录。
- 覆盖用户拒绝、工具超时、Desktop 断线、Server 重启、重复调用和 UNKNOWN 对账。
- 确认四篇实践子文档的验收项全部通过后，宣布 MVP v0.1 完成。
13. 后续文章与版本文档
MVP v0.1 的实现文章固定为下面四篇，均已作为本路线子文档存在：
- 手写一个最小 Agent Loop：模型、工具与停止条件
- Electron 与 FastAPI 如何完成流式 Agent 对话
- 从手写 Loop 到可恢复 Runtime：用 LangGraph、PostgreSQL Checkpoint 与 AG-UI 跑通中断恢复
- 通过 WSS 让 Server 安全调用 Desktop 本地工具
MVP v0.2 不在本路线下继续增加实现子文档，而是使用独立的 v0.2 需求文档与总体设计作为版本基线，再按知识库、权限和 Agent 集成的实施阶段补充后续实践记录。
14. 结语
DevMind v0.1 到 M4 为止，已经完成了从最小模型工具循环到可恢复 Agent Runtime，再到 Server 安全调用 Desktop 本地能力的完整基础链路。
这不是完整企业研发 Agent，却是后续所有企业能力真正能够落地的前提。v0.2 将沿用这套执行底座，开始解决企业知识如何进入、如何被权限约束，以及 Agent 如何读取 Jira 后基于可信知识给出可引用结论。
