pikasTech-unidesk/AGENTS.md

# UniDesk Agent Index

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

## P0 最高优先级：CLI 验证最小化规则

- P0: `scripts/cli.ts`、`scripts/src/**`、`trans`、`tran` 和轻量 helper 的 CLI 改动，除非用户明确要求，否则不做单元测试、合同测试或新增测试脚本；默认最多只做语法检查和必要的帮助/命令形态人工确认。
- P0: 历史合同测试和 prompt lint 属于过度门禁，不再作为 CLI 变更的默认验证、派单前置或关闭依据；发现旧入口阻碍最新目标时直接删除，不做兼容保留。

## P0 最高优先级：CLI 输出渐进披露规则

- P0: CLI 默认输出必须优先采用类似 Kubernetes CLI 的简洁表格、短摘要和可复制的 drill-down 命令；JSON 只作为 `--json`、`--raw`、`--full` 或明确机器消费模式输出，禁止把大段 JSON 当作面向人的默认阅读界面。
- P0: 看到高频 CLI 默认输出仍是 JSON、长对象、长数组或容易超过 YAML 配置阈值的噪声输出时，必须见到一个改一个，优先把该命令改成表格优先、可再展开的渐进式披露形态，而不是反复依赖 dump 后再人工抽取。
- P0: 自动 dump 只作为防止终端爆炸的兜底能力；一旦某个常用命令反复触发 dump，必须把 warning 视为 CLI 可用性缺陷并改进命令自身输出，不能把 dump 文件路径变成长期交互入口。
- P0: 本地或远端 `AGENTS.md`、`CLAUDE.md` 或等价入口文档超过 `10 KiB`、超过 YAML dump 阈值或触发自动 dump 时，必须优先把该入口拆成短索引；超出的细节迁入对应 skill 或 `docs/reference/` 长期参考，并在入口、skill 和长期参考之间建立交叉引用。

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

- P0: UniDesk 自有配置一律优先使用 YAML（`.yaml`/`.yml`），包括 `config/` 下的运行面、平台基础设施、节点/lane、部署参数和可调版本配置；除非外部工具硬性要求 JSON/TOML/ENV 等格式，禁止新增 JSON 作为 UniDesk 自有配置真相。
- P0: 需要代码读取的 YAML 配置必须显式校验格式、字段类型和必填项；配置校验只保证“能被正确读取和渲染”，不得把业务策略、调度策略或数值选择写成代码硬编码、schema 硬范围、合同测试或隐藏默认值。后续版本、镜像、namespace、endpoint、容量、冷却时间、退避窗口等可调项必须从 YAML 配置进入受控 CLI，具体数值以 YAML 为准。
- P0: UniDesk 自有平台服务的密钥、密码、API key、JWT/encryption key 和 `DATABASE_URL` 等凭据绑定，必须采用 YAML 声明 sourceRef/targetKey 并通过受控 CLI 下发；运行面 Kubernetes Secret、pod env、日志或数据库状态只能作为 presence/fingerprint/health 观测对象，禁止作为 source of truth 反推、解码、回填或再生成本地凭据。
- P0: 受控密钥下发 CLI 的输出只能披露对象名、key 名、sourceRef、缺失项、fingerprint、字节数和执行摘要；禁止打印 base64 payload、解码值、完整 DSN、可复制凭据或远端 raw transcript。缺少密钥时修 YAML/sourceRef/上游 Secret 生成入口，再执行受控 sync/apply，不得从运行面倒推补值。
- P0: YAML-first 异构分布式运维架构、现有 YAML 归属优先、禁止硬编码 node/service、公共 ops 层抽取和薄 domain CLI 规则见 `docs/reference/yaml-first-ops.md`。

## 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: Codex pool 账号容量与调度候选必须从 `config/platform-infra/sub2api-codex-pool.yaml` 进入受控 CLI；当前数值以 YAML 为准，禁止用代码常量、Secret、运行时手补或长期参考文档里的硬编码数值覆盖 YAML。
- P0: Codex pool 的业务策略和数值只做 YAML 配置与运行面同步验证；除非用户明确要求实现新能力，修改既有 YAML 数值不得自动扩展为代码 schema、合同测试、单元测试或长期参考文档变更。
- 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 最高优先级：固定主 repo 保护与独立 worktree 规则

