@walknpm/todo-cli 1.1.0 → 1.2.0

package/README.md

@@ -13,11 +13,20 @@ statistics, and export (JSON / CSV / Markdown). Data persists to
 
 ## Quick install
 
+**Via npm:**
+
+```bash
+npm install -g @walknpm/todo-cli
+todo --version   # → todo v1.1.0
+```
+
+**Via git:**
+
 ```bash
 git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
 cd todo_cli
 npm install -g .
-todo --version   # → todo v1.0.0
+todo --version   # → todo v1.1.0
 ```
 
 ## Commands
@@ -98,6 +107,10 @@ todo_cli/
 │   ├── store.js       # JSON file persistence layer
 │   ├── todo.js        # domain logic (CRUD, search, stats, export, ...)
 │   └── cli.js         # command parsing, ANSI colours, table output
+├── skill/
+│   ├── SKILL.md       # DSH skill instructions
+│   ├── README.md      # skill documentation
+│   └── CHANGELOG.md   # skill changelog
 ├── package.json
 ├── README.md          # English documentation
 └── README.zh-CN.md    # Chinese documentation
@@ -115,17 +128,15 @@ todo_cli/
 ```
 请帮我安装部署 todo-cli 命令行待办工具，步骤如下：
 
-1. 克隆仓库：git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
-2. 进入目录：cd todo_cli
-3. 全局安装：npm install -g .
-4. 验证安装：运行 todo --version，确认输出 "todo v1.0.0"
-5. 功能验证：依次执行以下命令并确认每步输出正常：
+1. 全局安装：npm install -g @walknpm/todo-cli
+2. 验证安装：运行 todo --version，确认输出 "todo v1.1.0"
+3. 功能验证：依次执行以下命令并确认每步输出正常：
    - todo add "部署测试任务" -p high -t test -c verify
    - todo list
    - todo done 1
    - todo stats
    - todo clear
-6. 如果任何步骤报错，请展示完整错误信息并尝试修复。
+4. 如果任何步骤报错，请展示完整错误信息并尝试修复。
 
 完成后告诉我安装路径和 todo --version 的输出。
 ```

package/README.zh-CN.md

@@ -12,11 +12,20 @@
 
 ## 快速安装
 
+**通过 npm：**
+
+```bash
+npm install -g @walknpm/todo-cli
+todo --version   # → todo v1.1.0
+```
+
+**通过 git：**
+
 ```bash
 git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
 cd todo_cli
 npm install -g .
-todo --version   # → todo v1.0.0
+todo --version   # → todo v1.1.0
 ```
 
 ## 命令一览
@@ -97,6 +106,10 @@ todo_cli/
 │   ├── store.js       # JSON 文件持久化层
 │   ├── todo.js        # 领域逻辑（增删改查、搜索、统计、导出等）
 │   └── cli.js         # 命令解析、ANSI 彩色、表格输出
+├── skill/
+│   ├── SKILL.md       # DSH 技能指令
+│   ├── README.md      # 技能文档
+│   └── CHANGELOG.md   # 技能变更记录
 ├── package.json
 ├── README.md          # 英文文档
 └── README.zh-CN.md    # 中文文档
