# 发布到 GitHub（含可选的 npm 发布）

本插件是纯 JavaScript 包，没有构建步骤：`node --test` 通过即可发布。

---

## 0. 先决条件

- 一个 GitHub 账号；
- 本机已装 `git`（`git --version` 有输出即可）；
- 可选：GitHub CLI（`gh`）。装了它，第 2 步可以用一条命令代替网页操作。

```powershell
winget install --id GitHub.cli
gh auth login          # 选 GitHub.com → HTTPS → 浏览器授权
```

---

## 1. 替换占位符（重要）

`package.json` 里的仓库地址目前是占位符 `OWNER`：

```json
"repository": { "type": "git", "url": "git+https://github.com/OWNER/dsh-fable8cents.git" }
```

把三处 `OWNER` 换成你的 GitHub 用户名（`repository.url`、`homepage`、`bugs.url`）。
`README.md` 开头的相对链接不受影响，不用改。

---

## 2. 本地建仓库并提交

在插件目录里执行：

```powershell
cd C:\Users\zzz\Documents\deepseek-harness\default-workspace\dsh-fable8cents

git init -b main
git config user.name "你的名字"
git config user.email "你的邮箱"

git add .
git status            # 确认没有 *.tgz、node_modules 进暂存区（.gitignore 已排除）
git commit -m "feat: dsh-fable8cents — Claude Fable 8 display shell"
```

> `dsh-fable8cents-0.1.0.tgz` 是构建产物，**不要提交**；它会在发布时由 `npm pack` 或 CI 生成。

---

## 3. 在 GitHub 创建仓库

### 用网页

1. 打开 <https://github.com/new>；
2. Repository name 填 `dsh-fable8cents`；
3. 选 Public（或 Private，都能用，只是别人看不到）；
4. **不要**勾选 “Add a README / .gitignore / license”（本地已有）；
5. Create repository，然后按页面提示推送。

### 用 gh（推荐）

```powershell
gh repo create dsh-fable8cents --public --source . --remote origin --push
```

它会自动建仓库、加 remote 并推送当前分支。

### 纯 git 推送

```powershell
git remote add origin https://github.com/<你的用户名>/dsh-fable8cents.git
git push -u origin main
```

推送时如果要求登录，用 GitHub 的 Personal Access Token 当密码（Settings → Developer settings → Personal access tokens），或先 `gh auth login`。

---

## 4. 发一个 Release（提供 tgz 下载）

仓库里已带 `.github/workflows/release.yml`：**推送 `v*` 标签时自动跑测试、`npm pack`、创建 Release 并附上 tgz**。

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

一两分钟后到仓库的 **Releases** 页就能看到 `dsh-fable8cents-0.1.0.tgz`。
别人下载后可以这样装：

```text
plugin_manager install_bundle  <解压后的目录>
```

或者把 tgz 解压到任意目录，运行：

```text
node scripts/install.mjs --profile desktop
```

> 手动发 Release 也可以：Releases → Draft a new release → 选 tag → 上传本地 `npm pack` 生成的 tgz。

### 如果 Actions 被禁用（HTTP 422 / “Actions has been disabled”）

某些新账号或受限账号无法运行 Actions（`gh workflow run` 会返回 422）。此时改用本地打包 + 手动上传：

```powershell
npm pack
gh release create v0.1.0 dsh-fable8cents-0.1.0.tgz `
  --title "v0.1.0 — Claude Fable 8 显示层" `
  --notes-file docs/RELEASE_NOTES_0.1.0.md
```

想恢复 CI：仓库 **Settings → Actions → General → Allow all actions**，或到账号级
<https://github.com/settings/actions> 检查策略。

---

## 5. 想让「启动自动更新」真的生效 → 发 npm 或让 GitHub Release 可匿名访问

插件的更新检查有**两个通道**，取版本号较新的一个：

1. **npm registry**：`{registry}/dsh-fable8cents` 里的 `dist-tags.latest` 与 tarball 地址；
2. **GitHub Release**：从 `package.json#repository` 解析 `owner/name`，读 `releases/latest` 与 `.tgz` 附件。

所以：

- **发到 npm**：最通用，镜像同步后国内外都能查（`npm publish --access public`）；
- **只发 GitHub Release**：只要仓库能被**匿名**访问（浏览器无痕打开仓库不是 404），
  插件就能在启动时发现新版本；不需要 npm 账号；
- 如果仓库匿名访问是 404（账号被限制或 private），在插件配置里给 `update.githubToken`
  （或设环境变量 `GITHUB_TOKEN` / `GH_TOKEN`）即可走已认证的 GitHub API。

> 只发 GitHub Release、且仓库匿名可见时，用户手动下载安装的体验和自动更新都能成立；
> npm 只是第二条更通用的通道，不是必须的。

```powershell
npm login                 # 没有账号先到 npmjs.com 注册
npm publish --access public
```

注意：

- 包名 `dsh-fable8cents` 必须没被别人占用（被占就改名，例如 `@你的名字/dsh-fable8cents`，同时改 `lib/updater.js` 里的 `PLUGIN_NAME`）；
- 开了 2FA 的账号，`npm publish` 会要求一次性验证码；
- 发布后镜像（npmmirror）通常需要几分钟到几十分钟同步；
- 每次发布前改 `package.json` 的 `version`（更新器按 semver 比较，`0.1.1 > 0.1.0` 才会触发）。

如果不想把包名发到公共 npm，也可以自建一个 npm 兼容源（Verdaccio），然后：

```yaml
# profile 的 cordis.patch.yml，本插件的行
- id: dsh-fable8cents
  name: dsh-fable8cents
  config:
    update:
      registries:
        - https://your-registry.example.com
```

---

## 6. 发布前自检清单

```powershell
node --test tests/*.test.mjs      # 17 项应全绿
node scripts/install.mjs --dry-run   # 安装脚本路径正确
npm pack --dry-run                # 看最终发布内容（lib/locale/icon/docs/scripts）
```

- [ ] `package.json` 里 `OWNER` 已替换
- [ ] `.gitignore` 生效：`git status` 里没有 `.tgz`、`node_modules`
- [ ] `LICENSE` 里的版权人写过（可选）
- [ ] 免责声明里的社区二创表述保留（避免被误认为官方）
- [ ] 没有提交任何本机绝对路径、token、账号信息

---

## 7. 常用命令速查

| 目的 | 命令 |
|---|---|
| 建仓并推送 | `gh repo create dsh-fable8cents --public --source . --remote origin --push` |
| 查看待提交 | `git status --short` |
| 发版 | `git tag v0.1.1 && git push origin v0.1.1` |
| 发 npm | `npm publish --access public` |
| 打本地包 | `npm pack` |
| 安装到本机 profile | `node scripts/install.mjs --profile desktop` |
| 从 profile 卸载 | `node scripts/install.mjs --uninstall --profile desktop` |