acm-cli 0.1.0__py3-none-any.whl

acm/config.py

@@ -0,0 +1,272 @@
+"""配置管理模块：加载、合并、校验 TOML 配置文件与环境变量。"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # pragma: no cover
+        import tomli as tomllib  # type: ignore[no-redef]
+
+import tomli_w
+
+
+# ---------------------------------------------------------------------------
+# 常量
+# ---------------------------------------------------------------------------
+
+GLOBAL_CONFIG_DIR = Path.home() / ".acm"
+GLOBAL_CONFIG_FILE = GLOBAL_CONFIG_DIR / "config.toml"
+PROJECT_CONFIG_FILE = ".acm.toml"
+
+DEFAULT_COMMIT_TYPES: list[str] = [
+    "feat", "fix", "docs", "style", "refactor", "perf", "test", "chore",
+]
+
+PROVIDER_DEFAULTS: dict[str, dict[str, str]] = {
+    "qwen": {
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "env_key": "DASHSCOPE_API_KEY",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# 数据类
+# ---------------------------------------------------------------------------
+
+@dataclass
+class LLMConfig:
+    provider: str = ""
+    api_key: str = ""
+    model: str = ""
+    base_url: str = ""
+
+
+@dataclass
+class CommitConfig:
+    language: str = "zh-CN"
+    max_diff_lines: int = 500
+    types: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PromptConfig:
+    system: str = ""
+    extra: str = ""
+
+
+@dataclass
+class ACMConfig:
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    commit: CommitConfig = field(default_factory=CommitConfig)
+    prompt: PromptConfig = field(default_factory=PromptConfig)
+
+
+# ---------------------------------------------------------------------------
+# 加载与合并
+# ---------------------------------------------------------------------------
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    """从文件加载 TOML，文件不存在时返回空 dict。"""
+    if not path.is_file():
+        return {}
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """深度合并两个 dict，override 覆盖 base。"""
+    merged = base.copy()
+    for key, val in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(val, dict):
+            merged[key] = _deep_merge(merged[key], val)
+        else:
+            merged[key] = val
+    return merged
+
+
+def _dict_to_config(data: dict[str, Any]) -> ACMConfig:
+    """将 dict 转换为 ACMConfig 数据类。"""
+    llm_data = data.get("llm", {})
+    commit_data = data.get("commit", {})
+    prompt_data = data.get("prompt", {})
+
+    return ACMConfig(
+        llm=LLMConfig(
+            provider=llm_data.get("provider", ""),
+            api_key=llm_data.get("api_key", ""),
+            model=llm_data.get("model", ""),
+            base_url=llm_data.get("base_url", ""),
+        ),
+        commit=CommitConfig(
+            language=commit_data.get("language", "zh-CN"),
+            max_diff_lines=commit_data.get("max_diff_lines", 500),
+            types=commit_data.get("types", []),
+        ),
+        prompt=PromptConfig(
+            system=prompt_data.get("system", ""),
+            extra=prompt_data.get("extra", ""),
+        ),
+    )
+
+
+def _resolve_api_key(config: ACMConfig) -> str:
+    """按优先级解析 API Key：环境变量 > 提供商专用环境变量 > 配置文件。"""
+    # 1. 通用环境变量
+    env_key = os.environ.get("ACM_API_KEY", "")
+    if env_key:
+        return env_key
+
+    # 2. 提供商专用环境变量
+    provider = config.llm.provider.lower()
+    if provider in PROVIDER_DEFAULTS:
+        provider_env = PROVIDER_DEFAULTS[provider].get("env_key", "")
+        if provider_env:
+            val = os.environ.get(provider_env, "")
+            if val:
+                return val
+
+    # 3. 配置文件
+    return config.llm.api_key
+
+
+def _resolve_base_url(config: ACMConfig) -> str:
+    """解析 base_url：配置文件值优先，否则使用提供商默认值。"""
+    if config.llm.base_url:
+        return config.llm.base_url
+    provider = config.llm.provider.lower()
+    if provider in PROVIDER_DEFAULTS:
+        return PROVIDER_DEFAULTS[provider].get("base_url", "")
+    return ""
+
+
+def load_config(project_dir: str | Path | None = None) -> ACMConfig:
+    """加载并合并配置，返回最终的 ACMConfig。
+
+    优先级（高 → 低）：项目级配置 > 全局配置 > 默认值。
+    API Key 额外叠加环境变量优先级。
+    """
+    global_data = _load_toml(GLOBAL_CONFIG_FILE)
+
+    if project_dir is None:
+        project_dir = Path.cwd()
+    else:
+        project_dir = Path(project_dir)
+    project_path = project_dir / PROJECT_CONFIG_FILE
+    project_data = _load_toml(project_path)
+
+    merged = _deep_merge(global_data, project_data)
+    config = _dict_to_config(merged)
+
+    # 解析 API Key 和 base_url
+    config.llm.api_key = _resolve_api_key(config)
+    config.llm.base_url = _resolve_base_url(config)
+
+    return config
+
+
+# ---------------------------------------------------------------------------
+# 校验
+# ---------------------------------------------------------------------------
+
+class ConfigError(Exception):
+    """配置错误。"""
+
+
+def validate_config(config: ACMConfig) -> None:
+    """校验必填配置项，缺失时抛出 ConfigError。"""
+    if not config.llm.api_key:
+        raise ConfigError("未配置 API Key，请运行 acm init 进行初始化")
+    if not config.llm.model:
+        raise ConfigError("未配置模型名称，请运行 acm init 或编辑配置文件")
+
+
+# ---------------------------------------------------------------------------
+# 获取所有 commit types
+# ---------------------------------------------------------------------------
+
+def get_commit_types(config: ACMConfig) -> list[str]:
+    """返回标准类型 + 用户自定义类型（去重）。"""
+    all_types = list(DEFAULT_COMMIT_TYPES)
+    for t in config.commit.types:
+        if t not in all_types:
+            all_types.append(t)
+    return all_types
+
+
+# ---------------------------------------------------------------------------
+# 写入配置文件
+# ---------------------------------------------------------------------------
+
+def save_config(config: ACMConfig, path: Path) -> None:
+    """将配置写入 TOML 文件。"""
+    data: dict[str, Any] = {
+        "llm": {
+            "provider": config.llm.provider,
+            "api_key": config.llm.api_key,
+            "model": config.llm.model,
+            "base_url": config.llm.base_url,
+        },
+        "commit": {
+            "language": config.commit.language,
+            "max_diff_lines": config.commit.max_diff_lines,
+            "types": config.commit.types,
+        },
+        "prompt": {
+            "system": config.prompt.system,
+            "extra": config.prompt.extra,
+        },
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def config_set(key: str, value: str, path: Path) -> None:
+    """设置单个配置项，key 格式为 'section.field'，例如 'llm.model'。"""
+    data = _load_toml(path)
+    parts = key.split(".", 1)
+    if len(parts) != 2:
+        raise ConfigError(f"无效的配置键: {key}，格式应为 section.field")
+    section, field_name = parts
+
+    if section not in data:
+        data[section] = {}
+
+    # 尝试将数值字符串转为 int
+    try:
+        value_typed: Any = int(value)
+    except ValueError:
+        value_typed = value
+
+    data[section][field_name] = value_typed
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def config_get(key: str, config: ACMConfig) -> str:
+    """获取单个配置项的值。"""
+    parts = key.split(".", 1)
+    if len(parts) != 2:
+        raise ConfigError(f"无效的配置键: {key}，格式应为 section.field")
+    section, field_name = parts
+
+    section_obj = getattr(config, section, None)
+    if section_obj is None:
+        raise ConfigError(f"未知的配置节: {section}")
+
+    value = getattr(section_obj, field_name, None)
+    if value is None:
+        raise ConfigError(f"未知的配置项: {key}")
+
+    return str(value)

acm/feedback.py

@@ -0,0 +1,148 @@
+"""反馈学习模块：记录用户反馈，按相似度匹配注入 prompt，动态优化后续生成。"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from acm.config import GLOBAL_CONFIG_DIR
+
+FEEDBACK_FILE = GLOBAL_CONFIG_DIR / "feedback.json"
+MAX_FEEDBACK_RECORDS = 20
+MAX_INJECT_RECORDS = 5
+
+
+@dataclass
+class FeedbackRecord:
+    """一条反馈记录。"""
+    original_message: str   # LLM 原始生成的 message
+    feedback: str           # 用户的反馈内容
+    improved_message: str   # 改进后的 message
+
+
+def load_feedback(path: Path | None = None) -> list[FeedbackRecord]:
+    """加载历史反馈记录。"""
+    fp = path or FEEDBACK_FILE
+    if not fp.is_file():
+        return []
+    try:
+        with open(fp, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return [
+            FeedbackRecord(
+                original_message=r["original_message"],
+                feedback=r["feedback"],
+                improved_message=r["improved_message"],
+            )
+            for r in data
+        ]
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return []
+
+
+def save_feedback(records: list[FeedbackRecord], path: Path | None = None) -> None:
+    """保存反馈记录到文件。"""
+    fp = path or FEEDBACK_FILE
+    fp.parent.mkdir(parents=True, exist_ok=True)
+    data = [asdict(r) for r in records]
+    with open(fp, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def add_feedback(
+    original_message: str,
+    feedback: str,
+    improved_message: str,
+    path: Path | None = None,
+) -> None:
+    """添加一条反馈记录，超过上限时淘汰最早的记录。"""
+    records = load_feedback(path)
+    records.append(FeedbackRecord(
+        original_message=original_message,
+        feedback=feedback,
+        improved_message=improved_message,
+    ))
+    # 保留最近 N 条
+    if len(records) > MAX_FEEDBACK_RECORDS:
+        records = records[-MAX_FEEDBACK_RECORDS:]
+    save_feedback(records, path)
+
+
+def clear_feedback(path: Path | None = None) -> int:
+    """清空所有反馈记录，返回清除的条数。"""
+    fp = path or FEEDBACK_FILE
+    records = load_feedback(fp)
+    count = len(records)
+    if fp.is_file():
+        fp.unlink()
+    return count
+
+
+def _parse_type_scope(message: str) -> tuple[str, set[str]]:
+    """从 commit message 中提取 type 和 scope 集合。
+
+    例如 'feat(auth, api): 描述' -> ('feat', {'auth', 'api'})
+    """
+    m = re.match(r"^(\w+)\(([^)]*)\)", message)
+    if not m:
+        return ("", set())
+    msg_type = m.group(1)
+    scopes = {s.strip() for s in m.group(2).split(",") if s.strip()}
+    return (msg_type, scopes)
+
+
+def match_feedback(
+    diff_content: str,
+    records: list[FeedbackRecord] | None = None,
+    path: Path | None = None,
+    max_results: int = MAX_INJECT_RECORDS,
+) -> list[FeedbackRecord]:
+    """从历史反馈中筛选与当前 diff 最相关的记录。
+
+    匹配策略（按优先级）：
+    1. 反馈内容中的关键词在 diff 中出现 -> 高相关
+    2. improved_message 的 type 在 diff 路径中能推断 -> 中相关
+    3. 兜底：最近的记录优先
+
+    Args:
+        diff_content: 当前的 diff 内容。
+        records: 反馈记录列表，None 时从文件加载。
+        path: 反馈文件路径。
+        max_results: 最多返回的条数。
+
+    Returns:
+        筛选后的反馈记录列表。
+    """
+    if records is None:
+        records = load_feedback(path)
+    if not records:
+        return []
+
+    diff_lower = diff_content.lower()
+
+    scored: list[tuple[float, int, FeedbackRecord]] = []
+    for idx, r in enumerate(records):
+        score = 0.0
+
+        # 策略1：反馈关键词出现在 diff 中
+        feedback_words = set(re.findall(r"[\w\u4e00-\u9fff]+", r.feedback.lower()))
+        for word in feedback_words:
+            if len(word) >= 2 and word in diff_lower:
+                score += 2.0
+
+        # 策略2：improved_message 的 scope 出现在 diff 路径中
+        _, scopes = _parse_type_scope(r.improved_message)
+        for scope in scopes:
+            if scope.lower() in diff_lower:
+                score += 1.5
+
+        # 策略3：recency bonus（越新的记录分数越高）
+        score += idx * 0.1
+
+        scored.append((score, idx, r))
+
+    # 按分数降序排列
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return [r for _, _, r in scored[:max_results]]

acm/generator.py

@@ -0,0 +1,127 @@
+"""Commit Message 生成核心逻辑：调用 LLM、解析响应、反馈重新生成。"""
+
+from __future__ import annotations
+
+import re
+from typing import Generator
+
+from acm.config import ACMConfig
+from acm.llm.base import LLMBase
+from acm.prompt import build_system_prompt, build_user_prompt
+
+
+class GenerateError(Exception):
+    """生成 commit message 时的错误。"""
+
+
+def _clean_message(raw: str) -> str:
+    """清理 LLM 返回的原始内容，去除 markdown 标记等。"""
+    text = raw.strip()
+    # 去除可能的 ```commit 或 ``` 包裹
+    text = re.sub(r"^```[\w]*\n?", "", text)
+    text = re.sub(r"\n?```$", "", text)
+    return text.strip()
+
+
+class CommitGenerator:
+    """Commit message 生成器，支持反馈多次重新生成。"""
+
+    def __init__(self, llm: LLMBase, config: ACMConfig):
+        self._llm = llm
+        self._config = config
+        self._system_prompt: str = ""
+        self._history: list[dict[str, str]] = []
+
+    def generate(self, diff_content: str) -> str:
+        """首次生成 commit message。
+
+        Args:
+            diff_content: git diff 内容（可能已截断）。
+
+        Returns:
+            生成的 commit message。
+        """
+        self._system_prompt = build_system_prompt(self._config, diff_content=diff_content)
+        user_prompt = build_user_prompt(diff_content)
+        self._history = [{"role": "user", "content": user_prompt}]
+
+        raw = self._llm.chat(self._system_prompt, user_prompt)
+        if not raw:
+            raise GenerateError("LLM 返回了空内容，请检查模型配置")
+
+        message = _clean_message(raw)
+        self._history.append({"role": "assistant", "content": message})
+        return message
+
+    def stream_generate(self, diff_content: str) -> Generator[str, None, str]:
+        """流式首次生成，逐块 yield 内容，最终 return 完整 message。
+
+        用法::
+
+            gen = generator.stream_generate(diff)
+            try:
+                while True:
+                    chunk = next(gen)
+                    # 实时显示 chunk
+            except StopIteration as e:
+                final_message = e.value
+        """
+        self._system_prompt = build_system_prompt(self._config, diff_content=diff_content)
+        user_prompt = build_user_prompt(diff_content)
+        self._history = [{"role": "user", "content": user_prompt}]
+
+        chunks: list[str] = []
+        for chunk in self._llm.stream_chat(self._system_prompt, user_prompt):
+            chunks.append(chunk)
+            yield chunk
+
+        raw = "".join(chunks)
+        if not raw:
+            raise GenerateError("LLM 返回了空内容，请检查模型配置")
+
+        message = _clean_message(raw)
+        self._history.append({"role": "assistant", "content": message})
+        return message
+
+    def stream_regenerate(self, feedback: str) -> Generator[str, None, str]:
+        """流式反馈重新生成，逐块 yield 内容，最终 return 完整 message。"""
+        feedback_prompt = f"用户对上一次生成结果的反馈：{feedback}\n请根据反馈重新生成 commit message。"
+        self._history.append({"role": "user", "content": feedback_prompt})
+
+        chunks: list[str] = []
+        for chunk in self._llm.stream_chat_with_history(self._system_prompt, self._history):
+            chunks.append(chunk)
+            yield chunk
+
+        raw = "".join(chunks)
+        if not raw:
+            raise GenerateError("LLM 返回了空内容，请检查模型配置")
+
+        message = _clean_message(raw)
+        self._history.append({"role": "assistant", "content": message})
+        return message
+
+    def regenerate(self, feedback: str) -> str:
+        """根据用户反馈重新生成（非流式）。
+
+        Args:
+            feedback: 用户的反馈意见。
+
+        Returns:
+            重新生成的 commit message。
+        """
+        feedback_prompt = f"用户对上一次生成结果的反馈：{feedback}\n请根据反馈重新生成 commit message。"
+        self._history.append({"role": "user", "content": feedback_prompt})
+
+        raw = self._llm.chat_with_history(self._system_prompt, self._history)
+        if not raw:
+            raise GenerateError("LLM 返回了空内容，请检查模型配置")
+
+        message = _clean_message(raw)
+        self._history.append({"role": "assistant", "content": message})
+        return message
+
+    @property
+    def history(self) -> list[dict[str, str]]:
+        """返回当前对话历史（只读）。"""
+        return list(self._history)