• 具身智能
• 机器人
• 人工智能
• 大模型
• 模型推理服务
• 本地部署
• 计算机视觉
• ROS

本文以 openEuler IB_Robot 仓库自带的 Agent 技能.agents/skills/deepwiki-translator/SKILL.md为骨架，完整解析如何将 DeepWiki 导出的英文 Markdown 端到端转换为可交付的中文文档。这套"配置优先（config-first）"流水线涵盖全量/增量翻译、目录与索引构建、链接与锚点校验，是 IB-Robot 社区把docs/migration下的英文文档体系本地化为ib_robot_zh中文站的核心工具链。读完本文，你将掌握从拆分原始 Markdown、本地化doc_config.json、逐页翻译，到生成 Sphinx 可消费文档并完成三层链接防护的完整实操能力。

技能定位与适用场景

deepwiki-translator是 IB-Robot 仓库.agents/skills/技能库中的一个文档类技能（技能清单见 .agents/skills/README.md）。它的使命是：使用现有doc_config.jsonschema，将 DeepWiki 生成的英文 Markdown 翻译为中文，并保证翻译产物能被deepwiki_processor.py的标题匹配逻辑正确消费。

按 SKILL.md 的定义，以下场景应当调用本技能：

• 需要从零开始将所有英文raw_md/*.md翻译为中文raw_md_zh/*.md（全量翻译）；
• 已翻译部分页面，只需翻译新增或修改的页面（增量翻译）；
• 希望中文页面标题生效，但不重构doc_config.jsonschema；
• 希望翻译后的 Markdown 兼容deepwiki_processor.py的标题匹配逻辑；
• 需要检查翻译后的链接、H1、配置一致性、Mermaid 图、代码块或 Sphinx 输出。

在 IB-Robot 中，该技能承接docs/migration/README.md定义的文档迁移流程的翻译与生成环节，其上游是deepwiki-config技能（生成doc_config.json），下游是doc-link-validator（链接体检）与mermaid-syntax-validation（Mermaid 图验证）。

输入参数总览

技能通过参数表定义了一次翻译任务的全部输入，默认值以当前工作目录为基准：

技能内部采用"渐进式披露"组织：每个执行步骤都指向对应的 reference 文档，仅读取当前步骤所需的内容：

这些 references 不对外暴露为独立技能，仅供翻译流水线内部消费。

核心设计原则：配置优先（Config-First）

整套流水线最关键的约束是不改变配置 schema。本地化后的配置仍然只保留doc_config.json原有的三个顶层字段：

{ "id_to_label": {}, "title_to_label": {}, "hierarchy": {} }

在此基础上，只翻译标题字符串：

• 将title_to_label的 key 从英文翻译为中文；
• 将每个hierarchy.*.title的值从英文翻译为中文；
• 将每个hierarchy.*.subs的值从英文翻译为中文；
• id_to_label所有条目必须原样保留；
• 所有 label 值必须原样保留；
• 所有 hierarchy key、目录名和 Markdown 文件名必须原样保留。

这样做的根本原因，从 deepwiki_config.py 的load_config可以看到，处理器读取配置时直接解构id_to_label、title_to_label、hierarchy三个字段；deepwiki_processor.py原本就要求title_to_label与hierarchy中的标题和输入 Markdown 的 H1 完全一致——配置是页面标题的唯一事实来源，翻译流程不得自行发挥生成 H1。

目录 Overview 标题后缀规则

当hierarchy条目包含subs字段（即该条目是目录 overview 页面）时，翻译后的title必须以**"概述"结尾**。这是为了避免 overview 页面与其所属章节同名。例如英文标题 "Getting Started"，中文标题应为"入门指南概述"而不是"入门指南"。叶子页面（不含subs的条目）不加"概述"后缀。

config-localization.md给出了完整的本地化前后对照示例。英文源配置：

{ "id_to_label": { "1": "getting_started", "1.1": "environment_setup" }, "title_to_label": { "Getting Started": "getting_started", "Environment Setup": "environment_setup" }, "hierarchy": { "getting_started": { "title": "Getting Started", "subs": { "environment_setup.md": "Environment Setup" } } } }

中文目标配置（注意目录 overview 标题加了"概述"后缀）：

{ "id_to_label": { "1": "getting_started", "1.1": "environment_setup" }, "title_to_label": { "入门指南概述": "getting_started", "环境配置": "environment_setup" }, "hierarchy": { "getting_started": { "title": "入门指南概述", "subs": { "environment_setup.md": "环境配置" } } } }

值得一提的是，生成阶段 deepwiki_generator.py 在写目录index.rst时会执行display_title = main_title.replace("概述", "").strip()，把"概述"后缀去掉作为目录显示标题，与上述规则形成闭环。

上游配套：doc_config.json 从何而来

deepwiki-translator是配置的消费者，配置的生产者是同技能库中的deepwiki-config（见 .agents/skills/deepwiki-config/SKILL.md）。理解 label 的生成规则有助于把握翻译时哪些字符串绝不可动。

deepwiki-config通过generate_config.py将 DeepWiki MCPread_wiki_structure返回的页面列表（每行如- 2.1 Environment Setup）解析为三段式配置。其 label 生成规则（见 references/script-design.md 与 scripts/generate_config.py）：

1. 去除标题中的(xxx)括号内容，如Configuration System (robot_config)→Configuration System；
2. slug 化：转小写 → 去除虚词（and/or/of/the/for/with/a/an/in/on/to）→ 非字母数字字符替换为单个下划线 → 去首尾下划线 → 合并连续下划线。

实际示例：Getting Started→getting_started，5DOF Kinematic Constraints→5dof_kinematic_constraints，Camera Tools (Alignment and ISP Calibration)→camera_tools。不同页面生成相同 label 时后到者追加_2、_3数字后缀；更新场景下已存在的 label 会被复用而不重新生成，以保护历史链接。

generate_config.py写入前还会做三向一致性校验（6a：id_to_label↔title_to_label；6b：id_to_label↔hierarchy的 label 集合；6c：title_to_label↔hierarchy的标题集合），任一失败即退出码1且不写文件。仓库中已经生成的成品配置见 docs/migration/doc_config.json，其hierarchy覆盖 18 个一级章节（overview、getting_started、core_concepts、architecture、configuration、protocol、inference、action_dispatch、data_pipeline、motion_planning、hardware、extended_capabilities、package_reference、development、embodied_intelligence_stack、perception_manipulation_services、model_export_toolchains、glossary），并采用混合模式——无子页面的一级章节为叶子节点<label>.md，有子页面的一级章节为目录节点<label>（其subs为子页面映射），目录节点自身的 label 在输出阶段映射为<label>/overview.md。

六步执行流程详解

SKILL.md 声明：本技能唯一权威流程在自身执行流程章节，scripts/下的deepwiki_config/deepwiki_generator/deepwiki_links/deepwiki_pages为内部模块（无 CLI，仅被命令行脚本导入，不可独立执行）。命令中的<skill_dir>指技能目录（scripts/、references/的父目录），执行时替换为实际路径。

第 1 步 — 拆分原始 Markdown

DeepWiki 导出的原始文件把所有页面打包在一个大文件里，页面以# Page: <Title>分隔。运行拆分脚本将其切分为扁平页面文件：

python -X utf8 <skill_dir>/scripts/split_md.py <raw_md_file> <source_dir>

从 split_md.py 源码看，split_raw_md会先清空重建输出目录，用re.split(r"# Page: ", content)切分页面，文件名由标题 slug 生成（_slugify：去除标点、空格替换为下划线、转小写），并自动补全每个页面的 H1 标题。脚本默认输入为docs/migration/IB_Robot_doc_raw.md、输出为docs/migration/raw_md，与迁移 README 记录的目录约定一致（docs/migration/README.md）。

第 2 步 — 本地化配置与构建映射

执行本步前必须完整阅读 references/config-localization.md。按其要求生成同 schema 的target_config并完成校验（增量模式下已存在则直接复用，跳过生成与校验）；随后从target_config.hierarchy构建"文件名 -> 中文 H1"映射。

本地化配置的校验清单共 6 项，任一失败必须停止并报告具体不一致项，不得基于错误配置翻译页面：

1. id_to_label中的 label 集合未变化；
2. title_to_label中的 label 集合与id_to_label中的 label 集合一致；
3. hierarchykey 与subskey 推导出的 label 集合与id_to_label中的 label 集合一致；
4. 每个hierarchy.title和hierarchy.subs标题都存在于title_to_label，并映射到相同 label；
5. 中文标题不能为空；
6. 中文标题不能重复。

映射构建规则：叶子页面"overview.md": {"title": "IB-Robot 概述"}映射overview.md->IB-Robot 概述；目录 overview"getting_started": {"title": "入门指南概述"}映射源文件getting_started.md->入门指南概述（目录 overview 标题必须带"概述"后缀）；子页面"environment_setup.md": "环境配置"映射environment_setup.md->环境配置。注意：目录 overview 的源文件仍然是 flat raw markdown 中按 label 命名的文件，如getting_started.md；后续生成时才变成getting_started/overview.md。

第 3 步 — 确定翻译范围

按mode选择翻译范围，文件判定逻辑仅在此定义。

全量翻译（mode=full）：从零翻译所有页面。适用场景包括新启动翻译项目、源内容变化较大需要完全重新翻译、用户明确要求全量重翻。翻译范围是source_dir中每一个.md文件。

增量翻译（mode=incremental）：仅翻译新增或修改的页面，保留已有翻译。先用 Glob 分别列出source_dir和target_dir中的.md文件，再按下表逐文件判定：

一个关键约束：增量只减少待翻译文件，不缩小后续步骤范围——第 5 步始终读取整个target_dir（旧译文 + 新译文）重新生成并整体重建output_dir，第 5-6 步的输出检查与锚点校验始终覆盖整个output_dir。

第 4 步 — 逐文件翻译

禁止编写脚本执行翻译，LLM 本身就是翻译引擎，Read → 翻译 → Write 循环在对话中逐文件执行。本步同时适用于全量和增量模式。

执行本步前必须完整阅读 references/content-protection.md。对每个待翻译文件：

1. 根据文件名从映射中找到对应中文 H1（缺失时停止并报告，不得编造）；
2. 使用 Read 工具从source_dir完整读取源 Markdown；
3. 按 content-protection 的规则翻译为简洁技术中文，保持 Markdown 结构；
4. 将第一个 H1 替换为# <target_config 中的中文标题>；
5. 使用 Write 工具以相同文件名和 UTF-8 编码写入target_dir。

**内容保护规则（不得翻译或改写）**包括：Markdown 链接目标text中的target；图片目标alt中的target；文件路径、目录名、文件名、anchor、URL、源码行号引用；空链接源码引用文本（如[scripts/setup.sh:1-62]()）；反引号包裹的行内代码；围栏代码块内容和代码块语言标记；Mermaid 图全部内容（图语法、节点 ID、连线操作符、subgraph ID、展示标签、节点文本及所有标记）；HTML 标签和属性；RST 指令和选项；产品名、包名、命令、API、类名、函数名、topic、action、参数名和环境变量名。

可安全翻译的内容包括：段落正文、非 H1 标题、链接目标非空且保持不变时的链接显示文本、表格中的自然语言单元格（代码/路径单元格保持原样）。

全站术语保持一致（content-protection.md术语表）：inference 推理、deployment 部署、teleoperation 遥操作、dataset 数据集、pipeline 流水线、action dispatch 动作分发、motion planning 运动规划、configuration 配置、validation 验证、submodule 子模块、workspace 工作空间。除非用户明确要求，IB-Robot、LeRobot、ROS 2、MoveIt、openEuler、OpenHarmony、AtomGit、Hugging Face、Conda、venv、colcon、rosdep等专有名词不翻译。

链接安全分析：只要 label 和文件名保持不变，配置优先流程可以保持链接稳定。高风险错误包括翻译environment_setup这类 label 值、翻译 hierarchy key 或subs文件名、翻译链接目标/anchor/源码引用/仓库路径、页面 H1 与本地化配置标题不一致、title_to_label出现重复中文标题、翻译 Mermaid 图任何部分。安全做法是只翻译配置中的标题字符串、页面 H1 直接复制本地化配置标题、可翻译普通链接显示文本但保留 target、文件名和输出路径继续使用英文 slug。

第 5 步 — 生成中文文档并检查输出

执行本步前必须完整阅读 references/output-pipeline.md。按命令生成中文文档（输出目录会被重建，先清空）：

python -X utf8 <skill_dir>/scripts/deepwiki_processor.py --input-dir <target_dir> --output-dir <output_dir> --config-file <target_config> --branch <branch>

--source-config-file <source_config>（可选）：源语言配置，作为链接解析的标题别名表，用于解析译文中残留的英文标题链接。若源配置与target_config同目录且名为doc_config.json，可省略（脚本自动发现）；否则建议显式传入。

迁移目录中实际使用的命令（见 docs/migration/README.md）：

python .agents/skills/deepwiki-translator/scripts/deepwiki_processor.py \ --input-dir docs/migration/raw_md_zh \ --output-dir docs/migration/ib_robot_zh \ --config-file docs/migration/doc_config_zh.json \ --branch master

源配置docs/migration/doc_config.json与目标配置同目录，满足自动发现条件，无需显式传--source-config-file。

生成后按「验证清单」逐项检查，汇总全部失败项后统一修复源（raw_md_zh或target_config）再重新生成并完整重检：

1. 每个配置标题都作为且只作为一个译文 Markdown 文件的第一个 H1 出现；
2. 每个译文 Markdown 文件都被hierarchy使用；
3. deepwiki_processor.py不输出Configured title missing from inputwarning；
4. deepwiki_processor.py不输出Input page not used by hierarchywarning；
5. 围栏代码块数量与英文源文件一致；
6. 在处理器转换前，Markdown 链接目标和图片目标与英文源文件一致；
7. link_conversions.json中的转换符合预期，没有被翻译过的路径或 URL；
8. 抽查链接显示文字：URL 与锚点不变，仅显示文本可翻译（对照英文源判断）；
9. 生成的index.rsttoctree 条目指向实际存在的生成文件。

失败处置规则：Configured title missing from input（译文 H1 与配置标题不一致）时对照第 2 步构建的映射判断哪边错——译文 H1 写错则改raw_md_zh的 H1，配置标题译错则改target_config的标题；Input page not used by hierarchy时核对hierarchy与该文件名，三选一处理（补充 hierarchy 条目 / 删除多余译文文件须经用户确认 / 纠正文件名）；保真失败（围栏代码块数量不符、路径或 URL 被翻译、链接显示文字的 URL 变了）则修raw_md_zh对应内容。

已知坑——UTF-8 BOM：带 BOM 的源文件会让首行 H1 解析失败（表现为Configured title missing from input）。读写统一用utf-8-sig（verify_anchors.py已内置；临时排查脚本也须如此）。这一约定在 deepwiki_pages.py 的load_pages中可以看到实际体现——它用encoding='utf-8-sig'读取每个译文文件。

第 6 步 — 锚点与链接校验

运行校验脚本对生成结果做锚点与相对链接全量校验，并检查link_conversions.json中的(dangling anchor)条目；退出码 0 且无该类条目为干净：

python -X utf8 <skill_dir>/scripts/verify_anchors.py --output-dir <output_dir>

从 verify_anchors.py 源码看，它逐行扫描生成目录下所有 Markdown 文件（忽略围栏代码块，不检查外部http(s)链接），检查四类问题：

1. 数字页面 ID 锚点（如#16.1）不应在生成结果中存活——它们必须被处理器转换为相对链接；
2. 页内锚点（#section）必须能匹配本文件某个标题的 GitHub 风格 slug；
3. 相对链接（./x.md、../y/x.md）的目标文件必须存在；
4. 带锚点后缀的相对 Markdown 链接的锚点必须能匹配目标文件的标题 slug。

退出码0表示干净，1存在问题，2参数错误。出现任一问题时必须完整阅读 references/link-repair.md，按「链接修复循环」处理。

源码级原理：处理器与生成器的工作方式

deepwiki_processor.py：CLI 入口与默认值

deepwiki_processor.py 是流水线的命令行入口，参数默认值如下：

• --input-dir默认raw_md/（当前工作目录下）；
• --output-dir默认ib_robot/；
• --branch默认master（用于拼接 AtomGit 仓库 URL）；
• --config-file默认doc_config.json；
• --source-config-file默认None，但当--config-file所在目录存在doc_config.json且与自身不同名时，会自动发现并补全（见 deepwiki_processor.py）。

处理器初始化时依次调用load_config、merged_title_to_label（合并源配置标题作为空链接解析的别名表）、label_to_title、build_label_to_filepath，随后调用run_generation。它收集的warnings与link_conversions在生成结束时统一输出。

deepwiki_generator.py：重建输出目录与索引构建

deepwiki_generator.py 的run_generation是生成核心，其关键行为：

• reset_output_dir会先清空再重建output_dir（因此输出目录每次生成都是全量重建）；
• base_url固定为https://atomgit.com/openeuler/IB_Robot/<branch>/，用于把仓库裸路径链接转换为 AtomGit URL；
• 对每个 hierarchy 条目分派generate_leaf_page（无subs）或generate_directory_section（有subs）；
• 目录节点生成<label>/overview.md（其内容源是 flat raw markdown 中同 label 的文件）并生成index.rst，toctree 条目为overview加各子页面 stem；
• 最后生成主index.rst，含.. _ib_robot_intro:锚点与 "IB-Robot 具身智能套件" 标题，以及.. toctree::目录树。

每页内容先经clean_content归一化（补齐/去重 H1、去尾随空行与---/***/___分隔线），再经fix_links做链接转换。

