企业官网建设流程全解析

代码圈子有个词叫“脚手架”，过去一听就觉得是“能跑，但什么都还没发生”的半成品。可 DeepSeek Harness（下面我直接叫它 DSH）这个项目让我改观不少。当时下载它的第一版目录，plugins、hooks、models、workflows 摆得清清楚楚，明摆着告诉你：我不是一个聊天网页，我是一个带插槽的宿主。真正让我惊讶的不是它本身能聊，而是我往 plugins 目录里塞了几个插件之后，这个壳长出了一个工具该有的样子——能抓网页、能挂知识库、能回退代码、能归档会话。今天这篇就是聊聊 DSH 的插件机制底层是怎么设计的，以及在什么场景下，脚手架才能真变成拿得出手的产品。

1. 先搞清楚：DeepSeek Harness 到底在解决什么问题

1.1 大多数 AI 工具的问题：功能是焊死的

以前我做 AI 工具总踩同一个坑：功能全写死在主程序里。想加一个网页抓取，改主代码；想换一个模型服务商，改主代码；想给回复加个数学公式渲染，还是改主代码。改多了主程序就变成一团乱麻，今天加了 A 功能，明天 B 功能坏了，再往后我自己都不敢动。

这种“焊死功能”的架构有一个致命问题：它把“核心循环”和“扩展功能”塞进了同一个进程、同一套代码里。而 DSH 的做法刚好反过来，核心循环只负责一件事：接收用户输入，带着上下文去问模型，把模型输出返回给用户。至于输入之前要不要做检索、输出之后要不要落盘、上下文要不要压缩，这些全部交给插件。

所以别看 DSH 装完以后界面朴素得像一个半成品，它的设计目标根本不是一个聊天的 Demo，而是一个能装进各种能力的平台。理解了这一点，你再看它的目录结构就不会觉得空，只会觉得“每一层都是留给未来的接口”。

1.2 DSH 的定位：一个带万能插槽的宿主

用生活里的话说，DSH 不是一个讲相声的演员，而是一个舞台。演员（模型、插件、工具）可以换，舞台的灯光、音响、幕布这些基础设施是固定的。它负责把演员请上来，保证流程走完，再把观众的反应传回去。

这就是我理解“万物皆插件”的意思：模型接入是插件，提示词构造是插件，知识库检索是插件，代码回退是插件，甚至 UI 上的一个按钮也可以是插件。对普通用户来说，DSH 是一个聊天工具；但对开发者来说，DSH 是一台什么都能往上面插的机器。

这个设计最大的好处是隔离。插件写坏了，最多是那个功能不可用，主程序不会崩；插件之间可以各自维护依赖，互不污染；插件坏了可以随时拔掉，不用卸载整个 DSH。团队协作的时候，一个人负责模型适配，一个人负责知识库，一个人负责 UI，大家各写各的插件，最后拼在一起就是一个完整产品。

1.3 脚手架本来的样子：能启动，但什么都没有

我第一次跑起 DSH 时，说实话有点失望。默认启动以后就是命令行聊天，支持多轮对话，能保存历史，然后……就没有然后了。没有联网搜索，没有知识库，没有花哨的 Agent 工作流。这就是脚手架的典型气质：骨架在，血肉全空。

但正是这种“空”，才给了插件足够的发挥空间。很多工具一上来塞满功能，反而让用户不知道该聚焦在哪。DSH 把最核心的对话能力做好，剩下的让用户自己选装，就像手机出厂只带基础应用，你要啥上应用商店下啥。这种设计看起来保守，实际后劲很足。我后来装了七八个插件，DSH 从一个只会聊天的壳，变成了我写代码、查资料、做综述时的常用工作台，这一步一步都是插件堆出来的。

2. 插件体系底层：加载、约定与生命周期的设计

2.1 插件的本质：一份合同，而不是一坨代码

插件听起来神秘，本质就是一段被宿主在特定时机加载的代码。但如果没有约定，宿主要怎么知道这段代码该放在哪、怎么初始化、能调用哪些能力？

所以 DSH 里的插件不是“随便扔一个 .py 文件进去就行”，而是必须遵守一份“合同”。这份合同通常由三部分组成：目录结构、清单文件、入口函数。

