# 新设备开发与验证

先看根目录 [HANDOFF.md](../HANDOFF.md)。以下命令在仓库根目录执行，不依赖原开发者的磁盘路径。
这里只构建/测试新执行器，不调用旧部署脚本，不连接服务器，不安装 Docker。

## 环境前提

- Git 和 SSH 客户端：克隆工作分支并访问仓库。服务器 SSH 权限与仓库权限是两件事。
- Go：`go.mod` 要求 1.26.0 或更新版本；本次基线实际使用 Go 1.27.1。
- Node.js：仅用于无第三方依赖的 CLI 冒烟测试；本次 Windows 基线为 v24.19.0。
  尚无面板 package.json，不需要 `npm install`。
- Windows：PowerShell；Linux：Bash。Linux 专有行为使用 Ubuntu/WSL 验证。
- Linux `go test -race` 需要可用的 C 编译器/CGO；检查 `go env CGO_ENABLED` 和 `cc --version`。
- 在线仓库测试另外需要 curl、GnuPG 的 `/usr/bin/gpg` 与 `/usr/bin/gpgv`、Python 3、awk、tar 和常规核心工具。

从组织认可的软件渠道或 [Go 官方下载](https://go.dev/dl/) / [Node 官方下载](https://nodejs.org/en/download)
获取工具链；核对下载摘要。不要复制旧机器临时目录里的未知二进制。
上述版本是实测基线，不表示所有更新版本已验收。macOS 便携产品尚未验证；完整 Linux 专有测试需 Linux。

## Windows：基础离线检查

确认 `go` 和 `node` 已在 PATH。新设备无需沿用原设备的 GOCACHE、临时 Go 目录或磁盘盘符。

```powershell
go version
node --version
go test ./... -count=1
if ($LASTEXITCODE -ne 0) { throw 'Go tests failed' }
go vet ./...
if ($LASTEXITCODE -ne 0) { throw 'Go vet failed' }
go build -o dist/deployctl.exe ./cmd/deployctl
if ($LASTEXITCODE -ne 0) { throw 'Build failed' }
node --test tests/cli-smoke.test.mjs
if ($LASTEXITCODE -ne 0) { throw 'CLI smoke tests failed' }
./dist/deployctl.exe version
Get-Content -Raw protocol/examples/plan-request.json | ./dist/deployctl.exe plan
```

Windows 可能因权限限制跳过符号链接测试；Linux 必须补验。仓库 `.gitattributes` 已将 Shell 脚本固定为 LF，
不要把脚本转为 CRLF。Git 换行提示不等于测试失败；实际错误须单独排查。

## Linux/WSL：基础离线检查

```bash
set -euo pipefail
go version
node --version
go test ./... -count=1
go vet ./...
go test -race ./... -count=1
go build -o dist/deployctl ./cmd/deployctl
node --test tests/cli-smoke.test.mjs
./dist/deployctl version
./dist/deployctl plan < protocol/examples/plan-request.json
./dist/deployctl preflight
```

`preflight` 报告运行它的本机/WSL，不是云服务器。它可以报告“不支持/有阻塞项”，不代表测试失败，
也不得为消除阻塞项擅自修改机器。WSL 临时目录可能随实例生命周期消失，不能作为跨会话依赖。

另有 `bash scripts/verify-linux.sh /绝对路径/已验证的Go.linux-amd64.tar.gz`：
会解包到新建临时目录、使用独立缓存执行 Go 全量测试/vet/race/构建及 CLI 只读检查。
它不下载 Go，不自动校验调用者提供的 Go 压缩包，不运行 Node 冒烟；调用前验证官方压缩包摘要，
Node 冒烟按上面命令另跑。该脚本按 amd64 测试流程提供，其他架构没有同等实测证据。

## 可选在线测试：不要默认运行

先完成离线检查。以下测试只在本地下载公开测试资料，不使用 SSH、不运行 APT、不解包或安装 deb。
需访问 Docker 官方仓库；网络、上游签名/密钥或元数据有效期变化都可能使测试失败，不能绕过校验。

```bash
set -euo pipefail
go build -o dist/deployctl ./cmd/deployctl
# 只验证官方仓库签名、索引及篡改拒绝
bash scripts/probe-docker-repository.sh "$PWD/dist/deployctl"
# 另外下载约 90 MB（随测试版本变化）的五个 deb，验证并故意损坏其中一个
DEPLOYCTL_ONLINE_ARTIFACT_PROBE=1 bash scripts/probe-docker-repository.sh "$PWD/dist/deployctl"
```

需要连同 Go 全量 Linux 检查及真实签名单元测试一起运行时：

```bash
DEPLOYCTL_ONLINE_REPOSITORY_PROBE=1 DEPLOYCTL_ONLINE_ARTIFACT_PROBE=1 \
  bash scripts/verify-linux.sh /绝对路径/已验证的Go.linux-amd64.tar.gz
```

命令末尾的临时目录仅用于该次诊断。负向测试会故意篡改资料，不能当成安装输入或备份。
日志中出现预期的 `artifact verification failed` / `repository verification failed` 后，
应跟随篡改已拒绝的提示且整个脚本退出码为 0；不能只看一条成功输出。
未提供真实元数据夹具时，`TestStagedSignatureIntegration` 会跳过，这是明确的在线覆盖缺口，
不是已完成在线验收。

## 接续纪律

- 当前没有可运行的面板/便携包；开发依赖与未来用户免安装的产品依赖不要混淆。
- 先失败测试、再实现；用真实 CLI 和隔离 Linux 环境覆盖涉及的边界。
- 未通过验证、不支持或未检查的能力须保持不可执行；不要临时开放 `apply` 以便演示。
- 每次交接更新 HANDOFF 和实施状态，记录运行环境、命令、结果、跳过项及待确认事项。
- `dist/`、下载包、缓存、日志、SSH 密钥与真实配置不纳入源码提交。