Gracker Deep Research

Gracker Deep Research Skill

核心理念：三阶段解耦 —— 本地扫描（已有知识激活）→ 探索落盘（互联网 → 本地文件）→ 利用写作（断网读本地文件）。

质检标准：Phase 2 报告必须通过 Gracker 写作四层质检，否则触发 rewrite。

可选配套 skill：如果运行环境安装了 gracker-writing，优先读取其 SKILL.md 作为完整文风规范；否则使用本文内置的质检摘要。

⚙️ 配置

local_vault_path: null        # 可选：本地知识库、笔记库或资料库路径；未配置则跳过本地资料扫描
workspace_path: .             # 当前项目或 AI 运行时工作目录
research_output_dir: ./research
writing_skill_path: null      # 可选：gracker-writing/SKILL.md 的本地路径

Portability：所有路径都必须由当前用户或运行时提供。路径不存在时 Phase 0 静默跳过，不阻断全流程；不得假定存在特定 AI 运行时、特定 HOME 路径或特定模型。

术语

三阶段总览

用户输入 (题目)
    │
    ▼
┌──────────────────────────────────────────────────────────┐
│  PHASE 0: 本地扫描 —— 激活已有知识资产                      │
│  目标: 在规划子问题之前，先摸清本地有什么                    │
│  策略: 扫描结果影响子问题范围（已有高覆盖 → 缩小搜索范围）    │
├──────────────────────────────────────────────────────────┤
│  PHASE 1: 探索 —— 调研 + 落盘                             │
│  目标: 把互联网的零散知识全部沉淀成本地文件                   │
│  原则: 全力搜索，不漏信号，断网前完成所有网络访问             │
├──────────────────────────────────────────────────────────┤
│  PHASE 2: 利用 —— 读文件 + 写作 + 四层质检                  │
│  目标: 基于本地干净文件进行高频迭代写作                       │
│  原则: 断网，只读本地文件                                   │
│  质检: Gracker 写作四层标准，不通过则 rewrite              │
└──────────────────────────────────────────────────────────┘

Phase 0: 本地文件扫描

执行时机：整个流程第一步，在规划任何子问题之前执行。

执行步骤

Step 0a: 扫描目录

对以下候选目录（存在才扫）执行关键词扫描。local_vault_path 未配置时，跳过所有本地知识库子目录；目录名应按用户实际资料库调整：

{local_vault_path}/DeepResearch/
{local_vault_path}/Research/
{local_vault_path}/调研/
{local_vault_path}/Notes/
{local_vault_path}/Articles/
{local_vault_path}/KnowledgeBase/
{workspace_path}/MEMORY.md
{workspace_path}/memory/

关键词从 topic 提取 3-5 个核心概念。

rg -l --max-count 10 --type md "keyword1|keyword2|keyword3" "{dir}/" 2>/dev/null

如果没有 rg，使用当前运行环境可用的等价全文搜索能力。

Step 0b: 读取高匹配文件

对每个找到的文件，提取相关段落（最多 5 个最有价值的文件，每文件限制 100 行）：

rg -C 3 "{keyword}" "{file}" 2>/dev/null | head -100

Step 0c: 写入 local context

路径：{research_output_dir}/{YYYY-MM-DD}-{slug}-研究材料/00-local-context.md

格式：

---
phase: 0
topic: {topic}
---

# Phase 0 · 本地知识扫描结果

## 扫描目录
- ✓ 本地知识库 A: 扫描了 X 个文件，命中 {N}
- ✓ Research: 命中 {N}
- ✗ Notes/（目录不存在，静默跳过）
...

## 命中文件

### {文件名1}
- **路径**: {path}
- **相关段落**: `{rg 输出片段，限制 80 行}`
- **对本题的价值**: 高/中/低

...

## 覆盖度评估

| 子维度 | 本地覆盖度 | 本地来源 |
|--------|-----------|---------|
| {维度1} | 高/中/低 | {文件列表} |
| {维度2} | 高/中/低 | {文件列表} |

## 子问题范围调整

- **{子问题A}**：本地高覆盖 → 缩小搜索范围，补充最新动态
- **{子问题B}**：本地无覆盖 → 正文搜索

Phase 1a: 规划子问题 + 创建目录

1. 读取 Phase 0 输出的 00-local-context.md
2. 结合 topic 拆解 2-4 个子问题，Phase 0 高覆盖的明确标注缩小范围
3. 创建目录：

DATE=$(date +%Y-%m-%d)
TOPIC_SLUG="{short-topic-slug}"  # 保留字母、数字和必要的中日韩字符；其他字符替换为 -
OUT_DIR="{research_output_dir}/${DATE}-${TOPIC_SLUG}-研究材料"
mkdir -p "${OUT_DIR}/references"

