### Setup development environment

Source: https://github.com/weijiafu14/pi2dsh/blob/main/CONTRIBUTING.md

Commands to install dependencies and verify the project configuration.

```sh
corepack pnpm@11.7.0 install
pnpm verify
```

--------------------------------

### Verify E2E Examples

Source: https://github.com/weijiafu14/pi2dsh/blob/main/CLAUDE.md

Run E2E verification for specific examples with custom environment variables.

```bash
ONLY=<example> PI2DSH_DSH_BIN=<该代 CLI> PI2DSH_DSH_CWD=<该代 CLI 目录> node scripts/verify-examples-e2e.mjs <另存的证据文件>
```

--------------------------------

### Verify Examples E2E

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/mcp-compatibility.md

Execute a clean profile scenario using a packed version of the pi2dsh package to reproduce user installation shapes.

```sh
ONLY=tui-mcp PI2DSH_ENGINE_SPEC=file:/absolute/path/to/pi2dsh.tgz \
  node scripts/verify-examples-e2e.mjs
```

--------------------------------

### Run Web Profile

Source: https://github.com/weijiafu14/pi2dsh/blob/main/CLAUDE.md

Start the web profile on a specific port.

```bash
node --import tsx/esm apps/cli/src/bin.ts --profile web --port 5178
```

--------------------------------

### Start DSH

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/alibaba-token-plan/README.md

Launch the DSH web interface to select the model route.

```sh
dsh web
```

--------------------------------

### Start DSH web profile

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/side-conversation/README.md

Initializes the DSH session using the web profile.

```sh
dsh --profile web
```

--------------------------------

### Install community provider for SuperGrok

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Installs the community-maintained pi-grok provider directly from GitHub.

```sh
dsh plugin --profile web add github:stnly/pi-grok
# restart dsh, then run: /login xai-oauth
```

--------------------------------

### Install community provider for Kimi Coding

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Installs the specific community package required for Kimi Coding support.

```sh
dsh plugin --profile web add pi-provider-kimi-code
```

--------------------------------

### Run acceptance tests

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/alibaba-token-plan/README.md

Execute the repository's example harness to verify the integration with a specific plan key.

```sh
ALIBABA_TOKEN_PLAN_API_KEY='<your-plan-key>' \
PI2DSH_ENGINE_SPEC='pi2dsh@<published-version>' \
ONLY=alibaba-token-plan pnpm test:examples
```

--------------------------------

### Example plugin output

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/presentation-surfaces/README.md

The rendered output of the pi-powerline-footer plugin as it appears in the DSH widget dock.

```text
 DeepSeek-V4-Flash | think:off | pi2dsh | 0/1.0M (0.0%)
```

--------------------------------

### Install pi2dsh and pi-btw plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/side-conversation/README.md

Use the DSH CLI to add the necessary plugins to the web profile.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-btw
```

--------------------------------

### Install pi2dsh and Pi plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/post-pi-community.md

Commands to install the compatibility engine and a Pi-compatible package into the DeepSeek Harness environment.

```sh
dsh plugin add pi2dsh        # the engine, once
dsh plugin add <your-package>  # your package, exactly as published
```

--------------------------------

### Install DSH CLI via npm

Source: https://github.com/weijiafu14/pi2dsh/blob/main/CLAUDE.md

Install the DSH CLI package using npm.

```bash
pnpm add @deepseek-ai/dsh@0.1.0-rc.8
```

--------------------------------

### Sorting algorithm request

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/side-conversation/README.md

Example prompt for requesting sorting algorithms in the main thread.

```text
Name three classic sorting algorithms, one line each.
```

--------------------------------

### Example settings profile

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/post-model-providers.md

The configuration structure added to DSH settings after successful authentication.

```yaml
llm-pi-ai:
  providers:
    openai-codex:
      displayName: OpenAI (ChatGPT Plus/Pro)
      apiKeyEnv: PI2DSH_OAUTH_OPENAI_CODEX
