pikasTech-unidesk/AGENTS.md

# UniDesk Agent Index

UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文件是项目顶级索引，也承担 `scripts/cli.ts` 的 CLI 使用说明入口。

## Critical Long-Term Reference Docs Rule

- P0: 任何新增、修改或蒸馏 `docs/reference/*.md` 长期参考文档的动作，必须遵循 `docs-spec` 规范；禁止绕过 `docs-spec` 凭临时习惯改写长期参考。
- `AGENTS.md` 只做顶级索引和一句话规则摘要；长期稳定、可复用的约束、入口、判定标准必须落到 `docs/reference/`，再由 `AGENTS.md` 提供索引。
- 过程记录、一次性排障、临时结论、带日期的流水账不得直接写成长期参考；需要沉淀时必须按 `docs-spec` 先蒸馏，再写入 `docs/reference/`。

## Critical G14 HWLAB Workspace Rule

- P0: `G14:HWLAB` 是当前 HWLAB DEV/PROD source workspace 和 k3s/GitOps 运行面真相；唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`；所有 HWLAB 新开发、文档、render、polling、CI/CD/GitOps 修复默认都必须以该目录和 G14 运行面为准。
- P0: 每次开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 `/root/hwlab/AGENTS.md`，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
- 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 `bun scripts/cli.ts ssh G14 script` 或 `bun scripts/cli.ts ssh G14 apply-patch`，k3s 操作用 `bun scripts/cli.ts ssh G14:k3s ...`；禁止使用 `ssh G14 k3s ...`，定位必须写在第一个 route token，后续 token 才是 operation。
- 每次开始 `G14:HWLAB` 工作前必须先通过 SSH 桥在 G14 执行 `cd /root/hwlab && git status --short --branch && git remote -v`；若分支不是 `G14...origin/G14`、remote 不是 `git@github.com:pikasTech/HWLAB.git`，或当前路径不是 `/root/hwlab`，必须停止并先修正 workspace，不得继续开发、render、polling 或部署。
- 禁止把 master server、D601、`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab` 或临时 clone 当作 `G14:HWLAB` source truth；master server 也不得运行 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证，验证必须走 G14 `/root/hwlab`、G14 k3s/Tekton 或其他获批外部执行面。
- 长期细节见 `docs/reference/g14.md`；G14 节点本地也保留 `/root/docs/hwlab-g14-workspace.md`，两处口径必须保持一致。

## Critical D601 HWLAB Legacy And Hardware Bridge Rule

- P0: `D601:HWLAB` 不再是 HWLAB 默认开发主阵地或运行面真相；`/home/ubuntu/workspace/hwlab-dev` 只作为历史迁移、D601 legacy 回滚、显式指定的 D601 补丁收敛和故障对照 workspace 使用。
- P0: 新的 HWLAB 代码、文档、render、polling、CI/CD、GitOps、DEV/PROD runtime 和验收默认必须走 `G14:HWLAB`；只有用户明确指定 D601 legacy 或 D601 Windows 硬件桥接时，才进入 D601 HWLAB 路径。
- D601 仍是 ConStart/71-FREQ 等 Windows 硬件与 Keil/串口资源的 bridge host；最小 device-agent 实验中，D601 Windows `hwlab-gateway` 可以作为外部 gateway 连接到 G14 `hwlab-dev` cloud-api，而不改变 HWLAB source/runtime truth。
- 每次确需进入 D601 legacy HWLAB workspace 前，仍必须通过 UniDesk SSH 桥执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v`，并重新读取 `/home/ubuntu/workspace/hwlab-dev/AGENTS.md`；发现 D601 口径与 G14 `/root/hwlab/AGENTS.md` 冲突时，以 G14 当前规则为准。
- `/home/ubuntu/workspace/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、`/home/ubuntu/hwlab` runner 历史目录和 master-server checkout 都不能作为 HWLAB 当前开发真相。
- 长期细节见 `docs/reference/hwlab.md`。

## Critical D601 UniDesk Workspace Rule

- P0: `D601:UniDesk` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/unidesk-dev`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/unidesk.git`；所有需要在 D601 上改 UniDesk 代码、跑轻量合同测试、做分布式敏捷实验补丁收敛或验证 Code Queue runner/tran 的工作，都必须优先使用这个目录。
- P0: 每次开始 `D601:UniDesk` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 `/home/ubuntu/workspace/unidesk-dev/AGENTS.md`，并以该文件和其引用的 UniDesk repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
- `/home/ubuntu/cq-deploy`、`/root/unidesk`、`/app`、Code Queue pod 内 `/root/unidesk` 和 `/tmp/unidesk-*` 都是运行副本、部署副本或一次性实验面，不是 `D601:UniDesk` 日常开发 source truth；运行面热修可以直接作用于 pod/容器，但必须随后把持久化修复落回 fixed workspace 和 Git remote。
- 每次开始 `D601:UniDesk` 工作前必须通过 UniDesk SSH 桥执行 `cd /home/ubuntu/workspace/unidesk-dev && git status --short --branch && git remote -v`；若路径、分支、remote 或权限不符合预期，必须先修正固定 workspace，再继续开发、测试或发布。
- D601 上 UniDesk 验证必须通过 UniDesk 透传在 D601 执行，禁止回到 master server 跑仓库级 check、Playwright/browser smoke、镜像构建或其他重型验证。Code Queue/tran 运行面验证应优先直达 D601 原生 k3s pod，k3s 操作使用 route 语法 `D601:k3s ...`。
- 长期细节见 `docs/reference/dev-environment.md`。

## Critical D601 Kubernetes Control-Plane Rule

- P0: D601 上的 Kubernetes 运行面只能以自部署原生 k3s 为准；Docker Desktop Kubernetes 已经停用并清理数据，任何人不得重新启用或把它作为 UniDesk/HWLAB 部署、CI/CD、诊断或验收目标。跟踪 issue: [pikasTech/unidesk#138](https://github.com/pikasTech/unidesk/issues/138)，热修复背景见 [pikasTech/unidesk#118](https://github.com/pikasTech/unidesk/issues/118)。
- D601 上裸 `kubectl` 不可信：`/home/ubuntu/.kube/config` 可能仍残留 `docker-desktop` / `127.0.0.1:11700`。所有 D601 k3s 读写、Tekton、Code Queue、UniDesk DEV 和显式 D601 legacy HWLAB 排障必须显式使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`，并在写操作前确认节点名是 `d601`。
- 写操作的实际目标 context/server/nodes 出现 `desktop-control-plane`、`docker-desktop` 或 `127.0.0.1:11700`，发现 Docker Desktop Kubernetes namespace、旧 direct Docker `code-queue-backend`，或同一服务被 Docker Desktop k8s 与原生 k3s 同时承载时，必须立即停止部署动作并按 #138 处理；裸 `kubectl` 默认 context 只作为诊断，不能把第二控制面的状态当作恢复证据。

