企业官网建设流程全解析

• dsh-plugin
• 人工智能
• 大模型
• AI 技能/插件
• 提示工程
• AI Agent

本指南面向第一次接触 dsh-super-injector 的用户与 Agent，完整讲解三种装配路径（Release 包 / git 装配 / 手动 patch）的逐步操作、安装后的双命令验证、duplicate loader entry id启动崩溃的根因与修复，以及卸载回滚与常见问题排查。读完你可以独立完成"装上注入器 → 验证健康 → 排障 → 卸载"的全流程，并理解每一步背后的源码依据（仓库根目录 injector/ 下的实现与脚本可交叉验证）。

1. 30 秒理解：dsh-super-injector 是什么

dsh-super-injector 是 DSH 生态的插件注入器（仓库内位于 injector/）：装好它之后，任意本地插件包都能免重启注入运行中的 DSH 进程——只需对 agent 说一句dev_inject_plugin即可生效，并自带热重载、自重载、卸载即净、一键自检等能力。

它的关键设计是：它本身也是一个标准 DSH 插件（包名@dsh-external/dsh-super-injector，见 injector/package.json）。因此"安装注入器"本质上就是走一遍 DSH 官方装配路径；装配成功后，后续所有插件都走运行时注入通道，不再需要触碰官方配置。

从源码结构看，注入器的能力清单写在 injector/src/index.ts：dev_inject_plugin（运行时注入）、dev_install_package（双路径热装配）、dev_reload_package（确定性整包热重载）、dev_plugin_status（装配清单）、dev_injected_list（注入清单）、自动轮询 watch 与静态能力提示注入。README（injector/README.md）将其定位为 DSH 生态的 "BepInEx 式模组注入入口"：官方装配机制（profile bundle / repository-plugin）是唯一的"官方入口"，就像游戏只有启动器能装模组；本插件打破这一点——引导器走官方入口装一次，之后万物皆可运行时注入。

三种方式任选其一，推荐方式 A（Release 包，免构建）。装完用第 7 节验证，装不上看第 8 节排查，想卸载看第 9 节。

⚠️Windows 用户注意：下文命令为 bash 语法（~/、mkdir -p、tar、ln -s）。请使用Git Bash（Git for Windows 自带）或 WSL 执行；PowerShell 需要等价改写（~→$HOME、mkdir -p→New-Item -ItemType Directory -Force、tar直接可用）。

2. 安装前的版本与产物常识

在动手前，先明确几个与当前仓库一致的版本事实（依据 injector/package.json）：

• 当前仓库源码版本为0.3.3（"version": "0.3.3"），已发布并打了 git tag（见 injector/CHANGELOG.md）。
• 发布产物的命名规则为dsh-external-dsh-super-injector-<版本>.tgz——dsh-external-前缀 + 包名 + 版本号，与仓库内其他发布产物（如 preset 目录的dsh-router-standard-0.3.0.tgz）命名风格一致。
• 包内files字段声明了发布时包含的内容：lib、cordis.patch.yml、scripts/build.sh、scripts/fix-patch.mjs、scripts/prepare.mjs（injector/package.json）。这决定了"解压后目录里应有 lib/、cordis.patch.yml、package.json、README.md、INSTALL.md"。
• peerDependencies全部为范围声明：@deepseek-ai/dsh-tools: >=0.0.1-rc <2、@deepseek-ai/cordis: >=4.0.0-rc <5、@deepseek-ai/schemastery: ^3.18.2（injector/package.json）。这意味着 DSH 升级时无需改动注入器——不硬编码 DSH 版本，是该项目刻意保持的兼容策略（README 明确说明 DSH 0.1.0-rc.6 一行不改直接运行）。

3. 方式 A：Release 包安装（推荐，免构建）

第 1 步：下载

从 Releases 页面下载最新版 tgz 包：

dsh-external-dsh-super-injector-<版本>.tgz

例如当前仓库版本 0.3.3，文件名为dsh-external-dsh-super-injector-0.3.3.tgz。下面命令里的<版本>一律替换成你实际下载的版本号。

