代码库文档感知

MyDeskBot 如何利用文档更好地理解您的代码库。

什么是代码库文档感知？

代码库文档感知是 MyDeskBot 读取和理解项目文档的能力，包括 README 文件、API 文档、架构图和代码注释，以提供更准确和相关的帮助。

文档类型

1. 项目文档

• README.md：项目概述和入门指南
• CONTRIBUTING.md：贡献指南
• ARCHITECTURE.md：架构说明
• CHANGELOG.md：变更日志
• docs/：详细文档目录

2. API 文档

• OpenAPI/Swagger：API 规范
• JSDoc/TSDoc：代码注释文档
• Docstrings：Python/Golang 文档字符串
• Javadoc：Java 文档

3. 架构文档

• 架构图：系统架构可视化
• 数据流图：数据流动的说明
• 服务图：微服务关系
• 部署图：部署架构

4. 代码注释

• 内联注释：解释复杂逻辑
• 函数/类文档：API 文档
• 类型注释：类型说明
• TODO/FIXME：未来工作标记

如何工作

1. 文档索引

MyDeskBot 索引您的文档：

项目文档
├── README.md
├── ARCHITECTURE.md
├── API.md
└── docs/
    ├── getting-started.md
    ├── api-reference.md
    └── deployment.md

索引内容包括：
- 文件路径
- 文档类型
- 关键词
- 代码引用
- 关联文件

2. 上下文构建

当您提问时，MyDeskBot 构建上下文：

用户："如何创建新用户？"

上下文构建：
1. 查找文档中提及"创建用户"
2. 查找相关 API 端点
3. 查找示例代码
4. 查找数据模型
5. 查找相关教程

3. 相关性评分

MyDeskBot 对文档进行相关性评分：

查询："创建用户"

相关文档：
1. API.md - 95% 匹配（包含 POST /users 端点）
2. README.md - 60% 匹配（概述中提及）
3. ARCHITECTURE.md - 40% 匹配（架构中提及用户模块）

配置

文档源配置

{
  "mydeskbot.documentationAwareness": {
    "enabled": true,
    "sources": {
      "markdown": ["**/*.md"],
      "api": ["**/openapi.yaml", "**/swagger.json"],
      "docs": ["docs/**"],
      "readme": ["README.md", "readme.md"],
      "architecture": ["ARCHITECTURE.md", "**/architecture/**"]
    },
    "exclude": ["node_modules/**", "**/CHANGELOG.md", "**/LICENSE"]
  }
}

优先级配置

设置文档优先级：

{
  "mydeskbot.documentationAwareness.priorities": {
    "api": 100,
    "architecture": 90,
    "readme": 80,
    "code": 70,
    "markdown": 60
  }
}

使用示例

示例 1：利用 README

用户："如何安装依赖？"

MyDeskBot：根据 README.md：

安装步骤：
1. 克隆仓库
2. 运行 npm install
3. 配置 .env 文件
4. 运行 npm start

详细信息：
README.md 第 15-25 行

示例 2：利用 API 文档

用户："创建用户的 API 端点是什么？"

MyDeskBot：根据 API.md：

POST /api/users

请求体：
{
  "name": "string",
  "email": "string",
  "password": "string"
}

响应：
{
  "id": "number",
  "name": "string",
  "email": "string"
}

错误：
400 - 无效输入
409 - 邮箱已存在

示例 3：利用架构文档

用户："认证是如何工作的？"

MyDeskBot：根据 ARCHITECTURE.md：

认证流程：
1. 用户提交凭证到 /auth/login
2. AuthService 验证凭证
3. 生成 JWT 令牌
4. 返回令牌给客户端
5. 客户端在后续请求中包含令牌
6. AuthMiddleware 在受保护路由前验证令牌

组件：
- AuthService (src/services/auth.ts)
- AuthMiddleware (src/middleware/auth.ts)
- JWT Utils (src/utils/jwt.ts)

最佳实践

1. 保持文档更新

过时的文档会误导 MyDeskBot：

<!-- 好的文档 -->

## 安装

1. 运行 `npm install`
2. 复制 `.env.example` 到 `.env`
3. 运行 `npm start`

最后更新：2024-01-20

2. 使用标准格式

MyDeskBot 理解标准格式：

<!-- API 文档 -->

## POST /api/users

创建新用户。

**请求体：**

```json
{
  "name": "string",
  "email": "string"
}
```

响应：

{
  "id": "number"
}

### 3. 提供示例

示例帮助 MyDeskBot 理解：

```markdown
## 使用示例

```python
# 创建用户
user = User.create(
    name="John Doe",
    email="john@example.com"
)

# 获取用户
user = User.get_by_id(1)

### 4. 链接相关文档

建立文档之间的联系：

```markdown
参见：
- [API 文档](./API.md)
- [数据模型](./models.md)
- [认证](./auth.md)

5. 使用清晰的标题

清晰的标题帮助 MyDeskBot 导航：

<!-- 好 -->

# 用户 API

## 创建用户

## 获取用户

## 更新用户

## 删除用户

<!-- 不好 -->

# 用户

# CRUD 操作

# 列表

# 详情

高级功能

1. 交叉引用

MyDeskBot 跟踪文档交叉引用：

ARCHITECTURE.md:
  参见 API.md 了解端点详情
  参见 DEPLOYMENT.md 了解部署

API.md:
  实现：src/controllers/userController.ts

文档网络建立连接，提供完整上下文

2. 版本感知

MyDeskBot 理解版本文档：

docs/
├── v1.0/
│   └── api.md
├── v2.0/
│   └── api.md
└── v3.0/
    └── api.md

MyDeskBot 使用您项目的当前版本

3. 文档验证

验证文档与代码的一致性：

检查：
- API 端点是否存在
- 参数类型是否匹配
- 返回值是否正确
- 示例是否可运行

警告：
- "文档中的 /api/users 端点在代码中未找到"
- "示例代码中的 User.create() 不存在"

故障排除

文档未找到

问题：MyDeskBot 找不到文档

解决方案：

1. 检查文档路径
2. 验证文件扩展名
3. 检查排除模式
4. 强制重新索引

不相关的建议

问题：建议与文档不符

解决方案：

1. 更新文档
2. 使用标准格式
3. 添加更多示例
4. 增加文档优先级

性能问题

问题：文档索引缓慢

解决方案：

1. 减少文档数量
2. 排除大型文档
3. 禁用自动索引
4. 增加延迟

相关链接

• 代码库感知
• 自定义代码 RAG
• 理解配置