yigraf Skill 技能

技能简介

yigraf（Why I Graph?）是一款专为 AI 编码代理设计的真值维护系统（Truth Maintenance System）。它将代理对代码库的认知——包括代码意图（intent）、执行计划（plan）、决策原因（why）以及必须满足的约束条件（what must hold）——以图结构的形式持久化存储，每个认知节点都锚定到具体代码行并附带理由。当代码发生变化时，yigraf 能够自动检测哪些既有认知已经失效，并提醒代理及时更新。与传统知识管理工具不同，yigraf 的核心用户是 AI 代理而非人类：它为代理提供了一个可信赖的长期记忆层，让代理在多会话协作中始终基于经过验证的真值而非过时的假设做决策，从而大幅降低代理因信息陈旧而重复讨论、错误执行或推翻已定方案的概率。

核心能力

1. 图结构认知存储：将代理对代码库的认知以图（Graph）形式存储，节点包含意图、计划、约束和理由，边记录节点间的逻辑关系，支持复杂的推理链路追踪。
2. 代码锚定机制：每个认知节点都精确锚定到对应的代码行（通过 Tree-sitter 解析），当该代码段发生变化时，yigraf 能自动检测到关联节点的置信度下降。
3. 置信度分层：认知节点携带置信度层级（grounding tier），区分经过测量验证的断言和基于假设的推断，避免代理将不同置信度的信息混为一谈。
4. 失效检测与修订：当锚定代码发生变化时，yigraf 自动标记受影响节点为可能失效，代理可在下次行动前查询这些节点，重新验证或修订认知。
5. 多语言代码解析：通过 Tree-sitter 支持 20+ 编程语言的 AST 解析，包括 Python、JavaScript、TypeScript、Go、Rust、Java、C++、Ruby、PHP、Swift、Kotlin、Scala 等，覆盖主流开发场景。
6. 语义嵌入支持：可选集成 sentence-transformers 嵌入模型，对认知节点进行向量化，支持语义相似度检索。
7. MCP 协议集成：内置 MCP（Model Context Protocol）客户端/服务器支持，代理可通过 MCP 协议访问图中的认知切片，读取相关历史决策背景。

安装配置

1. pip 安装（Python 3.10+）：

   pip install yigraf

   安装时自动下载 Tree-sitter 语法解析器和基础依赖。

2. 含嵌入模型版本（可选，需要 PyTorch）：

   pip install yigraf[embeddings-torch]

   这会额外安装 sentence-transformers 和 fastembed，用于语义搜索功能。

3. 初始化项目： 在代码仓库根目录运行：

   yigraf init

   初始化会在仓库中创建 .yigraf/ 目录，存储图数据库和配置文件。

4. 编辑器集成：在 Claude Code 的 .mcp.json 或其他 MCP 客户端配置中添加 yigraf 服务器地址和认证信息（若启用），即可在 AI 编程会话中调用 yigraf 工具。

使用步骤

1. 初始化仓库：在目标代码仓库中执行 yigraf init，yigraf 会扫描代码结构并建立初始的代码-意图映射图谱。

2. 代理自主记录认知：当代理在开发过程中做决策时（如确定某个方案、记录架构约束、标记待办），可通过 MCP 工具将认知写入 yigraf 图，指定节点类型、理由和锚定代码位置。

3. 代码变更触发检测：当 Git commit 或代码文件变更后，代理调用 yigraf check 命令，yigraf 会对比变更代码与图中各节点的锚定位置，输出可能已失效的认知列表。

4. 认知修订：代理根据 check 结果，使用 yigraf update 或 yigraf retract 命令更新或撤回已失效的认知节点，保持图的真实性。

5. 查询历史决策：使用 yigraf query 按语义或结构查询历史认知，例如查询某个文件上个月确定的架构约束，代理据此恢复上下文。

适用场景

1. 大型代码库长期维护：当项目跨越数月甚至数年，开发者（或 AI 代理）换人后，yigraf 提供了可检索的决策理由知识库，新成员可以快速了解某个设计选择的原因。
2. AI 代理多会话协作：AI 代理在多个工作会话中持续开发同一项目，yigraf 充当长期记忆层，避免代理每次从零开始理解项目历史。
3. 架构约束追踪：架构决策记录（ADR）往往存在于文档中但与实际代码脱节，yigraf 将约束锚定到代码本身，代码变更时自动触发约束有效性审查。
4. 渐进式重构辅助：在进行大规模重构前，yigraf 帮助代理了解哪些既有假设会被新代码影响，提前规划重构步骤。
5. Code Review 上下文恢复：reviewer 可以通过 yigraf 查询某个 PR 涉及的历史决策背景，理解改动的动机而非只看到 diff。

适用人群

• 使用 Claude Code、Cursor、Windsurf、Codex 等 AI 编码代理的专业开发者
• 维护大型、多人协作代码库的架构师和高级工程师
• 需要 AI 代理具备长期项目记忆的团队
• 关注代码决策可追溯性的技术管理者
• 研究 AI Agent 记忆与推理系统的研究人员

工作原理

yigraf 的核心是一个基于 NetworkX 的有向图数据库，图中的节点代表代理的认知（Belief），边代表认知间的逻辑关系。每个认知节点包含：content（认知内容）、anchor（锚定代码位置）、grounding_tier（置信度层级）、alternatives（被排除的替代方案）、created_at / invalidated_at（创建和失效时间戳）。

yigraf 通过 Tree-sitter 持续监控锚定代码的状态。当代码变更后，它比较变更前后的 AST，识别受影响的节点范围，然后根据节点与变更范围的交集判断置信度是否需要降级。代理通过 MCP 协议向 yigraf 查询当前有效的认知切片，用于决策和推理。

官方链接

• PyPI 主页：https://pypi.org/project/yigraf/
• GitHub 仓库：https://github.com/mansilla/yigraf
• MCP 协议文档：https://modelcontextprotocol.io