research-assist

Category: Tools & Productivity | Uploader: zhanglg12 | Downloads: 0 | Version: v1.0（Latest）

A lightweight arXiv literature digest skill for OpenClaw, with Zotero-driven interest profiling, research-map plus Zotero-semantic ranking, agent-enriched digest cards, and non-destructive feedback writeback.

Changelog: Source: GitHub https://github.com/zhanglg12/research-assist

Directory Structure

Current level: Root

📁 assets/
- 📁 readme/
  - 📄 digest-cards.svg 5.3 KB
  - 📄 feedback-loop.svg 3.8 KB
  - 📄 hero-overview.svg 4.6 KB
  - 📄 profile-map-card.svg 3.9 KB
  - 📄 six-stage-chain.png 601.1 KB
📁 automation/
- 📁 prompts/
  - 📄 candidate-review.prompt.txt 1.0 KB
  - 📄 profile-refresh.prompt.txt 2.0 KB
  - 📄 review-fill.prompt.txt 3.8 KB
  - 📄 task.prompt.txt 233 B
  - 📄 zotero-feedback.prompt.txt 787 B
- 📄 arxiv-profile-digest.example.toml 256 B
📁 profiles/
- 📄 research-interest.example.json 1.5 KB
📁 references/
- 📄 contracts.md 2.9 KB
- 📄 distribution.md 2.3 KB
- 📄 profile-map-generation.md 2.6 KB
- 📄 review-generation.md 5.4 KB
- 📄 setup-routing.md 21.7 KB
- 📄 workflow.md 3.0 KB
- 📄 zotero-feedback.md 2.5 KB
- 📄 zotero-mcp.md 2.3 KB
📁 reports/
- 📁 schema/
  - 📄 candidate-card.schema.json 10.6 KB
  - 📄 candidate-review.schema.json 4.3 KB
  - 📄 controller-run.schema.json 3.1 KB
  - 📄 digest-run-summary.schema.json 2.1 KB
  - 📄 research-digest.schema.json 7.7 KB
  - 📄 review-patch.schema.json 3.5 KB
  - 📄 zotero-feedback.schema.json 2.7 KB
📁 scripts/
- 📁 distribution/
  - 📄 build_skill_package.py 2.8 KB
  - 📄 install_skill.sh 2.0 KB
- 📁 repro/
  - 📄 real_zotero_flow.py 9.8 KB
  - 📄 run_real_zotero_flow.sh 379 B
📁 src/
- 📁 codex_research_assist/
  - 📁 arxiv_profile_pipeline/
    
    📄 __init__.py 13 B
    
    📄 client.py 2.6 KB
    
    📄 literature_sources.py 22.1 KB
    
    📄 parser.py 5.3 KB
    
    📄 pipeline.py 21.5 KB
    
    📄 profile_contract.py 5.8 KB
    
    📄 query.py 2.8 KB
  - 📁 controller/
    
    📄 __init__.py 56 B
    
    📄 profile_refresh_policy.py 4.7 KB
  - 📁 zotero_mcp/
    
    📄 __init__.py 114 B
    
    📄 chroma_client.py 18.0 KB
    
    📄 client.py 29.9 KB
    
    📄 config.py 6.8 KB
    
    📄 feedback.py 5.9 KB
    
    📄 local_db.py 14.8 KB
    
    📄 profile_evidence.py 2.4 KB
    
    📄 semantic_search.py 18.0 KB
    
    📄 semantic_utils.py 348 B
    
    📄 server.py 12.7 KB
  - 📄 __init__.py 49 B
  - 📄 __main__.py 121 B
  - 📄 digest_summary.py 1.6 KB
  - 📄 email_sender.py 3.5 KB
  - 📄 html_fmt.py 37.7 KB
  - 📄 openclaw_runner.py 50.8 KB
  - 📄 profile_refresh_output.py 987 B
  - 📄 ranker.py 8.8 KB
  - 📄 review_digest.py 6.1 KB
  - 📄 review_patch.py 6.5 KB
  - 📄 telegram_fmt.py 3.3 KB
  - 📄 telegram_sender.py 3.6 KB
📁 temp/
- 📁 semantic-test/
  - 📄 semantic-config.example.json 726 B
  - 📄 USAGE.md 1.0 KB
📁 tests/
- 📄 test_digest_summary.py 4.0 KB
- 📄 test_distribution.py 2.3 KB
- 📄 test_feedback.py 10.0 KB
- 📄 test_html_output.py 6.0 KB
- 📄 test_literature_sources.py 7.0 KB
- 📄 test_ranker.py 6.5 KB
- 📄 test_review_contracts.py 1.1 KB
- 📄 test_review_digest.py 3.2 KB
- 📄 test_review_patch.py 5.5 KB
- 📄 test_schema_alignment.py 3.4 KB
- 📄 test_semantic_setup.py 6.4 KB
- 📄 test_zotero_support.py 9.7 KB
📄 .gitignore 458 B
📄 config.example.json 2.0 KB
📄 LICENSE 1.0 KB
📄 pyproject.toml 1.1 KB
📄 README.md 15.4 KB
📄 README.zh-CN.md 15.6 KB
📄 SKILL.md 11.1 KB
📄 uv.lock 576.0 KB

