# deep-search-research

Adopt this skill: https://proskills.md/skills/other/canxia-hub-deep-search-research

Page: https://proskills.md/skills/other/canxia-hub-deep-search-research
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 9782
upstream: https://github.com/canxia-hub/deep-search-research/blob/HEAD/SKILL.md

````text
---
name: deep-search-research
description: Research-agent workflow for deep multi-source search, platform-aware routing, source normalization, evidence tracking, and structured report delivery. Use when the user asks to perform or build deep research across the web or multiple platforms; when a task needs a research plan before searching; when results must include citations, source credibility, or cross-platform synthesis; or when building/iterating a deep-search skill, adapters, retrieval pipelines, or research reports.
---

# Deep Search Research

## Overview

Use this skill to run or build a **research-style deep search workflow** instead of a plain keyword search. Treat the task as: **goal → plan → route → collect → normalize → rank → synthesize → report**.

Read additional references only when needed:
- For the end-to-end operating flow, read `references/workflow.md`.
- For payload formats and persistent artifacts, read `references/data-contracts.md`.
- For platform tiering and routing strategy, read `references/platform-strategy.md`.
- For current scoring, routing, reranking, and authority-calibration scaffolds, read `references/quality-layer.md`.
- For the finishing review and product-grade acceptance gates, read `references/review-procedure.md`.
- For local OpenSearch bring-up and diagnostics, read `references/local-opensearch-setup.md`.

## Quick start

### When executing a research task
1. Turn the user request into a research goal with explicit scope.
2. Generate a plan before searching.
3. Pick platforms and strategy by risk + access level:
   - `federated` for API-friendly/open sources
   - `indexed` for curated/topic indexes
   - `hybrid` when both are needed
4. Collect from the cheapest reliable path first:
   - API → index → HTTP → browser crawl
5. Normalize early.
6. Rank for evidence quality, not raw volume.
7. Deliver a report, not a pile of links.

### When building or iterating this skill
1. Update the technical contract first.
2. Keep `SKILL.md` lean; move detailed schemas and routing rules into `references/`.
3. Put deterministic helpers in `scripts/` and test them after edits.
4. Do not assume all platforms are equal—route by platform tier and risk mode.

## Workflow decision tree

### 1. Is the user asking for research or for skill development?
- **Research execution**: follow the runtime workflow below.
- **Skill design / implementation**: update contracts, adapters, and report pipeline skeleton first.

### 2. Does the task need a plan?
- **Yes, if multi-step / high-stakes / cross-platform**: generate a plan explicitly.
- **No, if small and obvious**: still create a minimal plan artifact internally.

### 3. Which retrieval path should you use?
- Use **federated** for GitHub / HN / arXiv / Semantic Scholar style sources.
- Use **indexed** for curated or unstable sources.
- Use **hybrid** when platform search alone is insufficient.

## Runtime workflow

### Step 1: Create a plan
Use `scripts/plan_research.py` to generate a deterministic plan skeleton when useful.

Example:
```bash
py scripts/plan_research.py "研究开源 AI 编码助手生态" --mode compliant
```

The generated plan should capture:
- goal
- sub-questions
- platform hints
- strategy per step
- include/exclude domains
- risk mode

### Step 2: Route by platform
Use the platform tiers in `references/platform-strategy.md`.

Default order:
1. Tier 1 open platforms
2. Tier 2 controlled expansion
3. Tier 3 high-risk sources only with explicit need and matching safeguards

### Step 3: Normalize findings
Convert all results into a uniform document shape before ranking or report writing. Use the `NormalizedDocument` contract from `references/data-contracts.md`.

### Step 4: Rank for evidence
Prefer:
- official / primary sources
- academic sources
- high-signal technical sources
- cross-source agreement

Apply:
- dedup
- source merge
- primary-source boosting
- credibility marking

### Step 5: Deliver a structured report
Use `scripts/render_report.py` to render Markdown from structured JSON when you already have synthesized findings.

Example:
```bash
py scripts/render_report.py report.json --output report.md
```

