At A Glance

Qiongli is for research work that needs a paper trail. It turns a broad academic request into a task flow with Task IDs, quality gates, role handoffs, and standard outputs under RESEARCH/[topic]/. Instead of asking an agent to improvise a whole paper in one pass, you get smaller steps that are easier to inspect, revise, and trust.

Use it when you need to:

• Choose a paper route: empirical, qualitative, systematic review, RCT/preregistration, theory, or code-first methods.
• Make literature work auditable: plan searches, record diagnostics, materialize search bundles, deduplicate results, and prepare screening or snowballing.
• Keep writing tied to evidence: map claims to sources, check citation risk, plan figures and tables, review limitations, proofread, and prepare rebuttals.
• Treat research code as research evidence: move through Stage-I I5 -> I6 -> I7 -> I8 for specification, planning, execution, and review.
• Coordinate more than one agent: use solo, duo, or triad modes with explicit handoffs, disagreement records, and verification status.

The public name is Qiongli, from the Chinese 穷理: to keep asking what principle, evidence, and limit sit underneath a question. The full methodology name is Qiongli Zhengche (穷理证澈): make evidence chains, citation risk, assumptions, and claim boundaries clear enough to audit.

Start Here

Latest Stable Downloads

Current stable release: v1.7.0. These direct links cover the common install paths; use the download guide for subject-specific Desktop ZIPs and maintainer artifacts.

How It Works

flowchart TD
    A["Research request<br/>topic, paper type, client, constraints"] --> B["Qiongli entrypoint<br/>skill, plugin command, CLI, or MCP tool"]
    B --> C["Task contract<br/>Task ID, stage, role, expected outputs, evidence rules"]
    C --> D{"Smallest runtime<br/>that fits the job"}

    D --> E["Skill / plugin only<br/>workflow guidance, prompts, templates, subject overlays"]
    D --> F["Literature MCP<br/>OpenAlex, Semantic Scholar, Crossref, PubMed, arXiv"]
    D --> G["Zotero companion<br/>local library search, import files, reference review tags"]
    D --> H["Full CLI / orchestrator<br/>doctor, task-plan, preview task-run, optional agent run"]

    E --> I["Route the stage<br/>A framing, B literature, C design, F writing, I code, H rebuttal..."]
    F --> J["Collect search evidence<br/>queries, provider status, diagnostics, dedup and screening readiness"]
    G --> K["Sync reference context<br/>local Zotero results, CSL/RIS/BibTeX exports, review queues"]
    H --> L["Run controlled execution<br/>controller, primary, reviewer, verifier, solo/duo/triad mode"]

    I --> M["Quality gates<br/>claim boundary, citation risk, method fit, code review, verification status"]
    J --> M
    K --> M
    L --> M

    M --> N["Write artifacts<br/>RESEARCH/[topic]/ context, search logs, plans, drafts, code, reviews"]
    N --> O{"Human or agent review"}
    O -->|revise| C
    O -->|accepted| P["Auditable package<br/>evidence trail, decisions, outputs, and release/submission materials"]

Current Structure

Qiongli is split into four surfaces so you can install only what the task actually needs:

This separation matters most on Desktop. A manual Skill ZIP gives Claude Desktop/Web the Qiongli skill and subject overlays. A .mcpb install adds local literature-provider tools. The full local agent runtime stays in the CLI/MCP surface, where it can be configured and audited separately.

For Codex marketplace plugins, the bundled literature MCP is launched from the plugin bundle. Configure provider keys through qiongli_config_status and the local qiongli_configure_provider, not by putting secrets into .mcp.json or plugin manifests. The same setup tool is exposed by the Claude Desktop MCPB, Claude Code plugin runtime, and full CLI MCP server for other local MCP clients.

Installation Decision Guide

Start with the smallest surface that matches the job. In Qiongli, "full workflow" means the complete methodology, workflows, templates, quality gates, skill registry, and subject overlays. It does not automatically mean local provider calls or local agent execution.

