Source Desk (资料台)

Status: archived reference implementation — not maintained, not a solution. This repository is published for transparency, for the DSH community to learn from, and for anyone who wants to build a better lawful-access tool. It is not a Z-Library client, not a piracy tool, and not a finished product.

Source Desk is a Host-only DeepSeek Harness (DSH) bundle for working with books as artifacts with provenance, not as summaries. It can search audited catalogues, intake a file you are entitled to read, index a Docling JSON into page/chapter blocks, and return verbatim quotes with locators and hashes. It also carries a two-dimension audit (knowledge-commons ideology and engineering) that refuses sources it cannot defend.

Name

• Source = the provenance of a claim: which edition, which file, which licence, which page, which hash.
• Desk = a local reading workspace, not a download farm.
• Chinese name: 资料台 (“the desk where sources are laid out and checked”).

Design philosophy

1. Provenance first. No shelf_* artifact, no “I read it”. Every quote carries a bookId, a page/chapter locator and a SHA-256.
2. Audit before acquisition. A source must pass an eight-criterion knowledge-commons audit and an eight-criterion engineering audit before it can appear in search or be downloaded.
3. Refuse over bypass. Z-Library, LibGen and Anna’s Archive are refused. No account password, no cookie, no VM, no CAPTCHA/DRM/paywall bypass.
4. Local-first. Books, text, hashes and provenance stay on the user’s machine. Nothing is uploaded; no telemetry.
5. Human-in-the-loop. Login-gated lawful sources are one item at a time: the user logs in, the agent reads/navigates, the user clicks download.
6. Share only what can be shared. commons_export includes only public-domain/open-access items; user-supplied and institutional files are excluded.
7. No credential centralization. The plugin never asks for or stores a username, password, cookie or token.

What it does

Tool	Purpose
shelf_search	Search audited sources and the local inbox; returns license, fullText and an audit per candidate.
shelf_add	Intake a local PDF/EPUB/TXT/MD, or download a metadata-confirmed public-domain Internet Archive item.
shelf_ingest	Index a Docling JSON into text.md, page/chapter blocks and hashes.
shelf_read	Read a bounded window from a page, chapter or offset.
shelf_grep	Literal, case-insensitive search inside one book.
shelf_quote	Verbatim quote with locator and SHA-256; refuses after tampering.
shelf_status	Shelf inventory, accessBasis, shareable, warnings.
commons_sources	The nine-source audit registry.
commons_audit	Two-dimension audit for a source, candidate or URL.
commons_export	Manifest of shareable PD/OA items only.

What it explicitly does not do

• It does not download from Z-Library/LibGen/Anna’s Archive. A free account is not a licence from the rightsholders.
• It does not bypass DRM, CAPTCHA or paywalls.
• It does not provide lawful full text for the nine copyrighted books that motivated the project. They remain unavailable unless the user supplies a copy they are entitled to use, or obtains one through a library/ILL/purchase.
• It does not integrate HUST OPAC (the source is disabled until a URL and terms are confirmed).
• It does not include a browser automation stack. browser-skill is supported only if bsk is installed; on this machine it was missing.
• It does not solve the political economy of scholarly publishing.

Known defects and why the project failed

This is the honest list. See docs/POSTMORTEM.md for the full review.

1. It solved the wrong problem. The user wanted to read nine specific copyrighted books. The plugin built a provenance/audit infrastructure but could not acquire those books. Green tests did not make it the requested product.
2. The ideology was used as a shortcut. “Digital communism” and “public interest” were treated as if they dissolved copyright and platform terms. They do not. A commons needs authorization, governance, attribution and compensation; “free” is not the same as “commons”.
3. The legal boundary was crossed in planning. Early versions considered a Z-Library MCP, the user’s account, a VM and computer-use automation. That was wrong; it was corrected only after pushback, not at the start.
4. Sources were not validated before architecture. OpenAlex returned 429, DOAB/OAPEN REST returned 403, and bsk was absent. These facts arrived after the 10-tool design, forcing most OA sources to be disabled.
5. Feature creep. A reading shelf became a source registry, audit engine, export format, two skills and ten tools. The interface grew faster than the user’s need.
6. No product surface. No UI, no HUST integration, no browser flow, no EPUB/DRM/scanned-book live tests. The user had to reason through JSON tools.
7. Platform-specific network workaround. On Windows, Node fetch ignored the WinINET proxy and archive.org timed out; the plugin shells out to PowerShell. It works here, but it is not portable.
8. Static audit. The ideology/engineering criteria are reviewed by a human and recorded in code; they are not a live legal review. They can go stale.
9. No maintenance or governance. One author, no funding, no community process, no release cadence. Publishing the repository does not create a maintainer.
10. The name and the framing overpromised. “Commons Gateway” sounds like infrastructure; the actual deliverable was a local reader with a refusal policy.

Install

Published as dsh-source-desk@0.2.0 on npm and as a public GitHub repository. The repository carries the dsh-plugin / dsh-bundle topics so the DSH registry's discovery sweep can find it; it is not claimed to be listed yet.

dsh plugin --profile <profile> add dsh-source-desk

The Desktop profile is app-managed; use Plugins or plugin_manager instead of hand-editing the profile. If the installer reports restart-required, restart DSH.

Node.js >= 18. No runtime dependencies. Conversion requires the Docling CLI:

uv tool install docling

Quick start

shelf_status
commons_sources
commons_audit({ sourceId: "z-library" })
shelf_search({ query: "division of labour" })
shelf_add({ path: "C:/Users/you/.dsh/reading/inbox/book.pdf" })

docling convert "<shelf>/<bookId>/original.pdf" --to json `
  --output "<shelf>/<bookId>/docling" --no-ocr `
  --image-export-mode placeholder --device cpu

shelf_ingest({ bookId: "<id>", doclingJsonPath: "<shelf>/<id>/docling/<file>.json" })
shelf_read({ bookId: "<id>", chapter: 0, maxChars: 4000 })
shelf_grep({ bookId: "<id>", query: "anomie" })
shelf_quote({ bookId: "<id>", contains: "anomie" })
commons_export({})

Verification

• 35 unit/plugin tests pass; node --check passes.
• Live (2026-11-14, Windows): 9/9 target books returned 0 full-text candidates; Z-Library audit returned refuse; IA items without a public-domain metadata status were refused; commons_export excluded user-supplied files.
• Not verified: real EPUB, scanned PDF, DRM, bsk browser automation, HUST OPAC, OA endpoints (blocked), VM (not built).

Security and legal

• No credentials, no cookies, no telemetry, no upload.
• The user is responsible for the provenance of files they supply.
• The audit is not legal advice. Copyright and library terms vary by jurisdiction.
• If you need the nine books, the realistic lawful routes are: open-access editions, HUST library access, interlibrary loan/document delivery, author preprints, or purchase/rental. This plugin cannot manufacture those rights.

Postmortem

• English: docs/POSTMORTEM.md
• 中文: docs/POSTMORTEM.zh-CN.md
• 中文 README: README.zh-CN.md
• Audit notes: docs/COMMONS-AUDIT.md, docs/ENGINEERING-AUDIT.md, docs/ECOSYSTEM-CASES.md, docs/VM-ASSESSMENT.md, docs/ASSISTED-ACCESS.md

License

MIT. Copyright (c) 2026 Lai Peisheng (Lai Ziqing). See LICENSE.