一个标准插件的目录长这样：

~/.dsh/plugins/session-summarizer/ ├── manifest.json ├── main.py ├── requirements.txt └── README.md

manifest.json 是插件身份证，记录名称、版本、最低宿主 API 版本、需要触发的事件、需要的权限等等。main.py 是真正的实现，它暴露一个 setup 函数，让宿主在加载时把插件注册进事件系统。requirements.txt 声明插件自己的依赖，这样宿主可以单独为它准备一个 Python 环境，不污染主环境。

把插件理解成“一份合同 + 一份实现”，很多问题就清楚了。安装插件不生效，十有八九是合同没签好——manifest 写错、入口函数名不对、事件名不匹配。不是宿主不帮你，是你们俩没对齐。

2.2 插件加载到底发生了什么：扫描、清单、注入

DSH 启动时会做三件事：扫描插件目录、解析清单、注册入口。这个过程外面看着安静，内部其实是一套流水线。

扫描阶段，宿主会读取~/.dsh/plugins/和项目目录下的plugins/两个位置，把它们下面的每个子目录当成一个候选插件。然后它打开每个候选的 manifest.json 校验字段，检查插件声明的min_api_version跟宿主当前版本是否兼容，不兼容的直接跳过并在日志里给出警告。

校验通过后，宿主会使用 Python 的动态导入机制把插件的入口模块加载进来，并调用里面约定的入口函数。我这里写一段简化逻辑示意：

# 简化的插件加载逻辑（示意） def load_plugins(plugin_dir): tasks = [] for folder in plugin_dir.iterdir(): manifesto_path = folder / "manifest.json" if not manifesto_path.exists(): continue info = json.loads(manifesto_path.read_text(encoding="utf-8")) if not compatible(info.get("min_api_version")): continue module = importlib.import_module(f"{folder.name}.main") # 宿主把“事件总线”注入给插件 bus = {} result = module.setup(host_context, bus) tasks.append((info["name"], result)) return tasks

这里最关键的一步是依赖注入：宿主不是把整个 DSH 的源码交给插件，而是把一小套受限的 API 塞给插件。插件只能通过这套 API 订阅事件、读会话、写文件、调用模型，它拿不到宿主的内存，也不能随便执行系统命令。后面做沙箱和权限控制，才是从这一步开始的。

加载顺序也有讲究。不是所有插件一起上，而是先加载模型适配器、再加载文本处理类插件、最后加载输出类插件。这个顺序保证模型先就绪，后面的插件才有东西可干。

2.3 生命周期：什么时候加载、什么时候回调、什么时候收尾

DSH 为插件定义了四个生命周期阶段：初始化、会话中、清理、升级。每个阶段都对应宿主的具体动作。

初始化阶段发生在 DSH 启动时，插件注册自己感兴趣的事件和权限。这里要强调的是：一个插件只要不订阅事件，它平时就是一个死代码，不占用任何对话链路。很多插件性能问题都源于“该订阅的没订阅，不该订阅的全都订阅了”，导致每一次对话都被无关的插件拖住。

会话中的核心是事件回调。DSH 把一次对话拆成多个事件，比如before_send（在把提示词发给模型之前触发）、after_response（在模型返回结果之后触发）、session_start、session_end等等。插件注册了哪个事件，宿主就在对应时机调用它。

清理阶段发生在 DSH 退出或插件被禁用时，宿主给插件一个机会保存状态、释放资源。很多新手写插件不写清理逻辑，结果插件把自己的状态文件写到一半就断电，下次启动直接读取失败。所以别小看关闭回调，它是插件稳定性的重要一环。

插件升级则是通过插件市场分发新版本，宿主比对版本号后，把旧插件停掉、安装新版本、重新触发初始化。这一步做得好，用户几乎无感；做得不好，版本号比对出错会导致一堆插件都显示“可升级但装不上”。后面第 5 节里我会细讲这个坑。

3. 从脚手架到产品：插件到底带来了什么

3.1 模型接入插件：把“每家 API 不同”这件事抹平

DSH 刚装好的时候，你需要在配置里写清楚用哪个模型服务、模型名、API Key。要是换个模型商，接口风格可能天差地别——有的返回 OpenAI 兼容格式，有的流式输出是另一种协议，有的还支持工具调用而有的不支持。

