# 上架插件市场 · 提交指南

这份文件只写给作者自己看（**不会**发布到 npm，也不在 `package.json` 的 `files` 里）。
它把「本地已经能用的主题」变成「插件市场里能搜到、一键装」的东西，分成三步。

---

## 先搞清楚：市场里的条目从哪来

插件市场（`dshmarket`）自己不维护插件清单。它每次打开都实时拉
[awesome-dsh-plugin.com/plugins.json](https://awesome-dsh-plugin.com/plugins.json)，
而那份目录由 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
仓库精选，CI 每日刷新。

所以链条是：

```
你的 GitHub 仓库 / npm 包  →  awesome-dsh-plugin 收录  →  plugins.json  →  插件市场 UI
```

**要上架，就得先有一个能被别人 `npm install` / `git clone` 到的东西。**
市场不能装一个只存在于你本机 `node_modules` 里的目录——这一步必须先做完。

---

## 先搞对 profile 路径：桌面端 ≠ CLI

写文档、写安装说明、给用户答问之前，先把这件事记牢——**踩过一次，代价是两条命令全红**：

| 载体 | profile 位置 |
| --- | --- |
| CLI 版 dsh | `~\.dsh\profiles\web\` |
| **DSH Desktop（本机）** | `%APPDATA%\dsh-desktop\harness\profiles\web\` |

网上教程、别的插件 README、以及本目录早期版本写的都是前者。先探一下再动手：

```powershell
@("$env:USERPROFILE\.dsh\profiles\web", "$env:APPDATA\dsh-desktop\harness\profiles\web") |
  ForEach-Object { "{0}  {1}" -f (Test-Path $_), $_ }
```

**本机实测**：`~\.dsh\` 不存在；真正在用的是
`C:\Users\Yill\AppData\Roaming\dsh-desktop\harness\profiles\web`。

顺手记一条 shell 的坑：上面这类 `$var = ...` / `Copy-Item` 是 **PowerShell**；
贴进 `cmd.exe` 会得到一串「不是内部或外部命令」。cmd 里要用 `copy /y "源" "目标"`
和 `%USERPROFILE%` / `%APPDATA%`。

---

## 第 0 步：先替换掉占位符

`package.json` 里有两个字段现在还是占位符，发布前必须改：

```json
"author": "AEMEATH",                                              ← 你的名字
"repository": { "url": "git+https://github.com/yll86/dsh-theme-aemath.git" }
"bugs":       { "url": "https://github.com/yll86/dsh-theme-aemath/issues" }
"homepage":   "https://github.com/yll86/dsh-theme-aemath#readme"
```

顺手确认一下 `assets/aemath-poster.jpg`、`assets/aemath-bg.jpg` 这两张图你**有权分发**
（同人主题里最容易出问题的就是这个；正式提交前把自己的画/有授权的图换上最稳）。

---

## 第 1 步：发布到 npm

这台机器上 npm 还没登录（`npm whoami` → `ENEEDAUTH`），而且当前 registry 指向
`registry.npmmirror.com`——**镜像是只读的，发布必须走官方源**。

```powershell
# 1) 登录官方 npm（浏览器授权；镜像源发布不了）
npm login --registry=https://registry.npmjs.org/

# 2) 确认包名没被占（返回 404 = 可用）
npm view dsh-theme-aemath version --registry=https://registry.npmjs.org/

# 3) 先干跑一次，确认要发出去的文件就是这些
npm publish --dry-run --registry=https://registry.npmjs.org/

# 4) 真发
npm publish --registry=https://registry.npmjs.org/
```

期望的 tarball 内容（由 `package.json` 的 `files` 决定）：

```
package.json
lib/index.js          host 半边
lib/client.js         浏览器半边（构建产物）
assets/aemath-bg.jpg
assets/aemath-chibi.jpg
assets/aemath-favicon.svg
assets/aemath-poster.jpg
screenshots.json
README.md / README.en.md / CHANGELOG.md / LICENSE
```

> `src/`、`scripts/`、本文件都不进包——它们属于仓库，不属于运行时。
> `npm publish` 之前先跑 `node scripts/build-client.mjs`，否则发的是旧产物。

**如果 `dsh-theme-aemath` 这个名字已经被别人占了**，就用作用域包：

```powershell
npm pkg set name="@你的npm用户名/dsh-theme-aemath"
npm publish --registry=https://registry.npmjs.org/
```

⚠️ 改了包名，**profile 补丁里的 `name:` 要跟着改成新包名**，否则加载器找不到它：

```yaml
- insert:
    - id: ui-theme-aemath
      name: '@你的npm用户名/dsh-theme-aemath'
```

## 第 2 步：推上 GitHub（这一步决定别人能不能看到）

```powershell
git init
git add .
git commit -m "feat: AEMEATH theme for DeepSeek Harness Web"
git branch -M main
git remote add origin https://github.com/yll86/dsh-theme-aemath.git
git push -u origin main
```

建议在仓库 **About** 里加上 `dsh-plugin` topic——目录站的爬虫按这个 topic 抓社区插件，
带上它就多一条被发现的路。（待办：确认这个 topic 名字与当前爬虫一致，别照抄。）

## 第 3 步：向 awesome-dsh-plugin 提 PR

收录规则、条目格式、评审要点都在那边的 contributing 文档里，**以那里为准**：
<https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md>

流程就是：

1. fork `awesome-dsh-plugin/awesome-dsh-plugin`
2. 在精选列表里加一条指向上一步那个 GitHub 仓库的条目
3. 提 PR；CI 校验通过后合入，站点和本市场通常一天内生效

⚠️ 注意：**不要往 `dsh-market/dsh-market` 仓库提插件条目**——那里面是市场应用本身，
条目一律走 `awesome-dsh-plugin`。

## 第 4 步：自己先验一遍

收录之后，在设置 → 插件市场里搜 `aemath`，走一遍一键安装，确认：

- [ ] 卡片能正常显示标题、双语描述、截图（`screenshots.json` 那两张）
- [ ] 一键安装成功，**刷新页面**主题就生效
- [ ] 设置里的主题切换（浅色/深色）跟着变
- [ ] 对话背景立绘和左下角 Q 版徽章都在（徽章不该是空白圆圈——那是旧版的 bug）
- [ ] 卸载后界面完全回到出厂配色，`cordis.patch.yml` 里不留残行

## 关于兼容性声明

市场卡片会展示插件声明的 DSH 版本要求，来源是 `engines.dsh` 或
`@deepseek-ai/dsh-*` 的 peer 依赖。这个主题只用 CSS 变量和 `body` 伪元素，
对宿主版本几乎无要求，所以**故意不声明**——不声明就是「保持可见、不做兼容性判断」，
比写一个可能过期的范围更不容易把用户挡在门外。

---

## 附：本地不发布也能测

想在上架前自己验证包结构，不用真的发布：

```powershell
# 打一个 tarball，看里面到底有什么
npm pack

# 用 link: 装进 profile 开发调试（改完刷新页面即可，无需重装）
dsh plugin --profile web add link:.
```

桌面客户端读的是 `desktop` profile、且 `dsh plugin` 按设计不碰它——
在桌面端要让 DSH 自己装：在会话里说「装一下 dsh-theme-aemath」。