feat: add skill health size check
This commit is contained in:
Codex
@@ -3,351 +3,31 @@ name: unidesk-trans
|
||||
description: UniDesk SSH 透传与 apply-patch 语法 — `trans <route> <operation>` 分布式执行入口，包含 route 语法、workspace/k3s/Windows 路由、apply-patch envelope 格式、sh/bash/py/upload/download operation 和 60s 短连接约束。用户提到 trans、tran、ssh 透传、远端执行、apply-patch、apply_patch、远端 patch、k3s route、workspace route 时使用。
|
||||
---
|
||||
|
||||
# UniDesk Trans（SSH 透传 + apply-patch）
|
||||
# UniDesk Trans
|
||||
|
||||
UniDesk 分布式 SSH 透传入口，统一通过 `trans <route> <operation>` 在远端 host/k3s/Windows 上执行命令或文本 patch。
|
||||
分布式 SSH 透传入口。`trans <route> <operation>` 中 route 只定位目标，后续 token 都属于 operation parser。
|
||||
|
||||
**固定入口**: `trans <route> ...`（wrapper 位于 `/root/.local/bin/trans`，委托 repo 内 ssh-only 启动入口 `bun scripts/ssh-cli.ts ssh "$@"`，避免被无关 CLI 子命令模块解析失败拖垮）
|
||||
|
||||
---
|
||||
|
||||
## Route 语法
|
||||
|
||||
```
|
||||
trans <providerId>[/absolute/workspace] <operation> [args...]
|
||||
trans <providerId>:<plane>[:<namespace>:<resource>[:<container>]] <operation> [args...]
|
||||
```
|
||||
|
||||
### Host workspace route
|
||||
## 高频 route
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab git status --short --branch
|
||||
trans G14:/root/hwlab-v02 sh -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2'
|
||||
trans D601:/home/ubuntu/workspace/unidesk-dev sh <<'SH'
|
||||
...
|
||||
SH
|
||||
```
|
||||
|
||||
**规则**: workspace 路径写在 route 第一个 token，不写进 `cd` 串。反面示例：~~`trans G14 sh -- 'cd /root/hwlab && git status'`~~
|
||||
|
||||
### k3s route
|
||||
|
||||
```bash
|
||||
# 控制面
|
||||
trans G14:k3s kubectl get pods -n hwlab-dev
|
||||
trans D601:/home/ubuntu/workspace/unidesk-dev git status --short --branch
|
||||
trans D601:k3s kubectl get pods -A
|
||||
|
||||
# 指定 namespace + workload
|
||||
trans G14:k3s:hwlab-dev:hwlab-cloud-web:app exec --cwd /app -- cat /app/version.txt
|
||||
trans G14:k3s:hwlab-dev:pod:hwlab-cloud-web-abc:app apply-patch --cwd /workspace <<'PATCH'
|
||||
...
|
||||
PATCH
|
||||
```
|
||||
|
||||
CLI 自动注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`。k3s route 中 `:` 是分布式路由分隔符，`/` 只表示容器内文件系统 cwd；容器选择必须写 `:<container>` 或 operation 参数 `--container <container>`，不要写成 `pod/<pod>/<container>`。
|
||||
|
||||
### Windows route
|
||||
|
||||
```bash
|
||||
trans D601:k3s:namespace:workload[:container] logs --tail 120
|
||||
trans D601:win ps <<'PS'
|
||||
Get-ChildItem C:\test
|
||||
PS
|
||||
|
||||
trans D601:win/c/test cmd cd
|
||||
trans gh:/owner/repo/issue/<number> cat
|
||||
```
|
||||
|
||||
Windows operation 必须显式区分：`ps` 走 PowerShell，`cmd` 走 cmd.exe。
|
||||
Host workspace、k3s、Windows、GitHub issue/PR route，sh/bash/argv/apply-patch/py/upload/download/playwright/kubectl/logs/skills/tcp-pool 操作，以及 apply-patch envelope 语法和 quoting 陷阱见 [references/full.md](references/full.md)。
|
||||
|
||||
### GitHub issue/PR route
|
||||
## P0 边界
|
||||
|
||||
```bash
|
||||
trans gh:/pikasTech/HWLAB/issue ls --state all --limit 20 --search 'YAML-first 测试账号 API_KEY 准备 PJ2026-0105' --full
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 cat
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 rg 'API_KEY|YAML-first'
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 apply-patch <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: body.md
|
||||
@@
|
||||
-old text
|
||||
+new text
|
||||
*** End Patch
|
||||
PATCH
|
||||
```
|
||||
- 远端文本修改优先 `trans <route> apply-patch`；不要 download/upload/sed 拼临时 diff 代替 patch。
|
||||
- `sh`/`bash` 必须显式声明 shell；单进程命令优先 direct argv 或已知 operation。
|
||||
- 普通 trans/ssh 短连接硬预算 60s；长 CI/CD、trace、logs、build、硬件流程必须 submit-and-poll。
|
||||
- Windows route 使用 `win ps` 或 `win cmd`；不要把 POSIX shell 当 Windows shell。
|
||||
|
||||
GitHub issue/PR 正文读写也走 `trans gh:/owner/repo/...`。常见读取优先用 `issue ls --search/--state`、`cat`、`rg`，不要为了看正文先回到 `bun scripts/cli.ts gh issue view --json body --full`；普通小补丁可直接 `apply-patch`，`--dry-run` 只作为高风险正文预览。
|
||||
## 何时读取 reference
|
||||
|
||||
---
|
||||
|
||||
## Operation
|
||||
|
||||
### sh / bash（显式 shell heredoc）
|
||||
|
||||
```bash
|
||||
# POSIX /bin/sh heredoc
|
||||
trans G14:/root/hwlab sh <<'SH'
|
||||
echo "step 1"
|
||||
git status --short --branch
|
||||
echo "step 2"
|
||||
SH
|
||||
|
||||
# Bash heredoc：只有用到 pipefail、数组、[[ ... ]]、${var:0:8} 等 Bash 语法时使用
|
||||
trans G14:/root/hwlab bash <<'BASH'
|
||||
set -euo pipefail
|
||||
short="${GITHUB_SHA:0:8}"
|
||||
printf '%s\n' "$short"
|
||||
BASH
|
||||
|
||||
# one-liner
|
||||
trans G14:/root/hwlab sh -- 'git fetch origin G14 && git pull --ff-only origin G14'
|
||||
|
||||
# 单进程 direct argv 不放在 sh/bash 下，直接用已知子命令或 argv
|
||||
trans D601:/path sed -n '1,20p' AGENTS.md
|
||||
trans D601:/path argv sed -n '1,20p' AGENTS.md
|
||||
```
|
||||
|
||||
`script` 和 `shell` operation 已移除并会失败；必须在 operation 位置明确写 `sh` 或 `bash`，让调用者和 Agent 都知道脚本语法边界。Windows PowerShell 必须用 `ps`。
|
||||
|
||||
### argv（单命令）
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab git status --short --branch
|
||||
trans D601 hostname
|
||||
```
|
||||
|
||||
### apply-patch（远端文本 patch）
|
||||
|
||||
|
||||
- **P0: 所有远端文本/源码修改必须优先使用 `apply-patch`，禁止用 `py`（python3 写文件）或 `sed` heredoc 拼接大段文本替代。** 只有当 apply-patch 本身不可用或需处理非文本/批量机械生成文件时，才使用其他受控方式；使用前必须在注释中说明原因，修改后立即用 `git diff` 或文件尾部检查确认没有截断或污染。
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab apply-patch <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: AGENTS.md
|
||||
@@
|
||||
## Heading
|
||||
context line
|
||||
-old line
|
||||
+new line
|
||||
more context
|
||||
*** End Patch
|
||||
PATCH
|
||||
|
||||
# 从文件读
|
||||
trans G14:/root/hwlab apply-patch < patch.diff
|
||||
```
|
||||
|
||||
v2 引擎（默认）：本地 TypeScript 解析 hunk，远端只读写文件。v1 legacy 入口：`apply-patch-v1`。
|
||||
|
||||
### py（远端 Python 脚本）
|
||||
|
||||
```bash
|
||||
trans D601 py -- arg1 arg2 < script.py
|
||||
```
|
||||
|
||||
自动写到远端临时 `.py` 文件，`python3 -u` 执行后清理。
|
||||
|
||||
### upload / download（整文件传输）
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab upload ./local-file.txt /root/remote-file.txt
|
||||
trans G14:/root/hwlab download /root/remote-file.txt ./local-file.txt
|
||||
```
|
||||
|
||||
自动校验 SHA-256，结果中 `verified=true` 即完整性证明。
|
||||
|
||||
### playwright（远端浏览器验收）
|
||||
|
||||
`trans <route> playwright` 只保留为跨 host 短生命周期浏览器执行和截图/PDF 回传底座。UniDesk/HWLAB Web 开发、HWLAB `web-probe run|script`、fake-server Playwright、fixture 脱敏、截图 artifact 与 Workbench/Performance 判定口径统一见 `$unidesk-webdev`；本 SSH 透传 skill 不维护第二套 Web 测试流程。
|
||||
|
||||
### kubectl / logs（k3s 诊断）
|
||||
|
||||
```bash
|
||||
trans G14:k3s kubectl get pods -n hwlab-dev
|
||||
trans G14:k3s logs deploy/hwlab-cloud-api -n hwlab-dev --tail 50
|
||||
trans G14:k3s:hwlab-dev:hwlab-cloud-web-abc logs --tail 100
|
||||
```
|
||||
|
||||
### skills（远端 skill 发现）
|
||||
|
||||
```bash
|
||||
trans G14 skills [--scope all|wsl|windows] [--limit N]
|
||||
```
|
||||
|
||||
### tcp-pool 状态与并发 smoke
|
||||
|
||||
查看 Provider 是否使用 SSH TCP data pool：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts debug health
|
||||
```
|
||||
|
||||
在输出或 frontend 原始 JSON 里看这些 labels：`providerGatewaySshDataTransport=tcp-pool`、`providerGatewaySshDataPoolReady`、`providerGatewaySshDataPoolClaimed`、`providerGatewaySshDataPoolDesired`、`providerGatewaySshDataPoolLastError`。
|
||||
|
||||
单个 provider 的低噪声池状态：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts debug ssh-pool D601
|
||||
```
|
||||
|
||||
如果 `trans`/`tran` stderr 出现 `UNIDESK_SSH_TCP_POOL_HINT`，优先按其中的 `failureKind` 处理：`provider-data-channel-closed` 表示会话中途 data channel 断开，`provider-data-channel-missing` 表示 core/provider 对 channel 状态不一致，`provider-data-pool-exhausted` 表示没有空闲 channel。对幂等受控操作先查 `debug ssh-pool <provider>`，再重试原受控 CLI；不要把这类 hint 单独定性为远端 runtime 配置失败。
|
||||
|
||||
快速验证 D601 维护桥：
|
||||
|
||||
```bash
|
||||
trans D601 argv true
|
||||
trans D601 argv hostname
|
||||
```
|
||||
|
||||
并发 smoke 用短命令并给每路加本地 timeout：
|
||||
|
||||
```bash
|
||||
tmp=$(mktemp -d /tmp/trans-d601-pool-10.XXXXXX)
|
||||
for i in $(seq 1 10); do
|
||||
timeout 30s trans D601 sh -- 'printf start:'"$i"':%s\\n "$(date +%s%3N)"; sleep 2; printf end:'"$i"':%s\\n "$(date +%s%3N)"' >"$tmp/$i.out" 2>"$tmp/$i.err" &
|
||||
done
|
||||
wait
|
||||
for i in $(seq 1 10); do echo "[$i]"; cat "$tmp/$i.out"; cat "$tmp/$i.err" >&2; done
|
||||
```
|
||||
|
||||
期望是每一路 rc=0、stderr 为空、stdout 同时包含 start/end；结束后 pool labels 回到 `claimed=0`。
|
||||
|
||||
---
|
||||
|
||||
## apply-patch 语法（Envelope 格式）
|
||||
|
||||
**不是 unified diff**，是 Codex 专用 envelope。
|
||||
|
||||
```
|
||||
*** Begin Patch
|
||||
*** Update File: <relative-path>
|
||||
@@
|
||||
context line
|
||||
-old line
|
||||
+new line
|
||||
more context
|
||||
*** End Patch
|
||||
```
|
||||
|
||||
### 关键规则
|
||||
|
||||
| 规则 | 正确 | 错误 |
|
||||
|------|------|------|
|
||||
| 路径必须相对 | `AGENTS.md` | `/root/unidesk/AGENTS.md` |
|
||||
| hunk 分隔符 | `@@` | `@@ -N,M +K,L @@` |
|
||||
| 空行 | ` \n`（空格+换行） | 裸 `\n` |
|
||||
| 首行/尾行 | `*** Begin Patch` / `*** End Patch` | 外层不能有空行 |
|
||||
|
||||
### 操作类型
|
||||
|
||||
```bash
|
||||
*** Update File: path/to/file.ext # 修改现有文件
|
||||
*** Add File: path/to/new.ext # 新增文件（可覆盖已有）
|
||||
*** Delete File: path/to/old.ext # 删除文件
|
||||
*** Move File: old/path -> new/path # 移动/重命名
|
||||
```
|
||||
|
||||
### 上下文定位
|
||||
|
||||
默认 3 行上文 + 3 行下文。同一 hunk 在文件中重复时用 `@@` 跳到 class/function：
|
||||
|
||||
```
|
||||
*** Update File: src/app.ts
|
||||
@@ class MyComponent
|
||||
old context
|
||||
-old code
|
||||
+new code
|
||||
more context
|
||||
```
|
||||
|
||||
### 常见失败
|
||||
|
||||
| 症状 | 原因 | 处理 |
|
||||
|------|------|------|
|
||||
| `failed to find expected lines` | 上下文不匹配（文件已变） | 重读目标块，缩小 hunk |
|
||||
| 空 stdout + stderr 报错 | 首行/路径格式错误 | 检查相对路径、envelope |
|
||||
| partialChanges | 前序 hunk 成功，当前失败 | 基于当前文件状态补小 patch |
|
||||
|
||||
成功 stdout：`Success. Updated the following files:` + 文件列表。失败 stdout 为空，stderr 写原因。
|
||||
|
||||
### 远端 patch 正确姿势
|
||||
|
||||
第一个 route token 直接定位到目标 pod/container，容器内 cwd 用 operation 参数 `--cwd /path`，不要从 host 生成 diff 再改路径上传：
|
||||
|
||||
```bash
|
||||
# ✅ 正确
|
||||
trans G14:k3s:hwlab-dev:pod:hwlab-cloud-web-abc:app apply-patch --cwd /web <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: app.mjs
|
||||
@@
|
||||
-old
|
||||
+new
|
||||
*** End Patch
|
||||
PATCH
|
||||
|
||||
# ❌ 错误：host 生成 diff → 本地 sed 改路径 → 管道到 pod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 60s 硬超时与短连接
|
||||
|
||||
`trans` 有 60 秒硬超时（不可调大）。长任务必须拆成 submit-and-poll：
|
||||
|
||||
```bash
|
||||
# ✅ 异步启动 + 短轮询
|
||||
trans G14:/root/hwlab sh -- 'hwlab-cli case run start d601-f103-v2-compile'
|
||||
trans G14:/root/hwlab sh -- 'hwlab-cli case run status <runId>'
|
||||
|
||||
# ❌ 长时间挂着等
|
||||
trans G14:/root/hwlab sh -- 'long_running_command && wait'
|
||||
```
|
||||
|
||||
### HINT 信号
|
||||
|
||||
| stderr 输出 | 含义 |
|
||||
|-------------|------|
|
||||
| `UNIDESK_SSH_HINT` | SSH 握手/超时摩擦，提示改用 `sh`/`bash` stdin heredoc |
|
||||
| `UNIDESK_TRAN_TIMEOUT_HINT` | 60s 硬超时触发，提示改用短查询+轮询 |
|
||||
| `UNIDESK_SSH_TIMING` | 慢命令 warning（>10s），用于性能回归监控 |
|
||||
| `UNIDESK_APPLY_PATCH_TIMING` | apply-patch 耗时摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 关键约定
|
||||
|
||||
### heredoc 优先
|
||||
|
||||
多行远端脚本优先用 heredoc，不拼接 shell 字符串：
|
||||
|
||||
```bash
|
||||
# ✅ 推荐
|
||||
trans G14:/root/hwlab sh <<'SH'
|
||||
cmd1
|
||||
cmd2
|
||||
SH
|
||||
|
||||
# ❌ 避免
|
||||
trans G14 sh -- 'cmd1 && cmd2 && cmd3'
|
||||
```
|
||||
|
||||
### 本地 shell 运算符陷阱
|
||||
|
||||
`&&` / `;` / `|` 在 `trans` 后面会被本地 shell 截获。需要远端执行多条命令时用 `sh` 或 `bash` 包裹：
|
||||
|
||||
```bash
|
||||
# ❌ 第二个 sed 在 master server 本地执行
|
||||
trans G14:/root/hwlab sed -n '1,20p' a && sed -n '1,20p' b
|
||||
|
||||
# ✅ 两个 sed 都在远端
|
||||
trans G14:/root/hwlab sh -- 'sed -n "1,20p" a && sed -n "1,20p" b'
|
||||
```
|
||||
|
||||
### Windows quoting
|
||||
|
||||
Windows PowerShell heredoc 用单引号 `<<'PS'`：
|
||||
|
||||
```bash
|
||||
trans D601:win ps <<'PS'
|
||||
Write-Output "hello"
|
||||
PS
|
||||
```
|
||||
- 不确定 route 语法、k3s/workspace/Windows 定位时，读 [references/full.md](references/full.md) 的 Route 语法段。
|
||||
- 编写远端 patch 前，读 apply-patch 语法、上下文定位和常见失败段。
|
||||
- 需要 shell heredoc、Python、upload/download、Playwright 或超时处理时，读 Operation 和 60s 段。
|
||||
|
||||
@@ -0,0 +1,353 @@
|
||||
---
|
||||
name: unidesk-trans
|
||||
description: UniDesk SSH 透传与 apply-patch 语法 — `trans <route> <operation>` 分布式执行入口，包含 route 语法、workspace/k3s/Windows 路由、apply-patch envelope 格式、sh/bash/py/upload/download operation 和 60s 短连接约束。用户提到 trans、tran、ssh 透传、远端执行、apply-patch、apply_patch、远端 patch、k3s route、workspace route 时使用。
|
||||
---
|
||||
|
||||
# UniDesk Trans（SSH 透传 + apply-patch）
|
||||
|
||||
UniDesk 分布式 SSH 透传入口，统一通过 `trans <route> <operation>` 在远端 host/k3s/Windows 上执行命令或文本 patch。
|
||||
|
||||
**固定入口**: `trans <route> ...`（wrapper 位于 `/root/.local/bin/trans`，委托 repo 内 ssh-only 启动入口 `bun scripts/ssh-cli.ts ssh "$@"`，避免被无关 CLI 子命令模块解析失败拖垮）
|
||||
|
||||
---
|
||||
|
||||
## Route 语法
|
||||
|
||||
```
|
||||
trans <providerId>[/absolute/workspace] <operation> [args...]
|
||||
trans <providerId>:<plane>[:<namespace>:<resource>[:<container>]] <operation> [args...]
|
||||
```
|
||||
|
||||
### Host workspace route
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab git status --short --branch
|
||||
trans G14:/root/hwlab-v02 sh -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2'
|
||||
trans D601:/home/ubuntu/workspace/unidesk-dev sh <<'SH'
|
||||
...
|
||||
SH
|
||||
```
|
||||
|
||||
**规则**: workspace 路径写在 route 第一个 token，不写进 `cd` 串。反面示例：~~`trans G14 sh -- 'cd /root/hwlab && git status'`~~
|
||||
|
||||
### k3s route
|
||||
|
||||
```bash
|
||||
# 控制面
|
||||
trans G14:k3s kubectl get pods -n hwlab-dev
|
||||
trans D601:k3s kubectl get pods -A
|
||||
|
||||
# 指定 namespace + workload
|
||||
trans G14:k3s:hwlab-dev:hwlab-cloud-web:app exec --cwd /app -- cat /app/version.txt
|
||||
trans G14:k3s:hwlab-dev:pod:hwlab-cloud-web-abc:app apply-patch --cwd /workspace <<'PATCH'
|
||||
...
|
||||
PATCH
|
||||
```
|
||||
|
||||
CLI 自动注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`。k3s route 中 `:` 是分布式路由分隔符，`/` 只表示容器内文件系统 cwd；容器选择必须写 `:<container>` 或 operation 参数 `--container <container>`，不要写成 `pod/<pod>/<container>`。
|
||||
|
||||
### Windows route
|
||||
|
||||
```bash
|
||||
trans D601:win ps <<'PS'
|
||||
Get-ChildItem C:\test
|
||||
PS
|
||||
|
||||
trans D601:win/c/test cmd cd
|
||||
```
|
||||
|
||||
Windows operation 必须显式区分：`ps` 走 PowerShell，`cmd` 走 cmd.exe。
|
||||
|
||||
### GitHub issue/PR route
|
||||
|
||||
```bash
|
||||
trans gh:/pikasTech/HWLAB/issue ls --state all --limit 20 --search 'YAML-first 测试账号 API_KEY 准备 PJ2026-0105' --full
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 cat
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 rg 'API_KEY|YAML-first'
|
||||
trans gh:/pikasTech/HWLAB/issue/1236 apply-patch <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: body.md
|
||||
@@
|
||||
-old text
|
||||
+new text
|
||||
*** End Patch
|
||||
PATCH
|
||||
```
|
||||
|
||||
GitHub issue/PR 正文读写也走 `trans gh:/owner/repo/...`。常见读取优先用 `issue ls --search/--state`、`cat`、`rg`，不要为了看正文先回到 `bun scripts/cli.ts gh issue view --json body --full`；普通小补丁可直接 `apply-patch`，`--dry-run` 只作为高风险正文预览。
|
||||
|
||||
---
|
||||
|
||||
## Operation
|
||||
|
||||
### sh / bash（显式 shell heredoc）
|
||||
|
||||
```bash
|
||||
# POSIX /bin/sh heredoc
|
||||
trans G14:/root/hwlab sh <<'SH'
|
||||
echo "step 1"
|
||||
git status --short --branch
|
||||
echo "step 2"
|
||||
SH
|
||||
|
||||
# Bash heredoc：只有用到 pipefail、数组、[[ ... ]]、${var:0:8} 等 Bash 语法时使用
|
||||
trans G14:/root/hwlab bash <<'BASH'
|
||||
set -euo pipefail
|
||||
short="${GITHUB_SHA:0:8}"
|
||||
printf '%s\n' "$short"
|
||||
BASH
|
||||
|
||||
# one-liner
|
||||
trans G14:/root/hwlab sh -- 'git fetch origin G14 && git pull --ff-only origin G14'
|
||||
|
||||
# 单进程 direct argv 不放在 sh/bash 下，直接用已知子命令或 argv
|
||||
trans D601:/path sed -n '1,20p' AGENTS.md
|
||||
trans D601:/path argv sed -n '1,20p' AGENTS.md
|
||||
```
|
||||
|
||||
`script` 和 `shell` operation 已移除并会失败；必须在 operation 位置明确写 `sh` 或 `bash`，让调用者和 Agent 都知道脚本语法边界。Windows PowerShell 必须用 `ps`。
|
||||
|
||||
### argv（单命令）
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab git status --short --branch
|
||||
trans D601 hostname
|
||||
```
|
||||
|
||||
### apply-patch（远端文本 patch）
|
||||
|
||||
|
||||
- **P0: 所有远端文本/源码修改必须优先使用 `apply-patch`，禁止用 `py`（python3 写文件）或 `sed` heredoc 拼接大段文本替代。** 只有当 apply-patch 本身不可用或需处理非文本/批量机械生成文件时，才使用其他受控方式；使用前必须在注释中说明原因，修改后立即用 `git diff` 或文件尾部检查确认没有截断或污染。
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab apply-patch <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: AGENTS.md
|
||||
@@
|
||||
## Heading
|
||||
context line
|
||||
-old line
|
||||
+new line
|
||||
more context
|
||||
*** End Patch
|
||||
PATCH
|
||||
|
||||
# 从文件读
|
||||
trans G14:/root/hwlab apply-patch < patch.diff
|
||||
```
|
||||
|
||||
v2 引擎（默认）：本地 TypeScript 解析 hunk，远端只读写文件。v1 legacy 入口：`apply-patch-v1`。
|
||||
|
||||
### py（远端 Python 脚本）
|
||||
|
||||
```bash
|
||||
trans D601 py -- arg1 arg2 < script.py
|
||||
```
|
||||
|
||||
自动写到远端临时 `.py` 文件，`python3 -u` 执行后清理。
|
||||
|
||||
### upload / download（整文件传输）
|
||||
|
||||
```bash
|
||||
trans G14:/root/hwlab upload ./local-file.txt /root/remote-file.txt
|
||||
trans G14:/root/hwlab download /root/remote-file.txt ./local-file.txt
|
||||
```
|
||||
|
||||
自动校验 SHA-256，结果中 `verified=true` 即完整性证明。
|
||||
|
||||
### playwright（远端浏览器验收）
|
||||
|
||||
`trans <route> playwright` 只保留为跨 host 短生命周期浏览器执行和截图/PDF 回传底座。UniDesk/HWLAB Web 开发、HWLAB `web-probe run|script`、fake-server Playwright、fixture 脱敏、截图 artifact 与 Workbench/Performance 判定口径统一见 `$unidesk-webdev`；本 SSH 透传 skill 不维护第二套 Web 测试流程。
|
||||
|
||||
### kubectl / logs（k3s 诊断）
|
||||
|
||||
```bash
|
||||
trans G14:k3s kubectl get pods -n hwlab-dev
|
||||
trans G14:k3s logs deploy/hwlab-cloud-api -n hwlab-dev --tail 50
|
||||
trans G14:k3s:hwlab-dev:hwlab-cloud-web-abc logs --tail 100
|
||||
```
|
||||
|
||||
### skills（远端 skill 发现）
|
||||
|
||||
```bash
|
||||
trans G14 skills [--scope all|wsl|windows] [--limit N]
|
||||
```
|
||||
|
||||
### tcp-pool 状态与并发 smoke
|
||||
|
||||
查看 Provider 是否使用 SSH TCP data pool：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts debug health
|
||||
```
|
||||
|
||||
在输出或 frontend 原始 JSON 里看这些 labels：`providerGatewaySshDataTransport=tcp-pool`、`providerGatewaySshDataPoolReady`、`providerGatewaySshDataPoolClaimed`、`providerGatewaySshDataPoolDesired`、`providerGatewaySshDataPoolLastError`。
|
||||
|
||||
单个 provider 的低噪声池状态：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts debug ssh-pool D601
|
||||
```
|
||||
|
||||
如果 `trans`/`tran` stderr 出现 `UNIDESK_SSH_TCP_POOL_HINT`，优先按其中的 `failureKind` 处理：`provider-data-channel-closed` 表示会话中途 data channel 断开，`provider-data-channel-missing` 表示 core/provider 对 channel 状态不一致，`provider-data-pool-exhausted` 表示没有空闲 channel。对幂等受控操作先查 `debug ssh-pool <provider>`，再重试原受控 CLI；不要把这类 hint 单独定性为远端 runtime 配置失败。
|
||||
|
||||
快速验证 D601 维护桥：
|
||||
|
||||
```bash
|
||||
trans D601 argv true
|
||||
trans D601 argv hostname
|
||||
```
|
||||
|
||||
并发 smoke 用短命令并给每路加本地 timeout：
|
||||
|
||||
```bash
|
||||
tmp=$(mktemp -d /tmp/trans-d601-pool-10.XXXXXX)
|
||||
for i in $(seq 1 10); do
|
||||
timeout 30s trans D601 sh -- 'printf start:'"$i"':%s\\n "$(date +%s%3N)"; sleep 2; printf end:'"$i"':%s\\n "$(date +%s%3N)"' >"$tmp/$i.out" 2>"$tmp/$i.err" &
|
||||
done
|
||||
wait
|
||||
for i in $(seq 1 10); do echo "[$i]"; cat "$tmp/$i.out"; cat "$tmp/$i.err" >&2; done
|
||||
```
|
||||
|
||||
期望是每一路 rc=0、stderr 为空、stdout 同时包含 start/end；结束后 pool labels 回到 `claimed=0`。
|
||||
|
||||
---
|
||||
|
||||
## apply-patch 语法（Envelope 格式）
|
||||
|
||||
**不是 unified diff**，是 Codex 专用 envelope。
|
||||
|
||||
```
|
||||
*** Begin Patch
|
||||
*** Update File: <relative-path>
|
||||
@@
|
||||
context line
|
||||
-old line
|
||||
+new line
|
||||
more context
|
||||
*** End Patch
|
||||
```
|
||||
|
||||
### 关键规则
|
||||
|
||||
| 规则 | 正确 | 错误 |
|
||||
|------|------|------|
|
||||
| 路径必须相对 | `AGENTS.md` | `/root/unidesk/AGENTS.md` |
|
||||
| hunk 分隔符 | `@@` | `@@ -N,M +K,L @@` |
|
||||
| 空行 | ` \n`（空格+换行） | 裸 `\n` |
|
||||
| 首行/尾行 | `*** Begin Patch` / `*** End Patch` | 外层不能有空行 |
|
||||
|
||||
### 操作类型
|
||||
|
||||
```bash
|
||||
*** Update File: path/to/file.ext # 修改现有文件
|
||||
*** Add File: path/to/new.ext # 新增文件（可覆盖已有）
|
||||
*** Delete File: path/to/old.ext # 删除文件
|
||||
*** Move File: old/path -> new/path # 移动/重命名
|
||||
```
|
||||
|
||||
### 上下文定位
|
||||
|
||||
默认 3 行上文 + 3 行下文。同一 hunk 在文件中重复时用 `@@` 跳到 class/function：
|
||||
|
||||
```
|
||||
*** Update File: src/app.ts
|
||||
@@ class MyComponent
|
||||
old context
|
||||
-old code
|
||||
+new code
|
||||
more context
|
||||
```
|
||||
|
||||
### 常见失败
|
||||
|
||||
| 症状 | 原因 | 处理 |
|
||||
|------|------|------|
|
||||
| `failed to find expected lines` | 上下文不匹配（文件已变） | 重读目标块，缩小 hunk |
|
||||
| 空 stdout + stderr 报错 | 首行/路径格式错误 | 检查相对路径、envelope |
|
||||
| partialChanges | 前序 hunk 成功，当前失败 | 基于当前文件状态补小 patch |
|
||||
|
||||
成功 stdout：`Success. Updated the following files:` + 文件列表。失败 stdout 为空，stderr 写原因。
|
||||
|
||||
### 远端 patch 正确姿势
|
||||
|
||||
第一个 route token 直接定位到目标 pod/container，容器内 cwd 用 operation 参数 `--cwd /path`，不要从 host 生成 diff 再改路径上传：
|
||||
|
||||
```bash
|
||||
# ✅ 正确
|
||||
trans G14:k3s:hwlab-dev:pod:hwlab-cloud-web-abc:app apply-patch --cwd /web <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: app.mjs
|
||||
@@
|
||||
-old
|
||||
+new
|
||||
*** End Patch
|
||||
PATCH
|
||||
|
||||
# ❌ 错误：host 生成 diff → 本地 sed 改路径 → 管道到 pod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 60s 硬超时与短连接
|
||||
|
||||
`trans` 有 60 秒硬超时（不可调大）。长任务必须拆成 submit-and-poll：
|
||||
|
||||
```bash
|
||||
# ✅ 异步启动 + 短轮询
|
||||
trans G14:/root/hwlab sh -- 'hwlab-cli case run start d601-f103-v2-compile'
|
||||
trans G14:/root/hwlab sh -- 'hwlab-cli case run status <runId>'
|
||||
|
||||
# ❌ 长时间挂着等
|
||||
trans G14:/root/hwlab sh -- 'long_running_command && wait'
|
||||
```
|
||||
|
||||
### HINT 信号
|
||||
|
||||
| stderr 输出 | 含义 |
|
||||
|-------------|------|
|
||||
| `UNIDESK_SSH_HINT` | SSH 握手/超时摩擦，提示改用 `sh`/`bash` stdin heredoc |
|
||||
| `UNIDESK_TRAN_TIMEOUT_HINT` | 60s 硬超时触发，提示改用短查询+轮询 |
|
||||
| `UNIDESK_SSH_TIMING` | 慢命令 warning（>10s），用于性能回归监控 |
|
||||
| `UNIDESK_APPLY_PATCH_TIMING` | apply-patch 耗时摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 关键约定
|
||||
|
||||
### heredoc 优先
|
||||
|
||||
多行远端脚本优先用 heredoc，不拼接 shell 字符串：
|
||||
|
||||
```bash
|
||||
# ✅ 推荐
|
||||
trans G14:/root/hwlab sh <<'SH'
|
||||
cmd1
|
||||
cmd2
|
||||
SH
|
||||
|
||||
# ❌ 避免
|
||||
trans G14 sh -- 'cmd1 && cmd2 && cmd3'
|
||||
```
|
||||
|
||||
### 本地 shell 运算符陷阱
|
||||
|
||||
`&&` / `;` / `|` 在 `trans` 后面会被本地 shell 截获。需要远端执行多条命令时用 `sh` 或 `bash` 包裹：
|
||||
|
||||
```bash
|
||||
# ❌ 第二个 sed 在 master server 本地执行
|
||||
trans G14:/root/hwlab sed -n '1,20p' a && sed -n '1,20p' b
|
||||
|
||||
# ✅ 两个 sed 都在远端
|
||||
trans G14:/root/hwlab sh -- 'sed -n "1,20p" a && sed -n "1,20p" b'
|
||||
```
|
||||
|
||||
### Windows quoting
|
||||
|
||||
Windows PowerShell heredoc 用单引号 `<<'PS'`：
|
||||
|
||||
```bash
|
||||
trans D601:win ps <<'PS'
|
||||
Write-Output "hello"
|
||||
PS
|
||||
```
|
||||
Reference in New Issue
Block a user