ai-todo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Todo - Task Management for AI Agents

AI Todo - 面向AI Agents的任务管理

Manage tasks, track progress, and maintain daily work logs through the

ai-todo

CLI tool. This tool connects to the ai-todo service for persistent, cross-session task management.

通过

ai-todo

CLI 工具管理任务、跟踪进度并维护日常工作日志。本工具对接 ai-todo 服务，可实现跨会话的持久化任务管理。

Prerequisites

前置要求

The

ai-todo

CLI must be installed and authenticated. Before running any command, check if credentials exist:

bash

cat ~/.config/ai-todo/credentials.json 2>/dev/null

If not authenticated, run

ai-todo login

first. The CLI outputs JSON for all commands, so parse responses accordingly.

If the

ai-todo

command is not found, install it:

bash

npm install -g ai-todo-cli

ai-todo

CLI 必须已安装并完成认证。执行任何命令前，请先检查凭证是否存在：

bash

cat ~/.config/ai-todo/credentials.json 2>/dev/null

如果未完成认证，请先运行

ai-todo login

。该 CLI 的所有命令输出均为 JSON 格式，请按需解析响应内容。

如果找不到

ai-todo

命令，请先安装：

bash

npm install -g ai-todo-cli

Command Reference

命令参考

All commands follow the pattern

ai-todo <command> [options]

and output JSON.

所有命令均遵循

ai-todo <command> [options]

的格式，输出为 JSON。

Task Operations

任务操作

List tasks - View tasks with optional filters:

bash

ai-todo tasks:list                           # All tasks
ai-todo tasks:list --filter today            # Today's tasks
ai-todo tasks:list --filter assigned         # Assigned to me
ai-todo tasks:list --filter completed        # Completed tasks
ai-todo tasks:list --space_id <id>           # Tasks in a space

Create a task - Always include a clear, actionable title:

bash

ai-todo tasks:create --title "Implement user auth" \
  --description "Add JWT-based authentication to the API" \
  --priority 1 \
  --due_date "2025-03-15T00:00:00Z" \
  --tags "backend,auth" \
  --space_id <id> \
  --parent_id <id>

Priority levels: 0=P0 urgent, 1=P1 high, 2=P2 normal, 3=P3 low. Default to P2 unless the user indicates urgency.

Update a task - Modify any field including progress:

bash

ai-todo tasks:update --id <task_id> \
  --title "New title" \
  --progress 60 \
  --priority 1

Progress is 0-100. Update progress as work advances rather than only at completion.

Complete a task - Marks task and its subtasks as done:

bash

ai-todo tasks:complete --id <task_id>

Delete a task - Cascades to subtasks:

bash

ai-todo tasks:delete --id <task_id>

列出任务 - 可通过可选过滤器查看任务：

bash

ai-todo tasks:list                           # 所有任务
ai-todo tasks:list --filter today            # 今日任务
ai-todo tasks:list --filter assigned         # 分配给我的任务
ai-todo tasks:list --filter completed        # 已完成任务
ai-todo tasks:list --space_id <id>           # 指定空间下的任务

创建任务 - 始终填写清晰、可执行的标题：

bash

ai-todo tasks:create --title "Implement user auth" \
  --description "Add JWT-based authentication to the API" \
  --priority 1 \
  --due_date "2025-03-15T00:00:00Z" \
  --tags "backend,auth" \
  --space_id <id> \
  --parent_id <id>

优先级说明：0=P0 紧急，1=P1 高，2=P2 正常，3=P3 低。除非用户明确说明紧急性，否则默认设置为 P2。

更新任务 - 可修改包括进度在内的任意字段：

bash

ai-todo tasks:update --id <task_id> \
  --title "New title" \
  --progress 60 \
  --priority 1

进度取值范围为 0-100。请随工作推进逐步更新进度，不要仅在完成时才更新。

完成任务 - 将任务及其所有子任务标记为已完成：

bash

ai-todo tasks:complete --id <task_id>

删除任务 - 会级联删除所有子任务：

bash

ai-todo tasks:delete --id <task_id>

Progress Logs

进度日志

Progress logs are timestamped entries that track what happened on a task. Use them to maintain a history of work done.

View logs:

bash

ai-todo tasks:logs --id <task_id>

Add a log entry - Record what was accomplished:

bash

ai-todo tasks:add-log --id <task_id> --content "Implemented login endpoint, added JWT validation middleware"

进度日志是带时间戳的记录，用于跟踪任务的执行情况，可用来留存工作完成历史。

