Core concept: Three-phase decoupling — local scan (activation of existing knowledge) → exploration dump (internet → local files) → utilization writing (offline reading of local files).
Quality check standard: The Phase 2 report must pass the Gracker writing four-layer quality check, otherwise it triggers a rewrite.
Optional companion skill: If the runtime environment has installed
gracker-writing, prioritize reading itsSKILL.mdas the complete style specification; otherwise use the built-in quality check summary in this document.
⚙️ Configuration
local_vault_path: null # 可选：本地知识库、笔记库或资料库路径；未配置则跳过本地资料扫描
workspace_path: . # 当前项目或 AI 运行时工作目录
research_output_dir: ./research
writing_skill_path: null # 可选：gracker-writing/SKILL.md 的本地路径
Portability: All paths must be provided by the current user or runtime. If a path does not exist, Phase 0 silently skips it without blocking the whole process; you must not assume the existence of a specific AI runtime, a specific HOME path, or a specific model.
Terminology
| Term | Meaning |
|---|---|
| Phase 0 scan | Scan local knowledge base related files and generate a coverage assessment |
| research dump | The researcher's raw findings for each sub-question, written to a local .md file |
| local context | The local knowledge summary produced in Phase 0 |
| master research | A single file after dump + local context are aggregated |
| Four-layer quality check | L1 banned words/fatal flaws → L2 readability → L3 content depth → L4 human feel (Gracker writing standard) |
Three-phase overview
用户输入 (题目)
│
▼
┌──────────────────────────────────────────────────────────┐
│ PHASE 0: 本地扫描 —— 激活已有知识资产 │
│ 目标: 在规划子问题之前，先摸清本地有什么 │
│ 策略: 扫描结果影响子问题范围（已有高覆盖 → 缩小搜索范围） │
├──────────────────────────────────────────────────────────┤
│ PHASE 1: 探索 —— 调研 + 落盘 │
│ 目标: 把互联网的零散知识全部沉淀成本地文件 │
│ 原则: 全力搜索，不漏信号，断网前完成所有网络访问 │
├──────────────────────────────────────────────────────────┤
│ PHASE 2: 利用 —— 读文件 + 写作 + 四层质检 │
│ 目标: 基于本地干净文件进行高频迭代写作 │
│ 原则: 断网，只读本地文件 │
│ 质检: Gracker 写作四层标准，不通过则 rewrite │
└──────────────────────────────────────────────────────────┘
Phase 0: Local file scan
Execution timing: The first step of the entire process, executed before planning any sub-questions.
Execution steps
Step 0a: Scan directories
Perform keyword scans on the following candidate directories (scan only if they exist).local_vault_path When not configured, skip all local knowledge base subdirectories; directory names should be adjusted according to the user's actual data repository:
{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/
Extract 3-5 core concepts from the topic as keywords.
rg -l --max-count 10 --type md "keyword1|keyword2|keyword3" "{dir}/" 2>/dev/null
If there is no rg, use the equivalent full-text search capability available in the current runtime environment.
Step 0b: Read high-match files
For each file found, extract relevant passages (at most the 5 most valuable files, limited to 100 lines per file):
rg -C 3 "{keyword}" "{file}" 2>/dev/null | head -100
Step 0c: Write local context
Path:{research_output_dir}/{YYYY-MM-DD}-{slug}-研究材料/00-local-context.md
Format:
---
phase: 0
topic: {topic}
---
# Phase 0 · 本地知识扫描结果
## 扫描目录
- ✓ 本地知识库 A: 扫描了 X 个文件，命中 {N}
- ✓ Research: 命中 {N}
- ✗ Notes/（目录不存在，静默跳过）
...
## 命中文件
### {文件名1}
- **路径**: {path}
- **相关段落**: `{rg 输出片段，限制 80 行}`
- **对本题的价值**: 高/中/低
...
## 覆盖度评估
| 子维度 | 本地覆盖度 | 本地来源 |
|--------|-----------|---------|
| {维度1} | 高/中/低 | {文件列表} |
| {维度2} | 高/中/低 | {文件列表} |
## 子问题范围调整
- **{子问题A}**：本地高覆盖 → 缩小搜索范围，补充最新动态
- **{子问题B}**：本地无覆盖 → 正文搜索
Phase 1a: Plan sub-questions + create directories
- Read the Phase 0 output
00-local-context.md - Break down 2-4 sub-questions in combination with the topic; clearly mark those with high Phase 0 coverage to narrow the scope
- Create directories:
DATE=$(date +%Y-%m-%d)
TOPIC_SLUG="{short-topic-slug}" # 保留字母、数字和必要的中日韩字符；其他字符替换为 -
OUT_DIR="{research_output_dir}/${DATE}-${TOPIC_SLUG}-研究材料"
mkdir -p "${OUT_DIR}/references"
- Reply to the user:
收到，开始处理。本地扫描命中 X 个文件。Phase 0 发现 {A} 子问题本地高覆盖，聚焦缺失部分。
Phase 1b: Researcher writes research dump
Key constraint: All of the researcher's network access must be completed before writing the dump file; do not access the network during the writing phase.
Sub-question planning (main session)
Based on the topic and Phase 0 results, break down 2-4 sub-questions, each with a search strategy:
| Sub-question | Search keywords | Preferred sources |
|---|---|---|
| {Sub-question A} | keyword1, keyword2 | Official documentation / Official source code |
| {Sub-question B} | keyword3, keyword4 | Papers / Standards / Official issues |
| ... | ... | ... |
Execution method
- If the runtime environment supports parallel tasks: assign one researcher to each sub-question, execute them simultaneously, and finally aggregate the dump files.
- If the runtime environment does not support parallelism: execute in the current session in sub-question order, still maintaining "one dump file per question".
- The Skill does not specify a model. The model and timeout are selected by the current AI runtime, user configuration, or caller policy.
Researcher Prompt
When generating the researcher prompt for each sub-question, read references/research-dump-template.md. This template defines the research question, search strategy, offline dump writing, file format, and quality self-assessment requirements.
Phase 1c: Reference archiving
After the researchers complete, the main session fetches or opens archives for all cited URLs (those not yet fetched), saving them to:
{OUT_DIR}/references/{num}-{slug}.md
Format:
---
source: {url}
title: {title}
fetched: {ISO timestamp}
research_topic: {topic}
sub_question: {sub_question}
---
{full content}
Phase 1d: Gap check + compile master-research
- Read all dump files, assess
是否需要补充调研 - If there are gaps: the main session directly supplements the search, without dispatching new researchers
- Compile master-research:
cat "{OUT_DIR}/00-local-context.md" \
"{OUT_DIR}"/*-dump-*.md \
> "{OUT_DIR}/master-research.md"
Phase 2: Writing (offline mode)
⚠️ Absolute constraint: In this phase, network access, search, fetching, or browser tools must not be used; only local files may be read.
Phase 2a: Verification
Check that {OUT_DIR}/master-research.md exists and is non-empty. If it does not exist, report an error and do not continue writing.
Phase 2b: Writing execution
Prefer the capability in the current runtime environment that is most suitable for long-form synthesis writing; if independent writer tasks are supported, a writer may be started separately, but the model, vendor, or runtime must not be fixed in the Skill.
Prompt: Read references/writer-prompt-template.md, replacing the template variables with this run's topic, OUT_DIR, and research_output_dir. The template contains the offline constraint, report structure, citation requirements, and writing quality standards.
Phase 2c: Four-layer quality check (Gracker writing standard)
Execution timing: after the report draft is produced and before formal delivery. If the quality check does not pass, trigger a rewrite.
Companion skill
If writing_skill_path points to a readable file, first read that file as the complete writing specification. Common values are gracker-writing/SKILL.md。
If there is no configuration or the file does not exist, continue using the four-layer quality check summary built into this Skill. Do not automatically download or install additional skills unless the user explicitly requests it.
Execution method
The main session reads the report draft + optional gracker-writing specification, and performs the four-layer quality check.
Network tools must not be used; all judgments are based on local file content.
Detailed quality check rules and report format are in references/quality-gate.md. When performing the quality check, first read that file, then check the report draft in combination with the optional gracker-writing specification.
rewrite trigger logic
| Quality check result | Handling |
|---|---|
| L1 does not pass | Force rewrite, explicitly listing the positions of prohibited words/hard errors hit by L1, with the main session supervising the fix |
| L2 does not pass (opening does not pass) | Force rewrite |
| L2 does not pass (other items) | Optional rewrite, explicitly informing of the specific paragraphs |
| L3-1/3-2 do not pass | Force rewrite, pointing out the specific judgments lacking support |
| L4 overall does not pass | Force rewrite, provide specific guidance on "which paragraph has a heavy AI flavor" |
| All passed | Proceed to Phase 3 delivery |
rewrite configuration：
- Execution method: reuse the writing execution method from Phase 2b; if the runtime supports a standalone writer/rewrite task, it can be executed separately
- Model: not specified in the Skill, decided by the runtime or user configuration
- prompt: based on the Phase 2b writer prompt, attach the QC report so that rewrite specifically fixes the flagged issues
- After rewrite is complete, run Phase 2c QC once more; delivery only after it passes
Phase 3: Delivery
- Report path：
{research_output_dir}/{YYYY-MM-DD}-{slug}-深度调研.md - Send to user：
- Title + summary preview (first 5 lines)
- Full text
- Note:
已完成。报告共 X 字，Phase 0 命中 {N} 个本地文件，Phase 1 抓取 {Z} 个来源，Phase 2c 四层质检 [通过/强制 rewrite X 轮]，参考资料 {M} 篇已归档。
- Optional record: if the runtime environment provides memory / notes / task log, append a brief record; if not, skip it—this does not affect delivery.
## [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}
Principle of prioritizing primary sources
| Priority | Source type |
|---|---|
| 1 | Source code (AOSP) |
| 2 | Official documentation |
| 3 | Academic papers (arxiv) |
| 4 | Official Issue / CL / Release Notes |
| 5 | Official blog |
| — | Secondary blog (as a lead only; must be traced back to a primary source) |
Error handling
| Scenario | Handling |
|---|---|
| Phase 0 scanned directory does not exist | Skip silently |
| Phase 0 ripgrep returns no results | Continue normally, output "no local hits" |
writing_skill_path does not exist |
Use the built-in QC summary to continue; do not automatically install via the network |
| Researcher timeout | Narrow the scope and retry once |
| The current model/runtime is not suitable for long-form synthesis | Notify the user of the capability limitation, provide the research materials already saved to disk and suggested next steps |
| Phase 2c QC fails | Trigger rewrite, then run QC again after fixes |
Write file to research_output_dir fails |
Degrade to workspace tmp, notify the user |
Differences from the old deep-research skill
| Difference | Old version | New version |
|---|---|---|
| Phase 0 local scan | None | Executed first, affects sub-question planning |
| Network access during the writing stage | May continue to access | Network disconnected, only local files are read |
| Researcher output | Inline text | Write to .md dump file |
| Reference materials | Archived but not mandatory | Mandatory archiving to references/ |
| Portability | None | Path is configurable; skip silently if scanning fails |
| Phase 2c QC | content-quality-gate general QC | Gracker four-layer writing QC + style taboos + rewrite trigger |
| Style guidelines | None | 15 categories of prohibited words/sentence patterns, with clear rewrite trigger conditions |
| Writing specification dependency | None | Optional read gracker-writing, use built-in summary when missing |