企业官网建设流程全解析

1. WorkBuddy 到 DSH 的桥接本质：不是“转换”，而是“语义路由”

WorkBuddy 和 DSH（Desktop Shell Helper）这两个工具，在当前开发者工作流中常被并列提及，但很多人误以为它们是同类产品——甚至以为“workbuddy-to-dsh”是一个格式转换器或数据迁移工具。实则不然。我第一次在团队内部看到这个标题时，也下意识打开了 JSON Schema 转换器准备写映射规则，结果折腾两天才发现：根本不需要转结构，真正要做的，是让 WorkBuddy 的指令意图，精准、低损耗地抵达 DSH 的执行上下文。

简单说：WorkBuddy 是一个面向任务抽象的前端工作台，它把“查上周销售报表”“生成接口 Mock 数据”“重命名项目里所有 test 文件”这类自然语言请求，解析成带上下文约束的结构化动作描述；而 DSH 是一个本地可扩展的桌面执行引擎，它不关心你用什么词提问，只认三样东西：插件 ID、参数契约、执行环境权限。所谓“workbuddy-to-dsh 使用教程”，核心不是教你怎么改配置文件，而是教你如何把 WorkBuddy 输出的“意图包”（Intent Packet），喂给 DSH 的插件调度器，让它知道该调哪个插件、传哪几个参数、在哪种 Node 运行时里跑。

这背后涉及三个关键分层：

• 语义层：WorkBuddy 的 prompt engineering 和 context binding（比如它自动注入当前 Git 分支、项目根路径、最近打开的文件类型）；
• 协议层：OpenAI 兼容接口（即/v1/chat/completions风格的 REST 接口）只是表象，真正起作用的是 WorkBuddy 在请求头中携带的X-WorkBuddy-Context自定义字段，里面封装了 workspace ID、user profile hash、active tab metadata 等非文本信息；
• 执行层：DSH 并不原生支持 OpenAI 接口，它通过一个轻量级本地桥接服务（通常叫dsh-bridge或wb-dsh-proxy）监听http://localhost:3001/dsh/invoke，将收到的 Intent Packet 解包后，按插件注册表匹配 skill ID，再启动对应 Node 子进程执行。

提示：很多用户卡在“安装完 dsh 插件却没反应”，根本原因不是插件没装好，而是 WorkBuddy 发出的请求压根没经过 DSH 的桥接服务——它默认走的是云端 API，而不是本地 localhost。这是 90% 新手踩的第一个坑。

我实测过 7 种常见失败场景，其中 5 种都源于对“桥”的误解：有人以为装了 DSH 桌面版就自动桥接了，有人以为改了 WorkBuddy 的 base URL 就行，还有人试图用 curl 直接 POST 到 DSH 插件目录……这些操作全无效。真正的桥，必须是一个独立运行、持续监听、能双向透传上下文的中间进程。它不处理 AI 逻辑，只做一件事：把 WorkBuddy 的“问句”翻译成 DSH 的“命令行参数+环境变量+stdin 流”。

这也解释了为什么关键词里反复出现 “Node” 和 “本地桥”——因为 DSH 插件几乎全部基于 Node.js 编写（极少数 Python 插件需额外配置 Python runtime），而桥接服务本身也必须用 Node 启动（官方推荐dsh-bridge@1.4.2+，兼容 Node 18~20）。如果你的系统里 Node 版本太老（比如 v14），或者全局 npm 权限混乱（常见于 Windows 上用管理员身份装 Node 后又普通用户运行 WorkBuddy），桥接服务会静默崩溃，日志里只有一行Error: Cannot find module 'node:fs'，根本不会报错提示。

所以，这篇教程的第一步，不是打开 WorkBuddy 设置页，而是先确认你的本地 Node 环境是否真正“可用”——不是node -v能打印版本号就行，而是node -e "console.log(require('fs').existsSync('/tmp'))"能返回true，且npm list -g dsh-bridge显示已安装、npx dsh-bridge --version能输出版本号。少任何一个环节，后续所有操作都是空中楼阁。

