# dsh-devforge 发布、开源与插件市场指南

本文记录本项目当前的四个发布面：

1. `modagentai.com`：自有官网的预构建 `.tgz` 下载源。
2. GitHub：主开源仓库、Release 预构建包和 dsh-market 精选目录的主链接。
3. CNB：国内公开镜像、代码协作和私密配置备份；它不是当前精选市场的目录来源。
4. `awesome-dsh-plugin` / `dshmarket`：社区精选目录与 DSH 内的一键安装界面。

## 1. 当前状态

截至本文更新时，本地仓库为：

```text
目录：/Users/andyfan/Documents/ds/dsh-devforge
分支：main
GitHub remote：github -> https://github.com/andyfan1094/dsh-devforge.git
CNB remote：origin  -> https://cnb.cool/andyfan1094/dsh-devforge.git
源码版本：0.26.7
```

两个远端账号均已在本机配置并可验证，但远端仓库当前仍是 **Private**。要上架精选插件市场，GitHub 仓库必须改为 **Public**；CNB 可以同步改为 Public，也可以继续作为私有协作镜像，但如果目标是“两个平台都开源”，应将 CNB 也改为 Public。

当前自有官网清单以已发布版本为准；下一次发布需完成测试、提交、推送和官网上传后才能成为官网 latest。

## 2. 发布前准备

### 2.1 检查仓库和敏感文件

```sh
cd /Users/andyfan/Documents/ds/dsh-devforge
git status --short --branch
git remote -v
pnpm install --frozen-lockfile
```

只提交本次文档/截图/发布元数据，不要提交：

- `~/.dsh`、`store.db`、`dsh-feishu.json`、浏览器 profile 或备份密码；
- API Key、Git Token、飞书 App Secret、SSH/WinRM 密码；
- `logs/`、临时截图脚本、浏览器复制档案和构建缓存；
- 与本次任务无关的源码改动。

### 2.2 源仓库验证

```sh
pnpm run typecheck
pnpm test
pnpm run build
npm pack --pack-destination /tmp/dsh-devforge-pack
```

交付红线是：源仓库测试通过后，使用中文提交说明；推送前检查 `git diff --cached`，只包含本次变更。推送不等于重启生产，生产重启仍必须等隔离暂存实例人工验收和用户明确确认。

## 3. 发布到自有官网 modagentai.com

自有官网源目录是本机的 `modagentai-site/`：

```text
modagentai-site/index.html
modagentai-site/downloads/index.json
modagentai-site/downloads/dsh-devforge-<version>.tgz
modagentai-site/downloads/dsh-devforge-latest.tgz
```

### 3.1 生成包和校验值

```sh
cd /Users/andyfan/Documents/ds/dsh-devforge
pnpm run build
npm pack --pack-destination /Users/andyfan/Documents/ds/modagentai-site/downloads
cd /Users/andyfan/Documents/ds/modagentai-site/downloads
cp dsh-devforge-0.23.0.tgz dsh-devforge-latest.tgz
shasum -a 256 dsh-devforge-0.23.0.tgz dsh-devforge-latest.tgz
```

`latest` 文件和版本化文件应当是同一包的字节副本，两个 SHA-256 必须一致。

### 3.2 更新官网清单

编辑 `modagentai-site/downloads/index.json`：

- `latest` 改为当前版本；
- `latestUrl` 指向 `/downloads/dsh-devforge-latest.tgz`；
- `updated` 使用发布日期；
- 在 `versions` 追加版本号、日期、下载 URL、SHA-256 和中文更新说明；
- 不删除历史版本，旧 URL 必须继续可下载。

官网更新说明应当与实际代码一致，避免把规划功能写成已上线功能。

### 3.3 上传和线上核验

服务器信息记录在 `modagentai-site/README.md`：Nginx root 为 `/var/www/modagentai`，下载目录为 `/var/www/modagentai/downloads/`。使用 `ssh_upload` 上传两个 `.tgz` 和 `index.json`，不要在聊天中输出服务器密码或 Token。

```sh
curl --noproxy '*' -sI https://modagentai.com/downloads/dsh-devforge-latest.tgz
curl --noproxy '*' -fsSL https://modagentai.com/downloads/index.json
curl --noproxy '*' -fsSL https://modagentai.com/downloads/dsh-devforge-latest.tgz -o /tmp/dsh-devforge-latest.tgz
shasum -a 256 /tmp/dsh-devforge-latest.tgz
```

