/click-path-audit — 行为流审计
发现静态代码阅读遗漏的缺陷：状态交互副作用、顺序调用之间的竞态条件，以及相互静默撤销的处理函数。
此技能解决的问题
传统调试检查：
- 函数是否存在？（缺失连接）
- 函数是否崩溃？（运行时错误）
- 函数是否返回正确的类型？（数据流）
但它不检查：
- 最终UI状态是否与按钮标签承诺的一致？
- 函数B是否静默撤销了函数A刚刚完成的操作？
- 共享状态（Zustand/Redux/context）是否存在抵消预期操作的副作用？
实际示例：一个“新邮件”按钮调用了 setComposeMode(true)，然后调用了 selectThread(null)。两个函数单独工作都正常。但 selectThread 有一个副作用，会重置 composeMode: false。该按钮最终什么都没做。通过系统性调试发现了54个缺陷——这一个却被遗漏了。
工作原理
对于目标区域中的每个交互式触摸点：
1. 识别处理函数（onClick、onSubmit、onChange等）
2. 按顺序追踪处理函数中的每个函数调用
3. 对于每个函数调用：
a. 它读取了什么状态？
b. 它写入了什么状态？
c. 它是否对共享状态产生了副作用？
d. 它是否作为副作用重置/清除了任何状态？
4. 检查：是否有后续调用撤销了先前调用所做的状态更改？
5. 检查：最终状态是否是用户根据按钮标签所期望的？
6. 检查：是否存在竞态条件（异步调用按错误顺序解析）？
执行步骤
步骤 1：映射状态存储
在审计任何触摸点之前，构建每个状态存储操作的副作用映射：
对于范围内的每个 Zustand 存储 / React 上下文：
对于每个操作/设置器：
- 它设置了哪些字段？
- 它是否作为副作用重置了其他字段？
- 记录：actionName → {sets: [...], resets: [...]}
这是关键的参考。“新邮件”缺陷在不知道 selectThread 会重置 composeMode 的情况下是看不见的。
输出格式：
STORE: emailStore
setComposeMode(bool) → sets: {composeMode}
selectThread(thread|null) → sets: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} RESETS: {composeMode: false, composeData: null, redraftOpen: false}
setDraftGenerating(bool) → sets: {draftGenerating}
...
危险的 RESET（清除不属于自己状态的函数）：
selectThread → 重置 composeMode（归 setComposeMode 所有）
reset → 重置所有内容
步骤 2：审计每个触摸点
对于目标区域中的每个按钮/切换/表单提交：
TOUCHPOINT: [按钮标签] 位于 [组件:行号]
HANDLER: onClick → {
call 1: functionA() → sets {X: true}
call 2: functionB() → sets {Y: null} RESETS {X: false} ← 冲突
}
预期：用户看到 [按钮标签所承诺内容的描述]
实际：X 为 false，因为 functionB 重置了它
判定：缺陷 — [描述]
检查以下每种缺陷模式：
模式 1：顺序撤销
handler() {
setState_A(true) // 设置 X = true
setState_B(null) // 副作用：重置 X = false
}
// 结果：X 为 false。第一次调用毫无意义。
模式 2：异步竞态
handler() {
fetchA().then(() => setState({ loading: false }))
fetchB().then(() => setState({ loading: true }))
}
// 结果：最终 loading 状态取决于哪个先解析完毕
模式 3：过期闭包
const [count, setCount] = useState(0)
const handler = useCallback(() => {
setCount(count + 1) // 捕获了过期的 count
setCount(count + 1) // 同样的过期 count — 只增加 1，而不是 2
}, [count])
模式 4：缺失状态转换
// 按钮显示“保存”，但处理函数仅进行验证，从未实际保存
// 按钮显示“删除”，但处理函数设置了一个标志，从未调用 API
// 按钮显示“发送”，但 API 端点已被移除/损坏
模式 5：条件死路径
handler() {
if (someState) { // 此时 someState 始终为 false
doTheActualThing() // 永远无法到达
}
}
模式 6：useEffect 干扰
// 按钮设置 stateX = true
// 一个 useEffect 监视 stateX 并将其重置为 false
// 用户看不到任何效果
步骤 3：报告
对于发现的每个缺陷：
CLICK-PATH-NNN: [严重性: 严重/高/中/低]
触摸点：[按钮标签] 位于 [文件:行号]
模式：[顺序撤销 / 异步竞态 / 过期闭包 / 缺失转换 / 死路径 / useEffect 干扰]
处理函数：[函数名或内联]
追踪：
1. [调用] → 设置 {字段: 值}
2. [调用] → 重置 {字段: 值} ← 冲突
预期：[用户期望的结果]
实际：[实际发生的结果]
修复：[具体修复方案]
范围控制
此审计成本较高。请适当限定范围：
- 完整应用审计： 在应用发布或大型重构后使用。按页面启动并行代理。
- 单页面审计： 在构建新页面后或用户报告按钮故障后使用。
- 存储聚焦审计： 在修改了 Zustand 存储后使用——审计所有使用了被修改操作的组件。
完整应用的推荐代理拆分：
代理 1：映射所有状态存储（步骤 1）——这是所有其他代理的共享上下文
代理 2：仪表盘（任务、笔记、日志、想法）
代理 3：聊天（DanteChatColumn、JustChatPage）
代理 4：邮件（ThreadList、DraftArea、EmailsPage）
代理 5：项目（ProjectsPage、ProjectOverviewTab、NewProjectWizard）
代理 6：CRM（所有子标签）
代理 7：个人资料、设置、保险库、通知
代理 8：管理套件（所有页面）
代理 1 必须首先完成。其输出是所有其他代理的输入。
何时使用
- 在系统性调试发现“没有缺陷”但用户报告UI故障后
- 在修改任何 Zustand 存储操作后（检查所有调用者）
- 在涉及共享状态的重构之后
- 在发布前，针对关键用户流程
- 当按钮“无响应”时——这是对付该问题的专用工具
何时不使用
- 对于 API 级别的缺陷（响应格式错误、端点缺失）——使用系统性调试
- 对于样式/布局问题——视觉检查
- 对于性能问题——性能分析工具
与其他技能的集成
- 在
/superpowers:systematic-debugging之后运行（它发现了另外54种缺陷类型） - 在
/superpowers:verification-before-completion之前运行（它验证修复是否有效） - 输入到
/superpowers:test-driven-development——这里发现的每个缺陷都应附带一个测试
示例：启发此技能的缺陷
ThreadList.tsx 中的“新邮件”按钮：
onClick={() => {
useEmailStore.getState().setComposeMode(true) // ✓ 设置 composeMode = true
useEmailStore.getState().selectThread(null) // ✗ 重置 composeMode = false
}}
存储定义：
selectThread: (thread) => set({
selectedThread: thread,
selectedThreadId: thread?.id ?? null,
messages: [],
drafts: [],
selectedDraft: null,
summary: null,
composeMode: false, // ← 这个静默重置杀死了按钮
composeData: null,
redraftOpen: false,
})
系统性调试未能发现它，因为：
- 按钮存在 onClick 处理函数（并非死代码）
- 两个函数都存在（没有缺失连接）
- 两个函数都不会崩溃（没有运行时错误）
- 数据类型正确（没有类型不匹配）
点击路径审计捕获了它，因为：
- 步骤 1 映射出
selectThread会重置composeMode - 步骤 2 追踪处理函数：调用 1 设置 true，调用 2 重置 false
- 判定：顺序撤销 — 最终状态与按钮意图相矛盾