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 文件。