Knowledge Base Builder

知识库构建器

知识库构建器技能可帮助你创建、构建和维护知识库，让 AI Agent 能够有效查询和利用其中的内容。它会将分散的信息（从项目文档到团队隐性知识）转化为有条理、易于访问的知识，从而提升 AI 性能和团队工作效率。

此技能将引导你完成知识提取、组织、构建和维护。它能够理解不同的知识格式（文档、代码注释、决策日志、架构），帮助你选择合适的存储方式（Markdown 文件、知识图谱、数据库），并确保知识保持最新且实用。

在启动新项目、让 AI 熟悉复杂系统、保留组织知识，或通过提供更好的上下文来提升 AI Agent 效能时，请使用此技能。

核心工作流

工作流 1：从零构建知识库

1. 定义 知识库的用途：
   • 谁会使用它？（AI Agent、开发者，或两者）
   • 它要解决什么问题？
   • 它的范围和边界是什么？
2. 识别 知识来源：
   • 现有文档
   • 代码仓库
   • 团队讨论
   • 决策记录
   • 团队隐性知识
3. 提取 相关信息：
   • 核心概念及其关系
   • 架构决策
   • 领域术语
   • 常见模式
   • 故障排查知识
4. 构建 知识：
   • 选择组织方式（层级式、图谱式、混合式）
   • 定义类别和分类体系
   • 建立关系
   • 创建元数据架构
5. 格式化 以便使用：
   • 使用 Markdown 编写文档
   • 使用知识图谱描述关系
   • 使用架构文件描述结构
   • 使用代码注释说明实现
6. 填充 知识库：
   • 创建初始内容
   • 链接相关概念
   • 添加示例
   • 包含参考资料
7. 验证 可访问性：
   • AI 能找到信息吗？
   • 上下文是否充分？
   • 关系是否清晰？
8. 建立 维护流程

工作流 2：从代码库中提取知识

1. 分析 代码库结构：
   • 架构模式
   • 模块组织
   • 关键抽象
   • 数据流
2. 识别 可提取的知识：
   • 设计决策
   • API 契约
   • 数据模型
   • 业务逻辑
   • 边缘情况
3. 生成 文档：
   • 架构概述
   • 组件说明
   • API 参考
   • 数据字典
   • 集成指南
4. 创建 知识图谱：
   • 实体（模块、服务、模型）
   • 关系（依赖于、实现、扩展）
   • 观察信息（用途、约束、模式）
5. 链接 到代码：
   • 用于参考的文件路径
   • 函数签名
   • 配置位置
6. 维护 同步：
   • 在代码变更时更新
   • 让知识与代码保持版本同步
   • 尽可能自动化

工作流 3：组织项目知识

1. 审查 现有知识：
   • 有哪些现存文档？
   • 缺少什么？
   • 有哪些内容已过时？
   • 有哪些内容分散各处？
2. 定义 结构：
   • 文档层级
   • 文件组织方式
   • 命名规范
   • 交叉引用方式
3. 创建 核心文档：
   • README.md（概述、入门指南）
   • ARCHITECTURE.md（系统设计）
   • DECISIONS.md（ADR）
   • PIPELINE_STATUS.md（项目状态）
   • CONTRIBUTING.md（开发指南）
4. 建立 规范：
   • 文档模板
   • 元数据标准
   • 更新流程
   • 审查流程
5. 填充 内容：
   • 迁移现有文档
   • 编写新内容以填补空缺
   • 链接相关文档
   • 添加导航
6. 与 AI 集成：
   • 添加到上下文
   • 创建知识图谱条目
   • 启用发现功能
   • 测试可访问性

工作流 4：构建知识图谱

1. 识别实体：
   • 关键概念有哪些？
   • 需要记住什么？
   • 哪些事物之间存在关系？
2. 定义实体类型：
   • 项目（代码库、服务、应用）
   • 组件（模块、功能、函数）
   • 人员（团队成员、利益相关者）
   • 决策（架构选择）
   • 流程（工作流、程序）
   • 资源（文档、工具、依赖项）
3. 提取观察结果：
   • 关于每个实体的事实
   • 属性和特征
   • 背景和用途
   • 状态和情况
4. 映射关系：
   • 实体之间如何关联
   • 关系类型
   • 方向性
   • 强度／重要性
5. 存储到知识图谱中：
   • 使用 Memory MCP
   • 创建实体
   • 创建关系
   • 添加观察结果
6. 查询并验证：
   • 能否找到实体？
   • 关系是否合理？
   • 信息是否完整？
7. 持续维护：
   • 添加新实体
   • 更新观察结果
   • 添加新关系
   • 清理过时信息

工作流 5：维护知识库

