@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/.claude/agents/code-reviewer.md

@@ -0,0 +1,109 @@
+---
+name: code-reviewer
+description: 强制只读 code review，检查 Vue、TypeScript、Element Plus、路由、权限和 AI 生成代码质量。
+tools: Read, Glob, Grep, Bash
+---
+
+# Code Reviewer
+
+你是本 AI 编写 Vue 后台项目的强制 code review subagent。主 agent 完成任务前，你必须 review 最新变更。
+
+## Review 范围
+
+- 检查当前 diff 和所有变更文件。
+- 阅读 `CLAUDE.md`、`AGENTS.md`，以及相关 `.claude/rules/*.md`。
+
+### Vue / TypeScript 代码质量
+
+- **Composition API**：必须使用 `<script setup lang="ts">`，禁止 Options API。
+- **SFC 顺序**：`<script>` → `<template>` → `<style>`，检查是否遵守。
+- **宏位置**：`defineOptions`、`defineProps`、`defineEmits` 应放在 `<script setup>` 顶部，在变量声明之前。
+- **显式类型**：props、emits、store state、route meta、API 边界必须显式类型化，禁止宽泛 `any`。
+- **组件边界**：路由页面保持轻薄，复杂 UI 应拆到 `src/components/<feature>/`。
+- **composables**：可复用的有状态逻辑应放到 `src/composables/useXxx.ts`。
+- **响应式纪律**：能用 `computed` 派生的状态不要重复存储；`watch` 只用于副作用，禁止无意义的空 watcher。
+- **async 错误处理**：避免静默吞掉 Promise reject，async 函数和 Promise 链应有适当的错误处理。
+- **生命周期清理**：检查事件监听、定时器、WebSocket 订阅等是否在 `onUnmounted` 中清理，避免内存泄漏。
+- **模板安全**：避免 `v-html` 渲染不可信内容，避免模板中执行复杂表达式。
+
+### 路由和认证
+
+- 检查 `meta.title`、`meta.requiresAuth` 和隐藏路由配置是否正确。
+- 检查 guard 行为是否与 `src/router/guards.ts` 一致。
+- 检查动态菜单逻辑是否基于后端 `/auth/menus` 菜单树，不维护第二套前端菜单或权限事实源。
+- 检查 `src/router/component-map.ts` 的组件解析和隐藏路由是否仍与真实页面文件匹配。
+- 禁止路由 meta 回归（删除或误改现有 meta）。
+- 检查是否错误地把当前占位业务页面、mock 数据或临时流程沉淀为永久 harness 规则。
+
+### Element Plus
+
+- 检查组件用法是否合理（props/events 是否正确、是否使用了已废弃的 API）。
+- 样式覆盖是否集中在 `src/styles/element-plus.scss`，业务组件避免零散深层覆盖。
+- 检查是否使用了冗余的显式导入（项目配置了 `unplugin-auto-import` + `unplugin-vue-components`）。
+
+### Pinia Store
+
+- 状态来源是否可预测，是否类型清晰。
+- 能用 `computed` 派生的状态是否在 store 中重复存储。
+- store 之间是否存在循环依赖。
+
+### 生成文件
+
+- 确认是否由工具有意生成，避免被手动误改。
+
+### 验证清单
+
+- 检查本次变更是否已经运行了对应的验证命令：
+  - 一般代码变更：`pnpm check`（包含 `type-check` + `lint` + `format:check` + `harness:check`）
+  - 影响构建/路由/依赖/Vite 配置：`pnpm build`
+  - harness/skill 变更：`pnpm harness:sync` + `pnpm harness:check`
+- 如果某些检查未运行，是否在交付说明中记录了原因和剩余风险。
+- 涉及可见 UI、布局、路由权限、表单、弹窗或上传时，是否按 `docs/verification.md` 完成本地浏览器验证或说明未验证风险。
+
+### 人工审核交接单
+
+- 检查主 agent 的最终交付说明是否按 `docs/delivery-template.md` 覆盖改动摘要、影响范围、AI 已验证、需要人工复核、人工决策记录和剩余风险。
+- 涉及真实审批流、角色权限口径、业务状态机、真实接口数据或复杂异常流程时，必须列出人工复核项，不能声称仅靠 AI 已完全验证。
+- 用户曾指出问题或补充业务规则时，检查交付说明是否记录了人工决策和二次验证结果。
+- 如果缺少关键交接信息，或复杂业务没有人工复核项，应作为验证遗漏指出；影响业务判断时返回 FAIL。
+
+## 阻断标准（P0 / P1 / P2）
+
+### P0 — 阻塞，必须修复
+
+- 质量门禁失败（`pnpm check` 或 `pnpm build` 未通过）
+- 安全风险（密钥泄露、XSS、命令注入、SQL 注入）
+- 权限绕过或路由 meta 回归
+- 宽泛未类型化的状态/API 边界（如显式 `any`、缺失的类型声明）
+- 与项目核心规则冲突的变更（如使用 Options API、错误的 SFC 顺序）
+
+### P1 — 严重，建议修复
+
+- async 错误未处理或静默吞掉 Promise reject
+- 生命周期资源未清理（事件监听、定时器泄漏）
+- `watch` 被滥用（用于本可用 `computed` 实现的派生）
+- Pinia store 中重复存储可计算状态
+- 冗余的显式 Element Plus 导入
+- 验证命令未运行且未说明原因
+- 涉及复杂业务但缺少人工复核项或人工决策记录
+
+### P2 — 建议，可备注通过
+
+- 代码风格不一致
+- 缺少必要的注释
+- 可进一步拆分的组件
+- 低风险的性能优化建议
+- 交接单信息存在轻微不完整，但不影响本次人工审核
+
+## 输出要求
+
+没有 P0 问题且没有未说明原因的验证遗漏时返回 PASS。存在 P0 问题或关键验证缺失时返回 FAIL。P1/P2 问题可作为备注列出，不阻断 PASS。
+
+结尾必须且只能包含一个结果标记：
+
+- `HARNESS_REVIEW_RESULT: PASS`
+- `HARNESS_REVIEW_RESULT: FAIL`
+
+无论 PASS 还是 FAIL，都要提醒主 agent：**Claude review 不能替代人工最终复核**。
+
+review 内容保持简洁、具体、可执行。

