Continue 的 PR 文档守门员：深入解析 `.continue/checks/update-continue-docs.md` 文档更新检查规则

Continue 仓库在 .continue/checks/ 目录下维护了一组可被 Checks 系统自动加载的 Markdown 检查规则。update-continue-docs.md 是其中唯一面向文档体系的规则：它定义了一个"文档守门员"Agent 的角色、决策标准与写作规范，用来判断某个 Pull Request 是否需要同步更新 Continue 官方文档（docs/ 目录下的 Mintlify 站点内容）。读完本文，你能理解 Checks 机制如何把一份提示词文件变成可执行的 PR 自动化能力，并能照此模式为自己仓库编写文档更新检查规则。

一、规则文件本身：结构与前导元信息

先看这份检查规则的完整结构（update-continue-docs.md）。文件以 YAML frontmatter 开头：

---
name: Update Continue Docs
description: Update Continue Docs
---

name 与 description 是 Checks 系统识别该检查的标识——CLI 在展示检查结果时输出的 CheckStatus.name 与 description 即来源于此（见 checks.ts 中定义的 name、state、description 字段）。正文则分成五个逻辑区块：

1. Role & Background —— 给执行者设定"Continue 开发者布道工程师"的角色与语气基线；
2. Task —— 核心任务：基于 PR 变更判断文档是否需要更新，并给出决策标准；
3. Requirements —— 硬性约束：只能改文档、保留 frontmatter、新页面要登记到导航文件；
4. Writing Guidelines —— 文档写作的语音、质量与 Mintlify 格式规范；
5. Context: Continue —— 项目背景一句话：Continue 提供 VS Code 与 JetBrains 插件以及 CLI（cn）。

