# Dida Todo Agent

Dida365（滴答清单）MCP Server + Agent Skill，让 AI Agent 用自然语言管理你的待办事项。

核心是一个**规则引擎**：通过可配置的路由规则，自动将自然语言任务分配到正确的项目、设定优先级和标签，避免 AI 自由发挥导致分类混乱。

## 核心特性

### 🎯 规则引擎驱动的任务路由

不再依赖 AI 的"直觉"来分类任务。通过 [Routing Profile](skill/references/routing-profile-guide.md) 定义明确规则：

- **项目路由**：为每个 Dida365 项目定义用途、正例、反例和优先级，语义匹配 + 优先级裁决
- **优先级策略**：基于截止时间、阻塞性、关键交付等维度设定优先级（0/1/3/5），规则独立于项目名称
- **标签管理**：自动匹配已有标签；新标签与任务合并确认，并通过任务 `tags` 字段 inline 写入
- **路由锁定**：每次写操作必须携带当前 routing revision，配置过期时自动重新读取，防止错误分类

示例路由配置：

```
分类顺序：
1. 个人事务和生活提醒 → 个人提醒项目
2. 影响结果的工作、领导要求或关键交付 → 重要工作项目
3. 不重要且近期没有截止时间的工作 → 非紧急工作项目
4. 其余日常工作 → 一般工作项目

优先级规则（独立于项目）：
- 紧急、阻塞或 24 小时内的关键交付 = 5
- 近期普通交付 = 3
- 可延后的规划 = 1
- 日常生活提醒 = 0
```

### 🔒 安全写入流程

所有状态变更操作都经过两步确认：

1. **Prepare**：服务端返回 5 分钟有效、绑定请求参数的一次性 confirmation token
2. **Confirm**：用户明确确认后，Agent 才用该 token 提交操作

适用于：完成任务、删除任务、创建带新标签的任务、保存路由配置等。Dida365 Open API 的独立标签创建端点不可靠，因此新标签不单独调用 `POST /tag`。

### 🔐 凭证隔离

Client Secret 和 OAuth Token 只存 OS Keyring，不落盘、不进日志、不进聊天记录。

## 架构

```
┌─────────────────────────────────────────────┐
│              Agent Framework                 │
│  (OpenClaw / Claude Desktop / Cursor / ...) │
├─────────────────────────────────────────────┤
│         Skill (dida-todo-agent)             │
│  自然语言理解 · 规则匹配 · 确认交互        │
├─────────────────────────────────────────────┤
│         MCP Server (dida365-mcp)            │
│  OAuth · 凭证 · 路由校验 · 任务 CRUD       │
│  确认令牌 · 操作日志 · 并发冲突检测         │
├─────────────────────────────────────────────┤
│              Dida365 Open API               │
│         api.dida365.com/open/v1             │
└─────────────────────────────────────────────┘
```

- **MCP Server**：规则引擎的执行层。负责 OAuth、凭证存储、路由配置校验、任务读写、确认令牌、操作日志和并发冲突检测。通过标准 stdio MCP 协议与宿主 Agent 通信。
- **Agent Skill**：规则引擎的决策层。负责自然语言理解、项目路由匹配、优先级判定、标签匹配和用户确认交互。适配任何支持 MCP 的 Agent 框架。

## 快速开始

### 1. 安装

```bash
cd dida-todo-agent
uv sync --frozen --extra dev
```

### 2. 配置 Dida365 应用凭证

```bash
.venv/bin/dida365-mcp-admin configure-app
```

按提示输入 Dida365 开放平台的 Client ID 和 Client Secret。凭证只保存在操作系统 Keyring 中，不要粘贴到聊天或提交到 README、Agent 配置文件。

### 3. OAuth 授权

启动 MCP 服务后调用 `start_oauth`，工具返回授权 URL。在浏览器中打开 URL 完成授权，然后调用 `auth_status` 验证授权确实成功。

### 4. 在宿主 Agent 中注册 MCP Server

标准 stdio 启动配置：

```json
{
  "command": ".venv/bin/python",
  "args": ["-m", "dida365_mcp.server"],
  "cwd": "."
}
```

服务端预期暴露 16 个工具（MCP tools）。不同 Agent 框架只需映射 command、args 和 cwd；不要把本机绝对路径、令牌或密钥提交到配置文件。

### 5. 注册 Agent Skill

将 `skill/` 目录复制到 Agent 框架的技能目录中。以 OpenClaw 为例：

```bash
cp -r skill/ ~/.openclaw/skills/dida-todo-agent/
```

### 6. 配置路由规则

参考 [Routing Profile Guide](skill/references/routing-profile-guide.md) 编写你的路由配置，通过 `save_routing_profile` 工具写入。路由配置定义了项目用途、优先级策略和标签规则。

## 项目结构

```
dida-todo-agent/
├── src/dida365_mcp/        # MCP Server
│   ├── server.py            #   MCP 工具入口 + _parse JSON 修复
│   ├── credentials.py       #   OS Keyring 凭证存储
│   ├── oauth.py             #   OAuth 2.0 回调流程
│   ├── dida_client.py       #   Dida365 API 客户端
│   ├── routing.py           #   路由配置校验
│   ├── confirmations.py     #   确认令牌管理
│   ├── ledger.py            #   操作日志
│   └── ...
├── skill/                   # Agent Skill
│   ├── SKILL.md             #   技能定义（路由决策、确认流程）
│   └── references/          #   适配器契约、行为用例、路由指南
├── tests/                   # 测试套件
└── scripts/                 # OAuth 授权辅助脚本
```

## 开发

```bash
uv run pytest -q             # 运行测试
uv run ruff check src tests  # 代码检查
uv run mypy src              # 类型检查
```

## License

MIT