pikasTech-unidesk/AGENTS.md

UniDesk Agent Index

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

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

• P0: 主 worktree 同时存在脏改且落后 origin/master 时，必须先 git stash push -u 保存当前脏改（包含 untracked），再 git pull --ff-only origin master 快进到最新 master，然后 git stash apply 并按语义合并，确认 diff 后 git commit 并 git push origin master；禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。

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 同步冲突处理以文件开头的“主 worktree 同步提交第一原则”为最高入口；语义合并时保留并行改动的有效意图，不回滚到旧运行面或旧配置路径。
• 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: D518 HWLAB v0.3 固定主 workspace 是 D518:/home/ubuntu/workspace/hwlab-v03；源码/PR/rollout 修复必须在该路径下从最新 github/v0.3 创建独立 .worktree/<task>，不得用 master server 或本机 /root/HWLAB 代替。
• P0: BK7258 项目/苗总项目/飞思创/脚本适配/中间件适配/MicroPython 相关材料常用目录是 D518:D:\Work\HWLabOA\Project Management\[EPIC002][MIAO][PRJ001][BK7258]\，进入后先读 D002001001-SUMMARY.md。
• P0: JD01 HWLAB v0.3 固定主 workspace 是 JD01:/root/workspace/hwlab-v03；源码/PR/rollout 修复必须在该路径下从最新 github/v0.3 创建独立 .worktree/<task>。
• P0: JD01 HWLAB v0.3 出网和依赖拉取以 YAML host-route/host-proxy 配置为准；不要把 JD01 MDTODO/Cloud Web 任务默认归因或切到 Sub2API。
• 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。
• 文档治理与过程蒸馏: docs/reference/docs-governance.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。