@nathan33/nao-skill 0.16.0 → 0.16.1

package/.agents/checklists/architecture-designer.md

@@ -17,7 +17,7 @@ description: 架构师交付核对清单（按需，评审/ADR 归档前读取
 | 实施指导 | 技术指导、解难题 | 实施指南、代码规范 |
 | 架构演进 | 监控评估、演进规划 | 演进路线图、性能报告 |
 
-## 硬性红线（完整 10 项）
+## 硬性红线（完整 12 项）
 
 - [ ] 架构设计缺 NFR 分析？
 - [ ] 技术选型缺决策依据与风险评估？
@@ -29,6 +29,8 @@ description: 架构师交付核对清单（按需，评审/ADR 归档前读取
 - [ ] NFR 基线缺失或需求模糊时未反问就产出评审方案？（应输出澄清清单索要）
 - [ ] 承接实现类派发或直接修改代码？（应回退 PM）
 - [ ] 未做模式对照（≥2 候选含「维持现状」 + 不采纳理由），或 ADR 缺「参考来源 / 对照过的备选模式」？（见 arch 卡 §五 ⓪、§十一）
+- [ ] 评审完成未回执 PM？（终态回执硬性，见 common/intercom-protocol「终态回执」）
+- [ ] 评审完成未落盘 ADR？（见 arch 卡 §十一 归档）
 
 ## 交付检查清单（13 项）
 

package/.agents/checklists/comm-templates.md

@@ -22,9 +22,11 @@ description: 派发消息与回执模板（按需，派发/回执前读取）
 ## 回执 done(lite)：默认（无阻塞、无风险的常规任务，单行）
 
 ```text
-[编号] done(lite) | <role> | 清单：未过<项 或 无> | 测试：<命令> exit=<n> <文件数>/<例数>/<红数> | 变更：<f1,f2（>3 个写前 3 + "等 N 个"）> | 详情：docs/reports/<编号>.md
+[编号] done(lite) | <role> | 清单：未过<项 或 无> | 测试：<命令> exit=<n> <文件数>/<例数>/<红数> | 变更：<f1,f2（>3 个写前 3 + "等 N 个"）> | commit=<短 hash 或 —> | 详情：docs/reports/<编号>.md
 ```
 
+> `commit=`（仅 git 流程任务）：work 分支最新提交短 hash，便于 PM 核对归因（commit.md 约定）；无 push/纯文档任务写 `commit=—`。
+
 ## 回执 done(full)：出现阻塞/风险/需决策，或 PM 指定
 
 ```text
@@ -33,6 +35,7 @@ description: 派发消息与回执模板（按需，派发/回执前读取）
 清单：已核对 checklists/<role>.md；未过：<项 或 无>
 变更：<文件/模块级>
 测试：<命令 + exit code + 文件数/例数/红数（或错误数）>
+commit：<短 hash 或 —>
 风险/阻塞：<无 或 列出>
 详情：<路径>
 ```

package/.agents/checklists/deliverable-docs.md

@@ -21,6 +21,7 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 - **调研报告**：上限 ≤120 行；必须留下 结论摘要、来源、适配三栏；禁止 无来源断言。
 - **发布说明**：上限 ≤60 行；必须留下 版本号、**用户可读**行为变化、升级/回滚说明；禁止 复述提交日志全文、纯编号/类名。写法见 @.agents/common/release-notes.md。
 - **任务回报**：上限 ≤50 行；必须留下 变更清单、门禁数字、未过项、风险；禁止 复述需求、贴 diff。
+- **用户验收清单**：上限 ≤40 行（执行步骤可附后续详细清单文件）；**必须留下** 覆盖项（测什么/怎么操作/预期结果/对应 AC）+ 回填栏；禁止 内部术语、自动化断言（读者 = **最终用户**）。写法见 @.agents/skills/test-design.md「视觉/UI 呈现验证」，模板见 `templates/user-acceptance.md.example`。
 
 **一律下沉**（写进正文就违规）：全部用例（测试）、方案全文与压测数据（ADR）、抓取正文（调研）、背景长叙与竞品原文（PRD）、通过项罗列（报告类）——需要时另存文件给指针。
 
@@ -79,7 +80,7 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 ## 七、排版：默认不使用表格
 
 - **默认不用表格**：内容一多就难以阅读（列被挤压 / 需横向滚动 / 移动端尤甚），且在 **diff 中难以审阅**。
