其他管理方法

除了 Wiki，还有哪些方式可以管理上下文

---

前面章节回顾

在前面几节中，我们详细介绍了用 Wiki 管理上下文的方法，并通过"拉了么"项目展示了真实效果。

本节将补充其他管理上下文的方法，你可以根据实际情况选择。

---

方法对比

方法	优势	劣势	适合场景
Wiki 系统	全面、结构化	需要维护	中大型项目
README + 注释	简单、低成本	信息有限	小型项目
AI 项目记忆	自动、无需维护	不够可靠	辅助手段
代码即文档	同步性好	表达能力有限	API 文档
RAG 系统	智能检索	复杂、成本高	大型企业

---

方法 1：README + 代码注释

核心思路

在项目根目录放一个详细的 README.md，代码中写好注释。

README 应该包含

# 项目名称

## 项目简介
（一两句话说明项目做什么）

## 技术栈
- 前端：React + TypeScript
- 后端：Nest.js + PostgreSQL

## 快速开始
\`\`\`bash
npm install
npm run dev
\`\`\`

## 项目结构
\`\`\`
src/
├── components/    # 通用组件
├── pages/         # 页面
└── utils/         # 工具函数
\`\`\`

## 开发规范
- 命名：camelCase
- 注释：JSDoc
- 提交：Conventional Commits

## 常见问题
### Q: 如何运行测试？
A: npm test

代码注释示例

/**
 * 用户服务
 *
 * 负责用户相关的业务逻辑：
 * - 用户注册/登录
 * - 用户信息查询/更新
 * - 密码加密和验证
 *
 * @author 你的名字
 * @since 2024-06-01
 */
class UserService {
  /**
   * 用户注册
   *
   * @param phone 手机号（必须唯一）
   * @param password 密码（至少 8 位）
   * @returns 新创建的用户 ID
   *
   * @throws DuplicatePhoneError 手机号已存在
   * @throws InvalidPasswordError 密码不符合要求
   */
  async register(phone: string, password: string): Promise<string> {
    // ...
  }
}

优缺点

优势：

• ✅ 简单，不需要额外工具
• ✅ 代码和注释在一起，容易同步
• ✅ AI 可以读取代码和注释

劣势：

• ❌ 信息量有限
• ❌ 不适合复杂的业务说明
• ❌ 不如 Wiki 结构化

适合场景

• 个人项目
• 小型项目（代码量 < 1 万行）
• 学习项目

---

方法 2：利用 AI 的项目记忆功能

核心思路

使用 Claude Projects、ChatGPT Custom Instructions 等功能，让 AI "记住"项目信息。

Claude Projects 示例

1. 创建项目

项目名称：拉了么
项目描述：外卖订餐系统

2. 上传关键文档

• README.md
• 技术栈说明
• API 文档
• 数据模型

3. 设置项目指令

这是一个外卖订餐系统，技术栈：
- 前端：React + TypeScript
- 后端：Nest.js + PostgreSQL
- 代码风格：参考 src/modules/user 模块

回答问题时：
1. 优先参考项目文档
2. 代码要符合项目规范
3. 考虑业务规则

4. 开始对话

你：帮我写一个订单创建功能

AI：（参考项目文档）我看了你的项目，给你写一个符合规范的实现...

优缺点

优势：

• ✅ AI 自动管理，无需手动更新
• ✅ 可以上传 PDF、Word 等多种格式
• ✅ 适合快速了解项目

劣势：

• ❌ 依赖特定平台（Claude/ChatGPT）
• ❌ 不如本地 Wiki 灵活
• ❌ 可能不是最新的（取决于上传的文档版本）

适合场景

• 快速原型开发
• 个人项目
• 作为 Wiki 的补充

---

方法 3：代码即文档（API 文档自动生成）

核心思路

用工具从代码自动生成 API 文档，保证文档和代码同步。

常用工具

TypeScript/JavaScript：

• TypeDoc（从类型注释生成文档）
• JSDoc（从注释生成文档）

Java：

• Javadoc

Python：

• Sphinx + autodoc

Go：

• godoc

示例：TypeDoc

代码中写注释：

/**
 * 订单服务
 */
export class OrderService {
  /**
   * 创建订单
   *
   * @param userId - 用户 ID
   * @param items - 订单明细
   * @param couponId - 优惠券 ID（可选）
   * @returns 创建的订单
   *
   * @throws InventoryNotEnoughError 库存不足
   * @throws CouponExpiredError 优惠券已过期
   */
  async createOrder(
    userId: string,
    items: OrderItem[],
    couponId?: string
  ): Promise<Order> {
    // ...
  }
}

生成文档：

npx typedoc --out docs src

生成的 HTML 文档：

• 包含所有 API
• 类型信息完整
• 可以搜索和导航

优缺点

优势：

• ✅ 文档和代码完全同步
• ✅ 类型信息准确
• ✅ 适合 API 文档

劣势：

• ❌ 只能表达代码层面信息
• ❌ 不适合业务逻辑说明
• ❌ 需要写详细注释

适合场景

• API 文档
• 函数库/SDK
• 组件库

---

方法 4：RAG 系统（高级）

核心思路

搭建 RAG（Retrieval-Augmented Generation）系统，让 AI 从文档库中智能检索相关信息。

架构

┌─────────────────────────────────────────────────────┐
│                      用户提问                        │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│                  RAG 系统                            │
│  1. 理解问题意图                                     │
│  2. 从向量数据库检索相关文档                         │
│  3. 将文档作为上下文传递给 LLM                       │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│                    LLM                               │
│  基于检索到的文档生成答案                             │
└─────────────────────────────────────────────────────┘

技术栈

向量数据库：

• Pinecone
• Weaviate
• Chroma
• pgvector（PostgreSQL 扩展）

框架：

• LangChain
• LlamaIndex

示例流程

# 1. 将文档存入向量数据库
documents = load_wiki_docs("./wiki")
vector_db.add(documents)

# 2. 用户提问
question = "订单创建后如何扣减库存？"

# 3. 检索相关文档
relevant_docs = vector_db.search(question, top_k=3)

# 4. 传递给 LLM
answer = llm.generate(
    prompt=f"""
    根据以下文档回答问题：

    文档：
    {relevant_docs}

    问题：{question}
    """
)

优缺点

优势：

• ✅ 智能检索，找得到相关信息
• ✅ 可以处理大量文档
• ✅ 支持自然语言提问

劣势：

• ❌ 搭建复杂
• ❌ 成本较高（向量数据库托管费）
• ❌ 需要技术维护

适合场景

• 大型企业项目
• 文档量非常大（> 1000 页）
• 有专门的维护团队

---

如何选择？

决策树

项目规模
    ├─ 个人/小型项目（< 1 万行代码）
    │   └─→ README + 注释
    │
    ├─ 中型项目（1-10 万行代码）
    │   └─→ Wiki 系统（VitePress）
    │
    └─ 大型项目（> 10 万行代码）
        └─→ Wiki + RAG 系统

组合使用

实际项目中，通常是组合使用：

README + Wiki + 代码注释 + AI Projects
    ↓
多层防护，确保 AI 能够理解项目

示例：

• README：快速了解项目（5 分钟）
• Wiki：深入了解项目（30 分钟）
• 代码注释：理解具体实现（随时查阅）
• AI Projects：让 AI "记住"项目（提升效率）

---

总结

核心观点

没有最好的方法，只有最适合的方法。

选择原则：

1. 根据项目规模选择
2. 根据团队规模选择
3. 根据维护成本选择
4. 可以组合使用

推荐方案

零基础学习者：

• 从 README + 注释开始
• 逐渐补充成 Wiki

小团队项目：

• VitePress 搭建 Wiki
• 配合良好的代码注释

大型项目：

• 完整的 Wiki 系统
• RAG 系统辅助检索
• 严格的文档维护流程

---

模块二总结

恭喜你完成了上下文管理模块的学习！

通过本模块，你应该掌握了：

• ✅ 什么是上下文，为什么需要管理
• ✅ 如何用 Wiki 系统管理项目上下文
• ✅ "拉了么"项目的真实实践案例
• ✅ 其他上下文管理方法

下一步

接下来，我们将学习 Skills 机制，了解 Skills 和 MCP 的关系，以及如何用 Skills 提升 AI 能力。

---

← 返回模块目录 | 继续学习：Skills 指南 →