# Trae CN 后续工作总纲

> 版本：v1.0　生成：2026-10-16　整理：DeepSeek Harness（验收方）
> 适用对象：Trae CN 施工方
> 工作目录：`D:\NX_AI`

---

## 0. 一分钟读懂

| 项 | 数字 |
|---|---|
| 已完成卡 | 16 张（P0-00 ~ P1-05） |
| **验收方自行修复的缺陷** | **7 个**（其中 4 个是产品入口/参数引擎的事故级缺陷） |
| 剩余卡片 | **13 张**，分 4 批执行 |
| 现有门禁 | 2 道（语法门禁、防退化评测门禁），当前**全绿** |

### ⚠️ 冲突规则（最重要）

> **本总纲与卡片正文冲突时，以本总纲为准。**
>
> 原因：部分卡片是在更早轮次写的。之后验收方在真机上自行修复了其中多个缺陷，
> 卡片正文可能仍描述"待修"状态。**动手前先看第 8 节的差异对照表**，
> 否则你会重做已经完成的工作、甚至把已修好的逻辑改回去。

### 开工前先确认起点干净（30 秒）

```powershell
python D:\NX_AI\tools\check_py_syntax.py     # 期望：28 个 .py，0 错误 0 预警，退出码 0
python D:\NX_AI\tests\run_eval.py            # 期望：通过 13/13，意外退化 0，漂移 0，退出码 0
```

如果这两条不是上面这个结果，**先报告、不要动手**——说明起点已被改动。

---

## 1. 必读的三份文档（按顺序）

| 顺序 | 文档 | 为什么读 |
|---|---|---|
| 1 | `D:\NX_AI\docs\08_交接清单与项目状态.md` | 全局状态：已达成什么、还剩什么、哪些需要用户决策 |
| 2 | `D:\NX_AI\docs\NXOpen跨版本兼容矩阵.md` | **哪些 API 存在、哪些根本不存在**——这是反复踩坑的根源治理 |
| 3 | 本文档第 2、8 节 | "不要重做"清单 + 卡片差异对照 |

---

## 2. 不要重做的东西（验收方已完成，附证据）

| 能力/模块 | 已完成的内容 | 证据 | **你只需做** |
|---|---|---|---|
| **`NxLauncher.py` 产品入口** | 修掉 **5 连缺陷**：①非 raw docstring 的 `\U` 语法错 ②`-Json` 当开关传（实为输出路径）③读 stdout 而脚本写文件 ④`Version`/`Root` 字段名不匹配 ⑤缺 `import tempfile`。现 `--dry-run --version 2412` **退出码 0** 并正确列出两个 NX | `D:\NX_AI\docs\08_交接清单`第五节；备份 `backup\NxLauncher.py.before_FIX01` | 复核这 5 处改动；补一条**集成测试**（`detect_nx()` 能解析出 ≥1 个版本且含 `version`/`root` 键） |
| **精加工 Ap（RL-009）** | 新增数据驱动红线 RL-009：精加工 Ap 是**绝对深度 0.1~0.3mm 不折算**。原来铝件算到 **6.4mm**，现为 0.3mm | `D:\NX_AI\docs\FIX-02_修复报告.md` | 补单元测试（断言 finishing Ap ∈ [0.1,0.3]）；写根因文档 |
| **丝锥 Fz（RL-002）** | 修掉"悬伸降额改错了对象"：原先降 `feed` 再反算 `fz`，导致 M3 的 Fz=0.375 ≠ 螺距 0.5。现全部 **7 把丝锥 Fz==螺距** | `D:\NX_AI\docs\FIX-04_修复报告.md` | 补**遍历全部丝锥**的单测（原测试只测部分，所以 bug 活了下来）；写根因文档；检查钻头分支是否有同类语义问题 |
| **L2 学习层 `core/feedback.py`** | 已建成：canonical key 精确匹配、溯源、success_rate=1.0、**自测 9/9**（含"换刀径/换工序/换材料都不误命中"）；已接进 `propose_plan.py`（实测 ap 4.8→3.0、MRR 自动重算 14.85→9.28） | `D:\NX_AI\docs\P2-02_L2学习闭环实测.md` | 加 `--from-file` 批量导入、`correct.bat` 交互入口、`conflicts` 子命令。**不要改 canonical key 规则**（已被 9/9 自测覆盖） |
| **防退化评测 `tests/run_eval.py`** | 已建成：13 条断言（8 条业务红线 + 5 条 L2）、特征化基线、known_issues 记账、`--strict-drift`。**漂移检测已被验证真会报** | 运行输出；`tests\golden\baseline.json` | 把金标集从"断言 + 10 个基线上下文"扩到 `golden_cases.json` **20~50 条真实任务**，并断言"学习后命中率 ≥ 学习前" |
| **语法门禁 `tools/check_py_syntax.py`** | 已建成：语法 + **缺 import** + 非 raw 路径写法 + 多余 BOM。已验证能抓出真 bug（当场抓出 `tempfile` 未导入） | 运行输出 | 不需要你再写，用它即可 |
| **`NXOpen跨版本兼容矩阵.md`** | 已由验收方在真机两版本上实测写成 | `D:\NX_AI\docs\NXOpen跨版本兼容矩阵.md` | **照它写，不要重新试那些不存在的 API**（见第 5 节红线） |
| **`nx_versions.ps1` 的输出字段** | `{Count, GeneratedAt, NxVersions:[{Version, Root, DisplayVersion, PythonDll, ...}]}` | 上表 | 按此字段写代码，别猜键名 |
| **队列/投喂器自身** | 修掉"标题格式不合法就**静默丢卡**"（曾丢 2 张） | `tools\make_queue.py` | 不需要你动 |