- P0: 固定主 repo 通常只作为 source truth 预检、fetch、status 和 worktree anchor；源码、配置、issue closeout、部署脚本、验收产物和高风险 dad-dev / post-task 工作，执行前必须从最新 remote/base 创建独立 `.worktree/<task>` 并在其中完成修改、验证、提交和 push。
- P0: 单纯文档、AGENTS.md、`docs/reference/*.md`、skill 规则、runbook 和其他长期参考收敛不需要新建 `.worktree`；在当前主 worktree 快进到最新 remote 后直接修改、验证、提交和 push，避免给轻量文档治理制造额外 PR/worktree 摩擦。
- P0: 固定主 repo 中已有并行未提交修改时，默认保持不动，不纳入当前任务，也不得 stash、reset、checkout 或删除；源码/配置/部署类当前任务通过独立 `.worktree` 隔离，文档类直接修改只提交当前文档相关文件。
- P0: P1 只读探测、运行面临时热补、文档/skill/长期参考轻量修改，或目标项目长期参考明确声明的直接修改例外，允许不创建新 `.worktree`。长期细则见 `docs/reference/devops-hygiene.md`。

## 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: 任何测试、预检或自检只允许表达当前最新目标行为；旧历史断言不得作为回归保护保留，避免把旧路线固化成长期摩擦。
- P0: 不做合同测试。CLI 改动除非用户明确要求，否则不做单元测试或新增测试脚本；非 CLI 的高频热点或明确曾修复 bug 回归风险才允许补最小单元测试。真实运行面问题通过原入口/端到端 CLI 交互验证，配置数值调整通常只跑对应 plan/sync/validate。

## Critical Long-Term Reference Docs Rule

