docs: 固化高频帮助输出边界
This commit is contained in:
Codex
@@ -31,6 +31,11 @@ Host workspace、k3s、Windows、GitHub issue/PR route 见 [references/routes.md
|
||||
|
||||
## P0 边界
|
||||
|
||||
- `trans --help` 是高频直接阅读入口：
|
||||
- 顶层只展示 route 语法、operation 分组和 `trans --help <operation>` 下钻索引。
|
||||
- 顶层与 scoped help 都必须有界且直接返回；出现 `outputTruncated` 或 dump 即视为 CLI 缺陷。
|
||||
- 修复帮助过长时必须收敛信息结构，禁止提高 stdout 阈值。
|
||||
- dump 只允许用于显式 `--full`、`--raw` 或确实无法预先界定的一次性异常证据。
|
||||
- 远端文本修改优先 `trans <route> apply-patch`；不要 download/upload/sed 拼临时 diff 代替 patch。
|
||||
- `upload` / `download` 仅用于必要的二进制文件或生成物：
|
||||
- 远端文本读取优先使用 `cat` / `rg`；
|
||||
|
||||
@@ -2,6 +2,12 @@
|
||||
|
||||
UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式固定为 `bun scripts/cli.ts <command>`；普通根 CLI 子命令仍使用该入口。`trans <route> ...` 是 SSH/WSL/k3s 透传专用入口，wrapper 委托轻量 `scripts/ssh-cli.ts` 启动链路，避免被无关根 CLI 子命令模块的解析或语法错误拖垮；长期参考文档、AGENTS 索引、CLI help 和人工远端操作示例都必须优先写 `trans ...`，不得再把 `bun scripts/cli.ts ssh ...` 作为默认透传入口。面向人工的默认输出采用 Kubernetes 风格的简洁表格、短摘要和 drill-down 命令；JSON 只用于 `--json`、`--raw`、`--full`、`-o json` 或其他明确机器消费模式。所有成功和失败路径仍必须给出可判定状态，避免无输出造成不可观测。
|
||||
|
||||
- 高频 CLI 默认输出与帮助输出是直接阅读入口：
|
||||
- 必须保持有界、低噪声并直接展示，不得触发 `outputTruncated` 或 `/tmp/unidesk-cli-output` dump。
|
||||
- 顶层帮助只展示分组索引和可执行的下钻命令，详细合同通过 `<command> --help <operation>` 或等价 scoped help 获取。
|
||||
- 默认输出或帮助输出触发 dump 视为 CLI 缺陷，必须收敛信息结构，禁止用提高 stdout 阈值掩盖。
|
||||
- dump 只允许用于用户显式请求的 `--full`、`--raw`、机器完整输出，或确实无法预先界定的一次性异常证据。
|
||||
|
||||
主 server 必须在 PATH 上提供 `/root/.local/bin/trans` 可执行 wrapper，内容委托 repo 内版本化 `scripts/trans` 并执行 `bun scripts/ssh-cli.ts ssh "$@"`；交互 shell 可额外提供 alias，但非交互 Codex `exec` 和脚本不能依赖 alias 展开。
|
||||
|
||||
主 server 固定提供 PATH 可见的 `/usr/local/bin/unidesk`，委托版本化 `scripts/unidesk` 执行根 CLI；`/root/.local/bin/unidesk` 可以保留为用户级兼容链接，但不能作为非交互入口的唯一安装位置。高频人工入口优先写 `unidesk <command>`；仓库内验证和未安装 wrapper 的 checkout 使用等价的 `bun scripts/cli.ts <command>`。
|
||||
@@ -274,7 +280,7 @@ GitHub issue/PR 正文局部修补必须优先使用 `trans gh:/owner/repo/issue
|
||||
|
||||
`trans <providerId> [ssh-like args...]` 是面向人的终端透传入口，不包装 JSON 输出，默认由 `scripts/ssh-cli.ts` 只加载 SSH/route/远程前端转发相关模块。主 server 本地执行时会在宿主机启动 `docker exec -i unidesk-backend-core backend-core --ssh-broker ...`，broker 只连接 backend-core 的 Docker 内网 `/ws/ssh`；core 使用 provider WebSocket 下发 open/dispatch 控制消息，但 stdin/stdout/stderr 数据面必须走 provider 主动连接 main server 的 `host.ssh.tcp-pool` TCP warm pool，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 `ssh -tt`，带远端命令的会话使用 `ssh -T`；`apply-patch`、脚本 stdin、`py` 和旧 `apply-patch-v1` fallback 这类命令模式不得被伪终端回显或注入控制字符。该入口不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的业务边界；provider data TCP port 是 provider 主动连入的数据面端口，不是计算节点入站要求。
|
||||
|
||||
`trans --help` 和 `trans <providerId> --help` 是本地 JSON 帮助命令，必须快速返回；不能把 `--help` 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。
|
||||
`trans --help` 和 `trans <providerId> --help` 是本地 JSON 帮助命令，必须快速返回；不能把 `--help` 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。顶层只展示 route 语法、operation 分组和 scoped help 索引；operation 细节通过 `trans --help <operation>` 获取。任一默认帮助触发 `outputTruncated` 或 dump 都是缺陷，必须缩减顶层内容，禁止提高 stdout 阈值。
|
||||
|
||||
主 server 固定提供 `trans` 缩写，等价于 `bun scripts/ssh-cli.ts ssh "$@"` 的受控 UniDesk SSH 透传入口。这里必须同时保留两层入口：交互式 shell 可额外配置 alias；Codex `exec`、脚本和其他非交互 shell 不会自动展开 alias，所以还必须有 `/root/.local/bin/trans` 可执行 wrapper，内容固定为委托 repo 内版本化脚本：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user