@apollo-music/dsh-enterprise-documents

DeepSeek Harness tools for the Apollo enterprise document library.

Version 0.5.1 targets DeepSeek Harness 0.1.0-rc.8 with Cordis 4.0.1 and keeps the DSH service packages on one exact RC line.

Install the bundle into the same DSH profile that mounts the trusted WeCom bridge:

dsh plugin --profile <profile> add @apollo-music/[email protected]

The bundle installs its enterprise-document row disabled by default. The deployment must separately mount @apollo-music/dsh-wecom-bridge with an explicit business Agent preset, then set APOLLO_ENTERPRISE_DOCUMENTS_ENABLED=1. If the Host-only wecomSession service is unavailable after enablement, DSH startup fails closed.

The plugin requires @apollo-music/dsh-wecom-bridge 0.3 or newer. Every API call resolves the current execution through Host-only ctx.wecomSession; ambiguous or unavailable user context fails closed. One full-capability service API key is resolved from ctx.credentials for every operation. The key authenticates the trusted tool, while the API performs live file ACL authorization for the resolved triggering user.

Storage implementation fields, signed URLs, object identifiers, credentials, and user identity are never part of tool parameters or canonical output. Write tools pass through DSH user approval. @apollo-music/dsh-file-reader is optional; while present it adds exact-revision open and current-session non-enterprise handle upload tools.

Uploads use short-lived OSS PUT URLs. Files larger than the server's simple-upload threshold use resumable multipart upload; each pending part is retried independently. The plugin never attaches the enterprise API credential or WeCom identity to OSS requests, and it best-effort aborts the server session after a terminal transfer failure.

Version 0.2 adds enterprise_documents_upload_workspace_batch and the read-only enterprise_documents_upload_batch_status tool. Batch upload supports exact paths, glob arrays, recursive directories, additive exclude patterns, and bounded in-workspace symlink following. The plugin computes SHA-256 while snapshotting the selected workspace files. The API reuses an existing current ready revision when its SHA-256 is identical, so unchanged files create neither a revision nor an upload session; changed files append an immutable version. It reserves the complete target manifest in one PostgreSQL transaction and recursively merges directories. File and multipart-part transfers stream from verified workspace file handles through one bounded worker pool; each retry revalidates the logical path and the opened file snapshot. A failed batch cleanup removes only uncompleted nodes that are still owned by the reservation, while completed or subsequently modified nodes remain available. Caller cancellation uses the explicit batch-cancel endpoint and preserves completed transfers; ordinary transfer failures remain failed rather than being mislabeled as cancellation. Failure details are paginated with failureCursor, failureLimit, and nextFailureCursor, and abandoned sessions are expired and reconciled by background maintenance without requiring a status read.

Version 0.3 makes destination mapping explicit. Every enterprise_documents_upload_workspace_batch call must provide stripSourcePrefix, a workspace-relative directory containing every selected source. That directory is removed from each destination path before the manifest is sent to the API. Selecting the prefix directory itself therefore merges its contents directly into parentId instead of recreating the source tree. Use stripSourcePrefix: "." when the complete workspace-relative paths should be preserved. Prefix matching is path-segment-aware; the prefix must resolve to an in-workspace directory, and any selection outside it fails before an upload batch is created. Exclude patterns continue to match source workspace paths. Target ambiguity checks run after prefix stripping and Unicode normalization.

Version 0.4 adds reversible recycle-bin operations. enterprise_documents_list_recycle_bin lists soft-deleted items visible to the triggering user. enterprise_documents_move_to_recycle_bin requires the exact node revision from a fresh browse; enterprise_documents_restore_from_recycle_bin requires both the deleted node revision and the original parent's current revision. Moving an item into or out of the recycle bin changes both revisions. Restoring fails closed after a concurrent change or when an active sibling already uses the same normalized name. Both mutations use the same DSH approval guard and live server-side ACL checks as other write tools. The plugin does not expose permanent deletion.

Version 0.5 adds enterprise_documents_download_batch. Its model-facing input is only { kind: "batch", documentIds: string[] }. A file ID downloads that file's current ready content; a directory ID recursively resolves its visible files. Every invocation creates a new inbox/enterprise-documents/<downloadId>/ and never accepts a target path, overwrite, merge, glob, exclude, or hash-deduplication option. Downloads resolve the current version when each file is requested rather than reserving or freezing a revision. Each file is attempted once and retried at most once; terminal failures are reported per file while other files continue. Caller cancellation stops retries and removes only the fresh inbox owned by that invocation. The public result contains only downloadId, inboxPath, counts, and per-file document ID, relative path, status, and stable failure code.

Batch upload is independently disabled by default. Enable ENTERPRISE_DOCUMENTS_BATCH_ENABLED=true on the Customer Assistant API only after migration 000050_enterprise_upload_batches is applied, then set APOLLO_ENTERPRISE_DOCUMENTS_BATCH_ENABLED=1 in the DSH Host. API batch file, directory, and total-byte ceilings use ENTERPRISE_DOCUMENTS_BATCH_MAX_FILES, ENTERPRISE_DOCUMENTS_BATCH_MAX_DIRECTORIES, and ENTERPRISE_DOCUMENTS_BATCH_MAX_BYTES. The DSH plugin also accepts bounded maxBatchFiles, maxBatchDirectories, maxBatchBytes, traversal, symlink-depth, failure-detail, and uploadConcurrency configuration; model arguments cannot raise these limits.

Operators can inspect legacy failed upload nodes with npm run repair:enterprise-upload-orphans --workspace @apollo-music/customer-assistant-api. This is a read-only dry run by default. Repair requires both --repair and one or more exact --session-id <uuid> arguments; ready documents and replacement uploads with an existing current version are excluded by the database predicate.

Configure apiBaseUrl with the integration prefix and set apiKeyCredentialRef to the credential reference holding the same single service key as the API's ENTERPRISE_DOCUMENTS_API_KEY. Defaults are the local Customer Assistant URL and APOLLO_ENTERPRISE_DOCUMENTS_API_KEY. File and response limits are bounded configuration values; exceeding them fails closed. Ordinary API requests use the bounded timeoutMs budget (60 seconds by default), while multipart initialization and signed OSS PUT requests use uploadTimeoutMs (10 minutes by default) so large uploads share the same bounded budget as their DSH tools. Caller cancellation always takes precedence over either deadline.