全能增强套件HIT-HTML/dsh-ENHANCED

dsh-enhanced

CI
License: MIT

preview

DeepSeek Harness（DSH）开箱即用所缺少的日常升级 —— 打包成一个插件。
免费的多引擎网页搜索，带自动回退；持久化的技能与 MCP 管理；受保护的会话清理；以及主题 —— 全部接入同一个 Settings 标签页和一个模型工具。预构建发布，因此从安装到可用之间无需构建步骤；并且它不会向任何人回传数据。

✨ 你将获得

- 🔍 持续运行的免费网页搜索 —— 一个内置的多引擎提供程序：DuckDuckGo ×2、Bing、AnySearch、SearXNG 以及兼容 SearXNG 的网关，外加带密钥的引擎（Exa、Tavily、Keenable、Perplexity、DeepSeek），当免费引擎触发速率限制时，它们会在回退链中待命。完全通过 Settings 标签页配置：对自托管实例进行实时健康检查、按引擎排除、重启后仍保留的故障冷却，以及用于代理设置的端点覆盖。
- 🌐 web_fetch —— URL 内容获取 —— 获取任意 HTTP(S) URL，并以 markdown 形式返回内容（HTML 页面会被剥离为可读文本）。插件加载后即可开箱即用（使用 Node 内置的 fetch；无需 harness fetch 提供程序）。20 秒超时，最多 5 次重定向跳转，256 KB 响应保护。
- ✅ web_search 在启动时自动配置 —— dsh-enhanced 在首次运行时将 free-search: provider: ddg 写入 ~/.dsh/settings.yaml（幂等；会重写过期的 provider: 值）。web_fetch 完全无需设置。
- 🧩 技能管理器 —— 持久化地安装、编辑和移除 agent 的 SKILL.md 技能。安装接受单个技能或一个技能文件夹（磁盘路径或浏览器文件夹选择器均可），保持捆绑的 scripts/ 可执行（浏览器会丢弃权限位；shebang 文件会被恢复为 0755），并按技能报告结果，因此一个坏包永远不会阻塞其余部分。
- 🔌 MCP 服务器管理器 —— 在一个地方跨配置文件管理 @deepseek-ai/dsh-mcp-client 行。
- 🎛️ 插件管理器 —— 通过将禁用行写入配置文件的补丁文件，按配置文件启用/禁用任何已挂载的插件；启动时会监视该文件并实时重新组合，因此切换无需重启即可生效。核心插件（dsh-base、dsh-web-app、dsh-enhanced）会被硬性拒绝，而禁用官方 @deepseek-ai/ 插件需要明确确认。
- 🗑️ 值得信赖的会话清理 — 将整个会话目录从 ~/.dsh/sessions/ 移入操作系统自带的回收站：macOS 的 Finder 废纸篓（~/.Trash）、Linux 上的 FreeDesktop 回收站（带有 .trashinfo 元数据，以便桌面环境提供“还原”功能），以及 Windows 的回收站（通过 PowerShell）。删除操作先进行试运行（计划 + 令牌），并拒绝删除在本进程中打开或最近 15 分钟内活跃的会话（另一个窗口可能仍持有它们）；如果原生移动失败，则不会删除任何内容——你会收到确切的错误信息。还原只需将文件夹拖回 ~/.dsh/sessions/ 下即可。在侧边栏中，每个会话行在悬停时会在其 ⋯ 菜单旁显示一个小垃圾桶图标；它驱动着同一套受保护的流程。
- 🧠 自动压缩调优器 — 将上下文压缩触发阈值限制在 harness 默认值以下，并保持在经过验证的安全范围内。
- 🔄 实例控制 — 通过侧边栏底部“设置”旁的图标按钮，一键关闭/重启 GUI 进程。
- 🎨 主题 — 原版 ENHANCED* 主题（磷光绿终端外观、数字雨启动动画）以及从社区主题移植的 Cyberpunk 2077 主题。

