1. 为什么先写一份整体设计
前面几篇文章里，我逐步明确了这个实践项目的出发点：不从框架名词和功能清单开始，而是先构造一个足够真实的企业研发场景，再让需求推动技术选择和架构演进。
真正动手之前，还需要一张覆盖全局的地图。这篇文章就承担这个角色：它会说明项目要解决什么问题、服务哪些研发角色、为什么拆成四个系统和八个工程，以及一条需求如何在 Agent、Jira、GitLab、知识库、流程引擎和发布平台之间流转。页面字段、接口参数、数据库表结构和具体算法，会放到后续详细文档中展开。
需要特别说明的是，这不是针对某一家真实公司的改造方案，而是我为学习和验证企业 Agent 构造的实践项目。我希望借这个项目，把 Agent Runtime、Tool、MCP、RAG、知识图谱、Workflow、RBAC、安全、评测和桌面端本地执行这些能力，放进同一个可以运行、可以联调、也可以不断演进的系统里。
我对这个项目的定位是：不替代 Jira、GitLab 和发布平台，而是在这些既有系统之上增加一个能够理解研发上下文、组织知识、协同流程，并在权限约束下执行动作的智能协作层。
2. 这个项目想解决什么问题
2.1 真正的难点不是少一个工具
企业研发过程通常横跨需求、设计、代码、测试、发布和知识文档。真实困难并不只是缺少某一个功能，而是信息分散在不同系统、系统关系依赖人工理解、协作状态反复同步、研发产物难以持续沉淀，以及自动化动作缺乏统一的权限和审计边界。
研发人员收到一个需求后，需要在多个系统之间查找资料、确认项目与仓库、理解历史方案、拆分任务、安排排期、修改代码、准备测试、处理缺陷并完成发布。Agent 的价值，是把这些分散信息组织成可判断的上下文，将重复操作封装为可控制的工具调用，并将关键决策继续留给真正负责的人。
需求侧还有一个更具体、也更容易被忽略的问题：需求文档通常按项目或迭代保存，却很难按照"功能位置"追踪历史。假设需求 A 修改了菜单 1、2、3，需求 B 又调整了菜单 2，需求 C 再修改菜单 1 下的某个按钮和菜单 3。时间一长，想知道某个页面或按钮为什么变成现在这样，只能逐份翻阅历史文档，必要时还要让前后端开发一起查看代码。
因此，新知识库不能只把文档切片后做向量检索。我会以主 Jira 串起每次需求，再从文档中解析本次新增、修改和删除的功能点，并用稳定身份组织"业务域---系统---项目---菜单---页面---模块---控件或业务规则"这棵功能树。这样查询某个菜单、按钮或规则时，不仅能看到当前结论，还能追溯它在哪些需求中发生过什么变化。
2.2 我希望最终得到什么
- 提供统一的 Agent Desktop，承载普通对话、项目研发和端到端流程协作。
- 连接 Jira、私有 GitLab、发布平台和旧文档平台，减少跨系统查找、复制和重复录入。
- 建设新的企业知识库，对存量资料统一迁移解析，并自动沉淀后续研发知识产物。
- 建设独立的研发 Workflow Service，用确定性状态机管理需求、设计、开发、测试、验收和发布协作。
- 建设统一 Permission Service，对用户、角色、页面能力、接口、工具和数据范围进行授权与审计。
- 让模型负责不确定性的理解、生成和决策辅助，让业务系统负责事实、权限、状态和最终高风险动作。
2.3 哪些事情明确不交给 Agent
- 不替代 Jira、GitLab 和发布平台，也不在 Agent 或知识库中复制它们的事实主数据。
- 不以"一次对话自动完成全部研发"为目标；人员仍负责确认需求、方案、排期、验收和高风险操作。
- 生产发布不允许由 Agent 自动点击完成。Agent 只能检查前置条件、汇总发布单、打开页面和记录结果，最终由测试人员逐单核对并手动发布。
- 流程参与者只能看到已提交的正式产物、状态和必要通知，不能查看其他人员与 Agent 的详细对话。
- 知识库保存知识文档、原文件、版本和检索索引，不保存需求状态、负责人、代码提交、流程节点、发布结果等确定性事实。
3. 先划清边界：谁负责保存事实
| 系统 | 事实主数据 | 本项目的使用方式 |
|---|---|---|
| Jira | 主需求、子任务、缺陷、负责人、状态和验收信息 | Agent 读取与回写；每个研发流程以主 Jira 为业务基线，设计、开发和缺陷分别创建子 Jira。 |
| 私有 GitLab | 仓库、分支、提交、合并请求和流水线结果 | Agent 查询远程信息；Desktop 在用户电脑拉取代码、切换分支、修改文件和运行测试。 |
| 发布平台 | 发布单、环境、版本、构建部署状态和发布结果 | Agent 创建或查询发布单、准备测试环境；生产发布由测试人员人工完成。 |
| 旧在线知识库 / 文档平台 | 项目上线前已有的历史文档与附件 | 仅作为上线前存量迁移源。通过 MCP 批量读取并导入新的知识库；上线后不再写入新的正式研发资料，也不作为事实主库。 |
项目上线前，需要对旧文档平台执行一次可重复、可校验的迁移任务。迁移过程保留源系统、原始链接、原文件、历史版本、修改时间和权限映射，并在新知识库中完成解析、切分、全文索引、向量索引和知识图谱构建。上线后，Agent 生成且经人员确认的需求、设计、开发和测试资料自动写入新知识库并触发解析，不再依赖人工二次上传。
4. 哪些人会参与，他们如何协作
| 角色 | 主要职责 |
|---|---|
| 需求人员 | 创建或绑定主 Jira，提供需求资料，确认需求文档与原型，选择负责人，组织验收并确认是否进入发布。 |
| 设计负责人 / 设计人员 | 接收设计任务、确定执行人员和排期，基于需求产出 HTML Demo 与必要图片，按模块提交正式设计资料。 |
| 开发负责人 / 开发人员 | 确定执行人员与排期，编写开发方案，确认项目和仓库，完成代码修改、自测、测试环境发布和缺陷修复。 |
| 测试负责人 / 测试人员 | 确定测试排期与方案，执行自动化和人工测试，创建和回归缺陷，提交测试报告，并在发布节点人工完成生产发布。 |
| 系统管理员 | 管理用户、角色、权限、系统资源和审计；初始化 admin 用户与默认超级角色不可删除。 |
负责人为单选，设计或开发执行人员可以多选。同一人员可同时拥有多个角色，但每一次动作都以当前用户、当前角色授权、资源范围和流程任务身份共同判断。
5. 四个系统、八个工程：整体架构怎么拆
按照职责边界，我把产品拆成主 Agent、用户权限、知识库和流程引擎四个系统。落实到工程上，一共是八个项目：四个客户端或 Web 前端，配套四个后端服务。Agent Desktop 虽然不是浏览器里的 Web 应用，但它承担统一交互界面、本地执行和设备能力接入，因此也算作一个前端交付物。
| 系统 | 工程 | 建议技术栈 | 核心职责 |
|---|---|---|---|
| 主 Agent | agent-desktop | Electron、React、TypeScript | 统一入口、三类任务、对话与产物展示、项目工作区、排期日历、通知、人工确认和本地工具执行。 |
| agent-server | Python、FastAPI、LangChain、LangGraph、Checkpoint、Deep Agents | Agent Runtime、模型与上下文、计划和步骤、工具调度、MCP 接入、运行恢复、产物管理及跨系统协作。 | |
| 用户权限 | permission-web | React、Vite、TypeScript、Ant Design | 用户、角色、权限资源、菜单按钮和审计管理界面。 |
| permission-server | Python、FastAPI、PostgreSQL、Redis | 统一身份认证、RBAC 授权决策、数据范围、高风险动作确认和审计。 | |
| 知识库 | knowledge-web | React、Vite、TypeScript、Ant Design | 文档管理、智能搜索、AI 问答、知识图谱、解析状态和统计。 |
| knowledge-server | Python、FastAPI、LangChain、LangGraph、Checkpoint、Deep Agents | 文档接入与解析、版本管理、全文与向量检索、图谱构建、RAG 问答、引用和权限过滤。 | |
| 流程引擎 | workflow-web | React、Vite、TypeScript、Ant Design、@xyflow/react | 流程定义、版本发布、实例看板、任务工作台、节点操作和异常处理。 |
| workflow-server | Python、FastAPI、PostgreSQL、Redis | 流程定义与实例、条件分支、并行节点、人员任务、门禁、事件、缺陷子流程、重开与补偿。 |
所有框架在功能匹配、生态稳定和依赖兼容的前提下使用实施时的最新稳定版本；具体版本由各工程锁文件和架构决策记录固定，整体需求不写死易过期的版本号。
6. 为什么 Agent Desktop 要支持三类任务
6.1 流程任务
用户创建会话时选择一个已经由流程引擎发布的流程模板。任务与流程实例、主 Jira、参与人员、正式资料包和节点状态绑定。任务下发到参与者后，其 Desktop 自动收到通知并创建对应流程任务，默认名称为"主 Jira 编号 + 需求摘要"。
6.2 项目任务
用户选择一个或多个远程代码仓库创建研发任务。Agent 检查本地工作区：未克隆则按权限拉取，已存在则更新远程信息；用户确认后，将任务与当前电脑上的真实目录绑定。后续文件读写、代码检索、Git、终端和 Playwright 操作都限定在已绑定工作区及授权范围内。
6.3 普通对话任务
普通对话不要求绑定流程或代码项目，用于知识问答、方案讨论、资料整理和临时分析。用户可以在后续明确操作中将正式产物提交知识库或关联到其他任务，但系统不能因为聊天中出现 Jira、仓库或发布意图就自动扩大执行权限。
6.4 三类任务共享同一套运行模型
- 统一使用 Thread、Run、Step、Tool Call、Checkpoint 和 Artifact 表达会话、执行过程与产物。
- 支持流式响应、暂停、取消、重试、中断恢复、人工确认和失败后继续。
- 支持展示计划、工具调用参数、执行结果、引用来源、风险提示和待确认动作。
- 任务之间默认隔离上下文；需要引用其他任务产物时必须通过正式 Artifact 或授权检索获得。
7. 核心流程任务：企业研发主流程
7.1 需求受理与资料基线
需求人员在 Agent Desktop 创建流程任务，选择项目，让 Agent 创建主 Jira，或直接绑定已有主 Jira。需求资料可以粘贴、上传，也可以从已经完成迁移的新知识库中检索引用。Agent 根据资料生成第一版需求文档和原型，需求人员通过多轮对话审核修改。
确认后的正式版本自动保存到新知识库并立即进入解析索引流程，知识库链接同步回主 Jira。主 Jira 是该需求的业务根节点和资料关联基线；新知识库保存正式文档及版本，两者通过稳定标识关联，但职责不能混淆。
7.2 任务下发与内部排期
需求人员判断是否需要设计，选择开发负责人、测试负责人和可选的设计负责人；负责人再确定实际执行人员。正式资料包以可点击、可下载的知识库链接跟随流程下发。
设计或开发执行人员收到任务后，Agent 首先提醒其给出排期，并在对话中澄清开始时间、结束时间、依赖和风险。人员确认后，排期写入 Agent 产品内部的排期模块并通知流程参与者。流程引擎只消费"排期已确认或已变更"的业务事件，不另建一个外部排期系统。
7.3 设计与开发并行
不需要设计时直接进入开发节点；需要设计时，流程引擎同时开启设计和开发节点。设计节点根据主 Jira 创建设计子 Jira，Agent 先生成可运行的 HTML Demo，设计人员通过自然语言持续调整；只有图标、资源位和必须切图的内容才输出图片。
设计任务可以按模块拆分并分批交付。每次确认后的设计资料自动进入新知识库、触发解析、加入本需求资料包并同步链接到主 Jira。开发人员不必等待全部设计完成，可以先处理框架、接口和不依赖设计的部分。
7.4 开发执行与测试准备
开发人员基于当前正式资料包与 Agent 共同编写开发方案。Agent 从方案中识别涉及的前端、后端及其他仓库，为每个项目创建开发子 Jira，并在发布平台创建关联子 Jira、仓库与分支的发布单。Desktop 拉取或更新代码，切换到发布单对应的开发分支，再由 Agent 辅助修改、检查和测试。
设计和开发启动时，测试准备节点同步进入进行中。开发排期确认后，测试人员结合需求范围和开发计划确认测试排期，Agent 写入内部排期模块并向流程参与者发送通知；后续允许保留原因和版本地修改排期。
7.5 自测与测试准入
开发完成后，开发人员必须使用 Agent 生成自测方案并执行验证。只有满足以下条件，流程任务才可以进入正式测试：
- 开发自测通过并提交自测报告；
- 所有相关项目已经成功发布到测试环境；
- 测试排期已经确认；
- 存在设计节点时，设计任务已完成或经授权明确豁免。
条件未满足时只能发送提醒或处理异常，不能由 Agent 绕过门禁。测试环境发布可以按权限自动或经确认执行，但不等同于最终生产发布。
7.6 测试执行与独立缺陷闭环
测试人员收到任务后，Agent 基于最新需求、设计、开发方案和测试环境生成测试方案。测试人员可以多轮调整用例、优先级、数据准备和执行顺序；确认后，Agent 执行可自动化的部分并记录结果，人工测试结果也进入同一份正式测试报告。
发现问题时不回退整个主流程。Agent 为每个问题创建问题子 Jira 和独立修复任务，主测试节点保持"进行中"，多个缺陷可以并行处理。缺陷建议状态为"待处理 → 修复中 → 开发自测 → 待回归 → 验证关闭"；回归失败只重新打开对应缺陷，不影响其他已经关闭的问题。
测试节点完成前，测试计划必须执行完成，阻断发布的缺陷必须关闭，延期缺陷必须获得明确授权，并提交最终测试报告。
7.7 验收与人工生产发布
测试完成后，Agent 通知所有参与者，并单独提醒需求人员安排验收。验收通过且需求人员确认可以发布后，流程进入由测试人员负责的发布节点。页面列出本次需求关联的全部发布单；测试人员逐个核对并手动点击发布，Agent 不得代替人员完成最终生产发布。
7.8 节点重开与版本影响
需求和设计节点完成后仍允许提出更新。系统保留已完成的历史版本，创建新的正式资料版本，并将对应节点重新置为进行中。Workflow Service 根据变更范围重新计算受影响的开发、测试、验收和发布门禁，通知相关人员。知识库保留资料版本与历史映射，主 Jira 保留业务关联和变更记录。
8. 四个系统的整体功能要求
8.1 主 Agent 系统
- 统一任务中心： 创建、搜索、归档和恢复三类任务，展示流程状态、项目绑定、待确认事项和未读通知。
- Agent Runtime： 管理模型消息、上下文、计划、步骤、工具调用、Checkpoint、Interrupt、Resume、重试、取消和 Artifact。
- 本地工具宿主： 在 Desktop 执行 Git、文件、代码检索、终端、测试和 Playwright；Playwright 浏览器二进制随桌面端安装包交付。
- 远程本地执行： Desktop 与 Server 通过经过认证的 WSS 长连接通信。Server 只能调用用户当前在线 Desktop 已注册且已授权的工具；调用包含唯一 ID、超时、取消、幂等和结果回传。
- 服务端工具接入： Jira、GitLab、发布平台、知识库和流程引擎等 HTTP 能力以受控 Tool 或 MCP 方式内置接入 Agent Server。
- 排期、日历与通知： 作为 Agent 产品内部能力保存人员确认后的排期，提供个人和流程日历视图，并接收 Workflow 事件产生通知。
- 产物管理： 区分对话草稿、待确认产物和正式产物；正式需求、设计、开发和测试资料自动写入新知识库。
8.2 用户权限系统
- 初始化一个不可删除、不可禁用到导致系统失管的 admin 超级管理员，并绑定一个不可删除的默认超级角色。
- 以 RBAC 为主模型，支持用户、角色、权限之间的多对多关系；临时权限优先通过临时角色、限时授权或审批实现，避免无审计的长期用户直授。
- 权限范围不仅包含系统、菜单和按钮，还必须覆盖接口、工具、资源、动作和数据范围，否则无法约束 Agent 的真实执行能力。
- 权限决策至少返回允许、拒绝、需要人工确认或需要审批，并带出决策原因与策略版本。
- 所有高风险工具在执行前重新鉴权，不能只依赖登录时的菜单权限；权限变更后应及时失效并记录审计。
8.3 知识库系统
- 支持文档、表格、演示文稿、文本、网页、图片、音频和视频等知识资料接入，保留原文件、来源、版本、权限和处理状态。
- 上线前通过 MCP 批量迁移旧文档平台资料；上线后接收 Agent 自动提交的正式研发产物，并统一进入异步解析与索引流水线。
- 支持全文关键词检索、向量语义检索、混合召回与重排、Neo4j 知识图谱检索，并在结果中返回可验证引用。
- Knowledge Web 支持文档管理、解析状态、智能搜索、AI 问答、知识图谱和基础统计。
- 需求和设计资料以主 Jira 建立业务关联，同时使用稳定身份组织"业务域---系统---项目---菜单---页面---模块---控件/业务规则"功能树；名称变化、移动、拆分与合并保留历史映射。
- 检索必须执行权限过滤；被召回的片段不能突破原文档与原业务资源的可见范围。
8.4 流程引擎系统
- 支持流程定义、版本、校验、发布和停用；运行中的实例固定使用启动时的流程版本。
- 支持人员节点、Agent 节点和系统节点，以及条件分支、并行、汇聚、定时、提醒、门禁、重试和补偿。
- 支持主流程与独立缺陷子流程，避免一个缺陷导致整个研发流程回滚。
- 支持负责人和执行人员、资料包、节点产物、评论、操作记录、重新打开与影响范围重算。
- 以事件驱动方式通知 Agent Server 和 Desktop；重复事件、网络重试和服务重启不能造成重复建单或重复推进节点。
- 流程状态由 Workflow Service 保存；Agent 的 Checkpoint 只保存一次 Agent Run 的执行状态，二者不得互相替代。
9. 跨系统协作与核心数据关系
9.1 核心标识
每个研发流程需要同时维护流程实例 ID、主 Jira ID、资料包 ID 和参与者信息。设计、开发、缺陷和发布活动分别通过子 Jira ID、仓库 ID、分支、发布单 ID 与主 Jira 关联。所有跨系统关系保存稳定 ID，显示名称仅用于展示，不能作为唯一关联键。
9.2 关键对象的归属
| 对象 | 归属系统 | 说明 |
|---|---|---|
| Thread、Run、Step、Tool Call、Artifact | Agent Server | 描述一次人机协作和 Agent 执行过程。 |
| 本地项目路径、终端会话、本地工具状态 | Agent Desktop | 只在用户设备侧保存或加密同步必要元数据。 |
| 用户、角色、权限、策略、审计决策 | Permission Server | 统一授权来源，业务服务不各自维护冲突的角色模型。 |
| 文档、版本、原文件、Chunk、索引、图谱关系 | Knowledge Server | 保存知识资产及派生检索数据，不保存外部事实系统状态。 |
| 流程定义、流程实例、节点实例、工作项、门禁 | Workflow Server | 保存确定性的研发业务流程状态。 |
| 需求、子任务与缺陷事实 | Jira | 通过外部 ID 与流程和资料包关联。 |
| 仓库、分支、提交与合并请求 | GitLab | 本地工作区只是受控执行副本。 |
| 发布单与发布结果 | 发布平台 | Workflow 只记录关联和节点状态。 |
9.3 一致性与幂等
跨服务写操作不依赖分布式数据库事务，而是使用业务幂等键、事件日志、Outbox/Inbox、重试和补偿保证最终一致。创建 Jira、发布单、知识文档或流程任务时，都必须以流程实例、节点、动作类型和目标资源组成稳定幂等键；超时后先查询实际结果，再决定是否重试。
10. 权限、安全与隐私要求
- 默认拒绝。无法识别用户、资源、动作或数据范围时，不允许执行写操作。
- 模型不能自行提升权限，也不能通过 Prompt 覆盖系统策略、工作区范围或审批结果。
- Desktop 的文件、命令、Git 和浏览器工具采用白名单能力、工作区边界和参数校验；危险命令必须阻止或要求明确确认。
- Server 发起本地调用时必须校验用户、设备、会话和任务绑定关系；WSS 使用短期凭证、心跳、断线重连和调用签名。
- Prompt、工具输入输出、文档片段和日志中的密钥、令牌及敏感字段需要脱敏，服务端不得收集无必要的本地文件内容。
- 关键操作记录"谁在何时基于什么权限，对哪个资源执行了什么动作，输入摘要、结果和关联任务是什么"。
- 其他参与者不可见的个人对话不能被直接拼入其上下文；共享必须通过已提交的正式产物、流程事件或授权知识检索实现。
11. 非功能性要求
| 维度 | 整体要求 |
|---|---|
| 可靠性 | Agent Run、解析任务和流程推进可恢复；服务重启后不丢失正式状态；外部写操作具备幂等和补偿。 |
| 可观察性 | 统一记录 Trace ID、任务、模型调用、Token、延迟、工具链路、异常、权限决策和事件积压，并支持按流程实例追踪。 |
| 性能 | 普通管理 API 在排除模型和第三方系统耗时后应保持秒级响应；大文件解析、索引、图谱构建和长时间 Agent 任务全部异步执行并反馈进度。 |
| 扩展性 | 模型、Embedding、Reranker、文档解析器、MCP Server、流程节点和通知渠道均可替换或扩展，核心业务不绑定单一供应商。 |
| 兼容性 | Desktop 支持目标企业操作系统；Playwright 所需浏览器二进制与安装包一起交付并进行版本锁定。 |
| 可测试性 | 核心权限、流程门禁、幂等、检索引用和本地工具边界具备自动化测试；Agent 输出通过固定数据集和回归评测验证。 |
| 可维护性 | 八个工程共享统一接口规范、错误码、事件信封、鉴权方式和可观测字段，同时保持独立部署与清晰数据所有权。 |
12. 分阶段实施范围
12.1 阶段一：纵向 MVP
先验证"输入主 Jira，Agent 读取需求与知识、检索指定仓库、生成带引用的需求理解和任务拆分，用户确认后回写 Jira"的闭环。同步建立最小 Agent Runtime、Desktop 本地工具、Permission 鉴权、Knowledge 检索和审计能力。
12.2 阶段二：项目任务与知识闭环
完善代码工作区绑定、Git 与终端工具、Playwright、正式 Artifact、知识库自动入库解析，以及旧文档平台的批量迁移和校验。
12.3 阶段三：研发主流程
实现流程定义、任务下发、排期、设计与开发并行、自测门禁、测试准备、独立缺陷子流程、节点重开和正式资料包。
12.4 阶段四：验收、发布与工程治理
接入验收与人工生产发布，补齐评测、可观察性、安全测试、故障恢复、成本与性能治理，形成完整演示和架构方法论。
13. 整体验收标准
- 八个工程能够独立启动，并通过统一身份、接口和事件协议完成基本联调。
- 用户可以明确创建流程任务、项目任务和普通对话任务，三类任务的上下文与权限不会串用。
- Agent Server 能安全调用在线 Desktop 的本地工具，支持超时、取消、断线恢复和完整审计。
- 旧文档可通过 MCP 批量迁移到新知识库；后续正式研发资料可自动入库、解析、检索并返回来源引用。
- 权限系统满足不可删除的 admin 和默认超级角色要求，能够控制菜单、按钮、接口、工具、资源动作和数据范围。
- 主流程可以从需求受理走到验收与发布，支持设计可选并行、测试准入、独立缺陷循环和节点重开。
- 生产发布只能由测试人员逐单手动完成，任何 Agent 路径都不能绕过该限制。
- Jira、GitLab、Workflow、Knowledge 和发布平台之间均使用稳定 ID 关联，任一正式结果可以追溯来源、版本、责任人和操作记录。
- 不同参与者只能看到流程要求共享的正式产物和状态，不能访问其他人员的私有 Agent 对话。