claxcode 0.1.1__py3-none-any.whl

claxcode/cli_completion.py

@@ -0,0 +1,174 @@
+"""Input completion for the interactive CLI (@file mentions and /commands).
+
+Built on prompt_toolkit. The file index is rebuilt lazily with a short TTL
+so completion stays cheap even on large projects; dependency/cache dirs
+(from tools.search.IGNORED_DIRS) are pruned.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.document import Document
+
+from claxcode.tools.search import IGNORED_DIRS
+
+MAX_FILES = 5000
+MAX_SUGGESTIONS = 30
+CACHE_TTL = 30.0
+
+UNSUPPORTED_FILE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+COMMAND_ARGUMENTS = {
+    "/mode": [
+        ("ask", "写操作和执行命令前逐项确认"),
+        ("auto_edit", "自动允许全部工具"),
+        ("plan", "只读规划，阻止写操作和命令执行"),
+        ("auto_safe", "允许读写，阻止命令执行"),
+        ("yolo", "不做任何限制，谨慎使用"),
+    ],
+    "/skills": [
+        ("list", "列出已加载技能"),
+        ("reload", "重新加载技能"),
+        ("create", "创建项目技能"),
+    ],
+    "/project": [("list", "列出项目"), ("switch", "切换项目"), ("info", "当前项目信息")],
+    "/memory": [
+        ("overview", "记忆总览"),
+        ("history", "当前会话历史"),
+        ("list", "长期记忆列表"),
+        ("search", "搜索长期记忆"),
+        ("export", "导出长期记忆"),
+        ("import", "导入长期记忆"),
+        ("delete", "删除长期记忆"),
+        ("learn", "添加自动记忆"),
+        ("forget", "删除自动记忆"),
+        ("facts", "自动记忆列表"),
+    ],
+    "/rollback": [("list", "列出可回滚快照")],
+}
+_AT_COMPLETION_RE = re.compile(r'(?<![A-Za-z0-9_@])@(?:"([^"]*)|([^\s，。；：、！？]*))$')
+
+
+class ProjectFileIndex:
+    """Cached list of project-relative file paths for @ completion."""
+
+    def __init__(self, root: Path):
+        self._root = root
+        self._files: list[str] = []
+        self._built_at = 0.0
+
+    def files(self) -> list[str]:
+        if time.monotonic() - self._built_at > CACHE_TTL:
+            self._rebuild()
+        return self._files
+
+    def _rebuild(self) -> None:
+        files: list[str] = []
+        stack = [self._root]
+        while stack and len(files) < MAX_FILES:
+            current = stack.pop()
+            try:
+                entries = sorted(current.iterdir())
+            except OSError:
+                continue
+            for p in entries:
+                if p.is_dir():
+                    if p.name not in IGNORED_DIRS and not p.is_symlink():
+                        stack.append(p)
+                elif p.is_file() and p.suffix.lower() not in UNSUPPORTED_FILE_SUFFIXES:
+                    files.append(str(p.relative_to(self._root)).replace("\\", "/"))
+        self._files = files
+        self._built_at = time.monotonic()
+
+
+def _fuzzy_match(needle: str, candidate: str) -> bool:
+    """Case-insensitive subsequence match (e.g. 'agt' matches 'agent.py')."""
+    it = iter(candidate.lower())
+    return all(ch in it for ch in needle.lower())
+
+
+def _file_rank(needle: str, path: str) -> tuple[int, int, str]:
+    needle_lower = needle.lower()
+    path_lower = path.lower()
+    basename = path_lower.rsplit("/", 1)[-1]
+    if not needle_lower:
+        rank = 0
+    elif path_lower == needle_lower or basename == needle_lower:
+        rank = 1
+    elif basename.startswith(needle_lower):
+        rank = 2
+    elif path_lower.startswith(needle_lower):
+        rank = 3
+    elif needle_lower in basename:
+        rank = 4
+    elif needle_lower in path_lower:
+        rank = 5
+    else:
+        rank = 6
+    return rank, len(path), path_lower
+
+
+class CliCompleter(Completer):
+    """Complete @file mentions, /slash commands, and common command arguments."""
+
+    def __init__(
+        self,
+        project_path: Path,
+        commands_provider: Callable[[], list[tuple[str, str]]],
+    ):
+        self._index = ProjectFileIndex(project_path)
+        self._commands_provider = commands_provider
+
+    def get_completions(
+        self, document: Document, _complete_event: Any
+    ) -> Iterable[Completion]:
+        text = document.text_before_cursor
+        mention = _AT_COMPLETION_RE.search(text)
+        if mention:
+            quoted, unquoted = mention.groups()
+            needle = quoted if quoted is not None else unquoted
+            needs_quote = quoted is not None and not document.text_after_cursor.startswith('"')
+            closing_quote = '"' if needs_quote else ""
+            yield from self._file_completions(needle, closing_quote)
+            return
+
+        if "\n" in text or not text.startswith("/"):
+            return
+        argument = re.fullmatch(r"(/\S+)[ \t]+([^\s]*)", text)
+        if argument:
+            yield from self._argument_completions(argument.group(1), argument.group(2))
+        elif re.fullmatch(r"/\S*", text):
+            yield from self._command_completions(text)
+
+    def _file_completions(self, needle: str, suffix: str = "") -> Iterable[Completion]:
+        candidates = [p for p in self._index.files() if not needle or _fuzzy_match(needle, p)]
+        candidates.sort(key=lambda p: _file_rank(needle, p))
+        for path in candidates[:MAX_SUGGESTIONS]:
+            yield Completion(path + suffix, start_position=-len(needle), display=path)
+
+    def _command_completions(self, needle: str) -> Iterable[Completion]:
+        needle_lower = needle.lower()
+        for name, description in self._commands_provider():
+            if name.lower().startswith(needle_lower):
+                yield Completion(
+                    name,
+                    start_position=-len(needle),
+                    display=name,
+                    display_meta=description,
+                )
+
+    def _argument_completions(self, command: str, needle: str) -> Iterable[Completion]:
+        needle_lower = needle.lower()
+        for value, description in COMMAND_ARGUMENTS.get(command.lower(), []):
+            if value.startswith(needle_lower):
+                yield Completion(
+                    value,
+                    start_position=-len(needle),
+                    display=value,
+                    display_meta=description,
+                )

claxcode/config.py

@@ -0,0 +1,54 @@
+"""Global configuration for ClaxCode."""
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Environment-driven settings."""
+
+    # App
+    app_name: str = "ClaxCode"
+    debug: bool = Field(default=False, validation_alias="CLAXCODE_DEBUG")
+
+    # LLM
+    llm_provider: str = "openai"  # openai | anthropic | generic_openai
+    llm_api_key: str = ""
+    llm_base_url: str = ""
+    llm_model: str = "gpt-4o"
+    llm_temperature: float = 0.2
+    llm_max_tokens: int = 4096
+    llm_custom_config: str = ""  # JSON string for custom provider settings
+
+    # Context
+    max_context_tokens: int = 128000
+    context_compression_threshold: float = 0.85
+
+    # Storage
+    database_url: str = "sqlite+aiosqlite:///./.claxcode/claxcode.db"
+    snapshots_dir: Path = Path("./.claxcode/snapshots")
+    project_context_file: str = "CLAUDE.md"
+
+    # Security
+    permission_mode: str = "ask"  # ask | auto_edit | plan | auto_safe | yolo
+
+    # Server
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+    # Tool Execution
+    tool_timeout: int = 60  # seconds
+
+    # Browser
+    browser_headless: bool = True  # headless mode for Playwright browser tools
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+settings = Settings()

