一、项目背景与设计目标
1.1 背景描述
传统软件研发流程长期存在三个结构性问题。
第一,节点之间信息割裂。需求工具、代码评审工具、测试管理工具、发布平台各自独立,信息靠人脑和人嘴在节点间搬运,损耗严重。一个需求从提出到上线,平均要在六到八个不同工具之间切换,每次切换都伴随上下文丢失。
第二,AI 能力接入零散。多数团队对 AI 的使用停留在"随手召唤聊天机器人"的阶段,AI 看不到完整的代码库、读不到历史评审记录、不知道上一次发布出了什么问题。模型输出质量受限于上下文质量,而上下文质量受限于工具的组织方式。
第三,临时验证成本过高。研发同学在提交评审之前想快速跑起来看看效果,通常需要排队等待测试环境、申请配额、等待镜像构建,等环境 ready 的时候,编码时的心气已经凉了一半。
1.2 设计目标
本平台旨在构建一条从需求登记到灰度发布的完整流水线,在流水线的每一个节点嵌入 AI 能力,并以一份贯穿全流程的可信知识库作为 AI 输出的上下文护栏。
具体目标分解如下:
- 流程一体化:七个主节点(需求登记、需求生成、技术方案、AI 编码、代码评审、测试验证、发布上线)在同一平台内闭环,节点间状态可追溯。
- AI 在场而非出现:AI 不是被顺手召唤的工具,而是每个节点工位的一部分,持有跨节点上下文。
- 知识库护栏:基于 VKF 知识库与工程图谱,为大模型提供可信上下文,抑制幻觉。
- 临时沙箱独立支线:提供非生产环节的即用即弃测试环境,不污染主流程。
- 决策权留在人手中:AI 给建议,人做决策,关键节点保留人工确认。
1.3 非目标
本平台不追求以下目标:
- 不替代开发者的单元测试设计职责。
- 不替代人工代码评审的最终决策。
- 不做多模型 PK 平台,模型选择由配置决定。
- 不做 CI/CD 底层引擎,流水线执行依赖现有 DevOps 基础设施。
1.4 为什么要建这个平台
回答"为什么"之前,先看研发组织当前真实面临的几组困境。
困境一,AI 能力散落,价值无法沉淀。 过去两年,几乎每个研发团队都在用大模型,但用法高度碎片化。有人在 IDE 里装插件,有人开浏览器聊,有人把代码复制到聊天框。这些用法的问题不在于模型不够强,而在于模型看不到全貌。一个评审者让模型分析某段代码,模型不知道这段代码上一版被谁改过、上一轮评审提过什么意见、需求文档怎么写的。每一次对话都是从零开始,上下文质量决定输出质量,而碎片化用法天生无法提供高质量上下文。结果是,AI 看起来很热闹,真正沉淀到研发流程里的价值很有限。
困境二,工具链割裂,信息靠人搬运。 一个需求从提出到上线,平均经过六到八个独立工具。需求在 Jira,代码在 GitLab,评审在 Gerrit,测试在 TestRail,发布在 Spinnaker,监控在 Grafana。每个工具都是孤岛,信息靠人脑和人嘴搬运。一个发布后的线上问题,要追溯到三周前的需求描述,需要打开五个系统翻历史。搬运的过程里,信息必然损耗,因果链必然断裂。
困境三,临时验证成本失控。 研发同学写完代码想跑起来看看效果,在多数公司是一件需要排队、申请、等待的事。环境不 ready,编码时的心气就凉了。等环境到位,代码的细节已经忘了一半。这种情绪痛点长期被管理者忽视,但它真实地拖慢了迭代节奏。
困境四,流程黑盒,等待不可见。 一个需求卡在哪个节点、为什么卡、卡了多久、谁来推进,在传统流程里往往是一笔糊涂账。看板要么没有,要么是手动维护的 Excel。流程最怕的不是慢,是没人知道慢在哪里,于是无法优化。
这四个困境叠加,直接表现为研发周期长、协作成本高、质量波动大、AI 投入产出不成正比。建这个平台,就是为了系统性解决这四个困境,而不是再做一个工具堆在工具链上。
1.5 平台能带来的核心价值
价值可以从效率、质量、成本、协作四个维度量化。
效率价值:全周期时长压缩。 对话式 PRD 生成把需求文档的修改成本降到一次自然语言输入,研发不再为改 Word 头疼。AI 编码节点把样板代码的产出从小时级压缩到分钟级。临时沙箱把"跑起来看看"的等待从小时级压缩到秒级。综合下来,一个中等复杂度需求的端到端周期,预期能从两周压缩到一周以内。
质量价值:AI 护栏 + 人工决策。 代码评审节点的 AI 建议分级、人工逐条采纳机制,既抓得住异步陷阱、缓存击穿这类高频问题,又不让模型越权拍板。测试验证节点的 AI 业务用例自动生成,把需求里的自然语言翻译成可执行断言,边界覆盖远超人工。Release Notes 自动生成消灭了"懒得写发布说明"这个长期顽疾。质量提升的同时,缺陷逃逸率预期下降 30% 以上。
成本价值:AI 调用精准化 + 资源即用即弃。 模型路由按任务复杂度分流,简单任务走轻量模型,推理密集任务走旗舰模型,token 成本整体可控。临时沙箱 30 分钟自动回收,云资源不再被孤儿容器长期占用。这两项叠加,平台自身的运行成本远低于"每人各自用 AI 工具"的隐性成本总和。
协作价值:等待可见,追溯可查。 看板把流程状态压缩成一个画面,谁卡在哪里一目了然。lineage 追溯链路让任何线上问题都能反向定位到需求源头,责任不再扯皮。这两件事表面是工具改进,深层是组织协作模式的升级。
治理价值:Skill 与 MCP 平台统一收口工具,流程强制约束。 这可能是平台最被低估、却最让管理者安心的价值。具体展开见下文。
下表把核心价值与对应的痛点、量化指标做了一个映射:
| 价值维度 | 解决的痛点 | 关键能力 | 预期指标 |
|---|---|---|---|
| 效率 | 工具割裂、临时验证等待 | 对话式 PRD、AI 编码、临时沙箱 | 端到端周期压缩 40% 以上 |
| 质量 | 评审靠人脑、测试边界不全 | AI 评审建议分级、业务用例自动生成 | 缺陷逃逸率下降 30% 以上 |
| 成本 | AI 散用、孤儿容器 | 模型路由、沙箱自动回收 | AI 调用与资源成本下降 25% 以上 |
| 协作 | 等待黑盒、追溯断裂 | 全流程看板、lineage 追溯 | 跨节点追溯响应时间从天级到分钟级 |
| 治理 | AI 工具各自为政、流程旁路 | Skill/MCP 统一审核收口、节点强制门禁 | AI 工具流程外使用率收敛到 5% 以内 |
1.6 平台的亮点功能
亮点不是功能清单,是那些"用了就回不去"的设计。本平台有七个这样的亮点。
亮点一,工程图谱驱动的影响面分析。 技术方案节点不是让模型凭空画架构图,而是真的去查代码仓库的工程图谱,告诉你这次改动会踩到哪些老符号、下游哪些接口要同步调整。这是市面上多数"AI 技术方案"做不到的,因为它们没有图谱资产。带数字的影响面分析,是技术方案能站住脚的基础。
亮点二,对话式 PRD 迭代。 PRD 不是一次生成完事,而是可以一句话一句话地改。低成本的修改意味着更频繁的修改,更频繁的修改意味着更准确的文档。这个设计直接解决了"文档越写越水"的组织顽疾。
亮点三,代码评审的逐条采纳机制。 AI 给建议,人做决策,每条建议独立采纳或拒绝。这个机制把模型的不确定性和人的判断清晰分离,既享受了 AI 的效率,又保留了人的掌控力。最后还有采纳率统计,长期看是衡量 AI 评审质量的硬指标。
亮点四,退回修改的智能提示词回传。 评审节点退回编码时,所有人工评论和被采纳的 AI 建议会自动整理成结构化提示词,带回编码节点填入对话框。研发不用再手抄评审意见,模型也能直接拿到干净的修改意图。这个跨节点传值经过三重存储兜底,在 file 协议下也稳定可用。
亮点五,临时测试沙箱。 一键拉起、即用即弃的非生产环境,研发同学三十秒就能看到自己代码跑起来的效果。回收按钮放在 C 位,是对"孤儿容器"反模式的态度。这个功能不解决任何严肃工程问题,但它解决了研发一个长期的情绪痛点,情绪痛点一旦被解决,工具的接受度立刻上来。
亮点六,角色视角的知识呈现。 同一份代码,产品看到业务影响,后端看到接口契约,架构看到依赖关系,安全看到权限边界。知识是同一份,呈现跟着角色走。这件事人很难做到一致,机器做起来很自然,是多角色协作的关键基础设施。
亮点七,Skill 与 MCP 双层治理,统一收口又保持灵活。 这是最能体现平台治理价值的设计,值得单独展开。
先说问题。AI 编码工具普及之后,每个研发都在自己的环境里挂各种 Skill 和 MCP Server:有人挂了数据库直连的 MCP,有人挂了能直接改生产的 Skill,有人把公司内部 API 包成 MCP 私自分享。这些动作单个看都没恶意,但放在一起就是一个失控的局面。AI 能绕过所有评审流程直接动代码、动数据、动生产,而组织完全不知道发生了什么。这不是危言耸听,是已经在很多公司发生的事。
平台的解法是把 Skill 和 MCP 的注册、审核、分发全部收口到统一层,而不是放任每个工具、每个员工各自配置。架构上体现为能力层的两个垂直模块:
Skill 注册中心 统一管理所有 AI 技能的描述、所需权限、适用节点、归属团队。一个 Skill 要在平台上对员工可用,必须先经过注册和审核,明确它能做什么、不能做什么、在哪些节点能被调用。未经注册的 Skill 在平台内根本无法加载,从源头杜绝野技能。
MCP Server 目录 把所有外部连接器(数据库、Jira、监控、代码仓库、生产 API)纳入统一目录,每个连接器声明它能访问的数据范围与操作权限。研发想用某个 MCP,不是自己挂,而是从目录里申请,审核通过后在指定节点生效。数据库 MCP 可以限定只读、限定到影子库,生产 API 的 MCP 可以限定到查询类接口。
策略引擎 决定"谁能用哪个 Skill/MCP、在哪个节点能用"。同样是数据库查询 MCP,在 AI 编码节点只允许读影子库,在测试验证节点可以读预发数据,在发布节点直接禁用。策略跟着节点和角色走,而不是一刀切地放开或锁死,这是治理精细化的关键。
审计与告警 记录每一次 Skill 与 MCP 的调用,谁在什么时候、在哪个节点、调用了什么、传了什么参数、返回了什么结果,全部留痕。异常模式(例如编码节点尝试访问生产数据库)实时告警,安全团队能第一时间介入。
这套治理体系带来的价值是双重的。
对管理者,流程不再是建议而是约束。 平台的状态机本身就是流程的强制实现。一个需求没经过评审节点,代码就无法进入测试验证节点;测试没通过,就无法触发发布动作。员工再不能"用 AI 工具自己跑一遍就上线",因为 AI 工具本身被收口在平台内,工具能做的事由平台决定,不由员工个人配置。流程外行为收敛到接近零,这是规模化研发组织最看重的合规底线。
对研发,灵活性没有被牺牲。 Skill 和 MCP 是可扩展的标准协议,平台收口的是注册与审核,不是禁止使用。团队依然可以引入新的 Skill 提升效率,依然可以接入新的 MCP 连接外部系统,只是走一遍注册流程,确保安全与可审计。这种"开放但有边界"的设计,比简单封禁更可持续,也比放任自流更负责。
举个具体场景。某研发同学想在 AI 编码节点引入一个能查公司内部设计稿的 MCP,在传统模式下他自己挂上就能用,无人知晓;在平台模式下,他提交 MCP 注册申请,声明数据源是只读设计稿库,策略引擎审核后允许在编码节点调用,审计层记录所有查询。同一个需求被满足了,但组织知道了、可控了、可追溯了。这就是治理与灵活的平衡。
对比一下没有这套治理会发生什么:三个月后公司发现某员工用 AI 工具直接改了生产数据库,问起来大家都说不知道,审计日志查不到,因为根本没有。这种事故在 AI 普及的当下只会越来越多。平台提前把这道闸门建好,是把未来的黑天鹅挡在今天。
下图把六个亮点在流水线中的位置做了标注:
1.7 这是企业必须的平台吗
这个问题要分层回答,不能一概而论。
对于研发规模超过 50 人、产品迭代周期以周计的企业,这个平台是必需的,不是可选的。 理由有三。
第一,研发规模一旦上来,工具链割裂的代价就呈非线性放大。10 个人的团队靠口头协作能跑通,50 个人以上就必须靠流程和工具,而传统工具链的孤岛问题在这个规模上会成为明显的效率瓶颈。平台的一体化设计在这个规模上的 ROI 最清晰。
第二,AI 已经是不可逆的趋势,但碎片化用法无法沉淀价值。企业要么主动建一体化平台把 AI 能力系统化嵌入流程,要么任由员工各自用各种工具,后者的隐性成本和数据安全风险远高于前者。平台提供的知识库护栏与审计合规能力,是企业级 AI 应用的底线要求。
第三,工程图谱、lineage 追溯、角色视角这些能力,是长期积累的资产,越早建越值钱。等到竞争对手已经把研发周期压到一半,再临时追赶,图谱和数据的积累差距不是一两年能补上的。
对于研发规模 20 人以下、产品相对单一的团队,这个平台不是必须的,可以先局部采用。 这种规模的团队口头协作还能跑通,全面上一体化平台的部署和迁移成本可能不划算。建议优先采用三个最有即时收益的模块:对话式 PRD 生成、临时测试沙箱、代码评审 AI 建议。这三个模块可以独立部署,不需要全套流水线上线,先尝到 AI 的甜头,再考虑全流程整合。
对于强监管行业(金融、医疗、政务、安全合规),这个平台的价值会进一步放大。 因为它天然带审计、带追溯、带人工决策回路。监管要求每一次代码改动可追溯到需求源头,平台 lineage 链路直接满足。监管要求 AI 输出可解释、可审计,平台记录每一次模型调用的提示词与输出。监管要求关键决策有人工确认,平台在每个关键节点都保留人工 gate。这些能力是监管行业的刚需,也是平台相比纯 AI 编码工具的差异化优势。
对于强监管行业(金融、医疗、政务、安全合规),这个平台的价值会进一步放大。 因为它天然带审计、带追溯、带人工决策回路。监管要求每一次代码改动可追溯到需求源头,平台 lineage 链路直接满足。监管要求 AI 输出可解释、可审计,平台记录每一次模型调用的提示词与输出。监管要求关键决策有人工确认,平台在每个关键节点都保留人工 gate。监管更要求 AI 工具本身不能脱离组织管控,平台通过 Skill 与 MCP 的统一注册、审核、策略、审计,把所有 AI 能力收口在治理边界内。这些能力是监管行业的刚需,也是平台相比纯 AI 编码工具的差异化优势。
结论:这个平台不是"又一个 DevOps 工具",而是企业级 AI 研发的操作系统。 它的定位是把 AI 能力从"员工个人技能"升级为"组织级基础设施",把研发流程从"工具堆砌"升级为"一体化协作",把 AI 工具从"各自为政"升级为"统一治理"。对于规模化研发组织,它是必需品;对于小团队,它是可渐进采用的提效工具;对于强监管行业,它是兼顾效率与合规的关键基础设施。一句话概括它的不可替代性:在 AI 普及的下半场,谁能把 AI 系统化地嵌入流程并保持可控,谁就拿到了规模化研发的入场券,而这个能力无法通过堆砌单点工具获得,只能通过一体化平台沉淀。
二、总体架构设计
平台总览架构图
上图把平台的核心结构浓缩为一张:顶部七节点主流水线(需求登记 → 需求生成 → 技术方案 → AI 编码 → 代码评审 → 测试验证 → 发布上线),中部左侧 VKF 知识层(文档资产、工程图谱、角色视角)作为 AI 上下文护栏,中部右侧产物与追溯(PRD vN、代码 Diff、Release)贯穿 lineage 全链路,核心横带 AI 能力治理层(Skill 注册中心、MCP Server 目录、策略引擎、审计告警)统一收口所有 AI 工具,底部五层技术架构(表现层 → 编排层 → 能力层 → 数据层 → 基础设施层)。下面用分层视图展开每一层的内部细节。
2.1 分层架构
平台采用五层架构,自上而下依次为表现层、编排层、能力层、数据层、基础设施层。
表现层当前为纯 HTML/CSS/JS 静态原型,后续可平滑迁移至 React 或 Vue 单页应用,后端通过 REST/WebSocket 暴露。编排层是平台的核心,负责节点状态机的推进与跨节点上下文的维护。能力层封装 AI 编码工具、知识库、Diff 引擎、评审 Agent 等可插拔能力。数据层与基础设施层依赖既有资产,平台本身不重复造轮子。
2.2 流水线全景
七节点主流程加一个临时支线,一个横跨全流程的知识库。
每个节点接收上游节点的产物作为输入,产出结构化的工件传递给下游。退回修改与测试不通过两条回边,使得流水线呈现带反馈的有向图,而非单向传送带。
2.3 节点状态机
每一个需求实例在流水线中维护一个状态机,状态枚举如下:
| 状态码 | 含义 | 后续可达状态 |
|---|---|---|
DRAFTED | 已登记,未生成 | GENERATING |
GENERATING | 需求生成中 | PRD_READY |
PRD_READY | PRD 已就绪 | TECH_SOLVING |
TECH_SOLVING | 技术方案生成中 | CODE_READY |
CODE_READY | 方案已确认,待编码 | CODING |
CODING | AI 编码中 | REVIEWING, SANDBOX_DEPLOYED |
REVIEWING | 评审中 | TESTING, CODING |
TESTING | 测试验证中 | RELEASING, CODING |
RELEASING | 发布中 | RELEASED, ROLLBACK |
RELEASED | 已上线 | 终态 |
ROLLBACK | 已回滚 | CODING |
SANDBOX_DEPLOYED | 临时沙箱运行中 | CODING |
状态机的持久化由编排层负责,前端通过轮询或 WebSocket 订阅状态变更。
三、核心概念与领域模型
3.1 核心实体
平台的领域模型围绕以下核心实体组织:
每一个实体都带版本号与审计字段,确保跨节点追溯时能定位到具体的版本快照。
3.2 知识库引用模型
KnowledgeRef 是贯穿全流程的关键结构,它定义了 AI 在每个节点能够看到的上下文边界:
interface KnowledgeRef {
repoId: string; // 代码仓库标识
refType: 'REPO' | 'DOC' | 'GRAPH' | 'HISTORY_REQ';
path?: string; // 文档路径或代码子路径
graphFilter?: { // 工程图谱过滤条件
symbols?: string[];
layers?: string[];
depth?: number;
};
role?: 'PRODUCT' | 'DEV' | 'QA' | 'ARCHITECT'; // 角色视角
}
角色视角字段决定了同一份知识在不同节点、不同角色面前的呈现方式。这是平台实现"千人千面上下文"的基础。
四、各节点技术方案详解
4.1 需求登记节点
职责:收集需求元信息,挂载知识库上下文,选择 AI 编码工具。
输入:产品同学填写的标题、描述、归属项目、代码源、分支策略。
输出:一个状态为 DRAFTED 的 Requirement 实体,附带 KnowledgeRef[] 与 ToolConfig。
界面设计原理:
界面采用左表单、右知识库选择的双栏布局。左侧表单刻意保持克制,只收集必要的元信息,避免产品同学在登记阶段就被细节淹没。右侧的知识库选择面板允许从 VKF 中勾选相关仓库、文档与历史需求,这些勾选结果构成 KnowledgeRef[],决定后续所有 AI 节点的上下文边界。
AI 编码工具(Claude Code、OpenCode、ZCode、Qoder、Trae)是可选项。这不是因为平台无法默认选择,而是因为这件事在真实团队里是分裂的,把选择权交回用户是基本尊重。所选工具的配置通过 ToolConfig 持久化,在编码节点被读取。
关键决策:不在本节点调用 AI。理由是,需求登记阶段信息密度极高、领域知识极重,没有上下文的模型只会写出放之四海而皆准的废话。AI 接入留到需求生成节点,那时 KnowledgeRef[] 已经就绪。
4.2 需求生成节点
职责:基于登记的元信息与挂载的知识库,生成结构化 PRD,并支持对话式迭代。
输入:Requirement 实体与 KnowledgeRef[]。
输出:PRD 实体,包含多个 Section。
界面设计原理:
界面分两栏,左侧是 AI 正在生成的结构化文档,右侧是聊天式输入框。模型基于知识库上下文先把一版 PRD 拉出来,然后用户通过自然语言指令逐段修改:
把权限模块的验收标准再细化一点,加上对超管账号的特殊处理。
本次需求里所有接口都要兼容 v1 老版本,加一节说明。
关键技术点:文档的低成本修改。
在传统流程里,修改 PRD 意味着打开 Word、找到那段、改成新版、发给评审、合并意见、再发一版,每次修改的体力消耗呈指数上升,最终导致团队宁可开会吵也不愿动文档。对话式生成把"修改一行字"的代价真正降到一次自然语言输入,AI 维持文档整体一致性,人只表达意图。
AI 调用契约:
POST /api/prd/generate
{
"reqId": "MUL-07",
"refs": [{"repoId":"user-center","refType":"GRAPH","graphFilter":{"symbols":["PermissionService","RbacGuard"]}}],
"instruction": "补全验收标准,超管账号特殊处理"
}
模型返回结构化的 Section[],前端按章节渲染。每轮对话都基于上一轮的 PRD.version 做增量修改,版本号单调递增。
4.3 技术方案节点
职责:基于 PRD 与代码工程图谱,生成带影响面分析的技术方案。
输入:PRD 实体、KnowledgeRef[](此处必须包含工程图谱类型)。
输出:TechSolution 实体,包含架构图、影响面分析、架构模式选项。
关键技术点:工程图谱驱动的影响面分析。
这是与市面方案最大的差异点。市面上的"AI 技术方案"通常是让模型吐一段架构说明文字配一张示意图,这种东西与真实代码库脱节,没用。
本平台在知识库中维护了代码仓库的工程图谱。工程图谱是一个有向图,节点是符号(类、函数、模块),边是调用、继承、组合关系。当 AI 分析新需求的影响面时,它真正去查询这张图:
MATCH (target:Symbol)<-[:CALLS*1..3]-(caller:Symbol)
WHERE target.name IN ['PermissionService.checkPermission','RbacGuard.canActivate']
RETURN caller.file, caller.symbol, count(*) AS calls
查询结果汇总成影响面报告:
本次改动涉及 18 个文件,1284 个符号。
核心改动集中在 permission.service.ts 与 rbac.guard.ts。
下游影响:auth.controller 的 3 个接口需要同步调整。
建议关注:旧版 v1 兼容路径不能动,有 7 处历史调用。
这种带数字的影响面分析,是技术方案能站住脚的基础。
架构模式对比:节点支持多种架构模式并排放置,代价与收益列清楚。模型不替团队拍板,但把账算明白。典型对比包括单体拆服务、引入消息队列、上事件驱动三种思路。
4.4 AI 编码节点
职责:根据技术方案生成代码,支持对话式调整,提供在线 IDE 预览。
输入:TechSolution 实体、ToolConfig、KnowledgeRef[]。
输出:CodeChange 实体,包含 FileDiff[]、commitSha、branch。
界面设计原理:
界面采用三栏布局,左侧对话区、中间在线 IDE 查看器、右侧技术方案与知识库引用面板。三栏联动,用户在对话框输入调整指令,中间 IDE 实时刷新 diff。
中间的 IDE 查看器提供语法高亮、行级差异对比、文件树折叠。它不替代本地 VS Code,而是让研发在提交评审前先看一眼,心里有底。上下文切换是生产力的隐形杀手,Alt+Tab 一下大脑里的临时记忆就掉一半,把 IDE 嵌进浏览器是减少切换的必要设计。
AI 编码工具适配器:
节点通过适配器模式屏蔽不同 AI 编码工具的差异:
interface CodingToolAdapter {
name: string;
generate(solution: TechSolution, refs: KnowledgeRef[]): Promise<FileDiff[]>;
adjust(prevDiffs: FileDiff[], instruction: string): Promise<FileDiff[]>;
explain(diffs: FileDiff[]): Promise<string>;
}
五个工具各自实现该接口,平台在运行期根据 ToolConfig 选择实例。新增工具只需新增适配器,不需要改动节点逻辑。
代码示例:
async checkPermission(ctx: PermissionContext): Promise<boolean> {
// 先走 RBAC 粗筛
if (await this.rbac.allow(ctx)) return true;
// 再走 ABAC 细粒度判断
return await this.abac.verify(ctx);
}
临时沙箱入口:本节点底部提供"发布到测试环境"按钮,点击后在新标签页打开测试环境预览页。这条支线不进入主流程状态机,而是独立的 SANDBOX_DEPLOYED 旁路状态。
4.5 代码评审节点
职责:AI 智能评审与人工评审结合,产出可追溯的评审结论。
输入:CodeChange 实体、KnowledgeRef[]。
输出:ReviewResult 实体,包含 Issue[]、Comment[]、Verdict。
关键设计原则:AI 不给最终结论,只给建议。
界面核心是一份 diff 视图,每一处改动旁边可以挂评论线程。AI 评审结果在独立弹窗中展开,按严重级别(严重、高、中、低)与类别(异步陷阱、缓存击穿、命名规范等)分级列出。
每一条 AI 建议都有两个按钮:采纳建议与不采纳建议。这背后的原则是决策权在人。AI 的每一条建议可以单独采纳或拒绝,被拒绝的建议标记为 rejected,不再出现在后续流程的提示词中;被采纳的标记为 accepted,随代码一起进入下游。最后给出全局统计:本次评审 AI 共提出 N 条建议,采纳 X 条,拒绝 Y 条。这个数字是衡量 AI 评审质量的长期指标。
退回修改的跨节点传值:
当点击"退回修改"时,节点需要把所有人工评论与被采纳的 AI 建议整理成提示词,带回编码节点填入对话框。这个跨节点传值经过多轮迭代,最终采用三重存储兜底方案:
之所以三重存储,是因为 file:// 协议下 sessionStorage 与 localStorage 存在分区问题,某些浏览器配置下两者都可能失效。URL Hash 是最可靠的兜底,但长度受限,因此三者并用,优先级为 Hash、sessionStorage、localStorage。
数据抓取规范:提示词只包含干净的反馈内容,不带序号、行号、作者、角色、条数等冗余信息。抓取时遍历 #aiModal 内的 issue DOM,跳过 rejected 类,提取严重级别、类别、问题描述、修复建议;遍历 THREAD_DATA 结构抓取人工评论,过滤掉 role 或 who 字段包含 “AI” 或 “Code Reviewer” 的条目。
4.6 测试验证节点
职责:统一管理四类测试,执行门禁控制。
输入:CodeChange 实体、PRD 实体(用于生成业务用例)。
输出:TestReport 实体。
四类测试的职责划分:
单元测试:开发者自己写,AI 不插手。单元测试是代码设计的一部分,反映开发者对自己代码的理解。让 AI 替开发者写单元测试,短期省事,长期会让团队对测试的掌控力越来越弱。
AI 业务测试:平台特色。模型根据 PRD 与代码 diff 自动生成业务用例并执行,擅长把需求里的自然语言描述翻译成可执行的断言。AI 在这里承担"机械但繁琐"的工作,根据几十条需求描述生成上百条边界用例。
压力测试:走性能基线,与历史数据对比。指标包括 P99 延迟、吞吐量、错误率、资源占用。
外部测试:负责和其他系统的集成联调,通常在预发环境进行。
测试详情统计:测试报告的价值不在于告诉你有多少个 bug,而在于告诉你 bug 集中在哪里。详情页按业务模块、严重级别、归属人做交叉分析,缺陷分类统计,覆盖率可视化,指引下一步该往哪里使劲。
4.7 发布上线节点
职责:灰度发布管理,异常监控,自动告警与回滚。
输入:TestReport 实体(全部通过)。
输出:ReleaseRecord 实体。
设计原则:这个页面的首要任务不是展示信息,而是降低焦虑。焦虑来自不确定性,因此页面把所有能消除不确定性的东西都摆在明面上。
灰度策略:支持 1%、5%、25%、100% 四档,每档有明确的放行条件和回滚阈值。放行条件可以是观察时长(例如每档至少观察 30 分钟),也可以是指标阈值(P99 延迟不超过基线 1.2 倍、错误率不超过 0.1%)。
Release Notes 自动生成:基于本次需求、代码改动、测试报告三方面综合,不需要人手敲一份连自己都不想看的文档。生成结果经过结构化处理,按"新功能、优化、修复、已知问题"四类组织。
异常检测与回滚:监控指标实时刷新,异常检测在后台跑。一旦指标越过红线,页面直接给出回滚按钮,不用翻三层菜单。回滚按钮默认禁用,只有当异常检测确认需要介入时才亮起。频繁误回滚比不回滚更伤团队信心,所以回滚动作本身需要克制。
4.8 测试环境预览节点(临时支线)
职责:为研发同学提供即用即弃的临时测试沙箱。
触发方式:AI 编码节点底部的紫色按钮,新标签页打开。
关键设计:
容器规格固定 2 核 4G,使用影子数据库或 H2 内存模式,与生产完全隔离。空闲 30 分钟自动回收。页面顶部 banner 明确标识"非生产环节的临时测试沙箱",同时写给两类人看:研发放心大胆折腾,运维和管理者知道这条线不会污染主流程。
部署过程模拟标准 DevOps 流水线:
pnpm install --frozen-lockfile
pnpm run build
docker build -t user-center:sandbox .
kubectl apply -f sandbox.yaml
构建日志流式输出,健康检查通过后给出预览地址。页面最显眼的按钮不是"部署",而是回收容器。临时环境最大的问题不是建不起来,是没人记得销毁,一晚上过去云账单多出几十个孤儿容器。把回收按钮放到 C 位,是对这个反模式的态度。
状态机:独立的状态机,idle、building、running、recycled,不与主流程状态机耦合。
五、跨节点数据流与状态管理
5.1 状态持久化
平台维护两类状态,持久化策略不同。
长期状态:需求实例在主流程中的节点状态、各节点的产物实体(PRD、TechSolution 等)。这类状态必须持久化到数据库,支持跨会话恢复、审计追溯、团队协作。持久化介质选用关系型数据库存储结构化字段,对象存储存放大文本与文件。
短期状态:页面交互过程中的临时状态,例如评审反馈提示词、对话历史草稿。这类状态优先存内存,必要时落 sessionStorage 或 localStorage。原型阶段采用三重存储(Hash、sessionStorage、localStorage)兜底,生产化后由后端统一管理。
5.2 上下文传递协议
跨节点传递的上下文分为三类:
| 上下文类型 | 内容 | 传递方式 |
|---|---|---|
| 产物上下文 | 上一节点的结构化输出 | 数据库主键引用 |
| 知识上下文 | KnowledgeRef[] | 跟随需求实体传递 |
| 反馈上下文 | 评审意见、测试失败原因 | 结构化消息 + 提示词模板 |
反馈上下文的传递是最复杂的部分,因为它承载的是"人脑里的判断",格式必须对模型友好。平台定义了一套反馈提示词模板:
根据代码评审反馈,请按以下意见修改代码(permission.service.ts):
【AI 智能评审建议】
• 严重 · 异步陷阱 · 缺失 await
问题:this.abac.verify(ctx) 未 await,返回 Promise 假阳性。
修复:改为 return await this.abac.verify(ctx);。
• 高 · 缓存击穿风险
问题:策略缓存无 singleflight 保护,热点资源高并发下可能压垮下游。
修复:引入 singleflight 包装 policySvc.evaluate。
【人工评审意见】
• TTL 之前你提过希望走配置中心,建议抽成可配置项。
• 击穿问题不大,热点 key 用 singleflight 包一层。
请优先处理严重级别问题,完成后重新生成代码并提交评审。
模板刻意去掉序号、行号、作者、角色等冗余信息,只保留对模型有用的反馈内容。这是从多次迭代中总结出的经验,带过多噪音会干扰模型理解核心意图。
5.3 追溯链路
平台要求每一个产物都可追溯到上游。追溯通过 lineage 字段实现:
interface Lineage {
reqId: string; // 需求 ID
prdVersion: number; // PRD 版本
solutionVersion: number;// 技术方案版本
commitSha: string; // 代码 commit
reviewVerdict: string; // 评审结论
testReportId: string; // 测试报告
releaseId: string; // 发布记录
}
任何节点都能沿 lineage 链路反向追溯到需求的最初描述。发布时某个指标异常,可以追溯到三周前那次技术方案选型;测试报告里某条失败,可以追溯到需求文档里那一句模糊描述。这种跨节点因果链,在传统工具里是断裂的,本平台通过统一的 lineage 模型把它填上。
六、AI 能力集成设计
6.1 模型选择策略
平台不在节点内硬编码模型,而是通过配置中心管理模型路由。不同节点、不同任务可以路由到不同模型:
model_routing:
prd_generate:
primary: claude-opus-4-6
fallback: claude-sonnet-4-6
tech_solution:
primary: claude-opus-4-6
code_generate:
primary: claude-sonnet-4-6 # 编码走工具适配器
code_review:
primary: claude-opus-4-6 # 评审需要更强推理
test_case_generate:
primary: claude-sonnet-4-6
release_note:
primary: claude-haiku-4-5 # 简单任务用轻量模型
模型选择遵循三个原则:推理密集型任务用 Opus,代码生成与中等复杂度用 Sonnet,简单文本任务用 Haiku 控制成本与延迟。
6.2 上下文组装
每次调用模型前,平台会把该节点的上下文按统一格式组装。组装顺序对模型输出质量影响显著:
[系统提示]
你是 XX 节点的 AI 助手,职责是 YY。
[知识库上下文]
仓库 user-center 工程图谱:
- PermissionService.checkPermission 被以下符号调用:...
- RbacGuard.canActivate 实现了 NestJS 的 CanActivate 接口
...
[历史产物]
上一节点 PRD v3 的关键约束:
- 所有接口兼容 v1 老版本
- 超管账号特殊处理
[当前任务]
根据以上信息,生成 permission.service.ts 的实现代码。
知识库上下文按"相关性 + 时效性"加权排序,控制在模型上下文窗口的合理比例内,避免单次调用塞入过多无关信息。
6.3 抑制幻觉的三道护栏
第一道,知识库护栏。模型只能基于 KnowledgeRef[] 指定的上下文作答,不接受凭空生成。
第二道,工程图谱护栏。涉及代码改动时,模型输出必须引用图谱中存在的符号,不存在的符号视为幻觉并拒绝。
第三道,人工评审护栏。AI 的所有输出最终都经过人工评审节点,被拒绝的建议进入长期统计,用于优化提示词与模型选择。
6.4 可观测性
每一次模型调用都记录以下字段到审计日志:
- 调用节点、任务类型、模型版本、提示词全文、模型输出、耗时、token 消耗、用户反馈(采纳或拒绝)。
这些数据有两个用途:一是线上问题排查,二是长期评估 AI 能力在各个节点的表现,为模型路由优化提供数据支撑。
七、知识库与工程图谱
7.1 VKF 知识库架构
VKF(Versed Knowledge Foundation)是平台的统一知识层,存储四类资产:
文档资产、代码资产、工程图谱、历史需求,四类资产通过统一的检索服务对外暴露。检索结果经过角色视角过滤,同一份知识在不同角色面前呈现不同的内容。
7.2 工程图谱的构建与更新
工程图谱是平台抑制幻觉的核心资产。它的构建是一个离线加在线的混合过程。
离线构建:定期扫描代码仓库,解析 AST,提取符号(类、函数、方法、变量)及其关系(调用、继承、组合、实现),写入图数据库。扫描频率与代码仓库的提交活跃度挂钩,核心仓库每次合并触发增量更新。
在线查询:AI 节点通过 Cypher 或类似图查询语言检索图谱。查询结果作为知识库上下文的一部分喂给模型。
// 查询某符号的所有调用者,深度 3 层
MATCH path = (caller)-[:CALLS*1..3]->(target:Symbol {name: 'PermissionService.checkPermission'})
RETURN caller.file, caller.symbol, length(path) AS depth
ORDER BY depth
图谱的时效性是关键。平台通过 commit hook 触发增量更新,保证图谱落后于代码主干的延迟在分钟级别。
7.3 角色视角的实现
角色视角不是简单的权限过滤,而是内容重组。同一份代码,产品看到的是业务影响(这个改动影响哪些用户场景),后端看到的是接口契约(签名变化、兼容性),架构看到的是依赖关系(模块边界、循环依赖),安全看到的是权限边界(鉴权链路、越权风险)。
实现上,每个角色对应一套渲染模板,模板定义如何把图谱查询结果组织成该角色友好的文本。这套模板是平台长期积累的知识资产,需要随业务演进持续维护。
八、安全与隔离
8.1 临时沙箱的隔离
临时测试沙箱是平台对生产环境最大的潜在风险源,因此采用多重隔离。
网络隔离:沙箱容器部署在独立的 namespace,与生产网络不通。访问预览地址需要通过专门的跳板代理,代理记录所有访问日志。
数据隔离:沙箱使用影子数据库或 H2 内存模式,不连接任何生产或预发数据库。数据初始化通过脱敏的种子数据完成。
资源隔离:容器规格固定 2 核 4G,通过 namespace 的 ResourceQuota 限制,防止失控容器挤占集群资源。
生命周期隔离:空闲 30 分钟自动回收,人工可强制回收。回收后容器、PV、Service 全部销毁,不留痕迹。
8.2 AI 调用的安全边界
模型调用不允许携带超出知识库范围的敏感信息。提示词在发送前经过敏感词扫描,匹配到密钥、token、内部域名等模式时自动脱敏。
模型输出在写入数据库前经过二次扫描,防止模型"幻觉"出敏感内容并持久化。
8.3 审计与合规
每一次模型调用、每一次节点状态变更、每一次人工决策(采纳、拒绝、退回、通过)都记录到审计日志,日志不可篡改,保留期满足合规要求。
九、部署与运维
9.1 部署拓扑
平台自身部署在公司内部 Kubernetes 集群,采用微服务架构。
流程编排服务是无状态的水平扩展单元,状态全部落 PostgreSQL 与 Redis。AI 适配服务负责对接外部模型 API,自带限流与重试。知识库服务对接 Neo4j 图数据库与对象存储。Diff 服务负责代码差异计算与渲染。
9.2 监控指标
平台监控四类指标。
业务指标:需求在各节点的停留时长、退回修改次数、AI 建议采纳率、测试一次通过率。
性能指标:页面响应时间、模型调用延迟、Diff 计算耗时。
资源指标:容器 CPU/内存占用、数据库连接池、Redis 命中率。
成本指标:模型 token 消耗、沙箱容器时长、图数据库存储增长。
四类指标都接入 Prometheus,关键看板固化在 Grafana。
9.3 容量规划
平台的核心瓶颈在两个地方。
第一,AI 调用的并发与延迟。模型 API 通常有并发限制,平台通过队列削峰,非实时任务(如 Release Notes 生成)允许排队,实时任务(如对话式编码)预留并发额度。
第二,图数据库的查询性能。工程图谱规模随代码仓库线性增长,查询深度与扇出决定延迟。平台通过缓存热点查询结果、限制查询深度、对大仓库做子图分区来控制延迟。
十、关键技术决策与权衡
10.1 为什么 AI 不给最终结论
代码评审节点里 AI 只给建议,不做决策。这个决策背后是权衡。
让 AI 拍板的好处是效率高,坏处是把模型的不确定性和人的判断搅在一起,评审者变成了验证 AI 输出的质检员,本末倒置。长期看,这会削弱团队对代码的掌控力。
让 AI 给建议、人做决策,短期慢一点,但保留了人的判断回路,这是平台能被研发团队真正接受的前提。
10.2 为什么保留多种 AI 编码工具
五个工具(Claude Code、OpenCode、ZCode、Qoder、Trae)并存,看起来是负担,实际上是必要的。
真实团队对工具的偏好是分裂的,强制统一会引发抵触。不同工具有不同的擅长场景,有些在重构上强,有些在补测试上强,允许混用能让团队按场景选最优解。平台通过适配器模式屏蔽差异,新增工具的成本可控。
代价是适配器维护成本与一致性测试成本,这个代价可以接受。
10.3 为什么临时沙箱单独成支线
把临时沙箱放进主流程,会让流程状态机变得复杂,沙箱的失败会污染主流程。单独成支线,主流程状态机保持简洁,沙箱独立演进。
代价是用户要在两个标签页之间切换,但这是合理的代价,因为沙箱本身就不是主流程的一部分,它是研发的私人临时工位。
10.4 为什么单元测试不让 AI 写
单元测试是代码设计的一部分,反映开发者对自己代码的理解。让 AI 替开发者写单元测试,短期省事,长期会让团队对测试的掌控力越来越弱,最终失去对代码质量的判断能力。
AI 适合做机械但繁琐的事情,比如根据需求生成业务边界用例、跑回归之后归类失败原因。这些事情人也能做,但人做起来又慢又容易走神。设计性的事情留给人,机械性的事情交给机器,这是分工的原则。
10.5 为什么提示词要去掉冗余信息
退回修改时拼装的提示词,经历了多轮迭代。最初版本带序号、行号、作者、角色、条数,信息看似完整,实际干扰模型理解核心意图。
去掉冗余后的版本,只保留严重级别、类别、问题描述、修复建议与人工评论正文。模型输出的针对性与质量明显提升。这是从实践中总结出的经验,提示词工程不是堆信息,是减信息。
十一、扩展性与演进路线
11.1 横向扩展:新增节点
流水线设计为可插拔。新增节点需要定义三件事:输入契约、输出契约、状态枚举。编排层通过配置注册新节点,不需要改动核心代码。
潜在的扩展节点包括:安全审计节点(在评审之后插入深度安全扫描)、性能评审节点(在测试验证之后插入性能专项评审)、可观测性验收节点(在发布之前验收监控指标是否就位)。
11.2 纵向扩展:能力层插件
能力层的每一个服务(AI 适配、知识库、Diff、评审 Agent)都是可插拔的。新增 AI 编码工具、新增图数据库后端、新增评审规则引擎,都通过实现对应接口完成。
11.3 模型演进
模型路由配置化,新模型上线后通过配置切换,不需要改代码。平台预留了模型评测能力,新模型在上线前可以在历史需求数据上跑离线评测,评估各节点的表现后再决定是否切换。
11.4 知识库演进
工程图谱目前覆盖符号级关系,后续可以扩展到服务级调用链(基于链路追踪数据)、数据级血缘(基于 SQL 解析)、业务级流程(基于需求文档)。覆盖越全,AI 的上下文质量越高,幻觉越少。
11.5 多租户与 SaaS 化
当前设计面向企业内部单租户。SaaS 化需要额外考虑三件事:租户隔离(数据、网络、模型配额)、计费模型(按节点、按 token、按容器时长)、租户级别的知识库隔离与共享。这三件事都不影响核心架构,可以在后续版本叠加。
结语
这份文档描述的不是一个完美系统,而是一个经过反复权衡的系统。
每一个设计决策背后都有取舍。AI 给建议不拍板,牺牲了效率换来了人的掌控力。临时沙箱单独成支线,牺牲了流程的简洁换来了研发的情绪痛点解决。提示词去掉冗余信息,牺牲了信息完整度换来了模型输出的针对性。保留多种 AI 编码工具,牺牲了一致性换来了团队的选择权。
这些取舍,不是为了显得高级,是为了让这套系统真正能被研发团队用起来,用起来之后真正能产生价值。
原型的每一页 HTML,都是这些取舍的具体呈现。文档里的每一行架构描述,都是这些取舍的逻辑支撑。
剩下的事情,是把它变成真实的产品,放进真实的团队,跑真实的流程。那才是真正的考验开始的地方。
扫一扫
393
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
