Skip to main content Home Creators mingchen666 reviva deep-research
deep-research Deep research report generation for Reviva's built-in deep-researcher agent. Use for learning and education research, teacher preparation research, document-based synthesis, literature/source reviews, office research, industry analysis, competitor scans, policy interpretation, and any request for a cited long-form research report.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/mingchen666/Reviva --skill deep-researchThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
concept-visualization-generator Design and generate concept-first learning artifacts: concept cards, visual explanations, diagrams, interactive HTML demos, Manim/math visualizations, matplotlib scientific plots, misconception checks, and short retrieval practice. Use this skill whenever the user wants to understand, teach, review, visualize, make a knowledge card for, or interactively explore a concept, especially when the best output format is not obvious. This skill should choose and orchestrate the right learning artifact instead of defaulting to plain text, video, or HTML.
Related occupations SOC
Based on SOC occupation classification
name deep-research description Deep research report generation for Reviva's built-in deep-researcher agent. Use for learning and education research, teacher preparation research, document-based synthesis, literature/source reviews, office research, industry analysis, competitor scans, policy interpretation, and any request for a cited long-form research report. allowed-tools file_read, file_write, document_read, kb_search, web_search_bing version 3.0.0 updated 2026-06-08T00:00:00.000Z risk medium author hoolulu repository https://github.com/hoolulu/deep-research
deep-research
生成对标券商/第三方研究机构标准的深度调研报告。
架构 ：主 agent 调度 4 个子 agent Task（大纲/数据/预检/装配）+ 1 轮主控并行派发章节，中间数据走临时文件数据源 ：在线模式 → 根据 Reviva 当前可用工具自适应使用 web_search_bing、mcp:exa、mcp:jina-mcp-server、SearXNG 或其他搜索/网页读取工具 → 按质量触发来源补强；离线模式 → 用户指定的本地文件（md/txt/pdf/docx/pptx/xlsx）安装 ：见下方「安装与配置」输出 ：$TMPDIR/outline.json（临时，非最终报告）最终报告 ：Reviva 中保存到 /agents/deep-researcher/outputs/{今天日期}/参考文件 ：RULES.md（硬约束/反模式）、TYPES.md（分类标准/编号规范）、profiles.json（三档模式参数，修改后重启软件即全局生效）容错原则 ：调研不阻塞。所有脚本/命令调用必须有兜底路径。主路径失败 → 自动尝试替代方案（换 sys.executable/检查路径/直接 Python 实现）→ 三次失败后向用户报告具体问题。详见「容错原则」。
Reviva 内置适配规则
本 skill 在 Reviva 中作为 deep-researcher 的专属核心技能使用。执行时优先遵循这些规则：
/skills/deep-research/ 是只读技能目录，只能读取 SKILL.md、RULES.md、TYPES.md、profiles.json、prompts/、tools/ 等参考资源；不要在 skill 目录内写入、删除、更新 reports/ 或 reports-browser/。默认输出目录是 /agents/deep-researcher/outputs/{今天日期}/。这是当前工作空间授权根目录下的 Reviva 虚拟路径，不是真实磁盘根目录。Markdown、HTML 等最终产物必须写到当前 Agent 的授权输出目录内。
默认临时目录是 /tmp/deep-researcher/{今天日期}/deep-research-{时间戳}/。/tmp/... 是当前工作空间授权根目录下的 Reviva 虚拟路径，不是真实系统临时目录。中间文件写到这里，不要构造宿主系统盘符路径、系统临时目录或平台特定绝对路径。
联网必须服从用户消息中的 [联网搜索] 开关。未启用联网时，不要调用搜索、网页读取、浏览器或抓取工具，并在报告中说明外部时效信息未校验。
web_search_bing、mcp:exa、mcp:jina-mcp-server、SearXNG、Scrapling、Python 辅助脚本都只是可选增强路线；没有任何单一搜索提供方是必需项。优先使用当前 Agent 实际绑定且可用的工具，不可用时改用其它搜索工具、kb_search、用户本地资料和模型已有知识完成研究，并明确标注覆盖范围。默认不要安装 Python 包、ASR 模型、浏览器自动化组件或抓取依赖。只有用户明确同意、当前 Agent 开启 exec_command 且工具可用时，才运行本 skill 附带的 Python 辅助脚本。
读取 Office/PDF 材料时优先使用 document_read，不要用 file_read 直接读取 .docx、.pptx、.xlsx、
.pdf
0. 支付级质量标准（所有 Task 共用，缺任何一项即降级） # 标准 说明 1 结论先行 每章以 > 引用格式 核心判断开头 2 来源可追溯 每个数字标注（机构，年份） 3 反方视角 至少 1 处呈现争议或反对观点 4 三层深度 事实层 → 因果层 → 判断层 5 零套话 无"近年来""值得注意的是"等填充词 6 标题含判断 "格局：高度集中"✅ | "行业概况"❌ 7 可自包含 首章必须定义核心概念 8 无内部编号 正文无任何流程编号，标题自解释 9 时间戳正确 文件名和报告尾时间必须 date 命令获取 10 目录源自大纲 目录从 outline.json 的第一级章节生成，不从正文提取 11 强制目录 报告正文前必须包含 ## 目录 标题及自动目录（TOC），列出所有章节标题 12 元数据完整 报告头部必须包含 总字数、阅读时间、数据截至日期（精确到月）、报告生成具体时间（精确到秒）、调研模式、Skill版本 六个字段，用 · 隔开。另起一行 > **参考来源**：{主要来源} 等 · 共引用 N 个来源。报告末尾须附 ## 参考来源（列出所有引用机构及链接）和 ## 免责声明。版本号从本 skill 的 VERSION 文件读取。 13 篇幅达标 见项目根目录 profiles.jsonprofiles.json 为准，修改后重启软件即全局生效。 14 四段式结构 顺序固定为：报告标题 → 元数据块（含六字段 + 参考来源行） → ## 目录 → 正文各章 → 尾部（参考来源 + 免责声明） 15 编码洁净 所有中间文件（outline.json / data-pool.json / chapter-*.md）必须使用 UTF-8 无 BOM 编码写入，不得出现替换字符（\ufffd）或 GBK→UTF-8 Mojibake。子 agent 在写入前必须自行验证编码洁净，不得将编码问题遗留到主 agent 16 纯文本公式 报告中不得使用 LaTeX/math 公式语法（$...$、$$...$$、\[...\] 等）。公式必须用纯文本或 Unicode 符号表达，确保复制到任何编辑器都不产生渲染问题
时间锚定规则 所有主题默认以 {CURRENT_YEAR} 为目标搜索最新数据。时间锚定模式在 Task 1 中由大纲 agent 按以下规则判定：
模式 符号 判定条件 target_year 验收 latest（默认）⏳ 所有主题的默认值 ，除非符合 relaxed 或 user_specified{CURRENT_YEAR}严格：≥50% 数据来自当年/前一年 relaxed（放宽）🔓 指南/教程/概念类主题，或用户问历史/原理（"草书发展""起源""背景"） {CURRENT_YEAR}宽松：标记旧数据但不过滤 user_specified📌 用户提问显式指定了年份/月份（"2025年""2026Q1""2020年至今"） 用户的指定年份 硬约束：>50% 匹配用户指定时间
{CURRENT_YEAR} 是动态变量，运行时通过 date +%Y 解析，无需手动修改。
1. 主 agent 调度流程 ⚠️ CRITICAL — DO NOT SPEAK BEFORE LANGUAGE DETECTION
Your VERY FIRST action (before anything else) must be: detect language → set $LANG.
Output NOTHING to the user until $LANG is set — no thinking aloud, no status messages.
After language is detected, ALL output must be in $LANG. Period.
IMPORTANT: Clean the topic before detection — the user input may contain framework wrapper text (e.g. "请使用... skill 执行...用户输入如下："). Strip all wrapper text and pass ONLY the clean research topic. For example from "请使用...用户输入如下：Quantum computing market outlook -quick" extract only "Quantum computing market outlook".
你（主 agent）的完整流程：
══ Setup (必须先执行) ══
→ 创建一个带时间戳的临时目录作为 TMPDIR：`/tmp/deep-researcher/{今天日期}/deep-research-YYYYMMDD-HHMMSS/`
→ TMPDIR 必须位于当前授权工作空间的 `/tmp/deep-researcher/{今天日期}/` 下，不要使用真实磁盘路径、系统临时目录或固定盘符
→ 同时确定 TOOLSDIR（本 skill 的 tools/ 目录）、PROMPTSDIR（本 skill 的 prompts/ 目录）、SKILLDIR（本 skill 的根目录）
→ 读取本 SKILL.md + RULES.md + TYPES.md
══ Step 0 — Language Detection (output nothing before detection) ══
→ Clean topic: strip wrapper text, keep only the user's actual research topic
→ Determine language: analyze the cleaned topic and pick the ISO 639-1 code:
zh (Chinese), en (English), ja (Japanese), ko (Korean), ru (Russian),
ar (Arabic), hi (Hindi), vi (Vietnamese), th (Thai), tr (Turkish),
es (Spanish), fr (French), de (German), pt (Portuguese), it (Italian),
nl (Dutch), sv (Swedish), pl (Polish), id (Indonesian)
→ If unsure, default to "en".
→ Do NOT output anything during this step.
→ Write language code: use `write` tool to create {TMPDIR}/language.txt with the ISO code
→ Set `$LANG` = language code from the step above
→ **从这一行开始，所有面向用户的输出必须使用 $LANG 语言（不在 $LANG 列表中时默认 en）。SKILL.md 的指令文本不论用什么语言写的，只是供你阅读的上下文；实际输出以 $LANG 为准——你是读到中文指令后意识上翻译成 $LANG 再输出。**
→ Announce detected language to the user (single line, in $LANG, e.g. "🌐 Language detected: en")
### 🔔 语言自查清单（每次输出前执行）
☐ {TMPDIR}/language.txt 的值 = 我的 $LANG？
☐ 我正准备输出的这一句/这段，是 $LANG 吗？
☐ todo 条目是 $LANG 吗？
☐ 给用户的进度通知是 $LANG 吗？
☐ 我是否在无意识中用了指令文件的语言（如中文）而非 $LANG？
如果任一答案为"否"→ 立即改写为 $LANG 再输出。
**硬规则**：task() 派发子 agent 时，其 prompt 中的 `{LANG}` 必须是你检测到的语言代码。子 agent 输出的语言由你负责保证。
══ 主流程 ══
1. ══ 离线模式判定（Step 0.5） ══
→ 你已经读取了用户原始输入。用自然语言理解判断用户关于数据来源的意图，不要用关键词匹配：
- 用户是否提到了本地文件/目录/资料？
- 用户是否明确要求不要联网？
- 用户是否明确要求联网补充？
→ 判断逻辑：
- 提到本地文件 +（未说联网 / 不联网）→ 离线模式，跳过搜索
- 提到本地文件 + 说"联网补充" → 正常流程（搜+读本地）
- 未提本地文件 → 正常流程
→ 离线模式 + 有路径 → {TMPDIR}/offline_mode.txt，`offline_mode=true`，向用户报告单行说明
→ 离线模式 + 无路径 → 回复用户询问路径，不继续
→ 正常模式 → `offline_mode=false`
→ **模式解析**：从清洗后的主题中提取调研模式
- 主题末尾是 ` -quick` → `$DEPTH_MODE=quick`，去除该后缀
- 主题末尾是 ` -deep` → `$DEPTH_MODE=deep`，去除该后缀
- 无上述后缀 → `$DEPTH_MODE=standard`（默认）
2. 记录任务开始时间到 {TMPDIR}/start_time.txt
3. todowrite 创建进度条目（使用 $LANG 语言）
4. ══ Task 1 — 分析主题 + 生成大纲 ══
→ 读取 {PROMPTSDIR}/task1_outline.md，替换 {TMPDIR} {TOOLSDIR} {LANG} {CURRENT_YEAR} {MODE}，注入 prompt
→ **只做变量替换，不添加语言、格式、报告结构等额外指令。语言已由 Step 0 判定为 $LANG 并在 prompt 中替换 {LANG}。**
→ 派发 task()，等待完成
→ 用 `read` 确认 {TMPDIR}/outline.json 存在
→ 从 outline.json 读取 title + chapter_count + depth_mode
→ todowrite 标记完成
→ 向用户报告进度（使用 $LANG 语言）
6. ══ Task 2 — 数据收集 + 结构化数据池 ══
→ 读取 {PROMPTSDIR}/task2_data_collection.md
→ 替换标准变量 {TMPDIR} {TOOLSDIR} {LANG} {COUNTRY}
→ 如果 `offline_mode=true`，额外替换：
{OFFLINE_MODE} → true
{LOCAL_PATHS} → 读取 {TMPDIR}/offline_mode.txt 的内容（路径列表）
→ 如果 `offline_mode=false`，替换 {OFFLINE_MODE} → false，{LOCAL_PATHS} → 空字符串
→ 派发 task()，等待返回
→ 如失败（task 报错或 task2_manifest.json 不存在），**自动重试 1 次**，重新派发。第二次仍失败则向用户报告并终止
→ 读取 {TMPDIR}/task2_manifest.json，提取 source_count + fact_count + search_engine + fetch_method + engines + free_fallback + english_fallback + unique_domains
→ todowrite 标记完成
→ 向用户报告进度（使用 $LANG 语言）
7. ══ Task 3 — 派发章节撰写 ══
→ 读取 {TMPDIR}/outline.json 获取 chapters 数组；读取 {TMPDIR}/data-pool.json
→ **读取 `profiles.json` 获取当前模式的 `max_chars`**，计算 `per_chapter_chars = max_chars ÷ chapters.length`
→ 从 data-pool.json 提取所有唯一 (src, yr) 组合，按首次出现顺序预分配引用编号 [1], [2], [3]...，写入 {TMPDIR}/citation_map.json
→ 读取 `{PROMPTSDIR}/task3_chapter_agent.md` 模板
→ **根据 $LANG 裁剪 prompt 中的多语言段落**：
- prompt 中的 `[LANG_en]` 段落：仅当 $LANG=en 时保留，其他语言删除
- prompt 中的 `[LANG_zh]` 段落：仅当 $LANG=zh 时保留，其他语言删除
- 删除标记文本本身（`[LANG_en]` `[/LANG_en]` 占位符行）
- 无标记的段落全部语言通用，保留
→ **撰写模式**：所有平台统一使用并行模式撰写章节
- **章节 agent 不做任何工具调用**（不跑 prepare-chapter、validate、manifest、word-count），只写文件
→ **并行派发章节**：
- 初始化空列表 task_ids = []
- For N = 1 to chapters.length:
- 读取 outline.chapters[N] 的 title、sections
- 从 data-pool.json 中筛选该章 sub_questions 对应的事实条目
- **将事实直接嵌入 prompt**：每条事实前标注预分配的 `[N]` 编号
- 调用 task(run_in_background=true) 并行派出每章
- 从 task 返回的元数据中提取 background_task_id（格式 bg_xxx），追加到 task_ids
- todowrite 标记该章 in_progress
- 将 task_ids 写入 {TMPDIR}/task3_bg_ids.json（持久化，防止主 agent 中断后丢失状态）
- 向用户报告："已并行派出 {N} 章，等待全部完成..."（使用 $LANG 语言）
- **结束 response，等待系统通知。仅当收到 [ALL BACKGROUND TASKS COMPLETE] 通知时，才继续到 Round 2。中间的单章完成通知忽略不处理。**
- 然后进入 Round 2：
**Round 2 — 收集结果 + 失败重写**：
- 读取 {TMPDIR}/task3_bg_ids.json 获取所有 background_task_id
- For 每个 bg_task_id in task_ids:
- 调用 background_output(task_id=bg_task_id) 收集章节结果
- 用 `read` 逐一确认 {TMPDIR}/chapters/chapter-{N}.md 是否存在且非空
- 如果有章节缺失或内容为空：
- 记录失败章节编号列表
- **串行重写**：对每个失败章节逐一重新派发 task(run_in_background=false)，同步等待完成
- 再次用 `read` 确认
- todowrite 标记每章 completed
- 向用户报告最终章节完成情况（使用 $LANG 语言）
8. ══ Task 4 — 验证 + 装配 + QA（**主 agent 直接执行**） ══
→ **Step 0 — 输出目录准备**：确定 `REVIVA_OUTPUT_DIR=/agents/deep-researcher/outputs/{今天日期}/`，并确定 `TMPDIR=/tmp/deep-researcher/{今天日期}/deep-research-{时间戳}/`。两者都是 Reviva 工作空间虚拟路径。不要清理或写入 `{SKILLDIR}/reports/`，不要使用宿主系统盘符路径。
→ **Step 1 — 批量验证**：`python {TOOLSDIR}/dr_tools.py validate-all-chapters --chapters-dir {TMPDIR}/chapters/ --chapters {chapter_count}`，内部 ThreadPoolExecutor 并行验证所有章节。从输出 JSON 的 `failed_chapters` 中找到失败章节，逐个重新生成（重新派发章节 agent → 重新验证该章）。
→ **Step 1b — 章节深度均衡检查**：`python {TOOLSDIR}/dr_tools.py depth-balance --chapters-dir {TMPDIR}/chapters/ --chapters {chapter_count}`。如果某章行数 < 平均值的 50%，标记告警（not blocking，仅提示）。
→ Step 1 或 Step 2 失败时，**先删除本次已写入的产物**（报告文件、中间文件等），再重新执行对应步骤，避免残留文件干扰下次运行
→ **Step 2 — 装配**：如果 `exec_command` 可用，运行 `python {TOOLSDIR}/dr_tools.py assemble-report --outline {TMPDIR}/outline.json --chapters-dir {TMPDIR}/chapters/ --datapool {TMPDIR}/data-pool.json --mode {depth_mode} --target-year {target_year} --output /agents/deep-researcher/outputs/{今天日期}/ --lang $LANG`；如果不可用，直接用 `file_write` 在该输出目录生成 Markdown/HTML 报告
→ **$REPORT 提取**：从装配输出中提取 `Report assembled: ...` 行中冒号后的第一个路径，设为 `$REPORT` 变量
→ **Step 2b — 可信评估(数据层)**：`python {TOOLSDIR}/dr_tools.py generate-confidence-section --datapool {TMPDIR}/data-pool.json --manifest {TMPDIR}/task2_manifest.json --report "$REPORT" --lang $LANG`
从输出中解析 `CONFIDENCE:` 行获取 `conf_coverage`、`conf_total_facts`、`conf_high_pct`、`conf_medium_pct`、`conf_low_pct`、`conf_actual_pct`、`conf_est_pct`、`conf_fct_pct`、`conf_auth_pct`、`conf_data_limited`、`conf_controversies`、`conf_adequate_subq`、`conf_total_subq`、`conf_score` 共 14 个变量。
→ **Step 2c — 可信评估(LLM判断)**：使用上一步的 14 个统计变量 + 报告标题（从 outline.json 读取）在 LLM 上下文内直接生成定性评估意见。
- 输出必须使用 $LANG 语言，2-4 句，纯定性判断，不重复逐项明细中的具体数字
- **语气校准（重要）**：本工具是开源信息综合项目，非付费研究报告。评估意见应遵循以下原则：
- **总分决定基调**：score≥75 → 正面肯定为主；50-74 → 中性平衡；<50 → 温和提醒
- **不说"缺陷""不足""未能"等负面措辞** → 改为"可进一步关注的方面""仍有补充空间"
- **不说"无法获取""受限于"** → 改为"部分高频量化指标因商业敏感性未纳入公开讨论范围"
- **不自我贬低**：不出现"门槛高""可信度大打折扣"等损害报告公信力的表述
- **正面收尾**：最后一句必须是肯定整体参考价值的结论
- **定位准确**：强调"综合公开信息形成的参考判断"而非"严谨学术研究"
- 写出到 `{TMPDIR}/llm_assessment.txt`
- 用 `edit` 工具将评估意见插入到报告可信评估区的 `**{综合评级标签}**` 行之后（追加 "**{评估意见标签}**：\n\n{文本}"），然后用 `read` 确认插入正确
- `{综合评级标签}` 和 `{评估意见标签}` 使用语言映射表中的翻译
→ **Step 3 — 数据受限处理**：读取 {TMPDIR}/task2_manifest.json 的 `data_limited` 字段。如果为 true，在报告标题后插入数据说明声明，**使用 $LANG 语言**。
→ **Step 4 — 引用处理**：`python {TOOLSDIR}/dr_tools.py convert-citations --datapool {TMPDIR}/data-pool.json "$REPORT" --lang $LANG`（从 data-pool 构建参考章节，验证正文 `[N]` 引用均有对应条目）
→ **Step 4b — 货币符号转义**：`python {TOOLSDIR}/dr_tools.py escape-currency "$REPORT"`（将 `$` 转义为 `\$`，避免被知乎/Obsidian/Typora 等渲染器错误解析为 LaTeX math mode）
→ **Step 5 — QA**：`python {TOOLSDIR}/dr_tools.py qa-report "$REPORT" --mode {depth_mode} --target-year {target_year} --lang $LANG`，解析 JSON 输出，从 `checks.word_count.count` 取字数，从 `checks.word_count.limit` 取上限
→ **Step 6 — Reviva 产物交付**：不要运行 `generate_pages.py --local` 更新 skill 内的 `reports-browser/`；最终 Markdown/HTML 文件留在 `/agents/deep-researcher/outputs/{今天日期}/`，由 Reviva artifact 规则扫描
→ todowrite 标记完成
→ ⏱ **强制计算总耗时**（读取 start_time.txt + 当前时间算差值）
→ 从 outline.json + task2_manifest.json + qa-report 中提取数据，使用 $LANG 语言汇报最终结果。
**语言自适应标签映射表**（以下所有 <词> 根据 $LANG 替换）：
| 中文 | en | ja | ko | fr | de | es | 其余语言 |
|------|----|----|----|----|----|----|---------|
| 执行总结 | Execution Summary | 実行サマリー | 실행 요약 | Résumé exécutif | Zusammenfassung | Resumen ejecutivo | Execution Summary |
| 阶段 | Stage | 段階 | 단계 | Phase | Phase | Fase | Stage |
| 详情 | Detail | 詳細 | 세부 | Détail | Detail | Detalle | Detail |
| 大纲/Plan | Plan | 概要 | 개요 | Plan | Plan | Plan | Plan |
| 观点速览/Insight | Insight | 洞察 | 인사이트 | Aperçu | Einblick | Perspectiva | Insight |
| 数据/Data | Data | データ | 데이터 | Données | Daten | Datos | Data |
| 报告/Report | Report | レポート | 보고서 | Rapport | Bericht | Informe | Report |
| 章 | ch | 章 | 장 | chap. | Kap. | cap. | ch |
| 来源 | sources | ソース | 출처 | sources | Quellen | fuentes | sources |
| 事实 | facts | 事実 | 사실 | faits | Fakten | datos | facts |
| 独立域名 | domains | ドメイン | 도메인 | domaines | Domains | dominios | domains |
| 行 | lines | 行 | 줄 | lignes | Zeilen | líneas | lines |
| 字 | chars | 語 | 단어 | mots | Wörter | palabras | chars |
| 分钟 | min | 分 | 분 | min | Min. | min | min |
| 生成时间 | Generated | 生成時刻 | 생성 시간 | Généré le | Erzeugt | Generado | Generated |
| 搜索 | Search | 検索 | 검색 | Recherche | Suche | Búsqueda | Search |
| 数据充足 | Adequate | 十分 | 충분 | Suffisantes | Ausreichend | Adecuado | Adequate |
| 数据受限 ⚠ | Limited ⚠ | 制限 ⚠ | 제한 ⚠ | Limitées ⚠ | Eingeschränkt ⚠ | Limitado ⚠ | Limited ⚠ |
| 可信评估 | Confidence | 信頼性評価 | 신뢰도 평가 | Évaluation de confiance | Vertrauensbewertung | Evaluación de confianza | Confidence |
| 覆盖充足/部分覆盖/覆盖不足 | Full/Partial/Limited coverage | 完全/部分/不足カバー | 충분/부분/부족 | Couverture complète/partielle/limitée | Vollständige/Teilweise/Eingeschränkte Abdeckung | Cobertura completa/parcial/limitada | Adequate/Partial/Limited |
| 统计 | Stats | 統計 | 통계 | Statistiques | Statistiken | Estadísticas | Stats |
| 综合评级 | Rating | 総合評価 | 종합 평가 | Note globale | Gesamtbewertung | Calificación general | Rating |
| 评估意见 | Assessment | 評価意見 | 평가 의견 | Avis d'évaluation | Bewertung | Opinión de evaluación | Assessment |
| 耗时 | Duration | 所要時間 | 소요 시간 | Durée | Dauer | Duración | Duration |
| 免费源补强 | free fallback | 無料補強 | 무료 보강 | sources gratuites | kostenlose Quellen | fuentes gratuitas | free fallback |
| 本地文件 | local files | ローカル | 로컬 파일 | fichiers locaux | lokale Dateien | archivos locales | local files |
**搜索策略描述拼接规则**（使用映射表中的翻译）：
```
IF offline_mode=true:
<搜索词>：{offline_$LANG}
ELSE:
engines_names = engines 数组元素大写（["searxng"] → "SearXNG"）
desc = engines_names
IF free_fallback=true: desc += " (+{free_fallback_$LANG})"
IF english_fallback=true: desc += " (+EN)"
<搜索词>：{desc}
```
**数据质量徽标规则**：
```
IF data_limited=true: <质量词> = {limited_$LANG}
ELSE: <质量词> = {adequate_$LANG}
```
严格按以下结构输出：
```
📊 **<执行总结词>**
| <阶段词> | <详情词> |
|:----|:------|
| 📋 <Plan词> | {outline.title} · {outline.chapter_count} <章词> · {outline.depth_mode} |
| 🎯 <Insight词> | {outline.chapters[0].description} |
| 📡 <Data词> | {task2_manifest.source_count} <来源词> · {task2_manifest.unique_domains} <独立域名词> · {task2_manifest.fact_count} <事实词> · <搜索词>：{search_desc} · {task2_manifest.fetch_method} |
| 📄 <Report词> | {REPORT} |
| 🌐 HTML 报告 | /agents/deep-researcher/outputs/{今天日期}/research-report.html |
| ✅ <可信评估词> | <覆盖_{coverage_summary}> · 高置信{conf_high_pct}% · 已公布{conf_actual_pct}% · {conf_score}/100 · {data_quality_badge} → {llm_verdict} |
| 📊 <统计词> | {qa_report.line_count} <行词> · {qa_report.word_count} <字词> · <耗时词>⏱ {totalMin} <分钟词> · <生成时间词>：{gen_time} |
```
其中：
- `{outline.chapters[0].description}` = 从 outline.json 读取第 1 章（核心观点）的 description 字段，作为观点速览摘要
- `{gen_time}` = 读取 {TMPDIR}/start_time.txt 中的任务开始时间，格式化为 `YYYY-MM-DD HH:mm:ss`
- `{REPORT}` 仅输出最终报告路径（`/agents/deep-researcher/outputs/{今天日期}/xxx.md`），不包含任何 TMPDIR 中间路径
- `{search_desc}` = 按搜索策略拼接规则生成，所有中文词根据 $LANG 翻译
- `{data_quality_badge}` = 按数据质量徽标规则生成
- `<覆盖_{coverage_summary}>` = 从 `task2_manifest.coverage_summary` 读取（adequate/partial/insufficient），用语言映射表中"覆盖充足/部分覆盖/覆盖不足"行对应翻译替换
- `{conf_high_pct}`、`{conf_actual_pct}`、`{conf_score}` = 从 Step 2b 的 `CONFIDENCE:` 行解析对应的字段
- `{llm_verdict}` = 读取 Step 2c 写入的 `{TMPDIR}/llm_assessment.txt` 完整内容
→ todowrite 全部完成
**禁止**：主 agent 不得在 Task 调度之间自行执行搜索引擎调用或数据处理。搜索/抓取归 Task 2，大纲生成归 Task 1，章节撰写归 Task 3，装配验证归 Task 4。Task 间的 handoff 文件读取（outline.json、task2_manifest.json 等）不受此限。
---
## 2. Task 1 — 主题分析 + 大纲
**工具**：`task()` | **一次调用**
**prompt 文件**：`prompts/task1_outline.md`
**用法**：读取文件内容，替换 `{TMPDIR}` `{TOOLSDIR} {LANG} {CURRENT_YEAR}` 为实际值后注入 prompt。
**输出**：大纲 agent 直接用 `write` 工具创建 `{TMPDIR}/outline.json`。主 agent 通过 `read` 确认文件存在。
---
## 3. Task 2 — 数据收集 + 结构化数据池（unspecified-high）
**工具**：`task(category="unspecified-high", load_skills=[], ...)`
**prompt 文件**：`prompts/task2_data_collection.md`
**用法**：读取文件内容，替换 `{TMPDIR}` `{TOOLSDIR}` `{LANG}` `{COUNTRY}` `{OFFLINE_MODE}` `{LOCAL_PATHS}` 为实际值后注入 prompt。
**输出**：{TMPDIR}/data-pool.json + {TMPDIR}/task2_manifest.json（使用 `write` 工具创建）
**LANG→COUNTRY 映射**（用于替换 `{COUNTRY}`）：zh→CN, en→US, ru→RU, ja→JP, ko→KR, fr→FR, de→DE, es→ES, pt→PT, it→IT, nl→NL, sv→SE, pl→PL, id→ID, th→TH, tr→TR, vi→VN, ar→SA, hi→IN。未覆盖的语言用空字符串。
---
## 3. Task 3 — 章节撰写 & 章节 agent 指令模板
主 agent 在循环中为每章调用 `task()` 时，prompt 参数使用 `{PROMPTSDIR}/task3_chapter_agent.md` 模板。
**用法**：读取 `{PROMPTSDIR}/task3_chapter_agent.md`，替换以下变量：
- `[章节 title]` → 当前章的 title（从 outline.json chapters 数组读取）
- `[N]` → 当前章节编号（第 1 章为 1，第 2 章为 2...）
- `[total]` → chapters 数组总长度
- `[sections 列表]` → 当前章的 sections 数组（逗号分隔）
- `{per_chapter_chars}` → `profiles.json` 中当前模式的 `max_chars ÷ 总章数`（主 agent 一次性算好）
- `{min_paragraphs}` → `profiles.json` 中当前模式的 `min_paragraphs`
- `{调研模式}` → quick / standard / deep（当前调研模式）
- `{TMPDIR}` → 运行时临时目录
- `{TOOLSDIR}` → tools 目录
**输出**：{TMPDIR}/chapters/chapter-{N}.md（使用 `write` 工具创建）
---
## 4. Task 4 — 验证 + 装配 + QA（主 agent 直接执行）
装配、引用转换、QA 检查均由主 agent 通过 bash 命令直接执行 `{TOOLSDIR}/dr_tools.py` 完成：
1. `validate-all-chapters` → 批量结构验证（并行）
2. `assemble-report` → 生成报告
3. `generate-confidence-section` → 可信评估（从 data-pool + manifest 聚合生成）
4. `convert-citations` → 引用转换
5. `escape-currency` → 货币符号转义
4. `qa-report` → 质量检查
**清理**：装配完成后只清理本次 `{TMPDIR}`（即 `/tmp/deep-researcher/{今天日期}/deep-research-{时间戳}/`）。如果当前工具策略不允许删除，保留该临时目录并在 manifest 中记录，不要改用真实磁盘路径或跨目录删除。
---
## 6. 输出文件管理
### 路径优先级
最终报告保存路径按以下优先级判定：
1. **Reviva 默认路径** — `/agents/deep-researcher/outputs/{今天日期}/`
2. **用户自定义子路径** — 仅当用户指定的是当前授权工作空间内、且文件工具允许写入的 Reviva 虚拟路径时才使用；如果用户给出真实磁盘路径或未授权路径，说明无法直接写入，并改写到默认输出目录。
装配阶段（Step 3）根据实际使用的路径写入，文件名格式不变：`<主题>-YYYYMMDD-HHmmss.md`。
### QA 路径核验
Step 4 QA 必须确认报告文件的保存路径为上述两者之一，如果路径不属于默认目录且非用户指定目录，标记"路径异常"不通过。
### 日期锚定
文件名中的日期用当前年月日。
### 清理机制
中间文件位于 {TMPDIR}，即 /tmp/deep-researcher/{今天日期}/deep-research-{时间戳}/
可以在文件工具允许时清理该临时目录；如果删除受限，保留并在 manifest 中记录
不使用宿主系统盘符路径、系统临时目录或其它平台特定绝对路径
---
## 7. 工具依赖速查
| 工具 | 用途 | 免费？ | 国内源？ |
|:----|:-----|:-----:|:--------:|
| `web_search_bing` | Reviva 内置 Bing 搜索，适合通用联网检索 | 取决于配置 | ✅ |
| `mcp:exa` | 可选 Exa MCP 搜索，适合英文/国际资料 | 取决于用户配置 | ❌ |
| `mcp:jina-mcp-server` | 可选网页读取/搜索增强，适合读取网页内容 | 取决于用户配置 | 取决于目标站 |
| `searxng` / `websearch` / 其它搜索工具 | 可选补充搜索通道，运行时探测 | 取决于环境 | 取决于引擎 |
| `scrapling_bulk_get/stealthy/fetch` / `webfetch` | 可选全文抓取/网页读取增强 | 取决于环境 | 取决于目标站 |
| `bash` | date 时间戳 / 文件操作 | ✅ | — |
| `write` | 写文件 | ✅ | — |
搜索策略由 agent 在运行时根据工具集**自动适配**，不依赖预设的搜索引擎配置。Exa、Bing、Jina、SearXNG 都是可选通道；谁可用就用谁，不要求全部存在。
**搜索链路**：
Layer 0 — Reviva 已绑定搜索工具探测（扫描可用工具集）
│
├─ 发现 Bing/Exa/Jina/其它搜索工具 → 使用可用工具检索
└─ 未发现 → 跳过联网搜索，转本地资料/知识库/模型常识
Layer 1 — 大纲建议源定向搜索（用当前可用搜索工具）
↓
Layer 2 — 补充全网搜索 + 反方关键词搜索（用当前可用搜索工具）
↓
搜索结果质量评估（Step 3 质量门）
├─ 达标 → 直接进入抓取
└─ 不达标 → 来源补强（官方/学术/行业机构/主流媒体/用户资料）
↓
全部来源 → 检测可用网页读取工具
├─ 可用 → 阅读全文 → 数据池
└─ 不可用 → 使用搜索摘要/知识库/本地资料，降低置信度并标注限制
---
## 8. 可选增强与配置
Reviva 默认不要求用户安装 SearXNG、Scrapling、Playwright 或额外 Python 包。
- 如果用户已配置 `mcp:exa`，可以把 Exa 作为搜索来源之一。
- 如果用户已配置 `mcp:jina-mcp-server`，可以把 Jina 作为网页读取/搜索增强之一。
- 如果当前 Agent 只有 `web_search_bing`，就用 Bing 完成联网检索。
- 如果用户未来显式安装了 SearXNG、Scrapling 或其它网页抓取工具，可以把它们作为补充通道。
- 如果没有任何联网工具，使用本地资料、知识库和模型常识完成，并在报告中说明“未启用或不可用联网搜索，外部时效信息未校验”。
---
## 9. 跨平台编码规范（Windows/macOS/Linux）
### 问题根因
Windows PowerShell 5.1 控制台编码为 CP936（GBK 中文编码），**无法表示 18 种非英语语言**：
俄语西里尔字母、日语假名/汉字、韩语谚文、阿拉伯语、泰语、印地语天城文、越南语调号、
以及德语 äöüß、法语 éèêç、西班牙语 ñ 等拉丁扩展字符——通过 shell 传参/pipe 时全部损坏。
macOS/Linux 的终端默认 UTF-8，无此问题。
### 硬性规则（所有 agent 必须遵守）
| # | 规则 | 正确做法 | 错误做法 |
|---|------|---------|---------|
| 1 | **非 ASCII 文本不进 shell argv/pipe** | 用 `write` 工具写文件 → Python `--file` 读取 | Python 脚本 argv 传非 ASCII 文本 ❌ |
| 2 | **所有文件读写用 UTF-8** | Python 统一 `encoding='utf-8-sig'`（BOM 容错） | 依赖 shell 编码 |
| 3 | **写文件只用 `write` 工具** | `write` 工具 → UTF-8 无 BOM | PowerShell `Set-Content -Encoding UTF8` ❌（会加 BOM） |
| 4 | **Python stdout 显式设 UTF-8** | `sys.stdout.reconfigure(encoding='utf-8')` | 依赖系统默认编码 |
| 5 | **Python 子进程输出用 `--output` 文件** | `python script.py --input file --output result` | shell 重定向 `> result.txt` ❌（CP936 编码输出） |
### 一劳永逸方案：全链路编码安全架构
┌─ 数据来源 ──────────────────────────────────┐
│ write 工具 / Python open(..., 'w', encoding) │ ← UTF-8 无 BOM
└──────────────┬──────────────────────────────┘
▼
┌─ 中间文件 ──────────────────────────────────┐
│ *.json / *.md : 全部 UTF-8（BOM 容错读取） │ ← utf-8-sig 代码编
└──────────────┬──────────────────────────────┘
▼
┌─ Python 处理 ───────────────────────────────┐
│ 所有脚本入口设 stdout.reconfigure('utf-8') │ ← 输出安全
│ 所有文件读用 encoding='utf-8-sig' │ ← 输入安全
│ Python 脚本统一用 --input/--output 参数 │ ← 完全绕过 shell
└──────────────┬──────────────────────────────┘
▼
┌─ 最终输出 ──────────────────────────────────┐
│ 报告文件 : UTF-8 无 BOM，任意语言均可正确显示 │
└─────────────────────────────────────────────┘
### 当前防护状态
| 文件 | 防护措施 | 状态 |
|------|---------|:----:|
| `dr_tools.py` | 入口 `stdout.reconfigure` + 所有读操作用 `utf-8-sig` | ✅ |
| `dr_check.py` | 所有读操作用 `utf-8-sig` | ✅ |
| `dr_gen.py` | 所有读操作用 `utf-8-sig`，写操作用 `utf-8`（无 BOM） | ✅ |
---
**Created by [hoolulu](https://github.com/hoolulu)** · [github.com/hoolulu/deep-research](https://github.com/hoolulu/deep-research)
