7.3 KiB
7.3 KiB
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 元数据块：
---
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
无需特殊语法，按约定书写即可自动识别。以下为完整示例：
# 登录模块开发
## 用户系统重构
**状态：** 进行中
**进度：** 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 } |
四、模式三：行内快捷字段
适合快速记录，在行内任意位置使用 @字段名(值) 语法：
# 登录模块开发
@状态(进行中) @进度(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 |
取消关闭 |
| 双击便签 | 打开编辑面板 |
| 双击分组标题栏 | 打开分组编辑面板 |