diff --git a/AGENTS.md b/AGENTS.md index dcbdb1ba..9680ed8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,13 @@ # HWLAB Agent Index -HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥官和 runner 进入本仓库时的顶级索引。 +HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥官和 runner 进入本仓库时的顶级索引，只放入口、一句话规则和长期参考链接；细则统一维护在 `docs/reference/`。 ## Workspace - Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 - D601 发布/构建工作区是 `/home/ubuntu/workspace/hwlab`；不要把 runner 临时目录当作发布真相，详见 [docs/reference/deployment-publish.md](docs/reference/deployment-publish.md)。 -- 当前一律走 PR 工作流；不要直推 `main`、不要合并自己的 PR、不要改 PROD。 +- 当前一律走 PR 工作流；不要直推 `main`、不要合并自己的 PR、不要改 PROD、不要重启服务。 +- `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 是当前 M3 虚拟硬件可信闭环的上位约束；其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。 ## 固定入口 @@ -17,7 +18,9 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## 长期参考 - 长期参考入口：[docs/reference/README.md](docs/reference/README.md) -- 文档治理规范：[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) +- 文档治理与 docs-spec 入库规则：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) - 架构和 M3 主线：[docs/reference/architecture.md](docs/reference/architecture.md) - DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md) - 部署正规化、镜像发布、回滚和 Cloud Web 路径：[docs/reference/deployment-publish.md](docs/reference/deployment-publish.md) @@ -25,6 +28,12 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - M3 闭环 rollout runbook：[docs/reference/m3-loop-rollout-runbook.md](docs/reference/m3-loop-rollout-runbook.md) - runner issue 可见性与 prompt handoff：[docs/reference/runner-issue-visibility-handoff.md](docs/reference/runner-issue-visibility-handoff.md) +## 工作优先级 + +- 中文优先：issue、PR 正文、长期参考文档和用户可见说明默认用中文；英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留，详见 [docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)。 +- 用户反馈优先：用户和参谋提出的问题默认按高优先级用户反馈处理，blocker 状态不能替代反馈分流，必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 醒目位置，详见 [docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)。 +- PR 工作流优先：从最新 `origin/main` 创建短分支，提交 PR 到 `pikasTech/HWLAB:main`，runner 不直推 `main`、不合并 PR、不改 PROD、不重启服务，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 + ## 常用轻量命令 - 静态合同校验：`npm run validate` diff --git a/docs/reference/README.md b/docs/reference/README.md index 9d9691b2..18396d89 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -1,41 +1,33 @@ -# HWLAB Long-Term Reference +# HWLAB 长期参考入口 -`docs/reference/` is the stable reference entry for HWLAB agents, commanders, -and runners. It records reusable rules, boundaries, commands, and acceptance -criteria. Process issues and reports remain sources; they are not copied here -as run logs. +`docs/reference/` 是 HWLAB agent、指挥官和 runner 的长期参考目录，只记录长期稳定、可复用的规则、边界、入口、命令和验收标准。issue、日报、简报、一次性报告和执行流水账只能作为来源，不混入长期参考文档。 -## Reference Index +## 参考索引 -| Topic | Reference | +| 主题 | 参考文档 | | --- | --- | -| Documentation governance | [documentation-governance.md](documentation-governance.md) | -| Architecture and M3 decision line | [architecture.md](architecture.md) | -| DEV runtime, ports, k3s, DB DNS, and environment boundary | [dev-runtime-boundary.md](dev-runtime-boundary.md) | -| Deployment regularization, artifact publish, rollback, and Cloud Web rollout | [deployment-publish.md](deployment-publish.md) | -| Cloud Workbench default UI and UX boundary | [cloud-workbench.md](cloud-workbench.md) | -| Commander, runner, PR, and prompt handoff | [commander-collaboration.md](commander-collaboration.md) | -| M3 loop rollout runbook | [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md) | -| Runner issue visibility handoff | [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md) | +| 中文优先规则 | [chinese-first-documentation.md](chinese-first-documentation.md) | +| 用户反馈分流规则 | [user-feedback-triage.md](user-feedback-triage.md) | +| 文档治理与 docs-spec 入库规则 | [documentation-governance.md](documentation-governance.md) | +| 架构和 M3 上位约束 | [architecture.md](architecture.md) | +| DEV 运行态、端口、k3s、DB DNS 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) | +| 部署正规化、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) | +| Cloud Workbench 默认界面和 UX 边界 | [cloud-workbench.md](cloud-workbench.md) | +| 指挥官/runner 协作、PR 和 prompt handoff | [commander-collaboration.md](commander-collaboration.md) | +| M3 闭环 rollout runbook | [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md) | +| runner GitHub 可见性与 prompt handoff | [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md) | -## Current Stable Sources +## 当前稳定来源 -- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7): - commander board, priority ordering, and current issue state. -- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78): - `DC-DCSN-P0-2026-003` M3 virtual hardware trusted-loop direction. -- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99): - Cloud Workbench default frontend direction. -- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108): - no outer page scroll, Chinese UI, and internal Markdown help page. -- [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61): - DEV manual rollout review and the path toward CLI plus `deploy/deploy.json` - automation. -- [pikasTech/HWLAB#109](https://github.com/pikasTech/HWLAB/issues/109): - documentation governance and this reference system. -- [pikasTech/HWLAB#116](https://github.com/pikasTech/HWLAB/issues/116): - service deployment regularization in three stages: long-term reference, - controlled CLI/script entrypoints, and UniDesk CI/CD plus imageized delivery. +- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7)：指挥官看板、优先级顺序和当前 issue 状态；用户反馈必须挂到这里的醒目位置。 +- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：`DC-DCSN-P0-2026-003`，M3 虚拟硬件可信闭环方向和上位约束。 +- [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：issue 和长期文档中文化要求。 +- [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋反馈默认按高优先级用户反馈处理，并挂到 `#7`。 +- [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 规则必须固化进 HWLAB 长期参考文档。 +- [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99)：Cloud Workbench 默认前端方向。 +- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)：禁止外层页面纵向滚动、中文 UI 和内部 Markdown 帮助页。 +- [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61)：DEV 手动 rollout 复盘，以及走向 CLI 加 `deploy/deploy.json` 自动化的路径。 +- [pikasTech/HWLAB#109](https://github.com/pikasTech/HWLAB/issues/109)：文档治理和长期参考体系。 +- [pikasTech/HWLAB#116](https://github.com/pikasTech/HWLAB/issues/116)：服务部署正规化三阶段：长期参考、受控 CLI/脚本入口、UniDesk CI/CD 加镜像化交付。 -When an issue, report, or old document conflicts with a reference file here, -update the reference file first and keep `AGENTS.md` as a short index. +当 issue、报告或旧文档与本目录 reference 文档冲突时，先更新 reference 文档，再让 `AGENTS.md` 保持短索引。过程记录不得被改写；只能把稳定结论蒸馏进这里。 diff --git a/docs/reference/chinese-first-documentation.md b/docs/reference/chinese-first-documentation.md new file mode 100644 index 00000000..f4916fca --- /dev/null +++ b/docs/reference/chinese-first-documentation.md @@ -0,0 +1,40 @@ +# HWLAB 中文优先文档规则 + +本规则固化 [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121) 的要求：HWLAB issue、PR 说明、长期参考文档和用户可见说明必须中文优先，不能由英文主导。 + +## 适用范围 + +- `AGENTS.md` 和 `docs/reference/*.md` 必须中文主导。 +- GitHub issue、PR body、review 结论、runner 最终回执默认使用中文。 +- 面向用户或指挥官的 UI 文案、报告摘要和验收说明默认使用中文。 +- 过程记录、日报和临时调查笔记不应进入 `docs/reference/`；需要长期保留时只蒸馏稳定结论。 + +## 允许保留英文的情况 + +下列内容需要保真时可以保留英文，但应在首次出现处给出中文解释或上下文： + +- 命令、脚本名、文件路径、环境变量、端口、URL、协议名、HTTP path、JSON 字段、commit、tag、digest、ID。 +- 产品或组件固有名词，例如 `Cloud Workbench`、`runner`、`patch-panel`、`hwlab-cloud-web`。 +- 证据标签，例如 `SOURCE`、`LOCAL`、`DRY-RUN`、`DEV-LIVE`、`BLOCKED`。 +- GitHub、Kubernetes、FRP、UniDesk、k3s 等外部系统或标准术语。 + +## 编写规则 + +- 标题、段落、表格说明、验收标准和禁止事项优先用中文。 +- 英文术语不要替代中文解释；例如写“PR 工作流（pull request 工作流）”，不要只写 `PR workflow`。 +- 面向用户的反馈必须直说影响、优先级和下一步，不用英文模板化句式。 +- 文档更新时如果只做翻译，不改变语义；如果同时改变规则，必须在 PR body 中说明规则变化。 +- 不把每日简报、一次性执行日志、临时 blocked 状态或 changelog 式流水账写进长期参考。 + +## 验收标准 + +- `AGENTS.md` 能索引中文优先规则。 +- `docs/reference/README.md` 的索引和来源说明中文主导。 +- 新增或更新长期参考时，中文解释覆盖“做什么、为什么、怎么判定、禁止什么”。 +- 必要英文术语保留精确拼写，但不能让文档主体变回英文。 + +## 稳定来源 + +- [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：issue 和长期文档中文化。 +- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)：Cloud Workbench 中文 UI 约束。 +- [documentation-governance.md](documentation-governance.md)：长期参考和 docs-spec 入库规则。 diff --git a/docs/reference/commander-collaboration.md b/docs/reference/commander-collaboration.md index b3d4eaad..d06b4fab 100644 --- a/docs/reference/commander-collaboration.md +++ b/docs/reference/commander-collaboration.md @@ -1,6 +1,6 @@ -# HWLAB 指挥官协作参考 +# HWLAB 指挥官与 runner 协作规则 -本文定义 HWLAB 指挥官、runner、分支、PR 和 prompt handoff 的长期规则。 +本文定义指挥官、runner、分支、PR、prompt handoff 和文档维护的长期规则。 ## 指挥作风 @@ -10,7 +10,7 @@ - 不得把战略判断、是否偏离用户目标的判断、关键 PR 最终审查、关键部署证据审查、指挥官自我反省和指挥规则更新外派给 runner。 - 不得为了 Gate 生成 Gate、为了报告生成报告、为了审查再派审查、为了管理继续拆管理；Gate、报告、预检和观测脚本只能作为真实上线、真实 E2E 或 blocker 解除的必要最小工具。 - 派单前必须能回答该任务直接带来的用户可见变化、运行态变化或 blocker 解除是什么；回答不了时默认不派单。 -- 用户反馈 issue 默认高优先级处理；`pikasTech/HWLAB#131` 是当前指挥作风纠偏的权威来源。 +- 用户反馈 issue 默认高优先级处理；`pikasTech/HWLAB#131` 是当前指挥作风纠偏的一手事实权威来源。 ## 工作区规则 @@ -28,7 +28,7 @@ - 向 `pikasTech/HWLAB:main` 创建 PR。 - runner 不合并自己的 PR。 - PR 冲突由指挥官审阅并处理；runner 不做大范围冲突手术，除非被明确分配。 -- 指挥官合并 PR 时必须同时 review，确认方向没有偏离 #7、#78、#99 和当前用户反馈。 +- 指挥官合并 PR 时必须同时 review，确认方向没有偏离 `#7`、`#78`、`#99` 和当前用户反馈。 ## Prompt 合同 @@ -72,4 +72,7 @@ node scripts/runner-issue-visibility-preflight.mjs - [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 入库要求。 - [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md)：runner 可见性和 prompt handoff 详细规则。 diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index 0d81d067..6d1a7136 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -1,64 +1,60 @@ -# HWLAB Documentation Governance +# HWLAB 文档治理与 docs-spec 入库规则 -This is the local HWLAB copy of the `docs-spec` rules. Use it when editing -`AGENTS.md`, `docs/reference/*.md`, or distilling process records into stable -reference material. +本文是 HWLAB 仓库内固化的 `docs-spec` 规则副本和可执行摘要。编辑 `AGENTS.md`、`docs/reference/*.md` 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 `docs-spec` skill，也要以本文作为 HWLAB 本地权威落点。 -## AGENTS.md +## AGENTS.md 规则 -- `AGENTS.md` is only the project-level top index for quickly locating - commands, entry points, and documents. -- Documents with the same role as `AGENTS.md`, for example `CLAUDE.md`, should - contain only `@AGENTS.md` so multiple top-level mouths do not drift. -- Each command in `AGENTS.md` keeps one main index entry; command details live - in the linked reference document. -- Each sublist item describes one function point in one sentence. Do not - expand implementation details, parameters, or background analysis there. +- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和长期参考文档。 +- 与 `AGENTS.md` 同等作用的文档，例如 `CLAUDE.md`，只保留 `@AGENTS.md` 引导，避免多套口径漂移。 +- 每个命令在 `AGENTS.md` 中只保留一条主索引；参数、背景、判定标准写入链接的 reference 文档。 +- 每个列表项只描述一个功能点，用一句中文概括，不在顶层展开实现细节。 +- `AGENTS.md` 必须索引中文优先、用户反馈分流、PR 工作流、`#78` 上位约束和 `docs/reference/` 入口。 -## docs/reference +## docs/reference 长期参考规则 -- `docs/reference/` records only stable, reusable entry points, prerequisites, - constraints, and decision criteria. -- Do not put one-time logs, timestamped execution records, changelog-style - history, or easily stale status notes in `docs/reference/`. -- Each feature or command detail should have an independent reference document - under `docs/reference/`; `AGENTS.md` links to it. -- When a feature needs detail, update the detailed reference first, then update - `AGENTS.md` with a one-sentence summary and link. -- Knowledge updates follow these rules: add new stable knowledge, delete stale - knowledge, fix wrong knowledge, and merge duplicates. -- Avoid duplicated authority. If content repeats across documents, choose one - reference as the authority and point other documents to it. -- If a reference mentions a skill, explain how the skill relates to HWLAB code, - hardware, directories, and acceptance criteria. Do not copy generic skill - CLI usage unless the local HWLAB copy is required for continuity. +- `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准。 +- 不写日期化日报、一次性过程记录、实测流水账、容易过时的 changelog 或临时 blocked 记录。 +- 每个功能点优先对应 `docs/reference/` 下的独立 Markdown 文档；`AGENTS.md` 只链接和摘要。 +- 功能需要补充说明时，先更新 reference 详细文档，再更新 `AGENTS.md` 的一句话摘要。 +- 知识更新遵循：增加新稳定知识、删除过时知识、修正错误知识、合并重复知识。 +- 跨文档重复时，选择一个 reference 作为唯一权威出处，其他文档交叉引用它。 +- 涉及 skill 的 reference 必须说明该 skill 与 HWLAB 代码、硬件、目录和验收标准的关系；通用 CLI 用法直接引用 skill，不在仓库内复制成另一份通用手册。 -## Process Distillation +## 过程文档蒸馏规则 -- Process documents are historical records, usually timestamped and volatile. -- Distillation means extracting only the stable conclusion into - `docs/reference/`. -- Process records must not be edited or rewritten during distillation. -- Start with older process records and move forward; for large records, read in - windows and update the reference as stable conclusions emerge. -- Newer stable conclusions override older conflicting conclusions. -- A reference may briefly outline important development turns, but it must not - become a run log. +- 过程文档是历史资料，通常带时间戳，时效性强，不能直接进入长期参考。 +- 蒸馏只提取稳定结论、边界、验收标准和禁止事项。 +- 不篡改过程文档；过程记录是原始来源。 +- 大文件按滑动窗口阅读，读一段就提炼稳定结论，不等全部读完才更新 reference。 +- 新稳定结论覆盖旧冲突结论；旧过程只作为历史来源。 +- 可以简述重要发展脉络，但不能把长期参考写成流水账。 -## HWLAB Application +## 中文和反馈治理 -- `docs/reference/README.md` is the long-term reference entry. -- `AGENTS.md` stays the short operational index. -- Process issue links such as `#7`, `#61`, `#78`, `#99`, `#108`, and `#109` - are preserved as sources in references, not copied as full timelines. -- Current HWLAB rules about `16666/16667`, D601 workspace paths, M3 evidence, - Cloud Workbench default route, and PR workflow live in the dedicated - reference files. +- 中文优先规则见 [chinese-first-documentation.md](chinese-first-documentation.md)；长期参考必须中文主导。 +- 用户和参谋反馈分流规则见 [user-feedback-triage.md](user-feedback-triage.md)；默认按高优先级用户反馈处理并挂到 `#7`。 +- 影响 M3 判定的文档必须显式对齐 `DC-DCSN-P0-2026-003` / `#78`，不得把 SOURCE、LOCAL、DRY-RUN、fixture、edge-only health 或前端状态写成 M3 DEV-LIVE。 +- 影响发布、运行态、端口和 PR 流程的规则必须交叉引用对应 reference，不在多个文档里各写一套。 -## Local docs-spec Text +## 本地入库和同步机制 -This local copy is kept so HWLAB documentation work remains governed even when -the external skill body is not available in a runner. +- 本文保留外部 `docs-spec` 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理。 +- 每次任务涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，runner 应先读取外部 `docs-spec` skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。 +- 如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。 +- `docs/reference/README.md` 是长期参考入口；新增 reference 后必须更新该索引和 `AGENTS.md`。 + +## HWLAB 当前应用 + +- `#7` 是指挥官看板和用户反馈集中入口。 +- `#78` / `DC-DCSN-P0-2026-003` 是 M3 虚拟硬件可信闭环上位约束。 +- `#121` 要求 issue 和长期文档中文化。 +- `#122` 要求用户和参谋反馈默认高优先级并挂到 `#7`。 +- `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill。 +- 当前 HWLAB 的 `16666/16667`、D601 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护。 + +## docs-spec 原文副本 + +以下副本来自当前 runner 可见的 `docs-spec` skill，用于满足 `#123` 的本地固化要求。后续如果外部 skill 更新，应按“本地入库和同步机制”同步。 ```markdown --- diff --git a/docs/reference/user-feedback-triage.md b/docs/reference/user-feedback-triage.md new file mode 100644 index 00000000..9ed6b362 --- /dev/null +++ b/docs/reference/user-feedback-triage.md @@ -0,0 +1,47 @@ +# HWLAB 用户反馈分流规则 + +本规则固化 [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋提出的问题默认按高优先级用户反馈处理，并必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 的醒目位置。 + +## 默认判定 + +- 用户直接提出的问题、阻塞、体验不满、验收异议和方向纠偏，默认视为高优先级用户反馈。 +- 参谋、指挥官或 reviewer 代表用户提出的问题，默认也按高优先级用户反馈处理。 +- `blocked`、`blocker`、环境不可用或等待上游只能描述执行状态，不能替代用户反馈分流；被阻塞的用户反馈仍要保留高优先级、来源、影响范围和下一步。 +- 只有明确属于普通内部整理、低风险技术债或已被用户降级的事项，才可降为普通优先级。 +- 与 `DC-DCSN-P0-2026-003` / `#78` 冲突的反馈不能被忽略；必须先在 `#7` 标明冲突，再由指挥官决定排序。 + +## 必须进入 #7 + +分流时必须在 `#7` 醒目位置保留： + +- 反馈来源：用户、参谋、reviewer 或具体 issue/PR。 +- 反馈摘要：用中文一句话描述可执行问题。 +- 影响范围：文档、用户体验、M3 判定、DEV 运行态、发布流程或其他范围。 +- 当前状态：待分流、已派发、blocked、已验证或已关闭。 +- 关联项：相关 issue、PR、commit 或 reference 文档。 + +如果 runner 无法访问 GitHub issue，任务 prompt 必须把上述内容直接带给 runner；不能假设 runner 能读取 issue 评论。可见性规则见 [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md)。 + +## 执行顺序 + +1. 先把反馈记录到 `#7`，不要只散落在子 issue 或 PR 评论中。 +2. 判断反馈是否改变长期规则；如果改变，更新 `docs/reference/` 的权威文档。 +3. 如果反馈影响 M3 虚拟硬件可信闭环，优先对照 `#78` 和 [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md)。 +4. 如果反馈只影响实现细节，走短分支 PR 工作流，不直推 `main`。 +5. PR body 必须说明反馈来源、交付点和验证命令。 + +## 禁止事项 + +- 不得把用户反馈当作普通 backlog 静默后移。 +- 不得只在临时过程记录里写反馈，不更新 `#7` 或长期参考。 +- 不得用 blocker、等待上游、报告待补或环境限制替代用户反馈记录和优先级判断。 +- 不得用英文主导的 issue 或 PR body 处理用户反馈。 +- 不得用 SOURCE、LOCAL、DRY-RUN 或前端状态回应 M3 DEV-LIVE 反馈。 +- 不得绕过 PR 工作流直接改 `main`、改 PROD 或重启服务。 + +## 稳定来源 + +- [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7)：指挥官看板和用户反馈集中入口。 +- [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋反馈默认高优先级。 +- [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：M3 上位约束。 +- [commander-collaboration.md](commander-collaboration.md)：PR、runner 和 prompt handoff 规则。