Kimi 网页管道 kenny2077/dsh-web-kimi

dsh-web-kimi

一把 Kimi Coding 密钥，贯通网页管道的两半——为 DeepSeek Harness 同时提供网页搜索与网页抓取。

- 它是什么
- 为什么
- 工作原理
- 快速开始
- 设置界面卡片
- 配置
- 字段映射
- 故障排查
- 同类插件对比
- 已知限制
- 仓库架构
- 开发
- 致谢
- 许可证

它是什么

一个向 ctx.web 接缝注册两个提供方 的 DSH 插件：

- kimi-coding —— 由 Kimi Coding API 搜索端点（POST /v1/search）支撑的 WebSearchProvider。搜索结果映射为 harness 的 WebSearchSource 结构：url、title、snippet 与 publishedAt（来自结果中的 date）。
- kimi-coding-fetch —— 由 Kimi Coding API 抓取端点（POST /v1/fetch）支撑的 WebFetchProvider。任意 http(s) 网址都由服务端完成提取（含 JavaScript 渲染），返回干净的 Markdown。

两半共用同一凭证、读取同一设置分区——密钥保存一次，所有网页操作全部覆盖。GUI 中专门的设置卡片经 DSH 凭据服务保存密钥，保存后的值在下一次搜索或抓取即生效，无需重启。

┌─────────────────────────────────────────────┐
│ ctx.web 接缝 │ ├──────────────────────┬──────────────────────┤ │ web_search 工具 │ web_fetch 工具 │ │ WebSearchProvider │ WebFetchProvider │ │ kimi-coding │ kimi-coding-fetch │ └──────────┬───────────┴──────────┬───────────┘ │ POST /v1/search │ POST /v1/fetch ▼ ▼ ┌─────────────────────────────────────────────┐ │ api.kimi.com/coding/v1 │ │ 一个 Bearer 密钥，一份订阅 │ └─────────────────────────────────────────────┘

为什么

DSH 生态里已有搜索聚合器与 OAuth 桥接，缺的是 Kimi 的厂商原生双接缝集成。本插件把你已订阅的 Coding 计划直接接入 web_search 与 web_fetch 两条链路——没有按次计费的搜索账单，没有第二个账号，中间也没有聚合层。

如果你已在用 Kimi Code（CLI），本插件零配置：凭据链会自动回退到 ~/.kimi-code/config.toml 并读取其中的密钥。

工作原理

1. 注册 —— 插件注入 ctx.web 并注册两个提供方。安装时 bundle 覆盖层选择 searchProvider: kimi-coding 与 fetchProvider: kimi-coding-fetch。
2. 凭证解析（每次操作执行，无需重启）—— 卡片保存值优先，其后依次是凭据服务的次级引用、配置字面量、启动环境变量、Kimi CLI 配置文件：

设置卡片 → KIMI_CODING_API_KEY → KIMI_API_KEY → 配置 apiKey → 启动环境 → ~/.kimi-code/config.toml → ~/.kimi/config.toml

3. 请求组装 —— text_query 加服务端 limit（钳制在 API 的 1–20 区间）、开关对应的 enable_page_crawling、timeout_seconds，以及每次调用全新的 X-Msh-Tool-Call-Id 关联 id。
4. 加固 —— 仅转发或呈现绝对 http(s) 网址；搜索响应体在缓冲前以 5 MB 为上限；抓取内容以 2 MB 封顶并带 truncated 标记。所有失败都以带类型的 WebError 呈现（WEB_PROVIDER_ERROR、WEB_PROVIDER_CREDENTIAL_MISSING、WEB_ABORTED），错误消息中保留上游 HTTP 状态码。

web_fetch 工具本身仍由 dsh-tool-web 把关（harness 出于 SSRF 考虑默认关闭抓取）；本插件只注册提供方与路由，供你启用工具后使用。

快速开始

dsh plugin --profile web add dsh-web-kimi

然后在 DSH web GUI 打开 设置 → Web Search (Kimi)，粘贴你的 Kimi Coding API Key 并保存。密钥进入 DSH 凭据服务（~/.dsh/.credentials.yaml）——绝不会写入 settings.yaml。

没有 GUI？以下任一方式同样可行：

export KIMI_CODING_API_KEY=sk-... # 启动环境变量
或者：经凭据服务保存在 KIMI_CODING_API_KEY / KIMI_API_KEY 名下或者：~/.kimi/config.toml 中 api_key = "..." （Kimi Code CLI 用户——自动读取）

提供方 id kimi-coding 刻意与 quei4r/dsh-host-kimi-search 一致，安装本插件即是对该脚本的原地替换，而非 id 冲突。

设置界面卡片

卡片包含三个字段，全部以凭据引用存储：

| 字段 | 类型 | 存储引用 |
| API Key | 密码 | KIMI_CODING_API_KEY |
| 接口地址 | 文本 | KIMI_SEARCH_BASE_URL |
| 页面抓取 | 选择（true / false） | KIMI_SEARCH_PAGE_CRAWLING |

- 掩码输入框、直达 Kimi 控制台的「获取 API Key ↗」链接，以及保存后实时刷新的已配置/未配置徽标。
- 字段留空表示保留当前值；重置将清空全部三个引用。
- CLI 配置回退是只读的——本插件绝不写 ~/.kimi/config.toml。

配置

设置分区 web-kimi（与卡片写入的同一批字段的文件编辑方式）：

