claxcode 0.1.1__py3-none-any.whl

claxcode/memory/project_memory.py

@@ -0,0 +1,194 @@
+"""项目记忆管理器 - 项目级别存储."""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from claxcode.memory.session_store import ProjectMemoryORM, get_db_session
+
+
+class ProjectMemory:
+    """管理项目级别记忆."""
+
+    async def init_project(
+        self,
+        project_path: str,
+        config: dict[str, Any],
+    ) -> str:
+        """初始化项目记忆.
+
+        Args:
+            project_path: 项目路径
+            config: 项目配置信息
+
+        Returns:
+            项目记忆ID
+        """
+        # 确保路径标准化
+        project_path = str(Path(project_path).resolve())
+
+        async for db in get_db_session():
+            db: AsyncSession
+            # 检查是否已存在
+            result = await db.execute(
+                select(ProjectMemoryORM).where(ProjectMemoryORM.project_path == project_path)
+            )
+            existing = result.scalar_one_or_none()
+
+            if existing:
+                # 更新现有配置
+                existing.config = json.dumps(config, ensure_ascii=False)
+                existing.updated_at = datetime.now(UTC)
+                await db.commit()
+                return existing.id
+            else:
+                # 创建新的项目记忆
+                memory_id = str(uuid4())
+                memory = ProjectMemoryORM(
+                    id=memory_id,
+                    project_path=project_path,
+                    initialized_at=datetime.now(UTC),
+                    config=json.dumps(config, ensure_ascii=False),
+                    context_summary="",
+                    updated_at=datetime.now(UTC),
+                )
+                db.add(memory)
+                await db.commit()
+                return memory_id
+
+    async def get_project(self, project_path: str) -> dict[str, Any] | None:
+        """获取项目记忆.
+
+        Args:
+            project_path: 项目路径
+
+        Returns:
+            项目记忆信息，不存在则返回 None
+        """
+        project_path = str(Path(project_path).resolve())
+
+        async for db in get_db_session():
+            db: AsyncSession
+            result = await db.execute(
+                select(ProjectMemoryORM).where(ProjectMemoryORM.project_path == project_path)
+            )
+            memory = result.scalar_one_or_none()
+
+            if memory:
+                return {
+                    "id": memory.id,
+                    "project_path": memory.project_path,
+                    "initialized_at": memory.initialized_at.isoformat(),
+                    "config": json.loads(memory.config) if memory.config else {},
+                    "context_summary": memory.context_summary,
+                    "updated_at": memory.updated_at.isoformat(),
+                }
+            return None
+
+    async def update_summary(self, project_path: str, summary: str) -> bool:
+        """更新项目上下文摘要.
+
+        Args:
+            project_path: 项目路径
+            summary: 摘要内容
+
+        Returns:
+            是否成功更新
+        """
+        project_path = str(Path(project_path).resolve())
+
+        async for db in get_db_session():
+            db: AsyncSession
+            result = await db.execute(
+                select(ProjectMemoryORM).where(ProjectMemoryORM.project_path == project_path)
+            )
+            memory = result.scalar_one_or_none()
+
+            now = datetime.now(UTC)
+            if memory is None:
+                memory = ProjectMemoryORM(
+                    id=str(uuid4()),
+                    project_path=project_path,
+                    initialized_at=now,
+                    config="",
+                    context_summary=summary,
+                    updated_at=now,
+                )
+                db.add(memory)
+            else:
+                memory.context_summary = summary
+                memory.updated_at = now
+            await db.commit()
+            return True
+
+    async def list_all_projects(self, limit: int = 100) -> list[dict[str, Any]]:
+        """列出所有项目.
+
+        Args:
+            limit: 返回数量限制
+
+        Returns:
+            项目列表
+        """
+        async for db in get_db_session():
+            db: AsyncSession
+            result = await db.execute(
+                select(ProjectMemoryORM)
+                .order_by(ProjectMemoryORM.updated_at.desc())
+                .limit(limit)
+            )
+            memories = result.scalars().all()
+            return [
+                {
+                    "id": m.id,
+                    "project_path": m.project_path,
+                    "name": Path(m.project_path).name,
+                    "initialized_at": m.initialized_at.isoformat(),
+                    "updated_at": m.updated_at.isoformat(),
+                    "has_summary": bool(m.context_summary),
+                }
+                for m in memories
+            ]
+
+    def generate_context_md(self, config: dict[str, Any]) -> str:
+        """生成 CLAUDE.md 文件内容.
+
+        Args:
+            config: 项目配置
+
+        Returns:
+            Markdown 格式的项目上下文
+        """
+        lines = [
+            f"# {config.get('name', '未命名项目')}",
+            "",
+            "## 项目描述",
+            config.get('description', ''),
+            "",
+            "## 技术栈",
+            config.get('tech_stack', ''),
+            "",
+            "## 常用命令",
+            "",
+            "### 构建",
+            f"```bash\n{config.get('build_command', '')}\n```",
+            "",
+            "### 测试",
+            f"```bash\n{config.get('test_command', '')}\n```",
+            "",
+            "## 代码风格",
+            config.get('code_style', ''),
+            "",
+            "## 其他说明",
+            config.get('notes', ''),
+        ]
+        return "\n".join(lines)
+
+
+# 全局实例
+project_memory = ProjectMemory()

