From e17f15bdce1460fcefb9979cbbfd6b105d873901 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 9 Jun 2026 07:14:06 +0000 Subject: [PATCH] docs: move unidesk skills into repo --- .agents/skills/unidesk-cicd/SKILL.md | 224 +++++++++++++++ .agents/skills/unidesk-code-queue/SKILL.md | 168 +++++++++++ .agents/skills/unidesk-decision/SKILL.md | 84 ++++++ .agents/skills/unidesk-gh/SKILL.md | 312 ++++++++++++++++++++ .agents/skills/unidesk-ops/SKILL.md | 185 ++++++++++++ .agents/skills/unidesk-trans/SKILL.md | 315 +++++++++++++++++++++ AGENTS.md | 2 +- 7 files changed, 1289 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/unidesk-cicd/SKILL.md create mode 100644 .agents/skills/unidesk-code-queue/SKILL.md create mode 100644 .agents/skills/unidesk-decision/SKILL.md create mode 100644 .agents/skills/unidesk-gh/SKILL.md create mode 100644 .agents/skills/unidesk-ops/SKILL.md create mode 100644 .agents/skills/unidesk-trans/SKILL.md diff --git a/.agents/skills/unidesk-cicd/SKILL.md b/.agents/skills/unidesk-cicd/SKILL.md new file mode 100644 index 00000000..f50714fc --- /dev/null +++ b/.agents/skills/unidesk-cicd/SKILL.md @@ -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- + +# 定点 source commit +bun scripts/cli.ts hwlab g14 control-plane status \ + --lane v02 --source-commit +``` + +定点 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 --confirm` 受控清理失败 PipelineRun 后重试。旧 branch/path allowlist gate 已删除，不要恢复旧 hook、直接 `kubectl delete`、手工 patch pod 内 hook 或绕过 `flush`。 + +手动 trigger closeout 不能只看 PipelineRun `Completed`。必须继续查 `control-plane status --pipeline-run ` 和 `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 [--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 ] [--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 \ + [--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 --source-commit +``` + +手动补记 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-` 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。 diff --git a/.agents/skills/unidesk-code-queue/SKILL.md b/.agents/skills/unidesk-code-queue/SKILL.md new file mode 100644 index 00000000..1570f65c --- /dev/null +++ b/.agents/skills/unidesk-code-queue/SKILL.md @@ -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 + +# 提交 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 +bun scripts/cli.ts agentrun v01 sessions output +bun scripts/cli.ts agentrun v01 sessions read +bun scripts/cli.ts agentrun v01 sessions steer --prompt-stdin +bun scripts/cli.ts agentrun v01 sessions cancel +``` + +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 ... +bun scripts/cli.ts codex resume ... +bun scripts/cli.ts codex queue create +bun scripts/cli.ts codex queue merge --into +bun scripts/cli.ts codex move --queue +``` + +不要用兼容开关、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 [--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 `。 + +--- + +## Trace / Output 分页 + +```bash +# 逻辑 trace（分页） +bun scripts/cli.ts codex task --trace \ + [--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full] + +# 原始 output（分页补取） +bun scripts/cli.ts codex output \ + [--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full-text] +``` + +--- + +## 标记已读 + +```bash +bun scripts/cli.ts codex read +``` + +标记单个终态任务已读，同时返回任务身份、终态 attempt 摘要和最终 response。 + +--- + +## Judge（复现评判） + +```bash +bun scripts/cli.ts codex judge --attempt N [--dry-run] [--include-prompt] +``` + +按指定 attempt 单步复现 judge，诊断入口。 + +--- + +## 中断/取消 + +```bash +bun scripts/cli.ts codex interrupt +bun scripts/cli.ts codex cancel +``` + +仅用于停止旧 Code Queue 残留任务；新 AgentRun session 使用 `bun scripts/cli.ts agentrun v01 sessions cancel `。 + +--- + +## 旧队列归档 + +```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 任务。 diff --git a/.agents/skills/unidesk-decision/SKILL.md b/.agents/skills/unidesk-decision/SKILL.md new file mode 100644 index 00000000..e604b82e --- /dev/null +++ b/.agents/skills/unidesk-decision/SKILL.md @@ -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 +bun scripts/cli.ts decision list [--include-body] +bun scripts/cli.ts decision show +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 --field ... +bun scripts/cli.ts decision requirement show +``` + +管理 `goal|decision|blocker|debt|experiment` 需求记录。`docNo` 唯一，未传 `--doc-no` 但提供 `--doc-type/--doc-priority/--year` 时由服务分配下一个序号。 + +--- + +## 工作日记 + +### 导入 + +```bash +bun scripts/cli.ts decision diary import +``` + +将带 `# 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 [--source-file path] +``` + +`--source-file` 用于同一天存在多个导入来源时精确选择。 + +### 编辑/新增 + +```bash +bun scripts/cli.ts decision diary edit --body-file [--title text] [--source-file path] [--tag tag] +bun scripts/cli.ts decision diary upsert --body-file [--title text] [--source-file path] [--tag tag] +``` diff --git a/.agents/skills/unidesk-gh/SKILL.md b/.agents/skills/unidesk-gh/SKILL.md new file mode 100644 index 00000000..2b5751fe --- /dev/null +++ b/.agents/skills/unidesk-gh/SKILL.md @@ -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 `，不依赖原生 `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 \ + [--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 --repo owner/name \ + --mode replace --body-stdin <<'EOF' +新正文 +EOF + +# 追加正文 +bun scripts/cli.ts gh issue update --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 \ + --repo owner/name --body-stdin <<'EOF' +评论正文 +EOF + +# 删除评论 +bun scripts/cli.ts gh issue comment delete +``` + +`--body ` 仅适合短单行。 + +### 关闭/重开 + +```bash +bun scripts/cli.ts gh issue close \ + --repo owner/name [--comment "关闭原因"] + +bun scripts/cli.ts gh issue reopen \ + --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 \ + [--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 [--repo owner/name] [--limit N] +``` + +返回 changed files 统计，不输出 raw diff。`gh pr diff --stat` 是兼容别名。 + +### 收口预检 + +```bash +bun scripts/cli.ts gh pr preflight \ + [--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 \ + [--draft] [--dry-run] <<'EOF' +PR 正文 +EOF +``` + +### 合并 + +```bash +bun scripts/cli.ts gh pr merge \ + [--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 --mode replace|append --body-stdin [--title ...] +bun scripts/cli.ts gh pr comment create --body-stdin +bun scripts/cli.ts gh pr comment delete +bun scripts/cli.ts gh pr close [--comment ...] +bun scripts/cli.ts gh pr reopen [--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 --board-issue 20 + +# 行更新（单字段） +bun scripts/cli.ts gh issue board-row update \ + --board-issue 20 \ + --field progress|status|validation|branch|tasks|focus \ + --value \ + [--expect-body-sha |--expect-updated-at ] + +# 行新增/插入（upsert） +bun scripts/cli.ts gh issue board-row upsert \ + --board-issue 20 --section open|closed \ + --branch --tasks --summary \ + --focus --validation --progress \ + [--expect-body-sha |--expect-updated-at ] + +# 行移动 / 删除 +bun scripts/cli.ts gh issue board-row move \ + --board-issue 20 --to open|closed [--status OPEN|CLOSED] +bun scripts/cli.ts gh issue board-row delete \ + --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 等。 diff --git a/.agents/skills/unidesk-ops/SKILL.md b/.agents/skills/unidesk-ops/SKILL.md new file mode 100644 index 00000000..bbb698b3 --- /dev/null +++ b/.agents/skills/unidesk-ops/SKILL.md @@ -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 [--target-use-percent N] [--dry-run|--confirm] +``` + +主 server 和 provider 磁盘高水位缓解。`plan` 只读输出候选、风险、估算收益和保护对象。`run` 必须 `--confirm`。`remote` 通过 SSH 透传执行远端 GC。 + +--- + +## 服务重建 + +```bash +bun scripts/cli.ts server rebuild +``` + +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 --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 退出 +- 日志在 `/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 + +# 2. 确认幂等（应返回 changed=false） +mxcx session-clean + +# 3. 注入 guard 防止复发 +mxcx session-guard + +# 4. 非交互 smoke 验证恢复 +mxcx exec resume 'Reply exactly: recovered-ok' + +# 5. apply-patch smoke（如涉及远端编辑） +# 验证使用 trans apply-patch，非 download/upload/sed +``` + +`mxcx resume ` 自动执行 `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` diff --git a/.agents/skills/unidesk-trans/SKILL.md b/.agents/skills/unidesk-trans/SKILL.md new file mode 100644 index 00000000..4410a115 --- /dev/null +++ b/.agents/skills/unidesk-trans/SKILL.md @@ -0,0 +1,315 @@ +--- +name: unidesk-trans +description: UniDesk SSH 透传与 apply-patch 语法 — `trans ` 分布式执行入口，包含 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 ` 在远端 host/k3s/Windows 上执行命令或文本 patch。 + +**固定入口**: `trans ...`（wrapper 位于 `/root/.local/bin/trans`，等价 `bun scripts/cli.ts ssh "$@"`） + +--- + +## Route 语法 + +``` +trans [/absolute/workspace] [args...] +trans :[::[:]] [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: +@@ + 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 ' + +# ❌ 长时间挂着等 +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 +``` diff --git a/AGENTS.md b/AGENTS.md index 3f26eb5b..e021c041 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 kubectl|logs|get|describe` / `tran ...` 只作为 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`。