Tama - AI 驱动的任务管理命令行工具 ✨
Tama 是一个命令行界面 (CLI) 工具，专为任务管理而设计，并通过 AI 能力增强，用于任务生成和分解。它利用 AI（特别配置为通过 OpenAI 兼容 API 使用 DeepSeek 模型）来解析产品需求文档 (PRD) 并将复杂任务分解为可管理的子任务。
特性
- 标准任务管理: 添加、列出、显示详情、更新状态以及移除任务和子任务，支持依赖关系追踪。
- 数据持久化: 使用 SQLite 数据库存储任务数据，确保数据操作的稳定性和可靠性。
- 依赖关系管理: 添加、删除和追踪任务依赖关系，自动检测循环依赖。
- AI 驱动的 PRD 解析: (
tama prd) 从.txt或.prd文件自动生成结构化的任务列表。 - AI 驱动的任务分解: (
tama expand) 使用 AI 将高层级任务分解为详细的子任务。 - 依赖检查: (
tama deps) 检测和可视化任务中的循环依赖。 - 报告生成: (
tama report [markdown|mermaid]) 生成 Markdown 表格格式或 Mermaid 依赖关系图的任务报告。 - 代码桩生成: (
tama gen-file) 基于任务详情创建占位符代码文件。 - 下一任务建议: (
tama next) 根据状态和依赖关系识别下一个可执行的任务。 - 富文本 CLI 输出: 使用
rich库提供格式化且视觉友好的控制台输出（例如表格、面板）。 - Git 集成: 支持在开始和完成任务时自动创建分支和提交。
- 文件关联: 支持将文件链接到任务，方便追踪任务相关代码。
安装与设置
- 创建并激活虚拟环境(推荐3.12):
uv的安装和使用的基本方法可以参考 uv安装和使用
uv venv -p 3.12
# Windows
.\.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate- 安装tama-cli库:
uv pip install --index-url https://pypi.org/simple/ tama-cli
配置 ⚙️
Tama 的 AI 功能需要 API 密钥。
- 在项目根目录创建一个
.env文件。
（你可以直接复制示例文件）
cp .env.example .env
# Windows 下可用：
copy .env.example .env- 添加你的 DeepSeek API 密钥和其他配置:
# .env 文件
# DeepSeek Configuration
DEEPSEEK_API_KEY=""
DEEPSEEK_BASE_URL="http://address:port/openai/v1"
# Optional: Default is set in settings
# Model Names (confirm exact identifiers from DeepSeek docs)
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 # 筛选任务列表现在包含状态和优先级的表情符号指示器，并以清晰的 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 depsAI 命令:
- 解析 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 文件。
