UniDesk CLI Reference

UniDesk 的统一 CLI 入口是根目录 scripts/cli.ts，运行方式固定为 bun scripts/cli.ts <command>。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。

CLI 可以从 master 快速演进，但必须兼容 deploy.json 固定的 CI/CD server 和生产运行面。CLI/server 能力协商、unsupported-version 失败语义和 release-line 边界由 docs/reference/release-governance.md 与 GitHub issue #6 约束。

Command Model

help 输出命令索引，适合作为交互式入口。
每个 CLI 命名空间必须支持 help、--help 或 -h 并返回 JSON，不得为了打印帮助而访问 runtime 服务、拉起交互会话或执行长时任务。
--main-server-ip <ip> <command> 默认通过公网 frontend 登录态调用主 server 的同源 API 代理，不要求计算节点持有主 server SSH key；显式提供 --main-server-key 或 --main-server-transport ssh 时才使用旧 SSH 传输。
config show 读取并校验根目录 config.json，不从环境变量、默认值或隐藏文件静默补配置。
check 默认只执行轻量配置校验、Bun 版本检查和 Bun Transpiler 语法解析（覆盖 CLI 入口、主要 scripts/ 模块和核心组件入口，不做类型推导）；关键文件存在性、scripts/ TypeScript 类型检查、src/components/ TypeScript 类型检查、Docker Compose config 和日志轮转策略扫描默认不启用，分别通过 --files、--scripts-typecheck、--components、--compose、--logs 开启，或用 --full 一次性开启。--rust 只允许在 D601 CI/dev execution 中配合 UNIDESK_D601_RUST_CHECK=1 使用，长期规则见 docs/reference/dev-environment.md。
server start 创建异步 job，在后台执行 Docker 构建和启动；命令本身只负责返回 job id、日志路径和启动命令。
server stop 创建异步 job，在后台停止固定 Compose project 中的全部 UniDesk 服务。
server status 查询公开端口、受限宿主端口、内部端口、主机 swap 摘要、Compose 容器、core/frontend/dev-frontend/provider/database 健康检查和访问 URL；D601 Code Queue 使用的 PostgreSQL/OA Event Flow host mapping 必须出现在受限宿主端口而不是无条件公开入口中。低内存主 server 上 swap.warning 非空时，先执行 server swap status 或 server swap ensure。
server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run] 是主 server swap 管理入口。status 仅读 /proc/meminfo、/proc/swaps 和 /etc/fstab 并返回 JSON；ensure 在已有任何 active swap 时只报告 no-op，在无 active swap 时创建固定 swapfile、chmod 600、mkswap、swapon 并尽量写入 /etc/fstab。输出必须包含 before、after、total memory、active swap、持久化状态、关键动作和错误详情；若 swap 已启用但 fstab 写入失败，状态为 degraded，调用者需按返回的 detail 修复持久化。
server logs 返回 logs/ 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。实现必须只读取文件末尾字节，不得为了 tail 先把巨大日志完整读入 CLI 内存。
server cleanup plan [--min-age-hours N] [--limit N] 只生成主 server Docker 镜像清理 dry-run 计划，不执行删除；默认 --min-age-hours 24，避免把刚发布或刚验证的镜像列为 stale。输出必须包含 dryRun=true、mutation=false、policy.deletionExecuted=false、active containers/images、受保护镜像、candidate stale images、估算释放空间、风险等级、commandsToReview 和人工审批清单。计划必须保守白名单：保留 running containers 使用的 image ID，保留 stopped containers 引用的 image ID 直到人工先复核容器，保留 deploy.json/CI.json 当前 commit-pinned artifact、Compose stable image、上游 digest pin 和 provider-gateway runner image；protectedStorage 必须显式列出 PostgreSQL named volume、Baidu Netdisk .state、D601 registry storage 和 Docker volumes/host data policy。该入口禁止生成或执行 docker system prune、docker image prune、docker builder prune、docker volume rm、docker compose down -v、数据库清理或 host data rm 命令；未来若增加真实删除，必须另设显式审批参数并先复核 dry-run 输出。
server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow> 创建异步 job，先构建目标服务镜像，随后在 .state/locks/server-compose.lock 串行保护下用 --no-deps --force-recreate 替换目标 service 并等待容器 healthy/running；该命令用于替代手工删除容器的兜底流程，其中 dev-frontend-proxy 只更新主 server dev 入口薄代理，todo-note、code-queue-mgr、project-manager、baidu-netdisk 和 oa-event-flow 只重建主 server 承载的对应后端，不会重建或删除 database 命名卷。D601 Code Queue 执行面不由 server rebuild 管理，Rust backend-core 迭代不得用 server rebuild backend-core 在 master server 编译，规则见 docs/reference/dev-environment.md。
provider attach <providerId> [--master-server URL] [--up] [--force] 在新计算节点生成两项配置的 provider-gateway 挂载包：.state/provider-<ID>.env 默认只包含 UNIDESK_MASTER_SERVER 与 PROVIDER_ID，provider-<ID>.yml 固定 Docker socket、pid: "host"、restart: always、只读 /workspace 和 SSH 维护私钥挂载；--up 会立即执行生成的 docker compose up -d --build。provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw] 是只读多信号健康裁决入口，会把单路径 provider is not online、SSH 超时、registry 失败和 service proxy 失败归类成 runner-local-observation-gap、service-degraded、provider-degraded 或 global-blocker。默认输出只返回裁决、scope、失败/降级/未知信号和有界 evidence 摘要，完整 evidence 必须显式加 --full 或 --raw；推荐交叉验证命令仍包含 debug health、debug dispatch <providerId> host.ssh --wait-ms 15000、ssh <providerId> argv true、artifact-registry health --provider-id <providerId>、microservice health k3sctl-adapter、microservice health code-queue 和 codex tasks --view supervisor --limit 20。
ssh <providerId> [ssh-like args...] 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；无后续参数时进入远端登录 shell，有后续参数时按 ssh 远端命令体验执行并返回远端 exit code。
ssh <providerId> apply-patch [tool args...] < patch.diff 直接调用远端注入的 apply_patch 工具，并把本地 stdin 中的标准 *** Begin Patch / *** End Patch patch 流透传给目标节点。
ssh <providerId> py [script-args...] < script.py 把本地 stdin 落到远端临时 .py 文件后再以 python3 -u 执行并自动清理，避免再手写 'python3 -'、heredoc 或多层引号；script-args 会按 argv 安全透传给远端脚本。
ssh <providerId> skills [--scope all|wsl|windows] [--limit N] 发现目标节点上的 WSL/Linux skill 根目录；当 provider 是 WSL 时同一次调用还会扫描 Windows 用户目录下的 .agents/skills 与 .codex/skills。
microservice list/status/health/diagnostics/tunnel-self-test/proxy 通过 backend-core 内网 API 管理挂载在计算节点 Docker 或 k3s 控制面中的用户服务（底层命令名仍为 microservice）；health、status 和 diagnostics 默认返回 compact summary、body 字节数和 --full|--raw 展开命令，只有小 body 或无法抽取 summary 时才带有界 body preview，避免 Code Queue/k3s 诊断一次性输出爆炸；tunnel-self-test 和 proxy 会走真实 backend-core -> provider-gateway 或 k3sctl-adapter -> 节点服务链路，proxy 支持受控 JSON 请求体并对超大响应 body 默认输出有界预览，规则见 docs/reference/microservices.md。
decision upload/list/show/health 通过 backend-core 用户服务代理访问 D601 k3s Decision Center，用于上传会议记录/决议 Markdown、列出权威记录、查看详情和健康检查；decision list 默认只返回摘要并省略完整 Markdown body，需要排查大正文时显式加 --include-body。正式文书字段通过 records 模型一等字段返回和查询：--doc-no DC-...、--doc-type DCSN|GOAL|PLAN|RPRT|ACTN|ISSU|RETR|RQST|RESP|MINS、--doc-priority P0|P1|P2|P3、--year YYYY、--signer、--issued-at、--effective-scope、--supersedes、--superseded-by；show 和 requirement update 可使用 id 或 docNo。decision requirement list/create/upsert/update/show 在同一 records 模型上管理 goal|decision|blocker|debt|experiment 需求记录，docNo 唯一，未传 --doc-no 但提供 --doc-type/--doc-priority/--year 时由服务分配下一个序号。它们不得直连 D601 Service、NodePort 或 provider-gateway 业务 HTTP。
decision diary import <markdown-file> 将带 # YYYY年M月D日、# YYYY-MM-DD 或 # YYYY/M/D 标题的工作日志拆成每天一篇 Markdown 日记，按 YYYY-MM/YYYY-MM-DD.md 虚拟路径写入 Decision Center PostgreSQL；decision diary list/history 默认只返回摘要，需要完整 Markdown 时显式加 --include-body；decision diary show <YYYY-MM-DD|id> [--source-file path] 查看单日正文，--source-file 用于同一天存在多个导入来源时精确选择；decision diary edit|upsert <YYYY-MM-DD|id> --body-file <path> [--title text] [--source-file path] [--tag tag] 通过 PUT /api/diary/entries/:idOrDate 创建当天或历史条目并编辑既有条目。
deploy check/plan/apply 默认从根目录 deploy.json 读取服务 repo 与 commit 期望状态，join config.json 和现有 manifest 后使用 target-side build 或 reviewed artifact consumer 校验/更新已支持目标；deploy plan --env dev|prod 只从 origin/master:deploy.json#environments.<env> 读取 manifest 并输出 dry-run 环境计划，不使用本地 dirty worktree；当前 deploy apply --env dev 支持 backend-core、frontend、baidu-netdisk、decision-center、mdtodo、claudeqq 和 dev-only code-queue artifact consumers，findjob/pipeline/met-nonlinear 为 D601 direct Compose artifact consumers，k3sctl-adapter 只提供 plan/dry-run；dev desired-state smoke 使用 ci run-dev-e2e；规则见 docs/reference/deploy.md、docs/reference/dev-environment.md 和 docs/reference/dev-ci-runner.md。deploy apply --env prod 同时覆盖 findjob 和 pipeline 的 pull-only Compose CD，但 met-nonlinear 仍然只允许 dry-run/plan，k3sctl-adapter 只允许 plan/dry-run。
dev-env validate [--manifest path] [--kubectl-dry-run] 离线校验 D601 unidesk-dev namespace、dev PostgreSQL 底座和 dev workload manifest。默认检查 src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-foundation.k8s.yaml；也可显式校验 src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml 或 src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-code-queue.k8s.yaml。所有 namespaced 对象必须只落到 unidesk-dev，foundation manifest 必须包含 postgres-dev StatefulSet/Service、dev secret/config、迁移 Job 和 DB URL guard，core manifest 必须包含 backend-core-dev/frontend-dev Deployment/Service，Code Queue dev manifest 必须包含 code-queue-scheduler-dev、code-queue-read-dev、code-queue-write-dev、dev provider egress proxy，以及只读挂载宿主 /home/ubuntu/.agents/skills 到容器 /root/.agents/skills 的 skills-dir volume。加 --kubectl-dry-run 时额外执行 kubectl apply --dry-run=client --validate=false -f <manifest>，仍不 apply 资源。
dev-env prewarm-images [--image image] [--provider-id D601] [--no-pull] [--proxy-url URL] [--pull-timeout-ms N] [--dry-run] 创建异步 job，通过 UniDesk SSH 维护桥在 D601 上把开发底座依赖镜像从 Docker 缓存导入原生 k3s containerd。默认镜像是 postgres:16-alpine 和 rancher/mirrored-library-busybox:1.36.1，用于避免 postgres-dev 与 local-path helper pod 卡在外部 registry 拉取。该命令固定验证 /etc/rancher/k3s/k3s.yaml 指向的 native k3s 上下文，并输出 dev_env_containerd_image_ready=... 作为成功判据；它不 apply manifest、不修改生产 unidesk namespace。
artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service 管理 D601 host-managed CNCF Distribution registry 的声明、安装、只读检查和 pull-only artifact CD。该 registry 固定为 D601 loopback 127.0.0.1:5000，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；deploy-service 只拉取 CI 已发布的 commit-pinned 镜像、retag/recreate 或导入 native k3s，并做 live commit 验证，不构建 runtime source。deploy-backend-core 是 deprecated 兼容名，标准 backend-core prod CD 入口是 deploy apply --env prod --service backend-core。长期规则见 docs/reference/artifact-registry.md。
commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run 是 host Codex 指挥官直管微服务 skeleton 入口。当前命令返回 phase=source-contract、service/API/state/bridge/prompt/trace/#20/#46/ClaudeQQ 审批边界、.state/commander/ 状态模型、dev 无 daemon smoke contract 和 dry-run 计划，服务骨架只提供本地 /health、/api/commander/contract、状态读写、trace summary 聚合和 approval draft preview，不接 live bridge、不注入 prompt、不发送 ClaudeQQ。plan、smoke 与 approval request 必须带 --dry-run；缺少时返回 error=dry-run-required。长期规则见 docs/reference/host-codex-commander.md。
gh auth status [--repo owner/name] 探测 GitHub 操作前置条件并输出脱敏 JSON：是否存在 gh binary、是否存在 GH_TOKEN/GITHUB_TOKEN 或可用 gh auth token fallback、REST API 是否可达、目标 repo 是否可见、issue 是否可读。degraded reason 必须归类为 missing-binary、missing-token、auth-failed、network-proxy-failed、permission-denied、repo-not-found、repo-forbidden、issue-not-found、pr-not-found、scope-insufficient、validation-failed、invalid-response 或 unsupported-command，不得打印 token；失败对象必须包含 runnerDisposition=infra-blocked|business-failed，runner 应优先用该字段分流。
gh issue list [--state open|closed|all] [--limit N] [--repo owner/name] [--json number,title,state,url,updatedAt,createdAt,author,labels] 通过 GitHub REST 列出 issue，默认 state=open、limit=30，输出稳定 JSON 且不依赖系统 gh binary。--limit 会映射到 GitHub per_page 并限制返回数量，避免一次拉爆上下文；未知 state 或未知 --json 字段必须结构化失败并带 runnerDisposition=business-failed。GitHub issues API 可能混入 PR，CLI 会从 .data.issues 中过滤 pull request。
gh issue read <number> [--repo owner/name] [--json body,title,state,comments] 通过 GitHub REST 读取 issue title/body/state/url 和 comments，默认输出 JSON；view 只保留为兼容别名。兼容旧脚本的 --json body 和 --json body,title,state,comments 字段选择，且正文仍稳定暴露在 .data.issue.body，避免调用方因为 JSON 路径变化把空值当成正文。字段白名单是 body,title,state,comments,number,url,author,createdAt,updatedAt，未知字段必须结构化失败并带 runnerDisposition=business-failed。gh issue create --title <title> --body-file <file> [--label label[,label...]]... [--dry-run]、gh issue update <number> --mode replace|append --body-file <file> [--title ...] [--dry-run]、gh issue comment create <number> --body-file <file> [--dry-run]、gh issue comment delete <commentId> [--dry-run]、gh issue close|reopen <number> [--dry-run] 都走 REST，不依赖 gh binary。--label 仅用于 issue create，支持重复传入和逗号分隔；--dry-run 会展示解析后的 labels 与 request plan，正式创建时把 labels 放入 GitHub REST create-issue payload，GitHub 返回不存在 label 等 422 校验失败时 CLI 结构化返回 validation-failed，不静默成功。gh issue delete <number> 是结构化 unsupported-command，因为 GitHub REST 不支持 issue 硬删除；生命周期删除语义请使用 close。
gh issue update <number> --mode replace|append --body-file <file> 是正文更新主入口，edit 保留为兼容别名。replace 用文件正文替换现有 body；append 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 null、空白正文和过短正文；只有真实需要写短正文时才允许显式加 --allow-short-body，返回 JSON 会报告该风险。#20 总看板和指挥简报类 issue 是长期 body-only issue，--body-profile auto 会按 issue number 自动启用 #20/#24 legacy guard：#20 必须包含 ## 看板（OPEN），#24 legacy 指挥简报必须包含 ## 常驻观察与长期建议。显式 --body-profile commander-brief 不再固定 #24；#24 仍兼容，标题为 YYYY-MM-DD 指挥简报（北京时间） 或既有正文首行/关键 heading 表明为每日滚动指挥简报的 issue 也合法，并仍必须包含 ## 常驻观察与长期建议。对非简报 issue 显式使用 commander-brief 会结构化失败为 profile-issue-mismatch。--dry-run 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 \n、反引号、Markdown 表格和 shell 污染信号；若环境里有 GH_TOKEN 或 GITHUB_TOKEN，dry-run 还会只读抓取旧正文长度、SHA 和 updatedAt 作为更新前对照。正式写入可带 --expect-updated-at <updated_at> 或 --expect-body-sha <sha256>，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。
#20 只允许承担长期总看板职责；每日进展必须写入当天滚动指挥简报 issue，并由 #20 顶部“指挥简报索引”引用。gh issue read/view 20 会返回 codeQueueBoardHint；gh issue update/edit 20 的 body guard 会拒绝 ## 更新 YYYY-MM-DD HH:mm 北京时间、## YYYY-MM-DD HH:mm 北京时间指挥更新 和 ### YYYY-MM-DD HH:mm CST：... 这类简报段落，并在 codeQueueBoardHint 中提示改写到每日简报 issue；gh issue board-row list|get|update|add|move|delete|upsert --board-issue 20 也会返回同一 hint，提醒不要把每日简报混入 #20。
gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run] 是 legacy #24 指挥简报的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 --body-file 读取新正文；随后先 PATCH issue 主体，再把本次新增的 ## 更新 YYYY-MM-DD HH:MM 北京时间 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 claudeqq.ok=false 和结构化 degradedReason。每日滚动简报 issue 可用普通 gh issue update <number> --body-profile commander-brief --dry-run 和并发 guard 更新，但此通知 helper 仍只支持 #24。带通知 flag 的 --dry-run 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 645275593，默认 base URL 是 UniDesk 受控入口 http://backend-core:8080/api/microservices/claudeqq/proxy，可用 UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED、UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL、UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE、UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID、UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID 和 UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS 覆盖。
gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run] 是总看板只读结构审计入口，默认 repo 为 pikasTech/unidesk、board issue 为 20、输出 JSON 且不 PATCH/POST/DELETE GitHub。它只读取目标 board issue 正文，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表是否覆盖全部 issue。兼容字段 missingOpenIssues、closedInOpenRows、missingClosedRows、openInClosedRows、rowValidationWarnings、ignoredIssues 和 recommendedActions 仍保留，但固定为空数组或 0，用于避免旧调用方因字段缺失失败。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 gh issue board-row list|get|update|add|move|delete|upsert 的行级结构化入口。
gh issue board-row list --board-issue 20 [--state open|closed|all] [--dry-run]、gh issue board-row get <issueNumber> --board-issue 20 和 gh issue board-row update <issueNumber> --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text> [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256] 是 #20 看板表格单行结构化入口。list/get 复用 board-audit parser，只读返回 row、cells、fields、section、lineNumber、bodySha 和 rowValidationWarnings。update 只替换命中的一行里一个单元格，返回 old/new row、old/new body SHA、body guard、request plan 和 parser 结果；默认没有并发期望时即使不写 --dry-run 也只做 dry-run，正式 PATCH 必须带 --expect-body-sha 或 --expect-updated-at。字段映射固定为：branch -> Branch，progress -> 进度，status/validation -> 验收状态，tasks -> 相关 Code Queue 任务，focus -> 当前关注点。单元格值中的 Markdown 表格管道会转义为 \|，真实换行会折叠为空格，避免新增字面量 \n 污染。gh issue board-row upsert <issueNumber> --board-issue 20 --section open|closed [--category text] --branch <branch> --tasks <task> --summary <text> --focus <text> --validation <text> --progress <text> [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at] 是行级补齐入口：若 issue 已存在则只更新传入字段并返回 operation=update，未传字段保留原值；若不存在则按目标 section 表头生成完整行并返回 operation=add。新增时 --section 必需，且目标表头中的 category/branch/tasks/summary/focus/validation/progress 列都必须有对应值；若表没有独立 Summary/摘要列，--summary 会并入 Issue 单元格。upsert 不关闭、不删除、不重开 GitHub issue，也不做 OPEN/CLOSED 迁移；已存在行的 --section 或 --status 与当前 section 冲突时会结构化失败并提示使用 board-row move。gh issue board-row add <issueNumber> --board-issue 20 --section open|closed --row-file <file> [--dry-run] [--expect-body-sha|--expect-updated-at]、move <issueNumber> --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha|--expect-updated-at] 和 delete <issueNumber> --board-issue 20 [--dry-run] [--expect-body-sha|--expect-updated-at] 是 row-scoped #20 结构化写入口。add 校验一行 --row-file 的 Issue 列、列数和 GitHub 状态列与目标 section 一致；move 允许跨 OPEN/CLOSED 表迁移并在需要时同步 GitHub 状态列；delete 仅删除匹配行。四类写入口默认 dry-run，非 dry-run 必须带 --expect-body-sha 或 --expect-updated-at，并返回 old/new row、body SHA、line/section 计划和 parser 结果；duplicate/ambiguous row、列数不匹配、缺少新增必填字段、section/status 冲突或 body SHA 不匹配都会结构化失败，不会 fallback 到整篇 body 手工替换。
gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run] 只读扫描 issue 主体和 comments 中的字面量 \n、可疑 \t、shell newline escape、escaped backtick、ANSI escape 字符串、短 body、blank body 和 null body。输出固定 JSON，findings 会带 bodyKind=issue-body|comment-body、issueNumber、issueId、commentId、lineNumber、column、kind、snippet 和 classification=suspected-pollution|explanatory-mention|risk，用于区分说明性提到 \n 和疑似污染；cleanupSuggestions 只给 dry-run 清理建议、body/comment 定位和 diff-like preview，不 PATCH、不 DELETE、不真实清理历史 comment。gh issue cleanup-plan 是同一只读能力的别名，默认 dryRun=true。gh pr list [--state open|closed|all] [--json ...] 提供 REST 列表，默认 state=all 以保持既有 UniDesk CLI 行为，字段白名单是 body,title,state,number,url,author,head,base,draft,createdAt,updatedAt；未知 state 或未知 --json 字段必须结构化失败并带 runnerDisposition=business-failed。gh pr read|view <number> [--json ...] 继续稳定返回这些字段，并额外支持 headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup。headRefName 与 baseRefName 来自 REST head.ref/base.ref；mergeable、mergeStateStatus 和 statusCheckRollup 只在 read/view 明确请求这些字段时通过 GitHub GraphQL 查询，GraphQL 权限不足、网络失败或 GitHub 暂未计算完成时会结构化失败或返回 GitHub 原始 UNKNOWN/null 状态。此时收口人员应优先重试一次；若仍缺失、需要完整 gh pr view --json 等 GitHub 官方字段、或需要执行 merge/review 这类 UniDesk CLI 尚未开放的操作，回退到系统 gh 只读观察或人工 GitHub UI，不要把空字段当作可合并证据。gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]、gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]、gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]、gh pr comment delete <commentId> [--dry-run]、gh pr close|reopen <number> [--dry-run] 是 PR CRUD/生命周期入口。pr create --dry-run 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。pr update --mode append 会先读取当前 PR body 再追加正文。gh pr delete <number> 和 gh pr merge 本阶段不开放，始终结构化返回 unsupported-command；PR 生命周期删除语义请使用 close。
PR dry-run/probe 的最小手动序列是：bun scripts/cli.ts gh auth status --repo pikasTech/unidesk 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run 检查创建计划；bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --state open --limit 5 --json number,title,state,url,head,base 和 bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup 做只读 PR 观察和收口元数据检查；bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run 检查评论计划；bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk 必须失败并返回结构化 unsupported-command。Code Queue runner 可用 bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number> 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。
ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs 管理 D601 原生 k3s 上的 Tekton CI。run 手动创建每 commit 检查和 Code Queue 只读性能门禁；publish-backend-core 与 publish-user-service 从 pushed Git commit 构建并发布 127.0.0.1:5000/unidesk/<service>:<commit> commit-pinned artifacts，输出 artifactSummary（含 serviceId、sourceCommit、sourceRepo、dockerfile、imageRef、tag、digest、digestRef），但不部署生产；run-dev-e2e 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 docs/reference/dev-ci-runner.md 定义；Tekton CI 通用规则见 docs/reference/ci.md。
schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup 管理 backend-core 定时任务和运行历史。schedule list、schedule get、schedule runs --limit N 和 schedule runs <scheduleId> --limit N 是只读观察入口；schedule run、schedule retry-run、schedule delete 和 schedule upsert-pgdata-backup 会触发运行或写入配置，生产恢复时必须有明确授权。schedule runs --limit N 是全局历史视图，返回 scope=global 和 scheduleId=null；schedule runs <scheduleId> --limit N 是指定 schedule 历史视图，返回 scope=schedule 和对应 scheduleId。CLI 必须拒绝 schedule runs 50 这类纯数字位置参数，并提示使用 schedule runs --limit 50，避免把空数组误判成“没有历史 run”。schedule run <id> --wait-ms N 触发同一 schedule，并且即使 wait 超时也必须返回 newRunId 和 observeCommand；schedule retry-run <failedRunId> 只接受 failed run，从原 run 反查 scheduleId 后重触发同一 schedule，并输出 originalRunId、scheduleId、newRunId 和 observeCommand。当 backend-core 目标容器缺失或只观察到 verify-only 容器时，schedule/microservice 命令必须以非零退出并返回 failureKind=target-stack-not-running、runnerDisposition=infra-blocked、readOnlyCommands 和 authorizationRequiredForRecovery，不得把 Docker 的 No such container 当成成功的空历史。
codex deploy <commitId> 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 ci run-dev-e2e smoke，不提供 Code Queue CD，详细规则见 docs/reference/codex-deploy.md。
codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue queueId] [--provider-id id] [--cwd path] [--model model] [--reasoning-effort effort] [--execution-mode mode] [--max-attempts N] [--reference-task-id id] [--dry-run] 通过 backend-core 私有代理向稳定 code-queue 用户服务路径提交任务；prompt 必须且只能来自位置参数、文件或 stdin 之一，--dry-run 只返回结构化请求且不实际入队。长 prompt、多行 prompt、含引号/反引号/Markdown 表格/JSON/反斜杠的 prompt 必须优先用 --prompt-stdin 或 --prompt-file，不要拼进 shell 单个参数；位置参数只适合短单行 smoke prompt。stdin 推荐用 quoted heredoc：cat <<'PROMPT' | bun scripts/cli.ts codex submit --prompt-stdin --queue <id> --dry-run，文件路径推荐 bun scripts/cli.ts codex submit --prompt-file /tmp/code-queue-prompt.md --queue <id> --dry-run，确认 dry-run 后移除 --dry-run 提交同一 payload。dry-run 会额外输出 routingRecommendation，包含推荐 route、runner、model、风险信号、prompt 自包含/issue 非唯一来源/prod-secret-DB 禁止/运行态或 release 禁止/证据要求/中等复杂度候选等 guard 状态；同时输出 policyContract，固定暴露 GPT-5.5、DeepSeek、MiniMax 的风险分层、并发上限和外部 provider 429 退避处置。该建议只用于指挥官 preflight，不会改写 payload，不改变 runtime admission，也不假设生产 MiniMax 或 DeepSeek 可用。--dry-run 必须返回完整 prompt、字符数和 truncated=false 用于人工验收；真实提交是写入操作，默认只返回 accepted=true、task id、队列、写入保护摘要和后续查看命令，必须标记 promptOmitted=true 且不得回显 prompt 或 promptPreview。真实提交会经过本机本地串行化保护和短节流，避免同一指挥端并发 submit 把低内存主机或 code-queue-mgr 控制面打抖；返回值会附带低噪声 submitConcurrencyGuard 说明本次提交的锁与等待信息。backend-core 默认把提交、队列 CRUD、已读状态、历史摘要和轻量 Trace 读取分流到主 server code-queue-mgr，由它写入主 PostgreSQL；D601 scheduler 只轮询并执行已入库任务。
codex pr-preflight [--remote] [--push-dry-run --push-dry-run-ref refs/heads/probe/<name>] [--pr-create-dry-run --pr-create-dry-run-head <head>] [--issue N] [--full] 通过稳定 code-queue proxy 请求 D601 scheduler /api/runtime-preflight，用于 PR 型派单 admission。输出会压缩展示 scheduler/runner 的 token 覆盖、Auth Broker source/capability/nextAction、工具、agent port、Git worktree、GitHub egress、repo/issue/PR 只读探测、可选 push dry-run，以及可选 PR body/create dry-run guard；只报告 GH_TOKEN/GITHUB_TOKEN 是否存在和来源 key，不打印值。当 auth-broker 配置存在时，tokenCoverage.source="auth-broker"、credentialSource="broker-issued-token" 且 runner env token 不是成功前提；当仅 env token 存在时，credentialSource="env-token" 且 preflight.authBroker.nextAction="use-env-token-until-auth-broker-live"；两者都缺失时顶层 ok=false、runnerDisposition=infra-blocked、degradedReason=auth-broker-needed，tokenCoverage.missing 同时列出 GH_TOKEN 与 GITHUB_TOKEN，并输出 preflight.authBroker.source="broker/auth-broker-needed"、capability.source="missing-token"。该 auth-missing 的 scope 是 scheduler-runner-env，不能简化成“当前 active runner/dev container 不能创建 PR”；输出必须带 scopeBoundary 和 activeRunnerDevContainer，要求调用方另跑 bun scripts/cli.ts gh auth status --repo pikasTech/unidesk 与 PR dry-run 来确认当前 dev container 能力。preflight.prCapabilityContract 是 runner-facing 合同摘要，必须包含目标分支、token/auth 来源、systemGhBinaryRequiredForWrites=false、UniDesk REST bun scripts/cli.ts gh 可用性、push dry-run/PR create dry-run 的 writesRemote=false、expected PR handoff、真实 PR 创建需要 commander 授权和 gh pr merge 的 unsupported-command 边界；系统 gh binary 缺失只进入 tools.systemGhBinary，不得误判为 UniDesk REST gh CLI 不可用。--remote 在 runner-like 环境里不再依赖本地 unidesk-backend-core、unidesk-database、baidu-netdisk-backend 容器存在；这些缺失只作为本地观测证据。若远程控制面可达，则继续走远程控制面结果；若远程控制面不可达，则结构化返回 failureKind=control-plane-missing / degradedReason=remote-control-plane-unreachable，而不是把本地 backend-core-container-missing 当作最终阻塞。--pr-create-dry-run 不 POST GitHub，只证明 runner 内 PR body 生成、scripts/cli.ts gh pr create --dry-run 和 branch 参数形态可用；服务端创建权限仍以 token/auth broker、repo/issue/PR read、push dry-run 和最终授权后的真实 PR 创建结果为准。
codex task <taskId> 通过 Code Queue 私有代理按任务 ID 查询结构化审阅摘要；默认只返回任务身份、执行 Provider、工作目录、attempt 计数、原始 prompt、最终 response、最后错误和渐进披露命令，适合指挥官审阅完成未读任务且避免上下文爆炸。--detail 仍是有界详细摘要：默认只返回少量 attempt/tool 行、短 prompt/response/stderr/feedback 预览和 omitted/truncated 元数据；需要完整 prompt/response 文本或更多 tool/attempt 细节时再显式加 --full、--tool-limit N、--trace 或 codex output。该摘要读取默认由主 server code-queue-mgr 从 PostgreSQL 返回，不依赖 D601 code-queue-read Service 可用。
codex tasks [--view supervisor|full] [--queue id] [--status succeeded|running|queued|failed|canceled|judging|retry_wait[,..]] [--unread|--unread-only] [--limit N] [--before-id id] 通过同一私有代理输出渐进式披露视图。默认 supervisor 是低噪声指挥官视图，只返回 running、completedUnread、recentCompleted、queued 和 executionDiagnostics 的紧凑行；prompt/body 只给短预览和原始字符数，running/completedUnread/queued 默认只返回一个很小的有界页并通过 section commands.next 继续分页，recentCompleted 默认也限量且不重复 completedUnread 未读终态，不嵌入完整 Trace、final response 或全量 overview。--limit 在 supervisor 中主要是扫描/分页预算，不是返回几十条肥行的开关；需要更详细当前页任务行时显式使用 --view full 或 --full，仍受 --limit 和 --before-id 分页约束。
codex task <taskId> --trace --tail|--from-start|--after-seq N|--before-seq N --limit N 按页拉取 Code Queue 的逻辑 trace；响应会返回 nextAfterSeq、previousBeforeSeq、hasMore、hasBefore 和下一页/上一页命令，默认 --trace 取最新一页，且仍以分页 trace 为主；需要完整 prompt/最终 response 时加 --full，需要详细 task 摘要时加 --detail。
codex output <taskId> --tail|--from-start|--after-seq N|--before-seq N --limit N [--full-text] 按原始 output seq 分页读取底层记录；当 trace 行提示 commandOmittedLines、bodyOmittedLines 或 rawSeqs 时，用该命令按 seq 补取信息。默认是低噪声 raw-output 摘要：即使传入很大的 --limit，非 --full-text 也会限制返回行数和单条文本预览，并在 disclosure.limitCapped、requestedLimit、effectiveLimit 和 commands.fullText 中说明如何继续展开；显式 --full-text 才返回该页全文。
codex read <taskId> 在人工审阅后标记单个终态任务已读；列表、overview 和 supervisor 视图只返回这个命令字段，不得自动执行，也不得批量清空未读状态。
codex dev-ready 查询 Code Queue /api/dev-ready 并返回有界 readiness 摘要，包括工具、Docker、Codex config、SSH 和 devReady.skills。devReady.skills 只暴露 UNIDESK_SKILLS_PATH、是否存在、是否只读、skillCount、cli-spec 是否可见和修复建议，不输出宿主 auth/token 文件内容。
codex judge <taskId> --attempt N [--dry-run] [--include-prompt] 通过 Code Queue 私有代理按指定 attempt 单步复现 judge；这是执行面诊断入口，仍依赖 D601 scheduler/runner 侧的真实 judge builder、MiniMax 调用路径和执行环境。默认会真实调用 MiniMax，--dry-run 只返回 prompt/payload 大小、attempt 窗口和重建来源诊断，--include-prompt 仅用于本地深度排查。
codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--dry-run] 通过 Code Queue 私有代理向正在运行的 task 注入纠偏提示，正式替代底层 microservice proxy code-queue /api/tasks/<taskId>/steer 调用。prompt 必须且只能来自位置参数、文件或 stdin 之一；--dry-run 只输出 method、path、stableProxyPath、prompt 字符数、截断预览和 raw proxy 等价命令，不触碰运行中 session，也不得泄露超长 prompt 全文。真实执行是写入操作，成功只返回 accepted=true、task id、prompt 字符数、promptOmitted=true、有界 task/queue 确认和后续查看命令，不回显 prompt 或完整 task state；路径固定为 /api/microservices/code-queue/proxy/api/tasks/<taskId>/steer，只能作用于 D601 scheduler 上存在 active steerable turn 的 running task。
codex steer 非 dry-run 失败仍输出 JSON 且退出非零；.data.diagnostics.reason 用于 runner 分流，当前包括 backend-core-unreachable、code-queue-microservice-unregistered、proxy-unauthorized、proxy-404、steer-endpoint-404、upstream-runtime-rejected、stable-proxy-failed 和 invalid-proxy-response。scope 区分 backend-core、stable-proxy、code-queue-runtime 或 unknown，并带 status、exitCode、retryable、有界 upstreamBodyPreview 和推荐交叉验证命令；若任务不在 running/active-turn 状态，通常归类为 upstream-runtime-rejected，不得静默成功。
codex interrupt|cancel <taskId> 通过 Code Queue 私有代理请求中断；running/judging 任务会请求 D601 当前 agent run 停止，queued/retry_wait 任务的取消也必须保持与 WebUI 相同代理路径，返回有界 task 摘要和后续查询命令。任何需要接触 active run 的动作仍属于 D601 执行面。
Code Queue 多队列 lane 由 codex 命令命名空间管理：queues [--full|--all] [--limit N] [--page N|--offset N] 列表、queue create <queueId> 创建、queue merge <sourceQueueId> --into <targetQueueId> 合并、move <taskId> --queue <queueId> 迁移；这些队列管理入口默认由主 server code-queue-mgr 直管 PostgreSQL，仍通过稳定 code-queue 用户服务代理路径访问。codex queues 默认只返回 active/nonempty/unread/runnable queue 摘要、全局 counts 和 execution diagnostics；--full 或 --all 只切换为完整队列行视图的一页，仍受 --limit/--page/--offset 分页约束，不再默认携带 deprecated full array。summary 和 full 的稳定机读路径都是 .data.queues.items[]，全局元数据固定在 .data.queues.counts、.data.queues.executionDiagnostics、.data.queues.activeTaskIds 和 .data.queues.queuedTaskIds；需要完整 upstream 时使用输出中的 raw command。旧 full 顶层数组语义已作为 deprecated 兼容信息记录，不再作为 .data.queues 主形态。同一个 queue 内部串行执行，不同 queue 之间并行执行。迁移只允许尚未被 scheduler claim 的 queued/retry_wait 任务，必须满足 startedAt=null、currentAttempt=0 且没有 active thread/turn；已进入 running/judging 或已有 claim 标记的任务返回 409，不得被 move/merge 回写成 queued。合并会移动可迁移任务归属并自动删除源 queue 记录，只保留合并后的目标 queue；若 source 或 target queue 存在 active/claimed 任务，合并整体返回 409。合并后的目标 queue 按任务原 queueEnteredAt/createdAt 时间顺序串行，成功迁移 queued/retry_wait 任务后由 D601 scheduler 轮询推进。
所有 codex 查询和管理命令必须走与 WebUI 相同的 backend-core 私有代理路径 /api/microservices/code-queue/proxy/...；CLI 不得为了提交、移动、中断、取消或队列管理直接调用 D601 内部 Service、数据库、pod curl 或 k3sctl scheduler 子服务。若该路径失败，应先修复 CLI/backend/provider tunnel 链路，而不是绕过控制面。
job list [--limit N] [--include-command] 与 job status <jobId|latest> [--tail-bytes N] 查询 .state/jobs/ 文件系统状态，是异步命令的可观测入口。job list 默认只返回最新 50 条摘要；job status 默认只返回 stdout/stderr 末尾 12000 字节，并带 tailPolicy 与完整日志路径。
debug health、debug dispatch 与 debug task 走真实内部 core、WebSocket、数据库、provider、系统指标、Docker 状态和 Host SSH 维护桥流程，只用于开发调试，不写入 TEST.md 的正式验收步骤。
e2e run [--only pattern[,pattern...]] [--skip pattern[,pattern...]] 使用 publicHost 派生的公开 production frontend/dev frontend/provider ingress URL，并通过 Docker 内网验证 core API、PostgreSQL、provider self-connection、系统指标曲线、Docker 状态快照、provider.upgrade 预检和 Playwright 前端页面，是交付前的自动化 E2E 门禁；CLI 默认输出 check 状态摘要，完整诊断写入 resultPath，日常迭代应优先用 --only / --skip 跑最小必要集合。

