@dsh-external/dsh-sitemap

Readme

# dsh-sitemap

> DeepSeek Harness（DSH）站点地图插件 · 把 Yakit 的站点地图交互搬进 DSH

在 DSH 侧边栏一键打开「站点地图」：按主机树形组织工作区侦察到的接口，每个站点有专属配色，支持搜索、接口详情（方法 / 参数 / 出现次数 / 来源）、一键复制 curl；还带一个 Cookie 保险库——导入浏览器导出的 cookie 后自动标注哪些站点能带着身份访问，src 工作流可以直接自取 cookie 注入浏览器测试。

---

## 设计来源

Yakit 里的「站点地图」我觉得做得很好，就借鉴了它的交互：把发现的所有接口按主机自动归类，形成一棵可展开、可搜索的树：

```
hosts
└── account.example.com
    └── /user/webrest/v1/login.do
```

做资产梳理和接口测试时，这棵树比零散的请求记录直观得多。本插件把同样的体验带到 DSH，并且补了两个 Yakit 没有的东西：**每个站点一种颜色**（一眼分清目标），和**cookie 覆盖标注**（哪些站点能直接以已登录身份访问，不用再猜）。

## 特性

- 🗺 **侧边栏入口**：点击「站点地图」打开应用内全屏地图（中 / 英双语）
- 🎨 **站点配色**：每个主机名哈希到 14 色盘里的一种，主机圆点、接口选中色统一
- 🌲 **主机树**：主机 → 接口路径两级树，可折叠、显示统计
- 🔍 **实时搜索**：按主机名 / 接口路径过滤
- 📋 **接口详情**：方法、参数、出现次数、来源文件；一键复制 curl、新窗口打开
- ♻️ **重新生成**：从工作区侦察文件全量覆盖合成 `sitemap_data.json`——历史残留站点一次清空
- 🗑 **清除**：站点树上每个主机可单独删除；顶部「清空」一键删掉整张地图
- 🍪 **Cookie 保险库**：导入 Cookie-Editor 的 JSON / Header String / Netscape 三种格式，按域名自动匹配并给站点打「🍪 n」标注，详情页可一键复制该站点的 Cookie header
- 🛠 **src 工作流工具**：`sitemap_query` / `sitemap_cookie` / `sitemap_regen` / `sitemap_import_cookie` 四个 agent 工具，工作流自己取数、取 cookie，不用用户复制粘贴

## 使用方法

### 站点地图

1. 侧边栏底部点击「🗺 站点地图」打开地图
2. 第一次打开时点「**重新生成**」：插件扫描工作区侦察文件，全量合成 `sitemap_data.json`
3. 右侧「刷新」随时重新读取；「清空」删除整张地图；悬停主机点 🗑 删除单个站点

**数据从哪来？** 点「重新生成」时插件扫描工作区根目录下这些侦察文件（没找到的自动跳过）：

| 文件 | 投进去什么 |
| --- | --- |
| `all_host_apis.json` | 主机 → 接口路径列表 |
| `urls_by_host.json` / `cvp_urls_by_host.json` | 主机 → 完整 URL（自动取 host + path） |
| `hll_apis.json` | 纯路径数组（挂到名为 `hll` 的虚拟主机下） |
| `sdp_apis.json` | `{path, method, count}` 对象数组（挂到 `sdp` 下） |

**什么时候触发？** 「重新生成」和「刷新」都是点一下拉一次，无缓存；生成器会**覆盖写**输出文件，所以老站点会随之消失。文件不存在时弹窗显示空状态。生成 / 删除后无需重启 DSH。

### Cookie 保险库

1. 在真实浏览器用 Cookie-Editor 扩展导出目标站点的 cookie（JSON 或 Header String，Netscape 也行）
2. 站点地图弹窗右上角「🍪 保险库」→ 粘贴 → 导入（Header 形式记得填「适用域名」）
3. 导入后插件按域名匹配：地图上覆盖到的站点会挂 `🍪 n` 角标，接口详情页列出匹配的 cookie，点一下复制 Cookie header
4. cookie 存在工作区 `dsh-sitemap-cookies.json`（跟 `sitemap_data.json` 同目录），**不进插件仓库、不上传 GitHub**

