可验证来源检索f0909172434/dsh-plugin-verified-search

dsh-plugin-verified-search

CI
Release
License

English · 繁體中文 · 简体中文

为 DeepSeek Harness 提供可审计的当前来源检索。

本插件会替换具备搜索能力的 agent 所继承的 web_search，改用有界工作流，让来源范围、保留证据、确定性的 JSON 选择和未解缺口都清晰可见。它是 deepseek-harness Discussion #332 的可安装配套，也会挂载 Discussion #344 讨论的时间上下文。

它验证的是工作流和 structured-source postcondition，不会认证 publisher 的内容一定正确，也不保证上游搜索索引永远最新。

有界证据工作流架构

发布状态

| 产品线 | 安装 ref | Model-facing 工具 | 验证边界 |
| --- | --- | --- | --- |
| 稳定版 | v0.1.1 | verified_search | 维护者验证的 release tag，包含软件包 artifact、checksums、跨平台 CI、干净 profile 安装和已记录的真实 provider conformance |
| 实验快照 | c29b531a6c2e52200d454aa9ded42214ba8c0014 | 下列全部五个工具 | 2026-08-16 当时最后一个绿色 main 快照；250 tests 和 42-case frozen offline corpus 全部通过 |
| 移动中的 main | main | 未发布开发代码 | 不要在可复现测试中直接安装；不同 commit 之间的行为和 generated artifacts 可能变化 |

外部独立验证：暂无。 Repository 提供内部 deterministic tests、CI、package reproducibility checks 和维护者执行的 conformance evidence；这些信号不会被描述成第三方审查。

前置要求

- DeepSeek Harness 0.1.1-rc.2 和 Cordis 4.0.1。官方 0.1.2-alpha.1 已做源码层级审查，本插件消费的 API 面均无破坏性变更；待其发布到 npm 后，exact peer contract 会随之推进。
- Node.js 22.19.x 或 24.x。
- 通过 Harness credential service 或启动环境提供 DEEPSEEK_API_KEY。
- 使用原本就有搜索能力的 preset；本插件不会给内置 minimal preset 扩权。
- 可与 dsh-web 生态全家桶（@linxin666/dsh-web-all）及 dsh-deepseek-girl-pet 共存在同一个 web profile：已用官方 @deepseek-ai/cordis-plugin-include 验证五层 patch 叠加（169 个 entries，零重复 id、零缺漏、零警告），生态套件没有注册 web_search、没有挂 time-context，HTTP 路由也无碰撞。
- CI 覆盖 Ubuntu 和 Windows；macOS 目前不属于正式支持契约。

更换 Harness、Cordis、Node 或 package-manager 版本前，请先阅读兼容性契约。

一分钟安装

稳定版 verified_search

dsh plugin --profile web add github:f0909172434/dsh-plugin-verified-search#v0.1.1
dsh --profile web --dump-config
dsh web

等价的单行 PowerShell 命令：

dsh plugin --profile web add github:f0909172434/dsh-plugin-verified-search#v0.1.1; dsh --profile web --dump-config; dsh web

Release 已提交 prebuilt lib/，并且没有 install-time build script；固定 Git ref 安装时，不会在用户机器上执行本 repository 的开发工具链。

五工具实验快照

dsh plugin --profile web add github:f0909172434/dsh-plugin-verified-search#c29b531a6c2e52200d454aa9ded42214ba8c0014
dsh --profile web --dump-config
dsh web

该快照只适合开发和评估。需要可复现结果时，不要把明确 commit 替换为会移动的 main。

如果 deployment 已挂载 Discussion #344 的 time-context row，请在启动 Harness 前设置 DSH_VERIFIED_SEARCH_DISABLE_TIME_CONTEXT=1，避免重复的 clock injector。

回滚

dsh plugin --profile web remove dsh-plugin-verified-search
dsh web

最小 quickstart

向具备搜索能力的 agent 提出有界、带绝对日期的问题，例如：

找出截至 2026-08-14 的 DeepSeek 当前旗舰 API model。只使用 api-docs.deepseek.com。如果保留来源没有包含答案的 excerpt，请报告 unresolved，不要用记忆补答案。

