@nathan33/nao-skill 0.21.2 → 0.22.0

package/.agents/scripts/nao-fleet.sh

@@ -19,6 +19,8 @@
 #                                                 （卡 role 与常驻 id/别名必须前缀不相交；不入 roles.yaml、不算常驻；
 #                                                  --as 须等于卡 role 或以 <role>- 为前缀，否则拒绝 —— fleet 按前缀识别身份）
 #   nao-fleet.sh ensure --force <别名>...          忽略"已在运行"判重
+#                                                 （目标解析为 pm 时追加一条固定首条用户消息：机制包版本自检，
+#                                                  仅提示不自动升级；关闭用 NAO_UPDATE_ON_ENSURE=0）
 #   nao-fleet.sh close <别名|派生会话名> [--task <编号>] [--force]
 #                                                 回收已完成会话（派生名如 rd-be-T1；跨仓定位；定位失败/名册报在线但无句柄 ⇒ 非 0 + 诊断）
 #                                                 （闸门：在跑 turn / tasks-state 未推进 → 拒绝，--force 跳过；
@@ -33,7 +35,7 @@
 #                                                 进程归属判定 pane_hosts_caller，不再依赖 $TMUX_PANE——T530）
 #
 # 角色别名 → 角色卡：见 .agents/roles.yaml（单一事实来源）
-#   当前：pm / arch-designer(arch) / rd-fe / rd-be / qa / rd-infra(infra)
+#   当前：pm / arch-designer(arch) / uiux-designer(uiux, ui-designer) / rd-fe / rd-be / qa / rd-infra(infra)
 #
 # 环境变量
 #   NAO_TMUX_LAYOUT=main-row2|main-col|grid   tmux 布局（默认 main-row2）
@@ -44,6 +46,7 @@
 #   NAO_MODEL_WHITELIST=<glob,...>            -m 白名单（默认空=不校验，支持 glob）
 #   NAO_CLOSE_BUSY_PATTERN=<ERE>             close 的在跑 turn 判定正则（默认内置 pi 状态行标记）
 #   NAO_TASKS_STATE=<path>                   任务状态文件（默认 docs/tasks-state.md，供残留检测/回收闸门）
+#   NAO_UPDATE_ON_ENSURE=0|false             ensure pm 的下游版本自检注入开关（默认开；0/false ⇒ 与本批之前逐字等价）
 #
 # 在线判定与 pane 定位（status / close / ensure 判重共用）
 #   ⚠️ pane id（%N）是 **server 局部**命名空间（每个 server 首块 pane 都是 %0）⇒ 任何「跨 server 比较
@@ -100,7 +103,15 @@ TMUX_MIN_PANE_WIDTH="${NAO_TMUX_MIN_PANE_WIDTH:-$TMUX_MIN_PANE_WIDTH_DEFAULT}"
 # T517：派生宿主窗口 ID（归一化 @<window_id>；空 = 定位失败 ⇒ 该角色 pane warn+skip，禁无 -t 续建）
 HOST_WINDOW=""
 # T536：本轮真正创建成功的 pane 数（>0 ⇒ ensure 收尾打印**恰一行**就绪提示；跳过/失败分支恒 0，BR3/AC4）
+# T539：三态计数（成功 / 跳过 / 失败）—— 每个 ensure 目标恰落一类，合计 = 目标数（BR3 计数守恒）
 SPAWN_OK=0
+SPAWN_SKIP=0
+SPAWN_FAIL=0
+# T539/BR2：spawn_tmux 的**显式**结果契约（返回值；调用方禁用「没打印就是成功」这类隐式约定）：
+#   0 = 成功（pane 已创建）· 2 = 跳过（宿主窗口未解析，未创建）· 3 = 失败（split-window 非 0，未创建）
+SPAWN_RC_OK=0
+SPAWN_RC_SKIP=2
+SPAWN_RC_FAIL=3
 # check 输出契约：默认摘要 2 行（摘要行 + codegraph 状态行，四态之一），-v 展开完整报告（六态全展开）；失败始终展开
 VERBOSE=false
 # close 的在跑 turn 判定（pi 默认状态行：Working (esc to interrupt) / Thinking... / Retrying / Compacting）
@@ -112,6 +123,33 @@ TASKS_STATE="${NAO_TASKS_STATE:-docs/tasks-state.md}"
 # 包名单源（BR5）：与 bin/nao-skill.js 的 PI_PLUGINS.codegraph 各一处，由 tests/t4/cases/18 等值断言兜住。
 # 运行时**不**跨语言抽取（sed 抽空 ⇒ 静默假「未声明」，且 shim-only 安装可能无 bin/）。
 CODEGRAPH_PKG="@sean_pedersen/pi-codegraph"
