🌐 中文版 (Chinese)

An academic research direction exploration skill pack based on Claude Code. It helps researchers converge from "fuzzy ideas" to "concrete research gaps" through Socratic dialogue + literature retrieval + the Matrix Method.

What CARS does: Helps you find research directions worth pursuing (Research Gaps).

What CARS DOES NOT do: It does not write papers, conduct experiments, or submit manuscripts for you.

Fuzzy Ideas → [CARS] → Concrete Research Gaps + Supporting Literature + Actionable Next Steps

Finding a research direction is often the most painful stage of academic research. You are frequently faced with:

• Having read dozens of papers but still not knowing where the gaps are.
• Having a vague intuition but being unable to articulate "what exactly I want to research."
• Being speechless when your advisor asks, "Where is your innovation?"

CARS structures this process through the collaboration of 5 modules:

[Socratic Dialogue] → Excavate the cognition in your mind
        ↓
[User Profile] → Structure your ideas
        ↓
[Literature Scout] → Find relevant papers
        ↓
[Literature Reader] → Extract the core structure of papers
        ↓
[Matrix Engine] → Visualize research gaps
        ↓
[Socratic Dialogue (Supervised)] → Lock in a specific direction

AI is your research partner, not your proxy.

CARS will not think for you. It forces you to think clearly through Socratic questioning, helps you see the big picture through literature retrieval, and helps you discover what others haven't done through matrix analysis. The final judgment—"Is this direction worth pursuing?"—is always yours.

Inspirations:

• The Matrix Method: Garrard's (2017) framework for comparative literature reading.
• Socratic Method: Guiding thought through questioning rather than telling.

• Claude Code (v3.7.0+ recommended)
• Python 3.10+
• Exported ANTHROPIC_API_KEY