Claude Code marketplace status: yes, Claude Code can install the Qiongli methodology through Skillsplace for core and subject complete packages. Codex and Claude Code both install the skill/command package plus the bundled zero-dependency Node literature MCP runtime for provider, search, and status tools. The full local product path is the CLI full profile and qiongli mcp serve --transport stdio.

Prerelease testing uses the separate qiongli-next marketplace entry. It installs only the core Qiongli workflow for Codex and Claude Code, keeps the bundled literature MCP runtime, and pairs with qiongli-next-claude-desktop-skill-core-<tag>.zip plus qiongli-literature-provider-<version>.mcpb for Claude Desktop. CLI prerelease testing uses npx qiongli@next ....

Detailed install instructions live in docs/guide/install.md. The quickest route from nothing installed is docs/quickstart.md.

Install Snippets

Native plugin installs:

# Codex
codex plugin marketplace add jxpeng98/skillsplace --ref main
codex plugin marketplace list

# Claude Code
claude plugin marketplace add jxpeng98/skillsplace@main
claude plugin install qiongli@skillsplace
claude plugin install qiongli-economics@skillsplace

# Prerelease channel
claude plugin install qiongli-next@skillsplace

npm / npx installs:

npm install -g qiongli
qiongli install --target all --project-dir "$PWD"
qiongli install --subject economics --target all --project-dir "$PWD"
qiongli install --subject accounting --target all --project-dir "$PWD"
qiongli install --subject economics-accounting --target all --project-dir "$PWD"
qiongli install --subject economics --coverage focused --target all --project-dir "$PWD"

# Prerelease testing
npx qiongli@next install --target all --project-dir "$PWD"
npx qiongli@next check --json

# Remove CLI-installed global assets before switching install channels
qiongli remove --target all --dry-run
qiongli remove --target all

Bootstrap installs:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/jxpeng98/qiongli/main/scripts/bootstrap_qiongli.sh | bash -s -- --profile partial --project-dir "$PWD" --target all
curl -fsSL https://raw.githubusercontent.com/jxpeng98/qiongli/main/scripts/bootstrap_qiongli.sh | bash -s -- --profile full --project-dir "$PWD" --target all

# Windows PowerShell 7+
pwsh -ExecutionPolicy Bypass -File .\bootstrap_qiongli.ps1 -Profile partial -ProjectDir "$PWD" -Target all
pwsh -ExecutionPolicy Bypass -File .\bootstrap_qiongli.ps1 -Profile full -ProjectDir "$PWD" -Target all

Use partial for skills and workflow discovery. Use full when you also need the shell CLI, doctor, validators, or local orchestrator execution.

Recommended CLI Setup Wizard

After npm, pipx, pip, or bootstrap installs, use the setup wizard when you want help choosing an install or upgrade path:

qiongli setup
qiongli setup --dry-run
qiongli setup --project-dir "$PWD" --no-doctor
qiongli install --target all --project-dir "$PWD"

The wizard covers install and upgrade, runtime surface (cli, codex, claude-code, antigravity, or multi-platform), subject, coverage, --mode copy|link, install scope, CLI directory / shell CLI location, --overwrite / --no-overwrite, optional provider config, and doctor verification unless --no-doctor is used.

On npm installs, qiongli setup delegates to the bundled Python bridge and therefore requires Python 3.12+ plus PyYAML. If you only need Node-based asset installation, use explicit qiongli install ... commands.

Provider keys entered through qiongli setup use the same provider config as qiongli provider setup and qiongli provider doctor. Secrets are stored in provider configuration outside generated research artifacts. Setup configures credentials and runs doctor/capability checks; it does not by itself guarantee external search results.

Remove CLI-installed Assets

Use qiongli remove (aliases: qiongli uninstall, qiongli delete) to remove CLI-installed global workflow assets and discovery links. It does not uninstall marketplace plugins such as qiongli or qiongli-next; remove those through the Codex, Claude Code, or Claude Desktop plugin manager that installed them.

Manual Desktop And MCP Boundaries

Claude Desktop / Claude.ai can use Qiongli without a terminal:

1. Download a release Skill ZIP such as qiongli-claude-desktop-skill-core-<tag>.zip or qiongli-claude-desktop-skill-economics-<tag>.zip.
2. Upload it through the Desktop/Web Skills flow.
3. Enable the uploaded qiongli skill.

