MonkeyCode 文档自动生成：从代码到技术文档的一键转换方案

引言

"文档是代码的镜子，但大多数项目的镜子都是碎的。"

在软件开发中，文档维护是公认的痛点——API 文档过时、README 缺失、架构文档停留在项目初期的美好愿景中。MonkeyCode 的 AI 文档生成能力可以让你从代码一键生成高质量的技术文档，并保持与代码同步更新。

本文将全面介绍 MonkeyCode 的文档自动化能力——从 API 参考文档到架构设计文档，从 README 生成到变更日志维护。

🎯 核心信息

GitHub 仓库: https://github.com/monkeycode-ai/monkeycode

开源协议: Apache License 2.0

欢迎提交 Issue: 文档相关问题请标记 documentation 标签

一、为什么文档自动化如此重要？

1.1 文件现状诊断

┌─────────────────────────────────────────────────────────────┐
│               项目文档常见问题自查表                           │
├──────────────┬──────────┬──────────┬────────────────────────┤
│   问题        │ 严重程度  │ 影响范围  │    MonkeyCode 解决方案   │
├──────────────┼──────────┼──────────┼────────────────────────┤
│ API 文档过时  │ 🔴 严重  │ 所有调用者│ 自动从代码签名+注释生成   │
│ README 空洞   │ 🟡 中等  │ 新人上手  │ 一键生成完整项目 README   │
│ 架构文档缺失  │ 🔴 严重  │ 团队协作  │ 从代码结构推断架构关系图   │
│ 注释不规范   │ 🟡 中等  │ 代码可读性│ 批量规范化函数/类注释     │
│ 变更日志缺失  │ 🟠 较高  │ 发布管理  │ 自动从 Git log 生成       │
│ 决策记录空白  │ 🟡 中等  │ 知识传承  | 引导式 ADR（架构决策记录） │
└──────────────┴──────────┴──────────┴────────────────────────┘

1.2 文档自动化的 ROI

投入	传统方式	MonkeyCode 方式
编写 API 文档 (100 个接口)	5-8 人天	10 分钟
生成 README	2-4 小时	30 秒
补充 JSDoc 注释 (500 函数)	3-5 人天	15 分钟
更新变更日志	每次发布 30 分钟	自动同步 Git
文档与代码同步	持续人工维护	按需重新生成

二、API 文档自动生成

2.1 从代码到 OpenAPI 规范

// ===== 源代码：src/api/user.ts =====

import { Router, Request, Response } from 'express';
import { body, validationResult } from 'express-validator';
import { UserService } from '../services/user.service';
import { AuthService } from '../services/auth.service';
import { rateLimit } from '../middleware/rateLimit';

const router = Router();
const userService = new UserService();
const authService = new AuthService();

/**
 * 创建新用户
 * @route POST /api/v1/users
 * @param {string} body.email - 用户邮箱（必须唯一）
 * @param {string} body.password - 密码（至少 8 位，包含大小写字母和数字）
 * @param {string} body.name - 显示名称（2-50 字符）
 * @param {string} [body.avatar] - 头像 URL
 * @param {string} [body.role] - 角色，默认为 'user'
 * @returns {object} 201 - 创建成功，返回用户信息（不含密码）
 * @returns {object} 400 - 参数校验失败
 * @returns {object} 409 - 邮箱已存在
 * @example
 * // 成功创建用户
 * {
 *   "email": "user@example.com",
 *   "password": "SecurePass123",
 *   "name": "张三"
 * }
 */
