abyss-cli 0.1.0__py3-none-any.whl

abyss/mcp/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+"""
+MCP 模块
+提供 Model Context Protocol 客户端能力，连接外部 MCP Server
+"""
+from .manager import MCPClientManager, ServerConfig, MCPServerType, create_default_manager
+
+__all__ = [
+    "MCPClientManager",
+    "ServerConfig",
+    "MCPServerType",
+    "create_default_manager",
+]

abyss/mcp/manager.py

@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""
+MCP Client Manager 模块
+管理多个 MCP Server 连接，支持 stdio 和 HTTP 两种传输（SSE 暂未实现）。
+工具命名规则：mcp__<server_name>__<tool_name>，避免与内置工具冲突。
+
+配置文件格式（~/.abyss/mcp.json）：
+{
+  "mcp_servers": [
+    {"name": "github", "transport": "stdio", "command": "npx", "args": [...], "env": {...}},
+    {"name": "db", "transport": "http", "url": "http://...", "headers": {...}}
+  ]
+}
+
+注：真实子进程连接（JSON-RPC over stdio）在 start() 中实现，
+本模块聚焦配置解析、工具注册表、schema 生成等可单测的核心逻辑。
+"""
+import json
+import subprocess
+import threading
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class MCPServerType(Enum):
+    """MCP Server 传输类型。"""
+    STDIO = "stdio"
+    HTTP = "http"
+    SSE = "sse"
+
+
+@dataclass
+class ServerConfig:
+    """单个 MCP Server 的配置。"""
+    name: str
+    transport: MCPServerType
+    command: Optional[str] = None
+    args: List[str] = field(default_factory=list)
+    env: Dict[str, str] = field(default_factory=dict)
+    url: Optional[str] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Optional["ServerConfig"]:
+        """从配置字典构造 ServerConfig，必填字段缺失返回 None"""
+        name = data.get("name", "").strip()
+        transport_str = data.get("transport", "").strip().lower()
+        if not name or not transport_str:
+            return None
+        try:
+            transport = MCPServerType(transport_str)
+        except ValueError:
+            return None
+
+        if transport == MCPServerType.STDIO:
+            command = data.get("command", "").strip()
+            if not command:
+                return None
+            return cls(
+                name=name, transport=transport,
+                command=command,
+                args=data.get("args", []) or [],
+                env=data.get("env", {}) or {},
+            )
+        if transport in (MCPServerType.HTTP, MCPServerType.SSE):
+            url = data.get("url", "").strip()
+            if not url:
+                return None
+            return cls(
+                name=name, transport=transport,
+                url=url,
+                headers=data.get("headers", {}) or {},
+            )
+        return None
+
+
+class MCPClientManager:
+    """管理所有已注册的 MCP Server 连接与工具发现。"""
+
+    def __init__(self, config_path: Optional[Path] = None):
+        self.servers: Dict[str, ServerConfig] = {}
+        # 工具全名 -> (server_name, original_tool_name, schema)
+        self._tools: Dict[str, Tuple[str, str, Dict[str, Any]]] = {}
+        # 运行中的子进程（stdio 类型）：server_name -> Popen
+        self._processes: Dict[str, subprocess.Popen] = {}
+        self._lock = threading.Lock()
+
+        if config_path is not None:
+            self._load_config(config_path)
+
+    def _load_config(self, config_path: Path) -> None:
+        """从 JSON 配置文件加载 mcp_servers"""
+        if not config_path.exists():
+            return
+        try:
+            with open(config_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return
+        for server_data in data.get("mcp_servers", []) or []:
+            cfg = ServerConfig.from_dict(server_data)
+            if cfg is not None:
+                self.servers[cfg.name] = cfg
+
+    @staticmethod
+    def make_tool_name(server_name: str, tool_name: str) -> str:
+        """生成 MCP 工具的全名：mcp__<server>__<tool>"""
+        return f"mcp__{server_name}__{tool_name}"
+
+    def register_tool(self, server_name: str, tool_schema: Dict[str, Any]) -> None:
+        """注册一个已发现的 MCP 工具"""
+        original_name = tool_schema.get("name", "")
+        if not original_name:
+            return
+        full_name = self.make_tool_name(server_name, original_name)
+        self._tools[full_name] = (server_name, original_name, tool_schema)
+
+    def get_server_for_tool(self, full_name: str) -> Tuple[Optional[str], Optional[str]]:
+        """根据工具全名返回 (server_name, original_tool_name)，未注册返回 (None, None)"""
+        entry = self._tools.get(full_name)
+        if entry is None:
+            return (None, None)
+        return (entry[0], entry[1])
+
+    def get_openai_schemas(self) -> List[Dict[str, Any]]:
+        """生成所有 MCP 工具的 OpenAI function calling 定义"""
+        schemas = []
+        for full_name, (_, _, tool_schema) in self._tools.items():
+            schemas.append({
+                "type": "function",
+                "function": {
+                    "name": full_name,
+                    "description": tool_schema.get("description", ""),
+                    "parameters": tool_schema.get("inputSchema", {"type": "object", "properties": {}}),
+                }
+            })
+        return schemas
+
+    def list_tool_names(self) -> List[str]:
+        """返回所有已注册 MCP 工具的全名"""
+        return list(self._tools.keys())
+
+    def start_stdio_server(self, server_name: str) -> bool:
+        """启动指定 stdio 类型的 MCP Server 子进程。
+        返回 True 表示启动成功。HTTP/SSE 类型无需启动子进程。
+        """
+        cfg = self.servers.get(server_name)
+        if cfg is None or cfg.transport != MCPServerType.STDIO:
+            return False
+        with self._lock:
+            if server_name in self._processes:
+                return True  # 已启动
+            try:
+                env = {**__import__("os").environ, **cfg.env}
+                proc = subprocess.Popen(
+                    [cfg.command] + list(cfg.args),
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    env=env,
+                    text=True,
+                    encoding="utf-8",
+                    bufsize=1,
+                )
+                self._processes[server_name] = proc
+                return True
+            except Exception:
+                return False
+
+    def stop_all(self) -> None:
+        """停止所有运行中的 MCP Server 子进程"""
+        with self._lock:
+            for name, proc in self._processes.items():
+                try:
+                    proc.terminate()
+                    proc.wait(timeout=2)
+                except Exception:
+                    try:
+                        proc.kill()
+                    except Exception:
+                        pass
+            self._processes.clear()
+
+
+def create_default_manager() -> MCPClientManager:
+    """创建指向 ~/.abyss/mcp.json 的默认 MCPClientManager"""
+    return MCPClientManager(config_path=Path.home() / ".abyss" / "mcp.json")

abyss/prompts/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""
+提示词加载模块
+加载系统提示词并注入环境信息
+"""
+import os
+
+
+def load_system_prompt(project_path: str = None) -> str:
+    """加载系统提示词，注入当前环境信息。"""
+    prompt_path = os.path.join(os.path.dirname(__file__), "system_prompt.md")
+    with open(prompt_path, "r", encoding="utf-8") as f:
+        prompt = f.read()
+
+    cwd = project_path or os.getcwd()
+    prompt = prompt.replace("{{WORKING_DIR}}", cwd)
+
+    # 检测项目类型
+    if os.path.exists(os.path.join(cwd, "package.json")):
+        prompt += "\n\n项目类型: Node.js"
+    elif os.path.exists(os.path.join(cwd, "requirements.txt")):
+        prompt += "\n\n项目类型: Python"
+    elif os.path.exists(os.path.join(cwd, "Cargo.toml")):
+        prompt += "\n\n项目类型: Rust"
+
+    return prompt

