Skill: huaruoji/research-report (version 1.0.0)

--- name: research-report description: "Research technical projects/papers and generate comprehensive reports with PDF export. Modes: lite (analysis + writing) or full (+ environment setup + experiments). Params: iterations, mode, project-path, output. Use for paper analysis, code review, technical reports, research documentation." metadata: {"openclaw": {"requires": {"bins": ["pandoc"]}, "primaryEnv": "", "emoji": "📝"}} --- # Research Report Generator Analyze technical projects/papers and produce comprehensive reports with PDF export. ## Modes ### Lite Mode (default) - Literature search + paper analysis - Code reading (local or remote) - Multi-iteration report writing - PDF generation via md2pdf skill - **No environment setup or experiment runs** ### Full Mode - Everything in lite mode + - Conda/virtualenv setup - Dependency installation - Experiment execution - Result analysis ## Usage ```bash bash {baseDir}/scripts/research-report.sh \ --topic "Spatial Forcing" \ --mode lite \ --iterations 3 \ --output both ``` ## Parameters | Parameter | Default | Description | |-----------|---------|-------------| | `--topic` | (required) | Paper/project name or arXiv ID | | `--mode` | `lite` | `lite` or `full` | | `--iterations` | `3` | Report revision iterations | | `--output` | `both` | `md`, `pdf`, or `both` | | `--project-path` | (auto) | Local code directory (optional) | | `--workspace` | (current) | Workspace directory | ## Workflow ### Phase 1: Discovery 1. Search arXiv + project pages 2. Fetch related papers (citations + references) 3. Identify key technologies and dependencies ### Phase 2: Analysis 1. Read source code (if `--project-path` provided) 2. Analyze architecture from docs/code 3. Map technology stack ### Phase 3: Report Writing (× iterations) 1. Draft outline 2. Write sections iteratively 3. Add diagrams (Mermaid/ASCII) 4. Refine explanations ### Phase 4: Export (Full mode only) 1. Setup conda env 2. Install dependencies 3. Run experiments 4. Append results to report ### Phase 5: PDF Generation 1. Call md2pdf skill 2. Send to user via Telegram ## Output Structure ``` <workspace>/ ├── reports/ │ ├── <topic>_report_v1.md │ ├── <topic>_report_v2.md │ ├── <topic>_report_final.md │ └── <topic>_report_final.pdf ├── memory/YYYY-MM-DD.md (appended) └── logs/<topic>_research.log ``` ## Report Template The generated report follows this structure: 1. **Executive Summary** - 100-word overview 2. **Motivation** - Problem statement + why it matters 3. **Background** - Prerequisites explained intuitively 4. **Core Method** - Technical details with analogies 5. **Code Analysis** - Key files walkthrough 6. **Experiments** - Setup + results (full mode) 7. **Troubleshooting** - Common issues + fixes 8. **References** - Papers + repos + docs ## Dependencies **Required:** - pandoc (for PDF export) - texlive-xetex (CJK + math support) **Full mode only:** - conda/miniconda - CUDA toolkit (if GPU experiments) ## Integration This skill automatically: - Uses `md2pdf` skill for PDF conversion - Appends to `memory/YYYY-MM-DD.md` - Creates structured report directory ## Examples **Lite mode, 5 iterations:** ```bash research-report --topic "VGGT" --iterations 5 --mode lite ``` **Full mode with local code:** ```bash research-report --topic "Spatial Forcing" \ --project-path ~/Spatial-Forcing/openvla-SF \ --mode full \ --iterations 3 ``` **PDF only output:** ```bash research-report --topic "OpenVLA" --output pdf ``` ## Troubleshooting | Issue | Fix | |-------|-----| | PDF generation fails | Check `pandoc --version`, install texlive-xetex | | CJK characters missing | Install `fonts-noto-cjk`, verify with `fc-list :lang=zh` | | Math formulas not rendered | Ensure markdown uses `$...$` / `$$...$$` syntax | | Full mode conda fails | Run `conda update -n base conda` first |

path: references/report-template.md
content: # Technical Report Template

## Structure Guidelines

### 1. Executive Summary (100-150 words)
- One paragraph overview
- What problem does this solve?
- Key innovation in one sentence
- Main result/achievement

