dsh-plugin-xparse

TextIn xParse for DeepSeek Harness

English | 简体中文

@intsig-xparse/dsh-xparse installs one structured xparse Tool, the bundled xparse-parse Skill, and the reviewed xparse CLI binaries used internally by the Tool.

Requirements

• DeepSeek Harness 0.2.1-rc.2 or 0.2.1-rc.3
• Node.js 22.19 or newer, as required by the current Harness dependency set
• Linux or macOS on x64/arm64; Windows binaries are packaged but are not part of the current native validation evidence

Install

dsh plugin --profile web add @intsig-xparse/dsh-xparse
dsh --profile web --dump-config
dsh --profile web

The Tool always executes the binary embedded in this package. It does not use PATH, a global xparse-cli, an install script, or a runtime download.

Operations

The first release exposes:

• parse
• quota
• get_doc_info
• get_outline
• search_text
• read_pages
• read_content
• task_run
• task_rerun
• task_status
• task_read
• task_export
• task_debug
• task_resume

get_confidence, interactive CLI commands, arbitrary CLI arguments, custom headers, custom base URLs, Task passwords, task_continue, foreground Task waiting controls, task_status.details, and encrypted-document passwords are not exposed. Task submission and rerun operations return Task/Run identity, status, progress counters, terminal state, and next_action immediately; use the compact exact-Run task_status response for later progress checks. Task debug/export responses expose only whitelisted file status, error code, and recovery fields rather than raw service payloads.

Parsing sends document data to TextIn. Uploads and explicit paid parsing follow the Bundle's Harness approval policy. Task auto-routing and reruns are not pre-approved merely because they may later need paid capacity: the service first returns waiting_paid_authorization or waiting_funds, and approval is requested only for the exact subsequent task_resume action. One approval covers that Task Run, not one approval per file; an after-funding retry for the already-authorized Run does not ask again. Results are written as workspace artifacts instead of returning a complete long document as Tool text.

Credentials

The browser card at Plugins > TextIn xParse writes App ID and Secret Code through the Harness credentials.set API. Secret Code never enters plugin settings, Tool arguments, or the Agent conversation. The card addresses the configured credential references, which default to XPARSE_APP_ID and XPARSE_SECRET_CODE. Credential references are projected through DSH's native configForms service. The non-secret App ID and temporary OAuth CSRF token are read on demand through an authenticated owner-only endpoint; they are not persisted as plugin settings. Secret Code remains write-only. A configured card shows App ID and a Modify action, while an unconfigured card keeps the AppKey form collapsed until the user selects the AppKey configuration button. The same nested control hides the configured App ID and modification actions by default. The outer xParse card starts collapsed whenever OAuth is already logged in or a complete AppKey exists; otherwise it starts expanded. Deployment-provided environment values remain higher priority and make the corresponding controls read-only. The same card offers Device OAuth login: the Host automatically starts the embedded CLI flow while logged out and directly shows the verification URL/code without a separate login button. Visible login URLs include launch_from=deepseek-harness, and OAuth requests use the public Client ID plugin_deepseek_harness. Grants created for another Client ID are not reused; the plugin starts a fresh login and replaces them. The Host stores the resulting xparse/oauth grant and refreshes it before use. Tokens never reach settings, the browser, Tool arguments, or conversation text. Every network operation (parse, quota, and Task Runtime) requires OAuth or a complete AppKey; cached local navigation remains available offline.

OAuth access tokens enter the refresh window five minutes before expiry by default (oauthRefreshSkewMs: 300000).

When a root Agent calls a network operation without usable credentials, the Tool starts Device OAuth and opens a dedicated xParse login card in the conversation composer. The card uses an aligned header, authorization panel, and action footer for the xParse label, login requirement, verification link, user code, and completion controls; it does not expose the generic question form, skip, or submit controls. Successful authorization closes the card, stores the grant Host-side, and continues the original Tool call. The user may also confirm completion or cancel from the card. Login waiting occurs before the CLI execution deadline. Subagents, headless callers, and deployments without a question provider must use the plugin settings card instead.

Never paste App IDs, Secret Codes, OAuth tokens, or document passwords into a conversation or Tool call.

