· 研发文件或售后手册交付 · v2.0
写管用条件发布平台
操作指南与条件处理用例
从 DITA 结构化编写到多构型条件发布——同一套源文件，通过在元素、Topic、Map 三级挂载条件属性，由 rtcondition 布尔引擎在发布时精准过滤， 为每个产品构型、每一类受众输出对应的交付物。 本指南以 RAV4 车主手册与 UBTECH 产品手册为实操样本，覆盖从业务规则到发布验证的完整链路。
6
条件维度
21
RAV4 条件代码
3
条件挂载层级
4
布尔运算符
3
实战样本
60%+
结构化复用率
01
平台概览与工作流
写 · 管 · 用——内容从创作到交付的三段链路
写
DITA 结构化编写
在 Oxygen XML Author 中以 Topic 为粒度模块化创作。Concept / Task / Reference 三类主题分工明确，内容一次编写、多处引用。
管
GitLab 版本与复用
分支、标签、合并请求管理手册迭代；conref / keyref 建立复用库， 共享 Topic 同时服务多条产品线。
用
条件化多格式发布
同一套源文件，按产品、配置、区域、动力等条件过滤， 输出 HTML5 / PDF / DOCX。
工作流
| 步骤 | 动作 | 说明 |
|---|---|---|
01 | 条件设计 | 识别内容差异，映射到 DITA 条件属性 |
02 | 条件库导入 | CSV 导入 TC 代码，注册互锁关系 |
03 | 源文件标注 | Topic 内挂载 product / platform / otherprops / rtcondition |
04 | Git 提交 | 分支 + 提交信息规范，Push 到 GitLab |
05 | 条件发布 | 选择表达式 → rtcondition 过滤 → DITA-OT 输出 |
06 | 结果验证 | 对照预期过滤表逐段检查 |
本指南与旧版的差异
本版本新增能力进阶章节（业务逻辑到条件模型的映射方法）与
RAV4 车主手册条件处理实战（元素级、Topic 级、Map 级三层样本），
每个样本附预期过滤表，可直接用于发布验证。
02
能力进阶：从业务规则到条件模型
复杂文档制作业务需求的建模方法
复杂手册制作的真正难点不在写作，而在把业务规则转化为 可执行的条件模型。本章给出四步映射方法，帮助用户独立完成从业务分析到发布设计的全过程。
2.1 平台五项核心能力
条件库
TC 代码管理
以 TC 代码为唯一标识，集中管理产品、平台、选装、受众、语言五个维度。支持 CSV 批量导入与条件树浏览。
互锁
条件关系注册
注册 implies、excludes、depends_on 关系，防止产生无效条件组合。
表达式
布尔引擎
原生支持 AND / OR / NOT 及任意嵌套，可在元素级、Topic 级、Map 级挂载。
参数化
keydef 变量
集中定义车型名、能耗单位等变量，切换取值即切换全文术语。
验证
过滤结果追溯
每份交付物附带条件过滤记录，配合验证清单逐段检查。
2.2 业务规则 → 条件模型的四步映射
第一步
识别差异来源
拆解业务规则为「哪些内容会因什么而不同」。例如：高配 / 低配、混动 / 纯电、中国 / 欧洲、年度改款。
第二步
建立条件维度
将差异来源映射到 DITA 标准属性（product / platform / otherprops / audience / xml:lang）， 每个维度分配 TC 代码。
第三步
注册互锁关系
分析维度间的依赖、排斥、隐含关系，注册到条件互锁表，防止无效组合。
第四步
设计发布表达式
针对每个发布目标组合维度生成表达式。单维度用平台构建表达式， 跨维度用 ISH 布尔表达式。
2.3 六维条件属性模型
| 维度 | DITA 属性 | 典型取值 | 过滤逻辑 |
|---|---|---|---|
| 产品 / 车型 | product | rav4-2026 / rav4-ev2014 / alpha1pro | 等值（多值 OR） |
| 平台 / 动力 | platform | hev / phev / ev / windows / mac | 等值（多值 OR） |
| 驱动 / 选装 | otherprops | 2wd / awd / digital-key / sunroof | 等值（多值 OR） |
| 市场 / 受众 | audience | us / ca / maintenance / operations | 等值（多值 OR） |
| 语言 | xml:lang | zh-CN / en / fr-CA | 前缀匹配 |
| 复杂组合 | rtcondition | (TC000002=ev) or (TC000002=phev) | 完整布尔 |
rtcondition 的使用边界
它依赖镭技术扩展 DTD，仅在跨维度组合时使用。
2.4 条件互锁关系速查
| 条件 A | 关系 | 条件 B | 说明 |
|---|---|---|---|
product=rav4-ev2014 |
implies | platform=ev |
2014 款必为纯电 |
product=rav4-2026 |
implies | platform=hev |
2026 款必为混动 |
otherprops=moon-roof |
excludes | otherprops=pano-roof |
两种天窗互斥 |
otherprops=digital-key |
depends_on | product=rav4-2026 |
数字钥匙仅 2026 可选 |
audience=us |
excludes | audience=ca |
单一发布目标区域 |
2.5 能力训练目标
完成本章学习后，您应能独立完成：
① 从业务规则中识别条件维度；② 为维度分配 TC 代码并导入条件库； ③ 注册互锁关系防止无效组合；④ 为每个发布目标设计正确的表达式。
① 从业务规则中识别条件维度；② 为维度分配 TC 代码并导入条件库； ③ 注册互锁关系防止无效组合；④ 为每个发布目标设计正确的表达式。
03
GitLab 仓库管理
分支、提交、合并请求——内容资产的版本控制
3.1 访问信息
| 项目 | 地址 | 说明 |
|---|---|---|
| 核心 Master Repo | ray/bistu-edu | UBTECH 机器人 + 飞行器两条产品线 |
| 本地化翻译 Repo | jeffrey/bistu-edu-l10n | 大模型翻译流程与多语言分支管理 |
| 登录账号 | 用户名 Jeffrey ／ 密码 vGk7sXj6LNQxWG7 |
|
| Personal Access Token | glpat-i8TJemxAD1PokXoIheEJ6G86MQp1OjcH.01.0w1f6xhdb |
|
认证方式必须使用 HTTPS + PAT
Windows 环境下 JGit 与部分 OpenSSH 版本存在
rsa-sha2-256/512 算法不兼容问题，
会导致 push / pull 随机失败。请使用 HTTPS + Personal Access Token，不要用 SSH。
3.2 分支命名与提交规范
分支命名
# 命名规范：release/<产品简称>-<语言>-v<版本号>
git checkout main
git pull origin main
git checkout -b release/rav4-zh-v1.1
# 变更类分支：feature/<变更类型>-<Issue 编号>
git checkout -b feature/config-awd-1024
# 版本迭代完成后打 Tag
git tag -a rav4-zh-v1.1 -m "RAV4 中文手册 v1.1 发布"
git push origin rav4-zh-v1.1
Commit Message 格式
# 格式：[模块/topic名] 简述改动内容
[c_battery_charging] 更正充电时长参数，2h → 2.5h
[r_troubleshooting] 新增第 18 条故障排除项
[lib_if_towed] 补充四驱混动拖车禁忌条件段落
[lib_smart_key] 挂载 otherprops=digital-key 条件
常见踩坑
忘记 Pull 就开始改 → 容易产生冲突。原则：开工前必 Pull，提交前必 Pull 一次再 Push。
用 SSH Clone 报算法错误 → 换成 HTTPS + PAT。
中英文版本号误认为必须同步 → 两者可独立管理，但需注明对应源语言版本号。
用 SSH Clone 报算法错误 → 换成 HTTPS + PAT。
中英文版本号误认为必须同步 → 两者可独立管理，但需注明对应源语言版本号。
04
Oxygen XML 编辑器
DITA Topic 的创建、编辑、校验与 AI 辅助
4.1 环境配置
- 下载 Oxygen XML Author，安装路径建议
F:\OxygenXMLAuthor28 - 授权：查阅《编辑器授权》文本文件获取授权码
- 打开
Window > Show View > Git Staging，确认 Git 插件已加载
4.2 Topic 类型与命名约定
| 类型 | 用途 | 前缀 | 示例 |
|---|---|---|---|
| Concept | 概念说明、背景介绍 | c_ | c_safety_intro.dita |
| Task | 操作步骤、流程指引 | t_ | t_power_on_off.dita |
| Reference | 参数表格、故障排除 | r_ | r_troubleshooting.dita |
| 共享库 | 多产品线复用的 Topic | lib_ | lib_if_towed.dita |
| DITA Map | 手册骨架与层级 | 产品名 + _user_guide | rav4_user_guide.ditamap |
Concept 主题示例
<?xml version="1.0" encoding="UTF-8"?>
<concept id="c_safety_intro" xml:lang="zh-CN">
<title>安全说明</title>
<shortdesc>操作 Alpha 1 Pro 机器人的重要安全信息</shortdesc>
<conbody>
<note type="warning">持 Alpha 的背包摘带，避免摔落损坏</note>
<section>
<title>通用安全预防措施</title>
<ul>
<li>运行时与机器人保持安全距离</li>
<li>连续运行不超过 1 小时以保护伺服寿命</li>
</ul>
</section>
</conbody>
</concept>
4.3 校验与 AI 辅助
| 校验类型 | 操作 | 目的 |
|---|---|---|
| 单文件校验 | Ctrl+Shift+V | 校验单个 .dita 文件的 DITA 合规性 |
| Map 完整性 | Validate + Check for Completeness | 确认无断链 |
| 本地预览 | 右键 ditamap → Configure Transformation Scenario | 预览 HTML5 输出效果 |
四款 AI 插件
A
反思翻译
对已有翻译进行反思性审校，识别语义偏差、术语不一致和风格问题。
B
内容推荐
基于上下文推荐内容片段，帮助快速完成相似结构的 Topic 编写。
C
术语管理
自动提取和匹配术语库标准译法，确保跨 Topic 术语一致性。
D
ASD-STE
对照简化技术英语规范检查英文文本的简洁性与可读性。
05
写管用条件发布系统
从条件库到表达式，再到最终交付件
5.1 系统入口
| 项目 | 信息 |
|---|---|
| 系统地址 | http://58.87.102.99:8080/#/dita-publish |
| 配套手册 | 写管用条件发布系统操作手册（金山文档） |
| 核心模块 | 标签选项代码库 · 产品管理 · DITA 发布 |
5.2 发布三步走
Step 1 — 构建条件
在发布系统中配置构建条件，包括目标格式（HTML5 / PDF / DOCX）、
受众条件（audience）、平台条件（platform）、产品条件（product）。
条件发布的核心价值
同一套 DITA 源文件，通过不同条件组合，自动生成面向不同受众、不同平台的差异化内容，
实现「一次编写，多渠道发布」。
Step 2 — 选择 Repo 与 Map
| 选择项 | 说明 |
|---|---|
| Repository | 选择 GitLab 上的目标仓库（如 bistu-edu） |
| Branch | 选择要发布的分支（如 main 或 release/rav4-zh-v1.1） |
| DITA Map | 选择 map 文件（如 maps/RAV4_Master.ditamap） |
Step 3 — 发布与下载
点击发布后，系统将自动完成以下动作：
- 从 GitLab 拉取指定分支的最新内容
- 调用 rtcondition 布尔引擎执行条件过滤
- 调用发布引擎完成格式转换
- 生成带版本号的输出包，提供下载链接并保留发布历史
产出物存放建议
建议路径
releases/<产品>/v<版本>/{html,pdf,docx}/，
不覆盖历史版本，保留完整可追溯的发布记录。
5.3 条件库 · 互锁 · 表达式构建器
① 标签选项代码库
条件树
所有条件属性及取值集中存储，组织为树形结构：产品线 / 动力平台 / 配置等级 / 市场区域 / 选装包。
② 条件互锁
逻辑约束
depends_on 选装电动座椅必须配置等级 ≥ 中
excludes 低配与天窗互斥
implies 旗舰版自动包含全部选装包
③ 表达式构建器
可视化组合
拖拽条件节点自动生成 rtcondition 布尔表达式，支持 AND / OR / NOT 与嵌套，发布前可预览过滤结果。
表达式示例
(product="rav4-2026" and platform="hev" and otherprops="awd")
or
(product="rav4-2026" and platform="hev" and otherprops="2wd" and otherprops="trailer-assist")
含义：2026 混动四驱版全显示；两驱版仅当选装拖车辅助时才显示对应章节。
06
RAV4 用户手册条件处理实战
元素级 · Topic 级 · Map 级三层样本与过滤验证
以丰田 RAV4 车主手册（2026 混动版 / 2014 纯电版）为实操案例。
两车型共享约 60% 的结构化内容，差异收敛到
platform（hev / ev）与 otherprops（2wd / awd）两个维度。
以下三个样本分别展示三层条件挂载方式，每个样本附预期过滤表可直接用于验证。
6.1 元素级布尔组合 — 拖车禁忌
文件：topics/library/emergency/lib_if_towed.dita
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="lib_if_towed" xml:lang="zh-CN">
<title>如果需要拖车</title>
<shortdesc>牵引本车的正确方式与禁忌。</shortdesc>
<conbody>
<!-- ① 无条件共享 -->
<p>本车必须使用平板拖车运输，使四轮全部离地。请勿使用吊起单轴的方式牵引，否则可能损坏传动系统。</p>
<!-- ② ev OR phev -->
<p rtcondition="(TC000002=ev) or (TC000002=phev)">
电动化车型（纯电/插电混动）：即使系统关闭，车轮转动也会带动电机发电，
可能损坏动力系统——严禁四轮着地牵引。
</p>
<!-- ③ hev AND awd -->
<p rtcondition="(TC000002=hev) and (TC000003=awd)">
四驱混动车型：任何情况下都禁止两轮着地牵引（前或后轴着地均会损坏耦合机构）。
</p>
<!-- ④ 无条件共享 -->
<p><note type="caution"><b>注意：</b>
紧急情况下如需短距离移动车辆，请使用辅助轮并联系专业救援。</note></p>
</conbody>
</concept>
过滤结果对照
段落
HEV AWD
HEV 2WD
EV 2014
① 平板拖车
✓
✓
✓
② ev / phev 禁四轮着地
—
—
✓
③ hev + awd 禁两轮着地
✓
—
—
④ 注意（紧急移动）
✓
✓
✓
大小写陷阱
若条件库中
TC000003 定义为 awd，而 DITA 中写作 AWD，
平台将匹配失败。建议统一小写，或在平台设置中启用 case-insensitive 匹配。
6.2 Topic 级产品过滤 — 智能钥匙
文件：topics/library/operation/lib_smart_key_system.dita
<concept id="lib_smart_key_system"
product="rav4-2026"
otherprops="digital-key"
xml:lang="zh-CN">
<title>智能钥匙系统</title>
<shortdesc>智能手机数字钥匙的绑定、使用与故障处理。</shortdesc>
<conbody>
<p>数字钥匙通过蓝牙与车辆通信，靠近车门即可解锁……</p>
<note type="important">
数字钥匙仅 RAV4 2026 款支持，需先完成手机 App 绑定。
</note>
</conbody>
</concept>
| 发布条件 | 是否显示本 Topic |
|---|---|
product=rav4-2026 otherprops=digital-key | 显示 |
product=rav4-2026（未选数字钥匙） | 隐藏 |
product=rav4-ev2014 | 隐藏 |
6.3 段落级平台分叉 — 保养前舱
文件：topics/library/maintenance/lib_front_compartment.dita
<task id="lib_front_compartment" xml:lang="zh-CN">
<title>前舱检查</title>
<taskbody>
<prereq>停车、熄火、等待冷却。</prereq>
<!-- HEV 专属 -->
<steps><step><cmd platform="hev">
拔出机油尺，擦拭后重新插入，检查油位在 MIN-MAX 之间。
</cmd></step>
<!-- EV 专属 -->
<step><cmd platform="ev">
检查电机冷却液液位是否在 FULL 标记处。
</cmd></step>
<!-- 共享步骤 -->
<step><cmd>检查挡风玻璃清洗液液位，低于 MIN 时补充。</cmd></step>
</steps>
</taskbody>
</task>
6.4 发布表达式与验证
| 场景 | 平台构建表达式 | 预期输出 |
|---|---|---|
| RAV4 2026 HEV AWD | (TC000001=rav4-2026) and (TC000002=hev) and (TC000003=awd) |
含 awd 段落、含拖车禁忌四驱段落 |
| RAV4 2026 HEV 2WD | (TC000001=rav4-2026) and (TC000002=hev) and (TC000003=2wd) |
排除 awd 段落，保留通用拖车段落 |
| RAV4 EV 2014 | (TC000001=rav4-ev2014) and (TC000002=ev) |
含充电程序、含 ev 拖车禁忌段落 |
| 电动化平台通用禁忌 | (TC000002=ev) or (TC000002=phev) |
仅显示电动化平台禁四轮着地段落 |
空格分隔 ≠ AND
TC000001=rav4-2026 TC000002=hev TC000003=awd 这种写法缺少布尔运算符，
引擎无法判定条件项之间的逻辑关系，表达式求值失败。
每个条件项必须用括号包住，项与项之间用 and / or / not 显式连接，
例如：(TC000001=rav4-2026) and (TC000002=hev) and (TC000003=awd)。
多值取值的 OR 关系写在取值内部（如 platform="hev ev"），不要与条件项之间的运算符混淆。
xml:lang 不参与布尔表达式
语言维度由 DITAVAL 的前缀匹配处理——
<prop att="xml:lang" val="zh" action="include"/> 即可匹配 zh-CN。
它是独立的过滤轴，不与产品 / 平台条件在同一布尔式中混写；发布目标只需在 DITAVAL 中声明语言即可。
若平台确需在同一表达式内标注语言，应写成 and (xml:lang=zh-CN)，而不是裸列在末尾。
6.5 条件预览
保留
过滤
无条件共享
共享
平板拖车通用说明
无条件
PASS
四驱混动禁两轮着地
(TC000002=hev) and (TC000003=awd)
FILTER
纯电/插混禁四轮着地
(TC000002=ev) or (TC000002=phev)
共享
紧急移动注意事项
无条件
能力训练目标
完成本章学习后，您应能独立完成：
① 读懂 rtcondition 布尔表达式；② 为段落 / Topic 正确挂载条件属性； ③ 按不同构型设计发布表达式；④ 对照预期结果表逐段验证输出。
① 读懂 rtcondition 布尔表达式；② 为段落 / Topic 正确挂载条件属性； ③ 按不同构型设计发布表达式；④ 对照预期结果表逐段验证输出。
07
附录与速查
访问信息 · 属性速查 · 命名规范 · 常见问题
A. 账号与访问信息
| 系统 | 地址 | 账号 / 凭据 |
|---|---|---|
| GitLab | 139.198.6.122:8888 | Jeffrey / vGk7sXj6LNQxWG7 |
| GitLab PAT | glpat-i8TJemxAD1PokXoIheEJ6G86MQp1OjcH.01.0w1f6xhdb | |
| 核心 Master Repo | ray/bistu-edu | UBTECH 机器人 + 飞行器 |
| 本地化翻译 Repo | jeffrey/bistu-edu-l10n | 大模型翻译流程 |
| 条件发布系统 | 58.87.102.99:8080 | 同 GitLab 账号 |
| 操作手册 | 写管用条件发布系统操作手册（金山文档） | |
B. DITA 条件属性速查
| 属性 | 用途 | 示例 | 过滤逻辑 |
|---|---|---|---|
product | 产品 / 车型 | product="rav4-2026" | 等值 |
platform | 动力 / 平台 | platform="hev ev" | 多值 OR |
otherprops | 选装 / 驱动 | otherprops="awd" | 等值 |
audience | 市场 / 受众 | audience="maintenance" | 等值 |
xml:lang | 语言 | xml:lang="fr-CA" | 前缀匹配 |
rtcondition | 复杂布尔 | (TC1=ev) or (TC1=phev) | 完整布尔 |
C. 命名规范速查
| 元素 | 规范 | 示例 |
|---|---|---|
| Concept | c_ + 主题名 | c_safety_intro.dita |
| Task | t_ + 主题名 | t_power_on_off.dita |
| Reference | r_ + 主题名 | r_troubleshooting.dita |
| 共享库 Topic | lib_ + 主题名 | lib_if_towed.dita |
| DITA Map | 产品名 + _user_guide.ditamap | rav4_user_guide.ditamap |
| 分支名 | release/<产品>-<语言>-v<版本> | release/rav4-zh-v1.1 |
| Tag 名 | <产品>-<语言>-v<版本> | rav4-zh-v1.1 |
D. 常见问题速查
| 问题 | 解决方案 |
|---|---|
| SSH Clone 失败 | 改用 HTTPS + PAT 认证 |
| Push 时冲突 | 先 Pull 再 Push，养成开工前 Pull 的习惯 |
| DITA 校验报错 | 检查标签闭合、note 位置（须在 section 前）、元素顺序 |
| 发布系统找不到 Map | 确认分支已 Push 到远程，且 ditamap 在仓库根目录或一级子目录 |
| AI 翻译破坏标签 | 使用 Author 模式而非 Text 模式调用 AI |
| 中英文版本号混淆 | 两者独立管理，在 metadata 中注明对应源语言版本号 |
| 条件过滤后内容为空 | 检查表达式语法与大小写，用表达式构建器验证并预览输出 |
| 低配车型显示了高配内容 | 检查条件互锁规则是否遗漏，属性名是否在条件层中声明 |