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

# 真实案例：用 Supervisor Change 交付项目知识引擎

> 复盘 Comet 仓库中一个已归档的 Supervisor Change，了解大型能力如何拆分、集成、修复并完成统一验收。

export const SupervisorVideo = ({src, width, height, label, fallback}) => <div className="comet-home__supervisor-media">
    <video autoPlay muted loop playsInline controls preload="metadata" width={width} height={height} aria-label={label}>
      <source src={src} type="video/mp4" />
      {fallback}
    </video>
  </div>;

本页复盘 Comet 仓库中已经完成交付的 `agent-project-knowledge-engine`。它在 2026 年 8 月 22 日归档，最终进入 `040rc1`。案例中的目标、child、依赖、提交和验证结果都来自仓库记录。

这次 Change 把 Project Knowledge 从即时运行 ripgrep 的文档检索，升级为面向 Agent 的项目理解能力。最终交付包含 SQLite FTS5 与 ripgrep 混合召回、项目知识单元、受控学习、CLI、Dashboard 和评测体系。

<img src="https://mintcdn.com/comet-bb5f5294/CIB1KsTG50DJzuVf/assets/supervisor-change-delivery-illustrations/01-integrated-delivery.png?fit=max&auto=format&n=CIB1KsTG50DJzuVf&q=85&s=d4e2bcc0a7d2e8bbdd20792826e38a90" alt="小鱼把三个 child 的成果装订进父级交付，并补齐最终验收缺口" width="1672" height="941" data-path="assets/supervisor-change-delivery-illustrations/01-integrated-delivery.png" />

## Supervisor 在 Codex 中的执行画面

下面的录屏展示 Supervisor 在 Codex 中创建独立任务、分配 child 和持续统筹的实际界面。录屏用于展示执行机制；本文的 child、提交和验收数据仍来自 `agent-project-knowledge-engine` 归档。

<SupervisorVideo src="/vedio/codex.mp4" width={1230} height={858} label="Comet Supervisor Change 在 Codex 中通过多个独立任务推进 child" fallback="你的浏览器不支持 HTML5 视频" />

## 用整体目标约束多个实现阶段

Project Knowledge 的改造横跨检索、索引、知识模型、插件事件、CLI、Dashboard 和评测。各部分可以分阶段实现，但必须共同满足一个产品目标：减少 Agent 的重复探索，同时继续以当前代码、配置和测试作为最终依据。

父级 Change 统一维护以下边界：

* Local Provider 默认使用 FTS5 与 ripgrep 混合召回，FTS5 不可用时保留回退；
* Project Knowledge 与 Personal Memory 保持独立所有权、存储和预算；
* 项目知识必须带当前来源，不能代替代码核对；
* 索引故障、来源不可读和语义适配器失败不能阻塞 workflow；
* CLI、Dashboard、生成资产、Retrieval Eval 和 Agent A/B 使用同一能力边界。

这些约束需要在全部实现集成后统一验收。单个模块独立通过测试，不能证明完整产品目标已经成立。

## 从真实依赖拆出三个 feature child

归档中的 `children.yaml` 使用 `comet.native.children.v2`。初始实施按真实依赖拆成三个 feature child：

| Child                                   | 依赖               | 主要结果                                             | 实现提交       |
| --------------------------------------- | ---------------- | ------------------------------------------------ | ---------- |
| `project-knowledge-hybrid-retrieval`    | 无                | 查询规划、SQLite section 索引、混合召回、索引管理和 Retrieval Eval | `d42226fb` |
| `project-knowledge-units`               | hybrid retrieval | 知识单元、确定性提取、来源校验和一跳关系                             | `efe007c9` |
| `project-knowledge-learning-management` | knowledge units  | 受控学习、Plugin Event、显式共享、CLI、Dashboard 和 Agent A/B | `cca74993` |

这三个 child 形成一条依赖链：

```text theme={null}
project-knowledge-hybrid-retrieval
  → project-knowledge-units
    → project-knowledge-learning-management
```

Supervisor Change 支持并行执行，也支持这种按依赖分阶段推进的任务。Runtime 每次只把依赖已经满足的 child 放入 `readyChildren`。后续 child 从最新集成基线开始，避免基于尚未稳定的数据结构或接口提前实现。

## 每个 child 在隔离工作区形成可集成结果

三个 feature child 都在自己的工作区完成实现和验证。它们没有直接修改目标分支，而是先进入 Supervisor 的集成分支。

