<p align="center"><img src="docs/assets/logo.svg" width="76" alt="AgentTodo HUD"></p>

<h1 align="center">AgentTodo HUD</h1>

<p align="center">
  <strong>把注意力，留给重要的事。</strong><br>
  本地优先的桌面任务 HUD，让本机可调用的 Agent 替你整理、排优、同步待办<br>
  <sub>Local-first desktop task HUD for MCP-capable agents</sub>
</p>

<p align="center">
  <img alt="version 0.5.0" src="https://img.shields.io/badge/version-0.5.0-5fca8c?style=flat-square&amp;labelColor=17261e">
  <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-5fca8c?style=flat-square&amp;labelColor=17261e">
  <img alt="platform Windows 11" src="https://img.shields.io/badge/platform-Windows%2011-6e7d74?style=flat-square&amp;labelColor=17261e">
  <img alt="Electron 44" src="https://img.shields.io/badge/Electron-44-6e7d74?style=flat-square&amp;labelColor=17261e">
  <img alt="59 tests passing" src="https://img.shields.io/badge/tests-59%20passing-5fca8c?style=flat-square&amp;labelColor=17261e">
</p>

<p align="center">
  <img src="docs/assets/preview-night.webp" alt="AgentTodo HUD 任务总览：P0–P3 分组、快速录入与桌面 HUD 预览">
</p>

> **本地优先。** 任务只保存在本机 SQLite，网关只监听 `127.0.0.1`；没有账号、云端同步与遥测。

## 为什么

待办应用不缺，缺的是把「整理」交出去、把「专注」留下来的那一个。

AgentTodo HUD 常驻桌面一角，通过 MCP / HTTP 与你的 Agent 协作：你随口说一句，它把时间、优先级与步骤都排好；你只需要看下一件事，然后完成它。它不内置大模型，也不依赖任何云服务。

## 亮点

- **一句话录入** —— `记一下：明天下午3点前交测试包，P1，30分钟 #发布`，截止时间、优先级、时长、标签与子步骤全部在本地解析。
- **Agent 接入** —— MCP Streamable HTTP / stdio、HTTP API、SSE；复制一段提示词，Agent 自己完成注册与自检。
- **桌面 HUD** —— 无边框透明窗口，始终置顶、鼠标穿透、托盘驻留；实时捕获并模糊 HUD 背后的桌面，做出 iOS 式毛玻璃（约每 8 秒刷新）。
- **日与夜，自动切换** —— 06:00–18:00 日间霜面玻璃，其余时间夜间极光玻璃；跨过边界时平滑过渡。
- **键盘优先** —— `Ctrl / ⌘ + K` 命令面板、`N` 新建、`/` 搜索、`?` 快捷键、`1–5` 切页；完成与归档都可以撤销。
- **本地优先** —— SQLite + WAL，凭据只存哈希，网关拒绝跨域写入；没有后台云服务，不需要注册。

## 桌面 HUD

| 日间 · 霜面玻璃 | 夜间 · 极光玻璃 |
| :---: | :---: |
| <img src="docs/assets/hud-day.webp" width="290" alt="桌面 HUD · 日间"> | <img src="docs/assets/hud-night.webp" width="290" alt="桌面 HUD · 夜间"> |

卡片内是实时捕获并模糊的桌面，卡片外保持清晰；毛玻璃约每 8 秒刷新一次，显示、拖动结束与鼠标进入时会立即刷新。`Alt + Space` 切换穿透，`Alt + H` 显示 / 隐藏，`Alt + Enter` 完成当前第一项。

## 快速开始

环境：**Windows 11**（Windows 10 理论兼容，未单独验证）· **Node.js ≥ 22.13** · npm

```powershell
npm install
npm run dev
```

`npm run dev` 会同时启动本地网关（`127.0.0.1:17530`）、Vite（`127.0.0.1:5173`，HMR）与 Electron 桌面端。关闭窗口只会收进托盘，结束开发请按 `Ctrl + C`。

仓库暂不提供预编译安装包；`npm run package` 可生成 Windows 便携版。首次启动是空列表，可点「载入文档示例」快速预览完整界面。

