Knowledge Work Plugins：让工作助手使用共享任务文件
阅读 productivity 的 Markdown 解析器：保存前先理解损失
分析 dashboard.html 的分组标识、复选框解析和保存条件，识别中文标题、重名分组与往返写入的限制。
你将学会
- 分组名称如何变成标识
- 序列化只保留特定结构
- 保存与监听各有条件
开始前需要
- 基本命令行与配置阅读能力
- 能够在独立且获准的环境中试验
设计独立的只读解析预览，在保存前展示不支持的 Markdown、分组冲突和往返序列化差异。
先看结论
- 标题规范化可能合并或遗漏分组。
- 任意 Markdown 不在任务结构保证内。
- 自动保存条件不等于无冲突编辑。
分组名称如何变成标识
taskSectionId 将标题转为小写，并把 ASCII 字母和数字以外的连续字符替换成连字符。parseTaskMarkdown 只有在分组标识有效时收集任务，因此纯中文标题可能得到空标识，下面的任务也无法被收集。
不同标题还可能规范化为同一标识，解析器此时复用已有任务数组。首次试验保留模板中的英文分组名称；本地化或定制标题应先在副本中测试，而不是直接修改正式清单。
序列化只保留特定结构
解析器识别二级标题、任务复选框、加粗标题、备注和带复选框的子任务。toMarkdown 根据这些字段重建文档，结构之外的普通段落或其他 Markdown 内容不保证在看板保存后保留。
解析出的任务标识使用时间和随机值，不应被当成稳定的跨设备身份。如果某个集成需要持久标识，应设计并测试自己的格式，而不是从临时卡片状态推断保证。
保存与监听各有条件
markChanged 在 500 毫秒后安排 autoSave，后者检查文件句柄、待保存修改及保存中标记。checkForExternalChanges 比较修改时间，但存在本地修改或保存过程时会提前返回。
这些分支解释了看板为何不会随意打断正在进行的编辑，也说明并发写入仍需要冲突处理。本次只做源码检查，没有执行浏览器竞争测试；下面的案例是验收计划，不是已通过的测试结果。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
连同调用关系阅读三个解析和序列化函数。
- 2
测试英文、纯中文和规范化冲突标题。
- 3
逐行比较原文件与重新序列化的结果。
可复制示例
{
"proposedCases": [
"Active",
"待办",
"A B / A-B",
"free paragraph before task"
],
"assertions": [
"section identity",
"task retention",
"round-trip diff"
],
"browserRaceTested": false
}常见问题
可以把所有分组标题换成中文吗？
应先测试，审阅的标识函数只保留 ASCII 字母和数字。
保存成功代表原文每行都保留吗？
不代表，序列化器重建的是受支持的任务结构。