Convention Graph Discovery

价值门禁 / Why This Is a Skill

这是 Cat Café 特有的方法论：把 repo 里的“约定层关联”（MCP tool、skill trigger、route、workflow callback、配置驱动注册）画成带 provenance/freshness 的图。它不是通用 AST 教程，也不是让猫依赖 codegraph/GitNexus；它把 F242 的 dogfood 经验沉淀成未来进 repo 的第一步。

核心知识 / Overview

LSP 看符号，grep 看文本；约定图看“这个 repo 的规矩”。每条边必须能回答三件事：它从哪个 source span 来、当前图新不新鲜、漏识别的 gap 在哪。

When to Use

用在：

• 刚进入陌生 repo，需要先摸清“改 X 会影响谁”。
• 改动触及配置/注册/manifest/route/callback 等约定层，不只是函数调用。
• 改 MCP tool schema/name、skill manifest、FastAPI/API route、workflow callback 前，需要先找约定层消费方。
• F242 / Convention Graph Layer 相关实现、dogfood、review。

不要用在：

• 已经能用 LSP 精确跳转的普通函数调用。
• 只想找文档或历史讨论（用 memory-navigation / memory-search-best-practices）。
• 想把 codegraph/GitNexus 当外部依赖直接接入。
• 只是 cat-cafe 自家 extractor 的硬编码搬运。

流程 / Discovery Protocol

1. 定边界：写清 repo、目标问题、要验证的 convention domain。例：MCP tool 消费方、FastAPI route、skill trigger。
2. 找显式锚点：优先找名字/ID/typed import/config key/manifest field。禁止 name-only 跨语言合并。
3. 定义 domain：列 domainId、node kinds、edge kinds、extractor inputs、invalidation scope、negative fixtures。
4. 写 extractor：先用最小 fixture TDD，产出 nodes / edges / gaps。每条 edge 带 extractor/version/sourceFile/sourceLine/confidence。
5. 接引擎：记录 index commit + indexed file hashes；查询必须带 freshness，pending changes 直接标 stale。
6. 对比基线：用 grep/LSP 或人工查证对比，记录它们漏了什么、约定图多解释了什么。
7. 报 gap：发现框架或约定但没覆盖时输出 gap/unknowns，不能静默 0 命中。

Product Entry / Commands

在 Cat Café repo 根目录，先重建当前 repo 的图：

pnpm convention-graph:index -- --repo .

查某个 MCP tool 的约定层消费方：

MCP_TOOL_NAME=replace_with_tool_name
pnpm convention-graph:code-consumers -- --repo . --domain mcp-tool --kind mcp_tool --name "$MCP_TOOL_NAME"

输出是 JSON，包含 targets、consumers、每条 edge 的 provenance，以及 freshness。如果 freshness.stale=true，这次查询只能当 stale 证据；先重跑 convention-graph:index，再决定影响面。

当前内置 domain：mcp-tool、skill-manifest、fastapi-route。新 repo 的未知约定不要写 ad-hoc 查询脚本；按 Discovery Protocol 定义 domain plugin，再接同一个 CLI/engine。

Quick Reference

Common Mistakes

验证 / Pressure Test

• 至少两个 domain 通过 fixture：一个结构注册类，一个 manifest/config 类。
• 每个 domain 有 negative fixture，证明同名非约定对象不误连。
• 改一个已索引文件后，查询结果必须 stale=true 并列出 pending change。
• 对一个真实“改 X 找消费方”场景 dogfood，写出 grep/LSP 对比差异。

和其他 Skill 的区别

• tdd：写 extractor 代码时仍要用；本 skill 负责“该画什么图、怎样定义 domain”。
• knowledge-engineering：面向文档结构化；本 skill 面向代码约定层。
• memory-navigation：找历史知识；本 skill 建当前 repo 的实时工作 artifact。
• open-source-teardown：拆外部项目学习；本 skill 把学习结果落成自家 repo 的约定图方法。

下一步

Domain 定义收敛后 → tdd 写 extractor → quality-gate 做 spec/freshness/provenance 自检。