package/templates/harness/full/.claude/agents/harness-reviewer.md

@@ -0,0 +1,51 @@
+---
+name: harness-reviewer
+description: 只读 review Claude Code harness 配置、hooks、项目 agents、skills 和 AI 治理文档。
+tools: Read, Glob, Grep, Bash
+---
+
+# Harness Reviewer
+
+你负责 review 本项目的 AI harness 层。不要编辑文件。
+
+## Review 范围
+
+- `.claude/settings.json`
+- `.claude/hooks/*.cjs`
+- `.claude/agents/*.md`
+- `.claude/rules/*.md`
+- `CLAUDE.md`
+- `AGENTS.md`
+- `docs/ai-harness.md`
+- `docs/delivery-template.md`
+- `docs/review-checklist.md`
+- `docs/verification.md`
+- `skills-lock.json`
+- `scripts/check-project-structure.mjs`
+- `scripts/*.test.mjs`
+- `package.json` scripts 和 `.husky/*`
+
+## 检查项
+
+- hooks 必须跨平台，不能依赖 `jq`，平台专属逻辑必须有安全 fallback。
+- 只有 `quality-gate.cjs stop` 允许运行 `pnpm format` 做 Stop 收尾自动格式化；其他 hooks 不得自动格式化、暂存或改写 repo-tracked 文件。
+- Stop review 必须在质量门禁失败或 P0/P1 review 问题时阻止结束。
+- 完成通知必须兼容 macOS 和 Windows，并在失败时安全降级。
+- skills 必须同步 lock hash（`skills-lock.json` 中每个 skill 的 `computedHash` 必须与当前文件内容一致）。
+- `.agents/skills/` 必须与 `.claude/skills/` 完全镜像（`diff -r .claude/skills/ .agents/skills/` 输出为空）。
+- harness 脚本的测试必须接入 `pnpm harness:check`，不能只放测试文件。
+- 结构检查必须只约束通用工程护栏，不得固化当前占位业务流程或 mock 数据。
+- harness 配置以源文件为准，不维护额外 generated config inventory。
+- 敏感文件和危险命令必须被拒绝。
+- 人工审核交付要求必须在入口文档、速查表、review checklist、delivery template 和 reviewer 规则中保持一致。
+- 不得让 AI 替代复杂业务决策；真实审批流、角色权限口径、状态机和真实接口数据必须保留人工复核边界。
+- 无论 PASS 还是 FAIL，都要提醒主 agent：Claude review 不能替代人工最终复核。
+
+## 输出要求
+
+结尾必须且只能包含一个结果标记：
+
+- `HARNESS_REVIEW_RESULT: PASS`
+- `HARNESS_REVIEW_RESULT: FAIL`
+
+review 内容保持简洁、具体、可执行。

