acm-cli 0.1.0__py3-none-any.whl

acm/git.py

@@ -0,0 +1,193 @@
+"""Git 操作封装：仓库检测、staged 文件、diff 获取、智能截断、commit 执行。"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+
+class GitError(Exception):
+    """Git 操作相关错误。"""
+
+
+# ---------------------------------------------------------------------------
+# 数据类
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FileChange:
+    """单个文件的变更信息。"""
+    path: str
+    status: str          # A/M/D/R 等
+    insertions: int = 0
+    deletions: int = 0
+
+
+@dataclass
+class DiffResult:
+    """diff 结果。"""
+    files: list[FileChange]
+    diff_content: str     # 完整或截断后的 diff
+    stat_summary: str     # git diff --stat 的输出
+    truncated: bool       # 是否被截断
+
+
+# ---------------------------------------------------------------------------
+# 底层 Git 命令执行
+# ---------------------------------------------------------------------------
+
+def _run_git(*args: str, cwd: str | None = None) -> str:
+    """执行 git 命令并返回 stdout。失败时抛出 GitError。"""
+    cmd = ["git"] + list(args)
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=30,
+        )
+    except FileNotFoundError:
+        raise GitError("未找到 git 命令，请确保已安装 Git")
+    except subprocess.TimeoutExpired:
+        raise GitError(f"git 命令超时: {' '.join(cmd)}")
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        raise GitError(f"git 命令执行失败: {stderr}")
+
+    return result.stdout
+
+
+# ---------------------------------------------------------------------------
+# 公开 API
+# ---------------------------------------------------------------------------
+
+def is_git_repo(cwd: str | None = None) -> bool:
+    """检测当前目录是否为 Git 仓库。"""
+    try:
+        _run_git("rev-parse", "--is-inside-work-tree", cwd=cwd)
+        return True
+    except GitError:
+        return False
+
+
+def has_unstaged_changes(cwd: str | None = None) -> bool:
+    """检测工作区是否有未暂存的修改。"""
+    output = _run_git("diff", "--name-only", cwd=cwd)
+    return bool(output.strip())
+
+
+def has_untracked_files(cwd: str | None = None) -> bool:
+    """检测是否有未跟踪的新文件。"""
+    output = _run_git("ls-files", "--others", "--exclude-standard", cwd=cwd)
+    return bool(output.strip())
+
+
+def add_all(cwd: str | None = None) -> str:
+    """执行 git add -A，将所有变更添加到暂存区。"""
+    return _run_git("add", "-A", cwd=cwd)
+
+
+def get_staged_files(cwd: str | None = None) -> list[FileChange]:
+    """获取暂存区的文件列表及变更状态。"""
+    # --name-status 输出格式: "M\tfile.py"
+    output = _run_git("diff", "--cached", "--name-status", cwd=cwd)
+    files = []
+    for line in output.strip().splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t", 1)
+        if len(parts) == 2:
+            status, path = parts
+            files.append(FileChange(path=path, status=status))
+    return files
+
+
+def get_staged_diff(cwd: str | None = None) -> str:
+    """获取暂存区的完整 diff 内容。"""
+    return _run_git("diff", "--cached", cwd=cwd)
+
+
+def get_staged_stat(cwd: str | None = None) -> str:
+    """获取暂存区的 stat 摘要。"""
+    return _run_git("diff", "--cached", "--stat", cwd=cwd)
+
+
+def get_staged_numstat(cwd: str | None = None) -> list[FileChange]:
+    """获取暂存区每个文件的增删行数。"""
+    output = _run_git("diff", "--cached", "--numstat", cwd=cwd)
+    files = []
+    for line in output.strip().splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        if len(parts) == 3:
+            ins_str, del_str, path = parts
+            ins = int(ins_str) if ins_str != "-" else 0
+            dels = int(del_str) if del_str != "-" else 0
+            files.append(FileChange(path=path, status="M", insertions=ins, deletions=dels))
+    return files
+
+
+def build_diff_result(max_diff_lines: int = 500, cwd: str | None = None) -> DiffResult:
+    """构建 diff 结果，超过阈值时进行智能截断。
+
+    Args:
+        max_diff_lines: diff 行数阈值，超过则截断。
+        cwd: 工作目录。
+
+    Returns:
+        DiffResult 包含文件列表、diff 内容、stat 摘要、是否截断。
+    """
+    files = get_staged_files(cwd=cwd)
+    stat_summary = get_staged_stat(cwd=cwd)
+    full_diff = get_staged_diff(cwd=cwd)
+
+    # 合并增删行数信息
+    numstat_files = get_staged_numstat(cwd=cwd)
+    numstat_map = {f.path: f for f in numstat_files}
+    for f in files:
+        if f.path in numstat_map:
+            f.insertions = numstat_map[f.path].insertions
+            f.deletions = numstat_map[f.path].deletions
+
+    diff_lines = full_diff.splitlines()
+    truncated = len(diff_lines) > max_diff_lines
+
+    if truncated:
+        # 截断 diff，保留前 max_diff_lines 行 + stat 摘要
+        truncated_diff = "\n".join(diff_lines[:max_diff_lines])
+        diff_content = (
+            f"{truncated_diff}\n\n"
+            f"... (diff 内容过长，已截断，共 {len(diff_lines)} 行) ...\n\n"
+            f"完整文件变更摘要:\n{stat_summary}"
+        )
+    else:
+        diff_content = full_diff
+
+    return DiffResult(
+        files=files,
+        diff_content=diff_content,
+        stat_summary=stat_summary,
+        truncated=truncated,
+    )
+
+
+def commit(message: str, cwd: str | None = None) -> str:
+    """执行 git commit。返回 git 输出。"""
+    return _run_git("commit", "-m", message, cwd=cwd)
+
+
+def commit_files(files: list[str], message: str, cwd: str | None = None) -> str:
+    """对指定文件执行 git commit（用于智能拆分提交）。
+
+    先 reset HEAD 取消全部暂存，再 add 指定文件，最后 commit。
+    """
+    # 先取消所有暂存
+    _run_git("reset", "HEAD", cwd=cwd)
+    # 暂存指定文件
+    _run_git("add", "--", *files, cwd=cwd)
+    # 提交
+    result = _run_git("commit", "-m", message, cwd=cwd)
+    return result

acm/llm/__init__.py

@@ -0,0 +1,25 @@
+"""LLM 提供商模块：工厂函数用于根据配置创建提供商实例。"""
+
+from __future__ import annotations
+
+from acm.config import ACMConfig
+from acm.llm.base import LLMBase
+from acm.llm.openai_compat import OpenAICompatProvider
+from acm.llm.qwen import QwenProvider
+
+
+def create_llm(config: ACMConfig) -> LLMBase:
+    """根据配置创建 LLM 提供商实例。"""
+    provider = config.llm.provider.lower()
+    api_key = config.llm.api_key
+    model = config.llm.model
+    base_url = config.llm.base_url
+
+    if provider == "qwen":
+        return QwenProvider(api_key=api_key, model=model, base_url=base_url)
+
+    # 其他未知提供商均视为 OpenAI 兼容接口
+    return OpenAICompatProvider(api_key=api_key, model=model, base_url=base_url)
+
+
+__all__ = ["LLMBase", "OpenAICompatProvider", "QwenProvider", "create_llm"]

acm/llm/base.py

@@ -0,0 +1,58 @@
+"""LLM 提供商基类。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Generator
+
+
+class LLMBase(ABC):
+    """LLM 提供商抽象基类。"""
+
+    @abstractmethod
+    def chat(self, system_prompt: str, user_prompt: str) -> str:
+        """发送对话请求，返回助手回复的文本内容。
+
+        Args:
+            system_prompt: 系统提示词。
+            user_prompt: 用户提示词。
+
+        Returns:
+            LLM 生成的文本内容。
+        """
+
+    @abstractmethod
+    def chat_with_history(
+        self,
+        system_prompt: str,
+        messages: list[dict[str, str]],
+    ) -> str:
+        """带历史消息的对话请求（用于反馈重新生成）。
+
+        Args:
+            system_prompt: 系统提示词。
+            messages: 消息历史，每条格式为 {"role": "user"|"assistant", "content": "..."}。
+
+        Returns:
+            LLM 生成的文本内容。
+        """
+
+    def stream_chat(
+        self, system_prompt: str, user_prompt: str
+    ) -> Generator[str, None, None]:
+        """流式对话请求，逐块 yield 生成内容。
+
+        默认实现回退到非流式接口，子类可覆盖以实现真正的 streaming。
+        """
+        yield self.chat(system_prompt, user_prompt)
+
+    def stream_chat_with_history(
+        self,
+        system_prompt: str,
+        messages: list[dict[str, str]],
+    ) -> Generator[str, None, None]:
+        """带历史的流式对话请求。
+
+        默认实现回退到非流式接口，子类可覆盖。
+        """
+        yield self.chat_with_history(system_prompt, messages)

