claxcode 0.1.1__py3-none-any.whl

claxcode/skills/task-workflow/SKILL.md

@@ -0,0 +1,38 @@
+# Task Workflow
+
+## Description
+
+通用任务处理方法论：接到任务时按"分类 → 探索 → 计划 → 小步执行 → 验证 → 汇报"的流程工作，避免臆测和返工。
+
+## Instructions
+
+处理任何任务时，先判断类型，再按对应流程执行：
+
+**1. 任务分类（先做）**
+- 问答/探索：只需读懂代码 → 直接用搜索和读取工具回答，不改文件。
+- 修改/新功能：需要动代码 → 走完整流程。
+- 调试：复现优先（见 bug-fix 方法论）。
+
+**2. 探索先行（修改前必做）**
+- 用 glob/grep 定位相关文件，用 read 读懂现状；绝不猜测路径、函数签名或已有实现。
+- 找不到时换关键词再搜，而不是编造。
+
+**3. 计划（超过 3 步的任务必做）**
+- 用编号列出步骤，每步可独立验证；先易后难，先根因后表象。
+- 计划内只包含任务要求的事，不顺带重构、不扩大范围。
+
+**4. 小步执行**
+- 一次改一个步骤，改完立刻验证（读回文件/跑相关测试），再进行下一步。
+- 写代码遵循项目已有风格和编码规范：最少代码、最简单实现、扁平不嵌套。
+
+**5. 验证（汇报前必做）**
+- 有测试跑测试；没测试至少读回改动确认。
+- 验证失败就继续修，不要说"应该没问题"。
+
+**6. 汇报**
+- 说清改了哪些文件、验证结果是什么；没验证的部分明确标注"未验证"。
+
+## Commands
+
+- `task`: 按完整方法论处理一个任务（用法：/task <任务描述>）
+- `plan`: 只输出执行计划，不动手修改（用法：/plan <任务描述>）

claxcode/subagents/__init__.py

@@ -0,0 +1 @@
+"""Subagent system for ClaxCode."""

claxcode/subagents/base.py

@@ -0,0 +1,108 @@
+"""Base subagent with isolated context and restricted tools."""
+
+from collections.abc import AsyncIterator
+from typing import Any
+from uuid import UUID, uuid4
+
+from claxcode.core.agent import DEFAULT_SYSTEM_PROMPT
+from claxcode.core.context import ContextManager
+from claxcode.core.models import get_provider
+from claxcode.tools.registry import registry
+
+
+class Subagent:
+    """Isolated subagent for delegated tasks."""
+
+    def __init__(
+        self,
+        session_id: UUID,
+        agent_type: str,
+        instruction: str,
+        allowed_tools: list[str] | None = None,
+        max_iterations: int = 5,
+    ):
+        self.id = uuid4()
+        self.session_id = session_id
+        self.agent_type = agent_type
+        self.instruction = instruction
+        self.allowed_tools = allowed_tools
+        self.max_iterations = max_iterations
+        self.provider = get_provider()
+        self.context = ContextManager(
+            system_prompt=f"{DEFAULT_SYSTEM_PROMPT}\n\n你是一个 {agent_type} 子代理。"
+            f"专注于你的专业领域并简洁地报告发现。"
+        )
+
+    async def run(self) -> AsyncIterator[dict[str, Any]]:
+        """Run the subagent and stream progress events."""
+        yield {"type": "status", "status": "running"}
+        self.context.add_message("user", self.instruction)
+
+        for i in range(self.max_iterations):
+            tools = self._build_tools()
+            content_buffer = ""
+            pending_tool_calls = []
+
+            async for chunk in self.provider.stream_chat(
+                messages=self.context.get_messages(),
+                tools=tools if tools else None,
+            ):
+                if isinstance(chunk, str):
+                    content_buffer += chunk
+                elif isinstance(chunk, dict) and chunk.get("type") == "tool_call":
+                    pending_tool_calls.append(chunk)
+
+            if not pending_tool_calls:
+                self.context.add_message("assistant", content_buffer)
+                yield {"type": "result", "content": content_buffer}
+                yield {"type": "status", "status": "completed"}
+                return
+
+            import json
+            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)
+
+            for tc in pending_tool_calls:
+                result = await self._execute_tool(tc["name"], tc["arguments"])
+                self.context.add_tool_result(tc["id"], tc["name"], result)
+
+        final_messages = self.context.get_messages()
+        final_content = "\n".join(m.get("content", "") for m in final_messages if m["role"] == "assistant")
+        yield {"type": "result", "content": final_content}
+        yield {"type": "status", "status": "completed"}
+
+    def _build_tools(self) -> list[dict[str, Any]]:
+        all_tools = registry.list_tools()
+        if self.allowed_tools:
+            all_tools = [t for t in all_tools if t.name in self.allowed_tools]
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": t.name,
+                    "description": t.description,
+                    "parameters": t.input_schema,
+                },
+            }
+            for t in all_tools
+        ]
+
+    async def _execute_tool(self, name: str, args: dict) -> str:
+        t = registry.get(name)
+        if t is None:
+            return f"错误：工具 {name} 不存在"
+        try:
+            return await t.execute(**args)
+        except Exception as exc:
+            return f"错误：{exc}"

