用途
CocoPivot 是 CocoPlus 体系中的多 Pod 收敛合成器(multi-pod convergence synthesizer)。当 N 个 CocoPod 并行检查同一代码库时,会产生 N 份独立的发现列表,同一底层问题常被以三种不同视角、三种不同方式描述。CocoPivot 的职责是成为 lifecycle/FINDINGS.md 的唯一作者,让开发者只有一个权威来源来了解需要处理什么、按什么顺序处理。没有它,并行 Pod 产生的是并行噪音;有了它,产生的是协调后的信号。
前置条件
执行前需确认 .cocoplus/ 目录存在。若不存在,输出:"CocoPlus is not initialized. Run $pod init first." 然后停止。
主要能力与命令
$pivot run:以 run 模式使用 cococonverge/pivot-merge 契约。读取最近一次 CocoFlow 并行步骤执行产生的所有 Pod 输出文件(来自 pod-status.json),应用三遍去重算法,分配优先级层级与工作量估算,写入 lifecycle/FINDINGS.md 和 lifecycle/findings-state.json。若上游流程使用 on_partial: skip_partial,则排除 PARTIAL 状态的 Pod 输出。$pivot run --since <timestamp>:仅针对在指定时间戳之后完成的 Pod 输出执行收敛,适用于上次运行后又有新 Pod 完成时重新收敛。$pivot show:按优先级层级分组显示当前 lifecycle/FINDINGS.md;若有 PARTIAL 贡献 Pod,则包含 Coverage Note 部分。$pivot status:读取 lifecycle/findings-state.json 并显示:唯一发现总数、按优先级层级(P1/P2/P3/P4)计数、按严重级别(BLOCKING/IMPORTANT/MINOR/ADVISORY)计数、贡献 Pod 列表及其完成状态(COMPLETE/PARTIAL/ERROR)、上次收敛运行的时间戳。$pivot clear:将当前 FINDINGS.md 归档到 lifecycle/findings-archive/<timestamp>-FINDINGS.md,并重置 findings-state.json,为新的收敛运行做准备。
去重算法(确定性,不使用 LLM)
V2 原生收敛契约按顺序对所有上游 Pod 输出应用三遍处理:
- Pass 1 — 相同 file:line 匹配:两条发现引用同一文件的同一行号,视为同一底层问题。取贡献来源中的最高严重级别,保留最详细的描述,引用所有贡献 Pod 名称及其原始发现 ID。
- Pass 2 — 同文件内相同问题类型:来自同一文件、引用相同问题类型(如 "SQL injection"、"missing null check"、"N+1 query pattern")的两条发现,即使行号略有不同也视为同一问题。合并为一条发现并整合引用,保留最能精确定位问题的描述。
- Pass 3 — 相似代码片段引用:两条发现引用实质相似的代码片段,视为同一问题在不同具体程度上的描述。合并,优先采用更具体的描述。
发现 ID(PIVOT-NNN)在会话内保持稳定——findings-state.json 中的 PIVOT-001 始终对应 FINDINGS.md 中的同一条发现。
优先级与工作量分配
去重后,每条合并发现被分配:
- 优先级层级(P1–P4,含时间范围):继承贡献来源中的最高优先级层级。
- 工作量估算(XS–XL):继承贡献来源中的最大工作量估算,因为合并后的修复可能超过任何单一来源的估算。
- 严重级别:取贡献来源中的最高值。
PARTIAL 来源透明性
当任一贡献 Pod 发出 PARTIAL 状态时,FINDINGS.md 头部包含:
Coverage Note: [pod-name] completed partial checks (skipped: [check-list]). Findings from this source may not reflect complete coverage of its declared territory.
$pivot status 也会显式列出 PARTIAL 来源。
Scope 异常检测
读取每个贡献 Pod 的 .agent.md 定义中的 excludes: frontmatter 字段。若某 Pod 的输出包含一条发现,其关注类别出现在该 Pod 自身的 excludes: 列表中,则记录 scope 异常:
Pod [name] produced a finding in concern class [class] which appears in its declared exclusions. Finding excluded from FINDINGS.md; scope anomaly recorded in findings-state.json.
该发现被排除出 FINDINGS.md,但异常本身记录在 findings-state.json 中供审查——这防止 scope 累积在收敛步骤中静默叠加。没有任何 excludes: 声明的 Pod 无法评估 scope 纪律,因为其边界未定义;此类 Pod 在收敛报告中被记录为 "unscoped",而非被静默信任。
输出产物
- lifecycle/FINDINGS.md(提交):权威、人类可读,按 P1→P4 排序,层级内按严重级别排序。每条发现包含:PIVOT-NNN ID、严重级别、优先级层级 + 时间范围、工作量估算、描述、贡献来源及其原始发现 ID、file:line 引用、建议修复方案。
- lifecycle/findings-state.json(gitignored):机器可读等价物,供 hook 消费和程序化处理。
- lifecycle/findings-archive/:由
$pivot clear创建的历史 FINDINGS.md 版本。
与 CocoFlow 的集成
CocoPivot 是 converge: 步骤类型的规范处理器。当流程定义包含 handler: cococonverge 时,一旦前序 parallel: 步骤中的所有并行 Pod 达到终态,$pivot run 会作为 fan-in 操作自动调用。在已定义的 CocoFlow 之外,仍可手动调用以进行临时多 Pod 审计会话。
退出标准
$pivot run从 N 个 Pod 输出生成 FINDINGS.md,对相同 file:line 发现零重复条目。$pivot show、$pivot status、$pivot clear使用 V2 原生收敛契约及提交/忽略产物。- PARTIAL 来源 Pod 在 FINDINGS.md 头部被标记,绝不作为 COMPLETE 静默合并。
- 依据每个 Pod 的 excludes: 声明检测 scope 异常,将其排除出 FINDINGS.md,异常本身记录在 findings-state.json。
- 收敛算法是确定性的——相同输入始终产生相同的 FINDINGS.md 和 findings-state.json。
- 合并发现继承贡献来源中的最高优先级层级和最大工作量估算。
$pivot clear归档而非删除当前 FINDINGS.md。
反合理化
| 诱惑 | 为何错误 |
|---|---|
| 用 LLM 判断两条发现是否"足够接近"可合并 | 三遍算法按设计是确定性的——在此引入 LLM 判断会重新引入 CocoPivot 旨在消除的不可复现性 |
| 将 PARTIAL Pod 的零发现呈现为等同于 COMPLETE Pod 的零发现 | 二者代表结构上不同的置信水平——相同呈现是对覆盖情况的不诚实 |
| 静默丢弃 scope 异常发现而不记录 | 异常本身即是信号——持续产生被排除类别发现的 Pod 需要重新审视其提示或工具范围,这需要可见记录 |
在 $pivot clear 时删除而非归档 FINDINGS.md |
先前的收敛运行是历史记录——findings-archive/ 保留它们用于趋势分析 |
适用场景
适用于使用 CocoPlus 多 Pod 并行代码审计的工作流:需要将多个并行 Pod 的发现合并为单一权威清单、需要确定性可复现的收敛结果、需要追踪 PARTIAL 覆盖与 scope 纪律的场景。
限制
- 依赖 .cocoplus/ 初始化,未初始化时无法运行。
- 去重算法为确定性三遍规则,不依赖 LLM 判断。
- 无 excludes: 声明的 Pod 无法进行 scope 纪律评估,会被标记为 "unscoped"。
- 关于收费、价格、平台支持等信息,资料中暂未提供。