dsh-storecloud

DSH 插件商城 · 用户端 —— 插件组一键装机、云端同步、联邦自建服，一体化的 DSH 插件商店客户端（源码 + 产物统一仓库）。

在 DSH Web 界面里浏览、搜索、安装 DSH 插件与 Agent 预设，跟着社区推荐的插件组整组装机，换环境一键拉回自己的插件，无需在海量插件里自己查找试错。

---

✨ 项目特色

🧩 插件组（组合）—— 用别人的推荐，避免自己试错

插件很多，逐个查找、试错成本高。商城把插件与 Agent 预设编成组合（combos），一键整组安装：

• 社区推荐组合：浏览/搜索他人分享的组合，按「推荐」「热门」「最新」筛选，组合详情里能看到完整成员清单与各自的安装模式；
• 一键整组安装：点安装即按组合成员的安装模式逐个执行真实的 dsh plugin add（直接安装 / 安装前询问 / 跳过），Agent 预设自动装进 ~/.dsh/.agent-presets/；
• 在线实时数据：组合列表打开即直连服务器刷新（覆盖本地缓存），创建/编辑/删除后立即同步权威数据，多端一致；
• 启动复核开关：安装带启动复核的组合时逐项确认，安装完的组合可一键复查状态；
• 订阅组合：订阅作者持续更新的组合，跟随推荐升级，不用自己维护清单；
• 创建并分享自己的组合：从已装插件/预设里挑选成员、设定安装模式与自动发布，一键发布到云端供他人订阅。

☁️ 云端同步 —— 换开发环境，一键拉回自己的插件

换电脑、重装环境，不用再翻历史记录重新查找：

• GitHub 登录：OAuth 一键登录，身份与数据跟随账号；
• 云端台账：你创建的组合、订阅的组合、安装记录全部同步到云端；
• 一键拉取：新环境装好插件 → 登录 → 从「我的」一键拉取自己的组合与已装清单，整组批量装回，开箱即续；
• 多源切换：?server=<地址> 可随时切换服务器源，本地缓存秒开、后台增量同步。

🛰️ 联邦与自建服务器 —— 数据在自己手里，还支持热更新

不想用作者的服务器？完全可以自己部署：

• 自建云端：服务端是独立开源仓库，一条命令部署到自己的服务器（PostgreSQL + Docker），插件库、组合、用户、联邦关系全在自己手里；
• 联邦互联：多台服务器之间握手互连，可选共享插件 / Agent 预设 / 组合 / 用户，服务器集群互为镜像，一处收录处处可用；
• 热更新：服务端管理面板支持一键在线更新（拉新镜像 → 自动迁移 → 重建容器 → 自检，失败自动回滚），日常升级不用登录服务器敲命令；
• 开箱即用：默认连接作者的服务器，零配置即可体验完整功能。

> 服务器端部署、管理端配置、联邦设置等详见文末「服务器端」章节。

其他亮点

• 双入口：⚙️ 设置页区块 + 📑 会话视图 Tab，每个入口可在「我的」页独立开关（悬浮球入口已移除，测试版保留在 dsh-store-shell/）；
• 页内直接安装：浏览到的插件点「安装」即执行真实的 dsh plugin add（pnpm 安装 + 自动入组合层），安装/卸载/已装清单实时核对本地真实状态；
• 零依赖客户端半：走 DSH 标准 client-modules 通道（dsh.client 声明），不捆绑 React、不依赖框架内部 API，随 DSH 主版本长期兼容；
• 无缝反向代理桥：/dsh-store/api 同源转发（自动携带登录态/访问口令/匿名凭证），OAuth 登录后 token 自动回传，无跨域无复制粘贴；通用转发带 SSRF 防护；
• 源码与产物统一仓库：npm install && npm run build 全链路可复现；npm pack 发布产物 tarball 只含产物（约 100 kB）。

---

一键安装

# 方式 A：官方装配命令（推荐）——装完重启 DSH web 进程即可
dsh plugin --profile web add github:hajimilvdou/dsh-storecloud

# 方式 B：本地 tarball / git 仓库
dsh plugin --profile web add ./dsh-storecloud-0.1.0.tgz
dsh plugin --profile web add github:hajimilvdou/dsh-storecloud

> ⚠️ 安装地址为 github: 源（或本地 tarball）；尚未发布到 npm 官方源，请勿使用 dsh plugin add dsh-storecloud 裸包名（npm 安装会失败）。 > ⚠️ Windows 注意：tarball/目录路径含空格时 dsh plugin add 的 cmd 拼接会失败，请用不含空格的路径。

---

使用说明

首次使用（三步）

1. 按上面命令安装并重启 DSH web 进程； 2. 打开商城：设置页「🧩 插件商城」区块，或会话头部「🧩 插件商城」Tab； 3. 等待插件库首次同步（本地缓存秒开，全量数据后台拉取，之后打开即用）。

登录与登录 token

• 商城「我的」页 → 点「⚡ 立即登录 GitHub」→ 新窗口完成授权 → token 自动回传并保存到本地（dsh_store_token），全程无需手动复制/粘贴；
• 再次打开商城自动恢复登录态；换电脑/换环境：装好插件 → 登录一次 → 云端组合/订阅/安装记录自动拉回，无需额外查找记录；
• 数据通道（浏览/搜索/安装）不登录也能用；登录仅用于云端同步与社区功能（发布插件/组合、订阅、点赞）；
• 如果登录按钮跳转后无反应：服务器端未配置 OAuth（需在服务端管理端配置中心填入 GitHub OAuth Client ID/Secret + JWT_SECRET，见服务器端 README「使用说明」）。