claxcode/memory/session_store.py

@@ -0,0 +1,206 @@
+"""SQLite persistence for sessions using SQLAlchemy async."""
+
+import json
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import DateTime, String, Text, select
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from claxcode.config import settings
+from claxcode.models.subagent import SubagentStatus, SubagentTask
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class SessionORM(Base):
+    __tablename__ = "sessions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), default="新会话")
+    project_path: Mapped[str] = mapped_column(String(512), default=".")
+    permission_mode: Mapped[str] = mapped_column(String(32), default="ask")
+    messages: Mapped[str] = mapped_column(Text, default="[]")
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+    )
+
+
+class SubagentTaskORM(Base):
+    __tablename__ = "subagent_tasks"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    session_id: Mapped[str] = mapped_column(String(36), default="")
+    agent_type: Mapped[str] = mapped_column(String(32), default="explore")
+    instruction: Mapped[str] = mapped_column(Text, default="")
+    status: Mapped[str] = mapped_column(String(32), default="pending")
+    result: Mapped[str] = mapped_column(Text, default="")
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+
+class LongTermMemoryORM(Base):
+    """长期记忆表 - 全局记忆存储"""
+    __tablename__ = "long_term_memories"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    session_id: Mapped[str] = mapped_column(String(36), default="")
+    timestamp: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+    keywords: Mapped[str] = mapped_column(Text, default="")  # JSON 格式存储关键词列表
+    compressed_content: Mapped[str] = mapped_column(Text, default="")  # 压缩后的核心内容
+    project_path: Mapped[str] = mapped_column(String(512), default="")
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+
+
+class ProjectMemoryORM(Base):
+    """项目记忆表 - 项目级别存储"""
+    __tablename__ = "project_memories"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    project_path: Mapped[str] = mapped_column(String(512), unique=True, index=True)
+    initialized_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+    config: Mapped[str] = mapped_column(Text, default="")  # JSON 格式存储项目配置
+    context_summary: Mapped[str] = mapped_column(Text, default="")  # 项目上下文摘要
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+    )
+
+
+_engine = None
+_session_maker = None
+
+
+def _get_engine() -> AsyncEngine:
+    global _engine
+    if _engine is None:
+        _engine = create_async_engine(settings.database_url, echo=settings.debug)
+    return _engine
+
+
+def _get_session_maker() -> async_sessionmaker[AsyncSession]:
+    global _session_maker
+    if _session_maker is None:
+        _session_maker = async_sessionmaker(_get_engine(), expire_on_commit=False)
+    return _session_maker
+
+
+async def init_db() -> None:
+    """Initialize database tables."""
+    # Ensure parent directory exists for SQLite file
+    if settings.database_url.startswith("sqlite"):
+        db_path = settings.database_url.replace("sqlite+aiosqlite:///", "").replace(
+            "sqlite:///", ""
+        )
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    engine = _get_engine()
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+async def get_db_session() -> AsyncIterator[AsyncSession]:
+    """Yield an async DB session."""
+    async with _get_session_maker()() as session:
+        yield session
+
+
+def _orm_to_subagent_task(row: SubagentTaskORM) -> SubagentTask:
+    return SubagentTask(
+        id=UUID(row.id),
+        session_id=UUID(row.session_id),
+        agent_type=row.agent_type,
+        instruction=row.instruction,
+        status=SubagentStatus(row.status),
+        result=row.result,
+        created_at=row.created_at,
+        completed_at=row.completed_at,
+    )
+
+
+async def create_subagent_task(task: SubagentTask) -> None:
+    """Persist a new subagent task."""
+    async with _get_session_maker()() as db:
+        db.add(
+            SubagentTaskORM(
+                id=str(task.id),
+                session_id=str(task.session_id),
+                agent_type=task.agent_type,
+                instruction=task.instruction,
+                status=task.status.value,
+                result=task.result,
+                created_at=task.created_at,
+                completed_at=task.completed_at,
+            )
+        )
+        await db.commit()
+
+
+async def get_subagent_task(task_id: UUID) -> SubagentTask | None:
+    """Load a subagent task by id, or None if it does not exist."""
+    async with _get_session_maker()() as db:
+        result = await db.execute(
+            select(SubagentTaskORM).where(SubagentTaskORM.id == str(task_id))
+        )
+        row = result.scalar_one_or_none()
+        return _orm_to_subagent_task(row) if row is not None else None
+
+
+async def finish_subagent_task(task_id: UUID, status: SubagentStatus, result_text: str) -> None:
+    """Mark a subagent task as completed/failed and store its result."""
+    async with _get_session_maker()() as db:
+        result = await db.execute(
+            select(SubagentTaskORM).where(SubagentTaskORM.id == str(task_id))
+        )
+        row = result.scalar_one_or_none()
+        if row is None:
+            return
+        row.status = status.value
+        row.result = result_text
+        row.completed_at = datetime.now(UTC)
+        await db.commit()
+
+
+async def save_session_messages(session_id: UUID, messages: list[dict[str, Any]]) -> None:
+    """Persist conversation messages (excluding the system prompt) for a session.
+
+    Creates the session row when it does not exist yet (e.g. CLI sessions).
+    """
+    async with _get_session_maker()() as db:
+        result = await db.execute(select(SessionORM).where(SessionORM.id == str(session_id)))
+        row = result.scalar_one_or_none()
+        if row is None:
+            row = SessionORM(id=str(session_id))
+            db.add(row)
+        row.messages = json.dumps(messages, ensure_ascii=False)
+        await db.commit()
+
+
+async def get_session_messages(session_id: UUID) -> list[dict[str, Any]]:
+    """Load previously persisted conversation messages for a session."""
+    async with _get_session_maker()() as db:
+        result = await db.execute(
+            select(SessionORM.messages).where(SessionORM.id == str(session_id))
+        )
+        raw = result.scalar_one_or_none()
+    if not raw:
+        return []
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return []
+    return data if isinstance(data, list) else []

