@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/formula-derivation/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: formula-derivation
+description: Structures and derives research formulas when the user wants to 推导公式, build a theory line, organize assumptions, turn scattered equations into a coherent derivation, or rewrite theory notes into a paper-ready formula document. Use when the derivation target is not yet fully fixed, the main object still needs to be chosen, or the user needs a coherent derivation package rather than a finished theorem proof.
+argument-hint: [problem-goal-current-formulas-or-notes]
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Formula Derivation: Research Theory Line Construction
+
+Build an honest derivation package, not a fake polished theorem story.
+
+## Constants
+
+- DEFAULT_DERIVATION_DOC = `DERIVATION_PACKAGE.md` in project root
+- STATUS = `COHERENT AS STATED | COHERENT AFTER REFRAMING / EXTRA ASSUMPTION | NOT YET COHERENT`
+
+## Context: $ARGUMENTS
+
+## Goal
+
+Produce exactly one of:
+1. a coherent derivation package for the original target
+2. a reframed derivation package with corrected object / assumptions / scope
+3. a blocker report explaining why the current notes cannot yet support a coherent derivation
+
+## Inputs
+
+Extract and normalize:
+- the target phenomenon, formula, relation, or theory line
+- the intended role of the derivation:
+  - exact identity / algebra
+  - proposition / local theorem
+  - approximation
+  - mechanism interpretation
+- explicit assumptions
+- notation and definitions
+- any user-provided formula chain, sketch, messy notes, or current draft
+- nearby local theory files if the request points to them
+- desired output style if specified:
+  - internal alignment note
+  - paper-style theory draft
+  - blocker report
+
+If the target, object, notation, or assumptions are ambiguous, state the exact interpretation you are using before deriving anything.
+
+## Workflow
+
+### Step 1: Gather Derivation Context
+Determine the target derivation file with this priority:
+1. a file path explicitly specified by the user
+2. a derivation draft already referenced in local notes
+3. `DERIVATION_PACKAGE.md` in project root as the default target
+
+Read the relevant local context:
+- the chosen target derivation file, if it already exists
+- any local theory notes, formula drafts, appendix notes, or files explicitly mentioned by the user
+
+Extract:
+- target formula / theory goal
+- current formula chain
+- assumptions
+- notation
+- known blockers
+- desired output mode
+
+### Step 2: Freeze the Target
+State explicitly:
+- what is being explained, derived, or supported
+- whether the immediate goal is:
+  - identity / algebra
+  - proposition
+  - approximation
+  - interpretation
+- what the derivation is expected to output in the end
+
+Do not start symbolic manipulation before this is fixed.
+
+### Step 3: Choose the Invariant Object
+Identify the single quantity or conceptual object that should organize the derivation.
+
+Typical possibilities include:
+- objective / utility / loss
+- total cost / energy / welfare
+- conserved quantity / state variable
+- expected metric / effective rate / effective cost
+
+If the current notes start from a narrower quantity, decide explicitly whether it is:
+- the true top-level object
+- a proxy
+- a local slice
+- an approximation
+
+Do not let a convenient proxy silently replace the actual conceptual object.
+
+### Step 4: Normalize Assumptions and Notation
+Restate:
+- all assumptions
+- all symbols
+- regime boundaries or special cases
+- which quantities are fixed, adaptive, or state dependent
+
+Identify:
+- hidden assumptions
+- undefined notation
+- scope ambiguities
+- whether the current formula chain already mixes exact steps with approximations
+
+Preserve the user's original notation unless a cleanup is necessary for coherence.
+If you adopt a cleaner internal formulation, keep that as a derivation device rather than silently replacing the user's target.
+
+### Step 5: Classify the Derivation Steps
+For every nontrivial step, determine whether it is:
+- **identity**: exact algebraic reformulation
+- **proposition**: a claim requiring conditions
+- **approximation**: model simplification or surrogate
+- **interpretation**: prose-level meaning of a formula
+
+Never merge these categories without signaling the transition.
+If one part is only interpretive, do not present it as if it were mathematically proved.
+
+### Step 6: Build a Derivation Map
+Choose a derivation strategy, for example:
+- definition -> substitution -> simplification
+- primitive law -> intermediate variable -> target expression
+- global quantity -> perturbation -> decomposition
+- exact model -> approximation -> interpretable closed form
+- general dynamic object -> simplified slice -> local theorem -> return to general case
+
+Then write a derivation map:
+- target formula or theory line
+- required intermediate identities or lemmas
+- which assumptions each nontrivial step uses
+- where approximations enter
+- where special-case and general-case regimes diverge or collapse
+
+If the derivation needs a decomposition, derive it from the chosen global quantity.
+Do not make a split appear magically from one local variable itself.
+
+### Step 7: Write the Derivation Document
+Write to the chosen target derivation file.
+
+If the target derivation file already exists:
+- read it first
+- update the relevant section
+- do not blindly duplicate prior content
+
+If the user does not specify a target, default to `DERIVATION_PACKAGE.md` in project root.
+
+Do NOT write directly into paper sections or appendix `.tex` files unless the user explicitly asks for that target.
+
+The derivation package must include:
+- target
+- status
+- invariant object
+- assumptions
+- notation
+- derivation strategy
+- derivation map
+- main derivation steps
+- remarks / interpretations
+- boundaries and non-claims
+
+Writing rules:
+- do not hide gaps with words like "clearly", "obviously", or "similarly"
+- define every symbol before use
+- mark approximations explicitly
+- separate derivation body from remarks
+- if the true object is dynamic or state dependent but a simpler slice is analyzed, say so explicitly
+- if a formula line is only heuristic, label it honestly
+
+### Step 8: Final Verification
+Before finishing the target derivation file, verify:
+- the target is explicit
+- the invariant object is stable across the derivation
+- every assumption used is stated
+- each formula step is correctly labeled as identity / proposition / approximation / interpretation
+- the derivation does not silently switch objects
+- special cases and general cases still belong to one theory line
+- boundaries and non-claims are stated
+
+If the derivation still lacks a coherent object, stable assumptions, or an honest path from premises to result, downgrade the status and write a blocker report instead of forcing a clean story.
+
+## Required File Structure
+
+Write the target derivation file using this structure:
+
+```md
+# Derivation Package
+
+## Target
+[what is being derived or explained]
+
+## Status
+COHERENT AS STATED / COHERENT AFTER REFRAMING / NOT YET COHERENT
+
+## Invariant Object
+[top-level quantity organizing the derivation]
+
+## Assumptions
+- ...
+
+## Notation
+- ...
+
+## Derivation Strategy
+[chosen route and why]
+
+## Derivation Map
+1. Target depends on ...
+2. Intermediate step A uses ...
+3. Approximation enters at ...
+
+## Main Derivation
+Step 1. ...
+Step 2. ...
+...
+
+## Remarks and Interpretation
+- ...
+
+## Boundaries and Non-Claims
+- ...
+
+## Open Risks
+- ...
+```
+
+## Output Modes
+
+### If the derivation is coherent as stated
+Write the full structure above with a clean derivation package.
+
+### If the notes are close but not coherent yet
+Write:
+- the exact mismatch
+- the corrected invariant object, assumption, or scope
+- the reframed derivation package
+
+### If the derivation cannot be made coherent honestly
+Write:
+- `Status: NOT YET COHERENT`
+- the exact blocker:
+  - missing object
+  - unstable assumptions
+  - notation conflict
+  - unsupported approximation
+  - theorem-level claim without enough conditions
+- what extra assumption, reframe, or intermediate derivation would be needed
+
+## Relationship to `proof-writer`
+
+Use `formula-derivation` when the user says things like:
+- “我不知道怎么起这条推导主线”
+- “这个公式到底该从哪个量出发”
+- “帮我把理论搭顺”
+- “把说明文档变成可写进论文的公式文档”
+- “这几段公式之间逻辑不通”
+
+Use `proof-writer` only after:
+- the exact claim is fixed
+- the assumptions are stable
+- the notation is settled
+- and the task is now to prove or refute that claim rigorously
+
+## Chat Response
+
+After writing the target derivation file, respond briefly with:
+- status
+- whether the target survived unchanged or had to be reframed
+- what file was updated
+
+## Key Rules
+
+- Never fabricate a coherent derivation if the object, assumptions, or scope do not support one.
+- Prefer reframing the derivation over overclaiming.
+- Separate assumptions, identities, propositions, approximations, and interpretations.
+- Keep one invariant object across special and general cases whenever possible.
+- Treat simplified constant-parameter cases as analysis slices, not as the conceptual main object.
+- If uncertainty remains, mark it explicitly in `Open Risks`; do not hide it in polished prose.
+- Coherence matters more than elegance.

