企业官网建设流程全解析

1. 先搞清楚 dsh-ads 到底是个什么东西

dsh-ads 这个名字，第一次看到的人大概率会以为是某个广告投放 SDK，或者是个浏览器去广告插件。实际上它跟这两件事都不沾边。dsh-ads 是 DSH（DeepSeek Harness）生态里的一个广告位管理模块，核心作用是控制 DSH 运行过程中各个界面位置上的推广内容、推荐位、提示条是否展示。你可以把它理解成一个“开关面板”——它不生产广告，它只是广告的搬运工和闸门。

DSH 本身是一套面向开发者的本地化 AI 辅助运行框架，支持 web profile、桌面版、命令行三种形态。dsh-ads 作为它的一个可选组件，默认不一定随主程序安装，需要单独拉取和配置。很多人第一次接触 dsh-ads 是因为在 DSH 的 web 界面里看到了不想看的推荐位，或者反过来，想让某些提示条重新出现却找不到开关在哪。这时候就需要把 dsh-ads 装回来，然后通过配置文件精确控制每一个广告位的状态。

这篇文章适合三类人看：第一类是完全没装过 dsh-ads、想从零开始走一遍完整流程的新手；第二类是装是装上了，但搞不清楚三条安装路径之间有什么区别、该选哪条的老哥；第三类是已经装好了，但广告位开关怎么调都不生效、想找个排查思路的。我会把三条安装路径的每一步都拆开讲，包括命令、参数、目录结构、配置文件格式，以及我在实际配置过程中踩过的那些坑。

关键词先摆出来，方便你对号入座：dsh-ads、DSH、web profile、dump-config、插件安装。这几个词贯穿全文，后面每个章节都会围绕它们展开。不管你是用 web 版、桌面版还是命令行版，dsh-ads 的安装逻辑是相通的，区别只在于入口和配置文件的落盘位置。

注意：dsh-ads 的版本需要和 DSH 主程序版本匹配。主程序升级后，dsh-ads 最好同步更新，否则可能出现配置项不识别的情况。这个后面会详细说。

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

2.1 为什么会有三条安装路径

DSH 的设计哲学是“一套核心，多种外壳”。核心逻辑跑在同一个引擎里，但用户接触到的界面可以是浏览器、可以是桌面窗口、也可以是纯终端。dsh-ads 作为依附于核心的模块，安装方式自然也要跟着外壳走。三条路径分别对应 web profile、桌面版、命令行版，它们最终做的事情是一样的——把 dsh-ads 的代码拉到本地、注册到 DSH 的模块加载器里、生成一份默认配置。但入口不同，中间步骤不同，出错的地方也不同。

我一开始以为三条路径只是“换个命令”的区别，后来发现完全不是。web profile 走的是浏览器端的模块注入，桌面版走的是本地包管理，命令行版走的是源码级挂载。三条路各有各的脾气，选错了会多绕很多弯路。

2.2 三条路径的对比与选择建议

选哪条路，取决于你平时怎么用 DSH。如果你只是偶尔在浏览器里跑一下，web profile 最省事；如果你天天开着桌面客户端干活，桌面版路径最稳；如果你要把 DSH 集成到自动化流程里，命令行版是唯一选择。

2.3 选型时容易忽略的两个点

第一个点是配置的持久性。web profile 的配置存在浏览器本地存储里，换个浏览器或者清了缓存就没了。桌面版和命令行版的配置是落盘的，相对持久。第二个点是权限。命令行版如果装在全局目录，可能需要管理员权限；桌面版一般不需要；web profile 完全在浏览器沙箱里，权限最小。

我个人的建议是：先用 web profile 路径快速试一遍，确认 dsh-ads 的功能符合预期，再根据实际使用场景决定要不要迁移到桌面版或命令行版。这样试错成本最低。

3. web profile 路径：从零到广告位可控

3.1 前置检查：确认 DSH web profile 已就绪

