智能文档生成与版本控制系统

🚀 GenCodeDoc

智能文档生成器和智能版本控制系统，完全支持MCP

现代开发工作流程的智能版本控制和文档

快速开始 • 特性 • MCP工具 • 文档

⚡ 快速开始

# 1. Install
cd /path/to/gencodedoc
poetry install

# 2. Initialize your project
poetry run gencodedoc init --preset python

# 3. Create your first snapshot
poetry run gencodedoc snapshot create -m "Initial version" -t v1.0

# 4. Generate documentation (Smart Split)
poetry run gencodedoc doc generate --limit 5000

# 5. Visualize Tree
poetry run gencodedoc tree

🎯 对于人工智能助理（Claude/Gemini）：请参阅MCP集成

✨ 特性 🎯 核心功能 📸 智能快照-通过SHA256重复数据删除创建智能快照，节省约70%的空间 🔄 智能自动保存-3种模式（定时器/差速器/混合动力），具有可配置的阈值 📝 漂亮的文档-生成带有语法高亮、目录树和 智能拆分 🔍 高级差异-将版本与基于统一、JSON或AST的差异进行比较 🗜️ 高效存储-zstd压缩（约3倍压缩）+具有优化索引的SQLite 🎨 项目预设-为Python、Node.js、Go和Web项目预先配置 🔌 MCP集成（模型上下文协议） 26个MCP工具 -通过MCP为AI助手提供完整的CLI功能 3传输-stdio（Gemini CLI）+SSE（Claude Desktop）+REST API 多项目-同时管理多个项目 代码智能-文件历史记录、搜索和更改日志生成 实时状态-实时项目统计和快照管理 📦 安装 先决条件 Python 3.10+ 诗歌（依赖关系管理器） 安装诗歌 Bash

Linux/macOS

卷曲-sSLhttps://install.python-poetry.org|python3-

Windows（PowerShell）

（调用WebRequest-Urihttps://install.python-poetry.org-使用基本解析）。内容|py- 安装GenCodeDoc Bash

克隆或导航到项目

cd/home/fkomp/Bureau/oracle/utilitaires/gencodedoc/gencodedoc

安装依赖项

诗歌装置

验证安装

诗歌运行gencodedoc-帮助 🎯 用法 📋 CLI使用情况 初始化项目 Bash

基本初始化

%s推荐

使用Python预设（建议用于Oracle项目）

gencodedoc初始化--预设python

可用预设：python、nodejs、go、web

快照管理 Bash

创建快照

gencodedoc快照创建--消息“功能X已完成”--标签v1.0

列出快照

gencodedoc快照列表--限制10

显示快照详细信息

gencodedoc快照显示v1.0

查看特定版本的文件内容（新）

gencodedoc快照猫v1.0 src/main.py

列出快照中的文件（新）

gencodedoc快照文件v1.0--模式“*.py”

比较版本

gencodedoc快照差异v1.0 v2.0

还原快照（完整或部分）

