Quality Gates

质量门禁

🛠️ 工程化 · 🏠 首页 › Quality-Gates

---

📑 本页目录

• 1. 三条核心规则
• 2. CI 中的其他门禁（静态分析 job）
• 3. 本地执行
• 4. 触发门禁后的正确做法
• 5. 提交 / PR 的附加要求
• 6. 相关页面

除了单元测试，仓库还有一组结构性门禁：它们不看"结果对不对"，而是看 "代码结构会不会腐烂"。全部由 quality-gate.yml 在 CI 中执行，也可以本地跑。

1. 三条核心规则

#	规则	阈值 / 内容	执行脚本
1	文件大小预算（反 God 文件）	main ≤ 1200 行，test ≤ 1600 行	scripts/check_file_size.sh
2	反模式	① javaClass.getMethod 反射分发 ② main 源中的 printStackTrace()	scripts/check_code_quality.sh
3	空 catch 普查	列出空 catch {} 便于审计（不阻断，仅输出报告）	scripts/check_code_quality.sh

扫描范围：core、app、platform、terminal-emulator 的 main 源码。

Note

为什么要这种看似粗暴的门禁？因为本项目有若干天然会膨胀的核心类 （ApexAgentEngine、DefaultTaskOrchestrator、ToolModule、UbuntuAptPackageManager）。 预算的作用是逼迫"先拆再提"，而不是默默长到 5000 行。

2. CI 中的其他门禁（静态分析 job）

门禁	说明
纯 kotlinc 编译 core 四模块	验证 core:* 没有偷摸引入 Android 依赖
工具 ID 唯一性	撞 id 直接红（历史上 MCP 三工具被注册三次）
重复类检查	同名类重复定义检测
词法感知括号平衡	scripts/kotlin_balance.py —— 剥离注释/raw 串/字符串模板后计数，避免误报
PRoot 二进制 sha256 校验（P71）	随包 .so 指纹与清单必须一致，防篡改/误替换
rootfs 指纹三重一致性	见 Ubuntu rootfs 供给

3. 本地执行

scripts/check_file_size.sh        # 文件预算
scripts/check_code_quality.sh     # 反模式 + 空 catch 普查
python scripts/kotlin_balance.py  # 括号/花括号平衡（词法感知）
scripts/fetch_rootfs.sh --check   # 内置 rootfs 指纹

（Windows 用户请用 Git Bash / WSL 执行 .sh，并保持 LF 换行。）

4. 触发门禁后的正确做法

被拦	怎么做
文件超预算	先抽再提：抽子类/拆包/移职责，core 优先拆子包；不要改阈值绕过
反射分发被拦	换成显式接口/策略模式；反射分发会让调用点不可追踪
printStackTrace() 被拦	改成 AppLogger（core:logging）的结构化日志； swallowing 的错误信息会让排错变考古
括号平衡失败	通常是字符串模板里的 ${...} 或 raw string 没闭合；本地先跑脚本定位
工具 ID 重复	改名或用命名空间前缀（插件工具尤其记得加前缀）

5. 提交 / PR 的附加要求

• type(scope): description 提交规范（feat / fix / docs / refactor / chore …）；
• 修缺陷必须带回归测试（先红后绿，KDoc 注明锁定的缺陷）；
• 不允许通过"跳过测试"让 :core:tool-registry 变绿；
• 改动 cs-mem 需同步更新 docs/memory-and-workflow-research.md 的对应结论。

完整清单见 贡献指南。

6. 相关页面

• CI 流水线 · 仓库脚本 · 测试体系

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}