一个宿主组合插件（cordis.patch.yml 中的一行）、一个模型工具接口（manage_skills_mcps）、一个浏览器卡片（设置 → 插件）。无遥测，除搜索引擎本身外无外部服务。机密信息遵循同样的纪律：密钥以仅所有者可访问的权限（0600）写入且绝不回显，操作错误在到达模型、UI 或日志之前会经过机密信息脱敏处理，破坏性流程在确认令牌之后先进行试运行——并且有一个无框架的自检套件在 CI 中为每次发布把关。

📦 安装与首次运行

前提条件： 一个可正常工作的 DeepSeek Harness 安装——这是一个 DSH 插件，不是独立应用。

1. 安装（一条命令）：

dsh plugin add https://github.com/HIT-HTML/dsh-ENHANCED

该仓库附带预构建的 dist/ 和 client.js，因此安装时无需构建步骤。若要进行开发，请参阅开发。

手动替代方案——自行克隆并添加该行

将仓库克隆到任意位置，然后将以下行添加到配置文件的 cordis.patch.yml 中（通常由 dsh plugin add 为你写入）：

- id: dsh-enhanced
name: dsh-enhanced
config:
mcpProfiles: ["default", "web"]   # whose cordis.patch.yml receives managed rows
allowRestart: false               # opt-in for supervisor-assisted restarts

2. 重启配置文件，以便加载新的组合行（插件在启动时挂载）。

3. 验证其是否正常运行：

- Web GUI 中会出现一个 设置 → 插件 卡片，其中包含搜索、技能、MCP、插件、会话和主题等部分。
- 你的智能体获得一个新的模型工具：manage_skills_mcps。
- 可选的冒烟测试：打开 设置 → 插件 → 搜索，选择一个引擎，点击保存，然后让你的智能体运行一次网络搜索。
就是这样——另外请注意，网络搜索需要零配置：全新安装默认使用无需密钥的 Bing 引擎，因此你的 agent 在配置文件启动的那一刻就能搜索。访问 Settings → Plugins → Search 完全是可选的——用于配置需要密钥的引擎、自托管的 SearXNG 实例、排除项或冷却时间调优。

🏗️ 架构

两半部分，标准 DSH 插件形态：