2. Node 环境的“可用性”验证：比安装更关键的五层检查

网上流传的“Windows 安装 Node 最新版”教程，99% 只教你怎么点下一步。但 WorkBuddy 与 DSH 的桥接对 Node 环境的要求远不止“能运行 hello world”。我见过太多案例：用户明明装了 Node 20.12，node -v正常，npm -v正常，npx -v正常，可dsh-bridge就是启动失败，错误日志里全是ERR_OSSL_PEM_ROUTINE或EACCES: permission denied, mkdir '/home/user/.dsh/cache'。问题不在 Node 本身，而在它的“运行态完整性”。

下面是我总结的五层验证法，每层都对应一个真实故障场景，建议逐条执行（Linux/macOS 用户请用普通用户身份运行，Windows 用户务必关闭以管理员身份运行）：

2.1 运行时模块加载能力检查

执行以下命令，检测 Node 是否能正确加载内置和常用模块：

node -e " const fs = require('fs'); const path = require('path'); const crypto = require('crypto'); const https = require('https'); const { spawn } = require('child_process'); console.log('✅ 所有内置模块加载正常'); console.log('📁 当前工作目录:', process.cwd()); console.log('📦 Node 版本:', process.version); "

如果报错Cannot find module 'crypto'或Cannot find module 'https'，说明 Node 安装损坏（常见于用非官方镜像源安装的精简版）。必须卸载重装官方二进制包（官网下载.exe或.pkg，不要用choco install nodejs或brew install node的默认配置，它们可能禁用了某些模块）。

2.2 全局 npm 权限与缓存路径校验

DSH 桥接服务依赖全局安装的dsh-bridge，而 npm 全局安装路径若指向系统保护目录（如 Windows 的C:\Program Files\nodejs\node_modules），普通用户无写入权限，会导致npm install -g dsh-bridge表面成功，实际文件未写入，npx dsh-bridge找不到命令。

验证方法：

npm config get prefix npm config get cache npm list -g dsh-bridge

理想输出应类似：

/home/username/.local/share/npm /home/username/.cache/npm /home/username/.local/share/npm/lib/node_modules/dsh-bridge

如果prefix是/usr/local（macOS）或C:\Program Files\nodejs（Windows），必须重置：

# Linux/macOS mkdir -p ~/.local/share/npm npm config set prefix ~/.local/share/npm npm config set cache ~/.cache/npm # Windows（PowerShell） mkdir "$env:USERPROFILE\AppData\Roaming\npm" npm config set prefix "$env:USERPROFILE\AppData\Roaming\npm" npm config set cache "$env:USERPROFILE\AppData\Roaming\npm-cache"

注意：重置后需重启终端，且PATH中必须包含新prefix/bin（Linux/macOS）或prefix（Windows）。Windows 用户尤其要注意，npm config get prefix返回路径后，要把该路径加到系统环境变量PATH里，否则npx找不到全局命令。

2.3 OpenSSL 与 TLS 协议栈兼容性测试

DSH 桥接服务需与 WorkBuddy 建立 HTTPS 连接（即使本地，WorkBuddy 也强制使用https://localhost:3000作为 bridge endpoint），而旧版 Node（<18.17）或某些定制版 Node（如企业内网打包版）的 OpenSSL 库不支持 TLS 1.3，会导致握手失败，错误表现为Error: write EPROTO或Error: unable to verify the first certificate。

验证命令：

node -e " const https = require('https'); const options = { hostname: 'localhost', port: 3000, path: '/health', method: 'GET', rejectUnauthorized: false }; const req = https.request(options, (res) => { console.log('✅ TLS 连接可达（忽略证书）'); }); req.on('error', (e) => console.error('❌ TLS 连接失败:', e.message)); req.end(); "