模型适配器插件就是解决这个痛的。它把外部模型包装成 DSH 的统一模型接口，对上只暴露几个方法：chat、stream_chat、chat_with_tools。至于底层是走 HTTP 请求，还是调用本地推理进程，插件自己搞定。

这样一来，切换模型就是换个插件的事。我在本地开发时用本地跑的模型，断网也能用；想省事的时候切到提供免费额度的服务商模型，靠插件自带的配置项切过去。DSH 只认统一接口，根本不关心你背后接的是哪个家伙。

如果要在离线局域网里用 DSH，这一层的价值就更明显。团队在内部服务器上跑一个大模型服务，DSH 通过本地模型插件连上去，所有对话数据都不离开局域网。这时候 DSH 就从一个依赖外部的玩具，变成了一个随时可用的内部生产力工具。能离线、能局域网共享，靠的就是模型接入插件这一层的抽象。

3.2 提示词优化插件：把玄学变成可维护的流程

很多人以为提示词是纯玄学。写提示词的时候全凭感觉，模型回复不满意就再改，改来改去自己都忘了哪句起作用。但我用 DSH 的提示词优化插件之后，发现提示词可以当成一条有输入、有输出的数据管道。

提示词优化插件的常规做法是：拦截即将发给模型的消息，在管道里依次做几件事——压缩超长历史、提取关键上下文、注入系统角色、拼接少量示例、最后加上输出格式约束。每一步都是一个独立的小函数，可以被配置开关。

一个典型的模板长这样：

system_prompt: | 你是一个严谨的技术助手。请优先使用背景资料回答问题。 背景资料： {context} 用户问题： {question} 约束： 1. 如果背景资料没有答案，直接说“资料里没有相关信息”。 2. 回答控制在 500 字以内。

这个插件真正厉害的地方在于：它让提示词从“聊天框里的一段文字”变成了“一个版本可管理的配置文件”。团队里谁都能改提示词模板，改完提交、测试、回退，整个过程跟改代码一样规范。产品从脚手架向成熟工具蜕变，这是非常关键的一步。

3.3 场景化插件组合：抓取、知识库、归档、代码回退

DSH 产品化最直观的体现，是几个场景化插件装完之后，它突然就“会干活”了。

网页抓取插件是我第一个装的。它给 DSH 加了一条指令：用户发一个网址，插件就去抓页面正文，转成干净的 Markdown 喂给模型，再让模型基于内容回答。这解决了 AI 助手最大的短板——没有实时信息。

知识库插件（LLM Wiki 那种）则让 DSH 从“问什么答什么”变成“基于你的资料回答”。它的原理是检索增强：先把本地文档切成小段、向量化；用户提问时，插件根据问题去向量库里捞最相关的段落，拼在提示词后面。不用重新微调模型，就能让模型拥有你的私有知识。写综述时这个插件特别顶，资料散落在十几个 Markdown 和 PDF 里，插件一股脑全处理完，模型直接给整理版要点。

代码回退插件是我这种手滑党的救命稻草。开发时经常会有“刚才那个版本还能跑，我怎么又把它改挂了”的瞬间。这个插件会在每轮对话后把代码块快照存成一个带时间戳的版本，用户说“回退到上一个版本”，它就自动把上轮代码替换回来，整个回退过程还会在当前会话里留下记录。

Markdown 数学公式插件看起来细碎，实际用起来很舒服。我写技术笔记、整理综述时，公式只要能正常渲染成 LaTeX 效果，阅读体验完全不同。它在回复输出后做一次渲染，本质上也是一个“输出处理器”插件。

再加上归档管理插件——把超过一定时间的旧会话自动打包、压缩、存成可检索的归档库，DSH 终于变成了一个我自己愿意长期用的工具。“产品”和“Demo”的最大区别本就不是功能多少，而是能不能在日常流程里稳定地给人省时间，这堆插件装完，DSH 做到了。

4. 实操：装插件、写插件，一次过手

4.1 插件的两种安装方式

DSH 装插件基本是两条路：在线安装和手动放置。在线安装走的是插件市场：

dsh plugin install web-crawler dsh plugin install llm-wiki dsh plugin install markdown-math

