mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6f2430512d907fb02f9668234c7a48c3a0e797e
pikasTech-HWLAB/AGENTS.md
T

23 KiB
Raw Blame History

HWLAB Agent 顶级索引

HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥官和 runner 进入本仓库时的顶级索引，只放入口、一句话规则和长期参考链接；细则统一维护在 docs/reference/。

P0 CaseRun 无服务与单步调试规则

  • P0: HWPOD CaseRun、case registry 产物整理、trace 语义化、harness 诊断、短连接 CLI 和目标 node/lane host 上可直接运行的 runner 调试，默认是无服务工作流；目标 node 和 lane 以 issue、PR、CLI 参数或 deploy/deploy.yaml 的明确声明为准。只要不需要变更 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务，就必须直接无服务运行和验证，禁止为了运行 CaseRun 触发 CI/CD、rollout 或服务发布。
  • P0: CaseRun 卡在 hwpod-node、workspace prepare、编译、下载、串口、artifact 收集或其他基础设施步骤时，必须先把卡点拆成同一目标运行面的单步命令验证；禁止用反复全量 CaseRun 大回环替代单步定位。
  • P0: 只有单步卡点已经验证通过，且需要验证完整编排、trace 和 registry 产物时，才启动一次完整 CaseRun；完整 CaseRun 仍必须按 cli-spec 异步启动、短轮询状态、收集 trace，不得加入 evidence 自动评价、门禁或自动判断。

P0 文档/CLI 直接主 worktree 规则

  • P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前 issue/CLI 明确的 node + lane 固定主 worktree 直接修改、提交并 push 到对应 remote 分支。没有明确目标时才读取受控配置解析默认值，禁止把 G14、D601 legacy 或 v0.2 写成全局默认。
  • P0: 只有业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 或明确高风险改动，才按项目规则创建隔离 worktree 或走 PR；不要把重型开发流程套到文档/CLI 轻量变更上。
  • P0: 若固定主 worktree 因并行 dirty 文件无法快进，先保留并行变更，只提交当前文档/CLI相关文件；必要时使用非破坏性 rebase/autostash 或等价方式对齐 remote 后直接 push，禁止绕到新 worktree 掩盖主 worktree 状态。

P0 最高优先级：最新要求与旧门禁清除

  • P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言、旧 guard 和旧 gate；开发过程中遇到任何阻碍最新目标的旧测试、旧门禁、旧预检或旧断言，一律拆除，禁止继续维护、修补、叠例外或用兼容路径绕行。
  • P0: 短连接 CLI、临时工具、文档和轻量 helper 不套用常驻服务、镜像、Job、GitOps、PR、CI/CD 或重型发布流程的旧门禁；如果旧流程要求与最新架构定位冲突，以最新架构定位为准并删除旧流程入口。
  • P0: 任何测试、预检或自检只允许表达当前最新目标行为；旧历史断言不得作为回归保护保留，避免把旧路线固化成长期摩擦。

P0 CLI 鉴权边界

  • P0: HWLAB CLI 和 AgentRun/HWPOD runner 只允许从 HWLAB_API_KEY 读取用户 API key；不得新增或复活 API_KEY、HWLAB_BEARER_TOKEN、--api-key、--bearer-token 等别名入口。HTTP Authorization: Bearer 只是 CLI 从 HWLAB_API_KEY 生成的协议 header，不是第二个配置来源。
  • P0: Web 只走 hwlab_session Web session；CLI 保护命令缺少 HWLAB_API_KEY 时必须返回 api_key_required 或 unsupported_api_key_source，不得回退 Web session、cookie、password login 或 Keycloak token。
  • P0: 处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 runtime 验收前，必须先按当前 issue/CLI 明确的 node + lane 读取对应 API key sourceRef 或受控本地 env 文件；禁止先把问题定性为缺少 API key，也禁止把某个节点或 v0.2 的路径写成全局默认。
  • P0: 若当前进程没有继承 HWLAB_API_KEY，先确认目标 node/lane 的受控来源、~/.bashrc / BASH_ENV 注入和 CLI status 输出；不得改走别名、token、cookie、password login 或临时 fallback。
  • P0: 查询 HWLAB_API_KEY 时只能输出 present/missing、source path、sourceRef 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。目标 runtime 中环境变量缺失不代表 key 不存在，应先通过同一受控来源注入再继续排查。