- P0: 任何新增、修改或蒸馏 `docs/reference/*.md` 长期参考文档的动作，必须遵循 `docs-spec` 规范；禁止绕过 `docs-spec` 凭临时习惯改写长期参考。
- `AGENTS.md` 只做顶级索引和一句话规则摘要；长期稳定、可复用的约束、入口、判定标准必须落到 `docs/reference/`，再由 `AGENTS.md` 提供索引。
- 本地和远端 `AGENTS.md` 治理口径一致：只要文件体积超过 `10 KiB` 或读取时触发 dump，就继续拆分到 skill / `docs/reference/`，并在入口文件和目标文档之间补交叉引用。
- 过程记录、一次性排障、临时结论、带日期的流水账不得直接写成长期参考；需要沉淀时必须按 `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 或双路径长期并存来绕开最新要求；实现、测试和文档必须直接收敛到最新目标状态。
- P0: 合同测试不是允许的测试形态；CLI 验证默认只做语法检查和必要命令形态确认，真实运行面问题走端到端 CLI 交互验证。历史上命名含 `contract` 的命令不得作为默认验证入口，业务策略和配置数值不得通过测试硬编码成额外门禁。

## 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/container，容器内 cwd 用 `--cwd /path` 表达后再执行 `apply-patch`；`:` 是分布式路由符号，`/` 是文件系统 cwd 符号，禁止用 `pod/<pod>/<container>` 选择容器，也禁止从 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 的用户反馈、CLI、Cloud Web、AgentRun、device-pod、公开 API 或运行面工作流 issue，关闭前必须按 issue/CLI 明确的 lane+node 完成用户入口或原入口真实验证；仅有源码检查、构建检查、PR 合并或源码层证据不得关闭 issue。
- P0: CLI 相关 issue 未完成目标 runtime 上的真实 CLI 验证时必须保持打开或重新打开；关闭评论必须写明实际 CLI/入口命令、目标 node/lane/URL/namespace、trace/session/thread/PipelineRun 等证据和结果，细则见 `docs/reference/hwlab.md`。

## Critical CI/CD CLI Control Rule

- P0: 任何 agentrun、HWLAB 或其他 k3s 服务的代码变更需要部署时，必须先解析目标 node/lane 并走 UniDesk 受控 CI/CD CLI；G14 target 按 `unidesk-cicd` skill 的标准流程（git-mirror sync → trigger-current → status 轮询），D601 HWLAB v0.3 target 按 `bun scripts/cli.ts hwlab nodes ... --node D601 --lane v03` 等 node-scoped 入口执行。禁止手动 `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` 来源必须按 issue/CLI 选中的 node/lane 和目标 HWLAB repo 规则解析；v0.2 的既有固定路径是 `/root/.config/hwlab-v02/master-server-admin-api-key.env`，但不得把它当成 v0.3/D601 或其他 lane 的隐藏默认。处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或验收前，必须先从目标 lane 的声明来源加载或确认 key，禁止先把问题定性为缺少 API key。
- P0: 当前执行 host 的 shell 启动文件可能会加载 lane-local API key；若当前进程没有继承环境，先显式读取目标 lane 规则或 source 文件，只能输出 source path、present/missing 或 redacted prefix，不得改走别名、token、cookie 或临时 fallback。
- P0: 查询 key 时只能输出 `HWLAB_API_KEY=present/missing`、source path 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。目标 runtime 中环境变量缺失不代表 key 不存在，应先通过选中 node/lane 的声明来源注入再继续排查。
- 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 + issue/CLI 选中 node/lane 的 workspace ref 为 checkout authority；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 HWLAB Node/Lane 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 目标选择必须以 issue/CLI 明确的 lane+node 为准；没有明确目标时才读取 `config/hwlab-node-lanes.yaml` 默认值。node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口、Secret sourceRef 和执行 route 都以 YAML 为 source of truth，禁止把 G14、D601、v0.2 或 v0.3 写成隐藏默认。
- P0: 每次开始 HWLAB node/lane 分布式开发、切换任务、恢复中断或上下文压缩后，必须先解析目标 node/lane，重新读取目标 workspace 的 `AGENTS.md`，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
- 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 `trans <node>:/<workspace> ...` 或 workspace route 加 `apply-patch`，远端文本 patch 默认使用 `apply-patch` 的 v2 引擎、旧 helper 仅通过 `apply-patch-v1` 显式调用；k3s 操作用 YAML 解析出的 route，例如 `trans D601:k3s ...` 或 `trans G14:k3s ...`；禁止使用 `ssh <node> k3s ...`，定位必须写在第一个 route token，后续 token 才是 operation。
- P0: 每次开始 HWLAB node/lane 工作前，目标固定仓库必须先即时快进到目标 remote 分支最新；例如 D601 v0.3 使用 `trans D601:/home/ubuntu/workspace/hwlab-v03 sh -- 'git fetch origin v0.3 && git pull --ff-only origin v0.3 && git status --short --branch && git remote -v'`。若有未提交并行变更阻碍快进，必须先判断是否能与最新 remote 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
- HWLAB service/runtime 开发必须先以目标 node/lane 固定 repo 做预检，再按目标 lane 创建独立 worktree/PR；CaseRun、短连接 CLI、trace、docs/reference 和配置治理这类无服务任务按目标 repo 规则可直接提交推送，不触发 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、未由 YAML 选中的 workspace、`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab`、retired `/root/hwlab` 或临时 clone 当作当前 HWLAB source truth；master server 也不得运行 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证，验证必须走目标 node/lane workspace、k3s/Tekton 或其他获批外部执行面。
- 长期细节见 `docs/reference/hwlab.md`；G14 节点本地也保留 `/root/docs/hwlab-g14-workspace.md`，该文档只约束 G14 target，不得覆盖 issue/CLI 明确选择的 D601 target。

## Critical D601 HWLAB Node And Legacy Boundary

- P0: D601 node-scoped runtime 不是 legacy；当 issue/CLI 明确写出 `目标节点: D601` 和当前 lane（例如 `HWLAB v0.3`）时，必须按 `config/hwlab-node-lanes.yaml` 的 D601 target 进入对应 workspace、k3s route、namespace 和 public endpoint。
- P0: D601 legacy 只指旧 DEV/迁移/回滚对照路径，例如 `/home/ubuntu/workspace/hwlab-dev`、16666/16667 或历史 `deploy/deploy.json` wrapper；只有 issue/CLI 明确写成 D601 legacy、迁移对照、回滚或旧 DEV 端口排障时才使用。
- D601 仍是 ConStart/71-FREQ 等 Windows 硬件与 Keil/串口资源的 bridge host；硬件桥接身份不覆盖 D601 node-scoped runtime 身份，二者必须按 issue/CLI 目标区分。
- 每次确需进入 D601 legacy HWLAB workspace 前，仍必须通过 UniDesk SSH 桥执行 `trans D601:/home/ubuntu/workspace/hwlab-dev sh -- 'git status --short --branch && git remote -v'`，并重新读取该目录的 `AGENTS.md`。
- `/home/ubuntu/workspace/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、`/home/ubuntu/hwlab` runner 历史目录和 master-server checkout 都不能作为 HWLAB 当前开发真相，除非它们正是 YAML 或明确 legacy issue 指定的目标 workspace。
- 长期细节见 `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](https://github.com/pikasTech/unidesk/issues/138)，热修复背景见 [pikasTech/unidesk#118](https://github.com/pikasTech/unidesk/issues/118)。
- D601 上裸 `kubectl` 不可信：`/home/ubuntu/.kube/config` 可能仍残留 `docker-desktop` / `127.0.0.1:11700`。所有 D601 k3s 读写、Tekton、Code Queue、UniDesk DEV 和显式 D601 legacy HWLAB 排障必须显式使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`，并在写操作前确认节点名是 `d601`。
- 写操作的实际目标 context/server/nodes 出现 `desktop-control-plane`、`docker-desktop` 或 `127.0.0.1:11700`，发现 Docker Desktop Kubernetes namespace、旧 direct Docker `code-queue-backend`，或同一服务被 Docker Desktop k8s 与原生 k3s 同时承载时，必须立即停止部署动作并按 #138 处理；裸 `kubectl` 默认 context 只作为诊断，不能把第二控制面的状态当作恢复证据。