```

--------------------------------

### Login Success Output

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Example of the confirmation message displayed after a successful login.

```text
Logged in to OpenAI (ChatGPT Plus/Pro); 7 models available
```

--------------------------------

### Run end-to-end verification for presentation surfaces

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/presentation-surfaces/README.md

Executes the verification script specifically for the presentation-surfaces example.

```bash
ONLY=presentation-surfaces node scripts/verify-examples-e2e.mjs
```

--------------------------------

### Install dsh-TUI plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Commands to add the necessary plugins to the dsh-TUI profile.

```sh
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui   # skip if the profile exists
dsh plugin --profile dsh-tui add pi2dsh
dsh plugin --profile dsh-tui add pi-mcp-adapter
```

--------------------------------

### Configure MCP servers

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Command to initiate the setup flow for MCP server definitions within dsh-TUI.

```text
/pi-mcp setup
```

--------------------------------

### Install DSH Plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/replies-mcp-oauth.md

Use the DSH CLI to add the necessary plugins for pi2dsh and MCP adapter support.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-mcp-adapter
```

--------------------------------

### Install the pi2dsh engine

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Adds the core pi2dsh plugin to the web profile.

```sh
dsh plugin --profile web add pi2dsh
```

--------------------------------

### Start the recording proxy

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/gateway-compat/README.md

Run the recording proxy to capture and inspect requests sent to the upstream gateway.

```sh
PROXY_UPSTREAM=https://api.deepseek.com \
  node examples/gateway-compat/probe/recording-proxy.mjs
```

--------------------------------

### Run Full End-to-End Regression

Source: https://github.com/weijiafu14/pi2dsh/blob/main/CLAUDE.md

Executes the complete suite of examples and step-seams using the newly released version from npm.

```bash
pnpm verify:release   # verify + 全部 examples（装 npm 上刚发的那版）+ step-seams 真机
```

--------------------------------

### Install DSH plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/alibaba-token-plan/README.md

Add the required pi2dsh engine and Alibaba provider packages to the DSH web profile.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-provider-alibaba
```

--------------------------------

### Example request capture

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/gateway-compat/README.md

A sample JSONL entry showing the translated request structure captured by the probe.

```json
{"roles":["system","user"],
 "maxTokensField":"max_tokens",
 "reasoningEffort":"high",
 "store":null}
```

--------------------------------

### Generate image via natural language prompt

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/codex-image-gen/README.md

Example prompt to trigger the image generation tool.

```text
Use codex_generate_image once. Generate a square app icon with white letters
DSH on a vivid cobalt-blue background. Use quality low. Show me the result.
```

--------------------------------

### Configure Proxy for DSH

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Command to start DSH with environment proxy support and warning suppression.

```sh
NODE_USE_ENV_PROXY=1 NODE_OPTIONS=--no-warnings dsh
```

--------------------------------

### Configure and run DSH with the probe provider

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/gateway-compat/README.md

Set the environment variables and install the necessary plugins to test the gateway compatibility.

```sh
export PROBE_API_KEY="$DEEPSEEK_API_KEY"
export PROBE_BASE_URL=http://127.0.0.1:4599/v1

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add file:examples/gateway-compat/probe/pi-probe-provider
dsh --profile web --port 5184
```

--------------------------------

### Configure MCP Server JSON

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/tui-mcp/README.md

Example configuration for an OAuth-protected Atlassian MCP server in .mcp.json.

```json
{
  "mcpServers": {
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1/mcp/authv2",
      "auth": "oauth"
    }
  }
}
```

--------------------------------

### Install a Pi provider package

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/post-model-providers.md

Use this command to add a specific Pi provider package to a DSH profile.

```sh
dsh plugin --profile <p> add pi-provider-litellm
```

--------------------------------

### Install pi2dsh plugin

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/post-model-providers.md

Add the pi2dsh plugin to a specific DSH profile and restart the application.

```sh
dsh plugin --profile <p> add pi2dsh
# restart dsh
```

--------------------------------

### Install Pi plugins for DSH

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/presentation-surfaces/README.md

Commands to add the pi2dsh engine and a specific Pi plugin to the web profile.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-powerline-footer
```

