企业官网建设流程全解析

1. dsh-ads 到底是个什么东西，为什么值得单独写一篇

dsh-ads 这个名字第一次看到的时候，很容易让人误以为是个广告投放 SDK 或者某个广告联盟的接入包。实际上它跟广告业务没有半点关系，它是 DSH（DeepSeek Harness）生态里的一个广告位管理插件，核心作用是控制 DSH 界面中各个"广告位"——也就是那些推荐位、提示条、入口卡片的显示与隐藏。你可以把它理解成 DSH 的"界面开关面板"，装好之后你能精确决定哪些模块露出来、哪些藏起来。

我最初接触这个插件是因为 DSH 默认会推一些推荐内容，在调试和演示场景下很干扰视线。手动去改配置文件当然也行，但每次升级或者切换 profile 之后配置就丢了，反复折腾很烦。dsh-ads 解决的正是这个痛点：它把广告位的开关做成了插件级别的配置，跟着 profile 走，切换环境不会丢，还能通过命令行一键 dump 出来看当前状态。

这篇内容适合三类人看：一是刚上手 DSH、还在摸索插件体系的新手；二是需要给团队统一配置 DSH 环境、想找可复现安装路径的运维或工具链同学；三是已经装了 dsh-ads 但被 profile 和 dump-config 搞晕、想搞清楚三条安装路径区别的人。我会把三条安装路径的适用场景、具体命令、踩坑点全部摊开讲，最后附上广告位开关的完整操作和排查表。

需要提前说明的是，DSH 的插件体系迭代比较快，命令参数可能随版本微调，我下面写的都是基于当前主流版本的实践，你实际操作时如果发现某个参数不认，先用--help确认一下，别硬套。

2. 三条安装路径的选型逻辑与适用场景

dsh-ads 的安装不是只有一种方式，官方和社区实践里至少有三条路径可走，它们不是互相替代的关系，而是对应不同的使用场景。很多人装不上或者装上了不生效，根本原因就是选错了路径——比如在 web profile 下用了桌面版的安装方式，插件注册到了错误的 profile，自然看不到效果。

2.1 路径一：通过 dsh plugin add 直接安装（推荐日常使用）

这是最标准、最省心的路径，适合绝大多数个人用户和日常开发场景。核心命令就一行：

dsh plugin --profile web add dsh-ads

这条命令做了几件事：指定--profile web表示把插件注册到 web 这个 profile 下；add dsh-ads表示从插件市场拉取 dsh-ads 并安装。执行完之后 DSH 会自动处理依赖、写入 profile 配置、刷新插件索引。

为什么推荐这条路径？因为它把 profile 绑定做在了命令里，你不需要事后手动去改配置文件，也不容易搞错注册位置。我见过太多人装完插件发现不生效，一查是插件装到了 default profile，而自己实际用的是 web profile，两边对不上。

注意：--profile参数的位置有讲究，必须放在add之前。写成dsh plugin add dsh-ads --profile web在部分版本上会被解析成把--profile web当成插件参数传给 dsh-ads，结果就是装上了但 profile 没绑对。这个坑我踩过，排查了半小时。

如果你不确定当前有哪些 profile，可以先跑：

dsh plugin --list-profiles

或者直接看配置目录下的 profile 清单。确认好目标 profile 再执行 add，能省掉后面一堆麻烦。

2.2 路径二：从插件市场手动下载后本地安装

这条路径适合网络环境受限、或者需要装特定版本的情况。DSH 插件市场（dsh market）里能搜到 dsh-ads，但有时候市场页面加载慢，或者你想装一个市场里已经更新掉的旧版本，就需要手动下载安装包再本地 add。

操作流程是这样的：先从市场页面找到 dsh-ads 的发布包，下载下来通常是个压缩包或者.dshpkg格式的文件。然后执行：

dsh plugin --profile web add ./dsh-ads-<version>.dshpkg

把路径换成你实际下载的文件路径。本地安装的好处是版本可控，坏处是依赖不会自动帮你解析，如果 dsh-ads 依赖了某个基础库而你没装，运行时会报模块找不到。