---

## 3. 执行顺序（13 张卡，4 批）

> 顺序理由：先把项目"洗干净"（批 A），再立入口与兼容层（批 B），再做界面/安装（批 C），
> 最后做云端与学习闭环（批 D）。**每批做完跑一次两道门禁和一次真实零件冒烟。**

### 批 A —— 收尾，让项目干净（4 张）

| 卡 | 目标 | 现状 | 你要做什么 | 验收 |
|---|---|---|---|---|
| **FIX-01** | `NxLauncher.py` 语法错 | ✅ 已修（5 连缺陷全修） | 复核 5 处改动；补集成测试 | 语法门禁 0 错误；`detect_nx()` 集成测试通过 |
| **FIX-02** | 精加工 Ap 语义 | ✅ 已修（RL-009） | 补单测 + 根因文档 + 复核 | finishing Ap ∈ [0.1,0.3]；`run_eval.py` 仍全绿 |
| **FIX-04** | 丝锥 Fz 缩放 | ✅ 已修 | 补**遍历全部丝锥**单测 + 根因文档 + 钻头同类检查 | 7 把丝锥全部 Fz==螺距；`run_eval.py` 仍全绿 |
| **FIX-03** | 刀具刃长 vs 悬伸语义 | ✅ 审计已完成（**43 把刀里 34 把会误报**；刀具库**无悬伸字段**） | **默认按方案 B 落地**：RL-007 降为 info 级"刃长比提示"，文案不得再冒充刚性告警；并在规则里注明"要真正判刚性需补 `overhang_mm`"。**若用户已选 A/C，则按用户选择** | 规则 JSON 里有明确语义说明；`run_eval.py` 的 RL-007 断言按新语义同步更新且全绿 |

### 批 B —— 入口与集成（3 张）

