@nathan33/nao-skill 0.7.1 → 0.9.3

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

@@ -3,7 +3,7 @@
 # nao-fleet.sh — 按角色一键拉起 pi 会话窗口（nao 团队工具箱）
 #
 # 用法
-#   nao-fleet.sh check [--strict] [-v]            静态体检：roles.yaml/缩进/EOL/角色卡/交叉引用/PR 模板/白名单/布局
+#   nao-fleet.sh check [--strict] [-v]            静态体检：roles.yaml/缩进/EOL/角色卡/交叉引用/PR 模板/qq-notify/白名单/布局
 #                                                 默认单行摘要（含 warn 计数）；-v 展开完整报告；失败始终展开
 #   nao-fleet.sh status                           角色会话在线状态（按终端标题/名册判定；权威名单见 intercom list）
 #   nao-fleet.sh ensure <别名>[@<repo>] [更多...]  拉起角色窗口（默认工作区=roles.yaml workspace）
@@ -14,12 +14,13 @@
 #                                                 回收已完成会话（闸门：在跑 turn / tasks-state 未推进 → 拒绝，--force 跳过）
 #
 # 角色别名 → 角色卡：见 .agents/roles.yaml（单一事实来源）
-#   当前：pm / arch-designer(arch) / rd-fe / rd-be / qa
+#   当前：pm / arch-designer(arch) / rd-fe / rd-be / qa / rd-infra(infra)
 #
 # 环境变量
 #   NAO_TERMINAL=ghostty|ptyxis|tmux|screen   强制宿主
-#   NAO_TMUX_LAYOUT=main-row2|grid            tmux 布局（默认 main-row2）
-#   NAO_TMUX_MAIN_WIDTH=<10..90>              main-row2 主 pane 宽度百分比（默认 35）
+#   NAO_TMUX_LAYOUT=main-row2|main-col|grid   tmux 布局（默认 main-row2）
+#   NAO_TMUX_MAIN_WIDTH=<10..90>             主 pane 宽度百分比（默认 35；main-row2/main-col 共用）
+#   NAO_TMUX_MIN_PANE_WIDTH=<10..80>         最小非主 pane 列宽守卫（默认 30；低于则回退）
 #   NAO_SKILLS=<dir>                          角色卡根目录（默认 <脚本>/../..）
 #   NAO_MODEL_WHITELIST=<glob,...>            -m 白名单（默认空=不校验，支持 glob）
 #   NAO_CLOSE_BUSY_PATTERN=<ERE>             close 的在跑 turn 判定正则（默认内置 pi 状态行标记）
@@ -35,10 +36,16 @@
 # tmux 宿主行为
 #   - 已在 tmux 内（$TMUX 存在）：当前窗口分屏拉起，不新建窗口。
 #   - 不在 tmux 内：创建 detached 会话 nao-<角色>，需 tmux attach -t nao-<角色>。
-#   - main-row2：第 1 个 pane 全高占左，后续每角色往右开列、每列上下 2 个：
+#   - main-row2：第 1 个 pane 全高占左，后续每角色往右开列、每列上下 2 个（默认）：
 #                 1 | 2 | 4
 #                 1 | 3 | 5
-#   - grid：所有 pane 等大网格（tmux 内建 tiled）。
+#   - main-col：第 1 个 pane 全高占左，其余 pane 在右列纵向堆叠（委托内建 main-vertical）：
+#                 1 | 2
+#                 1 | 3
+#                 1 | 4
+#   - grid：所有 pane 等大网格（tmux 内建 tiled），宽度最优。
+#   - 窄列守卫：main-row2 的最窄非主 pane < NAO_TMUX_MIN_PANE_WIDTH ⇒ 回退 main-col；
+#              回退后右列仍不足 ⇒ 再回退 grid（带 warn，不中断 ensure）。
 # =============================================================================
 set -euo pipefail
 
@@ -57,6 +64,9 @@ TMUX_LAYOUT="${NAO_TMUX_LAYOUT:-main-row2}"
 # main-row2 主 pane 宽度百分比：默认值与非法值回退共用同一常量（防三处漂移）
 TMUX_MAIN_WIDTH_DEFAULT=35
 TMUX_MAIN_WIDTH="${NAO_TMUX_MAIN_WIDTH:-$TMUX_MAIN_WIDTH_DEFAULT}"
+# 最小非主 pane 列宽守卫：默认值与非法值回退共用同一常量（防漂移）
+TMUX_MIN_PANE_WIDTH_DEFAULT=30
+TMUX_MIN_PANE_WIDTH="${NAO_TMUX_MIN_PANE_WIDTH:-$TMUX_MIN_PANE_WIDTH_DEFAULT}"
 # check 输出契约：默认单行摘要（省 PM 上下文），-v 展开完整报告；失败始终展开
 VERBOSE=false
 # close 的在跑 turn 判定（pi 默认状态行：Working (esc to interrupt) / Thinking... / Retrying / Compacting）
@@ -192,6 +202,50 @@ check_roles_indent() {
   ' "$MANIFEST"
 }
 
