Coador

Coador

在 AI Agent 开始阅读代码之前，为其提供一张 Android 项目地图。

Coador 会在本地以确定性方式扫描 Android 代码库，不使用 LLM， 并构建结构化、基于证据的知识库，涵盖项目架构、Gradle 配置、测试基础设施、UI 选择器、CI/CD 以及其他高价值上下文。

Agent 会先查询这些知识，然后只检查任务所需的文件。

更快获取上下文。减少重复探索。降低令牌用量。

Coador 会将 Android 代码库转化为本地知识库，供 AI Agent 查询，避免反复重新阅读和探索整个项目。

Coador 的核心理念很简单：扫描过程本身不使用 AI 或 LLM。

Coador 会以确定性方式分析 Android 项目，提取对开发和测试自动化最有用的信息，并以结构化形式保存： 架构信号、Gradle 配置、模块和依赖、测试基础设施、UI 选择器、深层链接、CI/CD、测试运行器、测试夹具、 依赖注入覆盖项，以及其他项目级知识。

因此，AI Agent 不必在每个新任务中都从头探索大型代码库——无需搜索合适的 Gradle 文件、重建模块结构、 识别测试框架，或弄清 UI 测试的组织方式。

Agent 可以查询已准备好的知识库，获取只针对当前所需项目部分的精简答案。

这能减少重复探索代码库的工作，降低需要纳入模型上下文的源代码量，并减少不必要的令牌消耗。

为什么扫描器不使用 AI？

Coador 有意将事实提取与 AI 解读分开。

代码库由专用的确定性检测器在本地扫描。它们不会生成架构描述，也不会试图猜测项目的设计方式。 Coador 只记录能够由源文件、Gradle 配置或代码库结构佐证的信号。

例如，Coador 不会断言：

此项目使用了 Clean Architecture。

而是可能报告：

找到了 domain、data 和 feature 模块，以及观察到的模块间依赖关系。

Agent 接收的是证据，而不是预先生成的解读，因此可以自行推理这些证据。

只要可行，Coador 还会保留每项发现的来源信息：源文件和确切的源代码行、文件级观察结果，或从已配置的 Gradle 模型中获取的值。

工作原理

Coador 会扫描 Android 仓库，并在本地构建项目的结构化配置文件。分析涵盖以下九个主要方面：

层级	涵盖内容
项目概览	仓库身份、结构、应用和 UI 信号
Gradle 和构建	构建系统、SDK、变体、任务和配置
架构	DI、网络、持久化、导航、状态和并发
模块	模块清单、类型和观察到的依赖关系
配置	环境、构建配置、资源、机密信息和功能标志
依赖项	按技术栈分组的库和版本
测试	单元测试和插桩测试、运行器、测试夹具和测试任务
UI 测试	框架、屏幕对象、选择器、深层链接和组件
CI/CD	流水线、设备、报告、制品、重试和通知

完整目录目前包含 84 个检测器，生成于 docs/detectors.md。

生成的知识会存储在本地，供开发者和 AI 工具使用。开发者可以使用 CLI 和易读的 Markdown 视图。AI Agent 可以通过 MCP 接口读取项目概览、搜索信息，并获取附有佐证的各个独立部分。

Android repository
        ↓
Coador scan
        ↓
structured local knowledge base
        ↓
AI agent queries only the information it needs
        ↓
agent opens specific source files only when required

Coador 会生成两类发现结果。信号会报告观察到的能力，并提供佐证样本。清单会保留收集到的值，例如深层链接、已导出的组件和 UI 测试中的字面选择器。在其文档所述的收集范围内，清单会标明自身状态为 complete、incomplete 或 unknown。

默认扫描会读取仓库文本，无需 Android 工具链。可选的 --gradle 扫描会从受信任项目配置的构建中获取静态文本无法解析的信息，例如由约定插件声明的变体。每个部分都会标明其来源是 heuristic 还是 gradle。

实际示例

假设 AI Agent 需要添加一个新的 Android UI 测试。

如果没有 Coador，Agent 可能首先需要了解：

• 插桩测试位于何处；
• 使用了哪个测试运行器；
• 是否存在共享的基础测试；
• 屏幕对象或机器人是如何组织的；
• 项目使用的是 Espresso、Kaspresso 还是 Compose 测试；
• 测试中如何处理身份验证；
• 已有哪些选择器；
• 是否提供了测试 DI 或伪依赖项；
• 如何在本地和 CI 中运行测试。