Async Job State

长时操作采用 Fire-and-Forget 模式：CLI 创建 .state/jobs/{jobId}.json，后台进程执行真实命令，并将 stdout、stderr 分别写入 .state/jobs/{jobId}.stdout.log 与 .state/jobs/{jobId}.stderr.log。调用者通过 bun scripts/cli.ts job status <jobId> 查询进度和尾部输出。

server rebuild 与 server start、server stop 一样必须通过返回的 job id 确认结果；不要把连续 server rebuild 命令理解成“前一个重建已完成”，因为两个命令只是在快速创建异步 job。重建 frontend 只保留为维护/非标准路径；标准 frontend 发布必须先运行 ci publish-user-service --service frontend --commit <full-sha>，再运行 deploy apply --env dev --service frontend 和 deploy apply --env prod --service frontend，并验证 /health.deploy.commit。重建 dev 入口薄代理使用 bun scripts/cli.ts server rebuild dev-frontend-proxy，随后验证 server status 的 urls.devFrontend 和 http://127.0.0.1:18083/health；重建 Todo Note 后端使用 bun scripts/cli.ts server rebuild todo-note，随后用 microservice health todo-note 和 microservice proxy todo-note /api/instances 验证；重建 Code Queue Manager 使用 bun scripts/cli.ts server rebuild code-queue-mgr，随后用 microservice health code-queue-mgr、microservice health code-queue 和 codex submit --dry-run 验证主 server 控制面路径；重建 Project Manager 后端使用 bun scripts/cli.ts server rebuild project-manager，随后用 microservice health project-manager 和 microservice proxy project-manager /api/projects 验证；重建 Baidu Netdisk 后端使用 bun scripts/cli.ts server rebuild baidu-netdisk，随后用 microservice health baidu-netdisk 和 microservice proxy baidu-netdisk /api/transfers 验证，但该命令只保留为维护/非标准路径；重建 OA Event Flow 后端使用 bun scripts/cli.ts server rebuild oa-event-flow，随后用 microservice health oa-event-flow 和 microservice proxy oa-event-flow /api/diagnostics 验证。D601 Code Queue 执行面和 Decision Center 后端由 D601 k3s/k8s 控制面代管；persistent dev backend-core、frontend 和 Decision Center 都走 artifact consumer，当前 Code Queue 仍不得通过维护通道直连 D601 做部署。不得把 docker rm 手工兜底当成正式交付步骤。

