upsello-ai

# upsello-ai

Upsello 是 Shopify 店铺运营 Agent —— 以 DeepSeek Harness（DSH） 插件的形式分发。装进你的 DSH profile 之后，它会在对话中作为店铺运营助手出现， 并给 Web 界面的侧边栏加一个店铺运营面板入口。

安装

前置条件：Node.js >=22、DeepSeek Harness >=0.2.0 <0.3.0、pnpm。

# 1) 安装（一条命令，profile 不存在会自动建好）
npx upsello-ai install --profile upsello

# 2) 启动
dsh --profile upsello --port 3081 --no-open

启动日志会打印一个带 ?token= 的登录地址，浏览器打开它即可进入。

这条命令会装上两个包：upsello-ai，以及它配套的 Bot 团队 ds-bot。 两个都要装 —— DSH 只激活 profile 的直接依赖，少装的那一个虽然进了 node_modules，插件和它的界面都不会被加载。

不想用 npx 时，底层命令等价：

dsh plugin --profile upsello add ds-bot upsello-ai

（Bot 团队写在前面：DSH 按 profile 中列出的顺序合成各插件层。）

安装器会从你配置的 registry 上取最新版本装（显式指定版本号）， 所以刚发布的新版不用等 24 小时就能升上去。

如果你用的是淘宝镜像这类同步有延迟的源：镜像还没追上时安装器会自己发现， 并从公共源装；镜像正在同步、第一次装不上时也会自动改用公共源重试一次。 也可以直接指定用哪个源：

npx upsello-ai install --profile upsello --registry https://registry.npmjs.org/

Docker 部署

本包自带一套 Docker 配方（包里的 docker/ 目录）：一个容器跑 DeepSeek Harness， 同一个 profile 里装着 Bot 团队和 Upsello。适合 NAS 或任何常开着的机器。

1. 把配方取出来

docker/ 目录跟着 npm 包一起发布，先解包：

npm pack upsello-ai
tar -xzf upsello-ai-*.tgz
cd package/docker

2. 填变量

两种方式选一种，别同时用：

# 方式一：直接改 compose.yml（推荐，变量一目了然）
# 填 DEEPSEEK_API_KEY、SHOPIFY_ADMIN_TOKEN、SHOPIFY_SHOP_DOMAIN、
# DSH_TRUSTED_HOST（你实际打开界面用的 IP 或域名）

# 方式二：用 .env 文件
cp env.example .env
# 改 .env 里同样的几项

3. 起容器

docker compose up -d --build
docker compose logs upsello

容器内固定监听 3080，compose 把它发布到宿主机的 13080。 启动日志里有一行带 ?token= 的登录地址，取出 token， 浏览器打开 http://<你的机器 IP>:13080/?token=... 即可。

换成 .env 方式时，compose.yml 里要改用 env_file， 否则里面写死的空值会盖住 .env 里的值：

services:
  upsello:
    env_file: .env

启动日志会打印带 ?token= 的登录地址，用宿主机端口（默认 13080）打开即可。 环境变量、目录挂载、HTTPS、权限与更新说明见包里的 docker/README.md。

运行时要求

依赖	要求	说明
Node.js	>=22
DeepSeek Harness	>=0.2.0 <0.3.0	覆盖 0.2.0-rc.x 等预发布版本
pnpm	任意近期版本	插件安装会转发给 pnpm
Bot 团队 (ds-bot)	^0.2.2	随本包一起安装

配置店铺凭据

凭据由你自己填写，插件不携带、也不内置任何密钥。

变量	作用
SHOPIFY_ADMIN_TOKEN	Shopify Admin API 访问令牌（shpat_ / shpca_ 等）
SHOPIFY_SHOP_DOMAIN	店铺域名，例如 my-store.myshopify.com

两个变量都不写入插件产物，也不会出现在工具返回值里。 插件只在进程内读取它们，shopify_status 返回的字段只有 tokenConfigured 与 shopDomain，永远不返回令牌本身。