The Desktop/Web ZIP uses coverage=focused to stay under the current 180-file upload budget. It is subject-specialized, not lower quality. It preserves workflows, prompts, templates, standards, selected profiles, skills-summary.md, skills-core.md, and selected effective skill markdown generated with layered overlays.

This Desktop skill ZIP is skill-only: it stores no secrets and does not execute provider calls. To add local Desktop literature tools, install the separate Qiongli Literature Provider .mcpb:

qiongli-literature-provider.mcpb

The MCPB runs a zero-dependency Node stdio server for OpenAlex, Semantic Scholar, Crossref, PubMed, and arXiv search, provider status, and provider key saving. arXiv is enabled without credentials. It supports provider setup through the local wizard, query variants, finance/economics deep-search routing, pagination, retry diagnostics, and limited citation/reference metadata expansion. Desktop users need qiongli-literature-provider MCPB or platform-native search before claiming provider_connected; otherwise record the run as strategy_only and treat platform search or a user-supplied corpus as the evidence source. Finance/economics data APIs such as FRED and SEC EDGAR belong in a separate data MCP surface; see Finance/Economics Data MCP Boundary.

The MCPB does not launch orchestrator agents. To expose the full Python-backed local product through MCP, install the npm, pipx/pip, or bootstrap full CLI runtime and configure:

qiongli install --profile full --target codex
qiongli mcp serve --transport stdio
qiongli mcp doctor --json
qiongli mcp config example --target codex --json
qiongli mcp config example --target claude-code --json
qiongli mcp config example --target antigravity --json
qiongli mcp config example --target hermes --json

The full CLI MCP server exposes:

• qiongli_config_status, qiongli_save_provider_config, and qiongli_collect_evidence
• qiongli_literature_status
• qiongli_literature_search
• qiongli_literature_export_evidence
• qiongli_orchestrator_route
• qiongli_orchestrator_doctor
• qiongli_task_plan
• qiongli_task_run

Use qiongli_orchestrator_route from Codex, Claude Code, Antigravity, or another local MCP client when a natural academic request might need multi-agent coordination, independent review, handoff, strict gates, or auditable task-run artifacts. It returns a preview-first doctor -> task_plan -> task_run sequence. qiongli_task_run defaults to preview mode. It launches local runtime agents only when the MCP caller explicitly sends JSON boolean run_agents: true and the local runtime passes doctor. Project-local guidance uses .qiongli/local_guidance.md and .qiongli/trace/, which the first non-off task run initializes if missing; formal task outputs still belong under RESEARCH/[topic]/....

See Cross-Platform MCP Server and MCP Providers Setup.

Subject Packages And Overlays

The user-visible skill name is qiongli. The installed directory remains qiongli-workflow for compatibility with existing clients and release artifacts.

Current official subjects:

• core
• economics
• accounting
• business
• finance
• political-economy
• geoeconomics
• economics-accounting

Default install means core/complete. CLI/npm specialized installs default to coverage=complete, so --subject economics means the full framework plus economics specialization, not a reduced package. Use --coverage focused only for deliberate slim packages and Desktop/Web ZIP-equivalent packages.

Subject specialization is layered:

• core owns shared workflow contracts, generic skills, templates, standards, and quality gates.
• Subject packages add discipline depth through selected profiles, append overlays, declared section replacements, and subject-specific skills.
• Effective packages are generated from skill_refs, subject overlays, layered section overrides, and optional local custom overlays.
• Generic skill source files are not duplicated.

Public Desktop ZIP subjects in this phase are core, economics, business, finance, political-economy, geoeconomics, and economics-accounting; there is no standalone accounting Desktop ZIP yet.

Local customization is available for source/Python workflows:

qiongli customize --subject economics --name my-econ-lab --out ./qiongli-custom/econ-lab
python3 scripts/materialize_subject_package.py --subject economics --custom-dir ./qiongli-custom/econ-lab --source . --out /tmp/qiongli-workflow

npm runtime installs use pre-generated payloads and do not accept runtime --custom-dir in this phase.

