245 lines
7.3 KiB
Markdown
245 lines
7.3 KiB
Markdown
# 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` | 取消关闭 |
|
||
| 双击便签 | 打开编辑面板 |
|
||
| 双击分组标题栏 | 打开分组编辑面板 |
|