package/templates/harness/full/.claude/hooks/guard-tool.cjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse 安全守护 hook
+ *
+ * 职责：在 Claude Code 执行任何工具之前拦截，阻断危险命令和敏感文件访问。
+ * 覆盖 Bash/Read/Write/Edit/Grep/Agent 等工具调用。
+ * 不改写任何文件，只返回 continue/deny 决策。
+ */
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// 从 stdin 读取 Claude Code 传入的 JSON hook payload
+function readJsonStdin() {
+  const input = fs.readFileSync(0, 'utf8').trim()
+  if (!input) {
+    return {}
+  }
+
+  try {
+    return JSON.parse(input)
+  } catch {
+    return {}
+  }
+}
+
+// 构造拦截响应：阻止执行并附带原因
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      continue: false,
+      stopReason: reason,
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    }),
+  )
+}
+
+// 构造放行响应：允许执行，抑制输出
+function allow() {
+  process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }))
+}
+
+// 统一路径格式：Windows 反斜线 → 正斜线，去除两端引号
+function normalizePath(value) {
+  return String(value ?? '')
+    .replaceAll('\\', '/')
+    .replace(/^["']|["']$/g, '')
+}
+
+// 从嵌套的 toolInput 对象中递归收集所有含路径含义的字符串值
+function collectPaths(value, results = []) {
+  if (!value) {
+    return results
+  }
+
+  if (typeof value === 'string') {
+    results.push(value)
+    return results
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectPaths(item, results)
+    }
+    return results
+  }
+
+  if (typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) {
+      if (/path|file|filename/i.test(key) && typeof item === 'string') {
+        results.push(item)
+      } else {
+        collectPaths(item, results)
+      }
+    }
+  }
+
+  return results
+}
+
+// 判断文件路径是否为密钥/凭证等敏感文件（允许 .env.example）
+function isSensitivePath(filePath) {
+  const normalized = normalizePath(filePath)
+  const base = path.posix.basename(normalized)
+
+  if (!normalized) {
+    return false
+  }
+
+  if (base === '.env.example') {
+    return false
+  }
+
+  return (
+    /^\.env($|\.)/.test(base) ||
+    /(^|\/)\.env($|\.)/.test(normalized) ||
+    /(^|\/)secrets?\//i.test(normalized) ||
+    /(^|\/)(id_rsa|id_ed25519|known_hosts)$/i.test(normalized) ||
+    /\.(pem|key|p12|pfx|crt|cer)$/i.test(base)
+  )
+}
+
+// 判断 glob pattern 是否匹配敏感文件模式
+function isSensitiveGlob(glob) {
+  const normalized = String(glob ?? '').replaceAll('\\', '/')
+  return (
+    /^\.env($|\*)/.test(normalized) ||
+    /(^|\/)\.env($|\*)/.test(normalized) ||
+    /(^|\/)secrets?\//i.test(normalized) ||
+    /\.(pem|key|p12|pfx|crt|cer)$/i.test(normalized)
+  )
+}
+
+// 从 shell 命令文本中提取可能的路径片段。不能只按空白切分：
+// cat<.env.production、node -e "readFileSync('.env')" 这类写法都不会产生独立空白 token。
+function collectCommandPathCandidates(command) {
+  return String(command ?? '')
+    .replaceAll('\\', '/')
+    .split(/[\s"'`$;&|()<>,={}[\]]+/)
+    .map((token) => token.trim())
+    .filter(Boolean)
+}
+
+// 检测 Bash 命令是否包含危险操作（破坏性 Git、递归删除、低级磁盘写入等）
+// commandStart 匹配命令起始位置：行首、管道/分号后，或环境变量赋值后
+function dangerousCommandReason(command) {
+  const commandStart = String.raw`(?:^|[;&|()])\s*(?:\w+=(?:"[^"]*"|'[^']*'|[^\s;|()]+)\s+)*`
+  const checks = [
+    [new RegExp(`${commandStart}git\\s+reset\\s+--hard\\b`, 'i'), 'Blocked destructive git reset.'],
+    [
+      new RegExp(`${commandStart}git\\s+reset\\s+--mixed\\s+HEAD\\b`, 'i'),
+      'Blocked destructive git reset.',
+    ],
+    [
+      new RegExp(`${commandStart}git\\s+push\\s+--force(?:-with-lease)?\\b`, 'i'),
+      'Blocked force push.',
+    ],
+    [
+      new RegExp(`${commandStart}git\\s+push\\s+\\S+\\s+--delete\\b`, 'i'),
+      'Blocked remote branch deletion.',
+    ],
+    [
+      new RegExp(`${commandStart}git\\s+push\\s+\\S+\\s+\\+\\S+\\b`, 'i'),
+      'Blocked force push via refspec.',
+    ],
+    [new RegExp(`${commandStart}git\\s+branch\\s+-D\\b`, 'i'), 'Blocked local branch deletion.'],
+    [new RegExp(`${commandStart}git\\s+stash\\s+(drop|clear)\\b`, 'i'), 'Blocked stash deletion.'],
+    [
+      new RegExp(`${commandStart}git\\s+checkout\\s+(?:--\\s+|\\.)`, 'i'),
+      'Blocked destructive git checkout.',
+    ],
+    [new RegExp(`${commandStart}git\\s+restore\\b`, 'i'), 'Blocked destructive git restore.'],
+    [
+      new RegExp(
+        `${commandStart}git\\s+clean\\s+(?=[^;&|\\n]*-[A-Za-z]*f)(?=[^;&|\\n]*-[A-Za-z]*d)`,
+        'i',
+      ),
+      'Blocked destructive git clean.',
+    ],
+    [
+      new RegExp(`${commandStart}rm\\s+(?=[^;&|\\n]*-[A-Za-z]*r)(?=[^;&|\\n]*-[A-Za-z]*f)`, 'i'),
+      'Blocked recursive force delete.',
+    ],
+    [new RegExp(`${commandStart}del\\s+\\/[fsq]\\b`, 'i'), 'Blocked destructive Windows delete.'],
+    [new RegExp(`${commandStart}rmdir\\s+\\/s\\b`, 'i'), 'Blocked recursive directory delete.'],
+    [
+      new RegExp(`${commandStart}Remove-Item\\b.*\\s-Recurse\\b.*\\s-Force\\b`, 'i'),
+      'Blocked recursive force delete.',
+    ],
+    [new RegExp(`${commandStart}dd\\s+\\b`, 'i'), 'Blocked low-level disk write command.'],
+  ]
+
+  for (const [pattern, reason] of checks) {
+    if (pattern.test(command)) {
+      return reason
+    }
+  }
+
+  return ''
+}
+
+// === 主逻辑 ===
+
+// 1. Bash 命令检查：先检测危险命令，再扫描命令中的敏感路径
+const payload = readJsonStdin()
+const toolName = payload.tool_name || payload.toolName || payload.tool || ''
+const toolInput = payload.tool_input || payload.toolInput || {}
+const command = String(toolInput.command || '')
+
+if (/bash/i.test(toolName) && command) {
+  const reason = dangerousCommandReason(command)
+
+  if (reason) {
+    deny(`${reason} Command: ${command.slice(0, 160)}`)
+    process.exit(0)
+  }
+
+  for (const token of collectCommandPathCandidates(command)) {
+    if (isSensitivePath(token)) {
+      deny(`Blocked command touching sensitive path: ${token}`)
+      process.exit(0)
+    }
+  }
+}
+
+// 2. 工具输入路径检查：递归收集所有路径参数，检测敏感文件
+const paths = collectPaths(toolInput).map(normalizePath)
+const sensitive = paths.find(isSensitivePath)
+
+if (sensitive) {
+  deny(`Blocked access to sensitive path: ${sensitive}`)
+  process.exit(0)
+}
+
+// 3. Grep 工具专项检查：glob pattern 和搜索路径中的敏感文件
+if (/grep/i.test(toolName)) {
+  const glob = String(toolInput.glob || '')
+  const grepPath = String(toolInput.path || '')
+
+  if (glob && isSensitiveGlob(glob)) {
+    deny(`Blocked Grep with sensitive glob pattern: ${glob}`)
+    process.exit(0)
+  }
+
+  if (grepPath && isSensitivePath(grepPath)) {
+    deny(`Blocked Grep in sensitive path: ${grepPath}`)
+    process.exit(0)
+  }
+}
+
+allow()

package/templates/harness/full/.claude/hooks/notify.cjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * SubagentStop / Notification hook
+ *
+ * 职责：
+ * - SubagentStop 模式：解析审查结果，FAIL 时阻断主 agent，PASS 时通知。
+ * - Notification 模式：将通用消息转发为系统通知。
+ * 跨平台支持：macOS osascript → Windows pwsh → powershell → stderr 降级。
+ */
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+
+const mode = process.argv[2] || 'notification'
+
+function readJsonStdin() {
+  const input = fs.readFileSync(0, 'utf8').trim()
+  if (!input) {
+    return {}
+  }
+
+  try {
+    return JSON.parse(input)
+  } catch {
+    return {}
+  }
+}
+
+// PowerShell 字符串中的单引号转义（单引号内用 '' 表示一个单引号）
+function escapePowerShell(value) {
+  return String(value).replaceAll("'", "''")
+}
+
+// 发送跨平台系统通知，带三级降级：macOS osascript → Windows pwsh/powershell → stderr
+function notify(title, message) {
+  const cleanTitle = String(title).slice(0, 80)
+  const cleanMessage = String(message).replace(/\s+/g, ' ').trim().slice(0, 220)
+
+  if (process.argv.includes('--dry-run') || process.env.HARNESS_NOTIFY_DRY_RUN === '1') {
+    process.stderr.write(`[dry-run notification] ${cleanTitle}: ${cleanMessage}\n`)
+    return
+  }
+
+  if (process.platform === 'darwin') {
+    const script = `display notification ${JSON.stringify(cleanMessage)} with title ${JSON.stringify(cleanTitle)}`
+    const result = spawnSync('osascript', ['-e', script], { stdio: 'ignore', timeout: 10000 })
+
+    if (!result.error && result.status === 0) {
+      return
+    }
+  }
+
+  if (process.platform === 'win32') {
+    const script = [
+      "$ErrorActionPreference = 'Stop'",
+      'Add-Type -AssemblyName System.Windows.Forms',
+      '$notify = New-Object System.Windows.Forms.NotifyIcon',
+      '$notify.Icon = [System.Drawing.SystemIcons]::Information',
+      '$notify.Visible = $true',
+      `$notify.ShowBalloonTip(5000, '${escapePowerShell(cleanTitle)}', '${escapePowerShell(cleanMessage)}', 'Info')`,
+      'Start-Sleep -Seconds 6',
+      '$notify.Dispose()',
+    ].join('; ')
+
+    const pwshResult = spawnSync(
+      'pwsh.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { stdio: 'ignore', timeout: 15000 },
+    )
+
+    if (!pwshResult.error && pwshResult.status === 0) {
+      return
+    }
+
+    const result = spawnSync(
+      'powershell.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { stdio: 'ignore', timeout: 15000 },
+    )
+
+    if (!result.error && result.status === 0) {
+      return
+    }
+  }
+
+  process.stderr.write(`[${cleanTitle}] ${cleanMessage}\n`)
+}
+
+// 从不同 hook payload 格式中提取消息文本（兼容多种 payload 结构）
+function extractMessage(payload) {
+  return (
+    payload.message ||
+    payload.notification_message ||
+    payload.last_assistant_message ||
+    payload.transcript_tail ||
+    ''
+  )
+}
+
+const payload = readJsonStdin()
+const message = extractMessage(payload)
+
+// SubagentStop 模式：解析审查结果，FAIL 时阻断主 agent 继续执行
+if (mode === 'subagent-stop') {
+  const text = String(message)
+
+  // 从后往前找最后一个配对的 {...}，避免贪婪正则匹配到解释性文本中的大括号
+  let jsonResult = null
+  let lastBrace = -1
+  for (let i = text.length - 1; i >= 0; i--) {
+    if (text[i] === '}') {
+      lastBrace = i
+      break
+    }
+  }
+  if (lastBrace >= 0) {
+    let depth = 1
+    let openBrace = -1
+    for (let i = lastBrace - 1; i >= 0; i--) {
+      if (text[i] === '}') depth++
+      else if (text[i] === '{') depth--
+      if (depth === 0) {
+        openBrace = i
+        break
+      }
+    }
+    if (openBrace >= 0) {
+      try {
+        jsonResult = JSON.parse(text.slice(openBrace, lastBrace + 1))
+      } catch {
+        // JSON 解析失败，继续使用字符串 fallback
+      }
+    }
+  }
+
+  // JSON 有效时以 ok 字段为准；无效时 fallback 到尾部字符串匹配
+  const isFail =
+    (jsonResult && jsonResult.ok === false) ||
+    (!jsonResult && text.trimEnd().endsWith('HARNESS_REVIEW_RESULT: FAIL'))
+
+  const isPass =
+    (jsonResult && jsonResult.ok === true) ||
+    (!jsonResult && text.trimEnd().endsWith('HARNESS_REVIEW_RESULT: PASS'))
+
+  if (isFail) {
+    notify('Claude Code 代码审查', '审查未通过，请继续修复报告的问题。')
+    process.stdout.write(
+      JSON.stringify({
+        continue: false,
+        stopReason: 'AI 代码审查未通过。请根据审查报告修复问题后再次尝试完成。',
+      }),
+    )
+    process.exit(0)
+  }
+
+  if (isPass) {
+    notify('Claude Code', '任务已完成，代码审查通过。')
+  }
+
+  process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }))
+  process.exit(0)
+}
+
+// Notification 模式：通用通知转发
+notify('Claude Code', message || 'Claude Code 需要您的关注。')
+process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }))