package/dist/skills/gemini-search/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: gemini-search
+description: Search research papers via Gemini for broad literature discovery. Use when user says "gemini search", "gemini papers", "search with gemini", or wants AI-powered literature discovery beyond arXiv/Semantic Scholar indexes.
+argument-hint: [search-query]
+allowed-tools: Bash(*), Read, Write, mcp__gemini-cli__*
+---
+
+# Gemini Literature Search
+
+Search query: $ARGUMENTS
+
+## Role & Positioning
+
+This skill uses Gemini as a **broad literature discovery** source:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Latest preprints, cutting-edge unrefereed work |
+| `/semantic-scholar` | Semantic Scholar API | Published venue papers (IEEE, ACM, Springer) with citation counts |
+| `/deepxiv` | DeepXiv CLI | Layered reading: search, brief, section map, section reads |
+| `/exa-search` | Exa API | Broad web search: blogs, docs, news, companies, research papers |
+| `/gemini-search` | Gemini MCP / CLI | **AI-powered broad literature discovery** — searches across multiple angles, aliases, and sub-problems |
+
+Use Gemini when you want AI-driven discovery that goes beyond keyword matching — Gemini decomposes topics into sub-problems, explores naming variants, and surfaces papers that traditional API searches may miss.
+
+## Constants
+
+- **MAX_RESULTS = 15** — Target number of papers Gemini should find.
+- **MIN_YEAR = 2022** — Default minimum publication year. Override with `— year: 2020-`.
+- **DEFAULT_MODEL = auto-gemini-3** — Auto-routes within the Gemini 3 family (Pro / Flash) by server-side capacity. Required by `mcp__gemini-cli__ask-gemini` and `gemini-cli` v0.40+; explicit `gemini-3-pro-preview` can be silently downgraded to `gemini-2.5-pro` on OAuth-personal / Google One AI Pro accounts when capacity is exhausted. Override with `— model: gemini-3-flash-preview` (Gemini 3 Flash explicit, faster, higher quota), or `— model: gemini-2.5-pro` / `gemini-2.5-flash` (legacy, only for users on older `gemini-cli` < v0.40). The MCP tool accepts all of these verbatim.
+
+> Overrides (append to arguments):
+> - `/gemini-search "topic" — max: 20` — request up to 20 papers
+> - `/gemini-search "topic" — year: 2020-` — papers from 2020 onward
+> - `/gemini-search "topic" — code-only` — only papers with open-source code
+> - `/gemini-search "topic" — venues: NeurIPS,ICML,ICLR` — focus on specific venues
+> - `/gemini-search "topic" — model: gemini-3-flash-preview` — Gemini 3 Flash (faster, higher quota, less capable than Pro)
+> - `/gemini-search "topic" — model: auto-gemini-3` — auto-routes within the Gemini 3 family by load
+> - `/gemini-search "topic" — model: gemini-2.5-pro` — legacy (only if your `gemini-cli` < v0.40)
+
+## Environment & Setup
+
+### Prerequisites
+
+1. **Node.js** v16.0.0+
+2. **Google Gemini CLI** — installed and authenticated
+   ```bash
+   npm install -g @google/gemini-cli
+   gemini auth
+   ```
+3. **gemini-mcp-tool** — MCP bridge for Codex CLI ([jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool))
+   ```bash
+   npm install -g gemini-mcp-tool
+   ```
+
+### MCP Configuration
+
+Register the Gemini bridge in Codex CLI:
+
+```bash
+codex mcp add gemini-cli -- npx -y gemini-mcp-tool
+```
+
+### Authentication
+
+Gemini CLI uses your Google account or an API key. Export the key in your shell or project environment:
+
+```bash
+export GEMINI_API_KEY=your-key-here
+```
+
+- Free key from [Google AI Studio](https://aistudio.google.com/apikey)
+- Flash model (`gemini-2.5-flash`) has a generous free tier (500 req/min)
+
+### Available MCP Tools
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `mcp__gemini-cli__ask-gemini` | `prompt` (required), `model` (optional), `sandbox` (optional) | Ask Gemini for analysis or research; supports `@file` syntax |
+| `mcp__gemini-cli__sandbox-test` | `prompt` (required), `model` (optional) | Safe code execution in sandbox |
+| `mcp__gemini-cli__ping` | — | Connection test |
+| `mcp__gemini-cli__help` | — | Show Gemini CLI help |
+
+### Verify Setup
+
+```bash
+gemini --version
+```
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+- **query**: The research topic (required)
+- **max**: Override MAX_RESULTS
+- **year**: Minimum publication year (e.g., `2020-`)
+- **code-only**: Only include papers with open-source code
+- **venues**: Comma-separated venue filter
+- **model**: Override DEFAULT_MODEL
+
+### Step 2: Execute Search (MCP Priority)
+
+**Priority 1 — Gemini MCP** (preferred):
+
+Try calling `mcp__gemini-cli__ask-gemini` with the search prompt:
+
+```
+mcp__gemini-cli__ask-gemini({
+  prompt: 'You are a research literature scout. Search comprehensively for papers on: "QUERY"
+
+IMPORTANT CONSTRAINTS:
+1. Search from MULTIPLE angles — do not just use the exact query. Decompose the topic into sub-problems, aliases, neighboring tasks, and common benchmark/settings variants.
+2. Prefer papers that are genuinely relevant, not merely keyword-adjacent.
+3. Include top venues, journals, surveys, recent preprints, and papers with code when available.
+4. Focus on papers from MIN_YEAR onward unless older foundational work is necessary.
+
+For EACH paper found, provide ALL of the following in this exact format:
+- Title: [exact title]
+- Authors: [full author list]
+- Year: [publication year]
+- Venue: [exact conference/journal name + year, or "arXiv preprint" if not published]
+- arXiv ID: [format 2401.12345, or "N/A"]
+- DOI: [if available, or "N/A"]
+- Code URL: [GitHub/GitLab link if available, or "No code"]
+- Summary: [one-sentence core contribution]
+
+Find at least MAX_RESULTS papers with good coverage across:
+- strong recent papers from top venues
+- surveys/reviews if they exist
+- papers with open-source code
+- closely related variants of the topic
+
+Format as a numbered list with all fields for each paper.',
+  model: 'auto-gemini-3'
+})
+```
+
+**Priority 2 — Gemini CLI fallback** (if MCP unavailable):
+
+If `mcp__gemini-cli__ask-gemini` fails or is not configured, fall back to CLI:
+
+```bash
+gemini -p 'You are a research literature scout. Search comprehensively for papers on: "QUERY"
+...same prompt as above...' 2>/dev/null
+```
+
+- **Timeout**: 120 seconds
+- **Stderr**: Pipe to `/dev/null` — contains hook warnings, not part of the response
+
+**When to use which:**
+- MCP is preferred because it integrates natively with Claude Code's tool system, handles model selection, and avoids shell escaping issues.
+- CLI fallback ensures the skill works even when MCP is not configured or the MCP server process has crashed.
+
+### Step 3: Parse Results
+
+Extract structured paper information from Gemini's response. For each paper, normalize to:
+
+```
+{
+  title, authors, year, venue,
+  arxiv_id,    // "N/A" if not available
+  doi,         // "N/A" if not available
+  code_url,    // "No code" if not available
+  summary      // one-sentence contribution
+}
+```
+
+If Gemini returns fewer papers than requested, note this but do not re-query.
+
+### Step 4: Present Results
+
+Format results as a structured table:
+
+```
+| # | Title | Venue | Year | Code | Summary |
+|---|-------|-------|------|------|---------|
+| 1 | ... | NeurIPS 2024 | 2024 | [GitHub](url) | ... |
+| 2 | ... | IEEE TWC | 2023 | No | ... |
+```
+
+For each paper, also show:
+- **arXiv ID**: if available (for cross-reference with `/arxiv`)
+- **DOI**: if available (canonical link for published papers)
+- **Code**: GitHub/GitLab link or "No"
+
+### Step 5: Offer Follow-up
+
+After presenting results, suggest:
+
+```text
+/semantic-scholar "topic"    — search published venue papers with citation counts
+/arxiv "arXiv:XXXX.XXXXX"   — fetch specific preprint details
+/research-lit "topic" — sources: gemini, semantic-scholar  — combined multi-source review
+/novelty-check "idea"       — verify novelty against literature
+```
+
+## Key Rules
+
+- **MCP first, CLI second.** Always try `mcp__gemini-cli__ask-gemini` before falling back to `gemini -p`.
+- **Gemini is a discovery source, not a database.** Its results may include papers it "knows about" from training data. Always cross-verify critical details (exact titles, venues, years) via `/semantic-scholar` or `/arxiv` when precision matters.
+- **Do not use Gemini for citation counts.** It may hallucinate citation numbers. Use Semantic Scholar for authoritative citation data.
+- **Pipe stderr to `/dev/null` in CLI mode** — Gemini CLI emits hook warnings on stderr.
+- **Timeout generously in CLI mode** — Gemini's thorough search can take 30-60 seconds. Set timeout to 120s.
+- If both MCP and CLI are unreachable, suggest using `/semantic-scholar`, `/arxiv`, or `/research-lit "topic" — sources: web` as alternatives.