td-task-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

td - Task Management for AI Agents

td - AI Agent任务管理工具

Overview

概述

td

is a minimalist CLI for tracking tasks and maintaining agent memory across context windows. When your AI session ends,

td

captures what was done, what remains, and what decisions were made—so the next session picks up exactly where the last one left off.

Core capability: Run

td usage

and get everything needed for the next action—current focus, pending reviews, open issues, recent decisions.

td

是一款极简CLI工具，用于跟踪任务并跨上下文窗口维护Agent的记忆。当你的AI会话结束时，

td

会记录已完成的工作、剩余任务以及做出的决策——让下一次会话能够精准接续上一次的工作进度。

核心功能： 运行

td usage

即可获取下一次行动所需的全部信息——当前聚焦任务、待审核事项、未解决问题、近期决策。

Quick Start

快速开始

Session Start (Every Time)

会话启动（每次必做）

bash

td usage --new-session  # Auto-rotation + see current state

Output tells you:

Active work sessions and recent decisions
What issues are pending review (you can review these)
Highest priority open issues
Recent handoffs from previous sessions

bash

td usage --new-session  # 自动切换会话 + 查看当前状态

输出内容包含：

活跃工作会话和近期决策
待审核的问题（你可以对这些问题进行审核）
最高优先级的未解决问题
来自上一会话的近期移交内容

Single-Issue Workflow

单议题工作流

For focused work on one issue:

bash

td start <issue-id>                    # Begin work
td log "OAuth callback implemented"    # Track progress
td log --decision "Using JWT tokens"   # Log decisions
td handoff <id> --done "..." --remaining "..."  # Capture state
td review <id>                         # Submit for review

针对单个议题的专注工作场景：

bash

td start <issue-id>                    # 开始工作
td log "OAuth callback implemented"    # 记录进度
td log --decision "Using JWT tokens"   # 记录决策
td handoff <id> --done "..." --remaining "..."  # 保存状态
td review <id>                         # 提交审核

Multi-Issue Workflow (Recommended for Agents)

多议题工作流（推荐Agent使用）

For agents handling related issues:

bash

td ws start "Auth implementation"      # Start work session
td ws tag td-a1b2 td-c3d4             # Associate issues (auto-starts them)
td ws tag --no-start td-e5f6          # Associate without starting
td ws log "Shared token storage"       # Log to all tagged issues
td ws handoff                          # Capture state, end session

针对Agent处理多个相关议题的场景：

bash

td ws start "Auth implementation"      # 启动工作会话
td ws tag td-a1b2 td-c3d4             # 关联议题（自动启动）
td ws tag --no-start td-e5f6          # 关联议题但不启动
td ws log "Shared token storage"       # 为所有关联议题记录日志
td ws handoff                          # 保存状态，结束会话

Key Workflows

关键工作流

Workflow 1: Starting New Work

工作流1：启动新工作

bash

undefined

bash

undefined

1. Check what to work on

1. 查看待处理工作

td usage # See current state td next # Highest priority open issue td critical-path # What unblocks most work

td usage # 查看当前状态 td next # 获取最高优先级未解决问题 td critical-path # 获取最影响工作推进的阻塞项

2. Start work

2. 开始工作

td start <id>

3. Begin logging

3. 开始记录日志

td log "Started implementation"

undefined

td log "Started implementation"

undefined

Workflow 2: Handing Off Work

工作流2：工作移交

This is critical for agent-to-agent handoffs:

bash

td handoff <id> \
  --done "OAuth flow, token storage" \
  --remaining "Refresh token rotation, error handling" \
  --decision "Using JWT for stateless auth" \
  --uncertain "Should tokens expire on password change?"

Keys:

```
--done
```
- What's actually complete (be honest)
```
--remaining
```
- What's left (be specific)
```
--decision
```
- Why you chose approach X
```
--uncertain
```
- What you're unsure about

Next session will see all this context with

td usage

td context <id>

这在Agent间移交工作时至关重要：