装完之后用dsh plugin list查看启用状态。少数插件需要手动开启，再改一下配置，比如把知识库插件的文档路径指向你的本地目录。

但如果你的环境完全离线，在线安装就不适用了。这时候手动放置更靠谱：在另一台联网机器上下载插件的压缩包，解压后整个目录放到~/.dsh/plugins/下，再改 DSH 配置文件里的插件开关。DSH 启动时扫描到目录就会加载，不需要额外注册表，这一点对离线环境非常友好。

手动放置最怕放错位置或者少了 manifest.json。我遇到过一次从网上下载的插件包没有 manifest，目录名还带版本号，DSH 直接判定为无效插件，在日志里静默跳过。所以下载插件包先看一眼里面有没有清单文件，比装完再排查要快得多。

4.2 手写一个会话摘要插件：完整流程

光会装插件不算本事，自己写一个才是真正理解插件机制的捷径。我拿一个最常见的“会话摘要”插件当例子，跑一遍完整流程。

需求很简单：每次对话结束，把当前会话的核心内容生成一段摘要，存到一个 Markdown 文件里。

先建目录和清单文件：

mkdir -p ~/.dsh/plugins/session-summarizer cd ~/.dsh/plugins/session-summarizer touch manifest.json main.py requirements.txt

manifest.json 这么写：

{ "name": "session-summarizer", "version": "0.1.0", "min_api_version": "1.0", "entry": "main.py", "hooks": ["session_end"], "permissions": ["history:read", "file:write"] }

这里hooks声明了插件关心的时机——session_end，也就是会话结束；permissions声明了插件需要读历史、写文件的权限。DSH 的权限模型属于白名单制，不声明就拿不到能力，防止插件乱来。

入口 main.py 长这样：

from dsh import api def setup(host, bus): # 把函数绑定到会话结束事件 bus.on("session_end", summarize_session) def summarize_session(ctx): history = ctx.get_history() if not history: return text = "\n".join(history) summary = api.summarize(text, max_tokens=200) api.write_file("summary.md", summary)

写完把插件目录放回~/.dsh/plugins/，然后在 DSH 里执行：

dsh plugin enable session-summarizer

重启 DSH 之后，正常聊几轮然后结束会话，看有没有生成 summary.md。这里我踩过一个坑：第一次写完忘记在 manifest 里声明history:read权限，插件运行时调 get_history 被挡了，日志里只留下一行权限拒绝。所以写插件第一件事就是确认权限声明齐全，尤其是涉及读会话、写文件、访问网络的插件。

4.3 插件的配置、日志与发布

插件写好了，下一步是加配置项。比如摘要长度不该写死在代码里，应该开放给用户。DSH 插件约定：配置写在插件目录的 config.yaml 或通过宿主配置中心下发。我上面那个插件，加一个max_tokens配置项，代码改成：

summary = api.summarize(text, max_tokens=api.get_config("max_tokens", 200))

用户在 DSH 配置界面里把session-summarizer.max_tokens改成 300，插件下次运行就生效，不用重启。这就是“插件与宿主解耦”的体现：用户不需要懂代码，也能按需调整插件的表现。

调试插件最好的工具是 DSH 的调试日志。启动时带上--debug参数，宿主会把插件加载过程、事件触发顺序、权限检查结果全部打出来。我的习惯是每个插件的入口函数第一行就加一句日志输出，确认它真的被加载进来了，再往下查逻辑。日志能帮你把问题定位范围缩小一大半。

插件测试稳定后，如果想让更多人用，可以打包成标准压缩包并收录到插件市场仓库。发布前检查三件事：manifest 里版本号是否合规、requirements.txt 是否闭环、README 是否写清楚配置项。很多插件明明好用但没人用，不是功能不行，是发布时缺文档、缺版本信息，用户装都不敢装。

5. 避坑实录：我在 DSH 插件上踩过的坑

5.1 插件不生效，99% 出在这四个环节

遇到“插件装了但没反应”，别急着怀疑 DSH，按顺序排查：先看插件目录是否被扫描到；再看 manifest 校验有没有通过；然后确认事件名跟宿主文档里的事件名一致；最后看权限声明齐不齐。这四个环节我几乎都踩过一遍。

