@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.
Version 0.4 adds an archived-PDF research workspace, optional OCR, human review, cited report exports, and recoverable research tasks. It preserves exact source anchors and keeps quoted evidence distinct from authored notes, inferences, normalizations, comparison decisions, and syntheses.
Upgrade warning: 0.3 profile data cannot be opened directly by 0.4. Back up existing storage and use fresh, separate profile storage; see upgrading.
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. |
| Scientific extraction | paper_structure pages through located tables, formula text, and chart extraction with exact parser-revision pins. The optional Docling provider supplies OCR and generated scientific structures. |
| Research workspace | Open Research in the Web sidebar to browse archived PDFs, retain reading positions, write notes, inspect matrices, and review claims and numeric observations as a registered researcher. |
| Reports and tasks | Download Markdown, LaTeX, BibTeX, CSL-JSON, and provenance files. research_task_list, research_task_get, and research_task_write retain explicit workflow checkpoints, pause/resume state, and stale-source warnings. |
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 https://github.com/F1star/dsh-research/releases/download/v0.4.0/dsh-research.tgz
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
- 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.
- 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.
- Create a research question, capture exact evidence, and record reading notes or passage questions. Write source statements separately from explicit inferences.
- 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.
- 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:
@deepseek-ai/dsh-base@deepseek-ai/dsh-web-app@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.
- Original PDF bytes and exact parsed revisions are archived in profile storage and can be restored after restart. Back up the complete profile storage; a paper-library record alone is not an archive backup.
- PDF.js extracts native text only. Scanned documents need the optional Docling setup. OCR, formula, and chart outputs can contain recognition errors and must be verified against the original; extraction is not scientific validation.
- 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.
research_review_render remains a deterministic Markdown projection with exact hashes, offsets, and opt-in selected text. The workspace additionally exports citation files and LaTeX through the report service; incomplete metadata and evidence remain visible as warnings. Neither path grants publication approval.- Task checkpoints survive restart; running agent executions never silently restart. The execution service requires an explicit trusted-client start, uses bounded steps/time/concurrency, and stops for required human review. Dedicated execution start/stop/history controls in the browser are not yet included; task creation, progress inspection, pause, and resume are included.
Upgrading from 0.3
Version 0.4 uses research_library version 2 and research_information version 7. Version 7 preserves standalone 0.3 synthesis comparison fields while adding human review records; it is not interchangeable with the source application's version 6. There is no automatic migration. Stop the old profile, back up its complete storage, and use separate fresh storage for 0.4. Unsupported versions fail without modifying old records; pin v0.3.0 to reopen unchanged 0.3 data. Do not delete storage to suppress a version error. Older 0.2 data likewise requires its matching plugin version.
See architecture for package roles, generated browser descriptors, and execution ownership. Run pnpm install && pnpm run check to build and test the standalone checkout; GitHub and release installations use committed prebuilt artifacts without install-time compilation.
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.
