claxcode 0.1.1__py3-none-any.whl

claxcode/extensions/mcp.py

@@ -0,0 +1,13 @@
+"""MCP (Model Context Protocol) connector (stub for Phase 5)."""
+
+from typing import Any
+
+
+class MCPClient:
+    """Client for connecting to MCP servers."""
+
+    def __init__(self, server_url: str):
+        self.server_url = server_url
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        return []

claxcode/extensions/plugins.py

@@ -0,0 +1,10 @@
+"""Plugin system (stub for Phase 5)."""
+
+from pathlib import Path
+
+
+class PluginManager:
+    """Load and manage cross-project plugins."""
+
+    def load_plugin(self, path: Path) -> None:
+        pass

claxcode/extensions/skills.py

@@ -0,0 +1,205 @@
+"""Skills system — load and inject skill packages into agent context.
+
+Inspired by Claude Code's Skills. A skill is a directory containing a SKILL.md
+file that describes capabilities, conventions, and commands. The SKILL.md content
+is injected into the agent's system prompt.
+
+Skill directory layout:
+    my-skill/
+        SKILL.md          # Required: name, description, instructions
+        tools.py          # Optional: skill-specific tools (auto-registered)
+        (optional files)  # Templates, scripts, or reference docs
+
+SKILL.md format:
+    # Skill Name
+
+    ## Description
+    Brief explanation of what this skill does.
+
+    ## Instructions
+    Detailed instructions for the agent on how to use this skill.
+    Can include examples, conventions, file patterns, etc.
+
+    ## Commands (optional)
+    - `cmd_name`: Description of what this command does
+
+Skill sources (later overrides earlier on name conflict):
+    builtin  — shipped inside the package at claxcode/skills/
+    user     — ~/.claxcode/skills/ and ~/.agent/skills/
+    project  — <project>/.claxcode/skills/, <project>/.agent/skills/ and <project>/skills/
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from claxcode.tools.registry import registry
+
+BUILTIN_SKILLS_DIR = Path(__file__).resolve().parent.parent / "skills"
+
+
+@dataclass
+class Skill:
+    """A loaded skill package."""
+
+    name: str
+    description: str
+    content: str          # Full SKILL.md text
+    commands: list[dict[str, str]]  # Optional custom commands
+    path: Path            # Directory containing the skill
+    source: str = "project"  # builtin | user | project
+    registered_tools: list[str] = field(default_factory=list)
+
+
+class SkillManager:
+    """Load and manage skill packages."""
+
+    def __init__(self) -> None:
+        self.skills: list[Skill] = []
+        self._skill_dirs: list[tuple[Path, str]] = []
+
+    def load_defaults(self, project_path: Path) -> None:
+        """Load built-in, user-global, then project skills.
+
+        Later sources override earlier ones when skill names collide.
+        """
+        self.load_skill_dir(BUILTIN_SKILLS_DIR, source="builtin")
+        self.load_skill_dir(Path.home() / ".claxcode" / "skills", source="user")
+        self.load_skill_dir(Path.home() / ".agent" / "skills", source="user")
+        self.load_skill_dir(project_path / ".claxcode" / "skills", source="project")
+        self.load_skill_dir(project_path / ".agent" / "skills", source="project")
+        self.load_skill_dir(project_path / "skills", source="project")
+
+    def load_skill_dir(self, path: Path, source: str = "project") -> None:
+        """Scan a directory for skill packages and load them."""
+        if not path.exists():
+            return
+        if (path, source) not in self._skill_dirs:
+            self._skill_dirs.append((path, source))
+        for entry in sorted(path.iterdir()):
+            if entry.is_dir() and (entry / "SKILL.md").exists():
+                self._load_skill(entry, source)
+
+    def _load_skill(self, skill_dir: Path, source: str) -> None:
+        """Parse and register a single skill, replacing any same-name skill."""
+        skill = self._parse_skill_md(skill_dir, source)
+        self._remove_skill(skill.name)  # unregister tools of the overridden skill
+        self._load_skill_tools(skill_dir, skill)
+        self.skills.append(skill)
+
+    def _parse_skill_md(self, skill_dir: Path, source: str) -> Skill:
+        """Parse SKILL.md into a Skill (no side effects)."""
+        raw = (skill_dir / "SKILL.md").read_text(encoding="utf-8")
+
+        name = skill_dir.name
+        description = ""
+        commands: list[dict[str, str]] = []
+
+        # Simple parsing: extract first H1 as name, first paragraph as description
+        lines = raw.splitlines()
+        for i, line in enumerate(lines):
+            if line.startswith("# ") and name == skill_dir.name:
+                name = line[2:].strip()
+            if line.lower().startswith("## description"):
+                # Collect following paragraph
+                for j in range(i + 1, len(lines)):
+                    if lines[j].strip() and not lines[j].startswith("##"):
+                        description = lines[j].strip()
+                        break
+            if line.lower().startswith("## commands"):
+                # Parse command list
+                for j in range(i + 1, len(lines)):
+                    cmd_line = lines[j].strip()
+                    if cmd_line.startswith("##"):
+                        break
+                    if cmd_line.startswith("- "):
+                        cmd_text = cmd_line[2:].strip()
+                        if ":" in cmd_text:
+                            cmd_name, cmd_desc = cmd_text.split(":", 1)
+                            cmd_label = cmd_name.strip().strip("`")
+                            commands.append({"name": cmd_label, "description": cmd_desc.strip()})
+
+        if not description:
+            # Fallback: first non-empty, non-header line
+            for line in lines:
+                stripped = line.strip()
+                if stripped and not stripped.startswith("#"):
+                    description = stripped
+                    break
+
+        return Skill(
+            name=name,
+            description=description,
+            content=raw,
+            commands=commands,
+            path=skill_dir,
+            source=source,
+        )
+
+    def _load_skill_tools(self, skill_dir: Path, skill: Skill) -> None:
+        """Dynamically load tools.py from a skill directory."""
+        tools_file = skill_dir / "tools.py"
+        if not tools_file.exists():
+            return
+
+        before = set(registry._tools.keys())
+        code = tools_file.read_text(encoding="utf-8")
+        namespace = {
+            "__name__": f"claxcode_skill_{skill.name}",
+            "__file__": str(tools_file),
+        }
+        exec(compile(code, str(tools_file), "exec"), namespace)  # noqa: S102
+        after = set(registry._tools.keys())
+        skill.registered_tools = sorted(after - before)
+
+    def _remove_skill(self, name: str) -> bool:
+        """Remove a skill by name and unregister its tools."""
+        for i, skill in enumerate(self.skills):
+            if skill.name == name:
+                for tool_name in skill.registered_tools:
+                    registry.unregister(tool_name)
+                self.skills.pop(i)
+                return True
+        return False
+
+    def unload_skill(self, name: str) -> bool:
+        """Unload a skill and unregister its tools."""
+        return self._remove_skill(name)
+
+    def reload_all(self) -> tuple[int, int]:
+        """Unload all skills and reload from all known directories.
+
+        Returns (skills_loaded, tools_registered).
+        """
+        for skill in self.skills:
+            for tool_name in skill.registered_tools:
+                registry.unregister(tool_name)
+        self.skills.clear()
+
+        for path, source in self._skill_dirs:
+            self.load_skill_dir(path, source)
+        return len(self.skills), sum(len(s.registered_tools) for s in self.skills)
+
+    def to_prompt_fragment(self) -> str:
+        """Convert all loaded skills into a system-prompt fragment."""
+        if not self.skills:
+            return ""
+        lines = ["# Skills"]
+        for skill in self.skills:
+            lines.append(f"\n## {skill.name}")
+            lines.append(skill.content)
+        return "\n".join(lines)
+
+    def get_skill_commands(self) -> list[dict[str, str]]:
+        """Return all custom commands defined across skills (with source skill)."""
+        cmds = []
+        for skill in self.skills:
+            for cmd in skill.commands:
+                cmds.append({**cmd, "skill": skill.name})
+        return cmds
+
+    def find_command(self, name: str) -> dict[str, str] | None:
+        """Find a skill command by name (without the leading slash)."""
+        for cmd in self.get_skill_commands():
+            if cmd["name"] == name:
+                return cmd
+        return None

claxcode/main.py

@@ -0,0 +1,55 @@
+"""FastAPI application entry point."""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import PlainTextResponse
+
+# Ensure all built-in tools are registered before API starts
+import claxcode.tools  # noqa: F401
+from claxcode.api import chat, session, subagents, tools
+from claxcode.config import settings
+from claxcode.memory.session_store import init_db
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan events."""
+    # Startup
+    await init_db()
+    yield
+    # Shutdown
+
+
+app = FastAPI(
+    title=settings.app_name,
+    description="Agentic coding assistant API",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.include_router(session.router, prefix="/sessions", tags=["sessions"])
+app.include_router(chat.router, prefix="/sessions", tags=["chat"])
+app.include_router(tools.router, prefix="/tools", tags=["tools"])
+app.include_router(subagents.router, prefix="/subagents", tags=["subagents"])
+
+
+@app.get("/health", response_class=PlainTextResponse)
+async def health():
+    return "ok"
+
+
+def run() -> None:
+    """CLI entry point to start the server."""
+    import uvicorn
+
+    uvicorn.run(
+        "claxcode.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug,
+    )
+
+
+if __name__ == "__main__":
+    run()

claxcode/memory/__init__.py

@@ -0,0 +1,23 @@
+"""Memory system for ClaxCode."""
+
+from claxcode.memory.long_term import LongTermMemory, long_term_memory
+from claxcode.memory.project_memory import ProjectMemory, project_memory
+from claxcode.memory.session_store import (
+    LongTermMemoryORM,
+    ProjectMemoryORM,
+    SessionORM,
+    get_db_session,
+    init_db,
+)
+
+__all__ = [
+    "long_term_memory",
+    "LongTermMemory",
+    "project_memory",
+    "ProjectMemory",
+    "init_db",
+    "get_db_session",
+    "SessionORM",
+    "LongTermMemoryORM",
+    "ProjectMemoryORM",
+]

claxcode/memory/auto_memory.py

@@ -0,0 +1,68 @@
+"""Auto-memory for learned facts and preferences (durable JSON store)."""
+
+import json
+from pathlib import Path
+
+DEFAULT_STORE_PATH = Path.home() / ".claxcode" / "auto_memory.json"
+
+
+class AutoMemory:
+    """Stores stable global user preferences and facts in a JSON file."""
+
+    def __init__(self, store_path: Path | None = None, limit: int = 50):
+        self._store_path = store_path or DEFAULT_STORE_PATH
+        self._limit = limit
+        self._memories: dict[str, str] = self._load()
+
+    def remember(self, key: str, value: str) -> str:
+        """Record or update a fact. Returns a human-readable status."""
+        if key not in self._memories and len(self._memories) >= self._limit:
+            return f"记忆已满（{self._limit} 条上限），请先清理其他条目"
+        self._memories[key] = value
+        self._save()
+        return f"已记住: {key}"
+
+    def recall(self, key: str) -> str | None:
+        return self._memories.get(key)
+
+    def forget(self, key: str) -> bool:
+        """Delete a fact. Returns True if it existed."""
+        if key not in self._memories:
+            return False
+        del self._memories[key]
+        self._save()
+        return True
+
+    def items(self) -> dict[str, str]:
+        return dict(self._memories)
+
+    def to_prompt_fragment(self) -> str:
+        if not self._memories:
+            return ""
+        lines = ["# 全局用户偏好与事实（自动记忆）"]
+        for k, v in self._memories.items():
+            lines.append(f"- {k}: {v}")
+        return "\n".join(lines)
+
+    def _load(self) -> dict[str, str]:
+        if not self._store_path.exists():
+            return {}
+        try:
+            data = json.loads(self._store_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+        return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {}
+
+    def _save(self) -> None:
+        try:
+            self._store_path.parent.mkdir(parents=True, exist_ok=True)
+            self._store_path.write_text(
+                json.dumps(self._memories, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+        except OSError:
+            pass  # 记忆写入失败不应阻塞主流程
+
+
+# Global singleton shared by the agent prompt, the remember_fact tool and the CLI.
+auto_memory = AutoMemory()

claxcode/memory/long_term.py

@@ -0,0 +1,196 @@
+"""Searchable long-term memories with project and global scopes."""
+
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from sqlalchemy import desc, or_, select
+
+from claxcode.memory.session_store import LongTermMemoryORM, get_db_session
+
+_STOP_TERMS = {
+    "我们", "你们", "他们", "这个", "那个", "可以", "怎么", "什么", "一下",
+    "帮我", "谢谢", "现在", "还是", "就是", "因为", "所以", "如果", "已经", "继续",
+}
+
+
+def _normalize_project_path(project_path: str) -> str:
+    return str(Path(project_path).resolve()) if project_path else ""
+
+
+def _search_terms(keywords: list[str] | None) -> list[str]:
+    """Build searchable words and Chinese bigrams without external tokenizers."""
+    if not keywords:
+        return []
+    terms: set[str] = set()
+    for token in re.findall(r"[a-z0-9_]+|[\u4e00-\u9fff]+", " ".join(keywords).lower()):
+        if re.fullmatch(r"[a-z0-9_]+", token):
+            if len(token) >= 2:
+                terms.add(token)
+            continue
+        if len(token) <= 6 and token not in _STOP_TERMS:
+            terms.add(token)
+        terms.update(
+            token[i:i + 2]
+            for i in range(len(token) - 1)
+            if token[i:i + 2] not in _STOP_TERMS
+        )
+    return sorted(terms, key=lambda term: (-len(term), term))[:60]
+
+
+def _relevance(memory: LongTermMemoryORM, terms: list[str]) -> int:
+    text = f"{memory.keywords}\n{memory.compressed_content}".lower()
+    return sum(len(term) if len(term) > 2 else 1 for term in terms if term in text)
+
+
+def _to_dict(memory: LongTermMemoryORM, truncate: bool = False) -> dict[str, Any]:
+    content = memory.compressed_content
+    if truncate and len(content) > 200:
+        content = content[:200] + "..."
+    return {
+        "id": memory.id,
+        "session_id": memory.session_id,
+        "timestamp": memory.timestamp.isoformat(),
+        "keywords": json.loads(memory.keywords) if memory.keywords else [],
+        "compressed_content": content,
+        "project_path": memory.project_path,
+    }
+
+
+class LongTermMemory:
+    """Manage searchable project memories and cross-project global memories."""
+
+    async def save(
+        self,
+        session_id: str,
+        compressed_content: str,
+        keywords: list[str],
+        project_path: str = "",
+    ) -> str:
+        """Save a memory; an empty project_path means global scope."""
+        content = compressed_content.strip()
+        if not content:
+            raise ValueError("记忆内容不能为空")
+        memory_id = str(uuid4())
+        normalized_keywords = list(dict.fromkeys(k.strip() for k in keywords if k.strip()))
+        async for db in get_db_session():
+            memory = LongTermMemoryORM(
+                id=memory_id,
+                session_id=session_id,
+                timestamp=datetime.now(UTC),
+                keywords=json.dumps(normalized_keywords, ensure_ascii=False),
+                compressed_content=content,
+                project_path=_normalize_project_path(project_path),
+            )
+            db.add(memory)
+            await db.commit()
+            return memory_id
+        return memory_id
+
+    async def search(
+        self,
+        keywords: list[str] | None = None,
+        project_path: str | None = None,
+        limit: int = 10,
+        include_global: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Search by relevance within a project, optionally including global memories."""
+        terms = _search_terms(keywords)
+        normalized_path = _normalize_project_path(project_path or "")
+        async for db in get_db_session():
+            query = select(LongTermMemoryORM).order_by(desc(LongTermMemoryORM.timestamp))
+            if normalized_path:
+                if include_global:
+                    query = query.where(
+                        or_(
+                            LongTermMemoryORM.project_path == normalized_path,
+                            LongTermMemoryORM.project_path == "",
+                        )
+                    )
+                else:
+                    query = query.where(LongTermMemoryORM.project_path == normalized_path)
+
+            result = await db.execute(query.limit(200 if terms else limit))
+            memories = list(result.scalars().all())
+            if terms:
+                memories = [m for m in memories if _relevance(m, terms) > 0]
+                memories.sort(key=lambda m: _relevance(m, terms), reverse=True)
+            return [_to_dict(m) for m in memories[:limit]]
+        return []
+
+    async def list_all(
+        self,
+        limit: int = 50,
+        project_path: str | None = None,
+        include_global: bool = False,
+    ) -> list[dict[str, Any]]:
+        """List recent memories, optionally restricted to project and global scopes."""
+        normalized_path = _normalize_project_path(project_path or "")
+        async for db in get_db_session():
+            query = select(LongTermMemoryORM).order_by(desc(LongTermMemoryORM.timestamp))
+            if normalized_path:
+                if include_global:
+                    query = query.where(
+                        or_(
+                            LongTermMemoryORM.project_path == normalized_path,
+                            LongTermMemoryORM.project_path == "",
+                        )
+                    )
+                else:
+                    query = query.where(LongTermMemoryORM.project_path == normalized_path)
+            result = await db.execute(query.limit(limit))
+            return [_to_dict(m, truncate=True) for m in result.scalars().all()]
+        return []
+
+    async def delete(self, memory_id: str) -> bool:
+        """Delete a memory by ID."""
+        async for db in get_db_session():
+            result = await db.execute(
+                select(LongTermMemoryORM).where(LongTermMemoryORM.id == memory_id)
+            )
+            memory = result.scalar_one_or_none()
+            if memory:
+                await db.delete(memory)
+                await db.commit()
+                return True
+            return False
+        return False
+
+    async def export_to_file(self, filepath: str, project_path: str | None = None) -> int:
+        """Export memories to JSON."""
+        memories = await self.search(project_path=project_path, limit=1000)
+        export_data = {
+            "export_time": datetime.now(UTC).isoformat(),
+            "memories": memories,
+        }
+        Path(filepath).write_text(
+            json.dumps(export_data, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        return len(memories)
+
+    async def import_from_file(self, filepath: str) -> int:
+        """Import memories from JSON without reusing their original IDs."""
+        data = json.loads(Path(filepath).read_text(encoding="utf-8"))
+        memories = data.get("memories", [])
+        count = 0
+        async for db in get_db_session():
+            for item in memories:
+                memory = LongTermMemoryORM(
+                    id=str(uuid4()),
+                    session_id=item.get("session_id", ""),
+                    timestamp=datetime.fromisoformat(item["timestamp"]),
+                    keywords=json.dumps(item.get("keywords", []), ensure_ascii=False),
+                    compressed_content=item.get("compressed_content", ""),
+                    project_path=_normalize_project_path(item.get("project_path", "")),
+                )
+                db.add(memory)
+                count += 1
+            await db.commit()
+        return count
+
+
+long_term_memory = LongTermMemory()

claxcode/memory/project_context.py

@@ -0,0 +1,20 @@
+"""Project-level context loading."""
+
+from pathlib import Path
+
+from claxcode.config import settings
+
+
+def load_project_context(project_path: Path) -> str:
+    """Load CLAUDE.md or .claxcode/context.md if present."""
+    candidates = [
+        project_path / settings.project_context_file,
+        project_path / ".claxcode" / "context.md",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            try:
+                return candidate.read_text(encoding="utf-8")
+            except Exception:
+                continue
+    return ""