bash

td handoff <id> \
  --done "OAuth flow, token storage" \
  --remaining "Refresh token rotation, error handling" \
  --decision "Using JWT for stateless auth" \
  --uncertain "Should tokens expire on password change?"

关键参数：

```
--done
```
- 实际已完成的工作内容（如实记录）
```
--remaining
```
- 剩余待完成的工作（具体明确）
```
--decision
```
- 选择方案X的原因
```
--uncertain
```
- 存在疑问的内容

下一次会话可通过

td usage

或

td context <id>

查看所有这些上下文信息。

Workflow 3: Reviewing Code

工作流3：代码审核

bash

undefined

bash

undefined

1. See reviewable issues

1. 查看可审核的问题

td reviewable

2. Check details

2. 查看详情

td show <id> td context <id>

3. Approve or reject

3. 批准或驳回

td approve <id>

Or:

或者：

td reject <id> --reason "Missing error handling"


**Important:** You cannot approve work you implemented. Session isolation enforces this.

td reject <id> --reason "Missing error handling"


**重要提示：** 你无法审核自己实现的工作。会话隔离机制强制要求这一点。

Workflow 4: Handling Blockers

工作流4：处理阻塞项

bash

undefined

bash

undefined

1. Log the blocker

1. 记录阻塞项

td log --blocker "Waiting on API spec from backend team"

2. Work on something else

2. 处理其他工作

td next # Get another issue td ws tag td-e5f6 # Add to work session

td next # 获取另一个议题 td ws tag td-e5f6 # 添加到工作会话

3. Come back to blocked issue later

3. 后续回到阻塞的议题

td context td-a1b2 # Refresh context when blocker resolves

undefined

td context td-a1b2 # 阻塞项解决后刷新上下文

undefined

Commands by Category

按类别划分的命令

Checking Status

状态查看

```
td usage
```
- Current state, reviews, next steps
```
td usage -q
```
- Compact view (after first read)
```
td current
```
- What you're working on
```
td ws current
```
- Current work session state
```
td next
```
- Highest priority open
```
td critical-path
```
- What unblocks most work

```
td usage
```
- 当前状态、待审核事项、下一步操作
```
td usage -q
```
- 精简视图（首次查看后使用）
```
td current
```
- 当前正在处理的工作
```
td ws current
```
- 当前工作会话状态
```
td next
```
- 最高优先级未解决问题
```
td critical-path
```
- 最影响工作推进的阻塞项

Working on Issues

议题处理

```
td start <id>
```
- Begin work
```
td unstart <id>
```
- Revert to open (undo accidental start)
```
td log "msg"
```
- Track progress
```
td log --decision "..."
```
- Log decision
```
td log --blocker "..."
```
- Log blocker
```
td show <id>
```
- View details
```
td context <id>
```
- Full context for resuming

```
td start <id>
```
- 开始工作
```
td unstart <id>
```
- 恢复为未开始状态（撤销误操作的启动）
```
td log "msg"
```
- 跟踪进度
```
td log --decision "..."
```
- 记录决策
```
td log --blocker "..."
```
- 记录阻塞项
```
td show <id>
```
- 查看详情
```
td context <id>
```
- 获取恢复工作所需的完整上下文

Handing Off

工作移交

td handoff <id> --done "..." --remaining "..."

- Single issue

```
td ws handoff
```
- Multi-issue work session

td handoff <id> --done "..." --remaining "..."

- 单个议题移交

```
td ws handoff
```
- 多议题工作会话移交

Reviews

审核相关

```
td review <id>
```
- Submit for review
```
td reviewable
```
- Issues you can review
```
td approve <id>
```
- Approve (different session only)
```
td reject <id> --reason "..."
```
- Reject

```
td review <id>
```
- 提交审核
```
td reviewable
```
- 你可审核的议题
```
td approve <id>
```
- 批准（仅不同会话可操作）
```
td reject <id> --reason "..."
```
- 驳回

Creating/Managing Issues

