你不必离开 Confluence。把描述架构的那些页面搬走，其余的留在原地——而搬迁本身，只需把 Atlassian 的 MCP 服务器和 Archyl 的 MCP 服务器接到同一个 AI 代理上。

如何用 MCP 把 Confluence 架构文档迁移到 Archyl

有一种场景我每周都会听到。一个团队用上了 Archyl，用 C4 把系统建好了模型，挂上了 ADR 和 API 契约——然后有人问出那个必然的问题："我们在 Confluence 里的那 200 页文档怎么办？"

第一句该说的话，恰恰是没人指望从厂商嘴里听到的：这些页面里的大多数，就该留在 Confluence。 会议纪要、入职清单、值班 runbook、上个季度的规划文档。这些正是 Confluence 擅长的，Archyl 也没打算来抢。真正该搬的，是其中描述架构的那一部分——而弄清楚哪些页面属于这一部分，才是这件事的大头。

过去难的其实是"搬"这个动作本身。以前，这个问题的答案要么是"等导入器"，要么是"复制粘贴一下午"。两个都不怎么样。但过去一年里有件事变了：这场迁移的两端，现在都会说 MCP 了。

Atlassian 官方提供了一个远程 MCP 服务器，把 Confluence 和 Jira 开放给任何 AI 代理，带 OAuth，沿用你现有的权限。而 Archyl 通过自己的 MCP 服务器开放了整个平台——文档、文件夹、ADR、完整的 C4 模型——足足 181 个工具。

在中间放一个代理，你一直在等的那个导入器，就变成了一段提示词。

哪些页面该搬，哪些该留

这一步要在连接任何东西之前做完。我用的判断标准是：一个新来的工程师需要这一页，是为了搞懂系统怎么运转，还是为了熬过第一周？ 前者该待在模型旁边，后者该待在 wiki 里。

按这个标准，一个空间会分成四堆。

作为文档搬走。 描述系统的页面：支付服务是怎么搭起来的、它和谁通信、为什么前面挂了一个队列、重试策略是什么。在 Archyl 里，你把这些挂到它们所描述的 container 或系统上，于是它们会和元素一起出现，而不是躲在页面树里三次点击之外。
作为 ADR 搬走。 "为什么我们选了 X"、RFC、权衡分析、那篇以一个决定收尾的复盘页面。这些是决策，不是文档，Archyl 把它们当成另一类对象来处理——带状态，并且链接到它们影响的那个元素。
留在 Confluence。 会议纪要、迭代规划、团队手册，以及任何围绕 Jira 宏搭起来、本质上是一份实时报表的页面。搬它们什么也换不到，反而把宏搞丢了。
删掉。 每个空间里都有描述着两年前就下线的系统的页面。一次迁移，是往后唯一还会有人再读它们的场合，所以也是你唯一一次能名正言顺删掉它们的机会。

先分类，这才是让整件事不至于变成一次全有或全无的迁移的关键。你不是在清空 Confluence，你是在从里面抽出一层。

你需要什么

一个 MCP 客户端。 这里我用 Claude Code，但 Cursor 或任何兼容 MCP 的代理用法完全相同。
一个 Confluence 账号，对你要迁移的空间有读取权限。
一个 Archyl API 密钥——在_个人资料 → API Keys_ 里创建一个，勾选写入权限。

连接两个服务器

两条命令。先加 Atlassian 的托管服务器（第一次使用时会打开浏览器完成 OAuth）：

claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp/authv2

然后是 Archyl：

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

配置到此为止。代理现在既能_读_你的 wiki，也能_写_你的架构工作区。

描述这次迁移，而不是开发它

下面是一段真实的提示词，和我在我们自己的空间上用的差不多：

把 "Platform Engineering" 这个 Confluence 空间迁移到我的
Archyl 项目 "Aurora Commerce" 里。

1. 先列出该空间的页面树，把层级结构展示给我看——
   暂时什么都不要导入。
2. 用文档文件夹复刻这个层级结构，然后把每个页面以
   markdown 形式导入。保留标题，清理格式，并把导入
   页面之间的相互链接改写为指向 Archyl 里的版本。
3. 任何记录决策的页面——"为什么我们选了 X"、RFC、
   权衡分析——都应该变成一条 ADR 而不是普通文档，
   状态设为 accepted。原始日期写进上下文的第一行：
   "2024-03-11 决定，自 Confluence 迁入。"
4. 最后给我一张汇总表，列出你创建的所有内容。

接下来看好了。代理会调用 getConfluenceSpaces 和 getPagesInConfluenceSpace 摸清空间结构，用 getConfluencePageDescendants 遍历页面树，再用 getConfluencePage 逐页拉取内容。在 Archyl 这一侧，它用 create_documentation_folder 镜像出同样的结构，把每个页面转成 markdown 后用 create_documentation 落地，再调用 move_documentation 把它归到正确的文件夹里（创建一篇文档和放置它是两个不同的工具）。然后——这是我最喜欢的部分——把那些"长得像决策"的页面改道送进 create_adr。

最后这一步比看起来重要得多。每个团队的 wiki 里都埋着一层被"文档"掩盖的决策化石。导入器会原样照搬。而代理会_读_它们，认出"为什么我们弃用了 RabbitMQ"是一条架构决策，把它归档到决策该在的地方——链接到它影响的那个元素上，就挨着你的 C4 模型，随时可查。

第零步法则：先审阅，再批量

注意提示词里那句"先把层级结构展示给我看——暂时什么都不要导入"。照做。每个 wiki 里都有归档区、会议纪要坟场，还有一个 2019 年留下来的叫"TEST 勿删"的页面。让代理先给出页面树，你用一句回复修剪一下（"跳过 Archive 和 Meeting Notes"），再放它跑。

