# README 第三方 Badge 准入标准

## 目的

本文件用于规范 `README.md` / `README.en.md` 首页 badge 的准入标准，避免：

- 首页信息被营销型 badge 挤占
- 双语 README 展示不一致
- 对第三方平台形成无意背书
- 未来遇到类似 PR 时重复临时判断

适用范围：

- 第三方平台提交的 badge PR
- 维护者主动考虑新增的外部 badge
- 任何会出现在 README 首页首屏 badge 区域的展示项

---

## 当前案例评估：PR #194 `Add MseeP.ai badge`

### 变更内容

- 来源：外部 PR `#194`
- 目标：在 `README.md` 顶部增加 `MseeP.ai` 第三方 badge
- 变更范围：仅修改中文 `README.md`

### 评估结论

**当前不合入主线**，归类为：`backlog / not planned`

当前远端状态：

- `PR #194` 已于 `2026-04-30T08:27:16Z` 关闭
- 未合并入 `master`

### 不合入原因

1. **不直接提升产品能力或接入体验**
   - 该 badge 不改善 CLI 功能、协议契约、测试覆盖、安装路径、排障路径或 Agent 集成。

2. **属于第三方营销 / 目录展示，不是系统真源**
   - README 首页 badge 应优先展示“项目当前状态”的真源信号，例如 CI、发布、许可证、包分发、覆盖率。
   - `MseeP.ai` badge 指向的是第三方目录页，不是当前仓库自身的第一手状态源。

3. **双语不对称**
   - PR 只修改 `README.md`，没有同步 `README.en.md`。
   - 首页级 badge 默认要求中英文 README 对称更新，除非 badge 仅服务于单语受众且有明确理由。

4. **公开方法论不足以支撑首页背书**
   - 在本轮评估中，公开可见信息能说明 `MseeP.ai` 是一个 MCP 目录 / 评分站点，但不足以证明其 badge 代表的评分机制、更新频率、误报处理和项目 claim 后的治理边界。
   - 在方法论没有足够透明之前，不适合把它提升到 README 首页背书位。

5. **与当前主线优先级不一致**
   - 当前仓库主线集中在：能力边界真值、平台抽象、Agent 集成、测试与执行纪律。
   - 该 badge 不属于当前主线的高优先级事项。

### 未来可重新评估的前提

满足以下任一条件后，可重新考虑：

- 维护者明确制定“第三方信誉 / 目录 badge”统一策略
- 对方提供清晰、可公开验证的评分方法、更新频率和申诉 / claim 机制
- 中英文 README 同步更新
- 能证明该 badge 对真实用户决策有明显帮助，而不只是外部导流

---

## 准入原则

README 首页 badge 的默认原则是：

**少而准，优先展示项目真状态，不展示未经统一策略批准的第三方背书。**

### 一类：默认允许

满足以下用途之一的 badge，可默认进入候选：

- **构建 / 质量真状态**
  - 例如：GitHub Actions、Codecov
- **分发 / 版本真状态**
  - 例如：GitHub Release、PyPI
- **许可证 / 兼容性信息**
  - 例如：License、Python 版本
- **项目贡献入口**
  - 例如：Contributors、PRs Welcome

这些 badge 的共同特征是：

- 信号来源明确
- 与项目使用或贡献直接相关
- 维护成本低
- 用户能快速理解其含义

### 二类：默认不允许

以下 badge 默认不进入 README 首页：

- 第三方目录站导流 badge
- 营销型 / 品牌合作型 badge
- 含糊的“Trust / Verified / Secure”类 badge，但无公开方法论
- 需要额外注册、claim 或商业关系才能维持语义稳定的 badge
- 只对维护者有意义、但对初访用户几乎无帮助的 badge

---

## 准入检查清单

任意第三方 badge，必须至少同时满足以下条件，才可进入“考虑合入”阶段：

### 1. 用户价值明确

必须能回答以下至少一个问题：

- 这个项目现在能不能用？
- 当前构建 / 发布 / 分发状态是什么？
- 用户应该通过什么渠道安装或验证版本？
- 这个 badge 是否能显著降低用户判断成本？

如果答案只是“能让仓库看起来更丰富”或“给第三方平台导流”，则不通过。

### 2. 信号来源是真源或可审计来源

优先级：

1. 项目自身系统真源
   - GitHub Actions
   - GitHub Releases
   - PyPI
   - 官方文档站
2. 行业广泛接受且语义明确的中立来源
3. 其他第三方来源

第三方来源若不是系统真源，需提供额外解释其必要性。

### 3. 方法论公开透明

若 badge 传达的是评分、信任、安全、验证类信号，必须能公开回答：

- 评分怎么算
- 更新频率是什么
- 数据源是什么
- 是否允许 claim / 更正
- 误报 / 争议如何处理

如果这些信息在公开页面上找不到，默认不通过。

### 4. 双语 README 对称

若 badge 出现在首页首屏：

- `README.md`
- `README.en.md`

默认必须同步更新，除非有明确的单语例外说明。

### 5. 维护成本可接受

badge 必须满足：

- URL 稳定
- 无登录依赖
- 不依赖易失的个人配置
- 不需要频繁人工同步
- 即使第三方服务异常，也不会明显破坏 README 可读性

### 6. 不形成未经批准的背书

如果 badge 会让用户自然理解为：

- 项目官方认可该第三方
- 项目愿意为其评估结论背书
- 项目未来会持续维护该外部关系

则必须经过维护者明确批准，不能因第三方自动 PR 而默认合并。

---

## 决策规则

### 可合入

仅当以下条件同时满足时，才可合入：

- 用户价值明确
- 来源是真源或可审计来源
- 方法论足够透明
- 中英文 README 同步
- 不会引入额外背书风险

### 暂不合入

满足任一情况即可判为暂不合入：

- 主要价值是营销或导流
- 只改一个语言版本 README
- 评分 / 安全 / 信任语义不透明
- 与当前 roadmap 主线无关
- 需要先有统一第三方 badge 策略

### 建议关闭

满足以下任一情况，建议直接关闭 PR：

- 外部自动 PR，仅增加第三方导流 badge
- 无方法论说明，且价值无法量化
- 与现有首页信息架构冲突
- 经评估后明确不进入当前主线

---

## 处理流程

以后遇到类似 PR，按以下顺序处理：

1. 查看 diff
   - 改了哪些 README
   - 是否只加 badge，还是同时补充解释

2. 核对来源
   - 是 GitHub / PyPI / Codecov 这类真源，还是第三方目录站

3. 核对公开方法论
   - 对“评分 / 安全 / 信任”类 badge 必做

4. 套用检查清单
   - 逐项判断是否通过

5. 输出明确结论
   - merge
   - backlog / not planned
   - close with comment

---

## 推荐回复模板

### 暂不合入 / 关闭 PR

```text
感谢提交。我们评估后认为，这个 badge 当前更偏第三方目录展示 / 导流，不属于 README 首页必须呈现的项目真状态信息；同时它也还没有满足我们对双语同步和公开方法论透明度的要求。因此这次先不合入主线。若后续我们建立统一的第三方 badge 策略，再重新评估。
```

### 需要补充信息再评估

```text
感谢提交。为了评估这类第三方 badge 是否适合进入 README 首页，我们还需要以下信息：评分方法、更新频率、claim / 更正机制，以及是否同步支持 `README.en.md`。补充这些信息后，我们可以继续评估。
```