acm/llm/openai_compat.py

@@ -0,0 +1,78 @@
+"""OpenAI 兼容接口通用实现，适用于所有兼容 OpenAI Chat API 的提供商。"""
+
+from __future__ import annotations
+
+from typing import Generator
+
+from openai import OpenAI
+
+from acm.llm.base import LLMBase
+
+
+class OpenAICompatProvider(LLMBase):
+    """通用 OpenAI 兼容 API 提供商。"""
+
+    def __init__(self, api_key: str, model: str, base_url: str = ""):
+        self._model = model
+        kwargs: dict = {"api_key": api_key}
+        if base_url:
+            kwargs["base_url"] = base_url
+        self._client = OpenAI(**kwargs)
+
+    def chat(self, system_prompt: str, user_prompt: str) -> str:
+        response = self._client.chat.completions.create(
+            model=self._model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=0.3,
+        )
+        return response.choices[0].message.content or ""
+
+    def chat_with_history(
+        self,
+        system_prompt: str,
+        messages: list[dict[str, str]],
+    ) -> str:
+        full_messages = [{"role": "system", "content": system_prompt}] + messages
+        response = self._client.chat.completions.create(
+            model=self._model,
+            messages=full_messages,  # type: ignore[arg-type]
+            temperature=0.3,
+        )
+        return response.choices[0].message.content or ""
+
+    def stream_chat(
+        self, system_prompt: str, user_prompt: str
+    ) -> Generator[str, None, None]:
+        stream = self._client.chat.completions.create(
+            model=self._model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=0.3,
+            stream=True,
+        )
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content
+            if delta:
+                yield delta
+
+    def stream_chat_with_history(
+        self,
+        system_prompt: str,
+        messages: list[dict[str, str]],
+    ) -> Generator[str, None, None]:
+        full_messages = [{"role": "system", "content": system_prompt}] + messages
+        stream = self._client.chat.completions.create(
+            model=self._model,
+            messages=full_messages,  # type: ignore[arg-type]
+            temperature=0.3,
+            stream=True,
+        )
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content
+            if delta:
+                yield delta

