@dshp-inx/mcwiki-search

Readme

# mcwiki-search

DeepSeek Harness（DSH）工具插件：查询 **Minecraft Wiki**（MediaWiki API，中文 / 英文），并把搜索结果与页面全文**完整转换为 AI 可直接阅读的干净文本**。

> 核心承诺：模型看到的永远是清洗后的结果 —— 模板、引用、图片、跨语言链接等噪声在插件内部全部处理完毕，绝不让原始 wikitext / HTML 进入模型上下文。

## 功能

注册 3 个模型工具：

| 工具 | 作用 | 返回 |
|---|---|---|
| `mcwiki_search` | 全文搜索 | 清洗后的标题 / 摘要（命中词加粗）/ URL / 更新时间 |
| `mcwiki_get_page` | 抓取页面 | `section=intro` 纯文本引言（默认）；`section=full` 全文 → Markdown / 纯文本 / wikitext。**默认完整输出、不截断**；可传 `maxChars`（0=不截断，正数=上限）按需设限 |
| `mcwiki_random` | 随机条目 | 条目标题 + 引言纯文本（完整、不截断） |

配套「设置 → Minecraft Wiki 搜索」页面：数据源状态、**配置卡**（API 端点 / 超时 / 搜索条数 / 全文与引言上限，直接保存到 `settings.yaml` 即时生效）、搜索测试、页面转换测试（直接看转换后的文本）。

> **完整性承诺**：搜索摘要、引言、全文（含表格）默认**完整输出、绝不截断** —— 所有信息与细节都保留给 AI。只有显式传 `maxChars`（正整数）或部署配置设限时才会截断，且输出末尾会明确标注。设置页中的转换测试为 UI 预览（最多 6000 字符），与模型工具无关。

## 同源路由

| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/ext/dshp-inx-mcwiki-search/state` | 数据源状态 + 当前生效配置快照 |
| POST | `/ext/dshp-inx-mcwiki-search/config` | 保存配置补丁（`apiBase/timeoutMs/maxChars/introMaxChars/searchMaxResults`，写 `settings.yaml`） |
| POST | `/ext/dshp-inx-mcwiki-search/test` | 连接测试（搜索 + 页面抓取） |

全部带同源校验（`Origin` 与 `Host` 一致或缺失才放行）。工具与路由每次调用都读当前生效配置，`settings.yaml` 外部编辑热重载、无需重启。

## 数据转换管线

```
MediaWiki API JSON
  └─ cleanSearchSnippet()   搜索摘要：searchmatch 高亮 → **加粗**，实体解码，
  │                         空白折叠，修复中文 bigram 拆词（「苦力 怕」→「苦力怕」）
  ├─ extracts plaintext     引言：MediaWiki 官方纯文本输出 + 收尾清洗
  └─ wikitextToMarkdown()   全文：
       ├─ {{模板}} 整块处理 —— 信息框/历史/音效/导航等噪声整块丢弃；
       │                     {{tr|简体|…}} 取简体、*Link/*Sprite 取条目名、
       │                     {{droptable|dropline}} 保留掉落表、{{only/in/el}} 渲染版本、
       │                     {{quote}} 保留引言、{{cd/cmd}} 保留代码
       ├─ <ref>/<gallery>/<syntaxhighlight> 等标签块丢弃
       ├─ [[File:…]]/[[Category:…]]/[[w:…]]/跨语言链接 丢弃；[[目标|显示名]] → 显示名
       ├─ == 标题 == → ## 标题；'''粗体''' → **粗体**；''斜体'' → *斜体*
       ├─ 列表 * # : ; 归一化；{|…|} 表格扁平化为 Markdown 表格（完整保留）
       └─ 输出完整不截断（默认）；传 maxChars 正整数才设上限并标注
```

## 安装（推荐：GitHub）

```sh
dsh plugin --profile web add github:Yinxe/dsh-mcwiki-search
```

`dsh plugin` 把参数转发给 profile 目录里的 pnpm，装完自动把插件写进 profile 的 `dsh.profile.bundles` 挂载列表 —— **无需手动改任何配置文件**。

**一键 AI 安装**：把下面这段直接发给你的 DSH AI（复制即用，无需修改）：

```text
帮我安装 Minecraft Wiki 搜索插件（GitHub 仓库 Yinxe/dsh-mcwiki-search，包名 @dshp-inx/mcwiki-search）：
1. 执行 dsh plugin --profile web add github:Yinxe/dsh-mcwiki-search
2. 重启 web 服务（dsh web），确认重启无报错
3. 验证插件已生效（设置页出现 Minecraft Wiki 搜索卡片，或注册出 mcwiki_search 工具）
4. 用 mcwiki_search 帮我查一下「苦力怕」，展示一条结果确认链路通畅
```

重启生效：

```sh
dsh web
```

**验证**：打开 web 页面 → 设置 → Minecraft Wiki 搜索 出现插件卡片；或直接对模型说「用 mcwiki_search 查一下苦力怕」。

## 更新

```sh
dsh plugin --profile web update "@dshp-inx/mcwiki-search" --latest
dsh web
```

`update --latest` 会让 pnpm 重新解析 GitHub 仓库的最新 commit 并更新 lockfile；重启后生效。

## 安装（备选：clone 源码 + 本地 link）

适合想改源码、或 GitHub 不可达的场景。clone 后用 `add ./<目录>` 安装 —— **依赖按插件真实包名（`@dshp-inx/mcwiki-search`）登记**，后续 update / remove 与 GitHub 安装完全一致。link 安装的源码改动**即时生效**（client 半刷新页面即可，host 半需重启 `dsh web`）：

```sh
git clone git@github.com:Yinxe/dsh-mcwiki-search.git ~/.dsh/plugins/mcwiki-search
cd ~/.dsh/plugins
dsh plugin --profile web add ./mcwiki-search
dsh web
```

> `add ./<目录>` 的相对路径按**你执行命令时所在的目录**解析，先 `cd` 到插件目录的父级再执行。
> ⚠️ **不要直接编辑 `node_modules/@dshp-inx/mcwiki-search/` 里的文件**：pnpm 的安装文件与内容寻址 store 硬链接，直接覆盖会连带改坏 store。改源码请改 clone 出来的源码目录。

link 方式的更新就是 `git pull`（源码目录）+ 刷新页面/重启。

## 验证（不依赖 DSH 运行时）

```sh
node lib/self-test.js                 # 中文搜索「钻石」+ 引言 + 全文转 Markdown + 随机
node lib/self-test.js 苦力怕          # 指定查询词
node lib/self-test.js "Ancient City" en   # 英文 wiki
node lib/self-test.js --no-page       # 仅搜索
```

每个用例输出均展示转换后的 AI 可读文本。

**集成测试**（真实 cordis 表面 + DSH schema 校验 + 真实执行）：

```sh
# 方式 A：在任意 DSH profile 目录内运行（dsh-tools 按 profile 解析）
cd ~/.dsh/profiles/web && node ../../plugins/dsh-mcwiki-search/test/integration.mjs

# 方式 B：任意位置，显式指定 dsh-tools 入口
DSH_TOOLS_ENTRY=/path/to/node_modules/@deepseek-ai/dsh-tools/lib/index.js \
  node test/integration.mjs
```

## 卸载

```sh
dsh plugin --profile web remove "@dshp-inx/mcwiki-search"
dsh web
```

`remove` 会自动从 `dsh.profile.bundles` 撤下挂载；clone 安装的再删掉 `~/.dsh/plugins/dsh-mcwiki-search` 目录即可。

## 配置（标准 settings 存储）

持久化到 `settings.yaml` 的 `dshp-inx-mcwiki-search` 命名空间，设置页可直接改，外部编辑热重载。
`config:` patch 层仍可覆盖默认值（settings 的 base 层），即开即用：

```yaml
- id: dshp-inx-mcwiki-search
  name: "@dshp-inx/mcwiki-search"
  config:
    apiBase: https://zh.minecraft.wiki/api.php   # 或 en: https://minecraft.wiki/api.php
    timeoutMs: 15000
    maxChars: 0          # 全文输出上限：0 = 不截断（默认，完整输出）
    introMaxChars: 0     # 引言上限：0 = 不截断（默认）
    searchMaxResults: 8  # 搜索默认条数
```

## 免责声明

- 数据来源：[zh.minecraft.wiki](https://zh.minecraft.wiki) / [minecraft.wiki](https://minecraft.wiki)，内容按 CC BY-NC-SA 3.0 授权，引用请注明出处；
- 本插件与 Mojang Studios / Microsoft 无任何隶属关系；
- 使用公开 MediaWiki API，无密钥、无配额申请。