## Critical GitHub Issue Write Rule

- P0: 对 GitHub issue/PR 做正式写入时必须优先使用 `bun scripts/cli.ts gh ...`；禁止用原生 `gh issue edit/create/comment` 直接写 UniDesk/HWLAB 长期看板、指挥简报或用户反馈 issue。事故和 CLI 补强需求见 [pikasTech/unidesk#142](https://github.com/pikasTech/unidesk/issues/142)。
- #20、HWLAB #7 和指挥简报类正文不得使用原生 `gh issue edit --body-file -`、shell 管道 stdin 或无 guard 的整篇替换。当前 CLI 局部替换能力未完成前，必须先 dry-run、保留 before body、确认 body guard，再写入。

## Critical Git / Multi-Repo Sync Rule

- UniDesk 同时存在 main server、D601 `~/cq-deploy` 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。
- 任何开发、文档或部署配置变更开始前，必须先在当前 worktree 执行 `git status` 并从主线拉取最新源码：`git pull --ff-only origin master`；若本地并行变更或远端推进导致不能快进，必须当即分清来源并解决冲突后再继续。
- 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 `git-spec` 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。
- 提交前必须用 `git status` 和 `git diff` 区分并只提交当前任务相关文件，保留并避开并行任务产生的无关修改；所有 UniDesk agent 变更只允许在 `master` 上开发并 `git push origin master`，禁止新建、切换到或推送其他分支；长期规则见 `docs/reference/arch.md`。
- `release/v1` 是规划中的稳定维护线，不是普通 feature/fix 分支；创建、更新或启用必须作为显式 release operation，先满足 `docs/reference/release-governance.md` 和 GitHub issue #6 的 CLI/CI/CD/文档条件。当前常规 agent 任务仍按 master-only 规则执行。
- `frontend`、`scripts/cli.ts`、`tran` 和分布式 SSH 透传能力跟随 `master`；`release/v1` 仅用于明确批准的 backend-core / Code Queue 稳定维护，不作为 frontend 或 CLI/tran 修复的 backport 目标。

## Critical Master Server Build Ban

- Master server 是生产入口和控制面，不得当作构建机使用；严厉禁止在 master server 上执行 Docker 镜像构建、`docker build`、`docker buildx build`、`docker compose build`、`docker compose up --build`、Rust 编译/测试（`cargo build`、`cargo test`、`rustc`）、Go 编译/测试（`go build`、`go test`）以及其他高 CPU/高内存编译构建任务。这类任务可能拖垮生产服务器，造成 UniDesk 整体不可用。
- Master server 资源也不足以承载仓库级 `check`/`test`/smoke 验证；禁止在 master server 上运行 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、Playwright/browser smoke 或其他会遍历大仓库、启动浏览器、长时间占用 CPU/内存的校验命令。HWLAB 正式验证必须改在 G14 `/root/hwlab`、G14 k3s/Tekton 或其他获批外部执行面完成；非 HWLAB 的 D601 服务仍按各自 reference 使用 D601 原生 k3s/CI runner。
- 镜像和编译产物必须通过标准 CI/CD 在外部构建资源上生成；HWLAB 默认使用 G14 k3s/Tekton/GitOps 或经过批准的外部 builder，非 HWLAB 服务按各自 reference 使用 D601 原生 k3s/Tekton 或其他获批外部 builder；源码以 Git remote 为 source of truth，CI 产出 commit-pinned image/artifact。
- Prod 发布必须走 CD pull-only 流程：由 `deploy.json` 声明期望服务版本，生产侧 CD 拉取已经构建好的镜像或 artifact 并按 `deploy.json` 部署；禁止把 master server 本地 Docker image、临时容器层或本地编译产物作为部署真相。
- 在 master server 上只允许轻量源码编辑、Git 操作、状态/健康/日志/诊断、JSON CLI 控制面操作和受控 CD 观察；一旦步骤需要构建镜像或编译 Rust/Go 等重型产物，必须停止在 master server 执行并改走 CI/CD 或 D601 构建路径。

## Critical Provider Gateway Upgrade Rule

- `src/components/provider-gateway` 有任何代码或行为变更时，必须在同一变更集中递增 `src/components/provider-gateway/package.json` 的版本号，并在升级后通过 frontend 或 `debug health` 确认目标节点上报新版本；权威规则见 `docs/reference/provider-gateway.md`。
- `provider.upgrade` 预检、执行升级和远程更新记录必须显式显示指定 Provider 的 gateway 版本号，不能只把版本放进原始 JSON；前端和 E2E 要求见 `docs/reference/provider-gateway.md` 与 `TEST.md`。
- 计算节点 `provider-gateway` 容器的重建/升级必须走带 sleep-and-validate 回滚保护的 `provider.upgrade mode=schedule` 远程升级路径或前端等价调度；禁止通过 `bun scripts/cli.ts ssh <providerId>` 同步执行 `docker compose up --build provider-gateway` 这类自重建命令，权威规则见 `docs/reference/provider-gateway.md`。
- Host SSH / WSL SSH 透传只能用于节点诊断、前置条件修复和升级后验证，不能作为计算节点 `provider-gateway` 自身的重建/升级通道；部署验收必须同时证明远程升级和 SSH 透传可用，测试门禁见 `TEST.md`。

## Critical Native k3s Runtime Rule

- 所有计算资源节点上的 k3s server、控制平面、agent 和 worker 必须原生安装在 host OS 或 WSL 发行版内，禁止用 Docker/Compose/`rancher/k3s` 长驻容器承载 k3s；权威规则见 `docs/reference/arch.md`、`docs/reference/microservices.md` 与 `docs/reference/deploy.md`。
- `k3sctl-adapter` 是 UniDesk 到 k3s 的控制桥，必须作为 UniDesk 直管服务运行在 k3s 故障域外，不得改成 k3s 代管服务；权威规则见 `docs/reference/arch.md` 与 `docs/reference/microservices.md`。

## CLI

- `bun scripts/cli.ts help`：输出所有可用命令的 JSON 索引，详细规范见 `docs/reference/cli.md`。
- `bun scripts/cli.ts --main-server-ip <ip> <command>`：默认通过公网 frontend 登录态远程执行调试、用户服务（底层命令名 `microservice`）、Code Queue 查询与节点自测命令，不要求主 server SSH key，详细规范见 `docs/reference/cli.md`。
- `bun scripts/cli.ts config show`：校验并展示根目录 `config.json`，配置来源规则见 `docs/reference/config.md`。
- `bun scripts/cli.ts check [--full|--files|--scripts-typecheck|--components|--compose|--logs|--recovery-guardrails|--rust]` / `bun scripts/cli.ts check recovery-guardrails`：默认只运行轻量配置和 TypeScript 语法检查；`check recovery-guardrails` 只读低噪声报告 D601 reboot 后 k3s/Code Queue hostPath、`/proc/mounts`、CRI sandbox 和 ContainerCreating 风险；Rust backend-core 检查只能在 D601 CI/dev execution 中用 `UNIDESK_D601_RUST_CHECK=1` 开启，规则见 `docs/reference/dev-environment.md` 和 `docs/reference/devops-hygiene.md`。
- `bun scripts/cli.ts server start`：以异步 job 启动 database、backend-core、frontend、provider-gateway、code-queue-mgr 和主 server 用户服务，部署规则见 `docs/reference/deployment.md`。
- `bun scripts/cli.ts server status`：查询固定端口、swap 摘要、容器状态、健康检查和访问 URL，包含生产 frontend、dev frontend proxy 和 provider ingress，判定标准见 `docs/reference/deployment.md` 与 `docs/reference/dev-environment.md`。
- `bun scripts/cli.ts server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run]`：以 JSON 查看或幂等创建主 server swapfile，`ensure` 输出 before/after、动作、持久化状态和 degraded/failed 详情，规则见 `docs/reference/deployment.md`。
- `bun scripts/cli.ts server logs [--tail-bytes N]`：分页返回文件日志与 Docker 日志尾部并带截断元数据，日志规则见 `docs/reference/observability.md`。
- `bun scripts/cli.ts server cleanup plan [--min-age-hours N] [--limit N]`：只读/干跑生成主 server Docker 镜像清理计划，默认只列出至少 24 小时前创建的非保护镜像，输出 active/protected images、stale candidates、预计释放空间、风险等级和必须人工确认的 `docker image rm` 命令；禁止默认删除、禁止 prune、禁止触碰 database volume、registry storage 或 Baidu Netdisk 状态。
- `bun scripts/cli.ts server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>`：以 build-first、Compose lock、no-deps force-recreate 和 post-up validation 的异步 job 重建主 server Compose 内单个服务；对 database、File Browser、Code Queue 执行面、k3sctl-adapter 或未知对象返回结构化 `unsupported-server-rebuild`，规则见 `docs/reference/deployment.md` 与 `docs/reference/cicd-standardization.md`。
- `bun scripts/cli.ts provider attach <providerId> [--master-server URL] [--up] [--force]` / `bun scripts/cli.ts provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]`：前者在新增计算节点上生成两项配置的 provider-gateway 挂载包；后者是只读多信号健康裁决入口，默认低噪声输出 `decision`、`healthyScopes`、`failedScopes`、`retryable` 和异常信号摘要，用来把单路径 `provider is not online`、SSH 超时、registry 失败或 proxy 失败归类为 `retryable-transient`、`service-degraded` 或 `global-offline`，完整 evidence 需显式 `--full|--raw`，规则见 `docs/reference/provider-gateway.md` 和 `docs/reference/code-queue-supervision.md`。
- `bun scripts/cli.ts ssh <route> [operation args...]` / `tran <route> [operation args...]`：通过 provider-gateway 的 Host SSH / WSL SSH 维护桥进入 provider、host workspace、Windows cmd route、k3s 控制面或 pod workspace；主 server 人工/Codex 分布式操作必须用本机 `tran` wrapper，CLI 参考和可移植脚本可保留完整命令，细则见 `docs/reference/cli.md`、`docs/reference/windows-passthrough.md` 和 `docs/reference/provider-gateway.md`。
- `bun scripts/cli.ts microservice list/status/health/diagnostics/tunnel-self-test/proxy`：管理和验证挂载在主 server、计算节点 Docker 或 k3s 控制面上的用户服务，`status/health/diagnostics` 默认 compact summary 并用 `--full|--raw` 展开完整 body，`proxy` 支持受控 JSON body，OA Event Flow/Todo Note/Baidu Netdisk/Code Queue Manager on main-server、k3s Control/Code Queue 执行面/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 的规则见 `docs/reference/microservices.md`。
- `bun scripts/cli.ts microservice health/diagnostics/proxy code-agent-sandbox`：验证独立 Code Agent Sandbox 的 health、只读 diagnostics、trace 和 adapter/mode/credential boundary 契约，规则见 `docs/reference/code-agent-sandbox.md`。
- `bun scripts/cli.ts decision upload/list/show/health`：通过 backend-core 用户服务代理上传会议记录/需求/决议 Markdown、列出记录和查看详情；Decision Center 运行在 D601 k3s，规则见 `docs/reference/microservices.md`。
- `bun scripts/cli.ts decision requirement list/create/show/update/upsert`：管理 Decision Center 产品化需求记录，类型覆盖外部目标、内部目标、决议、阻塞、债务和实验，规则见 `docs/reference/microservices.md`。
- `bun scripts/cli.ts decision diary import/list/history/months/today/show/edit/upsert`：把带日期标题的工作日志 Markdown 拆成 `YYYY-MM/YYYY-MM-DD.md` 日记条目并写入 PostgreSQL，支持按真实日期自动创建当天日记和编辑历史日记，规则见 `docs/reference/microservices.md`。
- `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service <id>]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.<env>` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout、reviewed registry artifact consumers 和 D601 direct consumer validation，`findjob`/`pipeline` 是 D601 direct pull-only 样板，`met-nonlinear` dry-run blocked，`k3sctl-adapter` supervisor-only，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。
- `bun scripts/cli.ts dev-env validate [--manifest path] [--kubectl-dry-run]` / `dev-env prewarm-images`：离线校验 D601 `unidesk-dev` 生产隔离护栏和 dev workload manifests，或把开发底座基础镜像预热到 D601 原生 k3s containerd，规则见 `docs/reference/deploy.md` 与 `docs/reference/microservices.md`。
- `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`findjob`/`pipeline` 支持 D601 direct dev/prod，`met-nonlinear` 和 `k3sctl-adapter` 只给受限计划路径，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。
- `bun scripts/cli.ts auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`：查看 Auth Broker P0 Rust skeleton 与 CLI adapter contract，runner 无 `GH_TOKEN`/`GITHUB_TOKEN` 时返回结构化 `auth-missing`/`broker-needed`，不读取或打印 token 值，规则见 `docs/reference/auth-broker.md`。
- `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment` / `bun scripts/code-queue-pr-preflight-example.ts`：通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察（含 merged/closed 区分与 merge commit）、低噪声 PR 收口 preflight 与 runner PR preflight；`gh issue/pr read|view` 支持 `owner/repo#number` shorthand，`--raw|--full` 是显式完整披露别名，`gh pr diff` 仅支持 `--stat` 紧凑 JSON，`gh pr merge` 当前仍结构化拒绝但普通 PR 可按任务边界用 repo-owned GitHub 路径收口，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。
- `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr`：查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合、ClaudeQQ 高风险请示草案和 GPT-5.5 PR prompt 边界辅助 lint；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，`prompt-lint` 不作为业务 PR 门禁也不改变 `codex submit` 默认行为，规则见 `docs/reference/host-codex-commander.md`。
- `bun scripts/cli.ts hwlab cd audit --env dev` / `status|preflight|apply --dry-run`：旧 D601 HWLAB DEV CD 指挥侧 wrapper，仅用于显式 legacy 诊断和迁移对照；当前 HWLAB DEV/PROD source/runtime truth 已迁到 G14 `/root/hwlab` 与 G14 k3s/GitOps，规则见 `docs/reference/hwlab.md`。
- `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。
- `bun scripts/cli.ts codex deploy <commitId>`：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。
- `bun scripts/cli.ts codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` / `codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue <id>]` / `codex execution-plane [--full|--raw]` / `codex pr-preflight [--remote]`：`prompt-lint` 在派发/steer 前 dry-run 检查 runner prompt 的 DEV 测试授权分级（`read-only`/`live-read`/`live-mutating`）且不回显 prompt；`submit --dry-run` 同时给出 MiniMax/GPT/人工路由建议、该 lint 结果和 requested/effective execution mode；真实提交成功只返回写入确认、task id、服务级 runnerPermissions 和后续查看命令，不回显 prompt；`execution-plane` 只读比较 D601 原生 k3s 正式 Code Queue 执行面、旧 Compose 残留、commit/digest/worktree/probe drift；`pr-preflight` 只读检查 D601 scheduler/runner 的 GitHub token、egress 和 PR 能力，PR 型派单前必须使用，规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。
- `bun scripts/cli.ts codex task <taskId>`：按 Code Queue 任务 ID 查询默认审阅摘要，只返回原始 prompt、最终 response、最后错误和渐进披露命令；`codex tasks --view commander` 是 host commander 推荐轮询入口，默认有界显示 active runner 精确计数、queued/retry_wait、terminal-unread、active 风险、分类和 drill-down 命令；`--view supervisor|full`、`codex output` 和大 `--limit` 仍默认有界，完整内容需显式 `--full`/`--full-text`/分页展开；`codex queues [--full] [--limit N] [--page N|--offset N]` 默认分页低噪声输出队列摘要，完整 upstream 只通过 raw command 显式获取。
- `bun scripts/cli.ts codex unread [--repo owner/name] [--issue N] [--limit N]`：只读汇总完成未读积压并给出 repo/issue/status/queue 计数和 drill-down/read 命令；批量已读必须显式 `codex unread mark-read ... --confirm`，规则见 `docs/reference/cli.md`。
- `bun scripts/cli.ts codex judge <taskId> --attempt <n> [--dry-run]`：按指定 task/attempt 用与队列 worker 相同的上下文构建和 MiniMax judge 调用路径单步复现完成判定；`--dry-run` 只输出 prompt/payload 诊断。
- `bun scripts/cli.ts codex steer <taskId> [prompt|--prompt-file path|--prompt-stdin] [--steer-id id] [--dry-run] [--no-retry|--retry-attempts N]` / `codex steer-confirm <taskId> --steer-id <id>`：向运行中的 active turn 注入纠偏提示并用 `steerId` 做幂等/trace 确认；真实输出不回显 prompt，遇到 `deliveryUnconfirmed` 先查确认命令，不重复发送同一纠偏。
- `bun scripts/cli.ts codex interrupt|cancel <taskId>`：通过 Code Queue 私有代理中断运行任务或取消 queued/retry_wait 任务，规则见 `docs/reference/cli.md`。
- `bun scripts/playwright-cli.ts screenshot|open|eval ...`：UniDesk 仓库自带的 Playwright 指挥手测 wrapper，默认 headless，可用 `--session <id>` 复用 storageState，适合截图、打开页面和一次性 JS 取值；它不实现长驻浏览器 daemon、element ref `click/fill/snapshot` 会返回结构化 unsupported 和 `xvfb-run`/headless 下一步，规则见 `docs/reference/cli.md`。
- `bun scripts/cli.ts server stop`：以异步 job 停止固定 Compose 项目中的全部 UniDesk 服务，停止后用 `server status` 复核。
- `bun scripts/cli.ts job list [--limit N]` / `bun scripts/cli.ts job status latest [--tail-bytes N]`：分页查询 `.state/jobs/` 中的异步任务状态，状态输出只读日志尾部并保留完整日志路径，job 机制见 `docs/reference/cli.md`。
- `bun scripts/cli.ts debug health` / `bun scripts/cli.ts debug dispatch` / `bun scripts/cli.ts debug task`：通过 Docker 内网 core、真实 HTTP、WebSocket、系统指标、Docker 状态和 Host SSH 维护桥流程调试健康检查、任务下发与任务结果，调试规则见 `docs/reference/cli.md`。
- `bun scripts/cli.ts e2e run [--only pattern[,pattern...]] [--skip pattern[,pattern...]]`：支持按 check/prefix/wildcard 选择性执行公网 production frontend/dev frontend/provider ingress、内网 core/database、provider-gateway 自接入与 Playwright 验证；日常迭代先跑当前问题对应的最小检查集，最终交付再跑全量回归，验收规则见 `docs/reference/e2e.md`。

## Runtime

- `bun`：TypeScript 运行时固定使用 Bun，组件入口和 CLI 都直接运行 `.ts` 文件，约束见 `docs/reference/config.md`。
- `docker-compose.yml`：主 server 统一编排 core、frontend、dev-frontend-proxy、database、本机 provider gateway、Todo Note 后端、Baidu Netdisk 后端、OA Event Flow 后端和轻量 Code Queue Manager 控制面；Code Queue 执行面、MDTODO、ClaudeQQ 和 Decision Center 由 D601 k3s/k8s 控制面代管，并经 `k3sctl-adapter` 的 Kubernetes API service proxy 单一路径接入，服务拓扑见 `docs/reference/deployment.md` 与 `docs/reference/dev-environment.md`。
- `src/components/frontend`：前端源码固定使用 TypeScript + React，`app.tsx` 只做 shell/router，左侧主模块与顶部子标签统一编译为模块前缀路由：`/ops/<tab>/`、`/nodes/<tab>/`、`/tasks/<tab>/`、`/config/<tab>/`，只有用户服务使用 `/app/<tab>/` 深链接，运行总览包含通用性能面板，资源监控含曲线和进程资源排序表，Todo Note、FindJob、Pipeline、MET Nonlinear、Baidu Netdisk、Code Queue、MDTODO、Decision Center、OA Event Flow、k3s Control 等业务页必须拆到独立 TSX 模块，界面规则见 `docs/reference/frontend.md`。
- `backend-core / frontend performance`：backend-core 暴露 `/api/performance`，frontend 暴露同源 `/api/frontend-performance` 并在 `/ops/performance/` 汇总组件请求、失败请求、内部操作和慢操作，规则见 `docs/reference/observability.md`；backend-core 当前为 Rust 服务，结构见 `docs/reference/repo-tree.md`，Rust 编译边界见 `docs/reference/dev-environment.md`。
- `Unified OA event flow`：`oa-event-flow` 是独立主 server 用户服务，提供事件表、按 tag 订阅和 Trace/STEP 统计中心，Code Queue 与 Pipeline 都必须接入统一事件流；共享契约见 `docs/reference/oa-event-flow.md`，Pipeline 专有控制流规则见 `docs/reference/pipeline-oa-event-flow.md`。
- `src/components/provider-gateway`：当前主 server `74.48.78.17` 也作为 provider gateway 接入 UniDesk，外部节点通过 `ws://74.48.78.17:18082/ws/provider` 接入，必须以 `restart: always` 部署 always-enabled 远程升级、sleep-and-validate 回滚保护和 Host SSH / WSL SSH 透传并完成自测，部署与 Playwright 公网前端验证方法见 `docs/reference/provider-gateway.md`。
- `microservices`：用户服务配置命名仍保留 `microservices`；用户服务指挂载在 UniDesk 核心服务上的用户业务能力，支持 `unidesk-direct`、`internal-sidecar` 与 `k3sctl-managed` 部署模式；`code-queue-mgr` 是主 server 内部 sidecar 控制面，D601 Code Queue 是执行面；k3s 代管必须使用标准 k3s/k8s 对象和 Kubernetes API service proxy，禁止业务容器直连、NodePort 和隐藏 fallback；缺少这些服务时核心仍可运行。主 server 本地开发边界固定为只开发 UniDesk frontend 和已登记的内部 sidecar 控制面；非 UniDesk 核心业务后端、Dockerfile、GPU/训练调试必须在目标计算节点通过 SSH 透传或 k3s 控制面完成，Todo Note 这类明确写入主 server 的例外需单独登记，规则见 `docs/reference/microservices.md`。
- `docs/reference/e2e.md`：交付前必须执行的自测门禁、Playwright 登录、资源监控进程排序、JSON 展示断言和数据库命名卷持久化要求。