把下载后的 SHA-256 与 `index.json` 和本地包三方核对。官网渠道是插件更新页的优先源，清单不一致时不要让用户升级。

## 4. 开源 GitHub 仓库

### 4.1 改为 Public

GitHub 网页操作：

1. 打开 `https://github.com/andyfan1094/dsh-devforge`。
2. 进入 **Settings → General → Danger Zone → Change repository visibility**。
3. 选择 **Make public**，逐项确认仓库名。
4. 在仓库 **About/Topics** 添加 `dsh-plugin`。
5. 确认仓库首页能看到中文 README、MIT/Apache 许可证、`cordis.patch.yml`、`package.json` 和 `docs/assets/screenshots/`。

公开前应再次检查 Git 历史，避免历史提交中出现密钥。仓库公开是不可逆风险操作，执行前应由仓库所有者确认。

### 4.2 推送源代码

验证完成并完成中文提交后：

```sh
git add README.md README.zh.md screenshots.json docs/用户手册.md docs/发布与开源指南.md docs/assets/screenshots
git diff --cached --stat
git commit -m "docs(天工造梦): 完善用户手册与发布指南"
git push github main
```

如果本次还包含用户已有的功能提交，先确认提交边界；不要用 `git add .` 把无关工作区改动带进去。Release 建议上传一个预构建包：

```text
dsh-devforge-0.23.0.tgz
```

为了让市场的 `tarball` 链接不随版本更新失效，推荐每次 Release 同时上传一个不带版本号的稳定资产：

```text
dsh-devforge.tgz
```

市场条目中的 `tarball` 可以使用：

```text
https://github.com/andyfan1094/dsh-devforge/releases/latest/download/dsh-devforge.tgz
```

如果只上传带版本号的资产，就应当把 `tarball` 固定到具体 tag，而不是让 `latest/download/` 指向一个下一版会消失的文件名。

### 4.3 npm（可选）

精选目录不要求 npm 包；发布 npm 的好处是市场可以显示下载量，并让用户直接获得预构建包。若发布：

- `package.json.repository` 必须准确指向 `https://github.com/andyfan1094/dsh-devforge`；
- 官方 `@deepseek-ai/*` 依赖优先放入 `peerDependencies`，按当前 DSH 预发布版本写显式 prerelease 分支；
- 发布前执行 `npm pack --dry-run`，检查没有把私密配置带进包；
- npm 发布仍然要经过测试、中文提交和发布后的安装验收。

## 5. 开源 CNB 镜像

CNB 远端是 `https://cnb.cool/andyfan1094/dsh-devforge`，当前作为 `origin`。

### 5.1 改为 Public

在 CNB 仓库设置中把可见性改为 **公开**，确认仓库描述、README、许可证和默认分支为 `main`。CNB 使用 HTTPS + Access Token，Git 用户名固定为 `cnb`；Token 不写入 URL、README 或 Git 配置。

### 5.2 推送镜像

```sh
git push origin main
```

如要保持 GitHub/CNB 完全一致，先在 GitHub 推送并确认远端提交，再推 CNB；必要时：

```sh
git fetch github main
git log --oneline --decorate -5
git push origin main
```

CNB 推送开关默认关闭；在天工造梦「代码仓库 → CNB → 安全设置」打开前，`cnb_push` 和面板 Push 都会被拒绝。开源镜像与 `dsh-devforge-backup` 私密备份仓库是两件事，不要把加密备份仓库改成公开。

## 6. 上架 awesome-dsh-plugin / dsh-market

### 6.1 先分清两个仓库

- `dsh-market/dsh-market` 是市场应用本身，不接受插件条目。
- `awesome-dsh-plugin/awesome-dsh-plugin` 是精选目录，市场和官网从它生成/读取插件清单。
- `dshmarket` 的安装命令是：

```sh
dsh plugin --profile web add dshmarket
```

市场当前从 `https://awesome-dsh-plugin.com/plugins.json` 获取目录；中国区域还会从 `dsh-plugin-catalog` npm 包读取镜像目录。发布者不需要修改 dsh-market 源码或手工上传 `plugins.json`。

### 6.2 提 PR 的唯一文件

在 `awesome-dsh-plugin` fork 中新增：

```text
data/plugins/andyfan1094__dsh-devforge.yml
```

内容建议：

```yaml
url: https://github.com/andyfan1094/dsh-devforge
name: andyfan1094/dsh-devforge
category: dev
description:
  en: Spec-driven service forge and integrated operations workspace for DeepSeek Harness.
  zh: 面向 DeepSeek Harness 的规范驱动服务工厂与本机智能体工作台。
```

