# 🚀 发布到 DSH 应用市场指南

本指南介绍如何把 `dolphin-pet-plugin` 发布到 DSH 插件市场（dshmarket），让所有人都能一键安装。

## 发布前检查清单

- [x] `package.json` 声明了 `dsh.bundle`（含 `cordis.patch.yml`）— 已完成
- [x] `cordis.patch.yml` 在仓库根目录 — 已完成
- [x] 代码真实可用（已在本地 DSH web 验证全部 API）— 已完成
- [x] README 中英文 — 已完成
- [ ] 创建 GitHub 仓库并推送代码
- [ ] 仓库创建满 1 天、提交数 ≥ 10
- [ ] 给仓库加 `dsh-plugin` topic

## 第一步：创建 GitHub 仓库

```bash
cd dolphin-pet-plugin

# 初始化 git（如果没有）
git init
git add .
git commit -m "feat: dolphin pet plugin with custom name, image upload and AI generation"

# 修改 package.json 中的仓库地址后：
git remote add origin https://github.com/bo961386926/dolphin-pet-plugin.git
git push -u origin main
```

**注意**：收录要求仓库创建满 1 天、提交数 ≥ 10。建议用多个有意义的 commit 推进（分步提交 host 端、client 端、文档等），等满 1 天后再提 PR。

```bash
# 建议的提交拆分（凑满 10 个 commit 也让历史更清晰）：
git commit -m "chore: scaffold plugin structure"
git commit -m "feat(host): config persistence API"
git commit -m "feat(host): image upload endpoint"
git commit -m "feat(host): AI image generation with fallback"
git commit -m "feat(client): pet rendering and interaction"
git commit -m "feat(client): settings panel"
git commit -m "feat(client): custom image support"
git commit -m "feat(client): AI generate UI"
git commit -m "docs: add bilingual README"
git commit -m "chore: bump to 1.0.0"
```

给仓库加 topic（GitHub 仓库页面右上角齿轮 → Topics）：

```
dsh-plugin deepseek-harness desktop-pet dolphin
```

## 第二步：发布到 npm（可选但推荐）

npm 包能让市场走「预构建」通道安装（数秒完成），否则回退到 GitHub 源码安装。

```bash
# 1. 确认 package.json 中 name/version/description/repository 正确
#    （发布前把 author、repository.url、homepage 换成你的真实信息）

# 2. 登录 npm
npm login

# 3. 试打包检查内容
npm pack --dry-run
# 应包含：lib/、client/、cordis.patch.yml、README.md、README.zh.md、package.json

# 4. 发布
npm publish
```

> `prepare` 脚本里是 echo，不会执行构建；包里直接就是纯 JS 源码，无需编译。

## 第三步：提交到 awesome-dsh-plugin（关键步骤）

市场数据源是 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)。
收录方式是 **PR 添加一个 YAML 文件**（README 由脚本生成，勿手改）。

### 1. Fork 仓库并创建文件

Fork 后新建 `data/plugins/bo961386926__dolphin-pet-plugin.yml`（文件名 = 你的 GitHub 用户名 + 仓库名）：

```yaml
url: https://github.com/bo961386926/dolphin-pet-plugin
name: bo961386926/dolphin-pet-plugin
category: fun
description:
  en: A desktop pet that swims in the web GUI - rename it, upload your own pet image, or generate one with AI.
  zh: 在网页界面里游来游去的桌面宠物——可以改名字、上传自定义图片，或用 AI 生成形象。
```

**格式要点**（来自官方 [contributing.md](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)）：

- `url` 必须与仓库地址完全一致
- `category` 选 `fun`（娱乐分类，宠物插件最贴切；分类选不准不会被拒，维护者会直接改）
- `description.en` 必填、以句号结尾、**只说功能不带营销词**
- 描述里提到的功能必须真实存在（会有人对着代码核对）
- 描述含 `: `（冒号+空格）时必须加引号

### 2. 重新生成 README 并一起提交

```bash
npm ci
node scripts/generate-readme.mjs

git add data/plugins/bo961386926__dolphin-pet-plugin.yml README.md README.zh.md
git commit -m "add dolphin-pet-plugin"
```

### 3. 提 PR

PR 标题示例：`add dolphin-pet-plugin`

提交后 CI 会自动检查：manifest 声明、仓库年龄、commit 数、格式、README 可重新生成。CI 全绿后维护者会实际阅读你的仓库代码再合并。

## 第四步：等待收录生效

- 合并后 CI 每日刷新 [awesome-dsh-plugin.com/plugins.json](https://awesome-dsh-plugin.com/plugins.json)
- 市场每次打开都实时请求该数据源，**通常一天内**出现在所有装了 dshmarket 的用户的「插件市场」里
- 用户即可：**设置 → 插件市场 → 搜索 dolphin-pet-plugin → 一键安装**

## 逆向验证（发布后自测）

```bash
# 模拟一个全新用户安装：
dsh plugin --profile web remove dolphin-pet-plugin   # 先移除本地 link 版
dsh plugin --profile web add dolphin-pet-plugin     # 从 npm 装
# 或从 GitHub 装：
dsh plugin --profile web add github:bo961386926/dolphin-pet-plugin
```

重启 `dsh web`，刷新页面，确认：
1. 屏幕右下角出现宠物和状态面板
2. 点 ⚙️ 打开设置，改名字 → 保存 → 名字生效
3. 上传一张图片 → 宠物形象替换
4. AI 生成 → 输入描述 → 生成图片（无图片模型时返回占位 SVG 并提示）

## 本插件 package.json 关键声明（已就绪）

```jsonc
{
  "name": "dolphin-pet-plugin",
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }   // ← 收录硬性要求
  }
}
```

`cordis.patch.yml`：

```yaml
- insert:
    - id: pet
      name: 'dolphin-pet-plugin'
```

## 已验证的功能清单

本地 web profile 已实测通过：

| 功能 | 状态 |
|------|------|
| 脚本注入 index.html | ✅ |
| GET/POST `/plugins/dolphin-pet/config`（改名/切换形象） | ✅ |
| POST `/plugins/dolphin-pet/upload`（multipart 图片上传） | ✅ |
| POST `/plugins/dolphin-pet/ai-generate`（含无模型时的 SVG 降级） | ✅ |
| 配置持久化（`~/.dsh-pet/config.json`） | ✅ |
| 设置面板（名字/上传/AI 生成 UI） | ✅ |