abyss/session.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+"""
+会话管理
+管理一次对话会话的消息历史，支持上下文维护
+"""
+from typing import List, Dict, Any
+
+
+class Session:
+    """管理一次对话会话的消息历史，维护完整的对话上下文。"""
+
+    def __init__(self, system_prompt: str):
+        self.messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": system_prompt}
+        ]
+        self._tool_call_counter = 0
+
+    def add_user(self, content: str):
+        """添加用户消息"""
+        self.messages.append({"role": "user", "content": content})
+
+    def add_assistant(self, content: str = None, tool_calls: list = None, reasoning_content: str = None):
+        """添加助手消息（含工具调用和思考链）"""
+        msg = {"role": "assistant"}
+        if content:
+            msg["content"] = content
+        if reasoning_content:
+            msg["reasoning_content"] = reasoning_content
+        if tool_calls:
+            msg["tool_calls"] = tool_calls
+        self.messages.append(msg)
+
+    def add_tool_result(self, tool_call_id: str, content: str):
+        """添加工具执行结果"""
+        self.messages.append({
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": content
+        })
+        self._tool_call_counter += 1
+
+    def get_messages(self) -> List[Dict[str, Any]]:
+        """获取当前消息列表（用于 API 请求）"""
+        return self.messages
+
+    def get_messages_for_api(self) -> List[Dict[str, Any]]:
+        """获取发给 LLM API 的消息列表。剔除 reasoning_content 以节省 token。
+
+        reasoning_content 是 AI 自己的上次思考，AI 不需要回看旧思考。
+        协议设计参考 OpenAI/Claude 协议，reasoning_content 是单次响应的辅助字段。
+        本地审计 get_messages() 仍保留 reasoning_content。
+        """
+        result = []
+        for m in self.messages:
+            if "reasoning_content" in m:
+                m = {k: v for k, v in m.items() if k != "reasoning_content"}
+            result.append(m)
+        return result
+
+    def get_message_count(self) -> int:
+        """获取消息数量（不含 system prompt）"""
+        return len(self.messages) - 1
+
+    def get_tool_call_count(self) -> int:
+        """获取工具调用次数"""
+        return self._tool_call_counter
+
+    def clear(self):
+        """清空历史，保留 system prompt"""
+        system = self.messages[0]
+        self.messages = [system]
+        self._tool_call_counter = 0
+
+    def get_last_user_message(self) -> Dict[str, Any]:
+        """获取最后一条用户消息"""
+        for msg in reversed(self.messages):
+            if msg["role"] == "user":
+                return msg
+        return None