P0 node/lane 运行面归一

  • HWLAB 当前开发、发布和验收目标必须先从 issue、PR、CLI 参数或受控 lane 配置解析 node + lane；例如 issue 明确 目标节点：D601、目标分支：HWLAB v0.3 时，D601 v0.3 就是当前运行面真相，不得回退到 G14、v0.2 或 D601 legacy。
  • 每个 lane 的 source branch、开发 workspace、CI/CD source repo、namespace、公网入口、Secret sourceRef 和 route 由 deploy/deploy.yaml 及 UniDesk hwlab nodes ... --node <node> --lane <lane> 控制面解析；长期文档只能记录解析规则和专项规格，不能把某个 node/lane 的数值写成全局默认。
  • v0.2 的人写 deploy/runtime 配置单一出处是 deploy/deploy.yaml；deploy/deploy.json 不再是 v0.2 兼容源。所有脚本、renderer、planner 和 CLI 必须通过 scripts/src/structured-config.mjs / scripts/src/deploy-config.mjs 这类格式无关读写层消费配置，禁止把 YAML parser import 或 ad hoc YAML 解析散落到业务脚本里。
  • Node GitOps render 若改变 Argo Application、AppProject、runtime path 或 lane 拆分目录，必须同步应用对应 node/lane 的 GitOps 文件；只推 GitOps 分支不等于 Argo 已切到新 path。
  • D601 旧 DEV、dev-cd-apply、ci-publish 和旧 main JS 脚本式 CI/CD 只属于 legacy 路径；D601 的 node-scoped runtime lane（例如 D601 v0.3）不属于 legacy。新开发、发布、验收、文档和运行面实验不得把 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。
  • k3s 操作必须通过当前目标 node 的 UniDesk route 执行，例如 D601:k3s 或 G14:k3s；不得用另一个节点的 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为当前 node/lane 的通过证据。

P0 HyueAPI Direct NO_PROXY 规则

  • hyueapi.com / .hyueapi.com 是 Codex API 通道的直连域名，必须始终保留在 NO_PROXY / no_proxy 中；DeepSeek、Codex API 或其他 provider profile 切换、G14 proxy 注入、旧 D601 egress 迁移和 pod/env render 都不得把 hyueapi 流量改成走 HTTP/SOCKS proxy。

P0 GitHub Issue 写入纪律

  • HWLAB #7、用户反馈、长期看板和指挥简报的 GitHub issue 正文写入必须走 UniDesk CLI：cd /root/unidesk && bun scripts/cli.ts gh ...；禁止直接用原生 gh issue edit/create/comment 写这些 issue。事故和工具补强需求见 pikasTech/unidesk#142。
  • 在 UniDesk CLI 局部替换、写前备份和写后 hash 验证能力完成前，不要对 #7 做无 guard 的整篇 body replace；必须先保留 before body、确认维护纪律 heading 仍存在，再写入。

P0 Legacy CD 删除纪律

  • 旧 D601 ci-publish、dev-cd-apply、dev-deploy-apply 和 dev-artifact-publish 脚本入口已经从当前发布面删除；不要恢复这些文件、CLI 子命令或文档入口。
  • 当前发布只走受控 node/lane 的 Tekton/GitOps/Argo CD 控制面；镜像构建 helper 是 scripts/artifact-publish.mjs，desired state 由 scripts/gitops-render.mjs 或 node/lane 控制面生成，细则见 docs/reference/node-gitops-cicd.md。
  • 发现旧脚本、旧文档或旧 hwlab-cli cicd 再次进入当前 node/lane Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到受控 GitOps 路径，不再做兼容保留。

P0 门禁最小化纪律

  • 架构迁移时，过时的自检、预检、guard、gate 优先拆除；不要在旧门禁上继续加例外、加复杂度或制造噪声。
  • 新增自检、预检、guard、gate 必须遵循最小原则，只覆盖明确高价值风险；禁止乱加门禁导致系统僵化、难迁移、难调试或产生大量误报和摩擦。