### src 工作流怎么用

插件加载后，SRC 会话的 agent 自动获得四个工具，典型开场：

1. `sitemap_regen` — 用工作区侦察文件刷新资产底图
2. `sitemap_query` — 查主机 / 接口，挑测试目标
3. `sitemap_cookie host=目标域名` — 取该站点的 Cookie header 与明细
4. `browser_add_cookies`（dsh-tool-playwright 提供的工具）写入共享浏览器 → `browser_navigate` 访问目标，即带着身份测试

第 3 步的工具返回里带完整注入指引，agent 照着做即可，全程不用在对话里贴 cookie。

> 浏览器注入依赖本机的 `dsh-tool-playwright` 带 `browser_add_cookies` 工具。如果你装的版本没有这个工具，就退化成手动粘贴 header（保险库仍负责匹配与标注）。

## 实现原理

### 整体架构：双半区

DSH 插件分两个半区运行，本插件亦是如此：

| 半区 | 文件 | 运行环境 | 职责 |
| --- | --- | --- | --- |
| 宿主半区 | `src/index.ts`、`src/collect.ts`、`src/cookies.ts` | Node 侧（cordis 插件） | webServer 路由 + Cookie 保险库 + 四个 agent 工具 |
| 浏览器半区 | `src/client/index.tsx` | 浏览器侧（React） | 侧边栏入口 + 树形地图弹窗 + 保险库弹窗 |

### 宿主半区

宿主半区注册 webServer 路由与 agent 工具：

- `GET /dsh-sitemap/data` → 读工作区 `sitemap_data.json`
- `POST /dsh-sitemap/regen` → 扫描工作区侦察文件，**全量覆盖**写回 `sitemap_data.json`（历史站点即清）
- `POST /dsh-sitemap/clear` → 删除整张地图；`POST /dsh-sitemap/host-remove` → 删除单个主机
- `GET /dsh-sitemap/cookies` → 保险库列表 + 站点覆盖映射
- `POST /dsh-sitemap/cookies-import` / `cookies-clear` → 导入 / 清空

agent 工具（`ctx.tools.register`）：

- `sitemap_query`：主机 / 路径过滤查询站点地图
- `sitemap_cookie`：按主机返回 Cookie header + 明细 + 注入指引
- `sitemap_regen`：命令行触发重新生成（返回来源统计）
- `sitemap_import_cookie`：工作流内直接导入 cookie（自动识别 JSON / Header / Netscape）

文件访问全部限制在工作区数据目录内。cookie 三种格式的解析在 `src/cookies.ts`，域名匹配规则：cookie 的 domain 等于站点或站点是其子域即命中，`hostOnly` 的 cookie 只认自己的主机。

### 浏览器半区

- 通过 `ctx.locale.register()` 注册 `sitemap` 命名空间的 `zh` / `en` 文案
- 通过 `ctx.slots.inject('sidebar.footer.action', ...)` 注入侧边栏「站点地图」按钮
- 弹窗加载时并行拉取地图与保险库，主机配色由 `hash(主机名) → 14 色盘` 决定，选中的接口用同色描边
- 重新生成 / 清空 / 删站点 / 导入 cookie 都走宿主路由，成功后本地状态即时更新

### 数据流

```mermaid
flowchart LR
    A["工作区侦察文件<br/>all_host_apis.json 等"] -->|"regen 全量覆盖"| B["sitemap_data.json"]
    C["Cookie-Editor 导出"] -->|"粘贴导入"| D["dsh-sitemap-cookies.json"]
    B -->|"GET /data"| E["树形地图（按站点配色）"]
    D -->|"域名匹配"| E
    B -->|"sitemap_query"| F["src 工作流 agent"]
    D -->|"sitemap_cookie"| F
    F -->|"browser_add_cookies"| G["共享浏览器<br/>带着身份测试"]
```

### 构建与分发

- `scripts/build.mjs` 用 esbuild 打两套产物：
  - `lib/index.js`：宿主 ESM 包，`@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` 设为 external（宿主提供）
  - `lib/client.js`：浏览器包，用 `window.__ModuleLoader__.load({ id, factory })` 包装成 DSH 模块加载器格式；`@deepseek-ai/*` 与 `react` 全部 external