abyss/skills/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""
+Skills 模块
+提供 Agent Skills 加载与注入机制（SKILL.md 格式）
+"""
+from .loader import Skill, SkillLoader, create_default_loader
+
+__all__ = [
+    "Skill",
+    "SkillLoader",
+    "create_default_loader",
+]

abyss/skills/loader.py

@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""
+Skill 加载器模块
+扫描指定目录下的 SKILL.md 文件，解析 YAML frontmatter + 正文，
+支持按关键词匹配 Skill 并生成注入 System Prompt 的文本。
+
+SKILL.md 格式遵循 agentskills.io 规范：
+- name（必填，kebab-case）：唯一标识
+- description（必填）：Agent 据此判断何时加载此技能
+- version/author/tags（可选）
+
+加载策略：按需延迟加载——根据用户输入关键词匹配 description。
+"""
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Skill:
+    """单个 Agent Skill：元数据 + 正文内容。"""
+    name: str
+    description: str
+    content: str
+    path: Path = None
+    version: str = ""
+    author: str = ""
+    tags: List[str] = field(default_factory=list)
+
+
+class SkillLoader:
+    """扫描并加载 Agent Skills，支持按关键词匹配。"""
+
+    def __init__(self, skill_dirs: List[Path]):
+        self.skill_dirs = skill_dirs
+        self._skills: Dict[str, Skill] = {}
+
+    def discover(self) -> List[Skill]:
+        """递归扫描所有 SKILL.md 文件并解析。返回已加载的 Skill 列表"""
+        self._skills.clear()
+        for skill_dir in self.skill_dirs:
+            if not skill_dir.exists() or not skill_dir.is_dir():
+                continue
+            for md_file in skill_dir.rglob("SKILL.md"):
+                skill = self._parse_skill(md_file)
+                if skill is not None:
+                    self._skills[skill.name] = skill
+        return list(self._skills.values())
+
+    def _parse_skill(self, path: Path) -> Optional[Skill]:
+        """解析单个 SKILL.md：拆分 frontmatter 和正文，校验必填字段"""
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except Exception:
+            return None
+
+        frontmatter, body = self._split_frontmatter(raw)
+        if frontmatter is None:
+            return None
+
+        name = frontmatter.get("name", "").strip()
+        description = frontmatter.get("description", "").strip()
+        if not name or not description:
+            return None  # spec 要求 name 和 description 必填
+
+        return Skill(
+            name=name,
+            description=description,
+            content=body.strip(),
+            path=path.parent,
+            version=str(frontmatter.get("version", "")),
+            author=str(frontmatter.get("author", "")),
+            tags=frontmatter.get("tags", []) or [],
+        )
+
+    @staticmethod
+    def _split_frontmatter(raw: str):
+        """拆分 YAML frontmatter 和正文。返回 (dict, str)，无 frontmatter 返回 (None, raw)"""
+        if not raw.startswith("---"):
+            return None, raw
+        # 找第二个 --- 作为 frontmatter 结束
+        end_idx = raw.find("\n---", 3)
+        if end_idx == -1:
+            return None, raw
+        fm_text = raw[3:end_idx].strip()
+        body = raw[end_idx + 4:].lstrip("\n")
+        # 简单 YAML 解析（仅支持 key: value 和列表）
+        fm = {}
+        for line in fm_text.splitlines():
+            line = line.rstrip()
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith("  - "):
+                # 列表项，归到最近一个 key
+                if fm:
+                    last_key = list(fm.keys())[-1]
+                    if not isinstance(fm[last_key], list):
+                        fm[last_key] = []
+                    fm[last_key].append(line[4:].strip())
+                continue
+            if ":" in line:
+                key, _, value = line.partition(":")
+                key = key.strip()
+                value = value.strip()
+                if value:
+                    fm[key] = value
+                else:
+                    fm[key] = []  # 可能是列表开头
+        return fm, body
+
+    def get(self, name: str) -> Optional[Skill]:
+        """按名获取已加载的 Skill"""
+        return self._skills.get(name)
+
+    def list_names(self) -> List[str]:
+        """返回所有已加载 Skill 名"""
+        return list(self._skills.keys())
+
+    def match_by_keyword(self, user_input: str, limit: int = 3) -> List[Skill]:
+        """根据用户输入关键词匹配 Skill 的 description。
+        简单实现：description 中关键词出现在用户输入中即命中。
+        更复杂的语义匹配可后续用 embedding 替换。
+        """
+        matched = []
+        user_lower = user_input.lower()
+        for skill in self._skills.values():
+            desc_lower = skill.description.lower()
+            # 提取 description 中的关键词（中文按字符，英文按单词）
+            keywords = re.findall(r"[a-zA-Z]+|[\u4e00-\u9fa5]+", desc_lower)
+            hit_count = sum(1 for kw in keywords if len(kw) >= 2 and kw in user_lower)
+            if hit_count > 0:
+                matched.append((hit_count, skill))
+        # 按命中数降序
+        matched.sort(key=lambda x: x[0], reverse=True)
+        return [s for _, s in matched[:limit]]
+
+    def build_system_prompt_extension(self, active_skills: List[Skill]) -> str:
+        """生成要注入 System Prompt 的 Skill 内容，用 <skill> 标签包裹"""
+        if not active_skills:
+            return ""
+        parts = []
+        for skill in active_skills:
+            parts.append(f"<skill name='{skill.name}'>\n{skill.content}\n</skill>")
+        return "\n".join(parts)
+
+
+def create_default_loader() -> SkillLoader:
+    """创建指向 ~/.abyss/skills/ 的默认 SkillLoader"""
+    return SkillLoader([Path.home() / ".abyss" / "skills"])

