docs(repo): studio is the 2.x line, ready to be the default branch

The repository now describes the two lines the version roadmap announced (discussions/10748): 2.x on studio, 1.x on main-v2 in maintenance. - README (en, zh-CN): a Versions section and a Studio 2.x release badge. Install leads with Reasonix Studio 2.x from the studio-v* pre-releases, with the 1.x CLI and desktop app beside it as the stable line. The zh-CN build-from-source section gains the Studio build it lacked. - Issue forms offer 2.x / 1.x / 0.x, and the labeler maps them to v3 / v2 / v1, with the pasted version still overriding the dropdown. The forms link the roadmap. The PR template and CONTRIBUTING say which branch takes which changes. Issue forms, schedules and Dependabot are read from the default branch only, so these take effect when studio becomes it: - CodeQL scans pushes and PRs on both lines, and the weekly scan checks out each line and files results under its own ref, so 1.x keeps its security scanning. - v1-maintenance-schedule starts main-v2's nightly app-memory and diagnostic-overhead monitors, which measure the 1.x desktop app, on main-v2. - Dependabot drops /desktop/frontend and /site, which do not exist on studio, and covers /desktop/frontend-next and /desktop/electron. It also names main-v2 as a target for patch updates only.
2026-11-07 02:36:01 -10:00 · 2026-09-24 20:21:38 -07:00
1 parent 8aa9cb02ae
commit 4fe5caf8ce
@@ -7,23 +7,25 @@ body:
    attributes:
      value: |
        Thanks for filing a bug. Pick which version line you're on below — it gets