若失败，请升级 Node 至 18.17+ 或 20.9+（LTS 版本），并确保系统 OpenSSL 版本 ≥ 1.1.1（Linux 用openssl version查，Windows 用户直接装官方 Node，它自带 OpenSSL）。

2.4 本地端口占用与防火墙穿透检查

DSH 桥接服务默认监听http://localhost:3001，WorkBuddy 默认尝试连接https://localhost:3000（注意：是 3000，不是 3001）。这个端口映射关系由桥接服务启动时的-p参数决定，但很多用户没改，默认配置下，WorkBuddy 实际访问的是http://localhost:3001（HTTP），而非 HTTPS。

验证端口是否空闲：

# Linux/macOS lsof -i :3000 lsof -i :3001 # Windows netstat -ano | findstr :3000 netstat -ano | findstr :3001

若端口被占用（如 Chrome Remote Debugging、其他本地开发服务），必须修改桥接服务端口：

npx dsh-bridge -p 3002 --https-port 3003

同时，WorkBuddy 设置中需同步修改 Bridge URL 为http://localhost:3002（注意：这里用 HTTP，因为桥接服务自身不提供 HTTPS，WorkBuddy 的 HTTPS 是它自己加的代理层）。

关键经验：WorkBuddy 的 Bridge URL 设置项，填的是“它要连谁”，不是“桥接服务监听谁”。桥接服务启动时-p指定的是它自己监听的端口，WorkBuddy 的设置项必须与之完全一致，且协议（http/https）也要匹配。很多用户填https://localhost:3001却启动dsh-bridge -p 3001（HTTP 模式），导致连接被浏览器拦截。

2.5 DSH 插件沙箱环境隔离验证

DSH 插件运行在独立子进程中，每个插件有自己的node_modules和环境变量。但若用户全局安装了冲突版本的依赖（如glob@10.0.0），而某个插件要求glob@8.1.0，就会因require.resolve('glob')返回错误版本导致插件崩溃。

验证方法：找一个最简单的 DSH 插件（如官方dsh-say-hello），手动运行其入口文件：

# 先安装插件（假设插件市场 ID 是 say-hello） dsh plugin install say-hello # 进入插件目录（Linux/macOS） cd ~/.dsh/plugins/say-hello # Windows 路径：C:\Users\{user}\AppData\Roaming\dsh\plugins\say-hello # 手动运行（跳过 DSH 调度，直击 Node） node index.js --input="world" --output=json

若输出{"message":"Hello, world!"}，说明插件环境正常；若报错Cannot find module 'lodash'或Error: ENOENT: no such file or directory，说明插件依赖未正确安装，需进入插件目录执行npm install（注意：不是全局npm install，是插件目录下的局部安装）。

这五层检查，我称之为“Node 可用性黄金五步”。跳过任何一层，都会导致桥接服务启动后看似正常（日志显示Bridge listening on http://localhost:3001），但 WorkBuddy 发送请求时，桥接服务收不到，或收到后无法分发给插件。这不是 bug，而是环境契约未满足。

3. DSH 桥接服务的启动与调试：从静默失败到日志可见

DSH 桥接服务（dsh-bridge）的设计哲学是“零配置默认运行”，但这恰恰是它最危险的地方——没有显式日志输出，没有状态指示灯，失败时只在终端闪一下就消失。我统计过团队内 37 个桥接失败案例，其中 29 个是因为用户启动后没盯住终端，以为“没报错就是成功”，结果 WorkBuddy 一直 fallback 到云端 API。

3.1 标准启动流程与必备参数

官方文档说npx dsh-bridge就能启动，但生产环境必须加至少三个参数：

• -p：指定 HTTP 监听端口（默认 3001）；
• --https-port：指定 WorkBuddy 期望的 HTTPS 端口（默认 3000），这个端口由 WorkBuddy 内部的反向代理监听，它把 HTTPS 请求解密后转发给-p指定的 HTTP 端口；
• -d：启用 debug 日志（必须加，否则只有 info 级别，看不到关键错误）。

