# 01 · 产品策划书 — dsh-free-models-hub

> DeepSeek Harness 免费模型排行榜插件 · v0.1.0 策划案
> 配套文档：`02-技术方案` / `03-开发计划` / `04-代码审查清单` / `05-安全审查与验收` / `06-发布与升级指南`

---

## 1. 项目概述

### 1.1 一句话定位

在 DeepSeek Harness（DSH）Web UI 左侧边栏提供一个「免费模型排行榜」面板：站长在自己网站（PHP 7.4 + SQLite）维护免费模型清单，用户在 DSH 内浏览、分页查看、点击标题展开详情，一键把模型写入 DSH 的 设置 → 模型 → 自定义提供方，用户只需自行填写免费 Key。

### 1.2 背景与动机

- DSH 生态（GitHub topic: `dsh-plugin`）已进入开发者预览期，社区市场（dsh-market、DSH-Plugins-Marketplace 等）按 topic 收录并支持一键安装/更新。
- 大量用户想用第三方平台的免费额度模型，但手动到 Settings → Models 添加自定义提供方步骤繁琐、参数易错。
- 站长侧缺少一个"发布免费模型 → 用户一键接入"的分发通道。

### 1.3 目标用户

| 角色 | 描述 | 核心诉求 |
|---|---|---|
| 模型用户 | 安装了 dsh web 的终端用户 | 发现免费模型、少配置、只填 Key |
| 站长/管理员 | 运营免费模型清单的站长 | 后台手工增删改查、排序、上下架 |

### 1.4 非目标（Non-Goals）

- ❌ 不代理、不转发任何模型流量（纯配置分发，零数据中转）。
- ❌ 不收集、不存储、不接触用户的 API Key（Key 全程只在用户本地 DSH 凭据体系内）。
- ❌ 不做用户注册体系（后台仅单管理员）。
- ❌ 不修改 DSH 核心源码（一切通过官方插件机制挂载）。
- ❌ **后端不对外分发**：`server-php/` 为作者私有运营组件（.gitignore 排除），
  其他站长无法用它自建数据源；插件默认数据源即作者站点，安装即用。

---

## 2. 功能需求规格（FSD）

### F1 左侧边栏「免费模型排行榜」面板

- 位置：DSH Web UI 左侧边栏区域（slot 注入，见技术方案 §4.3），带折叠能力。
- 列表：每页 **10 条**，显示序号 + 模型标题（如 `1. GLM-5-Flash 免费额度`）。
- 数据来源：站长 PHP 后端的公开 JSON API（分页拉取，服务端分页）。

### F2 分页器

- 上一页 / 下一页按钮；首末页时对应按钮禁用。
- 数字页码 `1 2 3 4 5 …`，当前页高亮，可自由点击跳转。
- 「首页」「末页」快捷按钮。
- 页码窗口算法：总页数 ≤7 全显；否则以当前页为中心保留窗口并出现省略号。
- 显示统计文案：`共 N 个模型 · 第 x/y 页`。

### F3 详情展开（点击标题）

点击标题行展开卡片，展示：

| 字段 | 说明 |
|---|---|
| API 调用地址 | 站长填写的 baseURL（等宽字体展示，可复制） |
| 模型名称 | 站长填写的 model id（可复制） |
| 【点击这里申请免费密钥key】按钮 | 打开站长填写的第三方平台注册页链接（新标签页，`rel="noopener noreferrer"`） |
| 【一键配置到 DSH】主按钮 | 见 F4 |

再次点击标题收起。同一时刻允许多个展开（互不干扰）。

### F4 一键配置自定义提供方

- 行为：把该模型的 `baseURL / 模型名 / openai-completions 协议 / compat 安全默认值` 写入 DSH 用户设置 `llm-pi-ai.providers.<freehub-xxxx>`（Provider ID 由标题生成 slug，前缀可配）。
- 成功后 toast 提示：**"已写入提供方配置，请到 设置 → 模型 找到该提供方并粘贴你的免费 API Key"**（Key 只由用户手动填写，本插件不采集）。
- 失败降级：若当前 DSH 版本的设置写入接口不可用，弹出引导弹窗：给出可直接粘贴的 YAML 片段（一键复制）+ "打开设置页"指引。**功能永不因版本差异而完全失效。**

### F5 底部菜单（固定三项，可在插件配置中覆盖）

1. 技术笔记 — http://blog.4wc.cn
2. 插件开发 — https://blog.gd7.cn/
3. 联系站长 — http://web.wuyiyun.cn/

### F6 站长后台（PHP 7.4 + SQLite）

- 登录：单管理员账号密码（首次安装自动初始化，强制改默认密码提示）。
- 模型管理：新增/编辑/删除/启用停用/拖动或数字排序，字段 = 标题信息、API 调用地址、模型名称、密钥 key 申请链接。
- 系统设置：站点标题、CORS 允许来源（供 DSH 页面跨域读取）、修改管理员密码、底部三菜单文案与链接。
- 公开 API：`GET api/models.php?page=&page_size=` 服务端分页输出启用中的模型。

### F7 市场分发与升级

- 仓库打 GitHub topics：`dsh-plugin`（必）+ `deepseek-harness-plugin`、`deepseek-harness`。
- README 提供一键安装命令：`dsh plugin add github:<owner>/dsh-free-models-hub`。
- 预构建产物随仓库提交（lib/），**无需 allowBuilds 构建许可**，装完即激活。
- 语义化版本 tag 发版；社区市场据此提供"更新安装"。

---

## 3. 交互原型（文字版）

```
┌──────────────────────────────┐
│ 🎁 免费模型榜            ▾   │
├──────────────────────────────┤
│ 1. GLM-5-Flash 免费额度    › │ ← 点击展开
│   ┌────────────────────────┐ │
│   │ API 地址 https://...v1 │ │
│   │ 模型名  glm-5-flash    │ │
│   │ [点击这里申请免费密钥key]│ │
│   │ [⚡ 一键配置到 DSH]      │ │
│   └────────────────────────┘ │
│ 2. Qwen3-Coder 免费          │
│ 3. …                         │
│ …（共 10 条）                 │
├──────────────────────────────┤
│ 首页 < 1 [2] 3 … 9 > 末页    │
│ 共 87 个 · 第 2/9 页          │
├──────────────────────────────┤
│ 技术笔记 · 插件开发 · 联系站长 │
└──────────────────────────────┘
```

---

## 4. 验收口径（产品层）

1. 全新 `npx @deepseek-ai/dsh web` 环境，执行一条安装命令后面板出现且可用。
2. 后台录入 25 条数据时，前端分页正确（3 页、页码窗口、首末页禁用逻辑）。
3. 点击标题展开四要素齐全；申请密钥按钮跳转正确且不泄漏 referrer。
4. 一键配置后，Settings → Models 出现对应自定义提供方；填入任意 Key 后该模型出现在模型选择器（以第三方 OpenAI 兼容端点联调为准）。
5. 卸载插件后面板、样式、注册项全部消失（Cordis effect 可逆性）。
6. 三条底部菜单可达且在新标签打开。

详细验收矩阵见《05-安全审查与验收》§4。