议题创建/管理

td create "title" --type feature --priority P1

- Create

```
td list
```
- List all
```
td list --status in_progress
```
- Filter by status
```
td block <id>
```
- Mark as blocked
```
td delete <id>
```
- Delete

td create "title" --type feature --priority P1

- 创建议题

```
td list
```
- 列出所有议题
```
td list --status in_progress
```
- 按状态筛选
```
td block <id>
```
- 标记为阻塞
```
td delete <id>
```
- 删除议题

File Tracking

文件跟踪

```
td link <id> <files...>
```
- Track files with issue
```
td files <id>
```
- Show file changes

```
td link <id> <files...>
```
- 关联议题与文件
```
td files <id>
```
- 查看文件变更

Other

其他命令

```
td monitor
```
- Live dashboard
```
td session --new "name"
```
- Force new session
```
td undo
```
- Undo last action

See quick_reference.md for full command listing.

```
td monitor
```
- 实时仪表盘
```
td session --new "name"
```
- 强制创建新会话
```
td undo
```
- 撤销上一次操作

完整命令列表请查看quick_reference.md。

Resources

资源

quick_reference.md

Complete command reference organized by task type.

按任务类型整理的完整命令参考。

ai_agent_workflows.md

Detailed workflows for common AI agent scenarios:

Single-issue focus
Multi-issue work sessions
Handling blockers
Resuming work
Code review process
Tips for AI agents

针对常见AI Agent场景的详细工作流：

单议题聚焦
多议题工作会话
阻塞项处理
恢复工作
代码审核流程
AI Agent使用技巧

Issue Lifecycle

议题生命周期

open → in_progress → in_review → closed
         |              |
         v              | (reject)
     blocked -----------+

open → in_progress → in_review → closed
         |              |
         v              | (reject)
     blocked -----------+

Key Principles

核心原则

Session Isolation: Every terminal/context gets a unique session ID. The session that implements code cannot approve it. Different session must review. This forces actual handoffs and prevents "works on my context" bugs.

Structured Handoffs: Don't just say "here's what I did"—structure it with done/remaining/decisions/uncertain so next agent has clear context.

Minimal: Does one thing. Single binary, SQLite local storage (

.todos/

), no server, works with any AI tool.

会话隔离： 每个终端/上下文都有唯一的会话ID。实现代码的会话无法审核该代码，必须由不同的会话进行审核。这强制要求真正的工作移交，避免“仅在我的上下文可用”的问题。

结构化移交： 不要只说“这是我做的工作”——用已完成/剩余/决策/疑问的结构来组织，让下一个Agent拥有清晰的上下文。

极简设计： 专注于一件事。单二进制文件、SQLite本地存储（

.todos/

）、无需服务器，可与任何AI工具配合使用。

For AI Agents

给AI Agent的建议

Always start conversation with:

bash

td usage --new-session

This auto-rotates sessions and gives you current state. Then:

Single focused issue → Use single-issue workflow
Multiple related issues → Use
```
td ws start
```
for work sessions
Before context ends → Always
```
td handoff
```
or
```
td ws handoff
```
Log decisions → Use
```
--decision
```
flag to explain reasoning
Log uncertainty → Use
```
--uncertain
```
flag to mark unknowns
Track files → Use
```
td link
```
so future sessions know what changed

See ai_agent_workflows.md for detailed examples.

始终以以下命令开启对话：

bash

td usage --new-session

该命令会自动切换会话并提供当前状态。然后：

单个聚焦议题 → 使用单议题工作流
多个相关议题 → 使用
```
td ws start
```
创建工作会话
上下文结束前 → 务必执行
```
td handoff
```
或
```
td ws handoff
```
记录决策 → 使用
```
--decision
```
参数说明推理过程
记录疑问 → 使用
```
--uncertain
```
参数标记未知内容
跟踪文件 → 使用
```
td link
```
让后续会话了解变更的文件

详细示例请查看ai_agent_workflows.md。