对应的 model-facing verified_search arguments：

{
"query": "DeepSeek current flagship API model as of 2026-08-14",
"allowed_domains": ["api-docs.deepseek.com"]
}

预期行为：

- 将原生 provider allowlist 发送给上游；
- 在本地按照精确 hostname 或 subdomain 对返回的 structured sources 再做 postfilter；
- credential-bearing URL 和敏感／跟踪 URL 组件会在组成 session-visible 结果前被拒绝或移除；
- 只有标题或 URL、却没有保留 citation excerpt 的来源，不会升级为已验证证据；
- 证据缺口会保持可见，不会被旧答案或模型记忆替代。

需要独立比较来源时，另做一次不限制 domain 的查询。Allowlist 是“返回 structured-source hostname”的 postcondition，不是 network-egress 或 privacy boundary。

选择正确工具

| 工具 | 适合的任务 | 有界结果 |
| --- | --- | --- |
| verified_search | 单一、狭窄、会变化的事实查询 | Structured-source hostname postfilter，citation excerpt 缺口保持可见 |
| verified_research | 多实体或多 claim 研究 | 每个 claim 的保留 excerpt、retrieval metadata、content hash 和明确 unresolved claims |
| verified_json_selection | 从官方 JSON feed 做 latest／as-of 选择 | 严格 RFC 6901、日期 cutoff、最大日期和全部 final ties |
| verified_json_numeric_extrema | JSON 的精确数值最大／最小值 | 直接比较 source lexeme、不经过 IEEE-754，并保留全部 final ties |
| verified_json_projection | 按来源顺序取得全部严格匹配 JSON rows | 有界 parent／nested projection、可审计 pointer repair、不推测排序语义 |

只有 verified_search 属于稳定的 v0.1.1。其余四个工具都属于固定 0.3.0-experiment.0 快照中的实验功能。

复合研究示例

{
"query": "Identify current flagship API model IDs as of 2026-08-14",
"lanes": [
{
"id": "deepseek",
"query": "DeepSeek current flagship API model ID as of 2026-08-14",
"required_claims": [
{
"id": "model_id",
"query": "latest DeepSeek flagship API model identifier",
"evidence_must_include": ["Model ID"],
"value_kind": "generic_text",
"scope": {"kind": "document", "must_include": ["DeepSeek"]}
}
],
"allowed_domains": ["api-docs.deepseek.com"],
"seed_urls": ["https://api-docs.deepseek.com/api/list-models/"],
"gap_query": "site:api-docs.deepseek.com/api/list-models model IDs 2026-08-14"
}
]
}

evidence_must_include 是规范化 substring postcondition，不是语义 entailment 裁判。不要把未知答案本身放进 required phrase，只为了确认模型自己的猜测。

失败行为

本插件会 fail closed，或者把状态保持为明确 unresolved。

- 无效 hostname allowlist、credential-bearing URL、不安全 redirect、非 public resolved address、不支持 media、错误 charset 声明、无效 UTF-8 和资源上限违规，都会产生可见失败。
- Structured JSON 操作会拒绝无效 JSON、duplicate key、过深 nesting、无效 pointer、缺少字段、不支持的 numeric projection、row／tie／output 超限，以及无法取得 exact number lexeme 的 runtime。
- Discovery 可以跳过已知 binary path；明确提供但不支持的 binary seed 会留下可见失败，不会被静默重新解释。
- Provider 或 fetch timeout 会中止有界工作，并保留证据缺口。
- allClaimsCovered、complete: true 或 truncated: false 只描述声明的有界操作；不证明来源新鲜度、语义 entailment、publisher authenticity、feed completeness 或 pagination 已耗尽。

信任与安全边界

本插件可以保证：本地过滤后返回的 structured sources 符合明确 hostname allowlist。实验版完整页面 reader 还会把抓取限制在有界 public HTTPS target，并执行 DNS/IP validation、pinned transport、redirect checks、text/JSON media 和 charset validation，以及 byte/time limits。

它不能证明：

