文档生成 Agent 代码注释变技术文档

❌ 现实情况：开发者：代码写完了，文档...以后再说结果：- 新人看不懂代码- API 没人会用- 维护成本极高- 技术债务累积（然后永远没有"以后"）

✅ 用 Agent 生成：开发者：代码写完，注释写好Agent:📝 生成 API 文档📖 生成使用手册📋 生成 README结果：- 文档与代码同步- 新人快速上手- API 清晰易懂

# 项目名称> 项目简介## 快速开始```bash# 安装pip install project-name# 使用from project import mainmain()

# 示例代码

### 2.2 AI 生成 README```pythonclass READMEGenerator:    """README 生成器"""    def __init__(self):        self.template = """你是一个技术文档专家。请根据以下项目信息生成 README.md。## 项目信息- 项目名称：{project_name}- 编程语言：{language}- 主要功能：{features}- 依赖包：{dependencies}## 目录结构{directory_structure}## 要求1. 包含项目简介2. 快速开始指南3. 功能特性列表4. 使用示例5. 安装说明6. 贡献指南7. 许可证信息输出 Markdown 格式。"""    def generate(self, project_info):        """        生成 README        Args:            project_info: dict                {                    "name": "项目名",                    "language": "Python",                    "features": ["功能 1", "功能 2"],                    "dependencies": ["requests", "pandas"],                    "directory": "目录结构"                }        """        prompt = self.template.format(**project_info)        readme = query_ai(prompt)        return readme# 使用generator = READMEGenerator()project_info = {    "project_name": "my-project",    "language": "Python",    "features": ["数据处理", "可视化", "导出报告"],    "dependencies": ["pandas", "matplotlib", "openpyxl"],    "directory_structure": """my-project/├── src/│   ├── __init__.py│   ├── processor.py│   └── visualizer.py├── tests/├── README.md└── requirements.txt"""}readme = generator.generate(project_info)print(readme)

import osimport astdef extract_project_info(project_path):    """    从项目提取信息    Args:        project_path: 项目路径    """    info = {        "name": os.path.basename(project_path),        "language": "Python",        "files": [],        "functions": [],        "classes": [],        "dependencies": []    }    # 遍历项目    for root, dirs, files in os.walk(project_path):        # 跳过隐藏目录        dirs[:] = [d for d in dirs if not d.startswith('.')]        for file in files:            if file.endswith('.py'):                file_path = os.path.join(root, file)                info["files"].append(file_path)                # 解析代码                with open(file_path, 'r', encoding='utf-8') as f:                    try:                        tree = ast.parse(f.read())                        # 提取函数                        for node in ast.walk(tree):                            if isinstance(node, ast.FunctionDef):                                info["functions"].append({                                    "name": node.name,                                    "file": file_path,                                    "line": node.lineno,                                    "docstring": ast.get_docstring(node)                                })                            # 提取类                            if isinstance(node, ast.ClassDef):                                info["classes"].append({                                    "name": node.name,                                    "file": file_path,                                    "line": node.lineno,                                    "docstring": ast.get_docstring(node)                                })                    except:                        pass            # 提取依赖            if file == 'requirements.txt':                with open(os.path.join(root, file), 'r') as f:                    info["dependencies"] = [                        line.split('==')[0].strip()                        for line in f.readlines()                        if line.strip() and not line.startswith('#')                    ]    return info# 使用project_info = extract_project_info("./my-project")print(f"发现 {len(project_info['functions'])} 个函数")print(f"发现 {len(project_info['classes'])} 个类")print(f"依赖：{project_info['dependencies']}")

def generate_api_docs(project_info):    """    从 docstring 生成 API 文档    Args:        project_info: 项目信息（从 extract_project_info 获取）    """    docs = []    docs.append("# API 文档\n")    docs.append(f"项目名称：{project_info['name']}\n")    docs.append(f"生成时间：{datetime.now().strftime('%Y-%m-%d')}\n")    docs.append("---\n")    # 按文件组织    files = {}    for func in project_info['functions']:        file = func['file']        if file not in files:            files[file] = []        files[file].append(func)    for file, funcs in files.items():        docs.append(f"\n## {os.path.basename(file)}\n")        for func in funcs:            docs.append(f"\n### `{func['name']}`\n")            docs.append(f"**位置**: `{file}:{func['line']}`\n")            if func['docstring']:                docs.append(f"\n**说明**:\n{func['docstring']}\n")            else:                docs.append("\n**说明**: 无文档说明 ⚠️\n")            docs.append("\n---\n")    return "\n".join(docs)# 使用api_docs = generate_api_docs(project_info)print(api_docs[:1000])