正确启动命令：

npx dsh-bridge -p 3001 --https-port 3000 -d

启动后，你会看到类似输出：

[INFO] Bridge server starting... [INFO] HTTP server listening on http://localhost:3001 [INFO] HTTPS proxy listening on https://localhost:3000 [DEBUG] Loaded 12 plugins from /home/user/.dsh/plugins [DEBUG] Plugin 'git-status' registered with skill ID 'git.status' [DEBUG] Plugin 'file-search' registered with skill ID 'file.search'

注意：[DEBUG] Loaded 12 plugins这行至关重要。如果这里显示Loaded 0 plugins，说明 DSH 插件目录路径不对，或插件未正确安装。DSH 默认插件目录是~/.dsh/plugins（Linux/macOS）或%APPDATA%\dsh\plugins（Windows），但 WorkBuddy 的插件市场下载的插件，有时会默认存到~/Downloads或临时目录，必须手动移动或用dsh plugin install <id>命令安装。

3.2 日志分级与关键错误定位

dsh-bridge日志分为四级：ERROR、WARN、INFO、DEBUG。日常调试只需关注ERROR和WARN，但首次部署必须开-d看DEBUG。

常见ERROR类型及对策：

WARN级别更需警惕，因为它不中断服务，但预示功能降级：

• WARN Plugin 'abc' has no manifest.json, using default config：插件缺少manifest.json，DSH 无法读取其 skill ID 和参数契约，只能 fallback 到通用执行器，可能导致参数传递错误；
• WARN Bridge is running without SSL cert, HTTPS proxy may be insecure：WorkBuddy 强制 HTTPS，但桥接服务没配证书，此时浏览器会拦截连接，必须在 WorkBuddy 设置中关闭 “Enforce HTTPS for bridge” 选项（不推荐，仅调试用）；
• WARN Cache directory '/home/user/.dsh/cache' is not writable：缓存目录权限不足，影响插件结果缓存，需chmod 755 ~/.dsh/cache。

3.3 实时请求追踪：用 curl 模拟 WorkBuddy 行为

当 WorkBuddy 界面点击“执行”没反应时，不要盲目重启，先用 curl 直接发请求，确认是前端问题还是桥接问题：

# 构造一个最小 Intent Packet（JSON 格式） cat > intent.json << 'EOF' { "skill_id": "file.search", "parameters": { "query": "README.md", "path": "/home/user/my-project" }, "context": { "workspace_id": "ws-abc123", "user_id": "u-def456" } } EOF # 发送给桥接服务（注意：用 HTTP，不是 HTTPS） curl -X POST http://localhost:3001/dsh/invoke \ -H "Content-Type: application/json" \ -d @intent.json

预期响应：

{ "status": "success", "result": ["/home/user/my-project/README.md"], "execution_time_ms": 124 }

如果返回curl: (7) Failed to connect to localhost port 3001: Connection refused，说明桥接服务没起来；如果返回{"error":"Invalid skill_id"}，说明插件没注册成功；如果返回空响应或超时，说明插件执行卡死，需查插件日志。

实操技巧：我把这个 curl 命令保存为test-bridge.sh，每次怀疑桥接有问题时，先跑一遍。它比看 WorkBuddy 控制台日志更快，因为 WorkBuddy 的日志会过滤掉原始 HTTP 请求体，而 curl 能看到完整输入输出。

3.4 桥接服务的守护与自启配置

开发阶段可以前台运行npx dsh-bridge -d，但生产环境（尤其 Win/macOS 桌面）需要后台常驻。不同系统方案不同：

• Linux（systemd）：创建/etc/systemd/system/dsh-bridge.service：

  [Unit] Description=DSH Bridge Service After=network.target [Service] Type=simple User=your-username WorkingDirectory=/home/your-username ExecStart=/usr/bin/npx dsh-bridge -p 3001 --https-port 3000 Restart=always RestartSec=10 [Install] WantedBy=multi-user.target

  然后sudo systemctl daemon-reload && sudo systemctl enable dsh-bridge && sudo systemctl start dsh-bridge。