仓库保留了三次真实集成提交：

| 集成提交       | 集成结果                                                       |
| ---------- | ---------------------------------------------------------- |
| `6a230657` | 合入 hybrid retrieval，新增 19 个文件，形成 SQLite 索引、CLI 和检索评测基础     |
| `576f4c25` | 合入 knowledge units，新增确定性提取器、知识单元存储与对应测试                    |
| `be58f9cc` | 合入 learning management，加入学习流程、管理命令、Dashboard 视图和 Agent A/B |

每个 child 的 feature commit 与集成 commit 分开保留。Runtime 可以据此判断候选是否经过验证、当前集成基线是否包含依赖，以及迟到结果是否仍适用于当前状态。

## 父级 Verify 暴露跨模块缺口

三个 feature child 集成后，父级没有直接归档。`verification.md` 记录了两轮失败：

| 目标周期 | Verify 结果 | 发现的问题                                 |
| ---- | --------- | ------------------------------------- |
| 2    | failed    | 调研结论与实现之间仍有实质性闭环缺口                    |
| 3    | failed    | 来源可信性、workspace 隔离、激活条件、增量成本和完整评测仍不充分 |

这些问题跨越多个 feature child。重新打开已经集成的 child 会破坏已确认的历史边界，也难以表达新的整体验收范围。Runtime 保留集成现场，并让父级回到 Shape 更新验收与 child 声明。

## 追加 closure child 收敛真实失败

最终归档的 `children.yaml` 增加了第四个 child：

```yaml theme={null}
- name: project-knowledge-closure
  depends_on: [project-knowledge-learning-management]
  covers: [A4, A8, A10, A15, A19, A20, A27, A29, A30, A31]
```

`project-knowledge-closure` 聚焦父级 Verify 已经观察到的缺口，包括来源边界、定向刷新、激活条件、workspace 隔离和评测完整性。后续修复提交没有扩大产品目标，而是在现有验收范围内补齐实现证据。

其中，`3cd0c25b` 完成了最后一轮 review boundary 修复，涉及知识单元、学习流程、插件集成、文件存储和两个评测脚本。这个 child 让跨模块问题拥有独立范围，同时保留前三个 feature child 的集成历史。

## 最终验收覆盖 49 项行为

第四个目标周期的第二次 Verifier 通过。最终 `verification.md` 记录：

* 49 项验收全部为 `passed`；
* Child 验证、父级集成和父级检查均完成；
* focused tests、Native tests、typecheck 和 build 已执行；
* 独立 code review 的三项重要问题已经修复；
* 没有 Critical 问题和未完成阻塞项。

全量测试同时保留了一个与本 Change 无关的既有 `/comet` Skill 长度基线失败。归档没有把它改写为本次能力通过，也没有让无关失败覆盖已经完成的专项证据。

## Archive 后一次性交付目标分支

父级完成 Verify 后，以 `de780ce2` 归档。随后 `58b6dfb2` 把 `comet/agent-project-knowledge-engine` 合入 `040rc1`。

整个过程只在父级完成一次最终交付：

```text theme={null}
3 个 feature child
  → 3 次独立集成
  → 2 轮父级 Verify 失败
  → 1 个 closure child
  → 49 项最终验收通过
  → Archive
  → 合入 040rc1
```

## 从这个案例提取拆分原则

这个真实 Change 展示了 Supervisor 的四个产品特点：

| 特点      | 案例中的表现                                   |
| ------- | ---------------------------------------- |
| 依赖驱动    | 后续 child 只在前置能力集成后开始                     |
| 工作区隔离   | 每个 child 形成独立候选，再由 Runtime 集成            |
| 父级统一验收  | 模块测试通过后仍检查完整产品目标和跨模块边界                   |
| 失败范围可追加 | 最终 Verify 的真实缺口形成 closure child，不改写已集成历史 |

选择 Supervisor Change 的关键依据是整体目标需要多个可独立验证的结果，并且父级仍有不可省略的最终验收。子任务能否同时运行只是执行效率的一部分，明确依赖、隔离候选和统一交付同样重要。

案例证据位于 Comet 源码仓库的 `docs/comet/archive/2026-08-22-agent-project-knowledge-engine/`。继续阅读：[Supervisor Change 机制](/zh/native/supervisor-change)、[Native Loop](/zh/native/native-loop) 和 [验证与修复](/zh/native/verification-and-repair)。