task-notes 0.1.0

LLM-friendly Markdown task notes CLI

task-notes

一个面向 LLM/Agent 的任务管理 CLI。
用 Markdown checklist 保存任务，支持多级子任务、稳定 selector（如 1.2.3）、文本/JSON 双输出，以及 Rich 终端展示。

功能

• 单项目单文件：<project>.md
• 多级树状任务
• selector 定位：1、1.2、2.1.3
• 原子写入 + 文件锁（并发安全）
• Rich 展示（ls 表格、show 树）
• edit 支持交互选择（方向键/jk + Space + Enter）
• --json 机读输出

安装与运行

使用 uv（推荐）

在项目目录内：

uv run task --help

临时执行（不安装到全局）：

uvx --from . task --help

安装为全局工具：

uv tool install --editable .
task --help

使用 pip

pip install .
task --help

默认数据目录与安全策略

• 默认目录：~/.task-notes
• 可自定义目录：--tasks-dir <path>
• 安全限制：默认禁止写入非 ~/.task-notes 目录；若要使用其他目录，必须显式加：

--unsafe-external-dir

示例：

task --unsafe-external-dir --tasks-dir ./tasks ls

快速开始

task new app-redesign "梳理需求" "实现功能" "验收发布"
task add app-redesign --parent 2 "实现 task ls/show"
task show app-redesign
task next app-redesign
task check app-redesign --path 1
task edit app-redesign --path 2.1 "实现 ls/show/tree 输出"

命令概览

task ls [--json]
task show <project> [--json]
task next <project> [--json]
task new <project> <content...> [--json]
task add <project> [--parent <selector>] <content...> [--json]
task edit <project> --path <selector> <content> [--json]
task edit <project> -i [--json]
task del <project> --path <selector> [--json]
task rm <project> [--json]
task check <project> --path <selector> [--json]
task uncheck <project> --path <selector> [--json]
task toggle <project> --path <selector> [--json]

交互式编辑

task edit <project> -i

按键：

• ↑/↓ 或 j/k：移动光标
• Space：选择当前任务
• Enter：确认并编辑文本
• q / Esc：取消

JSON 输出

适合 tools/LLM 集成：

task show app-redesign --json

错误时返回非 0，并输出：

• ok: false
• error_code
• error_message

开发

运行测试：

uv run python -m unittest discover -s tests -p 'test_*.py' -v

发布到 PyPI（建议流程）

uv build
uvx twine check dist/*
# uvx twine upload dist/*