open-paper-analysis

Open Paper Analysis

Read one paper deeply. Publish one verified manuscript everywhere.

A portable Agent Skill for evidence-grounded research notes in Markdown, Notion, and Feishu/Lark.

English | 简体中文 | Documentation | Worked example

Open Paper Analysis turns a paper, PDF, DOI, title, project page, code repository, or existing note into one deep semantic manuscript. The same research judgment is then rendered for one or more platforms without rewriting the analysis independently for each destination.

[!IMPORTANT] Markdown is the zero-configuration default and universal fallback. Notion and Feishu/Lark are optional publishing backends. API keys, OAuth tokens, private page IDs, and personal workspace schemas never belong in this repository or its configuration file.

Recommended Agents

The canonical Skill lives at skills/analyze-paper/. Any host that can load an Agent Skills-style directory can use the same source.

"Reviewed" means the public loading contract or package structure has been checked. It does not mean every third-party runtime is covered by this repository's CI. See Install for Your Agent for exact commands and the honest verification boundary.

Quick Start

git clone https://github.com/wanng-ide/open-paper-analysis.git
cd open-paper-analysis
./scripts/install.sh --target codex

Then ask your agent in ordinary language:

Use the analyze-paper skill to analyze https://arxiv.org/abs/2401.06066 in
Chinese. Create a deep Markdown note and keep exact Figure/Table markers.

Or request several outputs from the same analysis:

Analyze this paper deeply. Write Markdown and publish the same manuscript to
Notion and Feishu. Use media markers unless an open-license key figure is
essential.

Without configuration, a writable run creates paper-notes/<paper-slug>.md. In a read-only environment, the agent returns the complete Markdown directly. Remote publishing never blocks the Markdown fallback.

Worked Example

The DeepSeekMoE worked example is a complete Chinese model/method analysis, not a shortened demo. It shows one manuscript rendered to all three backends while preserving identity, evidence, chapter meaning, metrics, limitations, and research judgment.

The canonical fixtures contain no workspace URL, page ID, document token, signed media URL, credential, account identity, or local path. The Notion captures retain owner-approved visible recorder and comment metadata, but no private identifiers or credentials. See the full example guide for the reading path, cross-target mapping, and screenshot review boundary.

What It Produces

Every requested target reports success, partial, or blocked independently. A failed remote write does not roll back a successful local note or another platform.

Why It Is Different

How It Works

flowchart LR
    A[Load analyze-paper] --> B{Isolated worker available?}
    B -- Yes --> C[Delegate one complete paper run]
    B -- No --> D[Run the same contract inline]
    C --> E[Resolve paper, targets, and duplicates]
    D --> E
    E --> F[Build evidence map and media manifest]
    F --> G[Draft one deep semantic manuscript]
    G --> H[Render Markdown, Notion, and/or Lark]
    H --> I[Read back and validate each target]
    I --> J[Return independent target statuses]

Subagents are used for isolation and context containment, not fragmented authorship. The worker receives the complete single-paper task, including source resolution, duplicate detection, analysis, rendering, and read-back verification. Hosts without isolated workers execute the same contract inline.

Install for Your Agent

All commands copy the one canonical Skill. --dry-run prints the destination; --force is required to replace an existing installation.

Codex

./scripts/install.sh --target codex

Claude Code

./scripts/install.sh --target claude

Kimi Code or a shared Agent Skills directory

./scripts/install.sh --target agents --dest "$HOME/.agents/skills"

OpenClaw

./scripts/install.sh --target agents --dest "$HOME/.openclaw/skills"

CodeBuddy CLI

./scripts/install.sh --target agents --dest "$HOME/.codebuddy/skills"

OpenCode

./scripts/install.sh --target agents --dest "$HOME/.config/opencode/skills"

For Tencent WorkBuddy, import the local skills/analyze-paper/ directory from its Skills interface. For any other host, pass the parent skills directory to --dest; the installer creates <destination>/analyze-paper.

Configuration

Configuration is optional. Copy config.example.toml to .open-paper-analysis.toml or ~/.config/open-paper-analysis/config.toml:

version = 2

[defaults]
outputs = ["markdown"]
language = "auto"
depth = "deep"

[media]
mode = "markers"
max_items = 6
license_policy = "open-or-approved"

[markdown]
notes_directory = "paper-notes"

The active request overrides configured outputs, language, and media mode. Notion and Feishu/Lark destination IDs may be configured, but credentials must remain in the agent host, connected MCP, or CLI credential store.

Documentation

• Getting started
• Configuration
• Output backends and safe updates
• Quality, media, and safety
• Development and verification
• Complete Chinese documentation

The English and Chinese guide collections are mirrored and checked in CI.

Repository Layout

skills/analyze-paper/        Canonical portable Skill
docs/en/                     English guides
docs/zh-CN/                  Chinese guides
examples/deepseekmoe/        Three-target golden example
evals/                       Behavioral evaluation cases
scripts/                     Installer and repository checks
tests/                       Validator tests

Verification

The validation pipeline checks the open Agent Skills format, installer matrix, bilingual documentation, local links, public-artifact privacy, three-backend fixture consistency, XML syntax, Markdown/Notion structure, media references, and credential-shaped values. Gitleaks scans full Git history.

npx --yes skills-ref@0.1.5 validate skills/analyze-paper
python scripts/check_markdown_links.py
python scripts/check_docs_parity.py
python scripts/check_public_artifacts.py
python scripts/validate_examples.py
python -m unittest discover -s tests -v
bash scripts/test-install.sh

Claude Code, Kimi Code, OpenClaw, WorkBuddy, CodeBuddy, OpenCode, and MaxClaw runtime smoke tests are not currently part of CI. Their status is kept explicit in the compatibility table instead of being implied by format compatibility.

Security

Read SECURITY.md before publishing fixtures or configuration. Never commit API keys, OAuth tokens, cookies, private database or page IDs, personal property schemas, signed media URLs, or local paths. Visible account or comment metadata in a documentation screenshot requires explicit owner approval and must not reveal private identifiers or authentication data.

License

Open Paper Analysis is released under the Apache License 2.0.