# dsh-agent-teams-fish v0.6.1

**修复在 DSH `0.2.1-alpha.2` 上被整行禁用的问题**：`compatibility.json` 的 `supportedHosts` 与全部 21 条 `@deepseek-ai/dsh-*` peer 白名单此前未收录该版本，DSH 判定不兼容并**自动停用插件行**。

## 症状

升级 DSH 到 `0.2.1-alpha.2` 后，宿主日志出现：

```text
dsh: disabling profile plugin row "agent-teams": Plugin dsh-agent-teams-fish@0.6.0
is incompatible with dsh 0.2.1-alpha.2: peerDependencies { … }
```

面板上插件显示「异常」，**AgentTeams 团队协作完全不工作** —— 但这不是崩溃，是 DSH 的**主动保护**：声明面没跟上运行时，它宁可停用也不冒着崩溃或数据损坏的风险加载。

## 根因

本仓库用 `compatibility.json` 作为**单一事实源**，并由 `scripts/compatibility.mjs` 强制一条不变量：

> 每条 `@deepseek-ai/dsh-*` 的 peer 范围必须**精确枚举** `supportedHosts`（+ sourceCandidates）里的每一个版本。

校验逻辑（`validatePackageCompatibility`）：

```js
const declared = range.split('||').map(value => value.trim())
if (declared.length !== declaredVersions.length
    || declaredVersions.some(version => !declared.includes(version))) {
  throw new Error(`${name} peer range must enumerate the supported host targets and source candidates`)
}
```

DSH 运行时升到 `0.2.1-alpha.2` 后，这个枚举列表没有跟上 —— **插件代码本身没有任何缺陷**。

**为什么不能写成 `>=0.2.0-rc.2` 一劳永逸**：DSH 用 `includePrerelease` 语义比较，宽范围会宣称「与**所有**未来版本兼容」，而本仓库的立场是**逐版本实测后再声明**。所以新增宿主必须显式列出。

## 修法

1. **`compatibility.json`**：把 `0.2.1-alpha.2` 以 `track: "preview"` 加入 `supportedHosts`。
   - `recommendedHost` **保持** `0.2.0-rc.2` 不动 —— `validatePolicy` 明确禁止 alpha / beta 充当普通用户推荐目标。
2. **`package.json`**：给全部 **21** 条 `@deepseek-ai/dsh-*` peer 范围追加 `|| 0.2.1-alpha.2`（按既有约定放在最前）。
3. `scripts/compatibility.mjs` 门禁会**强制**第 2 步：只改 `compatibility.json` 而漏改 peer，立刻红。

## 验证

```powershell
node scripts/compatibility.mjs
# Compatibility targets: 0.2.0-rc.2, 0.2.1-alpha.2, 0.1.7-rc.2, …  rc=0
```

- **TDD 红→绿**：先只改 `compatibility.json` → 门禁报 `@deepseek-ai/dsh-agent peer range must enumerate the supported host targets`（红）→ 补齐 21 条 peer → 转绿。
- `scripts/compatibility.test.mjs`：**10 通过 / 1 失败**。那 1 个失败是 `doctor runs through an installed bin symlink`（Windows 建符号链接需开发者模式，`EPERM`）—— 在**未改动的上游克隆** `at-upstream` 里跑出**完全相同**的 10 / 1，证明是既有的环境限制，非本次回归。
- 运行时依赖实核：本插件编译产物只 value-import 两个包 —— `@deepseek-ai/dsh-llm`（`createUserMessage`）与 `@deepseek-ai/schemastery`（default），两者在新宿主上均照常导出。其余 `@deepseek-ai/*` 均为**类型导入**（编译期擦除）。

## 兼容性约定（供后续维护）

| 项 | 值 |
|---|---|
| `recommendedHost` | `0.2.0-rc.2`（稳定线，普通用户推荐） |
| 新增支持 | `0.2.1-alpha.2`（`preview` 轨道） |
| 已验证的历史宿主 | `0.1.7-rc.2` / `0.1.5-rc.3` / `0.1.5-rc.2` / `0.1.5-rc.1` / `0.1.2-rc.1` / `0.1.2-alpha.5` / `0.1.2-alpha.2` |

> **下次 DSH 升版时**：改 `compatibility.json` 一处 → 跑 `node scripts/compatibility.mjs` 让门禁把该改的 21 条 peer 全部点名 → 补齐 → 绿。