在大型代码仓库中，回答这些问题可能需要先检查数十个文件，才能开始实际任务。

使用 Coador 后，其中很多信息都已收集并整理好。Agent 可以只查询所需的测试基础设施、选择器或 CI 配置，然后打开实现所需的少量特定源文件。

例如，将 Agent 连接到已记录的 Now in Android 修订版本，并询问：

你： 如何在这个项目中添加并运行插桩 UI 测试？

Agent： 将测试放在现有应用测试旁边，即 app/src/androidTest。 按照项目的 Hilt/Compose 设置操作：使用 @HiltAndroidTest，先运行 HiltAndroidRule， 然后使用 createAndroidComposeRule<MainActivity>()。应用选择了 NiaTestRunner， 它会启动 HiltTestApplication。 共享伪对象通过 @TestInstallIn 替换生产绑定。CI 运行已观察到的任务 ./gradlew connectedDemoDebugAndroidTest。 该任务是有源代码依据的参考，并非完整的 Gradle 任务枚举。

回答虽然简洁，但每项陈述都与 Agent 或开发者可以检查的证据相关联。

本地且可验证

默认情况下，Coador 在本地运行。其标准分析不需要：

• 大模型；
• 嵌入模型；
• 向量数据库；
• 外部 API；
• Docker；
• 将代码仓库源代码上传到外部服务。

生成的项目配置文件具有确定性：预期相同的代码仓库状态和扫描配置会产生相同的结构化结果。因此，知识库适合与项目一同保存、随代码库更新，并像审查其他生成的项目产物一样审查其变更。

profile.json 是机器可读的事实来源。Markdown 层是该配置文件面向人类的呈现形式。精确的源代码证据包含相对于代码仓库的路径、从 1 开始的行号范围和快照摘要。文件级和 Gradle 模型的发现结果使用各自的溯源形式，不会伪造行号。

从源代码生成的字段会经过共享的常见机密信息清理流程，但清理并不能保证私有输出可以安全发布。分享生成的知识库前，请先进行检查。完整的信任边界见 SECURITY.md。

Coador 不会从扫描的项目收集遥测数据。其默认扫描不会访问网络。安装软件包和显式请求的 Gradle 阶段各自有独立的网络和信任边界。

不替代源代码

Coador 无意让 AI Agent 不再检查源代码。它旨在消除反复进行大范围仓库探索的需要。

当 Agent 需要修改某项功能时，它仍会打开相关的生产代码和测试文件。它不再需要做的，是从头反复重建整体架构、测试基础设施、Gradle 设置和 CI 工作流。

Coador 充当项目的预构建地图：精简、结构化、本地可用，并有源代码证据作为依据。

这张地图有明确的局限：

• 默认扫描通过模式匹配而非编译来完成。未找到启发式证据并不能证明某项能力不存在。
• 约定插件、生成的构建逻辑和动态创建的变体可能需要使用可选的 Gradle 扫描。
• coador scan --gradle 会执行目标构建的配置，仅应在可信项目中使用。
• 库存的完整性仅适用于检测器文档所述的源代码边界，不涵盖运行时可能存在的所有值。
• 元数据新鲜度快速路径无法检测路径、大小和修改时间均被刻意保留的内容变更；在这种情况下请使用 --force。
• Coador 可与符号导航、语义搜索、构建工具和设备自动化配合使用，但不能取代它们。

安装

Coador 需要 Python 3.11 或更高版本。通过 uvx 运行版本 0.1.0，无需永久安装：

uvx --from coador==0.1.0 coador --version

若要使用当前检出版本：

git clone https://github.com/automaticqa/coador.git
cd coador
uv sync --all-extras
uv run coador --version

也支持通过 pip 进行可编辑安装：

python -m pip install -e '.[dev]'

CLI

CLI 提供六条命令：

命令	用途
scan	构建或刷新知识库
status	报告存储的知识是否为最新
layers	列出九个知识层
overview	显示单屏项目地图
search	使用可识别标识符的词法排序搜索各个章节
show	查看某个层或章节及其证据

在 Android 仓库中运行基本工作流：

coador scan
coador overview
coador search "where do the base URLs come from"
coador show 03_architecture di_framework