# Clone the repository
git clone [https://github.com/Eureka39/CARS.git](https://github.com/Eureka39/CARS.git)

# Enter the directory
cd CARS

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements-dev.txt

# Configure MCP
cp .mcp.json.example .mcp.json
# Edit .mcp.json, replacing <CARS_ROOT> with your actual absolute path

# Configure API Keys
cp config/api_keys.json.example config/api_keys.json
# Edit api_keys.json, filling in your Semantic Scholar and Google AI Studio API Keys

# Configure Network Proxy (if needed)
cp config/network_config.json.example config/network_config.json
# Edit network_config.json to set up your local proxy

# Run in Claude Code
"Guide my research direction"

If the Socratic mentor initiates the conversation normally, the installation is successful.

4 Agents collaborate to excavate the user's research cognition through 5 layers of questioning.

Features:

• Devil's Advocate: Conducts stress tests during layer transitions.
• Question Judge: Ensures each question probes cognition rather than simply requesting facts.
• Progression Judge: Prevents premature convergence or infinite divergence.
• Conversation Health Monitor: Self-checks every 5 turns.
• Pause & Resume: Supervised mode can be paused to read literature and resumed later.

Integrates raw materials from Socratic dialogues into a structured profile.

Input: diagnostics/session_*.md (Chat logs) Output: user_profile.json (Single Source of Truth) + Update README.md

Extracted Content:

• [INSIGHT] → User-confirmed cognition
• [OPEN_THREAD] → Unresolved issues/questions
• [READING_REF] → Reading experiences/references
• [SEARCH_SEED] → Seed papers (Supervised mode)
• User Preferences / Constraints / Contradictions

5 Agents collaborate to complete the "Search → Filter → Download" pipeline.

Features:

• Confidence scoring (high/medium/low) for automatic routing.
• High-confidence papers are auto-downloaded; medium/low are presented for user confirmation.
• Incremental appending (prevents duplicate downloads).
• Supports batch downloading of arXiv PDFs.

2 Agents collaborate to convert PDFs into structured data.

PDF → [Gemini Cloud Deep Reading] → Markdown Report → [Parsing] → Structured JSON

Extracts 4 Dimensions:

1. Task Definition
2. Core Mechanism
3. Evaluation
4. Research Gap (Optional)

1 Agent that converts structured paper data into a 2D research map.

Structured JSON → [Extract Axes + Normalize + Populate] → matrix.json + matrix.csv

Outputs:

• Y-axis: Research Problems / Application Scenarios
• X-axis: Methods / Techniques
• Cells: Corresponding paper lists
• Empty Cells = Research Gaps

You: "Guide my research direction"

=== Round 1: Cognition Excavation ===
[Socratic Zeroshot] → 5-layer dialogue → session.md
[Profile Module] → user_profile.json

=== Round 2: Literature Retrieval ===
You: "Help me find papers"
[Literature Scout] → Search → Filter → Download
→ literature/jsons/ + literature/pdfs/

=== Round 3: Deep Reading ===
You: "Deep read the literature"
[Literature Reader] → PDF → Markdown → JSON
→ hypotheses/translated/*.json

=== Round 4: Matrix Generation ===
You: "Generate the matrix"
[Matrix Engine] → matrix.json + matrix.csv

=== Round 5: Direction Locking ===
You: "Continue the dialogue"
[Socratic Supervised] → Matrix-based 5-layer dialogue → Lock Research Gap
→ Concrete Research Idea + Next Action

cars/
├── config/
│   ├── api_keys.json.example
│   └── network_config.json.example
├── modules/
│   ├── socratic-method/
│   │   ├── SKILL.md
│   │   ├── agents/
│   │   │   ├── socratic_mentor_agent.md
│   │   │   ├── devils_advocate_agent.md
│   │   │   ├── question_judge_agent.md
│   │   │   └── progression_judge_agent.md
│   │   ├── protocols/
│   │   │   ├── socratic_zeroshot_protocol.md
│   │   │   └── socratic_supervised_protocol.md
│   │   └── references/
│   ├── profile-module/
│   │   ├── SKILL.md
│   │   └── agents/
│   │       └── profile_agent.md
│   ├── literature-scout/
│   │   ├── SKILL.md
│   │   ├── agents/
│   │   │   ├── literature_scout_agent.md
│   │   │   ├── query_builder_agent.md
│   │   │   ├── seed_expander_agent.md
│   │   │   ├── relevance_judge_agent.md
│   │   │   └── batch_fetch_agent.md
│   │   └── tools/
│   │       └── s2_mcp_server.py
│   ├── literature-reader/
│   │   ├── SKILL.md
│   │   ├── agents/
│   │   │   ├── deep_reader_agent.md
│   │   │   └── paper_cruncher_agent.md
│   │   └── tools/
│   │       └── cruncher.py
│   └── matrix-engine/
│       ├── SKILL.md
│       ├── agents/
│       │   └── matrix_engine_agent.md
│       └── tools/
│           └── matrix_to_csv_server.py
├── templates/
│   └── sampleProject1/           ← Skeleton copied when creating a new project
├── workspaces/                   ← User's research projects
│   └── ProjectX/
│       ├── README.md
│       ├── user_profile.json
│       ├── matrix.json
│       ├── matrix.csv
│       ├── diagnostics/
│       ├── literature/
│       └── hypotheses/
├── .mcp.json.example
├── requirements-dev.txt
└── README.md                     ← You are currently reading this file

• Rule-based Normalization: The normalization of matrix axis labels currently relies on rule matching, which may miss merging labels with identical semantics but vastly different phrasing.
• PDF Reading Relies on Gemini: Requires network connectivity and a Google API Key.
• Non-English Papers Unverified: The Gemini prompt is currently in English. The extraction quality for non-English papers has not been thoroughly verified.
• No Auto-Orchestration: Modules currently need to be triggered manually by the user; there is no fully automated pipeline yet.

• Agent Orchestration: Fully automated pipeline scheduler.
• Markdown Fetcher: Fetch Markdown originals of arXiv papers via Jina Reader (bypassing PDFs).
• Literature Reader Interactive Mode: Allow users to ask questions about a specific paper.
• Matrix Normalization Upgrade: LLM-assisted semantic clustering.
• Multi-Project Comparison: Cross-project matrix merging and gap analysis.

• Dialogue Language: Follows the user's input (Chinese/English/Mixed).
• Paper Reading Output: Chinese (Automatically condenses original papers into hard-core Chinese academic summaries for rapid scanning).
• Matrix CSV: English content, UTF-8-BOM encoded (Opens perfectly in Excel without garbled text on Windows/Mac).

• Semantic Scholar API — Paper search and recommendations.
• Google AI Studio (Gemini) — Multimodal PDF deep reading.
• The Matrix Method — Garrard's (2017) framework for comparative literature reading.

This project is licensed under the MIT License.