内容
# todouz
一款**适合多动症（ADHD）用户的任务管理器**，具备任务分块、子问题、时间块和MCP服务器等功能，支持Claude Code / Claude Desktop / Cursor会话实时读写任务。
> 🔧 这是一个个人工具，我公开分享 - 不是一个完善的产品。预计会有粗糙的边缘。欢迎提交PR。
## 为什么它存在
大多数生产力工具假设你会计划一次并执行到底。多动症（ADHD）的大脑工作方式并非如此。todouz基于三个实际有效的原则构建：
- **基于精力，而非日历**。任务根据它们在你当天的精力水平中的位置浮现，而不是基于你会放弃的僵化时间表。
- **捕捉，而不是行动**。按下按键，倾泻你的想法，回到你正在做的事情。代理处理倾泻的内容，稍后转化为结构化工作。
- **与代理共工**。多个Claude会话可以通过MCP连接到你的todouz，协作处理你的数据 - 在任务分组中留下笔记，分解工作为子问题，安排时间块。单人生产力工具，多人协作执行。
## 功能
- **分层任务模型**：类别 → 任务分组 → 问题 → 子问题 → 子任务。任意嵌套深度。
- **重复任务实例**：本周的健身房锻炼是一个独立的对象，与下周的锻炼不同，以避免进度溢出。
- **时间块**：计划的工作会话，与问题和事件区分开来。在日历中显示。
- **磁盘上的Markdown**：每个问题、任务分组和笔记都以纯Markdown格式存储在`data/`目录下。支持Git，方便手动编辑和导出。无需SQL。
- **基于精力的今日视图**：今日到期 + 今日重复 + 今日计划块合并成一个时间顺序列表，而不是三个独立的小部件。
- **单页网络仪表盘**：现代编辑器风格的UI（Fraunces + Onest + JetBrains Mono），单页垂直滚动，滑动抽屉显示问题和任务分组的详细信息。
- **通用代理聊天**：内置聊天界面，支持 `@anthropic-ai/claude-agent-sdk` - 使用本地Claude CLI的OAuth订阅令牌（无需API密钥，无需按消息计费）。
- **MCP服务器**：38+工具暴露相同的数据层，供任何外部Claude会话使用。将其添加到Claude Code或Claude Desktop配置中，从任何地方修改任务。
- **存档视图**：搜索所有已完成的问题，支持按日期范围过滤。
## 技术栈
- Node.js 20+
- Express 5（HTTP API + 仪表盘静态文件服务）
- React 18（通过CDN + Babel-standalone，无需构建步骤）
- `@modelcontextprotocol/sdk`（stdio MCP服务器）
- `@anthropic-ai/claude-agent-sdk`（仪表盘内聊天）
- Markdown + JSON文件存储在磁盘上
## 本地运行
```bash
git clone https://github.com/llhtoby38/todouz.git
cd todouz
npm install
npm run seed # 一次性：复制启动代理模板到 data/ 目录
npm run start # 前台运行；或使用 ./start.sh --background
open http://localhost:8765/dashboard/
```
服务器默认监听端口8765。可以通过 `PORT=9000 npm start` 自定义端口。
### 认证
仪表盘内的聊天界面尝试使用本地**Claude Pro/Max订阅**，通过Claude CLI存储在操作系统密钥链中的OAuth令牌。如果令牌不存在，SDK会回落到环境变量中的 `ANTHROPIC_API_KEY`。如果两者都没有配置，则仅限读写工具工作，聊天功能不可用。
安装Claude CLI：<https://docs.anthropic.com/claude-code>
## MCP集成
将todouz集成到其他Claude Code会话中，可以在终端、编辑器或磁盘上的任何地方编辑任务。
**适用于Claude Code（用户范围，可在任何地方使用）：**
```bash
claude mcp add todouz \
--scope user \
-- \
node /绝对路径/to/todouz/mcp-server/index.mjs
```
然后在任何Claude Code会话中： *"todouz: 列出今日任务并告诉我该专注什么"* - 代理将调用 `list_today` + `whats_next` 并根据结果采取行动。
**适用于Claude Desktop**，请在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"todouz": {
"command": "node",
"args": ["/绝对路径/to/todouz/mcp-server/index.mjs"]
}
}
}
```
**适用于Cursor**，请在项目的 `.mcp.json` 中添加：
```json
{
"mcpServers": {
"todouz": {
"command": "node",
"args": ["/绝对路径/to/todouz/mcp-server/index.mjs"]
}
}
}
```
连接后，外部会话可以访问所有38+工具：`list_today`、`create_issue`、`create_subissue`、`add_timeblock`、`complete_issue`、`update_epic`、`get_full_context`（用户完整状态的一次性转储）等。详见 `docs/03-mcp-tools.md`。
## 项目布局
```
todouz/
├── dashboard/ 单页React SPA（无需构建步骤）
├── mcp-server/ stdio MCP + Express HTTP服务器
│ ├── index.mjs stdio MCP入口
│ ├── http-server.mjs HTTP API + 仪表盘静态文件服务 + 聊天流式传输
│ ├── tools.mjs 38+工具实现 + JSON-RPC目录
│ ├── parsers.mjs 纯Markdown ↔ AST转换
│ └── store.mjs 原子文件IO
├── data/ 您的个人数据（gitignored - 每个用户都有自己的数据）
├── examples/ 启动模板，复制到data/目录下
└── docs/ 架构 + 数据模型 + 工具 + 仪表盘规格
```
## 数据模型
每个可执行的事物都是**问题**，隶属于**任务分组**，而任务分组隶属于六大**类别**之一：学习、副项目、身体、厨房、未来规划、个人。问题可以嵌套为子问题和子任务。重复问题按日期实例化，因此编辑一个问题不会影响下一个日期的实例。时间块是链接到问题的计划工作会话。时间表是派生视图，不存储在磁盘上。
阅读 `docs/02-data-model.md` 以获取完整的关系图和磁盘文件格式。
## 自定义代理
代理角色存放在 `data/agents/<name>/system-prompt.md`。`examples/` 目录中的启动模板涵盖了几种常见角色（调度器、规划器）。编辑它们以匹配您的工作方式。每个代理都在自己的文件夹中运行，因此其系统提示和身份信息会输入到每个聊天会话中。
## 注意事项
- **单用户，单机器**。无认证，无多租户。数据目录按机器存储在磁盘上。
- **macOS优先支持OAuth检测**。Claude CLI凭证的密钥链探测仅在macOS上运行；Linux/Windows用户需要设置 `ANTHROPIC_API_KEY` 以使仪表盘聊天功能正常工作。
- **SPA通过CDN加载**。Babel-standalone + React UMD包在浏览器中转换JSX。迭代快速，但首次加载较慢。可接受用于个人工具；如果需要，可替换为Vite。
- **无撤销**。删除操作永久生效。请信任磁盘上的Markdown + Git记录历史。
## 作者
Lee Lok Hang Toby — <https://github.com/llhtoby38>
## 许可证
MIT — 见 [LICENSE](./LICENSE)。