claxcode/subagents/executor.py

@@ -0,0 +1,16 @@
+"""Executor subagent — full-capability multi-step task executor."""
+
+from uuid import UUID
+
+from claxcode.subagents.base import Subagent
+
+
+class ExecutorSubagent(Subagent):
+    def __init__(self, session_id: UUID, instruction: str):
+        super().__init__(
+            session_id=session_id,
+            agent_type="executor",
+            instruction=instruction,
+            allowed_tools=None,  # all tools
+            max_iterations=10,
+        )

claxcode/subagents/explore.py

@@ -0,0 +1,25 @@
+"""Explore subagent — read-only codebase explorer."""
+
+from uuid import UUID
+
+from claxcode.subagents.base import Subagent
+
+READONLY_TOOLS = [
+    "glob_search",
+    "grep_search",
+    "explore_codebase",
+    "read_file",
+    "find_definition",
+    "find_references",
+]
+
+
+class ExploreSubagent(Subagent):
+    def __init__(self, session_id: UUID, instruction: str):
+        super().__init__(
+            session_id=session_id,
+            agent_type="explore",
+            instruction=instruction,
+            allowed_tools=READONLY_TOOLS,
+            max_iterations=8,
+        )

claxcode/subagents/planner.py

@@ -0,0 +1,25 @@
+"""Planner subagent — research-oriented for plan-mode analysis."""
+
+from uuid import UUID
+
+from claxcode.subagents.base import Subagent
+
+READONLY_TOOLS = [
+    "glob_search",
+    "grep_search",
+    "explore_codebase",
+    "read_file",
+    "find_definition",
+    "find_references",
+]
+
+
+class PlannerSubagent(Subagent):
+    def __init__(self, session_id: UUID, instruction: str):
+        super().__init__(
+            session_id=session_id,
+            agent_type="planner",
+            instruction=instruction,
+            allowed_tools=READONLY_TOOLS,
+            max_iterations=5,
+        )

claxcode/tools/__init__.py

@@ -0,0 +1,14 @@
+"""Tool system for ClaxCode."""
+
+import importlib
+import pkgutil
+
+from claxcode.tools.base import Tool  # noqa: F401
+from claxcode.tools.registry import registry, tool  # noqa: F401
+
+_EXCLUDED = {"base", "registry", "__init__"}
+
+# Auto-discover and register all built-in tools
+for _mod_info in pkgutil.iter_modules(__path__):
+    if _mod_info.name not in _EXCLUDED:
+        importlib.import_module(f"claxcode.tools.{_mod_info.name}")

claxcode/tools/admin.py