• macOS（launchd）：创建~/Library/LaunchAgents/com.dsh.bridge.plist：

  <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.dsh.bridge</string> <key>ProgramArguments</key> <array> <string>npx</string> <string>dsh-bridge</string> <string>-p</string> <string>3001</string> <string>--https-port</string> <string>3000</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> </dict> </plist>

  然后launchctl load ~/Library/LaunchAgents/com.dsh.bridge.plist。

• Windows（Task Scheduler）：不能用 bat 直接跑（会闪退），必须用 PowerShell 脚本包装：

  # start-bridge.ps1 Start-Process "npx" "-g dsh-bridge -p 3001 --https-port 3000" -WindowStyle Hidden

  在任务计划程序中创建触发器：“登录时”运行，勾选“不管用户是否登录都要运行”，并设置“只在本地运行”。

这些配置的核心目标只有一个：让dsh-bridge进程在用户登录后自动拉起，并在崩溃后自动重启。我见过太多用户抱怨“早上开机 WorkBuddy 就连不上 DSH”，其实只是桥接服务没随系统启动。

4. WorkBuddy 端的 Bridge 配置与上下文绑定：让意图精准落地

WorkBuddy 界面里的 “Bridge Settings” 看似简单，但每个字段都牵一发而动全身。很多人填完 URL 就以为万事大吉，结果发现 DSH 插件执行时，路径全是错的（比如插件想读./src/index.ts，却去读了C:\Users\Public），或者用户身份识别失败（所有操作都以root或SYSTEM权限执行）。问题根源在于：WorkBuddy 不只是把请求发过去，它还负责把当前工作上下文“注入”到 Intent Packet 中，而这个注入过程，高度依赖 Bridge Settings 的精确配置。

4.1 Bridge URL 的协议、域名、端口三要素

Bridge URL 格式：<protocol>://<host>:<port>，三者缺一不可，且必须与dsh-bridge启动参数严格一致。

• Protocol：必须是http，不是https。WorkBuddy 内部有一个 HTTPS 代理层，它会把https://localhost:3000的请求解密后，以 HTTP 协议转发给桥接服务。如果你在设置里填https://localhost:3001，WorkBuddy 会尝试建立 HTTPS 连接，而dsh-bridge默认不提供 HTTPS 服务，导致连接超时。
• Host：必须是localhost，不能是127.0.0.1。虽然两者等价，但 WorkBuddy 的证书验证逻辑对localhost有特殊豁免（允许自签名证书），对127.0.0.1则严格校验，容易触发NET::ERR_CERT_COMMON_NAME_INVALID。
• Port：必须与dsh-bridge -p <port>的<port>完全相同。例如dsh-bridge -p 3002，则 URL 必须是http://localhost:3002。

错误示例与后果：

4.2 Context Injection 的三大关键字段

WorkBuddy 在发送 Intent Packet 前，会自动注入三个核心上下文字段，它们决定了 DSH 插件执行时的“立足点”：

• workspace_root：当前打开的项目根目录绝对路径。DSH 插件（如git.status）会以此为基准执行git status。如果这个路径错了，插件就找不到.git目录。
• active_file_path：当前编辑器中焦点文件的绝对路径。插件（如code.analyze）会读取此文件内容进行分析。如果路径为空或错误，插件可能读取空白文件或报错。
• user_profile：用户唯一标识哈希值，用于 DSH 插件的权限控制和结果缓存。如果此值为空，DSH 可能 fallback 到匿名模式，导致缓存失效或权限拒绝。

这些字段的来源，取决于 WorkBuddy 的集成方式：

