# Update Docs Pr

> After publishing a new @opentiny/genui-sdk package, update opentiny/docs (submodule, genui package versions, VitePress sidebar) and opentiny/opentiny.design (submodule commit only), then open PRs on branch deploy/update-genui-{version}. Use when the user asks to 更新文档工程 or 更新官网工程 or sync docs, update opentiny/docs or opentiny.design, or create deploy PRs after a genui-sdk release.

- Skill: `opentiny/update-docs-pr` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add opentiny/update-docs-pr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opentiny/update-docs-pr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: opentiny (https://skillmd.com/u/opentiny)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opentiny/update-docs-pr

---


# Update docs & opentiny.design PRs

发布 genui-sdk 新版本后，更新以下仓库并自动提 PR：

- [opentiny/docs](https://github.com/opentiny/docs)：submodule + 版本 + 侧栏 → 详见 [docs.md](docs.md)
- [opentiny/opentiny.design](https://github.com/opentiny/opentiny.design)：仅 submodule → 详见 [design.md](design.md)
- 提 PR 后触发 Pages 部署并打开预览 → 详见 [deploy.md](deploy.md)

**不要 clone 整仓。** 一律用 `gh api`。**禁止 force-push**；后续修改在分支上追加 commit。

## 前置检查

1. **依赖**：需要 `gh`（GitHub CLI）、`jq`（解析 API 输出）、`npm`（docs 查 npm 最新版本用）。先检查：
   ```bash
   command -v gh >/dev/null || { echo "gh 未安装，请先安装：brew install gh" >&2; exit 1; }
   command -v jq >/dev/null || { echo "jq 未安装，请先安装：brew install jq" >&2; exit 1; }
   command -v npm >/dev/null || { echo "npm 未安装，请先安装 Node.js（含 npm）" >&2; exit 1; }
   ```
   缺失时给安装指引（macOS：`brew install gh jq`；npm 随 Node.js 一起安装），**不要**当作未登录去提示 `gh auth login`。
2. **版本号**：用户提供（如 `1.3.0` / `v1.3.0`），去前导 `v`；须为非空 semver（含预发布/构建号），非法值直接退出。`opentiny.design` 不写版本，只共用 `COMMIT`。
3. **鉴权**：`gh auth status`；未登录则提示 `gh auth login` 或提供对两仓有写权限的 token。

```text
COMMIT = 用户指定，否则 opentiny/genui-sdk 远程 main tip
BRANCH = deploy/update-genui-{version}
基线分支（两仓）= dev
```

## 工作流

```text
进度：
- [ ] 1. 确定 version 与 COMMIT
- [ ] 2. 更新 opentiny/docs 并提 PR        → docs.md
- [ ] 3. 更新 opentiny/opentiny.design 并提 PR → design.md
- [ ] 4. 触发 Pages 部署，成功后打开预览   → deploy.md
- [ ] 5. 回报 PR URL、run URL、预览 URL
```

### Step 1：确定 version 与 COMMIT

```bash
version="${version#v}"
if [ -z "${version}" ] || ! [[ "${version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
  echo "version required (semver, e.g. 1.3.0)" >&2
  exit 1
fi

if [ -n "${USER_COMMIT}" ]; then
  COMMIT="${USER_COMMIT}"
else
  COMMIT=$(gh api repos/opentiny/genui-sdk/git/ref/heads/main --jq .object.sha) || {
    echo "获取 genui-sdk main tip 失败，请检查网络与鉴权" >&2
    exit 1
  }
fi
if ! [[ "${COMMIT}" =~ ^[0-9a-fA-F]{40}$ ]]; then
  echo "COMMIT 无效：需为 40 位 hex SHA，当前为 ${COMMIT}" >&2
  exit 1
fi
BRANCH="deploy/update-genui-${version}"
```

- `version`：用户输入并去前导 `v`；用于分支名与 PR 文案；docs 里各 genui 依赖分别取各自 npm 最新正式版（见 docs.md）
- `COMMIT`：优先用户指定；否则 `main` tip；**两仓共用**；解析失败或非 40 位 hex SHA 直接退出；勿再用 tag 覆盖用户指定的 commit

### Step 2–4

按顺序执行并阅读对应文件中的命令与规则：

1. [docs.md](docs.md)
2. [design.md](design.md)
3. [deploy.md](deploy.md)

### Step 5：回报

返回 docs / design 的 PR URL、部署 run URL，以及：

- https://opentiny.github.io/docs/genui-sdk/
- https://opentiny.github.io/opentiny.design/

一仓失败时尽量完成另一仓，并说明原因。

## 常见问题

| 情况 | 处理 |
|------|------|
| gh / jq / npm 未安装 | 按前置检查安装（macOS：`brew install gh jq`；npm 随 Node.js），**不要**当作未登录 |
| 未登录 / 无权限 | `gh auth login` 或提供覆盖两仓的 token |
| 分支已存在 / 改 PR | 以分支 tip 为 parent 追加 commit，无 force PATCH |
| 用户指定了 commit | 两仓都用该 commit |
| docs 无侧栏变更 | 跳过 config.mts |
| design | 只动 `genui-sdk` gitlink |
| 部署失败 | 回报 run URL，不要打开过期预览 |
| 打不开浏览器 | 把预览 URL 发给用户 |