我印象最深的一次是插件目录放对位置了，manifest 格式也合法，但就是不触发。最后开 debug 日志才发现，我在 manifest 里把session_end写成了session_end_trigger，事件名差一个后缀，宿主当然不知道你在等什么。所以检查清单里最重要的一条：事件名必须和宿主文档逐字对齐，不能凭感觉写。

静默失败是 DSH 插件最常见的现象，一个插件加载失败，宿主通常不会打断主流程，只在日志里写一行警告。所以养成看日志的习惯，比反复重启有用得多。

5.2 依赖冲突和 Python 环境问题

插件多了之后，一个绕不过去的坑是 Python 依赖冲突。插件 A 需要某个库的旧版，插件 B 需要新版，共用一个环境迟早要出事。DSH 对这个问题的主流解法是给插件建立隔离环境，安装插件时根据 requirements.txt 生成一个独立的 venv。

如果使用全局环境，或者插件没有正确声明依赖，运行时就会报ModuleNotFoundError。这种报错比较好判断，难的是那种“装上了但不稳定”——某个插件把公共目录里的库版本改了，连带影响其他插件。碰上这种问题，优先把 DSH 和插件升到支持环境隔离的版本，再给每个插件标明依赖范围。如果已经局部坏了，最简单的办法是把插件目录整体删了重装，别想着手动修依赖，Python 依赖的泥潭越陷越深。

5.3 离线局域网部署的注意事项

热搜里常有人问 DSH 能不能在离线局域网里用，答案是可以，而且这本来就是 DSH 的典型玩法。离线场景需要注意三点。

第一，模型层要换成本地推理服务，DSH 侧通过本地模型插件对接，不再依赖外部网络。第二，插件市场在离线环境里用不了，但这不代表不能装插件，手动放目录、改配置的安装方式完全可行；最好提前把需要的插件包离线下载整理好，形成自己的本地插件库。第三，如果要用知识库插件，本地的向量数据库和嵌入模型也得准备一套离线版本，否则文档检索功能会失效。把这些准备好之后，DSH 就能在完全断网的局域网里给整个团队提供稳定的 AI 能力，数据也不用离开自己的服务器。

这个过程没有任何特殊操作，也不需要什么暗箱技巧，纯粹是架构选型带来的红利。模型接插件、插件离线放置、数据本地保存，每一步都是公开能力，只是很多人没想过把它们组合起来用。

5.4 插件拖慢回复速度的经典场景

插件越多越卡，这是最容易被忽略的性能问题。具体表现是：模型回复之后，界面还要等一两秒才出结果。原因多半是某个插件的after_response回调做了重活——比如摘要插件把整段历史重新送给模型总结一遍，这在回调里同步执行，用户就在那干等。

我自己调优的经验是：回调里尽量不要同步调用模型。你完全可以在模型回复后，把摘要任务扔到后台线程池去跑，等摘要完了再通过异步事件把结果写进 UI。这样用户先看到回复，摘要后台悄悄生成，体验完全不一样。

再一个细节是给插件回调加上超时控制。DSH 的插件机制一般默认每个回调有执行时间上限，超时会被宿主中断。但如果在自己的代码里用了没有超时的 HTTP 请求，卡住的怨气就得算到整个 DSH 头上。给请求加一个 5 秒超时，是我写所有网络类插件的底线。

最后一招是善用插件开关。很多插件只在特定场景有用，平时开着纯属浪费。用dsh plugin disable把不常用的插件关掉，只保留当前场景需要的，速度提升比调代码还立竿见影。

这类脚手架的后续扩展空间

DSH 这套设计真正让人上头的不是功能数量，而是边界感：宿主管好核心循环，插件管好专属能力。后续往哪个方向扩展，其实都顺理成章——加移动端，等于给同一套宿主套一个新壳；加多用户协作，等于在宿主层做权限和会话管理；加可视化编排，等于把插件调用关系画出来。我在实际使用中体会最深的一点是：好产品从来不是一次把所有功能做齐，而是先把插槽设计对，让能力源源不断自己长出来。脚手架不丢人，能稳定跑起来、还能持续长出新功能的脚手架，本身就是产品的最初形态。