自建服务器的搜索 token

• 插件库的自动收录依赖服务端的 GitHub 搜索 token（classic PAT）：在 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) 生成，填入服务端管理端 → 配置中心 → 搜索 token（或环境变量 GITHUB_TOKENS）；
• 只有打了 dsh-plugin topic 的仓库才会被收录；未配置搜索 token 时服务端同步与登录休眠，浏览/下载计数不受影响。

---

配置

插件通过 profile 的 cordis.patch.yml 传配置（全部可选，默认即用）：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-storecloud
  config:
    serverUrl: https://你的商店服务器   # 默认连接作者的服务器
    profileName: web                    # 本地安装器目标 profile（默认 web）
    # dshHome: ~/.dsh                  # DSH 家目录（默认 $DSH_HOME 或 ~/.dsh）
    # cacheTtlMs: 10000                # 静态资源缓存 TTL

环境变量兜底：DSH_STORE_SERVER_URL（服务器地址）、DSH_HOME（家目录）。

---

仓库结构（源码 + 产物统一）

dsh-storecloud/
├── packages/                # 📦 源码（改 bug 在这里改）
│   ├── shared/              #   @dsh-store/shared —— 跨端契约（协议/模型/API/配置）
│   └── client/              #   @dsh-store/client —— 商城 UI（React）+ 数据层/台账/核心纯函数
├── docs/                    # 设计文档（v3 ~ v3.7）与界面原型
├── lib/
│   ├── index.js             # 产物 · host 半（Node cordis 插件）：路由/反代/RPC/静态资源
│   └── client.js            # 产物 · client 半（浏览器）：双入口槽位（零依赖）
├── preview/                 # 产物 · 商城 UI 静态资源（由 packages 构建）
├── cordis.patch.yml         # bundle 层：插入本插件 loader 行
├── scripts/
│   ├── build.mjs            # 全链路构建：tsc workspaces → esbuild preview → 语法检查
│   └── verify-client.mjs    # 客户端半渲染自检（真实 React 渲染三槽位）
├── smoke-test.mjs           # 冒烟测试（core 纯函数 + mock 桥接全链路）
└── preview-server.mjs       # 本地预览服务器

发布产物 tarball（npm pack）只含产物（files 白名单）；GitHub 仓库含全部源码，随时可重新构建。

---

开发 / 修 bug

npm install                # 安装构建依赖
npm run build              # 全链路：tsc → esbuild → preview/preview.js
npm run typecheck          # 源码类型检查 + lib 语法检查
npm run smoke              # 冒烟测试
npm run verify:client      # 客户端半渲染自检
npm pack                   # 产出发布 tarball

改 bug 流程：改 packages/client/src/**（UI/数据层）→ npm run build；改壳层（入口/安装器）→ 直接改 lib/index.js / lib/client.js。重新发布：npm pack + 上传 tarball / push git。

发版流程（版本号单一事实来源）

1. bump 版本：只改根 package.json 的 version（如 0.1.0 → 0.2.0）； 2. 构建：npm run build——自动把版本注入 packages/client/src/generated-version.ts（构建产物 preview.js 内联）； 3. 提交：连同 generated-version.ts 与产物一起 git push； 4. 服务器推送：服务端管理端 → 系统更新 →「客户端插件版本推送」→ 安装地址填 github:hajimilvdou/dsh-storecloud → 点 「🔍 从 GitHub 检测」自动读回最新版本 → 保存推送； 5. 用户侧：客户端（host 半 /version RPC 报告真实安装版本）检测到推送版本更新 → 横幅提示 → 一键更新 → 重启 DSH web 生效。

> 版本判断以实际安装的包版本为准（git/npm/tgz 安装都准确），不依赖任何手动维护的常量。

---

服务器端

仓库地址：<https://github.com/hajimilvdou/dsh-store-server>

• 部署自己的云端服务器（一条命令从零拉起：建库 → 迁移 → 起服务 → 自检）；
• GitHub 自动收录插件库（topic:dsh-plugin）、联邦互联、管理端配置中心、面板一键热更新；
• 部署、配置、联邦、升级回滚等细节具体看服务器端仓库的 README。

---

GitHub 标签（Topics）

DSH 插件商店的服务端通过 GitHub topic 自动收录插件仓库，请给本仓库打上以下标签：

> 打上 dsh-plugin topic 后，运行中的商店服务器会在下一次同步时自动收录本仓库；package.json 的 name 即插件安装名，未发布 npm 时商店自动回落为 github:owner/repo 安装地址。

---

许可

本项目采用 CC BY-NC-SA 4.0（署名-非商业性使用-相同方式共享） 开源协议：

• ✅ 可自由使用、修改、分发，但禁止商业化使用；
• 📝 使用须署名；衍生作品须以相同协议共享；
• 🔗 完整法律文本：<https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode>

---

常见问题

• 装完看不到商城？ 确认重启了 web 进程；或在浏览器设置页 →「插件管理」检查 dsh-storecloud 状态。
• 连不上服务器？ 默认服务器需可访问；页面右上角「我的」可查看连接状态，?server= 可临时切换。
• 本地安装按钮报错？ 安装器需要本机 dsh CLI 可达（~/.dsh/profiles/node_modules/@deepseek-ai/dsh 或 PATH）；服务器需放行对应插件条目。