makkzone-task-todo

轻量级任务与待办管理，支持创建、列表、完成与优先级。

## 概述（中文）

轻量级任务与待办管理，支持创建、列表、完成与优先级。

## 技能正文

# Task-Todo 代理技能

## 概述

一个任务管理代理技能，使用 SQLite 数据库提供持久化的任务存储与管理。该技能使 AI 代理能够创建、读取、更新、删除和查询任务，并支持状态跟踪和优先级管理。

## 能力

- **任务创建**：添加带有标题、描述、状态和优先级的新任务
- **任务检索**：获取单个任务或列出所有任务
- **任务过滤**：按状态或优先级过滤任务
- **任务更新**：修改任务的任意字段（标题、描述、状态、优先级）
- **任务删除**：从数据库中移除任务
- **持久化存储**：所有任务存储在 SQLite 数据库中，并自动记录时间戳

## 用法

### 命令行界面

```bash
# Add task
python task_skill.py add "Task title" "Description" --status pending --priority high

# List all tasks
python task_skill.py list

# Filter by status
python task_skill.py list --status in_progress

# Filter by priority
python task_skill.py list --priority urgent

# Get task details
python task_skill.py get 1

# Update task
python task_skill.py update 1 --status completed --priority low

# Delete task
python task_skill.py delete 1
```

## 数据模型

### 任务字段

| 字段 | 类型 | 说明 | 必填 | 默认值 |
|-------|------|-------------|----------|---------|
| id | INTEGER | 自动生成的任务 ID | 自动 | - |
| title | TEXT | 任务标题 | 是 | - |
| description | TEXT | 任务描述 | 否 | "" |
| status | TEXT | 任务状态 | 是 | "pending" |
| priority | TEXT | 任务优先级 | 是 | "medium" |
| created_at | TIMESTAMP | 创建时间戳 | 自动 | 当前时间 |
| updated_at | TIMESTAMP | 最后更新时间戳 | 自动 | 当前时间 |

### 状态值

- `pending` - 任务待处理且尚未开始
- `in_progress` - 任务正在进行中
- `completed` - 任务已完成
- `blocked` - 任务被阻塞，无法推进

### 优先级值

- `low` - 低优先级任务
- `medium` - 中优先级任务（默认）
- `high` - 高优先级任务
- `urgent` - 需立即处理的紧急任务

## 响应格式

所有代理方法都返回一个带有 `success` 字段的字典：

### 添加成功
```python
{
    "success": True,
    "task_id": 1,
    "message": "Task created with ID: 1"
}
```

### 列表成功
```python
{
    "success": True,
    "tasks": [
        {
            "id": 1,
            "title": "Task title",
            "description": "Task description",
            "status": "pending",
            "priority": "medium",
            "created_at": "2026-02-11T10:30:00",
            "updated_at": "2026-02-11T10:30:00"
        }
    ],
    "count": 1
}
```

### 获取成功
```python
{
    "success": True,
    "task": {
        "id": 1,
        "title": "Task title",
        "description": "Task description",
        "status": "pending",
        "priority": "medium",
        "created_at": "2026-02-11T10:30:00",
        "updated_at": "2026-02-11T10:30:00"
    }
}
```

### 操作失败
```python
{
    "success": False,
    "message": "Task 1 not found"
}
```

## 数据库

- **数据库文件**：`tasks.db`（在当前目录中自动创建）
- **数据库类型**：SQLite3
- **架构约束**：状态和优先级的取值在数据库层面进行校验
- **时间戳**：由数据库自动管理

## 依赖

无 —— 使用 Python 内置的 `sqlite3` 模块。

## 使用场景

1. **任务跟踪**：跟踪带有状态和优先级的个人或项目任务
2. **TODO 管理**：维护一份持久化的 TODO 列表
3. **工作流自动化**：将任务管理集成到自动化工作流中
4. **项目管理**：简单的项目任务跟踪
5. **代理记忆**：为 AI 代理提供持久化的任务存储

## 注意事项

- 数据库连接在多次操作之间保持持久
- 完成后务必调用 `agent.close()` 以正确关闭数据库
- 使用上下文管理器模式实现自动清理：
  ```python
  with TaskAgent() as agent:
      agent.add_task("Task", "Description")
  ```
- 任务 ID 为从 1 开始自增的整数
- 所有时间戳均采用 ISO 8601 格式