从同目录的其他检查文件（如 stale-comments.md、anti-slop.md）的写法可以推断：.continue/checks/*.md 遵循统一约定——frontmatter 提供元信息，正文提供"检查什么、怎么检查、排除什么"。resolveReviews.ts 中的注释明确证实了这一发现机制：审查文件按"本地 .continue/agents/*.md 与 .continue/checks/*.md（fallback）"的优先级被解析，也就是说这份文件不需要任何注册步骤，放在约定目录即生效。

二、任务定义与决策标准（Task 区块）

规则的核心任务是：根据指定 PR 的变更，判断 Continue 文档是否应当更新。文档给出了三条决策标准（决策标准原文，完整继承自规则文件）：

• 变更应保持范围收敛，目标是让文档保持同等详细程度（"keep the docs at the same level of detail"）；
• 不要为细枝末节的代码更新（niche code updates）总是补充额外信息；
• 只有当变更实质影响开发者理解或使用方式时才更新文档。

对应两条执行分支：

• 需要更新：先制定文档更新计划，再按计划执行更新；
• 不需要更新：在 PR 上添加一条简短评论，解释为什么不必更新 Continue 文档。

这两条分支设计有一个值得注意的工程考量：无论判断结果如何，PR 上都会有一个"结论性产出"（要么是文档 diff，要么是一条解释评论）。这让 Checks 的运行不会"静默通过"，审查者总能回溯 Agent 的推理——这与 Checks 系统本身的透明性设计一致：CLI 的列表视图会为每个检查展示 commitMessage 与 suggestionStatus（见 checks.ts），即 Agent 产出的提交与建议的接受/拒绝状态都会对外可见。

三、硬性约束（Requirements 区块）

Requirements 区块列出了四条不可违反的边界，其中三条直接约束"改什么"：

• 只允许改动文档：失败检查、代码 bug、代码审查意见等都不在职责范围内（"not in your scope"）。这条约束把该检查与同目录下的 security-audit.md、stale-comments.md 等代码向检查在职责上做了清晰切分；
• frontmatter 原样保留：页面已有的 title、description 必须"EXACTLY as provided"，不得改动。这是 Mintlify 站点的 SEO/导航元信息，随意修改会破坏站点结构一致性；
• 新页面必须入导航：新增页面要加到文档导航文件（如 docs.json）的合适位置——Mintlify 以 docs.json 作为整站导航的唯一事实来源，跳过这一步新页面将无法被访问到。

第四条与展示方式相关：优先使用 Mintlify 组件来组织信息。下文第五节展开。

四、写作指南：语音、内容质量与组件规范

Writing Guidelines 是这份规则信息密度最高的部分，它把 Continue 文档站的"文风宪法"固化了下来。

4.1 语音与语气（Voice & Tone）

• 精确、结构化、技术准确、以示例驱动；
• 永远优先清晰而非术语（"clarity over jargon"）；
• 一切解释都要扎根于开发者实际体验；
• 绝不编造数据或声明，也不承诺未正式发布或未经验证的能力。

这与整个仓库的规则体系一脉相承：例如 continue-specificity.md、documentation-standards.md 等 rules 文件也围绕"文档描述要准确、具体"展开，可以视为同一写作纪律在不同粒度的落地。

4.2 内容质量（Content Quality）

• 页面要"可扫读"：短段落、强动词、最少术语；
• 描述用 1–2 句话，使用"结果导向"语言（outcome language），拒绝营销腔；
• 不重复 UI 文案，除非用于澄清权限或前置条件；
• 除非明确要求，不写逐步 UI 走查。

4.3 格式规范：Mintlify 组件的正确用法

规则列出了六个组件的分工，这基本就是 Continue 文档站（docs/ 目录，全部为 .mdx）的组件契约：

组件	用途
<Card>	带链接的"行动号召"项
<CardGroup cols={2}>	相关卡片的分组
<Accordion> / <AccordionGroup>	补充性、可折叠内容
<Tip>	可执行的操作建议
<Warning>	重要注意事项（caveats）
<Note>	补充上下文

配套的 mintlify-formatting.md 规则进一步给出了这些组件的排版硬约束：开标签后与闭标签前必须各留一空行、内容缩进 2 空格、列表每项独占一行。该规则文件甚至给出了错误示例——所有 bullet 挤在标签内一行，会被判定为错误格式。写这份检查的产出时，执行 Agent 同时受这两份文件约束，因此输出的 .mdx 在结构（选对组件）与排版（留白缩进）两个层面都有据可依。

4.4 Support & Resources 章节的写法

• 使用 <CardGroup cols={2}>，放 2–4 张卡片；
• 优先链接内部文档页；
• 只有在真正必要时才引用外部/厂商文档。

这一条实际上也约束了本文所在仓库的文档引用习惯：docs/ 下的指南（如 continue-docs-mcp-cookbook.mdx）在组织"资源"类章节时遵循同样的卡片分组模式。

五、在 Checks 体系中运行：从提示词文件到 PR 状态

把这份文件放回 Continue 的 Checks 架构里，可以看到一条完整的调用链：

1. 发现：本地 .continue/checks/*.md（以及 .continue/agents/*.md）被 resolveReviews.ts 作为 fallback 来源解析，frontmatter 决定检查名称与描述；
2. 执行：Check 会话运行后，服务端为每个检查维护 pending / success / failure 三态，以及 commitMessage、suggestionStatus、agentStatus（见 CheckStatus 接口）；
3. 查看：cn checks [pr-url] 列出 PR 下所有检查，对有提交的检查会拉取 agents/{sessionId}/diff 并内联打印 diff（printCheckDiff）；PR URL 可省略，此时 CLI 通过当前 git 分支调用 GitHub API 自动探测 open PR（detectPrUrl）；
4. 处置：cn checks accept / cn checks reject 分别对 suggestionStatus === "pending" 且带提交的检查批量调用 agents/{sessionId}/accept 或 /reject（acceptChecks、rejectChecks）；
5. 退出码契约：列表模式退出码为 0=全部通过、1=存在失败、2=仍有 pending，可直接嵌入 CI 判定（listChecks 中的注释明确了这一约定）。

# 查看当前分支 PR 的所有 checks 及 diff
cn checks

# 批量接受 / 拒绝所有 pending 建议
cn checks accept
cn checks reject

对于"文档更新检查"这类产出文档 diff 的场景，上述流程意味着：Agent 修改完 docs/ 下的 .mdx 文件并登记 docs/docs.json 后，开发者用 cn checks 审阅 diff，用 accept 将其合入建议 PR，或 reject 放弃——与规则文件"若需更新则按计划更新、否则在 PR 上评论说明理由"的两种分支恰好一一对应。

六、为什么文档本身值得这样维护：docs/ 与 docs-site/ 双轨结构

理解这条规则的价值，需要了解它守护的文档体系在仓库中的真实形态：

• docs/：Mintlify 文档站的内容源，全部为 .mdx（含 customize/、guides/、cli/ 等目录），由 docs.json 描述全站导航。规则中"新页面加入 docs.json"的要求正对应这里的站点机制；
• docs-site/：一个 Next.js 应用，通过 docs.ts 等模块在独立域名/路径下承载文档，copy-doc-images.ts 负责同步 docs/images/ 中的图片资源。

从 overview.mdx 等入口页的写法可以看到"短描述 + 卡片导航"的既定风格——这正是规则第四节所固化的内容。换言之，update-continue-docs.md 不是凭空立规，而是把既有文档站的实际约定（组件选择、frontmatter、导航登记）提升为 Agent 可执行的检查标准，使文档一致性不依赖人工审查的偶然性。

七、可借鉴的模式：为自己仓库写一个文档更新检查

这份规则文件展示了一个可直接复制的模式——"判定 + 分支产出 + 边界约束"：

1. 判定标准前置：先写清楚"什么情况下算需要更新"（本例：实质影响开发者理解或使用），避免 Agent 过度更新或漏更新；
2. 两种结果都要有产出：更新则提交文档 diff；不更新则在 PR 留解释性评论，保证每次运行都可审计；
3. 职责边界显式化：声明"只改文档、frontmatter 不动、代码问题不归我管"，防止检查 Agent 越权修改代码文件；
4. 风格规则与格式规则分离引用：本文例把"写什么"（Task/Requirements）与"怎么写"（Writing Guidelines，并另见 mintlify-formatting.md、documentation-standards.md）分层组织；
5. 目录约定即注册：文件放入 .continue/checks/ 即被发现，frontmatter 的 name/description 决定其在 PR 与 CLI 输出中的展示。

同目录下的其余检查可作为对照样本：stale-comments.md 示范了如何给出"BAD/GOOD"代码对照与排除清单（Exclusions），setup-scripts.md、security-audit.md、react-best-practices.md 则覆盖脚本、安全、前端实践维度。配合仓库根部的 environment.json（声明 npm i 安装步骤，供 Agent 环境准备），整个 .continue/ 目录构成了一套"仓库自带 AI 协作规范 + 自动化检查"的完整声明。

小结

update-continue-docs.md 虽篇幅不长，却是 Continue 文档质量管线的控制点：它用角色设定约束语气，用三条决策标准控制"何时更新"，用四条硬性边界控制"怎么改"，再用 Mintlify 组件契约与 mintlify-formatting.md 的排版规则控制"写成什么样"。其运行载体——.continue/checks/ 目录约定、cn checks 命令族的三态/退出码契约（checks.ts）、以及 accept/reject 的批量处置接口——共同保证了这条检查从提示词文本到 PR 落地建议的每一步都可查看、可审查、可回滚。对于任何希望让"文档与代码同步更新"成为自动行为而非口头约定的团队，这份文件是一个信息密度很高、可直接仿写的参考实现。