Windows 上也可以直接双击 **`启动 AgentTodo.cmd`**：自动安装依赖、构建并打开应用。手动运行构建产物：

```powershell
npm run build
npm start
```

### 常用命令

| 命令 | 作用 |
| --- | --- |
| `npm run dev` | 开发预览：网关 + Vite + 桌面端 |
| `npm run build` | 类型检查 + 生产构建 |
| `npm start` | 打开已构建的桌面应用 |
| `npm test` | 59 个后端 / 网关 / MCP / 解析用例 |
| `npm run package` | 构建 + 生成 Windows 便携版并验证 |
| `npm run verify:ui` | 需先 `npm run build`；Playwright 真实页面冒烟（新建 → 完成） |
| `npm run verify:theme` | 日 / 夜主题与 HUD 渲染验收 |

## 接入 Agent

推荐「提示词接入」，不需要手写配置：

1. 打开应用 → **Agent 接入** → **复制接入提示词**；
2. 粘贴给能在本机执行命令或发送 HTTP 请求的 Agent；
3. Agent 自动注册、保存凭据，并读取现有待办完成自检；接入列表实时更新。

提示词 30 分钟内有效；已接入的 Agent 使用自己的持久凭据继续工作，凭据只保存哈希。

MCP 客户端也可以直接连接（需先启动应用，保持本地网关运行）：

```json
{
  "mcpServers": {
    "agenttodo-hud": { "url": "http://127.0.0.1:17530/mcp" }
  }
}
```

```text
工具：quick_capture · get_active_tasks · sync_todo_list · update_task_status · append_subtasks · connect_agent
```

stdio 客户端用 `server/stdio.mjs`（或 `npm run mcp`）启动桥接，只访问本地网关，不会另开数据库。

## 一句话录入

```text
记一下：明天下午3点前把周报发给老王，P1，30分钟 #工作；顺便清理已合并的本地分支
```

Agent 调用 `quick_capture`（HTTP 为 `POST /api/v1/tasks/capture`），服务端在本地一步解析并写入：

| 输入片段 | 解析结果 |
| --- | --- |
| `P0`–`P3` / 紧急 / 尽快 | 优先级（未写默认 P2；P0 同时最多 3 项，超出自动记为 P1） |
| 今天 / 明天 / 周X / 10月25日 / 15:30 | 带本地时区的截止时间 |
| 30分钟 / 半小时 / 1.5小时 | 预计耗时 |
| `#工作` / `步骤：…` / `；` | 标签、子步骤、一次多件（最多 20 件） |

重复说同一件事不会重复建卡，只补全缺失的时间、时长与标签；支持 `dry_run` 预览，同一次录入可在同步条整体撤销。解析器不依赖大模型，离线可用。

<details>
<summary>HTTP API</summary>

