blume-update-docs

更新 Blume 文档

Blume 是一个 以 Markdown 为先 的文档框架，基于 Astro/Vite 构建：内容以 Markdown/MDX 格式存放在内容根目录下（默认为 docs/），导航由文件树和可选的 meta.ts 文件生成，blume build 会验证 frontmatter 和重复路由，blume validate 会检查链接和锚点。

你的工作是维护文档，而不是撰写文档：找出已发布的面向用户行为与文档描述不符之处，只修正这些问题，证明网站仍能成功构建，并将结果作为拉取请求提交。如果没有发现可处理的问题，则以简短报告结束，不创建分支、不提交、不发起拉取请求——宁可不做更改，也不要提交无意义的拉取请求。

基本原则

• 只记录已发布的功能。 切勿编造功能、时间线、定价、API 或兼容性声明。除非功能标志已对文档所面向的用户启用，或仓库明确记录了尚未发布的行为，否则带功能标志的开发内容尚未准备好写入文档。
• 事实优先于润色。 当命令、选项、默认值、路由、属性或工作流有误或缺失时才进行编辑。跳过主观措辞调整、营销文案润色、结构调整以及纯格式改动。
• 采用最小的正确差异。 只修改消除偏差所需的最少页面。保留网站的语气、frontmatter 风格、组件用法和 meta.ts 导航模式。
• 准确沿用事实来源中的措辞，包括命令、标志、配置键、环境变量、路由和版本号——从代码中复制，不要凭记忆转述。
• 遵守仓库规范。 遵循 AGENTS.md/CLAUDE.md 中的约定，不要修改生成的输出（.blume/、dist/），也绝不要覆盖无关的本地更改。

工作流

1. 了解上下文。

   • 阅读仓库中的 Agent/贡献者说明（AGENTS.md、CLAUDE.md、贡献文档），并遵循这些说明。
   • 找到文档应用和内容根目录：blume.config.ts（content.root）、.md/.mdx 页面目录、meta.ts 文件，以及包管理器和文档构建命令。
   • 如果本次运行配置了触发条件、回溯窗口、文档路径、目标分支或 PR 策略，请遵照执行。仅在提示未说明时使用以下默认设置。

2. 复用或创建维护分支。

   • 如果有上次运行创建的未关闭文档维护 PR（头部分支以 blume/ 开头），请检出并更新该分支，而不是另开重复 PR。
   • 否则，从默认分支创建 blume/docs-refresh-YYYY-MM-DD 分支。只有确认需要编辑后，才创建分支。

3. 查找偏差。 阅读 references/audit-checklist.md，了解完整的来源列表和变更标准，然后：

   • 检查回溯窗口内合并到默认分支的 PR（默认：最近 7 天），提取面向用户的变更。
   • 将这些变更与变更日志、发行说明、配置架构、导出的 API、CLI 帮助和示例一起，与文档内容进行对照。
   • 仅在已检查的页面依赖外部链接时检查这些链接；优先参考官方文档和发行说明，而非二手来源。
   • 记录检查内容、上游变更以及每项编辑需要（或不需要）的原因。

4. 更新文档。

   • 修正过时页面。新增、重命名或删除页面时，相应更新 meta.ts 条目。
   • 遵循相邻页面的风格：frontmatter 结构、已使用的 Blume 组件、代码围栏样式、根目录相对内部链接。

5. 验证。

   • 运行文档构建命令（blume build 或仓库记录的文档 QA 命令）——该命令会验证 frontmatter 和重复路由。
   • 运行 blume validate，检查内部链接和锚点。
   • 如果仓库规范要求对文档变更执行 lint/格式化/类型检查，也请运行。
   • 修复由本次编辑导致的失败；对于预先存在的失败，请单独报告，不要在此 PR 中修复。

6. 交付。

   • **有变更：**仅提交维护相关编辑，推送 blume/* 分支，并创建或更新针对默认分支的 PR，标题格式如 blume: refresh docs for YYYY-MM-DD。在正文中列出已检查的来源、变更的文档、验证命令及结果、跳过的检查和剩余风险。
   • **无需变更：**报告已检查的 PR 和文档范围，并说明无需变更。不要创建分支、提交或 PR。

资源

• references/audit-checklist.md — 来源检查清单、编辑/跳过标准和 Blume 专用编辑指南。进行文档变更前请阅读。