在装 dsh-ads 之前，先确认你的 DSH web profile 能正常跑起来。打开浏览器，进入 DSH 的 web 界面，如果能看到主界面正常加载，说明基础环境没问题。然后打开浏览器开发者工具，切到 Console 面板，输入dsh.version回车，如果能返回版本号，说明 DSH 的全局对象已经挂载。这一步很关键，因为 dsh-ads 的安装脚本依赖这个全局对象。

如果dsh.version返回 undefined，说明 web profile 没有正确初始化。这时候先别急着装 dsh-ads，回去检查 DSH 的 web profile 配置，确认 profile 文件里没有语法错误，确认浏览器没有拦截 DSH 的初始化脚本。

3.2 安装 dsh-ads 到 web profile

web profile 路径的安装，本质上是在浏览器环境里执行一段模块注册脚本。具体操作有两种方式：一种是通过 DSH 自带的插件安装入口，一种是在 Console 里手动执行安装命令。

先说自带入口的方式。在 DSH web 界面的设置里找到“插件管理”或“模块管理”，搜索 dsh-ads，如果列表里有，直接点安装。这种方式最省事，但前提是你的 DSH 版本内置了插件市场，而且市场里有 dsh-ads 这个包。

如果市场里没有，就走手动方式。在 Console 里执行：

dsh.install('dsh-ads', { source: 'registry', version: 'latest', autoConfig: true })

这段命令的意思是：从注册源拉取 dsh-ads 的最新版本，安装后自动生成默认配置。执行完会返回一个安装结果对象，里面包含安装路径和配置文件路径。把这两个路径记下来，后面调广告位开关要用。

提示：如果dsh.install报错说找不到模块，先执行dsh.registry.update()刷新一下注册源索引，再重试。

3.3 验证安装结果

安装完成后，执行dsh.modules.list()查看已加载的模块列表，确认 dsh-ads 在列表里。然后执行dsh.ads.status()，如果返回一个包含各个广告位状态的对象，说明 dsh-ads 已经生效。默认情况下，大部分广告位是开启状态，少数敏感位置是关闭的。

这时候刷新页面，你应该能看到 DSH 界面上的推荐位和提示条按照默认配置显示出来了。如果刷新后界面没变化，可能是浏览器缓存了旧版本，强制刷新（Ctrl+Shift+R）再试。

3.4 web profile 路径的配置调整

web profile 的 dsh-ads 配置存在浏览器的 localStorage 里，key 一般是dsh-ads-config。你可以直接在 Console 里读写这个配置：

// 读取当前配置 const config = JSON.parse(localStorage.getItem('dsh-ads-config')) console.log(config) // 修改某个广告位开关 config.placements.sidebarRecommend = false localStorage.setItem('dsh-ads-config', JSON.stringify(config)) // 通知 dsh-ads 重新加载配置 dsh.ads.reload()

这种方式的优点是即时生效，不用重启任何东西。缺点是配置跟浏览器绑定，换设备就没了。如果你需要跨设备同步，还是得走桌面版或命令行版。

4. 桌面版路径：插件市场与手动导入双通道

4.1 桌面版的插件安装入口在哪

DSH 桌面版的插件安装入口一般在设置菜单里，叫“插件市场”或“扩展管理”。打开后可以看到已安装插件列表和可安装插件列表。dsh-ads 如果在你使用的版本里被收录了，直接搜索安装即可。安装过程中客户端会自动处理依赖和版本匹配，比 web profile 省心。

但实际情况是，dsh-ads 不一定在每个版本的插件市场里都有。我遇到过好几次市场里搜不到的情况，这时候就得走手动导入。

4.2 手动导入 dsh-ads 包

手动导入的第一步是拿到 dsh-ads 的包文件。通常是一个压缩包或者一个目录，里面包含模块代码和一份 manifest 文件。拿到之后，在桌面版的插件管理界面选择“从本地导入”，指向包文件或目录，客户端会读取 manifest 并完成注册。

导入过程中最容易出问题的地方是 manifest 里的版本号跟客户端版本不匹配。如果客户端提示“不兼容的插件版本”，有两个选择：一是找对应版本的 dsh-ads 包，二是修改 manifest 里的版本约束。我一般建议找对应版本，改 manifest 虽然能绕过检查，但可能埋下运行时错误的隐患。

