Merge pull request #423 from pionxe/release/v2.0-split-build

feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收）

Author: phantom5099

.github/workflows/ci.yml

@@ -37,9 +37,92 @@ jobs:
       - name: Build
         run: go build ./...
 
+      - name: Gateway-only smoke
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          socket_path="/tmp/neocode-gateway-${RANDOM}.sock"
+          http_port="$((18080 + RANDOM % 1000))"
+          http_addr="127.0.0.1:${http_port}"
+          gateway_bin="/tmp/neocode-gateway"
+          gateway_log="/tmp/neocode-gateway.log"
+
+          go build -o "${gateway_bin}" ./cmd/neocode-gateway
+          "${gateway_bin}" --listen "${socket_path}" --http-listen "${http_addr}" --log-level info >"${gateway_log}" 2>&1 &
+          gateway_pid=$!
+
+          cleanup() {
+            if kill -0 "${gateway_pid}" >/dev/null 2>&1; then
+              kill "${gateway_pid}" || true
+              wait "${gateway_pid}" || true
+            fi
+            rm -f "${socket_path}" "${gateway_bin}" /tmp/gateway-healthz.json /tmp/gateway-rpc.json
+          }
+          trap cleanup EXIT
+
+          for _ in $(seq 1 60); do
+            if curl -fsS "http://${http_addr}/healthz" > /tmp/gateway-healthz.json; then
+              break
+            fi
+            sleep 0.2
+          done
+          test -s /tmp/gateway-healthz.json
+
+          rpc_status="$(curl -sS -o /tmp/gateway-rpc.json -w "%{http_code}" \
+            -X POST "http://${http_addr}/rpc" \
+            -H "Content-Type: application/json" \
+            -d '{"jsonrpc":"2.0","id":"smoke-1","method":"gateway.ping","params":{}}')"
+          if [[ "${rpc_status}" != "401" ]]; then
+            echo "unexpected /rpc status: ${rpc_status}" >&2
+            cat /tmp/gateway-rpc.json >&2
+            cat "${gateway_log}" >&2 || true
+            exit 1
+          fi
+          grep -q '"gateway_code":"unauthorized"' /tmp/gateway-rpc.json
+
       - name: Test with coverage
         run: go test ./... -covermode=atomic -coverprofile=coverage.out
 
+      - name: Install script dry-run regression (bash)
+        shell: bash
+        env:
+          NEOCODE_INSTALL_LATEST_TAG: v0.0.0-test
+        run: |
+          set -euo pipefail
+
+          full_output="$(bash ./scripts/install.sh --flavor full --dry-run)"
+          gateway_output="$(bash ./scripts/install.sh --flavor gateway --dry-run)"
+
+          echo "${full_output}" | grep -Eq '^asset=neocode_(Linux|Darwin)_(x86_64|arm64)\.tar\.gz$'
+          echo "${gateway_output}" | grep -Eq '^asset=neocode-gateway_(Linux|Darwin)_(x86_64|arm64)\.tar\.gz$'
+          echo "${full_output}" | grep -Eq '^download_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/neocode_(Linux|Darwin)_(x86_64|arm64)\.tar\.gz$'
+          echo "${gateway_output}" | grep -Eq '^download_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/neocode-gateway_(Linux|Darwin)_(x86_64|arm64)\.tar\.gz$'
+          echo "${full_output}" | grep -Eq '^checksum_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/checksums\.txt$'
+          echo "${gateway_output}" | grep -Eq '^checksum_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/checksums\.txt$'
+
+      - name: Install script dry-run regression (PowerShell)
+        shell: pwsh
+        env:
+          NEOCODE_INSTALL_LATEST_TAG: v0.0.0-test
+        run: |
+          $fullLines = & ./scripts/install.ps1 -Flavor full -DryRun
+          $gatewayLines = & ./scripts/install.ps1 -Flavor gateway -DryRun
+
+          $fullAsset = ($fullLines | Where-Object { $_ -like 'asset=*' } | Select-Object -First 1)
+          $gatewayAsset = ($gatewayLines | Where-Object { $_ -like 'asset=*' } | Select-Object -First 1)
+          $fullDownload = ($fullLines | Where-Object { $_ -like 'download_url=*' } | Select-Object -First 1)
+          $gatewayDownload = ($gatewayLines | Where-Object { $_ -like 'download_url=*' } | Select-Object -First 1)
+          $fullChecksum = ($fullLines | Where-Object { $_ -like 'checksum_url=*' } | Select-Object -First 1)
+          $gatewayChecksum = ($gatewayLines | Where-Object { $_ -like 'checksum_url=*' } | Select-Object -First 1)
+
+          if ($fullAsset -notmatch '^asset=neocode_Windows_(x86_64|arm64)\.zip$') { throw "Unexpected full asset line: $fullAsset" }
+          if ($gatewayAsset -notmatch '^asset=neocode-gateway_Windows_(x86_64|arm64)\.zip$') { throw "Unexpected gateway asset line: $gatewayAsset" }
+          if ($fullDownload -notmatch '^download_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/neocode_Windows_(x86_64|arm64)\.zip$') { throw "Unexpected full download URL: $fullDownload" }
+          if ($gatewayDownload -notmatch '^download_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/neocode-gateway_Windows_(x86_64|arm64)\.zip$') { throw "Unexpected gateway download URL: $gatewayDownload" }
+          if ($fullChecksum -notmatch '^checksum_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/checksums\.txt$') { throw "Unexpected full checksum URL: $fullChecksum" }
+          if ($gatewayChecksum -notmatch '^checksum_url=https://github.com/1024XEngineer/neo-code/releases/download/.+/checksums\.txt$') { throw "Unexpected gateway checksum URL: $gatewayChecksum" }
+
       - name: Upload coverage to Codecov
         continue-on-error: true
         uses: codecov/codecov-action@v5

