deeptutor

Imported from jiadizhunine/deeptutor (AGENTS.md). Install upstream with npx skills add jiadizhunine/deeptutor. Copyright stays with the author.

DeepTutor — Academic Advisor Investigation System

Single source of truth for agents.md compliant tools (Codex CLI, OpenCode, OpenClaw, Aider, Cline, Continue, etc.). For Claude Code and Cursor, see SKILL.md and .cursor/rules/deeptutor.mdc — both reference this file's workflow.

Comprehensive professor evaluation tool for graduate-school decisions. Investigates publications, co-author networks, student trajectories (the single most predictive signal), lab culture, and exploitation/PUA risk. Produces a standalone Chinese or English .html report.

Core principle: Your ceiling = your seniors' ceiling. A professor whose students thrive is gold; one whose students vanish is a red flag — regardless of publication metrics.

What this repo is

This is not a traditional code project — it is an AI "skill" / agent prompt-pack. There is nothing to build or npm install. When a user asks the assistant to evaluate a professor, the assistant should:

1. Detect language and region from the user's input.
2. Run the 10-phase investigation workflow below (or the 6-phase Lite variant for lower-capability models).
3. Output structured JSON, then render to HTML via scripts/generate_report.py.

The Python scripts in scripts/ are self-contained helpers — their enabled network path uses only Python's standard library. The fetcher pins each validated hostname to the public IPs returned by one DNS lookup, and search_social.py must reuse that fetcher rather than opening URLs independently. Its curl_cffi and Playwright interfaces fail closed because this integration cannot prove that every optional network path preserves the same boundary. The bundled fetcher intentionally refuses local/private/link-local targets.

When to trigger

Activate this workflow whenever a user asks to investigate, evaluate, or compare graduate advisors. Trigger phrases include:

• Chinese: 调查导师, 评估教授, 选导师, 导师怎么样, 能不能跟这个老师读研, 这个导师push吗, 帮我看看XX老师, 对比这几个导师
• English: investigate this advisor, should I join this lab, evaluate professor, is this prof good, rate my potential advisor, review this PI, compare these advisors
• Implicit: user provides <professor name> + <institution> with any evaluation intent.

Minimum input: professor name + institution. If missing, ask. Optionally ask for career goal, risk tolerance, and specific concerns to improve scoring.

Language & Region

• Language: The renderer supports Chinese and English. Match Chinese input with a fully Chinese report and English input with a fully English report. For another requested language, ask whether English is acceptable before starting. Never mix languages except when quoting original sources with a translation.
• Region detection (determines search platforms and scoring weights):

When uncertain, ask the user.

Model capability — choose Full or Lite

If unsure of model class, default to prompting. Lite specification: references/lite_mode.md.

10-Phase Investigation Workflow (Full)

11 Scoring Dimensions

Each dimension is scored 1–5. Region difference: CN D8 evaluates freedom for 考公/考编/实习; International D8 evaluates vacation policy, work hours, remote flexibility, conference support.

Deal-Breaker Conditions (One-Vote Veto)

If ANY of these are true, the final report MUST be annotated with ⚠️ 存在一票否决风险 regardless of composite score:

1. Multiple independent PUA/toxicity complaints (one is anecdotal; multiple is systemic).
2. Advisor retiring within 3 years with no succession plan.
3. No funding AND no publications in the last 3 years.
4. Multiple documented cases of students dropping out or significantly extended degrees.
5. An official finding of serious research misconduct or documented retaliation that creates a current supervision or lab-safety risk. A retraction by itself is not proof; verify its cause and outcome.

Web-Rooter Integration (Fallback for Chinese University Websites)

Chinese .edu.cn sites frequently return 404, deploy anti-bot, or require JS rendering. When WebFetch fails, escalate via Web-Rooter (wr).

Activation conditions

• WebFetch returns 404 / 403 / 5xx on .edu.cn
• Empty / garbled content (anti-bot, login wall)
• Timeout on a Chinese website
• Target is a social platform (知乎, 小红书, 百度贴吧) that blocks simple HTTP

4-Layer fallback chain

Layer 1: WebFetch (default)
  ↓ fails
Layer 2: wr html <URL>              # Better headers/TLS
  ↓ fails
Layer 3: wr html <URL> --js         # Full browser rendering (Playwright)
  ↓ fails
Layer 4: Re-search for current URL  # URL is probably outdated
         wr deep "教授姓名 大学名 课题组 官网" --top=5
         Then retry Layers 1–3 with the new URL

Phase-specific commands

If wr is not installed, fall back to the bundled self-contained scripts:

python scripts/robust_fetch.py "<URL>"             # pinned stdlib HTTP(S) only
# --js is intentionally disabled: browser networking cannot preserve this SSRF boundary
python scripts/search_social.py "导师名 大学名" --platforms zhihu,xiaohongshu,emuch

Details: references/web_rooter_integration.md.

Quality Rules (non-negotiable)

1. Every claim needs a source. No unsourced assertions.
2. Distinguish fact from inference. Mark speculative conclusions explicitly ("据观察 / Based on available evidence").
3. Cross-validate metrics. Use ≥ 3 databases for publication counts.
4. Weight recent evidence. Last 5 years matter more than career totals.
5. No fabrication. If information is unavailable, say so — don't guess.
6. Be balanced. Report both strengths and weaknesses.
7. Score vs peers. Compare against others at the same institution and rank.
8. Student signals > publication metrics. Always.
9. PUA/toxicity evidence is critical. Never downplay concerning signals.
10. Publication gap verification. Complete the 6-step checklist before concluding any gap.

Privacy & responsible use

• Use only public, professionally relevant information; do not seek or publish private contact details, family information, personal accounts, or data behind access controls.
• search_social.py sends query terms to Bing and may fall back to Sogou. Never include private or sensitive information in those queries.
• Prefer official institutional contact details. Identify students only when their professional identity is already public and necessary for a sourced trajectory claim.
• Treat search snippets and anonymous posts as leads, not verified facts. Corroborate serious allegations, label unresolved claims, and avoid reproducing handles or identifying details.
• Do not infer age, health, ethnicity, gender, family status, or other sensitive traits from proxies.
• Keep fact, allegation, and inference separate. The report is due diligence, not a misconduct finding.

Parallel search batching

Maximize efficiency by launching searches in parallel batches:

• Batch 1: Faculty page + Google Scholar + lab website + thesis database
• Batch 2: PubMed broad + Scopus/OpenAlex + name variants + preprints (bioRxiv/arXiv/medRxiv)
• Batch 3: Social platforms + news + funding databases + Retraction Watch
• Batch 4: Cross-validation and gap-filling

Report output

• Single standalone .html file, all CSS inline, no external dependencies.
• Sharp Critique (锐评) appears in top 3 sections, not buried at the end.
• All URLs clickable; printable layout.
• Filename pattern: 教授名_机构.html (CN) or firstname_lastname_institution.html (EN).
• Include top-level JSON field "model" only when the actual generating model is known. The footer becomes Generated by DeepTutor — Powered by <model>; otherwise it makes no model claim.
• For Lite output, include top-level JSON field "mode": "lite" so the renderer emits only the documented 7 sections.

Use scripts/generate_report.py — output JSON, let the script render HTML. This separates investigation (the model's job) from rendering (deterministic code).

Comparative mode

When comparing multiple advisors: investigate each independently with the full workflow, generate individual reports, then add a side-by-side scoring table with trade-off analysis and a career-goal-specific recommendation card.

Related skills (use if available)

pubmed-database, openalex-database, deep-research, exa-search, biorxiv-database, arxiv-database, scientific-visualization, matplotlib, literature-review, citation-management, web-rooter.

File layout (for tools that index this repo)

deeptutor/
├── AGENTS.md                          ← you are here (Codex CLI / agents.md spec entry)
├── SKILL.md                           ← Claude Code / agentskills.io entry (longer, same content)
├── .cursor/rules/deeptutor.mdc        ← Cursor entry (short pointer)
├── .opencode/AGENTS.md → ../AGENTS.md ← symlink
├── .openclaw/AGENTS.md → ../AGENTS.md ← symlink
├── agents/openai.yaml                 ← Codex display metadata + default prompt
├── THIRD_PARTY_NOTICES.md             ← bundled third-party licenses
├── scripts/
│   ├── generate_report.py             ← JSON → HTML renderer
│   ├── robust_fetch.py                ← anti-bot fetch fallback
│   └── search_social.py               ← Chinese social-platform search
├── references/
│   ├── advisor_evaluation_framework.md  ← scoring rubrics
│   ├── chinese_academic_system.md       ← China-specific strategy
│   ├── international_academic_system.md ← Int'l-specific strategy
│   ├── publication_search_protocol.md   ← name-variant + broad-search rules
│   ├── report_template.md               ← JSON schema + 18-section structure
│   ├── lite_mode.md                     ← 6-phase Lite spec
│   └── web_rooter_integration.md        ← wr fallback details
├── tests/                             ← stdlib unit + security regressions
└── examples/                          ← fictional reference reports (HTML)