+# qq-notify 主动推送器契约：存在 + 可执行 + EOL 全 LF + 无 Tab + node --check 语法
+check_qq_notify() {
+  local rc=0 f="$SKILLS_DIR/.agents/scripts/qq-notify"
+  if [[ ! -f "$f" ]]; then
+    printf '  ✗ 缺失: .agents/scripts/qq-notify\n'
+    return 1
+  fi
+  printf '  ✓ 存在: .agents/scripts/qq-notify\n'
+  if [[ -x "$f" ]]; then
+    printf '  ✓ 可执行位已设置\n'
+  else
+    printf '  ✗ 缺少可执行位（修复：chmod +x .agents/scripts/qq-notify）\n'; rc=1
+  fi
+  if grep -Iq $'\r' "$f"; then
+    printf '  ✗ 含 CR（须转 LF；CRLF 会破坏 shebang/管道）\n'; rc=1
+  else
+    printf '  ✓ 行尾 LF\n'
+  fi
+  if grep -Iq $'\t' "$f"; then
+    printf '  ✗ 含 Tab（禁止 Tab 缩进）\n'; rc=1
+  else
+    printf '  ✓ 无 Tab\n'
+  fi
+  # shell 转交守卫：禁止 `bash/sh <本脚本>` 逐行解释注释（防误执行示例/误发）
+  local l1 l2
+  l1="$(head -n 1 "$f")"
+  l2="$(sed -n '2p' "$f")"
+  if [[ "$l1" == '#!/bin/sh' ]] && [[ "$l2" == *'exec node "$0" "$@"'* ]]; then
+    printf '  ✓ shell 转交守卫（#!/bin/sh + exec node）\n'
+  else
+    printf '  ✗ 缺少 shell 转交守卫（第 1 行须 #!/bin/sh、第 2 行须含 exec node "$0" "$@"）\n'; rc=1
+  fi
+  if command -v node >/dev/null 2>&1; then
+    if node --check "$f" >/dev/null 2>&1; then
+      printf '  ✓ node --check 语法通过\n'
+    else
+      printf '  ✗ node --check 语法失败\n'; rc=1
+    fi
+  else
+    printf '  ! node 未安装（跳过语法校验）\n'
+  fi
+  return $rc
+}
+
 # CodeGraph 索引健康（ensure 拉起前 / check 用；缺失或过期仅 warn，不阻塞）
 check_codegraph() {
   local repo="$1" name st
@@ -422,22 +476,11 @@ _layout_checksum() {
   printf '%04x' "$c"
 }
 
-# main-row2：主 pane 全高占左；往右每列 2 个上下堆叠
-#   1 | 2 | 4
-#   1 | 3 | 5
-# tmux 规范：相邻子 pane 之间 1 格 gap；{} 左右排列，[] 上下排列
-build_main_row2_layout() {
-  local win_w="$1" win_h="$2" pct="$3"
-  shift 3
-  local -a panes=("$@")
-  local n=${#panes[@]}
-  (( n >= 1 )) || return 1
-  if (( n == 1 )); then
-    printf '%sx%s,0,0,%s' "$win_w" "$win_h" "${panes[0]}"
-    return 0
-  fi
-
-  # 根：水平分割，主 pane + 右侧容器，中间 1 gap
+# main-row2 / main-col 共用几何（单一源头，防守卫与构建两处漂移）
+# 输入：窗口宽 win_w · pane 数 n · 主宽百分比 pct
+# 输出（空格分隔）：main_w right_w right_x cols cw_base cw_last
+main_row2_geom() {
+  local win_w="$1" n="$2" pct="$3"
   local usable_w=$(( win_w - 1 ))
   (( usable_w < 2 )) && usable_w=2
   local main_w=$(( usable_w * pct / 100 ))
@@ -446,9 +489,8 @@ build_main_row2_layout() {
   local right_w=$(( usable_w - main_w ))
   (( right_w < 1 )) && right_w=1
   local right_x=$(( main_w + 1 ))
-
-  # 右侧 cols 列
   local m=$(( n - 1 ))
+  (( m < 1 )) && m=1
   local cols=$(( (m + 1) / 2 ))
   (( cols < 1 )) && cols=1
   local r_usable=$(( right_w - (cols - 1) ))
@@ -457,6 +499,43 @@ build_main_row2_layout() {
   (( cw_base < 1 )) && cw_base=1
   local cw_last=$(( r_usable - cw_base * (cols - 1) ))
   (( cw_last < 1 )) && cw_last=1
+  printf '%s %s %s %s %s %s' "$main_w" "$right_w" "$right_x" "$cols" "$cw_base" "$cw_last"
+}
+
+# main-row2 最窄非主 pane 列宽（窄列守卫用；与 build 共用 main_row2_geom）
+main_row2_min_col() {
+  local win_w="$1" n="$2" pct="$3"
+  (( n >= 2 )) || { printf '%s' "$win_w"; return 0; }
+  local main_w right_w right_x cols cw_base cw_last
+  read -r main_w right_w right_x cols cw_base cw_last < <(main_row2_geom "$win_w" "$n" "$pct")
+  if (( cw_base < cw_last )); then printf '%s' "$cw_base"; else printf '%s' "$cw_last"; fi
+}
+
+# main-col 右列宽（tmux main-vertical 百分比语义；与 main_row2_geom 的 right_w 同源）
+main_col_right_w() {
+  local main_w right_w right_x cols cw_base cw_last
+  read -r main_w right_w right_x cols cw_base cw_last < <(main_row2_geom "$1" 2 "$2")
+  printf '%s' "$right_w"
+}
+
+# main-row2：主 pane 全高占左；往右每列 2 个上下堆叠
+#   1 | 2 | 4
+#   1 | 3 | 5
+# tmux 规范：相邻子 pane 之间 1 格 gap；{} 左右排列，[] 上下排列
+build_main_row2_layout() {
+  local win_w="$1" win_h="$2" pct="$3"
+  shift 3
+  local -a panes=("$@")
+  local n=${#panes[@]}
+  (( n >= 1 )) || return 1
+  if (( n == 1 )); then
+    printf '%sx%s,0,0,%s' "$win_w" "$win_h" "${panes[0]}"
+    return 0
+  fi
+
+  # 几何统一来自 main_row2_geom（守卫与构建同源，防漂移）
+  local main_w right_w right_x cols cw_base cw_last
+  read -r main_w right_w right_x cols cw_base cw_last < <(main_row2_geom "$win_w" "$n" "$pct")
 
   # 每列内部：上下 2 个，中间 1 gap
   local v_usable=$(( win_h - 1 ))
@@ -496,6 +575,31 @@ build_main_row2_layout() {
     "$right_body"
 }
 
+# main-col：委托 tmux 内建 main-vertical（主 pane 左全高 + 右列纵向堆叠）
+#   坑：tmux 默认 main-pane-width=80（格）⇒ 必须显式设百分比
+apply_main_col() {
+  local pct="$1" n="$2" min_w="$3" win_w="$4" from="$5"
+  if (( n >= 2 )); then
+    local right_w; right_w="$(main_col_right_w "$win_w" "$pct")"
+    if (( right_w < min_w )); then
+      if [[ "$from" == "main-col" ]]; then
+        warn "main-col 右列 ${right_w} < 最小 ${min_w}（${n} pane @ ${win_w} 列）→ 回退 grid"
+      else
+        warn "${from} → main-col 右列 ${right_w} < 最小 ${min_w}（${n} pane @ ${win_w} 列）→ 再回退 grid"
+      fi
+      tmux select-layout tiled >/dev/null 2>&1 || true
+      return 0
+    fi
+  fi
+  tmux set-window-option main-pane-width "${pct}%" >/dev/null 2>&1 || true
+  local err
+  if ! err=$(tmux select-layout main-vertical 2>&1); then
+    warn "main-col（main-vertical）应用失败，回退 grid"
+    warn "  tmux:   ${err:-<no message>}"
+    tmux select-layout tiled >/dev/null 2>&1 || true
+  fi
+}
+
 apply_tmux_layout() {
   [[ -n "${TMUX:-}" ]] || return 0
   if [[ "$TMUX_LAYOUT" == "grid" ]]; then
@@ -512,13 +616,32 @@ apply_tmux_layout() {
   while IFS= read -r line; do
     [[ -n "$line" ]] && pane_ids+=("$line")
   done < <(tmux list-panes -F '#{pane_id}' 2>/dev/null | sed 's/^%//')
-  (( ${#pane_ids[@]} >= 1 )) || return 0
+  local n=${#pane_ids[@]}
+  (( n >= 1 )) || return 0
 
   local pct="$TMUX_MAIN_WIDTH"
   [[ "$pct" =~ ^[0-9]+$ ]] || pct="$TMUX_MAIN_WIDTH_DEFAULT"
   (( pct < 10 )) && pct=10
   (( pct > 90 )) && pct=90
 
+  local min_w="$TMUX_MIN_PANE_WIDTH"
+  [[ "$min_w" =~ ^[0-9]+$ ]] || min_w="$TMUX_MIN_PANE_WIDTH_DEFAULT"
+  (( min_w < 10 )) && min_w=10
+  (( min_w > 80 )) && min_w=80
+
+  if [[ "$TMUX_LAYOUT" == "main-col" ]]; then
+    apply_main_col "$pct" "$n" "$min_w" "$win_w" "main-col"
+    return
+  fi
+
+  # 窄列守卫：main-row2 最窄非主 pane < 阈值 ⇒ 回退 main-col（再不足⇒grid）
+  local narrow; narrow="$(main_row2_min_col "$win_w" "$n" "$pct")"
+  if (( narrow < min_w )); then
+    warn "${n} pane @ ${win_w} 列：main-row2 最窄列 ${narrow} < 最小 ${min_w} → 回退 main-col"
+    apply_main_col "$pct" "$n" "$min_w" "$win_w" "main-row2"
+    return
+  fi
+
   local full; full="$(build_main_row2_layout "$win_w" "$win_h" "$pct" "${pane_ids[@]}")"
   [[ -n "$full" ]] || return 0
 
@@ -535,12 +658,19 @@ apply_tmux_layout() {
 spawn_tmux() {
   local name="$1" inner="$2"
   case "$TMUX_LAYOUT" in
-    main-row2|grid) ;;
-    *) die "NAO_TMUX_LAYOUT 无效: $TMUX_LAYOUT（可选 main-row2|grid）" ;;
+    main-row2|main-col|grid) ;;
+    *) die "NAO_TMUX_LAYOUT 无效: $TMUX_LAYOUT（可选 main-row2|main-col|grid）" ;;
   esac
   local wrapped="bash -lc $(printf %q "$inner")"
   if [[ -n "${TMUX:-}" ]]; then
-    tmux split-window -h "$wrapped" >/dev/null
+    # 窄窗口/宿主上限会让 split-window 失败（no space for new pane）；
+    # 捕获后 warn 并继续，不因单个 pane 失败中断整轮 ensure。
+    local serr
+    if ! serr=$(tmux split-window -h "$wrapped" 2>&1); then
+      warn "pane 创建失败（窗口过窄或宿主已达上限）：${serr:-<no message>}"
+      warn "  已跳过该 pane，其余角色继续拉起；可放大窗口后重跑 ensure"
+      return 0
+    fi
     apply_tmux_layout
   else
     tmux new-session -d -s "nao-$name" "$wrapped"
@@ -606,6 +736,9 @@ cmd_check() {
   fi
   check_eol || rc=1
 
+  echo "== 主动推送器（qq-notify，可选能力）=="
+  check_qq_notify || rc=1
+
   echo "== 角色清单 roles.yaml =="
   load_manifest
   printf '  ✓ 解析成功，%d 个角色: %s\n' "${#ROLE_ORDER[@]}" "${ROLE_ORDER[*]}"
@@ -760,18 +893,23 @@ cmd_check() {
     echo "  （当前不在 tmux 内；若宿主命中 tmux 会创建 detached 会话）"
   fi
   case "$TMUX_LAYOUT" in
-    main-row2|grid)
+    main-row2|main-col|grid)
       printf '  ✓ NAO_TMUX_LAYOUT=%-10s 合法\n' "$TMUX_LAYOUT" ;;
     *)
-      printf '  ✗ NAO_TMUX_LAYOUT=%-10s 非法（可选 main-row2|grid）\n' "$TMUX_LAYOUT"; rc=1 ;;
+      printf '  ✗ NAO_TMUX_LAYOUT=%-10s 非法（可选 main-row2|main-col|grid）\n' "$TMUX_LAYOUT"; rc=1 ;;
   esac
-  if [[ "$TMUX_LAYOUT" == "main-row2" ]]; then
+  if [[ "$TMUX_LAYOUT" == "main-row2" || "$TMUX_LAYOUT" == "main-col" ]]; then
     if [[ "$TMUX_MAIN_WIDTH" =~ ^[0-9]+$ ]] && (( TMUX_MAIN_WIDTH >= 10 && TMUX_MAIN_WIDTH <= 90 )); then
       printf '  ✓ NAO_TMUX_MAIN_WIDTH=%-3s%% 合法\n' "$TMUX_MAIN_WIDTH"
     else
       printf '  ! NAO_TMUX_MAIN_WIDTH=%-3s  非法（10..90）：越界夹取到 10/90，非数字回退 %s\n' "$TMUX_MAIN_WIDTH" "$TMUX_MAIN_WIDTH_DEFAULT"
     fi
   fi
+  if [[ "$TMUX_MIN_PANE_WIDTH" =~ ^[0-9]+$ ]] && (( TMUX_MIN_PANE_WIDTH >= 10 && TMUX_MIN_PANE_WIDTH <= 80 )); then
+    printf '  ✓ NAO_TMUX_MIN_PANE_WIDTH=%-3s 合法\n' "$TMUX_MIN_PANE_WIDTH"
+  else
+    printf '  ! NAO_TMUX_MIN_PANE_WIDTH=%-3s 非法（10..80）：越界夹取到 10/80，非数字回退 %s\n' "$TMUX_MIN_PANE_WIDTH" "$TMUX_MIN_PANE_WIDTH_DEFAULT"
+  fi
 
   if [[ "$strict" == "true" && $wl_problems -gt 0 ]]; then
     warn "strict 模式：白名单发现 $wl_problems 项问题（空条目/重复/过宽）"
@@ -793,7 +931,7 @@ cmd_status() {
       printf '  · %-14s 未运行（ensure 拉起）\n' "$a"
     fi
   done
-  echo "== 任务派生会话（--task 拉起，如 rd-be-T1）=="
+  echo "== 任务派生会话（--task 拉起，如 rd-be-T1 / rd-infra-T1）=="
   local found=0 dname role id cls tag
   while IFS= read -r dname; do
     [[ -n "$dname" ]] || continue
@@ -819,7 +957,7 @@ cmd_status() {
 # 回收已完成会话：闸门（tasks-state 已推进 + 无在跑 turn）+ 落地（pane/会话/screen/进程）
 cmd_close() {
   local force="$1" task="$2" target="$3"
-  [[ -n "$target" ]] || die "close 需要目标：角色别名或派生会话名（如 rd-be / rd-be-T1）"
+  [[ -n "$target" ]] || die "close 需要目标：角色别名或派生会话名（如 rd-be / rd-be-T1 或 rd-infra / rd-infra-T1）"
   local name repo cls bus pane pids r ok
   intercom_list_json >/dev/null 2>&1 || true   # 预热名册缓存
   if [[ -n "$task" ]]; then
@@ -845,7 +983,7 @@ cmd_close() {
     # 非别名的目标必须是 <已知角色>-<编号>，否则视为拼错（防静默 no-op）
     ok=0
     for r in "${ROLE_ORDER[@]}"; do [[ "$name" == "$r-"* ]] && ok=1; done
-    (( ok )) || die "未知角色或派生会话名: $name（可用: ${ROLE_ORDER[*]}；派生名形如 rd-be-T1）"
+    (( ok )) || die "未知角色或派生会话名: $name（可用: ${ROLE_ORDER[*]}；派生名形如 rd-be-T1 / rd-infra-T1）"
     repo="$PWD"
   fi
 
@@ -862,7 +1000,13 @@ cmd_close() {
   # 闸门②：在跑 turn（tmux 可判；非 tmux 宿主无法判 → 需 --force）
   pane="$(find_pane_for "$name" "$repo")"
   if [[ -n "$pane" ]]; then
-    pane_busy "$pane" && bus="tmux pane $pane 末行显示在跑 turn"
+    # 显式双分支赋值：pane 空闲时 bus 必须落为 ""。
+    # 曾用 `pane_busy "$pane" && bus=…`：pane_busy 为假时 && 短路，bus 在 set -u 下未绑定 → 行 1007 崩溃。
+    if pane_busy "$pane"; then
+      bus="tmux pane $pane 末行显示在跑 turn"
+    else
+      bus=""
+    fi
   else
     bus="非 tmux 宿主，无法确认是否在跑 turn"
   fi
@@ -893,7 +1037,7 @@ cmd_ensure() {
   local force="$1" model="$2" task="$3"; shift 3
   local spec role repo key seen k
   local -a cg_done=()
-  [[ $# -eq 0 ]] && die "ensure 需要至少一个角色，如: nao-fleet.sh ensure arch rd-fe"
+  [[ $# -eq 0 ]] && die "ensure 需要至少一个角色，如: nao-fleet.sh ensure arch rd-fe rd-infra"
   for spec in "$@"; do
     if [[ "$spec" == *"@"* ]]; then
       role="${spec%%@*}"; repo="${spec#*@}"

package/.agents/scripts/qq-notify

@@ -0,0 +1,199 @@
+#!/bin/sh
+//bin/true; exec node "$0" "$@"
+//
+// qq-notify —— QQ 官方机器人「主动消息」推送器（舰队可选能力）
+//
+// 用法（三种形式等价：./qq-notify · node qq-notify · sh qq-notify）
+//   ./qq-notify "文本"                发给配置中的 ownerOpenId（默认收件人）
+//   ./qq-notify --to OPENID "文本"    发给指定 openid
+//   ./qq-notify --dry-run "文本"      只取 token、不发送（连通性自检）
+//   ./qq-notify --config PATH "文本"  指定配置文件
+//   ./qq-notify --help                显示帮助
+//   stdin 管道                         无参数时从标准输入读取文本
+//
+// 配置优先级：--config PATH > 环境变量 QQ_NOTIFY_CONFIG > ~/.pi/agent/pi-agent-qqbot.json
+// 退出码：0 成功 · 1 参数/配置错 · 2 取 token 失败 · 3 发送失败
+// 安全：绝不打印/落盘 clientSecret 与 access_token；错误输出截断。
+//
+// ⛔ 禁用 `bash <本脚本>` 这类「用 shell 逐行解释 Node 脚本」的调用方式：
+//    shell 会把注释里的示例当命令执行（管道、重定向、glob），可能触发意外发送
+//    （本仓历史上正因此误发过一条真实消息）。正确形式：./qq-notify 或 node qq-notify。
+//    第 2 行的 exec 守卫已使 sh/bash 调用自动转交 node，但仍不建议依赖该行为。
+//
+// 实现说明：本文件无扩展名，需同时兼容宿主项目 package.json 的
+// "type": "module" 与 CommonJS 两种解析；因此只用动态 import()（两种格式都合法）
+// 并包在 async IIFE 中，避免静态 import / 顶层 await / require。
+;(async () => {
+  const fs = await import('node:fs')
+  const os = await import('node:os')
+  const path = await import('node:path')
+
+  const EXIT = { OK: 0, ARG: 1, TOKEN: 2, SEND: 3 }
+  const DEFAULT_CFG = path.join(os.homedir(), '.pi/agent/pi-agent-qqbot.json')
+  const TOKEN_URL = 'https://bots.qq.com/app/getAppAccessToken'
+  const BODY_LIMIT = 300
+
+  const USAGE = [
+    'qq-notify —— QQ 官方机器人「主动消息」推送器',
+    '',
+    '用法',
+    '  qq-notify "文本"                 发给配置中的 ownerOpenId',
+    '  qq-notify --to <openid> "文本"   发给指定 openid',
+    '  echo "文本" | qq-notify          从 stdin 读取文本',
+    '  qq-notify --dry-run "文本"       只取 token、不发送（连通性自检）',
+    '  qq-notify --config <path> ...    指定配置文件',
+    '  qq-notify -h | --help            显示本帮助',
+    '',
+    '配置（优先级从高到低）',
+    '  1) --config <path>',
+    '  2) 环境变量 QQ_NOTIFY_CONFIG',
+    '  3) ' + DEFAULT_CFG,
+    '  字段：{ "appId": "...", "clientSecret": "...", "ownerOpenId": "...", "sandbox": true }',
+    '',
+    '退出码',
+    '  0 成功   1 参数/配置错   2 取 token 失败   3 发送失败',
+    '',
+    '说明',
+    '  · 主动消息受 QQ 开放平台权限与月度配额限制；sandbox 与 prod 权限不通用',
+    '  · 绝不打印或落盘 clientSecret / access_token',
+  ].join('\n')
+
+  const trunc = (v, n = BODY_LIMIT) => {
+    const s = String(v ?? '')
+    return s.length > n ? s.slice(0, n) + '…(截断)' : s
+  }
+  // 从任何即将打印的文本中抹去已知凭证值（客户端密钥 / access_token）
+  const redact = (v, secrets = [], n = BODY_LIMIT) => {
+    let s = String(v ?? '')
+    for (const sec of secrets) {
+      if (sec && String(sec).length >= 6) s = s.split(String(sec)).join('***')
+    }
+    return trunc(s, n)
+  }
+  const maskId = (v) => (v ? String(v).slice(0, 6) + '…' : '<无>')
+  const fail = (code, msg, hint) => {
+    process.stderr.write('FAIL: ' + msg + '\n')
+    if (hint) process.stderr.write('  → ' + hint + '\n')
+    process.exit(code)
+  }
+
+  // ---- 参数解析 -----------------------------------------------------------
+  const argv = process.argv.slice(2)
+  let to = null
+  let cfgPath = null
+  let dry = false
+  let text = null
+  let endOpts = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (endOpts) {
+      if (text === null) { text = a; continue }
+      fail(EXIT.ARG, '多余的位置参数: ' + trunc(a, 60), '文本请用引号括起为一个参数')
+    }
+    if (a === '-h' || a === '--help') { process.stdout.write(USAGE + '\n'); process.exit(EXIT.OK) }
+    else if (a === '--dry-run') dry = true
+    else if (a === '--') endOpts = true
+    else if (a === '--to') {
+      const v = argv[++i]
+      if (!v || v.startsWith('--')) fail(EXIT.ARG, '--to 缺少 openid', '用法：qq-notify --to <openid> "文本"')
+      to = v
+    } else if (a.startsWith('--to=')) {
+      to = a.slice(5)
+      if (!to) fail(EXIT.ARG, '--to 缺少 openid', '用法：qq-notify --to <openid> "文本"')
+    } else if (a === '--config') {
+      const v = argv[++i]
+      if (!v || v.startsWith('--')) fail(EXIT.ARG, '--config 缺少路径', '用法：qq-notify --config <path> "文本"')
+      cfgPath = v
+    } else if (a.startsWith('--config=')) {
+      cfgPath = a.slice(9)
+      if (!cfgPath) fail(EXIT.ARG, '--config 缺少路径', '用法：qq-notify --config <path> "文本"')
+    } else if (a.startsWith('-') && a !== '-') {
+      fail(EXIT.ARG, '未知参数: ' + trunc(a, 60), '查看帮助：qq-notify --help')
+    } else {
+      if (text === null) text = a
+      else fail(EXIT.ARG, '多余的位置参数: ' + trunc(a, 60), '文本请用引号括起为一个参数')
+    }
+  }
+
+  if (!text && !process.stdin.isTTY) {
+    try {
+      const piped = fs.readFileSync(0, 'utf8').trim()
+      if (piped) text = piped
+    } catch { /* 无 stdin：忽略 */ }
+  }
+  if (!text) fail(EXIT.ARG, '缺少推送文本', '用法：qq-notify "文本"  或  echo "文本" | qq-notify')
+
+  // ---- 配置 ---------------------------------------------------------------
+  const cfgFile = cfgPath || process.env.QQ_NOTIFY_CONFIG || DEFAULT_CFG
+  let cfg
+  try {
+    cfg = JSON.parse(fs.readFileSync(cfgFile, 'utf8'))
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      fail(EXIT.ARG, '读不到配置：' + cfgFile,
+        '创建该 JSON（appId / clientSecret / ownerOpenId / sandbox），或用 --config <path> / QQ_NOTIFY_CONFIG=<path> 指定')
+    }
+    fail(EXIT.ARG, '配置解析失败：' + cfgFile + '：' + trunc(e && e.message, 160), '确认该文件是合法 JSON')
+  }
+  if (!cfg || typeof cfg !== 'object') fail(EXIT.ARG, '配置内容非法：' + cfgFile, '应为 JSON 对象')
+  if (!cfg.appId || !cfg.clientSecret) fail(EXIT.ARG, '配置缺少 appId 或 clientSecret', '检查 ' + cfgFile)
+
+  const target = to || cfg.ownerOpenId
+  if (!target) {
+    fail(EXIT.ARG, '没有收件人：配置缺 ownerOpenId，且未传 --to',
+      '在配置中填 ownerOpenId，或 qq-notify --to <openid> "文本"')
+  }
+  const env = cfg.sandbox ? 'sandbox' : 'prod'
+  const base = cfg.sandbox ? 'https://sandbox.api.sgroup.qq.com' : 'https://api.sgroup.qq.com'
+
+  // ---- 取 access token（绝不打日志） --------------------------------------
+  let tokenRes
+  try {
+    tokenRes = await fetch(TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ appId: cfg.appId, clientSecret: cfg.clientSecret }),
+    })
+  } catch (e) {
+    fail(EXIT.TOKEN, '取 token 网络错误：' + trunc(e && e.message, 160), '检查网络/代理后重试')
+  }
+  let tokenJson = {}
+  try { tokenJson = await tokenRes.json() } catch { /* 非 JSON 响应 */ }
+  if (!tokenRes.ok || !tokenJson.access_token) {
+    fail(EXIT.TOKEN, '取 token 失败：status=' + tokenRes.status + ' body=' + redact(JSON.stringify(tokenJson), [cfg.clientSecret]),
+      '核对 appId/clientSecret，并确认 QQ 开放平台应用已开通机器人能力')
+  }
+
+  if (dry) {
+    process.stdout.write('OK (dry-run) 取 token 成功 · env=' + env + ' · to=' + maskId(target) + '\n')
+    process.exit(EXIT.OK)
+  }
+
+  // ---- 发送主动消息（不带 msg_id） ----------------------------------------
+  let res
+  try {
+    res = await fetch(base + '/v2/users/' + encodeURIComponent(target) + '/messages', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: 'QQBot ' + tokenJson.access_token,
+      },
+      body: JSON.stringify({ content: text, msg_type: 0 }),
+    })
+  } catch (e) {
+    fail(EXIT.SEND, '发送网络错误：' + trunc(e && e.message, 160), '检查网络后重试')
+  }
+  const body = await res.text().catch(() => '')
+  if (res.ok) {
+    process.stdout.write('OK env=' + env + ' to=' + maskId(target) + ' ' + redact(body, [cfg.clientSecret, tokenJson.access_token], 120) + '\n')
+    process.exit(EXIT.OK)
+  }
+  fail(EXIT.SEND, '发送失败：status=' + res.status + ' body=' + redact(body, [cfg.clientSecret, tokenJson.access_token]),
+    '核对收件人 openid、主动消息权限与月度配额；sandbox 与 prod 权限不通用')
+})().catch((e) => {
+  // 兜底：任何未预期错误都不抛栈（此处不依赖 IIFE 内作用域）
+  const msg = String((e && e.message) ? e.message : e)
+  process.stderr.write('FAIL: 未预期错误：' + (msg.length > 200 ? msg.slice(0, 200) + '…(截断)' : msg) + '\n')
+  process.exit(1)
+})

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

@@ -0,0 +1,92 @@
+---
+description: 按需技能——PM 运行手册（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 交付归档）
+---
+
+# PM 运行手册
+
+> 触发：**调度与运营操作**（拉起会话、派发、重开、建/改 `AGENTS.md`、归档）时读取；身份/边界/红线常驻在角色卡。
+> 角色路由与会话登记在 @.agents/skills/pm-routing.md；需求分支与 PR 流水线在 @.agents/skills/github-flow.md。
+
+## 一、多会话调度细则
+
+- **准入判定**：先 `intercom status` + `list`；不可用立即降级不重试。
+- **会话登记**：用户提供名称**及角色标注**（`fe-dev`/`be-dev`/`qa`/`infra`）；**未标注禁止猜测**，必须补问。
+- **舰队启动**：不在线先拉起再 `list` 验证（`ask` 仅对在线会话）：`bash .agents/scripts/nao-fleet.sh ensure <别名>[@<repo目录>]`；项目独立于 nao-skills 仓库时用 `bash "$NAO_SKILLS/.agents/scripts/nao-fleet.sh" ...`。
+- **环境自检（开工确认后、派发前）**：`bash .agents/scripts/nao-fleet.sh check`——默认单行摘要（完整报告不进 PM 上下文），`warn>0` 或失败加 `-v`；**exit code 非 0（硬错误）→ 停止派发**（白名单 / CodeGraph 处置见 intercom-protocol「开工前自检」）。
+- **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
+- **派发协议（省 token）**：一条消息给 `编号 + 范围 + 引用路径（docs/...md#section）+ AC 编号 + 回执级别 + 需求分支（feat/<issue-id>-<slug>）`；**不贴 PRD/方案全文、不用 `attachments` 传全文**（worker 自己读文件，PM 上下文不留副本）；worker `ask` → PM `reply`。
+- **忙闲闸门**：`list` 见目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不投递任务内容**，记入待派发队列（`docs/tasks-state.md`），转 `idle` 再派；**紧急**才抢占（交互会话可 steer 注入并注明 `紧急抢占：…回执须报告挂起任务状态`；非交互会话只能排队）。
+- **任务派生会话（并行隔离）**：`ensure <role>@<repo> --task <编号>` → `--name <角色>-<编号>`（如 `rd-be-T1`）；**验收通过后回收**：`nao-fleet.sh close --task <编号> <别名>`（工具内置「在跑 turn / tasks-state 未推进」双闸门，后者防验收未过就回收丢返工上下文）；回执 role 写派生名。
+- **状态外部化 + 接续快照（可恢复）**：任务状态落盘 `docs/tasks-state.md`（五栏 + 顶部「PM 接续快照」；骨架见 @.agents/templates/tasks-state.md.example），每次派发/回执/验收/抢占后更新；重开后**先读该文件重建状态**，不依赖历史消息。
+- **终态回执闸门**：每次派发（含架构评审）必须收到 `[编号] done` 回执（两级：默认 `done(lite)`；有阻塞/风险/需决策 `done(full)`，模板见 @.agents/checklists/comm-templates.md）；未见回执（含 arch 静默）→ 主动追讨，必要时上报用户，**不默认成功**。
+- **残留自检**：`nao-fleet.sh status` 标出派生会话残留（tasks-state 已归档 / 无记录）；发现即核对状态并 `close --task <编号> <别名>` 回收。
+- **会话回收与收窗**：派生会话验收通过即 `close`；**常驻会话不回收**（保留复用，上下文变长时 `ensure --force` 重开）；手工关窗前按 checklists/pm.md「会话回收 / 收窗核对」逐项核对（工具不替代回执与产物核对）。
+- **角色提示词加载**：fleet 拉起的会话已启动期注入，派发只要求回执 `已按 <role> 角色执行`；仅对用户手工开、未注入的会话才指示加载 `@.agents/prompts/<role>.md`。
+- **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码用 `codegraph node --file <f> --offset <n> --limit <m>` 行段，**禁 cat 全文**；依赖 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。
+
+## 二、开工确认卡（强制闸门）
+
+表格输出，末尾询问「是否开工？会话/角色是否如上？」：
+
+| 任务编号 | 目标会话 | 角色 | 任务概要 | 对应 AC |
+| :--- | :--- | :--- | :--- | :--- |
+| T1 | rd-be | 后端 | ... | AC1/AC3 |
+
+分支：`feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）· PR owner：<角色> · Reviewer：<arch-designer / 无> · 预览环境：<URL / 无>
+
+建议顺序：**QA 先行用例 → 前后端并行**。
+
+用户指定模型时在开工确认卡另起一行注明（如 `rd-be: deepseek-v4-flash:high`）；**未指定禁止传 `--model`、禁止继承 PM 模型**（白名单由 `nao-fleet.sh` 校验，PM 只需如实转达）。
+
+## 三、PM 会话生命周期（重开纪律，PM 专属）
+
+PM 是舰队唯一常驻长寿会话：上下文过长时丢的是**纪律**（红线/闸门遗漏且无感），因此不靠「记得住」，靠**批次边界重开 + 落盘接续**。**三个触发点，任一命中即 `ensure --force pm`**：
+
+1. 交付归档完成（批次终态，默认触发）；
+2. 用户切入新需求、上一需求已闭环；
+3. `/session` 显示 contextTokens 超上下文窗口 40%（主动交接，不等自动压缩）。
+
+- **重开前**：更新 `docs/tasks-state.md` 顶部「PM 接续快照」（当前阶段 / 当前 PRD / 未决决策 / 待用户回答 / 下次唤醒条件 / 会话体检）。
+- **重开后**：读 tasks-state（含接续快照）+ `docs/prds/README.md` 索引 → **向用户回读确认 3 行**（当前阶段 · 未决决策 · 口头约束），确认后方可调度；**禁止凭残缺记忆调度**。
+- **自动压缩只作兜底**：LLM 摘要**有损且不可审计**（决策点最易丢）、额外花 token、禁用该次 prompt-cache 写——它救的是溢出，不是记忆。
+
+## 四、AGENTS.md 项目上下文治理（PM 独有职责）
+
+项目根 `AGENTS.md` 是**项目级单一事实来源**（pi 自动加载进所有会话上下文，与 CLAUDE.md 兼容）。PM 负责建立与维护——让任何角色进入项目即获得一致的项目属性与约束。
+
+**内容范围（只放项目级；它常驻上下文，必须精简）**
+
+- 项目属性：仓库结构 / 技术栈与版本 / 构建·测试·lint 命令 / 运行方式 / 环境变量 / 目录约定。
+- 项目约束：领域红线、依赖与命令纪律、与 nao 机制衔接（CodeGraph 索引位置、UI tokens/ux-playbook 路径、checklists 位置）。
+- **指针而非复制**：角色级/团队级内容留在 nao-skills（roles.yaml / common / checklists），AGENTS.md 只写「在哪里」。
+
+**接入已有 AGENTS.md（项目已存在且非空时）**
+
+- **合并不覆盖**：原文件是项目既有资产，PM 无权单方面改写；先读全文判断来源（手写规范 / 工具生成）。
+- **在 pi 实际加载的文件里合并**：pi 按 `AGENTS.override.md → AGENTS.md → CLAUDE.md` 只取第一个存在者；在**被加载的那个文件**里追加，而非新建遮蔽文件。
+- **保留原文 + 追加接入区块**：原内容原样保留，末尾追加 `## nao 舰队接入（YYYY-MM-DD）` 区块，含：角色清单指针（`$NAO_SKILLS/.agents/roles.yaml`）、机制衔接（CodeGraph / checklists / UI tokens）、命令纪律；区块加注释标记便于未来移除（可回退）。
+- **同主题冲突**：原文件条目优先（它是项目既定决策）；nao 需要的补充以接入区块承载，不混改原文措辞。
+- **删除/改写原文须用户确认**：与零代码边界同源——PM 只增不改既有资产，除非用户明确授权。
+- **验收**：合并后 `nao-fleet.sh check` 通过；任意会话进项目可复述 AGENTS.md 中的项目约束。
+
+**更新时机**
+
+- 项目初始化（首个 PRD 定稿后**当日建立**）。
+- **用户口头约束即时落盘**：用户的任何约束性表述（如「这个项目不许用 ORM」）**当场**写入 `AGENTS.md`（项目级）或 PRD「变更治理」（需求级），**不等归档**——不落盘则 PM 重开后无法恢复。
+- 关键技术决策（ADR 归档时同步一条）。
+- 约束/命令/结构变化随改随更；交付归档时顺带核对（见本文件 §五）。
+
+**自查（PM 交付前）**
+
+- [ ] AGENTS.md 掺入角色级/团队级内容？（应留在 nao-skills）
+- [ ] AGENTS.md 超长（>120 行）或含易变细节？（应精简/移除）
+- [ ] 技术决策或约束变化后未同步 AGENTS.md？
+
+## 五、交付归档
+
+- 时机：PRD 完成且交付闭环后**当日**归档。
+- 落盘：`docs/prds/YYYY-MM-DD-<主题>.md`。
+- 内容：背景(5 Whys 摘要) → 目标指标与埋点 → 9 模块要点 → 决策留痕(RICE/取舍/回滚) → 参考来源(`docs/research/` 路径) → 派发记录（含需求分支、PR 编号、main 合并 commit hash） → 验收结果 → 变更记录 → 遗留项。
+- 首次归档创建 `docs/prds/README.md` 索引（日期 | 主题 | 交付 | 终签状态）。
+- 归档同时：更新 `docs/tasks-state.md` 接续快照；「派发记录」末行记**会话体检**（`contextTokens / 压缩次数 / cacheRead 占比`，取自 `/session`）；随后按本文件 §三「PM 会话生命周期」重开 PM 会话（归档 = 批次终态）。