.goreleaser.yaml

@@ -1,16 +1,15 @@
-# .goreleaser.yaml
 project_name: neocode
-version: 2 # 必须声明为 v2 语法
+version: 2
 
 before:
   hooks:
-    # 每次构建前清理模块并下载依赖
     - go mod tidy
     - go mod download
 
 builds:
-  - env:
-      - CGO_ENABLED=0 # 禁用 CGO，确保生成纯静态链接的二进制文件
+  - id: neocode
+    env:
+      - CGO_ENABLED=0
     ldflags:
       - -s -w -X 'neo-code/internal/version.Version={{.Version}}'
     goos:
@@ -20,27 +19,57 @@ builds:
     goarch:
       - amd64
       - arm64
-    # 指定 main.go 的路径（根据 NeoCode 的实际目录调整）
-    main: ./cmd/neocode/main.go 
-    # 编译出的二进制文件名
+    main: ./cmd/neocode/main.go
     binary: neocode
 
+  - id: neocode-gateway
+    env:
+      - CGO_ENABLED=0
+    ldflags:
+      - -s -w -X 'neo-code/internal/version.Version={{.Version}}'
+    goos:
+      - linux
+      - windows
+      - darwin
+    goarch:
+      - amd64
+      - arm64
+    main: ./cmd/neocode-gateway/main.go
+    binary: neocode-gateway
+
 archives:
-  - format: tar.gz
-    # 为 Windows 提供单独的 zip 格式
+  - id: neocode
+    ids:
+      - neocode
+    format: tar.gz
+    format_overrides:
+      - goos: windows
+        format: zip
+    name_template: >-
+      neocode_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+
+  - id: neocode-gateway
+    ids:
+      - neocode-gateway
+    format: tar.gz
     format_overrides:
       - goos: windows
         format: zip
     name_template: >-
-      {{ .ProjectName }}_
+      neocode-gateway_
       {{- title .Os }}_
       {{- if eq .Arch "amd64" }}x86_64
       {{- else if eq .Arch "386" }}i386
       {{- else }}{{ .Arch }}{{ end }}
       {{- if .Arm }}v{{ .Arm }}{{ end }}
 
 checksum:
-  name_template: 'checksums.txt'
+  name_template: checksums.txt
 
 changelog:
   sort: asc

Makefile

@@ -1,11 +1,14 @@
 .PHONY: install-skills docs-gateway docs-gateway-check
 
+GATEWAY_DOCS_GENERATOR := go run -tags gatewaydocgen ./scripts/generate_gateway_rpc_examples.go
+
 install-skills:
 	@./scripts/install_skills.sh
 
 docs-gateway:
-	@go run ./scripts/generate_gateway_rpc_examples
+	@$(GATEWAY_DOCS_GENERATOR)
 
 docs-gateway-check:
-	@go run ./scripts/generate_gateway_rpc_examples
-	@git diff --exit-code -- docs/reference/gateway-rpc-api.md
+	@$(GATEWAY_DOCS_GENERATOR)
+	@go run ./scripts/check_gateway_docs
+	@git diff --exit-code -- docs/generated/gateway-rpc-examples.json

README.md

@@ -274,6 +274,20 @@ Skill 内部调用脚本 `scripts/create_issue.sh` 创建 issue。你也可以
 - `wake.openUrl`：处理 `neocode://` 唤醒请求
 - `gateway.event`：网关推送通知事件（notification）
 
+## 双产物与启动兼容（RFC#420）
+
+- 发布产物：
+  - `neocode`（完整客户端，含 `gateway` 子命令）
+  - `neocode-gateway`（Gateway-Only 入口）
+- `url-dispatch` 网关不可达时的拉起优先级固定为：
+  - `NEOCODE_GATEWAY_BIN`
+  - `PATH` 中 `neocode-gateway`
+  - `neocode gateway`
+- 第三方接入与协议文档见：
+  - [`docs/guides/gateway-integration-guide.md`](docs/guides/gateway-integration-guide.md)
+  - [`docs/gateway-rpc-api.md`](docs/gateway-rpc-api.md)
+  - [`docs/gateway-error-catalog.md`](docs/gateway-error-catalog.md)
+
 ## License
 
 MIT