┌─ HOST (Node, src/.ts → dist/) ─────────────────────────────┐
│ index.ts   组合根：注册模型工具、                            │
│            browser RPC 通道、设置锚点，启动                 │
│            内置的搜索引擎                                   │
│ shared.ts  路径、托管块手术、Env/Handler 类型               │
│ skills.ts  mcp.ts  plugins.ts  sessions.ts  compact.ts      │
│            instance.ts  search.ts  cooldown.ts — 功能       │
│            模块，每个模块端到端拥有自己的操作               │
│ free-search-vendor.ts   内置引擎（见下文）                  │
└──────────────┬──────────────────────────────────────────────┘
│ 包私有 JSON RPC（browser → host）
┌─ CLIENT (browser, client/* → client.js bundle) ────────────┐
│ core.js            草稿/保存流水线、sections 注册表          │
│ main.js            启动、已保存主题激活                      │
│ sections/*         每个功能一张卡片（skills、mcp、plugins、  │
│                    sessions、compact、search、theme）        │
│ session-delete.js  原生侧边栏行的悬停垃圾桶删除              │
│                    （fiber 解析、受保护的 RPC）              │
│ themes/*           matrix、cyberpunk2077（+ 启动介绍）       │
└─────────────────────────────────────────────────────────────┘

持久化刻意保持无聊： 每个宿主功能都会将标记分隔的
“托管块”写入 /cordis.patch.yml（技能则写入 ~/.dsh/skills/）。
没有数据库，没有状态文件——用户的配置树就是状态，肉眼可读：

dsh-enhanced:mcp >>>     …rows…      # >> dsh-enhanced:plugins >>> …rows…      # >> dsh-enhanced:compact >>> …row…       # >> dsh-enhanced:search >>>  …row…       # .ts，导出 ACTIONS + Handler，在 index.ts 中加两行，在 client/sections/ 下加一个 section 文件。这就是整个集成流程。

📋 功能参考

| 模块 | 操作 | 写入到 |
|---|---|---|
| skills | list_skills, read_skill, add_skill, edit_skill, remove_skill, install_skill, install_skill_files | ~/.dsh/skills//SKILL.md |
| mcp | list_mcps, mcp_status, add_mcp, remove_mcp, enable_mcp, disable_mcp | 托管的 :mcp: 块 |
| compact | compact_status, set_compact | 托管的 :compact: 块 |
| instance | shutdown_instance, restart_instance | 仅进程控制 |
| plugins | list_plugins, set_plugin_enabled | 托管的 :plugins: 块 |
| sessions | list_sessions, delete_sessions | 将会话目录移入回收站 |
| search | list_search, set_search | 托管的 :search: 块 |
| fetch | web_fetch | —（直接调用 Node 内置的 fetch） |

在客户端，每个功能都是一个 section，接入 core.js 中的三个注册表：
DRAFT_SHAPES（表单状态）、DIRTY_CHECKS（未保存标记）、SAVE_STEPS（保存时重放）。
Section 在展开时自行拉取数据，并在本地暂存编辑；保存时按顺序重放步骤，
批次中途失败时，恰好未应用的部分会保持暂存状态。

密钥（API key）绝不会被回显：list_search 报告 hasKey. 布尔值，
密钥输入框初始为空，表示“未更改”，只有非空值才会被写入。还有两道防护：
一旦密钥被存储，补丁文件会以仅所有者可写（0600）的方式写入；并且每个操作错误
在到达模型、UI 或日志之前，都会经过基于形状的密钥脱敏——
因此，即使网关在错误消息中回显了你的密钥，也会被掩码处理。

🌐 搜索子系统

来源

该引擎是内嵌（vendored）自 dsh-free-search
v0.4.12（MIT，© DDDMUC），内嵌到 src/free-search-vendor.ts。我们选择内嵌而非依赖，
是因为上游的 peerDependencies 未发布到 npm——独立插件全新安装时可能直接失败。
上游的修复不会自动传播；采纳时需重新移植。

与上游相比的本地适配（均为冲突安全或去品牌化）：

| 项目 | 上游 | 此处 |
|---|---|---|
| 设置命名空间 | free-search | enhanced-free-search |
| 桥接前缀 | /api/dsh-free-search-settings | /api/dsh-enhanced-free-search |
| 搜索提供商 id | ddg | ddg（从 enhanced-free 回退；harness 配置期望 ddg） |
| 设置 UI section | 安装了自己的卡片 | 已移除——我们的 Search 标签页负责配置 UX |
| 自更新机制 | check-update + pnpm add 升级路由 | 已移除——内嵌副本不得用上游覆盖自身 |
| 代理可见字符串 | “Settings > Plugins > Free Search” | 指向本插件的 Search section |

启动流程

profile cordis.patch.yml          dsh-enhanced 主机启动
:search: 托管块 ─┐
├─► index.ts: readSearchConfig(profiles[0])
Settings→Search tab ────┘         │
▼
ctx.inject(["web"], scope => freeSearch.apply(scope, cfg))
│
registers provider id "ddg",
agent tools, system-prompt section, bridge routes
│
▼
harness web_search / advanced_search route through it

配置在启动时读取一次——在标签页中保存后，重启配置文件以应用。
如果独立版 dsh-free-search 也安装在某个地方，不会有任何冲突：
不同的命名空间/前缀/提供者 ID，并且每次注册都有防护。

引擎与回退链

首选引擎 = 你的 Provider 下拉选择。失败/结果为空时，回退链继续向下走：

付费（仅在配置密钥时）：  exa → tavily → keenable → perplexity → deepseek-official
免费，始终可用：          bing → anysearch → ddg → ddg-lite → searxng

时间过滤（advanced_search）由支持它的引擎处理，其余引擎跳过。
结果按查询缓存（LRU 约 50 条，TTL ≤5 分钟，可配置）。

排除、冷却、端点覆盖

- 排除引擎（excludedEngines）：一个 CSV 字符串或引擎 ID 数组，将其从回退链中
完全移除——拼写错误会被拒绝，排除所有引擎会被拒绝。保存在
:search: 块中；在配置文件重启后生效。
- 带记忆的失败冷却（src/cooldown.ts）：配额耗尽的失败会让引擎
冷却 12 小时，429/速率限制相关的措辞冷却 15 分钟。状态持久化到磁盘
（~/.dsh/dsh-enhanced/cooldown-state.json），因此重启不会重新耗尽已失效的配额；一般的
网络错误和缺失的密钥不会触发任何冷却。保存搜索配置会清除过期的
判定（你的密钥或端点已更改）。
- 端点覆盖（exaBaseUrl、tavilyBaseUrl、keenableBaseUrl）：将带密钥的引擎
指向自托管或代理网关；仅支持 http/https，留空则清除。
- 回退是可见的：落在非首选引擎上的结果会携带一个结构化的
_fallback {from, to, reason} 副本，与人类可读的 Note 并列。

SearXNG 实例（自托管路径）

公共 SearXNG 实例会把 JSON API 限流到死；运行你自己的：

mkdir -p ~/.searxng && cat > ~/.searxng/settings.yml  /tmp/lab-port.yml
dsh --profile lab --patch /tmp/lab-port.yml

实时提供工作区客户端（cache-control: no-cache），因此客户端修改刷新即可见；
宿主端修改需要重启实验台。切勿将其指向你的主 profile。

添加引擎（搜索）

1. src/free-search-vendor.ts：const X_URL、async function searchX(query, maxResults, options, signal)
返回 { sources: [{url,title?,snippet?}], truncated:false } — 复用 fetchHtmlWithRetry、
stripTags、uniqueSources。
2. 将 id 添加到 FREE_ENGINES / ALL_ENGINES、provider.search 内的 freeEngines 链式数组，
以及 runEngineTest 中的一个 case。
3. client/sections/search.js：一个 PROVIDER_META 条目（除非需要密钥，否则 free: true）。
4. 通过桥进行冒烟测试：curl -X POST .../raw-search -d '{"engine":"x","query":"hi"}'。

添加功能模块

复制 src/compact.ts 的结构（最小的完整示例）：actions 常量、Handler switch、
通过 splitBlock/writeFile 管理块，服务端有防护栏。然后在 index.ts 中加一行 handleX +
展开 X_ACTIONS，再加一个注册到客户端注册表的 section 文件。

发布检查清单

- [ ] npm run build && npm run selfcheck
- [ ] Lab bench 冒烟测试：使用首选引擎 + 一个回退引擎的 bridge 查询
- [ ] dist/ 和 client.js 是此处提交的产物——确保它们是最新的
- [ ] 跟踪文件中没有机器特定路径或密钥（git grep -E "/Users/|sk-[A-Za-z0-9]"）
- [ ] 提升 package.json 版本号，打上与之匹配的 vX.Y.Z 标签，一起推送提交和标签

🔒 隐私与安全说明

- 无遥测。唯一的出站流量是你（或你的 agent）运行的搜索。
- API 密钥存储在配置文件的 cordis.patch.yml 中，绝不会发送回浏览器
（空字段 = 未更改；仅返回 hasKey 布尔值）。
- 测试 bridge 仅接受回环请求（isLoopbackRequest 防护）并会脱敏密钥。
- 测试中类似 EXA123 的字符串是刻意设置的测试夹具，不是凭据。

📄 许可证

MIT——见 LICENSE。包含从
dsh-free-search（MIT，© DDDMUC）引入的代码，以及源自
Cyberpunk 2077 社区主题的主题工作；两者均在文件内注明出处。