fan969690 / dsh-module-center

🧩 DSH 模块中心(dsh-module-center)

把 DeepSeek Harness 的 Web 界面变成一个可自由组合的模块化桌面。 右侧嵌入一块"模块中心",像手机 APP 桌面一样排布卡片——每个卡片是一个独立功能模块,可拖动排序、可自定义大小、可折叠收起。 这是一个开放框架:任何插件注册进 panel.center.modules 槽,就能成为模块中心里的一张卡片。

---

✨ 特性

特性	说明
🖥 原生嵌列	面板真正嵌进 Web 主布局(对话区自动让位),不是悬浮层;可拖拽调宽(280~640px),宽度自动记忆
🗂 宫格排布	2 列 × N 行网格,像手机桌面;模块可占 1 或 2 列、1~6 行,任意组合
📐 自定义大小	每个模块 1×1 ~ 2×6 共 12 种尺寸预设,一键切换,选择自动记忆
🖐 手势操作	单击手柄改尺寸,长按拖动换位置(手机桌面式交互)
🧩 开放模块协议	任何插件注册进 panel.center.modules 槽即成模块,无需改框架代码
⚙ 显示管理	内置管理面板:显示/隐藏任意模块,不卸载插件
📌 折叠/展开	一键收起整列(对话区全宽),需要时从右缘浮动按钮恢复
♾️ 无上限	模块数量不限,右侧列可向下滚动扩展

---

📸 效果预览

先看整体形态——DeepSeek Harness 右侧嵌入一块「模块中心」,对话区自动让位,像手机桌面一样排布功能卡片:

🎬 交互演示

单击手柄 → 弹出尺寸选择器:每个模块右上角有个手柄(如 ⠿ 2x1),单击弹出 12 种尺寸预设,点击即应用,大小自动记住:

长按手柄 → 拖拽换位:像手机桌面一样,长按卡片拖动即可实时换位置,拖动中有高亮边框提示。

⚙ 管理面板:一键显示/隐藏任意模块,不卸载插件,状态自动记忆。

📸 界面实拍

真实运行截图——模块中心的卡片排布、尺寸自适应(1 列宽显示简称,2 列宽显示全名)一目了然:

---

🚀 安装

# 1. 安装框架
git clone https://github.com/fan969690/dsh-module-center.git
cd dsh-module-center
dsh plugin --profile web add ./framework

# 2. (可选)安装演示模块,看效果
dsh plugin --profile web add ./demos/demo-clock ./demos/demo-quicklaunch

# 3. (可选)安装模块库小组件(天气/快捷打开/时钟/便签/行情/每日一言)
dsh plugin --profile web add ./library/weather ./library/quicklaunch ./library/clock ./library/notes ./library/coins ./library/quote

装完重启 dsh web,右侧出现"🧩 模块中心"列。

框架本身不依赖任何内置模块——装上即有一个空白的模块中心。 演示模块(demos/)展示了模块协议的标准写法;模块库(library/)是社区共同维护的小组件集合,可作为你开发模块的起点模板。

---

📦 模块库(社区维护)

library/ 目录是官方小组件集合,由社区共同维护——每个小组件是独立插件,按需安装:

组件	功能
☀️ 天气	实时天气(Open-Meteo 免费 API),城市可切换
🚀 快捷打开	常用链接快捷方式,可自定义
🕐 时钟日历	时钟 / 日期 / 当月月历
📝 便签	快速便签,localStorage 持久
💰 行情	BTC/ETH/SOL/BNB 实时价格与涨跌
📖 每日一言	内置语录,点击换一条

想加自己的小组件? 复制 library/quicklaunch/ 改一改即可——详见 library/README.md 与 CONTRIBUTING.md。欢迎提 PR 共建!

---

🎯 使用

基本操作

• 手柄(标题栏左侧,如 ⠿ 2x1):单击弹出尺寸选择器(1×1~2×6),长按拖动换位置
• 尺寸选择器:12 个预设格,点击即应用;大小会记住,下次打开保持
• ⚙ 管理:显示/隐藏模块(记忆,不卸载插件)
• 折叠(标题栏右侧 »):收起整列;需要时点右缘「⬅ 模块」展开
• 拖动调宽:拖模块列左缘可调整整个面板宽度

尺寸规则

• 宽度为 1 列时:标题栏只显示图标 + 2 字符简称(悬停看全名)
• 宽度为 2 列时:显示图标 + 完整名称
• 模块内容会根据尺寸自适应:窄卡精简,宽卡完整

📐 尺寸与内容推荐

不同大小适合不同类型的内容,做模块时按这个表规划最合适:

尺寸	定位	适合内容	不适合
1×1	极简卡片(跳转/状态)	快捷入口、跳转按钮、状态指示灯、单一数字(在线数/待办数)、迷你开关	列表、图表、表单
1×2	纵向卡片(短列表)	最近 N 条列表、时间线、消息流、日志摘要、纵向小部件	双列数据、宽表格
1×3	纵向长卡(滚动列表)	完整列表(任务/通知/历史)、聊天记录、feed 流	并列对比
1×4+	纵向超长卡	大数据量列表、日志浏览器、时间线全览	—
2×1	横向宽卡(工具/紧凑列表)	工具栏+紧凑列表、搜索+结果、双栏摘要、横向仪表条	深内容阅读
2×2	🎯 中型·监控首选	监控面板(内存/磁盘/CPU 图表)、仪表盘、双列数据卡、状态总览	超长列表
2×3	中型偏大(监控+详情)	监控+明细混合、日历、文件管理器、富内容卡片	—
2×4+	大型工作区	完整工具(商店全宽、编辑器、终端)、复杂仪表盘、多视图网格	—

通用建议:

• 1 列宽 = 快捷/状态/摘要:信息密度要低,一眼能读
• 2 列宽 = 工具/监控/内容:可以承载工具栏、列表、图表
• 高度决定"能放多少行",宽度决定"每行能放什么"

---

🧩 模块协议(给插件开发者)

完整接口文档见 模块协议.md。快速上手:

在插件 client 端(lib/client.js)的 apply(ctx) 里:

function MyModule(props) { return React.createElement(MyModuleView, props); }
// 模块元数据(挂在组件上)
MyModule.moduleMeta = {
  icon: "📌",          // 标题栏图标
  type: "compact",     // 类型:compact(1x1) | wide(2x1) | tall(1x2) | full(2x2)
  desc: "一句话说明",   // 悬停提示
};

ctx.slots.inject("panel.center.modules", () =>
  ctx.slots.register({
    name: "panel.center.modules", // 固定槽名
    id: "my-module",              // 模块唯一 id
    order: 10,                    // 排序权重(小在前)
    label: () => "我的模块",      // 标题
    locale: NS,                   // 可选:组件会收到 t
    inject: () => ({}),           // 可选:业务 props
  }, MyModule)
);

组件通过 props 收到 moduleType / moduleSize,可据此自适应渲染(1×1 精简、2×1+ 完整)。

---

🧪 演示模块

仓库的 demos/ 目录有两个可直接安装、作为模板的演示模块:

演示	类型	展示点
🕐 时钟 demos/demo-clock	compact(1x1)	状态型模块:每秒刷新;1x1 只显示时间,2x1 加日期/星期/秒
🚀 快捷跳转 demos/demo-quicklaunch	compact(1x1)	跳转型模块:1x1 单个大按钮,2x1+ 网格显示全部入口(默认链接到作者 GitHub 仓库,可改 LINKS 换成你的常用页面)

装一个、改一改,就是你的第一个模块。

---

🏗 架构

dsh-module-center/
├── framework/         # 框架本体
│   ├── lib/
│   │   ├── index.js   # host 端(无业务,框架本身不需要 host API)
│   │   └── client.js  # client 端:布局控制器 + 宫格 + 手势 + 尺寸选择器 + 槽渲染
│   ├── cordis.patch.yml
│   └── package.json
├── demos/             # 演示模块(也是开发模板)
│   ├── demo-clock/
│   └── demo-quicklaunch/
├── library/           # 📦 模块库(社区共同维护的小组件集合)
│   ├── weather/       # ☀️ 天气
│   ├── quicklaunch/   # 🚀 快捷打开
│   ├── clock/         # 🕐 时钟日历
│   ├── notes/         # 📝 便签
│   ├── coins/         # 💰 行情
│   ├── quote/         # 📖 每日一言
│   └── README.md      # 清单 + 贡献指南
├── docs/              # 文档与截图
├── CONTRIBUTING.md    # 贡献指南
└── 模块协议.md         # 完整接口文档

核心技术

• 嵌列布局:监听 shell 的 frame grid([data-dsh-frame] 或 sidebarCol 父元素),用 MutationObserver 跟随 shell 每次 grid 写入,在其后追加模块列轨道——永不冲突
• 开放槽:框架注册 shell.overlay 时用 children 声明 panel.center.modules(list/root),"声明即授权"
• 逐条渲染:ctx.slots.entries() 枚举 + renderSlot(key, owner, { only: id }) 逐条渲染,宫格自由排布
• 手势:pointer 事件区分单击(尺寸)与长按拖拽(换位),拖动实时与指针下卡片交换
• 记忆:尺寸/顺序/宽度/隐藏全部存 localStorage,刷新不丢

---

🔗 借鉴与致谢

• deepseek-ai/deepseek-harness:官方扩展机制(shell.overlay / slots / webServer)
• zhu1090093659/dsh-web-ui:AionUi 嵌列布局思路(追加 grid 轨道 + MutationObserver 跟随)

---

📄 许可

MIT License