服务只监听 `127.0.0.1:17530`，拒绝非本机 Host 与未知网页 Origin。下列为常用端点，完整参数与同步模式见 [完整使用手册](docs/manual.md)。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/v1/health` | 服务状态 |
| GET | `/api/v1/connection-prompt` | 生成当前网关的接入提示词 |
| GET | `/api/v1/state` | 全部任务、配置与同步日志 |
| GET | `/api/v1/tasks?status=pending` | 未完成任务与 revision |
| GET | `/api/v1/events` | SSE 实时更新 |
| POST | `/api/v1/tasks` | 新建任务 |
| PUT | `/api/v1/tasks/:id` | 编辑任务 |
| POST | `/api/v1/tasks/sync` | Agent 同步与重排 |
| POST | `/api/v1/tasks/capture` | 快捷录入（支持 `dry_run`） |
| POST | `/api/v1/capture/parse` | 只解析、不写库 |
| PATCH | `/api/v1/tasks/:id/status` | 更新任务状态 |
| POST | `/api/v1/tasks/:id/subtasks` | 追加子任务 |
| PATCH | `/api/v1/tasks/:id/subtasks/:subId` | 勾选子任务 |
| PATCH | `/api/v1/tasks/:id/pin` | 锁定 / 解锁手动优先级 |
| POST | `/api/v1/tasks/rollback` | 撤销最近一次 Agent 同步 |
| PATCH | `/api/v1/settings` | 更新设置 |
| POST | `/api/v1/agents/register` | 用配对令牌注册 Agent |
| GET | `/api/v1/agents` | Agent 接入与活动记录（不含凭据） |
| DELETE | `/api/v1/agents/:id` | 断开并撤销凭据 |

同步支持 `merge_and_reprioritize`、`append_only`、`replace_all_pending` 三种模式；所有写入在事务内完成，revision 单调递增。

</details>

## 技术栈

| 层 | 技术 |
| --- | --- |
| 界面 | React 19 · TypeScript 5.8 · Vite 6 · Motion · lucide-react |
| 桌面 | Electron 44（无边框窗口 / 托盘 / 全局快捷键 / desktopCapturer） |
| 服务 | Node.js · Express 5 · SQLite（`node:sqlite`，WAL） |
| Agent | MCP TypeScript SDK（HTTP + stdio）· REST · SSE |
| 验证 | `node:test`（59 用例）· Playwright（冒烟 / 视觉 / 主题） |

## 项目结构

```text
src/       React 界面：任务总览、专注、已完成、Agent 接入、设置、桌面 HUD
desktop/   Electron 主进程、托盘与窗口管理、HUD 毛玻璃捕获、受限 preload
server/    SQLite 领域层、本地自然语言解析、Express 网关、MCP HTTP / stdio
tests/     59 个后端 / 网关 / MCP / 持久化 / 解析用例
scripts/   构建、打包、产物验证、Playwright 冒烟 / 视觉 / 主题脚本
docs/      完整手册、优化记录、特性实现与验收报告
design/    设计规范与概念图
public/    首帧主题引导脚本与 favicon
```

## 文档

| 文档 | 内容 |
| --- | --- |
| [完整使用手册](docs/manual.md) | 安装、接入、API、桌面能力与数据存储 |
| [设计规范](design/spec.md) | Liquid Glass 视觉基线（v0.3.0 起） |
| [快捷录入](docs/quick-capture.md) | 解析规则、多件录入与去重 |
| [日 / 夜主题](docs/day-night-theme.md) | 自动切换、日间材质与验收 |
| [HUD 毛玻璃](docs/hud-frost.md) | 实时捕获与模糊的实现、成本与取舍 |
| [优化记录](docs/optimizations.md) | 缺陷修复与性能数据 |
| [v0.5.0 验收](docs/verify-v050.md) | 249 项主题断言与独立验收（含如实标注的 PENDING 项） |

## 更多界面

<details>
<summary>日间主题 · Agent 接入 · 专注模式</summary>

<img src="docs/assets/preview-day.webp" alt="日间主题：清晨薄雾壁纸与白色霜面玻璃">

<img src="docs/assets/agents.webp" alt="Agent 接入：复制一段话，Agent 自己完成接入">

<img src="docs/assets/focus.webp" alt="专注模式：一次只做一件事">

</details>

## 数据与隐私

- 桌面端数据库：`%APPDATA%/AgentTodo HUD/tasks.sqlite`；开发网关：`.data/tasks.sqlite`
- 网关只监听本机，拒绝非本机 Host 与未知 Origin；不提供云端中转
- Agent 凭据只保存哈希，导出与公共状态不包含私钥
- 没有账号、遥测与云端依赖；关闭桌面应用后，由它启动的本地网关也会停止
- 删除 `%APPDATA%/AgentTodo HUD` 目录即可清空全部数据

## 已知边界

- **Windows 11** 上完成 v0.5.0 验收；Windows 10 理论兼容但未单独验证；macOS 源码路径兼容，未实测
- 毛玻璃约每 8 秒刷新；每次刷新约 0.3 秒的捕获窗口内，HUD 不会出现在其他程序的截图 / 录屏里，其余时间正常可见
- 远程云端或网页版 Agent 无法直接访问 `127.0.0.1`，需要在本机运行桥接
- 图标层嵌入、全屏检测自动折叠、开机自启、远程中转与内置大模型尚未实现

## License

[MIT](LICENSE) © 2026 AgentTodo HUD

---

<p align="center"><sub>AgentTodo HUD · 让 Agent 负责整理，让你负责专注</sub></p>