claxcode/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models for ClaxCode."""

claxcode/models/session.py

@@ -0,0 +1,25 @@
+"""Session and chat request models."""
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class Session(BaseModel):
+    id: UUID = Field(default_factory=uuid4)
+    name: str = "New Session"
+    project_path: str = "."
+    permission_mode: str = "ask"
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class SessionCreate(BaseModel):
+    name: str = "New Session"
+    project_path: str = "."
+    permission_mode: str = "ask"
+
+
+class ChatRequest(BaseModel):
+    message: str

claxcode/models/subagent.py

@@ -0,0 +1,25 @@
+"""Subagent models."""
+
+from datetime import UTC, datetime
+from enum import Enum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class SubagentStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class SubagentTask(BaseModel):
+    id: UUID = Field(default_factory=uuid4)
+    session_id: UUID
+    agent_type: str = "explore"  # explore | planner | executor
+    instruction: str
+    status: SubagentStatus = SubagentStatus.PENDING
+    result: str = ""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    completed_at: datetime | None = None

claxcode/models/tool.py

@@ -0,0 +1,24 @@
+"""Tool-related models."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ToolInfo(BaseModel):
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    category: str
+    required_permissions: list[str]
+
+
+class ToolInvokeRequest(BaseModel):
+    name: str
+    arguments: dict[str, Any] = {}
+
+
+class ToolInvokeResponse(BaseModel):
+    name: str
+    output: str
+    error: bool = False