链接转换与三层防护

deepwiki_links.py 的fix_links是链接转换的实现，其内部流程值得关注：

• 先用protect_blocks把围栏代码块整体替换为占位符，防止链接改写误伤代码；
• 对#数字形式的页面 ID 锚点，通过resolve_page_link结合id_to_label→label→label_to_filepath解析为输出相对路径；
• 非数字页内锚点对本地标题 slug（extract_heading_slugs，GitHub 风格，重复标题带-1后缀）做匹配，不匹配则 warning + 在link_conversions中记录(dangling anchor)；
• 空链接文本（[path.py:12-34]()这类源码引用或裸仓库路径）转换为带#L12-L34行号锚点的 AtomGit URL；
• 所有转换结果写入link_conversions.json报告（report_link_conversions将其写到output_dir.parent / "reports"目录）。

三层防护一览：

第 2、3 层配合工作：第 2 层在生成日志中即时暴露问题链接所在文件，第 3 层保证交付前全绿（退出码 0）。

链接修复循环（复用流程）

发现链接或锚点问题时的标准处理顺序，核心原则是只改源（raw_md_zh或target_config），改完重新生成，禁止手工修补生成结果：

1. 定位：从verify_anchors.py输出或link_conversions.json的(dangling anchor)条目找到问题链接所在文件与行号；
2. 诊断源文件：打开raw_md_zh中对应源文件，确认链接属于哪类问题；
3. 修源：在raw_md_zh中改链接；若问题源于标题翻译改写了锚点，则恢复锚点或对应标题；
4. 重新生成（初生成时若显式传入过--source-config-file，重跑同样传入）：重跑deepwiki_processor.py；
5. 全量校验：重跑verify_anchors.py，退出码非 0 时回到第 1 步；
6. 比对（可选）：git diff --no-index --ignore-cr-at-eol <旧输出> <新输出>确认重新生成未引入意外差异；
7. 保真复检：链接批量修改后，按验证清单中的保真项复检（围栏代码块数量、link_conversions.jsonConverted 字段无路径或 URL 被翻译、抽查链接显示文字 URL 不变）。