第 2 步：解压

# 解压到任意目录（示例；<版本> 换成实际版本号） mkdir -p ~/dsh-super-injector && tar -xzf dsh-external-dsh-super-injector-<版本>.tgz -C ~/dsh-super-injector --strip-components=1

解压后目录里应有：lib/、cordis.patch.yml、package.json、README.md、INSTALL.md。

这里有一个版本演进细节值得说明：早期发布包（v0.2.4 之前）的files只含lib，不带构建脚本，导致解压副本缺依赖链接、dsh plugin add后报ERR_MODULE_NOT_FOUND装不上；v0.2.4 起把scripts/build.sh纳入发布包（见 injector/CHANGELOG.md），v0.3.3 又通过 tsdown host bundle 把运行时依赖打进lib/index.js，根治了Cannot find package '@deepseek-ai/dsh-tools'问题（injector/CHANGELOG.md）。所以请尽量使用新版本 Release 包。

第 3 步：装配

dsh plugin --profile web add ~/dsh-super-injector

这条命令把解压目录作为 bundle 写入 web profile。注意--profile web必须与你实际启动的 DSH profile 一致——这是后续"装了但 dev_* 工具不存在"最常见的根因（详见第 8 节排查表）。

第 4 步：重启生效

重启 DSH web 进程（bundle 装配在启动时完成）。重启后向 agent 说一句：dev_plugin_status——看到dsh-super-injector且状态 active 即成功。

不想重启？如果你已有另一台机器/环境装过注入器，可以用它的dev_inject_plugin直接注入本目录（免重启）。这是运行时注入路径的典型场景：注入器作为"引导器"常驻一处，其他插件包随取随用。

4. 方式 B：git 装配

dsh plugin --profile web add github:yjh051108/dsh-super-injector

重启 web 后同上验证。（git 安装只取源码，构建由已提交的prepare脚本自动完成——npm/pnpm抓取后即运行，产出自包含的lib/，无需 DSH checkout。）

这里的 "prepare 脚本自动构建" 在仓库里有完整实现：injector/scripts/prepare.mjs。其策略要点：

• npm/pnpm安装 git 依赖时会在包内自动运行prepare（package.json的"prepare": "node scripts/prepare.mjs"，见 injector/package.json）；
• 若lib/index.js与lib/client.js已存在则直接跳过构建（幂等）；
• 优先使用本地 devDependency 的 tsdown（node_modules/.bin/tsdown），否则回退npx --yes tsdown@^0.22.14（首次需要网络）；
• 构建失败会响亮地失败：报错并提示两条替代路径——(a) 改用 Release tgz（预构建产物），(b) 设置DSH_CHECKOUT后运行bash scripts/build.sh再重装。

自己从源码构建（例如改过src/之后）

# 1. 安装依赖。peerDependencies 由 DSH 宿主提供，npm 却会自动装 peer 并撞上 # 未发布的 @deepseek-ai/dsh-type-meta（E404）——用 --legacy-peer-deps 跳过。 npm install --legacy-peer-deps --no-audit --no-fund # 2. 类型检查 + 声明产出。cordis/schemastery 必须解析到 @deepseek-ai 的分叉版 # （4.0.1 / 3.18.1）：公共 registry 的 cordis d.ts 在 NodeNext 下是坏的， # 而打包后的 app bundle 又把分叉版 d.ts 剥掉了。把分叉包复制进 # node_modules/@deepseek-ai/ 并链接（之后任何 npm install 都会再次剪掉，需重链）。 ./node_modules/.bin/tsc -p tsconfig.json # 3. 打包 host + client（lib/ 已存在时 prepare.mjs 会跳过——先 rm -rf lib 强制重建） ./node_modules/.bin/tsdown --config tsdown.config.ts

说明：第 3 步的rm -rf lib是原文档为"强制重建"给出的命令语义；若出于环境限制不方便删除，也可以先手动清理lib/目录再执行 tsdown。步骤 2 的tsc -p tsconfig.json对应仓库内的 injector/tsconfig.json，步骤 3 对应 injector/tsdown.config.ts。

