pikasTech-HWLAB/AGENTS.md

# HWLAB Agent Index

HWLAB 是硬件实验室运行面和控制面项目。本文件只作为低噪声顶级索引，详细规则统一进入 `docs/reference/` 或对应 skill；远端读取 `AGENTS.md` 不应超过 UniDesk CLI 默认输出阈值。

## P0 当前任务定位

- 先按 issue、PR、CLI 参数或受控 lane 配置解析目标 `node + lane`；没有明确目标时才读取受控配置，禁止把 G14、v0.2、D601 legacy 或任意历史路径写成全局默认。
- D601 v0.3 的固定 workspace 是 `/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `origin/v0.3`；它是当前 D601/v03 source truth，不是 legacy 对照面。
- D518 v0.3 的固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `github/v0.3`；D518 源码、配置、部署和 issue 修复必须从这里创建 `.worktree/<task>`，不要使用 master server 或 `/root/HWLAB` 作为 D518 source truth。
- k3s 操作必须通过 UniDesk route，例如 `D601:k3s` 或 `G14:k3s`；不要使用另一节点 kubeconfig、Docker Desktop Kubernetes、master server 本地构建或旧 JS CD 结果作为当前 lane 证据。
- `hyueapi.com` / `.hyueapi.com` 必须保留在 `NO_PROXY` / `no_proxy`，Codex API 通道不得被 HTTP/SOCKS proxy 劫持。

## P0 文档与可见性

- `AGENTS.md` 只保留项目索引、一句话规则和交叉引用；细则写入 `docs/reference/`，通用操作写入对应 skill，避免远端读取触发 dump。
- 如果远端 `AGENTS.md`、CLI help 或默认命令输出超过 UniDesk dump 阈值，先改可见性：拆分文档、改简洁表格输出或补 drill-down，不用长 dump 当常态入口。
- 编辑 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，先遵循 `docs-spec`；单纯文档/CLI/helper 轻量变更可在当前 node/lane 固定主 worktree 直接提交并 push。
- GitHub issue/PR 正式写入走 UniDesk CLI；不要用原生 `gh` 或手写 GitHub API 写长期看板、反馈 issue 或 PR closeout。

## P0 交付边界

- CaseRun、case registry、trace 语义化、harness 诊断和短连接 runner 调试默认是无服务工作流；先单步定位卡点，再决定是否跑完整 CaseRun。
- 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流；PR base 必须匹配当前 node/lane source branch。
- 当前发布只走受控 node/lane Tekton/GitOps/Argo CD 控制面；旧 D601 `ci-publish`、`dev-cd-apply`、`dev-deploy-apply`、`dev-artifact-publish` 不得恢复。
- 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard；阻碍最新目标的旧入口直接删除或迁移，不做兼容绕行。

## Skill 路由

- Code Agent session/trace/result/inspect/send：使用 `hwlab-code-agent` skill。
- HWPOD CaseRun：使用 `hwlab-caserun` skill。
- HWPOD node/cloud-api 注册与节点运维：使用 `hwpod-ops` skill。
- DAD 跨节点修复、运行面实测和 PR/rollout 验收：使用 `dad-dev` skill。
- GitHub issue/PR 写入：使用 UniDesk `unidesk-gh` skill 和 `bun scripts/cli.ts gh ...`。
- OTel/Tempo 链路追踪：使用 UniDesk `unidesk-otel` skill。
- Node/lane CI/CD、trigger-current、git mirror、Argo/Tekton：使用 UniDesk `unidesk-cicd` skill。

## 长期参考索引

- Agent 入口拆分、输出预算、skill/reference 归属：[docs/reference/agent-entrypoint.md](docs/reference/agent-entrypoint.md)
- 指挥官协作、worktree、PR、自合并和 prompt handoff：[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
- Node GitOps CI/CD、当前受控发布边界：[docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)
- DEV/runtime 边界与禁止误判：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
- Cloud Workbench 默认首页与 UX 约束：[docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)
- Code Agent 真实回复、provider blocker 与 readiness：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
- OpenCode 独立 UI 接入、iframe 鉴权换票与 OTel 追踪：[docs/reference/opencode-integration.md](docs/reference/opencode-integration.md)
- AgentRun 手动调度与 UniDesk SSH passthrough：[docs/reference/agentrun-code-agent-dispatch.md](docs/reference/agentrun-code-agent-dispatch.md)
- Kafka session 源码直连与独立 debug topic 单步调试：[docs/reference/kafka-source-direct-debug.md](docs/reference/kafka-source-direct-debug.md)
- 文档治理与 docs-spec 本地权威：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md)
- 中文优先规则：[docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)
- 用户反馈分流：[docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)

## 常用轻量入口

- 当前 node/lane 状态由 UniDesk 受控 CLI 查询，例如 `bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03`。
- Web 等价短连接 CLI 在当前 node/lane 固定 workspace 运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url <target-web-url>`。
- Cloud Web 检查需要依赖时先跑 `npm run worktree:deps`；随后按任务需要跑 `npm run web:check` 或 `npm run web:build`。
- G14/D601 发布和 git mirror 操作以 UniDesk `hwlab nodes ...` / `hwlab g14 ...` 受控入口为准，不使用旧脚本 CD。