# UniDesk Agent Index

- UniDesk 顶级入口：

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

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

- P0: 固定主/目标 worktree 与 remote 不一致时，必须按顺序处理：
  - 用带当前操作唯一 marker 的 `git stash push -u -m <marker>` 保存全部脏改，包括 untracked，并按 marker 记录稳定 stash commit SHA；
  - 用 `git fetch` 刷新 remote；
  - 仅落后时用 `git pull --ff-only` 快进；
  - 分叉时必须把 remote 分支语义合并到固定 worktree，逐项解决冲突并保留双方有效语义；
  - 用 `git stash apply <stash-commit-sha>` 精确恢复并继续按语义解决冲突或重复内容，禁止依赖可变的 `stash@{N}` 或无参数 apply；
  - 先提交并推送语义合并及主工作区恢复出的并行改动，再继续后续任务；
  - 禁止绕过未对齐的固定 worktree，改用干净 anchor 或新任务 worktree 继续；
  - 禁止用 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: 构建执行面遵循 `docs/reference/dev-environment.md`；通用重型构建默认使用 NC01，Master server 仅执行轻量操作和受控例外。
- 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: HWLAB/UniDesk/AgentRun/HarnessRL/CaseRun、跨仓库能力、长期 API/数据模型、前端页面设计或 native/L1 调试涉及代码时，必须先加载 `$unidesk-oa`，读取对应 `project-management/PJ*/specs/` 规格并确认主责 L1；没有规格先补规格，不得直接以 issue 或源码开始实现。
- P0: L1 native 每个服务使用固定端口；若端口被确认属于同一服务的旧 L1 进程，先停止旧进程再同端口启动，不得换临时端口或停止其他服务；规则详见 `$unidesk-devlevel`。
- P0: L1 固定端口、host、状态目录和服务组成必须来自 YAML-first；启动、停止、重启、状态和日志必须走项目 CLI，禁止裸起 `npm run`、`bun run`、`vite` 或临时脚本；规则详见 `$unidesk-devlevel` 与 `$unidesk-webdev`。
- P0: L1 浏览器和用户入口必须使用 owning YAML 解析出的公网 IP 与固定 port；`127.0.0.1`/`localhost` 只能做本机健康 probe，不能作为 L1 验收或交付 URL。
- P0: NC01 UniDesk server/backend-core 运行面规则：
  - 只认 `config/unidesk-host-k8s.yaml` 选中的 k8s `unidesk` 运行面；
  - 禁止用 Compose 替代；
  - healthy 后非明确要求不扰动；
  - 细则见 `docs/reference/nc01.md`。

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

- P0: 未经用户明确要求，禁止为当前任务新增或扩展合同、租约、安全机制或围栏：
  - 既有权限、脱敏和损害预防底线继续遵守；
  - 衍生问题只能登记支线，不得实现、合并或作为主线门禁；
  - 细则见 `docs/reference/devops-hygiene.md` 与 `$unidesk-subagent`。
- P0: 微服务线上契约、版本和 `commitId` 对齐只允许非阻塞 warning，禁止阻塞用户业务；细则见 `docs/reference/devops-hygiene.md`。
- 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 现场修复加载 `$unidesk-daddev`：
  - 完成真实运行面探测；
  - 完成最小验证、持久化和原入口复测。
- 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 和语义化 TaskTree Task；
  - 主代理只执行有界、可逆、可验证的临时缓解；
  - 支线交独立子代理后，主代理立即回到原主线；
  - 完整判定和交付规则见 `$unidesk-subagent`。
- P0: 任务管理与 MDTODO 迁移统一遵循 `$unidesk-tasktree`。
- P0: 远端文本修改：
  - 优先走 `$unidesk-trans` 的 `trans <route> apply-patch`；
  - route/cwd 见 `docs/reference/cli.md`。
- P0: 专项技能路由：
  - 项目规格、前端产品设计 spec、CaseRun/HarnessRL、AgentRun、Temporal、跨仓库实现和 native/L1 开发先走 `$unidesk-oa`，再按 Web、Temporal、AgentRun 或 devlevel 继续加载专项技能；
  - Nginx 负载均衡、logger API 和 PK01 host-Docker 运维走 `$unidesk-nginx`；
  - Web、网页登录、截图、移动端、Workbench 和浏览器验收走 `$unidesk-webdev` 的 `web-probe` 受控入口，禁止直接调用 Playwright；
  - OTel/Tempo/trace 走 `$unidesk-otel`；
  - Web 哨兵和周期巡检走 `$unidesk-monitor`。
- P0: “离线调查”：
  - 只分析既有 trace/artifact/源码；
  - 不新开探针或改运行面；
  - 边界见 `docs/reference/observability.md`。

## P0: 固定开发与运行面

- P0: 固定运行面：
  - HWLAB 固定使用 NC01/v03；
  - AgentRun 固定使用 NC01/nc01-v02；
  - 具体规则分别见 `docs/reference/hwlab.md` 和 `docs/reference/agentrun.md`。
- P0: PikaPython V2 固定执行面：
  - route/workspace 为 `D601-VM-HOST:/home/ubuntu/workspace/pika_workspace`；
  - `D601-VM` 只是目标 ID，不是 `trans` route；不得改用 `D601`。
- 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: MET 非线性补偿研究与 MN 小论文投稿查询固定工作区：
  - 透传路由：`D518:win/c/work/met_nonlinear_master`；
  - Windows 路径：`C:\work\met_nonlinear_master`；
  - 历史投稿任务入口恢复前按 `$unidesk-tasktree` 迁移。
- P0: 李昂研究资料归档固定工作区：
  - `D518:win/d/work/研究资料归档-李昂` 对应 `D:\work\研究资料归档-李昂`。
- P0: 李昂求职材料与投递执行固定仓库：`/root/liang-career-materials`：
  - 状态真相为 `data/career.yaml`；
  - 详细任务统一由 `$unidesk-tasktree` 管理；
  - Todo Note 只保留 TaskGroup ID、总进度和本人阻塞索引。
- P0: HWLAB 凭据脱敏和 issue 关闭遵循 `docs/reference/hwlab.md`；关闭前必须在选中 node/lane 走原入口真实验证。

## 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 稳定本地状态、语义合并与清理。
- 开发环境和 NC01/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`。
- PikaOA development/release 运行面: `docs/reference/pikaoa.md`。
- Webterm 配置与受控部署: `docs/reference/webterm.md`。
- Secretary: `docs/reference/secretary-reference.md`。
