@deepseek-harness-tui/dsh-tui 0.11.1 → 0.12.0

package/guide/dsh-tui-guide/getting-started.en.md

@@ -0,0 +1,398 @@
+# Getting Started
+
+[Documentation index](README.md) · [简体中文](getting-started.md)
+
+## Prerequisites
+
+- Node.js `^22.19 || >=24`; CI uses Node 24.
+- The official DeepSeek Harness CLI: `@deepseek-ai/dsh`.
+- `pnpm` **10 or newer** (CI uses 11). `dsh plugin` delegates profile
+  installation to pnpm; pnpm 9 hoists transitive dependencies differently,
+  leaving `dsh-working-activity` unresolvable inside the profile — the TUI
+  then exits right after startup with almost no error output (issue #60, see
+  Troubleshooting below).
+- An interactive terminal TTY. `dsh-tui` cannot start with stdout redirected.
+- The `deepseek-official` route needs `DEEPSEEK_API_KEY`; on DSH 0.2.0-rc.1+
+  the standard profile can instead sign in to the separate DeepSeek account
+  route with `/auth login deepseek-account`. Other supported accounts use
+  `/provider` or `/auth`. Set `DEEPSEEK_BASE_URL` for a compatible custom endpoint.
+
+macOS/Linux:
+
+```sh
+export DEEPSEEK_API_KEY='your-key'
+```
+
+PowerShell:
+
+```powershell
+$env:DEEPSEEK_API_KEY = 'your-key'
+```
+
+Never commit a real credential. A normal profile launch reads the environment
+variable directly.
+
+## Install
+
+```sh
+# Install the official CLI
+npm install -g @deepseek-ai/dsh
+
+# Install pnpm if needed (or use: corepack enable pnpm)
+npm install -g pnpm
+
+# Add the scoped package to the dsh-tui profile
+dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
+```
+
+From a checkout, the repository helper wraps the profile command:
+
+```sh
+sh install.sh
+```
+
+`install.sh` checks for `dsh` and `pnpm` and then runs the profile plugin
+command. It does not copy source files and does not require a local build.
+
+## Migrate from the former package
+
+Earlier releases used the unscoped `dsh-cc-tui` package and a `cc-tui` profile:
+
+- `CC_TUI_*`/`DSH_CC_*` environment variables.
+- a `~/.dsh-cc` data directory.
+
+The current identity is `@deepseek-harness-tui/dsh-tui` in a `dsh-tui` profile,
+using only `DSH_TUI_*` variables and `~/.dsh-tui`. Create the new profile with:
+
+```sh
+dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
+dsh --profile dsh-tui
+```
+
+The current release no longer reads the old names and does not migrate data
+automatically. After first launch, copy themes, configuration and history
+files from the old data directory (`~/.dsh-cc`) into `~/.dsh-tui` yourself.
+
+Once the new profile works:
+
+- `$DSH_HOME/profiles/cc-tui` and the old data directory are just
+  former-installation leftovers and may be removed when convenient.
+- Do not add both packages to the same profile.
+
+## What installation does
+
+On the first `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui`, the official CLI:
+
+1. Initializes `$DSH_HOME/profiles/dsh-tui/`. When `DSH_HOME` is unset, the
+   default root is normally `~/.dsh`.
+2. Uses `@deepseek-ai/dsh-base` as the first profile bundle.
+3. Installs `@deepseek-harness-tui/dsh-tui` inside the profile with pnpm.
+4. Reads the package's `dsh.bundle.patch` metadata and adds its
+   `cordis.patch.yml` as a composition layer.
+
+The important startup order is:
+
+```text
+dsh-base -> other bundles -> @deepseek-harness-tui/dsh-tui patch -> user profile patch
+```
+
+- The base supplies agent, model, session, filesystem, shell, policy, and
+  registry services.
+- The plugin patch overrides or inserts the TUI, agent-preset roster, SQLite
+  session persistence, and live activity row.
+
+`dsh-working-activity` is already a dependency of this package and is inserted
+by the `dsh-tui` patch. Do not separately add `dsh-working-activity` to the
+same profile or duplicate rows may be mounted.
+
+## Start the TUI
+
+```sh
+dsh --profile dsh-tui
+```
+
+The process starts in the current directory, which is also the Agent's default
+workspace. Change into the target project before starting it.
+
+On Windows, the checkout also provides:
+
+```bat
+dsh-tui.cmd
+dsh-tui.cmd --resume
+```
+
+- `--resume` reads `%USERPROFILE%\.dsh-tui\resume.txt` and restores the
+  session last selected by the TUI.
+- Set `DSH_TUI_WORKSPACE` to override the working directory used by the batch
+  launcher.
+
+## CLI subcommands
+
+`dsh-tui help` (or `dst help`) prints the full usage; the `dst` alias accepts
+the same commands:
+
+| Command | Purpose |
+| --- | --- |
+| `dsh-tui update` | Update the profile to the latest release and align the launcher (same install logic as the in-TUI `/update`, without restarting into the TUI) |
+| `dsh-tui doctor` | Environment checks: dsh/pnpm, profile install and version alignment, whether the API key is set (state only, never the value), config file presence; complements the in-TUI `/doctor` session diagnostics |
+| `dsh-tui safe` | Safe mode: read-only diagnostics, inventory, repair guidance (`safe --rescue` also creates/verifies the clean rescue profile) |
+| `dsh-tui version` | Show the launcher and profile versions (`--version`/`-v` are equivalent) |
+| `dsh-tui help` | Show usage (`--help`/`-h` are equivalent) |
+
+`help`/`version` work even when dsh is missing or the profile is not
+initialized; every other argument is forwarded verbatim to
+`dsh --profile dsh-tui`.
+
+## Safe mode (`dsh-tui safe`)
+
+When dsh exits unexpectedly, safe mode provides read-only environment
+diagnostics, a profile plugin inventory, and repair guidance.
+
+- **Two entries**: run `dsh-tui safe` manually; or accept the prompt after
+  dsh exits with a non-zero code.
+  - The prompt only appears in interactive terminals; scripts and pipes get
+    a single hint line and keep the exit code.
+  - It covers only a non-zero exit of the final dsh child process, not a
+    startup hang (a spawn failure counts as exit code 1).
+- **Read-only**: diagnostics, inventory, and guidance never change state. Two
+  exceptions:
+  - Retry normal startup; when `~/.dsh-tui/resume.txt` holds a pointer it is
+    passed along (`DSH_TUI_RESUME_SESSION`), so a retry after a crash returns
+    to the session you were in instead of a blank one.
+  - Create/reuse the rescue profile, writing only to
+    `$DSH_HOME/profiles/dsh-tui-safe/`.
+  Note: every dsh launch writes `$DSH_HOME/profiles/node_modules` fallback
+  links and the pnpm global store (not introduced by safe mode).
+- **The rescue profile must be clean, or it refuses to start**. Each check
+  blocks startup if it fails:
+  - The candidate directory exists but is not a recognizable profile.
+  - The existing profile's root manifest declares third-party plugins.
+  - `$DSH_HOME/cordis.patch.yml` (home layer): **rejects if it exists**.
+  - `dsh-tui-safe/cordis.patch.yml` (profile layer): **rejects only if it has
+    entries**; the default "comments + `[]`" does not count as entries.
+  Before deleting or rebuilding a rescue profile, it checks the top-level
+  entries by **name and shape**; any other name or shape makes it refuse and
+  list them — never silently deleting your files.
+- **Non-interactive**: `dsh-tui safe --rescue` runs the same gate plus
+  create/reuse and only reports the verdict (exit 0 when ready, 1 when
+  refused).
+- **Outdated launcher**: upgrade first when the profile copy is unreadable or
+  too old:
+  `npm install -g --legacy-peer-deps @deepseek-harness-tui/dsh-tui@<version>`.
+- **Run repair commands yourself** (safe mode only lists them):
+  - `dsh plugin --profile dsh-tui remove <third-party plugin>` removes
+    suspects one by one;
+  - `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<version>`
+    reinstalls/aligns;
+  - `dsh-tui doctor` runs environment diagnostics.
+
+## Running in VS Code / Herdr
+
+- **VS Code**: run directly in the integrated terminal, or use the
+  `dsh-tui-vscode` companion extension on the Marketplace (real terminal
+  sessions, session history, specific-session resume, IDE selection channel).
+  See [VS Code guide](vscode.en.md).
+- **Herdr**: run `dsh-tui` directly in a [Herdr](https://herdr.dev) pane with
+  no extra setup; dsh-TUI reports `idle` / `working` / `blocked` through
+  Herdr's local integration API (questionnaires and tool approvals count as
+  `blocked`), and stays completely inactive outside Herdr.
+
+## Update to the latest version
+
+The project moves fast. Updating reuses the install command with an explicit
+`@latest`:
+
+```sh
+dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
+```
+
+- Without `@latest`, pnpm resolves within the version range already recorded
+  in the profile's `package.json` (for example `^0.1.4`), so it may stay on an
+  old line. That is the usual reason "re-running the install command" appears
+  to change nothing.
+- To confirm: the startup banner shows the running version
+  (`✦ dsh-TUI vX.Y.Z`).
+- Your `cordis.patch.yml` override layer survives updates untouched.
+- Session storage may move between versions (since 0.3.7, `/resume` uses the
+  JSONL session store shared with dsh web), so older sessions missing from the
+  list after a major update is expected — the underlying data is not deleted.
+
+### pnpm install-script blocks and foreign-platform natives
+
+If `dsh plugin` fails with `ERR_PNPM_IGNORED_BUILDS` (pnpm ≥11 blocks
+dependencies that carry install scripts by default, e.g. `@google/genai` and
+`protobufjs` — none of these scripts is needed at runtime, so they can safely
+be ignored), add to the profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  '@google/genai': false
+  protobufjs: false
+```
+
+`/update` and `dsh-tui update` seed this configuration automatically — no
+manual step needed.
+
+Updates also maintain `ignoredOptionalDependencies` covering foreign-platform
+`@img/sharp-*` natives:
+
+- sharp ships as all-platform optional dependencies, and an untouched
+  `pnpm update` downloads every platform's binaries (about 200MB measured).
+- The list is recomputed for the running platform on every update. Foreign
+  natives are skipped while this platform's own and the platform-agnostic wasm
+  fallbacks stay.
+- Move the profile to another platform or musl container and the next update
+  there refreshes it.
+- An existing profile's lockfile still lists every platform, so its first
+  update downloads them once more before the filter takes effect.
+- Entries outside those two platform tables (a user's `fsevents`, a
+  hand-written `@img/sharp-wasm32` exemption) are left as they are. This needs
+  a pnpm that supports the key; one that does not fails nothing — it merely
+  loses the saving.
+
+## Profile configuration
+
+The user override file is:
+
+```text
+$DSH_HOME/profiles/dsh-tui/cordis.patch.yml
+```
+
+When overriding a row, its `config` block is replaced as a whole rather than
+deep-merged. Repeat every key you want to keep. See
+[Configuration](configuration.en.md) for examples.
+
+The root `cordis.yml` is a bare-composition example. A normal npm/profile
+installation uses `cordis.patch.yml`; do not copy the root configuration into
+the profile.
+
+## Develop from source
+
+```sh
+git clone --recurse-submodules https://github.com/ccch1mneyyy/dsh-TUI.git
+cd dsh-TUI
+pnpm install --frozen-lockfile
+pnpm build
+pnpm smoke
+```
+
+The repository has two submodules; `vendor/dsh-std` is required to install:
+
+- `vendor/dsh-std`: its `packages/*` are listed as workspace packages in
+  `pnpm-workspace.yaml`.
+- `dsh-ecosystem-spec`: the ecosystem specification used by contract checks.
+
+Without `--recurse-submodules` these directories stay empty and
+`pnpm install --frozen-lockfile` fails outright. For a checkout that was
+already cloned:
+
+```sh
+git submodule update --init --recursive
+```
+
+`pnpm build` cleans the ignored `lib/` directory, compiles `src/` into
+`lib/types/`, and runs the build gates.
+
+- **Git URL installs are not supported** (workspace deps / submodule / pnpm
+  ≥11 prepare allowlist).
+- The publish workflow performs an explicit clean compilation and
+  package-surface check before packing.
+
+For an integration test of the current source, run this once after initial
+setup or whenever the normal model/key configuration changes:
+
+```sh
+pnpm dev:copy-config
+```
+
+After each source change, build, pack, install in isolation, and launch with:
+
+```sh
+pnpm dev
+```
+
+`pnpm dev:copy-config` copies only `~/.dsh/settings.yaml` and
+`~/.dsh/.credentials.yaml`. Files are set to mode `0600` on Unix; Windows uses
+the OS-managed file ACL.
+
+`pnpm dev` uses isolated `HOME`, `DSH_HOME`, and session directories, leaving
+the normal `~/.dsh/profiles/dsh-tui`, `~/.dsh-tui`, and sessions untouched. The
+test root defaults to:
+
+- `$XDG_CACHE_HOME/dsh-tui-dev` on Unix (`~/.cache/dsh-tui-dev` when unset).
+- `%LOCALAPPDATA%\dsh-tui-dev` on Windows.
+- Override it with `DSH_TUI_DEV_ROOT`.
+
+To verify only the build, pack, and install path without launching the TUI,
+run:
+
+```sh
+pnpm dev:test
+```
+
+CI also runs three rendering regressions:
+
+```sh
+node --import tsx/esm scripts/repro-askpanel.tsx
+node --import tsx/esm scripts/verify-askpanel-layout.tsx
+node --import tsx/esm scripts/repro-toolcards.tsx
+```
+
+The `pnpm tui` script invokes `scripts/run.ts`, which directly composes
+DeepSeek Harness source patches and assumes a Harness monorepo `packages/*`
+layout by default. A standalone checkout must set `DSH_TUI_DEV_WORKSPACE` to
+the Harness root. To test only this repository's current source, prefer
+`pnpm dev`; it uses the same profile installation path as an end-user install.
+
+## Troubleshooting
+
+### `dsh-tui requires an interactive terminal`
+
+stdout is not a TTY. Start the process directly in a terminal rather than
+redirecting its main output to another command or file.
+
+dsh-tui detects two things: stdout is not a TTY, and the process was not
+started by the `dsh-tui` launcher. When both hold, it silently skips the TUI
+frontend (no error, the host keeps booting). That is the case when dsh-tui is
+only installed in a profile and a non-terminal host (Web / Tauri / GUI, stdout
+piped or null) starts the DSH composition.
+
+The error above only appears when `dsh-tui` (or the standalone portable build)
+was explicitly launched without a TTY.
+
+### `dsh` or `pnpm` cannot be found
+
+Make sure the global npm bin directory is on `PATH`, then open a new terminal.
+`install.sh` checks both commands before installation.
+
+### The TUI exits right back to the shell with almost no error (pnpm 9)
+
+In a profile installed by pnpm 9, the transitive dependency
+`dsh-working-activity` is not hoisted where the loader can resolve it; the
+failed module resolution tears down the whole plugin tree, and the TUI prints
+the resume hint and exits (issue #60). Upgrade pnpm to 10+ and reinstall:
+
+```sh
+npm install -g pnpm@latest
+dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
+```
+
+### The model reports missing credentials
+
+For `deepseek-official`, confirm that `DEEPSEEK_API_KEY` is set in the same shell
+that starts `dsh`. Check `DEEPSEEK_BASE_URL` too for a custom endpoint. For
+`deepseek-account` or a subscription model, inspect `/auth status` and sign in again with
+`/auth login <provider>` if needed.
+
+### The activity row appears twice
+
+Check whether `dsh-working-activity` was added separately to the profile. Keep
+the row inserted by the dsh-tui patch and remove the duplicate bundle entry.
+
+### The TUI is misaligned or leaves terminal state behind
+
+Run `/doctor`, record the terminal and mode, then consult
+[Interaction and commands](interaction.en.md) and
+[Architecture and limitations](architecture.en.md). `DSH_TUI_RENDER_LOG` can
+capture raw frames for rendering bugs, but those frames may contain visible
+conversation content and should be handled as sensitive data.