### 2. Motivation
**2.1 Problem Statement**
- What gap/challenge exists?
- Why is it hard? (technical constraints)
- Real-world impact

**2.2 Why This Matters**
- Applications
- Who benefits?
- State of field before this work

### 3. Background
**3.1 Prerequisites** (explain intuitively)
- Key concepts the reader needs
- Use analogies where possible
- Link to foundational papers

**3.2 Related Work**
- Timeline of approaches
- Compare in a table if possible
- What this work improves

### 4. Core Method
**4.1 Architecture Overview**
- High-level diagram (Mermaid or ASCII)
- Data flow description
- Component responsibilities

**4.2 Key Innovations**
- What's novel?
- Why does it work?
- Mathematical intuition (not just formulas)

**4.3 Implementation Details**
- Critical hyperparameters
- Architecture choices
- Trade-offs made

### 5. Code Analysis
**5.1 Project Structure**
```
project/
├── key_module/      # What it does
├── training/        # What it does
└── utils/           # What it does
```

**5.2 Key Components Walkthrough**
For each important file:
- Purpose in one sentence
- Input/output shapes
- Key functions with line references

**5.3 Data Flow Example**
Walk through one forward pass step by step

### 6. Experiments
**6.1 Setup**
- Hardware (GPU, RAM)
- Dataset
- Hyperparameters (table format)
- Baselines compared

**6.2 Results**
- Main results table
- Ablation studies
- Qualitative examples

**6.3 Analysis**
- Why do results look like this?
- Failure modes
- Surprising findings

### 7. Troubleshooting
Common issues and solutions:
```
Problem: XYZ error
Cause: ...
Fix: ...
```

### 8. References
Format:
- Papers: Authors, Venue, Year, arXiv ID
- Code: GitHub URL + commit hash
- Docs: URL + access date

---

## Writing Principles

1. **Progressive Disclosure**: Start simple, add details gradually
2. **Concrete Before Abstract**: Examples before theory
3. **Visual Anchors**: Diagrams every 2-3 sections
4. **Code Snippets**: Show, don't just tell
5. **Anticipate Questions**: Address "why?" before asked

## Common Pitfalls

❌ Too much jargon without explanation
❌ Equations without intuition
❌ No comparison to baselines
❌ Missing reproduction details
❌ Walls of text without breaks

✅ Use analogies ("like X but for Y")
✅ Include "why this matters" callouts
✅ Add troubleshooting from experience
✅ Link to runnable code
✅ Version everything

---

## Iteration Checklist

For each revision pass:

- [ ] Add more intuitive explanations
- [ ] Include missing diagrams
- [ ] Expand code walkthrough
- [ ] Add troubleshooting tips
- [ ] Verify all links work
- [ ] Check math notation consistency
- [ ] Add cross-references
- [ ] Improve formatting/tables


path: scripts/research-report.sh
content: #!/usr/bin/env bash
# research-report.sh — Research project/paper and generate technical report with PDF
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

# Defaults
MODE="lite"
ITERATIONS=3
OUTPUT="both"
TOPIC=""
PROJECT_PATH=""
WORKSPACE="${WORKSPACE:-$HOME/.openclaw/workspace-research}"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

log_info()    { echo -e "${BLUE}[INFO]${NC} $*"; }
log_success() { echo -e "${GREEN}[OK]${NC} $*"; }
log_warn()    { echo -e "${YELLOW}[WARN]${NC} $*"; }
log_error()   { echo -e "${RED}[ERROR]${NC} $*"; }

# Parse arguments
while [[ $# -gt 0 ]]; do
  case $1 in
    --topic) TOPIC="$2"; shift 2 ;;
    --mode) MODE="$2"; shift 2 ;;
    --iterations) ITERATIONS="$2"; shift 2 ;;
    --output) OUTPUT="$2"; shift 2 ;;
    --project-path) PROJECT_PATH="$2"; shift 2 ;;
    --workspace) WORKSPACE="$2"; shift 2 ;;
    -h|--help)
      echo "Usage: $0 --topic <name> [options]"
      echo "Options:"
      echo "  --topic          Required. Paper/project name or arXiv ID"
      echo "  --mode           lite (default) or full"
      echo "  --iterations     Report revision count (default: 3)"
      echo "  --output         md, pdf, or both (default: both)"
      echo "  --project-path   Local code directory (optional)"
      echo "  --workspace      Workspace directory (default: ~/.openclaw/workspace-research)"
      exit 0 ;;
    *) log_error "Unknown option: $1"; exit 1 ;;
  esac
