# @wangjunjian/dsh-github-trending

中文 | [English](README.md)

一个 DeepSeek Harness bundle 插件：暴露一个基于 https://github.com/trending
的 `github_trending` 工具，并在 `web` profile 中提供一个右侧趋势面板。

## 功能

插件注册了一个面向模型的工具 `github_trending`：抓取公开的 GitHub
Trending 页面（按语言和时间窗口），返回结构化的热门仓库列表。

每条结果包含：

- `rank` — 页面上的排名（从 1 开始）
- `owner` / `name` / `fullName`
- `url` — 仓库的完整 GitHub URL
- `description` — 仓库简介
- `language` — 主要编程语言
- `stars` — 总 star 数
- `forks` — fork 数
- `starsToday` — 今天（或本周/本月）新增的 star 数

在 `web` profile 下，插件还会在浏览器 UI 右侧渲染一个可停靠的趋势面板
（daily/weekly/monthly 标签页、可拖拽调宽、可折叠为窄条），数据来自宿主侧
内存缓存，通过 `/github-trending` HTTP 路由提供。

## 安装

将插件安装到某个 DeepSeek Harness profile，不会修改 `deepseek-harness`
仓库本身：

```sh
# 从本地检出目录安装
dsh plugin --profile headless add /Users/junjian/GitHub/wang-junjian/dsh-github-trending

# 或从 npm registry 安装
dsh plugin --profile headless add @wangjunjian/dsh-github-trending
```

使用 `--profile web` 可同时获得浏览器 UI 中的趋势面板。安装后 bundle 会
自动追加到 `dsh.profile.bundles`。

## 使用

直接向 agent 提问即可：

```text
列出今天 trending 的 Python 仓库。
```

### 工具参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `language` | `string` | 否 | 语言过滤，如 `python`、`typescript`、`go`。 |
| `since` | `string` | 否 | `daily`（默认）、`weekly` 或 `monthly`。 |
| `maxResults` | `integer` | 否 | 返回的仓库数量上限（默认 10，硬上限 25）。 |

### Cordis 配置

bundle patch 默认插入一行配置。可在 profile 的 `cordis.patch.yml` 中覆盖：

```yaml
- id: github-trending
  config:
    enabled: true
    timeoutMs: 30000
    maxResults: 10
    refreshIntervalMs: 14400000
```

| 字段 | 默认值 | 说明 |
|---|---|---|
| `enabled` | `true` | 是否注册工具、缓存与 web 路由。 |
| `timeoutMs` | `30000` | 每次 HTTP 请求的协作式超时预算（毫秒）。 |
| `maxResults` | `10` | 工具返回仓库数上限（最大会被钳制到 25）。 |
| `refreshIntervalMs` | `14400000` | UI 缓存的后台刷新间隔（毫秒，4 小时）。 |

## 开发

```sh
pnpm install           # 安装依赖（pnpm 10；prepare 钩子会自动构建）
pnpm run build         # tsc -b tsconfig.json && tsdown
pnpm run test          # vitest run
pnpm run typecheck     # tsc --noEmit
pnpm run lint          # biome check .
pnpm run lint:fix      # biome check --write .
```

`scripts/screenshot_test.py` 是手工开发辅助脚本：用本地 Playwright 驱动
浏览器访问 `http://127.0.0.1:3080` 截取 web 面板效果图；它不属于测试套件，
需要本地安装 Playwright。

## 已知限制

- GitHub Trending 没有官方 API。解析器针对当前服务端渲染的 HTML 结构，
  GitHub 改动页面标记时可能需要更新。
- 未认证的请求受 GitHub IP 级速率限制约束。
- 插件直接请求 GitHub，而不是通过 `ctx.web`，因此不继承 harness web
  能力的抓取策略。
- 面板通过 `shell.overlay` 浮于应用之上；DSH 目前尚无原生右侧栏插槽。