pikasTech-unidesk/AGENTS.md

UniDesk Agent Index

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

P0 最高优先级：自有配置 YAML 优先规则

• P0: UniDesk 自有配置一律优先使用 YAML（.yaml/.yml），包括 config/ 下的运行面、平台基础设施、节点/lane、部署参数和可调版本配置；除非外部工具硬性要求 JSON/TOML/ENV 等格式，禁止新增 JSON 作为 UniDesk 自有配置真相。
• P0: 需要代码读取的 YAML 配置必须显式校验 schema、字段类型和必填项；禁止静默 fallback、宽松猜测或把配置藏进脚本常量，后续版本、镜像、namespace、endpoint 等可调项必须从 YAML 配置进入受控 CLI。

P0 最高优先级：G14 platform-infra 规则

• P0: platform-infra 是 G14 k3s 上 UniDesk 运维的平台基础设施 namespace；Sub2API、Codex pool、FRP 暴露、统一消费 API key 和后续平台基础设施迁移的长期边界、路由与探针口径统一见 docs/reference/platform-infra.md，Sub2API 日常操作统一见 $unidesk-sub2api（.agents/skills/unidesk-sub2api/SKILL.md）。
• P0: devops-infra 仅作为既有控制面基础设施逐步迁移来源，不再作为新增平台服务的默认 namespace；新增/迁移必须优先落到 platform-infra，并通过 config/platform-infra/*.yaml 与 bun scripts/cli.ts platform-infra ... 受控。

P0 最高优先级：CaseRun 无服务与单步调试规则

• P0: CaseRun、case registry 产物整理、trace 语义化、harness 诊断、短连接 CLI 和本地/目标 host 上可直接运行的 runner 调试，默认是无服务工作流；只要不需要变更 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务，就必须直接无服务运行和验证，禁止为了运行 CaseRun 触发 CI/CD、rollout 或服务发布。
• P0: CaseRun 卡在基础设施、hwpod-node、workspace prepare、编译、下载、串口或 artifact 收集的某个步骤时，必须先把卡点拆成单步命令在同一目标运行面验证；禁止用反复全量 CaseRun 大回环替代单步定位。
• P0: 只有单步卡点已经验证通过，且需要验证完整编排、trace 和 registry 产物时，才启动一次完整 CaseRun；完整 CaseRun 仍必须按 cli-spec 异步启动、短轮询状态、收集 trace，不得把 evidence 自动评价、门禁或自动判断重新塞回流程。

P0 最高优先级：文档/CLI 直接主 worktree 规则

• P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前项目固定主 worktree 直接修改、提交并 push 到对应 remote 分支。
• P0: 只有业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 或明确高风险改动，才按项目规则创建隔离 worktree 或走 PR；不要把重型开发流程套到文档/CLI 轻量变更上。
• P0: 若固定主 worktree 因并行 dirty 文件无法快进，先保留并行变更，只提交当前文档/CLI相关文件；必要时使用非破坏性 rebase/autostash 或等价方式对齐 remote 后直接 push，禁止绕到新 worktree 掩盖主 worktree 状态。

P0 最高优先级：可见性先修

• P0: 可见性问题是所有任务的优先级最高基础设施问题；无论当前正在开发、发布、排障、写文档、跑 CI/CD 还是做远端透传，只要遇到会遮蔽状态、耗时、失败原因、任务进度、日志尾部、trace、命令结果或关键证据的可见性缺口，必须先修复可见性再继续原任务，避免后续反复踩坑和浪费时间。
• P0: 可见性修复优先采用低摩擦、短反馈、可复用的 CLI/日志/状态输出改进；不得把不可见问题包装成临时人工记忆、长日志全量 dump、重复大回环 CI/CD 试错或额外旧门禁。
• P0: 可见性、trace、诊断文案和降级原因只能作为定位与验收证据，不能替代缺失能力实现或未修复功能；发现能力缺失就补能力，发现功能未修复就修功能本身，细则见 docs/reference/observability.md。
• P0: check、smoke、layout、trace 或 CI/CD 观测命令因仓库声明依赖缺失而跳过、降级或不可见时，直接按该 repo 的锁文件和包管理器安装依赖后继续验证；禁止把缺依赖的 skip 当作有效结果，也不要绕到人工猜测、旧门禁豁免或重复大回环试错。

P0 最高优先级：最新要求与旧门禁清除

• P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言、旧 guard 和旧 gate；开发过程中遇到任何阻碍最新目标的旧测试、旧门禁、旧预检或旧断言，一律拆除，禁止继续维护、修补、叠例外或用兼容路径绕行。
• P0: 短连接 CLI、临时工具、文档和轻量 helper 不套用常驻服务、镜像、Job、GitOps、PR、CI/CD 或重型发布流程的旧门禁；如果旧流程要求与最新架构定位冲突，以最新架构定位为准并删除旧流程入口。
• P0: 任何测试、预检或自检只允许表达当前最新目标行为；旧历史断言不得作为回归保护保留，避免把旧路线固化成长期摩擦。

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 Secretary Long-Term Reference Rule

• P0: 任何秘书日程、时间盒、Todo Note / Decision Center 分流、滚排、复盘、外部催办登记、委托跟踪、回读与回写动作之前，必须先加载并以 docs/reference/secretary-reference.md 为唯一长期参考；AGENTS.md 索引条目只作入口，不替代该参考的完整约束。
• P0: 秘书工作面的最小核查（北京时、Todo Note、Decision Center 日记、schedule list）、反馈格式（"完成/未完成 + 卡点" 或 "路径 + 当前状态 + 下一步阻塞"）和"维护 Todo Note、只读 Decision Center diary"边界必须按 secretary-reference.md 执行；任何与之冲突的临时记忆、旧版规则或对话印象一律以该参考为准。
• P0: 禁止在未读完 secretary-reference.md 的情况下拍时间块、滚动调整、跨日复盘或代替用户写 Decision Center diary；时间分配由秘书主导，不向用户要选项，例外只有用户原话冲突、硬约束缺失或涉及外部承诺与身份判断。

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: 对 k3s pod 内文本热修必须把第一个 route token 直接定位到目标 pod/workspace 后再执行 apply-patch；禁止从 host/worktree 取 diff、改路径、再管道拼到 pod，反面案例和正确写法见 docs/reference/cli.md。
• 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: 分布式敏捷开发通用流程以 $dad-dev skill 为唯一权威：P1 目标运行面探测、P2 运行面最小热补丁闭环、P3 持久化 Git/项目交付路径、P4 原入口复测；UniDesk 项目特有入口和判定边界见 docs/reference/devops-hygiene.md。
• P0: 对第三方模型、API provider、硬件、跨平台 bridge、CLI/trans/tran 或高频工具链异常，禁止在未核对当前 runtime config/Secret/env/proxy 并完成目标运行面实地探测前定性为外部不可用。
• P0: 运行面热补只能作为实验和恢复证据，不能替代正式 PR/CI/CD；若热补被正常 GitOps、rollout、CI/CD 或镜像重建覆盖，保留最小闭环证据后直接转入 $dad-dev 的 P3/P4。

Critical HWLAB Issue Closure CLI Validation Rule

• P0: HWLAB/G14/v0.2 的用户反馈、CLI、Cloud Web、AgentRun、device-pod、公开 API 或运行面工作流 issue，关闭前必须完成用户入口或原入口的真实验证；仅有 targeted test、unit/contract test、构建检查、PR 合并或源码层证据不得关闭 issue。
• P0: CLI 相关 issue 未完成目标 runtime 上的真实 CLI 验证时必须保持打开或重新打开；关闭评论必须写明实际 CLI/入口命令、目标 lane/URL/namespace、trace/session/thread/PipelineRun 等证据和结果，细则见 docs/reference/g14.md。

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: CI/CD、GitOps、rollout、artifact 发布、PR 合并后 DEV/PROD 滚动、PipelineRun 重跑/清理、Argo refresh 和运行面 retention 这类控制动作必须走 UniDesk CLI 的受控子命令；禁止把原生 kubectl、argo、tkn、gh、curl 或临时 shell 当作正式控制入口。
• P0: trans <route> kubectl|logs|get|describe / tran <route> ... 只作为 CLI 介导的短查询诊断和证据采集底座；一旦某个 CI/CD 写操作需要重复使用，必须先补齐 bun scripts/cli.ts ... 高层子命令并把用法写入 docs/reference/cli.md，不能长期靠低层 route 手工 patch/annotate/delete。
• P0: 若现有 CLI 字段、状态、权限或动作不够，默认先改进 UniDesk CLI 后继续发布；不得绕过为原生命令直连 GitHub、Kubernetes、Tekton、Argo 或 registry。长期细则见 docs/reference/cli.md。

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 HWLAB_API_KEY Discovery Rule

• P0: HWLAB_API_KEY 已在 master server 和 G14 固化，统一来源路径都是 /root/.config/hwlab-v02/master-server-admin-api-key.env；处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 v0.2 验收前，必须先从当前执行 host 的该文件加载或确认 key，禁止先把问题定性为缺少 API key。
• P0: master server 和 G14 的 ~/.bashrc 会加载该固定文件，并通过 BASH_ENV=$HOME/.bashenv 让从交互 shell 派生的非交互 bash 也能读取 HWLAB_API_KEY；若当前进程没有继承环境，先显式 source ~/.bashrc 或确认该固定文件，不得改走别名、token、cookie 或临时 fallback。
• P0: 查询 key 时只能输出 HWLAB_API_KEY=present/missing、source path 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。G14/HWLAB runtime 中环境变量缺失不代表 key 不存在，应先通过同一固定来源注入再继续排查。
• P0: HWLAB v0.2 Code Agent provider profile 的 config.toml 与完整 Codex auth.json 提交、Secret 证据和真实试机验收规则统一见 docs/reference/hwlab.md#code-agent-provider-profile-配置与验收；AGENTS.md 只保留索引，不重复凭证语义。

Critical AgentRun Worktree Rule

• P0: pikasTech/agentrun 是新的共享 Agent 执行基础设施仓库，不是现有 Code Queue 的就地替换；v0.1 source truth 是 G14 节点固定 source worktree G14:/root/agentrun-v01，固定使用 v0.1 分支和 origin git@github.com:pikasTech/agentrun.git。
• P0: AgentRun v0.1 开发必须先预检 G14:/root/agentrun-v01 的路径、分支、remote 和 clean 状态，再在 /root/agentrun-v01/.worktree/{pr_branch} 创建独立 worktree 修改；不要把固定 source worktree、UniDesk、HWLAB、D601 或临时 clone 当作 AgentRun scratch 区。
• P0: AgentRun 废弃旧 dev/prod 运行口径；v0.1 固定部署目标是 G14:k3s 上的 agentrun-v01 namespace，后续按 v0.1、v0.2、v0.3 lane 滚动。
• P0: HWLAB 到 AgentRun 的 gitbundle 资源装配必须以 repo URL + workspace ref 为 checkout authority，HWLAB 默认通过 G14 git mirror 拉取 v0.2；cloud-api、CI/CD 或 rollout 注入的旧 commit 只能作为 requested hint，不得重新成为默认物化来源，细则见 docs/reference/agentrun.md。
• P0: 所有 AgentRun k3s 操作必须使用 route 语法 G14:k3s，UniDesk 侧只维护 AgentRun 的开发和部署运维约束，细则见 docs/reference/agentrun.md。
• P0: AgentRun 的文档、issue、PR、review 和交付说明一律中文；代码标识符、API path、配置键、命令和必要英文专有名词可保留英文，解释性文字必须中文。

Critical G14 HWLAB Workspace Rule

• P0: HWLAB legacy G14 DEV/PROD 运行面已退役；G14/G14-gitops、hwlab-dev/hwlab-prod、17666/17667 和 18666/18667 不再作为当前开发、发布、验收或回归真相。退役状态、计划和执行入口固定为 bun scripts/cli.ts hwlab g14 retirement status|plan|execute --confirm，且该入口只允许触碰 legacy Argo Application 与 legacy namespace，必须保护 hwlab-v02/hwlab-v03。
• P0: HWLAB 当前 G14 运行面默认收敛到 runtime lane：v0.2 固定使用分支 v0.2、开发 workspace G14:/root/hwlab-v02、CI/CD 专用 source repo G14:/root/hwlab-v02-cicd.git、namespace hwlab-v02、19666/19667 FRP 入口；v0.3 使用 hwlab-v03 namespace 和 20666/20667 FRP 入口；v0.3+ 通过 hwlab nodes --node G14 --lane vNN 和 config/hwlab-node-lanes.yaml 管理，长期细则见 docs/reference/g14.md。
• P0: 每次开始 G14 HWLAB runtime lane 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 lane workspace 的 AGENTS.md，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。/root/hwlab 只在显式 legacy/retirement follow-up 时使用。
• 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 trans G14 script 或 workspace route 加 apply-patch，远端文本 patch 默认使用 apply-patch 的 v2 引擎、旧 helper 仅通过 apply-patch-v1 显式调用；k3s 操作用 trans G14:k3s ...；禁止使用 ssh G14 k3s ...，定位必须写在第一个 route token，后续 token 才是 operation。
• P0: 每次开始 G14 HWLAB runtime lane 工作前，目标固定仓库必须先即时快进到目标 remote 分支最新；例如 v0.2 使用 trans G14:/root/hwlab-v02 script -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2 && git status --short --branch && git remote -v'。若有未提交并行变更阻碍快进，必须先判断是否能与最新 remote 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
• G14 HWLAB service/runtime 开发必须先以目标 runtime lane 固定 repo 做预检，再按目标 lane 创建独立 worktree/PR；v0.2 CaseRun、短连接 CLI、trace、docs/reference 和配置治理这类无服务任务按 docs/reference/g14.md 的 direct-lightweight 规则可在 G14:/root/hwlab-v02 直接提交推送，不触发 PR/CI/CD/rollout。
• 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。
• P0: G14 platform PostgreSQL 是 host-native 底层基础设施，HWLAB v0.3+ 通过 namespace-local g14-platform-postgres bridge 使用它；迁移后必须清理旧自有 Postgres StatefulSet/Service/ConfigMap/Secret/PVC，长期规则见 docs/reference/g14-platform-db.md。
• 禁止把 master server、D601、/root/HWLAB、/home/ubuntu/hwlab、/workspace/hwlab、retired /root/hwlab 或临时 clone 当作当前 G14 runtime lane source truth；master server 也不得运行 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证，验证必须走目标 runtime lane workspace、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、runtime lane 和验收默认必须走 G14 runtime lane；只有用户明确指定 D601 legacy 或 D601 Windows 硬件桥接时，才进入 D601 HWLAB 路径。
• D601 仍是 ConStart/71-FREQ 等 Windows 硬件与 Keil/串口资源的 bridge host；最小 device-agent 实验中，D601 Windows hwlab-gateway 可以作为外部 gateway 连接到当前 G14 runtime lane 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 runtime lane 规则冲突时，以 G14 runtime lane 规则为准。
• /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/trans/tran 的工作，都必须优先使用这个目录。
• P0: 每次开始 D601:UniDesk 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 /home/ubuntu/workspace/unidesk-dev/AGENTS.md，并以该文件和其引用的 UniDesk repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
• P0: UniDesk CLI/trans/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/trans/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 -、手写 GitHub API 或无 guard 的整篇替换；需要多行写入时优先使用 UniDesk gh issue update|comment create --body-stdin <<'EOF' 形式，由 CLI 读取 heredoc/stdin、执行 body guard、自动读取当前 issue 元数据并输出 old/new body SHA；--body-file 只作为复用已有文件的兼容入口。
• 长任务和跨回合排障应把专题 issue 评论区作为进展锚点；调查、计划、rollout、阻塞、复测 trace 和最终验收结论都追加到同一个 issue 评论中，细则见 docs/reference/code-queue-supervision.md。

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/trans/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、trans/tran 和分布式 SSH 透传能力跟随 master；release/v1 仅用于明确批准的 backend-core / Code Queue 稳定维护，不作为 frontend 或 CLI/trans/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 整体不可用。
• P0: backend-core 主 server 上线是唯一受控例外：当用户或 issue 明确要求把当前 backend-core 修复上线到 master server 时，可以在 master server 上用 CARGO_BUILD_JOBS=1、--jobs 1 或 CLI 内置等价限流执行 backend-core 专属 Rust 编译或 server rebuild backend-core；该例外不得扩展为仓库级 check、cargo test、Go/前端/其他服务构建或常规迭代路径，完成后必须用异步 job/status/health 证据回写 issue。
• 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 runtime lane workspace、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 观察；除 backend-core 主 server 上线受控例外外，一旦步骤需要构建镜像或编译 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 远程升级路径或前端等价调度；禁止通过 trans <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 Trans Shell Boundary Rule

• P0: trans <route> ... 后面禁止裸放本地 shell 续接控制符，包括 &&、; 和 |；需要在远端执行多步命令时，必须使用 trans <route> script -- '远端完整脚本'、trans <route> script <<'SCRIPT' 或等价的单一 stdin/script 参数，避免后半段被本地 shell 执行。tran 兼容入口遵守同一规则。script -- '<单个字符串>' 会按远端 shell one-liner 执行；script -- <多个 argv> 才是 direct argv。apply-patch、apply-patch-v1、script、py 等 stdin/capture-backed operation 可以使用 heredoc 或 < patch.diff 作为本地输入。
• P0: Windows PowerShell 透传必须使用 trans <provider>:win ps <<'PS' ... PS；script 只表示 host/k3s POSIX shell，cmd 只表示 Windows cmd.exe/batch，禁止把 ps、cmd、shell 混写成多层 quoting。
• P0: 新增或扩展 ssh/trans/tran 高频 operation 不得把完整实现继续堆进 scripts/src/ssh.ts；ssh.ts 只保留 route/parser/broker/dispatch，共享能力拆到 scripts/src/ssh-*.ts 专门模块，细则见 docs/reference/cli.md。

Critical Apply Patch Syntax

• apply_patch 是 Codex 本地文本 patch CLI，通过 stdin 吃 patch 文本；所有高频源码编辑（包括远端 trans <route> apply-patch 也走同一 v2 引擎）都依赖它。完整语法和用法见 unidesk-trans skill。
• P0: apply-patch 一旦出现误删、尾部截断、匹配漂移或其他正确性问题，必须立即优先修复 UniDesk apply-patch 本身；算法必须按 Codex 开源 apply_patch 源码语义做 1:1 对齐。
• P0: Codex 开源 apply_patch 参考源码已固定缓存到 /tmp/codex-apply-patch/codex/codex-rs/apply-patch/，排查或对齐 apply-patch 算法时必须先读该本地缓存。
• 完整 Codex 规范缓存于 /tmp/codex-apply-patch/codex/codex-rs/apply-patch/apply_patch_tool_instructions.md。

CLI

• P0: trans <route> ... 是 bun scripts/cli.ts ssh <route> ... 的短 alias，只用于 SSH/WSL/k3s 透传；人工/Codex 远端操作、长期参考、AGENTS 索引、CLI help、非交互脚本和非交互 exec 都必须直接调主 server PATH 上的 /root/.local/bin/trans wrapper，禁止把 bun scripts/cli.ts ssh ...、bun scripts/cli.ts trans ... 或任何带 bun scripts/cli.ts 前缀的透传写法作为默认入口。普通根 CLI 子命令仍使用 bun scripts/cli.ts <command>，分工见 docs/reference/cli.md。

• P0: trans <route> 的 host workspace 形态必须把已知远端 workspace 写在 route 第一个 token，例如 trans G14:/root/hwlab-v02 ...、trans D601:/home/ubuntu/workspace/unidesk-dev ...；禁止把 cd /root/hwlab-v02 && ... 塞进 script/shell 字符串或 long-form bun scripts/cli.ts ssh 串，长期规则见 docs/reference/cli.md 的 Standard Workspace-Prefixed Passthrough。

• 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 开启，backend-core 主 server 上线受控编译例外不改变 check --rust guard，规则见 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|remote：主 server 或受控 provider 磁盘高水位一次性缓解和低风险防膨胀入口，覆盖日志、journald、Docker BuildKit cache、allowlisted /tmp 诊断目录、受限 core dump、显式 trace 遥测留存和 systemd 定时策略；规则见 docs/reference/gc.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。

• trans <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 分布式操作必须优先用本机 trans wrapper，tran 只作为兼容入口，细则见 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 读写、分页 issue list、inactive issue stale-close、脱敏 auth/status 诊断、heredoc/stdin 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 retirement status|plan|execute --confirm：受控退役 legacy G14 DEV/PROD Argo Application 和 namespace，并写本地退役 marker 记录执行证据；base=G14 monitor 按退役合同固定阻止重启，bun scripts/cli.ts hwlab g14 monitor-prs --lane v02|v03 是当前 runtime lane PR 自动 CI/CD 入口，规则见 docs/reference/g14.md 与 docs/reference/cli.md。

• bun scripts/cli.ts agentrun v01 control-plane status|trigger-current|refresh|cleanup-runs|cleanup-released-pvs [--dry-run|--confirm]：通过 G14 route 只读观察、手动触发、刷新 Argo 或清理 AgentRun v0.1 completed CI workspace retention，规则见 docs/reference/agentrun.md、docs/reference/gc.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 runtime truth 已迁到 G14 runtime lane，规则见 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 通过 trans D601:k3s 只读观察 D601 原生 k3s 正式 Code Queue 执行面、旧 Compose 残留、commit/digest/worktree 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 默认编译边界和主 server 上线受控例外见 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 控制桥、legacy DEV/PROD 退役边界、当前 HWLAB runtime lane、device-agent 手动实验边界、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。
• docs/reference/platform-infra.md：G14 platform-infra namespace、YAML-first shared service 配置、Sub2API/Codex pool、FRP 暴露和 on-demand availability probe 开发边界；Sub2API 日常操作统一见 $unidesk-sub2api（.agents/skills/unidesk-sub2api/SKILL.md）。
• docs/reference/g14-observability-infra.md：G14 原生 k3s 上 Prometheus Operator、devops-infra 监控基础设施、跨 namespace scrape 声明和安全边界。
• docs/reference/gc.md：UniDesk 主 server 和 provider 磁盘 GC、G14/HWLAB registry retention、safe-stop 线和长期防膨胀收益规则。
• 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 编译边界和 master server 上线受控例外。
• 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/。

Critical v0.2 device-pod cloud-api Architecture

• v0.2 device-pod 集成 = cloud-api internal/cloud/access-control.ts + device-pod executor cmd/hwlab-device-pod/main.ts + 主机端 device-host-cli.mjs；意图/子动作/原因矩阵、output.text 三层透传链、cloud-api vs 主机端的运维边界、worktree/closeout 验证顺序都在 docs/reference/g14.md#v0.2-device-pod-cloud-api-architecture 一节，不重复抄写。
• 主机端 F:\Work\ConStart\tools\device-host-cli.mjs 与 v0.2 仓库内的 skills/device-pod-cli/assets/device-host-cli.mjs 是 D601 ops 侧副本关系，v0.2 lane CI/CD 不会自动同步；任何 host-side 行为变更需要 D601 ops 手动覆盖主机副本，详见 docs/reference/g14.md。