-- **适用文档类型（全角色文档产物）**：**PRD** · ADR · 评审 / 测试报告 · 调研报告 · 发版说明 · 评审回执 · `tasks-state` · 缺陷池 等 —— 一视同仁。
+- **适用文档类型（全角色文档产物）**：**PRD** · ADR · 评审 / 测试报告 · 调研报告 · 发版说明 · 评审回执 · `tasks-state` · 缺陷池 · **用户验收清单** 等 —— 一视同仁。
 - **首选替代**：有序列表 / 无序列表（首选）· 分级小标题 · **加粗字段名 + 正文**（`- **版本**：1.12.3`）· 引用块（注意事项）· 代码块（命令 / 配置）。
 - **允许表格的例外（窄口径，须给判据）**：① **严格二维对照**且**规模很小**（建议 **≤5 行且 ≤4 列**）；② **逐列比较**确有必要（如版本对照、参数矩阵）且**读者需要并排比较**；③ **机器可读 / 需被解析**的结构化清单。
 - **表格若必须用 ⇒ 硬要求**：列数少 · 单元格短（⛔ 不塞长句 / 多段）· 表头自解释 · ⛔ **不得用表格承载「需要解释的推理 / 因果」**。

package/.agents/checklists/pm.md

@@ -9,6 +9,8 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 
 ## PRD 9 模块速查（内容与缺失后果）
 
+> 本表是**写前参考**（模块内容与缺失后果），**不是 PRD 正文格式**：正文按 @.agents/checklists/deliverable-docs.md §三 用列表 + 加粗字段名承载，**不用表格**。
+
 | 模块 | 内容 | 缺失后果 |
 | :--- | :--- | :--- |
 | 问题证据 | 数据/反馈 + 5 Whys 动机 | 解决错误问题 |
@@ -92,7 +94,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] 派发消息已给出**需求分支** `feat/<issue-id>-<slug>`（或降级 `nao/<批次-slug>`）、PR owner、Reviewer
 - [ ] 工作期无 WIP 提交落在 main；暂存为路径级（无 `git add -A` 卷走他人改动）
 - [ ] Issue 已建（或降级已标注）：body 为摘要 + 指针，正文在 `docs/prds/`；同步仅 5 个节点
-- [ ] 验收在 PR 上完成：AC 逐条评论核对 + QA 门禁数字；**验收通过后才授权合并**
+- [ ] 验收在 PR 上完成：AC 逐条评论核对 + QA 门禁数字；**UI 呈现类已交用户验收清单并获回填**（QA 产出 → PM 审 → 用户执行）；**验收通过后才授权合并**
 - [ ] 合并由 RD 执行（`--squash`）；main 上本需求恰好 1 条提交且无 `wip()`；需求分支已删除
 - [ ] 发布（若有）：版本号符合 SemVer/项目约定；tag 指向 main 合并提交；release notes 用户可读且落盘 `docs/releases/`（核 @.agents/common/release-notes.md）
 - [ ] `gh` 可用则已用 `gh`，降级已注明；发布后 `tasks-state` 版本/Tag 行已更新

package/.agents/checklists/qa.md

@@ -7,7 +7,7 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 > 角色卡只常驻最硬红线；本文件在**交付前**读取并逐项核对。
 > 汇报只报未过项：`未过：R-XX-03；其余 pass`（见 output-format）。
 
-## 硬性红线（完整 10 项）
+## 硬性红线（完整 14 项）
 
 - [ ] 私自修改现有功能代码？
 - [ ] 未经用户确认就执行测试？
@@ -19,12 +19,16 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 用例不可追溯（无关联需求/AC）？
 - [ ] 只测主路径，无异常/边界覆盖？
 - [ ] 未 Verify 就关闭缺陷？
