内容
# Do-It.nvim
[](https://github.com/bearded-giant/do-it.nvim/actions/workflows/run-tests.yml)
Do-It.nvim 是一个适用于 Neovim 的模块化任务管理框架，提供一个干净、无干扰的界面，直接在编辑器中管理任务和笔记。
Do-It.nvim 最初是作为一种跟踪任务和保持简单 Markdown 笔记的方式而创建的，适用于每个项目。作为一名有许多不同任务需要跟踪的主要工程师，我希望有一种简单的方法可以在不离开编辑器的情况下做到这一点。我尝试过许多任务管理器，但它们似乎都过于复杂 - 我只需要知道我需要做什么，而不需要额外的功能。
> 该项目是 [Dooing](https://github.com/atiladefreitas/dooing) 的一个分支，由 [atiladefreitas](https://github.com/atiladefreitas) 扩展，增加了模块化框架和附加插件，如项目笔记和日历。.
## 功能
- **模块化框架** - 只使用您需要的组件
- **任务管理** - 创建、组织和跟踪待办事项
- **项目笔记** - 维护项目特定的文档
- **标签和筛选** - 使用 #标签分类任务
- **截止日期** - 使用日历集成设置截止日期
- **优先级** - 分配和按重要性排序
- **时间估计** - 跟踪估计的完成时间
- **导入/导出** - 备份或分享您的任务
- **Lualine 集成** - 在状态栏中显示活动任务
- **Tmux 插件** - 可选的 Tmux 集成，共享数据（见下文）
## 快速入门
### 使用 Lazy.nvim 安装
```lua
return {
"bearded-giant/do-it.nvim",
config = function()
require("doit").setup()
end,
}
```
### 基本用法
1. **打开待办事项**: `:Doit` 或 `<leader>td`
2. **添加待办事项**: 在待办事项窗口中按 `n`
3. **切换状态**: 在待办事项上按 `x`
4. **打开笔记**: `:DoItNotes` 或 `<leader>dn`
## 安装选项
### 先决条件
- Neovim `>= 0.10.0`
- [Lazy.nvim](https://github.com/folke/lazy.nvim) 作为您的插件管理器
### 完整框架（推荐）
```lua
return {
"bearded-giant/do-it.nvim",
config = function()
require("doit").setup({
modules = {
todos = { enabled = true },
notes = { enabled = true }
}
})
end,
}
```
### 独立模块
单独使用模块，而不使用框架：
```lua
-- 仅待办事项
return {
"bearded-giant/do-it.nvim",
config = function()
require("doit_todos").setup()
end,
}
-- 仅笔记
return {
"bearded-giant/do-it.nvim",
config = function()
require("doit_notes").setup()
end,
}
-- 日历（v2.0）- 仅限 macOS，需要 icalbuddy
return {
"bearded-giant/do-it.nvim",
config = function()
require("doit").setup({
modules = {
calendar = { enabled = true }
}
})
end,
}
```
## 命令和快捷键
参见 [**完整快捷键参考**](docs/KEYBINDINGS.md)，获取所有命令和键盘快捷键。
### 快速参考
**框架命令：**
- `:DoItDashboard` - 打开主 DoIt 仪表盘
- `:DoItPlugins list` - 列出已安装的模块
- `:DoItPlugins info <module>` - 显示模块详细信息
**模块命令：**
_待办事项：_
- `:DoIt` - 打开主待办事项窗口
- `:DoItList` - 快速待办事项列表（浮动）
- `:DoItLists` - 管理多个待办事项列表
_笔记：_
- `:DoItNotes` - 打开笔记窗口
- `:DoItNotesNew` - 创建新项目笔记
- `:DoItNotesSearch` - 在笔记中搜索
_日历（仅限 macOS）：_
- `:DoItCalendar` - 切换日历窗口
- `:DoItCalendarDay` - 以日视图打开
- `:DoItCalendar3Day` - 以 3 日视图打开
- `:DoItCalendarWeek` - 以周视图打开
**基本键（在待办事项窗口中）：**
- `n` - 添加新待办事项
- `x` - 切换状态
- `d` - 删除待办事项
- `?` - 显示完整帮助
- `L` - 列表管理器
- `q` - 关闭窗口
快捷键文档是从中央源自动生成的，以确保一致性。在更改后运行 `make update-help` 以重新生成。
## 模块
### 待办事项模块
待办事项模块提供任务管理功能：
[完整文档](docs/modules/todos.md)
- 创建、编辑和组织待办事项
- 基于标签的筛选和组织
- 基于优先级的排序
- 带有日历集成的截止日期
- 时间估计跟踪
- 导入/导出功能
### 笔记模块
笔记模块提供项目特定的笔记：
[完整文档](docs/modules/notes.md) | **正在进行中**
- 基于 Git 仓库的项目特定笔记
- 全局笔记模式，用于系统范围的文档
- Markdown 语法高亮
- 浮动窗口界面
- 自动保存
### 日历模块（v2.0）
日历模块提供 macOS 日历集成：
[完整文档](lua/doit/modules/calendar/README.md) | [模块文档](docs/modules/calendar.md)
- **icalbuddy 集成**：查看 macOS 日历应用中的事件
- **多种视图**：日、3 日和周视图
- **智能解析**：处理 100% 的 icalbuddy 事件格式
- **UTF-8 支持**：正确显示特殊字符
- **自动刷新**：在切换视图时更新
- **所有日历源**：支持 iCloud、Google、Exchange
_注意：需要安装 icalbuddy（`brew install icalbuddy`）_
## 文档
- **用户指南**：在 Neovim 中查看 `:help doit`
- **框架文档**：`:help doit-framework`
- **开发者文档**：[docs/](./docs/) 目录
- **API 参考**：`:help doit-api`
## 配置
Do-It.nvim 使用嵌套配置结构，分离核心框架设置和模块特定选项。这使得导航和自定义更加容易。
### 配置结构
```lua
require("doit").setup({
-- 核心框架设置
development_mode = false,
quick_keys = true,
timestamp = { enabled = true },
lualine = { enabled = true, max_length = 30 },
project = {
enabled = true,
detection = { use_git = true, fallback_to_cwd = true },
},
-- 模块配置
modules = {
todos = {
enabled = true,
ui = {
window = {
width = 55,
height = 20,
border = "rounded",
},
-- 更多 UI 设置...
},
formatting = {
pending = { icon = "○" },
in_progress = { icon = "◐" },
done = { icon = "✓" },
},
priorities = {
{ name = "critical", weight = 16 },
{ name = "urgent", weight = 8 },
{ name = "important", weight = 4 },
},
-- 更多待办事项设置...
},
notes = {
enabled = true,
ui = {
window = {
-- 绝对大小
width = 80, -- 列
height = 30, -- 行
-- 或相对大小
relative_width = 0.6, -- 屏幕的 60%
relative_height = 0.6, -- 屏幕的 60%
use_relative = true, -- 切换模式
position = "center", -- 或 top-left, bottom-right 等
},
},
storage = {
path = vim.fn.stdpath("data") .. "/doit/notes",
mode = "project", -- 或 "global"
},
-- 更多笔记设置...
},
},
})
```
### 关键配置点
- **核心设置**（顶级）：框架范围的配置，如 `development_mode`、`lualine` 和 `project` 检测
- **模块设置**（`modules.todos` 和 `modules.notes`）：特定于每个模块，组织成逻辑组，如 `ui`、`storage`、`formatting` 等
- **向后兼容性**：插件维护对旧的扁平配置结构的支持
有关带有详细描述的所有配置选项的完整列表，请参见 [`lua/doit/config.lua`](./lua/doit/config.lua)。
同时，请在 Neovim 中查看 `:help doit-configuration` 以获取交互式文档。
## Lualine 集成
Do-It.nvim 提供了几个 lualine 组件，以在状态栏中显示待办事项信息：
```lua
require("lualine").setup({
sections = {
lualine_c = {
-- 显示当前列表和待办事项数量
{ require("doit").lualine.current_list },
-- 显示待办事项统计信息（已完成/进行中/待处理）
{ require("doit").lualine.todo_stats },
-- 显示活动待办事项（如果有）
{ require("doit").lualine.active_todo }
}
}
})
```
可用组件：
- `current_list` - 显示当前列表名称和待办事项数量：`📋 work (5)`
- `todo_stats` - 显示待办事项统计信息：`✓3 ◐1 ○2` （已完成/进行中/待处理）
- `active_todo` - 显示当前进行的待办事项（如果有）
## Tmux 集成（可选插件）
> **注意**：Tmux 集成是一个单独的可选插件，共享数据与 Neovim 插件。您可以不使用 Tmux，或同时使用两者，以在终端工作流中实现无缝体验。
Tmux 插件提供直接从 Tmux 进行待办事项管理，并与状态栏集成和基于 fzf 的交互式管理器。更改会在 Neovim 和 Tmux 之间自动同步。
### 先决条件
- [tmux](https://github.com/tmux/tmux) 搭配 [TPM](https://github.com/tmux-plugins/tpm)
- [fzf](https://github.com/junegunn/fzf) 用于交互模式
- [jq](https://stedolan.github.io/jq/) 用于 JSON 解析
### 安装
将以下内容添加到您的 `tmux.conf`：
```bash
set -g @plugin 'bearded-giant/do-it.nvim'
```
然后使用 `prefix + I` 安装。
### 快捷键
**使用前缀键（`prefix + d + ...`）：**
| 键 | 操作 |
|-----|---------------------------|
| `t` | 快速待办事项弹出窗口 |
| `i` | 交互式管理器（fzf） |
| `x` | 切换当前待办事项完成 |
| `n` | 新待办事项 |
| `N` | 启动下一个待办事项 |
**直接快捷方式（Alt+Shift）：**
| 键 | 操作 |
|---------------|---------------------|
| `Alt+Shift+T` | 快速待办事项弹出窗口 |
| `Alt+Shift+I` | 交互式管理器 |
| `Alt+Shift+X` | 切换待办事项完成 |
| `Alt+Shift+N` | 新待办事项 |
**交互式管理器：**
| 键 | 操作 |
|---------|-----------------------|
| `Enter` | 切换完成 |
| `s` | 开始/进行中 |
| `x` | 停止进行中 |
| `X` | 恢复到待处理 |
| `n` | 新待办事项 |
| `e` | 编辑待办事项文本 |
| `d` | 删除（可撤销） |
| `u` | 撤销最后删除 |
| `?` | 显示帮助 |
| `q` | 退出 |
在创建/编辑模式下：输入文本，两次 Enter 保存，Esc 取消。
### 配置
```bash
# 更改前缀键（默认：d）
set -g @doit-key "t"
# 禁用 Alt+Shift 快捷方式
set -g @doit-alt-bindings "off"
# 在创建/编辑时使用 $EDITOR（nvim, vim）而不是内联输入
set -g @doit-use-editor "true"
# 交互式管理器弹出窗口大小（默认：80% x 80%）
# 接受绝对单元格（“120”）或终端相关百分比（“80%”）
set -g @doit-interactive-popup-w "80%"
set -g @doit-interactive-popup-h "80%"
```
### 状态栏集成
如果使用 [bearded-giant-tmux](https://github.com/bearded-giant/bearded-giant-tmux) 主题，请在状态模块中添加 `todo`：
```bash
set -g @bearded_giant_status_modules_right "meetings todo"
```
对于其他主题，请直接使用状态脚本：
```bash
set -g status-right "#(~/.tmux/plugins/do-it.nvim/tmux/scripts/todo-status.sh)"
```
## MCP 服务器（Claude Code 集成）
Do-it.nvim 包含一个 MCP 服务器，暴露您的待办事项列表给 [Claude Code](https://claude.ai/code) 和其他 MCP 兼容工具。这允许您在不离开 AI 编程会话的情况下读取、创建、更新和搜索待办事项。
### 设置
```bash
cd mcp && npm install
```
将以下内容添加到您的 Claude Code `settings.json` 中的 `mcpServers` 下：
```json
{
"doit": {
"command": "node",
"args": ["/path/to/do-it.nvim/mcp/server.js"]
}
}
```
如果您在 do-it.nvim 设置中配置了自定义存储路径（通过 `modules.todos.storage.save_path`），请设置 `DOIT_DATA_DIR` 以匹配：
```json
{
"doit": {
"command": "node",
"args": ["/path/to/do-it.nvim/mcp/server.js"],
"env": {
"DOIT_DATA_DIR": "/your/custom/data/path"
}
}
}
```
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `list_todos` | 列出列表中的项目，按待处理/完成/进行中筛选 |
| `add_todo` | 创建带有可选注释的新待办事项 |
| `update_todo` | 编辑文本、描述或切换状态 |
| `delete_todo` | 删除项目（在 deleted_todos 中保留以便撤销） |
| `list_lists` | 显示所有列表的待处理/总数 |
| `switch_list` | 更改活动列表 |
| `search_todos` | 在所有列表中按文本搜索 |
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DOIT_DATA_DIR` | `~/.local/share/nvim/doit` | 数据目录路径 |
| `DOIT_ACTIVE_LIST` | （来自 session.json） | 覆盖活动列表名称 |
MCP 服务器读取和写入与 Neovim 插件和 Tmux 插件使用的相同的 JSON 文件。更改会自动同步。
## 贡献
参见 [开发者文档](./docs/)，获取：
- [开发设置和调试](./docs/development/DEVELOPMENT.md)
- [框架架构](./docs/development/framework.md)
- [模块开发指南](./docs/modules/)
- [实现笔记](./docs/implementation/)
## 路线图
- [x] 重新排序待办事项
- [x] 活动待办事项置顶
- [x] 项目笔记
- [x] 模块化框架
- [x] 待办事项类别（带有筛选）
- [x] 跨模块集成（待办事项-笔记链接）
- [x] 模块注册表（内部模块）
- [x] 命名（多个）待办事项列表
- [x] 类别视图窗口
- [x] 外部/自定义模块加载
## 致谢
Do-It.nvim 最初是 [Dooing](https://github.com/atiladefreitas/dooing) 的一个分支，由 [atiladefreitas](https://github.com/atiladefreitas) 创建。特别感谢他创建了原始插件。
项目笔记功能的灵感来自 maple.nvim 的项目笔记功能。
框架架构的灵感来自其他模块化的 Neovim 插件，如 mini.nvim 和 snack.nvim。
