mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7d7642dfcef9dab11af00b9c152cb3fc3b278da9
pikasTech-HWLAB/AGENTS.md
T
Codex Agent 7d7642dfce docs: 同步 G14 HWLAB API key 发现入口
2026-06-06 16:32:04 +08:00

22 KiB
Raw Blame History

HWLAB Agent 顶级索引

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

P0 文档/CLI 直接主 worktree 规则

  • P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前工作线固定主 worktree 直接修改、提交并 push 到对应 remote 分支，v0.2 默认 /root/hwlab-v02 -> origin/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: master server 和 G14 均已固化 v0.2 用户 API key，统一来源路径都是 /root/.config/hwlab-v02/master-server-admin-api-key.env；处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 v0.2 验收前，必须先从当前执行 host 的该文件加载或确认 HWLAB_API_KEY，禁止先把问题定性为缺少 API key。
  • P0: master server 和 G14 的 ~/.bashrc 会加载该固定文件，并通过 BASH_ENV=$HOME/.bashenv 让从交互 shell 派生的非交互 bash 也能读取 HWLAB_API_KEY；若当前进程没有继承环境，先显式 source ~/.bashrc 或确认该固定文件，不得改走别名、token、cookie 或临时 fallback。
  • P0: 查询 HWLAB_API_KEY 时只能输出 present/missing、source path 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。G14/HWLAB runtime 中环境变量缺失不代表 key 不存在，应先通过同一固定来源注入再继续排查。

P0 G14 原生 k8s/GitOps 运行面归一

  • G14 是当前 HWLAB DEV/PROD 原生 k8s 与 GitOps 运行面真相；hwlab-dev 与 hwlab-prod 均由 G14 k3s、Tekton、G14-gitops 和 Argo CD 管理，详见 docs/reference/g14-gitops-cicd.md。
  • v0.2 是 G14 上的加法扩容线：固定分支 v0.2、固定开发 workspace G14:/root/hwlab-v02、固定 CI/CD source repo G14:/root/hwlab-v02-cicd.git、固定 namespace hwlab-v02、FRP 入口 74.48.78.17:19666/19667；创建和集成 v0.2 不得删除、重命名、复用或改义现有 G14/G14-gitops 分支、hwlab-dev/hwlab-prod namespace 或 17666/17667、18666/18667 入口。
  • G14 GitOps render 若改变 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步应用 deploy/gitops/g14/argocd/project.yaml、application-dev.yaml 和 application-prod.yaml；只推 G14-gitops 分支不等于 Argo 已切到新 path。
  • D601 HWLAB DEV、D601 dev-cd-apply、ci-publish 和旧 main JS 脚本式 CI/CD 已退出 G14 发布入口；G14 Tekton 只能通过 scripts/g14-artifact-publish.mjs 作为集群内 build/push helper，再由 GitOps/Argo CD rollout，新开发、发布、验收、文档和运行面实验不得把 D601 或 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。
  • G14 k3s 操作必须通过 UniDesk route G14:k3s 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。

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 子命令或文档入口。
  • 当前发布只走 G14 k3s Tekton + G14-gitops + Argo CD；镜像构建 helper 是 scripts/g14-artifact-publish.mjs，desired state 由 scripts/g14-gitops-render.mjs 生成，细则见 docs/reference/g14-gitops-cicd.md。
  • 发现旧脚本、旧文档或旧 hwlab-cli cicd 再次进入 G14 Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到 G14 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。

