---
name: obsidian-tasks
description: 管理 Obsidian vault 中基于 Markdown 复选框（`- [ ]`/`- [x]`）的任务清单与 GTD 工作流：跨文件列出/筛选任务、切换单条任务状态、项目进度统计、收集-处理-执行流程。触发词：todo、待办、任务清单、完成任务、GTD、任务状态。不用于 Linear/飞书任务（linear/lark-task），不用于 frontmatter status 字段（obsidian-meta）。
---

# Obsidian Tasks · 任务清单管理

> 基于 Markdown 复选框语法 `- [ ]` / `- [x]` 的任务管理子集。每个任务 = 笔记某一行。适合 GTD（Getting Things Done）与 Zettelkasten 流程化任务。

---

## 何时使用

- 列出 vault 中**所有任务**（跨文件）
- 筛选**未完成**（todo）或**已完成**（done）的任务
- 按**状态字符**筛选（`- [ ]` 待办、`- [x]` 完成、`- [/]` 进行中、`- [?]` 存疑等）
- **切换单个任务**状态（ref = `path:line`）
- 配合每日笔记做 GTD 收集/回顾流程

## 不用于

- Linear issue → **linear** 技能
- 飞书任务 → **lark-task** 技能
- Frontmatter 级别的 `status: done` → **obsidian-meta**（那是笔记级状态，不是任务级）
- 任务的视觉化看板 → **obsidian-bases** + obsidian-tasks

---

## 命令速查

### 列出任务

```bash
obsidian tasks                          # vault 所有任务（text 默认）
obsidian tasks todo                     # 只列未完成
obsidian tasks done                     # 只列已完成
obsidian tasks verbose                  # 按文件分组，含行号
obsidian tasks format=json              # JSON 输出（agent 友好）
obsidian tasks total                    # 仅返回任务总数

obsidian tasks file="项目Alpha"         # 某文件的任务
obsidian tasks path="10-Projects/alpha/README.md"
obsidian tasks active                   # 当前激活文件的任务
obsidian tasks daily                    # 今天每日笔记的任务

obsidian tasks status="/"               # 按自定义状态字符筛选（进行中）
obsidian tasks status="?"               # 存疑
obsidian tasks status="!"               # 重要
obsidian tasks status="-"               # 取消
```

### 操作单个任务

```bash
# 方式 1：用 ref（path:line）
obsidian task ref="10-Projects/alpha/README.md:42" toggle
obsidian task ref="10-Projects/alpha/README.md:42" done
obsidian task ref="10-Projects/alpha/README.md:42" todo
obsidian task ref="10-Projects/alpha/README.md:42" status="/"

# 方式 2：用 file + line
obsidian task file="项目Alpha" line=42 done

# 方式 3：操作每日笔记
obsidian task daily line=7 toggle
```

---

## Task Emoji Shorthand 约定（社区标准）

Obsidian Tasks 插件广泛使用的状态字符：

| 字符 | 含义 | 渲染 |
|-----|------|------|
| ` ` | 待办 | `- [ ]` |
| `x` | 已完成 | `- [x]` |
| `/` | 进行中 | `- [/]` |
| `?` | 存疑/需澄清 | `- [?]` |
| `!` | 重要/关键 | `- [!]` |
| `-` | 已取消 | `- [-]` |
| `>` | 已转发/委派 | `- [>]` |
| `<` | 已调度（计划中） | `- [<]` |

CLI 的 `status="<char>"` 参数支持这些自定义字符。

---

## AI Agent 最佳实践

### 场景 1 · 每日任务收集（GTD 收集阶段）

每天早晨，扫描所有来源把任务汇总到当天每日笔记：

```bash
# 1. 收集昨天未完成的任务
obsidian tasks todo format=json > /tmp/open-tasks.json

# 2. 提取 vault 中所有 "TODO:" "FIXME:" "XXX:" 标记（这些不是正式 task）
obsidian search query="TODO:" limit=50 format=json
obsidian search query="FIXME:" limit=50 format=json

# 3. 由 agent 分类后，写入今天的每日笔记（见 obsidian-daily 技能）
obsidian daily:append content="\n## 今日任务\n- [ ] 处理 TODO: ...\n- [ ] 继续昨日未完成: ..."
```

### 场景 2 · 周回顾（Weekly Review）

GTD 的核心仪式，每周一次：

