devops-analyzer 0.1.0__cp312-cp312-win_amd64.whl

devops/__init__.py

@@ -0,0 +1,3 @@
+"""Devops：扫描源码、提取代码块、大模型分析并生成 README。"""
+
+__version__ = "0.1.0"

devops/__main__.py

@@ -0,0 +1,3 @@
+from devops.cli import main
+
+raise SystemExit(main())

devops/analysis.py

@@ -0,0 +1,234 @@
+"""调用大模型 API 分析 extract 提取的代码块。"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from devops.extract import CodeBlock, extract_blocks_from_paths
+from devops.models import BaseChatModel, get_chat_model
+
+MAX_CODE_LINES = 80
+MAX_CHARS_PER_REQUEST = 24_000
+
+SYSTEM_PROMPT = """你是一名资深代码审查专家。
+请根据给出的代码块，输出简洁、结构化的中文分析，包含：
+1. 文件/模块职责概述
+2. 主要函数/类的作用
+3. 潜在问题或改进建议（如有）
+4. 关键依赖或调用关系（如能看出）
+
+直接输出分析正文，不要重复粘贴完整源码。"""
+
+
+def _truncate_code(code: str, max_lines: int = MAX_CODE_LINES) -> str:
+    lines = code.splitlines()
+    if len(lines) <= max_lines:
+        return code
+    head = "\n".join(lines[:max_lines])
+    return f"{head}\n# ... (省略 {len(lines) - max_lines} 行)"
+
+
+def _format_blocks_for_prompt(blocks: list[CodeBlock]) -> str:
+    parts: list[str] = []
+    for i, block in enumerate(blocks, 1):
+        title = block.name or "(anonymous)"
+        parts.append(
+            f"### 块 {i}: {block.block_type} `{title}` "
+            f"(L{block.start_line}-L{block.end_line})\n"
+            f"```{block.language}\n{_truncate_code(block.code)}\n```"
+        )
+    return "\n\n".join(parts)
+
+
+def _chat(model: BaseChatModel, prompt: str) -> str:
+    return model.chat(SYSTEM_PROMPT, prompt, temperature=0.2)
+
+
+def analyze_blocks(
+    blocks: list[CodeBlock],
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    model_name: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    """按文件分批调用大模型，并生成总览。"""
+    chat_model = get_chat_model(
+        provider=provider,
+        api_key=api_key,
+        model=model_name,
+        base_url=base_url,
+    )
+
+    if not blocks:
+        return {
+            "summary": "未提取到任何代码块，请确认目录内有支持的源码文件。",
+            "files": [],
+            "blocks_count": 0,
+        }
+
+    by_file: dict[str, list[CodeBlock]] = defaultdict(list)
+    for block in blocks:
+        by_file[block.file_path].append(block)
+
+    per_file: list[dict[str, Any]] = []
+    file_summaries: list[str] = []
+
+    for file_path, file_blocks in sorted(by_file.items()):
+        body = _format_blocks_for_prompt(file_blocks)
+        if len(body) > MAX_CHARS_PER_REQUEST:
+            body = body[:MAX_CHARS_PER_REQUEST] + "\n\n...(内容过长已截断)"
+
+        prompt = (
+            f"文件路径: {file_path}\n"
+            f"语言: {file_blocks[0].language}\n"
+            f"代码块数量: {len(file_blocks)}\n\n"
+            f"{body}"
+        )
+        analysis = _chat(chat_model, prompt)
+        per_file.append(
+            {
+                "file_path": file_path,
+                "blocks_count": len(file_blocks),
+                "analysis": analysis,
+            }
+        )
+        file_summaries.append(f"【{file_path}】\n{analysis}")
+
+    overview_prompt = (
+        "以下是多个源文件的逐项分析，请生成一份项目级总览（中文）：\n"
+        "1. 项目整体结构\n"
+        "2. 各文件之间的关系\n"
+        "3. 共性问题或架构建议\n\n"
+        + "\n\n---\n\n".join(file_summaries)
+    )
+    if len(overview_prompt) > MAX_CHARS_PER_REQUEST:
+        overview_prompt = overview_prompt[:MAX_CHARS_PER_REQUEST] + "\n...(已截断)"
+
+    summary = (
+        _chat(chat_model, overview_prompt)
+        if len(per_file) > 1
+        else per_file[0]["analysis"]
+    )
+
+    return {
+        "summary": summary,
+        "files": per_file,
+        "blocks_count": len(blocks),
+        "files_count": len(per_file),
+        "model_provider": chat_model.config.provider,
+        "model_name": chat_model.config.model,
+    }
+
+
+def analyze_files(
+    paths: list[str],
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    model_name: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    """从文件路径列表提取代码块并分析。"""
+    blocks = extract_blocks_from_paths(paths)
+    return analyze_blocks(
+        blocks,
+        provider=provider,
+        api_key=api_key,
+        model_name=model_name,
+        base_url=base_url,
+    )
+
+
+def analyze_folder(
+    folder: str,
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    model_name: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    """扫描目录、提取代码块并分析。"""
+    from devops.scan import scan_code_files
+
+    folder_path = Path(folder).resolve()
+    paths = scan_code_files(str(folder_path))
+    result = analyze_files(
+        paths,
+        provider=provider,
+        api_key=api_key,
+        model_name=model_name,
+        base_url=base_url,
+    )
+    result["folder"] = str(folder_path)
+    result["project_name"] = folder_path.name
+    result["scanned_files_count"] = len(paths)
+    result["generated_at"] = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    return result
+
+
+def render_readme(result: dict[str, Any]) -> str:
+    """将分析结果渲染为 README Markdown 正文。"""
+    project = result.get("project_name") or Path(result.get("folder", ".")).name
+    folder = result.get("folder", "")
+    generated_at = result.get("generated_at", "")
+    scanned = result.get("scanned_files_count", 0)
+    blocks = result.get("blocks_count", 0)
+    files_count = result.get("files_count", 0)
+    summary = result.get("summary", "").strip()
+    per_file: list[dict[str, Any]] = result.get("files", [])
+
+    lines: list[str] = [
+        f"# {project}",
+        "",
+        "> 本文档由代码分析工具自动生成。",
+        "",
+        "## 概览",
+        "",
+        summary or "_暂无分析内容。_",
+        "",
+        "## 统计",
+        "",
+        "| 指标 | 数值 |",
+        "| --- | --- |",
+        f"| 项目路径 | `{folder}` |",
+        f"| 扫描文件数 | {scanned} |",
+        f"| 提取代码块数 | {blocks} |",
+        f"| 已分析文件数 | {files_count} |",
+        f"| 生成时间 | {generated_at} |",
+        f"| 分析模型 | {result.get('model_provider', '')} / {result.get('model_name', '')} |",
+        "",
+    ]
+
+    if per_file:
+        lines.extend(["## 文件分析", ""])
+        for item in per_file:
+            rel = item.get("file_path", "")
+            if folder and rel.startswith(folder):
+                rel = rel[len(folder) :].lstrip("/\\")
+            count = item.get("blocks_count", 0)
+            analysis = (item.get("analysis") or "").strip()
+            lines.append(f"### `{rel}`")
+            lines.append("")
+            lines.append(f"- **代码块数量**: {count}")
+            lines.append("")
+            lines.append(analysis or "_无分析结果。_")
+            lines.append("")
+
+    lines.append("---")
+    lines.append("")
+    lines.append("*Generated by Devops code analyzer*")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def write_project_readme(folder: str, result: dict[str, Any], filename: str = "README.md") -> Path:
+    """将 Markdown 写入目标项目目录下的 README.md。"""
+    folder_path = Path(folder).resolve()
+    output_path = folder_path / filename
+    markdown = render_readme(result)
+    output_path.write_text(markdown, encoding="utf-8")
+    return output_path

devops/cli.py

@@ -0,0 +1,190 @@
+"""终端入口：devops <项目路径> | devops config"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from devops import __version__
+from devops.analysis import analyze_folder, write_project_readme
+from devops.config import config_exists
+from devops.config_cmd import run_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devops",
+        description="扫描项目源码，提取代码块，调用大模型分析并生成 README.md",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    config_parser = subparsers.add_parser(
+        "config",
+        help="配置模型 API（首次使用前必须执行）",
+    )
+    config_parser.add_argument(
+        "-s",
+        "--show",
+        action="store_true",
+        help="查看当前配置（API Key 脱敏）",
+    )
+
+    analyze_parser = subparsers.add_parser(
+        "analyze",
+        help="分析项目并生成 README",
+    )
+    analyze_parser.add_argument(
+        "project",
+        nargs="?",
+        help="要分析的项目目录路径",
+    )
+    analyze_parser.add_argument(
+        "-o",
+        "--output",
+        default="README.md",
+        help="输出 Markdown 文件名（默认: README.md）",
+    )
+    analyze_parser.add_argument(
+        "--provider",
+        choices=["openai", "zhipuai", "deepseek", "moonshot"],
+        help="覆盖配置文件中的模型提供商",
+    )
+    analyze_parser.add_argument(
+        "--model",
+        dest="model_name",
+        help="覆盖配置文件中的模型名称",
+    )
+    analyze_parser.add_argument(
+        "--api-key",
+        help="临时指定 API Key（不推荐，会留在 shell 历史）",
+    )
+    analyze_parser.add_argument(
+        "--base-url",
+        help="临时指定 API Base URL（OpenAI 兼容接口）",
+    )
+
+    # 兼容: devops /path/to/project（无子命令）
+    parser.add_argument(
+        "project_legacy",
+        nargs="?",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="README.md",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--provider",
+        choices=["openai", "zhipuai", "deepseek", "moonshot"],
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--model",
+        dest="model_name",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--api-key",
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--base-url",
+        help=argparse.SUPPRESS,
+    )
+
+    return parser
+
+
+def _run_analyze(args: argparse.Namespace) -> int:
+    folder = getattr(args, "project", None) or getattr(args, "project_legacy", None)
+    if not folder:
+        folder = input("请输入项目文件夹路径: ").strip()
+    if not folder:
+        print("错误: 未提供项目路径", file=sys.stderr)
+        return 1
+
+    if not config_exists() and not args.api_key:
+        print(
+            "错误: 尚未配置模型 API。请先运行:\n\n"
+            "  devops config\n",
+            file=sys.stderr,
+        )
+        return 1
+
+    folder_path = Path(folder).expanduser().resolve()
+    if not folder_path.is_dir():
+        print(f"错误: 不是有效目录: {folder_path}", file=sys.stderr)
+        return 1
+
+    try:
+        from devops.config import load_config
+
+        cfg = load_config(
+            provider=args.provider,
+            api_key=args.api_key,
+            model=args.model_name,
+            base_url=args.base_url,
+        )
+        print(
+            f"正在分析: {folder_path}  "
+            f"[{cfg.provider} / {cfg.model}]"
+        )
+        result = analyze_folder(
+            str(folder_path),
+            provider=args.provider,
+            api_key=args.api_key,
+            model_name=args.model_name,
+            base_url=args.base_url,
+        )
+        output = write_project_readme(
+            str(folder_path), result, filename=args.output
+        )
+        print(f"已生成: {output}")
+        return 0
+    except KeyboardInterrupt:
+        print("\n已取消", file=sys.stderr)
+        return 130
+    except Exception as exc:
+        print(f"错误: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(argv) if argv is not None else sys.argv[1:]
+
+    # devops /path/to/project -> 自动当作 analyze
+    if argv and not argv[0].startswith("-") and argv[0] not in ("config", "analyze"):
+        argv = ["analyze", *argv]
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "config":
+        extra = ["--show"] if args.show else []
+        return run_config(extra)
+
+    if args.command == "analyze" or args.project_legacy is not None:
+        return _run_analyze(args)
+
+    parser.print_help()
+    print(
+        "\n快速开始:\n"
+        "  1. devops config          # 首次配置 API\n"
+        "  2. devops /path/to/project\n",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devops/config.py

@@ -0,0 +1,159 @@
+"""用户模型 API 配置（~/.devops/config.json）。"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+CONFIG_DIR = Path.home() / ".devops"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+# provider -> (默认模型, 环境变量 API Key 备选名, 环境变量 Base URL 备选名)
+PROVIDER_DEFAULTS: dict[str, dict[str, Any]] = {
+    "openai": {
+        "model": "gpt-4o-mini",
+        "base_url": None,
+        "api_key_env": ["DEVOPS_API_KEY", "OPENAI_API_KEY", "LLM_API_KEY"],
+        "base_url_env": ["DEVOPS_BASE_URL", "OPENAI_BASE_URL", "LLM_BASE_URL"],
+        "model_env": ["DEVOPS_MODEL", "OPENAI_MODEL", "LLM_MODEL"],
+    },
+    "zhipuai": {
+        "model": "glm-4-flash",
+        "base_url": None,
+        "api_key_env": ["DEVOPS_API_KEY", "ZHIPUAI_API_KEY"],
+        "base_url_env": ["DEVOPS_BASE_URL"],
+        "model_env": ["DEVOPS_MODEL", "ZHIPUAI_MODEL"],
+    },
+    "deepseek": {
+        "model": "deepseek-chat",
+        "base_url": "https://api.deepseek.com",
+        "api_key_env": ["DEVOPS_API_KEY", "DEEPSEEK_API_KEY"],
+        "base_url_env": ["DEVOPS_BASE_URL", "DEEPSEEK_BASE_URL"],
+        "model_env": ["DEVOPS_MODEL", "DEEPSEEK_MODEL"],
+    },
+    "moonshot": {
+        "model": "moonshot-v1-8k",
+        "base_url": "https://api.moonshot.cn/v1",
+        "api_key_env": ["DEVOPS_API_KEY", "MOONSHOT_API_KEY"],
+        "base_url_env": ["DEVOPS_BASE_URL", "MOONSHOT_BASE_URL"],
+        "model_env": ["DEVOPS_MODEL", "MOONSHOT_MODEL"],
+    },
+}
+
+
+@dataclass
+class ModelConfig:
+    provider: str
+    api_key: str
+    model: str
+    base_url: Optional[str] = None
+
+    def masked(self) -> dict[str, Any]:
+        key = self.api_key
+        if len(key) > 8:
+            masked_key = f"{key[:4]}...{key[-4:]}"
+        else:
+            masked_key = "****"
+        return {
+            "provider": self.provider,
+            "api_key": masked_key,
+            "model": self.model,
+            "base_url": self.base_url or "(默认)",
+        }
+
+
+def _first_env(names: list[str]) -> Optional[str]:
+    for name in names:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return None
+
+
+def list_providers() -> list[str]:
+    return list(PROVIDER_DEFAULTS.keys())
+
+
+def config_exists() -> bool:
+    return CONFIG_FILE.is_file()
+
+
+def load_config_file() -> Optional[dict[str, Any]]:
+    if not CONFIG_FILE.is_file():
+        return None
+    try:
+        return json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_config(config: ModelConfig) -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = asdict(config)
+    CONFIG_FILE.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    CONFIG_FILE.chmod(0o600)
+    return CONFIG_FILE
+
+
+def load_config(
+    *,
+    provider: Optional[str] = None,
+    api_key: Optional[str] = None,
+    model: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> ModelConfig:
+    """加载配置：CLI 参数 > 配置文件 > 环境变量。"""
+    file_data = load_config_file() or {}
+
+    resolved_provider = (
+        provider
+        or os.environ.get("DEVOPS_PROVIDER", "").strip()
+        or file_data.get("provider", "").strip()
+        or "openai"
+    ).lower()
+
+    if resolved_provider not in PROVIDER_DEFAULTS:
+        supported = ", ".join(list_providers())
+        raise ValueError(f"不支持的模型提供商: {resolved_provider}，可选: {supported}")
+
+    defaults = PROVIDER_DEFAULTS[resolved_provider]
+
+    resolved_api_key = api_key or file_data.get("api_key", "").strip()
+    if not resolved_api_key:
+        resolved_api_key = _first_env(defaults["api_key_env"]) or ""
+    if not resolved_api_key:
+        raise RuntimeError(
+            "未配置 API Key。请先运行: devops config\n"
+            f"或设置环境变量: {defaults['api_key_env'][0]}"
+        )
+
+    resolved_model = (
+        model
+        or file_data.get("model", "").strip()
+        or _first_env(defaults["model_env"])
+        or defaults["model"]
+    )
+
+    resolved_base_url = base_url
+    if resolved_base_url is None:
+        file_base = file_data.get("base_url")
+        resolved_base_url = (
+            file_base.strip() if isinstance(file_base, str) and file_base.strip() else None
+        )
+    if resolved_base_url is None:
+        resolved_base_url = _first_env(defaults["base_url_env"])
+    if resolved_base_url is None:
+        resolved_base_url = defaults["base_url"]
+
+    return ModelConfig(
+        provider=resolved_provider,
+        api_key=resolved_api_key,
+        model=resolved_model,
+        base_url=resolved_base_url,
+    )

devops/config_cmd.py

@@ -0,0 +1,88 @@
+"""devops config 子命令：交互式配置模型 API。"""
+
+from __future__ import annotations
+
+import getpass
+import sys
+
+from devops.config import (
+    CONFIG_FILE,
+    ModelConfig,
+    list_providers,
+    load_config,
+    save_config,
+)
+
+
+def _prompt(label: str, default: str = "") -> str:
+    if default:
+        value = input(f"{label} [{default}]: ").strip()
+        return value or default
+    return input(f"{label}: ").strip()
+
+
+def run_config_show() -> int:
+    try:
+        config = load_config()
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        print(f"\n配置文件路径: {CONFIG_FILE}", file=sys.stderr)
+        return 1
+
+    print("当前模型配置:")
+    for key, value in config.masked().items():
+        print(f"  {key}: {value}")
+    print(f"\n配置文件: {CONFIG_FILE}")
+    return 0
+
+
+def run_config_interactive() -> int:
+    providers = list_providers()
+    print("支持的模型提供商:")
+    for i, name in enumerate(providers, 1):
+        print(f"  {i}. {name}")
+    print()
+
+    provider = _prompt("提供商 (openai/zhipuai/deepseek/moonshot)", "openai").lower()
+    if provider not in providers:
+        print(f"错误: 未知提供商 {provider}", file=sys.stderr)
+        return 1
+
+    api_key = getpass.getpass("API Key (输入不可见): ").strip()
+    if not api_key:
+        print("错误: API Key 不能为空", file=sys.stderr)
+        return 1
+
+    default_models = {
+        "openai": "gpt-4o-mini",
+        "zhipuai": "glm-4-flash",
+        "deepseek": "deepseek-chat",
+        "moonshot": "moonshot-v1-8k",
+    }
+    model = _prompt("模型名称", default_models.get(provider, "gpt-4o-mini"))
+
+    base_url = ""
+    if provider in ("openai",):
+        base_url = _prompt("Base URL (留空=官方 OpenAI)", "")
+    elif provider in ("deepseek", "moonshot"):
+        from devops.config import PROVIDER_DEFAULTS
+        default_url = PROVIDER_DEFAULTS[provider]["base_url"] or ""
+        base_url = _prompt("Base URL", default_url)
+
+    config = ModelConfig(
+        provider=provider,
+        api_key=api_key,
+        model=model,
+        base_url=base_url or None,
+    )
+    path = save_config(config)
+    print(f"\n配置已保存: {path}")
+    print("现在可以运行: devops /path/to/your/project")
+    return 0
+
+
+def run_config(argv: list[str] | None = None) -> int:
+    args = argv or []
+    if "--show" in args or "-s" in args:
+        return run_config_show()
+    return run_config_interactive()

devops/extract.py

@@ -0,0 +1,215 @@
+"""用 Tree-sitter 从源码文件中提取代码块。"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+from tree_sitter import Node, Tree
+from tree_sitter_languages import get_parser
+
+from devops.scan import scan_code_files
+
+EXT_TO_LANGUAGE: dict[str, str] = {
+    ".py": "python",
+    ".pyw": "python",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+    ".h": "cpp",
+    ".hh": "cpp",
+    ".hpp": "cpp",
+    ".hxx": "cpp",
+    ".c": "c",
+    ".java": "java",
+    ".go": "go",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".php": "php",
+    ".cs": "c_sharp",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".scala": "scala",
+    ".sh": "bash",
+}
+
+LANGUAGE_NODE_TYPES: dict[str, tuple[str, ...]] = {
+    "python": ("function_definition", "async_function_definition", "class_definition"),
+    "javascript": (
+        "function_declaration",
+        "class_declaration",
+        "method_definition",
+    ),
+    "typescript": (
+        "function_declaration",
+        "class_declaration",
+        "method_definition",
+        "interface_declaration",
+    ),
+    "cpp": ("function_definition", "class_specifier", "struct_specifier", "namespace_definition"),
+    "c": ("function_definition", "struct_specifier"),
+    "java": ("method_declaration", "class_declaration", "interface_declaration"),
+    "go": ("function_declaration", "method_declaration", "type_declaration"),
+    "rust": ("function_item", "impl_item", "struct_item", "enum_item", "trait_item"),
+    "ruby": ("method", "class", "module"),
+    "php": ("function_definition", "method_declaration", "class_declaration"),
+    "c_sharp": ("method_declaration", "class_declaration", "interface_declaration"),
+    "kotlin": ("function_declaration", "class_declaration"),
+    "scala": ("function_definition", "class_definition", "object_definition"),
+    "bash": ("function_definition",),
+    "swift": ("function_declaration", "class_declaration", "struct_declaration"),
+}
+
+_parser_cache: dict[str, object] = {}
+
+
+@dataclass
+class CodeBlock:
+    file_path: str
+    language: str
+    block_type: str
+    name: str
+    start_line: int
+    end_line: int
+    code: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def language_for_path(path: str | Path) -> Optional[str]:
+    return EXT_TO_LANGUAGE.get(Path(path).suffix.lower())
+
+
+def _get_parser(language: str):
+    if language not in _parser_cache:
+        _parser_cache[language] = get_parser(language)
+    return _parser_cache[language]
+
+
+def _read_source(path: Path) -> Optional[bytes]:
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def _line_number(source: bytes, byte_offset: int) -> int:
+    return source[:byte_offset].count(b"\n") + 1
+
+
+def _declarator_name(node: Node) -> str:
+    inner = node.child_by_field_name("declarator")
+    if inner is not None:
+        return _declarator_name(inner)
+    if node.type in ("identifier", "field_identifier", "operator_name"):
+        return node.text.decode("utf-8", errors="replace")
+    for child in node.children:
+        name = _declarator_name(child)
+        if name:
+            return name
+    return ""
+
+
+def _node_name(node: Node, language: str) -> str:
+    name_node = node.child_by_field_name("name")
+    if name_node is not None:
+        return name_node.text.decode("utf-8", errors="replace")
+
+    if language == "python" and node.type == "decorated_definition":
+        for child in node.children:
+            if child.type in ("function_definition", "class_definition"):
+                return _node_name(child, language)
+
+    if language == "cpp" and node.type == "function_definition":
+        decl = node.child_by_field_name("declarator")
+        if decl is not None:
+            return _declarator_name(decl)
+
+    for child in node.children:
+        if child.type in ("identifier", "type_identifier", "property_identifier"):
+            text = child.text.decode("utf-8", errors="replace")
+            if text not in ("def", "class", "fn", "function"):
+                return text
+    return ""
+
+
+def _walk_nodes(node: Node) -> Iterator[Node]:
+    yield node
+    for child in node.children:
+        yield from _walk_nodes(child)
+
+
+def _extract_from_tree(
+    tree: Tree,
+    source: bytes,
+    file_path: str,
+    language: str,
+) -> list[CodeBlock]:
+    target_types = set(LANGUAGE_NODE_TYPES.get(language, ()))
+    if not target_types:
+        return []
+
+    blocks: list[CodeBlock] = []
+    seen: set[tuple[int, int]] = set()
+
+    for node in _walk_nodes(tree.root_node):
+        if node.type not in target_types:
+            continue
+        key = (node.start_byte, node.end_byte)
+        if key in seen:
+            continue
+        seen.add(key)
+
+        blocks.append(
+            CodeBlock(
+                file_path=file_path,
+                language=language,
+                block_type=node.type,
+                name=_node_name(node, language),
+                start_line=_line_number(source, node.start_byte),
+                end_line=_line_number(source, node.end_byte),
+                code=source[node.start_byte : node.end_byte].decode(
+                    "utf-8", errors="replace"
+                ),
+            )
+        )
+
+    blocks.sort(key=lambda b: (b.start_line, b.name))
+    return blocks
+
+
+def extract_blocks_from_file(path: str | Path) -> list[CodeBlock]:
+    p = Path(path)
+    language = language_for_path(p)
+    if language is None:
+        return []
+
+    source = _read_source(p)
+    if source is None:
+        return []
+
+    try:
+        tree = _get_parser(language).parse(source)
+    except Exception:
+        return []
+
+    return _extract_from_tree(tree, source, str(p.resolve()), language)
+
+
+def extract_blocks_from_paths(paths: list[str]) -> list[CodeBlock]:
+    blocks: list[CodeBlock] = []
+    for path in paths:
+        blocks.extend(extract_blocks_from_file(path))
+    return blocks
+
+
+def extract_blocks_from_folder(folder: str) -> list[CodeBlock]:
+    return extract_blocks_from_paths(scan_code_files(folder))

devops/models/__init__.py

@@ -0,0 +1,50 @@
+"""多模型提供商统一入口。"""
+
+from __future__ import annotations
+
+from devops.config import ModelConfig, list_providers
+from devops.models.base import BaseChatModel
+from devops.models.openai import OpenAIChatModel
+from devops.models.zhipuai import ZhipuAIChatModel
+
+# deepseek / moonshot 使用 OpenAI 兼容协议
+_OPENAI_COMPAT = {"openai", "deepseek", "moonshot"}
+
+
+def create_chat_model(config: ModelConfig) -> BaseChatModel:
+  provider = config.provider.lower()
+  if provider in _OPENAI_COMPAT:
+    return OpenAIChatModel(config)
+  if provider == "zhipuai":
+    return ZhipuAIChatModel(config)
+  raise ValueError(
+    f"不支持的提供商: {provider}，可选: {', '.join(list_providers())}"
+  )
+
+
+def get_chat_model(
+  *,
+  provider: str | None = None,
+  api_key: str | None = None,
+  model: str | None = None,
+  base_url: str | None = None,
+) -> BaseChatModel:
+  from devops.config import load_config
+
+  config = load_config(
+    provider=provider,
+    api_key=api_key,
+    model=model,
+    base_url=base_url,
+  )
+  return create_chat_model(config)
+
+
+__all__ = [
+  "BaseChatModel",
+  "OpenAIChatModel",
+  "ZhipuAIChatModel",
+  "create_chat_model",
+  "get_chat_model",
+  "list_providers",
+]

devops/models/base.py

@@ -0,0 +1,16 @@
+"""大模型调用抽象基类。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from devops.config import ModelConfig
+
+
+class BaseChatModel(ABC):
+    def __init__(self, config: ModelConfig) -> None:
+        self.config = config
+
+    @abstractmethod
+    def chat(self, system: str, user: str, *, temperature: float = 0.2) -> str:
+        raise NotImplementedError

devops/models/openai.py

@@ -0,0 +1,30 @@
+"""OpenAI 及兼容 OpenAI 协议的服务（DeepSeek、Moonshot、本地 Ollama 等）。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from devops.config import ModelConfig
+from devops.models.base import BaseChatModel
+
+
+class OpenAIChatModel(BaseChatModel):
+    def __init__(self, config: ModelConfig) -> None:
+        super().__init__(config)
+        from openai import OpenAI
+
+        kwargs: dict[str, Any] = {"api_key": config.api_key}
+        if config.base_url:
+            kwargs["base_url"] = config.base_url.rstrip("/")
+        self._client = OpenAI(**kwargs)
+
+    def chat(self, system: str, user: str, *, temperature: float = 0.2) -> str:
+        response = self._client.chat.completions.create(
+            model=self.config.model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            temperature=temperature,
+        )
+        return (response.choices[0].message.content or "").strip()

devops/models/zhipuai.py

@@ -0,0 +1,28 @@
+"""智谱 AI (GLM) 模型。"""
+
+from __future__ import annotations
+
+from devops.config import ModelConfig
+from devops.models.base import BaseChatModel
+
+
+class ZhipuAIChatModel(BaseChatModel):
+    def __init__(self, config: ModelConfig) -> None:
+        super().__init__(config)
+        try:
+            from zhipuai import ZhipuAI
+        except ImportError as exc:
+            raise ImportError("使用智谱 AI 需要安装: pip install zhipuai") from exc
+
+        self._client = ZhipuAI(api_key=config.api_key)
+
+    def chat(self, system: str, user: str, *, temperature: float = 0.2) -> str:
+        response = self._client.chat.completions.create(
+            model=self.config.model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            temperature=temperature,
+        )
+        return (response.choices[0].message.content or "").strip()

devops/scan/__init__.py

@@ -0,0 +1,3 @@
+from devops.scan.scan_native import scan_code_files
+
+__all__ = ["scan_code_files"]

devops/scan/scan.cpp

@@ -0,0 +1,121 @@
+#include "scan.h"
+
+#include <algorithm>
+#include <cctype>
+#include <filesystem>
+#include <string>
+#include <unordered_set>
+#include <vector>
+
+namespace fs = std::filesystem;
+
+namespace {
+
+// Python 传入 UTF-8 路径，各平台统一用 u8path 解析
+fs::path toPath(const std::string& utf8Path) {
+    return fs::u8path(utf8Path);
+}
+
+// 返回统一使用正斜杠的路径，便于跨平台在 Python 中使用
+std::string toGenericPath(const fs::path& path) {
+    return path.generic_string();
+}
+
+bool nameEquals(const std::string& a, const std::string& b) {
+#if defined(_WIN32)
+    if (a.size() != b.size()) {
+        return false;
+    }
+    for (size_t i = 0; i < a.size(); ++i) {
+        if (std::tolower(static_cast<unsigned char>(a[i])) !=
+            std::tolower(static_cast<unsigned char>(b[i]))) {
+            return false;
+        }
+    }
+    return true;
+#else
+    return a == b;
+#endif
+}
+
+bool shouldSkipDir(const fs::path& dir) {
+    static const char* skip[] = {
+        ".git", ".svn", ".hg",
+        "node_modules", "vendor",
+        "build", "dist", "out", "target", "bin", "obj",
+        ".idea", ".vscode", ".vs",
+        "__pycache__", ".next", ".venv", "venv", "env",
+        // Windows / MSVC 常见输出目录
+        "Debug", "Release", "x64", "Win32", "CMakeFiles",
+    };
+
+    const std::string name = dir.filename().string();
+    for (const char* entry : skip) {
+        if (nameEquals(name, entry)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+bool isCodeFile(const fs::path& path) {
+    static const std::unordered_set<std::string> exts = {
+        ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp",
+        ".py", ".js", ".ts", ".tsx", ".jsx",
+        ".java", ".go", ".rs", ".rb", ".php",
+        ".cs", ".swift", ".m", ".mm",
+        ".sh", ".sql", ".html", ".css",
+        ".vue", ".kt", ".scala",
+    };
+
+    std::string ext = path.extension().string();
+    for (char& c : ext) {
+        c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    }
+    return !ext.empty() && exts.count(ext) > 0;
+}
+
+}  // namespace
+
+std::vector<std::string> scanCodeFiles(const std::string& folderPath) {
+    std::vector<std::string> result;
+    std::error_code ec;
+
+    const fs::path root = toPath(folderPath);
+    if (!fs::exists(root, ec) || !fs::is_directory(root, ec)) {
+        return result;
+    }
+
+    fs::recursive_directory_iterator it(
+        root,
+        fs::directory_options::skip_permission_denied,
+        ec);
+    const fs::recursive_directory_iterator end;
+
+    for (; it != end; it.increment(ec)) {
+        if (ec) {
+            ec.clear();
+            continue;
+        }
+
+        const fs::directory_entry& entry = *it;
+        if (entry.is_directory(ec)) {
+            if (shouldSkipDir(entry.path())) {
+                it.disable_recursion_pending();
+            }
+            continue;
+        }
+
+        if (entry.is_regular_file(ec) && isCodeFile(entry.path())) {
+            fs::path resolved = fs::weakly_canonical(entry.path(), ec);
+            if (ec) {
+                resolved = entry.path();
+                ec.clear();
+            }
+            result.push_back(toGenericPath(resolved));
+        }
+    }
+
+    std::sort(result.begin(), result.end());
+    return result;
+}

devops/scan/scan.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+// 递归扫描文件夹，返回其中所有代码文件的路径（已排序）
+std::vector<std::string> scanCodeFiles(const std::string& folderPath);

devops/scan/scan_bindings.cpp

@@ -0,0 +1,15 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include "scan.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(scan_native, m) {
+    m.doc() = "Scan a project folder and return code file paths";
+    m.def(
+        "scan_code_files",
+        &scanCodeFiles,
+        py::arg("folder_path"),
+        "Recursively list all code file paths under folder_path.");
+}

devops_analyzer-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: devops-analyzer
+Version: 0.1.0
+Summary: 扫描源码、提取代码块、大模型分析并生成 README.md
+Author: ZHUHK
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/example/devops-analyzer
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter<0.22,>=0.21.0
+Requires-Dist: tree-sitter-languages>=1.10.0
+Requires-Dist: openai>=1.40.0
+Provides-Extra: zhipuai
+Requires-Dist: zhipuai>=2.0.0; extra == "zhipuai"
+Provides-Extra: all
+Requires-Dist: zhipuai>=2.0.0; extra == "all"
+Provides-Extra: build
+Requires-Dist: build>=1.2.0; extra == "build"
+Dynamic: license-file
+
+# Devops Analyzer
+
+扫描项目源码 → Tree-sitter 提取代码块 → 大模型分析 → 生成 `README.md`。
+
+## 安装
+
+```bash
+cd /path/to/Devops
+conda activate devops
+pip install -e .
+
+# 使用智谱 AI 时额外安装
+pip install zhipuai
+```
+
+## 首次使用：配置模型 API
+
+**必须先配置你自己的 API Key**，再分析项目：
+
+```bash
+devops config
+```
+
+按提示选择提供商、输入 API Key 和模型名称。配置保存在 `~/.devops/config.json`（仅当前用户可读）。
+
+查看当前配置（Key 脱敏显示）：
+
+```bash
+devops config --show
+```
+
+## 支持的模型提供商
+
+| 提供商 | `provider` 值 | 默认模型 | 说明 |
+|--------|---------------|----------|------|
+| OpenAI | `openai` | `gpt-4o-mini` | 官方或自定义 Base URL |
+| 智谱 AI | `zhipuai` | `glm-4-flash` | 需 `pip install zhipuai` |
+| DeepSeek | `deepseek` | `deepseek-chat` | OpenAI 兼容协议 |
+| Moonshot | `moonshot` | `moonshot-v1-8k` | OpenAI 兼容协议 |
+
+也可用环境变量覆盖（优先级低于配置文件）：
+
+```bash
+export DEVOPS_PROVIDER=openai
+export DEVOPS_API_KEY=sk-...
+export DEVOPS_MODEL=gpt-4o-mini
+export DEVOPS_BASE_URL=https://api.openai.com/v1   # 可选
+```
+
+## 分析项目
+
+```bash
+devops /path/to/your/project
+
+# 或显式子命令
+devops analyze /path/to/your/project
+
+# 指定输出文件
+devops /path/to/project -o README.md
+
+# 临时覆盖模型（不改配置文件）
+devops /path/to/project --provider deepseek --model deepseek-chat
+```
+
+## 命令一览
+
+```bash
+devops config              # 交互式配置 API
+devops config --show       # 查看配置
+devops <项目路径>          # 分析并生成 README.md
+devops analyze <项目路径>
+devops --help
+devops --version
+```

devops_analyzer-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+devops/__init__.py,sha256=efMmj0qlEd8t459QNAdKbZFaWNurNByvxNdZew1I2sI,109
+devops/__main__.py,sha256=CqvNIJzp4XxyAaK_QKk5XJzwkYGN6hhlbEm76hbMetE,57
+devops/analysis.py,sha256=yVHV5HRbs6w-cKEhbyFSlUbXv7I-uqmzRxzDGTjOqJg,7745
+devops/cli.py,sha256=uVYJVFGn4QnZSf24i92c3zDiZwG9MKGsk0xevxOvAuY,5422
+devops/config.py,sha256=hOhQrkQHGFxfroik9fomkCpWgDosmBtWBOZEJNSd8XI,4961
+devops/config_cmd.py,sha256=tebWZmX9qq9lz2tuoqgiwHqAPW8BrVHaVDfju80kgtU,2577
+devops/extract.py,sha256=JufuM_3OjQFM4POkQ2nPSiMUBcyJLVirGej_zdZ9Ddo,6450
+devops/models/__init__.py,sha256=pAaRPi5Uj1qrX6KpaJSpgpzckeoYZFhsOIbsepoxngY,1261
+devops/models/base.py,sha256=3vhle8dDC0_8LujFuPOxNQiN0MVy7V9q1I7XKQC5IYM,410
+devops/models/openai.py,sha256=gkrNq-7zRcD3cced0ZiW_dsxirt6lREDQMLZeNSIEAw,1052
+devops/models/zhipuai.py,sha256=4vAyS9AMl2RXczvt8dytHm1cmS1ZACF4J25qWmAyzYo,976
+devops/scan/__init__.py,sha256=dwVWZaan-saFaPY6KIre1-bUrmTvmSfq4z5bzCjr8VY,86
+devops/scan/scan.cpp,sha256=aMzImUcvqFldWYRHa7H-GH5h3BZtZAfGaVlOG4u6HTw,3376
+devops/scan/scan.h,sha256=eCrTNjqxu6jlySNnpC7eyMIknqLkUTHFuc234_HXzoY,211
+devops/scan/scan_bindings.cpp,sha256=q139NtDIy07v78Pq4MMt7BX_-QT4_ob8wn37bw0tNYk,382
+devops/scan/scan_native.cp312-win_amd64.pyd,sha256=kXolVgXTnD0l4QG_uUuaW-otpNZtXzPv4_YzPLUgfNI,181760
+devops_analyzer-0.1.0.dist-info/licenses/LICENSE,sha256=MBvA7WLDGW82KmxFZLLfA7h0VS_jK5cRBq8crggZlDk,1083
+devops_analyzer-0.1.0.dist-info/METADATA,sha256=aYhrwciUIvkOZLSW17CxhKB7h1UuAedeCdZnFTvmFHA,2515
+devops_analyzer-0.1.0.dist-info/WHEEL,sha256=rR5QfsWcZl3mra5AmSD7Fd0dzQxZ3lHCpDo70IkfDK4,101
+devops_analyzer-0.1.0.dist-info/entry_points.txt,sha256=6kfJgW01wJybJetKc0qeIpHlldoiZn4g52Sd8B48p_U,43
+devops_analyzer-0.1.0.dist-info/top_level.txt,sha256=qcdbAA3CortK6Ce66IZXkIMR65YMclmS95JKCGGgTv0,7
+devops_analyzer-0.1.0.dist-info/RECORD,,

devops_analyzer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: false
+Tag: cp312-cp312-win_amd64
+

devops_analyzer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devops = devops.cli:main

devops_analyzer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZHUHK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devops_analyzer-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devops