abyss/tools/__init__.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+工具模块
+提供文件操作、命令执行、联网搜索等工具
+"""
+from .base import Tool
+from .file_read import FileReadTool
+from .file_write import FileWriteTool
+from .file_edit import FileEditTool
+from .shell_exec import ShellExecTool
+from .web_search import WebSearchTool
+
+__all__ = [
+    "Tool",
+    "FileReadTool",
+    "FileWriteTool",
+    "FileEditTool",
+    "ShellExecTool",
+    "WebSearchTool",
+]

abyss/tools/base.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""
+工具基类
+所有具体工具需继承此类
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class Tool(ABC):
+    """工具基类，所有具体工具需继承此类。"""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """工具名称。"""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """工具功能描述。"""
+        pass
+
+    @property
+    @abstractmethod
+    def parameters(self) -> Dict[str, Any]:
+        """工具参数 JSON Schema。"""
+        pass
+
+    @abstractmethod
+    def execute(self, **kwargs) -> Dict[str, Any]:
+        """执行工具，返回结果字典。"""
+        pass
+
+    def to_openai_schema(self) -> Dict[str, Any]:
+        """转换为 OpenAI Tool 格式。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters
+            }
+        }

abyss/tools/file_edit.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+文件编辑工具
+通过搜索替换修改文件内容
+"""
+from .base import Tool
+
+
+class FileEditTool(Tool):
+    """通过搜索替换修改文件内容的工具。"""
+
+    @property
+    def name(self) -> str:
+        return "file_edit"
+
+    @property
+    def description(self) -> str:
+        return "修改已有文件的指定内容，通过精确匹配旧字符串替换为新字符串。"
+
+    @property
+    def parameters(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "文件路径"},
+                "old_str": {"type": "string", "description": "要替换的旧内容"},
+                "new_str": {"type": "string", "description": "替换后的新内容"}
+            },
+            "required": ["path", "old_str", "new_str"]
+        }
+
+    def execute(self, path: str, old_str: str, new_str: str) -> dict:
+        """编辑文件内容"""
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            if old_str not in content:
+                return {"success": False, "error": "未找到匹配的旧内容"}
+
+            new_content = content.replace(old_str, new_str, 1)
+
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+            return {"success": True, "path": path}
+        except Exception as e:
+            return {"success": False, "error": str(e)}

abyss/tools/file_read.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""
+文件阅读工具
+读取指定文件的内容，支持指定行范围
+"""
+import os
+from .base import Tool
+
+
+class FileReadTool(Tool):
+    """读取文件内容的工具。"""
+
+    @property
+    def name(self) -> str:
+        return "file_read"
+
+    @property
+    def description(self) -> str:
+        return "读取指定文件的内容，支持指定行范围。"
+
+    @property
+    def parameters(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "文件路径"},
+                "offset": {"type": "integer", "description": "起始行号，默认1"},
+                "limit": {"type": "integer", "description": "最大读取行数"}
+            },
+            "required": ["path"]
+        }
+
+    def execute(self, path: str, offset: int = 1, limit: int = None) -> dict:
+        """读取文件内容"""
+        if not os.path.exists(path):
+            return {"success": False, "error": f"文件不存在: {path}"}
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+
+            start = max(0, offset - 1)
+            end = start + limit if limit else len(lines)
+            content = "".join(lines[start:end])
+
+            return {
+                "success": True,
+                "path": path,
+                "content": content,
+                "total_lines": len(lines),
+                "read_lines": min(end, len(lines)) - start
+            }
+        except Exception as e:
+            return {"success": False, "error": str(e)}

abyss/tools/file_write.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""
+文件写入工具
+创建新文件或覆盖写入已有文件
+"""
+import os
+from .base import Tool
+
+
+class FileWriteTool(Tool):
+    """创建或覆盖写入文件的工具。"""
+
+    @property
+    def name(self) -> str:
+        return "file_write"
+
+    @property
+    def description(self) -> str:
+        return "创建新文件或覆盖写入已有文件。"
+
+    @property
+    def parameters(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "文件路径"},
+                "content": {"type": "string", "description": "文件内容"},
+                "append": {"type": "boolean", "description": "是否追加，默认false"}
+            },
+            "required": ["path", "content"]
+        }
+
+    def execute(self, path: str, content: str, append: bool = False) -> dict:
+        """写入文件内容"""
+        try:
+            mode = "a" if append else "w"
+            os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+
+            with open(path, mode, encoding="utf-8") as f:
+                f.write(content)
+
+            return {"success": True, "path": path, "mode": "append" if append else "write"}
+        except Exception as e:
+            return {"success": False, "error": str(e)}