GenCodeDoc

🚀 GenCodeDoc

---

⚡ 快速入门

# 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

🎯 面向 AI 助手（Claude/Gemini）：请参阅 MCP 集成

✨ 功能 🎯 核心功能 📸 智能快照 - 通过 SHA256 去重创建智能快照，节省约 70% 的空间 🔄 智能自动保存 - 3 种模式（计时器/差异/混合），支持配置阈值 📝 精美文档 - 生成带语法高亮、目录树和智能拆分的 Markdown 文档 🔍 高级差异比较 - 使用统一、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+ Poetry（依赖管理器） 安装 Poetry Bash

Linux/macOS

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell)

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py - 安装 GenCodeDoc Bash

克隆项目或进入项目目录

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

安装依赖

poetry install

验证安装

poetry run gencodedoc --help 🎯 使用 📋 CLI 用法 初始化项目 Bash

基本初始化

gencodedoc init

使用 Python 预设（Oracle 项目推荐）

gencodedoc init --preset python

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

快照管理 Bash

创建快照

gencodedoc snapshot create --message "Feature X completed" --tag v1.0

列出快照

gencodedoc snapshot list --limit 10

显示快照详情

gencodedoc snapshot show v1.0

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

gencodedoc snapshot cat v1.0 src/main.py

列出快照中的文件（新增）

gencodedoc snapshot files v1.0 --pattern "*.py"

比较版本

gencodedoc snapshot diff v1.0 v2.0

恢复快照（完整或部分）

gencodedoc snapshot restore v1.0 --force gencodedoc snapshot restore v1.0 --filter "src/*.py" # 部分恢复

导出快照（新增）

gencodedoc snapshot export v1.0 ./dist-v1 --archive # 创建 .tar.gz

删除快照

gencodedoc snapshot delete old-version --force

清理孤立数据（新增）

gencodedoc snapshot cleanup 生成文档 Bash

完整文档

gencodedoc doc generate

自定义输出

gencodedoc doc generate --output docs/API.md

仅包含指定路径

gencodedoc doc generate --include src/api/ --include README.md

预览结构

gencodedoc doc preview --max-depth 3

项目统计

gencodedoc doc stats 配置 Bash

查看配置

gencodedoc config show

编辑配置

gencodedoc config edit

设置特定值

gencodedoc config set autosave.enabled true gencodedoc config set autosave.mode hybrid

应用预设

gencodedoc config preset python

管理忽略规则

gencodedoc config ignore --add-dir dist gencodedoc config ignore --add-ext .tmp gencodedoc config ignore --list-all

可自定义的预设

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

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

项目状态 Bash

显示项目状态

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

🎯 传输模式 传输方式 使用场景 AI 助手 端口 stdio CLI 集成 Gemini CLI、自定义脚本 stdin/stdout SSE Web/桌面应用 Claude Desktop、Web UI 8000 (HTTP) REST API 集成 任何 HTTP 客户端 8000 (HTTP) 🚀 Gemini CLI 设置（stdio）

1. 查找 Poetry 虚拟环境路径：

Bash

cd /home/fkomp/Bureau/oracle/utilitaires/gencodedoc/gencodedoc poetry env info --path

复制路径并追加 /bin/python

2. 添加到 ~/.config/gemini-desktop-app/settings.json：

JSON

{ "mcpServers": { "gencodedoc": { "command": "/path/to/your/venv/bin/python", "args": ["-m", "gencodedoc.mcp.server_stdio"], "env": { "PROJECT_PATH": "/home/fkomp/Bureau/oracle/utilitaires/gencodedoc/gencodedoc" } } } } 3. 重启 Gemini CLI，即可开始使用！🎉

🚀 Claude Desktop 设置（SSE）

1. 启动 SSE 服务：

Bash

终端 1：启动服务

poetry run python -m gencodedoc.mcp.server_sse

服务运行于 http://127.0.0.1:8000

2. 添加到 Claude Desktop 配置：

位置：

macOS：/Library/Application Support/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", "transport": "sse", "description": "GenCodeDoc - 智能文档与版本管理" } } } 3. 重启 Claude Desktop，并确保服务持续运行！

🚀 REST API Bash

启动 REST 服务

poetry run python -m gencodedoc.mcp.server

可用端点

GET http://127.0.0.1:8000/ # 服务信息 GET http://127.0.0.1:8000/mcp/tools # 工具列表 POST http://127.0.0.1:8000/mcp/execute # 执行工具 🛠️ MCP 工具（26 个）

🧠 代码智能（3 个工具）

工具	描述	关键参数
get_file_history	跟踪文件在不同版本中的更改	file_path
search_snapshots	在所有快照中搜索文本	query, case_sensitive, file_filter
generate_changelog	生成 Keep-a-Changelog	from_ref, to_ref

📸 快照管理（11 个工具）