要求：

- `url` 必须是已公开的 GitHub 仓库并与仓库完全一致。
- `name` 使用 `owner/repo`。
- `category` 选择最贴合功能的分类；本项目优先 `dev`，也覆盖 `tools`、`memory`、`remote` 等能力，但一个条目不需要重复投稿多个分类。
- `description.en` 必填，句号结尾；描述要对照源码，不能夸大工具数量或写入不存在的 API。
- 仓库的 `package.json` 必须声明 `dsh.bundle`；本项目已有 `dsh.bundle.patch` 和根目录 `cordis.patch.yml`。
- 仓库创建时间必须超过 1 天，代码真实可运行，添加 `dsh-plugin` topic，并处于持续维护状态。
- 一个 PR 最多新增 3 个条目；本项目只需要 1 个 YAML 文件。
- 不手工编辑生成的 `README.md`/`README.zh.md`，列表由 CI 从 `data/plugins/*.yml` 生成。

### 6.3 市场截图

市场支持在插件仓库根目录读取 `screenshots.json`，本项目已经准备：

```json
[
  "docs/assets/screenshots/guide.png",
  "docs/assets/screenshots/coding-plan.png",
  "docs/assets/screenshots/rag.png",
  "docs/assets/screenshots/memory.png",
  "docs/assets/screenshots/workflow.png",
  "docs/assets/screenshots/repos-cnb-accounts.png",
  "docs/assets/screenshots/repos-github-accounts.png",
  "docs/assets/screenshots/skin.png"
]
```

规则是 1-8 张；相对路径不能以 `/` 开头，也不能包含 `..`；图片应当留在自己的 GitHub 仓库内。没有 `screenshots.json` 时，市场会从 README 自动抽取图片，但顺序不可控。修改截图只需要推送自己的仓库，下一次目录构建会更新，不需要再改精选目录 PR。

### 6.4 可选 tarball 字段

如果要让市场优先安装 Release 预构建包，在同一个 YAML 中追加：

```yaml
tarball: https://github.com/andyfan1094/dsh-devforge/releases/latest/download/dsh-devforge.tgz
```

市场会校验：必须是 HTTPS、GitHub Release 托管、`.tgz`，并且 URL 所属仓库必须与 `url` 相同。推荐 Release 同时上传固定文件名 `dsh-devforge.tgz`；否则请把 URL 固定到 tag 和版本文件名。

### 6.5 合并后的传播链

```text
PR 合并
  → awesome-dsh-plugin CI 生成 README / plugins.json / 网站数据
  → awesome-dsh-plugin.com 更新
  → dshmarket 下次加载目录看到条目
  → DSH 用户在设置 → 插件市场搜索并安装
```

通常需要等待一次 CI/网站构建；市场不会即时读取你本机的仓库，也不会因为你把包上传到 CNB 就自动收录。

## 7. DSH 暂存验收与生产交付

插件/服务改动的完整顺序：

```text
源仓库 typecheck/test/build 通过
  → 中文提交
  → 推 GitHub/CNB
  → 官网上传并核对 sha256（若发布官网包）
  → 安装到 web profile
  → 隔离 HOME 暂存实例 3081 人工过目
  → 用户明确确认
  → 才允许重启生产 3080
```

暂存命令和 overlay 以 [插件暂存环境测试约束](插件暂存环境测试约束.md) 为准：

- `HOME=/Users/andyfan/.dsh-staging`；
- `DSH_HOME=/Users/andyfan/.dsh-staging/.dsh`；
- 端口 `3081`；
- 禁用 `web-ui-pet`；
- `devforge.feishu.enabled: false`；
- 暂存内不要执行插件安装/升级，插件安装在真实用户环境完成，暂存只做真实集成验收。

生产 DSH 不作为实验田；`devforge_restart` 和 GUI 重启按钮只在用户明确要求时执行。

## 8. 参考链接

- [GitHub 主仓库](https://github.com/andyfan1094/dsh-devforge)
- [CNB 镜像仓库](https://cnb.cool/andyfan1094/dsh-devforge)
- [自有官网版本清单](https://modagentai.com/downloads/index.json)
- [自有官网 latest 包](https://modagentai.com/downloads/dsh-devforge-latest.tgz)
- [Awesome DSH Plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
- [Awesome DSH Plugin 贡献指南](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md)
- [dsh-market](https://github.com/dsh-market/dsh-market)