# RA3 Apt CLI — 工作计划

> 将 ra3aptxmleditor 的 .apt ↔ 人类可读 XML 双向转换流程 CLI 化。
> 基于 `ra3apt-cli/` 目录下的 Node.js 项目。

---

## 0. 项目渊源

本 CLI 工具基于两个上游项目：

- **jonwil/cc3tools** — 提供 `apt2xml.exe`（.apt → raw XML）和 `xml2apt.exe`（raw XML → .apt），是本工具的二进制转换引擎。
- **utunnels/ra3aptxmleditor** — 基于 nw.js 的 RA3 .apt 图形化编辑器，其 `preprocess.html` 中的 `xmladdhint()`（raw XML → 人类可读 XML）和 `xmlcleanhint()`（人类可读 XML → raw XML）是本 CLI 核心逻辑的直接来源。

本 CLI 将 ra3aptxmleditor 的编辑流程从 nw.js 桌面 GUI 迁移到命令行环境，使用 cheerio 替代 jQuery，保持与原始工具的行为一致性。

---

## 1. 总体决策记录

### 1.1 项目定位

- **CLI 工具行为与现有 nw.js GUI 完全一致**，包括读写 manifest XML、.dat、.ru 文件
- **两阶段转换模式**：`ra3apt-cli expand` (apt → 人类可读 XML) 和 `ra3apt-cli build` (人类可读 XML → apt)
- **仅 Windows**（cc3tools 提供的是 Windows .exe）

### 1.2 输出文件命名

| 操作 | 默认输出 | 说明 |
|------|---------|------|
| `expand` | `<name>_edit.xml` | 人类可读 XML |
| `build` | `<name>.apt` + `<name>.const` | 二进制 .apt + 常量表 |

用户可自由指定 `-o` 覆盖默认名。

### 1.3 文件冲突策略

**人类可读 XML 与 manifest XML 不会冲突**，因为：
- manifest XML 是源目录中的 `[name].xml`（AssetDeclaration 格式，由 RA3 Mod SDK 管理）
- apt raw XML 是 `%TEMP%/[name].xml`（临时文件，用户不可见）
- 人类可读 XML 默认是 `[name]_edit.xml`（不同文件名）
- CLI 写回 manifest XML 的行为与现有 GUI 完全一致（第 3089 行）
- `.ru` 几何数据内嵌在人类可读 XML 的 `<shape><ru>` 元素中，build 时不再依赖源目录中的 `.ru` 文件

### 1.4 依赖库

| 库 | 用途 | 选择原因 |
|----|------|---------|
| `cheerio@1.0.0-rc.12` | DOM 操作（替代 jQuery） | 99% API 兼容，已验证全部 15 类用法 |
| `commander` | CLI 框架 | 最流行的 Node.js CLI 框架 |

### 1.5 CDATA 方案（修订）

原始代码用 `CDATASection` 包裹 action 汇编代码。CLI 改用**先 text node + 后处理 CDATA 包装**的方式。

| 方向 | 原始 | CLI |
|------|------|-----|
| expand (写入) | `xmldoc.createCDATASection(text)` | `v.empty().text(astr)` cheerio 序列化后，用正则将 action/initaction/clipaction 的内容替换为 CDATA |
| build (回读) | `$(el).text()` 自动解码 CDATA | cheerio 在 xmlMode 下自动将 CDATA 视为 text node，`.text()` 正常提取 |

**关键细节**：
- cheerio 不直接支持创建 CDATA 节点，所以用正则后处理实现
- 正则必须匹配带属性的标签（如 `<clipaction flags="Construct">`）
- `clipactions`（复数）不会被误匹配，因为正则要求标签名完整后跟空格或 `>`
- `&amp;` 双编码问题通过 `decodeAttrEntities()` 在 `actiontostring` 中解决

### 1.6 错误处理

- 原始代码中的 `alert()` 全部改为 **`throw new Error(msg)`**
- CLI 入口层 `catch` 后打印到 **stderr** 并以 **exit code 1** 退出
- 覆盖全部 15 处 alert（重复 ID、跳转目标未找到、语法错误、超出 255 等）
- 仅 `console.log`/`console.warn` 的诊断信息保留（非致命，不影响流程）