| 卡 | 目标 | 现状 | 你要做什么 | 验收 |
|---|---|---|---|---|
| **P2-05** | 跨版本安全访问层 | 矩阵已由验收方写好（交付物③**已完成**） | 写 `nx\compat.py`（`col_count`/`col_list`/`part_units`/`nx_version`/`open_part`/`log_line`）+ `nx\probe\compat_probe.py`，**严格按矩阵** | 两个真实版本各跑通一次、输出 `compat_probe.jsonl` |
| **P2-01** | 单入口 + 集成冒烟 | 验收方已修通入口链；**92 vs 2 已有可复现对比与最可能解释（Brep 收敛体拆分语义），但未证实** | 写 `nxai.ps1`（`list` / `run -Version -Task [-Part]` / `verify -TaskId`）；真实零件两版本各跑一次；报告里**必须写 92 vs 2 的结论**（可复现步骤，或"未证实 + 下一步怎么验"） | `nxai list` 列出 2 个版本；`nxai run` 两版本各成功一次、产物落 `artifacts` |
| **P2-02** | 三个已实测 bug + 控制台编码 | 三个问题**都仍然存在**（编码问题验收方也复现过：GBK 下 emoji 崩） | ①统一编码方案（**二选一并说明理由**：入口 `sys.stdout.reconfigure` 或去掉非 GBK 字符）**要求不设 PYTHONIOENCODING 也零异常** ②修 `nx\verify_refs.ps1` 的 `-Version all`（路径拼错）③明确 `data\validate.py` 退出码语义。**注意**：验收方本轮是靠设 `PYTHONIOENCODING=utf-8` 绕过的，**那不是本卡要的修法** | 三个问题各有"修复前/修复后"证据；默认控制台下自测零异常 |

### 批 C —— 界面与安装（3 张）