+
+# ---- ensure pm：下游机制包版本自检（M20261103 · PRD 2026-11-03-ensure-pm-update-check R1–R6）----
+# 注入文本是**常量**（R3 六要素齐备，grep 可自证）：fleet 进程内零外部命令、零网络（NFR），
+#   实际检查由 PM 会话自己按文本执行；未获用户同意前不得改文件/升级（R5）。
+# 开关（R6）：NAO_UPDATE_ON_ENSURE=0/false ⇒ 不注入（命令行与本批之前逐字等价）。
+NAO_UPDATE_MSG='【nao 机制包版本自检 · ensure pm 注入 · 仅提示，不自动升级】
+这条自检是本回合唯一额外动作；一行汇报后立即回到用户原来的消息，不要展开其它话题。
+1) 本地 pin：读 .pi/settings.json 里 @nathan33/nao-skill 的版本（X）；本仓若无该文件或无此 pin ⇒ 直接走 4 的情形 ④（不要说成必然有 pin）。
+2) 远端最新版：npm view @nathan33/nao-skill version --fetch-timeout=5000（内置 5s 超时；不要用外部 timeout 命令，macOS 原生没有；超时/报错 ⇒ 情形 ③）。
+3) 仅当有新版（Y 大于 X）才取要点：gh release view v<Y>（要点压成不超过两句，不要贴全文）；无 gh 或取不到 ⇒ 情形 ⑤。
+4) 只输出以下**恰好一行**（按 ①–⑤ 顺序命中即止，不解释、不追加）：
+   ① 有新版：当前 X → 可升 Y（要点）。要升吗？
+   ② 已最新：版本检查：已是最新 X。
+   ③ 离线或超时：版本检查：离线或超时，跳过（可稍后手动 npx @nathan33/nao-skill --version 核对）。
+   ④ 未检测到下游 pin：版本检查：未检测到下游 pin（本仓为机制源），跳过。
+   ⑤ 无 gh 只报版本号：版本检查：当前 X → 可升 Y（要点取不到，见 https://github.com/Nathan3303/nao-skills/releases）。要升吗？
+5) 硬约束：检查阶段只读；**未获我同意前不要改任何文件、不要升级**（不改 .pi/settings.json、不跑 pi install / pi update）。
+6) 只有我明确同意后才按序执行：pi install -l npm:@nathan33/nao-skill@<Y>（若提示安装脚本授权，停下来交给我确认，不要自行放行）→ pi update --extensions → 提醒我「本轮会话仍是旧角色卡，建议重开」。
+7) 我未表态或说稍后：原样待命，不要重试、不要轮询、不要后台检查。'
+
+# R1/R6：开关判定（默认开；仅显式 0/false 关闭）
+update_check_enabled() {
+  case "${NAO_UPDATE_ON_ENSURE:-1}" in
+    0|[Ff][Aa][Ll][Ss][Ee]) return 1 ;;
+  esac
+  return 0
+}
 # 状态文案单点（CG_MSG_*）：用例断言只认**固定前缀 + 命令子串**，不断言整行（防文案微调误伤）。
 CG_MSG_UNDECLARED='codegraph 插件未声明（装法：pi install npm:@sean_pedersen/pi-codegraph；定位回退 grep）'
 CG_MSG_NO_CLI='codegraph 插件已声明但 CLI 不在 PATH（装：npm i -g @colbymchenry/codegraph；回退 grep -rn + 行段）'
@@ -840,8 +878,10 @@ main_col_right_w() {
 }
 
 # main-row2：主 pane 全高占左；往右每列 2 个上下堆叠
-#   1 | 2 | 4
-#   1 | 3 | 5
+#   5 pane：1 | 2 | 4
+#           1 | 3 | 5
+#   7 pane：1 | 2 | 4 | 6
+#           1 | 3 | 5 | 7
 # tmux 规范：相邻子 pane 之间 1 格 gap；{} 左右排列，[] 上下排列
 build_main_row2_layout() {
   local win_w="$1" win_h="$2" pct="$3"
@@ -1059,17 +1099,20 @@ spawn_tmux() {
   local wrapped="bash -lc $(printf %q "$inner")"
   # T517：目标显式化——HOST_WINDOW 解析失败时此处已由解析处 warn（每 run 一次），
   #   跳过该 pane；禁止无 -t 续建（tmux 会落「当前窗口」= 用户视图，即缺陷根因）。
-  [[ -n "$HOST_WINDOW" ]] || return 0
+  # T539：显式回报「跳过」（不再用 return 0 冒充成功）。
+  [[ -n "$HOST_WINDOW" ]] || return "$SPAWN_RC_SKIP"
   # 窄窗口/宿主上限会让 split-window 失败（no space for new pane，含宿主窗已关竞态）；
   # 捕获后 warn 并继续，不因单个 pane 失败中断整轮 ensure。
+  # T539：显式回报「失败」；两条 warn 是诊断信息，保留不合并。
   local serr
   if ! serr=$(tmux split-window -h -t "$HOST_WINDOW" "$wrapped" 2>&1); then
     warn "pane 创建失败（宿主窗口 $HOST_WINDOW 过窄/已关或已达上限）：${serr:-<no message>}"
     warn "  已跳过该 pane，其余角色继续拉起；可放大窗口后重跑 ensure"
-    return 0
+    return "$SPAWN_RC_FAIL"
   fi
-  SPAWN_OK=$((SPAWN_OK + 1))   # T536：真创建成功才计数（就绪提示的唯一开关）
-  apply_tmux_layout
+  # 布局是尽力而为（内部各 tmux 调用已 || true）；布局成败不影响「pane 已创建」这一结果。
+  apply_tmux_layout || true
+  return "$SPAWN_RC_OK"
 }
 
 # 组装系统提示文件：角色卡 + 环境锚点（本机绝对路径，供跨仓库会话解析 @ 引用失败时兜底）
@@ -1084,9 +1127,14 @@ build_system_prompt() {
 }
 
 spawn_one() {
-  local name="$1" repo="$2" model="$3" card_override="${4:-}" card prompt_file inner
+  local name="$1" repo="$2" model="$3" card_override="${4:-}" role_id="${5:-}" card_name="${6:-}" card prompt_file inner
   # T537：卡路径可由调用方显式给出（下游仓卡）；未给出时仍走清单（PROMPTS_DIR/<card>）逐字不变
-  if [[ -n "$card_override" ]]; then card="$card_override"; else card="$PROMPTS_DIR/${PROMPT:-}"; fi
+  # #75：**两条取卡通道分两个参数，禁混用** ——
+  #   ④ card_override = `--card` 的**完整路径**（下游卡，已由 resolve_card 限定在 <repo>/.agents/prompts/ 内）
+  #   ⑥ card_name     = 清单**相对名**（roles.yaml 的 card 文件名，由 cmd_ensure **按目标**下发）
+  #   旧写法在无 override 时回落全局 `$PROMPT`（resolve 阶段每个目标覆写一次 ⇒ 最后一个胜出），
+  #   于是多目标 `ensure arch rd-fe` 的**每个** pane 都拿到最后一个目标的卡（身份级错误）。
+  if [[ -n "$card_override" ]]; then card="$card_override"; else card="$PROMPTS_DIR/${card_name:-}"; fi
   [[ -f "$card" ]] || die "角色卡不存在: $card"
   [[ -d "$repo" ]] || die "工作区不存在: $repo"
 
@@ -1095,6 +1143,12 @@ spawn_one() {
   inner="cd $(printf %q "$repo") && export CODEGRAPH_TELEMETRY=0 && exec pi --name $(printf %q "$name")"
   [[ -n "$model" ]] && inner+=" --model $(printf %q "$model")"
   inner+=" --append-system-prompt $(printf %q "$prompt_file")"
+  # M20261103/R2/R4：pm 目标在 `--append-system-prompt` **之后**以 `--` 分隔追加一条固定首条用户消息
+  #   （版本自检提示）；文本整体 printf %q 转义（禁拼接未转义文本）⇒ 不会被当成 @file 或选项。
+  #   纯字符串拼接，不跑任何外部命令（零网络）；非 pm / 开关关闭 ⇒ 本段不执行（命令行逐字不变）。
+  if [[ "$role_id" == "pm" ]] && update_check_enabled; then
+    inner+=" -- $(printf %q "$NAO_UPDATE_MSG")"
+  fi
   # T536/BR2：后台清理必须**完全脱离调用方 fd**。原写法 `( sleep 60; … ) &` 让子 shell 继承调用方
   #   stdout/stderr ⇒ 输出被 `| cat` / CI 捕获时调用方要等 EOF 到 60s 才返回（实测 60.3s vs 0.3s）。
   #   `disown` 只脱离作业表，不关继承而来的 fd。⇒ ① 三路重定向到 /dev/null；② 改用独立 argv 的
@@ -1102,9 +1156,17 @@ spawn_one() {
   #   不用 setsid：macOS 无该 bin，`… || true` 会静默跳过清理（BR1 缩水）。清理窗口 60s 不缩短。
   bash -c 'sleep 60; rm -f -- "$1"' _ "$prompt_file" >/dev/null 2>&1 </dev/null & disown 2>/dev/null || true
 
-  # 拉起（pane 级失败 = warn + 跳过该角色，D-A）；成功后打印「已拉起」
-  spawn_tmux "$name" "$inner"
-  log "[tmux] 已拉起 $name @ $repo${model:+（model=$model）}（layout=$TMUX_LAYOUT）"
+  # 拉起：spawn_tmux 以**显式三态**回报（T539/BR2）；每目标恰一行结果行：
+  #   成功 → 唯一一条 `[tmux] 已拉起 …`（内容逐字不变，BR1）· 跳过/失败 → 不打印成功行（BR2）。
+  #   `|| rc=$?` 是 set -e 下的必需写法（|| 列表豁免 errexit）；函数返回值即结果契约。
+  local rc=0
+  spawn_tmux "$name" "$inner" || rc=$?
+  case "$rc" in
+    "$SPAWN_RC_OK")   SPAWN_OK=$((SPAWN_OK + 1))
+                      log "[tmux] 已拉起 $name @ $repo${model:+（model=$model）}（layout=$TMUX_LAYOUT）" ;;
+    "$SPAWN_RC_SKIP") SPAWN_SKIP=$((SPAWN_SKIP + 1)) ;;
+    *)                SPAWN_FAIL=$((SPAWN_FAIL + 1)) ;;   # 3 = fail；未知值按失败处理（宁可少报成功）
+  esac
 }
 
 # ---------------------------------------------------------------------------
