@f1star/dsh-research

English | 简体中文

@f1star/dsh-research is an installable DeepSeek Harness bundle for evidence-first paper work. It is a DSH bundle plugin, not a Codex plugin, and runs inside an existing DSH profile.

The bundle adds local native-text PDF reading, a durable paper library, and an auditable research-information workflow. It preserves exact source anchors and keeps quoted evidence distinct from authored notes, inferences, normalizations, comparison decisions, and syntheses.

What it adds

Capability	Tools and behavior
Paper reading	paper_import, paper_reading_pack, paper_outline, paper_search, and paper_read import a local PDF, collect bounded excerpts from recognized key sections, navigate its structure, search lexical matches, and recover exact surrounding blocks with physical-page, parser-revision, and quote-hash anchors.
Paper library	paper_library_register, paper_library_list, paper_library_get, and paper_library_alias retain paper identities, bibliography provenance, exact source versions, parser observations, and reversible aliases in profile storage.
Research integration	Research-question, evidence, note, claim, entity, observation, comparison-protocol, synthesis, matrix, audit, and research_review_render operations build a traceable record across papers. Synthesis inferences can retain explicit comparison protocols, and the renderer presents that comparison basis in review-ready Markdown without presenting authored interpretation as source text.

This standalone bundle mounts both the research services and their model-facing tool consumers in the selected profile. Installing it is an explicit grant to every agent started through that profile: each agent can see the research tool schemas and their stable prompt guidance.

Prerequisites

• A compatible dsh installation with pnpm available on PATH.
• A target profile containing @deepseek-ai/dsh-base followed by @deepseek-ai/dsh-web-app. The shipped web profile has this composition.
• Model credentials available through the normal DSH credential sources.
• Local PDFs readable under the session's filesystem permissions. Relative file paths resolve from the session workspace.

Install and run

Install the bundle into the shipped Web profile:

dsh plugin --profile web add github:F1star/dsh-research
dsh --profile web --dump-config
dsh web

The install command initializes the shipped web profile when it does not exist. The configuration dump lets you confirm that the @f1star/dsh-research layer and its research rows are present before booting the profile.

A GitHub install follows the selected Git ref. After a tag or commit you trust is available, pin it for reproducible installation:

dsh plugin --profile web add github:F1star/dsh-research#<tag-or-commit>

Restart a running profile after adding, updating, or removing the bundle.

Recommended workflow

1. Import a PDF with paper_import, use paper_reading_pack for a bounded first pass over recognized key sections, inspect headings with paper_outline, find additional blocks with paper_search, and call paper_read before relying on a passage.
2. Register the retained document with paper_library_register. Keep the returned paper, source-version, document, block, parser-version, physical-page, and quote-hash identifiers with your notes.
3. Create a research question, capture exact evidence, and record reading notes or passage questions. Write source statements separately from explicit inferences.
4. When comparing numeric results, normalize the method, dataset, metric, value, unit, split, uncertainty, evaluation protocol, and conditions for each paper. Record an explicit comparison protocol only after the retained fields are compatible.
5. Use the matrix and audit views to find missing or stale support, then write structured synthesis findings that cite active source claims. Every durable finding stores the required comparisonProtocolIds service field; research_synthesis_write exposes it as the optional comparison_protocol_ids input and records an omitted input as an empty array. Source summaries cannot link a protocol. A non-empty array is accepted only on an inference, may contain only active, non-stale protocols, and requires claim_ids to include every resultClaimId from every observation in each linked protocol. Pass an explicit active synthesis id to research_review_render to obtain paged Markdown with Comparison basis sections plus evidence and bibliography ledgers.

You can describe the task in natural language; the agent chooses the tools. For example:

Import papers/one.pdf and build a reading pack for its abstract, introduction, method, results, limitations, and conclusion. Use the outline and search tools for anything the pack misses, and read the surrounding blocks before relying on them. Register the paper, create a research question about dataset effects, capture exact evidence for each source statement, normalize the reported results, record a comparison protocol only when they are compatible, link it from a synthesis inference, and render that synthesis as a review draft.

