镭内容技术 交付操作规范 · Direct Helpset
SOP · XDelivery Reader 适用角色:文档团队出版工程师 / XDelivery 平台管理员

XDelivery Reader HTML 交付操作说明书

本说明书规定将 DITA/HTML 资料发布至 XDelivery Reader 的标准操作流程。全部打包与发布步骤均在本地 DITA-OT 与 XDelivery Config 中直接完成。

STEP 01 · BUILD
生成 XHTML
--format=xhtml
STEP 02 · PACKAGE
根目录打包 ZIP
index.html 位于压缩包顶层
STEP 03 · PUBLISH
XDelivery 导入
Direct Helpset + Add Language
STEP 04 · VERIFY
Reader 线上校验
/kb/<lang>/<External ID>
01

前置条件

项目 要求
XDelivery Config 拥有 Add Publication 权限的账号
Reader 可正常登录的 Reader 账号
DITA-OT 建议使用与服务器同版本的 DITA-OT 3.7.4
源文件 DITA map、topics、images 及 common 依赖文件齐全
输出格式 必须使用 XHTML,严禁使用 HTML5
02

生成 XHTML 输出

oxygen 编辑器,执行 XHTML 为发布对象的操作:

输出必检项

  1. 输出根目录必须存在以下核心文件与目录:
    输出根目录结构
    index.html
    topicsimagescommonltr.css
  2. index.html 与所有 topic HTML 必须是 XML well-formed XHTML,文件头部包含标准 XML 声明与 XHTML 命名空间:
    XHTML 头部校验
    <?xml version="1.0" encoding="UTF-8"?>
    <html xmlns="http://www.w3.org/1999/xhtml">
  3. 若 map 引用了 ../../common/...,确认目标文件真实存在;缺失时需先补齐或移除相关引用。
禁止使用 --format=html5 HTML5 格式虽然能导入并在浏览器中打开单页,但会导致 Direct Helpset 的左侧 TOC 目录为空,Reader 页面将失去导航树。
03

整理输出目录

1. 扁平化目录层级

部分 DITA-OT 工程会输出嵌套子目录(例如 FPGA\项目名 opics\... 与 FPGA\项目名\images\...)。需将 topics 与 images 移动至与 index.html 同级,并同步修正 HTML 中的相对路径。

标准目录层级
index.html
topicsimagescommoncommonltr.css

2. 清理非法文件名

DHS 解析器禁止文件名中包含以下特殊字符:

禁止字符集
+ % @ # & ~ / \ : * ? " < > | ' , =
  • 不得包含 _xi 后跟数字的片段;
  • 不建议包含空格、圆括号 ();
  • 清除所有 .bak、.tmp、.list、.pp 等临时或无效扩展名文件。
重命名对照示例(修改后必须同步更新 HTML 引用)
image84(1).png          -> image84_1.png
high_purity_...,_...html -> high_purity_..._...html

3. 校验链接闭包

  • 包内所有文件均可通过 index.html 的相对链接逐级到达(无孤立文件);
  • 全文无 http://127.0.0.1:5200/... 等本地调试地址;
  • 无死链或指向包外的相对路径越界。
04

打包 Direct Helpset ZIP

进入输出目录内部,全选根目录下的内容文件与子文件夹直接压缩,切勿在上一级目录右键压缩整个文件夹。

正确打包结构index.html 位于根目录
FSUG-Man.zip
├── index.html
├── topics├── images├── common└── commonltr.css
错误打包结构多出一层父文件夹
FSUG-Man.zip
└── FSUG-Man    ├── index.html
    ├── topics    └── images\
05

在 XDelivery Config 中发布

1. 登录管理后台

XDelivery Config 地址
https://<你的域名>/kbconfig

2. 新建 Direct Helpset

依次进入 Publications → 选择目标 Category(或 ROOT)→ 点击 Add Publication → 选择 Direct Helpset(勿选 File)。

字段 示例 填写规则
External ID DH_UG285 仅限字母、数字、下划线、连字符;禁止空格与中文
Default Name UG285 Gowin BSRAM-SSRAM 手册显示名称,保存后在列表中选中该 Publication