claxcode/security/__init__.py

@@ -0,0 +1 @@
+"""Security and permissions for ClaxCode."""

claxcode/security/audit.py

@@ -0,0 +1,54 @@
+"""Durable audit logging — JSONL audit trail under .claxcode/."""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from threading import Lock
+from typing import Any
+from uuid import UUID
+
+
+class AuditLogger:
+    """Logs tool calls and permission decisions to a JSONL file."""
+
+    def __init__(self, log_path: Path | None = None):
+        self._log_path = log_path or Path(".claxcode") / "audit.jsonl"
+        self._lock = Lock()
+
+    def log_tool_call(
+        self,
+        session_id: UUID,
+        tool_name: str,
+        arguments: dict[str, Any],
+        result: str,
+        allowed: bool,
+    ) -> None:
+        entry = {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "session_id": str(session_id),
+            "tool_name": tool_name,
+            "arguments": arguments,
+            "result_preview": result[:500],
+            "allowed": allowed,
+        }
+        self._append(entry)
+
+    def read_recent(self, limit: int = 100) -> list[dict[str, Any]]:
+        """Return the most recent entries (newest last)."""
+        if limit < 1:
+            return []
+        if not self._log_path.exists():
+            return []
+        lines = self._log_path.read_text(encoding="utf-8").splitlines()
+        return [json.loads(line) for line in lines[-limit:] if line.strip()]
+
+    def _append(self, entry: dict[str, Any]) -> None:
+        try:
+            self._log_path.parent.mkdir(parents=True, exist_ok=True)
+            with self._lock, self._log_path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        except OSError:
+            pass  # 审计写入失败不应阻塞主流程
+
+
+audit_logger = AuditLogger()

claxcode/security/permissions.py

@@ -0,0 +1,29 @@
+"""Permission modes."""
+
+from enum import Enum
+
+
+class PermissionMode(str, Enum):
+    ASK = "ask"
+    AUTO_EDIT = "auto_edit"
+    PLAN = "plan"
+    AUTO_SAFE = "auto_safe"
+    YOLO = "yolo"
+
+
+def check_permission(
+    mode: PermissionMode, tool_name: str, required_perms: list[str]
+) -> tuple[bool, str]:
+    """Return (allowed, reason)."""
+    needs_write = "write" in required_perms or "execute" in required_perms
+    if mode == PermissionMode.PLAN and needs_write:
+        return False, "计划模式为只读模式"
+    if mode == PermissionMode.ASK:
+        # Read-only tools run freely; anything else requires user approval
+        if set(required_perms) <= {"read"}:
+            return True, ""
+        return False, "需要批准"
+    if mode == PermissionMode.AUTO_SAFE and "execute" in required_perms:
+        return False, "在自动安全模式下执行操作需要批准"
+    # AUTO_EDIT and YOLO allow everything
+    return True, ""

claxcode/skills/bug-fix/SKILL.md

