Continue 破坏性变更检测：用 `.continue/agents` 评审代理系统性排查改名与失效引用

本文围绕 Continue 仓库中自带的评审代理定义 breaking-change-detector.md 展开，完整解读它对 CLI 命令、公共 API、配置 schema 与硬编码 URL 四类破坏性变更（Breaking Change）的判定标准与处置规则，并结合 cn review 命令 的源码实现，说明该代理如何被自动发现、加载与执行。读完后你将能够：在自己的 Continue 代码库中定义、运行同类审查代理，并理解“哪些该修、哪些该标注、哪些不该报”的工程边界。

一、它是什么：一个 Markdown 定义的代码评审代理

breaking-change-detector.md 是 Continue 项目自用的一个评审代理（review agent），文件由 YAML frontmatter 加 Markdown 正文构成：

---
name: Breaking Change Detector
description: Flag renamed commands, APIs, or config options with stale references
---

正文开头一句话即代理的任务目标：“Analyze this pull request for breaking changes that may leave stale references elsewhere in the codebase”（分析本次 PR 中可能让代码库其他位置遗留失效引用的破坏性变更）。它不是脚本，而是一份写给 LLM 的结构化审查规程：定义“什么算破坏性变更”“发现问题该怎么办”“哪些情况不该报”。Continue 仓库在 .continue/agents/ 目录下还并列维护了同类型的代理，如 test-coverage.md、dependency-security-review.md、error-message-quality.md、input-validation.md，共同构成一套 PR 自检体系。

该代理的运行载体是 Continue CLI 的 review 子命令。从源码看，review 命令支持 --review-agents <agents...> 参数来指定要运行的具体审查代理，注册位置见 index.ts 中的 review 子命令：

program
  .command("review")
  .description("Run AI-powered reviews on your changes")
  .option("--base <ref>", "Base git ref to diff against (default: auto-detect)")
  .option("--format <format>", "Output format")
  .option("--fix", "Automatically apply suggested fixes")
  .option("--patch", "Show patches")
  .option("--fail-fast", "Stop on first failure")
  .option("--review-agents <agents...>", "Specific review agents to run")

当代理来源是本地 Markdown 文件时，isLocalPath 会把以 .md 结尾的路径识别为本地代理，因此可以显式指向该文件运行：

cn review --review-agents .continue/agents/breaking-change-detector.md

二、四类破坏性变更的判定标准与排查清单

这是该代理的核心资产：它把“破坏性变更”拆成四个可操作的类别，每个类别都附带一份“必须核对的引用点”清单。以下完整继承原文档内容，并结合仓库结构说明每个检查点的实际落点。

1. CLI 命令的重命名或移除

原文档规定：如果注册在 extensions/cli/src/commands/ 下的命令被重命名、移除或改动了 flag，必须核对五类位置——

• docs/ 中的文档已反映新命令名
• .continue/agents/ 中的代理定义没有引用旧命令
• skills/ 中的技能已同步更新
• README 与 CONTRIBUTING.md 保持最新
• GitHub Actions 工作流没有再调用旧命令

这份清单的针对性来自本仓库的真实命令结构。从源码看，CLI 入口 extensions/cli/src/index.ts 使用 commander 构建名为 cn 的程序（程序初始化），子命令注册在 extensions/cli/src/commands/ 目录下，当前包含：

子命令	源文件	说明
（根命令）	chat.ts	默认进入交互式会话，-p/--print 为无头输出
ls	ls.ts	列出最近会话
serve	serve.ts	启动带 /state、/message 端点的 HTTP 服务（隐藏命令）
checks	checks.ts	查看 PR 的 CI check 状态
review	review.ts	对变更运行 AI 评审

除子命令外，会话内的斜杠命令集中定义在 commands.ts 的 SYSTEM_SLASH_COMMANDS 表（help、resume、fork、export 等）。这正是代理清单中“flag 变化”要覆盖的范围：一旦 --print、--review-agents 这类 flag 或 ls、review 这类命令名变更，文档、skills/ 目录下的技能（如 skills/cn-check/）、代理定义与 CI 工作流都可能留下指向旧名称的失效引用。

2. 公共 API 变更

原文档规定：core/ 或 packages/ 下导出的函数、接口或类型被重命名或签名变化时，必须核对——

• gui/、extensions/、binary/ 中的所有调用方已同步更新
• packages/config-types/ 中的类型定义保持一致

这一点与仓库的分层结构吻合：core/ 承载核心能力（如 core/protocol/ 定义的通信协议、core/config/ 的配置加载），packages/config-types/ 提供对外暴露的配置类型定义，而 gui/、extensions/、binary/ 是消费这些 API 的三大端。由于这几个模块分属不同包，重命名一个导出符号很容易只改定义、漏改某一端的调用方——这正是该代理要求逐一核对的原因。