• VS Code 插件版：自动从 VS Code 的workspaceFolders[0].uri.fsPath和window.activeTextEditor?.document.uri.fsPath获取；
• 独立桌面版：依赖用户手动设置 “Default Workspace” 路径，并在打开文件时更新active_file_path；
• Web 版（PWA）：受限于浏览器沙箱，workspace_root无法获取，只能靠用户上传 ZIP 或指定 GitHub 仓库，此时workspace_root会被设为临时解压路径。

验证上下文是否正确：在 WorkBuddy 中执行一个简单命令（如 “What’s my current directory?”），然后查看桥接服务DEBUG日志，搜索Intent packet received，你会看到类似：

{ "skill_id": "shell.exec", "parameters": {"command": "pwd"}, "context": { "workspace_root": "/home/user/my-nextjs-app", "active_file_path": "/home/user/my-nextjs-app/pages/index.tsx", "user_profile": "sha256:abc123..." } }

如果workspace_root是/home/user（用户家目录）或空字符串，说明 WorkBuddy 没识别到当前项目，需检查 VS Code 是否已打开文件夹，或桌面版是否设置了正确的 Default Workspace。

4.3 Skill ID 映射与插件市场 ID 的对应关系

WorkBuddy 的指令（如 “Show git status”）最终要映射到 DSH 的 Skill ID（如git.status）。这个映射不是硬编码的，而是通过 DSH 插件的manifest.json文件声明的。

一个标准manifest.json示例：

{ "id": "git-status-plugin", "name": "Git Status", "description": "Get current git repository status", "skills": [ { "id": "git.status", "name": "Get Git Status", "parameters": [ {"name": "path", "type": "string", "required": true, "default": "{workspace_root}"} ] } ], "entry": "index.js" }

关键点：

• skills[].id就是 DSH 内部识别的 Skill ID，WorkBuddy 的自然语言理解模块（NLU）会把它和用户指令关联；
• parameters[].default支持模板变量{workspace_root}，DSH 运行时会自动替换为真实的路径；
• 如果插件没声明skills数组，或skills[].id为空，DSH 会分配一个默认 IDplugin.<id>，但 WorkBuddy 的 NLU 无法识别，导致指令无法触发。

因此，“workbuddy-to-dsh” 的核心配置，其实是确保 WorkBuddy 的 NLU 模型知道git.status对应 “Show git status” 这个说法。官方插件市场下载的插件，其manifest.json已预置了常用 Skill ID；但如果你自己开发插件，必须手动在manifest.json中定义skills，并确保 ID 与 WorkBuddy 的语义词典匹配。

经验技巧：我习惯在开发新插件时，先用dsh plugin list确认 Skill ID 是否注册成功，再在 WorkBuddy 中用 “Execute skill: git.status” 这样的精确指令测试，绕过 NLU，直接验证桥接链路。等确定链路通了，再优化 NLU 触发词。

4.4 缓存与超时策略：平衡响应速度与结果新鲜度

WorkBuddy 对 DSH 请求默认启用两级缓存：

• 客户端缓存：同一 Skill ID + 相同参数的请求，5 分钟内直接返回上次结果，不发网络请求；
• DSH 服务端缓存：桥接服务会缓存插件执行结果 60 秒，避免重复计算。

这带来两个典型问题：

• 问题1：代码改了，但 “Show git diff” 还显示旧结果
  原因：客户端缓存未失效。解决：在 WorkBuddy 设置中，找到 “Bridge Cache TTL”，改为0（禁用客户端缓存），或按Ctrl+Shift+R强制刷新。

• 问题2：大文件搜索卡住，WorkBuddy 显示 “Timeout”
  原因：DSH 默认超时 30 秒，而file.search插件扫描整个node_modules可能超时。解决：在 Bridge Settings 中，调整 “Request Timeout (ms)” 为60000（60 秒），并在插件代码中实现分块搜索或提前终止逻辑。

