docs: move unidesk skills into repo
This commit is contained in:
Codex
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: unidesk-cicd
|
||||
description: UniDesk CI/CD 控制面 — `hwlab g14` 和 `agentrun v01` 子命令，覆盖 PR 监控自动合并、Tekton/Argo 控制面、git-mirror、Secret、observability、CI tools image、PipelineRun 清理和 AgentRun v0.1 部署。用户提到 CI/CD、deploy、rollout、PipelineRun、trigger、git-mirror、control-plane、k3s 部署、agentrun 部署、hwlab g14、monitor-prs、trigger-current 时使用。任何需要把代码变更推送部署到 G14 k3s 的操作都必须走本 skill。
|
||||
---
|
||||
|
||||
# UniDesk HWLAB G14 CI/CD CLI
|
||||
|
||||
HWLAB G14 的 PR → CI → CD 控制面和运维入口，统一通过 `bun scripts/cli.ts hwlab g14 ...` 管理。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts hwlab g14 ...`
|
||||
|
||||
---
|
||||
|
||||
## PR 监控与自动合并
|
||||
|
||||
### G14 主线
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 monitor-prs \
|
||||
[--lane g14|v02] [--once] [--dry-run] \
|
||||
[--interval-seconds N] [--max-cycles N] [--timeout-seconds N]
|
||||
```
|
||||
|
||||
后台 worker 监控 `pikasTech/HWLAB` 的 open PR → preflight → 自动合并 → 观察 CI/CD 直到 DEV `Synced/Healthy`。成功 rollout 后自动追加指挥简报。状态指针按用途分离（`latest-monitor-job.json` / `latest-once-job.json` 等）。
|
||||
|
||||
### v0.2 lane
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 monitor-prs --lane v02 [--once] [--dry-run]
|
||||
```
|
||||
|
||||
只监控 base=`v0.2` 的 PR。CD 采用 latest-only：旧 PipelineRun 不取消不等待，stale commit 以 superseded/no-op 收口。合并后在原 PR 下追加语义化状态评论（含起止时间、source commit、PipelineRun、targetValidation、git mirror 状态）。
|
||||
|
||||
### v0.3 lane
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 monitor-prs --lane v03 [--once] [--dry-run]
|
||||
```
|
||||
|
||||
只监控 base=`v0.3` 的 PR。ready PR 经 UniDesk `gh pr merge` 合并后触发 runtime lane CD，检查 PipelineRun、Argo、`hwlab-v03` runtime public probes 和 Git mirror flush，并对失败 check、冲突、CD failure/timeout 创建或更新 failure issue。
|
||||
|
||||
---
|
||||
|
||||
## 控制面（Tekton/Argo）
|
||||
|
||||
### 状态查询
|
||||
|
||||
```bash
|
||||
# 最新 head
|
||||
bun scripts/cli.ts hwlab g14 control-plane status --lane v02
|
||||
|
||||
# 定点 PipelineRun
|
||||
bun scripts/cli.ts hwlab g14 control-plane status \
|
||||
--lane v02 --pipeline-run hwlab-v02-ci-poll-<short-sha>
|
||||
|
||||
# 定点 source commit
|
||||
bun scripts/cli.ts hwlab g14 control-plane status \
|
||||
--lane v02 --source-commit <full-sha>
|
||||
```
|
||||
|
||||
定点 status 输出 `targetValidation.state=passed|superseded`，只检查指定 target 的证据。
|
||||
|
||||
### 手动触发
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 control-plane trigger-current \
|
||||
--lane v02|v03 [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
从 `/root/hwlab-v02-cicd.git` 解析当前 `origin/v0.2` full SHA，创建 commit-pinned PipelineRun。confirmed trigger 创建异步 job 并立即返回 `job.id`。
|
||||
|
||||
### 应用 RBAC/Pipeline/Argo
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 control-plane apply --lane v02 [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
server-side apply v02 的 Tekton RBAC、Pipeline 和 Argo Application。
|
||||
|
||||
---
|
||||
|
||||
## Git Mirror
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 git-mirror status
|
||||
bun scripts/cli.ts hwlab g14 git-mirror apply [--dry-run|--confirm]
|
||||
bun scripts/cli.ts hwlab g14 git-mirror sync [--dry-run|--confirm]
|
||||
bun scripts/cli.ts hwlab g14 git-mirror flush [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
- `apply`: 渲染并 apply `devops-infra/git-mirror.yaml`
|
||||
- `sync`: 把当前配置声明的 GitHub refs 拉入本地 mirror
|
||||
- `flush`: 把本地 lane GitOps ref 快进推回 GitHub
|
||||
|
||||
PipelineRun `gitops-promote` 如果报 git mirror 控制面漂移、refs 不一致或 flush/publish 未完成，优先按当前 `devops-infra/git-mirror.yaml` 收敛：先 `git-mirror apply --confirm`，再 `git-mirror sync --confirm --wait`，然后用 `control-plane cleanup-runs --pipeline-run <failed-run> --confirm` 受控清理失败 PipelineRun 后重试。旧 branch/path allowlist gate 已删除，不要恢复旧 hook、直接 `kubectl delete`、手工 patch pod 内 hook 或绕过 `flush`。
|
||||
|
||||
手动 trigger closeout 不能只看 PipelineRun `Completed`。必须继续查 `control-plane status --pipeline-run <name>` 和 `git-mirror status`；若 `pendingFlush=true`，执行 `git-mirror flush --confirm --wait` 到 `githubInSync=true`。
|
||||
|
||||
---
|
||||
|
||||
## Secret 管理
|
||||
|
||||
```bash
|
||||
# 查看
|
||||
bun scripts/cli.ts hwlab g14 secret status --lane v02 \
|
||||
--name hwlab-v02-openfga|hwlab-v02-master-server-admin-api-key
|
||||
|
||||
# 确保
|
||||
bun scripts/cli.ts hwlab g14 secret ensure --lane v02 \
|
||||
--name hwlab-v02-master-server-admin-api-key [--dry-run|--confirm]
|
||||
|
||||
# 删除废弃 Secret
|
||||
bun scripts/cli.ts hwlab g14 secret delete --lane v02 \
|
||||
--name <obsolete-secret> [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 运行时迁移
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 control-plane runtime-migration \
|
||||
--lane v02 [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
通过 `deployment/hwlab-cloud-api` 容器内 migration CLI 执行。
|
||||
|
||||
---
|
||||
|
||||
## Observability
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 observability status|apply|query|targets|boundary|closeout \
|
||||
[--lane v02] [--promql <expr>] [--expect-count N] [--expect-value V] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
管理 G14 Prometheus 基础设施和 HWLAB v0.2 监控 closeout。
|
||||
|
||||
---
|
||||
|
||||
## Platform Infra / Sub2API
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api plan|apply|status|validate
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool plan|sync|validate|expose|configure-local
|
||||
```
|
||||
|
||||
- `platform-infra` 是 G14 k3s 上 UniDesk 运维的平台基础设施 namespace；新增平台服务优先进入该 namespace，旧 `devops-infra` 只作为渐进迁移来源。
|
||||
- Sub2API 的日常部署、Codex pool、FRP 暴露、master `~/.codex` 配置、验收和排障统一使用 `$unidesk-sub2api`（UniDesk 仓库 `.agents/skills/unidesk-sub2api/SKILL.md`）。
|
||||
- UniDesk 仓库 `docs/reference/platform-infra.md` 只保留开发边界、YAML-first 真相和探针口径，不重复日常操作手册。
|
||||
|
||||
---
|
||||
|
||||
## CI Tools Image
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 tools-image status
|
||||
bun scripts/cli.ts hwlab g14 tools-image build \
|
||||
--name ci-node-tools --tag <tag> \
|
||||
[--dockerfile deploy/ci/hwlab-ci-node-tools.Dockerfile] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
在 G14 host 构建并 push 到本地 registry。
|
||||
|
||||
---
|
||||
|
||||
## PipelineRun 清理
|
||||
|
||||
```bash
|
||||
# 清理已完成 PipelineRun
|
||||
bun scripts/cli.ts hwlab g14 control-plane cleanup-runs \
|
||||
--lane v02|g14|all [--min-age-minutes N] [--limit N] [--dry-run|--confirm]
|
||||
|
||||
# 补充清理 Released PV
|
||||
bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs \
|
||||
--lane all [--limit N] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 手动补记 rollout
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts hwlab g14 record-rollout --pr <number> --source-commit <sha>
|
||||
```
|
||||
|
||||
手动补记 CI/CD 耗时、TaskRun 指标和语义化 changelog 到指挥简报。
|
||||
|
||||
---
|
||||
|
||||
## AgentRun v0.1 控制面
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts agentrun v01 control-plane status \
|
||||
[--dry-run|--confirm]
|
||||
bun scripts/cli.ts agentrun v01 control-plane trigger-current \
|
||||
[--dry-run|--confirm]
|
||||
bun scripts/cli.ts agentrun v01 control-plane refresh \
|
||||
[--dry-run|--confirm]
|
||||
bun scripts/cli.ts agentrun v01 control-plane cleanup-runs \
|
||||
[--min-age-minutes N] [--limit N] [--dry-run|--confirm]
|
||||
bun scripts/cli.ts agentrun v01 control-plane cleanup-released-pvs \
|
||||
[--limit N] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
- `status`: 只读汇总 source commit、PipelineRun、Argo、manager image、git mirror 和 `aligned` 结论
|
||||
- `trigger-current`: 快进 `G14:/root/agentrun-v01` → mirror sync → 创建 `agentrun-v01-ci-<short12>` PipelineRun
|
||||
- `refresh`: Argo hard refresh（不 patch runtime workload）
|
||||
- `cleanup-runs`: 清理已完成 PipelineRun + 临时 PVC
|
||||
- `cleanup-released-pvs`: 回收 Released PV
|
||||
|
||||
## AgentRun v0.1 Git Mirror
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts agentrun v01 git-mirror status [--full|--raw]
|
||||
bun scripts/cli.ts agentrun v01 git-mirror sync [--dry-run|--confirm] [--wait]
|
||||
bun scripts/cli.ts agentrun v01 git-mirror flush [--dry-run|--confirm] [--wait]
|
||||
```
|
||||
|
||||
- `status`: 返回 `localV01`/`githubV01`/`localGitops`/`githubGitops`/`pendingFlush`/`githubInSync`
|
||||
- `sync`: 拉取 GitHub `v0.1` + `v0.1-gitops` refs
|
||||
- `flush`: 推送本地 `v0.1-gitops` → GitHub
|
||||
|
||||
与 HWLAB v0.2 mirror 共用 `devops-infra` 服务和 cache PVC。
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
name: unidesk-code-queue
|
||||
description: UniDesk legacy Code Queue archive CLI — `codex` 子命令只保留历史任务只读查看、未读积压、trace/output 分页、read、interrupt/cancel 残留任务和本地 prompt-lint；新任务提交、steer、resume、queue mutation 和 move 已冻结，必须使用 `agentrun v01 queue|sessions`。用户提到 codex、Code Queue、submit、steer、resume、tasks、unread、code-queue 时使用。
|
||||
---
|
||||
|
||||
# UniDesk Legacy Code Queue CLI
|
||||
|
||||
旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障、残留任务停止和 prompt-lint 入口；新的指挥官派单、trace/output、read/cancel、steer/reuse 必须走 AgentRun Queue/Sessions。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts codex ...`
|
||||
|
||||
---
|
||||
|
||||
## 新任务入口
|
||||
|
||||
```bash
|
||||
# 查看 AgentRun 指挥官队列
|
||||
bun scripts/cli.ts agentrun v01 queue commander --reader-id <id>
|
||||
|
||||
# 提交 AgentRun Queue payload
|
||||
bun scripts/cli.ts agentrun v01 queue submit --json-file /tmp/task.json
|
||||
|
||||
# 查看/控制 AgentRun session
|
||||
bun scripts/cli.ts agentrun v01 sessions trace <sessionId>
|
||||
bun scripts/cli.ts agentrun v01 sessions output <sessionId>
|
||||
bun scripts/cli.ts agentrun v01 sessions read <sessionId>
|
||||
bun scripts/cli.ts agentrun v01 sessions steer <sessionId> --prompt-stdin
|
||||
bun scripts/cli.ts agentrun v01 sessions cancel <sessionId>
|
||||
```
|
||||
|
||||
UniDesk bridge 会把本地 `--json-file`、`--prompt-file`、`--runner-json-file` 或 `--prompt-stdin` materialize 到 G14 `/root/agentrun-v01` 临时文件，然后调用官方 `./scripts/agentrun --manager-url auto`。它不是旧 Code Queue adapter，不双写，也不迁移旧历史。
|
||||
|
||||
---
|
||||
|
||||
## 冻结的旧写入口
|
||||
|
||||
以下命令必须返回 `ok=false`、`frozen=true`、`degradedReason=legacy-code-queue-frozen`，并提示 AgentRun 替代命令：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex submit ...
|
||||
bun scripts/cli.ts codex enqueue ...
|
||||
bun scripts/cli.ts codex steer <taskId> ...
|
||||
bun scripts/cli.ts codex resume <taskId> ...
|
||||
bun scripts/cli.ts codex queue create <queueId>
|
||||
bun scripts/cli.ts codex queue merge <sourceQueueId> --into <targetQueueId>
|
||||
bun scripts/cli.ts codex move <taskId> --queue <queueId>
|
||||
```
|
||||
|
||||
不要用兼容开关、legacy mode、adapter、双写或 fallback 绕开冻结边界。
|
||||
|
||||
---
|
||||
|
||||
## 历史任务视图
|
||||
|
||||
### Commander（低噪声轮询）
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex tasks --view commander [--limit N]
|
||||
```
|
||||
|
||||
返回旧 Code Queue 历史/残留任务的有界 action map：active runners 计数、少量 active item、queued/retry_wait 计数、terminal-unread 总数、关键风险计数、分类计数和 drill-down 命令。新任务队列状态用 `agentrun v01 queue commander`。
|
||||
|
||||
### Supervisor（分区视图）
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex tasks --view supervisor \
|
||||
[--status succeeded|running|queued|failed|canceled|judging|retry_wait] \
|
||||
[--unread] [--limit N] [--before-id id]
|
||||
```
|
||||
|
||||
返回 `activeRunning`、`running`、`completedUnread`、`recentCompleted`、`queued` 分区。状态 alias：`completed|successful → succeeded`、`cancelled → canceled`、`pending → queued`。
|
||||
|
||||
### 单任务
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex task <taskId> [--detail|--full] [--trace]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 未读积压
|
||||
|
||||
```bash
|
||||
# 摘要
|
||||
bun scripts/cli.ts codex unread [--queue id] [--repo owner/name] [--issue N]
|
||||
|
||||
# 详细列表
|
||||
bun scripts/cli.ts codex unread list [--view full] [--limit N]
|
||||
|
||||
# 标记已读
|
||||
bun scripts/cli.ts codex unread mark-read --confirm [--queue id]
|
||||
```
|
||||
|
||||
`mark-read` 必须 `--confirm`，单任务审阅优先用 `codex read <taskId>`。
|
||||
|
||||
---
|
||||
|
||||
## Trace / Output 分页
|
||||
|
||||
```bash
|
||||
# 逻辑 trace（分页）
|
||||
bun scripts/cli.ts codex task <taskId> --trace \
|
||||
[--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full]
|
||||
|
||||
# 原始 output（分页补取）
|
||||
bun scripts/cli.ts codex output <taskId> \
|
||||
[--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full-text]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 标记已读
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex read <taskId>
|
||||
```
|
||||
|
||||
标记单个终态任务已读，同时返回任务身份、终态 attempt 摘要和最终 response。
|
||||
|
||||
---
|
||||
|
||||
## Judge（复现评判）
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex judge <taskId> --attempt N [--dry-run] [--include-prompt]
|
||||
```
|
||||
|
||||
按指定 attempt 单步复现 judge，诊断入口。
|
||||
|
||||
---
|
||||
|
||||
## 中断/取消
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex interrupt <taskId>
|
||||
bun scripts/cli.ts codex cancel <taskId>
|
||||
```
|
||||
|
||||
仅用于停止旧 Code Queue 残留任务；新 AgentRun session 使用 `bun scripts/cli.ts agentrun v01 sessions cancel <sessionId>`。
|
||||
|
||||
---
|
||||
|
||||
## 旧队列归档
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex queues [--full|--all] [--limit N] [--page N]
|
||||
```
|
||||
|
||||
只读查看旧队列摘要。旧 queue create/merge 和 move 已冻结。
|
||||
|
||||
---
|
||||
|
||||
## Dev Ready / PR Preflight
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex dev-ready
|
||||
bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run ...] [--pr-create-dry-run ...] [--issue N] [--full|--raw]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Lint
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]
|
||||
```
|
||||
|
||||
AgentRun 派单或 steer 前的本地 dry-run lint，返回分级（`read-only|live-read|live-mutating`）和缺失项。它只用于 AgentRun payload 入队前的 prompt 审查，不提交旧 Code Queue 任务。
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
name: unidesk-decision
|
||||
description: UniDesk Decision Center CLI — 会议记录/决议管理、工作日记导入与查询。用户提到 decision、决策中心、会议记录、工作日记、requirement 需求记录时使用。
|
||||
---
|
||||
|
||||
# UniDesk Decision Center CLI
|
||||
|
||||
通过 `bun scripts/cli.ts decision ...` 管理 D601 k3s Decision Center 的会议记录、决议和工作日记。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts decision ...`
|
||||
|
||||
---
|
||||
|
||||
## 记录管理
|
||||
|
||||
### 上传/列表/查看/健康
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts decision upload <markdown-file>
|
||||
bun scripts/cli.ts decision list [--include-body]
|
||||
bun scripts/cli.ts decision show <id|docNo>
|
||||
bun scripts/cli.ts decision health
|
||||
```
|
||||
|
||||
`list` 默认只返回摘要，不包含完整 Markdown body。需要正文时加 `--include-body`。
|
||||
|
||||
### 文书字段
|
||||
|
||||
```bash
|
||||
--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`。
|
||||
|
||||
---
|
||||
|
||||
## 需求记录
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts decision requirement list
|
||||
bun scripts/cli.ts decision requirement create --doc-type GOAL --doc-priority P1 --year 2026 --summary "目标摘要"
|
||||
bun scripts/cli.ts decision requirement upsert --doc-no DC-GOAL-2026-001 --doc-type GOAL --summary "更新摘要"
|
||||
bun scripts/cli.ts decision requirement update <id|docNo> --field ...
|
||||
bun scripts/cli.ts decision requirement show <id|docNo>
|
||||
```
|
||||
|
||||
管理 `goal|decision|blocker|debt|experiment` 需求记录。`docNo` 唯一，未传 `--doc-no` 但提供 `--doc-type/--doc-priority/--year` 时由服务分配下一个序号。
|
||||
|
||||
---
|
||||
|
||||
## 工作日记
|
||||
|
||||
### 导入
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts decision diary import <markdown-file>
|
||||
```
|
||||
|
||||
将带 `# YYYY年M月D日`、`# YYYY-MM-DD` 或 `# YYYY/M/D` 标题的工作日志拆成每天一篇写入 PostgreSQL。
|
||||
|
||||
### 列表/历史/查看
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts decision diary list [--include-body]
|
||||
bun scripts/cli.ts decision diary history [--include-body]
|
||||
bun scripts/cli.ts decision diary show <YYYY-MM-DD|id> [--source-file path]
|
||||
```
|
||||
|
||||
`--source-file` 用于同一天存在多个导入来源时精确选择。
|
||||
|
||||
### 编辑/新增
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts decision diary edit <YYYY-MM-DD|id> --body-file <path> [--title text] [--source-file path] [--tag tag]
|
||||
bun scripts/cli.ts decision diary upsert <YYYY-MM-DD|id> --body-file <path> [--title text] [--source-file path] [--tag tag]
|
||||
```
|
||||
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: unidesk-gh
|
||||
description: UniDesk GitHub CLI - 通过 `bun scripts/cli.ts gh ...` 管理 GitHub issue/PR，不依赖原生 `gh` binary。用户提到 gh、GitHub issue、GitHub PR、创建 issue、评论 issue、合并 PR、preflight、看板操作时使用。
|
||||
---
|
||||
|
||||
# UniDesk GitHub CLI
|
||||
|
||||
UniDesk 受控 GitHub 操作入口，所有 issue/PR 读写走 `bun scripts/cli.ts gh <subcommand>`，不依赖原生 `gh` binary，不手写 `curl`/GraphQL。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts gh ...`
|
||||
|
||||
---
|
||||
|
||||
## 认证探测
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh auth status [--repo owner/name]
|
||||
```
|
||||
|
||||
探测 token 来源（`GH_TOKEN`/`GITHUB_TOKEN`/`gh auth token`）、GitHub REST egress、repo 可见性、issue 可读性。不打印 token。
|
||||
|
||||
---
|
||||
|
||||
## Issue 命令
|
||||
|
||||
### 列表
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue list [owner/repo] \
|
||||
[--state open|closed|all] [--limit N] [--search text] \
|
||||
[--label label[,label...]] [--repo owner/name] \
|
||||
[--json number,title,state,url,updatedAt,createdAt,author,labels] [--raw|--full]
|
||||
```
|
||||
|
||||
默认 `state=open`、`limit=30`。`owner/repo` 位置参数等价 `--repo`。`--search` 走 GitHub Search API 做查重。
|
||||
|
||||
### 查看
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue view <number|url|owner/repo#number> \
|
||||
[--repo owner/name] [--json body,title,state,comments] [--raw|--full]
|
||||
```
|
||||
|
||||
`read` 是兼容别名。支持 `owner/repo#number` shorthand（如 `pikasTech/HWLAB#1024`）。
|
||||
|
||||
### 创建
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue create \
|
||||
--repo owner/name \
|
||||
--title "标题" \
|
||||
--label "bug,v0.2" \
|
||||
--body-stdin <<'EOF'
|
||||
正文（Markdown，支持换行、反引号、表格）
|
||||
EOF
|
||||
```
|
||||
|
||||
`--body-stdin` 是 heredoc/stdin 第一等入口。`--dry-run` 只输出计划不写 GitHub。
|
||||
|
||||
### 更新正文
|
||||
|
||||
```bash
|
||||
# 替换正文
|
||||
bun scripts/cli.ts gh issue update <number> --repo owner/name \
|
||||
--mode replace --body-stdin <<'EOF'
|
||||
新正文
|
||||
EOF
|
||||
|
||||
# 追加正文
|
||||
bun scripts/cli.ts gh issue update <number> --repo owner/name \
|
||||
--mode append --body-stdin <<'EOF'
|
||||
追加内容
|
||||
EOF
|
||||
```
|
||||
|
||||
`edit` 是 `update --mode replace` 的兼容别名。正式写入默认先读当前 issue 做 body guard。
|
||||
|
||||
### 评论
|
||||
|
||||
```bash
|
||||
# 创建评论
|
||||
bun scripts/cli.ts gh issue comment create <number|owner/repo#number> \
|
||||
--repo owner/name --body-stdin <<'EOF'
|
||||
评论正文
|
||||
EOF
|
||||
|
||||
# 删除评论
|
||||
bun scripts/cli.ts gh issue comment delete <commentId>
|
||||
```
|
||||
|
||||
`--body <short-text>` 仅适合短单行。
|
||||
|
||||
### 关闭/重开
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue close <number|owner/repo#number> \
|
||||
--repo owner/name [--comment "关闭原因"]
|
||||
|
||||
bun scripts/cli.ts gh issue reopen <number|owner/repo#number> \
|
||||
--repo owner/name [--comment "重开原因"]
|
||||
```
|
||||
|
||||
附长证据时先用 `comment create` 写证据评论，再用 `close --comment <短引用>` 关闭。不支持 `delete`（走 `close`）。
|
||||
|
||||
### 批量过期关闭
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue stale-close \
|
||||
--repo owner/name [--inactive-hours 48] [--limit N] \
|
||||
[--label label] [--dry-run]
|
||||
```
|
||||
|
||||
关闭 `updatedAt < observedAt - inactiveHours` 的 open issue。先 `--dry-run` 观察，再正式执行。
|
||||
|
||||
### 转义扫描
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue scan-escape \
|
||||
--repo owner/name [--limit N] [--dry-run]
|
||||
```
|
||||
|
||||
只读扫描 issue 正文/评论中的字面量 `\n`、`\t`、ANSI escape 等污染。
|
||||
|
||||
---
|
||||
|
||||
## PR 命令
|
||||
|
||||
### 列表
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr list [owner/repo] \
|
||||
[--state open|closed|all] [--json ...] [--raw|--full]
|
||||
```
|
||||
|
||||
### 查看
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr view <number|url|owner/repo#number> \
|
||||
[--repo owner/name] \
|
||||
[--json body,title,state,stateDetail,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup] \
|
||||
[--raw|--full]
|
||||
```
|
||||
|
||||
`stateDetail` 归一化为 `open|closed|merged`。`mergeable`/`mergeStateStatus`/`statusCheckRollup` 走 GraphQL。
|
||||
|
||||
### 文件变更
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr files <number> [--repo owner/name] [--limit N]
|
||||
```
|
||||
|
||||
返回 changed files 统计，不输出 raw diff。`gh pr diff <number> --stat` 是兼容别名。
|
||||
|
||||
### 收口预检
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr preflight <number|owner/repo#number> \
|
||||
[--repo owner/name] [--full|--raw]
|
||||
```
|
||||
|
||||
`preflight`/`closeout` 是别名。只读检查 state/draft/conflict/mergeable/statusCheck，不写 GitHub。默认只给 status check 计数与失败预览。
|
||||
|
||||
### 创建
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr create \
|
||||
--repo owner/name \
|
||||
--title "标题" \
|
||||
--body-stdin --base master --head <branch> \
|
||||
[--draft] [--dry-run] <<'EOF'
|
||||
PR 正文
|
||||
EOF
|
||||
```
|
||||
|
||||
### 合并
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr merge <number> \
|
||||
[--repo owner/name] [--merge|--squash|--rebase] \
|
||||
[--delete-branch] [--dry-run]
|
||||
```
|
||||
|
||||
guarded merge：先做 closeout 预检，拒绝非 ready PR。已 merged 返回 `alreadyMerged=true`。
|
||||
|
||||
### 编辑 / 评论 / 关闭 / 重开
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh pr update <number> --mode replace|append --body-stdin [--title ...]
|
||||
bun scripts/cli.ts gh pr comment create <number> --body-stdin
|
||||
bun scripts/cli.ts gh pr comment delete <commentId>
|
||||
bun scripts/cli.ts gh pr close <number> [--comment ...]
|
||||
bun scripts/cli.ts gh pr reopen <number> [--comment ...]
|
||||
```
|
||||
|
||||
与 issue 对应命令行为一致。
|
||||
|
||||
---
|
||||
|
||||
## 虚拟文件系统 (`trans gh:`)
|
||||
|
||||
```bash
|
||||
# 列出 repo
|
||||
trans gh:/pikasTech/HWLAB ls
|
||||
|
||||
# 列出 PR / Issue
|
||||
trans gh:/pikasTech/HWLAB/pr ls [--limit N] [--full]
|
||||
trans gh:/pikasTech/HWLAB/issue ls [--limit N] [--full]
|
||||
|
||||
# 查看单个条目
|
||||
trans gh:/pikasTech/HWLAB/pr/507 ls
|
||||
trans gh:/pikasTech/HWLAB/505/1 cat
|
||||
|
||||
# patch-apply 写回正文（走 gh issue/pr update）
|
||||
trans gh:/pikasTech/HWLAB/pr/507 apply-patch <<'PATCH'
|
||||
*** Begin Patch
|
||||
*** Update File: body.md
|
||||
@@
|
||||
old line
|
||||
-old line
|
||||
+new line
|
||||
more context
|
||||
*** End Patch
|
||||
PATCH
|
||||
```
|
||||
|
||||
正文一楼映射为 `body.md`。写回走 `gh issue/pr update` 的 guard 规则。`rm` 对正文结构化拒绝。
|
||||
|
||||
---
|
||||
|
||||
## 看板命令 (#20 总看板)
|
||||
|
||||
```bash
|
||||
# 结构审计
|
||||
bun scripts/cli.ts gh issue board-audit \
|
||||
--repo pikasTech/unidesk --board-issue 20 [--dry-run]
|
||||
|
||||
# 行列表
|
||||
bun scripts/cli.ts gh issue board-row list \
|
||||
--board-issue 20 [--state open|closed|all]
|
||||
|
||||
# 行查看
|
||||
bun scripts/cli.ts gh issue board-row get <issueNumber> --board-issue 20
|
||||
|
||||
# 行更新（单字段）
|
||||
bun scripts/cli.ts gh issue board-row update <issueNumber> \
|
||||
--board-issue 20 \
|
||||
--field progress|status|validation|branch|tasks|focus \
|
||||
--value <text> \
|
||||
[--expect-body-sha <sha>|--expect-updated-at <ts>]
|
||||
|
||||
# 行新增/插入（upsert）
|
||||
bun scripts/cli.ts gh issue board-row upsert <issueNumber> \
|
||||
--board-issue 20 --section open|closed \
|
||||
--branch <branch> --tasks <task> --summary <text> \
|
||||
--focus <text> --validation <text> --progress <text> \
|
||||
[--expect-body-sha <sha>|--expect-updated-at <ts>]
|
||||
|
||||
# 行移动 / 删除
|
||||
bun scripts/cli.ts gh issue board-row move <issueNumber> \
|
||||
--board-issue 20 --to open|closed [--status OPEN|CLOSED]
|
||||
bun scripts/cli.ts gh issue board-row delete <issueNumber> \
|
||||
--board-issue 20
|
||||
```
|
||||
|
||||
写操作默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。
|
||||
|
||||
---
|
||||
|
||||
## 关键约定
|
||||
|
||||
### heredoc 优先
|
||||
|
||||
多行正文/评论一律用 `--body-stdin <<'EOF'`（quoted heredoc），不用 `--body` 内联长文本、不用临时文件、不用 `gh api -f body=...`：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue create --repo pikasTech/HWLAB \
|
||||
--title "标题" --body-stdin <<'EOF'
|
||||
正文，支持 `code`、**bold**、表格等 Markdown
|
||||
EOF
|
||||
```
|
||||
|
||||
### owner/repo#number shorthand
|
||||
|
||||
所有接受 issue/PR number 的命令都支持：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue view pikasTech/HWLAB#1024
|
||||
bun scripts/cli.ts gh pr preflight pikasTech/HWLAB#1020
|
||||
bun scripts/cli.ts gh issue comment create pikasTech/HWLAB#1024 --body-stdin <<'EOF'
|
||||
...
|
||||
EOF
|
||||
```
|
||||
|
||||
shorthand 与显式 `--repo` 冲突时结构化失败。
|
||||
|
||||
### 干跑优先
|
||||
|
||||
写操作前先 `--dry-run`：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh issue update 20 --mode append --body-stdin --dry-run <<'EOF'
|
||||
...
|
||||
EOF
|
||||
```
|
||||
|
||||
### debug 任务入口
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run ...] [--pr-create-dry-run ...] [--issue N] [--full|--raw]
|
||||
```
|
||||
|
||||
用于 PR 型派单 admission，检查 scheduler auth、runner GH token、git worktree、GitHub egress 等。
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: unidesk-ops
|
||||
description: UniDesk 手动运维 CLI — `server` 和 `gc` 子命令，覆盖主 server 启停、健康检查、swap、日志、Docker 镜像清理、磁盘 GC 和服务重建。用户提到 server start、server status、server swap、server rebuild、gc、磁盘清理、运维时使用。
|
||||
---
|
||||
|
||||
# UniDesk 手动运维 CLI
|
||||
|
||||
主 server 运维入口，通过 `bun scripts/cli.ts server ...` 和 `bun scripts/cli.ts gc ...` 操作。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts ...`
|
||||
|
||||
---
|
||||
|
||||
## 启停
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server start
|
||||
bun scripts/cli.ts server stop
|
||||
```
|
||||
|
||||
异步 job 模式，返回 `job.id`、日志路径。`start` 执行 Docker 构建+启动，`stop` 停止 Compose project 全部服务。
|
||||
|
||||
---
|
||||
|
||||
## 健康检查
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server status
|
||||
```
|
||||
|
||||
返回公开端口、受限宿主端口、内部端口、swap 摘要、Compose 容器状态、各服务健康检查和访问 URL。
|
||||
|
||||
低内存时 `swap.warning` 非空，先执行 `server swap ensure`。
|
||||
|
||||
---
|
||||
|
||||
## Swap 管理
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server swap status
|
||||
bun scripts/cli.ts server swap ensure [--path /swapfile] [--size 2GiB] [--dry-run]
|
||||
```
|
||||
|
||||
`ensure` 在无 active swap 时创建 swapfile（`chmod 600`、`mkswap`、`swapon`、写 `/etc/fstab`）。已有 swap 时 no-op。fstab 写入失败返回 `degraded`。
|
||||
|
||||
---
|
||||
|
||||
## 日志
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server logs
|
||||
```
|
||||
|
||||
返回文件日志和 Docker 容器日志尾部，默认限制输出大小。
|
||||
|
||||
---
|
||||
|
||||
## Docker 镜像清理
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server cleanup plan [--min-age-hours 24] [--limit N]
|
||||
```
|
||||
|
||||
只生成 dry-run 计划，不执行删除。保守白名单：保留 running/stopped 容器镜像、deploy.json/CI.json commit-pinned artifact、Compose stable image。禁止 `docker system prune`、`docker volume rm`、`docker compose down -v`。
|
||||
|
||||
---
|
||||
|
||||
## 磁盘 GC
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gc plan
|
||||
bun scripts/cli.ts gc run --confirm
|
||||
bun scripts/cli.ts gc db-trace
|
||||
bun scripts/cli.ts gc policy
|
||||
bun scripts/cli.ts gc remote <providerId> [--target-use-percent N] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
主 server 和 provider 磁盘高水位缓解。`plan` 只读输出候选、风险、估算收益和保护对象。`run` 必须 `--confirm`。`remote` 通过 SSH 透传执行远端 GC。
|
||||
|
||||
---
|
||||
|
||||
## 服务重建
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server rebuild <service>
|
||||
```
|
||||
|
||||
service 可选：`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` 替换容器 → 等待 `healthy/running`。
|
||||
|
||||
启动后必须轮询 job，不要把提交 job 当成已经完成：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server rebuild backend-core
|
||||
bun scripts/cli.ts job status <jobId> --tail-bytes 12000
|
||||
```
|
||||
|
||||
backend-core 重建完成后再做运行面验证：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server status
|
||||
docker exec unidesk-backend-core sh -lc 'backend-core --fetch-json http://127.0.0.1:8080/health --require-ok'
|
||||
```
|
||||
|
||||
**禁止事项**：
|
||||
- backend-core 常规迭代不得在 master server 编译；只有已提交修复需要上线主 server Compose runtime 时，才用 `server rebuild backend-core` 受控异步 job
|
||||
- D601 Code Queue 执行面不由 `server rebuild` 管理
|
||||
- 不重建/删除 database 命名卷
|
||||
|
||||
---
|
||||
|
||||
## Moon Bridge 管理
|
||||
|
||||
Moon Bridge 是 Codex ↔ 上游 provider 的桥接服务，通过 profile 级 wrapper 管理：
|
||||
|
||||
```bash
|
||||
# DeepSeek profile
|
||||
dscx bridge-start
|
||||
dscx bridge-status
|
||||
dscx bridge-smoke dscx-bridge-ok
|
||||
dscx bridge-stop
|
||||
|
||||
# MiniMax profile
|
||||
mxcx bridge-start
|
||||
mxcx bridge-status
|
||||
mxcx bridge-smoke mxcx-bridge-ok
|
||||
mxcx bridge-stop
|
||||
```
|
||||
|
||||
- `dscx` → `127.0.0.1:38440`（Codex custom provider `deepseek`，DeepSeek V4 Pro）
|
||||
- `mxcx` → `127.0.0.1:38441`（Codex custom provider `minimax`，MiniMax-M3）
|
||||
- 启动用 `setsid` + profile-local PID file，进程不随 CLI 退出
|
||||
- 日志在 `<CODEX_HOME>/logs/moonbridge/`
|
||||
|
||||
---
|
||||
|
||||
## Codex Profile Smoke
|
||||
|
||||
```bash
|
||||
# DeepSeek
|
||||
dscx doctor
|
||||
dscx bridge-smoke dscx-bridge-ok
|
||||
dscx exec --skip-git-repo-check 'Reply exactly: dscx-codex-ok'
|
||||
|
||||
# MiniMax
|
||||
mxcx doctor
|
||||
mxcx bridge-smoke mxcx-bridge-ok
|
||||
mxcx exec --skip-git-repo-check 'Reply exactly: mxcx-codex-ok'
|
||||
```
|
||||
|
||||
`bridge-smoke` 验证 Moon Bridge → provider 链路。`exec` 验证完整 Codex CLI → bridge → provider 全链路。
|
||||
|
||||
---
|
||||
|
||||
## MiniMax Session Recovery
|
||||
|
||||
MiniMax 会话因无效 tool-call arguments 导致 `resume` 反复失败时的恢复流程：
|
||||
|
||||
```bash
|
||||
# 1. 清理无效 tool arguments
|
||||
mxcx session-clean <session-id-or-jsonl>
|
||||
|
||||
# 2. 确认幂等（应返回 changed=false）
|
||||
mxcx session-clean <session-id-or-jsonl>
|
||||
|
||||
# 3. 注入 guard 防止复发
|
||||
mxcx session-guard <session-id-or-jsonl>
|
||||
|
||||
# 4. 非交互 smoke 验证恢复
|
||||
mxcx exec resume <session-id> 'Reply exactly: recovered-ok'
|
||||
|
||||
# 5. apply-patch smoke（如涉及远端编辑）
|
||||
# 验证使用 trans <route> apply-patch，非 download/upload/sed
|
||||
```
|
||||
|
||||
`mxcx resume <session-id>` 自动执行 `session-clean` + `session-guard` 后再调用 Codex。修复最小化：只修无效 `function_call.arguments`，不压缩/截断/重排 transcript。
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- **主 server 架构与行为规范**: `/root/docs/reference/master-server-ops.md`（Execution Boundary、Codex Provider Profile 架构、Moon Bridge 内部规则、MiniMax session-clean 行为约束、apply-patch 策略）
|
||||
- **磁盘 GC 长期规则**: `docs/reference/gc.md`
|
||||
- **部署边界**: `docs/reference/deployment.md`
|
||||
@@ -0,0 +1,315 @@
|
||||
---
|
||||
name: unidesk-trans
|
||||
description: UniDesk SSH 透传与 apply-patch 语法 — `trans <route> <operation>` 分布式执行入口，包含 route 语法、workspace/k3s/Windows 路由、apply-patch envelope 格式、script/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`，等价 `bun scripts/cli.ts ssh "$@"`）
|
||||
|
||||
---
|
||||
|
||||
## 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 script -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2'
|
||||
trans D601:/home/ubuntu/workspace/unidesk-dev script <<'SCRIPT'
|
||||
...
|
||||
SCRIPT
|
||||
```
|
||||
|
||||
**规则**: workspace 路径写在 route 第一个 token，不写进 `cd` 串。反面示例：~~`trans G14 script -- '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-abc/app cat /app/version.txt
|
||||
trans G14:k3s:hwlab-dev:pod-name/workspace apply-patch <<'PATCH'
|
||||
...
|
||||
PATCH
|
||||
```
|
||||
|
||||
CLI 自动注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`。
|
||||
|
||||
### 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。
|
||||
|
||||
---
|
||||
|
||||
## Operation
|
||||
|
||||
### script（POSIX shell heredoc）
|
||||
|
||||
```bash
|
||||
# heredoc（多行脚本）
|
||||
trans G14:/root/hwlab script <<'SCRIPT'
|
||||
echo "step 1"
|
||||
git status --short --branch
|
||||
echo "step 2"
|
||||
SCRIPT
|
||||
|
||||
# one-liner
|
||||
trans G14:/root/hwlab script -- 'git fetch origin G14 && git pull --ff-only origin G14'
|
||||
|
||||
# direct argv（单进程，带 -- 参数）
|
||||
trans D601:/path script -- sed -n '1,20p' AGENTS.md
|
||||
```
|
||||
|
||||
`script` 只走 host/k3s POSIX shell。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` 即完整性证明。
|
||||
|
||||
### 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`。
|
||||
|
||||
快速验证 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 argv bash -lc '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+workspace，不要从 host 生成 diff 再改路径上传：
|
||||
|
||||
```bash
|
||||
# ✅ 正确
|
||||
trans G14:k3s:hwlab-dev:hwlab-cloud-web-abc/app/web apply-patch <<'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 script -- 'hwlab-cli case run start d601-f103-v2-compile'
|
||||
trans G14:/root/hwlab script -- 'hwlab-cli case run status <runId>'
|
||||
|
||||
# ❌ 长时间挂着等
|
||||
trans G14:/root/hwlab script -- 'long_running_command && wait'
|
||||
```
|
||||
|
||||
### HINT 信号
|
||||
|
||||
| stderr 输出 | 含义 |
|
||||
|-------------|------|
|
||||
| `UNIDESK_SSH_HINT` | SSH 握手/超时摩擦，提示改用 stdin script |
|
||||
| `UNIDESK_TRAN_TIMEOUT_HINT` | 60s 硬超时触发，提示改用短查询+轮询 |
|
||||
| `UNIDESK_SSH_TIMING` | 慢命令 warning（>10s），用于性能回归监控 |
|
||||
| `UNIDESK_APPLY_PATCH_TIMING` | apply-patch 耗时摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 关键约定
|
||||
|
||||
### heredoc 优先
|
||||
|
||||
多行远端脚本优先用 heredoc，不拼接 shell 字符串：
|
||||
|
||||
```bash
|
||||
# ✅ 推荐
|
||||
trans G14:/root/hwlab script <<'SCRIPT'
|
||||
cmd1
|
||||
cmd2
|
||||
SCRIPT
|
||||
|
||||
# ❌ 避免
|
||||
trans G14 script -- 'cmd1 && cmd2 && cmd3'
|
||||
```
|
||||
|
||||
### 本地 shell 运算符陷阱
|
||||
|
||||
`&&` / `;` / `|` 在 `trans` 后面会被本地 shell 截获。需要远端执行多条命令时用 `script` 包裹：
|
||||
|
||||
```bash
|
||||
# ❌ 第二个 sed 在 master server 本地执行
|
||||
trans G14:/root/hwlab sed -n '1,20p' a && sed -n '1,20p' b
|
||||
|
||||
# ✅ 两个 sed 都在远端
|
||||
trans G14:/root/hwlab script -- '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
|
||||
```
|
||||
@@ -86,7 +86,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
|
||||
|
||||
## Critical CI/CD CLI Control Rule
|
||||
|
||||
- P0: 任何 agentrun、HWLAB 或其他 G14 k3s 服务的代码变更需要部署时，必须加载并遵循 `unidesk-cicd` skill 的标准流程（git-mirror sync → trigger-current → status 轮询）；禁止手动 `kubectl exec/cp/delete`、直接操作 pod 容器、或绕过 PipelineRun 做原地热补。skill 路径：`~/.agents/skills/unidesk-cicd/SKILL.md`。
|
||||
- P0: 任何 agentrun、HWLAB 或其他 G14 k3s 服务的代码变更需要部署时，必须加载并遵循 `unidesk-cicd` skill 的标准流程（git-mirror sync → trigger-current → status 轮询）；禁止手动 `kubectl exec/cp/delete`、直接操作 pod 容器、或绕过 PipelineRun 做原地热补。skill 路径：`.agents/skills/unidesk-cicd/SKILL.md`。
|
||||
- P0: CI/CD、GitOps、rollout、artifact 发布、PR 合并后 DEV/PROD 滚动、PipelineRun 重跑/清理、Argo refresh 和运行面 retention 这类控制动作必须走 UniDesk CLI 的受控子命令；禁止把原生 `kubectl`、`argo`、`tkn`、`gh`、`curl` 或临时 shell 当作正式控制入口。
|
||||
- P0: `trans <route> kubectl|logs|get|describe` / `tran <route> ...` 只作为 CLI 介导的短查询诊断和证据采集底座；一旦某个 CI/CD 写操作需要重复使用，必须先补齐 `bun scripts/cli.ts ...` 高层子命令并把用法写入 `docs/reference/cli.md`，不能长期靠低层 route 手工 patch/annotate/delete。
|
||||
- P0: 若现有 CLI 字段、状态、权限或动作不够，默认先改进 UniDesk CLI 后继续发布；不得绕过为原生命令直连 GitHub、Kubernetes、Tekton、Argo 或 registry。长期细则见 `docs/reference/cli.md`。
|
||||
|
||||
Reference in New Issue
Block a user