3. 配置 schema 变更

原文档规定：配置文件格式（YAML 或 JSON）被修改时，必须核对三点——

• 校验逻辑能同时处理新旧两种格式（或提供了迁移路径）
• 文档示例使用新格式
• 默认配置已更新

仓库中对应着真实的校验与迁移实现：packages/config-yaml/ 承担 YAML 配置的解析与校验，core/config/validation.ts 负责配置合法性检查，而 core/config/migrateSharedConfig.ts 的存在说明项目确实有“schema 演进需要迁移逻辑”的实践。文档侧则由 docs/ 下的配置参考（如 docs/reference/yaml-migration.mdx）承担示例更新。代理清单要求“校验逻辑兼容或提供迁移”，正是防止只改新格式解析、却让存量用户配置直接失效的典型事故。

4. URL 变更

原文档规定：任何硬编码 URL（例如 hub.continue.dev、api.continue.dev）发生变更时，需要全仓库扫描失效引用。

从仓库实际内容看，这类 URL 并非孤例，至少出现在 extensions/cli/src/env.ts、extensions/cli/src/version.ts、extensions/cli/src/util/apiClient.test.ts 等文件以及 packages/continue-sdk/ 的 SDK 代码中，还散见于 BUILD_DEPENDENCIES.md、extensions/cli/docs/ 等文档。跨端引用面决定了：改一个域名必须全局检索，而非只改单一实现文件。

三、处置规则：修、标注、还是放过

代理的第二部分定义了发现问题的处置边界，直接决定其作为自动化审查者的行为收敛程度。

What to Do（该做什么）：

• 发现失效引用时，直接修复（fix them directly）——即代理被授权产出补丁而非仅提意见；
• 若某个破坏性变更没有迁移路径且可能影响用户，添加评论标注该担忧，但不阻断 PR（do not block）；
• 只关注本次 PR 引入的变更（Focus only on changes introduced in this PR），不报告历史遗留问题（pre-existing issues）。

What NOT to Flag（不该报什么）：

• 同一 PR 内已把所有引用一并更新的内部重构；
• 仅测试代码（test-only code）的变更；
• 不影响用户、只涉及开发工具链的变更。

这套规则的设计意图很明确：自动评审的第一死敌是误报。通过“同 PR 内已同步更新则豁免”“只看增量不看存量”“测试与开发工具链免检”三条负面清单，把代理的输出收敛到“本次 PR 引入的、跨模块遗留的失效引用”这一高信噪比区间上——既能配合 cn review --fix 自动落补丁，又不会因陈年问题刷屏导致审查被忽略。

四、执行机制：代理如何被发现、加载与运行

理解代理被 cn review 消费的方式，可以完整闭合本文。核心逻辑在 resolveReviews.ts，按三级优先级决定运行哪些审查：

1. CLI --review-agents 标志（最高优先级），接受 Hub slug 或本地路径；
2. Hub API（源码注释说明该来源已移除，当前 resolveFromHub 恒返回空数组）；
3. 本地回退：扫描当前目录下 .continue/agents/*.md 与 .continue/checks/*.md，且同名文件 agents 目录优先于 checks 目录（见 resolveFromLocal 实现）。

代理显示名由文件名派生：去掉扩展名后把连字符、下划线替换为空格（agentDisplayName），所以 breaking-change-detector.md 在报告中显示为 "breaking change detector"。

确定代理后，review.ts 的 runReviewInWorker 会为每次评审 fork 一个带 --internal-review-worker 标志的子进程，在独立 git worktree 中运行，并设置 5 分钟超时；worker 从本地 Markdown 文件加载代理指令（见 reviewWorker.ts）。当仓库中没有任何本地代理时，review 命令会提示创建入口：“Create .continue/agents/my-review.md with agent instructions”（见 review.ts 中的提示信息）——breaking-change-detector.md 正是这条建议的成品示例。

五、可迁移的方法论

该文件示范了一套可复用的“破坏性变更审查规程”写法，要点可直接搬到其他仓库：

1. 按变更类别枚举检查点，而不是泛泛说“检查引用”：CLI 命令 → 文档/代理/技能/README/CI；API → 各消费端 + 类型包；schema → 校验兼容 + 文档示例 + 默认值；URL → 全局扫描。每类检查点都落到具体目录。
2. 正面规则与负面清单成对出现：既定义“发现即修复、只报增量”，也明确三类豁免，控制误报率。
3. 用 frontmatter 的 name/description 声明代理身份，使其能被 resolveReviews 的本地扫描机制自动发现并生成可读的显示名。

结合 extensions/cli/src/commands/ 的命令结构、packages/config-yaml/ 的配置校验层与 .continue/agents/ 的代理目录，这份 Markdown 把“破坏性变更审查”从一个口头约定变成了 cn review 可执行、可复现的工程流程。