ogito 1.2.0

# `ogito` 产品需求文档 (PRD)

**版本:** 1.0
**日期:** 2025年8月17日

## 1. 引言

### 1.1 项目愿景

`ogito` 是一个轻量级、高效的命令行工具，旨在简化从现有 Git 仓库创建新项目的流程。它并非要取代功能全面的项目脚手架（如 `create-react-app`），而是为开发者提供一种更灵活、更个人化的方式，来管理和复用他们自己的代码模板。核心理念是让开发者完全掌控自己的项目样板，实现快速、干净的项目初始化。

### 1.2 目标用户

- **开发者**: 希望根据自己的模板或常用的开源项目快速启动新项目的软件开发者。
- **团队**: 需要在团队内部统一项目结构和基础配置的开发团队。

### 1.3 项目目标

- **快速创建**: 提供一种从 Git 仓库一键生成新项目的能力。
- **模板管理**: 允许用户添加、缓存和管理自己的项目模板。
- **易于使用**: 提供清晰、简洁的命令行界面和操作反馈。
- **保持纯净**: 默认创建不含原有 Git 历史的纯净项目副本，同时提供保留历史的选项。

## 2. 功能详述

`ogito` 的核心功能通过以下子命令实现。

### 2.1 `new` - 创建新项目

此命令从指定的源 (Git 仓库) 创建一个新项目。

- **功能描述**: 克隆一个 Git 仓库到本地指定目录。用户可以指定分支，并选择是否保留 Git 历史记录。
- **使用方法**:
  ```bash
  ogito new <url> [options]
  ```
- **参数与选项**:
  - `url` (必需): 源仓库的 Git 链接。
  - `-d, --dir <DIRNAME>`: 指定新项目的本地目录名称。如果未提供，则可能使用默认名称。
  - `-b, --branch [BRANCH]`: 指定要克隆的分支。
  - `-m, --mode <MODE>`: 指定操作模式，默认为 `git`。
  - `-f, --force`: 强制操作。如果目标目录已存在，将覆盖它。
  - `-H, --keep-history`: 保留原始仓库的 Git 历史记录。默认情况下会移除 `.git` 目录以创建干净的副本。

### 2.2 `add` - 添加新模板

此命令允许用户将一个 Git 仓库添加为可复用的模板，方便后续使用。

- **功能描述**: 将一个源仓库注册到本地缓存中，并为其分配一个易于记忆的名称或别名。
- **使用方法**:
  ```bash
  ogito add <url> [options]
  ```
- **参数与选项**:
  - `url` (必需): 源仓库的 Git 链接。
  - `-n, --name <NAME>`: 为模板指定一个名称。
  - `-d, --description <DESCRIPTION>`: 为模板添加描述。
  - `-a, --alias <ALIAS>`: 为模板设置一个别名，方便快速调用。
  - `-u, --update`: 如果模板已存在，则更新它。
  - `-f, --force`: 强制添加，可能会覆盖现有配置。

### 2.3 `clear` - 清理缓存

此命令用于管理 `ogito` 的本地缓存。

- **功能描述**: 清理 `ogito` 下载和存储的模板缓存，释放磁盘空间。
- **使用方法**:
  ```bash
  ogito clear [options]
  ```
- **参数与选项**:
  - `-f, --force`: 强制执行清理，无需用户确认。
  - `-n, --dry-run`: 模拟运行。仅显示将要被删除的文件和目录，但不执行任何实际删除操作。
  - `-v, --verbose`: 显示详细的输出，列出每一个被移除的项目。

## 3. 核心工作流程

1.  **添加模板**: 用户发现一个有用的项目仓库 (例如 `https://github.com/user/my-starter.git`)。他使用 `ogito add https://github.com/user/my-starter.git --name my-starter` 将其添加为模板。
2.  **创建项目**: 当需要启动一个新项目时，用户运行 `ogito new my-starter --dir my-new-project`。
3.  **工具执行**: `ogito` 在其缓存中查找 `my-starter` 对应的 Git 链接，将其克隆到 `my-new-project` 目录，并默认移除 `.git` 文件夹。
4.  **完成**: 用户获得一个干净、可立即使用的新项目副本。

## 4. 技术栈

- **核心应用**: Rust
- **命令行框架**: `clap`
- **辅助脚本**: TypeScript (使用 `pnpm` 管理)

## 5. 未来规划 (建议)

根据 `GEMINI.md` 中的规划和当前实现状态，以下功能是未来可以扩展的方向：

- **`list` 命令**: 列出所有已添加的本地模板及其详细信息。
- **`remove`/`delete` 命令**: 从缓存中移除一个指定的模板。
- **`update` 命令**: 提供一个专门的命令来更新所有或指定的模板到最新版本。
- **本地路径支持**: 允许 `add` 和 `new` 命令使用本地文件系统路径作为模板源，而不仅仅是 Git 链接。