TaskFlow CLI

轻量级命令行任务管理器 —— 零依赖，仅使用 Python 标准库，由 AtomCode 构建。

TaskFlow 把待办事项存成一个人类可读的 JSON 文件（默认 ~/.taskflow.json）， 提供增删改查、优先级、截止时间、标签、完成/重开与 JSON 导出等能力。 无需安装任何第三方包，git clone 之后即可运行。

特性

• ✅ 零依赖：只用 Python 标准库（argparse / json / dataclasses）
• 📋 任务管理：添加、列出、编辑、删除、完成、重新打开
• 🚦 优先级：low / medium / high，列表自动按优先级排序
• ⏰ 截止时间：ISO 格式，过期任务自动标记 [已过期]
• 🏷️ 标签：逗号分隔，便于分类
• 💾 持久化：原子写入的 JSON 文件，损坏时优雅降级（保留可读错误信息）
• 🧪 测试完备：40+ 单元测试 + 端到端 CLI 测试（pytest）
• 🖥️ 跨平台：Windows / macOS / Linux 均可直接运行

安装

git clone https://gitcode.com/XJ-Cyber/taskflow-cli.git
cd taskflow-cli
pip install -e .          # 可选：安装后即可全局使用 taskflow 命令

不安装也可以直接运行：

python taskflow.py list
# 或
python -m taskflow_cli list

快速上手

# 添加任务
taskflow.py add "写周报" -p high -d 2026-09-30T18:00 -t work,urgent
taskflow.py add "部署新版本" -p medium

# 列出所有任务（待办在前，按优先级排序）
taskflow.py list
# [ ] #1   写周报  <high>  (截止 2026-09-30T18:00)  [work, urgent]
# [ ] #2   部署新版本  <medium>
# 共 2 条，已完成 0 条

# 标记完成 / 撤销完成
taskflow.py done 1
taskflow.py reopen 1

# 编辑任务（任意组合字段）
taskflow.py edit 2 --title "部署新版本 v1.2" -p high --undue

# 按状态过滤
taskflow.py list --status pending
taskflow.py list --status done
# 按标签筛选
taskflow.py list --tag work

# 删除任务
taskflow.py remove 2

# 以 JSON 导出
taskflow.py export

命令一览

命令	说明	示例
add TITLE	添加任务	add "写周报" -p high -d 2026-09-30 -t work
list	列出任务，可按状态或标签筛选	list --status pending / list --tag work
done ID	标记完成	done 1
reopen ID	撤销完成	reopen 1
edit ID	编辑任务	edit 1 --title "x" -p high -d 2026-10-01 -t a,b
remove ID	删除任务	remove 1
export	JSON 导出	export > backup.json

全局选项：

• --data-file PATH：指定数据文件（默认 ~/.taskflow.json）
• 环境变量 TASKFLOW_HOME：同上，优先级低于 --data-file
• --version：显示版本

list --tag TAG 只显示包含指定标签的任务，也可与 --status 组合使用。

数据格式

存储文件（~/.taskflow.json）示例：

{
  "version": 1,
  "next_id": 3,
  "tasks": [
    {
      "id": 1,
      "title": "写周报",
      "priority": "high",
      "due": "2026-09-30T18:00",
      "tags": ["work", "urgent"],
      "created_at": "2026-09-01T10:00:00",
      "completed_at": null
    }
  ]
}

• 纯文本 JSON，可用任意编辑器手工修改；
• next_id 为自增主键，若手工改乱了，读取时会自动按最大 id 修复；
• 单条任务损坏时跳过该条并保留其余任务（列表输出会给出警告信息）；
• 写入采用「临时文件 + 原子替换」，避免中途失败产生半截文件。

运行测试

pip install pytest
pytest

测试覆盖三层：

1. tests/test_tasks.py —— 数据模型：校验、状态流转、过期判断、序列化
2. tests/test_store.py —— 持久化：损坏文件降级、原子写入、id 修复
3. tests/test_cli.py —— 端到端：全部子命令的退出码与输出

项目结构

taskflow-cli/
├── taskflow.py              # 免安装入口
├── taskflow_cli/
│   ├── __init__.py          # 版本号
│   ├── __main__.py          # python -m taskflow_cli 入口
│   ├── cli.py               # argparse 命令定义与分发
│   ├── tasks.py             # Task 数据模型与校验
│   └── store.py             # JSON 持久化（原子写入）
├── tests/
│   ├── test_tasks.py
│   ├── test_store.py
│   └── test_cli.py
├── pyproject.toml           # 打包配置（pip install -e .）
├── LICENSE
└── README.md

License

MIT © XJ-Cyber —— 本项目由 AtomCode 创建并维护。