文本如何转换¶

Specivo 以 Markdown 存储工作项（Issue）的描述、评论和自定义字段中的文本，而 Jira 使用自己的格式，因此迁移工具会在导出过程中转换每一段文本。Jira Cloud 和 Jira Data Center 上的转换方式不同。

Jira Cloud：Atlassian Document Format¶

在 Jira Cloud 上，工具通过 REST API v3 读取工作项和评论，文本采用 Atlassian Document Format（ADF），即编辑器自身的 JSON 格式。工具自行把 ADF 逐节点转换为 Markdown，中途不经过 wiki 标记。（Cloud 旧版 v2 API 会在服务端做这一转换，并丢失智能链接、面板、任务、合并单元格等内容。）

生成的 Markdown 是针对 Specivo 的渲染能力编写的：

Jira 中	Specivo 中
标题、粗体、斜体、代码、链接、引用、分隔线	原样保留
删除线、下划线、下标、上标	`<del>`、`<u>`、`<sub>`、`<sup>`
文字颜色和背景色	丢弃颜色，保留文字
无序列表、有序列表和任务列表，可任意嵌套混用	Markdown 列表；任务写为 `- [ ]` 和 `- [x]`
决策	`- Decision: ...`
面板（信息、提示、警告等）和展开块	粗体标签（面板类型或展开块的标题）下方的块引用
代码块	带语言标识的围栏代码块（位于列表或引用内时为缩进代码块）
状态标签、日期	状态写为 `code`，日期写为 `2026-11-19`
表情	表情字符本身
表格	Markdown 表格。合并单元格拆开写，文字放在第一个单元格。单元格内的列表和代码折叠为一行。单元格内嵌的表格写在其所属表格之后。
智能链接（行内、块、嵌入）	指向本站工作项时写为工作项引用，否则写为链接
文本中显示的图片	`![name](attachment)`，指向该工作项的附件。宽度丢弃。
文本中显示的文件，以及非图片文件	`[name](attachment)`，即指向该文件的链接
附件不在导入包中的图片或文件	一条简短说明，写明名称，若已知原因也一并写出

工具不认识的元素类型会保留其文字，并按类型计入清单文件的 not_carried_over；合并单元格、单元格内的表格，以及附件不在导入包中的图片和文件也一并计入。原始 JSON 绝不会写入文本。

图片如何对应到附件¶

Jira 文本中的图片用媒体 ID（media id）标识文件，而不是用附件 ID。附件下载时的重定向中带有该附件的媒体 ID，工具对每个附件读取一次并保存在工作状态中，描述和评论中的图片正是据此找到对应附件的。

Jira 为图片保存的宽度会被丢弃：Specivo 只支持用 Markdown 图片语法指向附件，带宽度写出的图片将显示不出来。

Jira Data Center：wiki 标记¶

在 Data Center 上，工具通过 REST API v2 以 Jira wiki 标记的形式读取文本，并用开源库 jira2markdown 转为 Markdown，涵盖标题、列表、代码、表格、链接和文字效果。

按文件名写出的图片和文件链接（!screenshot.png!、!screenshot.png|thumbnail!、[^log.txt]，文件名可用任何文字）会对应到该工作项中同名的附件（有多个同名附件时取最新的）。尺寸选项丢弃；工作项中没有对应附件的名称则改写为一条说明。

Cloud 与 Data Center 通用¶

提及：对随迁用户的提及会变成占位符，Specivo 导入时将其转为 @login。对应用账户的提及则写为 @Display Name。
工作项编号：工作项编号（ACME-12）或指向本站 /browse/ACME-12 页面的链接会变成工作项引用，Specivo 会用该工作项的新编号写出。
导入包之外的工作项（属于其他项目，或超出 --limit 范围）的编号会在 Jira 中查询。若存在，Specivo 会在该工作项被导入时建立链接，无论是这次导入还是来自同一站点的后续导入包；否则按原文保留。
只是看起来像编号、而 Jira 并不认识的词（如 UTF-8）保持为文本。
代码、链接或 URL 中的内容一律不改。
--no-resolve-keys 跳过查询，此时只有导入包内工作项的编号会变成引用。
标记字符：纯文本中的标记字符会被转义，文本绝不会意外变成链接。
转换失败：无法转换的文本按原文保留，工具会打印失败文本的数量。

Specivo 工时记录中的评论是纯文本，因此 Cloud 上的工作日志评论会被压平：每段一行，提及写为 @Display Name，智能链接写为其地址。