Gencodedoc

🚀 GenCodeDoc

GenCodeDoc 是一款强大的工具，它重新定义了代码项目的版本跟踪方式。它结合了具备去重功能的智能快照系统、Markdown 文档生成器，以及用于自动化和与 AI 助手集成的完整接口（CLI、REST API、MCP）。

✨ 主要特性

• 📸 智能快照：通过基于哈希的内容去重，为项目创建“快照”，节省约 70% 的空间。
• 🔄 智能自动保存：提供三种自动保存模式（基于时间、基于更改或混合模式），保护您的工作成果。
• 📝 自动化文档：为您的项目生成完整的 Markdown 文档，包括文件树和代码片段。
• 🔍 高级差异对比：以统一差异（类似 Git）、JSON（用于脚本）或语义（AST，实验性）方式比较项目的任意版本。
• 🔌 三重接口：以最适合您的方式使用 GenCodeDoc：
  • CLI：完整且直观的命令行界面。
  • REST API：通过 HTTP 将 GenCodeDoc 集成到您自己的应用程序中。
  • MCP：通过 Model-Context-Protocol 公开的 17 个工具，使用 AI（Gemini、Claude）驱动该工具。

📦 安装指南

先决条件

• Python 3.10+
• 使用 Poetry 进行依赖管理。

安装步骤

1. 克隆仓库：

git clone https://github.com/VOTRE_NOM/gencodedoc.git
cd gencodedoc

2. 使用 Poetry 安装依赖：

poetry install

3. 验证安装：

poetry run gencodedoc --help

🚀 快速开始

安装完成后，以下是如何在现有项目中开始使用 GenCodeDoc：

1. 在项目中初始化 GenCodeDoc：

# 导航到您的项目目录
cd /path/to/your/project

# 使用预设初始化（例如：python）
poetry run gencodedoc init --preset python

可用预设：python、nodejs、go、web。 2. 创建第一个快照：

poetry run gencodedoc snapshot create --message "Version initiale du projet" --tag v1.0

3. 生成文档：

poetry run gencodedoc doc generate --output "PROJECT_DOCS.md"

将创建一个包含完整文档的 PROJECT_DOCS.md 文件。 4. （可选）启用自动保存：

poetry run gencodedoc config set autosave.enabled true

🔌 MCP 集成（适用于 AI 助手）

GenCodeDoc 旨在由 AI 驱动，它通过三种传输模式公开其 17 个工具。

• stdio：适用于像 Gemini CLI 这样的 CLI 客户端。
• SSE（服务器发送事件）：适用于像 Claude Desktop 这样的 Web 或桌面应用程序。
• REST：适用于通过 HTTP API 进行的任何自定义集成。

为 Gemini CLI（stdio）进行配置

1. 找到您的 Poetry 虚拟环境路径：

# 从 gencodedoc 目录执行
poetry env info --path 
# 复制返回的路径

2. 将服务器添加到您的 MCP 客户端配置中： (以 gemini-cli 为例)

{
  "mcpServers": {
    "gencodedoc": {
      "command": "/path/to/your/poetry-venv/bin/python",
      "args": ["-m", "gencodedoc.mcp.server_stdio"],
      "env": {
        "PROJECT_PATH": "/path/to/your/target-project"
      }
    }
  }
}

将 /path/to/your/poetry-venv 替换为步骤 1 中的路径，将 PROJECT_PATH 替换为您要管理的项目路径。

启动 SSE / REST 服务器

# 启动 SSE 服务器（适用于 Claude Desktop）
poetry run python -m gencodedoc.mcp.server_sse

# 启动 REST 服务器
poetry run python -m gencodedoc.mcp.server

两个服务器都在 http://127.0.0.1:8000 上运行。

🧰 工具参考

主要 CLI 命令

• gencodedoc init：初始化项目。
• gencodedoc snapshot create|list|show|diff|restore|delete：管理快照。
• gencodedoc doc generate|preview|stats：管理文档。
• gencodedoc config show|edit|set|preset|ignore：管理配置。
• gencodedoc status：显示项目的当前状态。

MCP 工具（17 个工具）

为 AI 提供的工具摘要：

• 快照管理（6 个工具）：create_snapshot、list_snapshots、get_snapshot_details、restore_snapshot、delete_snapshot、diff_versions。
• 文档（3 个工具）：generate_documentation、preview_structure、get_project_stats。
• 项目管理（2 个工具）：init_project、get_project_status。
• 配置（3 个工具）：get_config、set_config_value、apply_preset、manage_ignore_rules。
• 自动保存（3 个工具）：start_autosave、stop_autosave、get_autosave_status。

配置完成后，您可以直接向您的 AI 发出以下请求：

“创建一个标签为 v2.1 的快照，并附带消息 'Correction du bug de connexion'” “显示 v2.0 版本与当前版本之间的差异” “生成项目的完整文档”

🏗️ 架构与工作原理

GenCodeDoc 围绕一个管理配置、版本控制和文档生成的逻辑核心构建。这个核心通过不同的接口（CLI、MCP）公开。

存储经过优化，既高效又节省空间：

• SQLite 用于存储所有元数据（快照、文件等）。
• 文件内容通过 SHA256 哈希进行去重。即使一个文件存在于 100 个快照中，也只存储一次。
• 内容随后使用 zstandard 进行压缩，以进一步减少磁盘占用。

🤝 贡献

欢迎贡献代码！

1. 分叉项目。
2. 创建一个功能分支 (git checkout -b feature/ma-super-feature)。
3. 提交您的更改 (git commit -m 'Ajout de ma super feature')。
4. 推送您的分支 (git push origin feature/ma-super-feature)。
5. 打开一个拉取请求。

📄 许可证

本项目采用 MIT 许可证。有关更多详细信息，请参阅 LICENSE 文件。