200 页实际跑起来是什么样

这不是一段提示词加一个下午的事。有四件事决定了实际跑起来的样子，事先知道它们，就是干净收尾和半途而废之间的区别。

按板块推进，而不是按空间推进。 代理会在批次之间保持上下文，而一个你读得完摘要的批次，才是一个你改得动的批次。十页，检查，再十页。

Atlassian 的服务器会限流，而且不是在你以为的那个量级上。 官方 MCP 服务器上有一个尚未关闭的 issue，提交于 2026 年 5 月 29 日，Atlassian 至今没有回应：报告者称在几个小时里总共只发了 200 到 300 次调用，但只要并行调用超过大约 20 个就会收到 429。他的判断是，错误跟并发峰值相关，而不是跟持续负载相关。不管真实上限到底是多少，给出的指令都一样：告诉代理一页一页地处理，别一次铺开。

重跑失败的批次会产生重复。 Archyl 并不强制文档 slug 唯一，所以如果一个批次在第七页（共十页）挂掉，你说一句"再来一次"，前六页就会各有两份。让代理在重试前先调用 list_documentation，跳过已经存在的内容。

过深的树会被压平。 Archyl 的文档文件夹最多三层。嵌套更深的 Confluence 页面树会返回 Maximum folder nesting depth (3 levels) reached，所以要在开始之前就决定哪几层合并，而不是跑到第 40 页才发现。

坦白讲：几点局限

附件仍然不会自己搬家，只不过原因换了一边。 这篇文章第一次发出来的时候，Archyl 根本没地方放附件。现在有了：文档附件已经上线，底层是 S3 兼容的对象存储，而一个拿着你 API 密钥的代理可以把文件直接发到某篇文档上。缺口在 Confluence 那一侧。Atlassian 的远程 MCP 服务器压根没有附件相关的工具——截至 2026 年 8 月，支持的工具列出了十二项 Confluence 操作，没有一项碰得到文件，而那条功能请求从 2026 年 3 月起就一直开着。所以代理没法通过 MCP 把字节取回来。它可以走 Confluence 的 REST API 取（GET /wiki/api/v2/pages/{id}/attachments 会为每个文件返回一个 downloadLink），然后一个个推过去：
```
curl -X POST https://api.archyl.com/api/v1/docs/$DOC_ID/attachments \
  -H "X-API-Key: $ARCHYL_API_KEY" \
  -F "file=@architecture-overview.png"
```
响应里会直接带上一段现成的 markdown 片段，粘进页面即可。任何文件类型，默认每个 10 MB。但要看清楚这是什么：这是一个脚本，还需要第二份凭证（一个 Atlassian API token，因为 MCP 服务器手里那个 OAuth 会话不是你能借来用的）。对多数空间来说，把真正重要的那几张图通过 Archyl 的编辑器重新上传，依然是更快的答案。
ADR 的日期是你创建它的那天。 无论 MCP 还是 REST，都没有哪个 API 接受决策日期，所以一条 2023 年做出的决策，落地时盖的是今天的戳。上面那段提示词把原始日期写进上下文，正是因为这个。在你打算一口气迁移十年的决策之前，值得先知道这一点。
文档不会自己链接到你的模型上。 代理可以用一次调用把 ADR 挂到某个系统或 container 上（link_adr_to_element）。文档目前还没有对应的 MCP 工具，所以导入的文档到达时是没有链接的。要么在界面里手动关联，要么让代理用同一个 API 密钥 POST 到 /api/v1/docs/{id}/links。别跳过这一步：一篇文档就该待在它所描述的 container 旁边——这正是它离开 wiki 的全部理由。
复杂宏会降级。 Confluence 那些花哨的宏——Jira 工单表格、动态报表——会变成纯文本或链接。代码块、表格、信息面板都能干净地转换。
权限就是你的权限。 Atlassian MCP 服务器只暴露你的 OAuth 用户能读到的内容。这是特性。

为什么这比传统导入器强

一次性的导入器搬运的是字节。代理搬运的是_含义_：它一边迁移一边重组结构，把决策变成 ADR，修掉失效的格式，结束后还能回答"你跳过了什么、为什么跳过"。

它还让"分类"这件事成为可能。没有哪个导入器会去看一眼某个页面，然后判断它属于你要留下的那一堆。代理会——只要你把规则告诉它。

两边同时跑起来是什么样子

最终状态不是"只剩一个工具"，而是一条守得住的边界：

Confluence 继续干 wiki 的活。 笔记、计划、手册，一切跟 Jira 绑在一起的东西。没人需要被通知"别再用它了"——正因如此，这条边界经得起团队的实际使用。
Archyl 承载架构那一层。 C4 模型，加上描述它的文档、ADR 和 API 契约，各自挂在所属的元素上。当有人打开支付那个 container，解释它的文档和背后那条 ADR 就在眼前。
两边都仍然对你的代理开放。 你的 MCP 客户端同时连着两个服务器。它可以在同一段对话里，既向 Archyl 查询架构，又去 wiki 里搜那份规划页面。

有一条规则能防止这一切重新滑回原样，值得大声说一次：当一个页面在描述系统时，它就该放进 Archyl。 哪一天有人在 Confluence 里写下一篇新的架构页面，那 200 页的问题就又从头开始了。

配好密钥，把你的代理指向两个服务器，先扔给它一个板块慢慢消化。完整的工具清单见 MCP 服务器文档。

等文档都搬过去之后，同样的招式对架构本身也管用：把 Structurizr 文件、Terraform 模块、Mermaid 图表和代码库，变成一个 C4 模型。

如何用 MCP 把 Confluence 架构文档迁移到 Archyl - Archyl Blog