5. 方式 C：手动 patch（最底层，什么都依赖没有时）

编辑~/.dsh/profiles/web/cordis.patch.yml，把内容替换为：

# Your patch layer for this dsh profile, applied after every bundle layer: # a top-level YAML array of loader patch entries (id-targeted config # overrides, disables, and insert lists; !!js expressions allowed). - id: dsh-super-injector name: '@yjh051108/dsh-super-injector' config: {}

并且保证包能被 loader 解析：把插件目录链接到 profile 的 node_modules。

先确保父目录存在（全新 profile 上@dsh-external可能不存在，否则链接会报"系统找不到指定的路径"）：

mkdir -p ~/.dsh/profiles/web/node_modules/@dsh-external

再建立链接：

# Windows（junction，无需管理员；用 Git Bash 执行） ln -s /你的路径/dsh-super-injector ~/.dsh/profiles/web/node_modules/@yjh051108/dsh-super-injector # 或 cmd（Windows 原生） mklink /J "%USERPROFILE%\.dsh\profiles\web\node_modules\@dsh-external\dsh-super-injector" "D:\你的路径\dsh-super-injector" # Linux/macOS（软链） ln -s /你的路径/dsh-super-injector ~/.dsh/profiles/web/node_modules/@yjh051108/dsh-super-injector

注意cordis.patch.yml必须是单一顶层值（要么[]，要么- id:列表，不能两者混存——否则 YAML 解析报错）。

注意同 id 条目只允许一条（dsh loader 装配遇同 id 直接报duplicate loader entry id，启动即崩）。方式 C 是给"什么都不依赖"的场景兜底的，重复执行 / 重复粘贴会制造重复 id。如果之前已经装过注入器（方式 A/B），不要再手动 patch 一次——先跑dev_fix_patch检查去重。

与 bundle 层 patch 格式的对照：注意注入器自带的 bundle 层 patch（injector/cordis.patch.yml）使用的是- insert:包裹格式（- insert:下一级才是- id:/name:/config:），而方式 C 手动写的是顶层- id:列表。两种都属于"顶层 patch 条目数组"的合法形态，区别在于：bundle 层的- insert:由 DSH 装配机制自动应用（走方式 A/B 后无需手动加任何 patch），方式 C 则完全手写。README 中的"引导装配"示例用的也是- insert:形态（injector/README.md），并特别警告：走方式 A/B 装配后请勿再加这一条，否则与 bundle 层自注册的dsh-super-injector撞同一个 loader entry id，报duplicate loader entry id。这与原文档"方式 C 是给什么都不依赖的场景兜底"的定位完全一致。

从源码看，注入器自己的writePatch写入逻辑（injector/src/index.ts）专门处理了这两个坑：写入前扫描现有条目 id 做幂等（id 已存在则不追加），重写文件时按 id 去重（保留最后一条），并移除顶层[]再追加条目以保证单一顶层值。这也是第 6 节"预防"部分"注入器 ≥0.3.3 的 writePatch 按 id 幂等去重"的源码出处。

6. 故障修复：启动崩溃duplicate loader entry id

症状

dsh 启动即退出，报错含：

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include): duplicate loader entry id: <id>

原因：~/.dsh/profiles/<profile>/cordis.patch.yml里同 id 条目出现两次（手动 patch 重复执行、重复粘贴、或注入器旧版本盲追加写入）。dsh loader 要求 id 唯一。

修复（dsh 起不来时）

发布包自带独立修复脚本（零依赖，node 直接跑，不需要 dsh 启动）：

# 解压目录里（含 scripts/fix-patch.mjs）： node scripts/fix-patch.mjs # 修复全部 profile（自动备份原文件） node scripts/fix-patch.mjs --check # 只检查不写（退出码 0=健康 1=有重复） node scripts/fix-patch.mjs --profile web # 只修 web profile

修复后重新启动 dsh 即可。

这段脚本的实现在 injector/scripts/fix-patch.mjs，其内部逻辑值得展开（方便你理解它在做什么、边界是什么）：

