@deepseek-ai/dsh-web-search-perplexity 0.1.1-rc.2 → 0.1.2-alpha.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.i18n.yaml +2 -2
- package/README.md +119 -18
- package/README.zh.md +123 -22
- package/lib/index.js +2 -4
- package/lib/types/index.d.ts +2 -4
- package/package.json +10 -10
package/README.i18n.yaml
CHANGED
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
|
3
3
|
# after editing either side, bring the other along and re-record with:
|
|
4
4
|
# pnpm run verify-translation-pairing --write packages/web/web-search-perplexity/README.md
|
|
5
|
-
README.md:
|
|
6
|
-
README.zh.md:
|
|
5
|
+
README.md: a616925d172d7729b8cd24d5e701013111f5837d
|
|
6
|
+
README.zh.md: 48a866d04fc5458daf1424e7f2608e23a2984367
|
package/README.md
CHANGED
|
@@ -1,32 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "The Perplexity-backed search provider for ctx.web: how deployments mount OpenAI-compatible Perplexity search with generated answers and citations."
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# @deepseek-ai/dsh-web-search-perplexity
|
|
2
7
|
|
|
3
8
|
English | [中文](README.zh.md)
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
## Summary
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
With `dsh-web-search-perplexity`, the harness searches the web through Perplexity and gets a model-generated answer plus citeable sources in one call. Choose it when a deployment has a Perplexity API key and wants a generated answer. Perplexity has no result-count control, so the returned sources are truncated to the requested bound after the fact. When Perplexity omits structured result metadata, sources fall back to URL-only citations. The model-facing `web_search` tool lives in `dsh-tool-web`.
|
|
8
13
|
|
|
9
|
-
##
|
|
14
|
+
## Table of Contents
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
16
|
+
- [Use this package](#use-this-package)
|
|
17
|
+
- [Understand the implementation](#understand-the-implementation)
|
|
18
|
+
- [Further Exploration](#further-exploration)
|
|
19
|
+
- [Model Experience](#model-experience)
|
|
20
|
+
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
|
21
|
+
- [Dev Note](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## Use this package
|
|
27
|
+
|
|
28
|
+
Mount the provider in a composition that already loads the web service; it registers as the `perplexity` search provider, so `ctx.web.search()` resolves it automatically when it is the only usable search backend — or pin it with `searchProvider: perplexity`.
|
|
29
|
+
|
|
30
|
+
### When to choose it
|
|
31
|
+
|
|
32
|
+
Choose this backend when a deployment holds a Perplexity API key and wants a model-generated answer plus citeable sources in one search. The provider is unavailable — and every search call fails with a structured error — when the key is empty or the endpoint base does not parse.
|
|
33
|
+
|
|
34
|
+
### Minimal configuration
|
|
35
|
+
|
|
36
|
+
Load the web service and the provider; the API key falls back to `$PERPLEXITY_API_KEY` from the launch environment, and all other settings have safe defaults.
|
|
18
37
|
|
|
19
38
|
```yaml
|
|
20
|
-
-
|
|
21
|
-
|
|
39
|
+
- name: '@deepseek-ai/dsh-web'
|
|
40
|
+
- name: '@deepseek-ai/dsh-web-search-perplexity'
|
|
22
41
|
config:
|
|
23
42
|
apiKey: !!js process.env.PERPLEXITY_API_KEY
|
|
24
43
|
```
|
|
25
44
|
|
|
26
|
-
|
|
45
|
+
| Field | Default | Meaning |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `apiKey` | `$PERPLEXITY_API_KEY` | Perplexity API key; empty or absent makes the provider unavailable |
|
|
48
|
+
| `baseURL` | `https://api.perplexity.ai` | Endpoint base; `/chat/completions` is appended. An unparseable value makes the provider unavailable |
|
|
49
|
+
| `model` | `sonar` | Search model name |
|
|
50
|
+
| `maxTokens` | `1024` | Upper bound on generated answer tokens (`max_tokens`); must be a positive integer |
|
|
51
|
+
| `searchRecency` | (unset) | Recency window sent as `search_recency_filter`: `day`, `week`, `month`, or `year`. Unset sends no filter |
|
|
52
|
+
|
|
53
|
+
The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-perplexity) is the exhaustive source for every accepted field and its JSDoc.
|
|
54
|
+
|
|
55
|
+
### What a search returns
|
|
56
|
+
|
|
57
|
+
`content` carries Perplexity's generated answer. `sources[]` prefers the structured `search_results[]` (`url`, `title`, `snippet`, `publishedAt` from `date`) and falls back to the URL-only `citations[]` array only when `search_results` is absent — which is why `title`/`snippet`/`publishedAt` are optional on the service. Perplexity exposes no result-count control, so the service enforces `maxResults` by truncating and flagging.
|
|
58
|
+
|
|
59
|
+
### Failures and recovery
|
|
60
|
+
|
|
61
|
+
Provider failures — HTTP errors, network failures, unparseable or wrong-shape bodies — surface as `WebError` `WEB_PROVIDER_ERROR`; an aborted request surfaces as `WEB_ABORTED`. HTTP redirects are rejected before the `Location` target is contacted and surface as `WEB_PROVIDER_ERROR`. Callers route on the code; the model-facing `web_search` tool surfaces failures to the model under its own error wrapper.
|
|
62
|
+
|
|
63
|
+
-----
|
|
64
|
+
|
|
65
|
+
<a id="understand-the-implementation"></a>
|
|
66
|
+
## Understand the implementation
|
|
67
|
+
|
|
68
|
+
<details>
|
|
69
|
+
<summary>Implementation internals — click to expand</summary>
|
|
70
|
+
|
|
71
|
+
This section explains the design decisions behind the provider; the observable behavior is fully covered in [Use this package](#use-this-package).
|
|
72
|
+
|
|
73
|
+
### Design philosophy
|
|
27
74
|
|
|
28
|
-
|
|
75
|
+
The provider is a thin adapter over Perplexity's chat-completions endpoint with two deliberate rules:
|
|
29
76
|
|
|
77
|
+
- **The generated answer is trusted as `content`.** Unlike the other search backends, Perplexity returns a model-generated answer, and this provider passes it through as the normalized `content` field.
|
|
78
|
+
- **Structured sources win; URL-only citations are the fallback.** `search_results[]` carries the portable fields; `citations[]` carries only URLs, and the service vocabulary makes those fields optional precisely for this case.
|
|
79
|
+
|
|
80
|
+
### Source map
|
|
81
|
+
|
|
82
|
+
| File | Role |
|
|
83
|
+
|---|---|
|
|
84
|
+
| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, environment fallback, provider registration |
|
|
85
|
+
| [`src/provider.ts`](src/provider.ts) | The `PerplexitySearchProvider`: request dispatch, abort classification, answer and source mapping |
|
|
86
|
+
| [`src/types.ts`](src/types.ts) | Perplexity wire types for the chat-completions response |
|
|
87
|
+
| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; contracts are enforced at the service) |
|
|
88
|
+
|
|
89
|
+
### Request and mapping flow
|
|
90
|
+
|
|
91
|
+
`search()` posts the query with the model, token cap, and optional recency filter to `{baseURL}/chat/completions` with `redirect: 'error'`. The response's `content` becomes `content`; `search_results[]` becomes `sources[]` when present, otherwise each `citations[]` entry becomes a URL-only source; and the service applies the final `maxResults` bound on the way back. An abort — a `DOMException` named `AbortError` — becomes `WEB_ABORTED`; anything else becomes `WEB_PROVIDER_ERROR`.
|
|
92
|
+
|
|
93
|
+
</details>
|
|
94
|
+
|
|
95
|
+
-----
|
|
96
|
+
|
|
97
|
+
<a id="further-exploration"></a>
|
|
98
|
+
## Further Exploration
|
|
99
|
+
|
|
100
|
+
Read these pages when the package-level contract is not enough. They move from the shared vocabulary to the service, the model-facing tools, and the design rationale.
|
|
101
|
+
|
|
102
|
+
- [Web subsystem](../../../docs/subsystems/web.md) — the exhaustive search request/result vocabulary and error codes.
|
|
103
|
+
- [Web package map](../README.md) — the six-package family and each role.
|
|
104
|
+
- [dsh-web](../web/README.md) — the web service this provider registers into.
|
|
105
|
+
- [dsh-tool-web](../tool-web/README.md) — the model-facing `web_search` tool that renders this provider's sources.
|
|
106
|
+
- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-perplexity) — every accepted config field and its source declaration.
|
|
107
|
+
- [Web capability seam decision](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) — why search and fetch share one provider-selection service.
|
|
108
|
+
|
|
109
|
+
-----
|
|
110
|
+
|
|
111
|
+
<a id="model-experience"></a>
|
|
30
112
|
## Model Experience
|
|
31
113
|
|
|
32
114
|
### Auxiliary Perplexity request
|
|
@@ -47,7 +129,7 @@ Independent of the conversation request cache. An identical query under the same
|
|
|
47
129
|
|
|
48
130
|
#### What the model sees
|
|
49
131
|
|
|
50
|
-
Through
|
|
132
|
+
Through `dsh-tool-web`, the conversation model sees the generated answer plus structured result metadata or URL-only citations. This provider's exact failures are `Perplexity search aborted`, `Perplexity search request failed: <error>`, and `Perplexity returned an unprocessable response body: <error>`; HTTP failures preserve the provider message. The consumer owns the error wrapper.
|
|
51
133
|
|
|
52
134
|
#### Token effect
|
|
53
135
|
|
|
@@ -59,7 +141,26 @@ Append-only; newly visible content follows the reusable request prefix and does
|
|
|
59
141
|
|
|
60
142
|
## Known Limitations and Deferred Work
|
|
61
143
|
|
|
144
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
These limits define when the provider is a poor fit. They are current package constraints.
|
|
148
|
+
|
|
62
149
|
- **Citation-fallback sources are URL-only** — when Perplexity omits structured `search_results[]`, sources carry no `title`/`snippet`/`publishedAt`, so the tool renders bare hostname labels.
|
|
63
|
-
- **Over-returned sources still cost tokens and latency** — with no result-count control on the wire, `maxResults` is enforced only post-hoc by
|
|
64
|
-
- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral
|
|
65
|
-
- **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (
|
|
150
|
+
- **Over-returned sources still cost tokens and latency** — with no result-count control on the wire, `maxResults` is enforced only post-hoc by service truncation.
|
|
151
|
+
- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral service fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
|
|
152
|
+
- **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (such as `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
|
|
153
|
+
|
|
154
|
+
<a id="dev-note"></a>
|
|
155
|
+
### Dev Note
|
|
156
|
+
|
|
157
|
+
<details>
|
|
158
|
+
<summary>Working context for maintainers — click to expand</summary>
|
|
159
|
+
|
|
160
|
+
This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior, limits, and rationale live in the sections above and the linked Agent Notes.
|
|
161
|
+
|
|
162
|
+
#### Future: wider Perplexity control surface
|
|
163
|
+
|
|
164
|
+
Perplexity's domain filters, `web_search_options` context size, and image support stay unexposed. Exposing them needs provider-neutral service fields first, so the family adds one coordinated control rather than a vendor-specific argument.
|
|
165
|
+
|
|
166
|
+
</details>
|
package/README.zh.md
CHANGED
|
@@ -1,32 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "ctx.web 的 Perplexity 搜索提供方：部署方如何挂载 OpenAI 兼容的 Perplexity 搜索，获得生成答案与引用。"
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# @deepseek-ai/dsh-web-search-perplexity
|
|
2
7
|
|
|
3
8
|
[English](README.md) | 中文
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
## 概述
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
有了 `dsh-web-search-perplexity`，harness 可以通过 Perplexity 搜索 web，一次调用同时获得模型生成的答案与可引用来源。当部署持有 Perplexity API 密钥、并希望获得生成答案时选择它。Perplexity 没有结果数量控制，因此返回的来源会在事后被截断到请求的上限。Perplexity 省略结构化结果元数据时，来源回退为只含 URL 的引用。面向模型的 `web_search` 工具位于 `dsh-tool-web`。
|
|
8
13
|
|
|
9
|
-
##
|
|
14
|
+
## 目录
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
16
|
+
- [使用本包](#use-this-package)
|
|
17
|
+
- [理解实现](#understand-the-implementation)
|
|
18
|
+
- [进一步探索](#further-exploration)
|
|
19
|
+
- [模型体验](#model-experience)
|
|
20
|
+
- [已知限制与延期工作](#known-limitations-and-deferred-work)
|
|
21
|
+
- [开发备注](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## 使用本包
|
|
27
|
+
|
|
28
|
+
在已加载 web 服务的组合中挂载本提供方；它以 `perplexity` 搜索提供方身份注册，因此当它是唯一可用的搜索后端时，`ctx.web.search()` 会自动解析到它——也可以用 `searchProvider: perplexity` 固定。
|
|
29
|
+
|
|
30
|
+
### 何时选择
|
|
31
|
+
|
|
32
|
+
当部署持有 Perplexity API 密钥、并希望一次搜索同时获得模型生成的答案与可引用来源时选择此后端。密钥为空或端点基址无法解析时，提供方不可用——每次搜索调用都会以结构化错误失败。
|
|
33
|
+
|
|
34
|
+
### 最小配置
|
|
35
|
+
|
|
36
|
+
加载 web 服务与本提供方；API 密钥回退到启动环境中的 `$PERPLEXITY_API_KEY`，其余设置都有安全默认值。
|
|
18
37
|
|
|
19
38
|
```yaml
|
|
20
|
-
-
|
|
21
|
-
|
|
39
|
+
- name: '@deepseek-ai/dsh-web'
|
|
40
|
+
- name: '@deepseek-ai/dsh-web-search-perplexity'
|
|
22
41
|
config:
|
|
23
42
|
apiKey: !!js process.env.PERPLEXITY_API_KEY
|
|
24
43
|
```
|
|
25
44
|
|
|
26
|
-
|
|
45
|
+
| 字段 | 默认值 | 含义 |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `apiKey` | `$PERPLEXITY_API_KEY` | Perplexity API 密钥；为空或缺失时提供方不可用 |
|
|
48
|
+
| `baseURL` | `https://api.perplexity.ai` | 端点基址；追加 `/chat/completions`。无法解析时提供方不可用 |
|
|
49
|
+
| `model` | `sonar` | 搜索模型名称 |
|
|
50
|
+
| `maxTokens` | `1024` | 生成答案 token 上限（`max_tokens`）；必须是正整数 |
|
|
51
|
+
| `searchRecency` | （未设置） | 以 `search_recency_filter` 发送的新近程度窗口：`day`、`week`、`month` 或 `year`。未设置时不发送过滤条件 |
|
|
52
|
+
|
|
53
|
+
生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-perplexity)是每个受支持字段及其 JSDoc 的穷尽式真源。
|
|
54
|
+
|
|
55
|
+
### 搜索返回什么
|
|
56
|
+
|
|
57
|
+
`content` 携带 Perplexity 的生成答案。`sources[]` 优先使用结构化 `search_results[]`（`url`、`title`、`snippet`、`publishedAt` 取自 `date`），仅当 `search_results` 缺失时才回退到只含 URL 的 `citations[]` 数组——这正是服务上 `title`／`snippet`／`publishedAt` 为可选字段的原因。Perplexity 不公开结果数量控制，因此服务通过截断并标记来强制执行 `maxResults`。
|
|
58
|
+
|
|
59
|
+
### 失败与恢复
|
|
60
|
+
|
|
61
|
+
提供方失败——HTTP 错误、网络失败、响应体无法解析或结构不符——以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在访问 `Location` 指向的目标之前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。调用方按 code 路由；面向模型的 `web_search` 工具会在自己的错误包装层内把失败呈现给模型。
|
|
62
|
+
|
|
63
|
+
-----
|
|
64
|
+
|
|
65
|
+
<a id="understand-the-implementation"></a>
|
|
66
|
+
## 理解实现
|
|
67
|
+
|
|
68
|
+
<details>
|
|
69
|
+
<summary>实现细节——点击展开</summary>
|
|
70
|
+
|
|
71
|
+
本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
|
|
72
|
+
|
|
73
|
+
### 设计理念
|
|
27
74
|
|
|
28
|
-
|
|
75
|
+
该提供方是 Perplexity chat-completions 端点之上的薄适配器，遵循两条刻意的规则：
|
|
29
76
|
|
|
77
|
+
- **生成答案作为 `content` 受到信任。** 与其他搜索后端不同，Perplexity 返回模型生成的答案，本提供方将其作为规范化 `content` 字段透传。
|
|
78
|
+
- **结构化来源优先；只含 URL 的引用是回退。** `search_results[]` 携带可移植字段；`citations[]` 只携带 URL，服务词汇把这些字段设为可选，正是为了这种情况。
|
|
79
|
+
|
|
80
|
+
### 源码地图
|
|
81
|
+
|
|
82
|
+
| 文件 | 职责 |
|
|
83
|
+
|---|---|
|
|
84
|
+
| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema、环境变量回退、提供方注册 |
|
|
85
|
+
| [`src/provider.ts`](src/provider.ts) | `PerplexitySearchProvider`：请求分发、中止分类、答案与来源映射 |
|
|
86
|
+
| [`src/types.ts`](src/types.ts) | chat-completions 响应的 Perplexity 协议类型 |
|
|
87
|
+
| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；约定在服务处强制执行） |
|
|
88
|
+
|
|
89
|
+
### 请求与映射流程
|
|
90
|
+
|
|
91
|
+
`search()` 以 `redirect: 'error'` 把查询连同模型、token 上限与可选新近程度过滤条件 POST 到 `{baseURL}/chat/completions`。响应的 `content` 变为 `content`；存在 `search_results[]` 时它变为 `sources[]`，否则每个 `citations[]` 条目变为只含 URL 的来源；服务在返回路径上应用最终的 `maxResults` 上限。中止——名为 `AbortError` 的 `DOMException`——变为 `WEB_ABORTED`；其余情况变为 `WEB_PROVIDER_ERROR`。
|
|
92
|
+
|
|
93
|
+
</details>
|
|
94
|
+
|
|
95
|
+
-----
|
|
96
|
+
|
|
97
|
+
<a id="further-exploration"></a>
|
|
98
|
+
## 进一步探索
|
|
99
|
+
|
|
100
|
+
当包级约定不够用时阅读以下页面。它们从共享词汇逐步进入服务、面向模型的工具与设计依据。
|
|
101
|
+
|
|
102
|
+
- [web 子系统](../../../docs/subsystems/web.zh.md)——穷尽式的搜索请求／结果词汇与错误码。
|
|
103
|
+
- [web 包映射](../README.zh.md)——六包家族与各角色。
|
|
104
|
+
- [dsh-web](../web/README.zh.md)——本提供方注册进入的 web 服务。
|
|
105
|
+
- [dsh-tool-web](../tool-web/README.zh.md)——渲染本提供方来源的面向模型 `web_search` 工具。
|
|
106
|
+
- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-perplexity)——每个受支持配置字段及其源声明。
|
|
107
|
+
- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
|
|
108
|
+
|
|
109
|
+
-----
|
|
110
|
+
|
|
111
|
+
<a id="model-experience"></a>
|
|
30
112
|
## 模型体验
|
|
31
113
|
|
|
32
114
|
### 辅助 Perplexity 请求
|
|
@@ -37,7 +119,7 @@
|
|
|
37
119
|
|
|
38
120
|
#### Token 影响
|
|
39
121
|
|
|
40
|
-
|
|
122
|
+
每次搜索都会产生独立的提供方 token；`maxTokens` 限制生成答案。
|
|
41
123
|
|
|
42
124
|
#### KV Cache 影响
|
|
43
125
|
|
|
@@ -47,19 +129,38 @@
|
|
|
47
129
|
|
|
48
130
|
#### 模型看到的内容
|
|
49
131
|
|
|
50
|
-
通过
|
|
132
|
+
通过 `dsh-tool-web`，会话模型会看到生成答案及结构化结果元数据，或只含 URL 的引用。该提供方确切的错误消息为 `Perplexity search aborted`、`Perplexity search request failed: <error>` 和 `Perplexity returned an unprocessable response body: <error>`；HTTP 失败保留提供方消息。错误包装层属于消费方。
|
|
51
133
|
|
|
52
134
|
#### Token 影响
|
|
53
135
|
|
|
54
|
-
注册不会直接产生会话 token
|
|
136
|
+
注册不会直接产生会话 token。答案与来源 token 取决于数据，来源数量受服务限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
|
|
55
137
|
|
|
56
138
|
#### KV Cache 影响
|
|
57
139
|
|
|
58
140
|
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
|
|
59
141
|
|
|
60
|
-
##
|
|
142
|
+
## 已知限制与延期工作
|
|
143
|
+
|
|
144
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
这些限制说明提供方在哪些情况下不合适。它们是当前包约束。
|
|
148
|
+
|
|
149
|
+
- **引用回退来源只含 URL**——Perplexity 省略结构化 `search_results[]` 时，来源不含 `title`／`snippet`／`publishedAt`，因此工具只渲染纯主机名标签。
|
|
150
|
+
- **超量返回的来源仍会增加 token 消耗与延迟**——协议没有结果数量控制，`maxResults` 只能由服务在事后截断。
|
|
151
|
+
- **只公开 `model`／`maxTokens`／`searchRecency`**——Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关的服务字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)）。
|
|
152
|
+
- **按错误形状分类中止**——只有名为 `AbortError` 的 `DOMException` 才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）呈现为 `WEB_PROVIDER_ERROR`。
|
|
153
|
+
|
|
154
|
+
<a id="dev-note"></a>
|
|
155
|
+
### 开发备注
|
|
156
|
+
|
|
157
|
+
<details>
|
|
158
|
+
<summary>维护者的工作上下文——点击展开</summary>
|
|
159
|
+
|
|
160
|
+
本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和相关 Agent Note 为准。
|
|
161
|
+
|
|
162
|
+
#### 未来：更宽的 Perplexity 控制面
|
|
163
|
+
|
|
164
|
+
Perplexity 的域名过滤条件、`web_search_options` 上下文大小与图片支持仍未公开。公开它们需要先有提供方无关的服务字段，让家族以一个协调一致的控制项、而非厂商专有参数的方式新增。
|
|
61
165
|
|
|
62
|
-
|
|
63
|
-
- **超量返回的来源仍会增加 token 消耗和延迟**：协议没有结果数量控制，`maxResults` 只能由 seam 在事后截断。
|
|
64
|
-
- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）有待提供方无关的 Service Definition 字段支持（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)）。
|
|
65
|
-
- **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
|
|
166
|
+
</details>
|
package/lib/index.js
CHANGED
|
@@ -117,10 +117,8 @@ function isPositiveInteger(value) {
|
|
|
117
117
|
//#endregion
|
|
118
118
|
//#region lib/types/index.js
|
|
119
119
|
/**
|
|
120
|
-
*
|
|
121
|
-
* `
|
|
122
|
-
* default-export service): it registers INTO the seam's provider registry, like
|
|
123
|
-
* `@deepseek-ai/dsh-llm-deepseek` registers an adapter into `ctx.llm`.
|
|
120
|
+
* Perplexity-backed `WebSearchProvider` plugin. It contributes to the
|
|
121
|
+
* `ctx.web` registry without owning the service.
|
|
124
122
|
*
|
|
125
123
|
* @module @deepseek-ai/dsh-web-search-perplexity
|
|
126
124
|
*/
|
package/lib/types/index.d.ts
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* `
|
|
4
|
-
* default-export service): it registers INTO the seam's provider registry, like
|
|
5
|
-
* `@deepseek-ai/dsh-llm-deepseek` registers an adapter into `ctx.llm`.
|
|
2
|
+
* Perplexity-backed `WebSearchProvider` plugin. It contributes to the
|
|
3
|
+
* `ctx.web` registry without owning the service.
|
|
6
4
|
*
|
|
7
5
|
* @module @deepseek-ai/dsh-web-search-perplexity
|
|
8
6
|
*/
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@deepseek-ai/dsh-web-search-perplexity",
|
|
3
3
|
"description": "Perplexity-backed search provider for the DeepSeek Harness web capability seam (ctx.web)",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.2-alpha.3",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
7
7
|
},
|
|
@@ -32,18 +32,18 @@
|
|
|
32
32
|
],
|
|
33
33
|
"license": "MIT",
|
|
34
34
|
"peerDependencies": {
|
|
35
|
-
"@deepseek-ai/dsh-launch-environment": "^0.1.
|
|
36
|
-
"@deepseek-ai/dsh-invariants": "^0.1.
|
|
37
|
-
"@deepseek-ai/dsh-web": "^0.1.
|
|
38
|
-
"@deepseek-ai/cordis": "^4.0.
|
|
35
|
+
"@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.3",
|
|
36
|
+
"@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
|
|
37
|
+
"@deepseek-ai/dsh-web": "^0.1.2-alpha.3",
|
|
38
|
+
"@deepseek-ai/cordis": "^4.0.2"
|
|
39
39
|
},
|
|
40
40
|
"dependencies": {
|
|
41
|
-
"@deepseek-ai/schemastery": "^3.18.
|
|
41
|
+
"@deepseek-ai/schemastery": "^3.18.2"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
-
"@deepseek-ai/dsh-launch-environment": "^0.1.
|
|
45
|
-
"@deepseek-ai/dsh-invariants": "^0.1.
|
|
46
|
-
"@deepseek-ai/dsh-web": "^0.1.
|
|
47
|
-
"@deepseek-ai/cordis": "^4.0.
|
|
44
|
+
"@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.3",
|
|
45
|
+
"@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
|
|
46
|
+
"@deepseek-ai/dsh-web": "^0.1.2-alpha.3",
|
|
47
|
+
"@deepseek-ai/cordis": "^4.0.2"
|
|
48
48
|
}
|
|
49
49
|
}
|