ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
76 lines
5.3 KiB
Markdown
76 lines
5.3 KiB
Markdown
# 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~~b~~c |
|
||
| `<` | 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` 参数中也必须使用转义形式才能正确匹配。
|
||
|
||
**导出 → 更新 工作流示例：**
|
||
|
||
1. `docs +fetch --api-version v2` 导出得到 `C:\\Users\\test\[1\]`
|
||
2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
|
||
3. `--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 下载：
|
||
```markdown
|
||
|
||
```
|
||
- `alt text` 为图片描述（可选，可留空）
|
||
- URL 支持 `http://` 和 `https://` 协议
|
||
- 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`
|
||
|
||
## Markdown 不支持的 Block 类型
|
||
|
||
非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。
|
||
> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。
|
||
|
||
## 参考
|
||
|
||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范 |