md2do (Team Nick Hart)

md2do

](https://www.npmjs.com/package/@md2do/cli) ](https://www.npmjs.com/package/@md2do/cli)  ](https://nodejs.org/)  ](https://pnpm.io/)  

通过强大的过滤、排序和 简洁日程 同步。 使用TypeScript构建，专为喜欢markdown的开发人员设计。

✨ 特性

• 📝 Markdown原生 -直接使用现有的markdown文件
• 🔍 智能解析 -提取具有丰富元数据（受让人、优先级、截止日期、标签）的TODO
• 🎯 强大的过滤功能 -按受让人、优先级、项目、标签、截止日期等筛选
• 📊 丰富的统计数据 -按优先级、受让人、项目或任何元数据查看任务细分
• 🎨 漂亮的输出 -颜色编码的优先级，可点击的文件路径（VS Code集成）
• ⚡ 快 -使用快速glob以性能为出发点
• 🔧 灵活的 -以漂亮、表格或JSON格式输出
• 📁 上下文感知 -自动从文件夹结构中提取项目和人员上下文
• 🔄 Todoist集成 -导入任务并将完成状态与官方同步 简洁日程 API
• ⚙️ 可配置的 -分层配置支持（全局、项目、环境）
• 🤖 AI驱动 -Claude和其他AI助手的MCP服务器集成

📦 安装

npm

npm install -g @md2do/cli

pnpm

pnpm add -g @md2do/cli

纱线

yarn global add @md2do/cli

来源

git clone https://github.com/TeamNickHart/md2do.git
cd md2do
pnpm install
pnpm build
pnpm link:cli

🚀 快速开始

1. 导航到包含markdown文件的目录
2. 列出所有任务：

md2do list

1. 查看任务统计信息：

md2do stats

就是这样！md2do将扫描所有 .md 文件并提取TODO项目。

📖 用法

任务格式

md2do使用丰富的元数据识别标准markdown任务语法：

- [ ] Implement user authentication @jane !!! #backend #auth #due:2026-01-20
- [x] Write documentation @nick !! #docs {completed:2026-01-15}
- [ ] Fix bug in parser @alex ! #bug #due:2026-01-18

支持的元数据：

• @username -任务受让人
• !!! / !! / ! -优先级（紧急/高/正常）
• #tag -标签
• #due:YYYY-MM-DD -到期日
• {completed:YYYY-MM-DD} -竣工日期
• {todoist:ID} -待办事项同步ID
• - [x] -已完成任务
• - [ ] -任务未完成

注： 传统括号语法([due: ...], [completed: ...], [todoist: ...])仍在解析向后兼容性。

列出命令

显示具有过滤和排序功能的任务：

# List all tasks
md2do list

# Filter by assignee
md2do list --assignee nick

# Filter by priority
md2do list --priority urgent

# Filter by tag
md2do list --tag backend

# Show only incomplete tasks
md2do list --incomplete

# Show overdue tasks
md2do list --overdue

# Sort by priority
md2do list --sort priority

# Combine filters
md2do list --assignee nick --priority urgent --sort due

# Output as JSON
md2do list --format json

# Output as table
md2do list --format table

列表选项：

统计命令

查看有关任务的汇总统计信息：

# Overall statistics
md2do stats

# Group by assignee
md2do stats --by assignee

# Group by priority
md2do stats --by priority

# Group by project
md2do stats --by project

# Group by tag
md2do stats --by tag

# Filter before grouping
md2do stats --assignee nick --by priority

统计选项：

🤖 人工智能集成（MCP）

md2do包括一个 模型上下文协议（MCP） 服务器，使像克劳德这样的人工智能助手能够与您的 任务。MCP服务器通过标准化协议公开用于任务管理的工具、资源和提示。

什么是MCP？

模型上下文协议是Anthropic开发的一种开放协议，允许AI助手安全地连接到 外部数据源和工具。把它想象成人工智能助手的“语言服务器协议”。

Claude代码的快速设置：

# Build the MCP server
pnpm --filter @md2do/mcp build

# Add to your Claude Code configuration
# See packages/mcp/README.md for detailed instructions

可用功能：

• 🔧 工具: list_tasks, get_task_stats, search_tasks, get_task_by_id
• 📚 资源：按项目、人员、文件或所有任务访问任务
• 📋 提示：每日站立、冲刺总结、逾期审查模板

使用案例：

• 自动生成每日站立报告
• 让克劳德分析你的任务积压
• 获取基于人工智能的任务优先级建议
• 创建冲刺总结和进度报告

👉 完整的MCP文档 -完整的设置指南、API参考资料和示例

📁 项目结构和背景

md2do会自动从文件结构中提取上下文：

projects/
  acme-app/              # Project context: acme-app
    sprint-planning.md
    bugs.md
  widget-co/             # Project context: widget-co
    roadmap.md
1-1s/
  nick.md                # Person context: nick
  jane.md                # Person context: jane
personal/
  home.md

任务在 projects/acme-app/*.md 自动获取 project: acme-app 任务在 1-1s/nick.md 自动获取 person: nick

注： 运行时上下文提取有效 md2do list 从存储库根目录。这 --path 选项目前不保留项目/人员上下文。

🎨 输出示例

漂亮格式（默认）

Found 113 tasks
  ✓ 21 completed | ○ 92 incomplete

  ○ !!! Fix memory leak in WebSocket connection (2026-01-18) @nick #bug #critical
    file:///path/to/bugs.md:7

  ○ !! Design dashboard wireframes (2026-01-25) @emma #design #analytics
    file:///path/to/roadmap.md:9

表格格式

┌────────┬──────────┬──────────────────────────────┬──────────┬─────┬──────────────┐
│ Status │ Priority │ Task                         │ Assignee │ Due │ File         │
├────────┼──────────┼──────────────────────────────┼──────────┼─────┼──────────────┤
│ ○      │ !!!      │ Fix memory leak...           │ @nick    │     │ bugs.md:7    │
│ ○      │ !!       │ Design dashboard wireframes  │ @emma    │     │ roadmap.md:9 │
└────────┴──────────┴──────────────────────────────┴──────────┴─────┴──────────────┘

JSON格式

{
  "tasks": [
    {
      "id": "f777d4bd",
      "text": "Fix memory leak in WebSocket connection",
      "completed": false,
      "file": "bugs.md",
      "line": 7,
      "assignee": "nick",
      "priority": "urgent",
      "tags": ["bug", "critical"],
      "dueDate": "2026-01-18T00:00:00.000Z"
    }
  ],
  "metadata": {
    "total": 113,
    "completed": 21,
    "incomplete": 92
  }
}

🔧 发展

先决条件

• Node.js>=18.0.0
• pnpm>=9.0.0

设置

# Clone the repository
git clone https://github.com/TeamNickHart/md2do.git
cd md2do

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests in watch mode
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Format code
pnpm format

# Run all quality checks
pnpm validate

项目结构

md2do/
├── packages/
│   ├── core/          # Core parsing, filtering, and file writing
│   │   ├── src/
│   │   │   ├── parser/      # Markdown task parser
│   │   │   ├── scanner/     # File scanner
│   │   │   ├── filters/     # Task filtering
│   │   │   ├── sorting/     # Task sorting
│   │   │   ├── writer/      # File modification (atomic updates)
│   │   │   └── types/       # TypeScript types
│   │   └── tests/
│   ├── cli/           # CLI interface
│   │   ├── src/
│   │   │   ├── commands/    # List and stats commands
│   │   │   ├── formatters/  # Output formatters
│   │   │   └── scanner.ts   # File scanning
│   │   └── tests/
│   ├── config/        # Configuration management
│   │   ├── src/
│   │   │   ├── schema.ts    # Zod schemas for validation
│   │   │   └── loader.ts    # Hierarchical config loading
│   │   └── tests/
│   ├── todoist/       # Todoist API integration
│   │   ├── src/
│   │   │   ├── client.ts    # API client wrapper
│   │   │   └── mapper.ts    # Task format conversion
│   │   └── tests/
│   └── mcp/           # MCP server for AI integration
│       ├── src/
│       │   ├── tools/       # MCP tools (list, stats, search)
│       │   ├── resources/   # MCP resources (task URIs)
│       │   ├── prompts/     # MCP prompt templates
│       │   └── utils/       # Scanner utilities
│       └── tests/
├── docs/              # Documentation
│   ├── todoist-setup.md              # Todoist configuration guide
│   └── todoist-implementation-plan.md # Technical roadmap
├── examples/          # Example markdown files
└── .claude/          # Claude Code configuration

本地运行

# Build the project
pnpm build

# Link the CLI globally (choose one method)

# Method 1: Using convenience script (recommended)
pnpm link:cli

# Method 2: Run directly without global install
pnpm cli -- list --path examples
pnpm cli -- stats --path examples

# Method 3: Link from package directory
cd packages/cli && pnpm link --global

# Test it out (if using Method 1 or 3)
md2do list --path examples
md2do stats --path examples

# Unlink when done
pnpm unlink:cli

测试

我们使用Vitest进行高覆盖率的测试：

# Run all tests
pnpm test:run

# Run tests in watch mode
pnpm test

# Run tests for a specific package
pnpm --filter @md2do/core test

# Run tests with UI
pnpm --filter @md2do/core test:ui

测试覆盖范围：

• 14个测试套件中的359个测试
• 解析器测试（70次测试）
• 扫描仪测试（43次测试）
• 过滤器测试（41次测试）
• 分类测试（26项测试）
• 模式匹配测试（43项测试）
• 日期公用事业测试（45次测试）
• 写作测试（15次测试）
• 配置测试（26个测试）
• Todoist测试（31项测试）
• 还有更多！

📖 附加文档

• Todoist设置指南 -完整的配置指南 简洁日程 整合
• Todoist实施计划 -技术路线图和架构
• 配置包 -配置管理文档
• MCP包 -模型上下文协议服务器文档

🤝 贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试和验证(pnpm validate)
5. 提交您的更改(git commit -m 'Add some amazing feature')
6. 推到分支(git push origin feature/amazing-feature)
7. 打开拉取请求

代码质量

该项目保持高代码质量标准：

• ✅ 具有严格模式的TypeScript
• ✅ ESLint用于代码过滤
• ✅ 代码格式化的预处理
• ✅ 哈士奇的git挂钩
• ✅ lint已准备好进行预提交检查
• ✅ 全面的测试覆盖率
• ✅ Smart CI-跳过仅文档更改的代码质量检查（30秒vs 90秒）

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 建于 指挥官.js 用于CLI解析
• 风格与 粉笔 用于终端颜色
• 桌子由 对照表3
• 文件扫描 快速地球仪
• 日期处理 日期fns
• AI集成由 模型上下文协议SDK 通过Anthropic

🗺️ 路线图

• \[x\] MCP（模型上下文协议）集成 - ✅ 完成！看 MCP文件
• \[x\] 配置文件支持 - ✅ 完成！分层配置 .md2do.json/.yaml
• \[x\] Todoist集成基础 - ✅ 完成！API客户端、任务映射、文件编写器

- \[\]CLI命令(md2do todoist sync, md2do todoist push等等） - \[\]双向同步逻辑 - \[\]交互式令牌设置 - \[\]验证警告 {todoist:ID} 标记物 - \[\]检测格式错误的ID - \[\]验证Todoist中是否存在ID - \[\]警告孤立/删除的任务

CLI增强功能

• \[\]Markdown输出格式(--format markdown)

- \[\]具有保留元数据的机器可读标记 - \[\]轻松复制/粘贴到其他markdown文件

• \[\]持续监控的监视模式
• \[\]自定义输出模板
• \[\]列出文件中的所有受让人/标签(md2do list --assignees, md2do list --tags)

- \[\]检测重复和接近匹配（例如。， @nick vs @Nick) - \[\]显示使用频率和统计数据

• \[\]编辑对规范化元数据的支持

- \[\]规范跨文件的受让人（修复大小写不一致的问题） - \[\]规范化标签（合并同义词） - \[\]审查和批准变更的交互模式 - \[ \] --fix 标记以自动修复常见问题

• \[\]多值过滤器(--priority high,urgent, --tag backend,frontend)
• \[\]负过滤器(--no-assignee, --no-priority, --no-tags)
• \[\]日期范围筛选(--due-after DATE, --due-before DATE)
• \[\]结果限制(--limit N)
• \[\]配置检查(md2do config show)
• \[\]测试数据模拟(--simulate-date YYYY-MM-DD)

配置和定制

• \[\]精细的警告控制(.md2do-warnings.json 类似于 .markdownlint.json)

- \[\]启用/禁用特定警告类型 - \[\]警告严重级别 - \[\]每个项目的警告配置 - \[\]默认情况下关闭警告，按项目选择加入

• \[\]可配置的基于优先级的到期日默认值

- \[\]根据优先级自定义默认时间框架 - \[\]示例：紧急=今天，高=明天，正常=周末，低=下周 - \[\]CLI和编辑器扩展之间的共享配置

• \[\]默认情况下不区分大小写的标签和受让人

- \[\]可配置的区分大小写 - \[\]规范形式保存

智能功能和自动化

• \[\]基于优先级的截止日期推断

- \[\]到期日缺失时可选择自动分配 - \[\]尊重配置的优先级时间框架

• \[\]支持多个受让人

- \[\]主要受让人（首次提及） - \[\]次要受让人（额外@提及） - \[\]按任务中的任何受让人筛选

• \[\]增强的日期格式支持

- \[\]短格式： 1/25/26, 1/25 - \[\]自然语言： tomorrow, next week, next Monday, in 3 days - \[\]一天中的时间： (2026-01-25 9am), (tomorrow 2pm) - \[\]ISO 8601与时间： 2026-01-25T14:00

• \[\]基于ML的建议

- \[\]根据任务内容和模式建议优先级 - \[\]根据任务文本建议标签 - \[\]根据历史模式建议受让人

• \[\]VS Code扩展中的自动补全和智能默认值
• \[\]自动完成对受让人和标签的建议

- \[\]了解所有文件的现有用法 - \[\]上下文感知建议（文件、项目、最近使用情况） - \[\]模糊匹配和拼写错误更正

仪表板和可视化

• \[\]带有markdown模板的可配置仪表板

- \[\]利用现有的模板解决方案（调查：Handlebars、Mustache、Liquid） - \[\]可定制的小部件和布局 - \[\]导出为HTML/PDF

• \[\]VS代码扩展仪表板集成

- \[\]带有“漂亮”仪表板视图的侧面板 - \[\]文件更改时实时更新 - \[\]单击以获取任务

VS Code 扩展

• \[\]具有任务查看和过滤功能的核心扩展
• \[\]任务元数据的智能感知（@assignes、#标签、优先级）
• \[\]使用智能默认值自动完成到期日期
• \[\]快速操作（标记完成、更改优先级、设置截止日期）
• \[\]集成仪表板视图
• \[\]CodeLens显示每个文件的任务计数
• \[\]指定人员和标签的自动补全（从工作区学习）
• \[\]带有模糊匹配的内联建议

集成

• \[\]GitHub问题集成
• \[\]线性积分
• \[\]Jira集成
• \[\]概念整合

📞 支持

• 🐛 报告错误
• 💡 请求功能
• 📖 文档

______________________________________________________________________

制作🤖 + ❤️ 通过 尼克·哈特