dsh-codegraph-visualizer 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +223 -0
- package/cordis.patch.yml +17 -0
- package/dist/client/index.css +2404 -0
- package/dist/client/index.esm.js +44283 -0
- package/dist/client/index.js +46706 -0
- package/dist/client-cjs/index.cjs +44283 -0
- package/dist/client-cjs/index.css +2404 -0
- package/dist/index.d.ts +40 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2277 -0
- package/dist/index.js.map +1 -0
- package/package.json +96 -0
package/README.md
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# DSH CodeGraph Visualizer
|
|
2
|
+
|
|
3
|
+
> DeepSeek Harness (DSH) 代码图谱可视化插件 — 将 `dsh-codegraph` 与 `dsh-tool-lens` 数据源聚合为交互式代码关系图谱
|
|
4
|
+
|
|
5
|
+
[](https://github.com/xuanyuanchumo/dsh-codegraph-visualizer/actions/workflows/ci.yml)
|
|
6
|
+
[](https://github.com/xuanyuanchumo/dsh-codegraph-visualizer/actions/workflows/release.yml)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://nodejs.org/)
|
|
9
|
+
[](https://pnpm.io/)
|
|
10
|
+
|
|
11
|
+
## 概述
|
|
12
|
+
|
|
13
|
+
DSH CodeGraph Visualizer 是一个 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 生态插件，填补了代码关系图谱可视化领域的空白。它将 `dsh-codegraph`（CodeGraph CLI 封装工具）和 `dsh-tool-lens`（AST 代码图谱与拓扑分析）两个数据源的输出聚合、转换，并通过 [Cytoscape.js](https://cytoscape.org/) 渲染为交互式代码关系图谱面板，嵌入 DSH Web UI 侧边栏。
|
|
14
|
+
|
|
15
|
+
### 核心能力
|
|
16
|
+
|
|
17
|
+
- **多数据源融合** — 同时接入 `dsh-codegraph` 与 `dsh-tool-lens`，自动合并去重
|
|
18
|
+
- **渐进式层级聚合** — 目录级 → 文件级 → 函数级 三层聚类，逐层展开
|
|
19
|
+
- **4 种布局引擎** — Cose（力导向）、Dagre（层次）、Circle（环形）、Grid（网格）
|
|
20
|
+
- **交互式分析** — 符号搜索、调用链追踪、循环依赖检测、影响分析、继承层次
|
|
21
|
+
- **实时增量更新** — 文件监听 + 事件驱动，代码变更后图谱自动刷新
|
|
22
|
+
- **导出能力** — PNG / SVG / JSON 三格式导出
|
|
23
|
+
- **中英双语 i18n** — 完整国际化支持
|
|
24
|
+
- **主题切换** — 深色/浅色主题，自动适配 DSH 环境变量
|
|
25
|
+
|
|
26
|
+
## 安装
|
|
27
|
+
|
|
28
|
+
### 前置条件
|
|
29
|
+
|
|
30
|
+
- Node.js >= 22.19 或 >= 24
|
|
31
|
+
- pnpm >= 9
|
|
32
|
+
- DSH Web 环境（`dsh web`）
|
|
33
|
+
|
|
34
|
+
### 通过 DSH 插件管理安装
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
dsh plugin --profile web add /path/to/dsh-codegraph-visualizer
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 从源码构建
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
git clone https://github.com/xuanyuanchumo/dsh-codegraph-visualizer.git
|
|
44
|
+
cd dsh-codegraph-visualizer
|
|
45
|
+
pnpm install
|
|
46
|
+
pnpm run build
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## 快速开始
|
|
50
|
+
|
|
51
|
+
### 开发模式
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# 启动自包含的 dev server（模拟 DSH Web Shell + 模拟数据）
|
|
55
|
+
pnpm run dev
|
|
56
|
+
# → http://localhost:3080
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### 在真实 DSH 环境中测试
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# 构建并安装插件
|
|
63
|
+
pnpm run build
|
|
64
|
+
dsh plugin --profile web add /path/to/dsh-codegraph-visualizer
|
|
65
|
+
|
|
66
|
+
# 启动 DSH Web
|
|
67
|
+
dsh web
|
|
68
|
+
# → http://localhost:3080，点击侧边栏 "Code Graph" 标签页
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### 运行测试
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pnpm run test # 单元测试（320 tests）
|
|
75
|
+
pnpm run test:e2e # E2E 测试（需先启动 dev server）
|
|
76
|
+
pnpm run typecheck # 类型检查
|
|
77
|
+
pnpm run lint # Lint
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## 架构
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
84
|
+
│ DSH Web UI Shell │
|
|
85
|
+
│ ┌───────────────────────────────────────────────────────┐ │
|
|
86
|
+
│ │ CodeGraph Visualizer Plugin │ │
|
|
87
|
+
│ │ │ │
|
|
88
|
+
│ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
|
|
89
|
+
│ │ │ Host Layer │ │ Data Layer │ │ Client Layer│ │ │
|
|
90
|
+
│ │ │ │ │ │ │ │ │ │
|
|
91
|
+
│ │ │ • routes │ │ • CodeGraph │ │ • GraphPanel│ │ │
|
|
92
|
+
│ │ │ • watcher │ │ Adapter │ │ • Toolbar │ │ │
|
|
93
|
+
│ │ │ • config │ │ • LensAdapter│ │ • Cytoscape │ │ │
|
|
94
|
+
│ │ │ • security │ │ • GraphData │ │ Renderer │ │ │
|
|
95
|
+
│ │ │ • prereqs │ │ Merger │ │ • Store │ │ │
|
|
96
|
+
│ │ │ │ │ │ │ • i18n │ │ │
|
|
97
|
+
│ │ └─────────────┘ └──────────────┘ └─────────────┘ │ │
|
|
98
|
+
│ └───────────────────────────────────────────────────────┘ │
|
|
99
|
+
└─────────────────────────────────────────────────────────────┘
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### 目录结构
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
src/
|
|
106
|
+
├── index.ts # Host 端插件入口（re-export 聚合）
|
|
107
|
+
├── tools.ts # 4 个工具定义（graph_status/data/symbol/impact）
|
|
108
|
+
├── types/ # Branded 类型、GraphData、事件声明合并
|
|
109
|
+
├── adapters/ # 数据源适配器
|
|
110
|
+
│ ├── CodeGraphAdapter.ts # dsh-codegraph 数据源
|
|
111
|
+
│ └── LensAdapter.ts # dsh-tool-lens 数据源
|
|
112
|
+
├── merger/
|
|
113
|
+
│ └── GraphDataMerger.ts # 多数据源融合器（去重 + 合并）
|
|
114
|
+
├── host/ # Host 端模块
|
|
115
|
+
│ ├── config.ts # 配置定义与校验
|
|
116
|
+
│ ├── routes.ts # HTTP 路由注册
|
|
117
|
+
│ ├── watcher.ts # 文件监听与事件监听
|
|
118
|
+
│ ├── security.ts # 路径安全校验
|
|
119
|
+
│ └── prerequisites.ts # 前置条件检测
|
|
120
|
+
├── client/ # Client 端模块（浏览器渲染）
|
|
121
|
+
│ ├── index.ts # Client 端插件入口
|
|
122
|
+
│ ├── GraphPanel.tsx # 主面板 UI 组件
|
|
123
|
+
│ ├── api/ # HTTP API helpers
|
|
124
|
+
│ ├── components/ # UI 组件（Toolbar, SearchBar, ImportPanel, ...）
|
|
125
|
+
│ ├── renderer/ # 渲染引擎
|
|
126
|
+
│ │ ├── CytoscapeRenderer.ts # Cytoscape.js 渲染器
|
|
127
|
+
│ │ ├── IRenderer.ts # 渲染器接口
|
|
128
|
+
│ │ └── styles/ # 主题样式
|
|
129
|
+
│ ├── store/ # 状态管理
|
|
130
|
+
│ │ ├── graphStore.ts # Zustand 全局状态
|
|
131
|
+
│ │ └── cluster/ # 聚类策略模块
|
|
132
|
+
│ │ ├── types.ts # ClusterLevel/ClusterNode/ClusterEdge
|
|
133
|
+
│ │ ├── index.ts # 策略注册表
|
|
134
|
+
│ │ ├── directoryCluster.ts # 目录级聚类
|
|
135
|
+
│ │ ├── fileCluster.ts # 文件级聚类
|
|
136
|
+
│ │ ├── functionCluster.ts # 函数级（透传）
|
|
137
|
+
│ │ └── smartCluster.ts # 智能聚类（标签传播）
|
|
138
|
+
│ ├── i18n/ # 国际化（中/英）
|
|
139
|
+
│ ├── hooks/ # React Hooks
|
|
140
|
+
│ └── utils/ # 工具函数
|
|
141
|
+
├── push/ # 推送通知模块
|
|
142
|
+
└── shared/ # Host/Client 共享模块
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 聚类策略
|
|
146
|
+
|
|
147
|
+
采用 **策略模式（Strategy Pattern）** 实现 4 级聚类：
|
|
148
|
+
|
|
149
|
+
| 级别 | 策略 | 行为 |
|
|
150
|
+
|------|------|------|
|
|
151
|
+
| `directory` | DirectoryClusterStrategy | 按顶级目录聚合，展开后显示文件级聚类节点 |
|
|
152
|
+
| `file` | FileClusterStrategy | 按文件聚合，展开后显示函数/类/变量节点 |
|
|
153
|
+
| `function` | FunctionClusterStrategy | 透传，不做聚类 |
|
|
154
|
+
| `smart` | SmartClusterStrategy | 标签传播社区检测算法 |
|
|
155
|
+
|
|
156
|
+
**渐进式层级展开**：在目录级模式下，展开一个目录聚类节点会显示该目录下的文件级聚类节点（而非所有原始节点）。用户可以继续展开文件级聚类节点来查看函数级原始节点。
|
|
157
|
+
|
|
158
|
+
## DSH 插件规范合规
|
|
159
|
+
|
|
160
|
+
本项目遵循 DSH 插件开发规范九条红线：
|
|
161
|
+
|
|
162
|
+
- [x] 插件入口 `src/index.ts` 使用 `definePlugin()` 注册
|
|
163
|
+
- [x] `dsh.bundle.patch` 指定 Cordis 补丁文件
|
|
164
|
+
- [x] `dsh.client.platform` 为 `"web"`
|
|
165
|
+
- [x] `dsh.client.inject` 声明运行时注入依赖
|
|
166
|
+
- [x] `peerDependencies` 声明 Cordis/DSP-Tools/React
|
|
167
|
+
- [x] `exports` 字段正确导出 host/client 入口
|
|
168
|
+
- [x] `files` 字段仅包含 `dist` 和 `cordis.patch.yml`
|
|
169
|
+
- [x] `engines` 字段声明 Node/pnpm 版本要求
|
|
170
|
+
- [x] `packageManager` 字段指定 pnpm 版本
|
|
171
|
+
|
|
172
|
+
## 开发
|
|
173
|
+
|
|
174
|
+
### 技术栈
|
|
175
|
+
|
|
176
|
+
| 层 | 技术 |
|
|
177
|
+
|----|------|
|
|
178
|
+
| 语言 | TypeScript 5.7+ |
|
|
179
|
+
| 框架 | React 19 + Cordis 4 |
|
|
180
|
+
| 渲染 | Cytoscape.js 3.26 + cytoscape-dagre |
|
|
181
|
+
| 状态 | Zustand 5 |
|
|
182
|
+
| 构建 | tsdown (rolldown) |
|
|
183
|
+
| 测试 | Vitest 3 + Playwright 1.62 |
|
|
184
|
+
| Lint | oxlint |
|
|
185
|
+
| 包管理 | pnpm 9 |
|
|
186
|
+
|
|
187
|
+
### 常用命令
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
pnpm run build # 完整构建（host + client）
|
|
191
|
+
pnpm run build:client # 仅构建 client bundle
|
|
192
|
+
pnpm run dev # 启动 dev server
|
|
193
|
+
pnpm run test # 单元测试
|
|
194
|
+
pnpm run test:e2e # E2E 测试
|
|
195
|
+
pnpm run typecheck # 三面类型检查
|
|
196
|
+
pnpm run lint # Lint
|
|
197
|
+
pnpm run lint:fix # Lint 自动修复
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### CI/CD
|
|
201
|
+
|
|
202
|
+
项目使用两个独立的 GitHub Actions 工作流：
|
|
203
|
+
|
|
204
|
+
| 工作流 | 文件 | 触发条件 | 职责 |
|
|
205
|
+
|--------|------|----------|------|
|
|
206
|
+
| CI | `ci.yml` | push/PR to master | lint + typecheck + test + build |
|
|
207
|
+
| Release | `release.yml` | push tag `v*` | build + GitHub Release + npm publish |
|
|
208
|
+
|
|
209
|
+
### 测试覆盖
|
|
210
|
+
|
|
211
|
+
- **320 单元测试** — 覆盖 adapters, tools, plugin, graphStore, validators, i18n, logger, pathSecurity, services, deriveName
|
|
212
|
+
- **53 E2E 测试** — 覆盖 J1-J14 用户旅程（5 个 skip 为 dev mode 不支持的功能）
|
|
213
|
+
|
|
214
|
+
## 许可证
|
|
215
|
+
|
|
216
|
+
[MIT](LICENSE)
|
|
217
|
+
|
|
218
|
+
## 致谢
|
|
219
|
+
|
|
220
|
+
- [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh) — Agent 运行时框架
|
|
221
|
+
- [Cytoscape.js](https://cytoscape.org/) — 图可视化引擎
|
|
222
|
+
- [dsh-codegraph](https://github.com/jiangzhenguo/dsh-codegraph) — CodeGraph CLI 数据源
|
|
223
|
+
- [dsh-tool-lens](https://github.com/trench-xinxin/dsh-tool-lens) — AST 代码图谱数据源
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# CodeGraph Visualizer bundle patch
|
|
2
|
+
# Applied after dsh-base and dsh-web-app layers; inserts this plugin as a
|
|
3
|
+
# host-plane row so its graph_* tools register into the global `tools` registry.
|
|
4
|
+
# Config is explicit (red line 9) — all fields below match DEFAULT_CONFIG in
|
|
5
|
+
# src/index.ts; misconfigured values fail loud at load.
|
|
6
|
+
- insert:
|
|
7
|
+
- id: codegraph-visualizer
|
|
8
|
+
name: dsh-codegraph-visualizer
|
|
9
|
+
config:
|
|
10
|
+
dataSource: auto
|
|
11
|
+
requestTimeout: 5000
|
|
12
|
+
scanCacheTtl: 30000
|
|
13
|
+
scanCacheLimit: 4
|
|
14
|
+
maxBodyBytes: 1048576
|
|
15
|
+
prerequisiteRetryDelay: 3000
|
|
16
|
+
watchDebounce: 500
|
|
17
|
+
maxNodes: 10000
|