企业官网建设流程全解析

最近在重构公司的 NestJS 微服务模块，为了对比不同模型的长上下文生成效果，我一直在用 kulaai（leadhi.cn）这个 AI 模型聚合平台来回切模型测试。今天借此聊聊深度使用 Gemini 3.5 辅助编程的一个实战场景：30 分钟内给一个 NestJS 项目生成完整的代码注释。

为什么选 Gemini 3.5 做这件事

"写代码一时爽，补文档火葬场。"——这大概是每个开发者最真实的写照。高质量的 API 文档和代码注释不仅能拯救交接项目的同事，更是团队工程规范的底线。

手动注释一个中型 NestJS 项目（30+ 个 Controller + Service），至少需要 4-6 小时。但 Gemini 3.5 凭借 100 万 token 的上下文窗口，可以一次性吃下整个项目的源代码，直接基于现有代码风格生成注释。这个能力在代码注释场景下优势明显。

Gemini 3.5 Flash 在 Terminal-Bench 编码测试上拿了 76.2%，速度 289 tokens/s，比 Claude Opus 4.7 和 GPT-5.5 快 4 倍以上。价格 1.50/百万token输入、1.50/百万token输入、9.00/百万 token 输出。对注释这种"量大但不需要深度推理"的任务，Flash 版本的性价比极高。

准备工作：导出项目上下文

在提示词设计之前，先把项目的关键信息整理好。

第一步：导出项目目录树。在终端执行tree src/ --prune -I node_modules，得到一个简短的目录结构。

第二步：合并核心代码文件。把需要注释的 Controller、Service、DTO、Module 文件合并为一个长文本。Gemini 3.5 的上下文窗口能轻松容纳整个中型项目。

第三步：提供"项目拓扑"。在 Prompt 中明确告诉它哪些是核心文件、哪些是调用上下文参考。这一步很关键——Gemini 3.5 虽然能装下整个项目，但如果直接无脑丢二三十个文件，注意力机制会产生"大海捞针"式的衰减。

提示词设计：约束优先，过滤幻觉

提示词怎么写决定注释质量。"帮我写注释"和"为每个 Controller 方法生成符合 NestJS 规范的 JSDoc 注释，包含 @summary、@description、@param、@returns 标签"——两个提示词得到的结果差距非常大。

我实测通过率最高的一套提示词模板：

text

text

【角色】你是一个精通 NestJS 和 TypeScript 的高级后端工程师。 【上下文】以下是当前项目的目录结构和核心代码文件： src/ ├── modules/ │ ├── user/ │ │ ├── user.controller.ts (核心待注释文件) │ │ ├── user.service.ts (核心待注释文件) │ │ └── dto/ │ │ └── create-user.dto.ts │ └── order/ │ ├── order.controller.ts │ └── order.service.ts ├── common/ │ └── guards/auth.guard.ts (调用上下文参考) 【任务】请为上述所有 Controller 和 Service 文件中的每个公开方法生成完整的 JSDoc 注释。 【规范】 1. 使用 @summary 一行概括方法功能 2. 使用 @description 详细说明业务逻辑 3. 使用 @param 标注每个参数的类型和含义 4. 使用 @returns 标注返回值类型和含义 5. 使用 @throws 标注可能抛出的异常 6. 对于使用了装饰器的方法（如 @UseGuards），在注释中说明权限要求 【限制】 - 禁止使用 "// 保持不变"、"// 省略其余代码" 等占位符 - 即使是没有修改的方法和类成员，也必须完整输出 - 我需要直接复制并替换整个文件 - 注释语言使用英文，符合 JSDoc 标准规范

这个模板有三个关键设计：

约束优先。把注释规范写死在提示词里，避免模型自由发挥。Gemini 3.5 有时会"热心"地多写两段解释，但注释场景我们只需要结构化的 JSDoc 标签。

强制无损输出。Gemini 3.5 特别喜欢在生成长文件时使用// 此处省略其余代码的占位符。在自动化 CI/CD 或直接 Copy 代码时，这简直是灾难。所以必须在提示词中明确禁止。

文件拓扑引导。明确标注哪些是核心待注释文件、哪些是上下文参考。这样模型的注意力会集中在核心文件上，上下文参考文件只用来理解调用关系。

实战过程：分步生成，逐文件校验

复杂功能拆成小步骤分步生成，比一次性描述所有需求效果好。

第一轮：Controller 层注释（约 10 分钟）。把所有 Controller 文件一次性喂给 Gemini 3.5，让它只处理 Controller 方法的注释。生成的 JSDoc 注释质量很高——@summary 精准概括、@param 和 @returns 类型标注完整、@throws 异常说明到位。

第二轮：Service 层注释（约 10 分钟）。同样的方式处理 Service 文件。Service 层的注释需要更多业务逻辑描述，Gemini 3.5 在这方面表现不错——它能根据代码中的 Prisma 调用和条件判断，推断出业务意图。

第三轮：DTO 和 Guard 注释（约 5 分钟）。DTO 文件通常较短，一次性生成即可。Guard 文件的注释重点是权限说明，Gemini 3.5 能正确识别@UseGuards装饰器并说明所需角色。

第四轮：校验和修正（约 5 分钟）。逐文件检查生成的注释，主要关注三个方面：

实测效率数据

30 分钟搞定一个中型 NestJS 项目的完整代码注释。

三个必须注意的坑

第一，Gemini 3.5 偶尔会"发明"不存在的参数。对于复杂的 DTO，它有时会根据业务语义推测出代码中未定义的字段。校验时重点检查 @param 标注是否和代码中的实际参数一致。

第二，注释语言风格需要约束。如果不指定注释语言，Gemini 3.5 默认用英文，但偶尔会在英文注释中夹杂中文说明。建议在系统指令中明确写死语言要求。

第三，Temperature 要调低。代码注释是"确定性"任务，不需要创意。建议将温度值调低至 0.1 或 0，防止模型自己"发明"注释内容。

趋势：AI 代码注释正在从"可选"变成"标配"

两个判断。

第一，代码注释的自动化程度正在快速提升。从 GitHub Copilot 的实时补全注释，到 Compodoc 的自动化文档生成，再到 Teable 的"代码即文档"理念，整个行业正在把注释从"人力密集型工作"变成"自动化流水线"。Gemini 3.5 的 100 万 token 上下文窗口，让"一次性注释整个项目"成为现实。

第二，混合使用多个模型是当前务实策略。注释这种"量大、结构化、不需要深度推理"的任务，用 Gemini 3.5 Flash 的性价比最高——速度快、价格低。但如果需要注释复杂的业务逻辑或算法实现，可以灵活切换到 Claude 或 GPT-5.5 做局部深度注释。通过聚合平台灵活切换，比绑定单一模型更稳妥。

拿自己的真实项目跑一遍，比看任何评测都靠谱。

效率数据基于 2026 年 Q2 实测整理，模型能力以最新公告为准。提示词模板参考社区最佳实践。