export SHOPIFY_ADMIN_TOKEN=shpat_xxx
export SHOPIFY_SHOP_DOMAIN=my-store.myshopify.com
dsh --profile upsello --port 3081 --no-open

提供的能力

工具：shopify_status

告诉模型「店铺连接是否配置好、指向哪个店」，不泄露凭据。

{
  "tokenConfigured": true,
  "shopDomain": "my-store.myshopify.com",
  "summary": "The Shopify store connection is configured for my-store.myshopify.com. ..."
}

运营人设

注入一段店铺运营助手的人设：告诉模型它是店铺运营助手，连接没配好时先要求配置， 任何时候都不要打印令牌。

侧边栏入口

在 Web 界面的侧边栏底部加入一个入口按钮，用来打开店铺运营面板。

确认安装成功

dsh --profile upsello --dump-config | grep "^# =="

输出里应当同时出现 ds-bot 与 upsello-ai 两层：

# == @deepseek-ai/dsh-base
# == @deepseek-ai/dsh-web-app
# == ds-bot
# == upsello-ai

少任何一层，就按下面的「常见问题」重装一次。

常见问题

安装报 No matching version found for upsello-ai@...

你的 npm 镜像还没同步到这个版本 —— 镜像在同步过程中， 「精简的包信息」常常先更新，「完整的包信息」稍后才跟上， 两者对不上时 npm 就会这样报错。换个源立刻可装：

npx upsello-ai install --profile upsello --registry https://registry.npmjs.org/

npm 自己缓存的包信息也可能还没更新，缓存卡住时清一下：

npm cache clean --force

镜像追上之后，原来的命令（npx upsello-ai install --profile upsello）也能正常用。

报 npm error could not determine executable to run

当前目录的 node_modules 里有一份旧的 upsello-ai，npx 优先用了它 （旧版本里还没有这个可执行文件）。清掉再重跑：

rm -rf node_modules/upsello-ai
npx upsello-ai install --profile upsello

提示「a newer installer is published」

npx 会把下载过的版本缓存起来，可能一直跑旧的那份安装器。 按提示里给出的命令指定版本重跑即可：

npx --yes upsello-ai@<版本> install --profile upsello

界面上看不到 Bot 团队

多半是只装了 upsello-ai、没装 ds-bot。先确认上面那条命令的输出里有没有 # == ds-bot，没有就重装：

npx upsello-ai install --profile upsello

在界面上开关插件后没有变化

当前 DSH 版本的插件开关不会热重载，点「停用 / 启用」还会报 dsh: profile reload requires the root Include entry。开关状态其实已经保存了， 重启 DSH 即可生效：

dsh --profile upsello --port 3081 --no-open

shopify_status 返回 tokenConfigured: false

凭据没配好。检查 SHOPIFY_ADMIN_TOKEN 与 SHOPIFY_SHOP_DOMAIN 两个环境变量 是否在启动 DSH 的那个终端里设置了。

端口被占用

内置 web profile 占着 3080，换一个端口：

dsh --profile upsello --port 3081 --no-open

访问返回 403

DSH 有 Host/Origin 白名单校验。用 http://127.0.0.1:<port> 或 http://localhost:<port> 访问；换成本机 IP 需要把该地址加入 profile 的白名单。

两个 profile 一起跑时 Bot 状态互相覆盖

Bot 团队在 $DSH_HOME/bot/state.lock 上使用所有 profile 共享的单写者锁。 同一台机器上只让一个 profile 带 Bot 团队运行。

升级与卸载

# 升级（两个包一起升）
npx upsello-ai install --profile upsello

# 卸载（两个包一起移除）
dsh plugin --profile upsello remove ds-bot upsello-ai

升级或卸载后重启 DSH 才会生效。

安装器会按 registry 上的最新版本装（显式指定版本号），所以刚发布的新版 不用等就能升上去。

许可证

Apache-2.0