@@ -114,17 +127,15 @@ todo_cli/
 ```
 请帮我安装部署 todo-cli 命令行待办工具，步骤如下：
 
-1. 克隆仓库：git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
-2. 进入目录：cd todo_cli
-3. 全局安装：npm install -g .
-4. 验证安装：运行 todo --version，确认输出 "todo v1.0.0"
-5. 功能验证：依次执行以下命令并确认每步输出正常：
+1. 全局安装：npm install -g @walknpm/todo-cli
+2. 验证安装：运行 todo --version，确认输出 "todo v1.1.0"
+3. 功能验证：依次执行以下命令并确认每步输出正常：
    - todo add "部署测试任务" -p high -t test -c verify
    - todo list
    - todo done 1
    - todo stats
    - todo clear
-6. 如果任何步骤报错，请展示完整错误信息并尝试修复。
+4. 如果任何步骤报错，请展示完整错误信息并尝试修复。
 
 完成后告诉我安装路径和 todo --version 的输出。
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walknpm/todo-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A zero-dependency Node.js CLI todo list manager with CRUD, due dates, search, stats, export, and auto-update.",
   "type": "module",
   "main": "src/cli.js",
@@ -31,6 +31,7 @@
   "files": [
     "bin/",
     "src/",
+    "skill/",
     "README.md",
     "README.zh-CN.md"
   ]

package/skill/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## v1.0.0
+
+- 初始版本
+- 封装 todo-cli 全部命令：add/list/done/toggle/edit/delete/remove/search/stats/export/archive/update/clear
+- 支持 4 个工作流模板：项目规划、每日回顾、Bug 跟踪、导出汇报
+- 包含最佳实践和错误处理指南

package/skill/README.md

@@ -0,0 +1,48 @@
+# todo-cli-harness
+
+通过 `todo-cli` 命令行工具进行任务管理的 DSH Skill。
+
+**核心特性**：
+- **全命令覆盖**：增删改查、完成切换、搜索、统计、导出、自动更新
+- **结构化任务管理**：优先级、分类、标签、截止日期、备注
+- **工作流模板**：项目规划、每日回顾、Bug 跟踪、导出汇报
+- **零依赖**：仅需 Node.js >= 18 和 `todo` CLI
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `add` | 添加任务（支持优先级/标签/分类/截止日期/备注） |
+| `list` | 列出与过滤（按状态/分类/标签/优先级/排序） |
+| `done` | 标记完成（`--all` 批量完成） |
+| `toggle` | 切换完成/待办状态 |
+| `edit` | 编辑任务 |
+| `delete` / `remove` / `rm` | 删除任务 |
+| `search` | 搜索标题/标签/分类/备注 |
+| `stats` | 统计概览 |
+| `export` | 导出 JSON/CSV/Markdown |
+| `archive` | 归档已完成任务 |
+| `update` | 自动更新工具 |
+| `clear` | 清空全部任务 |
+
+## 安装
+
+```bash
+npm install -g @walknpm/todo-cli
+```
+
+## 使用
+
+加载本 skill 后，AI Agent 会获得 `todo` CLI 的完整使用指南，包括：
+- 所有命令的语法和示例
+- 4 个常用工作流模板
+- 最佳实践和错误处理指南
+
+## 文件结构
+
+```
+skill/
+├── SKILL.md       # 技能指令（加载后生效）
+├── README.md      # 本文档
+└── CHANGELOG.md   # 变更记录
+```

package/skill/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: todo-cli-harness
+description: "通过 todo-cli 命令行工具进行任务管理。支持增删改查、优先级、截止日期、分类标签、搜索、统计、导出与自动更新。"
+---
+
+## 概述
+
+本技能封装 `todo-cli` 命令行工具，为 AI Agent 提供结构化的任务管理能力。
+所有操作通过 `todo` 命令完成，数据持久化到 `~/.todo-cli/todos.json`。
+
+### 设计哲学
+
+- 所有任务操作通过 `todo` CLI 命令完成，不直接读写 JSON 文件
+- 每次操作后检查退出码，确认执行成功
+- 批量操作优先使用 `--all` 等聚合标志，减少命令轮次
+- 任务创建时主动设置优先级、分类、标签和截止日期，提升可管理性
+
+## 前置检查
+
+首次使用前，验证 `todo` 命令是否可用：
+
+```bash
+todo --version
+```
+
+若命令不存在，安装工具：
+
+```bash
+# 方式一：npm（推荐）
+npm install -g @walknpm/todo-cli
+
+# 方式二：git 克隆
+git clone https://gitcode.com/hw_aishell_projects/todo_cli.git /tmp/todo_cli
+cd /tmp/todo_cli && npm install -g .
+```
+
+安装后再次验证 `todo --version` 输出版本号。
+
+## 命令参考
+
+### 添加任务
+
+```bash
+todo add "<标题>" [-p high|medium|low] [-t tag1,tag2] [-c 分类] [-d YYYY-MM-DD] [--note "备注"]
+```
+
+**示例：**
+
+```bash
+todo add "修复登录页空指针" -p high -c bug -t frontend,urgent -d 2025-02-15 --note "用户点击空按钮时崩溃"
+todo add "编写 API 文档" -p medium -c docs -t api
+todo add "整理周报" -p low -c admin
+```
+
+### 列出与过滤
+
+```bash
+todo list [--status all|done|pending] [--category <分类>] [--tag <标签>] [--priority <优先级>] [--sort priority|created|due|id]
+```
+
+**示例：**
+
+```bash
+todo list                          # 全部（默认按优先级排序）
+todo list --status pending         # 仅待办
+todo list --status pending --sort due   # 待办按截止日期排序
+todo list --category bug --priority high # 高优 bug
+todo list --tag urgent             # 含 urgent 标签
+```
+
+### 完成与切换
+
+```bash
+todo done <id>           # 标记完成
+todo done --all          # 全部完成
+todo toggle <id>         # 切换完成/待办状态
+```
+
+### 编辑
+
+```bash
+todo edit <id> [--title "新标题"] [-p high|medium|low] [-t tag1,tag2] [-c 分类] [-d YYYY-MM-DD] [--note "备注"]
+```
+
+**示例：**
+
+```bash
+todo edit 3 --title "更新后的标题" -p low
+todo edit 5 -d 2025-03-01 --note "延期到三月"
+```
+
+### 删除
+
+```bash
+todo delete <id>    # 删除指定任务
+todo remove <id>    # 同上（别名）
+todo rm <id>        # 同上（别名）
+todo archive        # 删除所有已完成任务
+todo clear          # 清空全部任务（慎用）
+```
+
+### 搜索
+
+```bash
+todo search <关键词>    # 搜索标题/标签/分类/备注
+```
+
+### 统计
+
+```bash
+todo stats    # 显示总数、完成/待办/逾期、按优先级和分类分组
+```
+
+### 导出
+
+```bash
+todo export json    # JSON 格式（默认）
+todo export csv     # CSV 格式
+todo export md      # Markdown 表格
+```
+
+导出到文件：
+
+```bash
+todo export csv > todos.csv
+todo export md > todos.md
+```
+
+### 自动更新
+
+```bash
+todo update --check    # 检查是否有新版本
+todo update            # 安装最新版本
+```
+
+### 帮助与版本
+
+```bash
+todo --help      # 显示帮助（任意命令后均可加 --help）
+todo --version   # 显示版本
+```
+
+## 常用工作流
+
+### 工作流一：项目任务规划
+
+收到项目需求后，将拆解的任务批量创建：
+
+```bash
+todo add "搭建项目脚手架" -p high -c setup -d 2025-02-01
+todo add "实现用户认证模块" -p high -c feature -t auth -d 2025-02-05
+todo add "编写单元测试" -p medium -c test -d 2025-02-08
+todo add "编写集成文档" -p low -c docs -d 2025-02-10
+todo list --sort due
+```
+
+### 工作流二：每日任务回顾
+
+```bash
+# 查看待办概览
+todo stats
+
+# 查看今日紧急任务
+todo list --status pending --priority high --sort due
+
+# 搜索特定任务
+todo search "认证"
+
+# 完成任务
+todo done 3
+todo done 5
+
+# 归档已完成
+todo archive
+```
+
+### 工作流三：Bug 跟踪
+
+```bash
+# 添加 bug
+todo add "登录接口返回 500" -p high -c bug -t backend,auth --note "生产环境偶发"
+
+# 关联修复
+todo add "修复登录接口异常处理" -p high -c fix -t backend -d 2025-02-03
+
+# 修复后标记完成
+todo done 2
+
+# 查看未修复 bug
+todo list --category bug --status pending
+```
+
+### 工作流四：导出与汇报
+
+```bash
+# 导出为 Markdown 用于周报
+todo export md > weekly-todos.md
+
+# 导出为 CSV 用于数据分析
+todo export csv > todos.csv
+
+# 查看统计概览
+todo stats
+```
+
+## 最佳实践
+
+1. **标题简洁明确**：用动词开头，如「修复」「实现」「编写」
+2. **善用分类**：按工作类型分类（bug / feature / docs / test / admin）
+3. **标签交叉引用**：用标签关联跨分类维度（urgent / frontend / backend）
+4. **设置截止日期**：有明确 deadline 的任务务必加 `-d`，便于按日期排序和逾期追踪
+5. **备注补充上下文**：复杂任务用 `--note` 记录关键信息
+6. **定期归档**：完成的任务用 `todo archive` 清理，保持列表清爽
+7. **批量操作**：`todo done --all` 一次完成所有待办，减少重复命令
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| `todo` 命令不存在 | 执行安装流程（见前置检查） |
+| `✗ No todo with id N` | 先 `todo list` 确认有效 id |
+| `✗ Title is required.` | `add` 命令必须提供标题 |
+| `✗ Invalid due date` | 日期格式必须为 `YYYY-MM-DD` |
+| 退出码非 0 | 检查 stderr 输出的 `✗` 错误信息 |