--------------------------------

### Edit local image via prompt

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/codex-image-gen/README.md

Example prompt to edit an existing local image using an absolute path.

```text
Use codex_generate_image once to edit /absolute/path/solid-blue.png. Turn it
into a vivid orange square with one centered white five-point star and no text.
Show me the result.
```

--------------------------------

### Install pi2dsh and Codex Image Gen Plugin

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/upstream-codex-image-compat-report.md

Commands to add the necessary plugins to the DeepSeek Harness web profile.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add @crazygit/pi-codex-image-gen
```

--------------------------------

### Initialize and Manage MCP Adapter

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/tui-mcp/README.md

Commands to set up the adapter and launch the interactive server manager.

```text
/pi-mcp setup
```

```text
/pi-mcp
```

--------------------------------

### Initialize DSH with API Key

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/custom-gateways/README.md

Set the required environment variable for the gateway and launch the DSH web interface.

```sh
export OPENROUTER_API_KEY='<your-openrouter-key>'
dsh web
```

--------------------------------

### ctx.ui.getToolsExpanded

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Gets the bridge-local tools expanded presentation flag.

```APIDOC
## getToolsExpanded()

### Description
Returns the current state of the bridge-local tools expanded presentation flag.
```

--------------------------------

### ctx.ui.getAllThemes

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Lists all available themes.

```APIDOC
## getAllThemes()

### Description
Returns a list containing the single headless theme.
```

--------------------------------

### CLI Helper Commands

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Use these commands to inspect package compatibility, view the capability matrix, or generate MCP server configurations.

```sh
npx pi2dsh inspect <pkg>@<version>   # compatibility report before an upgrade
npx pi2dsh matrix --json             # the full capability matrix
npx pi2dsh mcp-config                # Pi mcpServers config → official DSH MCP entries
```

--------------------------------

### ctx.ui.getTheme

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Resolves the headless theme.

```APIDOC
## getTheme()

### Description
Resolves and returns the headless theme.
```

--------------------------------

### Verify TUI MCP Tool E2E

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/mcp-compatibility.md

Run the verification script against an installed upstream package after building the project.

```sh
PI2DSH_MCP_ADAPTER_ROOT=/absolute/path/to/node_modules/pi-mcp-adapter \
  node scripts/verify-tui-mcp-tool-e2e.mjs
```

--------------------------------

### Run project verification and testing commands

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/posting-kit/support-matrix.md

Use these commands to perform type checking, contract testing, packaging, and community-focused audits and tests.

```sh
pnpm verify                      # typecheck + 95 contract tests + packaging
pnpm audit:community             # static screening over the top-50 corpus
pnpm test:community              # deep runtime + official plugin manager + host e2e
```

--------------------------------

### Install DSH engine and vision plugin

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/vision-bridge/README.md

Commands to add the pi2dsh engine and the @kassing/pi-vision plugin to the DSH web profile.

```sh
dsh plugin --profile web add pi2dsh
dsh plugin --profile web add @kassing/pi-vision
```

--------------------------------

### ctx.ui.setTheme

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Sets the active theme.

```APIDOC
## setTheme(themeName)

### Description
Sets the theme. Accepts the headless theme; other names report an error.
```

--------------------------------

### ctx.ui Methods

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Methods for managing UI components, themes, and tool states.

```APIDOC
## ctx.ui Methods

### setFooter(factory)
Sets the footer component using a factory function. The factory is called with a headless theme and rendered.

### setHeader(factory)
Sets the header component using a factory function. Rendered by the client header-utilities seat.

### setTitle(title)
Sets the session-specific title, displayed as a pill in the shell.overlay seat.

### theme
A headless Theme object used for styling.

### getAllThemes()
Returns a list of all headless themes owned by the bridge.

### getTheme(name)
Resolves a headless theme by its name.