• 扫描范围：默认遍历~/.dsh/profiles下所有 profile 的cordis.patch.yml（跳过以.开头的目录）；--profile只处理指定 profile。
• 去重规则：按 entry id 去重，同 id 保留最后一条（后写的覆盖先写的）；注释块保留；顶层[]会被清理。
• 备份：修复前先把原文件改名为cordis.patch.yml.bak-<时间戳>，再重写新文件，保证可回滚。
• --check模式：只读不写，退出码0= 健康、1= 存在重复（可用于脚本化巡检），找不到 profiles 目录时退出码2。
• 零依赖：只用了 node 内置的fs/path/os，注释明确写着"此时注入器自身无法启动，只有本脚本能救——它不依赖 dsh，也不依赖任何 npm 包"（injector/scripts/fix-patch.mjs）。

修复（dsh 能启动时）

直接让注入器修（等价操作，含备份）：

dev_fix_patch # 修复全部 profile dev_fix_patch --check # 只检查

预防

• 注入器 ≥0.3.3 的writePatch按 id 幂等去重——它自己写 patch（卸载 disabled、self-test 等）不会再制造重复；已有重复也会在写入时顺带清理（对应源码 injector/src/index.ts 的注释："手动 patch / 重复安装 / 多路径写入都可能让同 id entry 出现两次……写入前扫描现有条目 id，若已存在则不追加"）。
• 手动 patch 前先确认没有装过注入器；装过就用dev_fix_patch --check验证。

重启 web 后验证。

7. 验证是否装好

装好后对 agent 说（或自己跑）：

dev_plugin_status → 看到 dsh-super-injector active，且操作统计面板正常 dev_self_test → 一键回归 8 项，期望全部 PASS（含注入/热重载/自重载节流/预检拦截/卸载）

dev_self_test全部 PASS = 注入器及其环境完全健康。

从源码与 CHANGELOG 可以确认这 8 项回归的具体内容（injector/CHANGELOG.md 记录了 v0.3.3 自检 8/8 PASS 的项目）：测试插件构建 / 注入 host ✓ / 热重载 uid 变化 / 自重载节流 / 预检拦截 / lib 恢复 / 卸载即净 / patch 写入合法性。自检中的两个"预期拒绝"场景（自重载节流、预检拦截）会显示为[EXPECTED]前缀，计入 PASS 而不是故障——这是为了让新手不被"预期行为"误导（见 injector/CHANGELOG.md）。

dev_plugin_status除了能看到dsh-super-injectoractive 之外，还会对运行时注入的插件标注[injected]标记（与 bundle 装配区分），并展示操作成功率统计与最近失败（lastFailures，最近 5 条失败的类型/时间戳/原因），方便追溯历史问题（injector/CHANGELOG.md）。

8. 常见问题排查

结合源码与 CHANGELOG，上面两条与 Windows 构建相关的排查项还有更深的背景，可作为排障时的参考：

• dev_build_plugin报 bash 找不到：v0.3.3 修复过一个真实 bug——Windows 装了 WSL 时，System32\bash.exe会抢先命中 PATH，导致构建直接失败（报"适用于 Linux 的 Windows 子系统没有已安装的分发版"）；修复策略是 Git/PortableGit 路径优先、PATH 探测结果含 wsl 标记即拒绝（injector/CHANGELOG.md）。所以排障时优先确认 PATH 里的是 Git Bash 的 bash 而非 WSL 的 bash。
• 路径错位类问题：部署的 web 进程homedir()可能与DSH_HOME环境变量指向不同（服务账户/跨用户部署场景），导致 registry / profileNodeModules / 日志路径全部错位、junction 建到错误 profile。源码统一采用process.env.DSH_HOME || join(homedir(), '.dsh')作为权威路径（injector/src/index.ts）。若你发现注入器写文件的位置"不对"，先检查DSH_HOME是否被显式设置。

9. 卸载 / 回滚