工具	描述	关键参数
create_snapshot	创建新快照	message, tag, include_paths
list_snapshots	列出所有快照	limit, include_autosave
get_snapshot_details	获取完整的快照信息	snapshot_ref
restore_snapshot	恢复快照（全部或部分）	snapshot_ref, force, file_filters
restore_files	恢复指定文件	snapshot_ref, file_filters
delete_snapshot	删除快照	snapshot_ref
diff_versions	比较两个版本	from_ref, to_ref, format, file_filters
get_file_at_version	获取单个文件的内容	snapshot_ref, file_path
list_files_at_version	列出快照中的文件	snapshot_ref, pattern
export_snapshot	将快照导出到文件夹或归档	snapshot_ref, output_path, archive
cleanup_orphaned_contents	清理未使用的数据	无

📝 文档（3 个工具）

工具	描述	关键参数
generate_documentation	生成 Markdown 文档	output_path, split_limit, ignore_tree_patterns
preview_structure	显示目录树	max_depth, ignore_add, limit, page
get_project_stats	获取项目统计信息	无

🎯 项目管理（2 个工具）

工具	描述	关键参数
init_project	初始化 gencodedoc	project_path, preset
get_project_status	获取项目状态	project_path

⚙️ 配置（4 个工具）

工具	描述	关键参数
get_config	查看配置	project_path
set_config_value	修改配置值	key, value
apply_preset	应用预设配置	preset (python/nodejs/go/web)
manage_ignore_rules	管理忽略规则	add_dir, add_file, add_ext, list_all

🔄 自动保存（3 个工具）

工具	描述	关键参数
start_autosave	启动自动版本管理	project_path, mode
stop_autosave	停止自动版本管理	project_path
get_autosave_status	获取所有自动保存任务的状态	无

---

🤝 参与贡献 欢迎贡献！🎉

🐛 通过 GitHub Issues 报告错误 💡 通过 Discussions 提出功能建议 🔧 提交 Pull Requests

开发工作流：

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing）
3. 进行更改
4. 运行测试（make test）
5. 提交 PR

📄 许可证 MIT 许可证 - 参见 LICENSE 文件

🐛 问题：GitHub Issues 💬 讨论：GitHub Discussions 🌐 网站：esprit-artificiel.com 📧 电子邮件：[email protected]

🤖 “以混合模式为此项目启动自动保存” → 调用：start_autosave(project_path="...", mode="hybrid")

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

project_name: "my-project"

要忽略的文件／目录

ignore: dirs: - node_modules - venv - .venv - pycache - .git - dist - build files: - "*.log" - package-lock.json - .DS_Store extensions: - .pyc - .pyo - .exe - .jpg - .png - .pdf patterns: [] # gitignore 样式的模式

智能自动保存

autosave: enabled: false # 设置为 true 以启用 mode: hybrid # timer | diff | hybrid（推荐）

定时器模式：固定间隔

timer: interval: 300 # 秒（5 分钟）

Diff 模式：基于阈值

diff_threshold: threshold: 0.05 # 文件变更达到 5% 时保存 check_interval: 60 # 每 60 秒检查一次 ignore_whitespace: true ignore_comments: false

混合模式：结合定时器和 Diff（推荐）

hybrid: min_interval: 180 # 保存间隔最短为 3 分钟 max_interval: 600 # 保存间隔最长为 10 分钟 threshold: 0.03 # 文件变更达到 3% 时保存

保留策略

retention: max_autosaves: 50 # 最多保留 50 个自动保存版本 compress_after_days: 7 # 7 天后压缩 delete_after_days: 30 # 30 天后删除 keep_manual: true # 始终保留手动快照

文档输出

output: default_name: "{project}doc{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: default: unified # unified | json | ast unified_context: 3 json_include_content: true ast_enabled: false # 实验性功能

存储

storage_path: .gencodedoc compression_enabled: true compression_level: 3 # 1-22（3 = 平衡性较好） 快速配置命令 Bash

启用自动保存

gencodedoc config set autosave.enabled true gencodedoc config set autosave.mode hybrid

调整自动保存阈值

gencodedoc config set autosave.hybrid.min_interval 300 gencodedoc config set autosave.hybrid.max_interval 1800 gencodedoc config set autosave.hybrid.threshold 0.03

添加忽略规则

gencodedoc config ignore --add-dir dist gencodedoc config ignore --add-ext .tmp gencodedoc config ignore --add-file debug.log 🏗️ 架构 text

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

┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ CLI (Typer) │ │ MCP stdio │ │ MCP SSE/REST │ │ │ │ (Gemini CLI) │ │ (Claude/Web) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ └─────────────────┼──────────────────┘ │ ┌──────────▼──────────┐ │ 核心管理器 │ ├─────────────────────┤ │ • ConfigManager │ │ • VersionManager │ │ • DocGenerator │ │ • AutosaveManager │ └──────────┬──────────┘ │ ┌───────────────┼───────────────┐ │ │ │ ┌────▼─────┐ ┌─────▼──────┐ ┌────▼──────┐ │ 扫描器 │ │ Diff 工具 │ │ 存储 │ │ │ │ │ │ │ │ • 扫描 │ │ • Unified │ │ • SQLite │ │ • 筛选 │ │ • JSON │ │ • zstd │ │ • 检测 │ │ • AST │ │ • 去重 │ └──────────┘ └────────────┘ └───────────┘ ┌─────────────────────────────────────────────────────────────┐ │ 存储层 │ ├─────────────────────────────────────────────────────────────┤ │ .gencodedoc/ │ │ ├── gencodedoc.db ← SQLite（元数据） │ │ │ ├── snapshots ← 快照记录 │ │ │ ├── snapshot_files ← 文件条目 │ │ │ ├── file_contents ← 去重后的内容（SHA256） │ │ │ └── autosave_state ← 自动保存状态 │ │ └── config/ ← 配置文件 │ └─────────────────────────────────────────────────────────────┘

主要功能： • 🔑 SHA256 去重 → 节省约 70% 空间 • 🗜️ zstd 压缩 → 体积缩小约 3 倍 • 📊 索引化 SQLite → 快速查询 • 🔄 Watchdog 观察器 → 实时文件监控 项目结构 text

gencodedoc/ ├── gencodedoc/ # 源代码 │ ├── cli/ # CLI 命令（Typer） │ │ ├── main.py # 入口点 │ │ ├── snapshot_cmd.py │ │ ├── doc_cmd.py │ │ ├── config_cmd.py │ │ └── mcp_cmd.py │ ├── core/ # 业务逻辑 │ │ ├── config.py # 配置管理 │ │ ├── scanner.py # 文件扫描和筛选 │ │ ├── versioning.py # 快照管理 │ │ ├── documentation.py │ │ ├── differ.py # 版本比较 │ │ └── autosave.py # 智能自动保存 │ ├── mcp/ # MCP 服务 │ │ ├── server_stdio.py # stdio 传输 │ │ ├── server_sse.py # SSE 传输 │ │ ├── server.py # REST 传输 │ │ └── tools.py # 工具定义 │ ├── models/ # 数据模型（Pydantic） │ │ ├── config.py │ │ └── snapshot.py │ ├── storage/ # 存储和压缩 │ │ ├── database.py # SQLite 管理器 │ │ ├── snapshot_store.py │ │ └── compression.py # zstd 压缩 │ └── utils/ # 实用工具 │ ├── filters.py │ ├── formatters.py │ └── tree.py ├── config/ # 配置预设 │ └── presets/ │ ├── python.yaml │ ├── nodejs.yaml │ ├── go.yaml │ └── web.yaml ├── tests/ # 单元测试 ├── pyproject.toml # Poetry 配置 ├── Makefile # 开发命令 └── README.md 🔬 高级功能 🎯 智能去重（节省约 70%） GenCodeDoc 使用基于 SHA256 的去重：

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

示例：对一个 100 MB 项目创建 10 个快照

不去重：1 GB 使用 GenCodeDoc：约 300 MB（去重 + 压缩） 🔄 自动保存模式 模式 工作方式 适用场景 timer 每隔 X 秒保存一次 持续开发 diff 更改达到 X% 时保存 关键项目 hybrid ⭐ 最小/最大间隔 + 阈值 一般用途（推荐） 混合模式示例：

YAML

hybrid: min_interval: 300 # 保存间隔不得短于 5 min max_interval: 1800 # 30 min 后强制保存 threshold: 0.03 # 或者在 3% 的文件发生变化时保存 📊 差异格式 格式 说明 使用场景 unified Git 风格的差异 人工阅读 json 结构化数据 自动化 ast 语义差异 代码分析（实验性） Bash

统一差异（默认）

gencodedoc snapshot diff v1.0 v2.0

用于脚本的 JSON

gencodedoc snapshot diff v1.0 v2.0 --format json > changes.json

AST（语义）

gencodedoc snapshot diff v1.0 v2.0 --format ast 🐛 故障排除 常见问题 1️⃣ MCP 错误：notifications/initialized 症状：MCP 启动时报错：

text

MCP ERROR: Unknown method: notifications/initialized 原因：MCP 协议会发送旧版本无法处理的通知。

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

2️⃣ 快照创建在错误的位置 症状：所有快照都保存到 gencodedoc 自身的目录中，而不是目标项目目录。

原因：未能从 MCP tools/call 参数中正确提取 project_path。

解决方案：✅ 已修复。服务现在会从参数中正确提取 project_path。

验证修复：

Bash

This should create snapshot in /path/to/project, not gencodedoc