SKILL.md

---
name: research-assist
description: A lightweight arXiv literature digest skill for OpenClaw, with Zotero-driven interest profiling, research-map plus Zotero-semantic ranking, agent-enriched digest cards, and non-destructive feedback writeback.
---

# Research Assist Skill

An OpenClaw skill that turns Zotero evidence into a profile-driven literature digest, using arXiv by default and optionally expanding recall with OpenAlex and Semantic Scholar before deduplication.

## CLI Usage

```bash
# Full digest: profile check → literature retrieval → rank → markdown output
uv run --project ~/.openclaw/skills/research-assist \
  research-assist --action digest --config ~/.openclaw/skills/research-assist/config.json

# Ad-hoc literature search
uv run --project ~/.openclaw/skills/research-assist \
  research-assist --action search --query "gaussian process" --top 5

# Check profile refresh status
uv run --project ~/.openclaw/skills/research-assist \
  research-assist --action profile-refresh --config ~/.openclaw/skills/research-assist/config.json

# Zotero MCP server (for profile evidence + feedback writeback)
uv run --project ~/.openclaw/skills/research-assist research-assist-zotero-mcp
```

Or via Python module:

```bash
uv run --project ~/.openclaw/skills/research-assist \
  python -m codex_research_assist --action digest --config ~/.openclaw/skills/research-assist/config.json
```

Default config path: `~/.openclaw/skills/research-assist/config.json`

During install or reconfiguration, do not embed the full setup questionnaire in this file. Use `references/setup-routing.md` as the install-time interaction guide, ask only the questions relevant to the user's goal, then edit `config.json` directly.

## Install-Time Behavior

Installation and reconfiguration are one-time operations.

Hard rules for the host agent:

- use `references/setup-routing.md` only when the user is installing, reconfiguring, or when required config is missing
- once `config.json` is valid, normal digest/search/render/feedback runs must not reopen setup questions
- do not restate dormant install options during regular literature work
- if the user asks for normal runtime work, prefer using the existing config over discussing installation
- when setup selects optional backends or delivery routes, execute the required install/setup commands instead of only listing them
- before leaving setup, run a minimal verification for the selected backend or route and report the result
- only fall back to manual instructions when a step is blocked by missing secrets, missing local services, missing permissions, or a platform limitation

## Config Format

```json
{
  "profile_path": "~/.openclaw/skills/research-assist/profiles/research-interest.json",
  "output_root": "~/.openclaw/skills/research-assist/reports",
  "retrieval_defaults": {
    "max_results_per_interest": 20,
    "since_days": 7,
    "max_age_days": 7
  }
}
```

## Architecture

```
config.json (OpenClaw skill config)
    ↓
openclaw_runner.py (CLI entry, markdown to stdout)
    ├── profile_refresh_policy  → check if profile needs update
    ├── pipeline.py             → multi-source literature retrieval (arXiv default)
    ├── ranker.py               → two-signal scoring (map_match + zotero_semantic)
    └── format_*_markdown()     → structured markdown output
```

No LLM calls inside the packaged Python pipeline. Retrieval, ranking, and formatting are pure data operations.
Intelligence comes from the calling agent (OpenClaw / Claude Code / Codex CLI).

Profile refresh should be handled by the OpenClaw controller or agent layer, using live Zotero evidence via the bundled Zotero MCP.

## Workflow Stages

### 1. `profile_update`

- read the current Zotero evidence base when refresh is required
- maintain `profiles/research-interest.json`
- preserve the compact contract: `method_keywords`, `query_aliases`, `exclude_keywords`
- keep method labels short and retrieval-friendly
- prefer `zotero_semantic_search` for discovery, then `zotero_search_items` for exact resolution
- use `research-assist-zotero-mcp` for live Zotero reads (no direct API calls)

OpenClaw generation rule:

- treat Zotero like a studio palette, not a flat folder dump
- use collection structure as the sketch of the research map
- use representative papers as the main evidence for what each region actually contains
- use semantic search as the blending layer that connects nearby themes across collections
- write interests that feel like stable method axes, not loose keyword bags
- aim for about 6 interests by default; usually stay in the 4-8 range unless the evidence strongly says otherwise
- if the draft has too few interests, split mixed regions by real method differences; if it has too many, merge nearby regions that share one stable method axis
- if collection names and paper content disagree, trust the papers more than the folder label
- if summary terms are frequent but too generic, use them only to refine wording, not to define the map
- the final profile should read like a compact map of the user's research territory: a few clear regions, each with short labels and retrieval-friendly aliases

### 2. `retrieval`

- query arXiv by default, optionally add OpenAlex and Semantic Scholar per interest
- expand the paper pool before ranking when multiple sources are enabled
- generate structured candidate JSON with full provenance
- deduplicate across interests and across enabled sources

### 3. `review`

- rank candidates with two-signal scoring:
  - **map_match** (0.30): how well the paper fits the current research-map slices
  - **zotero_semantic** (0.70): how close the paper is to nearby Zotero literature
