@czj-git/dsh-plugin-hub

Readme

# DSH Plugin Hub 插件

[English](https://github.com/czj-git/dsh-plugin-hub/blob/main/README.en.md) | 中文

在 DeepSeek Harness 里找插件、看榜单、管理安装，不用离开当前工作区。「设置 → 插件中心」提供插件市场、已安装、排行榜和任务四个标签：发现插件，审阅安装计划，再跟踪执行结果。也可以直接在对话中让 Agent 搜索插件、查询本机清单和任务状态。

本插件连接 [DSH Plugin Hub](https://dshpluginhub.dev) 的公开、只读目录 API，提供已发布且通过验证的社区插件信息、安装命令、兼容性、社区指标和来源链接。设置页面和对话工具同时保留，不需要打开市场网页才能搜索；安装、更新和卸载则在本机审阅并确认后执行。

[安装](#安装与启动) · [设置内浏览](#settings-插件中心) · [对话搜索](#在对话中搜索插件) · [工具输入](#工具输入) · [返回字段](#工具输出) · [配置](#配置)

## 能做什么

| 入口 | 用法 | 可以看到什么 |
|---|---|---|
| 设置 · 插件市场 | 按关键词、分类和分页浏览 | 插件卡片、兼容性与本机状态；安装或更新前先审阅计划，兼容性待确认时显示提示。 |
| 设置 · 已安装 | 读取当前 Harness profile | 本机依赖、实际版本、来源、bundle 状态、目录版本，以及单项或批量更新和卸载入口。 |
| 设置 · 排行榜 | 切换日增长、Star 总榜、最新上架或最近活跃 | 带排名和对应指标的插件列表，支持分类筛选。 |
| 设置 · 任务 | 跟踪当前 profile 的生命周期队列 | 排队、校验、执行、核对与最终状态；支持取消、重试、脱敏日志和重启提示。 |
| 对话 · `dsh_plugin_search` | 告诉 Agent 想找的功能、插件名、仓库或作者 | 搜索结果、安装命令和来源链接。 |
| 对话 · `dsh_plugin_rankings` | 让 Agent 查询指定榜单 | 排行结果、安装命令和来源链接。 |
| 对话 · `dsh_plugin_installed` | 查询本机已声明的插件 | 包名、版本、来源和启用状态，不执行安装或修改。 |
| 对话 · `dsh_plugin_task_status` | 查询本机安装、更新与卸载任务 | 任务状态、失败原因和重启要求，不返回原始日志或执行参数。 |

- 支持中文和英文描述；对话搜索工具还可按分类、运行形态、安装来源、排序和分页筛选。
- Native 模式向模型返回紧凑、便于后续操作的文本；PTC 模式（早期版本名为 Code Mode）返回完整结构化结果。
- 校验公网 API 的每个返回字段，并暴露分页、数据更新时间和匿名限流信息。
- 支持 Harness 取消信号、可配置超时、429 重试信息和稳定的错误分类。

公网目录访问只调用 `GET /api/v1/plugins/search` 和 `GET /api/v1/plugins/{owner}/{repo}`，不需要 API Key。已安装页在本机读取配置中的 profile；当依赖能关联公开 GitHub 仓库时，只发送 owner/repo 查询目录版本，不上传 package spec、profile 内容或文件系统路径。只有用户在设置页审阅并确认结构化计划后，本机任务队列才调用官方 `dsh plugin --profile ...` CLI 修改该 profile。

## 安装与启动

需要已安装的 DeepSeek Harness，以及 Node.js `^22.19.0 || >=24.0.0`。设置页需要 Web profile 的客户端扩展支持；在不提供 Web 客户端的环境中，设置页不会出现。插件检索无需额外 API Key；在对话中使用仍需要 Harness 已配置可用的模型。

从 npm 安装到 Web profile：

```sh
dsh plugin --profile web add @czj-git/dsh-plugin-hub
```

检查最终组合并启动：

```sh
dsh --profile web --dump-config
dsh --profile web
```

启动后可以打开「设置 → 插件中心」，也可以直接使用下面的[对话示例](#在对话中搜索插件)。如果已经运行 Harness，安装或更新插件后重新启动，再刷新页面。

### Harness 版本与认证

开发依赖对齐 `0.1.2-rc.1` SDK，客户端使用 Cordis Context 和独立的 UI renderer，不再依赖已移除的 `dsh-client-runtime`。peer 范围显式包含 `0.1.0-rc.7`、`0.1.1-rc.2` 和 `0.1.2-alpha.5` 起的预发布版本。`npm test` 会通过真实 Harness 工具注册表验证搜索与排行榜的输出，包括新增安全信息、兼容范围、可空值和旧 API 的缺省字段。

新版 Web profile 需要浏览器认证时，请使用 `dsh web` 在终端打印的启动地址；不要把其中的令牌发给网站或其他人。仅打开不带认证信息的本地地址可能返回 401。网站跳转的操作方式见下方说明。

## Settings 插件中心

启动 Web profile 后，打开 Harness 的「设置」，左侧会出现「插件中心」。这个页面采用 Harness 原生 Settings 布局和主题变量，随 Harness 的中英文语言切换，不会嵌入外部网页。切换语言后，市场和排行榜会按当前语言重新查询，简介、详情链接及日期格式同步更新，无需刷新页面；旧语言的未完成请求会被取消。

[插件市场](#插件市场) · [已安装](#已安装) · [排行榜](#排行榜) · [任务中心](#任务中心)

### 插件市场

![Harness 深色插件市场：四个标签、搜索分类、已安装状态和查看安装计划按钮](https://raw.githubusercontent.com/czj-git/dsh-plugin-hub/main/docs/screenshots/settings-marketplace-zh.png)

*在市场中直接区分已安装插件与待安装插件。黄色「查看安装计划」表示兼容性仍需确认，不是安装失败。*

- 默认按 GitHub Stars 展示已发布且通过验证的插件；输入关键词后切换为相关性排序。
- 支持九个市场分类和分页；分类标签自动换行、完整展示，桌面端使用两列紧凑卡片，窄窗口自动改为单列。
- 每张卡片展示插件名、作者、简介、验证状态、分类、Stars、浏览量、安装来源和主要语言。
- 主按钮结合本机清单和兼容性显示「安装」「更新」「已安装」或「不兼容」；兼容性未知时显示黄色「查看安装计划」或「查看更新计划」。已确认不兼容的插件不能从卡片安装。
- 安装和更新入口先打开计划确认面板，展示来源、版本、兼容性与风险提示；只有明确确认后才创建任务，点击卡片不会立即修改 profile。
- 插件名和详情箭头会在浏览器中打开 DSH Plugin Hub 的公开详情页。

### 已安装

![Harness 深色已安装页：当前 profile、本机版本、来源、目录版本、启用状态与卸载入口](https://raw.githubusercontent.com/czj-git/dsh-plugin-hub/main/docs/screenshots/settings-installed-zh.png)

*查看当前 profile 真正安装了什么。本机版本与目录版本分开展示；截图中的 LOCAL 是开发时的本地来源，日常安装使用上方 npm 命令即可。*

「已安装」页从当前 profile 的 `package.json`、实际依赖版本和 `dsh.profile.bundles` 读取本机状态，不从官网反向推测：

- 区分依赖声明、实际安装版本和 bundle 是否已经进入 profile layer。
- 标记 npm、GitHub、本地或未知来源，并识别安装缺失与未启用状态。
- 对能关联到官网目录的插件按语义版本判断“已是目录版本”或可更新；无法安全比较的版本不会被误称为升级。
- 官网明确返回 404 才标记“目录未收录”；网络错误显示“目录暂不可用”，不会影响本机状态。
- profile 尚未初始化或没有外部插件时显示明确空状态；本机 inventory 无需联网。
- 本机路由不开放 CORS，响应不包含文件系统路径；有新版时「已安装」标签会显示数量，并可审阅单项或全部更新计划。
- 批量更新先逐项重新校验目录详情，再把固定来源、目标版本、标准化操作、兼容性和构建授权提示汇总到一个确认窗口；一次确认后才按顺序加入串行任务队列。
- 每个已声明依赖都可进入卸载确认；批量排队中途失败时会明确显示已加入队列的数量，避免盲目重复提交。

### 排行榜

![Harness 深色排行榜：日增长榜、分类筛选、Star 增量与数据更新时间](https://raw.githubusercontent.com/czj-git/dsh-plugin-hub/main/docs/screenshots/settings-rankings-zh.png)

*日增长榜展示最近两个成功指标快照之间的 Star 变化；右侧增量与顶部更新时间帮助判断近期趋势。*

- `日增长`：最近两个成功指标快照之间的 GitHub Star 变化；缺少基线时显示“待生成”。
- `Star 总榜`：按 GitHub Stars 总数排序。
- `最新上架`：按 DSH Plugin Hub 首次收录时间排序。
- `最近活跃`：按 GitHub 最近推送时间排序。
- 排行榜采用单列信息行，保留排名、头像、作者、简介、分类、验证状态和当前榜单指标，并支持分类筛选和分页。

### 任务中心

![Harness 深色任务中心：安装任务已完成、固定版本命令、重启提醒和脱敏日志入口](https://raw.githubusercontent.com/czj-git/dsh-plugin-hub/main/docs/screenshots/settings-tasks-zh.png)

*「已完成」表示 CLI 执行和磁盘状态核对成功，不代表当前进程已经加载新插件。黄色提示要求重启 Harness 后生效，不是安装报错；展开「查看脱敏日志」可检查执行记录。*

安装、更新和卸载都分成“预览计划”和“确认创建任务”两步。确认面板显示 profile、包名、固定来源和版本、标准化 CLI 参数、兼容性、构建脚本授权、权限、外部服务、遥测、风险标记及重启要求。

- 浏览器只能提交结构化的 operation、profile、owner/repo、packageName，以及高级安装需要的精确 version 或 ref，不能提交 shell 命令；Host 会重新读取目录或来源元数据和本机状态并构造固定 argv。
- 提交确认时再次解析目录数据，并校验用户刚刚审阅的计划指纹；计划发生变化时拒绝创建任务，要求重新确认。
- 同一 profile 串行执行任务，同一包不能同时存在两个活动任务；任务状态为排队、校验、执行、核对、成功、失败、取消或中断。
- 运行中的 POSIX 任务可安全终止进程组；失败和中断任务可重试。任务日志会去除 ANSI 控制符、凭据、token 和私有主目录路径。
- 成功只以 CLI 返回码和重新读取后的真实 profile 状态共同判定。磁盘更新后仍需重启 Harness 才会加载新插件实例。
- 失败任务会链接到 DSH Plugin Hub 的中英文构建授权或故障排查指南，便于按错误类型继续处理。

截图中的插件数量、排名、版本和任务记录仅代表拍摄时的状态。中英文截图分别拍摄，本机已安装数量也可能不同。

### 高级安装

已安装页提供高级安装入口：输入 npm 包名和精确版本，或公开 GitHub 仓库及分支、标签、提交引用。Host 先查询来源元数据，并将 GitHub 引用解析为不可变的提交 SHA，再展示计划供确认。目录外来源会明确标为未验证，不把存在 package.json 当作兼容性保证；私有来源和任意 shell 命令不受支持。

### 从网站继续到 Harness

DSH Plugin Hub 的插件详情页和安装指南通过「在 Harness 中打开」进入默认本地 Web 地址 `http://127.0.0.1:3080/api/dsh-plugin-hub/open`。在本地中转页点击「继续前往 Harness」后进入插件中心。详情页链接只携带 `owner/repo` 和可选显示语言，通用指南只请求打开 Plugin Hub 设置页，不携带安装命令、版本、来源或登录令牌。此中转页需要本插件 `0.4.0` 或更新版本；旧版插件需先更新并重启 Harness。

若中转页提示需要登录，请在同一浏览器的新标签页打开 `dsh web` 在终端打印的启动地址，然后回到中转页继续。不要把启动令牌拼进网站链接；原来的插件选择留在中转页，不受登录重定向清理查询参数的影响。中转页不创建登录 Cookie、不读取凭据，也不改变 Harness 的认证设置。

- 插件只接受严格的仓库标识或固定设置页标识；重复参数、多余路径、空白和命令式内容会在调用预览接口前被拒绝。
- 深链接只使用一次，随后从地址栏移除，同时保留其他查询参数和 URL 片段。
- 对合法仓库，本机 Host 会重新获取目录详情，验证精确包名、来源、目标版本和 Harness 兼容性，再显示现有的结构化确认窗口。
- 打开链接不会自动安装，也不会绕过构建脚本授权或生命周期任务确认。只有用户在 Harness 内明确确认后，任务才会进入本机队列。

## 在对话中搜索插件

设置页面不是唯一入口。插件启用后，Agent 仍可调用 `dsh_plugin_search` 和 `dsh_plugin_rankings`；不必先打开设置，也不需要手写 JSON。下面任选一句发送到 Harness 对话中：

搜索具体功能：

```text
用 DSH Plugin Hub 搜索 memory 相关插件，选出最多 5 个，用中文说明用途，并给出安装命令和详情链接。不要执行安装。
```

查询排行榜：

```text
用 DSH Plugin Hub 查看 Star 最多的前 10 个插件，用中文介绍，并附上详情链接。
```

发现新插件：

```text
用 DSH Plugin Hub 查看最近新上架的 5 个插件，说明用途，并给出安装命令。
```

查看本机状态：

```text
用 DSH Plugin Hub 查看当前 profile 的已安装插件和最近任务，告诉我哪些已生效、哪些还需要重启。如果有失败任务，说明原因。不要修改配置或执行安装。
```

本机查询分别使用 `dsh_plugin_installed` 和 `dsh_plugin_task_status`，只读取状态，不创建安装任务。

![Harness 深色对话中的 Memory 插件搜索结果，包含用途、安装命令和详情链接](https://raw.githubusercontent.com/czj-git/dsh-plugin-hub/main/docs/screenshots/chat-search-zh.png)

*对话搜索示例：让 Agent 查找 memory 相关插件，并整理用途、安装命令和详情链接。*

模型负责决定是否调用工具和如何组织回答。若没有触发，可以明确说「请调用 `dsh_plugin_search`，用 `memory` 作为关键词，`locale` 设为 `zh`」。搜索基于关键词匹配；没有结果时，可以换一个更短的中英文关键词或减少筛选条件。

工具返回的安装命令只是文本，不会直接修改 profile。执行安装仍需另行请求，并遵循 Harness 的权限与审批策略。Native 模式的紧凑结果不展示所有兼容性和时间字段；需要这些细节时，可使用 PTC 模式（早期版本名为 Code Mode）读取[完整结构化结果](#工具输出)。

## 工作方式

```mermaid
flowchart TD
    website["网站：详情 / 安装指南"] --> deeplink["仅仓库标识或设置页标识"]
    deeplink --> settings
    settings["设置：插件市场 / 排行榜"] --> proxy["Host 同源搜索路由"]
    installed["设置：已安装"] --> inventory["Host 本机清单路由"]
    inventory --> profile["当前 Harness profile"]
    installed --> batch["单项 / 批量固定更新计划"]
    batch --> manage["设置：确认 / 任务"]
    manage --> tasks["Host 串行生命周期队列"]
    tasks --> catalog["重新校验目录详情"]
    tasks --> cli["固定 argv 调用 dsh plugin"]
    cli --> profile
    chat["对话：搜索 / 排行工具"] --> client["共享 PluginHubClient"]
    proxy --> client
    client --> api["DSH Plugin Hub 公网只读目录 API"]
    catalog --> api
```

浏览器不会直接请求跨域公网 API。`/api/dsh-plugin-hub/search` 代理并校验搜索，`/api/dsh-plugin-hub/installed` 只读取配置中的本机 profile。`/api/dsh-plugin-hub/tasks` 是不开放 CORS 的同源私有接口：所有变更请求必须携带匹配当前 Host 的 `Origin`，输入使用严格 schema，任务历史以 `0700` 目录和 `0600` 文件保存在 Harness home 下。

## 配置

Bundle 默认配置：

```yaml
- id: dsh-plugin-hub
  name: '@czj-git/dsh-plugin-hub'
  config:
    baseUrl: https://dshpluginhub.dev
    locale: en
    timeoutMs: 15000
    maxResults: 10
    profile: web
    taskTimeoutMs: 600000
    taskKillGraceMs: 5000
    taskHistoryLimit: 50
    taskLogBytes: 65536
    npmRegistryUrl: https://registry.npmjs.org
    githubApiUrl: https://api.github.com
```

| 字段 | 类型 | 默认值 | 约束与行为 |
|---|---|---:|---|
| `baseUrl` | `string` | `https://dshpluginhub.dev` | API 服务地址；只接受 HTTP(S)，不能包含用户名、密码、查询参数或 URL 片段，末尾 `/` 会被移除。 |
| `locale` | `zh \| en` | `en` | 工具调用没有传入 `locale` 时使用的描述语言。 |
| `timeoutMs` | `integer` | `15000` | 每次 HTTP 请求的超时，范围为 1–120000 毫秒。 |
| `maxResults` | `integer` | `10` | 工具允许的最大 `limit`，范围为 1–50；同时也是每次调用的默认 `limit`。 |
| `profile` | `string` | `web` | 已安装页读取的 Harness profile；必须是单个安全路径段。 |
| `taskTimeoutMs` | `integer` | `600000` | 单个生命周期命令超时，范围为 1000–3600000 毫秒。 |
| `taskKillGraceMs` | `integer` | `5000` | 发出终止信号后等待强制终止的时间，范围为 100–30000 毫秒。 |
| `taskHistoryLimit` | `integer` | `50` | 保留的终态任务数量，范围为 1–200；活动任务不受此限制。 |
| `taskLogBytes` | `integer` | `65536` | 每个任务保留的脱敏日志上限，范围为 1024–1048576 字节。 |
| `npmRegistryUrl` | `string` | `https://registry.npmjs.org` | 高级安装查询 npm 元数据的 HTTP(S) 服务地址。 |
| `githubApiUrl` | `string` | `https://api.github.com` | 高级安装解析公开 GitHub 引用与清单的 HTTP(S) API 地址。 |

后续 profile patch 覆盖配置时需要完整重述该行的全部 `config` 字段，因为 Cordis patch 替换整个配置对象而不是深度合并。

## 工具输入

### `dsh_plugin_search`

搜索已发布且通过验证的插件。`query` 会去除首尾空白并把连续空白合并成一个空格；规范化后为空会在发出网络请求前失败。

| 参数 | 必填 | 类型/可选值 | 默认值 | 说明 |
|---|---|---|---|---|
| `query` | 是 | `string` | — | 用户需求、功能、插件名、作者或仓库；规范化后必须非空，最长 100 个字符。 |
| `locale` | 否 | `zh`, `en` | 配置中的 `locale` | 返回本地化描述。 |
| `category` | 否 | 见“枚举值” | 全部分类 | 限定市场分类。 |
| `type` | 否 | `host`, `client`, `hybrid` | 全部形态 | 限定插件运行形态。 |
| `source` | 否 | `npm`, `github` | 全部来源 | 限定安装包来源。 |
| `sort` | 否 | `relevance`, `growth`, `stars`, `newest`, `active` | `relevance` | 控制稳定排序；非空关键词默认按相关性排序。 |
| `page` | 否 | `integer` | `1` | 页码，范围为 1–1000。 |
| `limit` | 否 | `integer` | 配置中的 `maxResults` | 本页条数，范围为 1–`maxResults`，且服务端上限为 50。 |

示例输入：

```json
{
  "query": "vision",
  "locale": "zh",
  "category": "multimodal-creative",
  "type": "hybrid",
  "source": "npm",
  "sort": "relevance",
  "page": 1,
  "limit": 5
}
```

自然语言示例：

```text
帮我找一个能让纯文本 Agent 分析截图的 DeepSeek Harness 插件，优先返回 npm 包，并给出安装命令。
```

### `dsh_plugin_rankings`

使用同一个公开搜索端点的排序能力列出榜单。该工具没有关键词、`type` 或 `source` 参数。

| 参数 | 必填 | 类型/可选值 | 默认值 | 说明 |
|---|---|---|---|---|
| `ranking` | 是 | `growth`, `stars`, `newest`, `active` | — | 选择榜单口径。 |
| `locale` | 否 | `zh`, `en` | 配置中的 `locale` | 返回本地化描述。 |
| `category` | 否 | 见“枚举值” | 全部分类 | 只排列指定分类。 |
| `page` | 否 | `integer` | `1` | 页码，范围为 1–1000。 |
| `limit` | 否 | `integer` | 配置中的 `maxResults` | 本页条数，范围为 1–`maxResults`。 |

`ranking` 的含义：

| 值 | 榜单 | 排序依据 |
|---|---|---|
| `growth` | 日增长 | 两个最近成功快照之间的 GitHub Star 变化。无上一份快照时 `starsDelta1d` 为 `null`。 |
| `stars` | Star 总榜 | GitHub Stars 总数。 |
| `newest` | 最新上架 | DSH Plugin Hub 首次收录时间。 |
| `active` | 最近活跃 | GitHub 最近推送时间。 |

示例输入：

```json
{
  "ranking": "stars",
  "locale": "zh",
  "category": "coding-tools",
  "page": 1,
  "limit": 10
}
```

## 枚举值

分类 `category`：

| 值 | 含义 |
|---|---|
| `agent-workflow` | Agent 与工作流 |
| `coding-tools` | 编程与工具 |
| `models-data` | 模型与数据 |
| `ui-experience` | 界面与体验 |
| `integrations` | 连接与集成 |
| `security-governance` | 安全与治理 |
| `multimodal-creative` | 多模态与创作 |
| `observability-cost` | 监控与用量 |
| `other` | 其他 |

排序 `sort`：

- `relevance`：名称、仓库和作者匹配优先，其次是简介匹配；同级结果使用 Stars 和插件 ID 保持稳定顺序。
- `growth`、`stars`、`newest`、`active`：与排行榜工具中的同名口径一致。

## 工具输出

搜索和排行榜两个工具返回同一份结构化数据。PTC 模式可以读取全部字段；Native 模式使用下面的文本投影，避免把大量 JSON 填入模型上下文。

### 完整字段

| 路径 | 类型 | 说明 |
|---|---|---|
| `items` | `Plugin[]` | 当前页的插件。空结果为 `[]`，不是错误。 |
| `items[].id` | `string` | 插件的稳定公开 ID。 |
| `items[].slug` | `string` | `owner/repository` 形式的公开标识。 |
| `items[].name` | `string` | 插件显示名称。 |
| `items[].owner` | `string` | GitHub 仓库所有者。 |
| `items[].repo` | `string` | GitHub 仓库名。 |
| `items[].description` | `string` | 按 `locale` 返回的插件简介。 |
| `items[].type` | `host \| client \| hybrid` | 插件运行形态。 |
| `items[].category` | `string` | 市场分类枚举值。 |
| `items[].topics` | `string[]` | 仓库主题标签。 |
| `items[].language` | `string` | 仓库主要语言。 |
| `items[].license` | `string` | 许可证标识。 |
| `items[].package.name` | `string` | 包或安装目标名称。 |
| `items[].package.version` | `string` | 已验证版本。 |
| `items[].package.source` | `npm \| github` | 安装来源。 |
| `items[].package.sourceSpec` | `string` | 固定到已验证来源/版本的安装说明符。 |
| `items[].package.installCommand` | `string` | 可复制的 DSH 安装命令；返回命令不会自动执行。 |
| `items[].package.profile` | `string` | 建议安装的 Harness profile。 |
| `items[].package.profiles` | `string[]` | 验证时声明支持的全部 profile；旧服务端可能省略。 |
| `items[].compatibility.harnessVersion` | `string` | 验证时使用或要求的 Harness 版本。 |
| `items[].compatibility.harnessRange` | `string \| null` | 插件声明的兼容版本范围；尚未采集时为 `null`。 |
| `items[].compatibility.platforms` | `string[] \| null` | 插件声明的平台；尚未采集时为 `null`。 |
| `items[].compatibility.verificationLevel` | `static-checked \| runtime-verified` | 静态检查或运行时验证级别。 |
| `items[].compatibility.smokeStatus` | `static-passed \| passed \| manual-step-required \| failed \| not-run` | Smoke 检查结果。 |
| `items[].compatibility.validatedAt` | `string` | 兼容性验证时间。 |
| `items[].safety` | `object` | 构建授权、权限、外部服务、遥测和风险标记；没有可信声明时使用 `unknown` 或 `null`，旧服务端可能省略。 |
| `items[].capabilities` | `string[] \| null` | Harness 能力标签；尚未采集时为 `null`。 |
| `items[].metrics.stars` | `integer` | GitHub Stars。 |
| `items[].metrics.starsDelta1d` | `integer \| null` | 最近两个成功快照之间的 Star 变化；缺少基线时为 `null`。 |
| `items[].metrics.forks` | `integer` | GitHub Forks。 |
| `items[].metrics.openIssues` | `integer` | GitHub Open Issues。 |
| `items[].metrics.views` | `integer` | DSH Plugin Hub 公开浏览量。 |
| `items[].timestamps.listedAt` | `string` | 市场首次收录时间。 |
| `items[].timestamps.lastPushedAt` | `string` | GitHub 最近推送时间。 |
| `items[].timestamps.sourceUpdatedAt` | `string` | 来源数据最近更新时间。 |
| `items[].links.detail` | `string` | DSH Plugin Hub 详情页 URL。 |
| `items[].links.repository` | `string` | GitHub 仓库 URL。 |
| `pagination.page` | `integer` | 当前页码。 |
| `pagination.perPage` | `integer` | 服务端返回的每页条数。 |
| `pagination.total` | `integer` | 符合条件的插件总数。 |
| `pagination.totalPages` | `integer` | 总页数。 |
| `meta.apiVersion` | `v1` | 公网 API 版本。 |
| `meta.locale` | `zh \| en` | 实际使用的描述语言。 |
| `meta.query` | `string` | 服务端接收的规范化关键词；排行榜通常为空字符串。 |
| `meta.sort` | `string` | 实际使用的排序。 |
| `meta.dataUpdatedAt` | `string` | 此响应所基于的数据更新时间。 |
| `rateLimit.limit` | `integer \| null` | 响应头中的匿名额度上限；响应头缺失或无效时为 `null`。 |
| `rateLimit.remaining` | `integer \| null` | 响应头中的剩余额度；缺失或无效时为 `null`。 |
| `rateLimit.reset` | `string \| null` | `RateLimit-Reset` 响应头的原始值。 |
| `rateLimit.retryAfterSeconds` | `integer \| null` | `Retry-After` 的非负整数秒数；通常只在 429 时出现。 |

### 完整结构化输出示例

以下为字段说明示例，插件名、指标和时间均为示例值，不代表当前目录；不要将示例包名作为真实安装目标。

```json
{
  "items": [
    {
      "id": "123",
      "slug": "owner/plugin",
      "name": "plugin",
      "owner": "owner",
      "repo": "plugin",
      "description": "一个已通过验证的 DeepSeek Harness 插件。",
      "type": "host",
      "category": "coding-tools",
      "topics": ["dsh-plugin", "developer-tools"],
      "language": "TypeScript",
      "license": "MIT",
      "package": {
        "name": "dsh-plugin-example",
        "version": "1.0.0",
        "source": "npm",
        "sourceSpec": "dsh-plugin-example@1.0.0",
        "installCommand": "dsh plugin --profile web add dsh-plugin-example",
        "profile": "web",
        "profiles": ["web"]
      },
      "compatibility": {
        "harnessVersion": "0.1.0-rc.7",
        "harnessRange": null,
        "platforms": null,
        "verificationLevel": "runtime-verified",
        "smokeStatus": "passed",
        "validatedAt": "2026-08-27T00:00:00.000Z"
      },
      "safety": {
        "buildApproval": "unknown",
        "permissions": null,
        "externalServices": null,
        "telemetry": "unknown",
        "riskFlags": []
      },
      "capabilities": null,
      "metrics": {
        "stars": 42,
        "starsDelta1d": 3,
        "forks": 4,
        "openIssues": 1,
        "views": 20
      },
      "timestamps": {
        "listedAt": "2026-08-20T00:00:00.000Z",
        "lastPushedAt": "2026-08-26T00:00:00.000Z",
        "sourceUpdatedAt": "2026-08-27T00:00:00.000Z"
      },
      "links": {
        "detail": "https://dshpluginhub.dev/zh/plugins/owner/plugin",
        "repository": "https://github.com/owner/plugin"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 5,
    "total": 1,
    "totalPages": 1
  },
  "meta": {
    "apiVersion": "v1",
    "locale": "zh",
    "query": "截图分析",
    "sort": "relevance",
    "dataUpdatedAt": "2026-08-27T00:00:00.000Z"
  },
  "rateLimit": {
    "limit": 60,
    "remaining": 58,
    "reset": "42",
    "retryAfterSeconds": null
  }
}
```

### Native 模式文本示例

```text
Plugin search: 1 matches; showing 1 on page 1.
1. plugin (owner/plugin)
   一个已通过验证的 DeepSeek Harness 插件。
   coding-tools · host · 42 stars · 1d growth +3
   Install: dsh plugin --profile web add dsh-plugin-example
   Details: https://dshpluginhub.dev/zh/plugins/owner/plugin
   Repository: https://github.com/owner/plugin
Anonymous API quota remaining: 58/60.
```

空结果会返回有效的 `items: []`。Native 模式显示：

```text
Plugin search: no published, verified plugins matched. Try a broader query or remove a filter.
```

## 错误与取消

设置页生命周期任务会保留稳定的本地失败码和修复建议，例如 `TASK_TIMEOUT`、`PNPM_NOT_FOUND`、`BUILD_APPROVAL_REQUIRED`、`NETWORK_FAILURE`、`COMMAND_FAILED` 与 `RECONCILIATION_FAILED`。Harness 重启时未完成的历史任务会被标记为 `PROCESS_INTERRUPTED`，不会自动重新执行。任务中心可查看脱敏日志并对允许的终态任务重试。

工具输入校验、网络访问、服务端错误和返回校验失败都会结束本次工具调用，不会把不完整数据伪装成成功结果。底层客户端抛出 `PluginHubApiError`，包含以下可编程字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `message` | `string` | 面向调用者的稳定错误说明。 |
| `code` | `string` | 本地错误码或服务端公开错误码。 |
| `status` | `integer \| null` | HTTP 状态码；请求未取得响应时为 `null`。 |
| `fields` | `Record<string, string>` | 服务端返回的字段级错误；没有时为空对象。 |
| `retryAfterSeconds` | `integer \| null` | 可重试等待秒数；只接受有效的非负整数响应头。 |

本地错误码：

| `code` | 触发条件 |
|---|---|
| `CANCELLED` | Harness 取消了正在进行的工具调用。 |
| `TIMEOUT` | 请求超过配置中的 `timeoutMs`。 |
| `NETWORK_ERROR` | DNS、TLS、连接或其他网络访问失败。 |
| `INVALID_RESPONSE` | 服务返回非 JSON，或成功响应不符合完整字段定义。 |
| `HTTP_<status>` | 非成功响应没有可识别的公开错误对象。 |

服务端错误码会原样保留，例如参数不合法的 `INVALID_QUERY` 或匿名额度耗尽的 `RATE_LIMITED`。429 响应同时读取 `Retry-After`。

程序化处理示例：

```ts
import { PluginHubApiError, PluginHubClient } from '@czj-git/dsh-plugin-hub/api'

const client = new PluginHubClient({
  baseUrl: 'https://dshpluginhub.dev',
  timeoutMs: 15_000,
})

try {
  const result = await client.search(
    { query: 'memory', locale: 'zh', page: 1, perPage: 5 },
    new AbortController().signal,
  )
  console.log(result.items)
} catch (error) {
  if (error instanceof PluginHubApiError) {
    console.error(error.code, error.status, error.retryAfterSeconds)
  }
}
```

## 开发与验证

```sh
npm install
npm run check
```

`npm run check` 依次运行严格类型检查、无网络单元测试和生产构建。GitHub 源安装会执行 `prepare` 生成 `dist/`；pnpm 10+ 会要求用户明确允许该构建脚本。若不希望授予安装期构建权限，请发布包含预构建 `dist/` 的 npm 包或 tarball。

## 限制

- 公网目录查询使用搜索和详情端点；排行榜工具通过搜索端点的稳定排序参数实现。
- 插件详情正文、评论、收藏和用户数据不在公开 API 中，因此本插件不读取这些内容。
- 对话工具只读取目录、本机清单和任务状态，不会创建安装、更新或卸载任务；生命周期管理只在设置页提供明确确认后执行。
- 生命周期任务只管理配置中的单个 profile，默认是 `web`；完成后必须重启 Harness 才能加载新的插件组合。
- 匿名额度由服务端控制；默认策略可能调整，工具只报告当前响应中的实际限流头。

## 许可证

MIT