# 插件兼容清单

这份清单回答一个问题：**这个第三方插件在手机上能不能用、为什么不能、该谁修。**

它不是适配包目录（那是 `catalog.json`），也不是插件推荐榜。条目只记录适配结论与证据，不排名、不打分。

```bash
dsh-adapt-packs compat                  # 全部条目
dsh-adapt-packs compat --verdict pack    # 只看本仓库有包的
dsh-adapt-packs compat --json            # 机器可读
```

数据在仓库根目录的 [`compat.json`](../compat.json)，一个插件一条。

## 四种结论

| verdict | 含义 | 谁来修 |
| --- | --- | --- |
| `native` | 原生在手机上就可用，不需要任何干预 | 不用修 |
| `pack` | 本仓库有对应适配包（`pack` 字段给出包 id） | 装包即可 |
| `upstream` | 能改，但只能由插件作者改（自有类名、固定宽度、hover-only 等） | 上游 PR / issue |
| `blocked` | 当前架构下做不了：自绘 canvas、原生控件、DOM 不可达 | 无解，记录原因 |

`upstream` 是**建议**，不是判决：上游有权不采纳，清单里只写"改哪里、为什么"。

## 一条记录长什么样

```jsonc
{
  "plugin": "dshmarket",            // npm 包名（尽量带 scope）
  "name": "插件市场",                // 中文短名，给人看的
  "version": "1.73.3",              // 结论对应的版本；版本一变结论可能失效
  "range": ">=1.73.3 <1.74.0",      // 可选：结论覆盖的范围
  "verdict": "pack",
  "pack": "dshmarket-mobile",       // verdict=pack 时必填
  "category": "market",             // 可选：和 awesome 列表的分类对齐
  "summary": "一句话说清结论依据",
  "mobile": "手机上的具体表现（尺寸、哪个控件、多大）",
  "evidence": "证据等级：实测 / 代码阅读 / 未验证；没实测就写没实测",
  "links": { "repo": "…", "npm": "…" }
}
```

## 判定标准

1. **A 档（能装包）**：面板根有 `data-dsh*` 标记，包可以只靠宿主标记点名，不碰插件私有类名。
2. **B 档（只能上游改）**：DOM 有标记但都是自有类名 / CSS Module 哈希，或问题在布局策略（固定宽度、hover-only、面板外溢）。
3. **做不了（blocked）**：内容在 canvas / 原生控件里，或者根本没有面板 DOM。

第 1 条是硬门槛：`check-pack` 的静态层不允许包点名第三方类名，所以不是 `data-dsh*` 的插件就只能走上游。

## 怎么提交一条

**只接受可复核的东西。** 一条记录至少要有：

- 插件名 + 版本号（`npm view <pkg> version`，或你本地装的那个版本）；
- 屏幕上看到的具体数字或现象（"搜索框 154×24" 比 "太小了" 有用）；
- 在哪种环境下看到的：真机（机型/系统/WebView 版本）、或 headless 的视口尺寸（如 390×844）。

提交方式二选一：

- 开一个 [插件适配建议](https://github.com/LUgABeEEE/dsh-adapt-packs/issues/new?template=compat-suggestion.yml) issue，附截图或数字；
- 直接改 `compat.json` 提 PR —— 用 `dsh-adapt-packs compat --json` 看格式，`node tools/cli.mjs list` 会在 `prepublishOnly` 里跑，`compat.json` 的 JSON 解析也会被 CI 顺带验到。

**不要做**：不写"很好用/很差"这类评价（只写事实）；不写营销词；不确定的标成 `[推断]` 而不是事实。

## 维护约定

- 结论随版本漂移：条目里的 `version` 是**结论成立的那个版本**，升级后如果没复核，改 `evidence` 说明"未在新版本复核"，别默认它仍然成立。
- 删除条目前先确认：是插件不再维护、还是结论本来就不对。两者都该写明原因。
- `pack` 条目必须能在 `catalog.json` 里找到对应包；CI 的 catalog 一致性检查会挡住对不上的情况。