### 1.7 浏览器特有 API 等价替换表

| 浏览器/nw.js API | CLI 替换 | 出现次数 |
|-----------------|---------|:-------:|
| `$.parseXML(xmlStr)` | `cheerio.load(xmlStr, { xmlMode: true })` | 4 |
| `new XMLSerializer().serializeToString(doc)` | `$.xml()` | 2 |
| `xmldoc.createCDATASection(text)` | 正则后处理替换：`/<tag>([\s\S]*?)<\/tag>/` → `<tag><![CDATA[$1]]></tag>` | 1 |
| `xmldoc.createElement(tag)` | `$('<' + tag + '>', $)` | 3 |
| `$(el).attr(name)` / `.attr(name, val)` | 不变 | ~60 |
| `alert(msg)` | `throw new Error(msg)` | ~15 |
| `escape(t)` | `encodeURIComponent(t)` | 1 |
| `el.outerHTML` | `$.html(el)` | 3 |
| `el.previousSibling` | `el.prev`（cheerio 节点） | 2 |
| `el.textContent` | `el.data`（文本节点） | 1 |
| `el.cloneNode()` | `$.clone(el)[0]` 或 `cheerio` 原生 clone | 1 |
| `editor.getValue()` / `editor.setValue()` | `fs.readFileSync()` / `fs.writeFileSync()` | GUI 专属 |
| nw.js / CodeMirror / Canvas / jQuery UI | **全部省略** | GUI 专属 |

---

## 2. 关键代码定位（preprocess.html）

| 模块 | 行号 | 说明 |
|------|:----:|------|
| 常量表 — `ActionNames` | 1484-1619 | opcode 名称表 |
| 常量表 — `ActionAligns` | 1627-1647 | 哪些 action 需要对齐 |
| 常量表 — `ActionSizes` | 1648-1835 | 每个 action 的固定长度 |
| 常量表 — flags 枚举 | 250-354 | PlaceObjectFlags / ClipEventFlags / ButtonRecordFlags / ButtonActionFlags / FunctionPreloadFlags / ButtonInput |
| 辅助函数 — `el()` / `bad()` | 2283-2288 | 元素创建 |
| 辅助函数 — `endian()` / `valuetoflags()` / `flagstovalue()` | 356-396 | 字节序/flag 转换 |
| 辅助函数 — `encodeXML()` / `mkstr()` | 1856-1866 | 字符串编码 |
| 辅助函数 — 对齐计算 | 1968-2001 | `alnsize()` / `calcaln()` / `thisaln()` / `nextaln()` / `copyindent()` / `indentstr()` |
| 核心 — `xmladdhint()` (expand) | 2023-2280 | raw XML → 人类可读 XML |
| 核心 — `actiontostring()` | 1885-1967 | action 节点 → 文本汇编语句 |
| 核心 — `xmlcleanhint()` (build) | 2597-3095 | 人类可读 XML → raw XML |
| 核心 — `stringtoaction()` | 2290-2582 | 文本汇编语句 → action 节点 |
| 核心 — .const 二进制写入 | 2741-2766 | 常量表二进制序列化 |
| 核心 — manifest / .dat 生成 | 2964-3092 | 写回 manifest XML、.dat、.ru |
| 核心 — `loadapt()` (打开流程) | 488-508 | apt → raw XML 的编排 |

---

## 3. 进度追踪

> 当前状态：✅ **全部完成**

### Phase 1 — 项目脚手架与常量提取 ✅

- [x] 创建 `ra3apt-cli/` 项目结构（已完成 `package.json` 初始化 + `cheerio` 安装）
- [x] 安装 `commander` 依赖
- [x] 提取常量表到 `lib/constants.js`：
  - `ActionNames` / `ActionNames2`（新旧两套 opcode 名称）
  - `ActionSizes` / `ActionAligns`
  - `PlaceObjectFlags` / `ClipEventFlags` / `ButtonRecordFlags` / `ButtonActionFlags` / `FunctionPreloadFlags` / `ButtonInput`
- [x] 创建 CLI 入口文件 `bin/ra3apt.js`，挂载 `expand` 和 `build` 子命令

### Phase 2 — 工具函数层 ✅

