From 1ecbcfb1f4abac34dcef282a886f16fa6c1b36e3 Mon Sep 17 00:00:00 2001 From: Hunter Bown Date: Thu, 14 May 2026 03:38:19 -0500 Subject: [PATCH] docs(install): add download safety verification Document checksum verification, AV false-positive triage, Linux binary dependency expectations, and blocked-GitHub download fallback guidance. --- README.md | 5 ++++ docs/INSTALL.md | 74 +++++++++++++++++++++++++++++++++++++------------ 2 files changed, 62 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 00499c8d..cd15a463 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,11 @@ docker run --rm -it \ > In mainland China, speed up the npm path with > `--registry=https://registry.npmmirror.com`, or use the > [Cargo mirror](#china--mirror-friendly-installation) below. +> +> Download safety: official release binaries live under +> `https://github.com/Hmbown/DeepSeek-TUI/releases`. For manual downloads, +> verify the SHA-256 manifest and avoid look-alike repositories or search-result +> mirrors. See [download safety and checksums](docs/INSTALL.md#2-download-safety-and-checksums). [![CI](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/DeepSeek-TUI/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/deepseek-tui)](https://www.npmjs.com/package/deepseek-tui) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index f93bead7..5520aec8 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -27,7 +27,13 @@ platform/architecture combinations from v0.8.8 onward: ¹ The npm package will exit with a clear error and point you here. ² Provided your toolchain can compile a recent Rust workspace; see - [Build from source](#5-build-from-source) below. + [Build from source](#7-build-from-source) below. + +The Linux release assets are glibc builds, not musl builds. They dynamically +link normal Linux runtime libraries such as `libdbus-1` and `libc`; SQLite is +currently bundled into the binary through `rusqlite` so users do not need a +separate `libsqlite3` runtime package for official release assets. Musl-based +systems such as Alpine should use [Build from source](#7-build-from-source). > **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not** > publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi @@ -35,11 +41,45 @@ platform/architecture combinations from v0.8.8 onward: > from `npm i -g deepseek-tui`. v0.8.8 publishes both `deepseek-linux-arm64` > and `deepseek-tui-linux-arm64`, so a plain `npm i -g deepseek-tui` works > on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to -> [Build from source](#5-build-from-source) — `cargo install` works fine. +> [Build from source](#7-build-from-source) — `cargo install` works fine. --- -## 2. Install via npm (recommended) +## 2. Download safety and checksums + +Official release binaries are published only from +`https://github.com/Hmbown/DeepSeek-TUI/releases` and the npm package named +`deepseek-tui`. Do not install release assets from look-alike repositories, +archives, or search-result mirrors unless you deliberately trust that mirror. + +Every GitHub release includes `deepseek-artifacts-sha256.txt`. If you download +binaries manually, verify them before running: + +```bash +# Run from the directory containing the downloaded binaries. +curl -L -O https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt +sha256sum -c deepseek-artifacts-sha256.txt --ignore-missing +``` + +On macOS, use `shasum -a 256 -c deepseek-artifacts-sha256.txt` instead of +`sha256sum`. + +If antivirus software flags an official release binary, treat it as unresolved +until the exact artifact is identified. Please include all of the following in +the GitHub issue: + +- the release tag, for example `v0.8.36` +- the exact download URL +- the filename, for example `deepseek-linux-x64` +- the file SHA-256 from your machine +- the antivirus product name and detection name + +That lets maintainers distinguish a false positive on an official artifact from +a download sourced from an impersonating repository or mirror. + +--- + +## 3. Install via npm (recommended) ```bash npm install -g deepseek-tui @@ -67,12 +107,12 @@ Useful environment variables: > npm config set registry https://registry.npmmirror.com > npm install -g deepseek-tui > ``` -> See also [Section 3](#3-install-via-cargo-any-tier-1-rust-target) if you +> See also [Section 4](#4-install-via-cargo-any-tier-1-rust-target) if you > prefer Cargo over npm. --- -## 3. Install via Cargo (any Tier-1 Rust target) +## 4. Install via Cargo (any Tier-1 Rust target) If GitHub releases are slow, blocked, or you're on an unsupported architecture, install from crates.io directly. Both crates are required — the dispatcher @@ -138,7 +178,7 @@ is fastest from your network. --- -## 4. Install via Nix +## 5. Install via Nix **Try it** @@ -196,7 +236,7 @@ Install into a NixOS module: --- -## 5. Manual download from GitHub Releases +## 6. Manual download from GitHub Releases Grab the matching pair of binaries for your platform from the [Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases) and drop them @@ -239,7 +279,7 @@ when you need the newest version immediately. --- -## 6. Build from source +## 7. Build from source This is the catch-all for any platform we don't ship — including musl, riscv64, LoongArch, FreeBSD, and pre-2024 ARM64 distros. @@ -372,17 +412,17 @@ Both binaries appear in `target\release\deepseek.exe` and > **Prefer `npm install -g` on Windows unless you need to modify source.** > The npm package pulls prebuilt binaries and avoids the C toolchain -> dependency entirely — see [Section 2](#2-install-via-npm-recommended). +> dependency entirely — see [Section 3](#3-install-via-npm-recommended). --- -## 7. Troubleshooting +## 8. Troubleshooting ### `Unsupported architecture: arm64 on platform linux` You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64 binaries. Either upgrade (`npm i -g deepseek-tui@latest`) or use -`cargo install` per [Section 3](#3-install-via-cargo-any-tier-1-rust-target). +`cargo install` per [Section 4](#4-install-via-cargo-any-tier-1-rust-target). ### `MISSING_COMPANION_BINARY` at runtime @@ -411,7 +451,7 @@ cargo install deepseek-tui-cli --locked Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to a mirrored release-asset directory (rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the -Cargo mirror setup in [Section 3](#3-install-via-cargo-any-tier-1-rust-target). +Cargo mirror setup in [Section 4](#4-install-via-cargo-any-tier-1-rust-target). ### Debian/Ubuntu: `feature edition2024 is required` from `cargo install` @@ -426,7 +466,7 @@ is not stabilized in this version of Cargo ``` Install current stable Rust through rustup, then rerun the two Cargo install -commands from [Section 3](#3-install-via-cargo-any-tier-1-rust-target). For +commands from [Section 4](#4-install-via-cargo-any-tier-1-rust-target). For mainland China networks, this rsproxy-based sequence has been verified to work: ```bash @@ -500,7 +540,7 @@ path-agnostic — moving `target-dir` does not help. 2. **Close the antivirus software temporarily** during `cargo build`. 3. **Use `npm install -g deepseek-tui` instead** — the npm package ships prebuilt binaries and skips the Cargo build entirely - ([Section 2](#2-install-via-npm-recommended)). + ([Section 3](#3-install-via-npm-recommended)). 4. **Use `cargo install deepseek-tui-cli --locked`** from crates.io — this changes the binary path, which some AV tools treat differently. @@ -541,16 +581,16 @@ Use one of these paths: binaries from the GitHub release. 3. Install via Cargo, which builds locally and does not download GitHub release - assets. See [Section 3](#3-install-via-cargo-any-tier-1-rust-target). + assets. See [Section 4](#4-install-via-cargo-any-tier-1-rust-target). 4. Download both `deepseek` and `deepseek-tui` manually from the [Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases), place them in a directory on `PATH`, and make them executable. See - [Section 4](#4-manual-download-from-github-releases). + [Section 6](#6-manual-download-from-github-releases). --- -## 8. Verifying your install +## 9. Verifying your install ```bash deepseek --version