P0 v0.2 文档治理

  • AGENTS.md 是唯一顶级入口；README.md、docs/*.md、docs/*.json 和 docs/plan/*.md 不再作为 v0.2 仓库内文档形态保留。
  • 计划、里程碑、阶段迁移、一次性排障和旧报告全文迁入 GitHub issue；长期参考只吸收稳定结论并引用对应 issue。
  • v0.2 文档树收敛、D601/G14 旧口径处理和 JSON 放置边界见 docs/reference/spec-v02-documentation-governance.md。

工作区

  • 当前工作区必须由 issue、PR、CLI 或受控 lane 配置解析，预检内容至少包括 pwd、git status --short --branch、git remote -v 和目标 node/lane control-plane status；不满足目标时先停止并修正 workspace。
  • D601 v0.3 的固定开发 workspace 是 D601 节点上的 /home/ubuntu/workspace/hwlab-v03，固定跟踪 origin/v0.3；当 issue 明确 D601 v0.3 时，这个 workspace 是当前 source truth，不是 legacy 对照面。
  • G14 v0.2、G14 DEV/PROD 或其他 lane 的固定 workspace 只在当前任务明确选择对应 node/lane 时使用；不得把它们写成所有 HWLAB 任务的默认入口，也不得用一个 lane 的 dirty、stale 或 untracked .worktree/ 状态阻塞另一个 lane 的 CI/CD source commit 选择。
  • 业务代码、运行面或高风险变更按当前 node/lane 的固定 workspace 创建独立 worktree；固定 repo 不作为并行任务 scratch 区，详见 docs/reference/commander-collaboration.md。
  • k3s 操作必须通过目标 node 的 UniDesk SSH route 执行，例如 D601:k3s 或 G14:k3s；禁止使用 ssh <node> k3s ...。不要把 /workspace/hwlab、/root/HWLAB、master-server checkout、另一个节点 workspace 或临时 clone 当作当前 node/lane source truth。
  • Runner 和指挥常用工作区是 /workspace/hwlab；进入仓库先检查分支与工作树状态，详见 docs/reference/commander-collaboration.md。
  • CI/CD 由当前 node/lane 的 source branch、CI/CD source repo、Tekton/GitOps branch 和 Argo Application 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到目标 node/k3s/runner/CI/CD，不在 master server 跑重型验证。
  • 远端验证必须用短连接触发后台 job、PipelineRun、脚本任务或 trans <node> playwright，再用短连接轮询 status/tail/exit code；不要用 UniDesk SSH/tran 长连接等待 check、layout、Playwright、Tekton/Argo 或发布动作完整结束。
  • D601 legacy 只指旧 DEV/CD 回放路径；D601 node-scoped runtime lane 由当前 issue/CLI 明确选择时是正式开发、发布和验收入口，当前入口见 docs/reference/node-gitops-cicd.md。
  • 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前 node/lane source branch，不能默认投向 main、G14 或 v0.2。默认不要合并自己的 PR，用户或指挥官明确授权且满足门禁时可按长期参考自合并，不要改 PROD、不要重启服务。
  • DC-DCSN-P0-2026-003 / pikasTech/HWLAB#78 是当前 M3 虚拟硬件可信闭环的上位约束；其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。
  • 仓库禁止创建或提交 repo report 目录；验收、进展和结论只承载在 #7、专题 issue、每日简报或 PR/issue 评论。临时 JSON 只能写入 /tmp、.state 或 CI artifact，不能进入源码仓库。

固定入口

  • Runtime Web/API/live 入口必须从当前 issue/CLI 明确的 node + lane control-plane status 读取；没有明确目标时才从受控 lane 配置解析，不得把 G14、v0.2、DEV/PROD 或 D601 legacy 端口写成所有任务默认入口。
  • D601 v0.3、G14 v0.2 和其他 node/lane 的公网入口、namespace、route 与 GitOps 应分别由 docs/reference/node-gitops-cicd.md 和受控 CLI 输出确认。
  • Cloud Workbench 默认首页与 UX 约束见 docs/reference/cloud-workbench.md。

规格

长期参考

工作优先级

  • 中文优先：issue、PR 正文、长期参考文档和用户可见说明默认用中文；英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留，详见 docs/reference/chinese-first-documentation.md。
  • 用户反馈优先：用户和参谋提出的问题默认按高优先级用户反馈处理，blocker 状态不能替代反馈分流，必须挂到 pikasTech/HWLAB#7 醒目位置，详见 docs/reference/user-feedback-triage.md。
  • docs-spec 本地权威优先：涉及 AGENTS.md、docs/reference/*.md 或过程文档蒸馏时，先按 docs/reference/documentation-governance.md 执行，不另建同级规则副本。
  • 交付路径按风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前 node/lane 的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 docs/reference/commander-collaboration.md。

常用轻量命令

  • 静态合同校验：npm run validate
  • Cloud Web worktree 依赖准备：npm run worktree:deps；新 .worktree/<task> 内需要 Web 检查时先复用固定 workspace 的共享依赖，web:check 和 web:build 会自动调用。
  • Cloud Web 静态检查：npm run web:check
  • Cloud Web 构建：npm run web:build
  • Cloud Web M3 只读护栏：npm run web:m3-readonly
  • G14 artifact build helper：node scripts/artifact-publish.mjs --publish ...，只能由 G14 Tekton task 携带 CI artifact identity 调用；人工发布走 G14 poller/GitOps，不走 legacy CLI CD。
  • G14 monorepo 组件计划：node scripts/ci-plan.mjs --base-ref <ref> --target-ref <ref> --pretty，只读分析 affected/reused services，基于内建 service-path component model 与 deploy/deploy.yaml；细则见 docs/reference/node-gitops-cicd.md。
  • G14 GitOps 渲染：npm run gitops:render；source 分支不再运行生成物 drift check，发布态由 Tekton 写入 G14-gitops。
  • 平行 lane 配置扩容：npm run lane:expand -- configure --lane v03 --from v02 --write，只写 deploy/deploy.yaml 的新 lane 声明，后续 v04/v05/v06 复用同一入口。
  • GitOps lane 严格 TS 检查：npm run gitops:ts:check；新拆 GitOps 模块直接进入 scripts/src/*.ts 和 tsconfig.gitops.json，不要继续堆进单个 .mjs。
  • DEV 依赖 runtime base 构建：npm run dev-runtime-base:build
  • Legacy D601 DEV CD：旧脚本入口已删除；事故回放只读历史 issue/commit，不恢复旧命令。
  • WEB 等价短连接 CLI：在当前 node/lane 固定 workspace 直接运行 bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url <target-web-url>，默认走 Cloud Web 同源 API；能力规格见 UniDesk OA PJ2026-010402 HWLAB CLI，操作细则见 hwlab-code-agent skill 和本仓实现。
  • Code Agent session/trace/result/inspect/steer 操作见 hwlab-code-agent skill。
  • HWPOD CaseRun 无服务入口：用法见 hwlab-caserun skill；HWPOD 能力规格见 UniDesk OA 硬件池，CaseRun 语义见 HarnessRL。
  • 目标 k3s 只读观测：使用当前 node/lane 的 UniDesk route，例如 D601:k3s 或 G14:k3s；D601 legacy 事故复盘只在任务明确选择旧路径时使用。
  • DEV runtime hotfix 只读审计计划：npm run dev-runtime:hotfix-audit
  • Gateway 主动出站本地 smoke：npm run gateway:demo:smoke；经本地 edge-proxy 验证用 npm run gateway:demo:edge-smoke。

D601 legacy 与 D601 node-scoped lane

D601 legacy 只指旧 DEV/CD、迁移对比、事故回放和历史证据查询路径。D601 上的 node-scoped runtime lane（例如 issue/CLI 明确的 D601 v0.3）是正式当前目标，不得被 legacy 规则排除；需要观察当前运行态时使用该 node/lane 的 UniDesk route，例如 D601:k3s，细则见 docs/reference/node-gitops-cicd.md。

禁止误判

Reference in New Issue View Git Blame Copy Permalink