Preferred report behavior:
- `product-comparison` questions should emit a **structured comparison matrix** and a short **dimension-delta summary**.
- `risk` questions should emit a **risk consistency judgment**, a **risk consistency matrix**, and a **claim-lineage style summary** showing support vs. mitigation evidence.
- All major claims should stay source-traceable through citations or structured evidence blocks.

Default report sections:
- 执行摘要
- 关键发现
- 证据与引用
- 限制与边界
- 后续研究问题
- 来源列表

## Guardrails

- Do not treat deep search as unrestricted crawling.
- Prefer API over crawl, and HTTP over full browser automation when possible.
- Do not default to high-risk platforms or aggressive acquisition modes.
- Mark uncertainty explicitly when coverage is partial.
- Preserve source traceability so every major claim can point back to evidence.

## Resources

### scripts/
- `plan_research.py`: generate a deterministic research-plan skeleton.
- `render_report.py`: render Markdown research reports from structured JSON.
- `run_mvp_research.py`: run the current open-platform MVP pipeline end-to-end.
- `opensearch_backend.py`: emit OpenSearch mapping and provide the MVP OpenSearch client integration layer.
- `check_opensearch_ready.py`: probe whether a local OpenSearch endpoint is actually reachable and usable.
- `github_adapter.py`, `hackernews_adapter.py`, `arxiv_adapter.py`, `semantic_scholar_adapter.py`: first-wave platform adapters.
- `adapter_registry.py`, `query_router.py`, `quality_layer.py`: routing and quality-layer core.
- `query_understanding.py`: language/region-aware query understanding and platform-specific query construction.
- `question_classifier.py`, `evidence_clustering.py`: question typing and evidence clustering for report shaping.
- `review_pipeline.py`: finishing review gates for report quality and trustworthiness.
- `embedding_stub.py`, `reranker_stub.py`: semantic-provider abstraction with graceful fallback when real providers are not configured.
- `.env.example`: local configuration template for embedding / reranker / OpenSearch inputs.

### references/
- `workflow.md`: concise runtime workflow and delivery rules.
- `data-contracts.md`: core payload formats for plan, document, evidence, and report.
- `platform-strategy.md`: platform tiering, routing guidance, and risk-aware defaults.

---

## 研究规范（建议采用）

以下规范用于提升研究质量和报告可信度，作为**建议性内容**，可根据任务复杂度选择采用。

### 任务分类指南

在开始研究前，先将任务归入以下模式：

| 模式 | 特征 | 示例 |
|------|------|------|
| **快速事实查询** | 单一问题，最短路径 | 某公司 CEO 是谁？某标准最新版本？ |
| **当前动态查询** | 获取最近变化 | 今天发生了什么？某法规是否更新？ |
| **实体研究** | 围绕实体综合检索 | 某公司产品路线与融资情况 |
| **深度研究** | 多维问题，跨来源验证 | 某行业供给格局、竞争态势 |
| **核查/证伪** | 判断说法是否成立 | 某 API 是否已弃用？某政策是否生效？ |

### 时效性判定规则

凡是**有超过 10% 概率已变化**的信息，必须联网核验：

- 新闻、价格、规则、政策
- 产品规格、版本、优惠
- 人物职位、比赛结果
- 门店、餐馆、旅行信息

#### 时效性判断流程

1. 判断信息类型是否易变
2. 若易变，检查来源时间
3. 若来源时间 > 时效窗口，必须重新搜索
4. 标注信息的时效性边界

### 证据链规范

#### 来源分级

| 级别 | 类型 | 示例 | 可信度 |
|------|------|------|--------|
| 1 | 官方/原始 | 官方公告、法规原文、论文原文、招股书 | 最高 |
| 2 | 权威机构 | 研究机构、专业出版社、监管机构 | 高 |
| 3 | 主流媒体 | 高质量新闻媒体、专业数据库 | 中高 |
| 4 | 二手来源 | 转引、摘要、博客 | 中 |
| 5 | 社交/论坛 | Twitter、Reddit、论坛帖子 | 低（仅作线索） |

#### 证据链要求

| 风险等级 | 来源要求 |
|----------|----------|
| 低风险（普通事实） | ≥1 个高可信来源 |
| 中风险（重要结论） | ≥2 个独立来源，其中 1 个为官方/原始 |
| 高风险（决策依据） | ≥2-3 个来源，必须含原始来源 |