@@ -0,0 +1,33 @@
+# Bug Fix
+
+## Description
+
+缺陷修复方法论：先复现、找根因、最小修复、回归防复发。不猜原因，不修表象。
+
+## Instructions
+
+修复 bug 时严格按以下顺序：
+
+**1. 复现（一切的前提）**
+- 先让 bug 可重复出现：运行失败测试、最小复现脚本，或按用户描述重走一遍。
+- 无法复现时，先向用户索要复现步骤/日志，不要直接开改。
+
+**2. 定位根因**
+- 从错误信息/堆栈出发，读相关代码；怀疑多处时逐一带假设验证（加打印或写小测试）。
+- 区分"出错的位置"和"出错的原因"——异常抛出点往往不是根因。
+- 若与近期改动有关，优先检查那些改动。
+
+**3. 最小修复**
+- 只修根因，用最少的改动；不顺手清理周边代码、不改变无关行为。
+- 修复方案有多个时，选最简单、对现有逻辑侵入最小的那个。
+
+**4. 回归验证（缺一不可）**
+- 先证明修复有效：复现步骤不再出错。
+- 再证明没有破坏：跑相关测试；最好补一个针对该 bug 的回归测试，防止复发。
+
+**5. 汇报**
+- 一句话说清根因、修复方式、验证证据；若只缓解了表象，必须明说。
+
+## Commands
+
+- `fix`: 按此方法论修复一个 bug（用法：/fix <bug 描述或错误信息>）

claxcode/skills/code-review/SKILL.md

@@ -0,0 +1,35 @@
+# Code Review
+
+## Description
+
+代码审查方法论：按"正确性 > 安全 > 简洁 > 规范"的优先级审查，输出按严重度分级、可直接执行的结论。
+
+## Instructions
+
+审查代码（diff、文件或目录）时按以下顺序检查，发现即记录：
+
+**1. 正确性（最高优先级）**
+- 逻辑错误、边界条件（空值/越界/并发）、异常路径、资源泄漏（连接/文件未关闭）。
+- 行为是否与注释、文档、测试描述一致。
+
+**2. 安全**
+- 注入风险（命令/SQL/路径穿越）、密钥硬编码、敏感信息进日志、不安全的反序列化。
+- 写操作是否有权限校验和备份/回滚手段。
+
+**3. 简洁**
+- 死代码、重复代码、可以压平的嵌套、过度设计（为用不到的需求做的抽象和配置）。
+
+**4. 规范（最低优先级）**
+- 命名、类型标注、docstring、与周边代码风格一致性；lint/类型检查是否引入新违规。
+
+**输出格式（严格遵守）**
+- 先给一行总体结论（可合并/需修改/不可合并）。
+- 问题按三级分类列出，每条注明 `文件:行号`、问题、建议改法：
+  - 🔴 阻断：必须修复（正确性/安全问题）
+  - 🟡 建议：应该修复（简洁/明显改进）
+  - ⚪ 可选：风格偏好，可不改
+- 没有问题就直说"未发现问题"，不要硬凑。
+
+## Commands
+
+- `review`: 审查指定文件、目录或当前改动（用法：/review [路径]；无参数时审查 git 未提交改动）

claxcode/skills/python-refactor/SKILL.md

@@ -0,0 +1,22 @@
+# Python Refactoring
+
+## Description
+
+Expert-level Python refactoring assistant. Prefer type hints, dataclasses, and modern Python idioms (3.11+).
+
+## Instructions
+
+When asked to refactor Python code:
+
+1. Use `pathlib.Path` instead of `os.path`.
+2. Prefer `dataclasses` over plain classes with `__init__`.
+3. Use structural pattern matching (`match`/`case`) where appropriate.
+4. Add type hints to all public functions.
+5. Keep docstrings in Google style.
+6. Use f-strings for formatting, never `%` formatting.
+7. Prefer list/dict comprehensions over explicit loops when readable.
+
+## Commands
+
+- `refactor_file`: Refactor an entire Python file in place
+- `add_types`: Add type hints to a function or module