使用 Windsurf 为 Deep Research 项目添加中文支持在开源社区中，优秀的项目往往面临着一个共同的挑战

本文也是用ai生成的😼

[Deep Research 项目主页] https://github.com/dzhng/deep-research

[项目中文文档] https://github.com/huixiangyang/deep-research/tree/zh-cn/README.zh-CN.md

[Windsurf IDE 官网] https://windsurf.dev

在开源社区中，优秀的项目往往面临着一个共同的挑战：如何让非英语母语的开发者更好地理解和使用代码。今天，我想分享一下我使用 Windsurf 为 Deep Research 项目添加中文注释和文档的经历。

Deep Research 介绍

Deep Research 诞生于一个简单而强大的想法：如何让 AI 辅助人类进行深度研究？在信息爆炸的时代，我们往往会被大量的信息所淹没。Deep Research 通过结合 AI 技术和搜索引擎，帮助研究者快速获取、分析和整理信息，生成有价值的研究报告。

核心功能详解

智能查询生成
- 基于用户初始问题自动生成优化的搜索查询
- 使用 AI 模型分析查询结果，提取关键信息
- 根据已获得的信息动态调整后续查询策略
递归深入研究
- 支持多层次的研究深度，每层都能发掘新的见解
- 通过广度参数控制每层的搜索范围
- 智能避免信息重复，确保研究的效率
实时进度追踪
- 可视化显示研究的深度和广度进度
- 实时更新当前查询状态
- 清晰展示已完成的查询数量
交互式反馈机制
- 生成针对性的跟进问题
- 根据用户反馈调整研究方向
- 支持实时调整研究参数

文件结构

deep-research/
├── src/
│   ├── run.ts              # 程序入口
│   ├── deep-research.ts    # 核心研究逻辑
│   ├── feedback.ts         # 反馈生成模块
│   ├── prompt.ts           # AI 提示模板
│   └── output-manager.ts   # 输出管理模块
├── ARCHITECTURE.md         # 架构文档
└── README.md              # 项目说明

技术架构详解

Deep Research 采用模块化设计，每个模块都有其明确的职责：

入口模块 (run.ts)

async function run() {
  // 获取用户输入
  const initialQuery = await askQuestion('研究主题？');
  // 设置研究参数
  const breadth = await askQuestion('研究广度？');
  const depth = await askQuestion('研究深度？');
  // 执行研究流程
  const result = await deepResearch({ query, breadth, depth });
}

核心研究模块 (deep-research.ts)
- 实现递归研究算法
- 管理研究状态和进度
- 整合多个信息源的数据
反馈生成模块 (feedback.ts)
- 分析用户初始查询
- 生成相关的跟进问题
- 优化研究方向
AI 提示模块 (prompt.ts)
- 管理与 AI 模型的交互
- 优化提示模板
- 确保输出质量
输出管理模块 (output-manager.ts)
- 处理终端输出
- 显示进度条
- 格式化研究报告

工作流程示例

以研究"人工智能在教育领域的应用"为例：

初始阶段
- 用户输入主题
- 系统生成跟进问题：
  - "您对哪个教育阶段最感兴趣？"
  - "是否关注特定的 AI 技术？"
  - "想了解技术实现还是应用案例？"
研究执行
- 根据用户反馈生成优化查询
- 并行处理多个信息源
- 递归深入相关主题
报告生成
- 整合所有研究发现
- 生成结构化报告
- 提供参考来源

注释本地化示例

/**
 * Deep Research - 核心研究模块
 * 
 * 该模块实现了深度研究的核心算法，包括：
 * 1. 查询生成和优化
 * 2. 搜索结果处理
 * 3. 内容分析和学习提取
 * 4. 研究报告生成
 */

用户界面文本本地化

const messages = {
  researchTopic: '您想研究什么主题？',
  researchDepth: '请输入研究深度（建议 1-5）：',
  researchBreadth: '请输入研究广度（建议 2-10）：',
  generatingPlan: '正在创建研究计划...',
  startingResearch: '开始研究您的主题...'
};

代码分析

查询优化算法

async function generateSerpQueries({
  query,
  numQueries = 3,
  learnings,
}) {
  // 使用 AI 模型分析查询
  const res = await generateObject({
    model: o3MiniModel,
    system: systemPrompt(),
    prompt: `根据用户查询生成优化的搜索列表...`,
    schema: z.object({
      queries: z.array(z.object({
        query: z.string(),
        researchGoal: z.string(),
      }))
    })
  });
  return res.object.queries;
}

进度追踪系统

export class OutputManager {
  private progressLines: number = 4;
  private progressArea: string[] = [];
  
  updateProgress(progress: ResearchProgress) {
    this.progressArea = [
      `深度：    [${this.getProgressBar(progress.totalDepth - progress.currentDepth, progress.totalDepth)}]`,
      `广度：    [${this.getProgressBar(progress.totalBreadth - progress.currentBreadth, progress.totalBreadth)}]`,
      `查询：    [${this.getProgressBar(progress.completedQueries, progress.totalQueries)}]`,
      progress.currentQuery ? `当前查询：${progress.currentQuery}` : ''
    ];
    this.drawProgress();
  }
}

内容分析与提取

async function processSerpResult({
  query,
  result,
  numLearnings = 3,
}) {
  const contents = compact(result.data.map(item => item.markdown));
  const res = await generateObject({
    model: o3MiniModel,
    prompt: `分析搜索结果并提取关键信息...`,
    schema: z.object({
      learnings: z.array(z.string()),
      followUpQuestions: z.array(z.string())
    })
  });
  return res.object;
}