超时值的设定需要权衡：设太短，复杂插件总失败；设太长，UI 卡顿影响体验。我的实践是：对 I/O 密集型插件（文件搜索、数据库查询），设 60000；对 CPU 密集型（代码分析、AI 处理），设 120000；对纯网络请求（API 调用），设 10000。

5. 故障排查全景图：从请求发出到插件执行的七步链路

当 WorkBuddy 点击执行按钮后毫无反应，或返回 “Execution failed”，不要急于重装。我梳理了一条完整的请求链路，共七个关键节点，每个节点都有对应的验证方法。按顺序排查，99% 的问题都能定位。

5.1 Step 1：WorkBuddy 前端是否发出请求？

打开浏览器开发者工具（F12），切换到 Network 标签页，过滤fetch，点击 WorkBuddy 执行按钮，观察是否有POST /dsh/invoke请求发出。

• 有请求，状态码 200→ 问题在 DSH 端或插件端；
• 有请求，状态码 0 或 pending→ 网络层阻塞（HTTPS 证书、CORS、防火墙）；
• 无请求→ WorkBuddy 未触发桥接，检查 Bridge URL 是否正确、Bridge 功能是否启用（Settings → Bridge → Enable toggle）。

5.2 Step 2：请求是否到达桥接服务？

在dsh-bridge终端窗口，开启-d日志，观察是否有Intent packet received日志。

• 有日志，且显示完整 JSON→ 请求已送达，进入 DSH 调度；
• 无日志→ 请求被拦截，检查 Bridge URL 端口是否匹配、防火墙是否放行、WorkBuddy 是否配置了代理。

5.3 Step 3：DSH 是否识别 Skill ID？

在dsh-bridgeDEBUG 日志中，查找Routing to skill行。

• 有Routing to skill 'xxx'→ Skill ID 匹配成功，进入插件加载；
• 无此日志，或显示No plugin found for skill_id 'xxx'→ 插件未安装或 Skill ID 不匹配，运行dsh plugin list确认。

5.4 Step 4：插件是否成功加载？

日志中查找Loaded plugin 'xxx'或Plugin 'xxx' failed to load。

• 有Loaded plugin→ 插件代码已读入内存；
• 有failed to load→ 插件index.js语法错误，或依赖缺失，进入插件目录手动node index.js测试。

5.5 Step 5：插件子进程是否启动？

dsh-bridge会为每个插件启动一个node子进程。用系统命令查看：

# Linux/macOS ps aux | grep "node.*index.js" # Windows tasklist /fi "imagename eq node.exe" | findstr "index.js"

• 有进程，且命令行含插件路径→ 子进程已启动；
• 无进程→ DSH 调度器未下发，检查插件manifest.json的entry字段是否指向正确文件。

5.6 Step 6：插件是否接收参数并执行？

在插件index.js开头加日志：

console.log('Plugin started with args:', process.argv); console.log('STDIN data:', process.stdin.read()); // 注意：需设置 stdin 为 flowing mode

然后重新触发请求，看日志是否输出。

• 有输出，且参数正确→ 插件逻辑开始执行；
• 无输出→ 插件未被调用，或process.stdin未正确读取，检查插件是否按 DSH 协议读取 STDIN（必须process.stdin.setEncoding('utf8')并监听data事件）。

5.7 Step 7：插件是否返回结果？

插件必须向 STDOUT 写入 JSON 格式结果，并以换行结束：

process.stdout.write(JSON.stringify({status: 'success', result: 'done'}) + '\n');

• 有stdout.write且格式正确→ 结果返回给桥接服务；
• 无输出，或格式错误（如多写了一个逗号）→ 桥接服务解析失败，日志报Invalid JSON response。

这七步链路，我画在一张 A4 纸上贴在显示器边框，每次遇到问题就按顺序打钩。它强迫你把模糊的 “不行” 拆解成具体的 “哪一步断了”，极大提升排错效率。记住：不要跳步，不要凭感觉，每个步骤都有客观证据（日志、进程、网络请求）。