docs: align Chinese-first feedback and docs governance
Merge PR #149 after Code Queue rebase and validation. This lands long-term documentation governance only: Chinese-first documentation, user-feedback triage, docs-spec entry rules, #131 first-source handling, and #78 commander constraints. No PROD/deploy/service changes.
This commit is contained in:
@@ -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`
|
||||
|
||||
+26
-34
@@ -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` 保持短索引。过程记录不得被改写;只能把稳定结论蒸馏进这里。
|
||||
|
||||
@@ -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 入库规则。
|
||||
@@ -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 详细规则。
|
||||
|
||||
@@ -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
|
||||
---
|
||||
|
||||
@@ -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 规则。
|
||||
Reference in New Issue
Block a user