## Architecture Docs

- `docs/reference/arch.md`：UniDesk 分布式工作平台的长期架构约束。
- `docs/reference/repo-tree.md`：仓库结构目标与组件边界。
- `docs/reference/strategy-governance.md`：UniDesk 外部收益约束、短长期收益划分和需求审视准则；战略分析记录见 GitHub issue #7。
- `docs/reference/staff-reference.md`：幕僚长期参考、决策过程和用户偏好摘要；与 `strategy-governance`、`code-queue-supervision` 配套。
- `docs/reference/secretary-reference.md`：秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。
- `docs/reference/code-queue-supervision.md`：Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。
- `docs/reference/hwlab.md`：HWLAB 指挥侧固定 workspace、G14 主运行面、D601 legacy/硬件桥接边界、最小 device-agent/gateway 桥接模型和受控发布边界。
- `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、当前 HWLAB DEV/PROD source/runtime truth、device-agent 手动实验边界、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。
- `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。
- `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。
- `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。
- `docs/reference/constar-d601.md`：D601 上 ConStart/constar 固件工作区的 UniDesk SSH 入口、WSL skill wrapper、Keil 编译下载和串口/JSON-RPC 验证简要引导。
- `docs/reference/oa-event-flow.md`：统一 OA 事件流微服务、事件表、tag 订阅、Trace/STEP 统计中心和前端可见性规则。
- `docs/reference/pipeline-oa-event-flow.md`：Pipeline/OA 事件流、审核/无审核流转、单步调试、甘特图渲染和最终去残留规则。
- `docs/reference/pipeline-model-proxy.md`：Pipeline v2 model proxy 链路架构、D601 宿主 proxy 服务部署、harness token 注入规则和 smoke test 验证流程。
- `docs/reference/deploy.md`：`deploy.json` desired-state、target-side build、一次性构建 proxy、直管/代管服务部署 executor 和 live commit 验证规则。
- `docs/reference/devops-hygiene.md`：Git-backed deployment truth、dirty worktree/manual repair 边界、受限手动操作和 CI 私有仓库 source-auth 规则。
- `docs/reference/cicd-standardization.md`：`CI.json` catalog、CI producer summary、blocked/upstream-image 服务、File Browser 上游镜像例外、legacy CI/CD 路径分类和 CD consumer 分工。
- `docs/reference/auth-broker.md`：Auth Broker P0 的 Rust skeleton、GitHub REST operation allowlist、CLI dry-run adapter、审计字段、失败语义和人工确认点。
- `docs/reference/release-governance.md`：`release/v1` 稳定维护线、`master` 集成线、CI/CD server 版本固定、master CLI 兼容和 feature flag 治理规则；决策记录见 GitHub issue #6。
- `docs/reference/artifact-registry.md`：D601 host-managed CNCF Distribution registry、loopback-only 边界和 backend-core artifact CD 目标流程。
- `docs/reference/host-codex-commander.md`：host Codex 指挥官 skeleton 的 source/contract、CLI dry-run、状态模型、SSH/PTY/stdio bridge 预留边界、#20/#46 入口和 ClaudeQQ 高风险审批边界。
- `docs/reference/user-service-delivery.md`：用户服务默认交付流程、CI 镜像构建与 registry、Baidu Netdisk 主 server 直管微服务样板、dev 自动测试、prod 拉镜像部署和 Decision Center 产品化需求管理规则。
- `docs/reference/dev-environment.md`：D601 `unidesk-dev` persistent dev 环境、18083 dev frontend proxy、`deploy apply --env dev` 服务范围和 Rust backend-core 只在 D601 编译的边界。
- `docs/reference/ci.md`：D601 k3s Tekton CI、只读主数据库性能门禁和 CLI 入口规则。
- `docs/reference/code-queue-supervision.md`：Code Queue 长任务波次的并发窗口、轮询、终态读取、阻塞拆分和 supervisor 边界。
- `docs/reference/dev-ci-runner.md`：`ci run-dev-e2e` 的 Git 控制 runner、短 launcher、结果目录和 no-CD 边界。
- `docs/reference/codex-deploy.md`：D601 Code Queue 旧 `codex deploy <commitId>` 入口禁用原因、受控部署边界和后续 CD 目标行为。
- `reference`：兼容旧路径的符号链接，指向 `docs/reference/`。