justdo - Just do it! 🚀

一个用 TDD 方式开发的简单命令行待办事项工具，支持任务优先级、AI 智能建议、用户画像分析。

Just do it! - 简单、高效的待办事项管理工具

✨ 特性

• 📋 任务管理 - 添加、完成、删除任务，支持优先级（高🔴/中🟡/低🟢）
• 🤖 AI 增强 - 智能任务描述优化、个性化反馈、流式响应
• 👤 用户画像 - 自动分析任务习惯，识别优势短板
• 🗑️ 回收站 - 删除任务暂存，支持恢复和自动清理
• 🌐 Web 界面 - 日式和风设计的单页应用
• ⚡ 高性能 - AI 响应优化（54秒 → 2.85秒）

安装

# 使用 pip 安装
pip install justdo

# 使用 uv 安装
uv pip install justdo

# 安装 AI 功能支持
pip install justdo[ai]

# 安装 Web 界面支持
pip install justdo[web]

使用方法

CLI 基础命令

# 添加任务（默认中等优先级）
jd add "购买牛奶"

# 添加高优先级任务 (1=高, 2=中, 3=低)
jd add "紧急任务" -l 1

# 列出所有任务
jd list

# 按优先级排序显示
jd list -s p

# 标记任务为完成（支持范围语法）
jd done 1
jd done 1 2-5 7

# 删除任务
jd delete 1

# 清空所有已完成的任务
jd clear

AI 功能

# 设置 API Key（智谱 GLM）
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4"

# AI 优化任务描述
jd add "写代码" --ai
# → AI 优化: 写代码 → 完成核心功能模块编码工作

# AI 智能建议（流式输出）
jd suggest --ai

# AI 对话模式
jd --chat "帮我分析今天的工作安排"

Web 界面

# 启动 Web 服务器（默认端口 8848）
jd-web

# 访问浏览器
open http://localhost:8848

Web 功能包括：

• 🎨 日式和风极简设计
• 📊 用户画像可视化
• 🔄 实时流式反馈
• 📱 响应式布局

用户画像

# 查看 API 请求示例
curl http://localhost:8848/api/profile/full

画像分析内容：

• 📈 基础统计 - 总任务数、完成率、连续天数
• 🎯 用户类型 - 执行模式、时间偏好、活动模式
• 💪 优势短板 - AI 分析强项和改进建议
• ⚠️ 风险预警 - 任务堆积、拖延提醒

回收站

# 查看 API 请求示例
curl http://localhost:8848/api/trash

回收站功能：

• 🗂️ 删除任务自动暂存
• 🔄 支持恢复已删除任务
• ⏰ 30 天自动清理
• 📊 按类别/优先级统计

优先级说明

优先级	Emoji	数字	说明
high	🔴	1	高优先级（紧急重要）
medium	🟡	2	中优先级（默认）
low	🟢	3	低优先级（可延后）

技术栈

类别	技术
语言	Python 3.8+
CLI	argparse
Web	FastAPI + uvicorn
AI	OpenAI API (GLM-4)
数据存储	JSON
测试	pytest
包管理	uv / setuptools

开发

# 克隆仓库
git clone https://github.com/gqy20/justdo.git
cd justdo

# 使用 uv 安装开发依赖
uv pip install -e ".[dev,ai,web]"

# 运行测试
uv run python -m pytest

# 查看测试覆盖率
uv run python -m pytest --cov=justdo

# 安装包到本地
uv build
pip install dist/justdo-0.1.3-py3-none-any.whl

项目结构

justdo/
├── src/
│   └── justdo/
│       ├── __init__.py       # 包导出，版本 0.1.3
│       ├── models.py         # TodoItem 数据模型
│       ├── manager.py        # TodoManager 核心逻辑
│       ├── cli.py            # 命令行接口
│       ├── ai.py             # AI 集成（GLM-4）
│       ├── emotion.py        # 情感反馈引擎
│       ├── prompts.py        # AI Prompt 模板
│       ├── user_profile.py   # 用户画像分析
│       ├── trash.py          # 回收站管理
│       ├── api.py            # FastAPI Web 接口
│       └── static/
│           └── index.html    # 单页 Web 应用
├── tests/
│   ├── unit/                 # 单元测试
│   └── integration/          # 集成测试
├── docs/                     # 项目文档
│   ├── api.md                # API 文档
│   ├── architecture.md       # 架构设计
│   ├── components.md         # 组件清单
│   ├── development.md        # 开发指南
│   └── testing.md            # 测试策略
├── pyproject.toml            # 包配置
├── justdo.json               # 数据存储（自动生成）
├── justdo.profile.json       # 用户画像（自动生成）
└── justdo.trash.json         # 回收站（自动生成）

📚 文档

• API 文档 - RESTful API 完整参考
• 架构设计 - 系统架构与模块关系
• 组件清单 - 模块职责边界
• 开发指南 - 开发环境与工作流
• 测试策略 - TDD 与测试覆盖

在线 API 文档

启动 Web 服务后访问：

• Swagger UI: http://localhost:8848/docs
• ReDoc: http://localhost:8848/redoc

主要端点

端点	方法	说明
/api/todos	GET/POST	列表/创建任务
/api/todos/{id}/toggle	POST	切换状态（SSE 流式）
/api/todos/{id}	DELETE	删除任务
/api/profile/full	GET	完整用户画像
/api/trash	GET	回收站列表
/api/chat	POST	AI 对话

测试

项目采用 TDD 开发模式，100 个测试全部通过：

• 数据模型测试 - 优先级、权重计算
• 业务逻辑测试 - CRUD、排序、过滤
• CLI 命令测试 - 参数解析、输出格式
• AI 功能测试 - 模拟 AI 响应、流式输出
• 用户画像测试 - 统计分析、风险预警
• 回收站测试 - 添加、恢复、清理
• API 集成测试 - REST 接口、SSE 流式

性能优化

指标	优化前	优化后	提升
AI 响应时间	54 秒	2.85 秒	19x
AI 调用次数	4 次	1 次	75%

优化手段：

• 统一分析：4 个场景 → 1 个 prompt
• 流式响应：Token 级实时输出
• 并发删除：批量操作优化

为什么叫 justdo？

• ✅ 简洁有力 - 两个音节，朗朗上口
• ✅ 寓意完美 - "Just do it!" 正是待办事项的核心精神
• ✅ 命令简短 - jd 两个字母，快速输入
• ✅ 易记易搜 - 用户搜索 "just do" 很容易找到
• ✅ 国际化 - 英语通用，全球用户都能理解

配置

环境变量

变量	说明	必需
OPENAI_API_KEY	智谱 API Key	AI 功能
OPENAI_BASE_URL	API 基础 URL	可选

数据文件

文件	位置	说明
justdo.json	~/.local/share/justdo/	任务数据
justdo.profile.json	~/.local/share/justdo/	用户画像
justdo.trash.json	~/.local/share/justdo/	回收站

链接

• GitHub: https://github.com/gqy20/justdo
• PyPI: https://pypi.org/project/justdo/
• 文档: http://home.gqy20.top/justdo/

License

MIT