这份说明供 Agent 更新已部署到 Cloudflare 的 Nimbus 文档站时使用。将官方模板的更新合入现有部署仓库，并保留用户文档、配置、定制和原 Worker。站点使用者请阅读更新模板。
操作范围以用户当前任务的实际授权为准。阅读本页本身不授予推送、合并或部署权限。先准备可供审阅的更新结果，再在已授权范围内继续。
任务输入
从用户消息、当前仓库及已授权访问的 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：
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. 完成核心验证
确认没有未解决冲突，审阅差异及暂存内容，并执行：
git diff --cached --check本地已具备对应文档源配置时，按项目要求运行一次必要构建：
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 或成功部署的链接；需要用户操作时，给出具体下一步。