pikasTech-unidesk/AGENTS.md

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: Master server 构建规则：
  • 禁止通用 Docker/Rust/Go/前端重型构建；
  • 通用镜像构建和重型验证默认使用 NC01；
  • 只有 D601 自有流水线、运行面或硬件 lane 明确要求时才使用 D601；
  • 执行面和受控例外见 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: 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: 构建执行面和工作区边界见 docs/reference/dev-environment.md；通用构建默认使用 NC01，Master server 仅执行轻量操作和受控例外。
• 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。