effortlist-ai

管理 EffortList AI 文件夹、任务和待办事项。当用户想要通过 EffortList AI 平台组织生活、跟踪项目或管理日程时使用。支持完整的 CRUD 操作、级联删除和原子撤消/重做历史记录以确保数据完整性。

# 📋 EffortList AI (Universal Skill)

## 🌟 Value Proposition (For Humans)

EffortList AI is a sophisticated life-management platform that merges advanced Generative AI with a robust, deterministic scheduling engine. Use this skill to give your agent full control over your project organization, time protection, and project lifecycles.

## 🚀 Setup & Authentication

1. **Subscription:** Requires a developer subscription ($5/month) at [effortlist.io](https://www.effortlist.io).
2. **API Key:** Human user must generate a **Persistent API Key** in Developer Settings.
3. **Storage:** Provide the key via the `EFFORTLIST_API_KEY` environment variable or OpenClaw internal config (`openclaw config set skills.entries.effortlist-ai.env.EFFORTLIST_API_KEY "your_key"`).

## 📐 Mental Model (Data Hierarchy)

EffortList AI operates on a strictly nested hierarchy:
**Folder (Container)** ──> **Task (Project)** ──> **Todo (Actionable Slot)**

- **Folders:** Optional top-level containers for grouping related projects.
- **Tasks:** Actionable projects that can be top-level or nested in a Folder.
- **Todos:** Granular actionable steps. **Every Todo MUST have a parent Task.**

## 🤖 Intelligence & Mapping (For Agents)

| User Intent      | Agent Workflow                     | Endpoint Goal                                  |
| :--------------- | :--------------------------------- | :--------------------------------------------- |
| "Plan a project" | Create Folder -> Tasks -> Todos    | `POST /folders`, `POST /tasks`, `POST /todos`  |
| "Fix my mistake" | Fetch History -> Target ID -> Undo | `GET /api/v1/undo`, `POST /api/v1/undo?id=...` |
| "Show my day"    | Fetch Todos by Date Range          | `GET /api/v1/todos?from=...&to=...`            |
| "Check settings" | Fetch User Profile & Schedule      | `GET /api/v1/me`                               |
| "Surgical Edit"  | Patch update a specific record     | `PATCH /api/v1/{type}?id=...`                  |
| "Manage Links"   | Create or update booking links     | `POST/PATCH /api/v1/availability/links`        |
| "Review Appts"   | Accept or decline appointments     | `PATCH /api/v1/appointments/{id}`              |

## 🛠️ Execution Logic (The "Omni" Way)

1. **Surgical Extraction & Patching:** Always prefer fetching a specific record by its ID (`GET ?id=...`) over broad list fetches. When updating, use `PATCH` with the record `?id=`.
2. **Phase-Aware Scheduling:** Be mindful of the 5-phase Omni processing loop. Proactively flag events with `isProtectedTime: true` to trigger the server-side safety net. Use `ignoreConflicts: true` only when explicit user intent overrides overlap protection.
3. **Appointment Awareness:** Be extremely cautious when deleting or rescheduling items where `isBooked: true`. This triggers automatic guest notifications/cancellations. Confirm with the user before performing destructive actions on booked slots.
4. **Efficiency & Throttling:** Respect the **100 requests per minute** rate limit. For bulk operations, batch requests appropriately and check `X-RateLimit-Remaining` headers.
5. **Pagination:** When listing folders, tasks, or todos, use `limit` and `offset` for large datasets.
6. **Scheduling Alignment:** Before blocking large segments of time or creating new recurring todos, use `GET /api/v1/me` to align with the user's `weeklySchedule`, `timezone`, and `minimumNotice` preferences.
7. **Cascading Safety:** Be aware that deleting a Folder or Task is an **Atomic Purge**. However, the engine protects items that are simultaneously being updated from accidental deletion.
8. **Temporal Fidelity:** When reporting event times to the user, strictly respect the user's `timezone` and local time offset (e.g., CDT vs. CST). Provide dates and times exactly as they appear in the local context or as explicitly requested, without performing unsolicited manual shifts. Use the `/me` endpoint to confirm the active offset before finalizing any scheduling summaries.
9. **Global Availability Awareness:** Before modifying booking links or schedules, use `GET /api/v1/availability` to retrieve the current `weeklySchedule`, `timezone`, and `minimumNotice` settings.
10. **Undo/Redo Competency:** If a destructive operation is performed in error, use the Undo stack (`POST /api/v1/undo`) to restore state.

## 🔒 Security & Privacy (Zero Trust)

- **Data Isolation:** Strict row-level security; users only see their own data.
- **AI Privacy:** Your personal data is **never** used to train models.

## 📖 Deep References

- **Full API Reference:** [API DOCs](https://www.effortlist.io/docs)
- **Omni Architecture:** (Located in references/architecture.md)
- **Security Audit Docs:** [SECURITY](https://www.effortlist.io/security)

---

## 中文说明

# 📋 EffortList AI（通用技能）

## 🌟 价值主张（面向人类用户）

EffortList AI 是一个复杂的生活管理平台，它将先进的生成式 AI 与稳健的确定性调度引擎相结合。使用此技能，让你的代理全面掌控你的项目组织、时间保护和项目生命周期。

## 🚀 设置与身份验证

1. **订阅：** 需要在 [effortlist.io](https://www.effortlist.io) 上购买开发者订阅（5 美元/月）。
2. **API 密钥：** 人类用户必须在开发者设置中生成一个**持久 API 密钥**。
3. **存储：** 通过 `EFFORTLIST_API_KEY` 环境变量或 OpenClaw 内部配置（`openclaw config set skills.entries.effortlist-ai.env.EFFORTLIST_API_KEY "your_key"`）提供密钥。

## 📐 思维模型（数据层级）

EffortList AI 采用严格的嵌套层级结构：
**文件夹（容器）** ──> **任务（项目）** ──> **待办事项（可执行时段）**

- **文件夹：** 可选的顶层容器，用于对相关项目进行分组。
- **任务：** 可执行的项目，可以是顶层的，也可以嵌套在文件夹中。
- **待办事项：** 细粒度的可执行步骤。**每个待办事项都必须有一个父任务。**

## 🤖 智能与映射（面向代理）

| 用户意图      | 代理工作流                     | 端点目标                                  |
| :--------------- | :--------------------------------- | :--------------------------------------------- |
| "规划一个项目" | 创建文件夹 -> 任务 -> 待办事项    | `POST /folders`, `POST /tasks`, `POST /todos`  |
| "修正我的错误" | 获取历史记录 -> 目标 ID -> 撤消 | `GET /api/v1/undo`, `POST /api/v1/undo?id=...` |
| "显示我的一天"    | 按日期范围获取待办事项          | `GET /api/v1/todos?from=...&to=...`            |
| "查看设置" | 获取用户资料和日程      | `GET /api/v1/me`                               |
| "精准编辑"  | 修补更新某条特定记录     | `PATCH /api/v1/{type}?id=...`                  |
| "管理链接"   | 创建或更新预约链接     | `POST/PATCH /api/v1/availability/links`        |
| "审核预约"   | 接受或拒绝预约     | `PATCH /api/v1/appointments/{id}`              |

## 🛠️ 执行逻辑（"Omni" 之道）

1. **精准提取与修补：** 始终优先按 ID 获取特定记录（`GET ?id=...`），而非进行宽泛的列表获取。更新时，使用带记录 `?id=` 的 `PATCH`。
2. **阶段感知调度：** 注意 5 阶段的 Omni 处理循环。主动用 `isProtectedTime: true` 标记事件以触发服务端的安全网。仅当用户明确意图覆盖重叠保护时才使用 `ignoreConflicts: true`。
3. **预约感知：** 删除或重新安排 `isBooked: true` 的项目时务必极其谨慎。这会触发自动的访客通知/取消。在对已预约时段执行破坏性操作前，请向用户确认。
4. **效率与限流：** 遵守 **每分钟 100 次请求** 的速率限制。对于批量操作，适当地批处理请求并检查 `X-RateLimit-Remaining` 响应头。
5. **分页：** 列出文件夹、任务或待办事项时，对大型数据集使用 `limit` 和 `offset`。
6. **调度对齐：** 在阻塞大段时间或创建新的周期性待办事项之前，使用 `GET /api/v1/me` 与用户的 `weeklySchedule`、`timezone` 和 `minimumNotice` 偏好对齐。
7. **级联安全：** 注意删除文件夹或任务是一次**原子清除**。不过，引擎会保护正在被同时更新的项目，避免意外删除。
8. **时间保真：** 向用户报告事件时间时，严格尊重用户的 `timezone` 和本地时间偏移（例如 CDT 与 CST）。完全按本地上下文中显示的方式或按明确请求的方式提供日期和时间，不要进行未经请求的手动偏移。在最终确定任何调度摘要前，使用 `/me` 端点确认当前生效的偏移量。
9. **全局可用性感知：** 在修改预约链接或日程之前，使用 `GET /api/v1/availability` 获取当前的 `weeklySchedule`、`timezone` 和 `minimumNotice` 设置。
10. **撤消/重做能力：** 如果错误地执行了破坏性操作，使用撤消栈（`POST /api/v1/undo`）恢复状态。

## 🔒 安全与隐私（零信任）

- **数据隔离：** 严格的行级安全；用户只能看到自己的数据。
- **AI 隐私：** 你的个人数据**绝不**会被用于训练模型。

## 📖 深入参考

- **完整 API 参考：** [API DOCs](https://www.effortlist.io/docs)
- **Omni 架构：**（位于 references/architecture.md）
- **安全审计文档：** [SECURITY](https://www.effortlist.io/security)