@@ -2000,8 +2062,8 @@ cmd_cleanup() {
 # ---------------------------------------------------------------------------
 cmd_ensure() {
   local force="$1" model="$2" task="$3"
-  local i spec role repo key seen k card_arg card_as disp
-  local -a cg_done=() t_names=() t_repos=() t_cards=()
+  local i spec role repo key seen k card_arg card_as disp role_id
+  local -a cg_done=() t_names=() t_repos=() t_cards=() t_roles=() t_prompts=()
   [[ ${#TARGETS[@]} -gt 0 ]] || die "ensure 需要至少一个角色，如: nao-fleet.sh ensure arch rd-fe rd-infra"
   # ==== 相位 1：全量解析 + 校验（BR11 两相执行）====
   #   卡、role、BR9、--as 全过才进相位 2；任一项失败都在**建 pane 之前** die ⇒ BR6「零副作用」可达
@@ -2032,12 +2094,16 @@ cmd_ensure() {
       else
         disp="$CARD_ROLE"
       fi
-      t_names+=("$disp"); t_repos+=("$CARD_REPO"); t_cards+=("$CARD_PATH")
+      t_names+=("$disp"); t_repos+=("$CARD_REPO"); t_cards+=("$CARD_PATH"); t_roles+=("${CARD_ROLE:-}")
+      # #75：card 目标只走 ④ 完整路径；⑥ 留空（两条通道互斥，override 不得被当相对名）
+      t_prompts+=("")
     else
       [[ -z "$card_as" ]] || die "--as 只能用于同一目标的 --card 之后（如 ensure --card <卡> --as <会话名>）"
       resolve_role "$role"
       [[ -n "$repo" ]] || repo="${ROLE_WS[$NAME]:-$PWD}"
-      t_names+=("$NAME"); t_repos+=("$repo"); t_cards+=("")
+      t_names+=("$NAME"); t_repos+=("$repo"); t_cards+=(""); t_roles+=("$NAME")
+      # #75：常驻卡名**当场**取证（resolve_role 每目标覆写全局 PROMPT ⇒ 只有此刻的值属于本目标）
+      t_prompts+=("$PROMPT")
     fi
   done
   # ==== 相位 2：拉起（宿主窗口解析、判重、codegraph 状态、spawn 逐目标不变）====
@@ -2055,18 +2121,20 @@ cmd_ensure() {
     if (( ! seen )); then codegraph_state "$repo" 1 "$(basename "$repo")"; cg_done+=("$key"); fi
     if [[ "$force" != "true" ]] && running "$disp" "$repo"; then
       warn "$disp 已在运行（终端标题/名册命中），跳过；确需重开请加 --force"
+      SPAWN_SKIP=$((SPAWN_SKIP + 1))   # T539/BR3：跳过也计入摘要（且不加成功行）
       continue
     fi
+    # #75：卡按目标下发（④ 完整路径 / ⑥ 相对名；两条通道互不混用），不再依赖全局 PROMPT
     if [[ -n "${t_cards[$i]}" ]]; then
-      spawn_one "$disp" "$repo" "$model" "${t_cards[$i]}"
+      spawn_one "$disp" "$repo" "$model" "${t_cards[$i]}" "${t_roles[$i]:-}" ""
     else
-      spawn_one "$disp" "$repo" "$model"
+      spawn_one "$disp" "$repo" "$model" "" "${t_roles[$i]:-}" "${t_prompts[$i]:-}"
     fi
   done
-  # T536/BR3/AC4：仅当本轮真拉起过 pane 才打印**恰一行**就绪提示；
-  #   跳过（已在运行）/失败（无宿主窗口、分屏失败）分支不打印；既有行内容与顺序不变（只追加末尾一行）。
-  if (( SPAWN_OK > 0 )); then
-    log "已拉起 ${SPAWN_OK} 个会话；就绪后在线状态用 nao-fleet.sh status 查看"
+  # T536/BR3/AC4 + T539/BR3：**恰一行**摘要，三类计数（成功/跳过/失败）；三类全 0 不打印（与现状一致）。
+  #   前缀「已拉起 N 个会话」保留（既有断言与用户习惯依赖），计数细化追加在括号内（BR6 旧→新对照见 T539 报告）。
+  if (( SPAWN_OK + SPAWN_SKIP + SPAWN_FAIL > 0 )); then
+    log "已拉起 ${SPAWN_OK} 个会话（成功 ${SPAWN_OK} / 跳过 ${SPAWN_SKIP} / 失败 ${SPAWN_FAIL}）；就绪后在线状态用 nao-fleet.sh status 查看"
   fi
 }
 

package/.agents/skills/github-flow.md

@@ -1,12 +1,12 @@
 ---
-description: 按需技能——新需求落地流水线（Issue → 分支 → PR → 验收 → squash 合并 → Release；GitHub Flow / trunk-based）
+description: 按需技能——新需求/缺陷修复落地流水线（阶段 0 受理分流 → Issue → 分支 → PR → 验收 → squash 合并 → Release；双通道 feat / fix）
 ---
 
 # 新需求落地流水线（GitHub Flow）
 
 ## 触发时机
 
-PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合并**时读取；QA 在 **PR 验证**时读取。日常轮次不加载。
+PM 在**受理 / 立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合并**时读取；QA 在 **PR 验证**时读取。日常轮次不加载。
 
 ## 原则
 
@@ -16,7 +16,23 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 - **合并权在 RD，闸门在 PM**：PM **验收通过前不得合并**；合并由 RD 在 PR 上执行，**PM 不亲自合并**。
 - **一个任务 PR = 全量改动**：实现 / 测试 / 文档（PRD 定稿 · 验收报告 · ADR · `tasks-state` 台账 · 报告 · 索引 · release notes）同属**一条** PR；**文档不单开 PR、不独立落 main**（唯一例外 = 立项摘要，细则见「文档与台账载体（一任务一 PR）」）。
 
-## 八阶段
+## 通道分流判据（唯一判据）
+
+- **默认 `fix`（轻通道）**：硬条件 = **能写出「期望行为 vs 实际行为」且可复现**（第三方按文字即可判定，禁「视情况」「大概率」）。
+- **升 `feat`（全通道）**：写不出期望/实际对比 · 不可复现 · **或超出报告所描述的期望范围**（新增能力 / 改动既有行为约定 / 破坏性契约）⇒ 全量 PRD（9 模块）+ 开工确认卡，按原流程走。**把「实际」改回「期望」不算行为改变**（否则每条修复都命中）。
+- **命名随通道**：`fix/<issue-id>-<slug>`（轻通道，diff 只碰修复路径）｜`feat/<issue-id>-<slug>`（全通道）；两者无 Issue 时统一降级 `nao/<批次-slug>`。
+- **减仪式不减门禁**：`fix` 免 9 模块 PRD / 开工卡降为一问 / 回执 `lite` / 复盘 `L0`，但 `check` + `npm test` 全量 rc=0 与「先红后绿」不变（细则 @.agents/prompts/product-manager.md §二）。**无测试设施**（纯文档仓 / 无 `npm test`）→ 用**最小复现命令**，修复前失败 / 修复后通过的**命令 + 输出**贴回执（可放 `docs/reports/<编号>-repro.*` 或 Issue 内联）；项目 `AGENTS.md` 指定了门禁命令则**以它为准**，未指定则 `check` rc=0。
+
+## 阶段 0 受理（triage；被动触发）
+
+| 触发 | 动作 | 产出 |
+| :--- | :--- | :--- |
+| ① 用户明确要求「看 Issue」；② PM 被指向具体 Issue 号；③ 对话中用户直接报障 | 一条 `gh issue list` 或 `gh issue view <n>`；按 triage 三问判定；摘录成 `docs/tasks-state.md` 任务条目并**以 Issue 号回链** | 通道判定（`fix` / `feat`）+ 台账条目 |
+
+- **triage 三问**：① 能否写出「期望 vs 实际」且可复现？② 来源是哪（用户 / QA / 线上 / 自查）？③ 是否影响已发布版本（影响则记版本 tag，`fix` 分支从该 tag 切出）？任一不能判定 ⇒ **挂起并回问用户，不猜**。
+- **被动义务（硬约束）**：**不轮询、不常驻、不建后台任务、不做标签自动化**；只在上述三种时机执行。无 `gh` / 离线时降级为用户口述 Issue 内容并留痕。
+
+## 八阶段（阶段 1–8）
 
 | # | 阶段 | 主责 | 动作 | 产出 |
 | :--- | :--- | :--- | :--- | :--- |
@@ -29,6 +45,10 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 | 7 | 发布 | PM | 版本号 + tag + Release notes（优先 `gh`） | Release 记录 + notes 落 `docs/releases/`，批间收尾事实随发布提交带走 |
 | 8 | 复盘 | PM | 监控指标、关 Issue、归档 PRD | 复盘 + 归档（随发布提交或**下一任务 PR**） |
 
+## 非范围（显式 out-of-scope）
+
+**生产部署 / 灰度发布 / 线上监控与告警 / 线上回滚执行 / MTTR / SLA 不归舰队**。舰队只负责「问题 → 分流 → 修 → PR → 验收 → 合并 → 发版」；线上暴露的问题仅作为 **Issue 输入源**进来（记受影响版本 tag、`fix` 分支从该 tag 切出、修完回合 main），其观测与回滚阈值不在本机制内。
+
 ## 文档与台账载体（一任务一 PR）
 
 **一个任务 PR = 该任务全量改动**（BR1）：文档与台账不另立载体，`docs/` 改动一律随该任务的 PR 进 main。
@@ -44,7 +64,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 ## 分支与提交
 
-- 命名：`feat/<issue-id>-<slug>`；无 Issue 时降级 `nao/<批次-slug>`；hotfix 用 `hotfix/<issue-id>`。
+- 命名：`fix/<issue-id>-<slug>`（缺陷修复）｜`feat/<issue-id>-<slug>`（新能力 / 行为变更）；无 Issue 时统一降级 `nao/<批次-slug>`；线上补丁用 `hotfix/<issue-id>`，且**从受影响版本 tag 切出**（tag 作为基线的唯一场景）。
 - **禁止** `git push` 到 main、**禁止绕过 PR 合并**；feature 分支允许 `--force-with-lease`（改基 / 压缩历史时）。
 - 提交规范、`wip()` 前缀、路径级暂存、可读性：见 @.agents/skills/commit.md。
 - **squash 后 main 上的提交信息 = PR 标题 + PR 正文** → **可读性硬性落在 PR 标题**（用户可见行为，禁纯编号/类名/路径）。
@@ -52,10 +72,12 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 ## Issue 与状态（避免双源）
 
-- **Issue = 入口 / 摘要 + 指针**：body 只放 TL;DR、AC 编号、优先级、`docs/prds/...md` 指针。
+- **一句判据（区分两侧，互不冲突）**：**输入侧 = 别人交来的报障原文，留平台（它是证据，不是规格）；输出侧 = PM 立项摘要，不抄正文（正文在 `docs/`）**。
+- **输入侧（外部 Issue / 线上转来）**：原始报告正文**留在平台**，不搬进仓库；PM 在阶段 0 triage 后**摘录成 `docs/tasks-state.md` 任务条目并以 Issue 号回链**；凡进入 `docs/prds/` 的规格正文仍**只写一处**（规格在 `docs/`，证据在平台）。原文里的**规格建议不算证据** —— 被采纳 ⇒ 写入 `docs/prds/`（规格唯一权威）并在 Issue 回帖指针、**原帖不改**；未采纳 ⇒ 只在 `tasks-state` 记一行决策。
+- **输出侧（PM 立项）**：**Issue = 入口 / 摘要 + 指针**：body 只放 TL;DR、AC 编号、优先级、`docs/prds/...md` 指针。
 - **`docs/` = 正文权威**（PRD 全文、`tasks-state.md` 运行时状态）：离线可用、会话重开读本地。
 - **同步时机（仅 5 个节点）**：立项、派发、验收通过、合并、发布——其余不动 Issue，省 gh 往返。
-- Issue 上的业务讨论由 PM **摘录进 `docs/`**，不留在平台。
+- Issue 上的业务讨论由 PM **摘录进 `docs/`**，不留在平台（**报障原文及其规格建议按输入侧处理，不在此列**）。
 
 ## PR 模板与 Reviewer
 
@@ -89,13 +111,17 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 降级须在 `tasks-state` 与回执中标注「降级」。
 
+- **降级用载体（无 PR 对象时）**：`fix` 通道的「书面理由」（>3 文件）与「复核 / 自审留痕」两个载体均默认落在 PR；降级模式（无远端 / 无 `gh`，无 PR 可写）⇒ 改为 **`docs/reports/<编号>-review.md`**（或 `docs/tasks-state.md` 该任务条目相邻行），内容不变（理由 + 日期 + 自审声明），「>3 文件须写书面理由」同落此处。
+
 ## 红线
 
 - [ ] 未过 PM 验收就合并 PR，或直推 main？
 - [ ] main 上出现多条本需求提交，或出现 `wip()` 提交（未 squash）？
 - [ ] 为文档 / 台账**单开 PR**，或任务期文档作为**独立提交直落 main**（立项摘要例外见 BR3）？
 - [ ] PM 亲自执行合并 / `push` main？
-- [ ] Issue 与 `docs/` 双源（正文抄进 Issue，或状态只留平台）？
+- [ ] Issue 与 `docs/` 双源（输入侧报障原文搬进 `docs/`，或输出侧把规格正文抄进 Issue）？
+- [ ] `fix` 通道夹带重构 / 格式化 / 无关文件，或未先写可失败用例？
+- [ ] 线上暴露的问题未记受影响版本 tag，或把部署 / 灰度 / 监控 / 回滚 / MTTR 揽进本机制？
 - [ ] 未过验收 / 门禁未绿就打 tag，或 tag 指向非 main 提交？
 - [ ] PR 标题 / release notes 不可读（纯编号 / 类名 / 路径）？
 - [ ] 降级未标注？

package/.agents/skills/nao-fleet/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: nao-fleet
-description: nao 多角色 AI 开发舰队的单一入口。当用户要在当前项目启用/运行 nao 工作流时加载——按角色拉起 6 个常驻会话（pm / arch-designer / rd-fe / rd-be / qa / rd-infra）、跑机制体检 check、迁移旧版安装。本 skill 只做入口与说明书：加载后按指引调用项目内 `.agents/scripts/nao-fleet.sh`（shim）；角色卡仍由 fleet 以 `--append-system-prompt` 常驻注入，不由 skill 承载。
+description: nao 多角色 AI 开发舰队的单一入口。当用户要在当前项目启用/运行 nao 工作流时加载——按角色拉起 7 个常驻会话（pm / arch-designer / uiux-designer / rd-fe / rd-be / qa / rd-infra）、跑机制体检 check、迁移旧版安装。本 skill 只做入口与说明书：加载后按指引调用项目内 `.agents/scripts/nao-fleet.sh`（shim）；角色卡仍由 fleet 以 `--append-system-prompt` 常驻注入，不由 skill 承载。
 ---
 
 # nao 舰队入口
 
-nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话（PM 拆需求/派活/验收，前端、后端、测试、架构、工程基座各自干活），用户只回答问题、点确认。
+nao 是一套「多角色 AI 开发舰队」：7 个分工明确的常驻会话（PM 拆需求/派活/验收，架构、UI/UX 设计、前端、后端、测试、工程基座各自干活），用户只回答问题、点确认。
 
 ## 何时加载
 
@@ -17,7 +17,7 @@ nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话
 
 机制全部在 **nao 机制包内**，项目内只有 shim。包根由环境锚点 `$NAO_SKILLS` 给出（fleet 注入到会话系统提示）：
 
-- 角色清单：`$NAO_SKILLS/.agents/roles.yaml`（6 角色，id 即 intercom 会话名）
+- 角色清单：`$NAO_SKILLS/.agents/roles.yaml`（7 角色，id 即 intercom 会话名）
 - 角色卡：`$NAO_SKILLS/.agents/prompts/<card>.md`
 - 按需技能：`$NAO_SKILLS/.agents/skills/*.md`
 - 交付清单：`$NAO_SKILLS/.agents/checklists/<role>.md`
@@ -28,7 +28,7 @@ nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话
 ## 怎么用
 
 1. **体检**：`bash .agents/scripts/nao-fleet.sh check`（exit=0 即可开工；非 0 看报告）。
-2. **拉起舰队**：`bash .agents/scripts/nao-fleet.sh ensure pm arch-designer rd-fe rd-be qa rd-infra`
+2. **拉起舰队**：`bash .agents/scripts/nao-fleet.sh ensure pm arch-designer uiux-designer rd-fe rd-be qa rd-infra`
    - 任务派生（并行隔离）：`ensure --task <编号> <别名>`
    - 状态 / 回收：`status` / `close --task <编号> <别名>`
    - 实验场清理：`cleanup -S <隔离socket>`（强制显式 socket；无 `-S`/指向默认 socket ⇒ exit 2 拒绝）
@@ -38,7 +38,7 @@ nao 是一套「多角色 AI 开发舰队」：6 个分工明确的常驻会话
 
 ## 硬约束（勿违反）
 
-- **BR1**：角色仍是 6 个独立会话；本 skill 不合并角色。
+- **BR1**：角色仍是 7 个独立会话；本 skill 不合并角色。
 - **BR2**：角色卡必须继续由 fleet `--append-system-prompt` 常驻注入；**不得**改用 skill / prompt 按需加载。
 - 项目根 `AGENTS.md` 是项目级单一事实来源（PM 维护，pi 自动注入），本 skill 不复制其内容。
 - 机制自身零网络；shim 只用 node resolve 定位包，不调用 `pi`/`npm` 可执行文件。

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

@@ -1,5 +1,5 @@
 ---
-description: 按需技能——PM 运行手册（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 交付归档）
+description: 按需技能——PM 运行手册（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 交付归档 / 机制包版本自检）
 ---
 
 # PM 运行手册
@@ -91,3 +91,34 @@ PM 是舰队唯一常驻长寿会话：上下文过长时丢的是**纪律**（
 - 内容：背景(5 Whys 摘要) → 目标指标与埋点 → 9 模块要点 → 决策留痕(RICE/取舍/回滚) → 参考来源(`docs/research/` 路径) → 派发记录（含需求分支、PR 编号、main 合并 commit hash） → 验收结果 → 变更记录 → 遗留项。
 - 首次归档创建 `docs/prds/README.md` 索引（日期 | 主题 | 交付 | 终签状态）。
 - 归档同时：更新 `docs/tasks-state.md` 接续快照；「派发记录」末行记**会话体检**（`contextTokens / 压缩次数 / cacheRead 占比`，取自 `/session`）；随后按本文件 §三「PM 会话生命周期」重开 PM 会话（归档 = 批次终态）。
+
+## 六、机制包版本自检（`ensure pm` 注入，仅提示不自动升级）
+
+> 契约来源：`docs/prds/2026-11-03-ensure-pm-update-check.md`（R1–R6）；关闭开关 `NAO_UPDATE_ON_ENSURE=0`。
+> 机制侧实现：`.agents/scripts/nao-fleet.sh` 的 `NAO_UPDATE_MSG` 常量（字符串常量，`grep -n '^NAO_UPDATE_MSG='` 可定位）。
+
+**触发**：目标解析为 `pm` 时，fleet 在 `--append-system-prompt <卡>` **之后**以 `--` 分隔追加一条固定首条用户消息；fleet 进程内**不执行任何** `npm`/`gh`/`curl`（零网络），检查由本会话自己做。非 `pm` 目标与开关关闭时命令行逐字不变。
+
+**检查顺序（只读）**
+
+1. 本地 pin：读 `.pi/settings.json` 里 `@nathan33/nao-skill` 的版本 X；无该文件/无该 pin ⇒ 走输出 ④。
+2. 远端：`npm view @nathan33/nao-skill version --fetch-timeout=5000`（内置 5s 超时；**不要**用外部 `timeout` 命令——macOS 原生无该命令，rc=127 会被误判成「离线或超时」）；超时/报错 ⇒ 走输出 ③。
+3. 仅当 Y > X 才取要点：`gh release view v<Y>`，**压成不超过两句**；无 `gh` 或取不到 ⇒ 走输出 ⑤。
+
+**输出（恰好一行，按序命中即止）**
+
+- ① 有新版：`当前 X → 可升 Y（要点）。要升吗？`
+- ② 已最新：`版本检查：已是最新 X。`
+- ③ 离线或超时：`版本检查：离线或超时，跳过（可稍后手动 npx @nathan33/nao-skill --version 核对）。`
+- ④ 未检测到下游 pin：`版本检查：未检测到下游 pin（本仓为机制源），跳过。`
+- ⑤ 无 `gh`：`版本检查：当前 X → 可升 Y（要点取不到，见 https://github.com/Nathan3303/nao-skills/releases）。要升吗？`
+
+**零改动保证**：检查阶段只读（`.pi/settings.json` 只读、`npm view` / `gh release view` 均为查询）；**「未获我同意前不要改任何文件、不要升级」**（逐字引自注入常量；不改 pin、不跑 `pi install` / `pi update`）。
+
+**用户同意后的动作序列**（升级属不可逆动作，按 ask-me 口径确认后再执行）
+
+1. `pi install -l npm:@nathan33/nao-skill@<Y>`（更新项目 `.pi/settings.json` 的 pin；**若提示安装脚本授权 ⇒ 停下来交给用户确认，不自行放行**）；
+2. `pi update --extensions`；
+3. 提醒用户「本轮会话仍是旧角色卡，建议重开」（`ensure --force pm`）。
+
+用户未表态或说「稍后」⇒ 原样待命，不重试、不轮询、不后台检查（无定时任务）。噪声可接受度见 PRD §八 观察项（若用户抱怨，改为 24h 节流，需另立需求）。

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

@@ -12,6 +12,7 @@ description: 按需技能——PM 路由与派单纪律（角色路由口诀 /
 > **改「业务行为」⇒ `rd-fe`/`rd-be`；改「怎么构建 / 怎么验 / 怎么发 / 怎么治理」⇒ `rd-infra`。**
 
 - **工程基座类 ⇒ `rd-infra`，不再由 `rd-be` 兜底**：CI 与流水线 · 构建/发布工具 · 脚本与守卫（`guard:*`、fleet 脚本） · 依赖与安全告警升级 · 仓库治理（分支/保护/清理/baseline 合并执行） · lint 与格式化工具链 · 跨项目安装器与分发 · 开发环境排障。
+- **UI/UX 设计类 ⇒ `uiux-designer`**：信息架构 · 交互流程 · 视觉规范与 token · 状态与断点 · 可用性/无障碍 · 设计一致性结论；触发条件见 @.agents/prompts/uiux-designer.md §一（BR1）。**不改源码**，实现层视觉风格仍由 `rd-fe` 的 `frontend-design` 技能管。
 - **兜底纪律（无匹配角色时）**：**显式声明 + 选最接近专精角色 + 临时附加清单 + 台账登记**——**不许默默兜底**。
 - 三条例外（避免口诀被滥用）：① 架构取舍（选型/分层/契约）先经 `arch-designer`，`rd-infra` 只落地已定方案；② 验收口径与断言归属 `qa`/`pm`，`rd-infra` **不自验自己的守卫**；③ 工程基座改动**触碰业务语义**时拆单，业务部分回 `rd-fe`/`rd-be`。
 
@@ -27,5 +28,5 @@ description: 按需技能——PM 路由与派单纪律（角色路由口诀 /
   4. 影响面跨 **>1 个包或 >1 个端**；
   5. 涉及性能量级、限流、契约字段语义、枚举/排序语义；
   6. 任何以外部文章/竞品做法为依据的**技术结论**（该用哪个方案/库/中间件）。
-- **转发对象**：技术选型与影响面 → `arch-designer`；验收策略与用例 → `qa`；实现细节 → `rd-fe` / `rd-be`；**工程基座（CI/构建/发布/脚本守卫/依赖安全/仓库治理）→ `rd-infra`**。
+- **转发对象**：技术选型与影响面 → `arch-designer`；验收策略与用例 → `qa`；实现细节 → `rd-fe` / `rd-be`；**UI/UX 设计（信息架构/交互/视觉规范/可用性）→ `uiux-designer`**；**工程基座（CI/构建/发布/脚本守卫/依赖安全/仓库治理）→ `rd-infra`**。
 - **判定口径**：不确定是否越界时**按越界处理**（转角色），不以「省一轮」为由自行下结论。

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

@@ -0,0 +1,54 @@
+---
+description: 按需技能——UI/UX 设计报告骨架、降级阶梯细则、可用性与无障碍基线、反 AI 味清单（设计类需求开工前/交付前读取）
+---
+
+# UI/UX 设计技能
+
+> 触发：设计类需求（BR1）开工前与交付前读取；非设计类需求不加载。
+> 报告骨架与禁写清单单源在 @.agents/checklists/deliverable-docs.md §九，本技能只给**逐项要点与判据**。
+
+## 一、设计报告骨架（9 项，缺项写「不适用 + 一行理由」）
+
+1. **信息架构** —— 页面/区块层级（≤3 层）、每层的用户目标一句话；导航与入口位置。
+2. **流程** —— 主路径 + 异常路径（失败/空/无权限），每步给触发点与系统反馈；用编号步骤，不画流程图依赖。
+3. **视觉规范** —— 层级（标题/正文/辅助）、间距节奏（4 或 8 的倍数）、圆角/描边/阴影档位；每项给数值，不给「大概/略微」。
+4. **token** —— 颜色（语义名 → 亮/暗两值）、字阶、间距、圆角、层级 z-index；命名用语义（`surface-raised`），不用色相（`gray-200`）。
+5. **状态** —— 空 / 加载 / 部分成功 / 错误 / 无权限 / 极值（超长、0 条、1 万条）；每态给可见信息与可执行动作。
+6. **断点** —— ≥3 档（窄 / 中 / 宽），每档给布局变化与首个被折叠的内容；窄档优先级 = 主任务可完成。
+7. **可用性** —— 关键路径点击数、防误操作（二次确认 / 撤销）、反馈时限（≤100ms 响应、≤1s 骨架屏、>1s 进度）。
+8. **无障碍** —— 对比度（正文 ≥4.5:1、大字 ≥3:1）、键盘可达（焦点顺序 + 可见 focus）、语义与标签、命中区 ≥44×44、动效可关。
+9. **降级产物** —— 本次实际交付的档位与内容（§二），无原型工具时**必填**。
+
+- 报告 ≤80 行；`docs/designs/<编号>-<slug>.md`；每项结论能对到 **AC 编号**。
+- 上线后设计稿与实现漂移的处置：设计产物问题回本角色改报告，实现偏差回 `rd-fe`/`rd-be`；不互相顶替。
+
+## 二、降级阶梯（BR4，按序取一，交付即成立）
+
+- **① 结构化文字规格**（默认）—— 按 §一 1/3/4/5/6 全量给数值与判定条件，可直接照着实现。
+- **② ASCII 线框** —— 单屏 ≤40 列 × ≤20 行，等宽字体可读；区块标 `[A]`、热点标 `①`，图下 3 行内说明热点行为。
+- **③ 分步作图指令** —— 画板尺寸（如 1440×900）、图层命名（`section/name`）、组件与变量命名（token 同名），每步一行、可照做复现。
+- **选择判据**：有原型工具就至少产出 ①+③；无工具时 ① 已成立，②/③ 视复杂度补足即可**停**，不追求完美。
+- **回执措辞**：写「交付档位 ①（无 MCP/实例，按 BR4 降级）」——**不得**写成「因缺工具阻塞」。
+
+## 三、Penpot 操作口径（本期未接入 · T540）
+
+- 现状：客户端未接入 MCP；本技能**只给占位口径**，不写实例 URL / token / 凭证（严禁从本机配置抄入仓）。
+- 接入后的最小口径：报告里留 **帧链接 + 要点摘录（≤5 行）**，断链仍可追溯；凭证走本机配置，不入仓、不入报告。
+- 断链/离线时必须回落 §二 降级阶梯，**不阻塞交付**；工具接入不改变闸门（BR2 / BR2a）。
+
+## 四、可用性与无障碍基线（默认值，可被项目基线覆盖）
+
+- 主任务在**主路径 ≤3 次点击**内完成；破坏性操作必须有二次确认或撤销。
+- 对比度：正文 ≥4.5:1、大字/图标 ≥3:1；**不用颜色单独承载语义**（配图标或文字）。
+- 键盘：全部可交互元素可 Tab 达、focus 可见、顺序符合阅读；弹层焦点陷阱 + Esc 关闭。
+- 命中区 ≥44×44；表单错误就近提示 + 明确下一步；空态给「为什么空 + 怎么开始」。
+- 动效可用「减少动效」关闭；不做 >400ms 的阻塞式过渡。
+
+## 五、反 AI 味清单（出现即改）
+
+- 满屏渐变 + 玻璃拟态 + 超大圆角 + 紫色发光，任意产品可套 ⇒ 换成有理由的中性底 + 一处强调色。
+- 标题用 emoji 当图标、正文用「🚀 一站式赋能」式空话 ⇒ 换成具体对象与动作。
+- 每个区块都是等宽卡片瀑布 ⇒ 按任务优先级给主次，允许主区块更大、留白更多。
+- 占位插画/假头像/假数据撑场面 ⇒ 空态给真实引导，不做装饰性填充。
+- 字阶只差 1–2px 的「差不多」层级 ⇒ 层级差距拉大到肉眼可辨（建议 ≥1.25 倍）。
+- 深色模式「反色了事」⇒ 单独定 token（降低饱和、提高层级亮度差）。

package/.agents/templates/github/issue_template_bug.md.example

@@ -0,0 +1,36 @@
+<!-- 由 PM 复制为项目 .github/ISSUE_TEMPLATE/bug_report.md（安装路径 .github/ISSUE_TEMPLATE/，见 @.agents/skills/github-flow.md） -->
+<!-- 用途：报障输入侧模板。填写要求：现象 + 期望 vs 实际 + 复现三件事能写全 ⇒ 可走 fix 轻通道；写不全 ⇒ PM triage 挂起回问，不猜 -->
+## 现象
+
+<!-- 一句话：哪里坏了、用户看到什么。写不满一行说明还缺复现信息 -->
+
+## 期望 vs 实际
+
+- 期望：
+- 实际：
+
+## 复现步骤
+
+1. <前置条件 / 版本>
+2. <操作>
+3. <观察到的结果>
+
+- 复现率：每次 / 偶发（约 n 次出现 1 次）
+- 最小复现（可选，能精简到 3 步以内最好）：
+
+## 影响版本
+
+- 受影响版本 / tag：
+- 是否影响已发布版本：是 / 否
+
+## 来源
+
+<!-- 来源=用户 / QA / 线上 / 自查（四选一；线上请附观测方式：截图、日志片段、通知） -->
+
+- 来源：
+- 关联链接（可选）：
+
+## 环境
+
+- 平台 / 宿主版本（如 pi 版本、tmux、OS）：
+- 其他（可选：数据规模、网络、配置差异）：

package/.agents/templates/github/issue_template_feature.md.example

@@ -0,0 +1,23 @@
+<!-- 由 PM 复制为项目 .github/ISSUE_TEMPLATE/feature_request.md（安装路径 .github/ISSUE_TEMPLATE/，见 @.agents/skills/github-flow.md） -->
+<!-- 用途：需求输入侧模板。写不出「期望 vs 实际」的对比 ⇒ 走 feat 通道（分流判据唯一出处 @.agents/skills/github-flow.md「通道分流判据」）；若是「本该如此却坏了」请改用 bug 模板 -->
+## 场景
+
+<!-- 谁、在什么情况下、为了什么要做这件事：一句话画像 + 触发条件 -->
+
+- 谁：
+- 什么情况下：
+- 现在怎么办（临时绕法 / 成本）：
+
+## 期望
+
+<!-- 写成「用户能做成什么」，不要写实现方案；有边界（不做什么）一并写 -->
+
+- 期望结果：
+- 明确不做：
+
+## 价值
+
+<!-- 不做会怎样 / 做了能省什么（时间、次数、出错率）；能量化就量化 -->
+
+- 价值：
+- 优先级线索（可选：影响人数 / 频率 / 阻塞程度）：

package/.agents/templates/pi-subagents/intercom-bridge.md

@@ -9,7 +9,7 @@
 
 ## 二、身份与消息禁令（硬性）
 
-- 不得以舰队角色名义回执：不得以任一舰队角色（`pm` / `arch-designer` / `rd-fe` / `rd-be` / `qa` / `rd-infra`）的名义说话或回执。
+- 不得以舰队角色名义回执：不得以任一舰队角色（`pm` / `arch-designer` / `uiux-designer` / `rd-fe` / `rd-be` / `qa` / `rd-infra`）的名义说话或回执。
 - 不得发送 `done` 形态的消息；不得直接向 PM 发送任何消息。
 - 需要决策、被阻塞、需要授权或确认范围：用 `contact_supervisor({ reason: "need_decision", message: "<问题>" })` 回父角色；有实质进展或计划变更：用 `contact_supervisor({ reason: "progress_update", message: "UPDATE: <摘要>" })`。
 - `contact_supervisor` 是进程内 native 通道（不依赖 pi-intercom），它会自动解析父会话目标，因此本指令不需要、也不会写死父会话名。