illusion-code 0.1.0__py3-none-any.whl

illusion/tools/task_create_tool.py

@@ -0,0 +1,98 @@
+"""
+后台任务创建工具
+================
+
+本模块提供创建后台任务的功能，用于任务进度跟踪和状态管理。
+
+主要组件：
+    - TaskCreateTool: 创建后台任务的工具
+
+使用示例：
+    >>> from illusion.tools import TaskCreateTool
+    >>> tool = TaskCreateTool()
+"""
+
+from __future__ import annotations
+
+
+from pydantic import BaseModel, Field
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskCreateToolInput(BaseModel):
+    """任务创建参数。
+
+    属性：
+        subject: 简短、可操作的任务标题（祈使形式）
+        description: 需要完成的内容
+        activeForm: 进行时显示的现在进行时形式
+    """
+
+    subject: str = Field(description="A brief, actionable title in imperative form (e.g., 'Fix authentication bug in login flow')")
+    description: str = Field(description="What needs to be done")
+    activeForm: str | None = Field(
+        default=None,
+        description="Present continuous form shown in spinner when in_progress (e.g., 'Fixing authentication bug')",
+    )
+
+
+class TaskCreateTool(BaseTool):
+    """创建后台任务。
+
+    用于创建结构化的任务列表来跟踪当前编码会话的进度。
+    """
+
+    name = "task_create"
+    description = """Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements as tasks
+- When you start working on a task - Mark it as in_progress BEFORE beginning work
+- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: What needs to be done
+- **activeForm** (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.
+
+All tasks are created with status `pending`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
+- Check TaskList first to avoid creating duplicate tasks"""
+    input_model = TaskCreateToolInput
+
+    async def execute(self, arguments: TaskCreateToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        # 获取任务管理器并创建任务
+        manager = get_task_manager()
+        task = manager.create_pending_task(
+            subject=arguments.subject,
+            description=arguments.description,
+            active_form=arguments.activeForm,
+        )
+        return ToolResult(output=f"Created task {task.id}\nsubject: {task.subject}")

illusion/tools/task_get_tool.py

@@ -0,0 +1,94 @@
+"""
+任务详情获取工具
+================
+
+本模块提供获取任务详细信息的功能，用于查看任务状态和依赖关系。
+
+主要组件：
+    - TaskGetTool: 获取任务详情的工具
+
+使用示例：
+    >>> from illusion.tools import TaskGetTool
+    >>> tool = TaskGetTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tasks.types import to_task_display_status
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskGetToolInput(BaseModel):
+    """任务查找参数。
+
+    属性：
+        task_id: 任务标识符
+    """
+
+    task_id: str = Field(description="Task identifier")
+
+
+class TaskGetTool(BaseTool):
+    """返回详细的任务状态。
+
+    用于获取任务的完整描述和上下文。
+    """
+
+    name = "task_get"
+    description = """Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', 'completed', 'failed', or 'killed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use TaskList to see all tasks in summary form."""
+    input_model = TaskGetToolInput
+
+    def is_read_only(self, arguments: TaskGetToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: TaskGetToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        # 获取任务
+        task = get_task_manager().get_task(arguments.task_id)
+        if task is None:
+            return ToolResult(output=f"No task found with ID: {arguments.task_id}", is_error=True)
+
+        # 构建与参考格式匹配的结构化输出
+        parts = [
+            f"id: {task.id}",
+            f"subject: {task.subject or task.description}",
+        ]
+        if task.description and task.subject:
+            parts.append(f"description: {task.description}")
+        parts.append(f"status: {to_task_display_status(task.status)}")
+        if task.owner:
+            parts.append(f"owner: {task.owner}")
+        if task.blocks:
+            parts.append(f"blocks: {task.blocks}")
+        if task.blocked_by:
+            parts.append(f"blockedBy: {task.blocked_by}")
+        if task.active_form:
+            parts.append(f"activeForm: {task.active_form}")
+        if task.comments:
+            parts.append(f"comments: {task.comments}")
+
+        return ToolResult(output="\n".join(parts))

illusion/tools/task_list_tool.py

@@ -0,0 +1,94 @@
+"""
+任务列表工具
+============
+
+本模块提供列出所有后台任务的功能。
+
+主要组件：
+    - TaskListTool: 列出任务的工具
+
+使用示例：
+    >>> from illusion.tools import TaskListTool
+    >>> tool = TaskListTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tasks.types import to_task_display_status
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskListToolInput(BaseModel):
+    """任务列表参数。"""
+
+
+class TaskListTool(BaseTool):
+    """列出后台任务。
+
+    用于查看所有任务的概要信息。
+    """
+
+    name = "task_list"
+    description = """Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with TaskGet, TaskUpdate)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', 'completed', 'failed', or 'killed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use TaskGet with a specific task ID to view full details including description and comments.
+
+## Teammate Workflow
+
+When working as a teammate:
+1. After completing your current task, call TaskList to find available work
+2. Look for tasks with status 'pending', no owner, and empty blockedBy
+3. **Prefer tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+4. Claim an available task using TaskUpdate (set `owner` to your name), or wait for leader assignment
+5. If blocked, focus on unblocking tasks or notify the team lead"""
+    input_model = TaskListToolInput
+
+    def is_read_only(self, arguments: TaskListToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: TaskListToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        # 获取所有任务
+        tasks = get_task_manager().list_tasks()
+        if not tasks:
+            return ToolResult(output="(no tasks)")
+
+        # 构建已完成任务 ID 集合用于依赖过滤
+        completed_ids = {t.id for t in tasks if t.status == "completed"}
+
+        # 格式化每个任务
+        lines: list[str] = []
+        for task in tasks:
+            subject = task.subject or task.description
+            owner = task.owner or ""
+            # 过滤 blockedBy 只显示未解决的依赖
+            active_blockers = [bid for bid in task.blocked_by if bid not in completed_ids]
+            blocked_str = f" blockedBy={active_blockers}" if active_blockers else ""
+            owner_str = f" owner={owner}" if owner else ""
+            status = to_task_display_status(task.status)
+            lines.append(
+                f"id={task.id} status={status} subject={subject}{owner_str}{blocked_str}"
+            )
+
+        return ToolResult(output="\n".join(lines))

illusion/tools/task_output_tool.py

@@ -0,0 +1,55 @@
+"""
+任务输出读取工具
+================
+
+本模块提供读取后台任务输出的功能。
+
+主要组件：
+    - TaskOutputTool: 读取任务输出日志的工具
+
+使用示例：
+    >>> from illusion.tools import TaskOutputTool
+    >>> tool = TaskOutputTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskOutputToolInput(BaseModel):
+    """任务输出获取参数。
+
+    属性：
+        task_id: 任务标识符
+        max_bytes: 最大返回字节数
+    """
+
+    task_id: str = Field(description="Task identifier")
+    max_bytes: int = Field(default=12000, ge=1, le=100000)
+
+
+class TaskOutputTool(BaseTool):
+    """读取后台任务的输出。
+
+    用于查看后台任务的输出日志。
+    """
+
+    name = "task_output"
+    description = "Read the output log for a background task."
+    input_model = TaskOutputToolInput
+
+    def is_read_only(self, arguments: TaskOutputToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: TaskOutputToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        try:
+            output = get_task_manager().read_task_output(arguments.task_id, max_bytes=arguments.max_bytes)
+        except ValueError as exc:
+            return ToolResult(output=str(exc), is_error=True)
+        return ToolResult(output=output or "(no output)")

illusion/tools/task_stop_tool.py

@@ -0,0 +1,52 @@
+"""
+任务停止工具
+============
+
+本模块提供停止正在运行的后台任务的功能。
+
+主要组件：
+    - TaskStopTool: 停止后台任务的工具
+
+使用示例：
+    >>> from illusion.tools import TaskStopTool
+    >>> tool = TaskStopTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskStopToolInput(BaseModel):
+    """任务停止参数。
+
+    属性：
+        task_id: 任务标识符
+    """
+
+    task_id: str = Field(description="Task identifier")
+
+
+class TaskStopTool(BaseTool):
+    """停止后台任务。
+
+    用于终止长时间运行的任务。
+    """
+
+    name = "task_stop"
+    description = """- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task"""
+    input_model = TaskStopToolInput
+
+    async def execute(self, arguments: TaskStopToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        try:
+            task = await get_task_manager().stop_task(arguments.task_id)
+        except ValueError as exc:
+            return ToolResult(output=str(exc), is_error=True)
+        return ToolResult(output=f"Stopped task {task.id}")

illusion/tools/task_update_tool.py

@@ -0,0 +1,224 @@
+"""
+任务更新工具
+============
+
+本模块提供更新后台任务元数据的功能，用于任务进度跟踪和状态管理。
+
+主要组件：
+    - TaskUpdateTool: 更新任务信息的工具
+
+使用示例：
+    >>> from illusion.tools import TaskUpdateTool
+    >>> tool = TaskUpdateTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from illusion.tasks.manager import get_task_manager
+from illusion.tasks.types import to_task_display_status
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TaskUpdateToolInput(BaseModel):
+    """任务更新参数。
+
+    属性：
+        task_id: 任务标识符
+        subject: 任务新标题
+        description: 更新后的任务描述
+        active_form: 进行中时显示的现在进行时形式
+        status: 新任务状态（pending, in_progress, completed, deleted）
+        owner: 任务新负责人
+        progress: 进度百分比（0-100）
+        status_note: 简短的人类可读任务备注
+        metadata: 要合并到任务的元数据键
+        add_blocks: 无法开始直到此任务完成的任务ID
+        add_blocked_by: 必须先完成才能开始此任务的任务ID
+        comments: 要追加的评论文本
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    task_id: str = Field(description="Task identifier", alias="taskId")
+    subject: str | None = Field(default=None, description="New subject for the task")
+    description: str | None = Field(default=None, description="Updated task description")
+    active_form: str | None = Field(
+        default=None,
+        alias="activeForm",
+        description="Present continuous form shown in spinner when in_progress (e.g., 'Running tests')",
+    )
+    status: str | None = Field(default=None, description="New task status (pending, in_progress, completed, deleted)")
+    owner: str | None = Field(default=None, description="New owner for the task")
+    progress: int | None = Field(default=None, ge=0, le=100, description="Progress percentage")
+    status_note: str | None = Field(
+        default=None,
+        alias="statusNote",
+        description="Short human-readable task note",
+    )
+    metadata: dict | None = Field(
+        default=None,
+        description="Metadata keys to merge into the task (set a key to null to delete it)",
+    )
+    add_blocks: list[str] | None = Field(
+        default=None,
+        alias="addBlocks",
+        description="Task IDs that cannot start until this one completes",
+    )
+    add_blocked_by: list[str] | None = Field(
+        default=None,
+        alias="addBlockedBy",
+        description="Task IDs that must complete before this one can start",
+    )
+    comments: str | None = Field(
+        default=None,
+        description="Comment text to append to the task",
+    )
+
+
+class TaskUpdateTool(BaseTool):
+    """更新任务元数据以进行进度跟踪。
+
+    用于更新任务列表中的任务状态、进度和依赖关系。
+    """
+
+    name = "task_update"
+    description = """Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` -> `in_progress` -> `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```"""
+    input_model = TaskUpdateToolInput
+
+    async def execute(
+        self,
+        arguments: TaskUpdateToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        del context
+        try:
+            # 获取任务管理器并更新任务
+            task = get_task_manager().update_task(
+                arguments.task_id,
+                subject=arguments.subject,
+                description=arguments.description,
+                active_form=arguments.active_form,
+                status=arguments.status,
+                owner=arguments.owner,
+                progress=arguments.progress,
+                status_note=arguments.status_note,
+                metadata=arguments.metadata,
+                add_blocks=arguments.add_blocks,
+                add_blocked_by=arguments.add_blocked_by,
+                comments=arguments.comments,
+            )
+        except ValueError as exc:
+            message = str(exc)
+            # 处理任务不存在的情况
+            if message.startswith("No task found with ID:"):
+                return ToolResult(
+                    output=(
+                        f"Ignored stale task_update for missing task {arguments.task_id}. "
+                        "Run task_list to refresh IDs before updating."
+                    ),
+                    is_error=False,
+                )
+            return ToolResult(output=message, is_error=True)
+
+        # 处理任务删除
+        if arguments.status == "deleted":
+            return ToolResult(output=f"Deleted task {task.id}")
+
+        # 构建输出信息
+        parts = [f"Updated task {task.id}"]
+        if arguments.subject:
+            parts.append(f"subject={task.subject}")
+        if arguments.description:
+            parts.append(f"description={task.description}")
+        if arguments.active_form:
+            parts.append(f"activeForm={task.active_form}")
+        if arguments.status:
+            parts.append(f"status={to_task_display_status(task.status)}")
+        if arguments.owner:
+            parts.append(f"owner={task.owner}")
+        if arguments.progress is not None:
+            parts.append(f"progress={task.metadata.get('progress', '')}%")
+        if arguments.status_note:
+            parts.append(f"note={task.metadata.get('status_note', '')}")
+        if arguments.add_blocks:
+            parts.append(f"blocks={task.blocks}")
+        if arguments.add_blocked_by:
+            parts.append(f"blockedBy={task.blocked_by}")
+        if arguments.comments:
+            parts.append(f"comments={task.comments}")
+        return ToolResult(output=" ".join(parts))