# UniDesk Agent Index

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

## P0: backend-core 运行面冻结

- P0: backend-core 运行面恢复 healthy 后，除非用户明确要求，不得再触碰 backend-core 运行面；禁止主动执行 `server rebuild backend-core`、`server restart backend-core`、手工重建/重启/替换 `unidesk-backend-core` 容器或等价生产变更。

## P0: AGENTS.md 体积与分流

- P0: 本地和远端 `AGENTS.md` 硬上限是 10 KiB；超过或即将超过时，必须先分流到对应 skill 或 `docs/reference/*.md`，再在本文件保留一句话索引。
- P0: `AGENTS.md` 触发 dump、输出爆炸或上下文膨胀时，修文件结构，不提高 dump 阈值，不继续追加规则。长期入口见 `docs/reference/devops-hygiene.md` 与 `docs/reference/cli.md`。
- P0: 新增、修改或蒸馏长期参考文档必须先遵循 `$docs-spec`；`AGENTS.md` 只保留入口，不承载长文、日志、JSON、trace dump 或一次性排障过程。

## P0: 工作区、语义合并与并行修改

- P0: 本机可能有多个并行开发任务；发现未预期本地修改时默认保留，不得自动 `git reset`、`git checkout --`、删除或回滚他人修改。
- P0: 当前目录的主工作区（非 `.worktree/` 路径）必须固定停留在 `master` 分支；禁止把主工作区切到其他分支，非 `master` 开发必须使用独立 `.worktree/<task>`。
- P0: 主 worktree 同时存在脏改且落后 `origin/master` 时，先用 stash 保存当前脏改（包含 untracked），再 `pull --ff-only` 快进到最新 `master`，然后 apply stash 并按语义合并；禁止用 reset/drop/checkout 覆盖并行改动。
- P0: 固定主 repo 通常只做 source-truth 预检、fetch、status 和 worktree anchor；源码、配置、部署脚本、issue closeout 和高风险 dad-dev 工作必须使用独立 `.worktree/<task>`。文档/skill/长期参考轻量修改可直接在当前主 worktree 处理。细则见 `docs/reference/devops-hygiene.md`。
- P0: 清理任务 worktree 前必须按语义确认已合入 `master`：工作区 clean，相关提交是 `origin/master` 祖先或被 `--cherry-pick` 判定为等价吸收，必要时检查关键文件 diff/PR merge commit；不得仅因分支落后就删除。仍有未合入语义、未提交文件或不确定归属时，先合并/提交/推送到 `master` 或记录阻塞，不清理 worktree。
- P0: UniDesk 工具链自身修复必须先合并到 `master`，再把实际执行工具命令的 checkout 更新到包含该 merge 的最新 `master` 后继续使用；若当前 checkout 有并行脏改或非 master 分支导致不能安全 fast-forward，禁止 reset/stash/checkout 清理，改用干净 `origin/master` worktree 运行工具并说明原因。
- P0: Master server 禁止作为通用构建机；不得在 master server 执行 Docker/Rust/Go/前端等高 CPU 构建。受控例外见 `docs/reference/dev-environment.md`。

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

- P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard；阻碍最新目标的旧入口应删除，不做兼容保留。
- P0: 可见性问题优先修复；状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出再继续。细则见 `docs/reference/observability.md`。
- P0: CLI 改动默认不做单元测试、合同测试或新增测试脚本；除非用户明确要求，最多做语法检查和必要命令形态确认。
- P0: CLI 默认输出应是 Kubernetes 风格的简洁表格、短摘要和 drill-down 命令；JSON 只用于 `--json`、`--raw`、`--full`、`-o json` 或机器消费。超长输出 dump 是兜底，不是长期交互入口。细则见 `docs/reference/cli.md`。

## P0: 配置、Secret 与 YAML-first

