部署与配置

August 25, 2026 · View on GitHub

面向部署方与运维：把插件装进托管服务、接自己的配置站、锁定 Skill 版本、改工作台的叫法。只想在本机用一下的读者不需要这一页，README 就够了。

插件加载在 Host 平面，不是 Agent Preset

README 里的 dsh plugin add 会把插件写进 profile 的 bundles，也就是 Host 组合——这是它唯一能工作的位置。托管部署自己拼装 profile 时同理，在 cordis.patch.yml 里 insert：

- insert:
    - id: aws-wechat-article
      name: '@aiworkskills/aws-wechat-article'

不要写进 Agent Preset 的 agent.cordis.yml。 插件注册的是进程级 Cordis 服务（wechatArticleConfiguration、wechatProductLibrary、wechatSkillSource），Harness 会拒绝挂载并报：

preset service must sit behind an `isolate` realm or move to the host composition

这条报错不会指出该放哪，照着「装插件」的直觉放进 Preset 很容易撞上。

换一个目录布局

README 里的安装命令把两个仓库放在固定位置，是为了让复制粘贴就能跑通。这个布局不是必须的。

构建客户端界面时需要读取 Harness 源码里的构建预设（这部分没有随 npm 发布），默认按 ../../deepseek-harness 查找。仓库放在别处时，用 DSH_SOURCE_ROOT 指明位置即可：

DSH_SOURCE_ROOT=/path/to/deepseek-harness pnpm build

容器构建、CI 以及把插件放进自有工作区的情况都适用。路径无效时构建会直接说明缺少什么，而不是抛出一串类型错误。

使用预置的 Skill 检出

默认情况下，公众号 Skill 由插件 git clone 到 DSH_HOME 下，每个 DSH_HOME 各持一份。单机单用户时这样最省事。

托管部署不适用这个默认值：那里每个用户都有独立的 DSH_HOME，于是每来一个新用户就要重新 clone 一次 GitHub —— 既要求运行环境能访问外网，也让不同用户可能拿到不同版本的 Skill。这类部署预置一份共享检出，并用 skillSourceDir 指向它：

- id: aws-wechat-article
  name: '@aiworkskills/aws-wechat-article'
  config:
    skillSourceDir: /opt/wechat-article-skills

Skill 版本随之固定，启动不再依赖网络。内网隔离环境、企业代理后，以及需要锁定 Skill 版本的场景同理。目录需要是一份完整的 Git 检出（保留 .git，「更新 Skill」才可用）。

换一个配置站

configurationUrl 指定工作台内嵌的配置站，默认 https://aiworkskills.cn/config：

- id: aws-wechat-article
  name: '@aiworkskills/aws-wechat-article'
  config:
    configurationUrl: https://config.example.com/wechat

这一个值同时决定三件事：iframe 打开哪里、postMessage 只信任哪个来源、导入 .aws 配置包时允许来自哪个域（该域及其子域）。

早期版本里浏览器端把站点地址写死了，于是这个配置项只对 Host 侧生效——自建配置站的人改了它，iframe 仍然指向原站，导入还会被一个自己从未配置过的域名拒绝。现在浏览器端从 Host 读取，三处一致。

缩略图

工作台里的缩略图是二十几个像素见方，而喂给它们的原本是全尺寸原图 —— 一篇文章六张配图就是 3 MB。现在 ?thumb=1 会返回一张 96px 的 JPEG（实测 654 KB → 1.5 KB，省 99.8%），在内存里按字节封顶缓存，缓存键含源文件 mtime，因而无需显式失效。

生成依赖 Python 与 Pillow（与图片入库工具同一个 pythonCommand）。拿不到就发原图 —— 缩略图是优化不是能力，没装 Pillow 的部署只是慢一点，不会少一块界面。

config:
  thumbnailCacheBytes: 8388608   # 可选，默认 8 MiB

换一个工作台的名字

左边栏那一行默认叫「公众号」。把工作台嵌进更大的产品里时，账号身份往往已经由外面那一层承载了，这一行于是该命名一件事：

- id: aws-wechat-article
  name: '@aiworkskills/aws-wechat-article'
  config:
    workbenchLabel: 创作素材

留空即插件自己的名字。取不到时也照常显示默认名——这一项是称呼，不是能力。

托管部署：把工作台锁在一个工作集上

给每个工作集单独起 Runtime 的托管部署（例如一个用户名下的多个公众号各占一个工作区），把该工作集的标识配成 workspaceId。插件会把它作为 workspace 参数拼进配置站地址：

- id: aws-wechat-article
  name: '@aiworkskills/aws-wechat-article'
  config:
    # 标识由部署方的网关决定，从环境变量注入即可；插件不认识任何具体网关的变量名。
    workspaceId: !!js process.env.YOUR_GATEWAY_WORKSPACE_ID || ''

https://config.example.com/wechat?embed=dsh&protocol=1&parentOrigin=…&workspace=<工作集 id>

对配置站而言这是一条约束：当前工作区属于这个工作集。配置站据此把自己锁在该工作集上，而不是让用户在 iframe 里切到别的账号——否则用户切过去再点「应用配置」，另一个账号的设置连同发布凭据就会被导入这个工作区。

本机单工作区安装不配这一项，也就不带这个参数，配置站行为与以往完全一致：在那里切换账号正是选择「要配哪一个」的方式，去掉反而会把这条路堵死。

插件只陈述事实，怎么处置由配置站决定。