docs: prevent stale trans script usage

AGENTS.md

@@ -130,7 +130,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: HWLAB 目标选择必须以 issue/CLI 明确的 lane+node 为准；没有明确目标时才读取 `config/hwlab-node-lanes.yaml` 默认值。node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口、Secret sourceRef 和执行 route 都以 YAML 为 source of truth，禁止把 G14、D601、v0.2 或 v0.3 写成隐藏默认。
 - P0: 每次开始 HWLAB node/lane 分布式开发、切换任务、恢复中断或上下文压缩后，必须先解析目标 node/lane，重新读取目标 workspace 的 `AGENTS.md`，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
 - 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 `trans <node>:/<workspace> ...` 或 workspace route 加 `apply-patch`，远端文本 patch 默认使用 `apply-patch` 的 v2 引擎、旧 helper 仅通过 `apply-patch-v1` 显式调用；k3s 操作用 YAML 解析出的 route，例如 `trans D601:k3s ...` 或 `trans G14:k3s ...`；禁止使用 `ssh <node> k3s ...`，定位必须写在第一个 route token，后续 token 才是 operation。
-- P0: 每次开始 HWLAB node/lane 工作前，目标固定仓库必须先即时快进到目标 remote 分支最新；例如 D601 v0.3 使用 `trans D601:/home/ubuntu/workspace/hwlab-v03 script -- 'git fetch origin v0.3 && git pull --ff-only origin v0.3 && git status --short --branch && git remote -v'`。若有未提交并行变更阻碍快进，必须先判断是否能与最新 remote 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
+- P0: 每次开始 HWLAB node/lane 工作前，目标固定仓库必须先即时快进到目标 remote 分支最新；例如 D601 v0.3 使用 `trans D601:/home/ubuntu/workspace/hwlab-v03 sh -- 'git fetch origin v0.3 && git pull --ff-only origin v0.3 && git status --short --branch && git remote -v'`。若有未提交并行变更阻碍快进，必须先判断是否能与最新 remote 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
 - HWLAB service/runtime 开发必须先以目标 node/lane 固定 repo 做预检，再按目标 lane 创建独立 worktree/PR；CaseRun、短连接 CLI、trace、docs/reference 和配置治理这类无服务任务按目标 repo 规则可直接提交推送，不触发 PR/CI/CD/rollout。
 - P0: G14 已有节点本地 GitHub/Google/DockerHub/npm 等 bootstrap 加速 proxy；在 G14 host、临时 pod、构建 pod 或透传 pod 里拉 GitHub/Google 资源前必须优先使用该 proxy，避免把网络直连失败当作代码阻塞。主入口：HTTP/HTTPS `http://127.0.0.1:10808`、SOCKS `socks5h://127.0.0.1:10808`，备份入口和 NO_PROXY 规则见 `docs/reference/g14.md`。
 - P0: G14 platform PostgreSQL 是 host-native 底层基础设施，HWLAB v0.3+ 通过 namespace-local `g14-platform-postgres` bridge 使用它；迁移后必须清理旧自有 Postgres StatefulSet/Service/ConfigMap/Secret/PVC，长期规则见 `docs/reference/g14-platform-db.md`。
@@ -142,7 +142,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: D601 node-scoped runtime 不是 legacy；当 issue/CLI 明确写出 `目标节点: D601` 和当前 lane（例如 `HWLAB v0.3`）时，必须按 `config/hwlab-node-lanes.yaml` 的 D601 target 进入对应 workspace、k3s route、namespace 和 public endpoint。
 - P0: D601 legacy 只指旧 DEV/迁移/回滚对照路径，例如 `/home/ubuntu/workspace/hwlab-dev`、16666/16667 或历史 `deploy/deploy.json` wrapper；只有 issue/CLI 明确写成 D601 legacy、迁移对照、回滚或旧 DEV 端口排障时才使用。
 - D601 仍是 ConStart/71-FREQ 等 Windows 硬件与 Keil/串口资源的 bridge host；硬件桥接身份不覆盖 D601 node-scoped runtime 身份，二者必须按 issue/CLI 目标区分。
