# Todo Monitor 语法说明

便签内容的 Markdown 文本支持三种解析模式，优先级从高到低为：

> YAML Front Matter > 约定式 Markdown > 行内快捷字段

同一字段若同时在多种模式中存在，高优先级覆盖低优先级。

---

## 一、支持的字段总览

| 字段 | 说明 | 类型 | 可选值 |
|------|------|------|--------|
| `title` | 卡片标题 | 字符串 | — |
| `subtitle` | 副标题 | 字符串 | — |
| `status` | 状态 | 枚举 | `待办` `进行中` `已完成` `阻塞` `延期` |
| `progress` | 进度百分比 | 数字 0-100 | — |
| `priority` | 优先级 | 枚举 | `紧急` `高` `中` `低` |
| `deadline` | 截止日期 | 日期字符串 | 如 `2026-08-15` |
| `startDate` | 开始日期 | 日期字符串 | 如 `2026-08-01` |
| `owner` | 负责人 | 字符串 | 如 `张三` |
| `tags` | 标签 | 字符串数组 | 如 `前端, 核心模块` |
| `type` | 卡片类型 | 枚举 | `task` `milestone` `metric` `countdown` `project` |
| `metric` | 指标数值 | 数字 | — |
| `target` | 目标值 | 数字 | — |
| `link` | 关联链接 | URL 字符串 | — |

---

## 二、模式一：YAML Front Matter（推荐）

在便签顶部用 `---` 包裹 YAML 元数据块：

````markdown
---
title: 登录模块开发
subtitle: 用户系统重构
status: 进行中
priority: 高
progress: 65
deadline: 2026-08-15
startDate: 2026-08-01
owner: 张三
tags: [前端, 核心模块]
type: task
metric: 1500
target: 3000
link: https://example.com
---

## 项目说明

这里是便签正文，支持 Markdown。
- [ ] 接口对接
- [x] 页面布局
- [ ] 单元测试
````

**规则：**
- `---` 必须独占一行，且位于便签最开头
- YAML 块内可以使用任意子集
- YAML 解析失败时自动回退到模式二/三

---

## 三、模式二：约定式 Markdown

无需特殊语法，按约定书写即可自动识别。以下为完整示例：

````markdown
# 登录模块开发

## 用户系统重构

**状态：** 进行中
**进度：** 65%
**优先级：** 高
**截止：** 2026-08-15
**开始：** 2026-08-01
**负责人：** 张三
**标签：** 前端, 核心模块
**类型：** task
**指标：** 1500
**目标：** 3000
**链接：** https://example.com

正文描述区域，所有未被识别的行均归为描述。
支持多段文本。

- [ ] 接口对接
- [x] 页面布局
- [ ] 单元测试
````

### 关键词表（近义词兼容）

系统使用**包含匹配**识别字段，只要关键词出现在 `**key**` 中即可识别，无需精确一致：

| 匹配关键词 | 对应字段 | 示例写法 |
|------------|----------|----------|
| `标题` / `title` | title | （仅限 `# ` 开头） |
| `状态` / `status` | status | `**状态：** 进行中` |
| `进度` / `progress` | progress 或 metric | 见下方说明 |
| `优先` | priority | `**优先级：** 高` `**优先：** 紧急` |
| `截止` / `deadline` / `到期` | deadline | `**截止日期：** 2026-08-15` `**截止时间：**` |
| `开始` / `start` | startDate | `**开始日期：** 2026-08-01` `**开始时间：**` |
| `负责` / `owner` / `执行` | owner | `**负责人：** 张三` `**执行人：**` |
| `标签` / `tags` | tags | `**标签：** 前端, 核心` |
| `类型` / `type` | type | `**类型：** milestone` |
| `指标` / `metric` / `进度` / `输出` | metric | `**指标值：** 1500` `**输出：**` |
| `目标` / `target` | target | `**目标值：** 3000` |
| `链接` / `link` / `url` | link | `**链接：** https://...` |

> **`进度` 字段智能识别**：若 value 含 `%` 符号（如 `65%`）→ 解析为 progress 百分比；若为纯数字（如 `1500`）→ 解析为 metric 指标值。

**兼容性：**
- 冒号支持中文 `：` 和英文 `:`，也支持冒号位于 `**` 内侧（如 `**负责人：** 张三`）
- 标签分隔符支持 逗号/顿号/空格：`前端, 核心模块` `前端、核心模块` `#前端 #核心`

