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。