Dendron 任务笔记（Task Notes）实战指南：从 frontmatter 字段到状态管理命令

知识管理知识库【免费下载链接】dendronThe personal knowledge management (PKM) tool that grows as you do!项目地址https://gitcode.com/gh_mirrors/de/dendron点击查看免费下载本文以 Dendron 测试工作区test-workspace/vault中的任务笔记为实例系统讲解 Dendron 任务笔记Task Notes的完整技术脉络笔记命名规范、frontmatter 字段语义、任务间 wiki 链接的组织方式以及插件侧任务状态管理命令的底层实现。读者将掌握如何创建、识别、追踪和完成一条 Dendron 任务笔记并理解status、due、priority、owner等字段如何驱动插件的行为。一、任务笔记是什么Dendron 将任务建模为一类特殊的层级化笔记称为 Task Note。它具备两个鲜明特征命名有规律默认任务层级以task为根dateFormat默认值为y.MM.dd例如本文实例 task.2021.10.26.020813.prepare-report 就是一个典型的任务笔记名前缀task.标识任务层级2021.10.26.020813为任务创建时间戳prepare-report为任务标题。frontmatter 有专属字段任务笔记通过status、due、priority、owner等字段携带任务元数据。以下为本文主实例笔记的完整内容task.2021.10.26.020813.prepare-report.md--- id: sEnzNEw04L4BZ2lN00zuI title: Prepare Report desc: updated: 1652737673279 created: 1635228506689 status: due: 2021.10.29 priority: H owner: kaan --- ## details Something about this task [[Get Documents Ready|task.2021.10.26.021747.get-documents-ready]] [[Task without Status|task.2021.10.26.031752.task-without-status]] [[Prepare Report|task.2021.10.26.020813.prepare-report]] [[mail report|task.2021.10.26.020813.prepare-report.mail-report]]可以看到这是一条准备报告Prepare Report任务截止日期为 2021.10.29高优先级负责人为 kaan并且通过四个 wiki 链接将相关任务串成一条工作流。二、任务笔记的 frontmatter 字段详解任务笔记的判定与字段处理逻辑位于 packages/common-all/src/types/configs/workspace/task.ts其中TaskNoteProps类型定义了核心字段export type TaskNoteProps { custom: { status?: string; due?: string; owner?: string; priority?: string; TODO?: string; DONE?: string; }; };各字段语义如下字段含义本实例取值status任务状态取值来自statusSymbols映射如wip、done、x等空字符串未开始due截止日期字符串形式2021.10.29priority优先级由prioritySymbols映射到可读文本H高优先级owner任务负责人kaanTODO/DONE启用todoIntegration后自动写入的 frontmatter 属性用于与 Todo Tree 等扩展互操作未启用值得注意due只是字符串Dendron 本身不做日历级别的到期提醒任务完成与否完全由status驱动。如何识别一条任务笔记TaskNoteUtils.isTaskNote()见 task.ts的判定逻辑是只要 frontmatter 中status、due、owner、priority任一字段存在该笔记即被视为任务笔记const TASK_NOTE_PROP_KEYS: string[] [status, due, owner, priority]; static isTaskNote(note: NotePropsMeta): note is NotePropsMeta TaskNoteProps { for (const prop of TASK_NOTE_PROP_KEYS) { if (note.custom ! undefined note.custom[prop] ! undefined) return true; } return false; }这解释了为何 task.2021.10.26.031752.task-without-status.md名为无状态任务仍被识别为任务笔记——它虽然没有status但带有priority: H与due字段。任务笔记的默认字段模板创建任务笔记时插件会按genDefaultTaskNoteProps见 task.ts生成默认 frontmatterconst props: TaskNoteProps { custom: { status: , due: , priority: , owner: }, }; if (config.todoIntegration) props.custom[TODO] note.title;三、任务层级命名与子任务组织Dendron 的层级Hierarchy是天然的任务组织方式。任务笔记的默认命名由task.name默认task与task.dateFormat默认y.MM.dd控制可通过 test-workspace/dendron.yml 中的task配置覆盖task: name: dateFormat: addBehavior: childOfCurrentaddBehavior: childOfCurrent表示新任务默认创建为当前笔记的子节点——这正是本实例命名结构的来源。用 wiki 链接串起任务流task.2021.10.26.020813.prepare-report 通过标准 wiki 链接组织相关任务[[Get Documents Ready|task.2021.10.26.021747.get-documents-ready]] [[Task without Status|task.2021.10.26.031752.task-without-status]] [[Prepare Report|task.2021.10.26.020813.prepare-report]] [[mail report|task.2021.10.26.020813.prepare-report.mail-report]][[目标标题|目标文件路径]]是第一代 wiki 链接语法|左侧为显示标题右侧为实际笔记路径。子任务 task.2021.10.26.020813.prepare-report.mail-report 在层级上属于准备报告的子节点用于拆分发邮件这一子步骤。子任务笔记同样具备任务 frontmatter本例中status: in-progress--- id: njcq8853ym5deoxwekdvzwx title: Mail Report desc: updated: 1652737697796 created: 1652737673213 status: in-progress due: priority: owner: ---四、status 与 priority 的状态符号映射任务笔记中的status与priority字段在界面上不会直接显示原始值而是通过statusSymbols/prioritySymbols映射为可读符号。默认映射定义于 packages/common-all/src/constants/configs/workspace.ts其配置条目说明如下statusSymbolsMaps symbols in the status frontmatter property to a symbol, word, or sentence——把status字段映射为界面符号。prioritySymbols同理映射priority字段。taskCompleteStatusIf the note state is set to any of these values, the note is considered to be done——命中这些状态即视为已完成。默认值由genDefaultTaskConfig()见 task.ts生成statusSymbols: { : , wip: w, done: x, assigned: a, moved: m, blocked: b, delegated: l, dropped: d, pending: y, }, taskCompleteStatus: [done, x], prioritySymbols: { H: high, M: medium, L: low },在 test-workspace/dendron.yml 中可以看到与之对齐的实际配置statusSymbols: : wip: w done: x assigned: a moved: m blocked: b delegated: l dropped: d pending: y prioritySymbols: H: high M: medium L: low taskCompleteStatus: - x - done因此实例笔记中priority: H在界面上显示为hightask.2021.10.26.021747.get-documents-ready.md 中的status: x显示为[x]完成符号。若某状态未在映射表中定义getStatusSymbolRaw见 task.ts会直接回退显示原始值。任务是否完成由isTaskCompletetask.ts判定只要status命中taskCompleteStatus列表中的任意值即视为完成。五、任务状态管理命令的底层实现插件侧的任务状态管理集中在 packages/plugin-core/src/commands 目录围绕两条命令展开。Task Status手动设置状态TaskStatusCommandpackages/plugin-core/src/commands/TaskStatus.ts用于为任务笔记设置status。其gatherInputs阶段处理两种使用场景光标位于任务笔记内直接取当前笔记作为操作对象光标选中了某个 wiki 链接通过engine.findNotes({ fname: selection.value, vault })解析链接指向的任务笔记若跨多个 vault 命中同名笔记则弹出 QuickPick 让用户选择目标笔记。若当前笔记不是任务笔记且未选中任何链接命令会给出警告Please open a task note, or select a link to a task note before using this command.。选定目标后命令从配置读取statusSymbols过滤掉当前状态后弹出 QuickPick 供选择const currentStatus selectedNote.custom?.status; const knownStatuses Object.entries( ConfigUtils.getTask(this._ext.getDWorkspace().config).statusSymbols ).filter(([key, value]) key ! currentStatus value ! currentStatus);最终execute阶段写入新状态并刷新编辑器装饰async execute(opts: CommandOpts) { opts.note.custom { ...opts.note.custom, status: opts.setStatus }; await this._ext.getEngine().writeNote(opts.note); delayedUpdateDecorations(); return {}; }Task Complete一键标记完成TaskCompleteCommandpackages/plugin-core/src/commands/TaskComplete.ts封装了完成这一高频操作它读取taskCompleteStatus配置的第一个值默认done作为完成状态然后复用TaskStatusCommand执行设置。若配置中未定义任何完成状态则提示用户补充taskCompleteStatus并引导打开配置文件const complete: string | undefined ConfigUtils.getTask( this._ext.getDWorkspace().config ).taskCompleteStatus[0]; if (complete undefined) { // 提示并引导打开配置 ... } const taskStatusCmd new TaskStatusCommand(this._ext); return taskStatusCmd.run({ setStatus: complete });集成测试 packages/plugin-core/src/test/suite-integ/TaskStatus.test.ts 通过多组用例验证了这两条命令的完整流程多 vault 同名笔记选择、状态更新落盘等可作为阅读与二次开发该功能的参考入口。六、任务相关配置项汇总任务相关的全部配置项均挂在dendron.yml的task节点下含义与默认值如下源码依据workspace.ts、task.ts配置项说明默认值task.name任务层级根节点名称tasktask.dateFormat任务笔记的日期格式y.MM.ddtask.addBehavior新任务创建时的层级行为asOwnDomain测试工作区使用childOfCurrenttask.statusSymbolsstatus字段到显示符号的映射→ 、wip→w、done→x、assigned→a、moved→m、blocked→b、delegated→l、dropped→d、pending→ytask.prioritySymbolspriority字段到显示文本的映射H→high、M→medium、L→lowtask.taskCompleteStatus命中即视为完成的状态集合[done, x]task.todoIntegration是否在 frontmatter 写入TODO属性以兼容 Todo Tree 等扩展falsetask.createTaskSelectionType创建任务笔记时的选区行为selection2link七、实战小结通过本文实例与源码对照可以总结出 Dendron 任务笔记的使用要点命名即组织task.时间戳.标题的层级命名天然支持子任务拆分如prepare-report.mail-reportaddBehavior决定新任务挂载位置字段即元数据status/due/priority/owner是任务笔记的四个核心判别字段任一存在即视为任务笔记符号即状态statusSymbols与prioritySymbols让原始值以更友好的符号展示taskCompleteStatus统一判定完成态命令即操作Task Status与Task Complete两条命令分别实现手动改状态与一键完成均以engine.writeNote落盘并刷新装饰链接即关系wiki 链接将准备报告 → 收集文档 → 发送邮件等步骤串成可回溯的任务流这是 Dendron 将笔记与任务管理统一在同一套 PKM 体系中的核心价值。如需进一步探索可继续阅读 task.ts 中的TaskNoteUtils完整实现、TaskStatus.ts 与 TaskComplete.ts 两条命令以及 TaskStatus.test.ts 集成测试。赞分享知识管理知识库【免费下载链接】dendronThe personal knowledge management (PKM) tool that grows as you do!项目地址https://gitcode.com/gh_mirrors/de/dendron点击查看免费下载相关推荐Dendron 根笔记 root.md 完全指南Vault 结构、Frontmatter 字段与发布落地页机制Dendron 根笔记 root.md 完全指南Vault 结构、Frontmatter 字段与发布落地页机制 每个 Dendron vault 的根目录下都知识管理知识库Taskbook 命令行任务管理完全指南boards、任务、笔记与归档恢复实战Taskbook 命令行任务管理完全指南boards、任务、笔记与归档恢复实战 Taskbook 是一款面向命令行的轻量级任务与笔记管理工具它用一套简洁、扁开发工具Taskbook 命令行任务管理实战指南跨看板组织任务、笔记与时间线Taskbook 命令行任务管理实战指南跨看板组织任务、笔记与时间线 Taskbook 是一款运行于终端command line环境的轻量级任务管理工具开发工具上一篇如何快速提取微信聊天记录打造个人AI助手的终极指南下一篇5分钟掌握思源宋体设计师的终极字体指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考