工作区

  • G14 分支固定 source workspace 是 G14 节点上的 /root/hwlab，固定使用 G14 分支和 origin git@github.com:pikasTech/HWLAB.git。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 pwd 为 /root/hwlab 且 git status --short --branch 为 G14...origin/G14；不满足时先停止并修正 workspace。
  • v0.2 固定开发 workspace 是 G14 节点上的 /root/hwlab-v02，固定使用 v0.2 分支和 origin git@github.com:pikasTech/HWLAB.git。/root/hwlab-v02 只能作为 v0.2 人工开发、短连接源码工具和问题复现工作区，不得作为 G14 scratch 区、DEV/PROD 热修目录或 CI/CD source commit 选择入口。
  • v0.2 CI/CD source commit 只来自 G14 专用 bare repo /root/hwlab-v02-cicd.git 的自动 fetch 结果，并通过 devops-infra git mirror/relay 进入 Tekton、GitOps promotion 和 Argo；/root/hwlab-v02 的 dirty、stale 或 untracked .worktree/ 状态只能作为 isolated warning，不得阻塞或改变 CI/CD。
  • G14 开发默认先以 /root/hwlab 做固定 repo 预检，再在 /root/hwlab/.worktree/<task> 从最新 origin/G14 创建独立 worktree 修改和提交；固定 repo 不作为并行任务 scratch 区，详见 docs/reference/commander-collaboration.md。
  • G14 k3s 操作必须通过 UniDesk SSH route G14:k3s 执行，例如 bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci；禁止使用 ssh G14 k3s ...。不要把 /workspace/hwlab、/root/HWLAB、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。
  • Runner 和指挥常用工作区是 /workspace/hwlab；进入仓库先检查分支与工作树状态，详见 docs/reference/commander-collaboration.md。
  • G14 DEV/PROD CI/CD 由 G14 source branch、G14 k3s Tekton 和 G14-gitops branch 驱动；v0.2 CI/CD 由 UniDesk 手动 trigger、/root/hwlab-v02-cicd.git、devops-infra git mirror/relay、G14 k3s Tekton 和 v0.2-gitops 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到 G14 k3s/runner/CI/CD，不在 master server 跑重型验证。
  • G14/v0.2 远端验证必须用短连接触发后台 job、PipelineRun 或脚本任务，再用短连接轮询 status/tail/exit code；不要用 UniDesk SSH/tran 长连接等待 check、layout、Playwright、Tekton/Argo 或发布动作完整结束，细则见 docs/reference/spec-v02-cicd.md。
  • D601 发布/构建 worktree 纪律只适用于 legacy 路径回溯，不再作为当前 HWLAB 发布默认入口；当前入口见 docs/reference/g14-gitops-cicd.md。
  • 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch，G14 默认 origin/G14，v0.2 默认 origin/v0.2；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前工作线，不能默认投向 main；默认不要合并自己的 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，不能进入源码仓库。

固定入口

规格

长期参考

工作优先级

  • 中文优先：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 到当前工作线的 source branch，G14 默认 origin/G14，v0.2 默认 origin/v0.2；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 docs/reference/commander-collaboration.md。

常用轻量命令

  • 静态合同校验：npm run validate
  • 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/g14-artifact-publish.mjs --publish ...，只能由 G14 Tekton task 携带 CI artifact identity 调用；人工发布走 G14 poller/GitOps，不走 legacy CLI CD。
  • G14 monorepo 组件计划：node scripts/g14-ci-plan.mjs --base-ref <ref> --target-ref <ref> --pretty，只读分析 affected/reused services，基于内建 service-path component model 与 deploy/deploy.json；细则见 docs/reference/g14-gitops-cicd.md。
  • G14 GitOps 渲染：npm run g14:gitops:render；source 分支不再运行生成物 drift check，发布态由 Tekton 写入 G14-gitops。
  • DEV 依赖 runtime base 构建：npm run dev-runtime-base:build
  • Legacy D601 DEV CD：旧脚本入口已删除；事故回放只读历史 issue/commit，不恢复旧命令。
  • v0.2 WEB 等价短连接 CLI：在 G14:/root/hwlab-v02 或当前 v0.2 worktree 直接运行 bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url http://74.48.78.17:19666，默认走 Cloud Web 同源 API；细则见 docs/reference/spec-v02-hwlab-cli.md。
  • v0.2 HWPOD CaseRun 无服务入口：bun tools/hwlab-cli/bin/hwlab-cli.ts case run <caseId> --case-repo /root/hwlab-case-registry，第一阶段默认 compile-only 并把 evidence 写回 case registry repo，细则见 docs/reference/spec-hwpod-harness.md。
  • D601 k3s 只读观测：legacy 回溯入口，仅在确认需要 D601 事故复盘时使用；当前 G14 运行面观察使用 UniDesk route G14:k3s。
  • 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 只读回溯

当前 HWLAB DEV/PROD runtime（运行态）以 G14 原生 k3s 与 GitOps 为准；D601 只保留 legacy 事故回放、迁移对比和历史证据查询，不作为当前开发、发布、验收或 hotfix 目标。需要观察当前运行态时使用 UniDesk route G14:k3s，细则见 docs/reference/dev-runtime-boundary.md。

禁止误判

Reference in New Issue View Git Blame Copy Permalink