| 卡 | 目标 | 你要做什么 | 验收 |
|---|---|---|---|
| **P1-08** | 主控界面骨架（版本中心 + 任务中心） | 技术栈已定：**C#/.NET + Avalonia**（用户已确认）；必须**断网可用**、能列版本、能看任务 | 不启动 NX 也能启动并列出本机两个 NX 版本 |
| **P2-03** | 界面接真实数据 | 把 P1-08 骨架接上版本探测 / 任务引擎 / 记忆库 | 在没装 NX 的机器上界面仍能启动（可临时改名 NX 目录模拟） |
| **P2-04** | 安装/卸载器替换 | 用 `deploy.ps1` 重写，替换旧 `install.ps1`。**注意**：启动器当前把文件放到 `<NX>\UGII\vendor\NX Copilot\startup\`，**请确认这是否是官方推荐加载方式**，并在报告里写明理由（用户已决定"不设 UGII_VENDOR_DIR 全局变量"，别违反） | 本机完整往返：安装→Verify→卸载→Rollback，结束后**目录与变量回到初始状态** |

### 批 D —— 云端与学习闭环（3 张）

| 卡 | 目标 | 你要做什么 | 验收 |
|---|---|---|---|
| **P2-06** | L2 接线 + 金标评测 | 采集入口（`--from-file` + `correct.bat`）、冲突可见（`conflicts`）、金标集 20~50 条 | `run_eval.py` 跑两种模式并断言"学习后命中率 ≥ 学习前" |
| **P1-07** | 人工修正 → 可训练数据 | 相似修正归并成候选经验（带溯源），编辑距离要有测试 | 假数据跑通"3 条相似修正 → 1 条候选经验 → 带溯源" |
| **P1-06** | 云端服务（**目标⑤唯一缺口**） | TLS + 按设备凭证 + 任务白名单 + 审计。**本机没有服务器就先在本地起服务自测**（自签证书），部署等用户给服务器 | 测试全绿；四条安全用例真实通过；代码里**搜不到** `shell=True` / `cmd /c` |

---

## 4. 每张卡完成后的固定动作

1. 写 `D:\NX_AI\状态\<卡号>.done.json`，格式**严格**如下：

```json
{
  "task": "FIX-01",
  "status": "done",
  "files": ["D:\\NX_AI\\tools\\NxLauncher.py", "D:\\NX_AI\\tests\\test_launcher.py"],
  "verify": "两条门禁输出摘要 + 你实际跑过的命令与结果",
  "blocked": null,
  "notes": "改了什么、为什么这么改"
}
```

> `files` **必须是纯字符串数组**（P0-04 曾写成对象导致验收失败）。
> `status` 只允许 `done` / `blocked`；`blocked` 时必须写清"卡在哪一步、需要谁给什么"。

2. 跑两道门禁，把结果粘进 `verify`：

```powershell
python D:\NX_AI\tools\check_py_syntax.py    # 必须 0 错误
python D:\NX_AI\tests\run_eval.py           # 必须"意外退化 0"
```

3. **改了规则/数据/学习层**时，除了跑门禁，还要：
   - 先跑一次看"漂移 N 处"，人工确认这是**有意变更**
   - 再 `python D:\NX_AI\tests\run_eval.py --rebuild-baseline` 重建基线
   - 最后再跑一次确认归零
   - 若本次修复让某个"已知未修"项转绿，**必须**从 `tests\golden\known_issues.json` 删掉该条目

---

## 5. 红线（违反即回滚，最高优先级）

| # | 红线 | 为什么 |
|---|---|---|
| 1 | **禁止设置机器级/用户级环境变量**。NX 环境一律**进程级注入**，切换版本必须对每个子进程独立设 | 全局污染会影响用户所有 NX 会话 |
| 2 | **禁止写入/恢复 `UGII_VENDOR_DIR` 与 `UGII_LOCAL_USER_DEFAULTS`**（用户明确决定不恢复；`UGII_USER_DIR` 保留） | 用户决定 |
| 3 | **禁止在脚本里写 `-Apply` / `-Force` / `-Execute` / `-Run` / `-Kill` 之类会真的改动系统的开关**（曾发生误清用户环境变量的事故） | 安全 |
| 4 | **禁止用 NX 对象个数做业务判断**（实体数/特征数）。实测同一零件 `list(part.Bodies)` 在 NX2212=**92**、NX2412=**2** | 必然出错 |
| 5 | **禁止猜 API 名字**。先用反射 `dir(obj)`；本机实测**不存在**的有：`face.Radius` / `face.GetRadius()` / `edge.Radius` / `edge.GetCurveData()` / `part.Faces` / `ufs.Modl.AskFaceData` / `body.GetBoundingBox()` | 反复踩坑的根因 |
| 6 | **丝锥 `Fz` 必须等于螺距，绝不缩放**；过度悬伸只能**降转速** | 缩放会乱扣/断丝锥 |
| 7 | **精加工 Ap 是绝对深度 0.1~0.3mm，不按刀径折算** | 否则铝件会算出 6.4mm 切深 |
| 8 | 集合不支持 `len()`/`ToArray()`，**只能迭代** | 本机实测 |
| 9 | **Python 文件不带 BOM**（只有 .ps1/.bat 需要）；**非 raw 字符串里禁止出现 Windows 路径** | 两者都会让文件"看起来坏了"或真的坏 |
| 10 | 改任何规则/数据/学习层后，**`run_eval.py` 的"意外退化"必须为 0** | 没有门禁就会越改越蠢 |

---

## 6. 整批交付的完成判定（Definition of Done）

13 张卡全部 done 且满足：

- [ ] `check_py_syntax.py`：0 错误 0 预警
- [ ] `run_eval.py`：**通过 13/13 或更多，已知未修 0，意外退化 0，漂移 0**
- [ ] `tests\golden\known_issues.json` 为空数组 `[]`
- [ ] `nxai list` 能列出本机 2 个 NX 版本
- [ ] `nxai run` 在 **2212 与 2412 各成功一次**真实零件，产物完整
- [ ] 界面在**不启动 NX** 的情况下能启动并显示两个版本
- [ ] 装/卸往返后**目录与环境变量回到初始状态**（含"全局零污染"自检）
- [ ] `test_cutting_rules.py` 覆盖：丝锥遍历全部、精加工 Ap 区间、钻头不乘 2 齿
- [ ] 云端服务：四条安全用例真实通过，无 `shell=True` / `cmd /c`
- [ ] 21 份以上 docs 文档齐全，每张卡有 `done.json`
- [ ] **没有任何全局环境变量被改动**（每次真机测试后自检）

---

## 7. 卡住了怎么办

| 现象 | 原因 | 处置 |
|---|---|---|
| 卡长时间无输出 | 审批弹窗挂着 | 看 Trae 窗口是否有待批准弹窗；把 `D:\NX_AI` 加入读写白名单、开自动批准 |
| 投喂器停住不动 | Trae 更新后窗口标题变了（曾发生） | 关掉卡住的黑窗口 → 关闭"更新日志"窗口 → 点一下聊天输入框 → 重跑 `tools\feeder_go.bat` |
| `sqlite3.OperationalError: unable to open database file` | 进程被沙箱限制写 `D:\NX_AI` | 用有写权限的方式运行；不要改建库路径 |
| `UnicodeEncodeError: 'gbk' codec can't encode ...` | 正是 P2-02 要修的问题 | 先按 P2-02 修（不要用设环境变量绕过） |
| 真机 NX 批处理退 1 但产物正常 | NX 对 journal 的 `sys.exit` 处理特殊 | **以产物为准**判断成功，不要只看退出码 |
| 拿不准要不要改某处 | — | **停下来问人**，不要猜。尤其：不要碰用户的环境变量、不要删用户数据 |