def enhance_api_docs(function_info):    """    AI 增强 API 文档    Args:        function_info: 函数信息    """    prompt = f"""你是一个技术文档专家。请为以下函数生成详细的 API 文档。## 函数信息- 名称：{function_info['name']}- 文件：{function_info['file']}- 行号：{function_info['line']}- 文档字符串：{function_info['docstring'] or '无'}## 要求生成以下内容：1. 函数说明（功能描述）2. 参数说明（参数名、类型、说明）3. 返回值说明4. 使用示例5. 注意事项输出 Markdown 格式。"""    enhanced = query_ai(prompt)    return enhanced# 使用func = project_info['functions'][0]enhanced = enhance_api_docs(func)print(enhanced)

def generate_examples(function_info, project_info):    """    生成使用示例    Args:        function_info: 函数信息        project_info: 项目信息    """    prompt = f"""你是一个编程教师。请为以下函数生成使用示例。## 函数信息- 名称：{function_info['name']}- 文档字符串：{function_info['docstring'] or '无'}## 项目依赖{', '.join(project_info['dependencies'])}## 要求生成 3 个使用示例：1. 基础用法2. 进阶用法3. 完整示例每个示例包含：- 场景说明- 完整代码- 预期输出输出 Markdown 格式。"""    examples = query_ai(prompt)    return examples

def generate_architecture_diagram(project_info):    """    生成系统架构图（Mermaid）    Args:        project_info: 项目信息    """    # 分析模块依赖    modules = {}    for file in project_info['files']:        module_name = os.path.basename(file).replace('.py', '')        modules[module_name] = {            "functions": [],            "classes": [],            "imports": []        }    # 提取导入关系    for file in project_info['files']:        module_name = os.path.basename(file).replace('.py', '')        with open(file, 'r', encoding='utf-8') as f:            for line in f:                if line.startswith('import ') or line.startswith('from '):                    # 简化处理                    parts = line.replace('import ', '').replace('from ', '').split()                    if parts:                        imported = parts[0].split('.')[0]                        if imported in modules:                            modules[module_name]["imports"].append(imported)    # 生成 Mermaid 图    mermaid = "```mermaid\ngraph TD\n"    for module, info in modules.items():        mermaid += f"    {module}[{module}]\n"        for imp in info["imports"]:            mermaid += f"    {module} --> {imp}\n"    mermaid += "```"    return mermaid# 使用diagram = generate_architecture_diagram(project_info)print(diagram)

def generate_dataflow_diagram(functions):    """    生成数据流图    Args:        functions: 函数列表    """    # 分析函数调用关系    calls = []    for func in functions:        file_path = func['file']        with open(file_path, 'r', encoding='utf-8') as f:            lines = f.readlines()            # 查找函数调用            for i, line in enumerate(lines[func['line']-1:], func['line']):                # 简化：查找函数调用模式                import re                matches = re.findall(r'(\w+)\(', line)                for match in matches:                    if match != func['name']:                        calls.append((func['name'], match))    # 生成 Mermaid 序列图    mermaid = "```mermaid\nsequenceDiagram\n"    seen = set()    for caller, callee in calls[:20]:  # 限制数量        if (caller, callee) not in seen:            mermaid += f"    {caller}->>{callee}: 调用\n"            seen.add((caller, callee))    mermaid += "```"    return mermaid

