dsh-github-search

Readme

# dsh-github-search

> **English overview** — full 中文说明 below.

A GitHub console plugin for the [DeepSeek Harness](https://github.com/ttb-eng/dsh-github-search) Web sidebar. It closes the loop — *search → browse README → judge fit → clone → hand to the agent → keep history* — inside one panel.

**Features** — repository & code search · inline README (sandboxed iframe) · one-click clone (git → zip fallback) · feed the agent (analyze / run / summarize / integrate / custom) · agent verdict against your workspace + the repo's README · post-judge clone (global vs per-project, path picker) · history (downloaded / browsed / judged) · Star / Fork · my stars · discover page · token config.

**Install**

```bash
dsh plugin --profile web add <this-directory>
dsh web
```

**Architecture** — host (`lib/index.js`, ESM bundle: slash commands + a host-side model call for the judge) ↔ client (`lib/client.js`, browser bundle: UI injected into `sidebar.footer.action` + `shell.overlay`). The client drives the host through `remote.commands.execute`. See [`PITFALLS.md`](./PITFALLS.md) for the integration gotchas.

---

DeepSeek Harness（DSH）Web 侧边栏的 GitHub 操作台插件。把「搜仓库 → 看 README → 判断合不合适 → 拉取到本地 → 交给 agent 干活 → 记一笔」这条链闭合在一个面板里。

> 定位：这是**给人用的操作台**，不是给 agent 加搜索能力（agent 自己本来就能搜 GitHub）。它的价值在于把散落在浏览器、终端、对话框里的动作收敛成一条顺手的闭环。

## 功能

- **搜索**：搜仓库（名称/描述，可加语言、排序、README 范围）；搜代码（走宿主端，绕过浏览器 CORS）。
- **浏览**：在卡片内直接渲染 README（iframe 沙箱隔离，防恶意 HTML），并拉取 stars/forks/issues/语言/协议/更新时间。
- **一键 Clone**：选盘符/工作区 + 可选子目录；git 失败自动降级 zip 下载（`tar --strip-components=1`）。
- **喂给 agent**：clone 后一键让 agent「分析 / 跑起来 / 总结 / 集成到当前项目 / 讲用法」，或输入自定义指令。
- **agent 判断**：让模型结合**当前工作区 + 仓库 README 摘要**中肯判断这个仓库适不适合你，结果直接回卡片（宿主端跑模型，不污染聊天）。
- **判断后一键 Clone**：全局（共享工具目录）/ 独立（仅当前项目）两种范围，都能自选路径。
- **历史记录**：三个标签页——**下载过 / 浏览过 / 判断过**，均持久化到 localStorage。
- **Star / Fork**：白底黑字按钮，缺 token 时引导去设置。
- **我 Star 过**：列出当前 token 的 Star 列表。
- **发现页**：本周新星、近期热门。
- **Token 配置**：支持配置 Personal Access Token，提升速率上限、解锁代码搜索 / Star / Fork。

## 安装

```bash
# 在 DSH 中把本插件链接进 web 配置文件（symlink，改源码只需重启）
dsh plugin --profile web add <本目录路径>

# 重启 web 后生效
dsh web
```

依赖：Node 22+、系统 `git` 与 `tar`（zip 降级用）、可选 `curl`。

## 使用

1. 打开 DSH Web，左侧边栏点 **GitHub 搜索**（或 `GH`）。
2. 输入关键词回车搜索；切换「类型」可搜代码（需先配 token）。
3. 点「浏览」看 README；点「下载」选盘符 + 子目录克隆。
4. 点「让 agent 判断」一键开判，结果直接显示在卡片里；合适就点「一键 clone」选全局/独立 + 路径。
5. 顶部导航：发现 / 历史记录 / 我 Star 过 / 设置。

## 目录结构

```
dsh-github-search/
├── package.json          # bundle 元信息 + dsh.bundle.patch + dsh.client(web)
├── cordis.patch.yml      # 插入插件行
└── lib/
    ├── index.js          # 宿主端：命令 + 判断用的模型调用
    └── client.js         # 浏览器端：全部 UI 与交互
```

## 架构

### 宿主端（`lib/index.js`）

ESM，导出 `{ name, inject, apply(ctx) }`。注册了这些斜杠命令，供客户端通过命令通道调用：

| 命令 | 入参(JSON) | 作用 |
|---|---|---|
| `ghclone` | `{url, dir}` | 克隆（git → zip 降级），返回摘要 |
| `ghrm` | `{dir}` | 删除本地仓库目录（带安全校验） |
| `ghcodesearch` | `{query, page, token}` | 代码搜索（绕 CORS） |
| `ghstar` / `ghfork` | `{full_name, token}` | 收藏 / Fork |
| `ghworkspace` | `{dir}` | 判断目录是否代码项目 |
| `ghopen` | `{dir}` | 系统文件管理器打开目录 |
| `ghjudge` | `{full_name, description, language, stars, cwd, token}` | 跑模型做仓库判断 |
| `ghstarred` | `{token}` | 列出当前 token 的 Star |

判断（`ghjudge`）直接调用会话自己的模型：通过 `ctx.get('llm')` 拿 LLM 运行时，用 `invocation.agent.options.provider/model` 确定模型，流式收集正文，**不写入会话日志**（所以不会在聊天里出现一条用户消息 + 长篇回复）。

### 浏览器端（`lib/client.js`）

通过 `window.__ModuleLoader__.load({ id, factory })` 注册，`exports.inject` + `exports.apply`。注入两个槽：

- `sidebar.footer.action` → 侧边栏入口按钮
- `shell.overlay` → 面板本体

与宿主通信走 `ctx.get('remote.commands').execute(sessionId, '/cmd ' + JSON.stringify(args))`。

## 说明

- 判断结果、浏览记录、克隆记录都持久化在 `localStorage`（key：`dsh-github-search-history` / `dsh-github-search-token`）。
- 未配 token 时 GitHub 搜索限速约 10 次/分钟，配 token 后 30 次/分钟。

踩过的坑见 [`PITFALLS.md`](./PITFALLS.md)。