kidai-hub

Readme

<div align="center">

# 🧩 Kidai Hub（纪代中枢）

**一个入口 · 贯穿所有 Kidai 插件** —— Kidai 系列插件的统一容器

**简体中文** · [**English**](README.en.md)

</div>

---

## ✨ 它是什么

Kidai 系列插件（纪代插件市场、纪代快照守护……）每个都有自己的界面，散落在侧边栏和设置里。
**Kidai Hub（纪代中枢）** 把这些插件的操作界面统一收进一个全屏 Hub：侧边栏底部一键直达，Hub 内用页签栏承载各个 Kidai 插件的面板。

核心理念：**有 Hub 进 Hub，没有 Hub 独立出现。**

- 🗂️ **统一容器** —— Kidai 插件把自己的界面注册进 `kidai-hub.tabs`，Hub 用动态页签栏渲染，一个 Hub 逛遍所有 Kidai 工具；
- 🚀 **侧边栏直达** —— 「Kidai Hub」按钮位于主页侧边栏「设置」上方，点开即全屏 Hub；
- 🧩 **天然回退** —— 当 `kidai-hub` 未安装时，各 Kidai 插件自动回退到自己的独立入口，功能不受任何影响；
- 🔌 **纯浏览器容器** —— 宿主半为 no-op，全部 UI 在客户端，不改 DSH 宿主逻辑。

> **装好即用** —— 安装 Kidai Hub 后，所有接入的 Kidai 插件界面都会聚集到同一个 Hub 里。

---

## 🚀 快速开始

### 安装

```bash
dsh plugin --profile desktop add github:NokorinNishikino/Kidai-Hub
```

**重启 DSH** 后生效，主页侧边栏「设置」上方会出现「Kidai Hub」按钮，点击打开全屏 Hub。

### 卸载

```bash
dsh plugin --profile desktop remove kidai-hub
```

> 需要本机可用的 `pnpm`（或 DSH 自带的 pnpm），并能访问 GitHub。

---

## 🎯 功能

- **全屏 Hub 页** —— 顶栏（标题 + 关闭按钮）+ 动态页签栏 + 可滚动内容区 `kidh_body`；
- **页签槽 `kidai-hub.tabs`** —— 类型 **keyed**、scope `root`；每个 Kidai 插件一个 `key`（通常用插件 id），用 `order` 控制排列；
- **顶栏动作槽 `kidai-hub.header.action`** —— 供插件在 Hub 顶栏追加自己的动作按钮；
- **实时更新** —— 页签注册/注销即时反映到 Hub 顶栏，且无空帧（活动页签自动回退到第一个）；
- **品牌底色** —— 为已知插件提供专属品牌渐变，其余插件按 `key` 稳定派生默认色；
- **双语言** —— 中文 / English 两版 README。

---

## 🔗 生态 / 已支持插件

| 仓库 | 职责 | 在 Hub 中的角色 |
| --- | --- | --- |
| **Kidai-Hub**（你在这里） | Kidai 系列插件的统一容器 | 提供侧边栏入口 + 全屏 Hub 页 + `kidai-hub.tabs` / `kidai-hub.header.action` 槽 |
| [**kidai-plugin-market-hub**](https://github.com/NokorinNishikino/kidai-plugin-market-hub) | 纪代插件市场 Hub（一键装 / 管 / 更新插件） | 注册为 Hub 页签「纪代市场」 |
| [**kidai-snapshot-guard**](https://github.com/NokorinNishikino/kidai-snapshot-guard) | 纪代快照守护（DSH 内部自动备份） | 注册为 Hub 页签「纪代备份」；无 Hub 时回退到 设置 → 纪代备份 |

> 装了 `kidai-hub` 时，上述插件的界面进 Hub；没装 `kidai-hub` 时，它们各自回退到自己的独立入口——两种形态都可正常使用。

---

## 🔌 如何接入一个新的 Kidai 插件

给插件新增「进入 Hub」的能力，完整接入清单见 [KIDAI_HUB_CONTRACT.md](./KIDAI_HUB_CONTRACT.md)。

```js
ctx.slots.inject("kidai-hub.tabs", () => ctx.slots.register({
  name: "kidai-hub.tabs",
  key: "<plugin-id>",      // 一个插件一个 key，通常用插件 id
  order: 90,               // 顶栏顺序（数字小的靠前）
  label: () => t("tabTitle"), // 顶栏按钮文字（跟随 locale 的 thunk）
  locale: "<NS>",
  inject: () => ({ ...yourFns, t }),
}, YourTabPanel));
```

当插件检测到 Hub 在场（`ctx.slots.spec("kidai-hub.tabs")` 非空）时，隐藏自己的独立入口；
Hub 未安装时，则正常显示独立入口——这就是「有 Hub 进 Hub，没有 Hub 独立出现」的判定点。

---

## ⚙️ 工作原理（技术细节）

| 组成部分 | 文件 | 说明 |
| --- | --- | --- |
| Host 半 | `lib/index.js` | 纯浏览器容器，宿主侧为 no-op（`apply(){}`），所有行为在客户端。 |
| 组合层 | `cordis.patch.yml` | 插入一行 `id: kidai-hub` 主机行；因包声明 `dsh.client`，同一行进入浏览器模块清单。 |
| Client 半 | `lib/client.js` | 浏览器 bundle：注册侧边栏启动器（`sidebar.footer.action`）与全屏 Hub 页（`shell.overlay`），声明 `kidai-hub.tabs` / `kidai-hub.header.action` 槽并渲染动态页签栏。 |

```
kidai-hub/
├── lib/
│   ├── index.js          # 插件入口（no-op 宿主）
│   └── client.js         # 浏览器 bundle：Hub 全部 UI（启动器 + 全屏页 + 页签渲染）
├── cordis.patch.yml      # 插入 id: kidai-hub 主机行
├── KIDAI_HUB_CONTRACT.md # 给 Kidai 插件的接入契约
└── package.json          # dsh bundle 清单
```

---

## 📚 更多

- **接入契约**：[KIDAI_HUB_CONTRACT.md](./KIDAI_HUB_CONTRACT.md)
- **开发**：`lib/client.js`（浏览器）重启生效或走 `dsh-client-hmr` 热更；语法检查 `node --check lib/client.js && node --check lib/index.js`；冒烟测试 `node scripts/smoke-client.mjs lib/client.js`。

## License

MIT