init: Todo Monitor

2026-08-02 02:50:27 +08:00
parent 278a7e90b0
commit 81dd92cf22
43 changed files with 7483 additions and 0 deletions
@@ -0,0 +1,244 @@
+# 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` | 取消关闭 |
+| 双击便签 | 打开编辑面板 |
+| 双击分组标题栏 | 打开分组编辑面板 |