kevinshi3200/persona-auditor

Persona Auditor（数字人审计员）

从真实用户视角审计 AI 代码，找出你反复试验才能发现、甚至永远发现不了的错误，归因成少数根因，一次修对。

Find the bugs real users hit that you'd only discover through costly trial-and-error — or never notice at all — and collapse them into a handful of root causes, so your agent fixes precisely instead of patching blindly.

🌐 English / 简体中文

License: MIT
Type: agent skill
skills.sh

一句话介绍（TL;DR）

问题

AI 写出的代码能跑、且内部自洽——但真实用户走一遍旅程，它就散了：

- 用户在最初几步就卡住，尽管每个函数单独看都对。
- 你一轮轮打补丁，就是找不到根因——因为每次修复只看到局部症状。
- 最糟的是：有些 bug 你永远发现不了。 跨项目串台、状态残留、排序错误——它们深藏在代码里，只有真实用户走完整路径时才会浮现。

解决

Persona Auditor 先读代码，画出一张项目完整结构图（每个页面 / 命令 / 场景），再派出两层数字人：机械执行者逐条在纸面穷尽每条用户路径，只记录可被代码验证的事实（断在哪、file:line、走了几步）；外加一个意图观察者，衡量哪些断点最可能被真实用户在意。最后退到上帝视角，把几十个症状归因成少数几个根因，每个都带可证伪的修复验证方式。

审计 → 报告（根因 + 位置）→ 你确认 → 代理修复 → 验证症状消失

为什么选它？

| 优势 | 对你意味着 |
|---|---|
| 🎭 真实用户视角 | 按人的方式走旅程——机械执行者记录事实，意图观察者加上人的权重 |
| 🗺️ 先画全局结构图 | 派发前先读代码列出每个页面 / 命令 / 场景——不盲目选路径 |
| 👁️ 发现你永远注意不到的 | 猎捕"内部自洽但体验错误"的落差，不只是运行时 bug |
| 🎯 上帝视角归因 | 反事实推理把几十个症状收敛成少数根因——每个都可证伪 |
| 🧮 穷尽而非抽样 | 等价类 + 边界值 + 正交表保证组合不漏，覆盖率可证明 |
| ⚖️ 事实与观点分离 | 执行者只记可证伪事实；观点标为假设，绝不当作发现 |
| 🎲 确定、可复现 | 有界的一组数字人——同输入同输出，没有不可控的意外 |
| 🔄 修循环而非报告 | 以"精准修复 + 验证"收尾，不是"审完了，自求多福" |
| 🧹 发布卫生 + 防御性污染 (独有) | 抓住 AI 特有的病灶：密钥 / PII / 试错痕迹写进代码，以及护栏备注（⚠️ 警告、"别发布"自我提醒）泄漏到公开产物 |
| 🔍 造轮子审计 (独有) | 标出"手搓的、却被成熟开源库吊打"的模块 |
| 🧩 技术栈统一 / 适配收敛 (独有) | 标出"同一个关注点被 N 套平行适配器解决、且从没收敛到一条缝"的病灶（子代理 / 借鉴技术踩的坑） |
| ⚖️ 随项目伸缩 | 轻量 / 标准 / 深度——落地页不做重量级审计 |
| 🔌 接入你的循环 | 一次性 / 每次改动后增量 / 提交前卡点 |

设计哲学

1. 纸面推演是手段，不是目的。 "不执行、不点击"是为了穷尽每条路径——比真点击更快、更全局。最终目的是精准修复——找到少数根因，一次修对，而不是永远打补丁。
2. 穷尽是灵魂；抽样是失职。 一条快乐路径证明不了什么。完整的 数字人 × 功能 × 操作 × 状态 × 时机 矩阵会被遍历，覆盖率可量化、可证明。
3. 代码是唯一事实源。 依据读代码恢复出的行为来推理，而不是文档或记忆。
4. 确定，而非混乱。 代码和状态机是确定的，所以模拟也确定——有界的一组数字人，结果可复现。
5. 事实与观点分离。 执行者只记录可被代码验证的事实（断在 file:line、走 N 步）；意图观察者补上带人类权重的假设，明确标注——绝不与发现混为一谈。
6. 不可证伪就不是发现。 每个根因都必须带验证路径（"若我修好 X，症状 Y 会消失"）。没有验证路径 = 降级为"印象"，绝不当结论上报。

能检测什么

七维能力、再加技术栈统一——几十项检查，一张表看全覆盖：

