@deepseekcode/cli 1.0.29 → 1.0.30

package/README.md

@@ -1,123 +1,150 @@
 # @deepseekcode/cli
 
-Terminal UI (TUI) for the DeepSeekCode TypeScript runtime. Built on [Ink](https://github.com/vadimdemedes/ink) (React-for-terminal).
+[![npm version](https://img.shields.io/npm/v/@deepseekcode/cli.svg)](https://www.npmjs.com/package/@deepseekcode/cli)
+[![License](https://img.shields.io/npm/l/@deepseekcode/cli.svg)](https://www.npmjs.com/package/@deepseekcode/cli)
+[![Node version](https://img.shields.io/node/v/@deepseekcode/cli.svg)](https://nodejs.org)
 
-## Usage
+**DeepSeekCode CLI** — a TypeScript-first AI coding agent with an interactive terminal UI, a built-in web UI, and a local HTTP/WS runtime. It starts a full agent core in-process, opens an [Ink](https://github.com/vadimdemedes/ink) (React-for-terminal) interface in your terminal, and serves a companion web UI you can use for configuration and remote access.
 
-```bash
-bun --filter @deepseekcode/cli build
-node packages/cli/dist/cli.js run          # Connect to remote server
-node packages/cli/dist/cli.js start        # Start local in-process runtime
-node packages/cli/dist/cli.js exec <cmd>   # Non-interactive execution
-node packages/cli/dist/cli.js codeview     # AI code review
-node packages/cli/dist/cli.js --resume     # Resume last session
-```
+- **TUI** — interactive, keyboard-first coding agent in your terminal
+- **Local runtime** — spins up an in-process server (HTTP + WebSocket), no separate install needed
+- **Web UI** — configuration & model management at `http://localhost:8080`
+- **Non-interactive modes** — `exec`, `codeview`, `test-fix` for scripts & CI
+- **Multi-theme** — dark / light / nord / dracula / monokai / one-dark / tokyo-night
 
-## Architecture
+Requires **Node.js >= 18**.
 
-```
-packages/cli/src/
-  main.ts              # Entry point — CLI arg parser, startup lifecycle
-  App.tsx              # Root React component (connected gating, animation clock control)
-  client.ts            # WebSocket client (DeepSeekCodeClient)
-  localClient.ts       # In-process runtime client (LocalRuntimeClient)
-  store.ts             # Microtask-batched state store
-  ink/                 # Forked Ink renderer (frame budget, Yoga caching)
-  hooks/               # React hooks for state, animation, WebSocket, mouse, keyboard
-  components/          # UI components (ChatArea, StatusLine, TextInput, etc.)
-  tui/                 # Interaction primitives (selection, navigation, search)
-  commands/            # Slash command registry and handlers
-  utils/               # Utilities (session persistence, logging, config)
+---
+
+## Install
+
+```bash
+npm install -g @deepseekcode/cli
 ```
 
-## Performance: OOM Prevention
+Or with your favorite package manager:
 
-The Ink renderer + React reconciler creates significant memory pressure per rendered frame. The following measures prevent OOM in large/heavy sessions:
+```bash
+# pnpm
+pnpm add -g @deepseekcode/cli
 
-### Animation Clock Governance
-- **Global gate**: `setAnimationsEnabled(false)` pauses ALL animation subscribers during startup. Animations only activate after WebSocket `connected`.
-- **Dynamic tick rate**: idle (2fps) → active (5fps) → streaming (10fps). Default changed from 50ms/20fps to 200ms/5fps.
-- **Auto-stop**: Clock stops entirely when last subscriber unsubscribes.
+# yarn
+yarn global add @deepseekcode/cli
 
-### Frame Budget Control
-- Ink's `onRender` measures frame generation time; if a frame completes faster than 100ms since the last, it's skipped (up to 3 consecutive skips before force-render).
-- Combined with `FRAME_INTERVAL_MS=500` throttle on the render scheduler.
+# bun
+bun add -g @deepseekcode/cli
+```
 
-### Yoga Layout Versioning
-- `onComputeLayout` tracks a `layoutVersion` counter; if no DOM mutations happened since last computation, `calculateLayout()` (the most expensive per-frame operation) is skipped entirely.
+This installs two commands: **`dscode`** (short) and **`deepseekcode`** (full name).
 
-### Lazy Hook Mounting
-- Interaction hooks (mouse wheel, text selection, keyboard selection, message navigation) only mount after `connected === true`.
-- Startup state updates are batched into a single `updateAppState()` call (from 3-5 sequential calls).
+## Quick Start
 
-## Theme System
+```bash
+dscode
+```
 
-The CLI supports **multi-theme** with dynamic switching, a `t` Proxy for live access, and JSON file loading compatible with MiMo-Code / opencode format.
+That's it. The CLI starts the local agent runtime and opens the interactive terminal. On first run (no provider configured) it prints a link to the web UI where you can set up your LLM provider and model:
 
-### Built-in Themes
+```bash
+# model/provider setup page (also served by the CLI)
+# → http://localhost:8080/#models
+```
 
-| Theme | Env Value | Style |
-|-------|-----------|-------|
-| Dark (default) | `dark` | ANSI named colors, broad compat |
-| Light | `light` | Light terminal variant |
-| Nord | `nord` | ❄️ Arctic blue-grey palette |
-| Dracula | `dracula` | 🧛 Dark purple-vibrant |
-| Monokai | `monokai` | 🎨 Classic code editor |
-| One Dark | `one-dark` | 🌙 Atom's iconic dark |
-| Tokyo Night | `tokyo-night` | 🌃 Deep navy + vibrant accents |
+If your terminal's stdin isn't a TTY (e.g. a script or CI pipeline), the CLI skips the TUI and runs **headless** — the web UI stays available at the printed URL.
 
-### Usage
+Connect to an **existing** backend instead of starting a local one:
 
 ```bash
-# Via environment variable
-DEEPSEEKCODE_THEME=nord node packages/cli/dist/cli.js run
-DEEPSEEKCODE_THEME=dracula node packages/cli/dist/cli.js start
-DEEPSEEKCODE_THEME=/path/to/my-theme.json node packages/cli/dist/cli.js run
-
-# Custom color overrides (partial merge on current theme)
-DEEPSEEKCODE_THEME_COLORS='{"primary":"#ff0000"}' node packages/cli/dist/cli.js run
+dscode run --backend http://localhost:8080
 ```
 
-### Programmatic API
+Resume your last session (or a specific one):
 
-```typescript
-import { t, setTheme, getTheme, registerTheme, listThemes } from './theme.js'
+```bash
+dscode --resume          # last session
+dscode --resume <id>     # specific session
+```
 
-// Components always use the live theme via Proxy
-<Text color={t.primary}>Brand</Text>
-<Text color={t.error}>Error</Text>
-<Text backgroundColor={t.success}>Success</Text>
+## CLI Commands
 
-// Switch at runtime
-setTheme('nord')
+| Command | Description |
+|---------|-------------|
+| `dscode` / `dscode start` | Start local runtime + interactive TUI (also serves Web UI + API) |
+| `dscode start --auto` | Start with auto-approval mode enabled |
+| `dscode run --backend URL` | Connect to an existing backend instead of starting one |
+| `dscode exec <command>` | Execute a command non-interactively (JSONL output) |
+| `dscode exec --file <path>` | Read the command from a file |
+| `dscode codeview` | AI code review — bugs + unwired features (JSON output) |
+| `dscode review` | Review current code changes (legacy) |
+| `dscode test-fix` | Run the auto-fix test loop |
+| `dscode --resume [id]` | Resume the last session, or a specific one |
+| `dscode version` | Print version |
 
-// Register a custom theme
-registerTheme('my-theme', { primary: '#ff6600', bg: '#1a1a2e', ... })
-setTheme('my-theme')
+Run `dscode --help` (or `-h`) for the full list.
 
-// Enumerate all registered themes
-listThemes()  // ['dark', 'dracula', 'light', 'monokai', ...]
-```
+### Non-interactive examples
 
-### Architecture
+```bash
+# Execute a command, get JSONL results
+dscode exec "fix the failing test in src/utils"
 
-```
-src/theme/
-├── types.ts         # ThemeColors interface (60+ color keys)
-├── registry.ts      # Theme registry + t Proxy
-├── detect.ts        # Terminal background detection (OSC 11)
-├── loader.ts        # JSON theme file loader
-└── builtins/        # Built-in theme factories
-    ├── index.ts, dark.ts, light.ts,
-    ├── nord.ts, dracula.ts, monokai.ts,
-    ├── one-dark.ts, tokyo-night.ts
-```
+# Plain text output, command from file
+dscode exec --file ./task.txt --text
 
-The `t` Proxy (`src/theme/registry.ts`) forwards every property access to the active theme via `getTheme()`, so `t.primary` always returns the current theme's primary color even after `setTheme()` — no re-import needed.
+# AI code review focused on security, write report to file
+dscode codeview --focus security --output review.json
 
-## Config
+# Auto-fix test loop (max 5 retries, analyze only)
+dscode test-fix --packages packages/cli --retries 5 --dry-run
+```
 
-The CLI reads `~/.agent/config.yaml`.
+## Interactive Commands
+
+Inside the TUI, use `/help` for the full list (most commands have Chinese aliases). Highlights:
+
+| Command | Action |
+|---------|--------|
+| `/help` | Show all commands |
+| `/model [name]` | Open model picker or switch model directly |
+| `/theme [name]` | Show or change terminal theme |
+| `/plan` | Toggle plan mode (review before executing) |
+| `/auto` | Toggle auto-approval mode |
+| `/mode <mode>` | Cycle/set mode: act · auto-act · plan · auto-plan · goal · auto-goal |
+| `/goal` | Set goal-directed mode |
+| `/thinking` | Toggle think mode on/off |
+| `/context` | Show current conversation state |
+| `/sessions [id]` / `/resume [id]` | List history / switch session |
+| `/tasks` | Toggle sub-task output panel |
+| `/undo [list]` | Undo the most recent file change |
+| `/clear` | Clear local conversation messages |
+| `/mcp <action>` | Manage MCP servers |
+| `/skills` | Insert a skill |
+| `/trace <traceId>` | Query a trace by id |
+| `/stop` `/pause` `/continue` | Control AI generation |
+| `/exit` | Exit |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | HTTP port (default: first available from 8080) |
+| `--ws-port <port>` | WebSocket port (default: HTTP port + 1) |
+| `-w, --workspace <dir>` | Workspace directory (default: current directory) |
+| `-F, --force` | Kill an existing process on the target port before starting |
+| `-b, --backend <url>` | Backend URL for `run` mode |
+| `--ws <url>` | Override WebSocket URL |
+| `--provider <name>` | Provider to use (exec/review) |
+| `--model <name>` | Model to use (exec/review) |
+| `--theme <name\|path>` | Theme name or JSON theme file path |
+| `--prompt-version <ver>` | Prompt template version |
+| `--timeout <ms>` | Per-attempt LLM timeout (default: 300000 = 5 min) |
+| `--stall-threshold <ms>` | Stream stall detection threshold (default: 240000 = 4 min) |
+| `--no-update-check` | Disable the startup new-version notice |
+| `--no-auto-update` | Disable background auto-update (notice still shown) |
+
+## Configuration
+
+The CLI reads `~/.agent/config.yaml`:
 
 ```yaml
 backend_url: http://localhost:8080
@@ -125,20 +152,53 @@ ws_url: ws://localhost:8081/ws
 workspace_dir: /path/to/workspace
 ```
 
-## Auto-Update
+Provider / model settings are managed through the web UI at `http://localhost:8080/#models`.
 
-`dscode` 每次启动会异步查询 npm 上的最新版本（不阻塞启动）。当发现新版本时，
-默认会在**后台自动重装全局包**（`npm install -g @deepseekcode/cli@latest`），
-新版本在下次启动时生效，升级结果会在下一次启动时报告。
+## Themes
 
-- 仅对「全局 npm 安装」生效；源码开发环境、`npx`/`bunx` 临时缓存不会误升级。
-- 关闭自动安装（保留版本提示）：`DEEPSEEKCODE_NO_AUTO_UPDATE=1` 或 `--no-auto-update`
-- 连版本检查一起关闭：`DEEPSEEKCODE_NO_UPDATE_CHECK=1` 或 `--no-update-check`
+Set the theme at startup via the `DEEPSEEKCODE_THEME` env var (or `--theme`):
 
-## Development
+| Theme | Env Value | Style |
+|-------|-----------|-------|
+| Dark (default) | `dark` | ANSI named colors, broad compat |
+| Light | `light` | Light terminal variant |
+| Nord | `nord` | Arctic blue-grey palette |
+| Dracula | `dracula` | Dark purple-vibrant |
+| Monokai | `monokai` | Classic code editor |
+| One Dark | `one-dark` | Atom's iconic dark |
+| Tokyo Night | `tokyo-night` | Deep navy + vibrant accents |
 
 ```bash
-bun --filter @deepseekcode/cli typecheck
-bun --filter @deepseekcode/cli build
-bun --filter @deepseekcode/cli test
+DEEPSEEKCODE_THEME=nord dscode
+DEEPSEEKCODE_THEME=/path/to/my-theme.json dscode
+
+# Partial overrides on the current theme (JSON)
+DEEPSEEKCODE_THEME_COLORS='{"primary":"#ff0000"}' dscode
 ```
+
+Switch themes at runtime with `/theme [name]`.
+
+## Auto-Update
+
+On startup, `dscode` checks npm for the latest version asynchronously (non-blocking). When a newer version is found, the CLI **automatically reinstalls the global package** in the background (`npm install -g @deepseekcode/cli@latest`); the new version takes effect on the next launch.
+
+- Only affects **global npm installs** — source builds and `npx`/`bunx` caches are never touched.
+- Disable auto-install (keep the version notice): `DEEPSEEKCODE_NO_AUTO_UPDATE=1` or `--no-auto-update`
+- Disable the check entirely: `DEEPSEEKCODE_NO_UPDATE_CHECK=1` or `--no-update-check`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DEEPSEEKCODE_THEME` | Theme name or JSON theme file |
+| `DEEPSEEKCODE_THEME_COLORS` | JSON partial color overrides |
+| `DEEPSEEKCODE_HTTP_PORT` / `DEEPSEEKCODE_WS_PORT` | Default HTTP / WebSocket ports |
+| `DEEPSEEKCODE_QUIET=1` | Suppress non-fatal startup warnings |
+| `DEEPSEEKCODE_NO_AUTO_UPDATE=1` | Disable background auto-update |
+| `DEEPSEEKCODE_NO_UPDATE_CHECK=1` | Disable the version check |
+| `DEEPSEEKCODE_FORCE_UTF8=0` | Skip forcing the Windows console to UTF-8 |
+| `DSC_HEAP_LIMIT_MB` | Node heap limit hint for large sessions (default: 8192) |
+
+## License
+
+[Apache-2.0](https://www.npmjs.com/package/@deepseekcode/cli)