Oxygen插件自定义协议Conref在Content Fusion中失效求助

问题背景 #

我们在Oxygen插件中实现了自定义abc://协议处理逻辑：

• 检测到该协议时，自动下载conref指向的sourceTopic.dita到本地临时文件夹，提取指定ID（如IP Notes）的<ph>元素内容
• 该逻辑在Oxygen XML Author中完全正常，但移植到**Content Fusion v5.1（Build ID:2023041205）**后出现以下问题：
  • 1. 无法自动下载sourceTopic.dita
  • 2. 手动放置源文件后，目标主题仍无法引用
  • 3. 现有数千个主题使用abc://topic/#/<elementId>格式的conref，需要兼容方案（已知改为<sourceTopic.dita>#/格式能在Content Fusion生效，但Oxygen仅支持同文件夹场景，不满足需求）

解决方案 #

1. 适配Content Fusion服务器端资源处理逻辑 #

Content Fusion的服务器环境和Oxygen本地环境差异极大，需调整核心逻辑：

• 替换本地C://临时路径为Content Fusion的应用级临时目录：通过ro.sync.exml.contentfusion.api.fs.FSManager获取服务器文件系统句柄，不要直接写本地盘符路径
• 使用Content Fusion内置的网络工具：用ro.sync.exml.contentfusion.api.network.NetworkManager实现文件下载，避免本地网络API在服务器端的权限/环境问题

2. 自定义Conref解析器绕开默认校验 #

Content Fusion对DITA conref的默认解析会严格校验文件路径，需主动接管解析流程：

• 实现ro.sync.exml.contentfusion.api.dita.ConrefResolver接口，当检测到abc://协议时，直接返回提前下载好的源文件中对应ID的DOM节点
• 在插件激活时注册该解析器，确保Content Fusion处理conref时优先调用自定义逻辑

3. 双向兼容现有格式 #

为了不修改数千个现有主题，同时适配两个环境：

• Oxygen端：新增对<sourceTopic.dita>#/格式的适配——当检测到该格式且源文件不在同文件夹时，自动映射到abc://协议的下载/提取逻辑
• Content Fusion端：新增对abc://topic/#/<elementId>格式的解析——将该格式转换为服务器可识别的文件路径+锚点格式，再通过自定义解析器返回内容

关键代码示例（伪代码） #

Content Fusion自定义ConrefResolver实现 #

public class ABCConrefResolver implements ConrefResolver {
  @Override
  public Node resolveConref(ConrefReference ref) throws Exception {
    String conrefValue = ref.getConref();
    if (conrefValue.startsWith("abc://")) {
      // 解析topic名称和元素ID
      String[] parts = conrefValue.split("#/");
      String topicName = parts[0].replace("abc://topic/", "") + ".dita";
      String elementId = parts[1];
      
      // 获取服务器临时目录下的源文件
      File sourceFile = FSManager.getInstance().getFile("/tmp/conref_resources/" + topicName);
      if (!sourceFile.exists()) {
        // 调用NetworkManager下载文件到临时目录
        NetworkManager.getInstance().download(getTopicDownloadUrl(topicName), sourceFile);
      }
      
      // 解析源文件并返回指定ID的ph元素
      Document sourceDoc = XMLUtil.parse(sourceFile);
      return sourceDoc.getElementById(elementId);
    }
    return null; // 非abc协议交给默认解析器处理
  }
}

插件激活时注册解析器 #

public class ABCContentFusionPlugin extends ContentFusionPlugin {
  @Override
  public void pluginStarted() throws Exception {
    super.pluginStarted();
    // 注册自定义Conref解析器
    registerConrefResolver(new ABCConrefResolver());
  }
}

内容的提问来源于stack exchange，提问作者Gyfu