acm/llm/qwen.py

@@ -0,0 +1,18 @@
+"""通义千问（Qwen）适配，复用 OpenAI 兼容接口。"""
+
+from __future__ import annotations
+
+from acm.llm.openai_compat import OpenAICompatProvider
+
+QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+
+
+class QwenProvider(OpenAICompatProvider):
+    """通义千问提供商，自动设置 base_url。"""
+
+    def __init__(self, api_key: str, model: str, base_url: str = ""):
+        super().__init__(
+            api_key=api_key,
+            model=model,
+            base_url=base_url or QWEN_BASE_URL,
+        )

acm/prompt.py

@@ -0,0 +1,178 @@
+"""Prompt 模板管理：内置 system prompt、用户自定义合并、diff 内容组装。"""
+
+from __future__ import annotations
+
+from acm.config import ACMConfig, get_commit_types
+from acm.feedback import FeedbackRecord, load_feedback, match_feedback
+
+# ---------------------------------------------------------------------------
+# 内置默认 System Prompt
+# ---------------------------------------------------------------------------
+
+DEFAULT_SYSTEM_PROMPT = """\
+你是一个专业的 Git Commit Message 生成助手。你的任务是根据提供的代码 diff 内容，生成规范的 commit message。
+
+## 规则
+
+1. **格式**：`<type>(<scope>): <描述>`
+2. **type** 必须从以下列表中选择：{types}
+3. **scope** 根据变更文件所在的目录/模块自动推断，使用最能代表变更范围的模块名
+4. **描述**使用{language}，简洁明了，不超过 50 个字符
+5. **合并同类变更**：如果多个文件的变更属于同一类操作（如都是优化导入、移除未使用代码、统一格式调整等），应合并为一条 message，scope 用逗号分隔列出所有涉及的模块，而不是为每个文件单独生成描述。例如：
+   - `refactor(cve_service, cve_serializer): 优化导入和移除未使用模块`
+   - `style(auth, api, utils): 统一代码格式化`
+6. 如果变更涉及多个不同类型的修改（非同类操作）：
+   - 标题行用逗号分隔 scope，如 `feat(auth,api): 描述`
+   - 标题行后空一行，再用列表形式分别描述每个模块的变更
+7. 只输出 commit message 本身，不要包含任何解释、前缀或 markdown 标记
+
+## 输出格式示例
+
+单域变更：
+```
+feat(auth): 添加用户登录功能
+```
+
+多文件同类变更（合并）：
+```
+refactor(cve_service, cve_serializer): 优化导入和移除未使用模块
+```
+
+多域不同类变更：
+```
+feat(auth,api): 添加用户认证模块
+
+- auth: 实现基于JWT的登录认证逻辑
+- api: 新增 /login 和 /logout 接口
+```
+"""
+
+
+# ---------------------------------------------------------------------------
+# Prompt 构建
+# ---------------------------------------------------------------------------
+
+def build_system_prompt(config: ACMConfig, diff_content: str = "") -> str:
+    """构建 system prompt，支持用户自定义覆盖。
+
+    Args:
+        config: ACM 配置。
+        diff_content: 当前 diff 内容，用于智能匹配相关反馈。
+    """
+    if config.prompt.system:
+        # 用户完全自定义
+        return config.prompt.system
+
+    types = get_commit_types(config)
+    types_str = ", ".join(types)
+
+    language_map = {
+        "zh-CN": "中文",
+        "en": "English",
+        "ja": "日本語",
+    }
+    language = language_map.get(config.commit.language, config.commit.language)
+
+    prompt = DEFAULT_SYSTEM_PROMPT.format(types=types_str, language=language)
+
+    if config.prompt.extra:
+        prompt += f"\n\n## 额外指令\n\n{config.prompt.extra}"
+
+    # 智能匹配并注入相关历史反馈
+    feedback_section = _build_feedback_section(diff_content=diff_content)
+    if feedback_section:
+        prompt += feedback_section
+
+    return prompt
+
+
+def _build_feedback_section(
+    records: list[FeedbackRecord] | None = None,
+    diff_content: str = "",
+) -> str:
+    """根据历史反馈记录构建学习示例段落。
+
+    当提供 diff_content 时，使用智能匹配选择最相关的反馈；
+    否则回退到全量注入。
+
+    Args:
+        records: 反馈记录列表，None 时从文件加载/匹配。
+        diff_content: 当前 diff 内容，用于匹配相关反馈。
+
+    Returns:
+        格式化后的反馈段落，无记录时返回空字符串。
+    """
+    if records is None:
+        if diff_content:
+            records = match_feedback(diff_content)
+        else:
+            records = load_feedback()
+    if not records:
+        return ""
+
+    lines = ["\n\n## 用户偏好（从历史反馈中学习）\n"]
+    lines.append("以下是用户曾经的修正记录，请学习用户的偏好并应用到后续生成中：\n")
+    for i, r in enumerate(records, 1):
+        lines.append(f"{i}. 原始: `{r.original_message}`")
+        lines.append(f"   反馈: {r.feedback}")
+        lines.append(f"   改进: `{r.improved_message}`")
+    return "\n".join(lines) + "\n"
+
+
+def build_user_prompt(diff_content: str, feedback: str = "") -> str:
+    """构建 user prompt，包含 diff 内容和可选的用户反馈。"""
+    prompt = f"请根据以下 git diff 内容生成 commit message：\n\n```diff\n{diff_content}\n```"
+
+    if feedback:
+        prompt += f"\n\n用户对上一次生成结果的反馈：{feedback}\n请根据反馈重新生成。"
+
+    return prompt
+
+
+def build_split_system_prompt(config: ACMConfig) -> str:
+    """构建用于智能拆分提交的 system prompt。"""
+    types = get_commit_types(config)
+    types_str = ", ".join(types)
+
+    language_map = {
+        "zh-CN": "中文",
+        "en": "English",
+    }
+    language = language_map.get(config.commit.language, config.commit.language)
+
+    return f"""\
+你是一个专业的 Git 提交拆分助手。你的任务是分析 git diff 内容，将变更按照逻辑关联性拆分为多个独立的原子提交。
+
+## 规则
+
+1. 每个提交组包含逻辑上相关联的文件
+2. 每个提交组对应一个 commit message，格式为：`<type>(<scope>): <描述>`
+3. type 从以下列表中选择：{types_str}
+4. 描述使用{language}
+5. 输出严格使用 JSON 格式，不要包含任何其他内容
+
+## 输出 JSON 格式
+
+```json
+[
+  {{
+    "files": ["path/to/file1.py", "path/to/file2.py"],
+    "message": "feat(auth): 添加用户登录功能"
+  }},
+  {{
+    "files": ["path/to/test_file.py"],
+    "message": "test(auth): 添加登录功能单元测试"
+  }}
+]
+```
+"""
+
+
+def build_split_user_prompt(diff_content: str, files: list[str]) -> str:
+    """构建用于智能拆分的 user prompt。"""
+    files_str = "\n".join(f"- {f}" for f in files)
+    return (
+        f"以下是待提交的文件列表：\n{files_str}\n\n"
+        f"以下是 git diff 内容：\n\n```diff\n{diff_content}\n```\n\n"
+        f"请将这些变更拆分为多个原子提交。"
+    )