- [x] 提取通用工具函数到 `lib/utils.js`：
  - `endian()` / `valuetoflags()` / `flagstovalue()`
  - `encodeXML()` / `mkstr()` / `el()` / `bad()` / `makelabel()`
  - `alnsize()` / `calcaln()` / `thisaln()` / `nextaln()` / `copyindent()` / `indentstr()`
  - `rgba()` / `getrgba()` / `cleanrgba()` / `getmatrix()` / `cleanmatrix()`
- [x] 适配浏览器 DOM 原生属性访问 → cheerio 等价写法
- [x] 编写 `expand/builder` 两流程共享的临时目录管理、exe 调用、文件复制逻辑

### Phase 3 — 实现 `ra3apt-cli expand` ✅

- [x] 实现 `expand()` 流程：复制 .apt + .const → 运行 `apt2xml.exe` → 读取 manifest XML + .dat
- [x] 移植 `xmladdhint()` 全部逻辑：
  - 常量展开
  - 跳转 label 解析
  - action 汇编化 + text node 写入
  - flags 符号化
  - image / shape 纹理解析
  - 编辑者友好清理
- [x] 移植 `actiontostring()` 全部九种 action 分支
- [x] 序列化输出人类可读 XML

### Phase 4 — 实现 `ra3apt-cli build` ✅

- [x] 移植 `xmlcleanhint()` 全部逻辑：
  - 文本汇编解析 + `stringtoaction()`
  - 常量池重构建 + .const 二进制写入（`Buffer` API，Node.js 原生）
  - character ID 重编号
  - 跳转偏移量解析
  - function size 计算
  - frame 编号
  - flags 数值化
  - placeobject flags 构建
  - shape/ru/image 处理 + manifest / .dat / .ru 生成
  - 矩阵/颜色属性拆解和清理
- [x] 运行 `xml2apt.exe` 生成 .apt + .const
- [x] 写回 manifest XML、.dat、.ru 文件

### Phase 5 — 端到端测试与文档 ✅

- [x] 从 `assets/` 获取 3 组测试数据（ig_HUD、fem_m_gameSetup、main_mouse）
- [x] 验证完整回路：`.apt` → expand → `_edit.xml` → build → `.apt` → apt2xml → raw XML 对比
- [x] **全部 3 组测试通过，raw XML 完全一致**
- [x] 清理测试临时文件
- [x] 编写 README 与 CLI 帮助文本

### Phase 6 — Bug 修复与完善 ✅

- [x] **Phase 6.1 — `parseArgs` 引号保留**：`parseArgs()` 返回的参数字符串两端保留引号，导致 `str` 属性带多余引号
- [x] **Phase 6.2 — 标签名不匹配**：build 产生 `data`/`noarg` 标签但 cc3tools 需要 `byte`/`short`/`float`/`long`
- [x] **Phase 6.3 — placeobject flag 计算缺失 rotm00→matrix 转换**：人类可读 XML 使用 `rotm00` 格式，但 flag 计算需 `matrix` 格式
- [x] **Phase 6.4 — label 正则冒号**：`^([\w]+):` 返回 `lxnx0:`（带冒号），导致 `[mylabel=lxnx0:]` 找不到目标
- [x] **Phase 6.5 — CDATA 正则误匹配 clipactions**：原正则 `([^>]*)` 吞掉 `clipactions` 的 `s`，修复为 `(\s[^>]*)?`
- [x] **Phase 6.6 — `&amp;` 双编码**：`decodeEntities: false` 读取 raw XML 时 `&amp;` 保持原样，cheerio 序列化再编码 → 需要 `decodeAttrEntities()` 手动解码
- [x] **Phase 6.7 — `pushconst "1"` 被误判为数字**：`parseInt("1")` = 1，`isNaN(1)` = false → 被当作数字常量。修复：检查原始 `argStr` 是否以引号开头
- [x] **Phase 6.8 — .const 文件整型标识符错误**：`writeUInt32LE(2)` 应为 `writeUInt32LE(7)`，并加 `console.warn` 警告
- [x] **Phase 6.9 — build 自动创建输出目录**：添加 `fs.mkdirSync` + `{ recursive: true }` 确保输出目录和 .ru 子目录自动创建

---

## 4. 注意事项

### 4.1 cheerio 使用要点

