knowledge: reconcile and integrate all pending knowledge updates

doc/architecture/SPEC/contract.md

@@ -1,8 +1,8 @@
 # contract.py —— 规范
 
-<!-- verified-against: 2026-09-11 -->
+<!-- verified-against: 2026-09-22 -->
 
-`LOC ~185 · 旧版跨仓库契约兼容层 · refactor-status: compatibility-shim`
+`旧版跨仓库契约兼容层 · refactor-status: compatibility-shim`
 
 ## 职责
 本 copilot 的**旧版对外消费契约兼容层**。新宿主只允许 import
@@ -13,7 +13,7 @@
 
 ## 公开契约（`__all__`）
 `SDK_API_VERSION` / `DIRECT_API_VERSION` / `STRICT_API_VERSION` /
-`QUALITY_API_VERSION` / `KNOWLEDGE_API_VERSION`（当前前四者为 `"1.0.0"`，Knowledge 为 `"1.1.0"`，且都从 `sdk.v1.models`
+`QUALITY_API_VERSION` / `KNOWLEDGE_API_VERSION`（SDK、Direct、Quality 为 `"1.0.0"`，Strict 为 `"1.2.0"`，Knowledge 为 `"1.1.0"`，且都从 `sdk.v1.models`
 取唯一值）。`capabilities(max_strict_workers=1,
 supports_file_locking=True) -> dict` 委托 SDK typed handshake 再投影为兼容
 dict；它包含 distribution/SDK/Direct/Strict/Quality/Knowledge 版本、resource
@@ -22,10 +22,10 @@ revision、supported repositories，以及 `supports_expected_head`、
 `supports_idempotent_strict_start`、`supports_knowledge_curation`、
 `max_strict_workers`。其余兼容导出包括 `build_review_result(run_dir) -> dict`（结构化评审
 结果：`contract_version`、`run_id`、`state`、`reviewed_head_sha`、`verdict`、
-`summary_markdown`、`comments`、`finding_dispositions`、
+`summary_markdown`、`comments`、`finding_dispositions`、`findings`、
 `stale`/`expected_head_sha`/`actual_head_sha`、`diagnostics`）；`unknown_run_result(run_id)`（显式
 `state: unknown`，绝不抛错 —— 丢响应和还在跑必须可区分）；
-`sanitize_comments` 与 `COMMENT_FIELDS`；以及从 `direct_routing` 再导出的
+`sanitize_comments` 与 `COMMENT_FIELDS`，以及 `finding_id` / `build_findings`；另有从 `direct_routing` 再导出的
 `direct_knowledge_routes` / `direct_execution_budget` /
 `direct_completion_result` / `direct_mandatory_review_guides` / 完整的
 `direct_review_plan`。
@@ -51,6 +51,14 @@ revision、supported repositories，以及 `supports_expected_head`、
   凭据——每个候选一条 `{anchor, disposition, declared}`，按
   `DISPOSITION_FIELDS` 白名单投影，被撤下的评论正文本身绝不过界。
   消费方因此无需把散文里的取舍和手上的列表对账（#141）。
+- `findings` 按发布顺序对每条最终评论输出
+  `{finding_id, severity, anchor, head_sha}`。identity 取文件路径与完整评论文本
+  （合并空白并 casefold）的 SHA-256 前 16 个 hex，不包含行号；anchor 是
+  `{path, line}`，无文件时为 `None`。severity 使用最终发布值，head 绑定
+  `pr_head_sha`。保留重复 identity，不与按 anchor 记账的 disposition 做 join，
+  避免同位置的撤下候选污染已发布 finding。评审前失败的 run 返回空列表。
+- 当前没有 carried finding 的显式复查生产链，因此不返回 `carried_from`、
+  `head_recheck` 或 `findings_missing_carried`；不能把结果中缺少旧 finding 当作已修复。
 - 本模块自身保持仓库中立；仓库专属的 Direct 路由表住在
   `direct_routing.py`（见其页）。
 - 能力身份的权威实现在 `sdk.v1.get_capabilities`；这里不维护第二份版本或