查看日志：

bash

ai-todo tasks:logs --id <task_id>

添加日志记录 - 记录已完成的工作内容：

bash

ai-todo tasks:add-log --id <task_id> --content "Implemented login endpoint, added JWT validation middleware"

Spaces

空间

Spaces are containers for organizing tasks by project or team.

bash

ai-todo spaces:list                                    # List all spaces
ai-todo spaces:create --name "Backend API" --description "API development tasks"

空间是用于按项目或团队归类任务的容器。

bash

ai-todo spaces:list                                    # 列出所有空间
ai-todo spaces:create --name "Backend API" --description "API development tasks"

Task Hierarchy

任务层级

Tasks support parent-child relationships for breaking down work:

bash

undefined

任务支持父子层级关系，可用于拆分工作：

bash

undefined

Create a parent task

创建父任务

ai-todo tasks:create --title "User authentication system"

Create subtasks under it (use the parent's ID from the response)

在父任务下创建子任务（使用响应中返回的父任务ID）

ai-todo tasks:create --title "Design auth schema" --parent_id <parent_id> ai-todo tasks:create --title "Implement login endpoint" --parent_id <parent_id> ai-todo tasks:create --title "Add JWT middleware" --parent_id <parent_id>

undefined

undefined

Workflow Patterns

工作流模式

Starting a work session

开启工作会话

At the beginning of a session, check existing tasks to understand current priorities:

bash

ai-todo tasks:list --filter today
ai-todo tasks:list --filter assigned

Review what's in progress and what needs attention.

会话开始时，先查看现有任务以明确当前优先级：

bash

ai-todo tasks:list --filter today
ai-todo tasks:list --filter assigned

梳理进行中的任务和需要关注的事项。

Task creation from development context

从开发上下文创建任务

When the user describes work to be done or you identify actionable items from code review, create tasks with appropriate structure:

Create a parent task for the overall objective
Break it into subtasks for individual steps
Set priorities based on dependencies and urgency
Add due dates if the user specifies deadlines

Example - user says "I need to add search functionality to the app":

bash

undefined

当用户描述待完成的工作，或者你从代码评审中识别出可执行项时，按合理结构创建任务：

为整体目标创建父任务
将父任务拆分为对应单个步骤的子任务
根据依赖关系和紧急程度设置优先级
如果用户指定了截止日期则添加到期时间

示例 - 用户说「我需要给应用添加搜索功能」：

bash

undefined

Create parent

创建父任务

ai-todo tasks:create --title "Add search functionality" --priority 2

Create subtasks (using parent_id from response)

创建子任务（使用响应中返回的parent_id）

ai-todo tasks:create --title "Add search API endpoint" --parent_id <id> --priority 2 ai-todo tasks:create --title "Build search UI component" --parent_id <id> --priority 2 ai-todo tasks:create --title "Add search indexing" --parent_id <id> --priority 2

undefined

undefined

Progress tracking during development

开发过程中的进度跟踪

As you complete work, update task progress and add logs:

When starting a task: update progress to 10-20%
At meaningful checkpoints: increment progress
When done: set progress to 100 and complete the task
Always add a log entry describing what was accomplished

bash

ai-todo tasks:update --id <id> --progress 50
ai-todo tasks:add-log --id <id> --content "Completed API endpoint, starting frontend integration"

当你完成部分工作时，更新任务进度并添加日志：

开始处理任务时：将进度更新为10-20%
到达有意义的检查点时：递增进度
任务完成时：将进度设为100并标记任务为完成
始终添加日志记录描述已完成的工作内容

bash

ai-todo tasks:update --id <id> --progress 50
ai-todo tasks:add-log --id <id> --content "Completed API endpoint, starting frontend integration"

Daily progress summary

每日进度总结

When the user asks for a daily standup or progress update, or at the end of a session:

List today's tasks and completed tasks
For each active task, add a log summarizing the day's work
Update progress percentages to reflect current state

bash

undefined

当用户需要每日站会或进度更新时，或者会话即将结束时：

列出今日任务和已完成任务
为每个进行中的任务添加日志，总结当日工作
更新进度百分比以反映当前状态

bash

undefined

Check what was worked on

查看已处理的工作内容

ai-todo tasks:list --filter today ai-todo tasks:list --filter completed

Log daily progress on active tasks

为进行中的任务记录当日进度

ai-todo tasks:add-log --id <id> --content "Today: fixed 3 bugs in auth module, added input validation. Next: write integration tests"

undefined

ai-todo tasks:add-log --id <id> --content "Today: fixed 3 bugs in auth module, added input validation. Next: write integration tests"

undefined

Post-action workflow (after commit/deploy)

操作后工作流（提交/部署后）

When a git commit, push, or deployment completes successfully:

List existing tasks to find related ones:

bash

ai-todo tasks:list --filter assigned

If related task exists: update progress, add a detailed log, mark complete if done
If no related task exists: suggest creating one to record the completed work
Keep it lightweight — one log entry summarizing what was done, not a lengthy report

Example — after a successful deploy:

bash

undefined

当 git commit、push 或部署成功完成时：

列出现有任务找到相关任务：

bash

ai-todo tasks:list --filter assigned

如果存在相关任务：更新进度、添加详细日志，如果已全部完成则标记为完成
如果不存在相关任务：建议创建任务记录已完成的工作
保持轻量化 - 仅用一条日志总结完成的内容，不需要冗长的报告

示例 - 部署成功后：

bash

undefined

Find related task

查找相关任务

ai-todo tasks:list --space_id <id>

Log the accomplishment

记录完成的工作

ai-todo tasks:add-log --id <task_id> --content "Completed and deployed: added search UI with debounced input, integrated with search API endpoint"

Complete if fully done

如果全部完成则标记任务为完成

ai-todo tasks:complete --id <task_id>

undefined

ai-todo tasks:complete --id <task_id>

undefined

Pre-action workflow (during planning/design)

操作前工作流（规划/设计阶段）

When the user is discussing implementation plans, architecture design, or feature breakdown:

Listen for actionable items in the discussion
Suggest creating a task hierarchy to track the planned work:

bash

undefined

当用户讨论实现方案、架构设计或功能拆分时：

留意讨论中的可执行项
建议创建任务层级来跟踪计划的工作：

bash

undefined

Create parent task for the overall plan

为整体计划创建父任务

ai-todo tasks:create --title "Implement user search feature" --priority 2 --space_id <id>

Break into subtasks

拆分为子任务

ai-todo tasks:create --title "Design search API schema" --parent_id <id> --priority 2 ai-todo tasks:create --title "Build search index pipeline" --parent_id <id> --priority 2 ai-todo tasks:create --title "Create search UI component" --parent_id <id> --priority 2

3. Set priorities based on dependencies discussed in the plan

3. 根据计划中讨论的依赖关系设置优先级

Cross-skill collaboration

跨技能协作

This skill works alongside other skills:

After git-tools: When git-tools completes a commit workflow, automatically trigger ai-todo to log progress on related tasks
After vercel:deploy: When deployment succeeds, log the deployment as progress and update/complete related tasks
After brainstorming: When brainstorming produces an action plan, convert it into a task hierarchy

本技能可与其他技能协同工作：

git-tools 执行完成后：当 git-tools 完成提交流程时，自动触发 ai-todo 为相关任务记录进度
vercel:deploy 执行完成后：当部署成功时，记录部署进度并更新/完成相关任务
头脑风暴执行完成后：当头脑风暴产出行动计划时，将其转化为任务层级

Error Handling

错误处理

Exit code 0: success, parse the JSON response
Exit code 1: error, check the
```
error
```
field in JSON
Exit code 2: not authenticated, run
```
ai-todo login
```

If you get exit code 2, inform the user they need to authenticate before task management features work.

退出码 0：执行成功，解析JSON响应即可
退出码 1：执行错误，检查JSON中的
```
error
```
字段获取详情
退出码 2：未认证，运行
```
ai-todo login
```
即可

如果返回退出码2，请告知用户需要先完成认证才能使用任务管理功能。

Best Practices

最佳实践

Write task titles as clear, actionable statements ("Implement X" not "X stuff")
Use subtasks to break complex work into manageable pieces
Update progress incrementally, not just at 0% and 100%
Add log entries with specific details about what was done, not vague summaries
Include both "what was done" and "what's next" in progress logs
Use tags to categorize tasks by area (frontend, backend, infra, docs)
Set realistic priorities - not everything is P0

任务标题要写清晰的可执行语句（如「实现X功能」而非「X相关内容」）
使用子任务将复杂工作拆分为可管理的小块
逐步更新进度，不要仅设置0%和100%两个状态
日志记录要包含具体的完成内容，不要写模糊的总结
进度日志中同时包含「已完成内容」和「下一步计划」
使用标签按领域归类任务（frontend、backend、infra、docs）
设置合理的优先级 - 不是所有内容都是P0