/gencodedoc create_snapshot project_path=/path/to/project tag=test 3️⃣ Zod 验证错误（id=null） 症状：

text

Error: Expected string or number, received null (path: ["id"]) 原因：JSON-RPC 响应中的 "id": null，而不是 "id": 0。

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

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

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

解决方案：✅ 已修复。SnapshotStore 现在会接收并使用 project_path 来设置文件的绝对路径。

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

text

Error: no such table: snapshots 原因：创建快照前未初始化项目。

解决方案：

Bash

Always init first (creates tables)

gencodedoc init --preset python

Or via MCP

/gencodedoc init_project project_path=/path/to/project preset=python 6️⃣ 自动保存未启动 症状：start_autosave 工具不起作用。

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

解决方案：

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

调试模式 Bash

Enable verbose logging (if implemented)

export GENCODEDOC_DEBUG=1 poetry run gencodedoc snapshot create --message "test"

Check SQLite DB directly

sqlite3 /path/to/project/.gencodedoc/gencodedoc.db ".tables" sqlite3 /path/to/project/.gencodedoc/gencodedoc.db "SELECT * FROM snapshots;" 🧪 测试 Bash

Run all tests

poetry run pytest

With coverage

poetry run pytest --cov=gencodedoc --cov-report=html

Specific tests

poetry run pytest tests/test_scanner.py -v poetry run pytest tests/test_versioning.py -v poetry run pytest tests/test_mcp.py -v

Watch mode (requires pytest-watch)

poetry run ptw 🛠️ 开发 设置开发环境 Bash

Install with dev dependencies

poetry install

Activate virtual environment

poetry shell

Install pre-commit hooks (if configured)

pre-commit install Makefile 命令 Bash

make help # Show all commands make install # Install dependencies make test # Run tests make test-cov # Tests with coverage make lint # Check code quality make format # Format code (Black) make clean # Remove temporary files make docs # Generate documentation make serve-mcp-sse # Start SSE server make serve-mcp-stdio # Start stdio server make all # Lint + test + build 代码风格 格式化工具：Black（行长 100） 代码检查工具：Ruff 类型提示：使用 Pydantic 强制执行 文档字符串：Google 风格 🎯 使用场景 1️⃣ 持续更新文档 Bash

Initialize with autosave

gencodedoc init --preset python gencodedoc config set autosave.enabled true gencodedoc config set autosave.mode hybrid

Documentation is always up-to-date

gencodedoc doc generate --output docs/API.md 2️⃣ 安全重构 Bash

Snapshot before critical changes

gencodedoc snapshot create
--message "Before refactoring authentication system"
--tag before-refactor

... make changes ...

快照之后

gencodedoc snapshot create
--message "After refactoring - tests passing"
--tag after-refactor

比较

gencodedoc snapshot diff before-refactor after-refactor

如有需要，回滚

gencodedoc snapshot restore before-refactor --force 3️⃣ 选择性 API 文档 Bash

仅记录特定模块

gencodedoc doc generate
--include src/api/
--include src/models/
--include README.md
--output docs/API_Reference.md 4️⃣ AI 辅助工作流（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 许可证 - 参见 LICENSE 文件

🤝 贡献 欢迎贡献！🎉

🐛 通过 GitHub Issues 报告错误 💡 通过 Discussions 提出功能建议 🔧 提交 Pull Request 开发工作流：

Fork 此仓库 创建功能分支（git checkout -b feature/amazing） 进行修改 运行测试（make test） 提交 PR 📞 支持 🐛 问题：GitHub Issues 💬 讨论：GitHub Discussions 🌐 网站：esprit-artificiel.com 📧 邮箱：[email protected] 🙏 致谢 使用以下出色工具构建：

FastAPI - MCP 服务框架 Pydantic - 数据验证 Typer - CLI 框架 Rich - 终端格式化 zstandard - 压缩 Watchdog - 文件监控 SQLite - 嵌入式数据库

``` 🎯 与旧版相比的变更 ✅ 主要新增内容 顶部徽章（Python、Poetry、MCP、License、AI Ready） 醒目易见的快速入门，分为 5 个步骤 通过表格记录 17 个 MCP 工具 完整的 ASCII 架构图 针对我们已修复的 6 个错误提供故障排除说明 具体的 AI 使用示例 更清晰地说明自动保存（3 种模式 + 表格） 明确说明 3 种传输方式（stdio/SSE/REST） 实用场景（4 个真实场景） 未来路线图 🎨 视觉改进 全文统一使用表情符号 使用表格进行比较 格式规范的代码块 通过分隔线划分清晰的章节 页脚添加行动号召 📊 结构优化 快速入门置于首位（最重要内容） 在安装之前介绍功能 单独设立 MCP 工具章节 完整的故障排除说明 将开发内容单独列出