-        labeled (`v1`/`v2`) automatically, no maintainer action needed.
+        labeled automatically, no maintainer action needed. Not sure which line
+        you run? See the [version roadmap](https://github.com/esengine/DeepSeek-Reasonix/discussions/10748).
  - type: dropdown
    id: version-line
    attributes:
      label: Version line
      description: Which line are you running?
      options:
-        - "v2 — Go rewrite (1.x), main-v2 (active development)"
-        - "v1 — Legacy TypeScript (0.x), maintenance only"
+        - "2.x — Reasonix Studio, studio branch (active development)"
+        - "1.x — main-v2 branch (maintenance / stable)"
+        - "0.x — legacy TypeScript (maintenance only)"
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Exact version
-      description: Output of `reasonix --version`.
-      placeholder: e.g. 1.0.0
+      description: Output of `reasonix --version`, or the version shown in Studio's settings.
+      placeholder: e.g. 2.20.0 or 1.39.0
    validations:
      required: true
  - type: textarea
@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Version roadmap (1.x / 2.x)
+    url: https://github.com/esengine/DeepSeek-Reasonix/discussions/10748
+    about: Which line to use, which branch takes which changes, and where Reasonix is heading.
  - name: Questions & discussions
    url: https://github.com/esengine/DeepSeek-Reasonix/discussions
    about: For usage questions, ideas, and general discussion — please use Discussions instead of opening an issue.
@@ -9,8 +9,9 @@ body:
      label: Version line
      description: Which line is this for?
      options:
-        - "v2 — Go rewrite (1.x), main-v2 (active development)"
-        - "v1 — Legacy TypeScript (0.x), maintenance only"
+        - "2.x — Reasonix Studio, studio branch (active development)"
+        - "1.x — main-v2 branch (maintenance / stable)"
+        - "0.x — legacy TypeScript (maintenance only)"
    validations:
      required: true
  - type: textarea
@@ -1,5 +1,6 @@
 version: 2
 updates:
+  # 2.x (studio): the development line.
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
@@ -21,7 +22,7 @@ updates:
        update-types: ["minor", "patch"]

  - package-ecosystem: "npm"
-    directory: "/desktop/frontend"
+    directory: "/desktop/frontend-next"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
@@ -31,7 +32,7 @@ updates:
        update-types: ["minor", "patch"]

  - package-ecosystem: "npm"
-    directory: "/site"
+    directory: "/desktop/electron"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
@@ -47,3 +48,61 @@ updates:
    groups:
      actions:
        patterns: ["*"]
+
+  # 1.x (main-v2): maintenance. Dependabot reads this file from the default
+  # branch only, so the 1.x line is named here; it takes patch updates alone.
+  - package-ecosystem: "gomod"
+    directory: "/"
+    target-branch: "main-v2"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+    groups:
+      go-1x:
+        patterns: ["*"]
+        update-types: ["patch"]
+
+  - package-ecosystem: "gomod"
+    directory: "/desktop"
+    target-branch: "main-v2"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+    groups:
+      go-1x:
+        patterns: ["*"]
+        update-types: ["patch"]
+
+  - package-ecosystem: "npm"
+    directory: "/desktop/frontend"
+    target-branch: "main-v2"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+    groups:
+      npm-1x:
+        patterns: ["*"]
+        update-types: ["patch"]
+
+  - package-ecosystem: "npm"
+    directory: "/site"
+    target-branch: "main-v2"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major", "version-update:semver-minor"]
+    groups:
+      npm-1x:
+        patterns: ["*"]
+        update-types: ["patch"]
@@ -1,3 +1,9 @@
+<!--
+Target branch: 2.x features and fixes go to `studio`. 1.x takes bug fixes,
+provider/API compatibility, release/updater, security and platform stability
+only, on `main-v2`.
+-->
+
 ## Summary

 -
@@ -4,23 +4,25 @@ on:
  # Docs/release-notes/root-Markdown changes carry no analyzable code; the
  # weekly cron keeps the full scan cadence regardless.
  push:
-    branches: ["main-v2"]
+    branches: ["main-v2", "studio"]
    paths-ignore:
      - 'docs/**'
      - 'release-notes/**'
      - '*.md'
  pull_request:
-    branches: ["main-v2"]
+    branches: ["main-v2", "studio"]
    paths-ignore:
      - 'docs/**'
      - 'release-notes/**'
      - '*.md'
+  # A schedule runs only from the default branch, so the weekly scan checks out
+  # both lines itself: 1.x is in maintenance, and security is part of it.
  schedule:
    - cron: "27 3 * * 1"

 jobs:
  analyze:
-    name: Analyze (${{ matrix.language }})
+    name: Analyze (${{ matrix.language }}${{ matrix.branch && format(', {0}', matrix.branch) || '' }})
    runs-on: ubuntu-latest
    permissions:
      security-events: write
@@ -30,21 +32,32 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        include:
-          - language: go
-            build-mode: autobuild
-          - language: javascript-typescript
-            build-mode: none
-          - language: actions
-            build-mode: none
+        language: [go, javascript-typescript, actions]
+        # Empty means "the ref this event is about"; a scheduled run names each line.
+        branch: ${{ fromJSON(github.event_name == 'schedule' && '["main-v2", "studio"]' || '[""]') }}
    steps:
      - uses: actions/checkout@v7
+        with:
+          ref: ${{ matrix.branch }}
+      - id: head
+        if: matrix.branch != ''
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
      - name: Initialize CodeQL
        uses: github/codeql-action/[email protected]
        with:
          languages: ${{ matrix.language }}
-          build-mode: ${{ matrix.build-mode }}
+          build-mode: ${{ matrix.language == 'go' && 'autobuild' || 'none' }}
      - name: Perform CodeQL Analysis
+        if: matrix.branch == ''
        uses: github/codeql-action/[email protected]
        with:
          category: "/language:${{ matrix.language }}"
+      # Results from a checked-out line are filed under that line's ref, not the
+      # default branch the schedule happened to run from.
+      - name: Perform CodeQL Analysis (${{ matrix.branch }})
+        if: matrix.branch != ''
+        uses: github/codeql-action/[email protected]
+        with:
+          category: "/language:${{ matrix.language }}"
+          ref: refs/heads/${{ matrix.branch }}
+          sha: ${{ steps.head.outputs.sha }}
@@ -2,7 +2,8 @@ name: Label issue version

 # Issue forms can't let a reporter set a label directly (that needs triage rights),
 # so the bug/feature forms carry a "Version line" dropdown and this workflow reads
-# the submitted value and applies the matching v1/v2 label on their behalf.
+# the submitted value and applies the matching label on their behalf:
+# 0.x -> v1 (TypeScript), 1.x -> v2 (main-v2), 2.x -> v3 (studio).
 on:
  issues:
    types: [opened, edited]
@@ -24,40 +25,40 @@ jobs:
            const body = context.payload.issue.body || '';
            const sectionOf = (name) =>
              body.split(/^###\s+/m).find((s) => new RegExp(`^${name}`, 'i').test(s)) || '';
+            const labelOf = (major) => ({ 0: 'v1', 1: 'v2', 2: 'v3' })[major];

-            const m = sectionOf('Version line').match(/\bv([12])\b/i);
+            const m = sectionOf('Version line').match(/\b([012])\.x\b/);
            if (!m) {
              core.info('No version line found; nothing to label.');
              return;
            }
-            let choice = 'v' + m[1];
+            let choice = labelOf(Number(m[1]));

-            // The dropdown is a choice, and v2 sits first, so it gets picked by
-            // reporters who are actually on 0.x. `Exact version` is pasted from
-            // `reasonix --version`, so when it parses it is the better evidence:
-            // 0.x is the TypeScript line, 1.x the Go rewrite. Anything that does
-            // not parse (a commit sha, "main-v2") leaves the dropdown to decide.
+            // The dropdown is a choice, and its first entry gets picked by
+            // reporters who never looked. `Exact version` is pasted from
+            // `reasonix --version` or Studio, so when it parses it is the better
+            // evidence. Anything that does not parse (a commit sha, a branch
+            // name) or names no known line leaves the dropdown to decide.
            const exact = sectionOf('Exact version').match(/\b(\d+)\.(\d+)\.(\d+)/);
-            if (exact) {
-              const fromVersion = Number(exact[1]) === 0 ? 'v1' : 'v2';
-              if (fromVersion !== choice) {
-                core.info(`Version line says ${choice} but ${exact[0]} says ${fromVersion}; trusting the version.`);
-                choice = fromVersion;
-              }
+            const fromVersion = exact && labelOf(Number(exact[1]));
+            if (fromVersion && fromVersion !== choice) {
+              core.info(`Version line says ${choice} but ${exact[0]} says ${fromVersion}; trusting the version.`);
+              choice = fromVersion;
            }
-            const other = choice === 'v2' ? 'v1' : 'v2';
            await github.rest.issues.addLabels({
              ...context.repo,
              issue_number: context.issue.number,
              labels: [choice],
            });
-            // Keep v1/v2 mutually exclusive in case an edit flipped the choice.
-            try {
-              await github.rest.issues.removeLabel({
-                ...context.repo,
-                issue_number: context.issue.number,
-                name: other,
-              });
-            } catch (e) {
-              core.info(`No ${other} label to remove.`);
+            // Keep the line labels mutually exclusive in case an edit flipped the choice.
+            for (const other of ['v1', 'v2', 'v3'].filter((l) => l !== choice)) {
+              try {
+                await github.rest.issues.removeLabel({
+                  ...context.repo,
+                  issue_number: context.issue.number,
+                  name: other,
+                });
+              } catch (e) {
+                core.info(`No ${other} label to remove.`);
+              }
            }
@@ -0,0 +1,29 @@
+name: 1.x nightly monitoring
+
+# A schedule runs only from the default branch. These monitors measure the 1.x
+# desktop app, which lives on main-v2 alone, so their nightly runs are started
+# from here on that branch. Their push and pull_request gates run on main-v2 as
+# before.
+on:
+  schedule:
+    - cron: "17 3 * * *"
+    - cron: "43 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  actions: write
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: App memory screening
+        if: github.event_name == 'workflow_dispatch' || github.event.schedule == '17 3 * * *'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run app-memory.yml --repo "$GITHUB_REPOSITORY" --ref main-v2
+      - name: Diagnostic overhead monitoring
+        if: github.event_name == 'workflow_dispatch' || github.event.schedule == '43 4 * * *'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run diagnostic-overhead.yml --repo "$GITHUB_REPOSITORY" --ref main-v2
@@ -162,16 +162,29 @@ ci: add golangci-lint and govulncheck

 ## Submitting changes

+Reasonix ships on two lines (see the
+[version roadmap](https://github.com/esengine/DeepSeek-Reasonix/discussions/10748)),
+and each takes different changes:
+
+| Line | Branch | Takes |
+| --- | --- | --- |
+| 2.x | `studio` | Features and fixes: active development |
+| 1.x | `main-v2` | Bug fixes, provider/API compatibility, release/updater, security, platform stability |
+
+A fix that matters on both lines lands on `main-v2` and is reviewed for
+porting to `studio`; do not open the same PR against both.
+
 1. Fork the repository
-2. Create a feature branch from `main-v2`
+2. Create a feature branch from the branch your change targets
 3. Make your changes with tests
 4. Ensure `go test ./...` passes
 5. Ensure `gofmt -l .` shows no changes
-6. Submit a pull request to `main-v2`
+6. Submit a pull request to that same branch

 ## Reporting issues

 Open an issue on GitHub with:
+- Which line (1.x or 2.x) and the exact version
 - Steps to reproduce
 - Expected vs actual behavior
 - Go version and OS
@@ -21,6 +21,7 @@
 </p>

 <p align="center">
+  <a href="https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true"><img src="https://img.shields.io/github/v/release/esengine/DeepSeek-Reasonix.svg?filter=studio-v*&include_prereleases&style=flat-square&color=8250df&labelColor=161b22&label=studio%202.x" alt="Reasonix Studio 2.x"/></a>
  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg?style=flat-square&color=cb3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
  <a href="https://github.com/esengine/DeepSeek-Reasonix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/DeepSeek-Reasonix/ci.yml?style=flat-square&label=ci&labelColor=161b22&logo=githubactions&logoColor=white" alt="CI"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg?style=flat-square&color=8b949e&labelColor=161b22" alt="license"/></a>
@@ -54,6 +55,24 @@

 <br/>

+## Versions
+
+Reasonix ships on two lines. See the [version roadmap announcement](https://github.com/esengine/DeepSeek-Reasonix/discussions/10748) for the reasoning behind the split.
+
+| Line | Branch | Status | Get it |
+| --- | --- | --- | --- |
+| **Reasonix 2.x** | `studio` (this branch) | Active development, pre-release | [Studio releases](https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true) |
+| **Reasonix 1.x** | [`main-v2`](https://github.com/esengine/DeepSeek-Reasonix/tree/main-v2) | Maintenance / stable | `npm i -g reasonix` · [desktop download](https://reasonix.io/?download=desktop#start) |
+
+- **Want something stable?** Stay on 1.x. It keeps receiving bug fixes,
+  provider/API compatibility, updater and security fixes; its core architecture
+  is no longer being extended.
+- **Want the new architecture?** Use 2.x Reasonix Studio. It is still moving
+  quickly; reports are welcome.
+
+Valuable fixes, tests and behaviour from 1.x are reviewed one by one and ported
+or reimplemented on 2.x where they fit the new architecture.
+
 ## Features

 - **Config-driven.** Providers, the agent, enabled tools, and plugins are all
@@ -73,53 +92,61 @@

 ## Install

-Choose the path that matches how you want to use Reasonix. The CLI/TUI,
-desktop app, and VS Code extension all use the same local Reasonix engine.
+This branch is **Reasonix 2.x**. Its desktop app is Reasonix Studio; the CLI,
+Studio, and editor integrations all run the same local Reasonix engine.

-### Path A: CLI / TUI
+### Reasonix Studio (2.x)

-Install the native binary through npm on any supported platform, or use
-Homebrew on macOS:
+Download the package for your platform from the latest
+[Studio release](https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true)
+(tagged `studio-v2.*`, published as pre-releases while 2.x is in active
+development):
+
+| Platform | Package | Architecture |
+| --- | --- | --- |
+| macOS | `.dmg` or `.zip` | Apple Silicon (`arm64`) / Intel (`amd64`) |
+| Windows | Installer `-installer.exe` or portable `.zip` | x64 |
+| Linux | `.deb` | x64 |
+
+Every package ships with a `.minisig` signature, and the release carries
+`SHA256SUMS`. Once installed, Studio updates itself in place.
+
+The same release also carries the 2.x `reasonix` CLI as archives for
+`darwin|linux|windows × amd64|arm64`.
+
+### Reasonix 1.x (stable)
+
+The 1.x CLI installs through npm on any supported platform, or Homebrew on
+macOS:

 ```sh
 npm i -g reasonix                  # any OS; pulls the prebuilt native binary
 brew install esengine/reasonix/reasonix   # macOS
 ```

-Prebuilt archives (`darwin|linux|windows × amd64|arm64`) and `SHA256SUMS` are on
-every [GitHub release](https://github.com/esengine/DeepSeek-Reasonix/releases).
+The 1.x desktop app is on the
+[official download page](https://reasonix.io/?download=desktop#start). Windows
+installers are code-signed through [SignPath.io](https://signpath.io/) with a
+free certificate provided by the [SignPath Foundation](https://signpath.org/).

-### Path B: Desktop app
+### VS Code extension

-Use the [official download page](https://reasonix.io/?download=desktop#start)
-for the latest desktop build.
-
-| Platform | Package | Architecture |
-| --- | --- | --- |
-| macOS | Universal `.dmg` or `.zip` | Apple Silicon / Intel |
-| Windows | Installer `.exe` or portable `.zip` | x64 / ARM64 |
-| Linux | `.deb` or `.tar.gz` | x64 |
-
-Windows installers are code-signed through [SignPath.io](https://signpath.io/)
-with a free certificate provided by the [SignPath Foundation](https://signpath.org/).
-
-### Path C: VS Code extension
-
-Complete Path A first. The extension does not bundle the CLI; it starts your
-local `reasonix acp` backend and adds native chat, editor context, tool-call
-approvals, model selection, and workspace sessions.
+The extension does not bundle the CLI; it starts your local `reasonix acp`
+backend and adds native chat, editor context, tool-call approvals, model
+selection, and workspace sessions. Install the 1.x CLI first.

 - **VS Code:** [install from Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SivanLiu.reasonix-agent)
 - **VSCodium / Eclipse Theia:** [install from Open VSX Registry](https://open-vsx.org/extension/SivanLiu/reasonix-agent)
 - **Extension ID:** `SivanLiu.reasonix-agent` · [source and usage guide](https://github.com/SivanCola/reasonix-vscode)

-### Path D: Build from source
+### Build from source

-Clone the repository first:
+Clone the repository; `studio` builds 2.x and `main-v2` builds 1.x:

 ```sh
 git clone https://github.com/esengine/DeepSeek-Reasonix.git
 cd DeepSeek-Reasonix
+git switch studio
 ```

 #### CLI
@@ -146,9 +173,12 @@ webview dependencies and Linux build tags.

 ## Quick start

-### CLI / TUI
+### Reasonix Studio

-These commands are for the CLI/TUI installed through Path A:
+Install and launch Studio, then connect a provider and model in the app. No CLI
+setup is needed.
+
+### CLI / TUI

 ```sh
 reasonix setup                      # configure a provider and model
@@ -159,13 +189,6 @@ reasonix run "implement the TODOs in main.go"
 In an interactive session, run `/init` when you want Reasonix to create project
 instructions.

-### Desktop app
-
-Download the installer for your platform from the
-[official download page](https://reasonix.io/?download=desktop#start), install
-and launch Reasonix, then configure a provider and model in the app. The CLI
-commands above are not required for the desktop app.
-
 For advanced CLI usage and configuration, see the **[CLI reference](./docs/CLI.md)**,
 **[Guide](./docs/GUIDE.md)**, and
 **[configuration paths](./docs/CONFIG_PATHS.md)**.
@@ -21,6 +21,7 @@
 </p>

 <p align="center">
+  <a href="https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true"><img src="https://img.shields.io/github/v/release/esengine/DeepSeek-Reasonix.svg?filter=studio-v*&include_prereleases&style=flat-square&color=8250df&labelColor=161b22&label=studio%202.x" alt="Reasonix Studio 2.x"/></a>
  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg?style=flat-square&color=cb3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
  <a href="https://github.com/esengine/DeepSeek-Reasonix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/DeepSeek-Reasonix/ci.yml?style=flat-square&label=ci&labelColor=161b22&logo=githubactions&logoColor=white" alt="CI"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg?style=flat-square&color=8b949e&labelColor=161b22" alt="license"/></a>
@@ -52,6 +53,21 @@
 > [!IMPORTANT]
 > **加入社区 · Community** — 双语 Discord，提供安装答疑（`#help` / `#求助`）、工作流展示与功能想法。→ **<https://discord.gg/XF78rEME2D>**

+## 版本
+
+Reasonix 分为两条版本线，调整的原因见[版本路线公告](https://github.com/esengine/DeepSeek-Reasonix/discussions/10748)。
+
+| 版本线 | 分支 | 状态 | 获取方式 |
+| --- | --- | --- | --- |
+| **Reasonix 2.x** | `studio`（当前分支） | 活跃开发，预发布 | [Studio 发布页](https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true) |
+| **Reasonix 1.x** | [`main-v2`](https://github.com/esengine/DeepSeek-Reasonix/tree/main-v2) | 维护 / 稳定 | `npm i -g reasonix` · [桌面端下载](https://reasonix.io/?download=desktop#start) |
+
+- **想要稳定**：继续使用 1.x。它会持续收到 Bug 修复、Provider / API 兼容、
+  更新器和安全修复，但不再扩展核心架构。
+- **想体验新架构**：使用 2.x Reasonix Studio。它仍在快速迭代，欢迎反馈问题。
+
+1.x 中有价值的修复、测试和行为会逐项 review，适合新架构的会迁移或重新实现到 2.x。
+
 ## 特性

 - **配置驱动**：provider、agent、启用的工具、插件全部在 `reasonix.toml` 中声明，
@@ -67,57 +83,84 @@

 ## 安装

-选择适合你的使用路径。CLI/TUI、桌面端和 VS Code 扩展都使用同一套本地
-Reasonix 引擎。
+当前分支是 **Reasonix 2.x**，桌面端是 Reasonix Studio；CLI、Studio 和编辑器集成
+都运行同一套本地 Reasonix 引擎。

-### 路径 A：CLI / TUI
+### Reasonix Studio（2.x）

-任意支持的平台都可以通过 npm 安装原生二进制；macOS 也可以使用 Homebrew：
+从最新的 [Studio 发布](https://github.com/esengine/DeepSeek-Reasonix/releases?q=studio-v&expanded=true)
+下载对应平台的安装包（标签为 `studio-v2.*`，2.x 活跃开发期间以预发布形式发布）：
+
+| 平台 | 安装包 | 架构 |
+| --- | --- | --- |
+| macOS | `.dmg` 或 `.zip` | Apple Silicon（`arm64`）/ Intel（`amd64`） |
+| Windows | 安装器 `-installer.exe` 或便携 `.zip` | x64 |
+| Linux | `.deb` | x64 |
+
+每个安装包都附带 `.minisig` 签名，发布页另有 `SHA256SUMS`。安装后 Studio 会在
+应用内自行更新。
+
+同一个发布页也提供 2.x 的 `reasonix` CLI 归档（`darwin|linux|windows × amd64|arm64`）。
+
+### Reasonix 1.x（稳定版）
+
+1.x CLI 在任意支持的平台上都可以通过 npm 安装，macOS 也可以使用 Homebrew：

 ```sh
 npm i -g reasonix                  # 任意系统;自动拉取对应平台的原生二进制
 brew install esengine/reasonix/reasonix   # macOS
 ```

-预编译归档(`darwin|linux|windows × amd64|arm64`)和 `SHA256SUMS` 见每个
-[GitHub release](https://github.com/esengine/DeepSeek-Reasonix/releases)。
-
-### 路径 B：桌面端
-
-前往[官方下载页](https://reasonix.io/?download=desktop#start)获取最新桌面版本。
-
-| 平台 | 安装包 | 架构 |
-| --- | --- | --- |
-| macOS | 通用 `.dmg` 或 `.zip` | Apple Silicon / Intel |
-| Windows | 安装器 `.exe` 或便携 `.zip` | x64 / ARM64 |
-| Linux | `.deb` 或 `.tar.gz` | x64 |
-
+1.x 桌面端请前往[官方下载页](https://reasonix.io/?download=desktop#start)。
 Windows 安装器通过 [SignPath.io](https://signpath.io/) 完成代码签名，证书由
 [SignPath 基金会](https://signpath.org/) 免费提供。

-### 路径 C：VS Code 扩展
+### VS Code 扩展

-请先完成路径 A。扩展不内置 CLI，而是启动本机的 `reasonix acp` 后端，
-并提供原生聊天、编辑器上下文、工具调用审批、模型选择和工作区会话。
+扩展不内置 CLI，而是启动本机的 `reasonix acp` 后端，并提供原生聊天、编辑器
+上下文、工具调用审批、模型选择和工作区会话。请先安装 1.x CLI。

 - **VS Code：** [从 Visual Studio Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=SivanLiu.reasonix-agent)
 - **VSCodium / Eclipse Theia：** [从 Open VSX Registry 安装](https://open-vsx.org/extension/SivanLiu/reasonix-agent)
 - **扩展 ID：** `SivanLiu.reasonix-agent` · [源码与使用说明](https://github.com/SivanCola/reasonix-vscode)

-### 路径 D：从源码构建
+### 从源码构建
+
+克隆仓库；`studio` 构建 2.x，`main-v2` 构建 1.x：

 ```sh
 git clone https://github.com/esengine/DeepSeek-Reasonix.git
 cd DeepSeek-Reasonix
+git switch studio
+```
+
+#### CLI
+
+CLI 构建需要 **Go 1.25+**。模块固定了 `toolchain`，保持 `GOTOOLCHAIN=auto`
+即可让 Go 自动下载对应工具链，也可以手动安装。
+
+```sh
 make build      # -> bin/reasonix(.exe)
 make cross      # -> dist/（darwin|linux|windows × amd64|arm64）
 ```

+#### Studio
+
+Studio 的前端还需要 **Node 24+ 与 pnpm 10**（`npm install -g pnpm@10`）。
+
+```sh
+make studio
+```
+
+各平台的 webview 依赖和 Linux 构建标签见 [Studio 构建指南](desktop/README.md#prerequisites)。
+
 ## 快速开始

-### CLI / TUI
+### Reasonix Studio

-以下命令仅适用于通过路径 A 安装的 CLI/TUI：
+安装并启动 Studio，然后在应用内连接 provider 和模型即可使用，无需配置 CLI。
+
+### CLI / TUI

 ```sh
 reasonix setup                      # 配置 provider 和模型
@@ -127,12 +170,6 @@ reasonix run "把 main.go 里的 TODO 实现掉"

 需要项目指令时，可在交互式会话中运行 `/init`。

-### 桌面端
-
-从[官方下载页](https://reasonix.io/?download=desktop#start)下载对应系统的安装包，
-安装并启动 Reasonix，然后在应用内配置 provider 和模型即可使用。桌面端无需执行
-上面的 CLI 命令。
-
 CLI 进阶用法和详细配置见 **[CLI 命令参考](./docs/CLI.zh-CN.md)**、
 **[指南](./docs/GUIDE.zh-CN.md)** 和
 **[配置路径](./docs/CONFIG_PATHS.md)**。