新部署入口优先使用 deploy apply。deploy apply --env dev --service backend-core 是 D601 k3s artifact consumer，消费 ci publish-backend-core 产出的成品镜像；deploy apply --env dev|prod --service frontend、deploy apply --env dev|prod --service baidu-netdisk 和 deploy apply --env dev|prod --service decision-center 是 artifact-consumer 样板；旧的 codex deploy 已禁用；后续 Code Queue 等 D601 服务部署应另行收敛到同一类受控 CD 路径，部署后用 live commit 校验证明不是旧服务。

Output Contract

每条命令的最外层 JSON 包含 ok、command 和 data 或 error。失败时 CLI 设置非零退出码，但仍然输出 JSON 错误对象；错误对象应包含 name、message 和可用的 stack。

诊断命令默认采用渐进披露：server logs、job list/status、codex task/trace/output 和 microservice proxy 都必须有默认条数、字节数或文本预览上限；用户显式传 --limit、--tail-bytes、--full-text 或 --full 才扩大单次输出。CLI stdout 遇到下游 pipe 关闭的 EPIPE 必须安静退出，不得打印 Bun stack trace。

microservice proxy 是面向人工验证和受控调试的私有后端入口。默认 method 为 GET；使用 --body-json JSON、--body-file path 或 --body-stdin 时默认 method 切换为 POST，也可显式加 --method POST|PUT|PATCH|DELETE，但 GET/HEAD 不允许携带请求体。所有请求仍受 config 中的 allowedMethods 和 allowedPathPrefixes 限制。为了避免 Pipeline snapshot 这类超大业务 JSON 造成 CLI 输出爆炸，响应 body 超过默认阈值时会返回 bodyOmitted=true、bodyPreview、bodyBytes 和 rawHint；--raw 仍受默认硬限额保护，需要完整 body 时显式添加 --raw --full，或用 --max-body-bytes <N> 调整预览阈值。正式 frontend 展示仍应优先使用业务控件和 __unideskArrayLimit 这类展示级裁剪参数，而不是默认倾倒完整 JSON。

