chore: 参考 novavis 优化 Agent 配置体系

新增 AGENTS.md 规则（§1-§22）、Hook 脚本和可复用工具脚本：

- 重构 AGENTS.md：新增 16 条规则（任务分解、双轨验证、骨架占位禁止、
  测试命令退出码保留、工具脚本可复用、完成前验证门禁、Flaky 测试门禁等）
- 新增 .trae/hooks/：session-start / pre-agent-check / check-completeness / stop-check
- 新增 .trae/settings.json：关联 4 个 Hook 到 SessionStart/PreToolUse/PostToolUse/Stop
- 新增 scripts/：flaky-scan.sh / check-task-checklist.sh / check-issue-checklist.sh
- 调整 .gitignore：保留 hooks/settings 纳入版本控制，忽略运行时状态文件

.trae/hooks/check-completeness.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# PostToolUse hook: 检查单个编辑文件中的未完成标记
+# 在 Write/Edit 操作后对修改的文件运行
+set -euo pipefail
+
+PROJECT_DIR="${AGENT_PROJECT_DIR:-$(pwd)}"
+
+# Suppress during brainstorming / exploratory sessions
+if [ -f "${PROJECT_DIR}/.trae/.suppress-hooks" ]; then
+  exit 0
+fi
+
+f="${AGENT_EDITED_FILE:-$AGENT_FILE}"
+if [ ! -f "$f" ]; then
+  exit 0
+fi
+
+issues=()
+ext="${f##*.}"
+basename=$(basename "$f")
+
+# ============================================================
+# PART 1: Unfinished markers scan
+# ============================================================
+
+if [[ "$ext" =~ ^(ts|tsx|js|jsx|vue)$ ]]; then
+  while IFS=: read -r line_no content; do
+    [ -z "$line_no" ] && continue
+    trimmed=$(echo "$content" | sed 's/^[[:space:]]*//')
+    if echo "$trimmed" | grep -qE '^\s*(TODO|FIXME|HACK|XXX):'; then
+      issues+=("  L${line_no}: TODO/FIXME ${trimmed:0:100}")
+    elif echo "$trimmed" | grep -qi 'not implemented' && echo "$trimmed" | grep -qi 'throw'; then
+      issues+=("  L${line_no}: [SKELETON] ${trimmed:0:100}")
+    elif echo "$trimmed" | grep -qE 'function [a-zA-Z_][a-zA-Z0-9_]*\s*\(\s*\)\s*\{\s*\}'; then
+      if ! echo "$trimmed" | grep -q 'return'; then
+        issues+=("  L${line_no}: [EMPTY FN] ${trimmed:0:100}")
+      fi
+    fi
+  done < <(grep -nE 'TODO:|FIXME:|HACK:|XXX:|not implemented|function [a-zA-Z_][a-zA-Z0-9_]*\s*\(\s*\)\s*\{\s*\}' "$f" 2>/dev/null || true)
+fi
+
+# ============================================================
+# REPORT
+# ============================================================
+
+if [ ${#issues[@]} -gt 0 ]; then
+  echo ""
+  echo "[COMPLETENESS] $(basename "$f") 检查发现 ${#issues[@]} 个问题:"
+  for issue in "${issues[@]:0:20}"; do
+    echo "$issue"
+  done
+  if [ ${#issues[@]} -gt 20 ]; then
+    echo "  ... 及其他 $((${#issues[@]} - 20)) 处"
+  fi
+  echo ""
+fi

.trae/hooks/pre-agent-check.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# PreToolUse hook: 写操作前根据文件路径输出 Skill 提示
+# 不阻止操作，仅输出提示信息
+set -euo pipefail
+
+f="${AGENT_EDITED_FILE:-$AGENT_FILE}"
+[ -z "$f" ] && exit 0
+[ ! -f "$f" ] && [ ! -e "$f" ] && exit 0
+
+basename=$(basename "$f")
+
+# Skill 提示: 命中时输出，供 agent 决策（AGENTS.md §3 Skill-First）
+skill_hint() {
+  local name="$1"; shift
+  echo "  → [SKILL] $name: $*"
+}
+
+# 检查 1: 算法文件 → 提示 TDD + 交叉验证
+if [[ "$f" == *"/algorithms/"* ]]; then
+  echo ""
+  echo "[PRE-CHECK] 算法变更: $basename"
+  skill_hint "tdd" "RED-GREEN-REFACTOR 测试优先"
+  skill_hint "systematic-debugging" "算法结果须与传统典籍/已知实现交叉验证"
+  echo ""
+  exit 0
+fi
+
+# 检查 2: 测试文件 → 提示测试相关 skill
+if [[ "$basename" == *.test.* || "$basename" == *.spec.* || "$f" == *"/__tests__/"* ]]; then
+  echo ""
+  echo "[PRE-CHECK] 测试文件变更: $basename"
+  skill_hint "tdd" "RED-GREEN-REFACTOR 测试优先"
+  skill_hint "systematic-debugging" "测试失败先定位根因再修复"
+  echo ""
+  exit 0
+fi
+
+# 检查 3: 组件文件 → 提示前端设计 skill
+if [[ "$f" == *"/components/"* && "$basename" == *.vue ]]; then
+  echo ""
+  echo "[PRE-CHECK] 组件变更: $basename"
+  skill_hint "frontend-design" "UniApp 组件设计最佳实践"
+  skill_hint "impeccable" "UI 审查与视觉打磨"
+  echo ""
+  exit 0
+fi
+
+# 检查 4: 页面文件 → 提示全链路验证
+if [[ "$f" == *"/pages/"* && "$basename" == *.vue ]]; then
+  echo ""
+  echo "[PRE-CHECK] 页面变更: $basename"
+  skill_hint "frontend-design" "页面布局与交互设计"
+  echo ""
+  exit 0
+fi
+
+# 检查 5: 国际化文件 → 提示同步所有语言
+if [[ "$f" == *"/locales/"* && "$basename" == *.ts ]]; then
+  echo ""
+  echo "[PRE-CHECK] 国际化变更: $basename"
+  echo "  → 确保同步更新所有 locales/*.ts 文件"
+  echo ""
+  exit 0
+fi
+
+# 检查 6: 文档/注释类 → 中文文档规范
+if [[ "$basename" == *.md || "$basename" == *.adoc ]]; then
+  echo ""
+  echo "[PRE-CHECK] 文档变更: $basename"
+  skill_hint "chinese-documentation" "中文排版/术语/结构规范"
+  echo ""
+  exit 0
+fi

.trae/hooks/session-start.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# SessionStart hook: 启动时输出项目关键上下文和提醒
+# 不阻止会话启动，仅输出提示信息
+set -euo pipefail
+
+PROJECT_DIR="${AGENT_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR"
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  万事宜 (Everything Is Suitable) — 项目上下文"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# 当前分支
+BRANCH=$(git branch --show-current 2>/dev/null || echo "未知")
+echo "  分支: $BRANCH"
+
+# 变更文件统计
+STAGED=$(git diff --cached --name-only 2>/dev/null | wc -l | tr -d ' ')
+UNSTAGED=$(git diff --name-only 2>/dev/null | wc -l | tr -d ' ')
+echo "  变更: ${STAGED} 个暂存, ${UNSTAGED} 个未暂存"
+
+# 检测关键文件变更
+CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null; git diff --cached --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null | sort -u)
+HAS_ALGORITHM_CHANGE=""
+HAS_TEST_CHANGE=""
+HAS_LOCALE_CHANGE=""
+HAS_COMPONENT_CHANGE=""
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  case "$f" in
+    */algorithms/*) HAS_ALGORITHM_CHANGE="yes" ;;
+    */__tests__/*|*.spec.*|*.test.*) HAS_TEST_CHANGE="yes" ;;
+    */locales/*) HAS_LOCALE_CHANGE="yes" ;;
+    */components/*) HAS_COMPONENT_CHANGE="yes" ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# 变更提醒
+if [ -n "$HAS_ALGORITHM_CHANGE" ]; then
+  echo ""
+  echo "  ⚠️  检测到算法文件变更，请确保:"
+  echo "  ┌─ 测试覆盖 ─────────────────────────────────┐"
+  echo "  │  npx vitest run algorithms/__tests__/       │"
+  echo "  ├─ 交叉验证 ─────────────────────────────────┤"
+  echo "  │  算法结果须与传统典籍/已知实现交叉验证       │"
+  echo "  └────────────────────────────────────────────────┘"
+  echo ""
+fi
+
+if [ -n "$HAS_TEST_CHANGE" ]; then
+  echo "  ⚠️  检测到测试文件变更，请确保:"
+  echo "  ┌─ 运行验证 ─────────────────────────────────┐"
+  echo "  │  npm test                                    │"
+  echo "  ├─ Flaky 检查 ────────────────────────────────┤"
+  echo "  │  新增测试至少连续运行 3 次确认稳定性         │"
+  echo "  └────────────────────────────────────────────────┘"
+  echo ""
+fi
+
+if [ -n "$HAS_LOCALE_CHANGE" ]; then
+  echo "  ⚠️  检测到国际化文件变更，请确保同步所有语言:"
+  echo "  locales/zh-CN.ts  locales/en.ts  locales/ja.ts ..."
+  echo ""
+fi
+
+if [ -n "$HAS_COMPONENT_CHANGE" ]; then
+  echo "  ⚠️  检测到组件变更，请确保:"
+  echo "  ┌─ 单元测试 ─────────────────────────────────┐"
+  echo "  │  npx vitest run components/                  │"
+  echo "  ├─ E2E 测试 ──────────────────────────────────┤"
+  echo "  │  npm run test:e2e                             │"
+  echo "  └────────────────────────────────────────────────┘"
+  echo ""
+fi
+
+# Skill 推荐
+echo "  🎯 Skill 推荐（基于变更类型）:"
+if [ -n "$HAS_ALGORITHM_CHANGE" ]; then
+  echo "    算法 → TDD / systematic-debugging"
+fi
+if [ -n "$HAS_TEST_CHANGE" ]; then
+  echo "    测试 → TDD / systematic-debugging"
+fi
+if [ -n "$HAS_COMPONENT_CHANGE" ]; then
+  echo "    组件 → frontend-design / impeccable"
+fi
+echo ""
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""

.trae/hooks/stop-check.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Stop hook: runs quick quality checks and outputs JSON result.
+# 轻量检查（<10s）
+# 残留扫描由 check-completeness.sh（PostToolUse）按文件处理，此处不重复。
+set -euo pipefail
+
+cd "${AGENT_PROJECT_DIR:-$(pwd)}"
+
+# Suppress during brainstorming / exploratory sessions
+if [ -f ".trae/.suppress-hooks" ]; then
+  echo '{"status":"ok","mode":"suppressed"}'
+  exit 0
+fi
+
+HAS_ERRORS=0
+
+# All diagnostics go to stderr
+{
+  echo '=== [STOP HOOK QUALITY GATE] ==='
+
+  # ---- 1/3: TypeScript type check ----
+  echo '[1/3] TypeScript 类型检查...'
+  APP_DIR="everything-is-suitable-uniapp"
+  if [ -f "${APP_DIR}/node_modules/.bin/tsc" ]; then
+    if (cd "${APP_DIR}" && npx tsc --noEmit --pretty false 2>&1); then
+      echo '  tsc: PASS'
+    else
+      echo '  tsc: FAIL'
+      HAS_ERRORS=1
+    fi
+  else
+    echo '  tsc: SKIP（未安装依赖，运行 npm install）'
+  fi
+
+  # ---- 2/3: TODO/FIXME 残留扫描 ----
+  echo '[2/3] 代码残留扫描（TODO/FIXME/skeleton）...'
+  FOUND=$(grep -rn 'TODO:\|FIXME:\|not implemented.*throw' "${APP_DIR}/src" --include='*.ts' --include='*.vue' --include='*.js' 2>/dev/null | grep -v 'node_modules' | grep -v '.test.' | head -10 || true)
+  if [ -z "$FOUND" ]; then
+    echo '  残留扫描: PASS'
+  else
+    echo '  残留扫描: 发现以下残留标记:'
+    echo "$FOUND"
+    HAS_ERRORS=1
+  fi
+
+  # ---- 3/3: 测试文件完整性检查 ----
+  echo '[3/3] 测试文件一致性检查...'
+  # 检查 src 中每个 .ts/.vue 文件是否有关联测试文件
+  ORPHANED=0
+  while IFS= read -r src_file; do
+    [ -z "$src_file" ] && continue
+    base=$(basename "$src_file" .ts)
+    base=$(basename "$base" .vue)
+    dir=$(dirname "$src_file")
+    test_file="${dir}/__tests__/${base}.test.ts"
+    if [ ! -f "$test_file" ]; then
+      # 跳过 index.vue 等特殊文件
+      case "$base" in
+        index|main|App) continue ;;
+      esac
+      # 跳过类型定义文件
+      case "$src_file" in
+        */types/*) continue ;;
+      esac
+      ORPHANED=$((ORPHANED + 1))
+    fi
+  done < <(find "${APP_DIR}/src" -name '*.ts' -o -name '*.vue' 2>/dev/null | head -100)
+  if [ "$ORPHANED" -eq 0 ]; then
+    echo '  测试文件一致性: PASS'
+  else
+    echo "  测试文件一致性: ${ORPHANED} 个源文件缺少关联测试（仅供参考，非强制）"
+  fi
+
+  # ---- Summary ----
+  if [ "$HAS_ERRORS" -eq 0 ]; then
+    echo '=== [STOP HOOK: ALL PASS] ==='
+  else
+    echo '=== [STOP HOOK: ERRORS FOUND] ==='
+  fi
+} >&2
+
+# Output final status as JSON
+if [ "$HAS_ERRORS" -eq 0 ]; then
+  echo '{"status":"ok"}'
+else
+  echo '{"status":"error"}'
+fi

.trae/settings.json

@@ -0,0 +1,51 @@
+{
+  "_comment": "Trae Hook 配置。环境变量 AGENT_PROJECT_DIR 应由宿主 agent 设置为项目根目录。",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${AGENT_PROJECT_DIR}/.trae/hooks/session-start.sh\"",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${AGENT_PROJECT_DIR}/.trae/hooks/pre-agent-check.sh\"",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${AGENT_PROJECT_DIR}/.trae/hooks/check-completeness.sh\"",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${AGENT_PROJECT_DIR}/.trae/hooks/stop-check.sh\"",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}