@volcengine/tls-observer-dsh-install

Installer for @volcengine/tls-observer-dsh. Install DeepSeek Harness first and make sure its dsh command is available on PATH when targeting a DSH profile. This package deliberately does not bundle DSH or pnpm; it delegates profile changes to the user's existing DSH installation and official profile plugin manager. Standalone ACP/custom Cordis targets do not require the dsh CLI: the installer places the observer in an isolated sibling npm runtime and appends one owned YAML entry. It keeps unrelated configuration intact and persists TLS settings in a managed environment block so the selected process can load them.

Content capture is disabled by default. Enable it explicitly only when prompt, response, and tool content may be exported to TLS.

The installed observer keeps OpenTelemetry as its in-process Span model, converts completed Spans to TLS trace-envelope log records, and writes them with TLS Producer SendLogs. It does not POST OTLP to port 4318 and does not require a local collector.

npm exec -y \
  --package=@volcengine/tls-observer-dsh-install@latest -- \
  tls-observer-dsh-install install \
  --profile web \
  --region cn-beijing \
  --trace-topic-id <topic-id> \
  --api-key <api-key> \
  --span-attribute user.id=<customer-user-id> \
  --span-attribute agent.version=<customer-agent-version>

--span-attribute key=value is repeatable. Values are applied to every Span after DSH's auto-detected attributes, so an explicitly supplied key overrides the detected value. The installer stores the map as DEEPSEEK_HARNESS_TLS_SPAN_ATTRIBUTES JSON in the managed environment block; status output reports only the count and never prints the values. Overriding identity fields such as session.id can break Trace and Session grouping and should be done only when the deployment owns that identity contract.

AK/SK authentication is also supported:

tls-observer-dsh-install install \
  --profile web \
  --region cn-beijing \
  --trace-topic-id <topic-id> \
  --ak <tls-ak> \
  --sk <tls-sk>

The default target is the web profile. Create the target profile with DSH before running this installer. Repeat --profile, or opt in to --all-existing-profiles, to install elsewhere. status never prints credentials. uninstall removes only the selected profile dependency and removes the managed environment block only after no profile still uses the plugin (or when --purge-config is explicit).

ACP and custom Cordis configurations

ACP is a JSON-RPC stdio transport backed by ordinary DSH agents and session EventLogs. It is not a DSH profile: runners such as dsh-acp-demo --config ./cordis.yml boot a standalone Cordis YAML composition. Target that composition explicitly:

npm exec -y \
  --package=@volcengine/tls-observer-dsh-install@latest -- \
  tls-observer-dsh-install install \
  --cordis-config /path/to/acp/cordis.yml \
  --region cn-beijing \
  --tls-endpoint tls-cn-beijing.ivolces.com \
  --trace-topic-id <topic-id> \
  --api-key <api-key>

The installer appends one owned tls-observer-dsh entry without rewriting unrelated YAML and installs the runtime under .tls-observer-dsh-install/ beside the configuration. The managed entry uses a relative module path into that isolated runtime, so it does not mutate the ACP application's package manifest or lockfile. TLS settings go to a sibling .env by default because the published ACP runner loads the launch directory's environment before booting the YAML. If the ACP process is launched from another directory, pass its actual environment file explicitly:

tls-observer-dsh-install install \
  --cordis-config /path/to/acp/cordis.yml \
  --observer-env-file /path/to/acp/observer.env \
  ...

The installer writes this file before starting npm or DSH child processes. Load it directly in the ACP launcher (for example with shell source or Node process.loadEnvFile()); do not inject Node's own --env-file option through NODE_OPTIONS.

--cordis-config is repeatable and may be combined with --profile. With only Cordis targets, the implicit web profile is not modified. status and uninstall accept the same target flags; uninstall removes only the installer-owned YAML block, isolated runtime, and managed environment block. A user-authored id: tls-observer-dsh outside the managed block is left untouched and causes install to fail instead of creating a duplicate.

--tls-endpoint selects the TLS Producer host and defaults to tls-<region>.volces.com. The legacy --otel-endpoint option remains accepted for upgrades, but only its hostname is retained; the installer no longer writes an OTLP path or port.