| 维度 | 检测内容 |
|---|---|
| 🧠 逻辑与状态 | 逻辑矛盾、死分支、死锁、死循环、状态污染、状态残留、缺前置条件、变量被意外覆盖、检查被跳过、竞态 |
| 👤 用户体验 | "内部自洽但体验错误"的落差、认知过载、功能碎片化、缺反馈、"说的 vs 做的"不一致、可发现性、可恢复性、信任建立、心智模型错配、弃用点 |
| 🔒 安全 | SQL 注入、XSS、SSRF、IDOR、越权、命令注入、路径穿越、任意读文件、竞态、提示词注入、越狱（34 类） |
| 🤖 AI 味与可维护性 | 命名的空洞、注释陈词滥调、过度抽象、吞异常、TODO 坟场、过度工程、造轮子、技术过时、比成熟开源还差 |
| 📋 合规与发布 | 软著合规、商店审核门控、缺 EULA/版权声明、密钥泄漏、真实 PII 泄漏、内部信息 / 试错痕迹泄漏、防御性内容污染（纠正 / 警告 / 自我提醒进公开产物） |
| ⚡ 并发与压力 | 多任务并发、竞态、超时、中断、重复提交、快速切换、多子代理冲突 |
| 🔗 跨场景 | 跨场景污染、精确切换、记忆/状态召回正确性、跨模块路由 |
| 🧩 技术栈统一 | 适配收敛失败：同一个关注点被 N 套平行适配器解决 / 1 活 1 死 / 只写不读的能力注册表 / 幽灵枚举值 / 一个事实两个名字或两个单位 / 大库只用了极小部分 |

检查按需触发，不倾倒给你。 审计先问"给谁用、发到哪"并跳过不适用的——不上架就不做商店审核，桌面应用不走移动商店审核。

工作原理

1. 情报接收 — 代理从代码推断项目类型、用户、发布场景，然后只问你代码告诉不了它的（设计意图、真实用户痛点、发布决定）。
2. 项目地图 — 读代码列出每个页面 / 命令 / 场景及其核心旅程，不留猜测空间。
3. 穷尽遍历 — 等价类 + 边界值 + 正交表，在没有组合爆炸的前提下覆盖完整路径矩阵。
4. 两层数字人 — 机械执行者只记事实（断在 file:line、走 N 步、是有意的门还是意外的断）；意图观察者补上带人类权重的假设。
5. 多层检查 — 安全、AI 味、发布卫生、防御性污染、造轮子、技术栈统一 / 适配收敛，外加三方对齐。
6. 上帝视角归因 — 反事实推理把根因与症状分开，并按影响力排序。

快速开始

skills 生态（Claude Code / Codex / Cursor / 其他代理）
npx skills add kevinshi3200/persona-auditor

或手动：把 SKILL.md 复制到你的代理技能目录
例如 ~/.agents/skills/persona-auditor/SKILL.md

然后用自然语言触发：

"Audit this project with Persona Auditor."
"审计这个项目" / "找 bug" / "推演" / "验收" / "出包前检查"

你得到： 一份报告，结论是少数根因 + 按影响力排序的修复方向——每条带 file:line 和可证伪的验证方式——而不是几十条摊平的清单。

对比

|  | 代码评审 | 端到端 / 点击测试 | 混沌多代理 | Persona Auditor |
|---|---|---|---|---|
| 视角 | 代码逻辑 | 机器操作 | 突发代理 | 真实用户 |
| 发现 | 代码质量 | 运行时 bug | 不可预知 | "内部自洽但体验错误"的落差 + 你永远注意不到的 bug |
| 根因 | 单点 | 单点 | 不明确 | 上帝视角反事实归因（少数根因） |
| 覆盖 | 抽样 | 一次一条路径 | 混沌 | 穷尽、可证明的覆盖 |
| 成本 | 便宜、浅 | 昂贵 | 不可预知 | 便宜 + 全局 + 可复现 |

局限

- 审计期间只读 — 从不改代码（避免污染现场）。修正在循环里，你确认后才进行。
- 不能读二进制 / 逆向，不能替代真实 UI 视觉检查，不能替代真实执行回归。
- 纸面推演揭示的是规范层矛盾；若实际运行时行为和代码所暗示的不同，会标出这个缺口并回喂给模型。

FAQ

会不会把我淹没在 findings 里？
不会。检查按发布场景按需触发，最终报告收敛到按影响力排序的少数根因，不是一堵症状墙。

是确定的，还是又一个混沌多代理模拟？
确定的。代码和状态机是确定的，所以它用有界的一组数字人（≤10，每组合一个）——可复现、可预测。

它会改我的代码吗？
审计期间不会。你确认报告后，同一个代理按报告精准修复，并验证症状消失。

小项目会不会被重度审计？
不会。它按深度分层——🟢 轻量（落地页 / 个人工具）、🟡 标准（多数项目）、🔴 深度（上架 / 敏感数据 / 代理系统）——只跑项目真正需要的。

作者与反馈

- 作者： kevinshi3200
- 邮箱： 915538592@qq.com
- 问题 / 反馈 / 需求： 开一个 issue

许可证

MIT