ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
5.3 KiB
Markdown 格式参考
docs +fetch --api-version v2 / docs +create --api-version v2 / docs +update --api-version v2 使用 --doc-format markdown 时适用。
转义规则
⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时，需用
\前缀转义。转义分为无条件转义（行内任意位置生效）和位置敏感转义（仅特定位置才需要）两类。
无条件转义（行内生效，任何位置都要转义）
| 符号 | Markdown 语法用途 | 转义写法 | 示例 |
|---|---|---|---|
\ |
转义符本身 | \\ |
C:\\Users → C:\Users |
` |
行内代码 | \` |
用 \` 包裹 |
* |
斜体 / 加粗 | \* |
3 \* 5 = 15 → 3 * 5 = 15 |
_ |
斜体 / 加粗 | \_ |
foo\_bar\_baz → foo_bar_baz |
[ ] |
链接文本 | \[ \] |
\[非链接\] |
$ |
数学公式定界 | \$ |
价格 \$100 |
~ |
删除线（GFM ~~text~~） |
\~ |
a\~\~b\~\~c → a |
< |
XML 标签起始（<b>、<img> 等会被当作标签解析并生效） |
\< |
字面量 <b> 须写为 \<b>；a < b 建议写为 a \< b |
位置敏感转义（仅在特定位置才需要转义）
| 符号 | Markdown 语法用途 | 转义条件 | 示例 |
|---|---|---|---|
# |
标题 | 仅行首（去除前导空白后） | 行首 \# 这不是标题；行内 A # B 无需转义 |
+ |
无序列表 | 仅行首（去除前导空白后） | 行首 \+ item；行内 1 + 2 无需转义 |
- |
无序列表 / 分隔线 | 仅行首（去除前导空白后） | 行首 \- item；行内 A - B 无需转义 |
> |
引用块 | 仅行首（去除前导空白后） | 行首 \> 不是引用；行内 a > b 无需转义 |
| |
表格 cell 分隔 | 仅在 GFM 表格 cell 内 | cell 内 A | B；行内普通文本 a | b 无需转义 |
不需要转义的场景：
- 在
`行内代码或```代码块内，所有符号均为字面量，无需转义 $...$数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响
导出已转义，不要反转义：
docs +fetch --api-version v2 --doc-format markdown 导出的内容中，特殊字符已经被转义过了（例如 \[、\|、\\ 等）。这些 \ 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。不要反转义或去掉 \。
写入时必须转义：
使用 docs +create 或 docs +update 的 --doc-format markdown 写入内容时，字面文本中的特殊字符同样必须转义。--pattern 参数中也必须使用转义形式才能正确匹配。
导出 → 更新 工作流示例：
docs +fetch --api-version v2导出得到C:\\Users\\test\[1\]- 用
str_replace --pattern 'C:\\Users\\test\[1\]'匹配（直接使用导出的转义形式） --content中的替换内容也要保持转义：C:\\Users\\prod\[2\]
自行构造 Markdown 内容写入时同理：如字面文本 a]b 应写为 a\]b，C:\Users 应写为 C:\\Users。
Shell 传参
- 首选文件传参：
--content支持@path/to/file.md（读文件）和-（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以@开头时用@@转义（--pattern不支持@file） - ⚠️
@file路径限制：@file只接受当前工作目录下的相对路径，传绝对路径（如@/tmp/xxx.md）会报unsafe file path。需要落盘时，将文件写在 cwd 下（如./_content.md），用完自行清理。 - 默认用单引号
'...'：完全字面量，$、`、\、>、\<b>等全部原样保留 - 双引号
"..."：会展开$变量、反引号和$(...)命令替换，\仍参与转义，易踩坑 $'...'ANSI-C 引号：按 C 转义解析，\n=换行、\\=单个\；zsh 下未知转义（如\<）的\会被吞，要保留字面\必须写\\。只在确实需要\n/\t时用- 多行内容：用
<<'EOF'heredoc，EOF 必须带引号，否则仍展开$ \n在'...'和"..."里都是字面量，不是换行；要真换行用$'...\n...'或 heredoc
图片语法
Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
alt text为图片描述（可选，可留空）- URL 支持
http://和https://协议 - 对应的 XML 格式为：
<img href="https://example.com/photo.png"/>
Markdown 不支持的 Block 类型
非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 lark-doc-xml.md。
⚠️ XML 标签会被解析并生效：即使在
--doc-format markdown下，<b>、<u>、<img>等 XML 标签也会被识别为对应的富文本节点，不会按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的<tag>），必须转义左尖括号：\<b>、\<img>。
参考
lark-doc-xml.md— XML 语法规范