GitHub issue/PR 写操作必须优先使用 bun scripts/cli.ts gh issue|pr ... --body-file <file>。不要把 Markdown 正文拼进 shell 参数、gh issue comment --body 或 gh api -f body=...；这些路径容易把真实换行污染成字面量 \n。从 shell 生成正文文件时使用 quoted heredoc，例如 cat <<'EOF' > /tmp/body.md，保证反引号、反斜杠和 Markdown 表格不被 shell 展开；之后再把文件交给 --body-file。gh issue 写命令不接受 stdin 正文；需要从生成内容写入 issue 时，先落到临时 Markdown 文件或已审阅的工作文件，再传给 --body-file。PR 安全写入口同样优先 --body-file，--body 只适合短单行内容。JSON 请求体场景使用各命名空间自己的 --body-file 或 --body-stdin，避免长 JSON 直接塞进 shell 参数；GitHub Markdown 写入仍只走 --body-file。update --mode append 用 REST 读取旧正文后追加文件字节，不引入 shell 拼接正文路径。gh pr merge 暂不开放，不存在 --confirm 可绕过的真实 merge 路径。CLI 会按 UTF-8 原样读取文件内容并用 JSON body 调用 REST API。

network perf 用于生成组网性能前后对比数据。标准 Code Queue overview 读路径基准命令是 bun scripts/cli.ts network perf --service code-queue --path /api/tasks/overview?limit=30 --count 30 --concurrency 1 --label before，远程主 server 可用 bun scripts/cli.ts --main-server-ip 74.48.78.17 network perf ...。输出包含成功/失败数、状态码分布、x-unidesk-cache、x-unidesk-proxy-mode、x-unidesk-upstream-proxy-mode 分布和 min/p50/p90/p95/max；provider-gateway 长连接数据面验收应看到 proxyModeCounts.provider-ws-http-tunnel，adapter native Service 数据面验收应看到 upstream proxy mode 为 kubernetes-native-service，若出现 kubernetes-api-service-proxy 必须结合 /api/control-plane.nativeServiceProxy.failedServices 解释 fallback 原因。