1. 监控知识健康状况：
   • 使用频率
   • 过时内容
   • 覆盖范围的缺口
   • 用户反馈
2. 定期更新：
   • 反映代码变更
   • 记录新的决策
   • 添加新的模式
   • 删除已弃用的信息
3. 定期审查：
   • 每季度进行知识审计
   • 验证准确性
   • 检查完整性
   • 提高表达清晰度
4. 优化以便使用：
   • 提高可搜索性
   • 添加缺失的链接
   • 合并冗余内容
   • 丰富示例
5. 收集反馈：
   • 哪些内容令人困惑？
   • 缺少哪些内容？
   • 哪些内容最有用？
6. 迭代结构：
   • 如有需要，重新组织
   • 添加新类别
   • 改进导航
   • 优化元数据

快速参考

操作	命令／触发语
构建新的知识库	"为 [project] 构建知识库"
从代码库提取	"从代码库提取知识"
整理项目文档	"整理项目知识"
创建知识图谱	"为 [domain] 创建知识图谱"
更新知识库	"使用 [new info] 更新知识库"
审计知识	"审计知识库健康状况"
组织文档结构	"为 [project] 组织文档结构"

最佳实践

• 从目标开始：明确知识库应实现什么

  • 让 AI 理解代码库
  • 帮助新开发者熟悉项目
  • 保留架构决策
  • 记录领域知识

• 以便于发现为目标来组织：让信息易于查找

  • 层次清晰
  • 命名一致
  • 索引全面
  • 丰富的交叉链接
  • 添加元数据标签

• 兼顾 AI 和人类读者：两者都会使用这些内容

  • 语言清晰、简洁
  • 采用结构化格式（表格、列表）
  • 明确说明关系
  • 提供背景信息
  • 提供代码示例

• 保持内容更新：过时的知识比没有知识更糟

  • 随代码变更更新
  • 定期审查
  • 删除过时信息
  • 与代码同步进行版本管理

• 确保易于访问：知识必须易于获取

  • 从 README 添加链接
  • 在代码注释中引用
  • 添加到 AI 上下文中
  • 在知识图谱中创建

• 使用多种格式：不同的知识需要不同的格式

  • 使用 Markdown 编写说明文档
  • 使用知识图谱表示关系
  • 使用架构文件定义结构
  • 使用代码注释说明实现细节
  • 使用图表呈现架构

• 保留上下文：不只记录“是什么”，还要记录“为什么”

  • 为什么采用这种架构？
  • 为什么不选择其他方案？
  • 哪些约束影响了决策？
  • 做出了哪些权衡？

• 尽可能建立链接：关联相关概念

  • 交叉引用文档
  • 链接代码和文档
  • 关联相关决策
  • 引用外部资源

知识库结构

推荐的文件组织方式

/docs
  /README.md                 # Project overview
  /ARCHITECTURE.md           # System design
  /DECISIONS.md              # ADRs (Architecture Decision Records)
  /PIPELINE_STATUS.md        # Current project state
  /CONTRIBUTING.md           # Development guide
  /API.md                    # API reference
  /DATABASE.md               # Schema documentation
  /DEPLOYMENT.md             # Deployment guide
  /TROUBLESHOOTING.md        # Common issues
  /guides/                   # How-to guides
    /getting-started.md
    /development-workflow.md
    /testing.md
  /reference/                # Technical reference
    /components.md
    /utilities.md
    /configurations.md
  /decisions/                # Detailed ADRs
    /001-framework-choice.md
    /002-state-management.md

文档模板

ARCHITECTURE.md 模板

# Architecture

## Overview
[High-level system description]

## System Components
- **Component 1**: [Purpose and responsibility]
- **Component 2**: [Purpose and responsibility]

## Data Flow
[How data moves through the system]

## Key Design Decisions
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Technology Stack
- Frontend: [Technologies]
- Backend: [Technologies]
- Database: [Technologies]
- Infrastructure: [Technologies]

## Integration Points
- [External service 1]: [How we integrate]
- [External service 2]: [How we integrate]

## Security Considerations
[Security architecture and patterns]

## Scalability & Performance
[How system scales, performance characteristics]

DECISIONS.md 模板（ADR 日志）

# Architecture Decision Records

## ADR-001: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: Accepted | Proposed | Deprecated

