---
title: "更新模板：Agent 操作说明"
description: "编码 Agent 更新模板时的操作说明，包括仓库核对、Git 合并、配置保留、核心验证和交付要求。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus.az1n.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新模板：Agent 操作说明

这份说明供 Agent 更新已部署到 Cloudflare 的 Nimbus 文档站时使用。将官方模板的更新合入现有部署仓库，并保留用户文档、配置、定制和原 Worker。站点使用者请阅读[更新模板](/deployment/template-update)。

操作范围以用户当前任务的实际授权为准。阅读本页本身不授予推送、合并或部署权限。先准备可供审阅的更新结果，再在已授权范围内继续。

## 任务输入

从用户消息、当前仓库及已授权访问的 Cloudflare 设置中确认：

| 输入        | 确认依据                              |
| --------- | --------------------------------- |
| 部署仓库      | Cloudflare“设置 → 构建”关联的 GitHub 仓库  |
| 生产分支      | Cloudflare 实际使用的分支，不能直接假定为 `main` |
| Worker 名称 | 已部署的 Worker，不新建替代站点               |
| 网站地址      | 原站点地址，用于更新后验证                     |
| 执行范围      | 准备本地更新、推送、创建 PR、合并或发布，按用户授权执行     |

官方模板固定为 `https://github.com/Azincc/nimbus-docs-template.git`，上游分支为 `main`。能从上下文确认的信息无需重复询问。部署仓库或生产分支仍不明确时，先询问必要信息。

## 1. 确认目标仓库

阅读仓库的 `AGENT.md` 及相关项目约定。核对 `git remote -v`、当前分支和 `git status`，确认操作的是部署仓库，而不是仅保存 Markdown 的 `DOCS_REPO`。

用户有未提交工作时，在独立克隆或工作目录中处理更新，保留原有工作。不重置、暂存或覆盖无关修改。

## 2. 准备更新分支

获取生产分支的最新提交，记录更新前的完整 SHA。以该提交创建独立更新分支，按仓库约定命名。

为官方模板配置并核对 `upstream`。如果名称已被其他仓库占用，换用新的远程名称，不改写现有远程地址。获取官方 `main`，记录目标提交的完整 SHA，本次合并固定使用该提交。

生产分支已包含目标且无须更新时，直接报告已是最新，不创建空提交或更新请求。

## 3. 合并官方更新

在更新分支执行下面的合并，将 `UPSTREAM_COMMIT_SHA` 替换为已确认的完整目标 SHA：

```sh
git merge --no-ff --no-commit --allow-unrelated-histories UPSTREAM_COMMIT_SHA
```

`--allow-unrelated-histories` 用于兼容 Cloudflare 创建的独立仓库历史；`--no-commit` 让你在检查合并结果后再提交。

检查自动合并结果和冲突文件，逐项处理双方修改。不要对整个仓库统一使用 `ours`、`theirs` 或强制覆盖。无法可靠解决冲突时，列出文件及需要用户决定的内容，保留现场供审阅。

## 4. 保留用户内容和配置

| 内容                                                  | 执行要求                                                                                |
| --------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 用户文档、图片和站点 JSON                                     | 保留用户内容，确认官方示例没有混入用户文档                                                               |
| 定制页面、组件及样式                                          | 保留用户修改，同时合入新版功能                                                                     |
| `wrangler.jsonc`                                    | 逐字段保留原 Worker 名称、`vars`、账户、域名及其他部署设置，补入新版所需配置；不把 Worker 名称改回 `nimbus-docs-template` |
| `package.json`、`pnpm-lock.yaml`、`package-lock.json` | 保留用户包名及必要定制，确保依赖与所用包管理器的锁文件一致                                                       |
| 构建脚本及关联文件                                           | 相互依赖的脚本、布局、组件和样式一起更新，避免只同步部分功能                                                      |
| Cloudflare 构建变量和机密                                  | 保留现有配置，不导出或复制机密到仓库                                                                  |

`DOCS_TOKEN` 仅用于 Git fetch，不能写入配置、日志、提示词或静态产物。构建源文档只写入临时或生成目录，不在 `src/content/docs/` 维护文档。

## 5. 完成核心验证

确认没有未解决冲突，审阅差异及暂存内容，并执行：

```sh
git diff --cached --check
```

本地已具备对应文档源配置时，按项目要求运行一次必要构建：

```sh
pnpm install --frozen-lockfile
pnpm run build
```

本地配置可能与 Cloudflare 不同，需要说明本次验证实际使用的文档源。验证私有文档时，可以使用 Cloudflare 已配置的分支构建，不要求用户把 Token 发到聊天。

只完成必要的核心验证。缺少权限、依赖或构建条件时，说明具体未验证项，不报告构建成功。

## 6. 在授权范围内提交和发布

仅提交已核对的变更。获准推送后，推送更新分支，并向实际生产分支创建 Pull Request，说明新增功能、用户配置保留情况和验证结果。

获准合并时，使用 **Create a merge commit** 保留上游历史，方便下次同步。若仓库不允许这种方式，先说明限制，不擅自改用 Squash 或 Rebase。不强制推送，不新建 Worker，不改变原站点域名。

如果用户当前只要求准备更新，交付可审阅的本地结果及剩余步骤。

## 7. 确认完成状态

获准发布后，先确认 Cloudflare 已成功构建并部署包含本次更新的新提交，再检查原站点首页、搜索和本次更新的功能。

重试旧构建不会构建新的模板代码。页脚及 `/_build.json` 的 SHA 是文档版本，不能单独证明模板已更新。报告时应区分 GitHub 检查通过、PR 已合并和网站已部署，按实际证据说明进度。

需要回退且已获用户授权时，撤销对应更新请求的合并提交，再重新部署。紧急情况下恢复 Cloudflare 旧部署后，还要同步处理仓库代码，避免下次构建再次发布有问题的版本。

## 交付结果

向用户报告：

* 部署仓库、生产分支、更新前 SHA 和官方目标 SHA。
* 本次变化及用户配置保留情况。
* 已完成的检查、未验证项及冲突。
* 实际达到的状态：本地准备、已推送、已创建 PR、已合并或已部署。
* 实际 PR 或成功部署的链接；需要用户操作时，给出具体下一步。

Source: https://nimbus.az1n.com/deployment/template-update-agent/index.mdx