Debug Contract

debug 子命令必须复用真实模块与真实端点，禁止维护平行实现。debug health 会摘要展示 /api/nodes/system-status 和 /api/nodes/docker-status，避免输出完整快照造成信息爆炸。debug dispatch 会通过 backend-core 容器内置 helper 访问 backend-core /api/dispatch，core 再通过 WebSocket 将 docker.ps、provider.upgrade、host.ssh、microservice.http 或 echo 任务下发给 provider gateway，因此它可以验证核心调度闭环，同时不需要公开 core REST API，也不要求 frontend 容器携带调试 broker。provider.upgrade 默认使用 mode: "plan" 预检；需要验证一键升级时必须显式加 --mode schedule，并通过 --wait-ms 或 debug task 确认任务进入 succeeded、result 中包含 updater 容器信息和 policy: "always-enabled"。host.ssh 默认使用 mode: "probe" 做短超时维护桥自检；需要执行明确命令时使用 --ssh-command 进入 mode: "exec"，并配合 --wait-ms 和 debug task 查看 stdout、stderr、exitCode 与 probeLine。microservice.http 只用于开发调试 provider-gateway 私有 HTTP 代理，正式用户入口应使用 microservice CLI 或 frontend 的用户服务页面。

SSH Command

ssh <providerId> [ssh-like args...] 是面向人的终端透传入口，不包装 JSON 输出。CLI 会在宿主机启动 docker exec -i unidesk-backend-core backend-core --ssh-broker ...，broker 只连接 backend-core 的 Docker 内网 /ws/ssh，core 再把 stdin/stdout/stderr 流量通过目标 provider 的既有 WebSocket 转发到 provider-gateway，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 ssh -tt，带远端命令的会话使用 ssh -T；脚本 stdin、apply-patch 和 py 这类命令模式不得被伪终端回显或注入控制字符。该入口不新增 core 公网端口，不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的公网边界。