- `package.json` 声明 `dsh.bundle.patch`（`cordis.patch.yml`），宿主半区以 bundle patch 挂载
- `dsh.plugin.json` 声明宿主插件清单（id / version / client 注入依赖 / 四个工具 contributions），`lib/` 产物随仓库提交，clone 即用

## 数据格式

站点地图文件默认在工作区根目录 `sitemap_data.json`（可用 `dataDir` 配置子目录），结构为「主机 → 接口路径 → 元信息」：

```json
{
  "api.example.com": {
    "endpoints": {
      "/v1/login": { "methods": ["POST"], "count": 3, "params": ["account", "password"], "sources": ["all_host_apis.json"] }
    }
  }
}
```

cookie 保险库 `dsh-sitemap-cookies.json` 与地图同目录：

```json
{
  "version": 1,
  "updatedAt": "2026-08-21T12:00:00.000Z",
  "cookies": [
    { "name": "sid", "value": "…", "domain": "example.com", "hostOnly": false, "path": "/", "secure": true, "httpOnly": true, "source": "json", "addedAt": "…" }
  ]
}
```

可运行示例见 [`examples/sample-data.json`](examples/sample-data.json)。示例使用占位域名，**仓库内不包含任何真实站点数据或 cookie**。

## 安装

1. 将本仓库复制到 DSH 的插件目录：

   ```bash
   git clone https://github.com/deCOLE118/dsh-sitemap.git <DSH插件目录>/dsh-sitemap
   ```

2. `lib/` 构建产物已随仓库提交，可直接使用；如需重新构建：

   ```bash
   npm install
   npm run build
   ```

3. 重启 DSH（宿主半区新增了路由和工具，必须重启才会加载），浏览器 **Ctrl+F5** 硬刷新，侧边栏底部即可看到「🗺 站点地图」入口。

本插件是标准的 **bundle 类型**插件：`package.json` 声明了 `dsh.bundle.patch`（`cordis.patch.yml`），社区安装器（如 find-plugins）可直接识别装法并挂载宿主半区。

## 配置

插件接受以下配置（宿主加载插件时传入）：

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `workspace` | `string` | `$DSH_WORKSPACE` 或当前工作目录 | 工作区根目录（绝对路径） |
| `dataDir` | `string` | 工作区根目录 | 存放地图与 cookie 保险库的子目录 |
| `sources` | `SourceSpec[]` | 表格里的五个默认文件 | 「重新生成」扫描的侦察文件；`{file, type}`，type 取值 `host-path` / `host-urls` / `paths` / `path-objects` / `sitemap`，纯路径类可加 `host` 指定挂载名 |

## 开发

```bash
npm install        # 安装依赖（仅 esbuild / typescript / react）
npm run build      # 构建 lib/（宿主 + 浏览器两套产物）
```

> 类型说明：`@deepseek-ai/dsh-client-*` 与 `@deepseek-ai/dsh-tools` 类型由 DSH 宿主提供，未随本仓库安装；在 DSH 源码目录（monorepo）下开发可获得完整类型提示，单独构建本仓库不受影响（类型/外部依赖会被 esbuild 按 external 擦除）。

目录结构：

```
dsh-sitemap/
├── dsh.plugin.json        # 宿主插件清单（id / version / client inject / tools）
├── cordis.patch.yml       # bundle 声明（宿主半区挂载）
├── src/
│   ├── index.ts           # 宿主半区：webServer 路由 + agent 工具注册
│   ├── collect.ts         # 重新生成：扫描侦察文件全量覆盖合成
│   ├── cookies.ts         # Cookie 保险库：三种格式解析 + 域名匹配
│   └── client/index.tsx   # 浏览器半区：侧边栏入口 + 树形地图弹窗 + 保险库弹窗
├── scripts/build.mjs      # esbuild 构建脚本
├── lib/                   # 构建产物（随仓库提交）
└── examples/              # 示例数据（占位域名）
```

## 免责声明

本插件仅用于**已获授权**的安全测试与资产梳理。请遵守目标系统的授权范围与当地法律法规，使用者需对自身行为负责。

## 许可证

[BSD-3-Clause](LICENSE) © 2026 deCOLE118