dsh-sciwork

A complete "doing research" workbench for DSH (DeepSeek Harness): an agent preset called Research Mode, plus a real, on-disk research library.

Version 0.3.14 · MIT · by 58catmiao · repo https://github.com/58catmiao/dsh-sciwork

中文: README.md

What this is

dsh-sciwork is not another "chat with your papers" box. It is a research workbench that lives on your disk and can be opened by other tools. Install it and you get four things at once:

1. An agent preset, "Research Mode" — it folds plotting, writing, references and journal rules into one workflow: find the evidence first, then act. Figures are made on a real Origin install, and every reference cited in a manuscript must carry a DOI or a URL.
2. A real, on-disk research library — an ordinary directory tree (projects / figures / data / drafts / references / journal profiles / submissions), a Python engine research.py, and a registration index.
3. 12 journal submission profiles — Nature, Science, Cell, IEEE Trans, ACS, a generic Elsevier profile, MDPI, PLOS ONE, Chinese core journals, CNKI theses, GB/T 7714, and a generic thesis profile, each with its numeric requirements, clauses and citations to their sources.
4. A visual "Research Library" panel plus a set of skills — a workbench by default (v2), a seven-tab classic panel one click away, read-only by and large, with filtering, import and archive; the skills pin down how to plot, write and cite.

The filesystem is always the authority. The index is only a cache, and the panel never writes to it — every panel write goes through the library scripts. That means you can zip up the whole library and move it, or touch it directly with a file manager, Git, or any other editor.

• The host half is plain Node ESM with zero npm dependencies.
• The client is a hand-written single-file web client with no build step.
• Plotting depends on the upstream open-source plugin dsh-origin-plugin (MIT, by Fantasality). This repository does not include it — it ships only an adaptor skill. See "Relationship to dsh-origin-plugin" below.

What is new in 0.3

• One action registry drives the panel, the agent tools, and the CLI — new capabilities are written once.
• Writes need confirmation: plan first (which files, which warnings), then a single-use token, then a receipt. Reads never write receipts.
• Projects are first-class: seven-stage state machine plus artifact hashes; legacy projects are migrated explicitly (backup first, idempotent, per-project rollback).
• Workbench by default: the workbench (v2) opens first; one button in the page header switches back to the classic list panel (v1), the choice is remembered, and switching keeps the last tab. Layout: page header (title, stats, Chinese primary actions) → KPI strip (projects / figures / references / open submissions) → cross-project todo table → dashboard → two-column project detail. The dashboard carries today, submission countdown, library health, recent changes and backup status; every todo row copies a ready-to-paste "生成指令" instruction. The header's 快速登记 builds a Chinese form from the CLI command table (references / figure provenance / submission) and still goes through plan → confirm → receipt.
• Clickable seven-stage bar: every stage in a project is a button that runs project.stage.set (jumping forward passes force, stepping back resets later stages to todo).
• The panel ships its own palette and type: twelve --rl-* variables in a "graphite blue" palette (light and dark via light-dark()), no host colour tokens, body/secondary/primary contrast ≥ 4.5:1; Noto Sans SC with Microsoft YaHei / system-ui fallbacks and tabular numerals.
• Real figure folders are visible again: _-prefixed figure folders such as figures/_ZT-1100-2h_v4/ are no longer filtered out as internal; only _history / _archive / _templates / _fetched and the like are excluded.

Install

Three channels; each installs the same thing. Pick the one your UI offers.

Channel 1: official plugin page

Sidebar "Plugins" → add plugin, then enter:

github:58catmiao/dsh-sciwork

Restart Harness afterwards — the panel is a client bundle, so reloading the page is not enough.

Channel 2: terminal

dsh plugin --profile <profile> add github:58catmiao/dsh-sciwork

Why the github: prefix: this package is not published to npm, so add dsh-sciwork sends the package manager to npm and gets a 404 (or "package not found"). The github: form installs straight from GitHub and records "dsh-sciwork": "github:58catmiao/dsh-sciwork" in the profile.

Channel 3: plugin marketplace (add the index)

DSH's marketplace does not crawl GitHub and does not guess repository names: it only reads index URLs you add yourself. This repository ships one (market/plugins.json, git source pinned to the release commit):

https://raw.githubusercontent.com/58catmiao/dsh-sciwork/main/market/plugins.json

It requires the optional bundle @deepseek-ai/dsh-experimental-plugin-market-bundle; without it the Discover tab does not exist, so use channel 1 or 2 instead (they are equivalent).

