Copilot CLI Agent Discovery Doctor

这是一个面向 CLI / agent 工作流的小工具，用来解决一个很具体的问题：在 monorepo 或 nested workspace 里，项目本地 agent 文件到底会不会被发现、会不会被 shadow、为什么会失效，当前很难看清楚。

这个仓库提供两层能力：

• 一个 discovery core：扫描 user、repo-root、cwd-local 三种 agent roots，并按固定优先级解释结果
• 一个 CLI：输出可读文本或 JSON，告诉你哪些 agent 会加载、哪些不会，以及原因是什么

面向谁

适合在多层目录、monorepo、或者混合本地 agent 规则里工作的人。尤其适合那些已经遇到“明明有 agent 文件，但 CLI 没找到”或者“同名 agent 到底哪个生效”这类问题的开发者。

当前能力

• 识别 repo-root 与 cwd-local agent roots
• 可选识别 user agent root
• 递归扫描 .github/agents/**/*.agent.md
• 按 user > cwd-local > repo-root 给出确定性 precedence
• 标记 selected、shadowed、invalid 结果
• 支持 --json 输出，方便录入 bug report 或 CI 检查

本地运行

python3 -m pip install -r requirements-dev.txt
python3 -m pytest tests
python3 -m pip install -e .
agent-discovery-doctor --json tests/fixtures/repo-root/packages/payments

如果你只想快速试一遍，最后一条命令就够了。当前 fixture 会返回两个同名 agent：一个来自 repo root，一个来自 nested cwd-local root，其中 cwd-local 版本会被选中，repo-root 版本会被标成 shadowed。

Happy Path

运行：

agent-discovery-doctor --json tests/fixtures/repo-root/packages/payments

预期结果：

• rootsScanned 里同时出现 repo-root 和 cwd-local
• nested root-audit.agent.md 被标成 selected: true
• root-level root-audit.agent.md 被标成 selected: false
• reason 明确显示 precedence 结果

项目结构

• src/copilot_cli_agent_discovery_doctor/discover.py：discovery core 与 precedence 逻辑
• src/copilot_cli_agent_discovery_doctor/explain.py：human-readable 输出
• src/copilot_cli_agent_discovery_doctor/cli.py：命令行入口
• tests/fixtures/：nested repo / invalid metadata / user scope fixtures
• tests/：fixture-driven regression tests
• scripts/run-guards.sh：轻量 guard runner

当前限制

• 这是一个 doctor 工具，不是 Copilot CLI 本体 patch
• 当前重点是解释 discovery 结果，不是自动修复 agent 文件
• 还没有实现 arbitrary path override、远程扫描、或完整 IDE 集成
• 现在只覆盖本地文件系统和一组明确的 precedence 规则

后续再做

• 增加更多无效 frontmatter / 重复命名 / 多层 nested fixture
• 增加对 instructions / AGENTS.md 并行解释的 doctor 模式
• 增加更适合 CI 的 exit code 约定和 summary 输出