每条命令都支持 --json。使用 --kb-dir 可将生成的输出保存在 Android 检出目录之外。如果无法信任源代码元数据，请使用 coador scan --force。对于配备 JDK 和 Gradle wrapper 的可信项目，coador scan --gradle 会添加已配置的 Gradle 模型。

默认情况下，生成的知识存放于此处：

.coador/
  .refresh.lock
  manifest.json
  profile.json
  layers/

扫描器会读取 Android 源代码和构建配置，但不会修改它们。它只会写入选定的知识库目录，绝不会编辑目标仓库的 .gitignore。所选目标目录不会纳入扫描和新鲜度指纹的范围。

当团队希望项目地图经过审核，并且无需本地重新扫描即可使用时，可以将 .coador/ 目录提交到版本控制。每层 `` 标记上方手写的 Markdown 会在刷新时保留。

MCP

coador mcp（也可通过 coador-mcp 使用）通过 MCP stdio 为单个仓库提供服务，并提供六个 kb_* 工具及对应的 kb:// 资源。请显式注册 Android 仓库，避免服务端悄悄切换到无关的工作目录：

codex mcp add coador -- uvx --from coador==0.1.0 coador mcp \
  --repo "/absolute/path/to/your/android/project"
codex mcp list

在 Android 项目中打开 Codex，使用 /mcp 验证服务端，然后提出一个项目相关问题。以下是一个实用的起始提示词：

如何为此项目添加插桩测试？请指出运行器、应用、检测到的测试任务、依赖项覆盖项、可扩展的 helper 或 robot，以及有用的选择器。请为每项回答引用仓库证据。

也可以使用 COADOR_REPO 和 COADOR_KB_DIR 进行配置。有关可信的项目级配置、包含空格的路径、多个仓库、Claude Code 和其他 MCP 客户端，请参阅 docs/mcp.md。

示例

从本地合成示例开始，在无需网络或 Android 工具链的情况下了解当前配置文件架构。对于固定版本的 Now in Android 演练，请在已下载的代码库目录之外生成当前 CLI 视图：

git clone https://github.com/android/nowinandroid.git
git -C nowinandroid checkout 12f80da6518e161ed16a06a68e71fb8a873576d6
uvx --from coador==0.1.0 coador scan nowinandroid --kb-dir ../nowinandroid-coador
uvx --from coador==0.1.0 coador show 07_testing instrumentation_runner \
  nowinandroid --kb-dir ../nowinandroid-coador
uvx --from coador==0.1.0 coador show 07_testing test_tasks \
  nowinandroid --kb-dir ../nowinandroid-coador

相关输出区分了证据与限制：

$ coador show 07_testing instrumentation_runner nowinandroid --kb-dir ../nowinandroid-coador
Instrumentation Runner (instrumentation_runner)
Detected: Observed: runner: androidx.test.runner.AndroidJUnitRunner, com.google.samples.apps.nowinandroid.core.testing.NiaTestRunner
source: heuristic

  app/build.gradle.kts:38  testInstrumentationRunner = "com.google.samples.apps.nowinandroid.core.testing.NiaTestRunner"

  limitation: Static scanning cannot resolve runner configuration supplied only by convention plugins or generated build logic

以证据为先的入门指南补充了 CI 测试、启动目标与选择器，以及在三个固定版本的公开代码库中隔离 Android Test Orchestrator 的演练。

项目状态

Coador 0.1.0 是首个公开版本（2026-09-17）。此软件包包含 9 个层级中的 84 个检测器、本地 CLI、MCP stdio 服务、可选的 Gradle 探测、确定性的 JSON/Markdown 输出、证据来源、清单分页、新鲜度检查，以及从损坏的生成输出中恢复的功能。

配置的 CI 矩阵针对 Linux 上的 Python 3.11–3.13，以及 Windows/macOS 上的 Python 3.12。网络检查和真实项目 Gradle 检查仍需选择启用。

开发指南：

uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy
uv run python -m coador.registry --check
uv build

COADOR_INTEGRATION=1 uv run pytest -m slow 还会克隆固定版本的公开 Android 代码库；Gradle 测试需要合适的 Android/JDK 工具链。贡献者可以从入门贡献任务开始。可选的公开使用反馈须遵循 docs/adoption.md 中的隐私边界。

许可证

MIT。请参阅 LICENSE。