pikasTech-unidesk/AGENTS.md

# UniDesk Agent Index

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

## P0: 文件体积与脚本分流

- P0: 任何源码/CLI 文件超过 3000 行必须先按职责差分拆到 2000 行以下再继续，禁止卡在 3000 行边界反复触发。
- P0: 禁止把 shell/Node/Python 等脚本作为大段字符串内嵌；脚本必须放入原生后缀文件（如 `.sh`/`.mjs`/`.py`）并从文件加载。

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

- P0: 发现固定主/目标 worktree 落后 remote 时，必须立刻先 `git stash push -u` 保存脏改（如有，含 untracked），再 `git pull --ff-only` 快进到最新 remote，然后 `git stash apply` 并按语义合并；主工作区恢复出的并行改动必须先直接提交，再继续后续任务；禁止用 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>`，PR 合并后及时快进固定主 worktree。文档/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: 不得用裸 `tsc`/`bun --bun tsc` 当语法验证；它会长时间卡住。CLI/TS 轻量验证用 `bun --check <具体文件>`、`bun scripts/cli.ts check` 默认 syntax transpile 和必要命令形态确认；细则见 `docs/reference/cli.md`。
- 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: 用户要求“离线调查”时，按 `$unidesk-otel` + `$unidesk-webdev` + `$unidesk-gh` 执行：OTel 离线 analyze、已有 web-probe artifact/analyze、代码静态分析和 `../opencode` 对比；不得新开 web-probe 或改运行面；工具不好用先改工具。
- 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`。