done

# Validate
if [ -z "$TOPIC" ]; then
  log_error "--topic is required"
  exit 1
fi

if [[ "$MODE" != "lite" && "$MODE" != "full" ]]; then
  log_error "--mode must be 'lite' or 'full'"
  exit 1
fi

if [[ "$OUTPUT" != "md" && "$OUTPUT" != "pdf" && "$OUTPUT" != "both" ]]; then
  log_error "--output must be 'md', 'pdf', or 'both'"
  exit 1
fi

if ! command -v pandoc &>/dev/null && [[ "$OUTPUT" == *"pdf"* ]]; then
  log_error "pandoc not found. Install: sudo apt install pandoc texlive-xetex"
  exit 1
fi

# Setup directories
REPORTS_DIR="$WORKSPACE/reports"
LOGS_DIR="$WORKSPACE/logs"
MEMORY_DIR="$WORKSPACE/memory"
mkdir -p "$REPORTS_DIR" "$LOGS_DIR" "$MEMORY_DIR"

TOPIC_SAFE=$(echo "$TOPIC" | tr ' ' '-' | tr -cd '[:alnum:]-')
REPORT_BASE="$REPORTS_DIR/${TOPIC_SAFE}_report"
LOG_FILE="$LOGS_DIR/${TOPIC_SAFE}_research_${TIMESTAMP}.log"

log_info "Topic: $TOPIC"
log_info "Mode: $MODE"
log_info "Iterations: $ITERATIONS"
log_info "Output: $OUTPUT"
log_info "Workspace: $WORKSPACE"
log_info "Log file: $LOG_FILE"

# Start logging
exec > >(tee -a "$LOG_FILE") 2>&1

log_info "=== Research Report Generation Started ==="
log_info "Timestamp: $(date)"

# Phase 1: Discovery
log_info ""
log_info "=== Phase 1: Discovery ==="

# Create initial research notes
NOTES_FILE="$REPORTS_DIR/${TOPIC_SAFE}_research_notes.md"
cat > "$NOTES_FILE" << EOF
# Research Notes: $TOPIC

## Search Queries
- arXiv: "$TOPIC"
- GitHub: "$TOPIC"
- Project page: "$TOPIC"

## Related Papers
(TBD)

## Key Technologies
(TBD)

## Code Repositories
(TBD)

---
Generated: $(date)
Mode: $MODE | Iterations: $ITERATIONS
EOF

log_success "Created research notes: $NOTES_FILE"

# Phase 2: Analysis
log_info ""
log_info "=== Phase 2: Analysis ==="

if [ -n "$PROJECT_PATH" ] && [ -d "$PROJECT_PATH" ]; then
  log_info "Analyzing local code: $PROJECT_PATH"
  CODE_FILES=$(find "$PROJECT_PATH" -type f \( -name "*.py" -o -name "*.md" -o -name "*.yaml" \) | head -20)
  log_info "Found files:"
  echo "$CODE_FILES" | while read -r f; do log_info "  - $f"; done
else
  log_info "No local code provided. Will analyze from remote sources."
fi

# Phase 3: Report Writing (iterations)
log_info ""
log_info "=== Phase 3: Report Writing (${ITERATIONS} iterations) ==="

PREV_VERSION=""
for i in $(seq 1 $ITERATIONS); do
  log_info ""
  log_info "--- Iteration $i/$ITERATIONS ---"
  
  if [ $i -eq 1 ]; then
    CURRENT_VERSION="${REPORT_BASE}_v${i}.md"
    # Draft initial outline
    cat > "$CURRENT_VERSION" << EOF
# ${TOPIC} Technical Report

## Executive Summary
(TBD - will be filled in final iteration)

## 1. Motivation
### 1.1 Problem Statement
(TBD)

### 1.2 Why This Matters
(TBD)

## 2. Background
### 2.1 Prerequisites
(TBD)

### 2.2 Related Work
(TBD)

## 3. Core Method
### 3.1 Architecture Overview
(TBD)

### 3.2 Key Innovations
(TBD)

