Contributing

贡献指南

📚 参考 · 🏠 首页 › Contributing

---

📑 本页目录

• 1. 硬门禁（不通过就别提）
• 2. 架构红线（Reviewer 一定会看）
• 3. 本地自检（提 PR 前跑一遍）
• 4. PR 描述建议
• 做了什么
• 为什么
• 怎么验证的
• 风险与回滚
• 5. 各领域的"从这里开始"
• 6. 行为准则（简版）
• 7. 许可证
• 8. 相关页面

欢迎 Issue / PR！本页是"提 PR 之前必须知道的事"。

1. 硬门禁（不通过就别提）

1. CI 全绿 —— 含 cs-mem / agent-engine / tool-registry / terminal 的测试以及全部静态门禁；
2. 结构预算 —— 单文件 main ≤1200 行 / test ≤1600 行，超了先拆再提；
3. 提交规范 —— type(scope): description， type ∈ feat / fix / docs / refactor / chore（也可带 test / perf / ci）；
4. 修缺陷必须带回归测试 —— 先红后绿，并在 KDoc/注释里注明这个测试锁定了哪个缺陷；
5. 新工具必须过工具 ID 唯一性检查 —— 撞 id 直接红（历史教训：MCP 三工具被注册三次）；
6. :core:tool-registry 的测试步骤不允许通过跳过来"变绿"；
7. 改动 cs-mem 请同步更新 docs/memory-and-workflow-research.md 的对应结论。

2. 架构红线（Reviewer 一定会看）

红线	为什么
core:* 不得依赖 Android SDK	纯 JVM 才能在 CI 静态分析里秒级校验、跑 JVM 单测
:terminal-emulator 不得依赖 :platform:terminal	详见 VT100 模拟器
不要动 targetSdk = 28	详见 终端运行时
新玻璃组件不要自己调 Haze	包 GlassSurface 走 七档材质
未实现的能力要标注	项目拒绝"假装拥有一枚没实现的特性"（如 Refraction 明确 NOT IMPLEMENTED）

3. 本地自检（提 PR 前跑一遍）

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

./gradlew :core:agent-engine:test :core:tool-registry:test \
  :platform:terminal:testDebugUnitTest :platform:cs-mem:testDebugUnitTest

Windows 请用 Git Bash / WSL 跑 .sh，并保持 LF 换行。详见 质量门禁 与 仓库脚本。

4. PR 描述建议

## 做了什么
（一句话）

## 为什么
（关联的 Issue / 现象）

## 怎么验证的
- 新增/修改的测试：
- 真机验证步骤（若适用）：

## 风险与回滚
- 影响面：
- 回滚方式：

可以参考仓库里的 docs/pr-body.md 与 docs/pr-t76.md 模板。

5. 各领域的"从这里开始"

想改	读
Agent 行为	Agent 引擎 · 任务编排器
工具	工具系统
LLM 协议	LLM 适配层
终端	终端运行时 · Ubuntu rootfs · VT100
记忆	cs-mem · 记忆生命周期
UI	界面导航地图 · Liquid Glass
扩展能力	技能与斜杠命令 · 插件 SDK · 浏览器
工程化	构建 · CI · 测试 · 质量门禁

6. 行为准则（简版）

• 对事不对人，评论针对代码；
• 大改动先开 Issue 对齐设计再动手，避免返工；
• 承认不知道，也不要假装实现 —— 这在本项目是明文原则（见 Liquid Glass）。

7. 许可证

Caution

⚖️ 许可证尚未确定（TBD）。 商业化使用前请先开 issue 与作者对齐。

8. 相关页面

• Home · Docs-Index · CI-Pipelines · Testing

---

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

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