4.3 桌面版的配置文件位置与格式

桌面版安装完成后，dsh-ads 的配置文件一般落在用户数据目录下，路径类似：

• Windows:%APPDATA%/DSH/config/dsh-ads.json
• macOS:~/Library/Application Support/DSH/config/dsh-ads.json
• Linux:~/.config/DSH/config/dsh-ads.json

配置文件是标准 JSON 格式，结构大概是这样：

{ "version": "1.0.0", "placements": { "sidebarRecommend": true, "topBanner": false, "footerTip": true, "welcomeCard": true, "upgradePrompt": false }, "refreshInterval": 3600, "logLevel": "info" }

每个字段的含义后面会详细解释。改完配置后，桌面版一般需要重启客户端才能生效，或者在插件管理界面点“重新加载”。

4.4 桌面版路径的注意事项

桌面版路径有一个坑：客户端升级后，配置文件可能被重置。我遇到过升级 DSH 桌面版之后，dsh-ads 的配置全部回到默认值的情况。所以改完配置后，最好备份一份，升级前先导出，升级后再导入。

另一个坑是配置文件编码。JSON 文件必须是 UTF-8 无 BOM 格式，如果用某些编辑器保存成了带 BOM 的 UTF-8，客户端解析会报错。这个错误提示往往很模糊，只说“配置加载失败”，不告诉你具体原因。遇到这种情况，用十六进制编辑器看一下文件头有没有 BOM 标记。

5. 命令行版路径：dump-config 与脚本化控制

5.1 命令行版的安装流程

命令行版的安装分三步：拉取模块、注册模块、生成配置。拉取模块一般用包管理命令，比如：

dsh module install dsh-ads --registry official

注册模块是让 DSH 核心知道 dsh-ads 的存在：

dsh module register dsh-ads --path ./modules/dsh-ads

生成配置是用 dump-config 命令导出默认配置：

dsh ads dump-config --output ./config/dsh-ads.json

这三步做完，dsh-ads 就装好了。后面调广告位开关，直接改./config/dsh-ads.json就行。

5.2 dump-config 命令的详细用法

dump-config 是 dsh-ads 提供的一个配置导出工具，作用是把当前生效的配置完整地输出成 JSON 文件。它的常用参数包括：

我一般会用--include-defaults，这样导出的配置里包含所有可配置项，方便对照着改。如果不加这个参数，导出的配置只包含被显式修改过的项，看起来会少很多。

5.3 命令行版的配置生效机制

命令行版的配置生效有两种方式：一种是重启 DSH 进程，一种是发送重载信号。重启最简单，但会中断正在运行的任务。发送重载信号更优雅：

dsh ads reload --config ./config/dsh-ads.json

这条命令会让 dsh-ads 重新读取配置文件并应用，不需要重启整个 DSH。如果你是在脚本里控制广告位开关，用这种方式最合适。

5.4 命令行版在自动化场景中的应用

命令行版最大的价值是可以脚本化。比如你可以在 CI 流程里根据环境变量决定广告位开关：

#!/bin/bash if [ "$ENV" = "production" ]; then dsh ads set --placement upgradePrompt --value false dsh ads set --placement topBanner --value false else dsh ads set --placement upgradePrompt --value true fi dsh ads reload

这种用法在 web profile 和桌面版里都做不到，是命令行版独有的优势。

6. 广告位开关的完整清单与配置详解

6.1 广告位开关的分类

dsh-ads 控制的广告位大致分四类：侧边栏推荐位、顶部横幅、底部提示条、欢迎卡片。每一类下面可能还有细分，比如侧边栏推荐位可能分“推荐插件”和“推荐配置”两个子位。具体有哪些开关，取决于你安装的 dsh-ads 版本。

查看完整开关列表的命令是：

dsh ads list-placements

这条命令会输出所有可控制的广告位标识符和当前状态。web profile 里对应的命令是dsh.ads.listPlacements()。

6.2 每个开关的含义与默认值

默认值不是固定的，不同版本可能不一样。以dsh ads list-placements的输出为准。

