better-deepseek-harness（更好的 DeepSeek Harness）

项目名致敬 Minecraft 模组名（？），更好的下界/末地/进度/砧板/FPS/地牢/村庄/经验修补/F3/树叶/动物动作/PVP/HUD/生存/战斗/延迟显示/附魔/图腾/掉落物/钠视频设置按钮……

为 DeepSeek Harness Web UI 编写的插件：在「设置 → 更好的 DeepSeek Harness」中直接安装、卸载、启用/停用 技能（Skills） 与 插件（Plugins），并把插件的自身偏好接入原生设置体系（settings.yaml 的 ext-center 节）。

目录

• 功能
• 兼容性（dsh-web-ui）
• 安装
• 部署配置
• 使用
• HTTP API
• 故障排查

想了解内部实现、参与开发与贡献？见 CONTRIBUTING.md（架构、目录结构、开发与测试流程）。

功能

兼容性（dsh-web-ui）

dsh-web-ui 是 DeepSeek Harness Web UI 的插件与皮肤全家桶（@linxin666/* 系列，可经聚合包 dsh-web-ui-all 一键安装）。它的部分功能与本插件界面重叠；当元素冲突时，本插件不加载自身相应功能，只启用 dsh-web-ui 的功能——自动让位，无需任何配置。

冲突界面与让位规则

说明：dsh-web-ui 的 describe-image 会在客户端把带图发送改写为文本引用，图片块根本到不了 llm/stream 转述瀑布——因此它生效时本插件的图片转述与视觉能力桥直接保持惰性，避免重复的视觉模型调用。

检测与行为

• 按加载器条目 id 或 npm 包名匹配，且只统计 ACTIVE（fiber state 2）且未禁用 的条目：全家桶插件处于 pending / 失败 / 停用状态时它没有渲染任何界面元素，本插件保留自己的功能（fail-open）。
• 宿主侧：apply() 时快照一次加载器树，树收敛后（最多 8 秒）再复查一次——兄弟 bundle 在本插件启动时可能仍在 pending，晚到的激活也会让位；转述监听器与能力桥内部先查门，被抑制时原样放行（恢复 api-gateway 原生图片准入校验）。
• 浏览器侧：文件树 / Git / 终端三个 slot 等客户端加载器树收敛后再注册，只注册不冲突的表面；无加载器或门禁异常时立即 fail-open，绝不隐藏本插件功能。
• 始终不受影响：设置页「更好的 DeepSeek Harness」区块、急救模式弹窗、归档面板、「优化输入」按钮，以及本插件的宿主 API 端点（/ext/api，与全家桶的 /git/*、/api/dsh-ssh/* 互不冲突）。
• 全家桶在运行期才安装时，浏览器侧插件本来就需要刷新页面才出现，刷新后让位自动生效。

安装

方式一：Git 安装（推荐，需要 git 与 npm）

克隆本仓库，然后运行仓库内的一键安装脚本：

git clone https://github.com/silencieuxzero/Better_Deepseek_Harness.git
cd Better_Deepseek_Harness
.\install.ps1                # 默认装入 web profile；其它 profile：.\install.ps1 -Profile agents

脚本会把本包复制到共享模块根 ~/.dsh/profiles/node_modules/better-deepseek-harness，自动执行 npm ci 并生成 lib/（lib/ 不再提交进 git），然后在 profile 的 cordis.patch.yml 追加 ext-center 行（按 id 去重）。配置监听器会在几秒内热生效：主机侧 API 立即可用，浏览器刷新页面后「设置 → 更好的 DeepSeek Harness」出现。

方式二：手动安装（需要 git 与 npm）

把 better-deepseek-harness 整个目录复制到共享模块根（git clone 下来的目录名是 Better_Deepseek_Harness，按实际目录名复制即可）：

Copy-Item -Recurse Better_Deepseek_Harness "$HOME\.dsh\profiles\node_modules\better-deepseek-harness"
cd "$HOME\.dsh\profiles\node_modules\better-deepseek-harness"
npm ci
npm run build

然后在 profile 的 cordis.patch.yml（例如 ~/.dsh/profiles/web/cordis.patch.yml）追加：

- insert:
    - id: ext-center
      name: better-deepseek-harness

配置监听器会在几秒内热生效：主机侧 API 立即可用，浏览器刷新页面后「设置 → 更好的 DeepSeek Harness」出现。

方式三：官方 dsh plugin 流程（需要 pnpm）

本地目录（或方式一 clone 下来的目录）：

dsh plugin --profile web add file:/path/to/better-deepseek-harness

也可以直接从 Git 仓库安装（需要 git）：

dsh plugin --profile web add git+https://github.com/silencieuxzero/Better_Deepseek_Harness.git

本包在 package.json 的 dsh.bundle.patch 中声明的补丁文件（cordis.patch.yml）会插入同名（ext-center）行，与方式一、方式二按 id 去重、不冲突。由于 lib/ 不再提交，安装过程中会通过 prepare 钩子自动构建。

部署配置（ext-center 行的 config 块）

部署可调的行为全部收敛在 cordis.patch.yml 中 ext-center 行的 config: 块，用 schemastery 校验：每个字段自带默认值与合法范围，非法值会让插件加载失败并给出明确报错（宁可响亮失败，不静默漂移）。安全不变量（请求体 2 MiB、技能 URL 下载 1 MiB、插件 tgz 下载 64 MiB、文件编辑器 1 MiB、终端单次写入 4096 字符、git 单批路径 500 条、归档删除单批 500 条、输入优化单次文本 100 KiB）保持固定、不可配置。

- insert:
    - id: ext-center
      name: better-deepseek-harness
      config:
        pluginRoot: ""                  # 插件安装根；留空 = profile 共享模块根 node_modules
        tree:
          maxEntries: 2000             # 单目录最多返回条目数
          ignores: [".git", ".svn", ".hg", "node_modules", ".dsh", "dist",
                    ".next", ".cache", ".turbo", "coverage", "__pycache__",
                    ".DS_Store"]
        terminal:
          maxSessions: 8               # 终端并发上限（1-64）
          bufferLimit: 262144          # 每个终端的输出环形缓冲（字节）
        git:
          timeoutMs: 60000             # 单条 git 命令超时（毫秒）
          diffLimit: 524288            # 单文件 diff 载荷上限（字节，超出截断）
          logMax: 30                   # 提交历史条数
        mcp:
          maxServers: 16               # 面板管理的 MCP 服务器上限
        vision:
          maxImagesCap: 8              # 单次请求转述图片的部署上限（设置页的 1-N 以此为界）
          maxTokens: 1024              # 单次转述输出的默认 token 上限（设置页可覆盖，64-8192）
        toolRepair:
          enabled: true                # tools/execute 参数修复总开关
          descriptionFill: "Execute tool"   # description 缺失时的中性占位文案
        client:
          terminalPollMs: 300          # 浏览器终端输出轮询间隔
          terminalListPollMs: 2000     # 浏览器终端列表轮询间隔
          gitPollMs: 5000              # 浏览器 git 状态轮询间隔
          mcpPollMs: 3000              # 浏览器 MCP 列表轮询间隔
        rescue:
          enabled: true                # 急救模式总开关（默认开）
          settleMs: 12000              # 启动窗口：启动后多久无异常才算启动成功（3000-120000）

以上全部字段均可省略（省略即取默认值）；config: 块本身也可省略。改完后配置监听器热生效（config 属于 ext-center 行的元数据，同样由监听器重放）。Web UI 通过 /ext/api/state 的 limits 块读取这些上限，界面文案（「前 2000 项」「上限 8 个」等）与轮询节奏随之自动跟随。

使用

1. 打开 Web UI → 设置（齿轮）→ 更好的 DeepSeek Harness
2. 「技能」页：填写名称（小写 kebab-case）与内容 / URL / 路径，点安装；列表项可卸载
3. 「插件」页：选择来源并填写 npm 包名 / tarball URL / 本机目录 / Git 仓库地址，点安装；已安装插件可启用、停用、卸载
4. 「设置」页：修改本插件的偏好（保存到 settings.yaml 的 ext-center 节）
5. 「Tavily」页：填写 API Key 并打开「启用搜索」，会话中模型需要实时信息时会自动搜索并引用来源
6. 「GitHub」页：公开仓库无需配置即可用；需要更高速率或访问私有仓库时填写 Token 并打开「启用 GitHub 工具」，会话中模型可查询仓库元数据、列目录、读文件、搜索仓库、查看发布
7. 「通知」页（Windows）：按需开关「提问时通知」与「流程结束时通知」——模型等你输入、或一次流程结束时会弹出系统 Toast 提醒
8. 会话页：在输入框右下角（发送按钮与上下文按钮之间）点击星星图标「优化输入」，当前模型会把输入优化后回填到输入框
9. 侧栏底部：点击「归档」查看已归档对话，勾选后点击「删除」批量永久删除（需二次确认；仍在运行 / 加载中的会话会自动跳过并提示）
10. 急救模式：Harness 启动失败后自动进入——启动成功后弹出对话框列出被禁用的第三方插件，多选后「启用所选并重新加载」，或「全部恢复」/「保持禁用」；也可在「插件」页手动点击「进入急救模式」

安全：所有变更类接口以及会暴露本机路径/输出的读取端点（/ext/api/state、文件树、终端输出、Git 读取、MCP 列表）默认只允许本机（回环地址）调用；如需局域网管理，在「设置」页打开 allowLan。另外注意：Git 源安装本身等于运行仓库里的代码——安装/加载插件以及自动构建（npm install 会执行该仓库声明的 npm 生命周期脚本）都会执行其内容，请只安装你信任的仓库。

故障排查

• 改动未热生效：cordis.patch.yml 的变更由 harness 的配置监听器（HMR）应用。若短时间内连续多次修改（例如安装后立刻停用）触发监听器竞态，配置监听可能卡住——重启一次 dsh web 即可恢复（补丁文件本身是正确的，重启后照常加载）。本插件的写入已做间隔串行化以尽量避免该情况。
• 看不到设置页区块：浏览器刷新页面（客户端 bundle 由 boot manifest 注入，刷新后加载）。
• 设置页一直「加载中…」/ 图片转述没有配置项：设置页改走本插件自己的 /ext/api/state 与 /ext/api/config，不再依赖 api-proxy 是否暴露 ext-center。旧版本若仍在加载中，升级后重启 dsh web 并刷新页面；若只有旧版可用，检查宿主日志确认 ext-center 设置命名空间已注册。
• 安装报 git-unavailable：本机未安装 git，改用目录 / tarball URL / npm 包名来源。
• 安装报 build-failed / build-tool-missing：Git 源仓库没有提交构建产物，且自动构建失败（或本机没有 npm）。先确认本机 npm 可用且能访问 registry；若仓库没有 build 脚本或构建后仍缺入口文件，请改用该包的 npm 包名 / tarball URL 安装。
• 安装报 EPERM: Permission denied（Windows，路径指向 .dsh-ext-center-staging）：Windows 上删除目录时若被其他进程短暂占用（杀毒实时扫描刚 clone 的仓库、文件监听等），会返回 EPERM。本插件已在 staging 清理与目标目录替换处内置重试（maxRetries: 5），瞬时锁会自动跳过；若反复复现说明锁是持续性的——将 ~/.dsh 加入 Windows 安全中心的排除目录，或重启一次后再装（残留的 staging 目录可手动删除，不影响数据）。
• 启动报 [better-deepseek-harness] invalid config on the ext-center row ...：cordis.patch.yml 里 ext-center 行的 config: 有非法值（超出范围或类型错误）。按「部署配置」一节修正或直接删掉该 config: 块（全部回落默认值）后重启。
• Harness 启动失败（插件冲突 / 第三方插件未构建）：正常重启一次应用——急救模式会在下一次启动时自动禁用出问题的第三方插件并以最小化配置启动，随后弹出对话框供你选择恢复哪些插件。若对话框选择「保持禁用」后想恢复，到「插件」页手动启用，或手动编辑 cordis.patch.yml 删除对应行的 disabled: true（急救记录在 profile 目录的 .dsh-rescue.json）。
• 偶发 invalid arguments: missing required property ...：模型生成的工具参数偶发缺字段或 JSON 损坏。本插件的 tools/execute 包装层会自动修复 description 缺失与可恢复的 JSON；确实缺少 code / command 等内容的调用仍会按 DSH 原机制报错并让模型重试，属正常反馈。