@vibeinging/dsh-red-alert

Readme

# DSH Red Alert

[简体中文](README.md) | [English](README.en.md)

运行在真实红警 2 引擎上的 AI 战场沙盘。让 DeepSeek 在战争迷雾下建基地、侦察、调兵、交战、失败、复盘，再把有证据的经验带入下一局。

这不是截图识别，不是 Canvas 战术图，也不是藏在后台的 headless 模拟。中间是 DSH 原生 Chat，模型的判断、工具调用和战报持续可见；右边是同一浏览器实例、同一座战场、同一个 AI 席位正在运行的真实红警 2 兼容客户端。用户随时可以在 Chat 里插入命令，改变下一步指挥。

如果你想看 Agent 不只“回答问题”，而是在真实规则、战争迷雾和失败代价下持续行动，这可能是 DSH 里最直观、最好玩的 AI 战场沙盘。

![DeepSeek 在 DSH Chat 中指挥右侧真实红警 2 战场](https://raw.githubusercontent.com/vibeinging/dsh-red-alert/main/docs/readme-media/real-ai-battlefield.webp)

上图是完整 DSH 页面：左侧 session，中间模型判断，右侧真实游戏画面。截图来自使用者自行提供本地 RA2 资源的实战；仓库不包含游戏素材。

## 它为什么好玩

- 看得到思考：模型每轮的态势判断、生产计划、批量命令和工具回执都留在 Chat。
- 能直接干预：输入“先守住第一波”“保持两个矿车”或“暂停扩张，出三辆坦克”，用户命令会进入后续指挥上下文。
- 输赢都是真的：经济、电力、建造队列、寻路、交火、战争迷雾和结算都来自右侧真实客户端。
- 不是一次一条慢慢点：一个工具调用可以批量下达多单位命令，精确回执同时带回最新战场摘要，减少重复观察。
- 微操真的是模型在做：插件不会在后台替模型选目标、撤退或发动进攻；模型从 Chat 中可见的公平快照亲自拆分编队，并在一个批次中同时下达集火、拉扯、侦察和推进命令。
- 会把失败变成规则：自然终局后生成结构化 episode，模型采用或拒绝候选经验；下一局按地图、阵营和对手取回短策略。
- 公平但不迟钝：模型只看本方、当前视野敌人和冻结的最后发现记录，不读隐藏敌军，却可以比人更稳定地检查队列和并行安排动作。

![模型在 Chat 中持续判断，右侧战场同步执行](https://raw.githubusercontent.com/vibeinging/dsh-red-alert/main/docs/readme-media/live-command.webp)

## 一分钟开始

需要 Node.js 22.19 以上、pnpm 和 Git。本插件只适配当前最新版 `@deepseek-ai/dsh@0.1.1-rc.2`，不兼容旧版 DSH。NPM consumer 已用 pnpm 8.15.3 完整实测；仓库源码开发仍由 `packageManager` 锁定 pnpm 11.7.0。首次准备兼容客户端时，setup 会通过 `pnpm dlx` 使用精确锁定的 Bun，不要求全局安装 Bun。

```sh
mkdir dsh-red-alert-play
cd dsh-red-alert-play
pnpm init
pnpm add @vibeinging/dsh-red-alert@0.1.3 @deepseek-ai/dsh@0.1.1-rc.2
pnpm exec dsh-red-alert-setup --profile web --download-resources
pnpm exec dsh-red-alert
```

`dsh-red-alert-setup` 会检查环境、准备锁定的兼容客户端、把已发布插件挂载到 DSH Web Profile，并验证最终配置。`--download-resources` 表示你明确授权 setup 从下方写明的固定地址下载资源；命令会校验固定大小和 SHA-256，再保存到 `$DSH_HOME/red-alert/renderer-v5/dist`。第一次打开兼容客户端时，它会静音启动并自动导入这份已经验证的本地归档，正在等待的建局会继续执行，不需要处理音频授权弹窗、找文件选择器、返回 Chat 告诉模型或重新建局。首次导入、解压和客户端启动可能持续数分钟，所以首次建局单独等待最多 10 分钟；普通战术命令仍是 120 秒。等待期间不要重复提交建局。以后只需运行 `pnpm exec dsh-red-alert`。启动器始终强制使用 `--no-open`，只在终端打印 DSH 地址，绝不会自动新建浏览器标签；请手动打开或复用同一个 DSH 标签页。

公开 NPM 包和 GitHub 仓库都不包含游戏美术、声音或地图素材。setup 的下载动作只在命令明确带有 `--download-resources` 时发生；你仍需自行确认有权获取和使用这份第三方资源。

## DSH 已经启动，怎么玩

DSH 的 Profile 插件和红警 renderer 环境在进程启动时加载，不能热插入当前已经运行的进程。你的 Profile、会话、设置和 `$DSH_HOME/.env` 都会保留；只需要按当前状态处理一次：

| 当前状态 | 操作 |
| --- | --- |
| 还没有运行过 `dsh-red-alert-setup` | 停止当前 DSH，在安装本包的目录运行 setup，再用红警启动器启动 |
| 已经 setup，但当前是用 `dsh web` 或 `dsh --profile web` 启动 | 停止一次，然后改用 `pnpm exec dsh-red-alert` 启动 |
| 当前就是用 `pnpm exec dsh-red-alert` 启动 | 不需要重启，直接打开它输出的 DSH 地址并新建 Chat |

最常见的接入方式是：

```sh
# 先在原终端按 Ctrl+C 停止当前 DSH
cd dsh-red-alert-play
pnpm add @vibeinging/dsh-red-alert@0.1.3 @deepseek-ai/dsh@0.1.1-rc.2
pnpm exec dsh-red-alert-setup --profile web --download-resources
pnpm exec dsh-red-alert
```

如果旧版启动时报“需要设置 `RA_ASSETS_DIR`”，不要创建或填写这个内部变量。它是 0.1.1 在没有红警启动环境时给出的错误提示，不代表缺少用户游戏素材。执行上面的升级和 setup 命令即可；0.1.2 及后续版本会直接说明需要停止 DSH、运行 setup，再改用红警启动器。

如果你平时使用的不是 `web` Profile，把 setup 命令里的 `web` 换成真实名称。后续仍然运行 `pnpm exec dsh-red-alert`；启动器会自动读取 setup 保存的 Profile、renderer 和端口，不需要复制 API Key，也不会创建第二套 DSH。

页面打开后，在 Chat 输入：

```text
创建一局苏军对普通 AI，速度 2。开局前读取苏军建筑和开局战场手册，自动打完，并在终局后根据证据复盘。
```

如果 setup 已带 `--download-resources` 并通过完整性校验，第一次建局会自动导入资源并继续；不再要求用户寻找弹出的窗口、手动选文件、回到 Chat 报告完成或让模型重试。首次加载可能持续数分钟，在右栏出现真实战场或明确错误前不要重复提交。之后可以在中间看到模型判断和工具回执，在右侧观看同一局真实战场；也可以随时输入“先守住”“补两个矿车”或“集中进攻”等命令，插入下一轮指挥。

对局运行时可以在右侧游戏画面按住鼠标左键拖动镜头、点击或拖动小地图定位，也可以使用方向键和滚轮。嵌入 DSH 后这些输入只改变观战镜头，不会选兵、生产或替模型下达战斗命令；真正的游戏命令仍来自 Chat 中可审计的模型工具调用。

如果右栏在正在创建或运行的对局中显示 `live Connection` 错误，不要重复运行启动命令，也不要继续打开新页面。确认终端已经输出同一个 DSH 地址后，只刷新当前 DSH 标签页，再点击一次“重试连接本地 renderer”。如果右栏显示“上一局已经结束”，不要重连旧终局；直接在当前 Chat 输入“复盘后继续下一局”。模型会使用复盘返回的策略、创建新的 `matchId`，页面也会切到全新的真实游戏画面。只有首次建局等待满 10 分钟后仍显示 `browser command receipt timed out`，才新建 Chat 重试。

### 从源码安装

```sh
git clone https://github.com/vibeinging/dsh-red-alert.git
cd dsh-red-alert
pnpm run setup -- --profile web --download-resources
pnpm run dsh
```

源码模式会额外安装依赖并构建插件；NPM 模式直接使用包内已经发布的 Host、浏览器和类型产物，不会尝试在 `node_modules` 中重新构建。

### 资源下载地址与本地备用

自动准备使用的公开候选地址是 [`https://download.ra2web.com/full-pack.7z`](https://download.ra2web.com/full-pack.7z)：

- 固定大小：`140316786` 字节
- 固定 SHA-256：`3119b300794839ab597df556df8718c0a0a28fe89648ddced1c3790d801cb646`
- 本地保存：`$DSH_HOME/red-alert/renderer-v5/dist/dsh-red-alert-resource.7z`

这个地址由 RA2WEB 提供，方便自动准备，不代表 EA 或其他权利方授权任意复制或分发。setup 会在下载前打印相同的来源、大小、摘要和权利提示；只有你明确运行带 `--download-resources` 的命令才会下载。NPM 包、GitHub 仓库和兼容客户端源码都不携带这份归档。

如果不希望使用该地址，去掉 `--download-resources`。右侧战场仍会显示本地归档入口；选择你自己有权使用的归档即可。已验证的最小归档只需要：

- `RA2.MIX`
- `LANGUAGE.MIX`
- `MULTI.MIX`

音乐、Taunts、电影、`exe` 和 `dll` 不需要进入最小归档。浏览器会把导入结果保存在稳定的 renderer 源空间，后续启动可直接复用。自动下载的原始归档留在本机 `$DSH_HOME`；本地选择的归档不会被复制进 NPM 包、GitHub 仓库或 DSH 源码目录。

自动归档存在且摘要正确时，兼容客户端只会自动接受 renderer 自己的固定同源路径；第三方 URL、其他端口、查询参数和散列都不能触发自动导入。如果本地归档不存在或首次导入失败，自动路径只尝试一次，随后回到可见的本地文件入口。安装器保存的稳定本地端口保证后续启动复用同一个浏览器资源空间。若该端口被别的程序占用，请重新运行 setup，或用 `--renderer-port <空闲端口>` 明确选择。

源码更新后重新运行同一条准备命令即可复核构建和挂载：

```sh
git pull --ff-only
pnpm run setup -- --profile web --download-resources
```

## 直接这样指挥

在 DSH Chat 中使用自然语言即可，例如：

```text
创建一局苏军对普通 AI，速度 2。开局前读取苏军建筑和开局战场手册，自动打完并复盘。

先守住第一波，保持两个矿车，再转三辆犀牛坦克。

敌人进视野后集中攻击威胁最高的目标，不要追进战争迷雾。

每个战术周期都由你亲自微操：用最新快照里的精确单位 ID，一次批量完成残血撤退、当前可见目标集火和主力推进，不要启动任何后台规则指挥器。

失败后总结本局，只采用有明确证据的规则，并带到下一局。
```

模型会先按需加载开局或学习工具，再随着阶段进入观察、生产、建设和战斗工具。未加载的工具 schema 不进入模型上下文。

## 赛后不是一句“下次努力”

![真实结算页与模型复盘、规则采纳同屏](https://raw.githubusercontent.com/vibeinging/dsh-red-alert/main/docs/readme-media/post-match-learning.webp)

自动学习不训练或修改模型权重，也不保存自由文本提示。插件只从公平战场数据和已经准入的命令结果中计算封闭候选规则，记录证据，再由模型选择采用或拒绝。后续对局只取回少量、匹配当前地图和阵营的规则，避免经验无限堆进上下文。

速度 2 的三局连续实战已经证明经验能跨局保存并被下一局读取；该样本中前两局失败，第三局在 tick 24090 时仍存活并完成更完整的防御与装甲生产。它证明学习链路在工作，不证明当前策略已经达到稳定胜率。完整过程见[自动增强与连续对战报告](docs/reports/2026-08-23_auto-learning-speed2-and-command-cycle.md)。

## 内置战场手册，不再瞎猜代号

`strategy/learning` 组新增 `red_alert_field_manual`。模型可以在开局前只读取一个需要的主题：建筑、步兵、载具与空军、开局或交战；还可以按苏军、盟军或通用内容过滤。建筑和单位的代号、价格、前置条件来自 Red Alert 2 `rules.ini`，开局和交战规则来自公开战术资料与本插件的公平对局复盘。

手册明确区分 `NAWEAP/GAWEAP` 陆军战车工厂和 `NAYARD/GAYARD` 船厂，并给出基础兵种用途、三辆核心坦克、首轮反步兵防御、编队掩护、当前视野侦察与 last-seen 使用边界。每次查询的完整页面都会写入 session 日志；它只提供公开静态知识，不会带入敌方隐藏位置、经济或单位。

## 真实战场，不作弊

Chat、工具、bridge、引擎和画面持续绑定同一个 `sessionId`、`matchId`、AI seat 和 tick。

模型可见敌情只有三类：

- `visibleEnemies`：当前真实视野内的敌人。
- `lastSeenEnemies`：敌人离开视野前最后一次合法观察；位置、生命值和 `observedAtTick` 在隐藏期间冻结。
- `visibleNeutralObjects`：当前真实视野内的中立对象。

模型不能访问敌方隐藏出生点、敌方经济、全图对象、debug state、观察者视角、Canvas 像素或未过滤的引擎对象。renderer 和模型 bridge 共用当前 LOS 规则；建筑放置也只在当前视野内搜索合法地基。

## 一套游戏能力，按阶段加载

引擎的 85 个公开声明全部进入 `METHOD_POLICY`。允许能力和插件自有学习能力由 22 个精确 manifest 项覆盖；危险方法保持不可见。初始只注册两个 bootstrap 工具：

| 组 | 主要能力 |
| --- | --- |
| `bootstrap/capability` | 发现能力、加载精确工具组 |
| `strategy/learning` | 按需战场手册、读取短策略、复盘和采用候选规则 |
| `lobby/setup` | 选地图、配置玩家、创建并开始对局 |
| `observation` | 公平观察、状态、地图、资源和规则 |
| `units/combat` | 单位移动、攻击、部署和批量命令 |
| `production/economy` | 目录、队列、生产、暂停和取消 |
| `construction` | 建筑目录、合法放置、维修和出售 |
| `diplomacy/comms` | 外交和通讯 |
| `superweapon` | 超级武器 |
| `lifecycle/replay` | 停止和结束对局 |

每个真实 renderer 精确工具都会返回 `commandView`：当前 tick、经济、电力、己方单位、当前可见敌人和冻结 last-seen。模型能基于同一回执继续下令，不必每个动作前再读取一次全量状态。

`red_alert_unit_order` 是执行器，不是 AI。目标、编队、撤退和进攻方向全部由真实模型选择；插件只校验最新己方 ID、当前可见攻击目标和同局身份，然后严格按模型给出的 `orders[]` 顺序执行。一次调用可以包含多条独立命令，因此模型可以在同一战术周期让残血坦克撤退、另一组集火、主力继续推进。

`red_alert_start.gameSpeed` 可选 0 到 6。插件默认速度 2，即原始 15 tick/s；速度同时作用于双方和画面，不改变模型权限。Profile 可以通过 `defaultGameSpeed` 调整。

## 安装器做什么，不做什么

```text
pnpm exec dsh-red-alert-setup --profile web --download-resources
  -> 检查 pnpm 和 dsh 0.1.1-rc.2
  -> 验证不加载用户插件的 DSH Web 基础 Profile
  -> 直接使用 NPM 包内的构建产物
  -> 首次准备时检查 Git，并通过 pnpm dlx 使用精确 Bun
  -> 准备锁定版本的 GPLv3 兼容客户端和 adapter；以后直接复用
  -> 明确带下载参数时，从打印的固定地址下载并校验资源归档
  -> 把验证后的本地归档交给同源兼容客户端，首次启动自动导入
  -> 通过官方 dsh plugin 命令挂载外部插件
  -> 用最终 Profile 配置验证挂载结果
  -> 保存启动配置到 $DSH_HOME/red-alert/install.json
```

安装器失败时会停在真实失败点。若活动命令不是 `dsh 0.1.1-rc.2`，它会在改动 Profile 前退出。若你还没有可运行的 DSH Web Profile，最新版 DSH 会在第一次检查时创建默认 `web` Profile。setup 不要求全局 Bun；只有第一次构建 renderer 时才通过 `pnpm dlx bun@1.3.14` 下载并运行锁定工具，已经准备好的 renderer 不再检查 Git 或 Bun。资源下载会先校验响应声明的大小，再在流式写入时限制总字节数并计算 SHA-256；任何不一致都会删除未完成的 `.part` 文件并停止 setup，不会把错误内容交给客户端。

需要自定义 renderer 目录时：

```sh
pnpm exec dsh-red-alert-setup --profile web --renderer-dir /absolute/new/red-alert-renderer
```

需要指定稳定 renderer 端口时：

```sh
pnpm exec dsh-red-alert-setup --profile web --renderer-port 4317
```

只预览将执行的命令，不改文件或 Profile：

```sh
pnpm exec dsh-red-alert-setup --profile web --dry-run
```

兼容客户端的锁定来源、提交、补丁内容和 GPLv3 边界见 [renderer adapter 说明](renderer-adapter/README.md)。

### 手动挂载

需要完全手动控制时：

```sh
pnpm install --frozen-lockfile
pnpm run build
pnpm prepare:renderer -- /absolute/new/red-alert-renderer
RA_RENDERER_DIST_DIR=/absolute/new/red-alert-renderer/dist \
  dsh plugin --profile web add -w file:/absolute/path/to/dsh-red-alert --save-exact --ignore-scripts
RA_RENDERER_DIST_DIR=/absolute/new/red-alert-renderer/dist \
  dsh --profile web --dump-config
```

卸载只移除外部插件，不触碰 DSH 源码：

```sh
dsh plugin --profile web remove -w @vibeinging/dsh-red-alert
```

## 验收结果

```text
RA_READY = min(PROFILE, FOG, VISUAL, TOOL_COVERAGE,
               LAZY_LOAD, SAME_MATCH, DSH_CONTRACT, REGRESSION)
         = 1
```

| 指标 | 结果 | 证据摘要 |
| --- | --- | --- |
| `PROFILE` | 1 | 外部 bundle 通过真实 DSH Profile 挂载，DSH checkout 零写入 |
| `FOG` | 1 | 离线审计无泄漏；真实浏览器 current LOS、last-seen 冻结和边界失败关闭通过 |
| `VISUAL` | 1 | DSH 右栏显示真实地图、HUD、小地图、迷雾、单位和建筑，中间 Chat 同屏 |
| `TOOL_COVERAGE` | 1 | 85 个公开声明分类，允许方法有精确 wrapper，危险方法不可见 |
| `LAZY_LOAD` | 1 | 初始仅 bootstrap；持久选择后才发布组 schema |
| `SAME_MATCH` | 1 | Chat 命令、bridge、引擎和 iframe 绑定同一局 |
| `DSH_CONTRACT` | 1 | 官方 SDK、Profile、client handoff、transport 和 projection 通过 |
| `REGRESSION` | 1 | 插件检查、adapter 测试、构建、包检查和公平审计通过 |

详细证据见[最终验收报告](docs/reports/2026-08-22_dsh-real-client-final-acceptance.md)、[宽栏防守复赛报告](docs/reports/2026-08-23_dsh-wide-panel-defense-rematch.md)和[自动增强报告](docs/reports/2026-08-23_auto-learning-speed2-and-command-cycle.md)。

## 验证

```sh
pnpm run check
pnpm run setup -- --profile web --dry-run
```

`pnpm run check` 包含仓库规则、方法策略、renderer adapter、lint、Host/client 类型检查、构建、插件测试、game-host 测试、公平审计和 publint。

## 项目边界

- 这是专为 DeepSeek Harness（DSH）打造的独立外部插件，通过官方 NPM SDK、`cordis.patch.yml` 和 Profile 机制即插即用，全程不修改 DSH 源码。
- 浏览器或 Host 进程崩溃后的 pending command 不承诺跨进程 exactly-once；恢复时失败关闭，不猜测命令是否执行。
- 未包含电影时，兼容客户端可能记录非阻断的视频解码警告；最小资源导入和实际对局不受影响。
- 兼容客户端源码开源不等于 EA 美术、声音和地图素材自动进入公有领域。用户必须自行确认资源来源和使用权。
- 插件源码和 NPM 包采用 `GPL-3.0-only`；兼容 renderer adapter 同样遵循上游 GPLv3。许可证不授予任何 EA 游戏素材权利。
- NPM 包和 GitHub 仓库不分发游戏素材；setup 仅在用户明确传入 `--download-resources` 后，从 README 写明的第三方地址取回固定摘要的归档并保存在本机。用户必须自行确认素材来源和使用权。