@@ -70,9 +78,9 @@ revision、supported repositories，以及 `supports_expected_head`、
 新的 Direct helper → 在 `direct_routing` 实现、在这里再导出。
 
 ## 测试
-`test_contract.py`（23 例：verdict 字段化、评论白名单、stale 即终局事实、
+`test_contract.py`（覆盖：verdict 字段化、评论白名单、stale 即终局事实、
 早死 run 的降级结果、unknown-run 显式化、能力上报、import 方向、
-本模块仓库中立）。
+本模块仓库中立、finding identity/最终 severity/head 绑定、重复保留与 disposition 隔离）。
 
 ## 重构备注
 新模块（PR2 mixed-mode contract 拆分）。保持它薄：任何"顺手在这里实现"

doc/architecture/SPEC/sdk.md

@@ -1,6 +1,6 @@
 # sdk/ —— 规范
 
-<!-- verified-against: 2026-09-11 -->
+<!-- verified-against: 2026-09-22 -->
 
 
 `Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
@@ -51,6 +51,11 @@
 - **Strict created 语义真实**：SDK 从 core 的 `(run_id, created)` 读取；命中
   idempotency key 的重试返回 `created=False` 且绝不再次入队。review depth 只经
   policy allowlisted `params` 传入。
+- **Strict findings 绑定发布结果**：`get_result` 的 `findings` 对最终发布集合逐条返回
+  `finding_id`、最终 `severity`、`anchor` 与 `head_sha`，保持顺序及重复 identity。
+  identity 以文件路径与完整归一化文本生成，行号变动不改变 identity；它不与
+  `finding_dispositions` 按 anchor 拼接。当前没有 carried-finding recheck，缺失旧
+  finding 不代表已修复；不得承诺 `head_recheck` 或 `findings_missing_carried` 字段。
 - **知识规则由 provider 唯一定义**：catalog 只暴露当前仓库 owner 与 general 的
   owner rule page document ID —— 每个 owner 的 `rules.md` 入口页及其
   `type: rule` 的 `rules-<topic>.md` 专题页（`catalog_entries()` 附每页
@@ -76,8 +81,8 @@
   push、开 PR 或 schedule。ReviewBot 必须向 `KnowledgeCurator` 传 dedicated work
   checkout，并继续拥有重试、artifact 与 fork publication；SDK 也绝不写 packaged
   knowledge tree。
-- SDK、Direct、Quality API 版本常量为 `1.0.0`；Strict 为 `1.1.0`
-  （结果新增 `finding_dispositions`，#141），Knowledge 为 `1.1.0`
+- SDK、Direct、Quality API 版本常量为 `1.0.0`；Strict 为 `1.2.0`
+  （1.1 新增 `finding_dispositions`；1.2 新增 `findings`），Knowledge 为 `1.1.0`
   （1.1 向后兼容地新增 `catalog_entries()` / `KnowledgeCatalogEntry` 与容量预检），
   distribution 为 `0.2.0`；`Capabilities.knowledge_api_version` 与
   `supports_knowledge_curation` 组成 ReviewBot 的 paired-release 握手，避免只按

knowledge/general/bug/guides/di-calculation.md

@@ -1,7 +1,7 @@
 ---
 title: "DI 计算说明"
 created: 2026-08-07
-updated: 2026-08-07
+updated: 2026-09-22
 type: guide
 tags: [general, bug]
 sources: []
@@ -17,9 +17,9 @@ sources: []
 | Bug 优先级分类 | 划分标准 | DI 值 | SLO |
 |---|---|---|---|
 | critical | 高优先级 | 10 | 1 天 |
-| high priority | CI Failure | 3 | 3 天 |
-| medium priority | 中优先级 | 1 | 5 天 |
-| low priority | 低优先级 | 0.1 | 10 天 |
+| high priority | CI Failure | 3 | 5 天 |
+| medium priority | 中优先级 | 1 | 10 天 |
+| low priority | 低优先级 | 0.1 | 14 天 |
 | invalid | 非问题 | 0 | / |
 
 ## 其他规则

knowledge/repos/vllm-omni/benchmark/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni 性能与 Profiling"
 created: 2026-07-10
-updated: 2026-09-21
+updated: 2026-09-22
 type: index
 tags: [vllm-omni, benchmark]
 sources: [benchmarks/tts/bench_tts.py, benchmarks/tts/model_configs.yaml, "PR #6522", "PR #6634", "PR #6818", vllm_omni/benchmarks/data_modules/omniinteract_dataset.py, vllm_omni/benchmarks/omniinteract.py, vllm_omni/benchmarks/patch/patch.py, tests/benchmarks/patch/test_patch.py, vllm_omni/benchmarks/duplex/, vllm_omni/entrypoints/cli/benchmark/omni_duplex_eval.py, vllm_omni/experimental/fullduplex/client.py]
@@ -21,7 +21,7 @@ sources: [benchmarks/tts/bench_tts.py, benchmarks/tts/model_configs.yaml, "PR #6
 
 | 遇到什么 | 查看哪里 |
 |---|---|
-| 新增/审查 perf JSON、warmup 覆盖、realtime artifact、Hub dataset fallback、per-request timeout 或 `/v1/videos` 轮询预算、最终性能复测与控制漂移 | [benchmark rules](rules.md) |
+| 新增/审查 perf JSON、warmup 覆盖、realtime artifact、Hub dataset fallback、per-request timeout 或 `/v1/videos` 轮询预算、最终性能复测与控制漂移 | [benchmark rules](rules.md)   新增核对：BENCH-1f2、BENCH-1g。 |
 | 查看旧 benchmark 总览 | [overview](overview.md) |
 | 运行 AR graph、Hunyuan 或 MiniCPM-o Omni-DuplexEval benchmark | [benchmark guides](guides/_index.md) |
 | 调查 profiling、模型加载和性能验证错误 | [benchmark incidents](incidents/_index.md) |

knowledge/repos/vllm-omni/benchmark/rules.md

@@ -1,10 +1,10 @@
 ---
 title: "vLLM-Omni Benchmark 规则"
 created: 2026-09-05
-updated: 2026-09-21
+updated: 2026-09-22
 type: rule
 tags: [vllm-omni, benchmark]
-sources: ["PR #7648", "PR #6817", tests/dfx/perf/scripts/run_benchmark.py, tests/benchmarks/test_omniinteract.py, "PR #7130", "PR #7259"]
+sources: ["PR #7648", "PR #6817", tests/dfx/perf/scripts/run_benchmark.py, tests/benchmarks/test_omniinteract.py, "PR #7130", "PR #7259", "PR #7624", "PR #7504"]
 confidence: high
 ---
 
@@ -72,3 +72,17 @@ confidence: high
   determinism 或 eager 数值等价证明。
 - 验收：产物能追溯各 arm 的真实 source/config/environment，报告候选差值和控制漂移；
   稳态统计可从相同筛选重算，正确性另由对应 parity 测试支持。 ^[PR #7648]
+
+## BENCH-1f2 — benchmark 结果必须始终导出样本计数，包括零
+
+- 触发：修改 `benchmarks/patch` 的 result dict，或 DFX 对 `num_tpot_samples` 等计数字段的读取。
+- 强制：`calculate_metrics()` 已经产出的 `num_ttft_samples`、`num_tpot_samples`、`num_itl_samples`、`num_audio_ttfp_samples`、`num_audio_rtf_samples` 必须写入结果，包括 0，且与 percentile 是否被选中无关。JSON 往返后字段仍在。缺键是 `None`，不是 0；DFX 在 finite `mean_tpot_ms` 下仍会因 `isinstance(None, int)` 失败。
+- 禁止：只在选中 TPOT/ITL percentile 时写出计数；用均值存在代替样本数字段；改 DFX 判定去迁就缺字段的 JSON。
+- 验收：真实聚合加 JSON round-trip，分别覆盖 measured/unmeasured TPOT 与选中/未选中 percentile；省略 `num_tpot_samples` 而保留 finite mean 的结果必须被 baseline 拒绝。^[PR #7624]
+
+## BENCH-1g — duplex/eval 媒体解码必须用捆绑 PyAV，不得依赖 host ffmpeg
+
+- 触发：修改 `omni-duplex-eval` 或同类 benchmark 的视频时长、帧抽取、音频 PCM 解码，或重新引入 `ffmpeg`/`ffprobe` subprocess。
+- 强制：媒体路径经 PyAV（`av`）打开/seek/decode/resample；结果不得依赖主机安装的 ffmpeg 版本。帧抽取语义对齐“首个 PTS ≥ 目标时刻”；非 WAV 音频经 `AudioResampler` 并在循环后 `resample(None)` flush 尾部样本。
+- 禁止：`subprocess` 调用 host `ffmpeg`/`ffprobe` 作为默认路径；把“本机 ffmpeg 能跑”当作可复现证据；在已知会挂起的旧 HEVC decoder 上无超时地阻塞 generate 阶段。
+- 验收：覆盖 duration/JPEG/PCM 合同与失败 raise；至少用曾触发 host ffmpeg 4.4.2 挂起的样本证明不再无限忙等。^[PR #7504]

knowledge/repos/vllm-omni/ci/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni CI"
 created: 2026-07-10
-updated: 2026-09-21
+updated: 2026-09-22
 type: index
 tags: [vllm-omni, ci]
 sources: [.buildkite/cuda/pipeline.yml, docs/contributing/ci/test_system_overview.md, tests/diffusion/quantization/test_svdquant_config.py, tests/diffusion/quantization/test_svdquant_linear.py, tests/diffusion/quantization/test_svdquant_tp_loading.py, tests/diffusion/quantization/test_wan_autoround_mxfp4.py, tests/e2e/offline_inference/test_wan21_autoround_mxfp4.py, "PR #5544", "PR #6162", "PR #6170", "PR #6303", "PR #6390", "PR #6613", .buildkite/cuda/test-nightly.yml, tests/e2e/online_serving/run_minicpmo_realtime_duplex_server_vad.py, tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py, tests/e2e/online_serving/test_qwen_image_expansion.py, tests/dfx/perf/tests/test_qwen_image_vllm_omni.json, tests/platforms/npu/test_diffusion_attn_backend_selector.py, "PR #6054", .buildkite/cuda/test-merge.yml, .buildkite/cuda/test-ready.yml, tests/e2e/online_serving/test_hunyuan_video_15_expansion.py, tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json, tests/dfx/perf/tests/test_hunyuanvideo15_i2v_vllm_omni.json, "PR #6349", .buildkite/amd/scripts/bootstrap-amd-omni.sh, .buildkite/amd/test-amd-merge.yml, .buildkite/amd/test-amd-ready.yml, tests/diffusion/distributed/test_tensor_parallel.py, tests/diffusion/offloader/test_diffusion_layerwise_offload.py, tests/helpers/clean.py, "PR #6704", tests/model_executor/models/minicpmo_4_5/test_pipeline.py, tests/model_executor/stage_input_processors/test_minicpmo_4_5_async_chunk.py, "PR #5464", "PR #6730", "PR #6745", "PR #6727", tests/diffusion/quantization/test_quantization_quality.py, "PR #5831", tests/dfx/perf/tests/test_qwen3_omni_async_chunk.json, tests/dfx/perf/tests/test_qwen3_omni_no_async_chunk.json, "PR #6743", tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py, "PR #6742", "PR #6650", pyproject.toml, tests/helpers/mark.py, tests/helpers/tests/test_mark.py, tools/pre_commit/check_test_marks.py, "PR #6174", .buildkite/cuda/test-weekly.yml, tests/e2e/offline_inference/test_dots_tts_expansion.py, "PR #6556", tests/e2e/online_serving/minimax_h3/]
@@ -209,11 +209,15 @@ sources: [.buildkite/cuda/pipeline.yml, docs/contributing/ci/test_system_overvie
 
 | 遇到什么 | 查看哪里 |
 |---|---|
-| 审查硬件 lane（含 MiniMax-H3 DLO DP2 ready smoke 的证据边界）、回归 fence、CI 工具供应链、ASR 文本比较或 xdist/shared fixture、Buildkite 失败日志与运行时差异 | [CI rules](rules.md) |
-| AMD/ROCm timeout、quarantine、memory signal、single-card diffusion job 的 multi-card marker 排除、Qwen3-TTS argv 或 Qwen3-Omni control-plane fixture | [AMD/ROCm CI rules](rules-amd.md) |
+| 审查硬件 lane（含 MiniMax-H3 DLO DP2 ready smoke 的证据边界）、回归 fence、CI 工具供应链、ASR 文本比较或 xdist/shared fixture、Buildkite 失败日志与运行时差异 | [CI rules](rules.md)   新增核对：OMNI-CI-1g、OMNI-CI-1h。 |
+| AMD/ROCm timeout、quarantine、memory signal、single-card diffusion job 的 multi-card marker 排除、Qwen3-TTS argv 或 Qwen3-Omni control-plane fixture | [AMD/ROCm CI rules](rules-amd.md)   新增核对：OMNI-CI-2i、OMNI-CI-2i2、OMNI-CI-2i3、OMNI-CI-2i4。 |
 | CUDA L4 Kubernetes preset、GPU-count shard、resource/retry policy | [L4 Kubernetes CI rules](rules-l4-k8s.md) |
 | Whisper 转写 helper 的 GPU 首选、16 GiB 门槛、CPU fallback 或 CUDA ready/merge source dependency | [Whisper 转写 CI 规则](rules-whisper-transcription.md) |
 | 查看仓库特有 CI 陷阱 | [CI guides](guides/_index.md) |
 | 调查历史 CI 失败 | [CI incidents](incidents/_index.md) |
 
 - [CI 并行测试与 engine fixture 合同](rules-test-fixtures.md)：`OMNI-CI-2b`, `OMNI-CI-2c`, `OMNI-CI-2d`, `OMNI-CI-2h`。
+
+- [rules-review-validation](rules-review-validation.md) 新增核对：VOMNI-CI-1a、VOMNI-CI-1b。
+
+- [release-gates](release-gates.md)：维护者分工与发布政策。

knowledge/repos/vllm-omni/ci/release-gates.md

@@ -0,0 +1,34 @@
+---
+title: "发布规范"
+created: 2026-08-28
+updated: 2026-09-22
+type: guide
+tags: [vllm-omni, ci]
+sources: ["https://github.com/JiusiServe/InferMatrixCopilot/pull/70"]
+---
+
+# 发布规范
+
+vLLM-Omni 版本 **release 前**必须满足以下门禁。标注 `(Guide)` 的项按当期迭代指南解释与举证；其余为硬性门槛。
+相关入口：[CI 索引](_index.md)、[DI 计算说明](../../../general/bug/guides/di-calculation.md)、[benchmark](../benchmark/_index.md)。
+
+## Release 前门禁
+
+| # | 要求 | 类型 | 说明 |
+|---|---|---|---|
+| 1 | UT coverage meets this iteration requirement | Guide | 单元测试覆盖率达到当期迭代要求；具体阈值与举证方式以当期 Guide 为准 |
+| 2 | Performance regression < 10% | Guide | 性能回退小于 10%；对比基线、指标与证据口径以当期 Guide 为准 |
+| 3 | Latest CUDA L1 & L2 & L3 & L4 & L5 (excluding Non-critical) pass rate = 100% | Gate | 最新一轮 CUDA L1/L2/L3/L4/L5 中，排除 Non-critical 后通过率必须为 100% |
+| 4 | Latest NPU L1 & L2 & L4 pass rate = 100% | Gate | 最新一轮 NPU L1/L2/L4 通过率必须为 100% |
+| 5 | Requirement completion rate > 85% | Gate | 需求完成率大于 85% |
+| 6 | Remaining DI < 30 | Gate | 剩余 DI 小于 30；DI 计算见 [DI 计算说明](../../../general/bug/guides/di-calculation.md) |
+| 7 | No remaining critical issues | Gate | 无未关闭的 critical 问题 |
+| 8 | All remaining bugs have assignees | Gate | 所有剩余 bug 均已指派负责人 |
+
+## 验收记录
+
+发布前在发布说明或 checklist 中逐项给出：
+
+- 是否通过（Pass / Fail / N/A）
+- 证据链接（CI run、benchmark 报告、需求看板、DI 统计、issue 列表）
+- Guide 项写明当期 Guide 版本或链接