```bash
# 1. 本周已完成（展示成就）
obsidian tasks done verbose format=json > /tmp/done-this-week.json

# 2. 未完成且超期 7+ 天的任务（僵尸任务，需要决策）
obsidian tasks todo verbose format=json > /tmp/stale-tasks.json

# 3. 由 agent 生成周报
obsidian create path="99-Log/weekly-$(date +%Y-W%V).md" content="# 周回顾\n..."
```

### 场景 3 · 项目进度检查

```bash
# 某项目的完成度
obsidian tasks path="10-Projects/alpha/README.md" total          # 总数
obsidian tasks path="10-Projects/alpha/README.md" done total     # 已完成数

# 计算百分比后写回 frontmatter（配合 obsidian-meta）
# progress = done / total * 100
obsidian property:set name=progress value=65 type=number file="项目Alpha"
```

### 场景 4 · AI 生成任务的注入规范

当 AI agent 为用户拆解任务时，输出格式应遵循：

```markdown
## AI 拆解任务 · 2026-04-09

来源：用户需求"重构认证模块"
拆解方式：按 PR 颗粒度，每个任务 < 2h

- [ ] 📖 阅读现有认证中间件代码
- [ ] 🧪 补充现有逻辑的单元测试（无则写）
- [ ] ✂️ 抽取 Token 验证为独立函数
- [/] 🔧 引入 JWT 库替换自研实现
- [ ] 📝 更新 API 文档
- [ ] ✅ 回归测试
```

**约定**：
- Emoji 前缀标注任务类型（📖 阅读 / 🧪 测试 / ✂️ 重构 / 🔧 开发 / 📝 文档 / ✅ 验证）
- 带 `/`（进行中）的任务至多 1 个（WIP 限制）
- 每个任务自描述，不依赖上下文才能理解

### 场景 5 · 跨笔记任务聚合视图

```bash
# 把所有 `50-Zettel/` 下的待办聚合到一个 MOC 笔记
obsidian tasks path="50-Zettel" todo verbose format=json > /tmp/zettel-tasks.json

# 写入 MOC
obsidian create path="60-MOC/open-research-questions.md" content="# 待解决的研究问题\n..."
```

---

## Bash 脚本范式：完整的 Daily Standup

```bash
#!/bin/bash
# 每日站会助手：生成今日状态

TODAY=$(date +%Y-%m-%d)
YESTERDAY=$(date -d "yesterday" +%Y-%m-%d 2>/dev/null || date -v -1d +%Y-%m-%d)

echo "# Daily Standup · ${TODAY}"
echo ""
echo "## ✅ 昨日完成"
obsidian tasks done verbose format=json | \
  jq -r '.[] | select(.completed >= "'${YESTERDAY}'") | "- \(.text) [\(.file):\(.line)]"'

echo ""
echo "## 🔄 今日计划"
obsidian tasks todo verbose format=json | \
  jq -r '.[] | "- [ ] \(.text) [\(.file):\(.line)]"' | head -10

echo ""
echo "## 🚧 进行中"
obsidian tasks status="/" verbose format=json | \
  jq -r '.[] | "- [/] \(.text) [\(.file):\(.line)]"'
```

---

## 与其他技能的协作

| 场景 | 链路 |
|-----|------|
| 每日任务注入 | obsidian-tasks → **obsidian-daily**（`daily:append`） |
| 项目进度同步 | obsidian-tasks（统计）→ **obsidian-meta**（`property:set progress`） |
| 任务可视化 | obsidian-tasks（写入）→ **obsidian-bases**（视图展示） |
| GTD 周回顾工作流 | **obsidian-workflow-pkm**（编排） |
| Linear 双向同步 | obsidian-tasks + **linear** |

---

## 常见陷阱

| 现象 | 原因 | 对策 |
|------|------|------|
| `task toggle` 不生效 | line 数字错了 | `tasks verbose` 先确认行号 |
| 缩进子任务被识别为独立任务 | Markdown 语法正常 | 接受：Obsidian 视子任务为独立 |
| 自定义 status 字符不显示 | 主题不支持 | 切换支持 Tasks Emoji 的主题 |
| tasks 命令返回空 | 路径/文件名错 | 用 `obsidian files` 先确认 |
| 每日任务重复出现 | 没有迁移机制 | 在每日模板里写"迁移昨日未完成"逻辑 |
| AI 滥加任务导致 WIP 爆炸 | 没设置上限 | 约定：进行中（`/`）至多 1~3 个 |