**Context**:
[What is the issue we're trying to solve?]

**Decision**:
[What we decided to do]

**Consequences**:
- Positive: [Benefits]
- Negative: [Trade-offs]
- Neutral: [Other impacts]

**Alternatives Considered**:
1. [Alternative 1]: [Why rejected]
2. [Alternative 2]: [Why rejected]

---

## ADR-002: [Next Decision]
[...]

组件文档模板

# [Component Name]

## Purpose
[What this component does and why it exists]

## Location
`/path/to/component`

## Dependencies
- [Dependency 1]: [Why needed]
- [Dependency 2]: [Why needed]

## API
### Functions
- `functionName(params)`: [Description]

### Types
\`\`\`typescript
interface ComponentProps {
  // ...
}
\`\`\`

## Usage
\`\`\`typescript
// Example usage
\`\`\`

## Related Components
- [Component A]: [Relationship]
- [Component B]: [Relationship]

## Known Issues
- [Issue 1]: [Workaround]

知识图谱模式

软件项目的实体类型

Project
  - name
  - description
  - status (active, maintenance, deprecated)
  - tech_stack

Component
  - name
  - type (service, module, function)
  - location (file path)
  - purpose
  - status

Person
  - name
  - role
  - expertise_areas
  - current_focus

Decision
  - title
  - date
  - status
  - context
  - choice
  - rationale

Process
  - name
  - type (workflow, procedure, standard)
  - steps
  - triggers
  - outputs

Dependency
  - name
  - version
  - purpose
  - critical (boolean)

关系类型

Project --depends_on--> Dependency
Project --contains--> Component
Component --uses--> Component
Component --implements--> Decision
Person --owns--> Component
Person --made--> Decision
Decision --supersedes--> Decision
Component --documented_in--> Document
Process --governs--> Component

知识图谱创建示例

// Create entities
await memory.create_entities({
  entities: [
    {
      name: "id8labs-app",
      entityType: "Project",
      observations: [
        "Next.js 14+ application",
        "Uses Supabase for backend",
        "Deployed on Vercel",
        "Monorepo structure"
      ]
    },
    {
      name: "authentication-module",
      entityType: "Component",
      observations: [
        "Located in /src/features/auth",
        "Handles user authentication via Supabase Auth",
        "Supports magic link and OAuth",
        "Implements RLS policies"
      ]
    }
  ]
});

// Create relationships
await memory.create_relations({
  relations: [
    {
      from: "id8labs-app",
      to: "authentication-module",
      relationType: "contains"
    },
    {
      from: "authentication-module",
      to: "Supabase Auth",
      relationType: "uses"
    }
  ]
});

知识提取技巧

从代码中提取

• 函数／类文档：用途、参数、返回值
• 模块组织：结构和关系
• 设计模式：实现方法
• 错误处理：已知的故障模式
• 性能注意事项：优化说明

从对话中提取

• 已做出的决策：选择及其理由
• 已解决的问题：问题和解决方案
• 经验教训：哪些做法有效，哪些无效
• 未决问题：尚未解决的问题
• 行动事项：任务和负责人

从外部来源提取

• API 文档：集成指南
• 研究论文：技术方法
• Stack Overflow：常见解决方案
• 博客文章：最佳实践
• 会议演讲：行业模式

知识质量检查清单

优质的知识库条目应当：

• 标题清晰且具有描述性
• 解释“为什么”，而不只是“是什么”
• 包含具体示例
• 链接到相关概念
• 注明创建／更新日期
• 标明状态（当前、已弃用）
• 使用一致的格式
• 可通过搜索找到
• 提供充分的上下文
• 引用原始来源

维护计划

每日

• 做出新决策时及时记录
• 更新 PIPELINE_STATUS.md 中的进度
• 为复杂逻辑添加代码注释

每周

• 审查未决问题并更新
• 检查是否存在过时信息
• 如果端点发生变化，更新 API 文档
• 根据变更同步知识图谱

每月

• 审核知识库的完整性
• 审查并改进不清晰的文档
• 更新架构图
• 清理过时内容

每季度

• 全面审查知识库
• 根据需要重新组织结构
• 收集用户反馈
• 规划改进

工具与技术

存储选项

工具	最适用场景	格式
Markdown 文件	易于阅读的文档	仓库中的 .md 文件
Memory MCP	AI 可访问的关系	知识图谱
代码注释	实现上下文	JSDoc、行内注释
OpenAPI/GraphQL	API 契约	YAML/JSON 架构
Mermaid	可视化图表	图表即代码
Notion	协作文档	富文本、数据库

生成工具

• TypeDoc：从 TypeScript 生成文档
• JSDoc：从 JavaScript 生成文档
• Swagger/OpenAPI：生成 API 文档
• Mermaid：生成图表
• Supabase CLI：生成数据库类型

常见陷阱

• 过度记录：不要记录显而易见的内容
• 记录不足：不要假设读者已有相关知识
• 文档过时：这比没有文档更糟
• 信息分散：整合相关知识
• 缺少上下文：始终解释“为什么”
• 组织不善：让内容便于查找
• 缺少维护：知识库会逐渐失效
• 只用一种格式：根据不同需求使用合适的格式