企业官网建设流程全解析

AIOX @qa质量代理详解：10阶段结构化代码审查是怎么做的

【免费下载链接】aiox-coreSynkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0项目地址: https://gitcode.com/GitHub_Trending/ai/aiox-core

AIOX（Synkra AIOS）的@qa 质量代理（代号 Quinn，守护者原型）是专职的测试架构师与质量顾问。本文带你拆解它的核心能力——一套10 阶段结构化代码审查流程：从自动扫描自愈，到风险分级、质量门（Quality Gate）四态决策，让 AI 代码审查既有章法，又可追溯。

先认识 @qa：AI 团队里的"质量守门人"

在 AIOX 的多代理协作体系中，@dev 负责写代码，@po 负责需求，而@qa 负责"把最后一道关"。它的工作特点可以概括为 8 条核心原则：

它的完整定义位于.aiox-core/development/agents/qa.md，官方流程文档见 qa-system.md。

10 阶段结构化审查：全景一览

当 @dev 把 story 标记为 "Review"，或用户手动执行*review {story}命令后，审查引擎就会按下面 10 个阶段顺序推进：

整套流程的"总剧本"就是.aiox-core/development/tasks/qa-review-story.md这个任务文件。下面逐段拆解。

阶段 0：CodeRabbit 自动扫描 + 自愈循环

审查还没开始，机器先"巡逻"一遍：

1. 运行 CodeRabbit CLI，对比 main 分支的已提交变更；
2. 按严重度分级：CRITICAL / HIGH / MEDIUM / LOW；
3. 发现 CRITICAL 或 HIGH 问题 →自动尝试修复，最多 3 轮迭代；
4. 3 轮后仍有高危问题 → 质量门直接判FAIL，强制人工介入；
5. MEDIUM 问题不阻断，自动登记为技术债务（tech debt）工单。

💡 这种"自愈"设计的好处：把机械性问题交给机器反复磨，把人的注意力留给真正需要判断的地方。单轮超时上限 30 分钟，总时长约 90 分钟封顶。

阶段 0b：代码智能参考影响（可选）

如果项目配置了代码智能（Code Intelligence）提供者，@qa 会调用.aiox-core/core/code-intel/helpers/qa-helper.js中的getReferenceImpact(files)，生成一张"影响面表格"：

• 每个被修改文件有多少个"消费方"文件会受影响；
• 消费方超过 10 个的文件，会自动升级审查深度；
• 若代码智能不可用则静默跳过，不影响后续流程。

阶段 1：风险评估决定审查深度

@qa 不是"一刀切"地审每一行代码。满足以下任一信号，会自动升级为深度审查：

• 📌 改动了认证、支付、安全相关文件
• 📌 story 没有新增任何测试
• 📌 diff 超过500 行
• 📌 上一次质量门是 FAIL / CONCERNS
• 📌 story 有 5 条以上验收标准

风险评分会写入门文件：任意风险分≥ 9 直接 FAIL，≥ 6 记 CONCERNS。

阶段 2：六维综合分析

这是整个审查最"重"的一环，覆盖 6 个维度：

阶段 3~6：不只是"挑刺"，还能直接动手

很多静态审查工具只能"发现问题"，而 @qa 的定位是测试架构师——它被授权在安全的前提下直接重构代码：

• 阶段 3 积极重构：动手改安全范围内的代码，跑测试确认不破坏功能，并在 QA Results 中写清楚为什么改、怎么改；
• 阶段 4 合规检查：逐条对照编码规范、项目结构、测试策略文档；
• 阶段 5 验收核验：确认每条 AC 完整实现，边界用例已覆盖；
• 阶段 6 文档审阅：复杂逻辑缺注释就补上，API 变更必须同步文档。

⚠️ 注意边界：@qa 只能更新 story 文件中的 "QA Results" 区块和状态流转，无权修改 File List 等其他章节，也禁止git push/git commit（这些权限只属于 @github-devops）。职责隔离正是这套体系可靠的原因。

阶段 7~8：QA Results 落盘与质量门四态决策

审查结论最终以"双产物"形式持久化，且协议是fail-closed的（写盘 + 回读校验全部通过才允许交接）：

产物 1：QA Results（写回 story 文件）包含代码质量评估、重构清单、合规核对表、安全与性能结论，并执行状态流转：PASS/CONCERNS/WAIVED →InReview → Done；FAIL →InReview → InProgress。

产物 2：质量门文件（YAML）由.aiox-core/development/templates/qa-gate-tmpl.yaml渲染，保存到docs/qa/gates/目录，包含决策理由、质量评分、NFR 逐项状态、修复建议与责任人（dev/sm/po），默认 2 周过期。

质量门四态决策速查

质量评分算法很直观：质量分 = 100 − 20×FAIL数 − 10×CONCERNS数，介于 0~100 之间。

QA Loop：审查-修复自动闭环

单次审查不是终点。.aiox-core/development/workflows/qa-loop.yaml定义了自动化循环：

1. Review：@qa 执行完整审查并给出判定；
2. Fix Request：若 REJECT，生成QA_FIX_REQUEST.md交接给 @dev；
3. Apply Fixes：@dev 修复后标记 Ready for Re-review；
4. Re-review：@qa 重新审查，最多 5 轮迭代，超限则升级人工处理。

APPROVE 即完成，BLOCKED 则直接升级——循环始终有明确出口。

关键文件路径导航

想深入源码或自行调整配置，这些路径值得收藏：

• 完整任务剧本：.aiox-core/development/tasks/qa-review-story.md
• 质量门任务：.aiox-core/development/tasks/qa-gate.md
• 风险矩阵：.aiox-core/development/tasks/qa-risk-profile.md
• NFR 评估：.aiox-core/development/tasks/qa-nfr-assess.md
• 测试设计：.aiox-core/development/tasks/qa-test-design.md
• 需求追溯：.aiox-core/development/tasks/qa-trace-requirements.md
• QA 循环编排：.aiox-core/development/workflows/qa-loop.yaml
• 全局配置（覆盖率目标 80%、质量分下限 70 等）：.aiox-core/core-config.yaml
• 流程文档：docs/zh/aiox-agent-flows/qa-system.md

总结：这套 10 阶段流程好在哪？

🎯可预期：每次审查走完全相同的路径，没有"看心情审查"； 🎯可追溯：门文件记录决策理由、评审修订号、证据清单，随时可审计； 🎯可自愈：机械问题机器 3 轮内消化，MEDIUM 问题自动进技术债务； 🎯有边界：QA 只改该改的，权限最小化，FAIL 必回炉，PASS 必放行。

对于想引入 AI 代码审查的团队，AIOX 的 @qa 提供了一个很好的范本：先用流程约束 AI，再让 AI 释放效率。

【免费下载链接】aiox-coreSynkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework v4.0项目地址: https://gitcode.com/GitHub_Trending/ai/aiox-core