router.post('/',
  rateLimit({ windowMs: 60000, max: 10 }),  // 每分钟最多 10 次
  [
    body('email').isEmail().normalizeEmail(),
    body('password').isLength({ min: 8 }).matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/),
    body('name').trim().isLength({ min: 2, max: 50 }),
    body('avatar').optional().isURL(),
    body('role').optional().isIn(['user', 'admin', 'editor']),
  ],
  async (req: Request, res: Response) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({
        error: { code: 'VALIDATION_ERROR', details: errors.array() }
      });
    }

    const { email, password, name, avatar, role } = req.body;

    // 检查邮箱是否已存在
    const existingUser = await userService.findByEmail(email);
    if (existingUser) {
      return res.status(409).json({
        error: { code: 'EMAIL_EXISTS', message: 'Email already registered' }
      });
    }

    // 创建用户
    const user = await userService.create({
      email,
      password: await authService.hashPassword(password),
      name,
      avatar,
      role: role || 'user',
    });

    // 返回用户信息（排除敏感字段）
    const { password: _, ...safeUser } = user;
    res.status(201).json({ data: safeUser });
  }
);

/**
 * 获取当前用户信息
 * @route GET /api/v1/users/me
 * @header {string} Authorization - Bearer JWT token
 * @returns {object} 200 - 当前用户信息
 * @returns {object} 401 - 未认证或 token 过期
 */
router.get('/me', authService.authenticate, async (req: Request, res: Response) => {
  res.json({ data: req.user });
});

export default router;

/* 请分析以上 Express Router 代码，生成完整的 OpenAPI 3.0 规范文档。

要求：
1. 提取所有路由路径和方法
2. 从 JSDoc 注解提取请求参数、响应格式、示例
3. 从 express-validator 规则提取校验约束
4. 从中间件提取速率限制等附加信息
5. 生成符合 OpenAPI 3.0 规范的 YAML 格式输出
6. 包含 Components/Schemas 定义
*/

2.2 MonkeyCode 生成的 OpenAPI 文档

openapi: 3.0.3
info:
  title: User API
  description: 用户管理相关接口
  version: 1.0.0
  contact:
    name: API Support
    email: dev@example.com

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 测试环境

paths:
  /users:
    post:
      summary: 创建新用户
      description: 注册一个新用户账号。邮箱必须唯一，密码需满足复杂度要求。
      operationId: createUser
      tags:
        - Users
      
      security:
        - {}
        
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              basic:
                summary: 基本注册
                value:
                  email: "user@example.com"
                  password: "SecurePass123"
                  name: "张三"
              with_role:
                summary: 指定角色注册
                value:
                  email: "admin@example.com"
                  password: "AdminPass456"
                  name: "管理员"
                  role: "admin"

      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
              example:
                data:
                  id: "usr_abc123"
                  email: "user@example.com"
                  name: "张三"
                  avatar: null
                  role: "user"
                  created_at: "2026-06-25T10:30:00Z"
                  
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error:
                  code: "VALIDATION_ERROR"
                  details:
                    - field: "password"
                      issue: "Password must contain at least one uppercase letter"
                      
        '409':
          description: 邮箱已存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: "EMAIL_EXISTS"
                  message: "Email already registered"

      x-rateLimit:
        windowMs: 60000
        max: 10

  /users/me:
    get:
      summary: 获取当前用户信息
      description: 返回当前认证用户的详细信息。
      operationId: getCurrentUser
      tags:
        - Users
      
      security:
        - bearerAuth: []
      
      parameters:
        - name: Authorization
          in: header
          required: true
          description: Bearer JWT 访问令牌
          schema:
            type: string
            example: "eyJhbGciOiJIUzI1NiIs..."

      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: 未认证或 token 过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer Token 认证

  schemas:
    CreateUserRequest:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          description: 用户邮箱（必须唯一）
          example: "user@example.com"
        password:
          type: string
          minLength: 8
          pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)'
          description: 密码（至少 8 位，包含大小写字母和数字）
          example: "SecurePass123"
        name:
          type: string
          minLength: 2
          maxLength: 50
          description: 显示名称
          example: "张三"
        avatar:
          type: string
          format: uri
          description: 头像 URL
        role:
          type: string
          enum: [user, admin, editor]
          default: user
          description: 用户角色

    UserResponse:
      type: object
      properties:
        id:
          type: string
          example: "usr_abc123"
        email:
          type: string
          format: email
        name:
          type: string
        avatar:
          type: string
          nullable: true
        role:
          type: string
        created_at:
          type: string
          format: date-time

    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  issue:
                    type: string

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

三、README 一键生成

3.1 完整项目 README 生成

/*
请基于以下项目信息生成完整的 GitHub README.md：

项目信息：
- 名称: MonkeyCode Server
- 类型: AI 编程助手后端服务
- 技术栈: TypeScript + Node.js + Express + PostgreSQL + Redis
- 许可证: Apache 2.0

目录结构：
src/
├── api/           # REST API 路由
├── services/      # 业务逻辑层
├── models/        # 数据模型
├── middleware/    # Express 中间件
├── utils/         # 工具函数
└── config/        # 配置管理

功能特性：
1. 多模型支持（OpenAI/Claude/本地模型）
2. 流式响应（SSE）
3. 用户认证（JWT + OAuth2）
4. 速率限制
5. 完整的审计日志

要求：
1. 使用标准的 GitHub README 结构
2. 包含 Badge（license、version、CI status）
3. 包含安装步骤（Docker + 手动两种方式）
4. 包含环境变量说明表格
5. 包含 API 快速开始示例
6. 包含贡献指南链接
7. 中英文双语标题（正文用中文）
*/

3.2 生成的 README 示果

<p align="center">
  <img src="logo.svg" width="120" alt="MonkeyCode Server">
</p>

<h1 align="center">🐵 MonkeyCode Server</h1>
<p align="center">
  <strong>AI 编程助手后端服务 — 开源、高效、可私有化部署</strong>
</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://github.com/monkeycode-ai/monkeycode/releases"><img src="https://img.shields.io/badge/version-v4.2.1-green.svg" alt="Version"></a>
  <a href="https://github.com/monkeycode-ai/monkeycode/actions"><img src="https://github.com/monkeycode-ai/monkeycode/workflows/CI/badge.svg" alt="CI"></a>
  <a href="https://discord.gg/monkeycode"><img src="https://img.shields.io/badge/chat-Discord-purple.svg" alt="Discord"></a>
</p>

---

## ✨ 功能特性

- 🧠 **多模型支持** — OpenAI GPT-4 / Claude 3.5 / 本地 LLM 无缝切换
- ⚡ **流式响应** — SSE 实时推送，首字延迟 < 200ms
- 🔐 **安全认证** — JWT + OAuth2 + MFA 多因素认证
- 🚦 **智能限流** — 基于用户级别的精细化速率控制
- 📊 **完整审计** — 符合等保要求的操作日志
- 🐳 **一键部署** — Docker Compose 开箱即用
- 🔌 **插件生态** — VSCode / JetBrains / Vim 全平台覆盖
- 🌍 **国际化** — 中英日韩多语言界面支持

## 📋 目录

- [快速开始](#快速开始)
- [安装部署](#安装部署)
- [配置说明](#配置说明)
- [API 文档](#api-文档)
- [开发指南](#开发指南)
- [贡献方式](#贡献方式)
- [许可证](#许可证)

## 🚀 快速开始

### Docker 部署（推荐）

```bash
# 克隆仓库
git clone https://github.com/monkeycode-ai/monkeycode.git
cd monkeycode

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的配置

# 一键启动
docker compose up -d

# 验证服务
curl http://localhost:8443/health

手动安装

# 安装依赖
npm install

# 数据库迁移
npm run db:migrate

# 启动开发服务器
npm run dev

# 启动生产服务器
npm start

⚙️ 配置说明

环境变量	必填	默认值	说明
`PORT`	否	`8443`	服务监听端口
`DATABASE_URL`	是	—	PostgreSQL 连接字符串
`REDIS_URL`	是	—	Redis 连接地址
`JWT_SECRET`	是	—	JWT 签名密钥（≥32 字符）
`OPENAI_API_KEY`	条件*	—	OpenAI API Key（使用云端模型时）
`LOCAL_MODEL_PATH`	条件*	—	本地模型路径（使用本地模型时）
`LOG_LEVEL`	否	`info`	日志级别：debug/info/warn/error
`CORS_ORIGINS`	否	`*`	允许的跨域来源

*条件必填：根据使用的模型类型决定是否需要

📖 API 文档

启动服务后访问：

Swagger UI: http://localhost:8443/docs
ReDoc: http://localhost:8443/redoc

快速示例

# 健康检查
curl http://localhost:8443/health

# 代码补全
curl -X POST http://localhost:8443/v1/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "def fibonacci(n):", "max_tokens": 128}'

🛠️ 开发指南

# 安装开发依赖
npm install

# 运行测试
npm test

# 运行 lint
npm run lint

# 构建
npm run build

🤝 贡献方式

我们欢迎所有形式的贡献！请查看贡献指南了解详情。

👉 报告 Bug: GitHub Issues

💡 功能建议: Feature Request

📄 许可证

本项目采用 Apache License 2.0 许可证开源。

Made with ❤️ by the MonkeyCode Team and contributors

```

四、批量注释生成与规范化

4.1 JSDoc/TSDoc 批量生成

// ===== 生成前的代码 =====
class CacheManager {
  constructor(ttl, maxSize) {
    this.ttl = ttl
    this.maxSize = maxSize
    this.store = new Map()
  }
  
  get(key) {
    const item = this.store.get(key)
    if (!item) return undefined
    if (Date.now() - item.timestamp > this.ttl) {
      this.store.delete(key)
      return undefined
    }
    return item.value
  }
  
  set(key, value) {
    if (this.store.size >= this.maxSize) {
      this.evictOldest()
    }
    this.store.set(key, { value, timestamp: Date.now() })
  }
  
  evictOldest() {
    let oldestKey = null
    let oldestTime = Infinity
    for (const [key, item] of this.store) {
      if (item.timestamp < oldestTime) {
        oldestTime = item.timestamp
        oldestKey = key
      }
    }
    if (oldestKey) this.store.delete(oldestKey)
  }
  
  clear() {
    this.store.clear()
  }
  
  get size() {
    return this.store.size
  }
}

/*
请为上面的 CacheManager 类添加完整的 JSDoc 注释，
要求：
1. 类级别描述：功能说明和使用场景
2. 每个方法：@param/@returns/@throws/@example
3. 属性：@type 和描述
4. 泛型支持（CacheManager<T>）
5. 设计模式标注（如适用）
*/

// ===== MonkeyCode 生成后的代码 =====

/**
 * 通用缓存管理器，基于 TTL（Time-To-Live）和 LRU 淘汰策略。
 * 
 * 采用 Map 数据结构实现 O(1) 的读写性能，
 * 当容量达到上限时自动淘汰最久未访问的条目。
 * 
 * @template T 缓存值的类型
 * 
 * @example
 * ```ts
 * // 创建一个缓存实例（TTL=5分钟，最大100条）
 * const cache = new CacheManager<UserProfile>(5 * 60 * 1000, 100)
 * 
 * cache.set('user_001', profile)
 * const user = cache.get('user_001')
 * ```
 * 
 * @designpattern Cache / Repository Pattern
 * @since v1.0.0
 */
class CacheManager<T> {
  /** 缓存条目的默认存活时间（毫秒） */
  private readonly ttl: number
  
  /** 缓存最大容量 */
  private readonly maxSize: number
  
  /** 内部存储：key → 缓存条目 */
  private store: Map<string, CacheEntry<T>>

  /**
   * 创建一个新的 CacheManager 实例
   * @param ttl - 缓存条目的存活时间（毫秒），超过此时间将被视为过期
   * @param maxSize - 缓存最大条目数，超过时触发 LRU 淘汰
   * @throws {RangeError} 当 ttl ≤ 0 或 maxSize ≤ 0 时抛出
   */
  constructor(ttl: number, maxSize: number) {
    if (ttl <= 0) throw new RangeError('TTL must be positive')
    if (maxSize <= 0) throw new RangeError('MaxSize must be positive')
    
    this.ttl = ttl
    this.maxSize = maxSize
    this.store = new Map<string, CacheEntry<T>>()
  }

  /**
   * 从缓存中获取值
   * @param key - 缓存键名
   * @returns 缓存的值，如果不存在或已过期则返回 undefined
   * 
   * @example
   * ```ts
   * const value = cache.get('myKey')
   * if (value !== undefined) {
   *   console.log('Cache hit!', value)
   * }
   * ```
   */
  get(key: string): T | undefined {
    const item = this.store.get(key)
    if (!item) return undefined
    
    // TTL 过期检查
    if (Date.now() - item.timestamp > this.ttl) {
      this.store.delete(key)
      return undefined
    }
    
    return item.value
  }

  /**
   * 向缓存中写入键值对
   * 如果缓存已满，自动淘汰最久未访问的条目
   * @param key - 缓存键名
   * @param value - 要缓存的值
   * 
   * @remarks
   * 此方法会更新已有键的时间戳（LRU 策略）
   */
  set(key: string, value: T): void {
    // 容量检查 → LRU 淘汰
    if (this.store.size >= this.maxSize) {
      this.evictOldest()
    }
    
    this.store.set(key, { value, timestamp: Date.now() })
  }

  /**
   * 淘汰最久未访问的缓存条目（内部方法）
   * @private
   * 
   * @description
   * 遍历所有条目找到 timestamp 最小的那个并删除。
   * 时间复杂度 O(n)，对于大容量缓存建议使用双向链表优化版本。
   */
  private evictOldest(): void {
    let oldestKey: string | null = null
    let oldestTime = Infinity
    
    for (const [key, item] of this.store) {
      if (item.timestamp < oldestTime) {
        oldestTime = item.timestamp
        oldestKey = key
      }
    }
    
    if (oldestKey) {
      this.store.delete(oldestKey)
    }
  }

  /**
   * 清空所有缓存条目
   * @remarks 通常在应用关闭或测试重置时调用
   */
  clear(): void {
    this.store.clear()
  }

  /**
   * 获取当前缓存中的条目数量
   * @returns 当前缓存条目数
   */
  get size(): number {
    return this.store.size
  }
}

/**
 * 缓存条目内部数据结构
 * @interface CacheEntry
 * @template T
 */
interface CacheEntry<T> {
  /** 缓存的值 */
  value: T
  /** 写入时的时间戳（用于 TTL 和 LRU 判断） */
  timestamp: number
}

五、架构文档自动生成

5.1 从代码结构生成架构图

/*
请分析以下项目目录结构，生成：

1. 架构分层图（用 Mermaid 语法）
2. 模块依赖关系图
3. 数据流向图
4. 核心组件职责说明表

项目结构：
src/
├── main.ts                 # 入口文件
├── app.ts                  # Express App 配置
├── config/
│   ├── index.ts            # 配置加载器
│   ├── database.ts         # DB 配置
│   └── redis.ts            # Redis 配置
├── api/
│   ├── index.ts            # 路由聚合
│   ├── user.router.ts      # 用户路由
│   └── code.router.ts      # 代码补全路由
├── services/
│   ├── user.service.ts      # 用户业务逻辑
│   ├── completion.service.ts # 补全服务
│   └── auth.service.ts      # 认证服务
├── models/
│   ├── user.model.ts        # 用户数据模型
│   └── session.model.ts     # 会话模型
├── middleware/
│   ├── auth.middleware.ts   # 认证中间件
│   ├── error.middleware.ts  # 错误处理中间件
│   └── rate-limit.middleware.ts
├── utils/
│   ├── logger.ts            # 日志工具
│   └── crypto.ts            # 加密工具
└── types/
    └── index.ts             # 全局类型定义
*/

5.2 生成的架构文档

# MonkeyCode Server 架构文档

## 系统架构总览

```mermaid
graph TB
    Client[客户端<br/>VSCode/JetBrains/Web] -->|HTTPS| API[API Gateway<br/>Express + Helmet]
    
    subgraph "API Layer"
        API --> Auth[认证中间件<br/>JWT + OAuth2]
        API --> RL[速率限制中间件]
        API --> EH[错误处理中间件]
    end
    
    subgraph "Service Layer"
        Auth --> US[UserService]
        RL --> CS[CompletionService]
        US --> AS[AuthService]
        CS --> MS[ModelService]
    end
    
    subgraph "Data Layer"
        US --> PG[(PostgreSQL)]
        AS --> PG
        CS --> RD[(Redis)<br/>Session + Cache]
        MS --> LM[Local Model<br/>/ Cloud API]
    end
    
    subgraph "Infrastructure"
        LOG[Logger<br/>Winston] --> |File| FS[(文件系统)]
        LOG --> |Stdout| MT[监控终端]
    end
    
    CS --> LOG
    US --> LOG

模块依赖关系

graph LR Main[main.ts] --> App[app.ts] Main --> Config[config/index.ts] App --> Routers[api/index.ts] App --> MW[middleware/] App --> Utils[utils/] Routers --> Services[services/] Services --> Models[models/] Services --> Utils Services --> Config Config --> DB[config/database.ts] Config --> RD[config/redis.ts] Models --> DB AS[auth.service.ts] --> RD CS[completion.service.ts] --> RD

核心组件职责

组件	职责	关键依赖	对外接口
app.ts	Express 应用初始化、中间件注册、错误处理	helmet/cors/morgan	HTTP Server
auth.service.ts	JWT 签发/验证、OAuth2 协调、密码哈希	jsonwebtoken/bcrypt	signToken / verifyToken / hashPassword
completion.service.ts	AI 补全核心逻辑、上下文构建、模型调度	openai/anthropic/local-model	complete() → Stream
user.service.ts	用户 CRUD、权限验证、资料管理	pg (TypeORM)	create / find / update / delete
rate-limit.middleware.ts	基于 Redis 的滑动窗口限流	ioredis	middleware function
error.middleware.ts	统一错误处理、错误分类、日志记录	winston	errorHandler

数据流向

用户输入代码
     │
     ▼
┌─────────────┐
│  VSCode 插件  │ ← 捕获上下文（光标位置、文件内容、导入信息）
└──────┬──────┘
       │ HTTPS POST /v1/completions
       ▼
┌─────────────┐
│  API Gateway │ ← 认证 + 限流 + 日志
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│  CompletionService  │ ← 构建 Prompt（系统提示 + 代码上下文 + 用户意图）
│                     │
│  1. 读取光标前后的代码 │
│  2. 解析 AST 获取语义 │
│  3. 查找相关导入和类型 │
│  4. 组装完整 Context │
└──────┬──────────────┘
       │
       ├─────────────┬──────────────┐
       ▼             ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────────┐
│ OpenAI   │  │ Claude   │  │ Local Model  │
│ GPT-4o   │  │ 3.5 Sonnet│  │ Qwen-Coder   │
└────┬─────┘  └────┬─────┘  └──────┬───────┘
     │             │              │
     └─────────────┴──────────────┘
                   │
                   ▼
          ┌────────────────┐
          │  SSE Stream    │ ← 逐 Token 推送
          │  (Server-Sent  │
          │   Events)      │
          └────────┬───────┘
                   │
                   ▼
          ┌────────────────┐
          │  VSCode 插件    │ ← 渲染内联补全建议
          └────────────────┘

六、变更日志自动维护

6.1 从 Git Log 生成 CHANGELOG

# ===== 自动化脚本 =====
#!/bin/bash
# generate-changelog.sh — 从 Git log 生成标准格式的 CHANGELOG

echo "# Changelog\n"
echo "All notable changes to this project will be documented in this file.\n"

# 获取上一个 tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

if [ -z "$LAST_TAG" ]; then
  echo "## [Unreleased]\n"
else
  echo "## [Unreleased]\n"
  echo "### Added\n"
  echo "### Changed\n"
  echo "### Fixed\n"
fi

# 分析每个 commit
git log ${LAST_TAG}..HEAD --pretty=format:"%h|%s|%an|%ad" --date=short | \
while IFS='|' read HASH MSG AUTHOR DATE; do
  # 分类
  if [[ "$MSG" == feat:* ]]; then
    echo "- **${MSG#feat: }** ($HASH) — $AUTHOR, $DATE"
  elif [[ "$MSG" == fix:* ]]; then
    echo "- **${MSG#fix: }** ($HASH) — $AUTHOR, $DATE"
  elif [[ "$MSG" == docs:* ]]; then
    echo "- ${MSG#docs: } ($HASH)"
  fi
done

6.2 用 MonkeyCode 智能整理 Changelog

/*
以下是原始的 Git commit 历史，请帮我整理成规范的 KEEPCHANGELOG 格式：

原始 commits:
feat: add multi-file context support
fix: resolve crash when file is deleted during analysis
docs: update API reference for v4.2
feat: implement streaming response for chat mode
fix: handle empty input edge case
perf: reduce memory usage by 30% with paged attention
test: add integration tests for auth module
refactor: extract common logic into shared utility
feat: support custom model endpoints
docs: add deployment guide for Kubernetes

要求：
1. 按 Added / Changed / Deprecated / Removed / Fixed / Security 分类
2. 关联相关的 issue 编号（如果有）
3. 合并同类项
4. 使用 Markdown 链接格式
*/

七、文档工作流集成

7.1 CI/CD 中的文档检查

# .github/workflows/docs.yml
name: Documentation Check

on:
  pull_request:
    paths:
      - 'src/**'
      - 'docs/**'

jobs:
  doc-coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check documentation coverage
        uses: monkeycode-ai/doc-coverage-action@v1
        with:
          api-key: ${{ secrets.MONKEYCODE_API_KEY }}
          min-coverage: 80           # 公共 API 必须 80% 以上有注释
          check-public-only: true    # 只检查导出的符号
          
      - name: Generate API docs on PR
        if: github.event_name == 'pull_request'
        uses: monkeycode-ai/api-docs-action@v1
        with:
          output-format: markdown
          comment-on-pr: true         # 在 PR 下评论生成的文档预览

7.2 Git Hooks 文档同步

// .husky/pre-commit
// 提交前检查：新增的公共函数是否有 JSDoc 注释

const { execSync } = require('child_process');

const changedFiles = execSync(
  'git diff --cached --name-only --diff-filter=A -- "*.ts" "*.js"'
).toString().split('\n').filter(Boolean);

if (changedFiles.length > 0) {
  console.log(`📝 Checking documentation for ${changedFiles.length} new files...`);
  
  // 可以集成 MonkeyCode CLI 进行批量检查
  // monkeycode doc-check --files ${changedFiles.join(' ')}
}

process.exit(0);

八、参与文档功能的改进

我们需要的帮助

方向	说明	适合谁
📝 更多模板	各框架风格的 README / API 文档模板	技术写作者
🌐 多语言文档	英文/日文/韩文版本文档生成	双语开发者
🎨 文档美化	更美观的 Markdown 渲染样式	前端/UI 设计师
🔗 工具集成	与 Swagger/Redoc/Docusaurus 深度集成	DevOps 工程师
✅ 文档校验	自动检测文档与代码的一致性	测试工程师

欢迎在 GitHub 提交 Issue 和 PR！

👉 GitHub Issues: https://github.com/monkeycode-ai/monkeycode/issues

结语

"好的文档不是写出来的，而是随着代码一起生长出来的。"

MonkeyCode 让文档不再是负担——它从你的代码中学习，理解你的意图，然后生成清晰、准确、美观的技术文档。当代码变更时，只需重新生成即可保持同步。

现在就打开 MonkeyCode，对你的项目说："帮我生成文档"吧！ 📚✨

本文由 MonkeyCode 团队原创，采用 Apache 2.0 许可证发布。

关键词: MonkeyCode 文档自动生成 API文档 README JSDoc OpenAPI AI编程助手 开源 GitHub

posted on 2026-06-25 12:16 MonkeyCode 阅读(20) 评论(0) 收藏举报

刷新页面返回顶部

导航