claxcode/core/__init__.py

@@ -0,0 +1 @@
+"""Core engine for ClaxCode."""

claxcode/core/agent.py

@@ -0,0 +1,327 @@
+"""Agentic Loop controller."""
+
+import json
+from collections.abc import AsyncIterator, Awaitable, Callable
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from claxcode.config import settings
+from claxcode.core.checkpoint import CheckpointManager
+from claxcode.core.context import ContextManager
+from claxcode.core.models import get_provider
+from claxcode.extensions.hooks import HookManager
+from claxcode.extensions.skills import SkillManager
+from claxcode.memory.auto_memory import auto_memory
+from claxcode.memory.project_context import load_project_context
+from claxcode.security.audit import audit_logger
+from claxcode.security.permissions import PermissionMode, check_permission
+from claxcode.tools.base import Tool
+from claxcode.tools.execution import clear_tool_cancelled
+from claxcode.tools.registry import registry
+
+DEFAULT_SYSTEM_PROMPT = """你是 ClaxCode，一个智能编程助手。
+你帮助用户编写、编辑、调试和理解代码。
+当你需要与项目交互时，请使用提供的工具。
+始终逐步思考并解释你的推理过程。
+
+## 工作原则
+1. 先理解后行动：改代码前先用工具读懂相关实现，不臆测路径、签名和行为。
+2. 最小改动：只做任务要求的事，用最少代码、最简单实现，不顺手重构。
+3. 小步验证：每完成一个改动就验证（跑测试或读回文件），再往下走。
+4. 诚实汇报：没验证过的不要声称完成；遇到阻塞如实说明并给出下一步建议。"""
+
+
+class Agent:
+    """Main agent implementing Gather -> Think -> Act -> Verify loop."""
+
+    def __init__(
+        self,
+        session_id: UUID,
+        project_path: str = ".",
+        permission_mode: str = "ask",
+        skill_manager: SkillManager | None = None,
+        debug: bool | None = None,
+        approval_callback: Callable[[str, dict[str, Any]], Awaitable[bool]] | None = None,
+    ):
+        self.session_id = session_id
+        self.project_path = Path(project_path).resolve()
+        self.permission_mode = permission_mode
+        self.approval_callback = approval_callback
+        self.debug = settings.debug if debug is None else debug
+        self.provider = get_provider()
+        self.checkpoint = CheckpointManager()
+        self.hooks = HookManager(self.project_path)
+        self.max_iterations = 10
+
+        # Build system prompt: system-level -> project-level -> skills
+        system_prompt_path = Path.home() / ".claxcode" / "system_prompt.md"
+        if system_prompt_path.exists():
+            system = system_prompt_path.read_text(encoding="utf-8")
+        else:
+            system = DEFAULT_SYSTEM_PROMPT
+
+        project_ctx = load_project_context(self.project_path)
+        if project_ctx:
+            system += f"\n\n# Project Context\n{project_ctx}"
+
+        # Auto-load skills (built-in + user + project) if not provided
+        if skill_manager is None:
+            skill_manager = SkillManager()
+            skill_manager.load_defaults(self.project_path)
+
+        self._system_prompt_before_skills = system
+        skills_fragment = skill_manager.to_prompt_fragment()
+        if skills_fragment:
+            system += f"\n\n{skills_fragment}"
+
+        self._base_system_prompt = system
+        self.context = ContextManager(system_prompt=system)
+
+    def update_skills(self, skill_manager: SkillManager) -> None:
+        """Replace the skill fragment while preserving dynamically loaded memories."""
+        memory_suffix = self.context.system_prompt.removeprefix(self._base_system_prompt)
+        system = self._system_prompt_before_skills
+        skills_fragment = skill_manager.to_prompt_fragment()
+        if skills_fragment:
+            system += f"\n\n{skills_fragment}"
+        self._base_system_prompt = system
+        self.context.system_prompt = system + memory_suffix
+        if self.context.messages and self.context.messages[0].get("role") == "system":
+            self.context.messages[0]["content"] = self.context.system_prompt
+
+    async def _load_memories(self, user_message: str) -> None:
+        """Refresh scoped memories for each user message without duplicating them."""
+        from claxcode.memory import long_term_memory, project_memory
+
+        auto_fragment = auto_memory.to_prompt_fragment()
+        auto_prompt = f"\n\n{auto_fragment}" if auto_fragment else ""
+        fragments: list[str] = []
+        project_summary = ""
+        try:
+            project = await project_memory.get_project(str(self.project_path))
+            if project:
+                project_summary = project.get("context_summary", "").strip()
+            if project_summary:
+                fragments.append(
+                    f"\n# 项目滚动摘要（历史状态，需结合当前代码验证）\n{project_summary}"
+                )
+
+            memories = await long_term_memory.search(
+                keywords=[user_message],
+                project_path=str(self.project_path),
+                include_global=True,
+                limit=3,
+            )
+            if not memories:
+                memories = await long_term_memory.search(
+                    project_path=str(self.project_path), include_global=True, limit=2
+                )
+            lines = ["\n# 相关长期记忆（仅作历史参考，当前指令优先）"]
+            for memory in memories:
+                content = memory["compressed_content"].strip()
+                if not content or content == project_summary:
+                    continue
+                scope = "全局" if not memory["project_path"] else "项目"
+                lines.append(f"- [{scope}] {content[:400]}")
+            if len(lines) > 1:
+                fragments.append("\n".join(lines))
+        except Exception:
+            fragments = []  # 长期记忆加载失败不应阻塞主流程或全局偏好
+
+        self.context.system_prompt = self._base_system_prompt + auto_prompt + "".join(fragments)
+        if self.context.messages and self.context.messages[0].get("role") == "system":
+            self.context.messages[0]["content"] = self.context.system_prompt
+
+    async def run(self, user_message: str) -> AsyncIterator[dict]:
+        """Stream agent events."""
+        clear_tool_cancelled()
+        await self._load_memories(user_message)
+
+        yield {"type": "thinking", "content": "正在收集上下文..."}
+        self.context.add_message("user", user_message)
+
+        for iteration in range(self.max_iterations):
+            # Prepare available tools
+            available_tools = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.input_schema,
+                    },
+                }
+                for t in registry.list_tools()
+            ]
+
+            yield {"type": "thinking", "content": f"思考中... (步骤 {iteration + 1})"}
+
+            if await self._compress_context_if_needed():
+                yield {"type": "thinking", "content": "上下文过长，已压缩早期对话。"}
+
+            messages = self.context.get_messages()
+
+            # Debug: emit raw context
+            if self.debug:
+                yield {
+                    "type": "debug",
+                    "label": "发送给 LLM 的原始上下文",
+                    "payload": {
+                        "messages": messages,
+                        "tools_count": len(available_tools),
+                        "tools": [t["function"]["name"] for t in available_tools],
+                    },
+                }
+
+            content_buffer = ""
+            pending_tool_calls: list[dict] = []
+
+            async for chunk in self.provider.stream_chat(
+                messages=messages,
+                tools=available_tools if available_tools else None,
+            ):
+                if isinstance(chunk, str):
+                    content_buffer += chunk
+                    yield {"type": "message_delta", "content": chunk}
+                elif isinstance(chunk, dict) and chunk.get("type") == "tool_call":
+                    pending_tool_calls.append(chunk)
+                    yield {
+                        "type": "tool_call",
+                        "name": chunk["name"],
+                        "arguments": chunk["arguments"],
+                    }
+
+            if not pending_tool_calls:
+                # Assistant finished without tools
+                self.context.add_message("assistant", content_buffer)
+                if self.debug:
+                    yield {
+                        "type": "debug",
+                        "label": "助手响应（无工具调用）",
+                        "payload": {"content": content_buffer},
+                    }
+                yield {"type": "done"}
+                return
+
+            # ACT: execute tools
+            assistant_tool_calls = []
+            for tc in pending_tool_calls:
+                assistant_tool_calls.append(
+                    {
+                        "id": tc["id"],
+                        "type": "function",
+                        "function": {
+                            "name": tc["name"],
+                            "arguments": json.dumps(tc["arguments"]),
+                        },
+                    }
+                )
+            self.context.add_assistant_tool_calls(assistant_tool_calls)
+
+            if self.debug:
+                yield {
+                    "type": "debug",
+                    "label": "来自 LLM 的工具调用",
+                    "payload": {"tool_calls": pending_tool_calls},
+                }
+
+            for tc in pending_tool_calls:
+                name = tc["name"]
+                args = tc["arguments"]
+                yield {"type": "tool_result_start", "name": name}
+
+                result = await self._execute_tool(name, args)
+                yield {"type": "tool_result", "name": name, "output": result}
+                self.context.add_tool_result(tc["id"], name, result)
+
+                if self.debug:
+                    yield {
+                        "type": "debug",
+                        "label": f"工具结果: {name}",
+                        "payload": {"arguments": args, "result": result},
+                    }
+
+            # VERIFY: lightweight step (just a thinking marker)
+            yield {"type": "thinking", "content": "正在验证结果..."}
+
+        yield {"type": "done", "warning": "已达到最大迭代次数"}
+
+    async def _execute_tool(self, name: str, args: dict[str, Any]) -> str:
+        tool = registry.get(name)
+        if tool is None:
+            return f"错误：工具 '{name}' 不存在"
+
+        allowed, reason = await self._check_tool_permission(tool, args)
+        if not allowed:
+            audit_logger.log_tool_call(
+                self.session_id, name, args, f"已阻止: {reason}", allowed=False
+            )
+            return f"[权限阻止] 工具 '{name}': {reason}"
+
+        hook_ok, hook_reason = await self.hooks.run_pre(name, args)
+        if not hook_ok:
+            audit_logger.log_tool_call(
+                self.session_id, name, args, f"钩子阻止: {hook_reason}", allowed=False
+            )
+            return f"[钩子阻止] 工具 '{name}': {hook_reason}"
+
+        # Snapshot before file edits (kept in every mode for rollback safety)
+        if "write" in tool.required_permissions and "path" in args:
+            await self.checkpoint.snapshot(self.session_id, args["path"])
+
+        try:
+            result = await tool.execute(**args)
+        except Exception as exc:
+            result = f"执行 {name} 时出错: {exc}"
+
+        hook_output = await self.hooks.run_post(name, args, result)
+        if hook_output:
+            result += f"\n\n[Hook 输出]\n{hook_output}"
+
+        audit_logger.log_tool_call(self.session_id, name, args, result, allowed=True)
+        return result
+
+    async def _check_tool_permission(self, tool: Tool, args: dict[str, Any]) -> tuple[bool, str]:
+        """Check the permission mode; in ask mode consult the approval callback."""
+        try:
+            mode = PermissionMode(self.permission_mode)
+        except ValueError:
+            mode = PermissionMode.ASK
+
+        allowed, reason = check_permission(mode, tool.name, tool.required_permissions)
+        if allowed:
+            return True, ""
+        if mode == PermissionMode.ASK and self.approval_callback is not None:
+            if await self.approval_callback(tool.name, args):
+                return True, ""
+            reason = "用户拒绝了执行"
+        return False, reason
+
+    async def _compress_context_if_needed(self) -> bool:
+        """Replace the oldest half of the history with a summary when over threshold."""
+        if not self.context.over_threshold():
+            return False
+        removed = self.context.pop_oldest(max(1, len(self.context.messages) // 2))
+        summary = await self._summarize_messages(removed)
+        self.context.insert_summary(summary)
+        return True
+
+    async def _summarize_messages(self, messages: list[dict[str, Any]]) -> str:
+        """Summarize dropped messages with the LLM; fall back to a placeholder."""
+        lines = [f"{m.get('role')}: {str(m.get('content', ''))[:500]}" for m in messages]
+        prompt = (
+            "请用中文简要总结以下早期对话的关键信息（用户目标、已完成的工作、"
+            "重要文件路径和结论），200 字以内：\n\n" + "\n".join(lines)[:8000]
+        )
+        summary = ""
+        try:
+            async for chunk in self.provider.stream_chat(
+                messages=[{"role": "user", "content": prompt}], tools=None
+            ):
+                if isinstance(chunk, str):
+                    summary += chunk
+        except Exception:
+            summary = ""
+        summary = summary.strip() or f"[已省略 {len(messages)} 条早期对话消息]"
+        return f"[早期对话摘要]\n{summary}"

claxcode/core/checkpoint.py

@@ -0,0 +1,100 @@
+"""Pre-edit snapshot and rollback system."""
+
+import asyncio
+import json
+import shutil
+from contextlib import suppress
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from claxcode.config import settings
+
+
+class CheckpointManager:
+    """Creates filesystem snapshots before edits and restores them on demand."""
+
+    def __init__(self) -> None:
+        self.base_dir = settings.snapshots_dir
+
+    def _session_snapshot_dir(self, session_id: UUID) -> Path:
+        ts = datetime.now(UTC).strftime("%Y%m%d_%H%M%S_%f")
+        return self.base_dir / str(session_id) / ts
+
+    async def snapshot(self, session_id: UUID, file_path: str) -> Path:
+        """Copy file to snapshot directory before editing."""
+        target = Path(file_path)
+        if not target.exists():
+            return Path()
+        snap_dir = self._session_snapshot_dir(session_id)
+        while snap_dir.exists():  # same-microsecond collision: wait for a fresh timestamp
+            await asyncio.sleep(0.001)
+            snap_dir = self._session_snapshot_dir(session_id)
+        snap_dir.mkdir(parents=True, exist_ok=True)
+        dest = snap_dir / target.name
+        shutil.copy2(target, dest)
+        self._write_manifest(snap_dir, target)
+        return dest
+
+    def _write_manifest(self, snap_dir: Path, target: Path) -> None:
+        """Record the original path of each snapshotted file."""
+        manifest = snap_dir / "manifest.json"
+        data: dict[str, str] = {}
+        if manifest.exists():
+            with suppress(json.JSONDecodeError, OSError):
+                data = json.loads(manifest.read_text(encoding="utf-8"))
+        data[target.name] = str(target.resolve())
+        manifest.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def _read_manifest(self, snap_dir: Path) -> dict[str, str]:
+        manifest = snap_dir / "manifest.json"
+        if not manifest.exists():
+            return {}
+        with suppress(json.JSONDecodeError, OSError):
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                return data
+        return {}
+
+    def list_snapshots(self, session_id: UUID, limit: int = 10) -> list[dict[str, Any]]:
+        """Most recent snapshot batches, newest first."""
+        if limit < 1:
+            return []
+        session_dir = self.base_dir / str(session_id)
+        if not session_dir.exists():
+            return []
+        entries = []
+        for snap_dir in sorted(session_dir.iterdir(), reverse=True):
+            if not snap_dir.is_dir():
+                continue
+            files = list(self._read_manifest(snap_dir).values())
+            if not files:  # legacy snapshots without a manifest
+                files = [
+                    f.name for f in snap_dir.iterdir() if f.is_file() and f.name != "manifest.json"
+                ]
+            entries.append({"timestamp": snap_dir.name, "files": files})
+            if len(entries) >= limit:
+                break
+        return entries
+
+    def restore(self, session_id: UUID, steps: int = 1) -> list[str]:
+        """Restore files from the `steps` most recent snapshots.
+
+        For each file the oldest copy wins, so the file returns to its state
+        before all of the rolled-back actions. Returns restored paths.
+        """
+        batches = self.list_snapshots(session_id, limit=steps)
+        restored: list[str] = []
+        for batch in reversed(batches):  # oldest batch first
+            snap_dir = self.base_dir / str(session_id) / batch["timestamp"]
+            for name, original in self._read_manifest(snap_dir).items():
+                if original in restored:
+                    continue
+                src = snap_dir / name
+                if not src.exists():
+                    continue
+                Path(original).parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, original)
+                restored.append(original)
+        return restored