# 1. 从 profile bundles 移除（官方路径） dsh plugin --profile web remove @yjh051108/dsh-super-injector # 2. 清理 profile patch 里的 disabled/配置条目（若存在） # 编辑 ~/.dsh/profiles/web/cordis.patch.yml，删除含 dsh-super-injector 的条目， # 保持文件为单一顶层值（[] 或列表） # 3. 删除 node_modules 链接（若存在） rm -rf ~/.dsh/profiles/web/node_modules/@yjh051108/dsh-super-injector # 4. 清理运行时注入清单（若走的是运行时注入） # 重启后由 agent 执行 dev_uninject_plugin，或直接删除 ~/.dsh/super-injector/registry.json

重启 web 后dev_*工具消失即卸载完成。若只是临时禁用：在 patch 里给dsh-super-injector加disabled: true即可（保留数据，随时恢复）。

关于第 3 步的链接删除，有一个实现细节：注入器在注入/安装插件时通过 junction（Windows）或软链（Linux/macOS）把插件包链接到~/.dsh/profiles/web/node_modules；对悬空 junction（源目录已被删除/改名）会先用lstatSync判断链接存在再删除重建（injector/CHANGELOG.md）。手动清理时同理：直接删除链接本身即可，不需要理会链接指向的目标是否还存在。

另外，~/.dsh/super-injector/registry.json是运行时注入清单（源码中readRegistry/writeRegistry使用"先写 tmp 再 rename"的原子写策略，避免中途崩溃留下半截 JSON 毒化下次自动恢复，见 injector/src/index.ts）。直接删除该文件即可放弃全部运行时注入的恢复记录。

10. 给 agent 的一句话（环境说明模板）

本环境装有 dsh-super-injector（dev_* 工具）：任意本地插件包可运行时注入——工具包/守护循环（timer+LLM 自主 agent loop）/UI 面板/混合形态，同一通道；注入即完整生效（host+UI）、可热重载与自重载、卸载即净。插件自身的提示词/工具/循环皆可自我优化；建新插件优先克隆/借鉴/重构生态已有资源，不重复造轮子。若注入器无法支撑此闭环，优先修复注入器。从零体验路径：dev_plugin_status → dev_self_test → dev_scaffold_plugin → dev_build_plugin → dev_inject_plugin → dev_uninject_plugin。

这段"从零体验路径"对应的正是注入器提供的 dev_* 工具全家桶。除了上面出现的命令，完整工具清单（见 injector/README.md 与源码注册处 injector/src/index.ts）还包括：

这些工具的底层机制（injector/README.md）可以作为你理解安装后行为的心智模型：① junction 链接插件包到~/.dsh/profiles/web/node_modules（loader 标准解析路径）；②ctx.loader.create({ name, config })运行时装配（完整 ctx）；③ 清单持久化（~/.dsh/super-injector/registry.json），重启后自动恢复注入；④ client 联动——注入/重载后清除 entry disabled 标记并补扫 client 模块表。

11. 安装之后：你能得到什么

装好注入器（方式 A/B/C 任选其一并验证通过）之后，DSH 就拥有了"万物可注入、注入可回滚、改完即生效"的 Mod 级体验。一个典型的开发闭环是（injector/README.md）：

• 装模组：拿到插件包（package.json + lib/ 产物）→ 对 agent 说dev_inject_plugin（参数 = 插件包绝对路径）→ 当场生效（下一 step 工具可见）。
• 开发迭代：改代码 → build → 自动 watch 约 1.5 秒自动重载（或dev_reload_package）→ 验证 → 稳定后dev_stage_promote一键转正。
• 卸载：dev_uninject_plugin（参数 = 包名子串）→ 工具/监听/路由/client 表全清，免重启。

如果你要在此基础上继续开发自己的插件，injector/docs/SPEC.md 是注入器的设计契约文档（基于 DSH 0.1.0-rc.6 源码语义推导），injector/README.md 的"插件开发指南"一节给出了四种插件形态（toolkit / daemon-loop / ui-panel / hybrid）的一分钟起步路径与十条规范铁律——这些内容与安装手册互补，适合装好之后继续深入。

• dsh-plugin
• 人工智能
• 大模型
• AI 技能/插件
• 提示工程
• AI Agent