- apply the low-map guard:
  - if `map_match < 0.30`, apply the configured penalty to avoid semantic-only false positives
- output ranked markdown to stdout for agent review
- prefer a smaller sharper set over a noisy dump
- stay `abstract-first`

### Digest Enrichment

- OpenClaw should treat agent-filled review as the default digest-enrichment path
- after retrieval, let the host agent enrich the top-ranked candidate JSON files with review patches
- use `review_generation.agent_top_n` to cap how many ranked candidates the host agent needs to inspect
- let the host agent decide the final visible subset by setting `review.selected_for_digest`
- use `review_generation.final_top_n` as the hard upper bound for the final rendered digest
- keep `fallback_to_system` enabled unless the user explicitly wants hard failure instead of fallback text
- after patches are applied, re-render the digest so HTML / Telegram outputs use the enriched review text
- `why_it_matters` should sound like a recommendation, not a provenance report
- `caveats` should capture real uncertainty or scope boundaries, not generic hedging
- the host agent should also fill `review.zotero_comparison`, including nearest-neighbor fallback when candidate-level evidence is missing
- keep nearest-neighbor output compact: usually 1-2 items
- the host agent is not responsible for email / telegram wrapper copy, subjects, or routing

### Delivery Routing

- use one shared delivery path and branch at the end with `delivery.primary_channel`
- default primary channel is `email`; `telegram` is backup or alternate primary
- channel wrappers are system-owned:
  - email subject/body/profile card/stat cards
  - telegram compact message shell
- do not ask the host agent to generate channel-specific wrappers

### Stage 6: `feedback_sync`

After the digest is reviewed and delivered, the host agent may push non-destructive feedback back into Zotero.

Workflow:

1. collect the user's explicit feedback on each digest candidate (keep, drop, archive, watch, etc.)
2. encode feedback as `reports/schema/zotero-feedback.schema.json`
3. call `zotero_apply_feedback` through the bundled Zotero MCP with `dry_run=true` first
4. show the dry-run plan to the user and ask for confirmation before applying
5. only after confirmation, re-run with `dry_run=false`

Allowed feedback decisions:

- `read_first` — high-priority paper, tag and promote in library
- `skim` — worth scanning, tag for later review
- `watch` — track this topic area, add to watchlist collection
- `skip_for_now` — not relevant now, mark but do not remove
- `archive` — reviewed and filed, move to archive collection
- `watchlist` — add to a standing watchlist for periodic check-in
- `ignore` — not relevant, tag to suppress in future runs
- `unset` — no decision yet, skip writeback for this item

What feedback can do (non-destructive only):

- add tags (including `ra-status:*` decision tags)
- add or change collection membership
- append notes to items
- create new collections if needed for organization

What feedback must never do:

- delete Zotero items or collections
- modify item metadata (title, authors, abstract, DOI)
- move or delete attachment files
- rewrite top-level taxonomy without explicit user instruction
- apply changes without showing the dry-run plan first

Matching behavior:

- match items by `item_key` (preferred), `doi`, or `title_contains`
- at least one match field must be provided per decision
- DOI matching is case-insensitive
- `title_contains` uses substring match (not exact)
- if no match is found, the decision is recorded as `not_found` in the plan

Edge cases:

- duplicate tags are deduplicated (case-insensitive)
- previous `ra-status:*` tags are replaced when a new decision is applied
- the `research-assist` system tag is always preserved
- `unset` decisions produce no status tag and no writeback
- empty `add_tags`, `remove_tags`, `add_collections`, `remove_collections` are allowed (no-op for that field)

## Hard Rules

- do not expand concise method labels into long topic sentences
- do not make full text the default review mode
- do not delete Zotero items or collections automatically
- prefer `dry_run=true` for any Zotero writeback
- do not treat scheduler wiring as part of the skill

## Key Runtime Files

- OpenClaw runner: `src/codex_research_assist/openclaw_runner.py`
- Ranker: `src/codex_research_assist/ranker.py`
- Pipeline: `src/codex_research_assist/arxiv_profile_pipeline/pipeline.py`
- Example config: `config.example.json`
- Example profile: `profiles/research-interest.example.json`

## Reference Documents

- `references/workflow.md` — stage order and controller boundary
- `references/contracts.md` — profile contract and review policy
- `references/distribution.md` — packaging include/exclude rules
- `references/setup-routing.md` — install-time route selection and option questions
- `references/review-generation.md` — `system` vs `agent_fill` review contract
- `references/profile-map-generation.md` — how to turn Zotero evidence into a research-map-style profile

## Packaging Boundary

Include in distributable skill:

- `SKILL.md`, `config.example.json`, `pyproject.toml`, `uv.lock`
- `src/`
- `references/`
- `profiles/research-interest.example.json`
- `automation/arxiv-profile-digest.example.toml`
- `automation/prompts/`
- `reports/schema/`
- generated package-root `install.sh`

Exclude:

- generated reports, temporary state
- local secret config
- scheduler wrappers
- repository planning documents (`NEXT_PLAN.md`, `CODEMAP.md`)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

research-assist

Directory Structure

SKILL.md

Report

Notice