提示：本地安装前先跑一次dsh plugin --profile web list看看已装插件，避免重复安装或者版本冲突。我遇到过本地装了旧版、市场又自动更新到新版，结果两个版本打架的情况，最后只能先 remove 再重装。

2.3 路径三：源码方式安装（适合二次开发和调试）

如果你要改 dsh-ads 的源码、加自定义广告位规则，或者想跟进最新未发布的功能，就得走源码安装。把仓库 clone 下来，进到目录里，然后：

dsh plugin --profile web add . --link

--link是关键，它建立的是软链接而不是拷贝，你改源码后不用重新安装，DSH 直接读你本地的文件。调试插件逻辑的时候这条路径效率最高。

但源码安装也有代价：你需要自己保证依赖装齐，通常进目录先跑一遍包管理器的 install。另外--link模式下如果源码目录被移动或删除，插件就会失效，DSH 启动时可能报错。所以源码安装适合开发机，不适合生产或演示环境。

三条路径对比一下更清楚：

选路径的原则很简单：能用市场装就用市场装，装不了再本地包，要改代码才上源码。别为了"显得专业"一上来就源码安装，后面依赖问题能把你拖垮。

3. profile 机制与 dump-config 的配合使用

搞懂 profile 是玩转 dsh-ads 的前提。DSH 的 profile 本质上是一套配置隔离机制，你可以把它类比成浏览器的多用户配置——每个 profile 有独立的插件列表、独立的设置、独立的广告位开关状态。web profile 和桌面版 profile 是两套东西，插件装在哪套里，就只在哪套生效。

3.1 profile 的查看、切换与常见误区

查看当前有哪些 profile，最直接的方式是看配置目录。不同系统路径不一样，但通常都在用户目录下的.dsh或者dsh配置文件夹里。命令行方式：

dsh profile list

切换 profile 用：

dsh profile use web

这里有个高频误区：很多人以为dsh plugin --profile web add之后，当前会话就自动切到 web profile 了。并不是。add 只是把插件注册到 web profile，你当前实际使用的 profile 可能还是 default。要真正生效，得确认当前 profile 就是 web，或者显式切换过去。

注意：桌面版和 web 版的 profile 命名可能不同。桌面版有时用desktop或app作为 profile 名，web 版用web。装插件前先确认你实际运行的是哪个版本，profile 名对不上，插件就是装了白装。

我自己的习惯是，装完插件立刻跑一次dsh profile current确认当前 profile，再跑一次插件列表确认 dsh-ads 在列表里。两步都对了，才继续往下配广告位。

3.2 dump-config 到底 dump 出了什么

dump-config是排查 dsh-ads 问题的核心工具，它把当前 profile 下的完整配置导出成可读格式。命令很简单：

dsh dump-config --profile web

输出内容通常包括插件列表、每个插件的配置项、广告位的开关状态、以及一些运行时参数。为什么这个命令重要？因为广告位开关的实际状态，光看界面不一定准——界面可能缓存了旧状态，或者某个开关被上层配置覆盖了。dump-config 拿到的是配置源头，最可信。

我一般会配合重定向把输出存下来：

dsh dump-config --profile web > dsh-web-config.yaml

存成文件之后可以 diff，比如你改了一个广告位开关，再 dump 一次，两次对比就能确认改动有没有真正写进去。这个技巧在排查"改了不生效"类问题时特别管用。

dump 出来的配置里，dsh-ads 相关的部分通常长这样（字段名以实际版本为准）：

plugins: dsh-ads: enabled: true slots: recommend-card: false promo-banner: true entry-tip: false

slots下面就是各个广告位的开关，true是显示，false是隐藏。你直接改这个文件再让 DSH 重载配置也行，但更推荐用插件提供的命令改，避免格式写错导致整个配置加载失败。

3.3 profile 与 dump-config 的联动排查思路

当 dsh-ads 表现异常时，我有一套固定的排查顺序：先dsh profile current确认当前 profile，再dsh plugin --profile <当前profile> list确认插件在不在，然后dsh dump-config --profile <当前profile>看配置里 dsh-ads 的 enabled 和 slots 状态。三步走完，问题基本能定位到是"装错 profile"、"插件没启用"还是"开关状态不对"。