bun scripts/cli.ts ssh --help 和 bun scripts/cli.ts ssh <providerId> --help 是本地 JSON 帮助命令，必须快速返回；不能把 --help 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。

bun scripts/cli.ts ssh D518 应表现为登录 D518 WSL 的 shell；bun scripts/cli.ts ssh D518 hostname 应像 ssh D518 hostname 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，-p、-i、-l、-o 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。

core 只允许声明了 host.ssh capability 的 provider 使用 ssh 透传或 host.ssh dispatch；旧 provider 不支持该能力时必须快速失败并输出错误，不能把未知命令误判成 echo 成功。

本地 broker 默认等待 provider SSH 会话打开 60000ms，以便在目标节点同时有较多 microservice.http 任务时仍能建立维护会话；需要诊断慢连接时可用 UNIDESK_SSH_OPEN_TIMEOUT_MS=<ms> 临时调大，但最小有效值固定为 15000ms，避免把真实离线误判为长时间阻塞。

ssh <providerId> 会在远端会话启动时注入 /tmp/unidesk-ssh-tools/apply_patch、/tmp/unidesk-ssh-tools/glob 和 /tmp/unidesk-ssh-tools/skill-discover，并把该目录加入远端 PATH。apply_patch 接受标准 *** Begin Patch / *** End Patch patch 格式，便于通过 SSH 透传编辑远端仓库文件；glob 在远端用 Python 执行路径匹配，避免依赖 shell glob 展开；skill-discover 用于列出远端 Linux/WSL 与 Windows skill。目标节点需要具备 python3 和 base64。注入工具只写 /tmp/unidesk-ssh-tools，不修改目标仓库，交互式 shell 和远端命令都可以直接调用这些工具。