package/templates/harness/full/.claude/hooks/quality-gate.cjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Stop hook
+ *
+ * 职责：
+ * - git 有变更时先自动格式化，再运行 type-check / lint / harness:check。
+ *   失败时阻断 agent 停止，成功时放行并通知。
+ *   注意：不自动暂存（不 git add），由人工决定暂存与提交。
+ */
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const { spawnSync } = require('node:child_process')
+
+const dryRun = process.argv.includes('--dry-run') || process.env.HARNESS_QUALITY_DRY_RUN === '1'
+
+function writeJson(value) {
+  process.stdout.write(JSON.stringify(value))
+}
+
+// 跨平台 shell 参数转义：安全字符直接通过，POSIX 用单引号，Windows 用双引号
+function shellQuote(value) {
+  const text = String(value)
+
+  if (!/[^\w@%+=:,./-]/.test(text)) {
+    return text
+  }
+
+  if (process.platform === 'win32') {
+    return `"${text.replaceAll('"', '\\"')}"`
+  }
+
+  return `'${text.replaceAll("'", "'\\''")}'`
+}
+
+// 跨平台执行 shell 命令：Windows 用 cmd.exe，POSIX 用 sh -lc
+function runShell(commandLine, timeout = 180000) {
+  if (process.platform === 'win32') {
+    return spawnSync('cmd.exe', ['/d', '/s', '/c', commandLine], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      shell: false,
+      timeout,
+    })
+  }
+
+  return spawnSync('sh', ['-lc', commandLine], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    shell: false,
+    timeout,
+  })
+}
+
+// 封装命令执行，支持 --dry-run 模式跳过实际执行
+function run(command, args) {
+  if (dryRun) {
+    return {
+      command: [command, ...args].join(' '),
+      status: 0,
+      stdout: '[dry-run] skipped command execution',
+      stderr: '',
+      error: '',
+    }
+  }
+
+  const commandLine = [command, ...args].map(shellQuote).join(' ')
+  const result = runShell(commandLine)
+
+  return {
+    command: [command, ...args].join(' '),
+    status: result.status ?? 1,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? result.error.message : '',
+  }
+}
+
+// 获取 git 变更文件列表（porcelain 格式）
+function gitStatus() {
+  const result = runShell('git status --porcelain --untracked-files=all', 15000)
+
+  if (result.status !== 0) {
+    return null
+  }
+
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+}
+
+// Stop 模式：无变更时跳过门禁，否则运行完整的质量检查流水线
+const changed = gitStatus()
+
+if (changed && changed.length === 0) {
+  writeJson({
+    continue: true,
+    systemMessage: 'Harness 质量门禁跳过：git 未检测到变更文件。',
+  })
+  process.exit(0)
+}
+
+// Stop 收尾阶段允许自动格式化（本项目唯一允许自动格式化的 hook）
+const formatResult = run('pnpm', ['format'])
+const commands = [
+  ['pnpm', ['type-check']],
+  ['pnpm', ['lint']],
+  ['pnpm', ['harness:check']],
+]
+
+const results = [formatResult, ...commands.map(([command, args]) => run(command, args))]
+const failed = results.filter((result) => result.status !== 0)
+
+if (failed.length > 0) {
+  const details = failed
+    .map((result) => {
+      const output = `${result.stdout}\n${result.stderr}\n${result.error}`.trim()
+      return `命令失败：${result.command}\n${output.slice(-2400)}`
+    })
+    .join('\n\n')
+
+  writeJson({
+    continue: false,
+    stopReason: `Harness 质量门禁未通过。请修复以下问题后再继续。\n\n${details}`,
+  })
+  process.exit(0)
+}
+
+writeJson({
+  continue: true,
+  systemMessage: `Harness 质量门禁通过。变更文件数：${
+    changed ? changed.length : 0
+  }。已通过的检查：pnpm format（自动修复）、pnpm type-check、pnpm lint、pnpm harness:check。`,
+})