agent-cli-Mrzhou300 0.2.1__py3-none-any.whl

agent_cli/__init__.py

@@ -0,0 +1,2 @@
+# Agent-CLI — 轻量级个人助手
+__version__ = "0.2.0"

agent_cli/compact/__init__.py

@@ -0,0 +1 @@
+# Context Compression — Phase 2 实现

agent_cli/compact/pipeline.py

@@ -0,0 +1,347 @@
+"""CompactPipeline — 四层上下文压缩管道。
+
+设计哲学（来源：learn-claude-code）：
+  这是 learn-claude-code 项目最有特色的设计。
+  L1-L3 零 API 调用，纯算法压缩。
+  L4 使用 LLM 重写关键上下文。
+  70% 阈值触发 L1-L3，90% 阈值触发 L4。
+
+L1 (丢弃层):
+  - 丢弃已完成的 tool_use 调用 details（保留 tool_result）
+  - 丢弃 tool_result 中过大的内容（> 2000 字符截断）
+  - 移除空的 tool_result 块
+
+L2 (合并层):
+  - 合并连续的 tool_result 消息
+  - 合并连续的 text-only assistant 消息
+  - 合并连续的 user 消息
+
+L3 (摘要层):
+  - 对早期对话做结构化摘要
+  - 提取关键决策和结论
+  - 移除非核心的中间步骤
+
+L4 (重写层 — 需要 LLM):
+  - 用 LLM 重写关键上下文
+  - 保持语义完整性
+  - 标记压缩来源位置
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+from typing import Any
+
+from agent_cli.core.provider import IModelProvider
+
+logger = logging.getLogger(__name__)
+
+# 估算 token 数的经验常量
+_CHARS_PER_TOKEN = 4
+_TOOL_BLOCK_BASE = 50  # 每个 tool_use block 的固定开销
+
+
+def _estimate_tokens(data: Any) -> int:
+    """估算任意数据的 token 数。
+
+    使用简单字符计数法（~4 chars/token），
+    对结构化的 tool block 添加额外开销估算。
+    """
+    if isinstance(data, str):
+        return math.ceil(len(data) / _CHARS_PER_TOKEN)
+    if isinstance(data, list):
+        return sum(_estimate_tokens(item) for item in data)
+    if isinstance(data, dict):
+        total = sum(_estimate_tokens(v) for v in data.values())
+        # tool block 有结构化开销
+        if data.get("type") in ("tool_use", "tool_result"):
+            total += _TOOL_BLOCK_BASE
+        return total
+    return len(str(data)) // _CHARS_PER_TOKEN
+
+
+class CompactPipeline:
+    """四层上下文压缩管道。
+
+    Usage:
+        pipeline = CompactPipeline(max_tokens=100000)
+        if pipeline.should_compact(messages):
+            messages = pipeline.compress(messages)
+    """
+
+    COMPACT_RATIO = 0.7  # 70% → 触发 L1-L3
+    CRITICAL_RATIO = 0.9  # 90% → 触发 L4
+
+    def __init__(
+        self,
+        max_tokens: int = 100000,
+        provider: IModelProvider | None = None,
+    ):
+        self._max_tokens = max_tokens
+        self._provider = provider
+        self.compression_count = 0
+        self.last_ratio = 0.0
+
+    def should_compact(self, messages: list[dict]) -> bool:
+        """检查是否需要压缩。
+
+        Args:
+            messages: 消息列表。
+
+        Returns:
+            超过 70% 阈值返回 True。
+        """
+        if not messages:
+            return False
+        current = _estimate_tokens(messages)
+        ratio = current / self._max_tokens
+        self.last_ratio = ratio
+        return ratio >= self.COMPACT_RATIO
+
+    def compress(self, messages: list[dict]) -> list[dict]:
+        """执行渐进压缩。
+
+        根据当前 Token 比率自动选择压缩层级：
+          - < 70%: 不压缩
+          - 70-90%: L1 丢弃
+          - >= 90%: L1 → L2 → L3
+
+        Args:
+            messages: 消息列表。
+
+        Returns:
+            压缩后的消息列表。
+        """
+        if not messages:
+            return messages
+
+        ratio = _estimate_tokens(messages) / self._max_tokens
+        self.last_ratio = ratio
+        self.compression_count += 1
+
+        if ratio < self.COMPACT_RATIO:
+            logger.debug("压缩跳过: ratio=%.2f < %.2f", ratio, self.COMPACT_RATIO)
+            return messages
+
+        logger.info("压缩触发 #%d: ratio=%.2f", self.compression_count, ratio)
+
+        # L1: 丢弃层
+        compressed = self._layer1_discard(messages)
+        if ratio < self.CRITICAL_RATIO:
+            compressed.append(self._compression_marker("L1"))
+            logger.info("L1 压缩完成: %d → %d 条", len(messages), len(compressed))
+            return compressed
+
+        # L2: 合并层
+        compressed = self._layer2_merge(compressed)
+        compressed.append(self._compression_marker("L1+L2"))
+        logger.info("L1+L2 压缩完成: %d → %d 条", len(messages), len(compressed))
+
+        # L3: 摘要层
+        compressed = self._layer3_summarize(compressed)
+
+        # L4: 重写层（仅当有 LLM Provider 时）
+        if ratio >= self.CRITICAL_RATIO and self._provider is not None:
+            compressed = self._layer4_rewrite(compressed)
+
+        compressed.append(self._compression_marker("L3+L4" if self._provider else "L3"))
+        logger.info("压缩完成: %d → %d 条", len(messages), len(compressed))
+        return compressed
+
+    def _compression_marker(self, level: str) -> dict:
+        """生成压缩标记消息。"""
+        return {
+            "role": "system",
+            "content": f"[compressed: {level}] 上下文已压缩以减少 Token 消耗。"
+            f" 压缩 #{self.compression_count}, ratio={self.last_ratio:.1%}",
+        }
+
+    # ── L1: 丢弃层 ──────────────────────────────────────────
+
+    def _layer1_discard(self, messages: list[dict]) -> list[dict]:
+        """丢弃过时细节，保留核心信息。"""
+        result: list[dict] = []
+        for msg in messages:
+            content = msg.get("content", "")
+
+            # 跳过空的 tool_result
+            if isinstance(content, list):
+                filtered_blocks = []
+                for block in content:
+                    if block.get("type") == "tool_result":
+                        block_content = block.get("content", "")
+                        # 截断过大的 tool_result
+                        if isinstance(block_content, str) and len(block_content) > 2000:
+                            block = dict(block)
+                            block["content"] = block_content[:2000] + "\n... [截断]"
+                        # 跳过完全空的 tool_result
+                        if not block_content or (
+                            isinstance(block_content, dict) and block_content.get("content") == ""
+                        ):
+                            continue
+                    filtered_blocks.append(block)
+                if filtered_blocks:
+                    result.append({**msg, "content": filtered_blocks})
+                continue
+
+            if isinstance(content, str) and len(content) > 4000:
+                result.append({**msg, "content": content[:4000] + "\n... [截断]"})
+                continue
+
+            result.append(msg)
+
+        return result
+
+    # ── L2: 合并层 ──────────────────────────────────────────
+
+    def _layer2_merge(self, messages: list[dict]) -> list[dict]:
+        """合并相邻同类消息。"""
+        if not messages:
+            return messages
+
+        merged: list[dict] = [messages[0]]
+
+        for msg in messages[1:]:
+            last = merged[-1]
+            last_role = last.get("role", "")
+            curr_role = msg.get("role", "")
+
+            # 合并连续 tool_result (user role)
+            last_content = last.get("content")
+            msg_content = msg.get("content")
+
+            def _all_tool_results(items: list) -> bool:
+                return all(isinstance(b, dict) and b.get("type") == "tool_result" for b in items)
+
+            if (
+                last_role == "user"
+                and curr_role == "user"
+                and isinstance(last_content, list)
+                and isinstance(msg_content, list)
+                and _all_tool_results(last_content)
+                and _all_tool_results(msg_content)
+            ):
+                merged[-1] = {**last, "content": last["content"] + msg["content"]}
+                continue
+
+            # 合并连续 assistant text-only 消息
+            if last_role == "assistant" and curr_role == "assistant":
+                last_text = self._get_text_content(last)
+                curr_text = self._get_text_content(msg)
+                if last_text and curr_text:
+                    merged[-1] = {
+                        "role": "assistant",
+                        "content": last_text + "\n" + curr_text,
+                    }
+                    continue
+
+            merged.append(msg)
+
+        return merged
+
+    def _get_text_content(self, msg: dict) -> str:
+        """从消息中提取文本内容。"""
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts = [
+                b.get("text", "")
+                for b in content
+                if isinstance(b, dict) and b.get("type") == "text"
+            ]
+            return " ".join(parts)
+        return ""
+
+    # ── L3: 摘要层 ──────────────────────────────────────────
+
+    def _layer3_summarize(self, messages: list[dict]) -> list[dict]:
+        """对早期对话做结构化摘要。
+
+        保留最近 6 条消息完整，之前的消息压缩为摘要。
+        """
+        if len(messages) <= 6:
+            return messages
+
+        keep_recent = messages[-6:]
+        early = messages[:-6]
+
+        # 从早期消息中提取关键信息
+        topics: list[str] = []
+        files: set[str] = set()
+
+        for msg in early:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+
+            if role == "user":
+                text = content if isinstance(content, str) else ""
+                if text:
+                    topics.append(text[:100])
+
+            elif role == "assistant":
+                text = content if isinstance(content, str) else ""
+                if isinstance(content, list):
+                    for block in content:
+                        if isinstance(block, dict):
+                            text += block.get("text", "") or ""
+                # 提取文件路径
+                import re
+
+                found_files = re.findall(r"[\w/.-]+\.\w+", text)
+                files.update(f for f in found_files if "/" in f or "\\" in f)
+
+        summary_text = (
+            f"[对话摘要] 共 {len(early)} 条早期消息。\n"
+            f"涉及文件: {', '.join(list(files)[:10]) if files else 'N/A'}\n"
+        )
+        if topics:
+            summary_text += f"关键主题: {' | '.join(topics[:5])}\n"
+
+        return [
+            {"role": "system", "content": summary_text},
+            *keep_recent,
+        ]
+
+    # ── L4: 重写层 ──────────────────────────────────────────
+
+    def _layer4_rewrite(self, messages: list[dict]) -> list[dict]:
+        """用 LLM 重写关键上下文。"""
+        if not self._provider:
+            logger.warning("L4 需要 LLM Provider，跳过")
+            return messages
+
+        try:
+            prompt = (
+                "请压缩以下对话历史，保留所有关键信息、决策和上下文，"
+                "但使用更简洁的表达。请直接输出压缩后的对话内容。\n\n"
+                f"对话历史:\n{json.dumps(messages[-20:], ensure_ascii=False)}"
+            )
+
+            response = self._provider.invoke(
+                messages=[{"role": "user", "content": prompt}],
+            )
+
+            if response.text:
+                return [
+                    {
+                        "role": "system",
+                        "content": f"[compressed: L4 - LLM 重写]\n{response.text[:5000]}",
+                    },
+                ]
+        except Exception as e:
+            logger.error("L4 重写失败: %s", e)
+
+        return messages
+
+    def get_stats(self) -> dict:
+        """获取压缩统计信息。"""
+        return {
+            "compression_count": self.compression_count,
+            "last_ratio": round(self.last_ratio, 3),
+            "max_tokens": self._max_tokens,
+            "compact_ratio": self.COMPACT_RATIO,
+            "critical_ratio": self.CRITICAL_RATIO,
+        }

agent_cli/config.py

@@ -0,0 +1,178 @@
+"""配置管理 — 从 config.json 加载默认设置。
+
+设计原则：
+  - 配置文件位于 .agent/config.json
+  - CLI 参数 > 环境变量 > 配置文件 > 默认值
+  - 支持 provider、logging、retry 等配置项
+  - init 命令自动创建默认配置
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_PATH = ".agent/config.json"
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "provider": {
+        "default": "auto",
+        "model": "deepseek-chat",
+        "base_url": "https://api.deepseek.com/v1",
+        "max_tokens": 4096,
+    },
+    "logging": {
+        "level": "WARNING",
+        "format": "text",
+        "file": ".agent/logs/agent-cli.log",
+    },
+    "retry": {
+        "max_retries": 3,
+        "base_delay": 1.0,
+        "max_delay": 30.0,
+    },
+}
+
+
+def get_config_path(path: str | None = None) -> str:
+    """获取配置文件路径。"""
+    return path or os.environ.get("AGENT_CLI_CONFIG") or DEFAULT_CONFIG_PATH
+
+
+def load_config(path: str | None = None) -> dict[str, Any]:
+    """从 JSON 文件加载配置。
+
+    如果文件不存在或格式错误，返回默认配置。
+
+    Args:
+        path: 配置文件路径。默认使用 .agent/config.json。
+
+    Returns:
+        合并后的配置字典。
+    """
+    config_path = Path(get_config_path(path))
+    if not config_path.exists():
+        return {}
+
+    try:
+        raw = config_path.read_text(encoding="utf-8")
+        user_config: dict = json.loads(raw)
+        return user_config
+    except (json.JSONDecodeError, OSError) as e:
+        import logging
+
+        logging.getLogger(__name__).warning("加载配置文件失败 %s: %s", config_path, e)
+        return {}
+
+
+def merge_config(
+    cli_args: dict[str, Any],
+    env_prefix: str = "",
+) -> dict[str, Any]:
+    """合并 CLI 参数、环境变量、配置文件。
+
+    优先级（从高到低）：
+      1. CLI 参数（显式传入的值）
+      2. 环境变量
+      3. 配置文件（.agent/config.json）
+      4. 默认值
+
+    Args:
+        cli_args: CLI 参数字典（已解析的值）。
+        env_prefix: 环境变量前缀（用于查找覆盖）。
+
+    Returns:
+        合并后的配置。
+    """
+    config = dict(DEFAULT_CONFIG)
+    file_config = load_config()
+
+    # 深度合并文件配置
+    _deep_merge(config, file_config)
+
+    # 环境变量覆盖
+    provider_env = _get_env_provider(env_prefix)
+    _deep_merge(config, provider_env)
+
+    # CLI 参数覆盖（只覆盖非 None/非空的值）
+    _deep_merge(config, cli_args)
+
+    return config
+
+
+def _deep_merge(base: dict, override: dict) -> None:
+    """深度合并两个字典。"""
+    for key, value in override.items():
+        if key in base and isinstance(base[key], dict) and isinstance(value, dict):
+            _deep_merge(base[key], value)
+        else:
+            base[key] = value
+
+
+def _get_env_provider(prefix: str = "") -> dict:
+    """从环境变量读取 provider 配置。"""
+    env: dict[str, Any] = {}
+    api_key = os.environ.get(f"{prefix}COMPATIBLE_API_KEY") or os.environ.get("COMPATIBLE_API_KEY")
+    anthro_key = os.environ.get(f"{prefix}ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_API_KEY")
+
+    if api_key or anthro_key:
+        env["provider"] = {}
+        if api_key:
+            env["provider"]["api_key"] = api_key
+        if anthro_key:
+            env["provider"]["anthropic_key"] = anthro_key
+
+    log_level = os.environ.get(f"{prefix}AGENT_CLI_LOG_LEVEL") or os.environ.get(
+        "AGENT_CLI_LOG_LEVEL"
+    )
+    if log_level:
+        env["logging"] = {"level": log_level}
+
+    return env
+
+
+def save_config(config: dict[str, Any], path: str | None = None) -> str:
+    """保存配置到 JSON 文件。
+
+    Args:
+        config: 要保存的配置字典。
+        path: 配置文件路径。默认使用 .agent/config.json。
+
+    Returns:
+        保存的配置文件路径。
+    """
+    from copy import deepcopy
+
+    cfg_path = Path(get_config_path(path))
+    cfg_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 清理空值，避免写入 null
+    cleaned = _clean_none(deepcopy(config))
+
+    cfg_path.write_text(
+        json.dumps(cleaned, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return str(cfg_path)
+
+
+def _clean_none(d: dict[str, Any]) -> dict[str, Any]:
+    """递归删除字典中的 None 值。"""
+    result = {}
+    for k, v in d.items():
+        if v is None:
+            continue
+        if isinstance(v, dict):
+            sub = _clean_none(v)
+            if sub:
+                result[k] = sub
+        else:
+            result[k] = v
+    return result
+
+
+def save_default_config(path: str | None = None) -> str:
+    """保存默认配置文件。"""
+    return save_config(DEFAULT_CONFIG, path=path)

agent_cli/core/executor.py

@@ -0,0 +1,65 @@
+"""Executor — 执行层。
+
+在 Agent Loop 的工具执行阶段提供额外服务：
+  - 权限检查（委派给 PermissionEngine）
+  - 执行结果格式化
+  - 错误处理与重试
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agent_cli.permissions.engine import PermissionEngine
+from agent_cli.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class Executor:
+    """工具执行器。
+
+    在 Agent Loop 与 ToolRegistry 之间提供一层服务：
+    1. 权限检查
+    2. 执行调度
+    3. 异常处理
+    """
+
+    def __init__(self, registry: ToolRegistry, permissions: PermissionEngine | None = None):
+        self.registry = registry
+        self.permissions = permissions or PermissionEngine()
+
+    def execute(self, name: str, **kwargs: Any) -> dict:
+        """执行工具（带权限检查和错误处理）。
+
+        Args:
+            name: 工具名。
+            **kwargs: 工具参数。
+
+        Returns:
+            执行结果字典，始终包含 'success' 字段。
+        """
+        # 1. 检查工具是否存在
+        tool = self.registry.get(name)
+        if tool is None:
+            return {"success": False, "error": f"工具 '{name}' 不存在"}
+
+        # 2. 权限检查
+        spec = tool.spec()
+        decision = self.permissions.check(name, spec.safety.value)
+        if decision == "deny":
+            return {"success": False, "error": f"权限拒绝: 操作 '{name}' 被禁止"}
+        # ask 决策留给上层（CLI/UI）处理
+
+        # 3. 执行
+        try:
+            result = self.registry.execute(name, **kwargs)
+            if isinstance(result, dict):
+                result.setdefault("success", True)
+            else:
+                result = {"success": True, "result": result}
+            return result
+        except Exception as e:
+            logger.error("工具执行异常: %s — %s", name, e)
+            return {"success": False, "error": str(e)}