6.3 修改开关的三种方式

第一种是直接编辑配置文件，改完 reload。这种方式适合批量修改。第二种是用dsh ads set命令逐个修改，适合脚本化。第三种是在 web profile 的 Console 里用dsh.ads.set()修改，适合临时调整。

三种方式改的是同一份配置，只是入口不同。我一般批量改用第一种，临时调用第三种，自动化用第二种。

6.4 开关不生效的常见原因

开关改了但界面没变化，最常见的原因是配置没 reload。改了配置文件不等于生效，必须执行 reload 命令或重启。第二个原因是缓存，web profile 里浏览器可能缓存了旧的模块代码，强制刷新可解决。第三个原因是开关标识写错了，比如把sidebarRecommend写成了sidebar-recommend，标识符是大小写敏感的。

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

7.1 安装阶段的问题

问题一：dsh.install报错“module not found”

这个错误一般是注册源索引没更新。先执行dsh.registry.update()，再重试安装。如果还是不行，检查网络是否能访问注册源，或者换一个注册源。

问题二：桌面版导入包时提示“manifest 解析失败”

大概率是 manifest 文件格式有问题。用 JSON 校验工具检查一下，确认没有多余的逗号、引号不匹配等低级错误。另外确认 manifest 里的main字段指向的入口文件确实存在。

问题三：命令行版dsh module register报权限错误

如果 DSH 装在全局目录，注册模块可能需要管理员权限。用sudo重试，或者把 DSH 装到用户目录下避免权限问题。

7.2 配置阶段的问题

问题四：dump-config 输出的文件是空的

检查是否加了--include-defaults。不加这个参数时，如果没有任何显式修改过的配置，输出就是空的。另外确认 dsh-ads 模块已经正确加载，没加载的模块 dump 不出配置。

问题五：改了配置文件但 reload 报错

先检查 JSON 格式是否合法。JSON 对格式要求很严，多一个逗号少一个引号都会导致解析失败。用python -m json.tool config.json验证一下。如果格式没问题，检查配置项的 key 是否跟当前版本匹配，版本不匹配时会出现未知 key，某些严格模式下会报错。

问题六：广告位开关改了但界面没变化

按这个顺序排查：确认 reload 命令执行成功；确认改的是当前生效的配置文件（有时候有多个配置文件，改错了文件）；确认开关标识正确；强制刷新界面清除缓存；最后重启 DSH 进程。

7.3 版本兼容性问题

问题七：主程序升级后 dsh-ads 报错

主程序升级可能改变了模块加载接口，导致旧版 dsh-ads 不兼容。解决办法是同步升级 dsh-ads 到匹配版本。如果找不到匹配版本，可以尝试修改 dsh-ads 的 manifest 版本约束，但这只是临时方案。

问题八：配置文件里的某些 key 不被识别

新版本可能删除了某些配置项，或者重命名了。用dsh ads dump-config --include-defaults导出当前版本的完整配置，对照着看哪些 key 变了。

7.4 排查速查表

8. 我在实际配置中总结的几条经验

第一条经验：不管走哪条安装路径，装完之后第一件事都是dump-config导出一份完整配置备份。这份备份在后续出问题时能救命，尤其是升级之后配置被重置的情况。

第二条经验：web profile 路径适合试错，桌面版路径适合日常使用，命令行版路径适合自动化。三条路径不是互斥的，你可以在不同场景下用不同路径，配置可以各自独立。

第三条经验：广告位开关的修改尽量走配置文件，少用命令行逐个 set。配置文件改起来直观，能一眼看到所有开关的状态，命令行 set 多了容易乱。

第四条经验：遇到报错先看日志。dsh-ads 的日志一般在 DSH 的日志目录下，文件名包含 dsh-ads。日志里的错误信息比界面上的提示详细得多，能省很多排查时间。

最后分享一个小技巧：如果你不确定某个开关对应界面上的哪个位置，可以先把所有开关关掉，然后逐个打开，观察界面变化。这样能快速建立开关标识和实际位置的对应关系。这个方法比看文档快，尤其适合文档不全的版本。