内容
# 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），规则独立于项目名称
- **标签管理**：自动匹配已有标签，新标签必须用户确认才能创建
- **路由锁定**：每次写操作必须携带当前 routing revision，配置过期时自动重新读取，防止错误分类
示例路由配置：
```
分类顺序：
1. 个人事务和生活提醒 → 个人提醒项目
2. 影响结果的工作、领导要求或关键交付 → 重要工作项目
3. 不重要且近期没有截止时间的工作 → 非紧急工作项目
4. 其余日常工作 → 一般工作项目
优先级规则（独立于项目）：
- 紧急、阻塞或 24 小时内的关键交付 = 5
- 近期普通交付 = 3
- 可延后的规划 = 1
- 日常生活提醒 = 0
```
### 🔒 安全写入流程
所有状态变更操作都经过两步确认：
1. **Prepare**：服务端返回 5 分钟有效、绑定请求参数的一次性 confirmation token
2. **Confirm**：用户明确确认后，Agent 才用该 token 提交操作
适用于：完成任务、删除任务、创建标签、保存路由配置等。
### 🔐 凭证隔离
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 中。
### 3. OAuth 授权
启动 MCP 服务后调用 `start_oauth`，工具返回授权 URL。在浏览器中打开 URL 完成授权，然后调用 `auth_status` 验证。
### 4. 在宿主 Agent 中注册 MCP Server
标准 stdio 启动配置：
```json
{
"command": "<path-to-project>/.venv/bin/python",
"args": ["-m", "dida365_mcp.server"],
"cwd": "<path-to-project>"
}
```
### 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