---

## 8. 卡片-现状差异对照表（13 张，动手前逐条看）

| 卡 | 卡片正文说 | 实际现状 | 实际剩余范围 |
|---|---|---|---|
| FIX-01 | 修语法错 | 5 连缺陷全修完，`--dry-run` 退出码 0 | 复核 + 集成测试 |
| FIX-02 | 修精加工 Ap | RL-009 已落地，Ap=0.3mm | 单测 + 文档 + 复核 |
| FIX-03 | 核实刃长数据 **或** 修语义 | 审计完成：34/43 误报、无悬伸字段 | **按方案 B 落地**（除非用户选 A/C） |
| FIX-04 | 修丝锥 Fz | 已修，7 把全对 | 遍历全部丝锥的单测 + 文档 + 钻头同类检查 |
| P1-06 | 重做云端 | **完全未做**（目标⑤唯一缺口） | 全部（本机可先自测） |
| P1-07 | 修正→可训练数据 | 未做（`feedback.py` 已提供数据底座） | 全部 |
| P1-08 | 界面骨架 | 未做 | 全部 |
| P2-01 | 单入口 + 冒烟 | 入口链已修通；92 vs 2 有对比但未证实 | `nxai.ps1` + 双版本冒烟 + 92vs2 结论 |
| P2-02 | 3 个 bug + 编码 | **3 个都还在** | 全部（编码**不要**用环境变量绕过） |
| P2-03 | 界面接数据 | 依赖 P1-08 | 全部 |
| P2-04 | 装卸器替换 | 依赖 P2-01；**加载方式需确认** | 全部 |
| P2-05 | 兼容层 + 探针 + 矩阵 | **矩阵已完成** | `compat.py` + `compat_probe.py`（照矩阵写） |
| P2-06 | L2 接线 + 评测 | `feedback.py` 与 `run_eval.py` **已建成** | 采集入口(--from-file/correct.bat/conflicts) + 金标集 20~50 条 |

---

## 9. 需要用户决策、但**不要**由 Trae 自行决定的事

1. **服务器与云部署**（P1-06 的落地）：需要用户提供服务器/域名/证书策略
2. **FIX-03 的方案选择**（A 补悬伸数据 / B 降级为提示 / C 重定阈值）：默认 B，用户可改
3. **NX 插件的官方加载方式**（`UGII\vendor\...` 是否符合官方推荐，P2-04）：需要用户或西门子文档确认
4. **对外销售相关的合规**：许可证审计、脱敏策略的最终口径

> 遇到这四件事：**写进 `done.json` 的 `blocked` 字段并停下来**，不要替用户决定。