knowledge-graph

知识图谱技能

概述

知识图谱（KG）是一个持久化 JSON 文件，用于存储代码库分析中发现的信息，避免重复探索并支持任务验证。

位置：docs/specs/[ID-feature]/knowledge-graph.json

主要优势：

• ✅ 避免重复探索已分析过的代码库
• ✅ 根据代码库的实际状态验证任务依赖项
• ✅ 在团队成员之间共享发现
• ✅ 利用缓存的上下文加快任务生成

使用时机

在以下情况下使用此技能：

1. spec-to-tasks 需要缓存／复用代码库分析结果 - 存储 Agent 的发现以供后续复用
2. task-implementation 需要验证任务依赖项和契约 - 在实现前检查所需组件是否存在
3. 任何命令需要查询现有模式／组件／API - 检索缓存的代码库上下文
4. 减少重复的代码库探索 - 避免重新分析已探索过的代码

触发短语：

• “加载知识图谱”
• “查询知识图谱”
• “更新知识图谱”
• “根据知识图谱进行验证”
• “检查组件是否存在”
• “查找现有模式”

说明

可用操作

1. read-knowledge-graph - 加载并解析某项规格的 KG

• 输入：规格文件夹的路径（例如，docs/specs/001-feature/）
• 输出：包含元数据、模式、组件和 API 的 KG 对象

2. query-knowledge-graph - 查询特定部分（组件、模式、API）

• 输入：规格文件夹、查询类型、可选筛选条件
• 输出：符合条件的筛选结果

3. update-knowledge-graph - 使用新发现更新 KG

• 输入：规格文件夹、更新内容（部分 KG）、来源描述
• 输出：合并新发现后的 KG

4. validate-against-knowledge-graph - 根据 KG 验证任务依赖项

• 输入：规格文件夹、需求（组件、API、模式）
• 输出：包含错误／警告的验证报告

5. validate-contract - 验证任务之间的提供项／预期项

• 输入：规格文件夹、预期项（文件 + 符号）、已完成的依赖项
• 输出：预期项已满足／未满足的报告

6. extract-provides - 从已实现的文件中提取符号

• 输入：文件路径数组
• 输出：包含文件、符号和类型的提供项数组

7. aggregate-knowledge-graphs - 合并所有规格中的模式

• 输入：项目根路径
• 输出：去重模式后的全局 KG

详细用法示例请参阅 references/query-examples.md。

示例

输入／输出示例

读取知识图谱：

Input: /knowledge-graph read docs/specs/001-hotel-search/
Output: {
  metadata: { spec_id: "001-hotel-search", version: "1.0" },
  patterns: { architectural: [...], conventions: [...] },
  components: { controllers: [...], services: [...]}
}

查询组件：

Input: /knowledge-graph query docs/specs/001-hotel-search/ components {"category": "services"}
Output: [{ id: "comp-svc-001", name: "HotelSearchService", type: "service"}]

更新知识图谱：

Input: /knowledge-graph update docs/specs/001-hotel-search/ {
  patterns: { architectural: [{ name: "Repository Pattern"}] }
}
Output: "Added 1 pattern to knowledge graph"

验证依赖项：

Input: /knowledge-graph validate docs/specs/001-hotel-search/ {
  components: ["comp-repo-001"]
}
Output: { valid: true, errors: [], warnings: [] }

完整的工作流示例请参阅 references/examples.md。

KG 架构参考

完整的 JSON 架构及示例请参阅 references/schema.md。

集成模式

与 Developer Kit 命令集成的详细信息请参阅 references/integration-patterns.md。

错误处理

全面的错误处理策略和恢复流程请参阅 references/error-handling.md。

性能注意事项

优化策略和性能特征请参阅 references/performance.md。

安全性

安全注意事项、威胁缓解措施和最佳实践请参阅 references/security.md。

最佳实践

何时查询 KG：代码库分析、任务生成、依赖项验证之前

何时更新 KG：Agent 有新发现、组件实现完成、发现新模式之后

KG 新鲜度：

• < 7 天：新鲜
• 7-30 天：已过时，提醒用户

• 30 天：严重过时，建议重新生成

详细的最佳实践请参阅 references/performance.md 和 references/security.md。

约束与警告

关键约束

• 源代码安全操作：不会修改源代码文件。只会创建或更新 knowledge-graph.json 文件。
• 路径验证：仅从 docs/specs/[ID]/ 路径读取或写入 KG 文件。
• 不自动生成代码：会缓存分析结果，但不会生成实现代码。

局限性

• 验证范围：会检查组件是否存在于 KG 中，但如果 KG 已过时，则无法验证组件是否存在于实际代码库中
• 新鲜度依赖：KG 的准确性取决于它最近一次更新的时间
• 优先支持单个规格：每个 KG 主要针对单个规格
• 文件大小：对于复杂规格，KG 文件可能会变得很大（>1MB）

有关完整的约束和警告，请参阅 references/error-handling.md 和 references/security.md。

参考文件

• schema.md - 完整的 JSON 架构
• query-examples.md - 查询模式
• integration-patterns.md - 命令集成
• error-handling.md - 错误处理指南
• performance.md - 性能优化
• security.md - 安全注意事项
• examples.md - 实用示例