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，热修复背景见 pikasTech/unidesk#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。
• #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。

Critical Tran Shell Boundary Rule

• P0: tran <route> ... 后面禁止裸放本地 shell 续接控制符，包括 &&、; 和 |；需要在远端执行多步命令时，必须使用 tran <route> script -- '远端完整脚本'、tran <route> script <<'SCRIPT' 或等价的单一 stdin/script 参数，避免后半段被本地 shell 执行或被 CLI 误当成 operation 参数。apply-patch、script、py 等明确 stdin-backed operation 可以使用 heredoc 或 < patch.diff 作为本地输入。

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 通过 tran D601:k3s 只读比较 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/。