3. 添加语言并导入 ZIP

  1. 点击 Add Language,选择目标语言代码(如 zh-CN 或 en-US)并保存。
  2. 在语言列表中选中该语言行,点击 Import,上传第 04 步生成的 ZIP 压缩包并确认。
  3. 导入完成后,检查语言行状态是否显示为 Content Present = true。若仍为 false,请排查 ZIP 根目录与 XHTML 格式后重新导入。
06

在 Reader 中验证

在浏览器中访问以下 URL 规则打开已发布手册:

Reader 访问路径与示例
https://<你的域名>/kb/<langCode>/<External ID>

# 示例:
https://raycontentech.com/kb/zh-CN/DH_UG285
https://raycontentech.com/kb/en-US/DH_FSUG_X

测试账号参考(正式交付前请务必修改默认密码):kbreader / Reader_999!

  • 左侧 TOC 目录树层级完整且可展开;
  • 点击任意 topic 节点,右侧正文正常渲染;
  • 图片加载清晰,commonltr.css 样式生效;
  • 多语言版本切换指向正确。
07

常见错误与处理

错误现象 根本原因 处理方法
Invalid externalId 包内文件名含括号、空格、逗号等非法字符 重命名文件并同步更新 HTML 引用
Invalid file name 存在 .bak 或未注册扩展名文件 删除冗余文件或修改为合法扩展名
element type "link" must be terminated HTML 未闭合标签,不符合 XML well-formed 使用 Oxygen 编辑器 --format=xhtml 重新构建
导入成功但 Reader 页面空白 误用了 HTML5 输出,导致 DHS 无法解析 TOC 改用 XHTML 输出重新打包导入
仅显示部分 topic 部分页面不在 index.html 链接闭包内 在 map/index 中补齐链接或清理孤立文件
来源或页面链接打不开 链接硬编码指向 127.0.0.1 批量替换为相对路径或正式公网域名
08

互联网访问 平台管理员操作

普通内容发布者无需操作本节。公网部署推荐使用标准 443 端口反向代理:

Apache 反向代理配置
ProxyPass        /kb  https://localhost:8444/kb
ProxyPassReverse /kb  https://localhost:8444/kb
ProxyPass        /lwa https://localhost:8444/lwa
ProxyPassReverse /lwa https://localhost:8444/lwa
  • 域名 DNS 已解析至服务器公网 IP,防火墙已放行 443 端口;
  • TLS 证书覆盖实际访问域名;
  • 安全边界:严禁将 8444、5200 内部端口直接暴露至公网。
  • 公网连通性验证地址:https://<域名>/kb/<lang>/<External ID>
09

AI 助手配置 可选 · 平台管理员操作

AI 助手属于服务器端增强配置,普通发布者无法在 XDelivery Config 界面中直接开启。

  1. 将 Reader 的 XHTML 输出目录作为 RAG 知识语料库;
  2. 生成 ograg_manifest.xml 清单文件;
  3. 配置 RAG 路径参数:TOP_DIR=<语料根> 与 DB_PATH=<metadata.db>;
  4. 依次执行索引构建命令:
    OG-RAG 索引构建
    OG-RAG-Pipeline.exe extract
    OG-RAG-Pipeline.exe reindex
    OG-RAG-Pipeline.exe hypergraph
  5. 确认 /chatbot/chat 同源反向代理路由畅通;
  6. 在 Reader 的 custom-footer.js 中挂载 AI 助手前端组件;
  7. 发起业务提问验证,确认引用来源链接可直接跳转至对应 XDelivery HTML topic(当前 POC 已验证 UG285 / FSUG-Man 可正常问答并返回来源)。
10

发布检查清单

每次交付前请逐项核对以下 12 项基准(点击可实时勾选记录进度):

已完成 0 / 12 项

要领总结:用 Oxygen 编辑器生成 XHTML → 整理成 index.html 在根目录的 ZIP → 在 XDelivery Config 选择 Direct Helpset + Add Language + Import → 用 /kb/<lang>/<External ID> 验证。

切记:HTML5 虽能导入成功但 TOC 必定为空,生产交付必须使用 XHTML。