paper_reading_pack recognizes a closed set of English and Chinese section labels and returns individually anchored source blocks, subject to the configured text budget and explicit text_truncated flags. It does not summarize those blocks, and an entry in missing_roles means only that the parser did not recognize a matching label. research_review_render likewise does not write new findings: it renders one selected active synthesis and labels source summaries, inferences, evidence relations, current verification state, and incomplete bibliography metadata. A linked inference also receives a Comparison basis drawn from its retained comparison protocols; that authored compatibility decision does not establish statistical significance or turn an inference into source text. Exact selected text is opt-in through include_selected_quotes; every continuation page must reuse the first page's render_digest, so a changed record cannot be silently combined with an earlier page. A ready-with-warnings result requires review before publication.

Configuration

The bundle rows live in cordis.patch.yml, while each plugin's schema supplies its defaults. A profile's own cordis.patch.yml is applied later and can override a row by id. A row override replaces its complete config value rather than merging individual keys, so retain parserProvider: pdfjs when overriding f1star-research-document unless another registered parser is intentional. The reading-pack controls on f1star-tool-research-document default to 12 blocks per section, at most 14 blocks per section, and at most 7 requested sections; defaultReadingPackBlocksPerSection must not exceed maxReadingPackBlocksPerSection, and maxOutputTextChars must be at least maxReadingPackSections × maxReadingPackBlocksPerSection. That text budget covers variable source fields; fixed provenance anchors and notices are additional bounded output. f1star-research-information.maxClaimReferencesPerFinding defaults to 256 so one comparison protocol at the default observation limit can retain every result claim; a finding that combines several protocols can still reach this explicit limit and should be split or deliberately reconfigured. maxComparisonProtocolReferencesPerFinding defaults to 64. f1star-tool-research-information.maxReviewTextChars defaults to 2,000,000 UTF-16 code units and fails a complete review closed before paging if that limit is exceeded.

For a custom profile, compose the bundles in this order:

1. @deepseek-ai/dsh-base
2. @deepseek-ai/dsh-web-app
3. @f1star/dsh-research

Installing this bundle into a custom profile that contains only the base bundle fails because the filesystem, tool, system-prompt, and durable-storage services supplied by the Web layer are absent.

Data and limitations

• Paper identities, source observations, research questions, evidence, notes, claims, entities, observations, comparison protocols, and syntheses are stored in the selected profile's durable storage and can be visible across sessions using that storage.
• Parsed PDF pages are process-local. After a restart, import the PDF again before reading blocks or capturing new evidence. The library records identities and observations, not the source PDF bytes.
• Evidence records retain exact block text and provenance, but reconstructing an historical PDF still requires your own durable copy of the source file.
• PDF.js extracts native text only. Scanned or image-only documents require OCR outside this bundle and do not support a text claim from the import.
• Reading-pack recognition depends on extracted heading labels and approximate reading order. A missing role does not establish that the paper omits the corresponding topic.
• Search and library matching are lexical. The bundle does not provide semantic retrieval, remote DOI or arXiv verification, automatic claim clustering, or automatic entity resolution.
• Numeric observations and comparison protocols are authored normalizations. Linking a protocol to a synthesis inference records its explicit comparison basis; the bundle still does not silently convert units or aliases, rank results, calculate deltas, infer statistical significance, or perform meta-analysis.
• Review rendering is a deterministic Markdown projection of retained records, not automatic literature-review generation or a formal CSL/BibTeX citation exporter. It always emits exact selection hashes and offsets, includes selected text only when explicitly requested, and otherwise emits locators instead of repeating complete evidence blocks.

Upgrading from 0.2

Version 0.3 raises the research_information durable domain from version 4 to version 5 because every synthesis finding now stores a required comparison-protocol reference array. There is no automatic version 4-to-5 migration. Back up the selected profile's storage before updating. If it already contains version 4 research-information data, version 0.3 refuses to open that domain with a version mismatch and leaves the data untouched; pin the bundle to v0.2.0 to access that data again. The version 1 paper-library domain is unchanged.

Update or remove

dsh plugin --profile web update @f1star/dsh-research
dsh plugin --profile web remove @f1star/dsh-research

Removing the bundle stops mounting its services and tools. It does not delete source PDFs, and research records can remain in the profile's storage; manage that storage separately if you need archival or deletion.

See the DeepSeek Harness guide to packaging and installing bundle plugins for profile and layer behavior.

License

MIT. This standalone distribution is derived from the DeepSeek Harness research packages and retains their 2026 DeepSeek copyright notice. See LICENSE and THIRD_PARTY_NOTICES.md.