Tama - 基于AI的任务管理命令行工具 ✨

英文原文

Tama 是一个专门为任务管理设计的命令行界面（CLI）工具，并通过集成AI能力来增强任务生成和分解的功能。它利用AI（特别配置为通过与OpenAI兼容的API使用DeepSeek模型）解析产品需求文档（PRD），并把复杂任务分解成可管理的子任务。

功能

• 标准任务管理： 添加、列出、显示详情、更新状态和移除任务及子任务，支持依赖关系追踪。
• 数据持久化： 使用SQLite数据库存储任务数据，确保数据操作的稳定性和可靠性。
• 依赖管理： 添加、删除和追踪任务依赖关系，自动检测循环依赖。
• 基于AI的PRD分析： (tama prd <文件路径>）从.txt或.prd文件自动生成结构化的任务列表。
• 基于AI的任务分解： (tama expand <任务ID>）使用AI将高层次任务分解为详细的子任务。
• 依赖检查： (tama deps）检测并可视化任务中的循环依赖。
• 报告生成： (tama report [markdown|mermaid]）以Markdown表格格式或Mermaid依赖图生成任务报告。
• 代码堆生成： (tama gen-file <任务ID>）根据任务细节创建占位符代码文件。
• 下一个任务建议： (tama next）基于状态和依赖关系识别下一个可执行任务。
• 丰富的文本CLI输出： 使用rich库提供格式化且视觉友好的控制台输出（如表格、面板）。
• Git集成： 支持在任务开始和完成时自动创建分支和提交。
• 文件关联： 支持将文件链接到任务，便于跟踪任务相关的代码。

安装和设置

1. 创建并激活虚拟环境（推荐Python 3.12）： 安装和使用UV的基本方法可以参考UV安装和使用

uv venv -p 3.12

# Windows
.\.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

2. 安装Tama CLI库： uv pip install --index-url https://pypi.org/simple/ tama-cli

配置 ⚙️

Tama的AI功能需要一个API密钥。

1. 在项目目录中创建根目录.env文档。 （可以直接复制示例文件）

cp .env.example .env
# Windows 下可用：
copy .env.example .env

2. 添加您的DeepSeek API密钥和其他配置：

# .env 文件
# DeepSeek 配置
DEEPSEEK_API_KEY=""
DEEPSEEK_BASE_URL="http://address:port/openai/v1" 
# 可选：默认设置在settings中

# 模型名称（确认DeepSeek文档中的确切标识符）
DEEPSEEK_GENERAL_MODEL="deepseek-v3"
DEEPSEEK_REASONING_MODEL="deepseel-r1"

(参考) .env.example 文件检索模板) 应用使用src/config/settings.py文件中定义的设置将加载.env文件中的变量。

使用说明 🚀

Tama命令需要在一个已激活的虚拟环境中运行终端。 核心命令：

• 列出任务：

tama list
tama list --status pending --priority high # 筛选

任务列表现在包括状态和优先级的emoji指示器，并以清晰的markdown表格格式显示依赖关系。

• 显示任务详情：

tama show 1       # 显示任务 1
tama show 1.2     # 显示任务 1 的子任务 2

• 添加任务/子任务：

# 添加顶级任务
tama add "实现用户认证" --desc "处理登录和会话" --priority high
# 为任务 1 添加子任务
tama add "创建登录 API 端点" --parent 1 --desc "需要处理 JWT"

• 移除任务/子任务：

tama remove 2       # 移除任务 2 及其所有子任务
tama remove 1.3     # 移除任务 1 的子任务 3

移除任务时，所有依赖于该任务的其他任务将自动更新，系统会通知受影响的依赖关系。

工作流命令：

• 设置任务状态：

tama status 1 done
tama status 1.2 in-progress
# 级联更新子任务/依赖任务状态
tama status 1 done --propagate

(有效状态: pending, in-progress, done, deferred, blocked, review)

--propagate 参数描述：

• --propagate 控制是否将状态变化级联到所有子任务或依赖任务。
• 默认行为由配置文件决定（settings. PROPAGATE-STATUS_CHANGE）。
• 显式添加 --propagate 可强制级联更新。

• 开始任务： 此命令将任务状态设为 in-progress 并自动创建一个Git分支。

tama start 1

• 完成任务： 此命令将任务状态设为 done 如果使用了 --commit 标志，还将自动提交更改进行临时存储。

tama complete 1
tama complete 1 --commit

• 查找下一个任务：

tama next

依赖关系命令：

• 管理依赖关系：

tama add-dep 1 2      # 设置任务 1 依赖于任务 2
tama add-dep 1.2 2.1  # 设置子任务 1.2 依赖于子任务 2.1
tama remove-dep 1 2   # 移除任务 1 对任务 2 的依赖

• 检查依赖关系：

tama deps

AI命令：

• 分析PRD： 输入文件必须是 .txt 或 .prd）

tama prd path/to/your/document.txt

• 任务分解： （提供主要任务ID）

tama expand 1

文件管理命令：

• 生成占位符文件：

tama gen-file 1
tama gen-file 2 --output-dir src/generated

• 关联文件： 将一个或多个文件链接到任务。

tama link 1 src/main.py

• 取消文件关联： 从任务中移除一个或多个文件的链接。

tama unlink 1 src/main.py

• 通过文件搜索任务： 查找与指定文件相关联的所有任务。

tama find-task src/main.py

其他命令：

• 生成报告：

tama report markdown       # 在控制台打印 Markdown 表格
tama report mermaid       # 打印 Mermaid 图定义
tama report markdown --output report.md # 保存到文件

Shell自动补全：

• 您可以通过以下命令获取设置Shell自动补全的说明：

tama --install-completion

(注意：根据您的Shell和操作系统设置，这可能需要管理员权限)

开发 🔧

如果您修改了源代码，请记得重新安装包以便在CLI中生效：

uv pip install -e .

MCP服务器使用

Tama可以用作MCP（模型上下文协议）服务器，允许其他应用程序通过编程方式与其交互。MCP服务器提供了以下工具：

• list_tasks 列出所有任务，可以根据状态或优先级进行筛选，并返回markdown表格。
• show_task 根据ID显示指定任务或子任务的详细信息。
• set_status 设置任务或子任务的状态。
• next_task 搜索下一个可执行任务。
• add_task 添加一个新的主任务。
• add_subtask 向主任务添加子任务。
• remove_item 移除任务或子任务，并自动清理依赖关系。
• add_dependency 向任务或子任务添加依赖关系。
• remove_dependency 从任务或子任务中移除依赖关系。
• check_dependencies 检查所有任务中的循环依赖。

要启动服务器，请运行：

uv --directory /path/to/your/TAMA_MCP run python -m src.mcp_server

客户端配置示例：

{
  "mcpServers": {
    "TAMA-MCP-Server": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/your/TAMA_MCP",
            "run",
            "python",
            "-m",
            "src.mcp_server"
        ],
        "disabled": false,
        "transportType": "stdio",
        "timeout": 60
    },
  }
}

许可证

MIT许可证

本项目采用MIT许可证。详情请参阅LICENSE文档。