- provider 的私有 candidate pool 或生成 prose 只使用 allowlist；
- provider 没有自行抓取其他页面或跟随 allowlist 以外的 redirect；
- 上游索引一定包含最新页面，或时间 ranking 正确；
- 保留的 phrase 已在语义上支持 claim，或者能正确处理否定；
- caller 指定的 seed URL 一定 canonical、first-party 或 authoritative；
- API response 真实、完整、没有 pagination、排序语义正确或事实正确；
- public page 的文字可以安全地当作指令执行。

Search query 会成为 durable Harness session data。不要把 secret、signed URL 或私人数据放入 query。私密报告和完整 threat boundary 请见 SECURITY.md。

验证快照

固定的实验快照记录：

- source commit：c29b531a6c2e52200d454aa9ded42214ba8c0014；
- push CI：Ubuntu 和 Windows、Node 22.19.x 和 24.x 全部通过；
- HonestCI baseline：250 tests，0 failures、0 errors、0 skipped；
- frozen offline corpus：42/42 cases；
- registered offline result digest：sha256:3002001da02d0b8501bcc97ee867109f1bfbf0e1a227d87845db81da658ea5c0；
- committed lib/ 和 package-content reproducibility checks；
- 外部独立验证：暂无。

Machine-readable 的 lifecycle、runtime、capability 和 architecture facts 位于 capabilities.json 和 architecture.json。评估方法请见 docs/OFFLINE_EVALUATION.md、docs/PROPERTY_TESTING.md 和 docs/HONEST_CI_DOGFOOD.md。

实测观察

两个困难官方来源任务的完成率变化

两个 frozen-ledger live tasks 在 600 秒外层上限下得到以下单次观察：

| 任务 | 修正前 | 实验工作流 | Terminal 时间 |
| --- | ---: | ---: | ---: |
| Go 支持 releases、security scope 和 Linux artifact provenance | 0/8 | 8/8 | 317 秒 |
| EU AI Act 修法时间线和 GPAI 过渡期限 | 0/8 | 6/8 | 307 秒 |
| 合计 | 0/16 | 14/16（87.5%） | — |

已回答的 14 个 requested fields 都有保留的官方来源证据；另外两个字段保持 unresolved。这些只是单次观察，不是标准化 benchmark、统计估计、latency target 或 release guarantee。两次成功 terminal run 都超过 240 秒，因此 timeout 和 latency 仍是重要改进方向。

配置

Bundle 可以从 Harness credential service 或 launch environment 读取 DEEPSEEK_API_KEY。可选配置包括：

| 类别 | Fields |
| --- | --- |
| Provider | apiKeyEnv、apiKey、baseURL、model、apiVersion |
| Search limits | maxTokens、maxUses、maxResults、searchTimeoutMs |
| Experimental research | researchTimeoutMs、researchMaxResults |

researchMaxResults 默认为 24，范围 4–32，并且不得低于本次调用声明的 claim count。配置变更属于 compatibility 和 resource-boundary 变更，不只是性能调参。

开发和完整验证

pnpm install --frozen-lockfile --ignore-scripts
pnpm run check
pnpm test
pnpm run build
pnpm run evaluate:offline
npm pack --dry-run --ignore-scripts --json
git diff --check
git diff --exit-code -- lib

第二次 build 不得产生新的 lib/ diff。Frozen offline digest 发生变化代表可能存在行为变更；不要只为让 CI 变绿就更新 expected digest。

文档

- 架构和 ownership boundaries
- 兼容性契约
- Frozen offline evaluation
- Property-testing contract
- HonestCI dogfooding evidence
- 单人串行维护 roadmap
- 维护规则
- 安全策略
- 变更记录

与上游核心修复的关系

本 repository 是可部署的 compatibility layer。Provider-neutral Harness core change 仍位于 ce4d0455c。如果官方项目发布等价的有界能力，本插件可以转为额外验证模式，或通过有文档的 migration path 退役。

安全报告

如果怀疑存在 credential leak、allowlist bypass 或 unsafe page-fetch path，请使用本 repository 的 GitHub private security-advisory interface。不要把 API key、signed URL、私人 query、私人 excerpt 或 raw session log 粘贴到 public issue。

License

MIT