-- 每次确需进入 D601 legacy HWLAB workspace 前，仍必须通过 UniDesk SSH 桥执行 `trans D601:/home/ubuntu/workspace/hwlab-dev script -- 'git status --short --branch && git remote -v'`，并重新读取该目录的 `AGENTS.md`。
+- 每次确需进入 D601 legacy HWLAB workspace 前，仍必须通过 UniDesk SSH 桥执行 `trans D601:/home/ubuntu/workspace/hwlab-dev sh -- 'git status --short --branch && git remote -v'`，并重新读取该目录的 `AGENTS.md`。
 - `/home/ubuntu/workspace/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、`/home/ubuntu/hwlab` runner 历史目录和 master-server checkout 都不能作为 HWLAB 当前开发真相，除非它们正是 YAML 或明确 legacy issue 指定的目标 workspace。
 - 长期细节见 `docs/reference/hwlab.md`。
 
@@ -203,8 +203,9 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 
 ## Critical Trans Shell Boundary Rule
 
-- P0: `trans <route> ...` 后面禁止裸放本地 shell 续接控制符，包括 `&&`、`;` 和 `|`；需要在远端执行多步命令时，必须使用 `trans <route> script -- '远端完整脚本'`、`trans <route> script <<'SCRIPT'` 或等价的单一 stdin/script 参数，避免后半段被本地 shell 执行。`tran` 兼容入口遵守同一规则。`script -- '<单个字符串>'` 会按远端 shell one-liner 执行；`script -- <多个 argv>` 才是 direct argv。`apply-patch`、`apply-patch-v1`、`script`、`py` 等 stdin/capture-backed operation 可以使用 heredoc 或 `< patch.diff` 作为本地输入。
-- P0: Windows PowerShell 透传必须使用 `trans <provider>:win ps <<'PS' ... PS`；`script` 只表示 host/k3s POSIX shell，`cmd` 只表示 Windows cmd.exe/batch，禁止把 ps、cmd、shell 混写成多层 quoting。
+- P0: `trans <route> ...` 后面禁止裸放本地 shell 续接控制符，包括 `&&`、`;` 和 `|`；需要在远端执行多步 POSIX shell 命令时，必须显式选择 shell 方言：`trans <route> sh -- '远端完整脚本'`、`trans <route> bash -- '远端完整脚本'`、`trans <route> sh <<'SH'` 或 `trans <route> bash <<'BASH'`。`tran` 兼容入口遵守同一规则。`script` 和 `shell` operation 已移除并会失败，禁止在新文档、技能、脚本或排障命令中继续使用旧名。`apply-patch`、`apply-patch-v1`、`sh`、`bash`、`py` 等 stdin/capture-backed operation 可以使用 heredoc 或 `< patch.diff` 作为本地输入。
+- P0: 本地 shell 中检索或引用 Markdown 命令片段时，包含反引号的 pattern 必须用单引号、`rg -F -e` 或 stdin/file 传入；禁止把 `` `trans ...` `` 这类文本放进双引号参数，否则 shell 会先执行命令替换，可能误触已移除的 `trans ... script`。
+- P0: Windows PowerShell 透传必须使用 `trans <provider>:win ps <<'PS' ... PS`；host/k3s POSIX shell 必须显式使用 `sh` 或 `bash`，`cmd` 只表示 Windows cmd.exe/batch，禁止把 ps、cmd、shell 混写成多层 quoting。
 - P0: 新增或扩展 `ssh`/`trans`/`tran` 高频 operation 不得把完整实现继续堆进 `scripts/src/ssh.ts`；`ssh.ts` 只保留 route/parser/broker/dispatch，共享能力拆到 `scripts/src/ssh-*.ts` 专门模块，细则见 `docs/reference/cli.md`。
 
 ## Critical Apply Patch Syntax
@@ -217,7 +218,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 
 - P0: `trans <route> ...` 是 `bun scripts/cli.ts ssh <route> ...` 的短 alias，只用于 SSH/WSL/k3s 透传；人工/Codex 远端操作、长期参考、AGENTS 索引、CLI help、非交互脚本和非交互 `exec` 都必须直接调主 server PATH 上的 `/root/.local/bin/trans` wrapper，禁止把 `bun scripts/cli.ts ssh ...`、`bun scripts/cli.ts trans ...` 或任何带 `bun scripts/cli.ts` 前缀的透传写法作为默认入口。普通根 CLI 子命令仍使用 `bun scripts/cli.ts <command>`，分工见 `docs/reference/cli.md`。
 
-- P0: `trans <route>` 的 host workspace 形态必须把已知远端 workspace 写在 route 第一个 token，例如 `trans G14:/root/hwlab-v02 ...`、`trans D601:/home/ubuntu/workspace/unidesk-dev ...`；禁止把 `cd /root/hwlab-v02 && ...` 塞进 `script`/`shell` 字符串或 long-form `bun scripts/cli.ts ssh` 串，长期规则见 `docs/reference/cli.md` 的 Standard Workspace-Prefixed Passthrough。
+- P0: `trans <route>` 的 host workspace 形态必须把已知远端 workspace 写在 route 第一个 token，例如 `trans G14:/root/hwlab-v02 ...`、`trans D601:/home/ubuntu/workspace/unidesk-dev ...`；禁止把 `cd /root/hwlab-v02 && ...` 塞进 `sh`/`bash` 字符串或 long-form `bun scripts/cli.ts ssh` 串，长期规则见 `docs/reference/cli.md` 的 Standard Workspace-Prefixed Passthrough。
 - `bun scripts/cli.ts help`：输出所有可用命令的 JSON 索引，详细规范见 `docs/reference/cli.md`。
 - `bun scripts/cli.ts --main-server-ip <ip> <command>`：默认通过公网 frontend 登录态远程执行调试、用户服务（底层命令名 `microservice`）、Code Queue 查询与节点自测命令，不要求主 server SSH key，详细规范见 `docs/reference/cli.md`。
 - `bun scripts/cli.ts config show`：校验并展示根目录 `config.json`，配置来源规则见 `docs/reference/config.md`。

docs/reference/cli.md

@@ -244,6 +244,8 @@ exec /root/unidesk/scripts/trans "$@"
 
 `trans` 同样遵守 route/operation 解析器；route 后面的第一个 token 不是原生 ssh 命令字符串。带变量展开、管道、重定向或多条命令的远端逻辑，默认使用 `trans G14:/root/hwlab sh <<'SH'`；`sh` 走目标节点 `/bin/sh`，并继承 provider-gateway/G14 已长期化的 proxy 环境。需要 Bash 专有语法，例如 `set -o pipefail`、数组、`[[ ... ]]` 或 `${var:0:8}` 子串展开时，必须把 operation 写成 `bash`，例如 `trans D601:/home/ubuntu/workspace/hwlab-v03 bash <<'BASH'`。需要临时单步执行一行远端 shell 逻辑、且不想先创建脚本文件或 heredoc 时，使用 `trans G14:/root/hwlab sh -- 'sed -n "1,20p" a && sed -n "1,20p" b'` 或 `bash -- '<bash command>'`，CLI 会把单个字符串放进目标节点对应 shell 的 `-c`，第二个 `sed`、管道和重定向都会留在远端；`sh --` 与 `bash --` 只接受一个 shell command 字符串，多 argv 单进程命令必须走 `argv`、`exec` 或已知直接子命令。`script` 和 `shell` operation 已移除并会失败；不得用 `--shell bash` 或旧名绕过显式 shell 选择。`sh` 和 `bash` helper 会在用户 shell 文本前注入一个极小的 POSIX 兼容 `printf` wrapper，使 `printf "--- section ---\n"` 这类高频排障分隔标题在 dash/sh 与 bash 下行为一致；direct argv 形态不注入该 wrapper。单进程命令才直接写成 argv，例如 `trans G14:/root/hwlab git status --short --branch`。遇到分布式开发摩擦时，优先补强 `trans`/`tran` 的 route/operation、stdin helper 或目标节点环境，并把稳定解法写回长期参考文档，不要退回多层 shell 字符串拼接。
 
+本地检索或引用 Markdown 命令片段时也要避免外层 shell 误解析。任何包含反引号的 pattern，例如文档里的 `` `trans ...` ``，都必须用单引号、`rg -F -e` 或 stdin/file 传入；禁止写进双引号参数，因为 shell 会先执行 backtick command substitution，可能在搜索旧文档时反而误触 `trans ... script` 这类已移除 operation。
+
 
 ### Standard Workspace-Prefixed Passthrough