## Critical GitHub Issue Write Rule

- P0: 对 GitHub issue/PR 做正式写入时必须优先使用 `bun scripts/cli.ts gh ...`；禁止用原生 `gh issue edit/create/comment` 直接写 UniDesk/HWLAB 长期看板、指挥简报或用户反馈 issue。事故和 CLI 补强需求见 [pikasTech/unidesk#142](https://github.com/pikasTech/unidesk/issues/142)。
- 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 默认集成线是 `master`，但 agent 开发必须优先在从最新 `origin/master` 创建的独立 `.worktree/<task>` 和任务分支中完成，避免污染固定主 repo；长期规则见 `docs/reference/arch.md`。
- P0: 单纯文档或 UniDesk CLI/trans/tran/helper 变更属于轻量交付，默认仍以 `master` 为合入目标；可按任务风险直接合入/push，也可走短生命周期 PR，禁止在固定主 repo 根目录直接当 scratch 区修改。
- `release/v1` 是规划中的稳定维护线，不是普通 feature/fix 分支；创建、更新或启用必须作为显式 release operation，先满足 `docs/reference/release-governance.md` 和 GitHub issue #6 的 CLI/CI/CD/文档条件。当前常规 agent 任务默认以 `master` 为集成目标，但不再禁止任务分支或 PR。
- `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 正式验证必须改在 issue/CLI 选中的 node/lane workspace、k3s/Tekton 或其他获批外部执行面完成；非 HWLAB 的 D601 服务仍按各自 reference 使用 D601 原生 k3s/CI runner。
- 镜像和编译产物必须通过标准 CI/CD 在外部构建资源上生成；HWLAB 使用 issue/CLI 选中的 node/lane 对应 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 续接控制符，包括 `&&`、`;` 和 `|`；需要在远端执行多步 POSIX shell 命令时，必须显式选择 shell 方言：`trans <route> sh -- '远端完整脚本'`、`trans <route> bash -- '远端完整脚本'`、`trans <route> sh <<'SH'` 或 `trans <route> bash <<'BASH'`。`tran` 兼容入口遵守同一规则。`script` 和 `shell` operation 已移除并会失败，禁止在新文档、技能、脚本或排障命令中继续使用旧名。`apply-patch`、`apply-patch-v1`、`sh`、`bash`、`py` 等 stdin/capture-backed operation 可以使用 heredoc 或 `< patch.diff` 作为本地输入。
- P0: 本地 shell 中检索或引用 Markdown 命令片段时，包含反引号的 pattern 必须用单引号、`rg -F -e` 或 stdin/file 传入；禁止把 `` `trans ...` `` 这类文本放进双引号参数，否则 shell 会先执行命令替换，可能误触已移除的 `trans ... script`。
- P0: Windows PowerShell 透传必须使用 `trans <provider>:win ps <<'PS' ... PS`；host/k3s POSIX shell 必须显式使用 `sh` 或 `bash`，`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 && ...` 塞进 `sh`/`bash` 字符串或 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|--scripts-typecheck-timeout-ms N|--check-heartbeat-ms N|--components|--compose|--logs|--recovery-guardrails|--rust]` / `bun scripts/cli.ts check recovery-guardrails`：默认只运行轻量配置和 TypeScript 语法检查；`--scripts-typecheck` 长命令只跑 scripts TypeScript 类型检查并输出 `unidesk.check.progress` 心跳，除非用户明确要求，不运行单元测试、合同测试或新增测试脚本；`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/cli.md`、`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|run --confirm [--min-age-hours N] [--limit N]`：生成主 server Docker 镜像清理 dry-run 计划，并在显式确认后只删除同一 classifier 选出的 stale images；禁止 prune、禁止触碰 database volume、registry storage 或 Baidu Netdisk 状态，规则见 `docs/reference/cli.md` 和 `docs/reference/deployment.md`。
- `bun scripts/cli.ts gc plan|run|db-trace|policy|remote`：主 server 或受控 provider 磁盘高水位一次性缓解和低风险防膨胀入口，覆盖日志、journald、Docker BuildKit cache、allowlisted `/tmp` 诊断目录、显式 opt-in stale `/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`。
- `bun scripts/cli.ts platform-db postgres plan|status|apply --config config/platform-db/postgres-pk01.yaml`：管理 PK01 host-native PostgreSQL 16 外置平台库、TLS、Secret 导出和备份；跨节点消费者直连 YAML 声明的 PK01 公网 endpoint，不经 master server 中转，规则见 `docs/reference/pk01.md`。
- `bun scripts/cli.ts secrets plan|sync|status --config config/secrets-distribution.yaml --scope platform-infra`：按 YAML 声明把本地 Secret sourceRef 下发到 G14 `platform-infra` Kubernetes Secret key，禁止从运行面反推密码/API key，规则见 `docs/reference/platform-infra.md#secret-distribution-boundary`。
- `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 dry-run 形态，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`：查看 host Codex 指挥官直管微服务 skeleton 的 source summary、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合和 ClaudeQQ 高风险请示草案；当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令，不接 live bridge、不接管人工指挥官，不发送消息，AgentRun 派单边界由指挥官直接审查，规则见 `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 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 以 issue/CLI 选中的 node/lane 和 `config/hwlab-node-lanes.yaml` 为准，规则见 `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 submit [prompt] [--prompt-file path|--prompt-stdin] [--queue <id>]` / `codex execution-plane [--full|--raw]` / `codex pr-preflight [--remote]`：`submit` 等旧写入口已冻结并返回 AgentRun 替代命令；`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`。
- `$unidesk-webdev`：UniDesk/HWLAB Web 开发、Playwright、fake-server、web-probe、截图 artifact、Workbench/Performance 判定和 node/lane 原入口验收的唯一操作面；`docs/reference/cli.md` 只保留 CLI 命名索引。
- `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...]]`：交付前自动化 E2E 门禁，支持按 check/prefix/wildcard 选择最小相关集合；Web/Playwright 执行、截图和浏览器断言只看 `$unidesk-webdev`，门禁范围见 `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 透传并完成自测；部署边界见 `docs/reference/provider-gateway.md`，Web/Playwright 验收只看 `$unidesk-webdev`。
- `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`：交付前必须执行的自测门禁；Web/Playwright 操作面统一见 `$unidesk-webdev`，该文档不再作为浏览器测试细则来源。