See Subject Packaging Model.

Workflow Runtime

Qiongli writes durable research artifacts under RESEARCH/[topic]/. The most common runtime checks are:

python3 -m bridges.orchestrator doctor --cwd .
python3 -m bridges.orchestrator task-plan --task-id F3 --paper-type empirical --topic ai-in-education --cwd .
python3 -m bridges.orchestrator task-run --task-id F3 --paper-type empirical --topic ai-in-education --cwd .

Useful controls:

• --execution-mode solo|duo|triad
• --controller codex|claude|antigravity
• --primary, --reviewer, and --verifier
• --solo-role-gates strict|standard|off
• --mcp-strict and --skills-strict
• --research-depth deep
• --only-target <id>

Full functionality requires a real Python runtime plus model CLIs in PATH: python3, codex, claude, and antigravity. You also need runtime authentication. codex can run with OPENAI_API_KEY or an existing ChatGPT/Codex login, claude uses ANTHROPIC_API_KEY or an existing Claude Code login, and antigravity uses the local Antigravity CLI login/configuration.

Without these runtime pieces, you can still install assets and use shell qiongli check|upgrade|align, but doctor, validators, tests, and full orchestrator execution will be partial or unavailable.

Academic Idea Boundary

Qiongli includes an Academic Idea Funnel and Academic Grill Loop before early-stage paper outputs. This is an academic adaptation of Matt Pocock's grill-me interaction pattern, not a generic grill-me clone. The adaptation turns one-question-at-a-time clarification into academic idea-discovery: claim strength, evidence threshold, rival explanations, feasibility, venue/reviewer risk, and the handoff into context/boundary_review.md.

The funnel artifact is:

RESEARCH/[topic]/context/idea_funnel.md

The boundary artifact is:

RESEARCH/[topic]/context/boundary_review.md

Source credit: Matt Pocock's skills repository.

Repository Map

Generated outputs are intentionally not normal feature-review targets. Normal feature PRs should update canonical source, tests, and documentation only. Release automation performs staged materialization into temporary roots, including plugins/qiongli/, plugins/qiongli-next/, packages/qiongli-plugin/, and packages/qiongli-next-plugin/.

When adding or deepening a subject, update content/subjects/catalog.yaml, subject overlays, subject-specific registry/markdown, selected profiles, eval fixtures, specialization audit expected terms, materializer tests, npm package contract tests against staged materialization, and release validation if the subject has a Desktop/Web artifact.

For agent and skill collaboration details, see Agent-Skill Collaboration. The legacy shell installer source remains available at scripts/install_qiongli.sh; most users should prefer the install paths in docs/guide/install.md.

Verification

Common local checks:

uv run python -m unittest tests.test_mcp_cli tests.test_mcp_tool_handlers tests.test_mcp_stdio_server -v
uv run python -m unittest tests.test_orchestrator_workflows tests.test_controller_agnostic_orchestration -v
uv run python scripts/validate_research_standard.py --strict
npm test --prefix packages/npm-qiongli
git diff --check

For runtime readiness:

uv run python -m bridges.orchestrator doctor --cwd .

More Documentation

• Quick Start
• Install Guide
• Using Agent Skills
• Task Recipes
• Multi-Agent Runtime Guide
• CLI Reference
• Architecture
• Cross-Platform MCP Server
• Plugin-First Architecture
• Controller Modes
• Subject Packaging Model

Design Lineage

Qiongli borrows useful ideas from existing agent-workflow projects while adapting them to academic research:

• fengshao1227/ccg-workflow: strict phase separation, spec -> plan -> execute -> review, and constrained execution.
• GuDaStudio/skills: reusable Claude-oriented collaboration skill packaging.
• Matt Pocock's grill-me skill: one-question-at-a-time clarification, adapted here into the Academic Idea Funnel and Academic Grill Loop for defensible scholarly idea formation.

Community Credit

Thanks to the linux.do community for being an open Chinese-language space for practical AI tooling, developer workflow, and local-first productivity discussions. Qiongli will be shared there as the workflow matures, both to reach more users and to collect direct feedback.