--- slug: "explain-code-tool-pro" name: "explain-code-tool-pro" version: "1.0.0" displayName: "代码解释工具专业版" summary: "企业级代码理解工具,支持项目架构分析、批量文档生成、Mermaid可视化与API文档输出。。面向研发团队的高级代码理解工具,提供项目级架构分析、批量代码文档生成、Mermaid/UML可视化" license: "Proprietary" edition: "pro" description: |- 面向研发团队的高级代码理解工具,提供项目级架构分析、批量代码文档生成、Mermaid/UML可视化与API文档自动输出。核心能力: - 项目级架构分析与依赖图 - 批量代码文档自动生成 - Mermaid/UML 高质量可视化 - API 文档自动提取与生成 - 代码复杂度与质量分析 - 团队知识库构建 适用场景: - 大型项目代码理解与onboarding - 技术文档自动化生成 - 架构评审与可视化 - 遗留系统逆向理解 差异化: - 专业版完全兼容免费版解释风格,支持平滑升级 - 支... tags: - 开发工具 - 代码理解 - 技术文档 - 企业级 - 代码生成 - 编程辅助 - true - docs - mermaid - api tools: - read - exec - write - glob - grep homepage: "" category: "Development" --- 代码解释工具专业版为研发团队提供项目级代码理解能力。在免费版单文件解释能力之上,专业版新增项目架构分析、批量代码文档生成、Mermaid/UML高质量可视化和API文档自动提取,帮助团队高效理解和管理大型代码库. 专业版完全兼容免费版的解释风格和配置,研发团队可从免费版无缝升级。专业版保留了免费版的类比解释和ASCII图表风格,同时增加了更强大的可视化能力. ## 核心能力 ### 1. 项目级架构分析 分析整个项目的架构,生成依赖关系图和模块结构图. > 详细代码示例已移至 `references/detail.md` **输入**: 用户提供项目级架构分析所需的指令和必要参数. **处理**: 解析项目级架构分析的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回项目级架构分析的响应数据,包含状态码、结果和日志. ### 2. 批量代码文档生成 自动为整个项目生成代码文档. **输入**: 用户提供批量代码文档生成所需的指令和必要参数. **处理**: 解析批量代码文档生成的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回批量代码文档生成的响应数据,包含状态码、结果和日志. ### 3. Mermaid 高质量可视化 ## 输入格式 | 参数名 | 类型 | 必填 | 说明 | |---|---|---|---| | input | string | 是 | 代码解释工具专业版处理的输入数据或指令 | | options | object | 否 | 附加配置选项,如模式选择、格式偏好等 | | callback_url | string | 否 | 异步处理完成后的回调通知URL | ```python class MermaidDiagramGenerator: """Mermaid图表生成器""" # ... @staticmethod def generate_flowchart(code_structure): """生成流程图""" return f"""```mermaid graph TD A[用户请求] --> B{路由器} B --> C{参数验证} C -->|通过| D[控制器] C -->|失败| E[返回错误] D --> E[服务层] E --> F[数据库] F --> G[返回结果] ```""" @staticmethod def generate_sequence_diagram(interaction_flow): """生成时序图""" return """```mermaid sequenceDiagram participant U as 用户 participant C as 客户端 participant S as 服务器 participant D as 数据库 U->>C: 发起请求 C->>S: HTTP请求 S->>D: 查询数据 D-->>S: 返回数据 S-->>C: 响应数据 C-->>U: 显示结果 ```""" # ... @staticmethod def generate_class_diagram(class_structure): """生成类图""" return """```mermaid classDiagram class User { +String name +String email +login() +logout() } # ... class Order { +String id +Date createdAt +addItem() +checkout() } # ... class Product { +String name +Number price +getInfo() } # ... User --> Order : 创建 Order --> Product : 包含 ```""" @staticmethod def generate_dependency_graph(modules): """生成依赖关系图""" lines = ["```mermaid", "graph LR"] for module, deps in modules.items(): for dep in deps: lines.append(f" {module} --> {dep}") lines.append("```") return '\n'.join(lines) ``` # ... **输入**: 用户提供Mermaid 高质量可视化所需的指令和必要参数. **处理**: 解析Mermaid 高质量可视化的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回Mermaid 高质量可视化的响应数据,包含状态码、结果和日志. # ... ### 4. 代码复杂度分析 # ... > 详细代码示例已移至 `references/detail.md` # ... **输入**: 用户提供代码复杂度分析所需的指令和必要参数. **处理**: 解析代码复杂度分析的输入参数,完成核心逻辑,返回结构化响应. **输出**: 返回代码复杂度分析的响应数据,包含状态码、结果和日志. **能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：企业级代码理解工、支持项目架构分析、批量文档生成、可视化与、API、文档输出、面向研发团队的高、级代码理解工具、UML、文档自动输出、核心能力、项目级架构分析与、依赖图、批量代码文档自动、文档自动提取与生、代码复杂度与质量、团队知识库构建等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持. # ... ## 使用场景 ### 场景一:大型项目onboarding 新成员加入团队时快速理解项目架构. # ... ```bash #!/bin/bash echo "=== 生成项目理解文档 ===" echo "1. 项目架构分析..." python3 architecture_analyzer.py ./src > architecture.json echo "2. 生成架构图..." python3 mermaid_generator.py --input architecture.json --output architecture.mmd echo "3. 生成模块文档..." python3 doc_generator.py ./src --output ./docs/ echo "4. 代码复杂度分析..." python3 complexity_analyzer.py ./src > complexity-report.json echo "5. 生成onboarding指南..." python3 generate_onboarding.py \ --architecture architecture.json \ --docs ./docs/ \ --complexity complexity-report.json \ --output ONBOARDING.md echo -e "\n项目文档已生成:" echo " - 架构图: architecture.mmd" echo " - 模块文档: ./docs/" echo " - 复杂度报告: complexity-report.json" echo " - 入门指南: ONBOARDING.md" ``` # ... ### 场景二:API文档自动生成 从代码中自动提取API文档. # ... ```bash python3 doc_generator.py \ --mode api \ --input ./src \ --output ./docs/api.md \ --format markdown python3 doc_generator.py \ --mode api \ --input ./src \ --output ./docs/openapi.json \ --format openapi ``` # ... ### 场景三:遗留系统逆向理解 对遗留系统进行逆向分析和文档化. # ... > 详细代码示例已移至 `references/detail.md` # ... ## 不适用场景 # ... 以下场景代码解释工具专业版不适合处理： # ... - 实时流数据处理 - 小规模数据手动分析 - 非结构化文本情感分析 # ... ## 触发条件 # ... 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求. # ... ## 快速开始 ### Step 1:配置分析 ```yaml version: "2.0" edition: pro analysis: architecture: true complexity: true dependencies: true documentation: generate_api_docs: true generate_module_docs: true output_format: markdown output_dir: ./docs/ visualization: use_mermaid: true diagram_types: [flowchart, sequence, class, dependency] ``` # ... ### Step 2:运行分析 ``` 请对当前项目进行完整架构分析,生成模块文档和架构图. ``` # ... ### Step 3:查看结果 - `./docs/architecture.md`:架构分析报告 - `./docs/api.md`:API文档 - `./docs/modules/`:各模块文档 - `./docs/diagrams/`:Mermaid图表 # ... # ## 配置示例 ### 企业级完整配置 ```yaml version: "2.0" edition: pro analysis: architecture: true complexity: true dependency_graph: true code_metrics: true exclude_dirs: [node_modules, .git, dist, build, vendor] documentation: generate_api_docs: true generate_module_docs: true generate_readme: true output_format: markdown output_dir: ./docs/ include_examples: true language: zh-CN visualization: use_mermaid: true use_ascii: true diagram_types: - flowchart - sequence - class - dependency - state max_diagram_nodes: 50 complexity: cyclomatic: true cognitive: true thresholds: low: 5 medium: 10 high: 20 critical: 30 knowledge_base: enabled: true output_dir: ./wiki/ auto_update: true search_index: true ``` # ... ## 最佳实践 1. **定期更新文档**:设置定时任务重新生成文档 # ... ```bash 0 2 * * 0 /opt/tools/code-doc-generator.sh ``` # ... 2. **结合Git Hook**:代码提交时自动更新相关文档 # ... ```bash python3 doc_generator.py --incremental --changed-files $(git diff --name-only HEAD~1) ``` # ... 3. **分层文档**:为不同读者生成不同详细度的文档 # ... ```yaml documentation: levels: executive: summary_only architect: architecture_focused developer: full_detail new_member: onboarding_focused ``` # ... 4. **版本化文档**:将文档纳入版本控制 # ... 5. **团队共享**:将生成的文档部署到内部Wiki # ... ## 常见问题 ### Q1:专业版如何兼容免费版? 专业版完全兼容免费版的解释风格。免费版的 `.explain-code.yml` 配置可直接使用,专业版会自动启用架构分析和文档生成功能. # ... ### Q2:大型项目分析性能如何? | 项目规模 | 文件数 | 分析时间 | 内存 | |:-----|:-----|:-----|:-----| | 小型 | <100 | <30s | <100MB | | 中型 | 100-1000 | 1-5min | 100-500MB | | 大型 | 1000-10000 | 5-20min | 500MB-2GB | | 超大型 | >10000 | 20min+ | 建议分模块 | # ... ### Q3:支持哪些文档格式? | 格式 | 用途 | 输出 | |---:|---:|---:| | Markdown | 通用文档 | .md | | HTML | 在线浏览 | .html | | OpenAPI | API规范 | .json/.yaml | | Mermaid | 图表 | .mmd | # ... ### Q4:如何集成到CI/CD? ```yaml code_documentation: stage: docs script: - python3 doc_generator.py --all --output ./docs/ artifacts: paths: - docs/ expire_in: 30 days ``` # ... ## 依赖说明 ### 运行环境 - **Agent 平台**:支持 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等) - **操作系统**:Windows / macOS / Linux - **运行时**:Python 3.8+ / Node.js 16+ # ... ### 依赖详情 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:---:|:---:|:---:|:---:| | Python 3.8+ | 运行时 | 必需 | python.org 下载 | | Mermaid CLI | 可视化工具 | 推荐 | npm install -g @mermaid-js/mermaid-cli | | mkdocs | 文档站点 | 可选 | pip install mkdocs | | LLM API | API | 必需 | 由 Agent 内置 LLM 提供 | # ... ### API Key 配置 - 基础LLM由Agent平台内置提供，Skill基于Markdown指令 - 所有代码分析在本地完成 # ... ### 可用性分类 - **分类**:MD+EXEC+PRO(专业版支持项目级分析、批量文档生成和可视化) - **说明**:企业级代码理解工具,支持架构分析、文档生成和知识库构建 - **适用规模**:中小型到大型项目 - **兼容性**:完全兼容免费版解释风格,支持平滑升级 # ... ## 错误处理 # ... | 错误场景 | 原因 | 处理方式 | |:------|------:|:------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 | # ... ## 已知限制 # ... ## 示例 # ... ### 基本用法 # ... **输入**：用户提供操作指令和必要参数 # ... **输出**：返回执行结果,包含操作状态和输出数据 # ... ```text 用户: 执行核心功能 Skill: 正在执行核心功能... Skill: 执行完成,结果如下: 操作成功 ``` # ... ## 输出格式 ```json { "success": true, "data": { "result": "代码解释工具专业版处理结果", "execution_time": "0.5s", "metadata": { "version": "1.0", "processor": "explain code pro" } }, "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"], "error": null } ``` # ...