## 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`：AgentRun Queue 与旧 Code Queue 指挥监督策略、并发窗口、轮询节奏、终态读取、阻塞拆分、PR handoff 和验收收口规则。
- `docs/reference/hwlab.md`：HWLAB 指挥侧 node/lane 目标解析、D601 v0.3 与显式 legacy 边界、最小 device-agent/gateway 桥接模型和受控发布边界。
- `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、legacy DEV/PROD 退役边界、G14 target 的 HWLAB runtime lane、device-agent 手动实验边界、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。
- `docs/reference/pk01.md`：PK01 腾讯云 provider-gateway、pikanode/MET Docker workload、SSH 透传、磁盘 GC 和 pikanode temp 长效 retention 边界。
- `docs/reference/yaml-first-ops.md`：YAML-first 异构分布式运维架构、现有 YAML 归属优先、公共 ops 层抽取、禁止硬编码 node/service 和薄 domain CLI 规则。
- `docs/reference/platform-infra.md`：G14 `platform-infra` namespace、YAML-first shared service 配置、YAML-controlled Secret distribution/no runtime reverse inference、Sub2API/Codex pool、WeChat archive / D601 WeChatFerry read-only upstream、FRP 暴露和 on-demand availability probe 开发边界；Sub2API 日常操作统一见 `$unidesk-sub2api`（`.agents/skills/unidesk-sub2api/SKILL.md`）。
- `docs/reference/master-server-ops.md`：主 server 本机 Codex profile wrapper、ACX/GOCX/Moon Bridge 路由边界、默认模型、真实调用验收和 MiniMax session recovery 规则。
- `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 summary、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/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`](docs/reference/g14.md) 一节，不重复抄写。
- 主机端 `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`](docs/reference/g14.md)。