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 Decision Consensus Anti-Regression Rule

• P0: 决策共识优先于僵化门禁；这条适用于 CI/CD、部署、工具链、运行面、前后端架构、文档治理和其他开发改进，不只适用于某一条发布链路。
• P0: 防止回归旧路径、防止分叉乱路径是通用治理目标；默认做法是把迁移背景、当前标准路径、废弃路径、判断理由和收敛原则蒸馏到 docs/reference/，形成基于深入理解的决策共识。
• P0: 不得为了防回归而堆砌僵化的自检、预检、guard、gate、审计或证据收集；只有明确高价值风险无法靠长期参考、代码结构和标准入口自然收敛时，才新增最小门禁。

Critical Guard Minimalism Rule

• P0: 架构迁移时，过时的自检、预检、guard、gate 一律优先拆除；禁止在旧门禁上继续修改、叠加例外或引入复杂度和噪声。
• P0: 新增自检、预检、guard、gate 必须遵循最小原则，只覆盖明确且高价值的风险；禁止乱加门禁导致系统僵化、难迁移、难调试，或制造大量误报、摩擦和重复劳动。
• P0: 审计、证据收集和观测采样也必须最小化，只收集能支撑当前判断的必要证据；禁止把大范围、重复、长日志、全量 trace、全量 dump 或无明确判定用途的数据收集做成默认门禁或流程噪声。

Critical Latest-Requirement Test Rule

• P0: 当用户明确给出最新验收要求或纠偏原则时，旧断言、旧门禁和旧兼容路径一律拆除；测试只按最新要求表达目标行为，不保留与最新目标无关或相冲突的历史断言。
• P0: 不做兼容迁移，不做分支/开关，不用 feature flag、legacy mode 或双路径长期并存来绕开最新要求；实现、测试和文档必须直接收敛到最新目标状态。

Critical Remote Patch Transport Rule

• P0: 对 G14/D601/远端 worktree 做文本源码修改时，必须优先使用 UniDesk SSH workspace route 的 apply-patch 透传入口；不要优先用远端 Python/Perl/sed heredoc 或复杂 shell quoting 拼接大段文本补丁。
• P0: 只有在 apply-patch 本身不可用或需要处理非文本/批量机械生成文件时，才使用其他受控方式；使用前必须说明原因，并在修改后立即用 git diff、语法检查或文件尾部检查确认没有截断或污染。
• P0: apply-patch 一旦出现误删、尾部截断、匹配漂移或其他正确性问题，必须立即优先修复 UniDesk apply-patch 本身；算法必须按 Codex 开源 apply_patch 源码语义做 1:1 对齐，不能用局部护栏、兼容绕行、分支开关或改用其他 patch 入口掩盖基础链路缺陷。
• P0: Codex 开源 apply_patch 参考源码已固定缓存到 /tmp/codex-apply-patch/codex/codex-rs/apply-patch/，core 侧相关文件和 commit 记录在 /tmp/codex-apply-patch/；排查或对齐 apply-patch 算法时必须先读该本地缓存，只有缓存缺失或明确需要更新时才重新联网拉取。

Critical Distributed Agile Validation Rule

• P0: 分布式敏捷开发默认先在目标 provider/pod/host 透传环境做最小真实闭环验证，再进入完整 CI/CD、GitOps 或发布流水线；禁止把完整 CI/CD 当作每轮兼容性探索和试错工具。
• 对第三方模型、硬件、跨平台 bridge、CLI/tran 和高频工具链摩擦的修复，必须先用目标运行面上的最小脚本、临时 pod exec、真实端口或受控透传命令证明核心链路跑通；只有闭环通过后，才把修复固化到源码、测试、长期参考和正式发布。
• 外部 API 或模型行为可能变化时，先查官方/一手文档和成熟实践，再在目标运行面做实验验证；不要凭旧记忆反复推 CI/CD 试错。

Critical CI/CD CLI Control Rule

• P0: CI/CD、GitOps、rollout、artifact 发布、PR 合并后 DEV/PROD 滚动、PipelineRun 重跑/清理、Argo refresh 和运行面 retention 这类控制动作必须走 UniDesk CLI 的受控子命令；禁止把原生 kubectl、argo、tkn、gh、curl 或临时 shell 当作正式控制入口。
• P0: ssh/tran <route> kubectl|logs|get|describe 只作为 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。

Critical HyueAPI Direct NO_PROXY Rule

• P0: hyueapi.com / .hyueapi.com 是 Codex API 通道的直连域名，必须始终保留在 NO_PROXY / no_proxy 中；DeepSeek、Codex API 或其他 provider profile 切换、G14 proxy 注入、旧 D601 egress 迁移和 pod/env render 都不得把 hyueapi 流量改成走 HTTP/SOCKS proxy。

Critical AgentRun Workspace Rule

