文档整理规则

文档整理规则

默认行为

整理文档时，除非明确要求，否则：

不要做的事情

• ❌ 不要编写代码示例 - 避免添加完整的代码块
• ❌ 不要整理具体的请求参数 - 用户可以自己查看 API 文档
• ❌ 不要整理具体的响应格式 - 详细的响应结构用户自己看
• ❌ 不要复制粘贴大段代码 - 保持文档简洁

应该做的事情

• ✅ 专注于逻辑结构 - 解释系统如何工作、流程如何进行
• ✅ 引用代码位置 - 使用 file_path:line_number 格式指向相关代码
• ✅ 整理架构和流程 - 说明组件如何交互、数据如何流动
• ✅ 提炼核心概念 - 解释关键设计决策和模式
• ✅ 组织层次结构 - 创建清晰的文档层级和导航

代码引用格式

当需要引用代码时，使用位置引用而非完整代码：

# 正确示例
用户认证流程在 `litellm/proxy/auth/user_api_key_auth.py:145` 中实现

# 错误示例
用户认证流程实现如下：
\`\`\`python
def user_api_key_auth(request):
    # 大段代码...
\`\`\`

文档组织重点

1. 概念层面 - 解释"是什么"和"为什么"
2. 架构层面 - 说明组件关系和依赖
3. 流程层面 - 描述执行顺序和决策点
4. 配置层面 - 指出关键配置项和影响

何时可以包含代码

仅在以下情况下包含代码示例：

• 用户明确要求代码示例
• 配置文件示例（YAML、JSON 等）
• 极简的关键代码片段（少于 5 行）用于说明核心概念

文档结构模板

# 功能名称

## 概述
[简要说明功能目的和价值]

## 架构
[组件关系图或文字描述]
- 核心组件位置：`path/to/file.py:line`
- 依赖组件位置：`path/to/dependency.py:line`

## 工作流程
1. [步骤 1 描述] - 实现位置：`file.py:line`
2. [步骤 2 描述] - 实现位置：`file.py:line`
3. [步骤 3 描述] - 实现位置：`file.py:line`

## 关键配置
[配置项说明，指向配置文件位置]

## 相关文档
[链接到其他相关文档]

明确要求时的例外

如果用户明确说：

• "给我代码示例"
• "展示完整的 API 参数"
• "我需要看具体的实现"

则可以提供详细的代码和参数说明。