这是什么
嵌入 Oxygen XML Author 与 Oxygen Web Author 的能力包。不改变写作方式，照常在 Author 视图里写 DITA / Markdown；需要 AI 时，从「AI 能力」菜单按场景选择动作。
What is this
An add-on package embedded in Oxygen XML Author and Oxygen Web Author. It doesn't change how you write—you keep authoring DITA / Markdown in Author view. When you need AI, pick an action by scenario from the "AI Capabilities" menu.
动作层
Action Layer
25 个动作：19 个「产出内容 / 报告」的模型动作 + 6 个「跑流程」的工具动作。
25 actions: 19 model actions that produce content/reports + 6 tool actions that run processes.
分析层
Analysis Layer
一次看完整本，不用逐篇翻：打开手册地图点一下，系统会把地图里的每一篇都读一遍再交给 AI 出结论。实测 206 处引用 / 93 个主题，0 遗漏；手册再大也能整本分析（系统自动分批，不会漏尾部）；如只想看当前文件，可在设置里切换。
三类人，各看一段
Three readers, one paragraph each
文档工程师：打开手册、点一下，就拿到逐章结论；中英同步时只改该改的那几句，其它一个字都不动。
文档经理：一次覆盖整本手册，不用逐篇翻；发布前自动体检，通过才放行；中英版本号自动对得上。
研发总经理：不用另外买 AI 许可，不换现有工具；检查口径可追溯、可审计，出问题有门禁拦住。
Documentation engineer: open the manual, click once, get per-chapter conclusions; when syncing EN, only the changed sentences move — nothing else is touched.
Documentation manager: cover the whole manual in one pass; get an automatic pre-release health check that only lets clean output through; CN/EN version numbers line up by themselves.
Engineering GM: no extra AI licence, no tool replacement; the checking criteria are traceable and auditable, and problems are blocked by the gate.
Cover the whole manual in one pass: open the manual map and click once; every referenced topic is read before the model is asked to conclude. Measured 206 references / 93 topics, 0 omitted. Large manuals are batched automatically so nothing at the end is dropped; switch to "current file only" in settings if you prefer. Measured: 206 refs / 93 topics.
流程层
Process Layer
本地化 Delta 管线：版本对齐 → 只译增量 → 严格合并 → 门禁放行。
Localization Delta Pipeline: Version align → translate only increments → strict merge → gate release.
特征
按场景组织的 25 个动作、一次覆盖整本手册、报告开在编辑器里、中英只改该改的、安装即用、不用命令行。
Features
25 scenario-based actions, map analysis, HTML reports, localization that touches only what it should, sealed delivery, zero command line.
2.1 按场景组织的 25 个动作
2.1 25 actions organized by scenario
| 场景 | Scenario | 动作数 | Actions | 做什么 | What it does |
|---|---|---|---|---|---|
| 通用底座 | General Foundation | 2 | 生成 DITA 主题 · 结构评审 | Generate DITA topic · Structure review | |
| 术语库 | Termbase | 4 | 术语合规检查 · 术语规范化改写 · 生成术语引用片段 · 术语资产一致性审计 | Term compliance check · Normalize terminology · Generate term reference snippet · Term asset consistency audit | |
| 质量门禁 | Quality Gate | 2 | 生成质量评分 · 按评分整改 | Generate quality score · Remediate by score | |
| DITA 复用 | DITA Reuse | 2 | 分析复用机会 · 改写为复用引用 | Analyze reuse opportunities · Rewrite as reuse references | |
| Markdown 出版 | Markdown Publishing | 4 | 预检出版 · 宽表溢出修复 · 生成出版说明 · 规划 CMS 转换 | Pre-flight publish · Wide-table overflow fix · Generate publishing notes · Plan CMS conversion | |
| 本地化 | Localization | 4 | 标注变更节点 · 提取增量片段 · 翻译增量片段 · 核查英文镜像 | Mark changed nodes · Extract incremental segments · Translate incremental segments · Verify English mirror | |
| 工具动作 | Tool Actions | 6 | 运行门禁 · 提取增量 · 严格合并到英文镜像 · 标记版本载体 · 创建发布标签 · 发布检查清单 | Run gate · Extract increment · Strict merge to English mirror · Mark version carrier · Create release tag · Release checklist |
一次看完整本，一处不漏
The whole manual in one pass, nothing missed
打开一张手册地图点一下，系统按地图把每一篇都读到再交给 AI。报告第一句就写清范围：本次分析：整本手册 · 93 个主题 · 0 遗漏。手册再大也能整本分析（系统自动分批，不会漏尾部）；如只想看当前文件，可在设置里切换。
Open a manual map and click once; every referenced topic is read before the model concludes. The report opens with its scope: this run: whole manual · 93 topics · 0 omitted. Large manuals are batched automatically; switch to "current file only" in settings if you prefer.
在 93 个主题里，找出 232 处重复内容
232 duplicated passages found across 93 topics
复用分析的每一条都算出了相似度，没有一条是空的：两种方法交叉判定——完全相同的段落，以及只有个别字词不同的近似段落。报告给出相似度 · 重复次数 · 段落字数 · 出现位置。若内容太少（不足 3 份内容地图），报告直接写「语料不足，不可判定」，不会拿 0% 当结论。
Every reuse candidate carries a computed similarity — none is left blank. Two methods cross-check: identical passages, and near-identical ones differing in a few words. The report shows similarity · repeat count · passage length · location. With too little content (fewer than 3 content maps) it says "insufficient corpus, not decidable" instead of a 0% headline.
报告开在编辑器里，不用切工具
Reports open inside the editor
结果是带样式的网页报告，在 Oxygen 标签页里打开，可保存、可比对、可直接进评审包。需要改文档的动作只在状态栏提示一句「已替换 N 字符，可撤销」。
Results are styled HTML reports opened in an Oxygen tab — savable, comparable, attachable to a review package. Write-back actions only show a status-bar hint: "replaced N characters, undo available".
网页版：8 个整本手册动作 + 19 个当前文件动作
Web version: 8 whole-manual actions + 19 current-file actions
网页版分两类，界面已标注清楚：8 个整本手册动作（质量评分、术语检查与审计、复用机会、结构评审、出版前检查、抽取增量、核查英文），一次覆盖整本；19 个当前文件动作，只处理你正在看的那一篇。管理员在后台点一下安装、重启服务即生效，无需登录服务器；两家公司内容各自独立，互相看不到对方资料；只需购买此国产 AI 插件许可。
The web version is split into two clearly labelled groups: 8 whole-manual actions (quality score, terminology check and audit, reuse opportunities, structure review, pre-release check, extract changes, verify English) and 19 current-file actions for the topic you have open. An administrator installs it from the backend and restarts the service — no server logins. Each company's content stays separate, and the AI service runs on your own account with no extra editor AI licence.
技术细节（给工程师）· Technical details for engineers
打开 .ditamap/.bookmap/.map 时默认整图：解析 topicref/mapref，逐篇读取被引用 topic，跳过 resource-only 与 external。报告首行 scope=whole-map | 检查 topic: N | 引用 M | 遍历完整: true/false；单篇为 scope=current-document。开关 map.wholeMapOnMapDocument=false；分批上限 map.batchChars=40000；完整性读数 topicsOmitted=0 / charactersOmitted=0，实测 93/93 (100%)。
复用打分：FNV-1a-64 + shingle/MinHash + 字符 5-gram；字段 similarity/containment/occurrences/charLen；实测 blocks=238 / candidates=232 / notComputed=0。
本地化：release/CN-x.y ↔ release/EN-x.y；prolog 版本权威、@rev 派生且须一致；6 道门禁退出码 0/1/2/3；英文侧 1 file changed, 1 insertion(+)。
2.2 打开地图就覆盖整本（不是只读当前文件）
2.2 A map covers the whole manual (not just the open file)
选中一张 DITA Map → 自动解析 topicref、逐篇读取 topic、展开引用、聚合成结构化结果，再交给模型。
Select a DITA Map → automatically parses topicref, reads each topic, expands references, aggregates into a structured result, then hands it to the model.
实测：206 引用 / 93 topic / 77,658 正文字符 / 626–795 ms。
Measured: 206 refs / 93 topics / 77,658 body chars / 626–795 ms.
2.3 报告在编辑器里，以 HTML 呈现
2.3 Reports in the editor, rendered as HTML
结果不弹独立小窗：生成自包含 HTML（表格 / 列表 / 代码块 / 深色模式 / 打印样式），在 Oxygen 标签页里打开；可保存、可比对、可入库。
Results don't pop up in a separate window: a self-contained HTML (tables / lists / code blocks / dark mode / print styles) opens in an Oxygen tab; it can be saved, compared, and archived.
写回类动作只在状态栏提示：「已替换 N 字符，可 Ctrl+Z 撤销」。
Write-back actions only show a status bar hint: "Replaced N characters, undo with Ctrl+Z".
2.4 本地化：只动该动的
2.4 Localization: touch only what should change
- 版本号对齐：中文 release/CN-1.1 ↔ 英文 release/EN-1.1，文件内版本说明为权威。
- 只译增量：以 Git 差异定位改动节点，模型只翻这几句。
- 严格合并：未改动的英文逐字节保留（含 <sub>、Ω、缩进、行尾），越界即拒绝。
- 6 道门禁放行：覆盖、未译、良构、引用、中文残留、版本一致——不通过就不发布。
- Version alignment: Chinese release/CN-1.1 ↔ English release/EN-1.1; the in-file version note is authoritative.
- Translate only increments: Git diff locates changed nodes; the model translates only those sentences.
- Strict merge: unchanged English is preserved byte-for-byte (including <sub>, Ω, indentation, line endings); out-of-bounds is rejected.
- 6 gates for release: coverage, untranslated, well-formed, references, Chinese residue, version consistency—no pass, no release.
2.5 即插即用
2.5 Sealed delivery
作为 Oxygen AI Positron 替代，它就是一个插件，部署方便。
As a plugin, it is easy to deploy.
2.6 零命令行
2.6 Zero command line
日常流程全部在 Oxygen 界面完成：编辑 → AI 能力动作 → Git 暂存提交 → 创建标签（可勾选「推送标签」）→ 发布。需要外的部分已做成 6 个工具动作。
The daily flow is entirely in the Oxygen UI: edit → AI action → Git stage & commit → create tag (optionally push tag) → publish. Anything beyond that is packaged as 6 tool actions.
好处 · 按角色
Benefits · by role
| 角色 | Role | 好处 | Benefit |
|---|---|---|---|
| 文档工程师 | Documentation Engineer | 不切工具、不学命令；点按钮就得结果；改动可追溯、可撤销。 | No tool switching, no commands to learn; click a button and get results; changes are traceable and reversible. |
| 本地化 / 译者 | Localization / Translator | 只翻新增的几句；英文对照稿不会被「顺手改坏」；版本号两边自动对齐。 | Translate only the few new sentences; the English mirror won't be accidentally broken; version numbers align automatically. |
| 评审 / 发布 | Review / Release | 有门禁结论（通过 / 不通过 + 违规清单）；报告可直接存证、进评审包。 | Gate conclusion (pass / fail + violation list); reports can be archived directly and included in review packages. |
| 技术文档负责人 | Documentation Lead | 一套动作覆盖术语 · 质量 · 复用 · 出版 · 本地化，口径统一、可复制到别的产品线。 | One action set covers terminology, quality, reuse, publishing, localization—unified and replicable to other product lines. |
| IT / 平台 | IT / Platform | 与 Oxygen 升级解耦（插件式、可回滚）；后端一个 OpenAI 兼容端点即可；不依赖 Positron 授权。 | Decoupled from Oxygen upgrades (plugin-based, rollback-able); one OpenAI-compatible endpoint on the backend; no Positron license needed. |
价值
Value
效率
Efficiency
把「翻遍 93 篇找问题」变成「点一下 + 看报告」——实测 93 个主题不到 1 秒读完（626–795 毫秒），AI 只处理汇总后的结果。
Turns "search 93 topics for issues" into "click once + read a report"—map analysis aggregates in sub-second time, and the model only processes the aggregate.
一致性
Consistency
术语只取受控词表、复用优先 conref / keyref、语言与动力类型正交——同一份源稿出多本手册，不克隆文件。
Terms come only from the controlled vocabulary, reuse favors conref / keyref, language and powertrain type are orthogonal—one source produces multiple manuals without cloning files.
可审计
Auditability
每次改动 = 一个 changeset + 一份门禁结论 + 一对版本标签；「哪里改了、改了多少、能不能发」都有据可查。
Each change = one changeset + one gate conclusion + one version tag pair; "what changed, how much, can it ship" is fully traceable.
资产化
Assetization
术语库、质量规则、复用盘点、出版规则、本地化增量链路——从「文档里的规定」变成「点一下就执行的检查」。
Termbase, quality rules, reuse inventory, publishing rules, localization increment pipeline—from "rules in a document" to "checks that run on click".
可复制
Replicability
换品牌、换仓库、换提示词即可服务新产品线；能力 = 动作目录，加能力不改机器。
Change the brand, repo, or prompts and it serves a new product line; capability = action catalog, adding capability doesn't change the machine.
三步上手
Three-step quick start
1 · 覆盖插件
1 · Replace plugin
用新包覆盖插件目录（保留你的 oxygeai-capabilities.properties）→ 重启 Oxygen。
Overwrite the plugin folder with the new package (keep your oxygeai-capabilities.properties) → restart Oxygen.
2 · 选场景与动作
2 · Choose scenario and action
打开一篇 DITA 或一张 Map → 菜单「AI 能力」→ 选场景与动作。建议先跑：生成质量评分（打开地图就自动覆盖整本）。
Open a DITA topic or Map → menu "AI Capabilities" → choose scenario and action. Suggested first run: Generate Quality Score (opening a map already covers the whole manual).
3 · 本地化 SOP
3 · Localization SOP
改稿 → 标注变更 → 提交 / 打标签 → 翻译增量 → 严格合并 → 运行门禁 → 发布。
Edit → mark changes → commit / tag → translate increment → strict merge → run gate → release.
本地化 Delta 流程 · 1.0 → 1.1
每次改稿照这 8 步走。日常循环 0 条命令。橙色编号步骤是「AI 能力 → 场景-本地化」里的菜单按钮；提交 / 标签 / 推送用 Git 视图。
Localization Delta Flow · 1.0 → 1.1
Follow these 8 steps for every edit. Daily loop: 0 commands. Orange-numbered steps are menu buttons under "AI Capabilities → Scenario-Localization"; commit / tag / push use the Git view.
改中文稿，按 Ctrl+S 保存。
Edit Chinese source, press Ctrl+S to save.
看到 工作副本出现改动。
See changes appear in the working copy.
AI 能力 → 场景-本地化 → 标注变更节点。
AI Capabilities → Scenario-Localization → Mark Changed Nodes.
看到 报告列出「这次改了哪几句」。
See a report listing "which sentences changed this time".
勾选改动的文件 → 阶段选中 → 填一句话 → 提交。
Check changed files → Stage Selected → write a message → Commit.
看到 提交成功。
See commit succeeded.
AI 能力 → 场景-本地化 → 标记版本载体（填 1.1）→ 再提交一次。
AI Capabilities → Scenario-Localization → Mark Version Carrier (enter 1.1) → commit again.
看到 报告显示「改前 → 改后」。
See a report showing "before → after".
右键上面那次提交 → 创建标签，名字 release/CN-1.1，勾 推送标签。
Right-click the commit above → Create Tag, name release/CN-1.1, check Push Tag.
看到 中文标签已推送到远端。
See the Chinese tag pushed to remote.
选中改动的那一句 → AI 能力 → 场景-本地化 → 翻译增量片段。
Select the changed sentence → AI Capabilities → Scenario-Localization → Translate Incremental Segment.
看到 报告只给这一句的英文。
See the report gives English for that one sentence only.
AI 能力 → 场景-本地化 → 严格合并到英文镜像（先「预演」）。
AI Capabilities → Scenario-Localization → Strict Merge to English Mirror (dry-run first).
看到 报告写着「未改动的英文没有被碰过」。
See the report says "unchanged English was not touched".
AI 能力 → 场景-本地化 → 运行门禁。✅ 通过后：英文文件提交 → 创建标签 release/EN-1.1 → 推送。
AI Capabilities → Scenario-Localization → Run Gate. ✅ Passed: commit English file → create tag release/EN-1.1 → push.
看到 门禁结论与发布标签就位。
See the gate conclusion and release tag in place.
发布前打勾 · 5 条
Pre-release checklist · 5 items
- 中文提交过，版本号两处一样（第 4 步报告） Chinese committed, version numbers match in both places (step 4 report)
- 严格合并报告：未改动的英文没有被碰过 Strict merge report: unchanged English was not touched
- 运行门禁：✅ 检查通过 Run gate: ✅ Passed
- 英文那次提交只有 1 个文件、1 行新增（Git 历史点开看） English commit has only 1 file, 1 insertion (check in Git History)
- 两个标签同号并已推送：release/CN-1.1 ↔ release/EN-1.1 Both tags same number and pushed: release/CN-1.1 ↔ release/EN-1.1
遇到问题 · 速查
Troubleshooting · quick reference
检查 ❌
Check ❌
照报告里那条红字后面写的「怎么修」做一遍，再跑一次门禁。
Follow the "how to fix" note after the red text in the report, then run the gate again.
合并被拒绝
Merge rejected
英文对照稿被别人改过。先问发布负责人是否保留。
The English mirror was modified by someone else. Ask the release owner whether to keep it.
翻译还带中文 / 少一句
Translation still has Chinese / missing a sentence
再点一次；仍不行就把范围缩到那一句。
Click again; if it still fails, narrow the scope to that one sentence.
标签已存在
Tag already exists
显示标签 → 右键 → 删除标签，再重新创建。
Show Tags → right-click → Delete Tag, then create again.
一页看懂：中文改稿 → 英文对照稿
普通用户版 · 只动改过的那几句
① 你会用到的 2 样东西
② 第一次用（4 步）
- Oxygen 打开项目的 .xpr，再打开那张地图。
- 看左下的 Git 暂存：最上面的「工作副本:」就是你的项目目录。
- 点「获取」，再点「拉取」。
- 菜单「窗口 → 显示视图 → Git 历史」，确认那一行是 main。
③ 每次改稿（8 步）
- 改中文稿 → Ctrl+S 保存。
- AI 能力 → 场景-本地化 → 标注变更节点 → 报告列出「这次改了哪几句」。
- Git 暂存 → 阶段选中 → 填一句话 → 提交 → 看到「提交成功」。
- AI 能力 → 场景-本地化 → 标记版本载体（填 1.1）→ 再提交一次 → 报告显示「改前 → 改后」。
- Git 历史 → 右键上面那次提交 → 创建标签 → release/CN-1.1 → 勾选「推送标签」 → 标签出现在列表里。
- 选中改动的那一句 → AI 能力 → 场景-本地化 → 翻译增量片段 → 报告只给这一句的英文。
- AI 能力 → 场景-本地化 → 严格合并到英文镜像（先预演） → 报告写着「未改动的英文没有被碰过」。
- AI 能力 → 场景-本地化 → 运行门禁 → 通过后：英文文件提交 → 创建标签 release/EN-1.1 → 推送 → ✅ 检查通过；英文侧只多了那一句。
④ 发布前打勾（5 条）
- 中文提交过，版本号两处一样（第 4 步报告）
- 严格合并报告：未改动的英文没有被碰过
- 运行门禁：✅ 检查通过
- 英文那次提交只有 1 个文件、1 行新增（Git 历史点开看）
- 两个标签同号并已推送：release/CN-1.1 ↔ release/EN-1.1
⑤ 遇到问题（速查）
- 检查 ❌ → 照报告里那条红字后面写的「怎么修」做一遍，再跑一次门禁。
- 合并被拒绝 → 英文对照稿被别人改过：先问发布负责人是否保留。
- 翻译还带中文／少一句 → 再点一次；仍不行就把范围缩到那一句。
- 标签已存在 → 显示标签 → 右键 → 删除标签，再重新创建。