4. 回执用户：收到，开始处理。本地扫描命中 X 个文件。Phase 0 发现 {A} 子问题本地高覆盖，聚焦缺失部分。

Phase 1b: 研究员写 research dump

关键约束：研究员的全部网络访问必须在写 dump 文件之前完成，不在写作阶段访问网络。

子问题规划（主 session）

根据 topic 和 Phase 0 结果，拆解 2-4 个子问题，每个附搜索策略：

执行方式

• 如果运行环境支持并行任务：每个子问题分配一个 researcher，同时执行，最后汇总 dump 文件。
• 如果运行环境不支持并行：在当前 session 按子问题顺序执行，仍然保持“一题一 dump 文件”。
• Skill 不指定模型。由当前 AI 运行时、用户配置或调用方策略选择模型和超时。

Researcher Prompt

按子问题生成 researcher prompt 时，读取 references/research-dump-template.md。该模板定义了研究问题、搜索策略、断网写 dump、文件格式和质量自评要求。

Phase 1c: 参考资料归档

研究员完成后，主 session 对所有 cite 的 URL 执行抓取或打开归档（未抓取过的），保存到：

{OUT_DIR}/references/{num}-{slug}.md

格式：

---
source: {url}
title: {title}
fetched: {ISO timestamp}
research_topic: {topic}
sub_question: {sub_question}
---

{full content}

Phase 1d: 缺口检查 + 编译 master-research

1. 读取所有 dump 文件，评估 是否需要补充调研
2. 如有缺口：主 session 直接补搜，不派新 researcher
3. 编译 master-research：

cat "{OUT_DIR}/00-local-context.md" \
    "{OUT_DIR}"/*-dump-*.md \
    > "{OUT_DIR}/master-research.md"

Phase 2: 写作（断网模式）

⚠️ 绝对约束：此阶段不得使用联网、搜索、抓取或浏览器工具，只读本地文件。

Phase 2a: 验证

检查 {OUT_DIR}/master-research.md 存在且非空。不存在则报错，不继续写作。

Phase 2b: 写作执行

优先使用当前运行环境中最适合长文综合写作的能力；如果支持独立 writer 任务，可以单独启动 writer，但不得在 Skill 中固定模型、供应商或 runtime。

Prompt：读取 references/writer-prompt-template.md，用本次 topic、OUT_DIR 和 research_output_dir 替换模板变量。模板包含断网约束、报告结构、引用要求和写作质量标准。

Phase 2c: 四层质检（Gracker 写作标准）

执行时机：报告草稿产出后、正式交付前。如质检不通过，触发 rewrite。

配套 skill

如果 writing_skill_path 指向可读文件，先读取该文件作为完整写作规范。常见值是 gracker-writing/SKILL.md。

如果没有配置或文件不存在，继续使用本 Skill 内置的四层质检摘要。不得自动下载或安装额外 skill，除非用户明确要求。

执行方式

主 session 读取报告草稿 + 可选 gracker-writing 规范，执行四层质检。

不得使用联网工具，全部基于本地文件内容判断。

详细质检规则和报告格式见 references/quality-gate.md。执行质检时先读取该文件，再结合可选 gracker-writing 规范检查报告草稿。

rewrite 触发逻辑

rewrite 配置：

• 执行方式：复用 Phase 2b 的写作执行方式；如果运行时支持独立 writer/rewrite 任务，可以单独执行
• 模型：不在 Skill 中指定，由运行时或用户配置决定
• prompt：在 Phase 2b writer prompt 基础上，附加质检报告，让 rewrite 专门修复标出的问题
• rewrite 完成后再执行一次 Phase 2c 质检，通过才能交付

Phase 3: 交付

1. 报告路径：{research_output_dir}/{YYYY-MM-DD}-{slug}-深度调研.md
2. 发送用户：
   • 标题 + 摘要预览（前 5 行）
   • 全文
   • 附注：已完成。报告共 X 字，Phase 0 命中 {N} 个本地文件，Phase 1 抓取 {Z} 个来源，Phase 2c 四层质检 [通过/强制 rewrite X 轮]，参考资料 {M} 篇已归档。
3. 可选记录：如果运行环境提供 memory / notes / task log，则追加一条简短记录；没有则跳过，不影响交付。

## [HH:MM] task | 深度调研·{topic}·已完成
- 规模: {small/medium/large}，耗时约 X 分钟
- Phase 0: 扫描 {X} 个目录，命中 {N} 个本地文件
- Phase 1: Y 个研究员落盘，Z 个来源
- Phase 2: 断网写作
- Phase 2c: 四层质检 [{通过/强制 rewrite X 轮}]
- 报告: {research_output_dir}/{filename}

一手资料优先原则

错误处理

与旧版 deep-research skill 的差异