fix: preserve legacy text across trans helpers

docs/reference/cli.md

@@ -443,7 +443,21 @@ PS
 
 `<provider>:win skills [--scope agents|codex|all] [--limit N] [--name <精确名称>|--filter <文本>]` 是 Windows 用户 skill 发现入口，默认只读取当前 Windows 用户的 `%USERPROFILE%\.agents\skills`，输出 JSON 中包含 `roots`、`counts`、`query` 和每个 skill 的 `name`、`path`、`skillFile`、`description`。查单个 skill 时优先 `--name`，模糊查找时使用 `--filter`，避免全量结果触发 stdout dump；需要同时检查 `%USERPROFILE%\.codex\skills` 时显式加 `--scope all`。
 
-`<provider>:win/<drive>/<path> rg` 是有界 Windows 文件搜索入口，调用 Windows PATH 中的原生 `rg.exe`，支持 `--files`、`-g|--glob`、`--max-count`、`--max-files` 和 `--timeout-ms`。每次搜索都在 stderr 输出 `UNIDESK_WINDOWS_RG_SUMMARY`，稳定披露 `matched`、`fileCount`、`elapsedMs`、`timeout` 和截断状态；默认预算由 `config/unidesk-cli.yaml#trans.windowsFs.rg` 唯一控制。超时返回 124，无匹配返回 1，缺少 `rg.exe` 返回 127 和可执行替代提示，均不会以空输出伪装成功。Windows `wc` 同时支持 `-l|--lines`、`-w|--words`、`-m|--chars` 与 `-c|--bytes`。
+- Windows `rg`：
+  - `<provider>:win/<drive>/<path> rg` 调用 Windows PATH 中的原生 `rg.exe`。
+  - 支持一个或多个 `-e|--regexp`，以及 `--files`、`-g|--glob`、`--max-count`、`--max-files` 和 `--timeout-ms`。
+  - 搜索强制输出文件名，`UNIDESK_WINDOWS_RG_SUMMARY` 披露 `matched`、`fileCount`、`elapsedMs`、`timeout`、`encoding` 和截断状态。
+  - legacy 或无效 UTF-8 输出必须标记 `encoding=legacy-or-invalid-utf8`，不能静默当作 UTF-8 正常文本。
+  - 默认预算由 `config/unidesk-cli.yaml#trans.windowsFs.rg` 唯一控制。
+  - 超时返回 124，无匹配返回 1，缺少 `rg.exe` 返回 127 和可执行替代提示。
+- Windows 有界读取：
+  - `wc` 支持 `-l|--lines`、`-w|--words`、`-m|--chars` 与 `-c|--bytes`。
+  - `head` 和 `tail` 在行裁剪阶段使用流式读取，不得先以整文件大小门禁拒绝已经有界的 `-n N` 请求。
+- `apply-patch v2` legacy 文本：
+  - bulk read、plan 和 apply 必须共享同一原始字节 fingerprint。
+  - 非 UTF-8 单字节文本标记为 `legacy-single-byte`。
+  - ASCII localized replacement 必须保持原 legacy 字节和换行风格。
+  - legacy replacement 包含无法用单字节保持的新字符时必须显式拒绝，不能转码整个文件。
 
 `D601:k3s` 或 `G14:k3s` 定位到对应 provider 的原生 k3s 控制面；`<provider>:k3s:<namespace>:<workload>[:container]` 定位到 namespace 下的一个默认 deployment workload；若目标是具体 Pod，标准 workload 段写成 `pod:<podid>`，例如 `D601:k3s:hwlab-v03:pod:hwlab-cloud-api-abc:hwlab-cloud-api`。`pod/<podid>` 不是合法 route 写法，因为 `:` 是分布式路由分隔符，`/` 只表示目标容器里的文件系统 cwd；如果调用者写成 `pod/<podid>/<container>`，CLI 必须在连接运行面前报错并提示改用 `pod:<podid>:<container>` 或 `--container <container>`。若目标是 Deployment，也可以显式写 `deployment:<name>` 或简写 `<name>`；容器选择写 `:<container>` 或 operation 参数 `--container <container>`。pod 内 cwd 推荐用 operation 参数 `--cwd /path`，例如 `D601:k3s:hwlab-dev:hwlab-cloud-api:hwlab-cloud-api exec --cwd /app -- pwd`。`kubectl`、`logs`、`sh`、`bash`、`apply-patch`、旧 `apply-patch-v1` fallback、`exec` 和普通容器命令都是 route 后面的 operation，这样路由子模块和操作子模块可以独立扩展。