介绍
# 🦞 clawdo — The missing todo list for AI agents
你的智能体有记忆文件、定时任务（cron jobs）和聊天功能，但唯独缺少待办事项列表。
没有任何方式可以说 **“等有空的时候做这个。”** 不是“在 UTC 时间 14:00 做”。不是“就在这次对话中现在做”。仅仅是……记得要做。跟踪它。有空时捡起来做。
这就是 clawdo。
## 安装
```bash clawhub install clawdo # installs skill + docs into your workspace npm install -g clawdo # install the CLI binary ```
**要求：** Node.js ≥18
## 快速开始
```bash # Capture a task clawdo add "update dependencies" --urgency soon
# Agent checks its queue (heartbeat, cron, conversation — wherever) clawdo inbox --format json
# Agent works it clawdo start a3f2 clawdo done a3f2 --json ```
`add → inbox → start → done`。基于 SQLite 的持久化状态。每个命令都有 `--json` 选项，因此智能体解析的是结构化输出，而非终端艺术字。
## 适用场景
clawdo 适用于智能体工作的任何地方：
- **心跳循环** — “队列里有什么吗？让我在检查间隙处理一下” - **定时任务** — “每小时处理一个任务” - **对话** — “J 提到了修复 auth 模块，让我记下来” - **管道和子智能体** — 非TTY 安全，无交互式提示
### 心跳集成示例
```bash # In HEARTBEAT.md — runs every ~30 minutes TASKS=$(clawdo inbox --format json) AUTO=$(echo "$TASKS" | jq '.autoReady | length')
if [ "$AUTO" -gt 0 ]; then TASK=$(clawdo next --auto --json | jq -r '.task.id') clawdo start "$TASK" --json # ... do the work ... clawdo done "$TASK" --json fi ```
## 自主级别
任务可以标记为权限层级，用于控制允许智能体在无人监督下执行的操作：
| 级别 | 时间限制 | 含义 | |-------|------------|---------------| | **auto** | 10 分钟 | 智能体静默执行。修复拼写错误，运行测试。 | | **auto-notify** | 30 分钟 | 智能体执行，完成后通知人类。 | | **collab** | 无限制 | 需要人类介入。复杂、有风险或模棱两可的任务。 |
默认：`collab`（安全）。
**关键规则：** 自主级别是一种权限，而非建议。一旦设定，智能体无法更改。如果智能体失败 3 次，自主级别将*降级*为 `collab`。安全措施只能向下调整，绝不能向上。
**智能体提议，人类批准。** 智能体任务始终以 `proposed` 状态开始。人类需运行 `clawdo confirm <id>`，否则任务不会执行。
## 用法
### 面向人类
```bash # Add tasks — inline metadata parsing clawdo add "deploy new API +backend auto-notify now" # └── text ──────┘ └project┘ └─level──┘ └urg┘
# View clawdo list # active tasks clawdo list --status proposed # agent suggestions clawdo next # highest priority
# Review agent proposals clawdo confirm <id> # approve clawdo reject <id> # reject
# Work clawdo start <id> clawdo done <id> clawdo done abc,def,ghi # complete several ```
### 面向智能体
```bash # Check inbox (structured) clawdo inbox --format json
# Propose work clawdo propose "add input validation" --level auto --json
# Execute TASK=$(clawdo next --auto --json | jq -r '.task.id // empty') if [ -n "$TASK" ]; then clawdo start "$TASK" --json # ... do the work ... clawdo done "$TASK" --json fi ```
收件箱返回：`autoReady`、`autoNotifyReady`、`urgent`、`overdue`、`proposed`、`stale`、`blocked`。
## 内联语法
```bash clawdo add "fix auth bug +backend @code auto soon" ```
- `+word` → 项目 - `@word` → 上下文 - `auto` / `auto-notify` / `collab` → 自主级别 - `now` / `soon` / `whenever` / `someday` → 紧急程度 - `due:YYYY-MM-DD` → 截止日期
## 安全性
- **不可变自主权** — 智能体无法提升权限 - **提议限制** — 最多 5 个活跃提议，60 秒冷却时间 - **提示注入防御** — 输入清理，参数化 SQL - **审计追踪** — 每次状态变更的仅追加日志 - **安全 ID** — `crypto.randomInt()`，无取模偏差
## 资源
- **GitHub:** https://github.com/LePetitPince/clawdo - **npm:** https://www.npmjs.com/package/clawdo - **完整文档:** `clawdo --help`
## 许可证
MIT