• P0: pikasTech/agentrun 是新的共享 Agent 执行基础设施仓库，不是现有 Code Queue 的就地替换；默认 source truth 是 G14 节点 /root/agentrun，固定使用 master 分支和 origin git@github.com:pikasTech/agentrun.git。
• P0: AgentRun v0.1 固定工作区是 G14:/root/agentrun-v01，固定使用 v0.1 分支和 origin git@github.com:pikasTech/agentrun.git；明确面向 UniDesk/HWLAB 基础 Code Agent 调用服务 v0.1 的任务必须使用该工作区。
• P0: AgentRun 开发必须按目标分支先预检对应固定工作区的路径、分支、remote 和 clean 状态，再在对应 .worktree/{pr_branch} 创建独立 worktree 修改；不要把固定 repo、UniDesk、HWLAB、D601 或临时 clone 当作 AgentRun scratch 区。
• P0: AgentRun 默认部署目标是 G14:k3s 上的 agentrun_dev 与 agentrun_prod namespace；所有 k3s 操作必须使用 route 语法 G14:k3s，UniDesk 侧只维护 AgentRun 的开发和部署运维约束，细则见 docs/reference/agentrun.md。
• P0: AgentRun 的文档、issue、PR、review 和交付说明一律中文；代码标识符、API path、配置键、命令和必要英文专有名词可保留英文，解释性文字必须中文。

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: HWLAB v0.2 是在 G14 上的加法扩容线，不改变、删除或重命名现有 G14/G14-gitops 分支、hwlab-dev/hwlab-prod namespace 或 17666/17667、18666/18667 入口；v0.2 固定使用分支 v0.2、workspace G14:/root/hwlab-v02、namespace hwlab-v02 和 19666/19667 FRP 入口，长期细则见 docs/reference/g14.md。
• P0: 每次开始 G14:HWLAB 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 /root/hwlab/AGENTS.md，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
• 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 bun scripts/cli.ts ssh G14 script 或 workspace route 加 apply-patch，远端文本 patch 默认使用 apply-patch 的 v2 引擎、旧 helper 仅通过 apply-patch-v1 显式调用；k3s 操作用 bun scripts/cli.ts ssh G14:k3s ...；禁止使用 ssh G14 k3s ...，定位必须写在第一个 route token，后续 token 才是 operation。
• P0: 每次开始 G14:HWLAB 工作前，固定仓库 /root/hwlab 必须先即时快进到 origin/G14 最新；先通过 SSH 桥执行 cd /root/hwlab && git fetch origin G14 && git pull --ff-only origin G14 && git status --short --branch && git remote -v。若有未提交并行变更阻碍快进，必须先判断是否能与最新 origin/G14 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
• G14 HWLAB 开发必须先以 /root/hwlab 做固定 repo 预检，再在 /root/hwlab/.worktree/<task> 从最新 origin/G14 创建独立 worktree 修改和提交；不要把固定 repo 当作并行任务 scratch 区，细则见 docs/reference/g14.md。
• P0: G14 已有节点本地 GitHub/Google/DockerHub/npm 等 bootstrap 加速 proxy；在 G14 host、临时 pod、构建 pod 或透传 pod 里拉 GitHub/Google 资源前必须优先使用该 proxy，避免把网络直连失败当作代码阻塞。主入口：HTTP/HTTPS http://127.0.0.1:10808、SOCKS socks5h://127.0.0.1:10808，备份入口和 NO_PROXY 规则见 docs/reference/g14.md。
• 禁止把 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 记忆继续改代码。
• P0: UniDesk CLI/tran/SSH 透传客户端工具链改进可以直接在 master server /root/unidesk 做轻量源码修改、提交和推送；这不允许在 master server 运行仓库级 check、browser smoke、镜像构建或编译，细则见 docs/reference/dev-environment.md。
• /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 开发必须先以 /home/ubuntu/workspace/unidesk-dev 做固定 repo 预检，再在 /home/ubuntu/workspace/unidesk-dev/.worktree/<task> 从最新 origin/master 创建独立 worktree 修改和提交；不要把固定 repo 当作并行任务 scratch 区，细则见 docs/reference/dev-environment.md。
• 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。
• P0: GitHub PR/issue 读写、PR 合并、评论、状态观察和收口动作必须走 UniDesk gh 子命令；禁止绕过为原生 gh、手写 curl/GraphQL/REST 请求或临时脚本直连 GitHub。若 bun scripts/cli.ts gh ... 不顺手、字段不够、merge 不支持或可见性不足，必须先改进 UniDesk gh 子命令并用它完成任务，不能跳过该入口。
• #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。
• P0: 单纯文档或 UniDesk CLI/tran/helper 变更默认直接提交并推送到 origin master，不开 PR、不建临时分支；若涉及外部仓库、发布线、运行面部署或服务高风险行为，按对应 reference 的显式规则执行。
• 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 执行。script -- '<单个字符串>' 会按远端 shell one-liner 执行；script -- <多个 argv> 才是 direct argv。apply-patch、apply-patch-v1、script、py 等 stdin/capture-backed operation 可以使用 heredoc 或 < patch.diff 作为本地输入。
• P0: 新增或扩展 ssh/tran 高频 operation 不得把完整实现继续堆进 scripts/src/ssh.ts；ssh.ts 只保留 route/parser/broker/dispatch，共享能力拆到 scripts/src/ssh-*.ts 专门模块，细则见 docs/reference/cli.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 gc plan|run|db-trace|policy：主 server 磁盘高水位一次性缓解和低风险防膨胀入口，覆盖日志、journald、Docker BuildKit cache、allowlisted /tmp 诊断目录、显式 trace 遥测留存和 systemd 定时策略；gc run 和 gc db-trace run 需要显式确认，规则见 docs/reference/cli.md。
• 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，并提供带 SHA-256 校验的 upload/download 文件传输；主 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|merge / 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、guarded PR merge 与 runner PR preflight；gh issue/pr read|view 支持 owner/repo#number shorthand，--raw|--full 是显式完整披露别名，gh pr diff 仅支持 --stat 紧凑 JSON，gh pr merge 会先执行 closeout 预检并拒绝非 open、draft、冲突、非 CLEAN、失败或 pending checks 的 PR，规则见 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 g14 monitor-prs：一行启动异步监控 HWLAB base=G14 的未合并 PR；可合并时走 UniDesk gh pr merge 合并、监控 G14 Tekton/GitOps/Argo DEV rollout，并向 #7 索引的北京日期每日简报追加 CI/CD 耗时与上线 changelog，规则见 docs/reference/g14.md 与 docs/reference/cli.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 外部收益约束、短长期收益划分、需求压缩和 reference/plan 拆分准则；战略分析记录见 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/。