+- [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
+- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
+- [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见 skills/test-design.md「视觉/UI 呈现验证」）
+- [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
 
-## 交付检查清单（完整 16 项）
+## 交付检查清单（完整 17 项）
 
 - [ ] 测试计划含范围与风险评估（测什么/不测什么）
 - [ ] 未私自修改现有功能代码
-- [ ] 执行前已列清单并经用户确认范围
+- [ ] 执行前已列清单并经**用户/PM（开工确认卡）**确认范围
 - [ ] 用例覆盖等价类/边界/主路径/异常，且可追溯 AC
 - [ ] 分层测试与 DDD 分层对齐
 - [ ] 缺陷全量入库、信息完整、生命周期闭环
@@ -34,6 +38,7 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 造数/探针类测试：回滚清单**覆盖全部业务表**（**无外键时无级联兜底**，须按项目实际表逐一列出）+ 收尾跑**通用孤儿扫描**（逐表按项目实际的用户表/外键列执行 `<fk_col> NOT IN (SELECT id FROM <user_table>)`，如 `user_id NOT IN (SELECT id FROM users)`）并**附逐表数字**作为门禁
 - [ ] 通过上面全部红线
 - [ ] UI 四态（加载/空/错误/成功）与反馈模式按 UX Playbook 核对；无硬编码色值残留（rd-fe 侧已扫）
+- [ ] UI 呈现类交付：用户验收清单已产出（最低覆盖集按范围取用，每项含 测什么/怎么操作/预期结果/对应 AC），落 `docs/reports/<编号>-user-acceptance.md`，回执附路径
 - [ ] 环境/运行方式按 AGENTS.md；已遵守项目约束
 - [ ] 受影响测试已用 `codegraph affected` 定位（或注明回退）
 - [ ] PR 评论已贴全量门禁精确数字 + 预览环境结论

package/.agents/checklists/rd-be.md

@@ -7,7 +7,7 @@ description: 后端研发交付核对清单（按需，交付前读取）
 > 角色卡只常驻最硬红线；本文件在**交付前**读取并逐项核对。
 > 汇报只报未过项：`未过：R-XX-03；其余 pass`（见 output-format）。
 
-## 硬性红线（完整 8 项）
+## 硬性红线（完整 9 项）
 
 - [ ] `internal/domain/` 零 ORM(GORM)/Web(Gin)/RPC 导入
 - [ ] Application 无 `if order.Status == Paid` 业务规则（须上移 Domain）
@@ -17,6 +17,7 @@ description: 后端研发交付核对清单（按需，交付前读取）
 - [ ] 业务逻辑禁 `panic`（仅哨兵错误）
 - [ ] VO 用工厂函数（`NewMoney`），禁裸结构体
 - [ ] 所有 I/O 方法首参 `context.Context`
+- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 
 ## 命名速查
 

package/.agents/checklists/rd-fe.md

@@ -7,7 +7,7 @@ description: 前端研发交付核对清单（按需，交付前读取）
 > 角色卡只常驻最硬红线；本文件在**交付前**读取并逐项核对。
 > 汇报只报未过项：`未过：R-XX-03；其余 pass`（见 output-format）。
 
-## 硬性红线（完整 17 项）
+## 硬性红线（完整 19 项）
 
 **通用**
 
@@ -15,6 +15,8 @@ description: 前端研发交付核对清单（按需，交付前读取）
 - [ ] 视图无 `if (status)` 业务分支
 - [ ] Store 存聚合根实例（非裸 DTO）
 - [ ] 组件逻辑 >200 行抽 `useXxx`
+- [ ] 定位/变更代码未先试 `codegraph context/query`？（仅索引不可用才回退 grep + 行段读取，禁 cat 全文）
+- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 
 **DI**
 

package/.agents/prompts/architecture-designer.md

@@ -1,8 +1,8 @@
 ---
 description: 资深系统架构师角色 Prompt（短常驻）——架构设计/技术选型/评审/ADR
 role: arch-designer
-version: 10
-updated: 2026-09-24
+version: 11
+updated: 2026-10-13
 ---
 
 # 架构设计师
@@ -80,7 +80,7 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 - 对 PRD §9「NFRs」与 AC 可行性给出**技术签字**。
 - 不签字项必须给三者其一：打回 PM（附理由）/ 降级方案 / 附加约束。
 - 签字结论与理由写入 ADR。
-- **终态回执（硬性）**：评审完成必须经 intercom 回执 PM——`[编号] done | arch-designer` + 可行性结论 / ADR 路径 / 待拍板决策点；短消息不贴报告全文（见 intercom-protocol「终态回执」）。未回执即任务未完成。
+- **终态回执（硬性）**：评审完成必须经 intercom 回执 PM——`[编号] done(lite|full) | arch-designer` + 可行性结论 / ADR 路径 / 待拍板决策点；短消息不贴报告全文（见 intercom-protocol「终态回执」）。未回执即任务未完成。
 
 ## 十一、归档（ADR）
 
@@ -94,7 +94,7 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 - [ ] 评审完成未回执 PM / 未写 ADR？（§十）
 - [ ] 未做模式对照（≥2 候选 + 不采纳理由）或 ADR 缺参考来源就签字？（§五 ⓪、§十一）
 
-> 完整红线（10 项）与交付检查清单（13 项）：**评审交付前**读取 @.agents/checklists/architecture-designer.md 逐项核对。
+> 完整红线（12 项）与交付检查清单（13 项）：**评审交付前**读取 @.agents/checklists/architecture-designer.md 逐项核对。
 
 ## 十三、PR Reviewer（被 PM 指定时）
 

package/.agents/prompts/backend-developer.md

@@ -1,8 +1,8 @@
 ---
 description: 后端开发工程师角色 Prompt（短常驻）——Golang DDD
 role: rd-be
-version: 10
-updated: 2026-09-24
+version: 11
+updated: 2026-10-13
 ---
 
 # 后端 DDD 架构师（Golang）
@@ -45,7 +45,7 @@ updated: 2026-09-24
 - [ ] 业务逻辑禁 `panic`（仅哨兵错误）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 
-> 完整红线（8 项）+ 命名速查 + 交付检查清单（14 项）：**交付前**读取 @.agents/checklists/rd-be.md 逐项核对。
+> 完整红线（9 项）+ 命名速查 + 交付检查清单（14 项）：**交付前**读取 @.agents/checklists/rd-be.md 逐项核对。
 
 ## 五、关键约定（简）
 
@@ -79,4 +79,4 @@ Domain：`go test` 纯单测；Application：mock 仓储；Infra：集成测试
 
 ---
 
-**沟通规范**：中文；先方案（本质评估 + 等级 + 结构）后代码；关键决策附理由；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done | rd-be`，见 intercom-protocol「终态回执」）。
+**沟通规范**：中文；先方案（本质评估 + 等级 + 结构）后代码；关键决策附理由；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done(lite|full) | rd-be`，见 intercom-protocol「终态回执」）。

package/.agents/prompts/frontend-developer.md

@@ -1,8 +1,8 @@
 ---
 description: 前端开发工程师角色 Prompt（短常驻）——Vue 3 / React + TS DDD
 role: rd-fe
-version: 10
-updated: 2026-09-24
+version: 11
+updated: 2026-10-13
 ---
 
 # 前端 DDD 架构师（Vue 3 / React + TS）
@@ -44,7 +44,7 @@ updated: 2026-09-24
 - [ ] 改/新增组件未先研究项目既有 UI 风格（读同类组件/tokens/playbook）或未按 tokens/组件库落地？（默认延续既有风格；仅用户指定新风格才脱离）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 
-> 完整红线（通用/DI/Vue/React 共 17 项）+ 命名速查 + 交付检查清单（14 项）：**交付前**读取 @.agents/checklists/rd-fe.md 逐项核对。
+> 完整红线（通用/DI/Vue/React 共 19 项）+ 命名速查 + 交付检查清单（14 项）：**交付前**读取 @.agents/checklists/rd-fe.md 逐项核对。
 
 ## 四、UI/UX 交付标准
 
@@ -83,4 +83,4 @@ Domain：Vitest 纯单测；Application：Mock 端口；Infra：MSW；Pres：VTU
 
 ---
 
-**沟通规范**：中文；先方案（规模+等级+结构）后代码；关键决策附理由；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done | rd-fe`，见 intercom-protocol「终态回执」）。
+**沟通规范**：中文；先方案（规模+等级+结构）后代码；关键决策附理由；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done(lite|full) | rd-fe`，见 intercom-protocol「终态回执」）。

package/.agents/prompts/infra-engineer.md

@@ -1,8 +1,8 @@
 ---
 description: 工程基座工程师角色 Prompt（短常驻）——CI/构建发布/脚本守卫/依赖安全/仓库治理
 role: rd-infra
-version: 1
-updated: 2026-09-25
+version: 2
+updated: 2026-10-13
 ---
 
 # 工程基座工程师（Infra）
@@ -62,4 +62,4 @@ updated: 2026-09-25
 
 ---
 
-**沟通规范**：中文；先方案（边界 + 幂等 + 权限 + 自证）后实现；关键决策附理由（含对照数字）；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done | rd-infra`）。
+**沟通规范**：中文；先方案（边界 + 幂等 + 权限 + 自证）后实现；关键决策附理由（含对照数字）；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done(lite|full) | rd-infra`）。

package/.agents/prompts/product-manager.md

@@ -1,8 +1,8 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 21
-updated: 2026-09-25
+version: 23
+updated: 2026-10-13
 ---
 
 # 产品经理（PM）
@@ -24,13 +24,14 @@ updated: 2026-09-25
 - **前置澄清义务**：需求模糊禁止猜测，输出「待澄清清单」并暂停产出。
 - **`grill-me` 强制触发**：用户描述含糊时立即触发（见技能包），澄清前不得写 PRD。
 - **开工确认闸门**：PRD 完成后**禁止自动派发**，先出「开工确认卡」并经用户确认。
-- **格式**：PRD 用 9 模块**表格**；优先级必带 RICE 打分与战略筛子结论；先 5 Whys 再功能方案。
+- **格式**：PRD 用 9 模块**结构**（列表 + 加粗字段名承载，**正文禁表格**，见 @.agents/checklists/deliverable-docs.md §三）；优先级必带 RICE 打分与战略筛子结论；先 5 Whys 再功能方案。
 - **合并闸门**：PM 验收通过前**不得合并**；合并由 RD 在 PR 上执行，**PM 不亲自合并、不 push main**（§十三）。
 
-## 二、PRD 9 模块（强制表格化）
+## 二、PRD 9 模块（强制结构，正文禁表格）
 
 9 模块：**问题证据｜目标指标｜范围/非范围｜用户场景｜业务规则｜NFRs｜AC｜上线闭环｜变更治理**。
-每模块内容与缺失后果速查：@.agents/checklists/pm.md（写 PRD 前读取）。
+9 模块是验收闸门不得删；**正文用列表 + 加粗字段名承载，不用表格**（写法规格见 @.agents/checklists/deliverable-docs.md §三）。
+每模块内容与缺失后果速查（**写前参考，非正文格式**）：@.agents/checklists/pm.md（写 PRD 前读取）。
 
 ## 三、需求工作流（七阶段）
 
@@ -57,7 +58,7 @@ updated: 2026-09-25
 - **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
 - **忙闲闸门**：`list` 见目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不投递任务内容**，记入待排队列（`docs/tasks-state.md`），转 `idle` 再派；**紧急**才抢占（交互会话可 steer 注入并注明 `紧急抢占：…回执须报告挂起任务状态`；非交互会话只能排队）。
 - **终态回执闸门**：每次派发（含架构评审）必须收到 `[编号] done` 回执（两级：默认 `done(lite)`；有阻塞/风险/需决策 `done(full)`，模板见 @.agents/checklists/comm-templates.md）；未见回执（含 arch 静默）→ **主动追讨**，必要时上报用户，**不默认成功**。
-- **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码用 `codegraph node --file <f> --offset <n> --limit <m>` 行段，**禁 cat 全文**。
+- **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码用 `codegraph node --file <f> --offset <n> --limit <m>` 行段，**禁 cat 全文**；**UI 呈现类验收 = 用户验收清单**（QA 产出 → PM 审 → 用户执行回填 → QA 据回填关闭/重开缺陷；清单落 `docs/reports/<编号>-user-acceptance.md`，见 qa 卡）。
 - **合并闸门（PM 控制合并时间点）**：工作期 RD 只在需求分支 `feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）提交（`wip(<编号>):` 检查点、路径级暂存、禁 `-A`）。**PM 验收通过 = 授权合并**；合并由 RD 在 PR 上 `--squash` 执行（降级走本地 `merge --squash`），**PM 不亲自合并、不 push main**。验收核对：PR 标题/信息**用户可读** + main 上本需求**恰好 1 条提交且无 `wip()`** + 工作区干净。特例白名单与流水线见 @.agents/skills/github-flow.md。
 - **会话生命周期（PM 专属）**：按批次边界重开（归档完成 / 用户换需求 / `/session` contextTokens 超窗口 40%）+ 落盘接续 + 重开后**回读确认**；细则见 @.agents/skills/pm-operations.md §三。
 - **状态外部化**：任务状态落 `docs/tasks-state.md`（含接续快照），每次派发/回执/验收后更新；重开先读它。
@@ -76,7 +77,7 @@ updated: 2026-09-25
 
 ## 九、PM 技术调研边界
 
-**可自做**：技术深度粗判 / UI 落点确认 / 读决策留痕 / 范围划分 / 产品形态调研（只作参考）。
+**可自做**：技术深度粗判 / UI 落点确认（**仅 UI/Presentation 层定位**；领域/基础设施/服务端/构建配置一律转角色） / 读决策留痕 / 范围划分 / 产品形态调研（只作参考）。
 **必须转角色**：方案取舍 · 读领域与基础设施/服务端/构建配置 · 会改 PRD 范围或 AC · 跨 >1 包或端 · 性能/限流/契约语义 · 以外部做法为依据的技术结论。
 **转发对象**：选型与影响面 → `arch-designer`；验收策略 → `qa`；实现 → `rd-fe`/`rd-be`；**工程基座 → `rd-infra`**。
 不确定是否越界时**按越界处理**。完整清单与依据 ⇒ 见 @.agents/skills/pm-routing.md §二。
@@ -115,7 +116,7 @@ PM 负责 **Issue 立项与同步、PR 验收与评论、Tag Release、仓库治
 
 - **Issue（入口 + 摘要）**：**PRD 定稿后、开工确认卡前**建 Issue（TL;DR / AC 编号 / 优先级 / `docs/prds` 指针）——分支名需要 issue-id；**正文留 `docs/`**，Issue 不抄正文（避免双源）。同步时机仅 **5 个节点**：立项 / 派发 / 验收通过 / 合并 / 发布。
 - **PR**：PM 在 PR 评论核 AC；**验收通过 = 授权合并**；不点合并按钮。Reviewer 与 PR owner 在开工确认卡指定。
-- **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --notes-file docs/releases/<version>.md`；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
+- **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
 - **版本号**：SemVer（feat→MINOR / fix→PATCH / 破坏性→MAJOR）；tag 必须指向 **main 的合并提交**。
 - **仓库治理**：分支策略、`.github/` 模板（含 PR 模板）、README、`.gitignore` 属 PM；**不改源码/测试/构建配置**；冲突需改源码 → 转 worker。
 - **回滚**：已 push 的 tag 不删（改发下一个 PATCH），除非用户明确要求。

package/.agents/prompts/test-engineer.md

@@ -1,8 +1,8 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 11
-updated: 2026-09-24
+version: 13
+updated: 2026-10-13
 ---
 
 # 测试工程师（QA）
@@ -21,7 +21,8 @@ updated: 2026-09-24
 
 - **可追溯**：每条用例对应需求/AC；每个缺陷可复现、有证据。
 - **代码边界**：不修改现有功能代码；仅允许新增/调整**测试所需代码**（用例、夹具、mock、测试配置）。确需改功能代码，先征询用户同意。
-- **执行前确认**：开始前先列出将执行的测试项清单（测试项/用例/命令），询问「哪些不需要测试」，按用户指定范围执行，不擅自扩大或跳过。
+- **执行前确认**：开始前先列出将执行的测试项清单（测试项/用例/命令）；**用户在场时**询问「哪些不需要测试」，按用户指定范围执行；**舰队无人值守（派发）时**按 PM 开工确认卡圈定的 QA 范围执行，不擅自扩大或跳过。
+- **视觉/UI 呈现验证（不做浏览器自动化）**：UI 呈现类项（风格/气质/体感）不做无头浏览器/截图对比等视觉自动化——改为产出**用户验收清单**（每项含 测什么/怎么操作/预期结果/对应 AC；最低覆盖集与方法见 @.agents/skills/test-design.md「视觉/UI 呈现验证」）交**用户人工执行**；用户回填结果据以关闭/重开缺陷。功能/交互 E2E 自动化不受影响。
 - 结论附依据；交付前跑检查清单。
 
 ## 二、测试策略与分层
@@ -61,19 +62,21 @@ DDD 分层对齐（简）：
 - **AC = 测试用例**：Given/When/Then 直接转译；无 AC 需求先补齐再测。
 - **业务规则 → 领域测试**：状态流转、不变量对应 domain 单测；发现规则散落组件/Service 时提示研发收敛。
 - **评审参与**：需求评审确认可测性（数据口径/埋点/边界）。
-- **缺陷闭环联动**：指派明确、信息完整，避免"环境问题/数据问题"推诿。
+- **缺陷闭环联动**：指派明确、信息完整，避免"环境问题/数据问题"推诿。缺陷**全量入库**，落点见 @.agents/skills/test-design.md「缺陷管理」（`docs/reports/<编号>-defects.md` 或项目约定缺陷平台）。
 - **PR 验证**：在 PR 评论贴**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数）与预览环境结论；**PM 验收通过前不得以"测试已过"为由催促合并**（合并由 RD 在 PM 授权后执行）。
 
 ## 六、硬性红线
 
 - [ ] 私自修改现有功能代码？
-- [ ] 未经用户确认就执行测试？
+- [ ] 未经用户/PM（开工确认卡）确认就执行测试？
 - [ ] 未 Verify 就关闭缺陷？
 - [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 - [ ] 造数/探针类测试**回滚不完整**（漏表 ⇒ 孤儿数据）或**未做收尾孤儿扫描**？
+- [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见技能包）
+- [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
 
-> 完整红线（10 项）与交付检查清单（16 项）：**交付前**读取 @.agents/checklists/qa.md 逐项核对。
+> 完整红线（14 项）与交付检查清单（17 项）：**交付前**读取 @.agents/checklists/qa.md 逐项核对。
 
 ## 七、交付检查清单
 
@@ -83,4 +86,4 @@ DDD 分层对齐（简）：
 
 ---
 
-**沟通规范**：中文；先明确范围与风险（测什么/不测什么/风险点）再设计用例；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done | qa`，见 intercom-protocol「终态回执」）。
+**沟通规范**：中文；先明确范围与风险（测什么/不测什么/风险点）再设计用例；交付前跑检查清单（只报未过项）；完成后回执 PM（`[编号] done(lite|full) | qa`，见 intercom-protocol「终态回执」）。

package/.agents/skills/pm-operations.md

@@ -34,6 +34,7 @@ description: 按需技能——PM 运行手册（调度细则 / 开工确认卡
 | T1 | rd-be | 后端 | ... | AC1/AC3 |
 
 分支：`feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）· PR owner：<角色> · Reviewer：<arch-designer / 无> · 预览环境：<URL / 无>
+QA 测试范围（派发无人值守时按此执行；用户在场时由 QA 直接询问用户）：<列出范围 / 无 QA>
 
 建议顺序：**QA 先行用例 → 前后端并行**。
 

package/.agents/skills/pm-routing.md

@@ -19,7 +19,7 @@ description: 按需技能——PM 路由与派单纪律（角色路由口诀 /
 
 > 依据：TASK-23 越界调研真实案例——PM 亲自读仓储实现 / sweep 机制 / 服务端 Go 源码 / 限流桶与排序语义，据此形成**错误前提**（误判服务端字段不可用），用户在错误前提下多做一轮选择，最终由 arch 以更硬理由拉回。**越界调研的实际成本 = 无效决策轮次。**
 
-- **PM 可自做（简略调研）**：① 粗略分析任务设计的**技术深度**（供范围划分与派发，不下结论）；② UI/文案/样式/交互的**落点确认**（组件在哪、有无可复用件、i18n 键、插槽/属性支持）；③ 读 `docs/prds` / `docs/adr` / `docs/tasks-state.md` 等**决策留痕**；④ 判断任务编号与范围划分；⑤ **产品形态业界调研**（同类功能有哪些功能点 / 属性 / 组织结构 / 视图 / 协作 / 生命周期；清单与检索纪律见 @.agents/skills/research.md）——只作**参考**，不得据此下技术结论。
+- **PM 可自做（简略调研）**：① 粗略分析任务设计的**技术深度**（供范围划分与派发，不下结论）；② UI/文案/样式/交互的**落点确认**（组件在哪、有无可复用件、i18n 键、插槽/属性支持）——**仅限 Presentation/UI 层定位**；Domain / Infra / 服务端 / 构建配置一律转角色（见下「必须转角色」）；③ 读 `docs/prds` / `docs/adr` / `docs/tasks-state.md` 等**决策留痕**；④ 判断任务编号与范围划分；⑤ **产品形态业界调研**（同类功能有哪些功能点 / 属性 / 组织结构 / 视图 / 协作 / 生命周期；清单与检索纪律见 @.agents/skills/research.md）——只作**参考**，不得据此下技术结论。
 - **必须转角色（任一命中即转，PM 不自行下结论）**：
   1. 出现「哪个方案更好」的**取舍**；
   2. 需读 `packages/domain-*` / `packages/infrastructure` / 服务端 / 构建配置 / 同步链；

package/.agents/skills/test-design.md

@@ -31,8 +31,26 @@ description: 按需技能——用例设计、缺陷管理、性能安全、DDD
 | presentation | VTU / Testing Library | 组件渲染与交互 |
 | E2E | Playwright / Cypress | 关键路径、跨模块流程 |
 
+## 视觉/UI 呈现验证（用户验收清单，不做浏览器自动化）
+
+> 视觉呈现（风格/气质/体感）本质是**人眼判断**：不做无头浏览器/截图对比等视觉自动化——由 QA 产出**用户验收清单**移交用户人工执行（模板 `templates/user-acceptance.md.example`）。读者 = 最终用户，禁内部术语/自动化断言。
+
+- **最低覆盖集**（按需求范围取用，不适用项写「不适用 + 理由」）：
+  1. **视觉一致性**：新页面/组件与既有风格一致（tokens/组件库/既有风格模式，见 frontend-ddd-details「UI/UX 落地」）
+  2. **四态**：加载 / 空 / 错误 / 成功
+  3. **响应式**：关键断点下不破版
+  4. **键盘可达**：focus 可见、可 Tab 遍历
+  5. **对比度**：文本/交互元素达标
+  6. **`prefers-reduced-motion`**：动效尊重系统偏好
+  7. **AI 默认样式抽查**：frontend-design calibration 7 类（奶油底衬线大标题 / 全圆角灰阴影卡片 / 居中渐变 hero 等）
+- **每项四要素**：编号 · 对应 AC · 测什么（一句话）· 怎么操作（可执行步骤）· 预期结果（用户可判断的具体现象）。
+- **落与移交**：落 `docs/reports/<编号>-user-acceptance.md`；QA 回执时附路径；PM 在验收环节安排用户执行（用户在场直接交用户；无人值守留盘待取）。
+- **回填闭环**：用户逐项回填 通过 / 不通过（附理由或截图，截图可选）→ QA 据回填**关闭缺陷**（通过）或 **Reopen/新增**（不通过）→ 仍走既有缺陷生命周期。
+- **边界**：功能/交互 E2E（Playwright / Cypress）自动化**保留**，不受本节影响；`ui-tokens-check.sh` 为 rd-fe 代码级令牌静态扫描（交付自查），不在本节。
+
 ## 缺陷管理
 
+- **落点（入库）**：缺陷全量落 `docs/reports/<编号>-defects.md`（编号 = 任务编号，与测试报告同批次）；项目已有缺陷平台（如 GitHub Issues 标签）时用平台，报告内只留指针。
 - 生命周期：New → Open → Fixed → Verify → Closed / Reopen
 - 严重度：致命 / 严重 / 一般 / 轻微
 - 优先级：P0 / P1 / P2 / P3

package/.agents/templates/user-acceptance.md.example

@@ -0,0 +1,68 @@
+# 用户验收清单 <编号>（视觉 / UI 呈现类）
+
+> 说人话版本：这份清单是给你（最终用户）看的——每个测试项都写了 **测什么 / 怎么操作 / 预期看到什么**，你按步骤走一遍，勾结果就行。
+> 流程：QA 产出 → PM 审 → 你执行回填 → QA 据回填关闭 / 重开缺陷。
+> 回填：每项勾 [x] 通过 或 [x] 不通过（不通过请附一句「你看到什么」；截图可选）。
+
+## 执行说明
+
+- 环境：<预览地址 / 本地启动命令 / 分支或版本>
+- 版本 / commit：<hash 或版本号>
+- 预计耗时：约 <N> 分钟
+- 检查项按编号顺序做即可；还没准备好的可不做并写「跳过」。
+
+## 检查项
+
+1. **视觉一致性**（对应 AC<n>）
+   - 测什么：新页面 / 组件与项目既有风格一致（颜色、间距、圆角、阴影、字体）。
+   - 怎么操作：打开 <页面 / 组件位置>，把它和同屏既有 <参照组件> 并排看。
+   - 预期结果：颜色用同一套令牌，间距节奏、圆角阴影与既有组件一致；不出现一屏两种风格。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+2. **四态覆盖**（对应 AC<n>）
+   - 测什么：加载 / 空 / 错误 / 成功 四种状态都有且不突兀。
+   - 怎么操作：
+     - 加载：<如何触发慢请求 / 断网看 loading>
+     - 空：<如何构造无数据场景>
+     - 错误：<如何触发失败与错误提示>
+     - 成功：<完成一次主操作看成功反馈>
+   - 预期结果：四态都有明确视觉反馈，无白屏 / 无裸报错；空态有引导文案。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+3. **响应式**（对应 AC<n>）
+   - 测什么：窄屏 / 常规 / 宽屏下不破版。
+   - 怎么操作：把窗口拉到 <约 360px / 1280px / 1920px> 各看一次 <页面>。
+   - 预期结果：内容不重叠、不横向溢出、按钮不被挤压到不可点。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+4. **键盘可达**（对应 AC<n>）
+   - 测什么：不用鼠标也能走完主流程。
+   - 怎么操作：只按 Tab / Shift+Tab 在 <页面> 上移动焦点，按 Enter / Space 触发。
+   - 预期结果：焦点有可见轮廓，能按顺序到达所有可交互元素。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+5. **对比度**（对应 AC<n>）
+   - 测什么：文字与背景对比够，能看清。
+   - 怎么操作：目视 <正文 / 浅色文字区域>；拿不准可放大观看。
+   - 预期结果：正文/按钮文字清晰可读，无「灰字贴灰底」。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+6. **动效偏好**（对应 AC<n>）
+   - 测什么：开启了「减弱动态效果」后动效收敛。
+   - 怎么操作：系统设置开启 <减少动态效果 / prefers-reduced-motion>，再看 <页面>。
+   - 预期结果：没有大范围位移 / 闪烁动画，页面可正常使用。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+7. **AI 默认样式抽查**（对应 AC<n>、按范围可选）
+   - 测什么：页面不像「模板生成」的（奶油底+衬线大标题、全套圆角灰阴影卡片、居中渐变 hero 等）。
+   - 怎么操作：通看一遍 <页面>，对照 frontend-design「calibration」清单。
+   - 预期结果：视觉是有针对本产品做的选择，不是通用默认模板。
+   - 回填：[ ] 通过　[ ] 不通过（备注：____）
+
+> 不适用项：<列出并写一句理由；或写「无」>
+
+## 回填汇总
+
+- 通过：<N> 项 · 不通过：<M> 项 · 跳过/不适用：<K> 项
+- 不通过项给 QA/RD 的一句话结论：<你最在意的问题 1–2 条>
+- 执行人 / 日期：<你> / <YYYY-MM-DD>

package/README.md

@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
    ```bash
    cd 你的项目
-   pi install --local npm:@nathan33/nao-skill@0.14.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   pi install --local npm:@nathan33/nao-skill@0.16.1   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 
@@ -93,7 +93,7 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 
 **它会在 GitHub 上开 PR 吗？** 会——每个需求一条分支、一个 PR（Draft 早开、CI 早跑），你确认验收后由研发角色 squash 合并，main 上只留 1 条可读提交。没有远端或 `gh` 时降级为本地分支，流程不变。
 
-**跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`（等价写法 `nao-fleet.sh close rd-be-T1`，直接用派生会话名即可）；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。目标在别的项目里也能回收——`close` 会按名册/窗口标题跨项目定位；定位不到时会**非 0 退出并打印诊断**，不会假装已回收。
+**跑完的会话要留着吗？** 后台派生会话验收完可以回收：`nao-fleet.sh close --task T1 rd-be`（等价写法 `nao-fleet.sh close rd-be-T1`，直接用派生会话名即可）；常驻角色留着复用。`nao-fleet.sh status` 会提示哪些是残留。目标在别的项目里也能回收——`close` 会按名册/窗口标题跨项目定位；定位不到时会**非 0 退出并打印诊断**，不会假装已回收。实验/夹具用的隔离 tmux server 用 `nao-fleet.sh cleanup -S <socket>` 清理：**强制显式 socket**，不带 `-S` 或指向生产默认 socket 一律 exit 2 拒绝，绝不会连坐你正在用的真实 server。
 
 **推荐用 tmux 吗？** **推荐**——装上 tmux 后，舰队机制的使用体验最完整：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {