Skip to content

Latest commit

 

History

History
241 lines (203 loc) · 12.8 KB

需求文档.md

File metadata and controls

241 lines (203 loc) · 12.8 KB

刘耀文: 完整项目需求文档：自动生成开发日志的 NPM 包

项目名称: devlog-generator

功能目标:

devlog-generator 是一个自动生成开发日志的工具，能够根据 Git 提交记录生成日志，并通过 AI（如 OpenAI、Anthropic、Google PaLM）生成详细的开发日志内容。工具支持日志格式自定义（Markdown、JSON、HTML），并提供对日志风格的控制。所有配置项均通过配置文件进行管理，用户无需通过命令行频繁修改。默认生成 HTML 格式的日志，并支持配置 public 文件夹的位置来存放生成的日志文件。

  1. 核心功能

    1. 根据 Git 提交记录生成开发日志： • 自动读取 Git 提交记录并生成结构化的日志。 • 可选：启用 AI，根据 Git 提交的简短描述生成更详细的开发日志内容。
    2. 支持多种 AI 接口： • 支持 OpenAI、Anthropic、Google PaLM 等多个 AI 供应商。 • 用户可以通过配置文件选择要使用的 AI 供应商，避免每次都手动输入 API 密钥。
    3. 日志格式支持： • 默认生成 HTML 格式的日志。 • 支持 Markdown、JSON、HTML 等多种日志输出格式。 • 配置文件中通过 logFormat 字段设置默认日志格式。
    4. 日志风格自定义： • 当启用 AI 后，用户可以通过配置文件中的 stylePrompt 字段调整 AI 生成的日志风格。例如，用户可以选择生成正式、简洁、详细、幽默等不同风格的日志。
    5. 生成并管理配置文件： • 安装后，工具会自动生成配置文件 devlog.config.json，并填充必要的默认配置项（如是否启用 AI，AI 供应商选择，API 密钥等）。 • 配置文件可以放在项目根目录或用户主目录下，支持灵活配置。
    6. 日志输出目录配置： • 用户可以通过配置文件配置生成日志的输出目录，默认输出至 public 文件夹。 • outputDirectory 字段用于指定自定义的输出文件夹。
    7. 全局安装与 npx 支持： • 支持全局安装，也支持通过 npx 直接运行，方便用户临时使用。

  2. 配置管理

    1. 配置文件结构： • 配置文件 devlog.config.json 用于管理 AI 配置和其他日志生成参数，所有功能的开关和选项均可通过此配置文件进行管理。 • 配置文件示例：

{ "useAI": true, "aiInterface": "openai", "openai": { "apiKey": "your-openai-api-key", "model": "gpt-4", "stylePrompt": "Generate formal and technical logs" }, "anthropic": { "apiKey": "your-anthropic-api-key", "model": "claude-3" }, "googlePaLM": { "apiKey": "your-google-api-key", "model": "palm-2" }, "logFormat": "html", // Supported formats: markdown, json, html "gitLogOptions": { "maxCommits": 50, "includeTags": false }, "outputDirectory": "./public", // Directory where logs will be saved "help": { "usage": "This configuration file controls how logs are generated. You can choose to use AI or Git commit history to generate your dev logs.", "instructions": "1. Set 'useAI' to true to enable AI, or false to use Git commit logs.\n2. If using AI, choose the AI provider and input your API key and model.\n3. Adjust other settings like maxCommits and includeTags as needed." } }

2.	配置项说明：
•	useAI: 布尔值，是否启用 AI（默认为 false）。启用 AI 后，日志会通过 AI 接口生成。
•	aiInterface: 选择 AI 供应商，支持 openai、anthropic、googlePalm。
•	openai, anthropic, googlePaLM: 各供应商的配置项，包含 API 密钥、模型名称、日志风格（stylePrompt）。
•	stylePrompt: 用于控制 AI 生成日志的风格。例如：
•	Generate formal and technical logs
•	Generate concise and informal logs
•	Generate detailed and explanatory logs
•	Generate humorous logs
•	logFormat: 指定日志输出的格式，支持 markdown、json、html。
•	gitLogOptions: Git 提交日志的配置：
•	maxCommits: 最大提交数，控制生成的日志条目数量。
•	includeTags: 是否包含 Git 提交的标签（默认 false）。
•	outputDirectory: 设置日志文件的输出目录，默认为 ./public。用户可以在配置文件中自定义此目录。
•	help: 配置文件的使用说明。
3.	配置文件读取顺序：
•	配置文件的优先级加载顺序为：
1.	项目根目录的 devlog.config.json。
2.	用户主目录中的配置文件（~/.config/your-package-name/devlog.config.json）。
3.	.env 文件中的环境变量。
4.	环境变量支持：
•	用户可通过 .env 文件管理 API 密钥等敏感信息，避免直接在配置文件中存储。

USE_AI=true AI_INTERFACE=openai OPENAI_API_KEY=your-openai-api-key OPENAI_MODEL=gpt-4 STYLE_PROMPT="Generate formal and technical logs" LOG_FORMAT=html OUTPUT_DIRECTORY=./public

  1. 安装与配置引导
    1. 安装过程中的引导： • 安装时，工具提供交互式引导，用户可以选择配置文件保存位置、启用 AI 以及选择 AI 供应商。 • 用户可以根据需要选择是否启用 AI，选择供应商（如 OpenAI、Anthropic、Google PaLM），并输入 API 密钥和模型。 • 用户可以选择日志格式、风格以及其他参数。
    2. 安装示例：

DevLog Generator Installation:

  1. Where would you like to save the configuration file? (default: project directory) (1) Project directory (devlog.config.json) (2) User home directory (~/.config/your-package-name/devlog.config.json) (3) Custom location (enter your own path)

  2. Enable AI for log generation? (default: No) (1) Yes (2) No

  3. If Yes:

    • Choose AI provider: (default: OpenAI) (1) OpenAI (2) Anthropic (3) Google PaLM

    • Enter your API Key for the selected provider:

    • Enter your AI model (e.g., gpt-4, claude-3, palm-2)

  4. Optional: Choose log style for AI generation (default: "Generate formal and technical logs"): (1) Formal and Technical (2) Concise and Informal (3) Detailed and Explanatory (4) Humorous (5) Custom (Provide your own prompt)

  5. Select the log output format: (default: html) (1) Markdown (2) JSON (3) HTML

  6. Select the output directory: (default: ./public) (1) ./public (2) Custom directory (enter your own path)

Configuration will be saved at: [selected location]. Press Enter to continue...

3.	配置文件生成：
•	安装后，自动生成并保存配置文件 devlog.config.json，并提供修改功能。
  1. 生成日志的功能
    1. Git 提交记录生成日志： • 从 Git 提交记录中读取并生成日志内容，支持按提交信息、日期等筛选。 • 支持通过配置文件设置日志的最大条目数（maxCommits）和是否包含 Git 提交标签（includeTags）。
    2. AI 优化日志： • 启用 AI 时，工具会通过 AI 服务根据提交记录生成详细的日志内容。用户可以选择不同的 AI 模型，并配置风格（例如，正式、简洁、详细、幽默等）。 • 风格配置：用户可以通过 stylePrompt 配置 AI 生成日志的风格，例如： • Formal and Technical：生成正式、技术性的日志。 • Concise and Informal：生成简洁且非正式的日志。 • Detailed and Explanatory：生成详细、解释性的日志。 • `

刘耀文: 4. 生成日志的功能（续） 2. AI 优化日志（续）： • 风格配置：用户可以通过 stylePrompt 配置 AI 生成日志的风格，例如： • Formal and Technical：生成正式、技术性的日志。 • Concise and Informal：生成简洁且非正式的日志。 • Detailed and Explanatory：生成详细、解释性的日志。 • Humorous：生成幽默风格的日志。 • Custom：用户提供自定义的风格提示，允许灵活生成符合团队风格的日志。 3. 生成日志的命令行工具： • 提供简便的命令行接口 devlog generate，用于生成开发日志，支持以下参数： • --format：指定输出日志的格式，支持 markdown、json、html。 • --output-dir：设置日志文件的输出目录，默认为 ./public，用户可以自定义路径。 • --max-commits：设置最大提交数量，默认为 50 条。 • --include-tags：是否包括 Git 提交标签，默认为 false。 • --help：查看命令行工具的帮助文档。 示例命令：

devlog generate --format html --output-dir ./public --max-commits 100 --include-tags true devlog generate --format markdown --max-commits 30

通过这些命令，用户可以轻松生成不同格式的日志，并将日志保存到指定目录。

  1. 错误处理与容错性

    1. 配置文件错误： • 如果配置文件格式不正确或缺少必需的字段（如缺少 API 密钥、缺少日志格式设置等），工具应提供详细的错误信息，并提示用户修正配置文件。 • 提供日志，帮助用户快速定位问题所在。
    2. AI 错误处理： • 当 AI 服务调用失败时（如 API 密钥无效、请求超时等），工具应通过错误消息提醒用户，并提供重试或退出的选项。 • 提供详细的错误信息，帮助用户调整配置（例如：检查网络连接、API 密钥、模型选择等）。
    3. Git 错误处理： • 如果 Git 仓库无法访问（如路径错误、未初始化 Git 仓库等），工具应给出明确的错误提示，建议检查仓库路径或初始化 Git 仓库。 • 提供调试信息，帮助用户解决问题。
    4. 日志生成错误： • 在生成日志过程中，若遇到错误（如日志格式不支持、AI 生成失败等），工具应通过详细的错误消息提示用户修改配置。 • 提供日志输出，帮助开发者诊断问题。

  2. 性能与优化

    1. 异步操作： • Git 提交日志的提取和 AI 服务调用应采用异步操作，避免阻塞主线程，提高工具的性能和响应速度。 • 对于大规模 Git 仓库，支持分页加载提交记录，减少内存压力。
    2. 批量日志生成： • 支持批量生成多个版本或时间段的日志。用户可以一次性生成多个版本或时间段的开发日志，节省时间和资源。
    3. 缓存机制： • 为了避免重复生成相同的日志，工具可缓存已生成的日志。用户可以配置缓存过期时间，缓存会定期清理。 • 缓存机制有助于提高生成速度，尤其是当日志内容未发生变化时。
    4. 性能监控： • 提供实时反馈日志生成的进度（尤其是在长时间运行的操作中），例如，显示当前处理的提交记录数量、剩余时间等。 • 输出日志生成的详细时间统计，帮助用户了解工具的性能表现。

  3. 命令行工具设计 1. 生成日志： • 命令行工具 devlog generate 用于生成开发日志，支持自定义配置选项。日志输出格式默认为 HTML，用户可以通过 --format 参数选择 Markdown、JSON 或 HTML 格式。 示例命令：

devlog generate --format html --output-dir ./public --max-commits 100 --include-tags true devlog generate --format markdown --max-commits 50

2.	查看帮助文档：
•	提供 --help 参数，查看命令行工具的帮助文档，帮助用户了解如何使用工具及各个命令的详细说明。

示例命令：

devlog --help devlog generate --help

3.	日志生成过程反馈：
•	在日志生成过程中，工具应输出详细的实时状态信息，包括正在读取 Git 提交记录、请求 AI 服务、生成日志等。
•	生成完成后，输出最终生成的日志文件路径和生成时间。

  1. 扩展性与兼容性

    1. 支持不同的 Git 仓库结构： • 支持多种 Git 仓库结构，包括单一仓库、子模块、多仓库等情况。 • 配置文件中支持用户指定 Git 仓库路径，支持本地仓库和远程仓库。
    2. 支持 CI/CD 集成： • 提供与 CI/CD 流水线的集成支持。可以在构建过程中自动生成开发日志，并将日志文件保存到指定目录，便于持续集成和部署。 • 在 CI 环境中，工具支持无交互执行模式，自动使用配置文件生成日志。
    3. 插件机制： • 支持插件扩展机制，用户可以开发自定义插件来扩展日志输出格式、风格等功能。插件可以通过配置文件启用。 • 提供插件的社区共享和复用，促进生态扩展。
    4. 支持多 AI 服务供应商： • 当前支持 OpenAI、Anthropic 和 Google PaLM，未来可以扩展更多 AI 服务提供商。只需要在配置文件中配置相应的 API 密钥和模型即可切换 AI 服务供应商。

  2. 更新与维护 • 提供详细的用户文档，包括使用指南、配置说明、命令行工具使用方法等。