- P0: UniDesk 自有配置优先使用 YAML；节点/lane、namespace、endpoint、版本、容量、退避窗口、Secret sourceRef 等可调项必须从 YAML 进入受控 CLI，不得写成隐藏默认。细则见 `docs/reference/yaml-first-ops.md` 和 `$unidesk-ymalops`。
- P0: Secret、API key、JWT/encryption key、`DATABASE_URL` 等凭据只能通过 YAML 声明 sourceRef/targetKey 和受控 CLI 下发；输出只披露对象名、key 名、presence、fingerprint 和摘要，不得打印完整凭据。
- P0: `hyueapi.com` / `.hyueapi.com` 是 Codex API 直连域名，必须保留在 `NO_PROXY` / `no_proxy` 中。

## P0: 受控入口与技能路由

- P0: 分布式敏捷现场修复必须使用 `$dad-dev`：P1 目标运行面探测，P2 最小热补闭环，P3 Git/项目持久化，P4 原入口复测。
- P0: CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署必须走 `$unidesk-cicd` 与受控 CLI；禁止把原生 `kubectl`、`argo`、`tkn`、`curl` 或临时 shell 当正式控制入口。
- P0: GitHub issue/PR 正式写入必须走 `$unidesk-gh` / `bun scripts/cli.ts gh ...`，禁止原生 `gh` 或手写 GitHub API 绕过；正文、评论和 closeout 默认中文。
- P0: 远端文本修改优先走 `$unidesk-trans` 的 `trans <route> apply-patch`；route 定位和容器 cwd 规则见 `docs/reference/cli.md`。
- P0: Web、Workbench、Playwright/web-probe、前端状态投影和线上 Web bug 复测使用 `$unidesk-webdev`；OTel/Tempo/trace 追踪使用 `$unidesk-otel`。
- P0: Web 哨兵、`web-probe sentinel`、`monitor.pikapython.com`、定期/周期巡检和新建巡检使用 `$unidesk-monitor`，涉及页面复现或截图时同时使用 `$unidesk-webdev`。

## P0: HWLAB、AgentRun 与节点边界

- P0: HWLAB 目标选择以 issue/CLI 明确的 lane+node 为准；无明确目标时才读取 `config/hwlab-node-lanes.yaml`。node、lane、workspace、namespace、GitOps path、Secret sourceRef 和 route 都以 YAML 为 source of truth。细则见 `docs/reference/hwlab.md`。
- P0: 每次开始 HWLAB node/lane 或 D601 UniDesk 分布式开发，必须先解析目标 node/lane，读取目标 workspace 的 `AGENTS.md`，并以该仓库规则为准。
- P0: D601 node-scoped HWLAB v0.3 不是 legacy；D601 legacy 只用于明确指定的旧 DEV/迁移/回滚对照路径。D601 k3s 操作使用 route `D601:k3s`，不得依赖裸 `kubectl` 默认 context。
- P0: D601 UniDesk 固定开发 workspace 是 `/home/ubuntu/workspace/unidesk-dev`；源码/配置任务先从最新 `origin/master` 创建独立 worktree。细则见 `docs/reference/dev-environment.md`。
- P0: AgentRun 是共享 Agent 执行基础设施；source-truth、lane、k3s route、gitbundle checkout authority、session policy 和 AipodSpec SecretRef 规则见 `docs/reference/agentrun.md`。

## P0: HWLAB API key 与 issue 关闭

- P0: `HWLAB_API_KEY` 必须按 issue/CLI 选中的 node/lane 和目标 HWLAB repo 规则解析；只能输出 source path、present/missing 或 redacted prefix，不得打印完整 key。细则见 `docs/reference/hwlab.md`。
- P0: HWLAB 用户反馈、CLI、Cloud Web、AgentRun、device-pod、公开 API 或运行面工作流 issue，关闭前必须按明确 lane+node 完成用户入口或原入口真实验证；仅源码检查、PR 合并或构建检查不得关闭。

## P0: 长期参考入口

- CLI 与 route: `docs/reference/cli.md`。
- DevOps hygiene、source truth、worktree 语义合并与清理: `docs/reference/devops-hygiene.md`。
- 开发环境和 D601/Master 边界: `docs/reference/dev-environment.md`。
- HWLAB: `docs/reference/hwlab.md`。
- AgentRun: `docs/reference/agentrun.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`。