SuperAPI AI 工具集

cococonverge

编程与开发

查看项目

更新于 10-23 23:07

技能介绍

用途

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 输出应用三遍处理:

  1. Pass 1 — 相同 file:line 匹配:两条发现引用同一文件的同一行号,视为同一底层问题。取贡献来源中的最高严重级别,保留最详细的描述,引用所有贡献 Pod 名称及其原始发现 ID。
  2. Pass 2 — 同文件内相同问题类型:来自同一文件、引用相同问题类型(如 "SQL injection"、"missing null check"、"N+1 query pattern")的两条发现,即使行号略有不同也视为同一问题。合并为一条发现并整合引用,保留最能精确定位问题的描述。
  3. 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"。
  • 关于收费、价格、平台支持等信息,资料中暂未提供。