class DocGenerator:    """文档生成器"""    def __init__(self, project_path):        self.project_path = project_path        self.project_info = None    def analyze(self):        """分析项目"""        print("🔍 分析项目...")        self.project_info = extract_project_info(self.project_path)        print(f"   文件数：{len(self.project_info['files'])}")        print(f"   函数数：{len(self.project_info['functions'])}")        print(f"   类数：{len(self.project_info['classes'])}")        print(f"   依赖数：{len(self.project_info['dependencies'])}")    def generate_all(self, output_dir="./docs"):        """生成所有文档"""        os.makedirs(output_dir, exist_ok=True)        print("\n📝 生成文档...\n")        # 1. README        print("1️⃣ 生成 README.md...")        readme_gen = READMEGenerator()        readme = readme_gen.generate(self.project_info)        with open(os.path.join(output_dir, "README.md"), 'w', encoding='utf-8') as f:            f.write(readme)        # 2. API 文档        print("2️⃣ 生成 API 文档...")        api_docs = generate_api_docs(self.project_info)        with open(os.path.join(output_dir, "API.md"), 'w', encoding='utf-8') as f:            f.write(api_docs)        # 3. 架构文档        print("3️⃣ 生成架构文档...")        architecture = "# 架构文档\n\n"        architecture += generate_architecture_diagram(self.project_info)        with open(os.path.join(output_dir, "ARCHITECTURE.md"), 'w', encoding='utf-8') as f:            f.write(architecture)        # 4. 变更日志模板        print("4️⃣ 生成变更日志模板...")        changelog = self._generate_changelog_template()        with open(os.path.join(output_dir, "CHANGELOG.md"), 'w', encoding='utf-8') as f:            f.write(changelog)        print(f"\n✅ 文档生成完成：{output_dir}/")        return {            "readme": os.path.join(output_dir, "README.md"),            "api": os.path.join(output_dir, "API.md"),            "architecture": os.path.join(output_dir, "ARCHITECTURE.md"),            "changelog": os.path.join(output_dir, "CHANGELOG.md")        }    def _generate_changelog_template(self):        """生成变更日志模板"""        return """# 变更日志## [未发布]### Added- ### Changed- ### Deprecated- ### Removed- ### Fixed- ### Security- ---## [1.0.0] - YYYY-MM-DD### Added- 初始版本"""# 使用generator = DocGenerator("./my-project")generator.analyze()files = generator.generate_all()print("\n生成的文件：")for name, path in files.items():    print(f"  - {name}: {path}")

def check_doc_quality(docs_path):    """    检查文档质量    Args:        docs_path: 文档目录    """    issues = []    # 检查必要文件    required_files = ["README.md", "API.md"]    for file in required_files:        if not os.path.exists(os.path.join(docs_path, file)):            issues.append(f"❌ 缺少必要文件：{file}")    # 检查文档内容    readme_path = os.path.join(docs_path, "README.md")    if os.path.exists(readme_path):        with open(readme_path, 'r', encoding='utf-8') as f:            content = f.read()            # 检查必要章节            required_sections = ["安装", "使用", "示例"]            for section in required_sections:                if section not in content:                    issues.append(f"⚠️ README 缺少章节：{section}")            # 检查代码示例            if "```" not in content:                issues.append("⚠️ README 缺少代码示例")            # 检查长度            if len(content) < 500:                issues.append("⚠️ README 内容过短")    return {        "passed": len(issues) == 0,        "issues": issues    }# 使用result = check_doc_quality("./docs")print(f"文档质量：{'✅ 通过' if result['passed'] else '❌ 不通过'}")for issue in result['issues']:    print(f"  {issue}")

---name: doc-generatordescription: 文档生成，代码注释变技术文档metadata:  {"openclaw": {"requires": {"bins": ["python"]}}}---# 文档生成技能## 功能从代码和注释自动生成 README、API 文档、架构文档等。## 使用示例用户：帮我的项目生成文档AI 执行：1. 分析项目结构2. 提取函数和类3. 生成 README4. 生成 API 文档5. 生成架构图6. 质量检查输出：✅ 文档生成完成生成文件：- README.md- API.md- ARCHITECTURE.md- CHANGELOG.md"""

# .github/workflows/docs.ymlname: 文档生成on:  push:    branches: [main]jobs:  generate-docs:    runs-on: ubuntu-latest    steps:    - uses: actions/checkout@v2    - name: 设置 Python      uses: actions/setup-python@v2      with:        python-version: '3.9'    - name: 安装依赖      run: |        pip install -r requirements.txt    - name: 生成文档      run: |        python scripts/generate_docs.py    - name: 提交文档      run: |        git config --local user.email "action@github.com"        git config --local user.name "GitHub Action"        git add docs/        git commit -m "docs: 自动更新文档" || echo "无变更"        git push