### setTheme(theme)
Sets the active headless theme.

### getToolsExpanded()
Returns the current bridge-local flag for tool expansion.

### setToolsExpanded(value)
Sets the bridge-local flag for tool expansion.
```

--------------------------------

### ctx.ui.theme

Source: https://github.com/weijiafu14/pi2dsh/blob/main/docs/capabilities/interaction.md

Accesses the headless theme.

```APIDOC
## theme()

### Description
Returns the headless theme whose styling calls return unstyled text.
```

--------------------------------

### Authentication Header Error Message

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/subscription-login/README.md

Example of the error message displayed when a provider requires a request header instead of an API key.

```text
logged in to "kimi-coding", but this provider authenticates with a request
header rather than an api key — DSH routes name a credential reference, so no
model route was added for it
```

--------------------------------

### Get absolute path for local image editing

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/codex-image-gen/README.md

Command to retrieve the absolute path of a local image file for use in editing prompts.

```sh
realpath examples/vision-bridge/test-images/solid-blue.png
```

--------------------------------

### Troubleshoot pnpm build and versioning

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Commands to resolve build script blocks and force specific package versions.

```sh
pnpm approve-builds
```

```sh
dsh plugin add pi2dsh@<version>
```

--------------------------------

### Development and Testing Commands

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Commands for verifying code, running community tests, and executing live model acceptance tests requiring specific environment variables.

```sh
pnpm verify                 # typecheck + contract tests + packaging
pnpm audit:community        # static screening over the top-50 corpus
pnpm test:community         # deep runtime + official plugin-manager + e2e
DEEPSEEK_API_KEY=… pnpm test:live    # real-model acceptance (key from env only)
CODEX_AUTH_FILE=… pnpm test:codex-image # real OAuth generation + reference edit + Web pixels
```

--------------------------------

### Export plan credentials

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/alibaba-token-plan/README.md

Set the environment variables for the specific Alibaba plan purchased. Ensure the correct key is used for the corresponding plan type.

```sh
export ALIBABA_TOKEN_PLAN_API_KEY='<your-plan-key>'
```

```sh
export ALIBABA_CODING_API_KEY='<your-Coding-Plan-specific-key>'
```

--------------------------------

### Compare DSH MCP Commands

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/tui-mcp/README.md

Distinction between native DSH MCP client commands and the Pi adapter manager.

```text
/mcp       # native DSH MCP-client status
/pi-mcp    # the installed Pi adapter's manager
```

--------------------------------

### Configure Gateway in settings.yaml

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/custom-gateways/README.md

Add an llm-pi-ai section to your DSH settings file to define custom providers and their supported models.

```yaml
llm-pi-ai:
  providers:
    my-gateway:
      displayName: My Gateway
      api: openai-completions
      baseURL: https://openrouter.ai/api/v1
      apiKeyEnv: OPENROUTER_API_KEY        # a reference — no secret in the file
      models:
        - id: qwen/qwen2.5-vl-72b-instruct
          name: Qwen2.5-VL 72B
          contextWindow: 131072
          input: [text, image]
          reasoningEfforts:
            off:
            low: low
            high: high
          compat:
            supportsDeveloperRole: false
            maxTokensField: max_tokens
```

--------------------------------

### Run automated acceptance tests

Source: https://github.com/weijiafu14/pi2dsh/blob/main/examples/codex-image-gen/README.md

Command to execute the test suite using a specific authentication file.

```sh
CODEX_AUTH_FILE=$HOME/.codex/auth.json pnpm test:codex-image
```

--------------------------------

### Manage pi2dsh plugins

Source: https://github.com/weijiafu14/pi2dsh/blob/main/README.md

Common CLI commands for adding, removing, upgrading, and inspecting plugins.

```sh
dsh plugin add <pkg>
```

```sh
dsh plugin remove <pkg>
```

```sh
dsh plugin add <pkg>@latest
```

```sh
dsh plugin add pi2dsh@latest
```

```sh
npx pi2dsh inspect <pkg>@<version>
```