pikasTech-unidesk/AGENTS.md

UniDesk Agent Index

UniDesk 以主 server 为统一入口。本文件只做自动加载的顶级索引；长期规则、流程和判定标准必须放到 skill 或 docs/reference/*.md。

P0: 主 worktree 同步提交第一原则

• P0: 发现固定主/目标 worktree 落后 remote 时，必须立刻先 git stash push -u 保存脏改（如有，含 untracked），再 git pull --ff-only 快进到最新 remote，然后 git stash apply 并按语义合并；主工作区恢复出的并行改动必须先直接提交，再继续后续任务；禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。

P0: 损害预防与文档治理

• P0: 源码/CLI 超过 3000 行必须按职责拆到 2000 行以下；大段脚本放入 .sh/.mjs/.py 等原生文件。细则见 docs/reference/devops-hygiene.md。
• P0: /root/unidesk 主 worktree 固定停留在 master；未预期修改默认属于并行任务，禁止 reset/checkout/删除，非 master 开发、语义合并和 worktree 清理由 docs/reference/devops-hygiene.md 约束。
• P0: Master server 禁止通用 Docker/Rust/Go/前端重型构建；执行面和受控例外见 docs/reference/dev-environment.md。
• P0: AGENTS.md 硬上限 10 KiB，只保留损害预防规则和索引；文档修改先加载 $docs-spec，细则见 docs/reference/agent-instruction-hygiene.md 与 docs/reference/docs-governance.md。
• P0: NC01 UniDesk server/backend-core 只认 config/unidesk-host-k8s.yaml 选中的 k8s unidesk 运行面；禁止用 Compose 替代，healthy 后非明确要求不扰动。细则见 docs/reference/nc01.md。

P0: 最新要求、可见性与验证

• P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard；阻碍最新目标的旧入口应删除，不做兼容保留。
• P0: 缺失的已声明验证依赖按仓库包管理器和锁文件安装后继续；状态、耗时、失败或关键证据不可见时先修可见性。细则见 docs/reference/devops-hygiene.md 与 docs/reference/observability.md。
• P0: CLI 改动、轻量语法验证和 compact text/显式 JSON 输出契约统一遵循 docs/reference/cli.md；默认不新增测试或运行裸 tsc。

P0: 配置、Secret 与 YAML-first

• P0: UniDesk 可调运维事实以 owning YAML 为唯一真相，代码只校验/渲染，变更走受控 CLI；细则见 docs/reference/yaml-first-ops.md、docs/reference/platform-infra.md 和 $unidesk-ymalops。
• P0: Secret 仅由 YAML sourceRef/targetKey 和受控 CLI 下发；禁止从运行面反解，输出只披露对象/key、presence、fingerprint 与摘要。
• P0: hyueapi.com / .hyueapi.com 必须保留在 NO_PROXY / no_proxy。

P0: 受控入口与技能路由

• P0: 跨 host/lane 现场修复加载 $dad-dev，完成真实运行面探测、最小验证、持久化和原入口复测。
• P0: CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署走 $unidesk-cicd 与受控 CLI；原生工具仅限有界诊断。
• P0: GitHub issue/PR 正式读写走 $unidesk-gh / bun scripts/cli.ts gh ...，禁止原生 gh/手写 API；写入默认中文。
• P0: 远端文本修改优先走 $unidesk-trans 的 trans <route> apply-patch；route/cwd 见 docs/reference/cli.md。
• P0: Web/Workbench/Playwright/web-probe 走 $unidesk-webdev；OTel/Tempo/trace 走 $unidesk-otel；Web 哨兵和周期巡检走 $unidesk-monitor。
• P0: “离线调查”只分析既有 trace/artifact/源码，不新开探针或改运行面；边界见 docs/reference/observability.md。

P0: 固定开发与运行面

• P0: HWLAB 固定使用 NC01/v03，AgentRun 固定使用 NC01/nc01-v02；workspace、route、配置真相、CI/CD 和原入口验收分别见 docs/reference/hwlab.md 与 docs/reference/agentrun.md。
• P0: D601 UniDesk workspace、任务 worktree 和 Master 构建边界见 docs/reference/dev-environment.md。
• P0: HWLAB 凭据脱敏和 issue 关闭遵循 docs/reference/hwlab.md；关闭前必须在选中 node/lane 走原入口真实验证，源码、PR 或构建通过不能替代。

P0: 长期参考入口

• CLI 与 route: docs/reference/cli.md。
• 文档治理与过程蒸馏: docs/reference/docs-governance.md。
• Agent 指令体积与分流: docs/reference/agent-instruction-hygiene.md。
• DevOps hygiene、source truth、worktree 稳定本地状态、语义合并与清理: docs/reference/devops-hygiene.md。
• 开发环境和 D601/Master 边界: docs/reference/dev-environment.md。
• 主 server Codex profiles/resume: docs/reference/master-server-ops.md。
• HWLAB: docs/reference/hwlab.md。
• AgentRun: docs/reference/agentrun.md。
• NC01: docs/reference/nc01.md。
• OTel/可观测性: docs/reference/observability.md。
• YAML-first: docs/reference/yaml-first-ops.md。
• Platform infrastructure: docs/reference/platform-infra.md。
• Secretary: docs/reference/secretary-reference.md。