gencodedoc快照恢复v1.0--强制 gencodedoc快照还原v1.0--过滤器“src/*.py”#部分还原

导出快照（新）

gencodedoc快照导出v1.0。/dist-v1--归档#创建.tar.gz

删除快照

gencodedoc快照删除旧版本--强制

清理孤立数据（新）

gencodedoc快照清理 文档生成 Bash

全部文件

gencodedoc文档生成

自定义输出

gencodedoc单据生成--输出单据/API.md

仅限特定路径

gencodedoc文档生成--包括src/api/--包括README.md

结构预览

gencodedoc文档预览——最大深度3

项目统计

gencodedoc文档统计 配置 Bash

视图配置

gencodedoc配置显示

编辑配置

gencodedoc配置编辑

设置特定值

gencodedoc配置集autosave.enabled true gencodedoc配置集autosave.mode混合

应用预设

gencodedoc配置预置python

管理忽略规则

gencodedoc配置忽略--添加目录dist 忽略gencodedoc配置--添加ext.tmp gencodedoc配置忽略--列出所有

可定制的预设

预设现在在YAML文件中定义（gencodedoc/config/Presets/*.YAML）

并且可以直接在源代码中修改。

项目状态 Bash

显示项目状态

gencodedoc状态 🔌 MCP集成 GenCodeDoc通过模型上下文协议公开了22个强大的工具，与Claude Desktop、Gemini CLI和任何兼容MCP的客户端兼容。

🎯 运输方式 运输用例AI助手端口 stdio CLI集成Gemini CLI，自定义脚本stdin/stdout SSE网络/桌面应用程序Claude Desktop，网络UI 8000（HTTP） REST API集成任何HTTP客户端8000（HTTP） 🚀 Gemini CLI（stdio）的设置

1. 找到你的诗歌之路：

Bash

cd/home/fkomp/Bureau/oracle/utilitaires/gencodedoc/gencodedoc 诗歌环境信息路径

复制路径并附加/bin/python

2. 添加到~/.config/gemini桌面应用程序/settings.json：

JSON

{ “mcpServers”：{ “gencodedoc”：{ “command”：“/path/to/your/venv/bin/python”， “args”：[“-m”，“gencodedoc.mcp.server_strio”]， “env”：{ “项目路径”：“/home/fkomp/Bureau/oracle/utilitaires/gencodedoc/gencodedoc” } } } } 3.重新启动Gemini CLI，您就准备好了！ 🎉

🚀 克劳德桌面（SSE）的设置

1. 启动SSE服务器：

Bash

终端1：启动服务器

诗歌运行python-m gencodedoc.mcp.server_sse

服务器在上运行http://127.0.0.1:8000

2. 添加到Claude桌面配置：

地点：

macOS：~/库/应用程序支持/Claude/Claude_desktop_config json Windows：%APPDATA%\Claude\Claude_desktop_config.json Linux:~/.config/Claude/Claude_desktop_config json 配置：

JSON

{ “mcpServers”：{ “gencodedoc”：{ “url”：“http://127.0.0.1:8000/mcp/sse", “运输”：“sse”， “description”：“GenCodeDoc-智能文档和版本控制” } } } 3.重新启动Claude Desktop，服务器必须保持运行！

🚀 REST API Bash

启动REST服务器

诗歌运行python-m gencodedoc.mcp.server

可用端点

获取http://127.0.0.1:8000/#服务器信息 获取http://127.0.0.1:8000/mcp/tools#列出工具 发布http://127.0.0.1:8000/mcp/execute#执行工具 🛠️ MCP工具（26个工具）

🧠 代码智能（3个工具）

📸 快照管理（11个工具）

📝 文档（3个工具）

🎯 项目管理（2个工具）

⚙️ 配置（4个工具）

🔄 自动保存（3个工具）

🤝 贡献 欢迎投稿！ 🎉

🐛 通过GitHub Issues报告错误 💡 通过讨论建议功能 🔧 提交拉取请求

开发工作流程：

1. 分叉回购
2. 创建要素分支(git checkout -b feature/amazing)
3. 进行更改
4. 运行测试(make test)
5. 提交PR

📄 许可证 MIT许可证-请参阅许可证文件

🐛 问题：GitHub问题 💬 讨论：GitHub讨论 🌐 网站：esprit-artificiel.com 📧 电子邮件：support@esprit-artificiel.com

💡 专业提示：使用GenCodeDoc与Gemini CLI或Claude Desktop进行AI驱动的版本控制！

⭐ 如果你觉得这个仓库有用，就把它标上！

🤖 “停止所有自动保存并向我显示其状态” → 调用：stop_autosave（…）+get_autosave_status（） ⚙️ 配置 配置文件（.gencodedoc.yaml） YAML

project_name：“我的项目”

要忽略的文件/目录

忽略： dirs： -节点模块 - venv - .venv - __pycache__ -.git -dist -建造 文件夹： -“*.log” -package-lock.json - .DS_存储 扩展名： -.pyc -.pyo -.exe -jpg -.png -.pdf patterns：[]#gitignore风格的图案

智能自动保存

自动保存： enabled：false#设置为true以启用 模式：混合模式#定时器|diff|hybrid（推荐）

定时器模式：固定间隔

计时器： 间隔：300秒（5分钟）

Diff模式：基于阈值

diff_threshold： 阈值：0.05#如果5%的文件发生更改，则保存 check_interval:60#每60秒检查一次 ignore_whitespace：真的 ignore_comments：false

混合模式：结合定时器+差速器（推荐）

混合的： min_interval:180#两次保存之间至少间隔3分钟 max_interval：600#两次保存之间最多10分钟 阈值：0.03#如果3%的文件发生更改，则保存

保留政策

保留： max_autosaves:50#保持最多50次自动保存 压缩后天数：7#7天后压缩 delete_after_days:30#30天后删除 keep_manual:true#始终保留手动快照

文件输出

输出： 默认名称：“｛项目｝文档{date}.md“ include_tree：true include_code：true tree_full_code_select:false#完整树，仅选择代码 language_detection：true max_file_size:1000000#1每个文件最大MB

Diff输出格式

diff_format： 默认值：unified#unified|json|ast 统一上下文：3 json_include_content:true ast_enabled:false#实验

存储

存储路径：.gencodedoc 压缩启用：true 压缩级别：3#1-22（3=良好平衡） 快速配置命令 Bash

自动保存

gencodedoc配置集autosave.enabled true gencodedoc配置集autosave.mode混合

调整自动保存阈值

gencodedoc配置集autosave.hybrid.min_interval 300 gencodedoc配置集autosave.hybrid.max_interval 1800 gencodedoc配置集autosave.hybrid.threshold 0.03

添加忽略规则

gencodedoc配置忽略--添加目录dist 忽略gencodedoc配置--添加ext.tmp gencodedoc配置忽略--添加文件debug.log 🏗️ 建筑 文本

┌─────────────────────────────────────────────────────────────┐ │ GenCodeDoc系统│ └─────────────────────────────────────────────────────────────┘

┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ CLI（打字机）│ │ MCP标准│ │ MCP SSE/REST│ │ │ │ （Gemini CLI）│ │ （克劳德/Web）│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ └─────────────────┼──────────────────┘ │ ┌──────────▼──────────┐ │ 核心管理人员│ ├─────────────────────┤ │ • 配置管理器│ │ • 版本管理器│ │ • DocGenerator│ │ • 自动保存管理器│ └──────────┬──────────┘ │ ┌───────────────┼───────────────┐ │ │ │ ┌────▼─────┐ ┌─────▼──────┐ ┌────▼──────┐ │ 扫描仪│ │ 差异│ │ 存储│ │ │ │ │ │ │ │ • 扫描│ │ • 统一│ │ • SQLite│ │ • 过滤器│ │ • JSON│ │ • zstd│ │ • 检测│ │ • AST│ │ • 去重│ └──────────┘ └────────────┘ └───────────┘

┌─────────────────────────────────────────────────────────────┐ │ 存储层│ ├─────────────────────────────────────────────────────────────┤ │ .通用代码文档/│ │ ├── gencodedoc.db← SQLite（元数据）│ │ │ ├── 快照← 快照记录│ │ │ ├── 快照文件← 文件条目│ │ │ ├── 文件内容← 重复内容（SHA256）│ │ │ └── autosave_state← 自动保存状态│ │ └── 配置/← 配置文件│ └─────────────────────────────────────────────────────────────┘

主要特点： • 🔑 SHA256重复数据删除→ ~70% 节省空间 • 🗜️ zstd压缩→ ~3x尺寸减小 • 📊 索引SQLite→ 快速查询 • 🔄 看门狗观察员→ 实时文件监控 项目结构 文本

通用代码文档/ ├── gencodedoc/#源代码 │ ├── cli/#cli命令（Typer） │ │ ├── main.py#入口点 │ │ ├── snapshot_cmd.py │ │ ├── doc_cmd.py │ │ ├── config_cmd.py │ │ └── mcp_cmd.py │ ├── core/#业务逻辑 │ │ ├── config.py#配置管理 │ │ ├── scanner.py#文件扫描和过滤 │ │ ├── version.py#快照管理 │ │ ├── 文档.py │ │ ├── different.py#版本比较 │ │ └── autosave.py#智能自动保存 │ ├── mcp/#mcp服务器 │ │ ├── server_strio.py#stdio传输 │ │ ├── server_sse.py#sse传输 │ │ ├── server.py#REST传输 │ │ └── tools.py#工具定义 │ ├── models/#数据模型（Pydantic） │ │ ├── config.py │ │ └── 快照.py │ ├── 存储/#存储和压缩 │ │ ├── database.py#SQLite管理器 │ │ ├── snapshot_store.py │ │ └── compression.py#zstd压缩 │ └── utils/#实用程序 │ ├── 过滤器.py │ ├── formatters.py │ └── tree.py ├── config/#配置预设 │ └── 预设/ │ ├── python.yaml │ ├── nodejs.yaml │ ├── go.yaml │ └── web.yaml ├── 测试/#单元测试 ├── pyproject.toml#诗歌配置 ├── Makefile#开发命令 └── README.md 🔬 高级功能 🎯 智能重复数据删除（节省约70%） GenCodeDoc使用基于SHA256的重复数据消除：

✅ 快照中的相同文件存储一次 ✅ 节省大量空间（实际项目约70%） ✅ zstd压缩，可额外减少约3倍 ✅ 使用索引优化SQLite

示例：100 MB项目的10个快照

无重复数据删除：1 GB 使用GenCodeDoc：约300 MB（数据消除+压缩） 🔄 自动保存模式 模式如何最好地工作 timer每X秒保存一次持续开发 diff当X%更改关键项目时保存 混合⭐最小/最大间隔+阈值一般用途（推荐） 混合模式示例：

YAML

混合的： min_interval:300#保存时间不要超过5分钟 max_interval：1800#30分钟后强制保存 阈值：0.03#或者，如果3%的文件发生了更改 📊 不同格式 格式说明用例 统一Git风格差异人工阅读 json结构化数据自动化 ast语义差异代码分析（实验） Bash

统一差异（默认）

gencodedoc快照差异v1.0 v2.0

JSON用于脚本

gencodedoc快照diff v1.0 v2.0--格式json>changes.json

AST（语义）

gencodedoc快照差异v1.0 v2.0——格式ast 🐛 故障排除 常见问题 1.️⃣ MCP错误：通知/初始化 症状：MCP启动时出错：

文本

MCP错误：未知方法：通知/初始化 原因：MCP协议发送旧版本无法处理的通知。

解决方案：✅ 已在当前版本中修复。服务器现在默认忽略MCP通知。

2.️⃣ 在错误位置创建的快照 症状：所有快照都会转到gencodedoc自己的目录，而不是目标项目。

原因：未从MCP工具/调用参数中正确提取project_path。

解决方案：✅ 已经修好了。服务器现在可以从参数中正确提取project_path。

验证修复：

Bash

这应该在/path/to/project中创建快照，而不是gencodedoc

/gencodedoc create_snapshot项目路径=/path/to/project标签=test 3.️⃣ Zod验证错误（id=null） 症状：

文本

错误：预期字符串或数字，收到null（路径：[“id”]） 原因：JSON-RPC响应的“id”为null，而不是“id”：0。

解决方案：✅ 已经修好了。所有错误响应现在都使用request_id或0。

4.️⃣ 文件未正确扫描 症状：快照显示错误数量的文件或来自错误目录的文件。

原因：snapshot_store.py使用了相对路径而不是绝对路径。

解决方案：✅ 已经修好了。SnapshotStore现在接收并使用project_path作为绝对文件路径。

5.️⃣ 数据库未初始化 症状：

文本

错误：没有这样的表：快照 原因：创建快照之前未初始化项目。

解决方案：

Bash

始终先初始化（创建表）

gencodedoc初始化--预设python

或通过MCP

/gencodedoc init_project项目路径=/path/to/project预设=python 6.️⃣ 自动保存未启动 症状：start_autosave工具不起作用。

原因：自动保存要求MCP服务器保持运行（这是一个后台进程）。

解决方案：

stdio模式：服务器按请求运行→ 请求结束时自动保存停止 SSE/REST模式：✅ 服务器持久→ 自动保存工作！ 建议：使用SSE/REST进行自动保存，使用stdio进行一次性命令。

调试模式 Bash

启用详细日志记录（如果已实现）

导出GENCODEDOC_DEBUG=1 诗歌运行gencodedoc快照创建——消息“测试”

直接检查SQLite数据库

sqlite3/path/to/project/.gencodedoc/gencodedoc.db“.tables” sqlite3/path/to/project/.gencodedoc/gencodedoc.db“从快照中选择*；” 🧪 测试 Bash

运行所有测试

诗歌运行pytest

覆盖范围

诗歌运行pytest--cov=gencodedoc--cov报告=html

具体测试

诗歌运行pytest测试/test_scanner.py-v 诗歌运行pytest测试/test_version.py-v 诗歌运行pytest测试/test_mcp.py-v

监视模式（需要pytest监视）

诗歌运行ptw 🛠️ 发展 设置开发环境 Bash

使用开发依赖项进行安装

诗歌装置

激活虚拟环境

诗壳

安装预提交挂钩（如果已配置）

预提交安装 Makefile命令 Bash

make help#显示所有命令 make install#安装依赖项 make test#运行测试 使测试cov#覆盖率测试 make lint#检查代码质量 make format#格式化代码（黑色） make clean#删除临时文件 make docs#生成文档 make service mcp sse#启动sse服务器 make serve mcp stdio#启动stdio服务器 让所有#Lint+test+build 代码风格 格式化程序：黑色（线长100） 林特：拉夫 类型提示：用Pydantic强制 文档字符串：谷歌风格 🎯 用例 1.️⃣ 持续文档 Bash

使用自动保存进行初始化

gencodedoc初始化--预设python gencodedoc配置集autosave.enabled true gencodedoc配置集autosave.mode混合

文档始终是最新的

gencodedoc单据生成--输出单据/API.md 2.️⃣ 安全重构 Bash

关键更改前的快照

gencodedoc快照创建
--消息“重构身份验证系统之前”
--重构前标记

…做出改变。..

快照后

gencodedoc快照创建
--消息“重构后-测试通过”
--重构后的标签

比较

重构前后gencodedoc快照差异

必要时回滚

重构前的gencodedoc快照还原--强制 3.️⃣ API选择性文档 Bash

仅记录特定模块

gencodedoc文档生成
--包含src/api/
--包括src/模型/
--包含README.md
--输出文档/API_Reference.md 4.️⃣ 人工智能辅助工作流程（Gemini/Claude） Bash

1.配置MCP（一次）

将gencodedoc添加到您的AI助手配置中

2.使用自然语言

“使用标记v2.0创建快照” “比较v1.0和v2.0” “显示项目统计信息” “在混合动力模式下启动自动保存” “生成完整的文档”

AI会自动调用正确的MCP工具！ 🎉

🌟 路线图 Git集成（提交时自动快照） 云备份（S3、GCS） Web UI仪表板 基于AST的语义差异（完整实现） 多语言预设（Rust、Java、C++） 快照加密 协作功能（共享快照） 📄 许可证 MIT许可证-请参阅许可证文件

🤝 贡献 欢迎投稿！ 🎉

🐛 通过GitHub Issues报告错误 💡 通过讨论建议功能 🔧 提交拉取请求 开发工作流程：

分叉回购 创建一个功能分支（git checkout-b功能/惊人） 进行更改 运行测试（进行测试） 提交PR 📞 支持 🐛 问题：GitHub问题 💬 讨论：GitHub讨论 🌐 网站：esprit-artificiel.com 📧 电子邮件：support@esprit-artificiel.com 🙏 致谢 使用这些神奇的工具构建：

FastAPI-MCP服务器框架 Pydantic-数据验证 Typer-CLI框架 丰富-终端格式化 z标准-压缩 看门狗-文件监控 SQLite-嵌入式数据库

💡 专业提示：使用GenCodeDoc与Gemini CLI或Claude Desktop进行AI驱动的版本控制！

⭐ 如果你觉得这个仓库有用，就把它标上！