企业官网建设流程全解析

装完 dsh-data-agent 之后，很多人的疑问是「它到底是怎么把『数据模式』塞进我的会话里的」。答案全在预设（preset）这一层：插件不是往界面里硬加一个按钮，而是往 DSH 的预设注册表里注册一个名为data-agent的模式，再由宿主决定这个模式在哪种会话、带哪些工具生效。把这层机制弄清楚，TUI 和 Web 两种入口的差别、升级后报错的原因、installPreset: false的后果就都能自己推导出来。

从 standingKeyFor() 到 dsh-agent-preset-registry

旧版本里，数据模式是靠standingKeyFor()这个调用接入的。当前版本已经不再调用它——它被移除了。取而代之的是新版dsh-agent-preset-registry：插件通过这个注册表把 data-agent 预设注册进去。这是一个值得注意的迁移信号：预设的接入方式是跟着 DSH 主干走的，如果你从很旧的版本一路升上来，遇到的第一类问题往往就出在这层。

预设是从哪个目录读出来的

预设不是编译进插件包里的固定字符串，而是从磁盘上的目录读出来的：

对 data-agent 来说，<presetId>就是data-agent，默认$DSH_HOME位于~/.dsh。目录里有两个文件是机制的关键：agent.cordis.yml描述这个预设由哪些插件组成，preset.yml存的是预设元数据。插件在启动时会读这两个文件（静态扫描里能看到对应的读取点），把它们变成可用的预设。所以「预设」对 DSH 来说是一份可读、可改、可覆盖的配置，不是一个封闭的黑盒——这也解释了下面所有和自定义有关的行为。

宿主注册表负责什么

预设注册进去之后，真正决定它「在哪、怎么用」的是宿主注册表。README 列了三件事：工具作用域、空会话切换和卸载。

• 工具作用域：数据模式会带上它需要的那批工具（查询、报表生成等），宿主负责把作用范围界定清楚，不让它越界到别的场景。

• 空会话切换：在一个还没指定模式的空会话里，切到 data-agent 是由注册表完成的。

• 卸载：卸载插件时，注册表负责把预设一并摘掉，不会在$DSH_HOME里留一个孤儿预设。

README 同时明确了一句：现有自定义预设与名称保持不变。也就是说升级插件不会把你已经建好的预设名和内容动掉。

installPreset: false 会关掉什么

如果你的配置里把installPreset设成了false，插件会禁用自身的预设安装及注册。后果很直接：插件装是装上了，但不会有 data-agent 预设被注册进来，你也就找不到「数据模式」这个入口。README 给的出路是——此时需要由其他宿主插件来声明预设。

这个开关的意义在于「谁说了算」。团队做统一预设分发的时候，往往不希望某个子插件自作主张往注册表里塞预设，而是由一个统一的宿主插件集中声明，installPreset: false就是给这种情况准备的开关。

升级后第一次启动：prefix 会被自动补上

新版 DSH 要求预设里的persona.config.prefix是必填的。为了让老预设能继续跑，插件在升级后的首次启动会自动更新已识别的原版 data-agent 预设，让它兼容这个必填字段，同时保留已有的text字段。README 特意强调：自定义过的预设不会被覆盖。

这最后一句是一把双刃剑：你的自定义被保护了，但也意味着如果你自己改过这个预设、恰好又缺prefix，自动修补不会碰它，启动就会报$.prefix missing required value。解法是手工的：备份$DSH_HOME/.agent-presets/data-agent/agent.cordis.yml（默认在~/.dsh），在persona的config里让prefix与原来的text使用相同提示词，然后重启。

两种入口的差别：Web「数据模式」和 TUI 斜杠命令

同一套预设、同一套工具，在两个 profile 下的打开方式不一样。

Web 界面（dsh --profile web）是图形化路径：新建会话时选择「数据模式」，选中之后连接入口出现在两处——新会话页「数据模式」旁的「连接配置」，或进入会话后输入框右上角的数据库图标。填完连接信息，工作台里可以直接点「测试连接」验证连通性，连通之后直接在对话框里提问。

终端（dsh --profile dsh-tui）是命令路径，分两步：

/preset data-agent负责切到数据模式，/database connect负责建连接，两步都做完才能提问。区别在于 Web 把「选模式」和「配连接」做成了可视化的点击与状态提示（连接配置、库表浏览、数据治理、SQL 执行都在工作台里），TUI 则把它们拆成两条命令，适合键盘流。

两种方式的产物是一致的：分析需要可视化时会生成单图或多维 Dashboard，并自动把独立的离线 HTML 报告写到工作目录的analysis-reports/下。

安装与版本边界

两条安装命令分别对应两个 profile：

版本边界必须记牢：插件 0.2.2 的 peerDependencies 全部要求>=0.2.0-rc.1（其中@deepseek-ai/cordis钉在精确版本4.0.4），README 声明的也是>=0.2.0-rc.1，目前已完成运行验证的是0.2.0-rc.2。README 里还有一句给旧版用户的话：旧版 DSH 请继续使用相应旧版插件。

各插件对不同 DSH 版本的要求、预设形态与安装方式，都汇总在 完整插件清单与汉化避坑指南 里，动手前可以先对照一遍。如果你还想横向比较同类数据分析插件，同一份 完整插件清单与汉化避坑指南 也把它们的安装形态与中文说明放在了一起。

总结

data-agent 的接入全靠预设这一层：注册走dsh-agent-preset-registry，读取走$DSH_HOME/.agent-presets/<presetId>/，生效范围由宿主注册表管；想对照同类插件的中文清单与安装形态见 完整插件清单与汉化避坑指南。

适合与不适合

适合：需要理解 DSH 预设机制、准备自己做预设分发的开发者；从旧版 DSH 升级上来、要排查预设报错的人；偏向键盘流、想用/preset加/database connect的终端用户；团队里需要统一预设、考虑installPreset: false的维护者。不适合：DSH 还停在 0.1.x、暂时不打算升级的用户；只想点开就看图、完全不关心配置层次的纯业务使用者；不准备维护任何本地配置、希望装完零心智的人。

标签：dsh-data-agent、DeepSeek Harness、预设注册机制、dsh-agent-preset-registry、TUI 与 Web 入口

本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。