一、Skill 介绍
背景
在日常开发中，技术文档的编写往往是一个繁琐且耗时的过程。开发者需要花费大量时间来整理思路、构建结构、绘制图表，这不仅影响开发效率，也可能导致文档质量参差不齐。
使用场景
- 项目架构设计：快速生成架构文档，包含模块关系和流程图
- 功能实现说明：详细记录功能实现逻辑和关键代码
- 技术方案评审：为技术评审提供清晰、结构化的文档支持
- 团队知识共享：创建标准化的技术文档，方便团队成员理解和协作
二、具体使用方法
安装步骤
-
下载
visual-docs-master目录或克隆仓库 -
进入
visual-docs-master目录 -
无需安装额外依赖（基础功能无需外部库）
使用方式
1. 代码调用
from main import generate_documentation, save_documentation
# 定义文档主题和上下文
topic = "新功能实现"
context = {
"background": "描述问题和目标",
"core_change": "总结方法的根本转变",
"modules": ["模块1", "模块2", "模块3"],
"implementation_steps": ["步骤1", "步骤2", "步骤3"],
"code_snippets": ["def example():\n return True"],
"files": ["file1.py", "file2.py"]
}
# 生成文档
doc_content = generate_documentation(topic, context)
# 保存到文件
save_documentation(topic, doc_content)
2. 命令行使用
直接运行脚本生成示例文档：
python main.py
三、Skill 编写思路
核心设计理念
- 可视化优先：使用 Mermaid 图表直观展示流程和关系
- 结构清晰：采用一致的标题和层级结构
- 代码上下文：只包含最相关的代码片段，而非整个文件
- 职责明确：清晰定义各个模块的职责
技术实现要点
- 模块化设计：将文档生成拆分为多个功能函数
- 模板化输出：使用固定模板确保文档结构一致性
- 灵活配置：通过上下文参数支持不同场景的文档生成
- 自动保存：提供文档保存功能，方便后续使用
四、效果展示
使用前
- 文档编写耗时：约 2-3 小时/份
- 文档质量：取决于编写者经验，质量参差不齐
- 图表绘制：需要单独使用绘图工具，过程繁琐
使用后
- 文档编写耗时：约 10-15 分钟/份
- 文档质量：标准化结构，内容完整清晰
- 图表绘制：自动生成 Mermaid 图表，美观且专业
示例输出
运行 python main.py 后，会在 docs 目录生成示例文档，包含：
-
完整的文档结构
-
自动生成的 Mermaid 流程图
-
标准化的代码片段展示
-
清晰的文件清单