cmd/neocode-gateway/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"neo-code/internal/cli"
+)
+
+func main() {
+	if err := cli.ExecuteGatewayServer(context.Background(), os.Args[1:]); err != nil {
+		fmt.Fprintf(os.Stderr, "neocode-gateway: %v\n", err)
+		os.Exit(1)
+	}
+}

cmd/neocode-gateway/main_test.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+func TestMainHelpPathDoesNotExit(t *testing.T) {
+	originalArgs := os.Args
+	defer func() {
+		os.Args = originalArgs
+	}()
+
+	os.Args = []string{"neocode-gateway", "--help"}
+	main()
+}
+
+func TestMainReturnsExitCodeOneOnCommandError(t *testing.T) {
+	if os.Getenv("NEOCODE_GATEWAY_MAIN_HELPER") == "1" {
+		os.Args = []string{"neocode-gateway", "--log-level", "trace"}
+		main()
+		return
+	}
+
+	command := exec.Command(os.Args[0], "-test.run=TestMainReturnsExitCodeOneOnCommandError")
+	command.Env = append(os.Environ(), "NEOCODE_GATEWAY_MAIN_HELPER=1")
+	var stderr bytes.Buffer
+	command.Stderr = &stderr
+
+	err := command.Run()
+	if err == nil {
+		t.Fatal("expected subprocess to exit with non-zero status")
+	}
+	var exitErr *exec.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("error type = %T, want *exec.ExitError", err)
+	}
+	if exitErr.ExitCode() != 1 {
+		t.Fatalf("exit code = %d, want %d", exitErr.ExitCode(), 1)
+	}
+	if !strings.Contains(stderr.String(), "neocode-gateway:") {
+		t.Fatalf("stderr = %q, want contains %q", stderr.String(), "neocode-gateway:")
+	}
+}

docs/gateway-compatibility.md

@@ -0,0 +1,53 @@
+# Gateway 兼容性与弃用策略
+
+本文定义 Gateway 对外契约的版本兼容规则，适用于方法、字段、错误码与发布资产。
+
+## 1. 兼容性分层
+
+1. Stable（稳定层）：默认向后兼容，不做破坏性改动。
+2. Experimental（实验层）：允许演进，但必须有显式标注与迁移说明。
+
+当前分层：
+
+1. Stable Core：`gateway.authenticate`、`gateway.ping`、`gateway.bindStream`、`gateway.run`、`gateway.compact`、`gateway.cancel`、`gateway.listSessions`、`gateway.loadSession`、`gateway.resolvePermission`、`gateway.event`
+2. Experimental：`wake.openUrl`
+
+## 2. 字段弃用生命周期（必须遵守）
+
+### 2.1 标准流程
+
+1. **v1.2 标记 Deprecated**  
+   字段继续可用；文档、日志、响应元信息中标记 `deprecated: true`（或等效说明）。
+2. **v1.3 兼容保留期**  
+   新客户端 SHOULD 停止依赖该字段；服务端保持兼容读取/写出策略。
+3. **v1.4 正式移除**  
+   字段从请求/响应契约中删除；若客户端仍发送，返回可诊断错误（通常 `invalid_frame` 或 `unsupported_action`，视场景而定）。
+
+### 2.2 示例
+
+若字段 `params.legacy_x` 计划移除：
+
+1. v1.2：文档标记 Deprecated，并在 release notes 给迁移路径。
+2. v1.3：继续接受 `legacy_x`，但服务端优先使用新字段。
+3. v1.4：拒绝 `legacy_x`，返回明确错误与替代字段提示。
+
+## 3. 破坏性变更门禁
+
+以下变更 MUST 走 RFC 流程并通过灰度窗口：
+
+1. 删除 Stable 方法。
+2. 修改 Stable 方法必填字段语义。
+3. 修改稳定 `gateway_code` 含义。
+4. 改变资产命名规则（下载 URL / checksum 路径）。
+
+## 4. 双产物发布兼容承诺
+
+1. `neocode`：保留现有主入口行为。
+2. `neocode-gateway`：仅承载网关服务语义。
+3. 同参条件下，`neocode gateway` 与 `neocode-gateway` MUST 行为等价（参数归一化、错误语义、关键日志字段）。
+
+## 5. 回滚原则
+
+1. 升级失败时 SHOULD 先回滚二进制版本，再恢复配置。
+2. 回滚版本 MUST 与当前稳定协议兼容（至少同主版本）。
+3. 回滚步骤必须在发布说明中提供可执行命令与验证点（`/healthz`、`/rpc` 最小请求）。