# ADR-0005: 社区测试套件市场 — 拉取式 CLI + 单仓索引 + 严格 TI

**状态**: 已采纳
**日期**: 2026-05-04
**参与者**: roger, Claude

## 背景

ROADMAP Phase 6 列了「测试用例市场 / 社区共享」。「市场」的形态可以从 README 列一份外部分支链接（零基础设施）一直延伸到带签名、检索、评分、发布 API 的完整注册中心（多月工作量）。

当前现状：

- 单人维护，没有外部贡献者。
- 现有 `test_suites/` 已经覆盖 OpenClaw 端到端评测，社区贡献还没有真实需求。
- 装一份「真注册中心」会立刻引入签名密钥管理、CDN/对象存储、发布鉴权这些维护负担。

需要在「能让外部 PR 共享测试套件」和「不为想象中的需求过度建设」之间找一个最小可用解。

## 决策

承重的三个判断：

1. **分发深度**：拉取式 CLI（`agentsec suite install <name>`），不做完整注册中心。Bundle 托管在贡献者自己的公开 GitHub 仓库里；本仓只持有索引和审计后的哈希。
   - 否决：纯 README 链接列表 — 没有产品面，安装路径不可复现。
   - 否决：完整注册中心 — 在没有需求证据之前就引入签名密钥和发布 API，过度工程化。

2. **索引位置**：单一 `community-suites.yaml` 放在主仓 `src/agentsec/suite_registry/`，外面包一个细 `Registry` 接口。`--registry-url` 参数保留但隐藏，仅用于开发与测试，生产环境只读 wheel 内置的索引。
   - 否决：独立 `agentsec-community` 仓 — 单维护者下会让维护面翻倍；如果未来需求增长，`Registry` 接口本身就是切换点。

3. **TI 依赖策略**：严格 — 社区套件 `threat_refs_required` 列出的每一个 TI ID 必须已经存在于主仓 `src/agentsec/audit/ioc/threat_intel.yaml`。
   - 否决：sidecar TI 片段（让 bundle 自带 TI 行）— 因为 `threat_intel.yaml` 是评分输入（`version_patch` 严重度、KEV 升级），允许未审计 bundle 注入 TI 行等价于让外部代码影响评分。

## 后果

**正面**：

- 新增表面最小：复用 PR review 作为信任机制；不需要新的基础设施；不需要管理签名密钥。
- 故障模式显式：所有失败都映射到 typed exception（`SuiteHashMismatch` / `SuiteTIRefMissing` / `SuiteValidationError` 等）。
- 升级路径清晰：未来切到独立社区仓，只需要新增一个 `Registry` 实现，CLI 表面无需变化。

**负面**：

- 索引更新随 AgentSec 版本走（用户必须升级才能看到新条目）。可以接受，因为社区套件目前每月增量很少，且 `agentsec ioc-update` 也是同样的发布节奏。
- 如果贡献者的 case 引用了主仓还没有的 TI ID，需要提交两个 PR（一个加 TI 行、一个加索引条目）。已在 `contributing-a-suite.md` 中明确写出来。
- 不签名意味着信任链根植在「pinned hash + maintainer review」上。如果哪天外部贡献者数量起来，这套机制会捉襟见肘 —— 那时候再重新看 (1)/(2) 就行。

如果索引超过约 20 条且有多个活跃贡献者，重新评估第 (1)、(2) 项：独立社区仓配独立 CI 可能就成了更合理的选项，`Registry` 抽象本身是无成本的切换点。