如果只是远端打小补丁，不需要再手写 ssh D601 'apply_patch' < patch.diff 这种命令拼接；正式入口是 bun scripts/cli.ts ssh D601 apply-patch < patch.diff。apply-patch 与 patch 等价，附加参数会原样透传给远端 apply_patch，例如 bun scripts/cli.ts ssh D601 apply-patch --help。标准单命令用法如下，不需要先创建本地 patch 临时文件：

bun scripts/cli.ts ssh D601 apply-patch <<'PATCH'
*** Begin Patch
*** Update File: /home/ubuntu/pipeline/scripts/src/nodeControl.ts
@@
-const value = "old";
+const value = "new";
*** End Patch
PATCH

如果只是想远端执行 Python 脚本，不要再手写 bun scripts/cli.ts ssh D601 'python3 -' < script.py。正式入口是 bun scripts/cli.ts ssh D601 py < script.py；CLI 会先把本地 stdin 写入远端临时 .py 文件，再以无缓冲模式执行并自动清理，同时对额外脚本参数逐个做 shell quoting，避免字符串转义问题。典型用法：

printf 'import sys\nprint(sys.argv)\n' | bun scripts/cli.ts ssh D601 py foo '--bar=baz'

ssh <providerId> py 的附加参数是脚本参数，不是 Python 解释器参数；如需 -m、-X 或多条 shell 命令，仍使用原始远端命令入口。为了保证 CLI 输出及时可见，helper 固定采用“临时文件 + python3 -u”模式；provider 命令模式不分配 TTY，因此脚本内容不应被远端回显。