### 子任务

| Markdown 写法 | 含义 |
|---------------|------|
| `- [ ] 未完成任务` | subTask `{ done: false }` |
| `- [x] 已完成任务` | subTask `{ done: true }` |

---

## 四、模式三：行内快捷字段

适合快速记录，在行内任意位置使用 `@字段名(值)` 语法：

````markdown
# 登录模块开发

@状态(进行中) @进度(65%) @优先级(高)
@截止(2026-08-15) @负责人(张三)

这里写描述文字 #前端 #核心模块

- [ ] 接口对接
- [x] 页面布局
````

**可用的行内语法：**

| 写法 | 说明 |
|------|------|
| `@状态(进行中)` | 设置 status |
| `@进度(65%)` | 设置 progress（需带 `%`） |
| `@进度(1500)` | 设置 metric（不带 `%`） |
| `@指标(1500)` | 设置 metric（同上） |
| `@目标(3000)` | 设置 target |
| `@优先级(高)` | 设置 priority |
| `@截止(2026-08-15)` | 设置 deadline |
| `@开始(2026-08-01)` | 设置 startDate |
| `@负责人(张三)` | 设置 owner |
| `@类型(milestone)` | 设置 type |
| `#标签名` | 自动提取到 tags 数组 |

---

## 五、智能推断规则

部分字段可以不写，系统自动推断：

### 进度自动计算
存在子任务但未写 progress → 自动按 **已完成数 / 总数** 计算进度百分比。

### 状态自动推断

若有子任务的显式进度（或通过子任务推算），系统优先用进度反推状态。除非用户显式写了 `**状态：**xxx`（或 YAML 中的 status），否则按以下规则：

| 条件 | 推断结果 |
|------|----------|
| 内容含 `阻塞` / `blocked` / `卡壳` | `阻塞` |
| 截止日期已过 且 progress < 100 | `延期` |
| progress >= 100 | `已完成` |
| progress > 0 | `进行中` |
| 其他 | `待办` |

> **注意**：`阻塞` 和 `延期` 优先级最高，即使 progress 为其他值也会覆盖。

### 卡片类型推断

| 条件 | 类型 |
|------|------|
| 有 metric 或 target 字段 | `metric` |
| 子任务 ≥ 3 个 | `project` |
| 有 deadline 且距离 ≤ 60 天 | `milestone` |
| 其他 | `task` |

---

## 六、颜色映射

### 状态
| 状态 | 颜色 |
|------|------|
| 待办 | 灰色 `#64748b` |
| 进行中 | 蓝色 `#38bdf8` |
| 已完成 | 绿色 `#22c55e` |
| 阻塞 | 橙色 `#f59e0b` |
| 延期 | 红色 `#ef4444` |

### 进度条
| 进度值 | 颜色 |
|--------|------|
| 0% | 灰色 `#64748b` |
| 1% ~ 99% | 蓝色 `#38bdf8` |
| 100% | 绿色 `#22c55e` |
| 阻塞 / 延期（覆盖上述） | 红色 `#ef4444` |

### 优先级
| 优先级 | 颜色 | 视觉特征 |
|--------|------|----------|
| 紧急 | 红色 `#ef4444` | 字号加大 + 呼吸闪烁动画 |
| 高 | 橙色 `#f97316` | `!` 前缀 |
| 中 | 蓝色 `#38bdf8` | `·` 前缀 |
| 低 | 灰色 `#64748b` | 无前缀 |

---

## 七、卡片类型说明

| 类型 | 触发字段 | 展示方式 |
|------|----------|----------|
| `task` | 默认 | 标题 + 状态徽章 + 优先级徽章 + 负责人 + 进度条 + 子任务列表 + 描述 + 标签 |
| `milestone` | deadline 字段 | 倒计时圆环 + 截止日期 + 标题 |
| `metric` | metric + target 字段 | 大号数值 + 达成率 + 标题 |
| `countdown` | 仅 deadline，无子任务 | 全屏倒计时数字 |
| `project` | 子任务 ≥ 3 个 | 整体进度 + 子任务汇总 |

---

## 八、编辑器快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+S` | 保存并关闭 |
| `Esc` | 取消关闭 |
| 双击便签 | 打开编辑面板 |
| 双击分组标题栏 | 打开分组编辑面板 |