| 字段 | 默认值 | 含义 |
| apiKey | — | 字面量密钥；凭据引用中存储的值优先于它 |
| apiKeyEnv | KIMI_CODING_API_KEY | 主凭据引用 |
| baseURL | https://api.kimi.com/coding/v1 | 端点基址（自动追加 /search、/fetch） |
| pageCrawling | false | 发送 enable_page_crawling，使结果携带全文 content |
| timeoutSeconds | 30 | 服务端 timeout_seconds |

字段映射

| Kimi /v1/search 字段 | WebSearchSource |
| url | url（必填；非 http(s) 结果被丢弃） |
| title | title（为空时省略） |
| snippet，其次 content | snippet（取第一个非空值） |
| date | publishedAt（为空时省略） |
| site_name、icon、mime | 不映射 |

/v1/fetch 响应以 Markdown 返回，映射为 WebFetchResult { statusCode, body: { kind: 'text' }, truncated }——超过 2 MB 的内容被截断并标记。

故障排查

每条失败消息都带 HTTP 状态码，多数问题一眼可断：

| 看到的报错 | 含义 | 处理 |
| url.not_found | 基址指向没有 /search 的服务面——典型是把聊天 API（https://api.moonshot.cn/v1）填了进来 | 基址改为 https://api.kimi.com/coding/v1；coding 端点需要 coding 凭证 |
| Kimi search error (HTTP 401): … | 密钥被识别但被拒绝——它不是 Coding 凭证 | 使用 Kimi Coding API Key，而非聊天/开放平台密钥 |
| Kimi search error (HTTP 403): … | 密钥有效，但计划未含搜索/抓取服务 | 在 coding 计划上开通该服务 |
| … (HTTP 5xx): … / 非 JSON 响应体 | 上游侧故障 | 重试；状态码说明与你的配置无关 |
| WEB_PROVIDER_CREDENTIAL_MISSING | 凭据链全程未解析到密钥 | 在设置卡片粘贴，或存于 KIMI_CODING_API_KEY / KIMI_API_KEY 名下，或导出环境变量，或写入 ~/.kimi/config.toml |
| 结果没有 content | 页面抓取关闭 | 打开页面抓取开关 |

同类插件对比

| | dsh-web-kimi | dsh-web-search-doubao | dsh-web-search-zai | quei4r/dsh-host-kimi-search |
| 覆盖接缝 | 搜索 + 抓取 | 搜索 | 搜索 | 搜索 |
| 凭证 | 一把 coding 计划密钥 | 独立的豆包搜索密钥 | 复用 ZAI_API_KEY | coding 密钥链 |
| 设置 GUI 卡片 | 有 | 有 | — | — |
| CLI 配置回退 | 有 | — | — | 有 |
| 带类型的错误分类 | 有 | 有 | 有 | 部分 |
| 已上架 npm | 有 | 有 | 有 | — |

已知限制

- 权益：coding 计划账户须包含搜索/抓取服务，否则端点返回 403。
- content 依赖抓取：不开 pageCrawling 时结果正文为空。
- 抓取工具把关：需在 dsh-tool-web 中启用 web_fetch 才会路由到本提供方。
- 每个 profile 只有一个 searchProvider：安装本插件会把 profile 的选择从原搜索插件切换过来；移除（或覆盖配置）即可切回。
- 不做 DeepSeek 密钥回退（与 quei4r 链路的刻意差异）：DeepSeek API Key 在 api.kimi.com 只会得到 401。

仓库架构

dsh-web-kimi/
├── package.json # dsh.bundle.patch + dsh.client 清单，导出 ./client ├── tsdown.config.ts # 客户端半构建（ModuleLoader 包装的浏览器 bundle） ├── cordis.patch.yml # searchProvider + fetchProvider 选择与插入条目 ├── src/ │ ├── index.ts # 节点入口：Config、凭据链、apply() │ ├── provider.ts # KimiSearchProvider 与共享的请求头/中止管线 │ ├── fetch-provider.ts # KimiFetchProvider（第二条接缝） │ ├── types.ts # 线路类型 │ ├── invariant.ts # no-op invariant 伴生导出 │ └── client/ │ ├── card.tsx # 可复用的设置卡片工厂 │ └── index.tsx # Kimi 实例化（引用、语言、控制台链接） ├── tests/ # 覆盖搜索、抓取、卡片的 79 个单元测试 └── lib/ # 已提交的构建产物——git 安装无需构建步骤

开发

pnpm install
pnpm typecheck && pnpm build && pnpm test

- Node 22.19+ / 24，pnpm 11——与 harness 相同的下限。
- 测试套件针对 mock 的 fetch 运行（79 个测试）；tests/kimi.e2e.ts 的在线冒烟在无 $KIMI_CODING_API_KEY 时自动跳过。
- CI 在每次 push 与 PR 上运行完整关卡（typecheck、build、test），矩阵为 Node 22/24 × Ubuntu/Windows。

致谢

多来源凭据链（KIMI_CODING_API_KEY → KIMI_API_KEY → Kimi CLI 配置）与仅限 http(s)/体积上限的加固思路源自 quei4r/dsh-host-kimi-search——本插件把这一思路扩展到抓取接缝、设置卡片、测试套件与 npm 发行。卡片架构沿用同级 DSH 搜索插件验证过的 settings.section/凭据引用约定。

许可证

MIT