dsh-beginner-hub

Readme

# 🧭 dsh-beginner-hub · DSH 新手台

> 面向 DeepSeek Harness（DSH）纯新手的**需求路由 + 轻量引导**面板：用大白话输入想干的事，
> 本地规则引擎把需求路由成「马上能用」的方案（直接问它的话术 / 可用技能 / DSH 进阶玩法），
> 一键填入新会话。技能/插件的安装管理交给生态成熟插件（我们不重复造轮子）。

*English:* dsh-beginner-hub is a **need-router + lightweight onboarding panel** for DeepSeek Harness beginners.
Type a request in plain language and the panel routes it (local keyword rules, no network) into ready-to-use
plans — ask-it prompts, usable skills, and DSH advanced moves — each one-click fillable into a new session.
Skill management itself is delegated to mature ecosystem plugins.

[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![version](https://img.shields.io/badge/version-0.4.1-blue)](package.json)
[![dsh-plugin](https://img.shields.io/badge/dsh-plugin-4d6bfe)](#)
[![platform](https://img.shields.io/badge/platform-web%20profile-2ea44f)](#)
![中文](https://img.shields.io/badge/语言-中文-important)

---

## 为什么有它（定位与差异）

DSH 生态的成熟插件各有分工；新手缺的是「**开口第一步**」——不知道问什么、怎么问、能让它干什么。
本插件补上这一环：把一句大白话需求，路由成可直接使用的方案。

| | **dsh-beginner-hub（本项目）** | [dsh-starter-zh](https://github.com/863683348/dsh-starter-zh)（新手包） | [dsh-skill-manager](https://github.com/sulfide2085/dsh-skill-manager)（技能管理） | [dsh-launcher](https://github.com/loudMore/dsh-launcher)（傻瓜式启动器） |
|---|---|---|---|---|
| 定位 | **需求路由 + 轻量引导** | 欢迎语/学习路径/自查清单 | 技能安装/启停/市场（设置页 UI） | dsh 与插件的一键安装/维护/环境检测 |
| 大白话需求 → 方案 | ✅ 核心能力（10 类本地规则） | ❌ | ❌ | ❌ |
| 一键填入新会话 | ✅ | ❌ | 部分（技能调用） | ❌ |
| 技能管理 | ❌（引导你装管理器） | ❌ | ✅ | 插件级（非技能级） |
| 运维/环境检测 | ❌ | ❌ | ❌ | ✅ |

### 同类对比 / 借鉴与差异（v0.4.0 调研）

> 调研方式：GitHub API 读取仓库元数据（星数/描述/语言）与 README（2026-09-09~10）。
> 下表只列**已核实**的项目；星数为调研时快照。

| 项目（★） | 它有什么 | 我们有没有 | 借鉴了什么 / 为什么 |
| --- | --- | --- | --- |
| [863683348/dsh-starter-zh](https://github.com/863683348/dsh-starter-zh)（★1） | 新手入门包：安装即欢迎语、0→1 学习路径、按场景推荐插件、新手自查清单；联动 dsh-handbook-zh 中文教程 | 部分（有路由与进阶，但没“欢迎引导”与“自查清单”） | ✅ **首次引导卡** + ✅ **新手自查清单**——两者都是“零学习成本”的轻量引导，直接用 localStorage 本地记忆，不碰核心路由 |
| [loudMore/dsh-launcher](https://github.com/loudMore/dsh-launcher)（★32） | 小白向启动器：一键安装/更新/维护 dsh 与插件、环境检测 | 部分（进阶页有环境自检，但不做安装/维护） | 只借鉴“**小白友好文案与零门槛表述**”；安装/维护是它的强项，我们不去抢 |
| [sulfide2085/dsh-skill-manager](https://github.com/sulfide2085/dsh-skill-manager)（★11） | 设置页统一管理 DSH/Codex/Claude 技能：热开关启停、GitHub 技能市场一键发现安装、本地 ZIP 导入 | ❌（刻意不做） | 不借鉴功能（职责不同）；我们**检测它是否已装并在技能页引导用户去用它**——管理靠生态 |
| [MichengAI/dsh-skills-manager](https://github.com/MichengAI/dsh-skills-manager)（★38） | 统一加载并安全管理本机 Agent Skills | ❌（同上） | 同上：作为备选管理器列入引导区 |
| [863683348/dsh-need-finder](https://github.com/863683348/dsh-need-finder)（★1） | **面向 agent 的工具**：`plugin_guide` 把自然语言需求语义匹配到精选**插件目录**（84 个插件），给出理由与 `dsh plugin add` 安装命令；`recipe` 一键装整套社区配方 | ❌（刻意不同） | 不借鉴功能：我们是**面向新人的 Web 面板**，输出是**可直接用的方案**（提问话术/技能引用/进阶玩法）而非插件导购，且方案可**一键填入新会话**；它服务“装哪个插件”，我们服务“这句话该怎么用 DSH” |

**与“路由器”类插件的边界**（[CARVIN94/dsh-router](https://github.com/CARVIN94/dsh-router) ★7、[BruceLanLan/dsh-tier-router](https://github.com/BruceLanLan/dsh-tier-router) ★6 等）：那些路由的是**模型/供应商请求**（网关层）；本项目路由的是**用户意图**（把需求变成可执行方案），两者层级不同、不冲突。

**未纳入本轮借鉴（本轮网络受限未能核实其 README/功能，不做臆测）**：
`zebbkira/dsh-skills-mcp-manager`、`liqichen/dsh-plugin-manager`、`omdsh-dev/dsh-genui`（用户提及 427★，待后续核实后再评估）。

**已落地的借鉴点（宁缺毋滥，共 4 个，v0.4.0）**：
1. 首次引导卡（可关闭、本地记忆）——降低第一屏迷茫；
2. 新手自查清单（可勾选、本地记忆）——把“学会用 DSH”变成可打勾的小目标；
3. 快捷键：`Esc` 关闭面板、路由输入框 `Enter`/`Ctrl+Enter` 直接出方案；
4. 错误恢复：「去 GitHub 找找」失败态补「🔄 重试」。

> 我们刻意**不做**：GitHub 搜技能、一键安装/卸载、启停管理、回收站——这些交给 dsh-skill-manager
> （sulfide2085/dsh-skill-manager 等，均已 GitHub API 核实存在）。管理靠生态，我们专注路由与引导。

## ✨ 功能一览

- ⚡ **需求路由（默认页）**：输入大白话 → 本地规则分类（**9 类意图** + 兜底万能公式）→ 每类 ≥3 方案卡：
  - 方案A **直接问它**（2–3 个可直接用的口语话术变体）
  - 方案B **可用技能**（已装技能引用 + 用法；未装推荐 → 链接 + 「用 dsh-skill-manager 装」提示）
  - 方案C **进阶玩法**（读文件给路径 / 改完自己跑验证 / 让它先给依据再给结论…）
  - 每张卡带「🚀 填入新会话 / 📋 复制」（针对 DSH Lexical 输入框做了真实填充）
  - 覆盖：学知识 / 解释代码 / 写东西 / 整理资料 / 编程任务 / 让它动手 / **AI 防乱说避坑** / 求职 / 兜底
  - **动态兜底（v0.3.2）**：本地规则没猜中时三管齐下——保留万能公式 + 换说法示例，新增
    「🌐 让 DSH 上网查」（一键把问题填进会话，让 DSH 上网搜索并给来源）与
    「🐙 去 GitHub 找找」（区内联 GitHub 仓库搜索结果 top5，带星数；限速/失败自动降级为
    打开 GitHub 搜索页）；成功方案卡尾部也有同样的升级出口（不满意→交外部）
- 📚 **技能筛选（只读三块）**：① 已装一览（扫描本机技能目录读 SKILL.md，无管理按钮）② 匹配说明
  ③ 想要更多/想管理？（检测 dsh-skill-manager 是否已装：未装→是什么 + 一键装命令复制；已装→去它入口）+ 社区推荐（带 GitHub 链接）
- 🗺️ **学习路线（折叠占位）**：一句话 + CTA 跳回路由自动问备战路线
- ⚙️ **进阶（折叠）**：环境自检（模型/凭据/Ollama）+ 常用命令速查（点击复制）
- 🚪 **浮层交互**：入口 pill 与面板独立可拖动（4px 阈值区分点击）、位置各自记忆（localStorage）、版本角标；`Esc` 关闭面板，路由输入框 `Enter`/`Ctrl+Enter` 出方案
- 🆕 **新手引导（v0.4.0）**：首次进入的**三步引导卡**（可关闭）+ 底部**新手自查清单**（可勾选、本地记忆）——借鉴同类新手包，轻量、不碰核心路由
- 🔒 **隐私与成本**：分类是纯前端本地关键词规则（零网络、零 token）；数据都在本机

## 📸 截图（真实运行截图，无头浏览器实拍）

| 需求路由（默认页） | 路由结果（输入「我想学清楚 RAG」） | 技能页·已装一览（只读） | 动态兜底三出口（含 GitHub 内联结果） |
|---|---|---|---|
| ![需求路由默认页](docs/screenshots/01-route-default.png) | ![路由结果-方案卡](docs/screenshots/02-route-result.png) | ![技能已装一览](docs/screenshots/03-skills-installed.png) | ![动态兜底-上网查与GitHub](docs/screenshots/04-fallback-outlets.png) |

## 🚀 快速开始

```powershell
# 1) 指向你的 DSH 数据目录（必设，别用别的值）
$env:DSH_HOME = 'D:\deepseek_harness_qwen\dsh_data'

# 2) 本地开发安装（本仓库当前推荐方式；dsh plugin 会把 link 目录装进 web profile）
dsh plugin --profile web add link:D:\openclaw_workspace\dsh-beginner-hub

# 3) 重启 dsh web，浏览器 Ctrl+F5 强刷
dsh web --no-open --port 3080
```

- 发布到 npm/GitHub 后安装：`dsh plugin --profile web add dsh-beginner-hub`
- 卸载：`dsh plugin --profile web remove dsh-beginner-hub`
- 装完若面板右下角版本不是 **v0.4.0**，多半是页面缓存：Ctrl+F5。

## 🧑‍💻 本地开发

```powershell
$env:DSH_HOME = 'D:\deepseek_harness_qwen\dsh_data'
dsh plugin --profile web add link:<本仓库绝对路径>   # 目录链接安装
node --check lib\index.js; node --check lib\frontend\hub.js   # 语法自检
node tests\smoke.mjs                                          # 离线冒烟测试
```

⚠️ **为什么零运行时依赖**：`link:` 安装是目录链接，插件内 import 会按真实路径解析、够不到 profile
依赖树，所以本插件只用 Node 内建模块（含纯前端规则引擎，不引第三方包）。

## 📁 结构速览

```text
lib/
├── index.js                    # 宿主侧入口：注入面板 + 只读端点(数据/自检/技能扫描/管理器检测)
├── data.js                     # 内容层聚合（路由/词典/避坑/进阶命令）
├── skill-scan.js               # 只读扫描本机已装 Skills（SKILL.md frontmatter）
├── env-check.js / settings-lite.js  # 环境自检（settings.yaml 零依赖子集解析）
├── content/
│   ├── router-data.js          # ★ 意图→方案数据表（10 类 × 词表/话术/进阶），换 API 理解只改这里
│   └── skills-catalog.js       # 社区推荐清单（真实项目 + 来源链接）
├── frontend/
│   ├── hub.{js,css}            # 面板（规则引擎 classify、Lexical 填入、拖动、引导卡/自查清单、快捷键）
│   └── external.js             # 外部出口（GitHub 搜索封装，带节流/降级）
docs/                           # 调研笔记 / 验证记录 / 截图（含真实证据）
tests/smoke.mjs                 # 离线冒烟
```

**换「模型理解」的接口**：路由分类目前是本地关键词打分（零网络）。数据表结构与
`classify()` 单函数隔离——将来接 API 增强只需替换这一个函数，面板无需改动。

## 🗺️ Roadmap

- **v0.5 · API 增强路由**：可选用模型理解替换本地规则（`classify()` 单函数隔离，UI 提供开关）
- **v0.5 · 与 dsh-skill-manager 深度联动**：检测到管理器已装时，方案B 未装推荐直接跳它市场
- **v0.6 · 学习路线正式化**：把占位折叠做成「差距清单 → 分周计划」闭环
- **v0.6 · 多语言**：英文 UI 文案；词库支持中英混输
- **长期**：词库社区化（PR 扩充高频说法）、新手自查项/避坑清单随社区反馈增补、更多本地插件间协作示例

## 📚 调研与机制说明

- [调研笔记](docs/research-notes.md)：DSH 插件注册机制、Skill 存储/调用真相、生态与安装路线核实
- [验证记录](docs/verification-log.md)：逐轮验收证据（含 headless E2E 数据）
- [更新日志](CHANGELOG.md) · [参与贡献](CONTRIBUTING.md)
- 参考：[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录标准与安全警告

## ⚖️ License

[MIT](LICENSE) © chaochaokongbai — 学习/求职作品集项目，欢迎交流与 PR。