Codex
100 lines
9.2 KiB
Markdown
100 lines
9.2 KiB
Markdown
# HWLAB 指挥官与 runner 协作规则
|
||
|
||
本文定义指挥官、runner、分支、PR、prompt handoff 和文档维护的长期规则。
|
||
|
||
## 指挥作风
|
||
|
||
- 指挥官必须亲自掌握关键一手事实，不能只依赖 runner 的二手摘要。
|
||
- 必须亲自查看 `http://74.48.78.17:17666/` 默认首屏、`/gate` 或内部诊断页、关键 PR diff、部署 revision、DEV 验收结果和失败证据。
|
||
- 专题 issue 评论是长任务的上下文锚点。调查结论、细化方案、阶段进展、卡点、修复边界、验收命令和最终结论必须及时写入对应 GitHub issue 评论；不要只存在对话上下文、临时文件或本地记忆里。上下文压缩、换 agent、跨仓库修复或进入 CI/CD 前，应先读最新 issue 评论，再继续执行。
|
||
- Web/CLI 路径分叉属于优先级高的工具摩擦。浏览器工作台暴露问题后，先用 `hwlab-cli client` 走同一 Cloud Web base URL 复现；Code Agent continuation 优先用 `client agent send --from-trace <traceId>` 从 inspect 自动恢复 Web 上下文，device-pod 操作优先验证 `19666` 同源代理，再决定是否修业务本体。
|
||
- 一层 Code Queue 直接执行业务实现、修复、部署和验证是允许的基层指挥模式。
|
||
- 不得把战略判断、是否偏离用户目标的判断、关键 PR 最终审查、关键部署证据审查、指挥官自我反省和指挥规则更新外派给 runner。
|
||
- 不得为了 Gate 生成 Gate、为了报告生成报告、为了审查再派审查、为了管理继续拆管理；Gate、报告、预检和观测脚本只能作为真实上线、真实 E2E 或 blocker 解除的必要最小工具。
|
||
- 派单前必须能回答该任务直接带来的用户可见变化、运行态变化或 blocker 解除是什么；回答不了时默认不派单。
|
||
- 用户反馈 issue 默认高优先级处理；`pikasTech/HWLAB#131` 是当前指挥作风纠偏的一手事实权威来源。
|
||
|
||
## 门禁最小化原则
|
||
|
||
不要滑向不必要的复杂门禁是 HWLAB 指挥、runner、PR、CI/CD、GitOps 和扩容治理的通用原则。优先用固定边界、唯一真相源、标准入口、清晰命名、长期参考文档和验收 checklist 收敛共识；不要把每个设计约定、运行策略、观测项、回滚手册或一次性纠偏都升级成新的 preflight、guard、gate 或报告生成器。
|
||
|
||
旧门禁阻碍最新交付决策时，默认处理是删除或从当前调用链移除，而不是兼容性迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁前必须能说明它保护的明确高价值风险、为什么文档/结构/标准入口不足以自然收敛、失败信号如何保持低噪声，以及未来什么条件下可以删除。
|
||
|
||
## 工作区规则
|
||
|
||
- 常规 runner 和指挥官工作区是 `/workspace/hwlab`。
|
||
- 进入仓库先检查分支和工作树状态。
|
||
- G14 人工/指挥官开发必须先在固定 repo `/root/hwlab` 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建任务专属 worktree；代码、文档、测试补丁、提交和 PR 准备都在该独立 worktree 中完成。
|
||
- G14 `v0.2` 固定开发 workspace 是 `/root/hwlab-v02`，固定跟踪 `origin/v0.2`。所有 `v0.2` 文档、计划、CI/CD lane 和 namespace 设计必须在该 workspace 或其明确创建的 `v0.2` worktree 中完成；不得使用 `/root/hwlab` 根目录或现有 `hwlab-dev`/`hwlab-prod` 运行面作为 `v0.2` scratch 区。CI/CD source commit 选择只使用 `/root/hwlab-v02-cicd.git` 自动 fetch 后的 commit-pinned detached worktree，不能因为 `/root/hwlab-v02` dirty、stale 或存在 `.worktree/` 就阻塞或改变发布。
|
||
- 固定 repo `/root/hwlab` 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/<task>`。
|
||
- D601 `/home/ubuntu/workspace/hwlab` 只作为 legacy 事故回放和迁移对照工作区；当前 G14 DEV/PROD 与 `v0.2` 发布、rollout 和验收不使用 D601 作为运行面真相。
|
||
- 不要清理、reset 或复用无关 runner worktree 作为发布真相。
|
||
|
||
## 分支和交付工作流
|
||
|
||
- 单纯文档、CLI/helper 轻量变更默认直接提交并 push 到 `origin/G14`，不开 PR；这类变更仍要先从最新 `origin/G14` 创建独立 worktree，提交前审查 diff，只提交当前任务相关文件。
|
||
- `v0.2` 线的单纯文档和规格更新可以直接提交并 push 到 `origin/v0.2`，不开 PR；涉及 namespace 创建、Argo CD Application、Tekton Pipeline/control-plane、git mirror/relay、FRP、Secret、DB、权限或 runtime rollout 的变更必须先有 GitHub issue 承接过程计划，再按 issue 和对应 `docs/reference/spec-*.md` 分步执行。仓库内不再新增 `docs/plan/*.md`。
|
||
- 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD、重启服务、CI/CD 控制面高风险变更或其他影响 runtime truth 的变更默认走 PR 工作流。
|
||
- 用户或指挥官给出最新交付纠偏时，以最新要求为准，删除旧断言或旧门禁，不用 feature flag、legacy mode 或双路径长期并存绕开最新要求。
|
||
|
||
- G14 线需要 PR 时，从最新 `origin/G14` 创建短分支，PR base 指向 `pikasTech/HWLAB:G14`；`v0.2` 线需要 PR 时，从最新 `origin/v0.2` 创建短分支，PR base 指向 `pikasTech/HWLAB:v0.2`。
|
||
- `origin/main` / `main` 不再是当前 G14 或 `v0.2` 默认开发、PR 或发布 base；只有显式 branch-governance 或 D601 legacy 任务才可使用。
|
||
- 不要修改 PROD。
|
||
- 除非任务明确授权，不要重启服务。
|
||
- 需要 PR 时，目标分支必须匹配当前工作线的 source branch；不要把 G14 或 `v0.2` 变更默认投向 `main`。
|
||
- runner 默认不合并自己的 PR；用户或指挥官可以对单个 PR 明确授权 runner 自合并。
|
||
- 自合并前必须同时满足：PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态；required checks 没有失败；G14/`v0.2` CI 或当前 issue 显式指定的 legacy/runtime 验证证据已贴到 PR/issue；变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启；runner 在最终评论中列出提交 SHA、验证命令和回滚边界。
|
||
- 当前 GitHub 写入仍优先走 UniDesk CLI 或 repo-owned GitHub 路径；若当前 CLI 不支持 merge，必须使用可审计的授权路径，不能用无记录的本地绕行来规避审计。
|
||
- PR 冲突由指挥官审阅并处理；runner 不做大范围冲突手术，除非被明确分配。
|
||
- 指挥官合并 PR 时必须同时 review，确认方向没有偏离 `#7`、`#78`、`#99` 和当前用户反馈。
|
||
|
||
## Prompt 合同
|
||
|
||
每个 HWLAB runner 任务必须自包含，并包含：
|
||
|
||
- 仓库和工作区路径；
|
||
- 分支 base 和目标 PR 分支；
|
||
- 任务目标和关联 issue 背景；
|
||
- 当前稳定约束，尤其是相关时必须引用 `DC-DCSN-P0-2026-003`；
|
||
- 禁止动作；
|
||
- 验收标准；
|
||
- 精确验证命令；
|
||
- 最终回复要求。
|
||
|
||
派单前必须用 dry-run 或提交结果确认 prompt 实际内容不是本地临时文件路径、空字符串或被 shell 转义污染的文本。误派的任务要立即 cancel，并在后续派单中改用 `--prompt-file`。
|
||
|
||
不要假设 runner 能读取 issue 评论。需要 issue/PR 可见性时，运行：
|
||
|
||
```sh
|
||
node scripts/runner-issue-visibility-preflight.mjs
|
||
```
|
||
|
||
详细 prompt handoff 合同见 [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md)。
|
||
|
||
## 审查护栏
|
||
|
||
审查时必须拒绝以下输出：
|
||
|
||
- 把 SOURCE、LOCAL、DRY-RUN、fixture、edge-only health 或前端状态说成 DEV-LIVE；
|
||
- M3 绕过 `hwlab-patch-panel`；
|
||
- 用 UniDesk runtime 替代 HWLAB runtime；
|
||
- 把 Gate 或 diagnostics 放回 Cloud Web 默认首页；
|
||
- 继续使用历史公网 `:6666` 或 `:6667` 作为当前 DEV 入口；
|
||
- 把 runner kubeconfig 缺失、runner 观测 gap 或瞬时网络问题直接写成 D601/k3s 不可用；
|
||
- 把 `/v1/agent/chat` 的 `provider_unavailable`、`OPENAI_API_KEY` 缺失或
|
||
本地/mock 回显写成真实 assistant reply；
|
||
- 用报告完成、Gate 通过、预检通过替代用户可见上线、真实 DEV 运行态变化或 M3 blocker 解除。
|
||
|
||
## 稳定来源
|
||
|
||
- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7)：当前指挥官总看板。
|
||
- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：M3 prompt 和审查约束。
|
||
- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99)：Cloud Workbench 用户工作台主线。
|
||
- [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131)：指挥作风纠偏，一手调研和真实推进规则。
|
||
- [pikasTech/HWLAB#109](https://github.com/pikasTech/HWLAB/issues/109)：文档治理任务。
|
||
- [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：中文化要求。
|
||
- [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户反馈优先级要求。
|
||
- [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 入库要求。
|
||
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent chat 真实回复和 provider blocker 判定。
|
||
- [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md)：runner 可见性和 prompt handoff 详细规则。
|