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/删除；
  - 任务 worktree 只允许短生命周期使用，不得作为长期开发分支或常驻工作区；
  - 任务提交语义进入 `master` 后，必须立即核查并清理对应 worktree 和已合并本地分支；
  - 存在未提交修改、未吸收提交或语义不确定时禁止强行清理；
  - 非 `master` 开发、语义合并和 worktree 清理由 `docs/reference/devops-hygiene.md` 约束。
- P0: Master server 构建规则：
  - 禁止通用 Docker/Rust/Go/前端重型构建；
  - 执行面和受控例外见 `docs/reference/dev-environment.md`。
- P0: Agent 指令体积规则：
  - `AGENTS.md` 硬上限 10 KiB，只保留损害预防规则和索引；
  - 文档修改先加载 `$docs-spec`；
  - 细则见 `docs/reference/agent-instruction-hygiene.md` 与 `docs/reference/docs-governance.md`。
- P0: 文档、skill 与 Agent 指令写作规则：
  - 自然语言统一使用中文；
  - 发现非中文先翻译；
  - 过长单行随见随拆，且必须拆成结构化子列表，禁止自然换行；
  - 命令、路径、代码字段、协议名和上游原文引用可保留原文；
  - 细则见 `$docs-spec`。
- 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: 可临时缓解的非主线问题：
  - 先创建独立 GitHub issue 和语义化 MDTODO；
  - 主代理只执行有界、可逆、可验证的临时缓解；
  - 支线交独立子代理后，主代理立即回到原主线；
  - 完整判定和交付规则见 `$unidesk-subagent`。
- 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；
  - HWLAB 的 workspace、route、配置真相、CI/CD 和原入口验收见 `docs/reference/hwlab.md`；
  - AgentRun 对应规则见 `docs/reference/agentrun.md`。
- P0: D601 UniDesk workspace、任务 worktree 和 Master 构建边界见 `docs/reference/dev-environment.md`。
- P0: 控之星、CONSTAR、71-FILTER、71-FREQ、PLC 项目及 PLC 控制器相关任务的固定工作区：
  - 透传路由：`G14-WSL:win/d/Work/CONSTAR_workspace`；
  - Windows 路径：`D:\Work\CONSTAR_workspace`。
  - 直接在该固定主 worktree 工作，不创建任务 `.worktree`；并行改动保护和精确提交边界见 `docs/reference/devops-hygiene.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：`docs/reference/devops-hygiene.md`。
  - 同一文档也负责 worktree 稳定本地状态、语义合并与清理。
- 开发环境和 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`。
- Webterm 配置与受控部署: `docs/reference/webterm.md`。
- Secretary: `docs/reference/secretary-reference.md`。