ssh <providerId> skills 是远端 skill 发现入口，也可写作 ssh <providerId> skill discover。输出固定为 JSON，包含 node、roots、counts 和 skills：roots 会显示每个候选 skill 根目录是否存在、扫描到多少 skill 以及错误；skills 会给出 scope、name、description、path、skillMd 和可转换时的 windowsPath。默认扫描远端用户的 ~/.agents/skills、~/.codex/skills、可访问的 /root/.agents/skills、/root/.codex/skills；如果目标是 WSL，还会扫描 /mnt/c/Users/*/.agents/skills 与 /mnt/c/Users/*/.codex/skills，从而一次性看清 WSL 和 Windows 两套 skill。常用参数是 --scope wsl、--scope windows、--limit N、--max-depth N、--root <path> 和 --windows-root <path>；不要用宽泛的 Linux find /mnt/* 扫 Windows 盘，优先用这个结构化入口避免卡在 Windows 挂载层。

bun scripts/cli.ts ssh D601 skills --limit 80
bun scripts/cli.ts ssh D601 skills --scope windows --limit 40

Windows 工具链透传的 wrapper、路径转换、是否修改 skill、是否额外安装依赖等长期规则见 docs/reference/windows-passthrough.md；ssh skills 本身只负责发现，不会修改远端 skill。

ssh <providerId> find 是常用远端搜索的结构化入口，避免在 Host SSH / WSL SSH 透传里手写 find \( ... \)、*、管道和多层引号。它会把路径、谓词和 pattern 作为 argv 安全拼接，并支持重复 --name、--iname、--path 或 --ipath，重复 pattern 默认按 OR 组合。稳定参数包括 --max-depth/-maxdepth、--min-depth/-mindepth、--type/-type、--contains、--icontains、--name/-name、--iname/-iname、--path/-path、--ipath/-ipath、--mtime/-mtime、--mmin/-mmin、--size/-size、--sort 和 --limit N。典型用法：

bun scripts/cli.ts ssh D601 find /home/ubuntu --max-depth 4 --type d --icontains pika --limit 50 --sort

ssh <providerId> glob 是远端 glob 匹配入口，支持 --root DIR、--pattern PATTERN、--contains TEXT、--icontains TEXT、--type any|f|d、--limit N、--sort 和 --absolute。--contains 与 --icontains 可避免在本地 shell 中输入 *；若显式使用 --pattern '**/*.ts' 这类 pattern，仍应按本地 shell 规则加引号，防止参数到达 CLI 前已被本地 shell 展开。典型用法：

bun scripts/cli.ts ssh D601 glob --root /home/ubuntu/pikapython --pattern '**/*-test.cpp' --limit 20 --sort

ssh <providerId> argv <command> [args...] 是通用 argv 安全拼接入口；exec 是同义入口。它适合不需要 shell 管道的常用命令。find、glob 和 apply-patch 有专用入口；rg、grep、sed、nl、stat、du、ls、cat、head、tail、wc 和 pwd 可以直接作为 ssh 子命令使用，CLI 会对每个 argv token 做 shell quoting。需要管道、重定向、变量展开或多条命令时仍使用旧的自由远端命令入口，并把整段远端 shell 脚本作为一个本地参数传入。

通过 ssh <providerId> 执行多行脚本时，优先使用结构化 helper，例如 bun scripts/cli.ts ssh D601 py < script.py 或 printf ... | (bun scripts/cli.ts ssh D601 'bash -s') 这种单层 stdin 传输。不要在远端命令字符串里再嵌套 heredoc、复杂引号或 ssh 'python3 - <<EOF ...' 形态；多层 shell 解析容易把 stdin 绑定到错误进程，结果会打开远端交互解释器并留下悬挂的 broker/SSH 会话。长脚本需要复用时，优先通过 stdin 写入目标节点的临时脚本，再在同一个远端命令中显式执行并清理。

Remote Main Server Passthrough

--main-server-ip 是一个全局前缀，必须放在需要透传的命令同一次调用中，例如 bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health。默认传输是公网 frontend：本地 CLI 读取本仓库 config.json 中的 frontend 登录账号密码，登录 http://<ip>:<frontendPort>/ 获取 HttpOnly session cookie，然后通过 frontend 的 /api/* 同源代理访问 backend-core 内网 API；因此计算节点只需要能访问公网 frontend，不需要主 server SSH key，也不需要打开 backend-core REST API 或 PostgreSQL 端口。

默认 frontend 传输支持 debug health、debug dispatch、debug task、artifact-registry status|health、ci publish-user-service --dry-run、microservice list/status/health/diagnostics/tunnel-self-test/proxy、decision upload/list/show/health、decision requirement list/upsert、decision diary import/list/history/months/show/edit/upsert、codex task <taskId>、codex tasks、codex output <taskId>、codex judge <taskId> --attempt N 和 ssh <PROVIDER_ID> <remote-command>。运行中纠偏 codex steer 属于 active run write control，应在主 server 本机 CLI 或显式 SSH 传输上执行，避免公网 frontend 透传限制 stdin/body 审计语义。其中 ssh 的 remote frontend 传输使用 host.ssh dispatch 执行有界远端命令，适合 ssh D601 hostname 和 ssh D601 skills 这类自测；交互式登录 shell 仍应在主 server 本机 CLI 使用，或显式切换到旧 SSH 传输后在主 server 上执行。frontend 远程透传不会流式转发本地 stdin，因此 ssh py < script.py、ssh apply-patch < patch.diff 这类 stdin-backed helper 必须在主 server 本机运行，或显式切换到 --main-server-transport ssh。当 backend-core、database、provider-dispatch 或 provider-host-ssh 缺失时，这些 read-only 预检必须返回结构化 runnerDisposition=infra-blocked 和缺失通道列表，而不是裸 No such container。若确实需要旧行为，可使用 --main-server-key <key> 或 --main-server-transport ssh，这时 CLI 会通过 SSH 登录主 server 的 --main-server-root 目录执行同一个 bun scripts/cli.ts <command>。

计算节点可以用该入口测试自身的远程升级闭环，而不需要在计算节点公开 core REST API 或 database。标准顺序是：先运行 bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health 确认主 server 看到当前 Provider 在线，且该 Provider labels 中 unideskCapabilities 包含 host.ssh、hostSshConfigured=true、hostSshKeyPresent=true；再运行 bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> provider.upgrade --mode schedule --wait-ms 15000 触发真实 provider.upgrade；随后再次运行 debug health 确认节点重新上线；最后运行 bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000 和 bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> hostname 验证 SSH 透传能力。provider-gateway 新部署或升级后没有完成这组 remote CLI 自测，不能视为交付完成。

远程透传的安全边界是公网 frontend 登录态和 frontend 到 backend-core 的内网代理；不要把 provider token、数据库端口或 backend-core REST API 暴露给计算节点。旧 SSH 传输只作为兼容路径保留，不得把“必须提供主 server SSH key”作为计算节点自测的前置条件。

62 KiB Raw Blame History Unescape Escape