name: rnoh-docs-version-upgrade description: >- After React Native / RNOH releases, upgrade version numbers in docs/ Markdown files only (.md). Never modify package.json, json5, js, ts, or other non-md files. Sync zh-cn and en in pairs. Covers docs/zh-cn, docs/en, docs/Samples README*.md. Use for patch/major releases or bilingual doc sync.
RNOH 文档版本升级（全 docs 目录 · 中英文对齐）
RNOH / React Native Harmony 发布新版本后，用本 skill 将 docs/ 树中所有版本绑定内容升级到与代码仓 package.json 一致的版本，并保证 中文（docs/zh-cn）与英文（docs/en）成对对应。
范围：
docs/下所有.md文件（含zh-cn、en、Samples/**/README*.md）。
硬性要求：有英文对应路径的文件必须同一 PR 内中英成对改完；禁止只升中文。
文件类型边界（最高优先级）
本 skill 只修改 .md 文件，禁止改动任何其他类型文件。
| 允许 | 禁止 |
|---|---|
docs/**/*.md |
**/package.json、**/oh-package.json5 |
docs/Samples/**/README.md、README_zh.md |
**/hvigor-config.json5、hvigorfile.ts |
新建/删除 release note 的 .md |
**/*.js、**/*.ts、**/*.ets、**/*.cpp |
**/*.tgz、**/CMakeLists.txt、metro.config.js、babel.config.js |
|
docs/templates/** 下非 md 文件 |
|
docs/**/figures/** 图片 |
执行前：git diff --name-only 确认变更列表全部为 .md。
执行后：若 diff 出现非 md 文件，立即 revert，并在报告中说明。
工程依赖（
package.json等）由示例/模板维护者单独升级，不属于本 skill 职责。错误案例：commiteb08e4e7误改了docs/Samples/**/package.json、hvigor-config.json5。
目标
- 从仓库版本真源读取目标版本（禁止凭记忆写号）。
- 将文档中旧版本号统一替换为真源版本（见下方「版本替换矩阵」）。
- 按 P0→P1→P2 覆盖全部待改文件（见 version-doc-index.md）。
- 双语成对：每改一个中文文件，立即改 locale-map 中对应英文文件（见 bilingual-sync.md）。
- grep 扫描残留旧版本，输出变更报告（含双语缺口）。
版本真源（先读再写）
# 执行前先读取并记录
cat packages/react-native-harmony/package.json | rg '"version"|peerDependencies' -A1
cat packages/react-native-harmony-cli/package.json | rg '"version"'
cat package.json | rg '"react"'
| 变量 | 路径（只读，不修改） | 字段 |
|---|---|---|
RNOH_VERSION |
packages/react-native-harmony/package.json |
version |
RN_VERSION |
同上 | peerDependencies.react-native |
CLI_VERSION |
packages/react-native-harmony-cli/package.json |
version |
REACT_VERSION |
根 package.json |
react |
OLD_* |
文档中当前版本 | grep 得出，用于替换源 |
UPGRADE_TYPE |
— | patch（仅 PATCH 变）或 major（RN 大版本变） |
当前示例（以仓库为准，勿硬编码）：真源 RNOH 0.84.1 / RN 0.84.1 / CLI 0.84.1；文档依赖示例写 0.84.xx。
版本号写法（必守）
文档里版本号分两类，不要混用：
| 类型 | 格式 | 示例 | 适用场景 |
|---|---|---|---|
| 版本线占位符 | {MAJOR}.{MINOR}.xx |
0.84.xx |
依赖安装命令、JSON 示例、@react-native-oh/*@、@rnoh/*@、init --version、Samples README |
| 精确发版号 | {MAJOR}.{MINOR}.{PATCH} |
0.84.1 |
release note 文件名/表格、版本索引条目、发版说明正文 |
核心规则：升级文档时，依赖/安装/示例代码中的版本号写成 0.84.xx，不要写成 0.84.1 等具体 patch 号。
真源 0.84.1 ──→ release note / 版本索引：写 0.84.1（精确）
──→ 环境搭建、编译指南、Samples README 等：写 0.84.xx（占位符）
- patch 升级（0.84.0→0.84.1）：更新 release note、版本索引；依赖示例保持
0.84.xx，勿改成0.84.1。 - major 升级（0.82→0.84）：依赖示例中
0.82.xx→0.84.xx（含docs/Samples/**/README*.md，中英文同步）。
版本替换矩阵
升级时将 OLD_* 替换为目标写法。成对文件中替换结果必须相同。
| 文档区域 | 写法 | 双语 |
|---|---|---|
| 版本索引 | 精确号 RNOH v0.84.1 (日期) 及链接 |
zh + en |
| Release note | 精确号：文首 RN、表格 RNOH/CLI | zh + en 各一份 |
| 环境搭建 | 0.84.xx：init --version、package.json 示例、@react-native/* |
zh + en |
| SDK 配置指导 | 版本线占位符或「RNOH 0.84.xx」类表述 | zh + en |
| 版本升级指导 | 示例 JSON 用 0.84.xx；历史「A→B」章节保留精确旧号 |
zh + en |
| Codegen / TurboModule / 编译构建 | 依赖示例 0.84.xx |
zh + en |
| roadmap | 版本状态（已发布 / 进行中） | zh + en |
| 共建指南 | 适用版本列表 v0.84 等 |
zh + en |
docs/Samples/**/README*.md |
依赖安装 @0.84.xx；大版本线变更时 0.82.xx→0.84.xx |
README + README_zh 一致 |
允许保留旧号：升级指导中历史迁移 JSON（如 0.82→0.84）、稳定性历史修复条目、规格 FAQ 中的历史说明。
升级类型
| 类型 | 条件 | 文档工作量 |
|---|---|---|
| patch | 仅 PATCH 变，如 0.84.0→0.84.1 | release notes、版本索引（精确号）；依赖示例仍用 0.84.xx |
| major | RN 大版本变，如 0.82.x→0.84.x | 上述 + 依赖示例 0.82.xx→0.84.xx（含 Samples）、升级指导新章节 |
大版本路径参考：docs/zh-cn/05-运维/版本升级指导.md ↔ docs/en/05-operations/version-upgrade-guide.md。
工作流程
1. 建立清单
文档版本升级进度：
- [ ] 读取版本真源，记录 RNOH / RN / CLI / REACT / OLD_*
- [ ] 判定 patch / major
- [ ] P0 成对（zh-cn + en）：版本索引、release notes、环境搭建、SDK
- [ ] P1 成对：升级指导、Codegen、TurboModule、roadmap、Samples README*.md
- [ ] 确认 diff 中**仅有 `.md` 文件**
- [ ] P2 grep 残留（docs/ 全目录）
- [ ] 双语验证（bilingual-sync 检查项）
- [ ] 输出报告
2. P0 — 每次发布必改（中英成对）
对 locale-map.md 中每一行，同时打开 zh / en 文件修改：
| 要点 | zh-cn | en |
|---|---|---|
| 版本索引 | 05-运维/版本说明.md |
05-operations/release-notes-overview.md |
| Release note | 05-运维/release-notes/react-native-harmony-v{RNOH}.md |
en/05-operations/release-notes/ 同文件名 |
| 环境搭建 | 02-开发/01-环境与工具/环境搭建.md |
02-development/01-environment-and-tools/environment-setup.md |
| SDK | 02-开发/01-环境与工具/SDK版本配置指导.md |
01-environment-and-tools/SDK version configuration guide.md |
patch 发版：
- 中英文各新建
react-native-harmony-v{新版本}.md - 中英文各删除被取代的旧 patch 文件（如
v0.84.0.md） - 版本索引两侧增最新条、链到新文件
release note 双语：章节结构、表格行、变更条目数量与语义一致（详见 bilingual-sync.md）。
3. P1 — 强烈建议（中英成对）
按 locale-map 逐对处理：
- 版本升级指导 ↔
version-upgrade-guide.md RN-JS打包.md↔rn-js-bundle.mdhvigorfile配置.md↔hvigorfile-configuration.mdCodegen.md、TurboModule.md、编译构建指南roadmap.md（中英文）开发者文档共建指南.md↔documentation-contribution-guide.mdzh-cn/README.md↔en/README.mddocs/Samples/**/README.md+README_zh.md（仅显式版本号，不改同目录工程文件）
仅中文（改中文 + 报告标注英文缺口）：RN应用鸿蒙化开发指南.md、RN升级需要开发者适配整理.md。
完整列表：version-doc-index.md。
docs/Samples（README*.md，写法同主文档）
docs/Samples/**/README*.md 与主文档使用相同规则：依赖安装写 0.84.xx，禁止写成 0.84.1。
| 场景 | 做法 |
|---|---|
| patch 升级 | 若已是 0.84.xx，无需改 Samples |
| major 升级 | 0.82.xx → 0.84.xx，中英文 README 同步 |
| 误改纠正 | 若被改成 0.84.1，改回 0.84.xx |
4. P2 — grep 驱动
在 docs/ 下仅扫描 .md 文件，将 {OLD} 换为实际上一版本：
rg "{OLD_RNOH}" docs/ -g "*.md"
rg "{OLD_RN}" docs/zh-cn docs/en -g "*.md"
rg "react-native[\"']:\s*[\"']{OLD_RN}" docs/zh-cn docs/en -g "*.md"
rg "placeholder:\s*[\"']0\.\d+" docs/ -g "*.md"
rg "WARNING.*RNOH 0\.(72|77|82)" docs/en -g "*.md"
允许保留：历史稳定性修复、升级指导「从 A 到 B」JSON、规格 FAQ 历史条目。
5. 大版本额外项
- 升级指导新增「A→B」章 + upgrade-helper 链接（中英各一份）
上游社区不兼容变更.md↔upstream-community-incompatible-changes.md追加行- 新建
0.XX稳定性修复汇总/（有修复时） - 删除占位 release-notes（
[RN_VERSION]模板） getting-started.md与environment-setup.md版本一致
6. 验证（含双语）
-
版本说明.md/release-notes-overview.md最新条 =RNOH_VERSION - 环境搭建 / environment-setup 依赖示例为
0.84.xx，非0.84.1 - release note 中英文表格版本、变更条目数一致（release note 内用精确号）
- 无过时
release-notes/react-native-harmony-v{旧patch}.md（中英两侧均无） - locale-map 全部 P0/P1 成对文件已改或标注缺口
-
docs/Samples/**/README*.md依赖示例为0.84.xx（大版本升级时已同步） - 依赖示例中无误写的具体 patch 号（如
@0.84.1） -
git diff --name-only全部为.md文件（无 package.json / json5 / js 等） - 相对链接未断
双语验证细节见 bilingual-sync.md。
输出格式（默认中文）
# docs 版本升级报告
## 版本信息
- 类型：patch | major
- RNOH / RN / CLI / React：…（真源路径）
- 替换：{OLD_RNOH} → {RNOH_VERSION}，…
## P0 成对（zh ✓ / en ✓）
| 中文路径 | 英文路径 | 状态 | 要点 |
## P1 / P2
| 路径 | 语言 | 状态 | 要点 |
## 双语缺口
| 中文 | 英文 | 说明 |
## grep 残留
| 文件:行 | 匹配 | 建议 |
## 后续动作
- [ ] …
与用户协作
- 只问「改哪些」：输出 P0/P1 成对清单 + grep 命令 + locale-map。
- 给目标版本：以
package.json真源为准，与用户输入不一致时说明并以仓库为准。 - 要求直接改：仅改
.md文件，按 locale-map 成对 P0→P1→P2 编辑，禁止只改中文；附 diff 摘要（确认无非 md 文件）与双语验证结果。
参考
- 双语同步规则：references/bilingual-sync.md
- 文件分级与正则：references/version-doc-index.md
- 中英文路径对照：references/locale-map.md