Zhiwen Assistant MCP

# 智文助手使用指南 本文档详细介绍智文助手的各项功能和使用方法。 ## 📚 目录 - [快速开始](#快速开始) - [基础功能](#基础功能) - [高级功能](#高级功能) - [配置管理](#配置管理) - [使用技巧](#使用技巧) - [故障排除](#故障排除) ## 🚀 快速开始 ### 最简单的使用方法 1. **启动智文助手** ```bash python folder_documentation_mcp.py ``` 2. **生成项目文档** ```python # 在MCP客户端中调用 generate_readme_files({ "root_dir": "/path/to/your/project" }) ``` 3. **查看生成的文档** - 项目目录中的每个文件夹都会有 `README.md` - 项目根目录会有 `folder_structure_mindmap.md` ## 🎯 基础功能 ### 1. 生成README文档 #### 功能说明 自动扫描项目文件夹结构，为每个主要文件夹生成中文README.md文件，包含： - 文件夹用途说明 - 子文件夹列表及描述 - 文件列表及类型说明 - 生成时间戳 #### 使用方法 ```python # 基础用法 generate_readme_files({ "root_dir": "/path/to/project" }) # 高级用法 generate_readme_files({ "root_dir": "/path/to/project", "exclude_dirs": [".git", "__pycache__", "node_modules"], "force_update": True # 强制更新已存在的README }) ``` #### 示例 ```bash # 命令行使用 python folder_documentation_mcp.py --generate-readme --root /home/user/myproject # 配置文件中设置 options: exclude_dirs: - ".git" - "__pycache__" - "node_modules" - ".vscode" force_update: false ``` ### 2. 生成思维导图 #### 功能说明 生成项目文件夹结构的思维导图，使用Mermaid格式，支持： - 多层级嵌套结构 - 可视化层次关系 - 自动排除无用目录 #### 使用方法 ```python # 基础用法 generate_mindmap({ "root_dir": "/path/to/project" }) # 自定义输出文件 generate_mindmap({ "root_dir": "/path/to/project", "output_file": "custom_mindmap.md", "exclude_dirs": [".git", "temp"] }) ``` #### 示例输出 ```markdown # 项目文件夹结构思维导图 ```mermaid flowchart TD subgraph 项目结构 root["myproject/"] root --> src["src/"] root --> docs["docs/"] src --> main["main.py"] src --> utils["utils.py"] docs --> guide["guide.md"] end ``` ### 3. 获取文件夹结构 #### 功能说明 以文本树形结构显示项目文件夹层次，便于快速了解项目结构。 #### 使用方法 ```python get_folder_structure({ "root_dir": "/path/to/project", "exclude_dirs": [".git"] }) ``` #### 示例输出 ``` myproject/ ├── src/ │ ├── main.py │ └── utils.py ├── docs/ │ └── guide.md ├── tests/ │ └── test_main.py └── README.md ``` ## 🔧 高级功能 ### 1. 批量文档更新 #### 功能说明 更新项目中的所有README.md文件和思维导图，支持增量更新。 #### 使用方法 ```python update_documentation({ "root_dir": "/path/to/project", "exclude_dirs": [".git", "__pycache__"], "update_mindmap": True }) ``` ### 2. 自定义文件夹描述 #### 功能说明 为特定文件夹提供自定义中文描述，使生成的文档更准确。 #### 配置方法 1. 创建 `config/custom_descriptions.yaml` 2. 添加自定义描述： ```yaml custom_descriptions: "src": "源代码目录" "tests": "单元测试目录" "docs": "项目文档目录" "utils": "工具函数目录" "config": "配置文件目录" "assets": "静态资源目录" # 子文件夹描述 "src/controllers": "控制器模块" "src/models": "数据模型" "src/views": "视图层代码" ``` ### 3. 安全验证 #### 功能说明 启用安全验证后，系统会： - 检查恶意路径 - 扫描敏感内容 - 验证文件类型安全性 #### 配置方法 ```yaml security: enable_security_validation: true scan_sensitive_content: true block_dangerous_files: true allowed_paths: - "/projects/*" - "/workspace/*" ``` ### 4. 性能优化 #### 功能说明 - **缓存系统**: 缓存扫描结果，提高处理速度 - **并发处理**: 支持多线程文件操作 - **增量更新**: 只处理变更的文件 #### 配置方法 ```yaml performance: cache_ttl: 3600 # 缓存1小时 max_concurrent_operations: 5 enable_performance_monitoring: true ``` ## ⚙️ 配置管理 ### 1. 主配置文件 编辑 `mcp_config.yaml`： ```yaml # 服务器基本配置 server: name: "智文助手" version: "2.0.0" transport: "stdio" # 功能选项 options: exclude_dirs: - ".git" - "__pycache__" - "node_modules" - "dist" - "build" force_update: false output_file: "folder_structure_mindmap.md" max_depth: 10 include_hidden: false # 性能配置 performance: cache_ttl: 3600 max_concurrent_operations: 5 enable_performance_monitoring: true # 安全配置 security: enable_security_validation: true scan_sensitive_content: true block_dangerous_files: true allowed_paths: [] ``` ### 2. 环境变量 ```bash # 设置配置文件路径 export ZHIWEN_CONFIG="/path/to/config.yaml" # 设置缓存目录 export ZHIWEN_CACHE_DIR="/tmp/zhiwen_cache" # 设置日志级别 export ZHIWEN_LOG_LEVEL="INFO" ``` ## 💡 使用技巧 ### 1. 最佳实践 #### 项目结构建议 ``` project/ ├── src/ # 源代码 ├── docs/ # 文档 ├── tests/ # 测试 ├── config/ # 配置 ├── scripts/ # 脚本 ├── assets/ # 资源 └── README.md # 主说明文件 ``` #### 文档生成策略 ```python # 首次生成 - 全面扫描 generate_readme_files({ "root_dir": "/project", "force_update": True }) # 日常更新 - 增量更新 update_documentation({ "root_dir": "/project", "update_mindmap": False }) # 发布前 - 完整更新 update_documentation({ "root_dir": "/project", "update_mindmap": True, "force_update": True }) ``` ### 2. 集成开发流程 #### Git Hooks ```bash #!/bin/sh # .git/hooks/pre-commit python /path/to/folder_documentation_mcp.py --update-docs git add docs/ git commit -m "Update documentation" ``` #### CI/CD集成 ```yaml # .github/workflows/docs.yml name: Update Documentation on: [push] jobs: update-docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Python uses: actions/setup-python@v2 with: python-version: '3.10' - name: Update Docs run: | python folder_documentation_mcp.py --update-all git config --local user.email "action@github.com" git config --local user.name "GitHub Action" git add docs/ git commit -m "Auto update documentation" || exit 0 git push ``` ### 3. 团队协作 #### 共享配置 ```yaml # team_config.yaml team_settings: documentation_standard: "chinese" excluded_patterns: - "secret/*" - "personal/*" custom_descriptions: "frontend": "前端模块" "backend": "后端模块" ``` ## 🐛 故障排除 ### 常见问题 #### 1. 文档生成失败 **症状**: 运行后没有生成文档文件 **解决方案**: ```bash # 检查权限 ls -la /target/directory # 检查路径 python -c "import os; print(os.path.exists('/path/to/project'))" # 启用详细日志 export ZHIWEN_LOG_LEVEL="DEBUG" ``` #### 2. 中文编码问题 **症状**: 生成的文档中文乱码 **解决方案**: ```python # 在配置文件中设置 encoding: input: "utf-8" output: "utf-8-sig" ``` #### 3. 性能问题 **症状**: 大项目处理缓慢 **解决方案**: ```yaml # 优化配置 performance: cache_ttl: 86400 # 24小时缓存 max_concurrent_operations: 10 enable_incremental_update: true # 排除不必要的目录 options: exclude_dirs: - ".git" - "__pycache__" - "node_modules" - ".pytest_cache" - "coverage" ``` ### 调试技巧 #### 1. 启用调试模式 ```bash python folder_documentation_mcp.py --debug --verbose ``` #### 2. 检查日志 ```bash # 查看实时日志 tail -f logs/zhiwen.log # 搜索错误 grep "ERROR" logs/zhiwen.log ``` #### 3. 测试特定功能 ```python # 只测试README生成 python -c " from folder_documentation_mcp import generate_readme_files result = generate_readme_files({'root_dir': '/test/path'}) print(result) " ``` --- *更新时间: 2025-12-19*