源链接形态规范（raw_md_zh中）：

判别方法：目标文件的 H1 出现在target_config的hierarchy中即为 wiki 页面；否则是仓库文件链接，保持裸路径。

已知坑：批量改写链接时必须先保护围栏代码块（```分隔），否则示例中的链接文本会被改坏；根级页面映射后位于输出根目录，子目录页指向它用../architecture.md是正确形态，不要"修复"成./architecture.md；直接编辑生成结果会造成与重新生成输出不一致（历史交付中曾残留过 3 处手工修补与 regen 不一致的行）。

输出摘要与可交付物

翻译完成后，技能要求向用户输出以下摘要：

• 使用的翻译模式（全量或增量）与本地化配置路径（新建或复用）；
• 翻译的配置标题数量、翻译的 Markdown 文件数量（增量模式含跳过的文件数）；
• 缺少配置映射的源文件、空标题或重复标题情况；
• output-pipeline.md「验证清单」检查结果（如有失败项）；
• verify_anchors.py校验结果（扫描文件数、问题数）；
• 生成目录和链接转换报告路径。

生成产物的标准可交付物包括：层级化 Markdown 文档目录（含各目录的overview.md与index.rst、主index.rst）、reports/link_conversions.json链接转换报告、生成阶段的 warning 汇总。

约束清单

流程末尾明确列出的硬性约束，翻译与生成环节都必须遵守：

• 本流程不向doc_config.json添加新字段；
• 不修改 label、文件名、hierarchy key 或id_to_label；
• 不翻译代码、命令、包名、API 名、文件路径、URL、anchor 或 Mermaid 图的任何内容（包括展示标签和节点文本）；
• 不以生成后的ib_robot/作为主要翻译源；
• 不手工修改生成结果；应修复target_config或raw_md_zh后重新生成；
• 禁止编写脚本执行翻译（翻译引擎是 LLM 本身）。

在 IB-Robot 仓库中的落地与下游链路

deepwiki-translator不是孤立脚本，它位于 docs/migration/README.md 定义的完整文档迁移流水线中部。推荐顺序为：deepwiki-config（生成/更新doc_config.json）→deepwiki-translator（拆分、config-first 翻译、生成、锚点校验）→doc-link-validator（链接体检）→mermaid-syntax-validation（Mermaid 语法检查与渲染验证）。

其中链接体检由 .agents/skills/doc-link-validator/SKILL.md 承担：link_validator.py对文档树做只读体检，本地相对链接查文件与锚点存在性、外部 URL 发真实 HTTP 请求、AtomGit 链接通过官方 CLI 逐类验证存在性，输出状态分valid/broken/auth_error/error/inconclusive五类，其中broken是确定缺陷必须修复，inconclusive是"没法确认"，两者必须区分对待。运行前需执行gitcode auth login --hostname atomgit.com --with-token完成认证。

Mermaid 图验证由 .agents/skills/mermaid-syntax-validation/SKILL.md 承担，遵循"诊断 → 预览 → 修复 → 复验 → 构建 → 浏览器验证"的完整闭环：context_check.py做 5 项必做上下文检查、parse_check.mjs用真实 Mermaid 解析器定位失败块、fix_labels.py仅做语法级修复（不改变图含义、节点文本、边含义、顺序或周边正文）、html_scan.py扫描生成 HTML 中的错误文本与 CDN 依赖。

总结

IB-Robot 的deepwiki-translator技能为 DeepWiki 英文文档的中文化提供了一套工程化程度很高的标准流水线：以doc_config.json为单一事实来源，通过"只翻译标题字符串、绝不触碰 label 与文件名"的强约束保证配置与页面标题的可机械校验一致性；六步流程（拆分 → 本地化配置 → 定范围 → 逐页翻译 → 生成 → 校验）职责分明，每步都有配套 reference 与脚本支撑；三层链接防护从生成期到交付期全程拦截悬空锚点与失效链接。配合上游deepwiki-config与下游doc-link-validator、mermaid-syntax-validation，构成了 IB-Robot 文档体系从英文 DeepWiki 到可交付中文站点的完整闭环。对于希望将 DeepWiki 文档汉化落地为高质量中文技术站的团队，这套技能目录（scripts/与references/可独立携带）本身就是一份可直接复用的参考实现。

• 具身智能
• 机器人
• 人工智能
• 大模型
• 模型推理服务
• 本地部署
• 计算机视觉
• ROS