acm/splitter.py

@@ -0,0 +1,92 @@
+"""智能拆分提交：LLM 分析 staged 内容，按逻辑分组为多个原子提交。"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from acm.config import ACMConfig
+from acm.llm.base import LLMBase
+from acm.prompt import build_split_system_prompt, build_split_user_prompt
+
+
+class SplitError(Exception):
+    """拆分提交相关错误。"""
+
+
+@dataclass
+class CommitGroup:
+    """一个原子提交组。"""
+    files: list[str]
+    message: str
+
+
+def _parse_split_response(raw: str) -> list[CommitGroup]:
+    """解析 LLM 返回的 JSON 拆分结果。"""
+    text = raw.strip()
+    # 尝试提取 JSON 块
+    if "```" in text:
+        # 从 markdown 代码块中提取
+        start = text.find("[")
+        end = text.rfind("]")
+        if start != -1 and end != -1:
+            text = text[start:end + 1]
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise SplitError(f"无法解析 LLM 返回的拆分结果: {e}")
+
+    if not isinstance(data, list):
+        raise SplitError("LLM 返回的拆分结果格式错误，应为 JSON 数组")
+
+    groups = []
+    for item in data:
+        if not isinstance(item, dict):
+            raise SplitError("拆分结果中的每个元素应为对象")
+        files = item.get("files", [])
+        message = item.get("message", "")
+        if not files or not message:
+            raise SplitError("拆分结果中的每个元素必须包含 files 和 message")
+        groups.append(CommitGroup(files=files, message=message))
+
+    return groups
+
+
+class CommitSplitter:
+    """智能拆分提交。"""
+
+    def __init__(self, llm: LLMBase, config: ACMConfig):
+        self._llm = llm
+        self._config = config
+
+    def split(self, diff_content: str, files: list[str]) -> list[CommitGroup]:
+        """分析 diff 内容并返回拆分建议。
+
+        Args:
+            diff_content: git diff 内容。
+            files: staged 文件路径列表。
+
+        Returns:
+            拆分后的提交组列表。
+        """
+        system_prompt = build_split_system_prompt(self._config)
+        user_prompt = build_split_user_prompt(diff_content, files)
+
+        raw = self._llm.chat(system_prompt, user_prompt)
+        if not raw:
+            raise SplitError("LLM 返回了空内容")
+
+        groups = _parse_split_response(raw)
+
+        # 校验：所有文件都应被分配到某个组
+        assigned = set()
+        for group in groups:
+            assigned.update(group.files)
+
+        missing = set(files) - assigned
+        if missing:
+            # 将未分配的文件归入最后一组
+            groups[-1].files.extend(sorted(missing))
+
+        return groups