State and artifacts

The adapter assigns a session-scoped state directory below <workspace>/.xparse/sessions/ through XPARSE_STATE_DIR. Parse artifacts use per-call directories below <workspace>/.xparse/calls/. The sandbox remains the authority for file access. Every embedded CLI subprocess also receives XPARSE_CLIENT_FROM=deepseek-harness, so TextIn API requests carry X-From: deepseek-harness instead of the standalone cli attribution.

Provenance

embedded-cli-manifest.json records the public npm source package, source revision, protocol versions, paths, and SHA-256 digest of every embedded binary. skill-source.json records the external Skill repository, locked commit, MIT license, and file digests.

Development

This repository owns only the DeepSeek Harness plugin. The embedded CLI is built by xparse-client, and the generic Skill is maintained by xparse-skills; reviewed revisions are pinned in release-lock.json and materialized only during assembly.

Install dependencies and run the source-level checks with:

npm install
npm run typecheck
npm test
npm run build

Generated release inputs are intentionally not committed. CLI binaries are downloaded from the six npm platform-package tarballs pinned by URL, npm integrity, tarball SHA-256, and binary SHA-256 in release-lock.json. Populate or verify the cache with:

npm run fetch:cli
npm run fetch:skill

Then assemble with a clean checkout of the locked Skill:

python3 scripts/prepare-dsh-xparse.py \
  --skill-dir /path/to/xparse-skills/skills/xparse-parse

Use --offline to prove the assembly is reproducible from the verified cache without registry access.

After assembly, validate the package and a real DSH web boot with:

npm run validate:docker

Docker validation uses the public node:22.22.0-bookworm image, including Node and Python. Set DSH_VALIDATION_IMAGE to override it.

Validate each supported Host version independently:

DSH_VALIDATION_DSH_VERSION=0.2.1-rc.2 npm run validate:docker
DSH_VALIDATION_DSH_VERSION=0.2.1-rc.3 npm run validate:docker

The script uses separate versioned Host caches and checks types against the installed Host's actual packages. It verifies configuration projection, anonymous access rejection, live credential-reference updates, App ID refresh and clearing, OAuth CSRF checks, and the advertised browser bundle. To also exercise the settings card in an existing temporary headless Chrome, supply its DevTools browser WebSocket as DSH_VALIDATION_BROWSER_WS and use DSH_VALIDATION_NETWORK=host on Linux. The browser check saves, edits, updates, and clears test AppKeys; it stubs OAuth status in the browser and does not authorize against TextIn.

Check the tag and supported platforms, then pull and smoke-test the image before running validation:

docker manifest inspect node:22.22.0-bookworm
docker pull node:22.22.0-bookworm
docker run --rm node:22.22.0-bookworm bash -lc \
  'set -eu; node --version; npm --version; python3 --version; git --version'
npm run validate:docker

A registry connection timeout does not establish whether a tag exists. Docker's official image record records this tag and its platform digests; a successful pull and validation are still required to establish that it works in your environment.

Release

Build the complete npm tarball and checksum manifest with one command:

npm run release:build -- --output-dir dist/release

The command fetches the locked Skill and CLI artifacts, assembles generated inputs, compiles TypeScript, runs npm pack, verifies the tarball, and writes SHA256SUMS. Add --offline to require both verified caches.

Before publication, run the same content audit enforced by the release workflow:

python3 scripts/audit-public-release.py --skip-cli-binaries dist/release/*.tgz

The release workflow intentionally skips the six locked CLI binaries because the upstream CLI path-leak exception is currently accepted. It still checks every other archive member for internal infrastructure, non-production API URLs, developer home paths, and employee emails. Run without --skip-cli-binaries when reviewing a new upstream CLI build. This targeted audit does not replace credential scanning or an upstream environment access review.

GitHub CI performs the same release build on every pull request and uploads the review artifact. Pushing tag v<package-version> runs the release workflow, publishes the exact verified tarball to npm, and attaches the tarball plus checksums to a GitHub Release. Configure repository secret NPM_TOKEN with publish access to @intsig-xparse/dsh-xparse before creating a release tag.