unitask-task-agent

通过作用域 API 令牌（CLI 或 MCP）管理 Unitask (unitask.app) 中的任务和时间块。

# Unitask Task Agent

## Purpose

This skill lets an AI agent safely manage a user's Unitask account using **scoped API tokens**.

It is designed for **hosted use on unitask.app**, so end users do not need to run any local server code.

Supported operations:
- List tasks
- Get one task
- Create task
- Update task status
- Delete task (soft delete)
- Read/update settings (optional one-time setup)
- Plan day time blocks (preview/apply time-blocking)

Subtasks:
- Subtasks are supported as tasks with a `parent_id`.
- Create a subtask by creating a task with `parent_id=<parent task id>`.

## When to use

Use this skill when the user asks for things like:
- "List my tasks / what's next?"
- "Create a task for X"
- "Mark these tasks done"
- "Time-block my day from 9am to 5pm"

## Required setup

1. User creates a Unitask API token from `Unitask -> Dashboard -> Settings -> API`.
2. User stores it in their agent/app as a secret/env var: `UNITASK_API_KEY=<token>`.

Never ask users to paste full tokens in chat logs. Ask them to set environment variables instead.

## Scope model

- `read`: required to read/list tasks.
- `write`: create/update tasks.
- `delete`: delete tasks.
- If `write` or `delete` is granted, `read` must also be granted.

## Hosted MCP (unitask.app, HTTPS)

Use the hosted MCP endpoint:

- `https://unitask.app/api/mcp`

Auth header (recommended):
- `Authorization: Bearer <UNITASK_API_KEY>`

## MCP tools

Exposed tools:
- `list_tasks` — filter by `status` (todo|done|archived), `limit` (1-500), `offset`, `parent_id`
- `get_task` — get one task by id
- `create_task` — title required; optional: description, parent_id, status, priority, due_date, start_date, recurrence, scheduled_start, duration_minutes
- `update_task_status` — change status (todo|done|archived)
- `delete_task` — soft-delete task + descendants
- `get_settings` — get user settings + quiz prefs
- `update_settings` — partial update settings/quiz
- `plan_day_timeblocks` — schedule time blocks in a window

Recommended usage for time blocking:
- Call `plan_day_timeblocks` with `apply=false` to preview.
- Only call again with `apply=true` after the user confirms the plan.

## Safety rules

- Use smallest required scope for the requested action.
- Confirm destructive actions (delete) unless user explicitly asks to proceed.
- Prefer `status=done` over delete when user intent is completion, not removal.
- For `plan_day_timeblocks`, prefer preview (`apply=false`) first; only apply after user confirms.

---

## 中文说明

# Unitask Task Agent

## 用途

此技能让 AI 代理能够使用 **作用域 API 令牌** 安全地管理用户的 Unitask 账户。

它专为 **在 unitask.app 上托管使用** 而设计，因此终端用户无需运行任何本地服务器代码。

支持的操作：
- 列出任务
- 获取单个任务
- 创建任务
- 更新任务状态
- 删除任务（软删除）
- 读取/更新设置（可选的一次性配置）
- 规划当日时间块（预览/应用时间分块）

子任务：
- 子任务以带有 `parent_id` 的任务形式支持。
- 通过创建一个带有 `parent_id=<parent task id>` 的任务来创建子任务。

## 何时使用

当用户提出以下类似请求时使用此技能：
- “列出我的任务 / 接下来做什么？”
- “为 X 创建一个任务”
- “把这些任务标记为已完成”
- “把我从早上 9 点到下午 5 点的时间分块安排”

## 必需的配置

1. 用户从 `Unitask -> Dashboard -> Settings -> API` 创建一个 Unitask API 令牌。
2. 用户将其作为密钥/环境变量存储在其代理/应用中：`UNITASK_API_KEY=<token>`。

切勿要求用户在聊天记录中粘贴完整令牌。而应要求他们设置环境变量。

## 作用域模型

- `read`：读取/列出任务所必需。
- `write`：创建/更新任务。
- `delete`：删除任务。
- 如果授予了 `write` 或 `delete`，则也必须授予 `read`。

## 托管 MCP（unitask.app，HTTPS）

使用托管的 MCP 端点：

- `https://unitask.app/api/mcp`

认证头（推荐）：
- `Authorization: Bearer <UNITASK_API_KEY>`

## MCP 工具

已暴露的工具：
- `list_tasks` — 按 `status`（todo|done|archived）、`limit`（1-500）、`offset`、`parent_id` 过滤
- `get_task` — 按 id 获取单个任务
- `create_task` — title 必填；可选：description、parent_id、status、priority、due_date、start_date、recurrence、scheduled_start、duration_minutes
- `update_task_status` — 更改状态（todo|done|archived）
- `delete_task` — 软删除任务及其后代
- `get_settings` — 获取用户设置 + 测验偏好
- `update_settings` — 部分更新设置/测验
- `plan_day_timeblocks` — 在某个时间窗口内安排时间块

时间分块的推荐用法：
- 以 `apply=false` 调用 `plan_day_timeblocks` 进行预览。
- 仅在用户确认计划后才以 `apply=true` 再次调用。

## 安全规则

- 对所请求的操作使用所需的最小作用域。
- 确认破坏性操作（删除），除非用户明确要求继续。
- 当用户的意图是完成而非移除时，优先使用 `status=done` 而非删除。
- 对于 `plan_day_timeblocks`，优先先进行预览（`apply=false`）；仅在用户确认后才应用。