### 来源冲突处理

当不同来源说法不一致时：

#### 处理流程

1. **识别冲突点** — 具体哪个事实有分歧
2. **记录各方说法** — 每个来源分别怎么说
3. **比较来源质量** — 发布时间、类型、可信度
4. **标注不确定** — 暂不能下定论时明确说明

#### 输出模板

```markdown
⚠️ 来源冲突：

**冲突点**：[具体事实]

**来源 A**：[说法]（来源类型，发布时间）
**来源 B**：[说法]（来源类型，发布时间）

**判断**：[可信度分析]
**结论**：目前无法确定 / 倾向于 [来源]
```

### 不确定性披露规范

#### 必须披露的场景

在以下场景必须显式披露不确定：

- 来源冲突
- 仅有单一非官方来源
- 页面不可访问/抽取失败
- 最新信息可能尚未公开
- 结论依赖推断

#### 披露格式

```markdown
⚠️ 不确定性说明：

**不确定点**：[具体内容]
**原因**：[为什么不确定]
**影响范围**：[对结论的影响]
**建议**：[如何进一步核验]
```

### PDF/图表处理规范

#### 原则

- 纯文本能读取时，优先文本抽取
- 图表、扫描件、复杂表格，必须视觉确认
-
````

## File: README.md
upstream: https://github.com/canxia-hub/deep-search-research/blob/HEAD/README.md

```text
# Deep Search Research v2 · OpenClaw

当前Agent驱动的多轮研究与证据综合技能；默认通过quick-web-search v2共享检索/正文阅读底座，旧MVP/OpenSearch/语义后端仅为保留的legacy选项。

## 安装

需要同级安装[quick-web-search v2](https://github.com/canxia-hub/quick-web-search)及其requirements.txt中的依赖：

~~~text
skills/
  quick-web-search/
  deep-search-research/
~~~

如底座在其他位置，SEARCH_V2_HOME应指向quick-web-search仓库或技能根目录。本技能不会下载底座、安装服务或自动启用付费模型。

## 使用

用户以自然语言提出研究、比较或带来源报告；Agent负责查询拆解、读取证据、回查缺口与最终综合。CLI示例从本仓库根目录执行，Windows可用py替代python：

~~~shell
python scripts/research.py "AI 视频制作 工作流 教程" --sources wechat,bilibili,xiaohongshu,web --output ./research-output
python scripts/research.py "AI 视频制作 工作流 教程" --resume ./research-output/checkpoint.json --output ./research-output
~~~

默认总工作预算300秒，快速search为30秒工作预算；这是工作上限/目标，不是全负载SLA。平台登录与限流边界、取消/缓存/配置及正文契约以quick-web-search/SKILL.md为准。

## 产物

- report.json：结果、traces、平台覆盖、读取documents/evidence及缺口。
- checkpoint.json：同问题续跑；成功读取可复用，未成功内容仍须回查。
- report.md：检索证据包，不是已经完成事实综合的LLM报告。
- body/pdf_text/transcript/metadata/none分级，逐段定位、时间码与失败状态保持原样。

最终报告由当前Agent写作，区分事实、推断、冲突和未知项；不把摘要、简介、索引线索当全文。

## 兼容与验证范围

scripts/research.py为v2薄入口；旧run_mvp_research.py、OpenSearch与embedding/rerank流程保留、不自动运行、不对旧入口套用新预算。v2默认仅词法排序，不能将旧版历史语义验收当本版本默认能力证明。

2026-10-04已通过真实共享入口与同问题续跑验证；平台代表样本和限制见quick-web-search的[发布验收](https://github.com/canxia-hub/quick-web-search/blob/master/docs/SEARCH-V2-ACCEPTANCE.md)。详情：[SKILL.md](SKILL.md)；版本：[CHANGELOG.md](CHANGELOG.md)。

许可证：MIT（LICENSE）；安全策略：SECURITY.md。历史参考保留在docs/与references/，其中旧流程说明不替代当前v2指引。
```
