# ✦ dsh-constellation

**让你的 DeepSeek Harness 插件宇宙，呈现为一幅实时、自动归类的星座图。**

DeepSeek Harness 说"万物皆插件"——但当你的 profile 装上一百多个 fiber 之后，没人能说清你的 agent 到底由什么组成。哪个 fiber 卡在 pending？`llm` 服务是谁提供的？`dsh-session-title-first-prompt-llm` 是干什么的？

Constellation 一次性回答这三个问题：DSH Web UI 右下角悬浮的 ✦ 按钮，一键打开当前运行 profile 中所有插件与服务 fiber 的实时地图——按均衡的能力域自动归类、用中英文短标签消除命名迷雾、支持搜索定位，并且可以直接操作。

[English](README.md) | [中文](README.zh.md)

![overview](docs/overview-zh.png)

## 功能

### 🌌 星座图 —— 三个缩放层级

地图**默认收起**：每个能力域一个胶囊大节点，大小随成员数增长，域之间是聚合的依赖边。

- **点击域胶囊**，成员插件以径向布局在胶囊周围展开，外围一圈虚线领地边界——再次点击收起
- **大域先聚类**：成员超过 12 个的域先展示服务聚类胶囊（如 `llm ×8`），点击聚类只看这组插件
- **悬停或选中插件**，即时显示它的依赖边（提供者 → 它 → 消费者），其余节点淡出——你的插件组合的"内部逻辑"按需呈现
- **搜什么都可以**：按 `/` 聚焦搜索框，输入插件名、服务名、关键词或域名；结果自动排序、支持键盘导航，点击后镜头飞行定位并脉冲高亮目标节点
- 节点按 fiber 状态着色（active / pending / failed / disabled……），图例同时是状态筛选器

![domain](docs/domain-zh.png)
![deps](docs/deps-zh.png)

### ✦ AI 驱动的自动归类

插件生态的膨胀速度永远快于任何手工维护的分类表。当你的 profile 配置了默认模型时，Constellation 会让它干活：

- **AI 分类** —— 大模型提出一份*均衡*的能力域分类（没有 34 个成员的巨型域，也没有只有 1 个成员的孤域），每个域带中英双语标签；再把每个插件分配进域，并写上短标签：`dsh-session-title-first-prompt-llm` 变成 *标题生成 / Session title LLM*
- **AI 简介** —— 包本身没有描述的插件，由 profile 自己的模型补写一句简介
- **一键重跑** —— 插件集合变化后，点 ✦ *AI 智能分类* 按钮随时重新组织地图

所有结果缓存在 `$DSH_HOME/storages/` 下，一次分类在重启后依然生效。没有配置模型的 profile 会自动退回内置启发式分类器——图谱本身从不依赖模型可用性。

### 🗂 详情侧栏 —— 查看与操作

每个插件可打开侧栏：短标签、简介、状态、提供/消费的服务，以及**实时条目操作**：

- **启用 / 禁用** —— 通过 cordis-plugin-loader 树 API 切换条目并持久化到 profile（无需重启）
- **卸载（Remove）** —— 停止条目并从 loader 树移除（需确认）

![detail](docs/detail-zh.png)

### 📋 清单

按能力域分组的插件卡片：状态、标签、简介、消费与提供的服务。点击卡片打开详情侧栏。

### 🩺 体检

基于实时快照的自动诊断（点击条目可直接查看对应插件）：

- ⏳ **卡死待定** —— fiber 等待的服务没有任何活跃插件提供（并指出缺失的服务名）
- ❌ **加载失败** —— 加载即崩溃的插件
- 🧟 **僵尸条目** —— 已启用但 fiber 已销毁
- ⚠️ **重复提供** —— 两个插件提供同一服务（只有最后激活者生效）

### 🌏 中英双语界面

整个界面支持**中文 / English** 一键切换——插件名是英文的，但使用者未必是。

![search](docs/search-zh.png)

## 安装

```bash
dsh plugin --profile web add dsh-constellation
```

然后启动 Web UI（`dsh --profile web`），点击右下角 ✦ 按钮即可。

## 工作原理

```
┌─ 浏览器 ───────────────────────────────────────┐
│  客户端包（React，约 90 KB）                    │
│  body 门户面板 · canvas 星座图                  │
│  轮询 GET /constellation/graph                 │
└───────────────────┬────────────────────────────┘
                    │ 同源 + 环回地址校验
┌───────────────────┴────────────────────────────┐
│  宿主半（Node）                                 │
│  每次请求遍历 ctx.loader.entries()：           │
│    fiber.inject 的键 → 消费的服务              │
│    fiber.store  的键 → 提供的服务              │
│    fiber.state      → 状态                     │
│  可选 llm 子纤程：AI 分类 + 短标签 + 简介      │
└────────────────────────────────────────────────┘
```

图数据读取的正是 cordis 上下文代理解析服务时参考的同一批运行时记录——不碰内核私有 API，可在小版本漂移下存活。数据不出本机：路由拒绝非环回地址的 Host 头，AI 调用走 profile 自己配置的默认模型。

## 环境要求

- DeepSeek Harness `>= 0.1.0-rc.8`，含 Web 组合（如 `web` profile）
- Node `>= 20`
- *（可选）* 已配置默认模型——用于 AI 分类、短标签与简介生成

## 开发

```bash
npm install
npm run build        # tsc（类型）+ tsdown（lib/index.js + lib/client.js）
```

客户端包遵循 DSH 官方 client-bundle 预设：以 CJS 闭包工厂注册到 `window.__ModuleLoader__`，React / react-dom 对外壳模块表保持 external。

## 许可证

MIT