The third-party dshmarket reads its own curated catalog, not this index; it has to list the plugin first. Until then use channel 1 or 2.

The index is rewritten after every release with node scripts/make-market-index.mjs --commit v<version>, which pins the version to that tag's commit — marketplace installs are therefore reproducible. node scripts/test-install.mjs checks its format and commit.

No npm / pnpm, or the command above says npm cannot be found

dsh plugin forwards its arguments to the profile's package manager (pnpm), so it needs a working pnpm. On machines where the DSH runtime does not ship one, use the package-manager-free path instead:

1. On GitHub click Code → Download ZIP and unpack it to a fixed directory (for example D:/apps/dsh-sciwork), or git clone https://github.com/58catmiao/dsh-sciwork.git.
2. From that directory run:

node scripts/install-plugin.mjs --profile <profile> --source .

It adds a link: dependency line to the profile's package.json, links <profile>/node_modules/dsh-sciwork to that directory, and appends dsh-sciwork to dsh.profile.bundles. The existing package.json is backed up as package.json.bak-<timestamp> first; --dry-run shows the changes without writing.

(The plugin page's "add plugin" also accepts that unpacked directory's absolute path — same result.)

Verify with dsh --profile <profile> --dump-config | grep -c dsh-sciwork (should be greater than 0).

After installing, nothing changed

What you get after installing:

• an agent preset "Research Mode" with id research (selectable in a session);
• a new sidebar panel entry, "Research Library" (科研库), opening on the workbench; the header reports the plugin version and offers "check for updates";
• one precisely registered read-only route, /api/research/call, which the panel uses for snapshots and actions;
• six skills registered by the plugin on activation (runtime skills), so no manual scripts/install.mjs run is needed; your own copies under ~/.dsh/skills win and are never overwritten.

Prerequisites: Node on the machine (the host half and the self-test scripts use it) and a working Python 3 interpreter (the library engine research.py uses it). python is not required to be on PATH — the launcher probes candidates in order: explicit configuration → SCIWORK_PYTHON → the library's own venv → the Origin plugin directory's venv → PATH. Plotting additionally needs Origin — see below.

Quick start

1. Create the library

# Preflight first: writes nothing, just reports what is missing
node scripts/install.mjs --verify-only

# Once the preflight passes, create the library
node scripts/install.mjs

The installer creates the library root, the .research/ engine and index, journals/ profiles and the refs/ store. The root defaults to <home>/Research (%USERPROFILE%\Research on Windows) and can be changed with the SCIWORK_LIBRARY environment variable.

Installer flags:

Library-root resolution order: --library-root / the SCIWORK_LIBRARY environment variable (the former name RESEARCH_LIBRARY is still accepted) → libraryRoot in the package's library/config.json → <home>/Research. Note that an existing library's own .research/config.json libraryRoot also overrides the environment variable — the panel and the engine prefer the library's own configuration.

2. Open the panel

Click "Research Library" (科研库) in the DSH sidebar. The header row shows the current library root and live counts (projects / figures / drafts / datasets / references / journal profiles / submissions / index time); the seven tabs sit underneath.

3. Let the agent create a project

Select the "Research Mode" preset in a session, then just say:

Create a project called zt-ceremic on the oxidation behaviour of ZrB₂-SiC ceramics.

The agent runs research.py new-project to lay down the directories, and every figure it plots and every results section it writes afterwards lands in that project's figures/, origin/, data/ and drafts/. You can also click "New project" in the panel and do it yourself.

4. Make a figure

The panel does not plot (that capability was removed on 2026-10-13). To make a figure, tell the agent:

Plot the XRD data in projects/zt-ceremic/data/ as a comparison figure, using MDPI's layout requirements.

The agent plots on a real Origin install, verifies the result, exports it, and registers the figure's provenance back into the library.

The panel: the workbench and the seven tabs

Sidebar → "Research Library". The workbench (v2) opens by default; the page header switches to the classic list panel (v1), which has seven tabs (Figures / Drafts / References / Data / Journal profiles / Submissions / Archive), plus a counts header row and a "Command console" overlay — neither of the latter two is a tab:

The workbench (v2) shows the whole library on one screen: page header (title, counts, Quick entry / New project / Import data / Refresh), a KPI row (projects / figures / references / active submissions), a cross-project to-do table, an overview (Due today / Submission countdown / Library health / Recent activity / Backup), and a two-column project area. The search box on the right of the tab row filters projects and to-dos in v2: the project list, the cross-project to-do table, Due today, Library health and Recent activity are all filtered together, a strip reports the hit counts with a "Clear filter" button, and each empty section says why it is empty (the KPI row always counts the whole library). With a project selected, its detail pane also carries a per-project artifact strip (figures / drafts / datasets / tables / projects / references / active submissions): the numbers are that project's registered artifacts plus its references and active submissions; clicking a number jumps to the matching list tab with the project slug pre-filled as the filter, so only its entries remain (buttons showing 0 are disabled).

The 6 data-transform operators: normalize, baseline (baseline subtraction), smooth, peaks (peak finding), integrate, linear. Every transform leaves a provenance record next to the derived table (.research/transforms/<project>/<table>.json) and writes its output into the project's tables/.

The submission gate (new in 0.2): in the Submissions tab, pick a project and a journal profile, then run the compliance check for per-item verdicts — figure width against the single/double-column spec, effective resolution, raster-vs-vector preference, caption presence, title and abstract length, reference and DOI coverage, and whether every citation key in the draft exists in the library. Each item is pass / warn / fail / na and carries its source and confidence; anything the profile does not state is na, never a generic default posing as a journal requirement. "Export submission package" zips the manuscript, figures, data and refs.bib (with a per-file sha256 manifest and a checklist) into submissions/packages/. As with the profiles themselves, the journal's current requirements win.

The panel's boundary, in one sentence: it can view, filter, import, archive, delete, run data transforms on tables, and do the pre-submission check and packaging — it does not plot. Every write lands a file and registers it through the library scripts, and the panel itself never touches the registration index.

Configuration

Configuration has two layers. <root>/.research/config.json inside the library is authoritative; the environment variables tell DSH where the library is and which Python to use.

Authoritative in-library configuration:

Directory layout

<root>/                          # default <home>/Research, changeable via SCIWORK_LIBRARY
├── projects/
│   └── <project>/
│       ├── figures/             # finished figures (exported png / svg / pdf / tif)
│       ├── origin/              # Origin project files (.opju), still editable in Origin
│       ├── data/                # raw data
│       ├── tables/              # tables derived by data transforms
│       └── drafts/              # manuscript sections for this project
├── refs/
│   ├── refs.json                # reference entries (a DOI or URL is mandatory)
│   └── pdf/                     # local PDF attachments (optional)
├── journals/                    # journal submission profiles
├── submissions/                  # submission records and timelines
└── .research/                   # engine and metadata
    ├── research.py              # the single authoritative entry point for library operations
    ├── config.json              # authoritative config
    ├── index.json               # registration index (a cache; rebuildable)
    ├── archive/                 # archive area (reversible)
    ├── transforms/<project>/    # provenance records for data transforms
    └── lock                     # write lock

Registration (adding references, registering figure provenance, rebuilding the index) is always done by research.py, never by the panel on its own.

The library's authoritative entry point: research.py