@@ -0,0 +1,170 @@
+"""Admin tools for runtime extension."""
+
+import textwrap
+from typing import Any
+
+from claxcode.tools.base import Tool
+from claxcode.tools.registry import registry, tool
+
+
+@tool
+class AdminAddTool(Tool):
+    """Dynamically add a new tool at runtime by providing its Python source."""
+
+    name = "admin_add_tool"
+    description = (
+        "动态注册新工具。"
+        "提供工具名称、描述、JSON 输入模式和 execute() 方法体作为字符串。"
+        "代码在受限环境中运行，仅包含基本内置函数。"
+    )
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "唯一的工具标识符"},
+            "description": {"type": "string", "description": "工具的功能描述"},
+            "category": {"type": "string", "default": "custom"},
+            "required_permissions": {
+                "type": "array",
+                "items": {"type": "string"},
+                "default": [],
+            },
+            "input_schema": {
+                "type": "object",
+                "description": "工具参数的 JSON Schema",
+            },
+            "code": {
+                "type": "string",
+                "description": (
+                    "execute() 方法体的 Python 源代码。"
+                    "仅使用 'self' 和标准库。返回一个字符串。"
+                ),
+            },
+        },
+        "required": ["name", "description", "code"],
+    }
+    category = "admin"
+    required_permissions = ["write"]
+
+    async def execute(
+        self,
+        name: str,
+        description: str,
+        code: str,
+        category: str = "custom",
+        required_permissions: list[str] | None = None,
+        input_schema: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        if registry.get(name):
+            return f"错误：工具 '{name}' 已存在。"
+
+        # Sanitize name
+        if not name.replace("_", "").isalnum():
+            return "错误：工具名称只能包含字母数字或下划线。"
+
+        safe_name = "".join(ch if ch.isalnum() else "_" for ch in name)
+        class_name = f"Dyn{safe_name.title()}"
+
+        # Build the full class source
+        schema = input_schema or {"type": "object", "properties": {}, "required": []}
+        perms = required_permissions or []
+        perms_repr = repr(perms)
+        schema_repr = repr(schema)
+
+        body = textwrap.dedent(code).strip()
+        # Indent to 12 spaces so it sits inside the try block (try is at 8 spaces)
+        wrapped_code = textwrap.indent(body, "            ")
+
+        class_source = f"""
+class {class_name}(Tool):
+    name = {repr(name)}
+    description = {repr(description)}
+    input_schema = {schema_repr}
+    category = {repr(category)}
+    required_permissions = {perms_repr}
+
+    async def execute(self, **kwargs) -> str:
+        try:
+{wrapped_code}
+        except Exception as _exc:
+            return f"{repr(name)} 中出错: {{_exc}}"
+"""
+
+        # Restricted execution environment
+        allowed_builtins = {
+            "__build_class__": __build_class__,
+            "Exception": Exception,
+            "BaseException": BaseException,
+            "ValueError": ValueError,
+            "TypeError": TypeError,
+            "KeyError": KeyError,
+            "IndexError": IndexError,
+            "AttributeError": AttributeError,
+            "RuntimeError": RuntimeError,
+            "len": len,
+            "str": str,
+            "int": int,
+            "float": float,
+            "bool": bool,
+            "list": list,
+            "dict": dict,
+            "set": set,
+            "tuple": tuple,
+            "range": range,
+            "enumerate": enumerate,
+            "zip": zip,
+            "map": map,
+            "filter": filter,
+            "sum": sum,
+            "min": min,
+            "max": max,
+            "sorted": sorted,
+            "reversed": reversed,
+            "any": any,
+            "all": all,
+            "type": type,
+            "callable": callable,
+            "abs": abs,
+            "round": round,
+            "print": print,
+            "repr": repr,
+            "format": format,
+            "isinstance": isinstance,
+            "hasattr": hasattr,
+            "getattr": getattr,
+            "setattr": setattr,
+            "open": open,
+            "Path": __import__("pathlib").Path,
+            "json": __import__("json"),
+            "re": __import__("re"),
+            "textwrap": __import__("textwrap"),
+            "datetime": __import__("datetime"),
+            "typing": __import__("typing"),
+            "httpx": __import__("httpx"),
+            "math": __import__("math"),
+            "random": __import__("random"),
+            "hashlib": __import__("hashlib"),
+            "base64": __import__("base64"),
+            "urllib": __import__("urllib"),
+        }
+
+        namespace = {
+            "__builtins__": allowed_builtins,
+            "__name__": "__claxcode_dynamic__",
+            "__doc__": None,
+            "Tool": Tool,
+            "Any": Any,
+        }
+
+        try:
+            exec(class_source, namespace)  # noqa: S102
+        except Exception as exc:
+            return f"编译工具时出错: {exc}\n\n生成的源代码:\n{class_source}"
+
+        tool_cls = namespace.get(class_name)
+        if tool_cls is None or not isinstance(tool_cls, type) or not issubclass(tool_cls, Tool):
+            return "错误：编译的类不是有效的 Tool 子类。"
+
+        instance = tool_cls()
+        registry.register(instance)
+        return f"✅ 工具 '{name}' 已成功注册到类别 '{category}'。"

claxcode/tools/base.py

@@ -0,0 +1,19 @@
+"""Tool base class."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Tool(ABC):
+    """Base class for all ClaxCode tools."""
+
+    name: str = ""
+    description: str = ""
+    input_schema: dict[str, Any] = {}
+    category: str = "general"
+    required_permissions: list[str] = []
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> str:
+        """Execute the tool and return a string result."""
+        ...