## 4. Code Analysis
### 4.1 Project Structure
(TBD)

### 4.2 Key Components
(TBD)

## 5. Experiments
### 5.1 Setup
(TBD)

### 5.2 Results
(TBD)

## 6. Troubleshooting
(TBD)

## 7. References
(TBD)

---
Version: v$i | Generated: $(date)
EOF
    log_success "Created draft v$i"
  else
    CURRENT_VERSION="${REPORT_BASE}_v${i}.md"
    PREV_VERSION="${REPORT_BASE}_v$((i-1)).md"
    # Copy previous and mark for revision
    cp "$PREV_VERSION" "$CURRENT_VERSION"
    log_success "Copied v$((i-1)) → v$i (ready for revision)"
  fi
  
  PREV_VERSION="$CURRENT_VERSION"
done

FINAL_MD="${REPORT_BASE}_final.md"
cp "$PREV_VERSION" "$FINAL_MD"
log_success "Final report: $FINAL_MD"

# Phase 4: Full mode - Environment + Experiments
if [ "$MODE" == "full" ]; then
  log_info ""
  log_info "=== Phase 4: Environment Setup + Experiments ==="
  log_warn "Full mode requires manual intervention for conda setup and experiment runs"
  log_info "Append experiment results to: $FINAL_MD"
fi

# Phase 5: PDF Generation
if [[ "$OUTPUT" == *"pdf"* ]]; then
  log_info ""
  log_info "=== Phase 5: PDF Generation ==="
  
  # Check if md2pdf skill exists
  MD2PDF_SCRIPT="$HOME/.openclaw/skills/md2pdf/scripts/md2pdf.sh"
  if [ -f "$MD2PDF_SCRIPT" ]; then
    log_info "Using md2pdf skill for conversion"
    bash "$MD2PDF_SCRIPT" "$FINAL_MD" "${FINAL_MD%.md}.pdf" 2>&1 | while read -r line; do
      log_info "  $line"
    done
    if [ -f "${FINAL_MD%.md}.pdf" ]; then
      log_success "PDF generated: ${FINAL_MD%.md}.pdf"
    else
      log_warn "PDF generation may have failed"
    fi
  else
    log_warn "md2pdf skill not found. Using direct pandoc:"
    pandoc "$FINAL_MD" -o "${FINAL_MD%.md}.pdf" \
      --pdf-engine=xelatex \
      -V geometry:margin=20mm \
      -V fontsize=10pt \
      --toc 2>&1 | while read -r line; do
      log_info "  $line"
    done
  fi
fi

# Append to memory
TODAY=$(date +%Y-%m-%d)
MEMORY_FILE="$MEMORY_DIR/${TODAY}.md"
cat >> "$MEMORY_FILE" << EOF

## ${TOPIC} Research Report

- **Mode:** $MODE
- **Iterations:** $ITERATIONS
- **Output:** $OUTPUT
- **Report:** $FINAL_MD
- **PDF:** ${FINAL_MD%.md}.pdf
- **Log:** $LOG_FILE

EOF
log_success "Appended to memory: $MEMORY_FILE"

log_info ""
log_info "=== Research Report Generation Complete ==="
log_success "Final report: $FINAL_MD"
if [[ "$OUTPUT" == *"pdf"* ]]; then
  log_success "PDF: ${FINAL_MD%.md}.pdf"
fi
log_info "Log file: $LOG_FILE"

# Print summary
echo ""
echo "=========================================="
echo "           GENERATION COMPLETE          "
echo "=========================================="
echo "Report (Markdown): $FINAL_MD"
if [[ "$OUTPUT" == *"pdf"* ]]; then
  echo "Report (PDF):       ${FINAL_MD%.md}.pdf"
fi
echo "Log file:          $LOG_FILE"
echo "=========================================="


path: scripts/run-research-agent.sh
content: #!/usr/bin/env bash
# run-research-agent.sh — Invoke the full research workflow via OpenClaw agent
# This script is called by the agent to execute the research process
set -euo pipefail

# Usage: run-research-agent.sh --topic <name> --mode <lite|full> --iterations <n> --workspace <dir>

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(dirname "$SCRIPT_DIR")"

# Source the main script with agent-friendly defaults
exec "$SCRIPT_DIR/research-report.sh" "$@"


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)