- 始终使用 `{ xmlMode: true, decodeEntities: false }` 加载 XML
- 元素创建：`$('<' + tagName + '>')` — 创建的元素不会自动加入当前文档，需要手动 `.append()`/`.prepend()` 等
- `.text(text)` 设置文本时，`<` `&` 等字符自动 entity 编码，`.text()` 回读自动解码
- `.sort(fn)` 可用在 cheerio 集合上（继承 Array.prototype.sort）
- `$(el).is(selector)` 只接受 CSS 选择器字符串，不支持传入 jQuery 对象（GUI 预览代码用 `$(f).is(curnode)` 但那是 GUI 专属，不需要移植）

### 4.2 二进制 .const 文件写入

第 237-257 行的 `Buffer.alloc` / `writeUInt32LE` / `asciiWrite` / `fs.openSync` / `fs.writeSync` / `fs.closeSync` 已经是**标准的 Node.js API，不需要额外改动**。注意：

- 整型常量标识符从原代码的 `writeUInt32LE(2)` **修正为** `writeUInt32LE(7)`（7 才是正确的整型标识）
- 当有整数写入 consttable 时会输出 `console.warn` 警告

### 4.3 manifest XML 写回策略

- build 操作会写回 `filedir/[name].xml`（manifest XML），行为与 GUI 第 3089 行完全一致
- 同时也写回 `.dat`、`.ru` 文件
- CLI 不会写回 `_edit.xml` 本身，只消费它

### 4.4 临时目录

- 遵循原代码方式（第 515 行）：`fs.mkdtempSync(os.tmpdir() + path.sep) + path.sep`
- apt raw XML (`[name].xml`) 生成在这里，处理完后清理
- 可通过 `--keep-temp` 标志保留临时目录用于调试

### 4.5 cc3tools 路径

- 默认相对路径：`cc3tools/`（从启动位置出发，即与 `ra3apt-cli/` 同级的工作区目录或由用户指定）
- 可通过 `--tools-path` 参数覆盖

### 4.6 `pushconst` 字符串/数字区分

`pushconst "1"`（带引号）应作为**字符串常量**处理，`pushconst 1`（无引号）作为数字常量。区分逻辑：

```js
// 检查原始 argStr 是否以引号开头
if (argStr && argStr[0] === '"') {
    a.attr('str', args[0] || '');   // 字符串
} else {
    const numVal = parseInt(args[0], 10);
    if (isNaN(numVal) || args[0] === '') {
        a.attr('str', args[0] || '');  // 不是数字 → 字符串
    } else {
        a.attr('num', numVal);         // 是数字
    }
}
```

### 4.7 `decodeAttrEntities()` — 防止 `&amp;` 双编码

expand 以 `decodeEntities: false` 加载 raw XML，属性值中的 `&amp;` 保持原样。但 cheerio 序列化时会将文本中的 `&` 再编码为 `&amp;`，导致双编码。修复：在 `actiontostring()` 中通过 `decodeAttrEntities()` 手动解码实体后再输出。

```js
function decodeAttrEntities(s) {
  if (typeof s !== 'string') return s;
  return s.replace(/&amp;/g, '&').replace(/&lt;/g, '<')
          .replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
}
```

### 4.8 自动创建输出目录

build 命令会在写入输出文件前自动创建目录：

- `fs.mkdirSync(outDir, { recursive: true })` — 确保 `.apt`/`.const`/`.xml`/`.dat` 的输出目录存在
- `fs.mkdirSync(path.dirname(rup), { recursive: true })` — 确保 `.ru` 文件所在的子目录（如 `geometry/`）存在

用户无需手动创建输出目录，build 会递归创建所有缺失的父目录。

### 4.9 错误时 return false 的处理

原始代码中 `xmlcleanhint()` 在出错时 `return false`，调用方据此判断。CLI 版本改为 `throw new Error()`，不再需要返回值检查。

原始模式（第 430 行）：
```js
if(xmlcleanhint()){
  // 继续保存
}else{
  // 保存失败
}
```

CLI 模式：
```js
try {
  xmlcleanhint(...);  // 出错时 throw
  // 继续保存
} catch(err) {
  console.error(err.message);
  process.exit(1);
}
```