Every structured write to the library goes through it (the panel's "Command console" overlay is just a visual front end for it).

Reads:

Writes:

Irreversible: remove-ref deletes one reference registration (it backs up refs.json first).

On Windows the library ships a Python wrapper, .research/bin/py.cmd, which picks an interpreter according to the library config; the invocation examples in the agent documentation go through it. To choose the interpreter yourself, use SCIWORK_PYTHON.

The journal profiles at a glance

Strictness drives the default layout and the strictness of validation; each profile also carries concrete numbers and citations to its source. For how to read and apply a profile, see the journal-profile skill.

Skills

Skills are discipline documents, not code: they constrain the agent's behaviour and add no dependencies.

Relationship to dsh-origin-plugin

• The plotting capability comes from dsh-origin-plugin (MIT, by Fantasality). It provides the 74 origin_* MCP tools that talk to Origin on your machine.
• This repository does not include dsh-origin-plugin, and does not copy its code; dsh-sciwork ships only an adaptor skill, skills/origin-plot, that teaches the agent to use those 74 tools to research-delivery standards.
• skills/origin-plot/references/origin-tools.json is a derived file: generated from dsh-origin-plugin's tool list so the agent can look tools up offline (name / arguments / purpose).
• The two can be installed independently. Without Origin and dsh-origin-plugin, everything else in dsh-sciwork — the library, the panel, writing, references, journal profiles — still works; only the "make a figure" step is unavailable.
• The SCIWORK_ORIGIN_PLUGIN environment variable tells the adaptor skill where dsh-origin-plugin is installed.

Self-tests

The repository ships four self-test scripts and one patch preflight. None of them writes to your real library (write actions run against an isolated copy behind a hard gate). The first four need Node only; the patch preflight is written in Python and needs one non-stdlib dependency, PyYAML:

node scripts/selftest-host.mjs      # host half: route registration, path guards, snapshot shape
node scripts/selftest-actions.mjs   # the 23 actions: read/guard checks + writes against an isolated copy
node scripts/selftest-client.mjs    # client: the seven tabs' rendering, overlays, buttons and request shapes
node scripts/test-install.mjs       # install surface: bundled skills, market index, package files, apply wiring
python -m pip install pyyaml        # only for the next line (CI installs it in its own step)
python scripts/validate-patch.py    # cordis.patch.yml preflight: preset rows, persona, inserted row

Before pushing to a public repository there is one more gate: node scripts/check-local-info.mjs (also run by cycle.mjs). It takes this machine's home directory, user name, host name, temp directory and library root as markers, scans every tracked file and every commit message, and fails on any hit — replace those with placeholders such as <repo-root> / <library-root> / <system-temp> before committing.

The self-tests run in two modes, and a fresh clone with no library configured can still run them:

A. Without pointing at any research library (CI / a freshly cloned machine)

node scripts/selftest-host.mjs      # all pass, exit 0
node scripts/selftest-actions.mjs   # all pass · 0 failed · content checks skipped
node scripts/selftest-client.mjs    # all pass · 0 failed · content checks skipped
python scripts/validate-patch.py    # ✓ patch preflight passed

Every content check (the ones that need real drafts / figures / data tables in the library) is recorded as SKIP or "not run"; the script prints a line saying so (未运行：内容类检查需要一个可用的科研库（当前库根 …）) and exits 0 — having no library is not a failure.

B. Pointing at a real library (measured baseline)

SCIWORK_LIBRARY=/path/to/Research node scripts/selftest-actions.mjs   # 127 passed · 0 failed · 3 skipped (fixture library; counts vary with library content)
SCIWORK_LIBRARY=/path/to/Research node scripts/selftest-client.mjs    # 230 passed · 0 failed

• selftest-host.mjs — tallies passes and failures only, exit code 0. The only check that can be recorded as "skipped" is one that depends on the real library actually containing a figure file (when there is none, it is not counted as a failure).
• selftest-client.mjs — its summary line likewise has only those two columns; in mode B it measures 230 passed · 0 failed, exit code 0.
• validate-patch.py — prints ✓ 补丁预检通过 (patch preflight passed), exit code 0. It reports the preset-research preset's top-level row count (19 rows, 29 leaf rows after recursion, 2 of them disabled by an !!js condition), its nested groups (planning / compaction / delegation), the persona length, and confirmation that the inserted research-library row belongs to the host plugin rather than to an agent preset.
• selftest-actions.mjs — the write-action stage requires the library root to point at the isolated copy the script creates. If it finds the snapshot pointing somewhere else, it prints FAIL 隔离闸门：snapshot 指向副本 and exits with code 2, having written not a single byte. That is by design, not a plugin defect: write actions always run inside the copy and never touch your real library.

Documentation map

License and credits

License: MIT, copyright 58catmiao. The license text lives in LICENSE.

Credits

• The Origin plotting capability comes from dsh-origin-plugin (MIT, by Fantasality). This repository does not include it; skills/origin-plot/references/origin-tools.json is derived from its tool list for offline lookup. Thanks to the author for open-sourcing this local Origin automation.
• DSH (DeepSeek Harness) provides the plugin mechanism, agent presets and tool routing that this plugin extends.
• The journal profiles are this project's own summaries of numeric requirements, clauses and sources — not official journal documents.

On content copyright

This repository contains no copyrighted paper text or journal PDFs.

• The 12 journal profiles under journals/ describe submission requirements as numbers, clauses and summaries with sources cited (word limits, figure requirements, reference formats, and so on); where a specific clause matters, the journal's own current author guidelines take precedence.
• refs/ holds your own reference metadata (title, DOI, URL, …) and attachments you place in refs/pdf/ yourself; the repository preloads no full text.
• The journal profiles are an aid, not legal or submission advice; any consequence of using them in place of the official guidelines is the user's own.

dsh-sciwork · every research step lands on your own disk