这套顺序的价值在于它把问题空间从"插件不工作"这种模糊描述，收敛到了具体的某一层。很多人一上来就重装插件，其实问题可能只是当前 profile 不对，重装十遍也没用。

4. 广告位开关的完整操作与参数详解

dsh-ads 的核心功能就是广告位开关，这部分值得单独拎出来讲透。广告位在 DSH 里指的是界面上那些可配置的展示模块，不同版本叫法可能不同，但逻辑一致：每个广告位有个唯一标识，开关状态存在 profile 配置里，插件负责读取状态并应用到界面。

4.1 广告位的识别与命名规则

要开关广告位，首先得知道每个广告位的标识名。获取方式有两种：一是 dump-config 之后看 slots 下面的 key，二是用插件自带的列表命令：

dsh plugin --profile web exec dsh-ads list-slots

不同版本的命令可能略有差异，有的用list，有的用slots，以--help为准。列出来的标识名通常是小写加连字符，比如recommend-card、promo-banner、entry-tip这种。

为什么命名规则重要？因为开关命令里要用到这些标识名，写错一个字符就不生效，而且不一定报错——插件可能静默忽略未知的 slot 名。我建议第一次配置时把 list-slots 的输出复制下来，别手敲。

4.2 单个广告位的开启与关闭

关闭一个广告位：

dsh plugin --profile web exec dsh-ads disable recommend-card

开启：

dsh plugin --profile web exec dsh-ads enable recommend-card

执行完之后，界面不一定立刻刷新，有的版本需要重启 DSH 或者手动触发一次配置重载。我一般改完就跑一次 dump-config 确认状态写进去了，再重启验证界面效果。

提示：批量操作时可以用逗号分隔多个 slot 名，比如disable recommend-card,promo-banner，但不是所有版本都支持，先拿一个 slot 试一下确认语法。

4.3 广告位开关的持久化与 profile 迁移

广告位开关状态是存在 profile 配置里的，这意味着它跟着 profile 走。你把 web profile 的配置导出，换台机器导入，开关状态能一起带过去。这对团队统一环境很有用——一个人配好，dump 出来发给同事，同事导入即可。

但要注意，dump-config 导出的是完整配置，里面可能包含一些机器相关的路径或密钥。分享之前把敏感字段清掉，只保留 dsh-ads 相关的 slots 部分。我通常的做法是导出后手动裁剪，只留 plugins.dsh-ads 这一段，别人拿到后合并进自己的配置。

迁移时还有个坑：不同版本的 slot 名可能变过。旧配置里的 slot 名在新版本里如果不存在，插件可能报错或者忽略。所以跨版本迁移后，务必重新跑一次 list-slots 核对，把失效的 slot 名替换掉。

5. 常见问题与排查技巧实录

dsh-ads 的安装和配置过程中，问题集中在几个固定位置。我把踩过的坑整理成速查表，遇到问题先对号入座，能省不少时间。

除了表格里的，还有几个不那么常见但很折磨人的问题。一个是权限问题：在某些系统上，DSH 配置目录的写权限不对，插件装的时候看似成功，实际配置没写进去。排查方式是看配置文件的修改时间，如果装完时间没变，基本就是权限问题。另一个是缓存问题：DSH 有时会缓存插件索引，装了新插件但列表里看不到，清一下缓存目录再重启就好。

注意：排查时优先用 dump-config 看配置源头，别只盯着界面。界面是配置的下游，配置对了界面才对，反过来推容易绕远路。

我个人的经验是，dsh-ads 这类插件的问题，八成出在 profile 和配置重载这两环。把这两环的确认动作固化成习惯——装完确认 profile、改完确认 dump——能挡掉绝大多数故障。剩下两成里，一半是版本不匹配，一半是 slot 名写错，都有明确的排查路径。

最后分享一个我常用的组合命令，装完插件后一次性确认状态：

dsh profile current && dsh plugin --profile web list | grep dsh-ads && dsh dump-config --profile web | grep -A 10 dsh-ads

三条命令串起来，profile、插件列表、配置状态一次看全。如果这三步输出都正常，dsh-ads 基本就是可用状态，剩下的只是按需调广告位开关了。这个习惯帮我省掉了大量"装了但不确定好没好"的反复验证时间。