# 编码 / 换行审查 — Ubuntu 阶段 2

| 项 | 内容 |
|----|------|
| 日期 | 2026-06-04 |
| 前置 | `docs/audit/2026-06-04-encoding-review-ubuntu-phase1.md` |

---

## 1. 阶段 2 完成项

| 任务 | 结果 |
|------|------|
| 工作区 LF 归一化（索引 blob 写盘） | ✅ `normalize_worktree_lf.sh` 260+ 文件；`check_worktree_eol` **OK** |
| `web/agent/agent.py` 全文 I/O | ✅ 所有 `open`/`read_text` 显式 `utf-8`；`config.json` 写 LF；去重 `_os_release()` |
| `.cursor/rules/*.mdc` | ✅ 从索引重写 LF；门控扩展至 `check_text_eol` / `check_worktree_eol` |
| `docs/project/mysql-mcp-setup.md` | ✅ WSL 示例路径改为 `$NEXUS_ROOT` |
| `frontend` `vue-tsc` | ✅ **已通过**（见 changelog `2026-06-04-frontend-typecheck-fixes.md`） |

---

## 2. `web/agent/agent.py` Closure

| 位置 | 变更 |
|------|------|
| `load_config` | `encoding="utf-8"` |
| `reload_config` | `encoding="utf-8"`, `newline="\n"`, `ensure_ascii=False` |
| `health` + `_os_release` | 统一 `Path.read_text(encoding="utf-8")` |

子服务器 Agent **不依赖** `server.utils.text_io`（保持独立部署包）。

---

## 3. 门控复验

```text
check_worktree_eol: OK (201 paths)
check_text_eol:   OK (206 paths, 含 .mdc + web/agent)
check_shell_eol:  OK
pytest test_text_io: 5 passed
pre_deploy Pre-flight EOL: PASS
```

---

## 4. 非编码项（阶段 3 建议）

### 4.1 前端 TypeScript（`npm run type-check`）

| 文件 | 问题 |
|------|------|
| `PushSyncModeCard.vue` | `SyncMode` 与 `null` 联合 |
| `useFilesPage.ts` | `OpenFilePayload` 与简化类型不一致 |
| `PushPage.vue` | `string \| null` vs `string \| undefined` |

修复方式：对齐 composable 类型，**非**换行/UTF-8。

### 4.2 文档 Windows 路径

- ✅ **SSOT**：`docs/project/linux-dev-paths.md`；`AI-HANDOFF-2026-06-03`、handoff 顶部已指向
- 历史 handoff 正文仍保留 `C:\Users\...` 作归档，不影响运行

### 4.3 Playwright E2E（待你本机一条命令）

本地库 **admins=0** 时需先种子账号（密码只写 `.env`，不入 git）：

```bash
# 在 .env 增加: NEXUS_TEST_ADMIN_PASSWORD='你的密码'
python3 scripts/seed_local_admin.py
cd frontend && NEXUS_E2E_BASE=http://127.0.0.1:8600 NEXUS_E2E_PASSWORD='同上' npm run test:e2e
```

### 4.3 `*.md` 工作区 CRLF

`check_text_eol` **不**扫描 `docs/**/*.md`（不影响 Ubuntu 运行）；可选 `git add --renormalize '*.md'`。

---

## 5. DoD（阶段 2）

- [x] 工作区与索引 LF 一致
- [x] Agent I/O 审查完毕
- [x] Cursor 规则 `.mdc` 纳入门控
- [x] MCP 文档 Linux 段更新
- [x] 前端 TS 三处（已修复）
- [ ] 历史 handoff 文档路径清理（可选）

## 验证命令

```bash
bash scripts/normalize_worktree_lf.sh
python3 scripts/check_worktree_eol.py
python3 scripts/check_text_eol.py
cd frontend && npm run type-check   # 当前 3 errors
```
