# 06 · 发布与升级指南

## 1. 首次发布（v0.1.0）

### 1.1 GitHub 仓库准备

```bash
cd D:\DeepSeekHarness
git init
git add .
git commit -m "feat: dsh-free-models-hub v0.1.0"
# 在 GitHub 创建空仓库 <owner>/dsh-free-models-hub 后：
git remote add origin https://github.com/<owner>/dsh-free-models-hub.git
git push -u origin main
```

### 1.2 打 topic（被市场收录的关键动作）

仓库页 → About ⚙ → Topics 添加：

- `dsh-plugin`（**必需**，社区市场按它索引）
- `deepseek-harness-plugin`、`deepseek-harness`、`deepseek`、`free-models`

### 1.3 发 tag 与 Release

```bash
git tag v0.1.0
git push origin v0.1.0
```

GitHub Release：基于 tag，粘贴 CHANGELOG 对应段落，附 `pack` 产物 zip。

### 1.4 提交到社区目录（可选加速收录）

- dsh-market / DSH-Plugins-Marketplace 等市场均自动扫描 topic；如需加速可在其 repo issue 区提交收录申请。
- awesome-dsh-plugin 类精选列表可 PR 自荐。

## 2. 用户安装与更新路径

```bash
# 安装（预构建产物随仓库走，无 allowBuilds 弹窗）
dsh plugin add github:<owner>/dsh-free-models-hub

# 更新 = 再次执行（pnpm 会拉取 main/tag 最新内容）
dsh plugin add github:<owner>/dsh-free-models-hub

# 卸载
dsh plugin --profile <name> remove dsh-free-models-hub
```

> 建议在 README 同时给出 pin 版本写法 `github:<owner>/dsh-free-models-hub#v0.1.0`，供安全敏感用户固定代码。

## 3. 后续版本升级流程（作者侧）

1. 功能分支开发 → 按 04 清单自查 → 合并。
2. 更新 CHANGELOG（Added/Changed/Fixed/Security）。
3. `npm version patch|minor|major`（同步 package.json + 自动 commit+tag）→ push 含 tag。
4. CI 绿后确认 Release 自动产出或手动补 zip。
5. 在 CHANGELOG 标注"已验证的 DSH 版本"；若适配了 slot/API 变化，在 README 兼容性表格登记。
6. 市场侧用户点击更新即得新版——**保证 tag 与 main 内容一致是更新安全的前提**。

## 4. 版本号约定

| 变更类型 | 示例 | 升级 |
|---|---|---|
| 修复（分页边界、XSS 加固） | 0.1.1 | PATCH |
| 新功能、DSH 预览期破坏性适配 | 0.1.x → 0.2.0 | MINOR |
| 数据结构/配置不兼容迁移 | 0.x → 1.0.0 | MAJOR |

## 5. 私有后端部署（仅作者本人）

> `server-php/` 已加入 .gitignore，**不随开源仓库发布**——其他站长拿不到后台代码，
> 无法自建数据源。插件默认数据源即作者站点，用户安装即用。

1. 改动后端后，在仓库目录执行：
   `powershell -ExecutionPolicy Bypass -File scripts\deploy-site.ps1 -Target "D:\phpstudy_pro\WWW\DeepSeekHarness"`
   （脚本不碰线上 `data\`，数据库与密码保留。）
2. 验证：`https://free-api.gd7.cn/` 榜单、`/api/models` 接口、`/admin/` 后台。
3. 后台「系统设置」CORS 白名单需包含 DSH 页面来源（如 `http://127.0.0.1:3080`）。
4. 生产建议：全站 HTTPS（CF 已提供）、`/admin` 可再加 Basic Auth、对 `/api/models` 加 CDN 缓存或限流。

## 6. 常见问题（发布侧）

| 问题 | 处理 |
|---|---|
| 装了没激活 | 检查 package.json 是否保留 `dsh.bundle.patch` 字段（官方文档明确警告缺失时静默不激活） |
| 安装弹 allowBuilds | 说明误用了 prepare 构建；本插件应保持 lib/ 预构建直出 |
| 市场搜不到 | 确认 topics 已含 `dsh-plugin` 且仓库 public；等市场索引周期刷新 |
| 更新后界面异常 | 先 `remove` 再 `add`；对照 README 兼容表确认 DSH 版本 |