pi-pua-x

英文版本 | 中文版本

pi 的状态化 PUA 运行时扩展 —— 生命周期钩子、压力升级、能力感知增强与子代理继承。基于 tanweai/pua 构建。

这是什么？

pi-pua-x 是 pi 中 PUA 行为协议的程序化运行时。与依赖模型"记住"规则的静态技能文件不同，此扩展利用 pi 的生命周期钩子以确定性方式强制执行行为：

⚠️ 两个模块：本扩展只替换 hooks，不替换 skill

PUA 由两个独立模块组成，完整体验两者缺一不可：

模块	是什么	谁维护	pi-pua-x 提供？
skill	静态规则文件（SKILL.md + references/：flavors、methodology）。模型读取这些文件获取 PUA 文化/内容。	上游 tanweai/pua —— Claude Code 用完整版，其他 CLI 用最小版	❌ 否
hooks	程序化运行时（生命周期钩子、失败追踪、压力升级、强制执行）。	官方只维护 hooks 作为 pi 适配器；pi-pua-x 是其增强替代版。	✅ 是（本仓库）

这就是为什么装了 pi-pua-x 之后，你还需要安装/同步官方 tanweai/pua skill： pi-pua-x 只替换了 hooks 那一半。skill 那一半（模型实际读取的 flavor/methodology 文本）仍由上游 tanweai/pua 提供。没有 skill，hooks 照跑，但模型没有规则内容可依据（扩展会回退到内置最小集；若完全找不到 skill 则会自动禁用 PUA）。

➡️ 安装顺序：（1） 部署 tanweai/pua skill → （2） 安装 pi-pua-x（hooks）→ （3） 运行 /pua-x-sync-skills 保持 skill 的 references/ 更新。详见 INSTALL.md。

能力	实现方式
失败追踪	tool_result 事件 → 持久化计数器存储于 ~/.pua/.failure_count
压力升级	基于失败次数，通过 before_agent_start 注入 L1–L4 提示
能力感知	读取活跃工具/技能，仅增强实际可见的能力
子代理继承	tool_call 拦截 → 将 PUA 胶囊注入子代理提示
挫败检测	input 事件 → 检测到用户挫败信号时自动升级
循环检测	turn_end + tool_call → 阻止重复失败的命令
完整性守卫	tool_call → 阻止写入隐藏测试 / 污染目标
紧凑状态保存	session_before_compact → 在上下文压缩前持久化状态

与官方 @tanweai/pi-pua 的区别

官方 pi 适配器（约 100 行）仅提供基础的提示注入和计数。本扩展提供：

1. 完整风味系统 —— 13 种方法论 + 路由 + Banner 协议 + 失败切换链
2. 能力感知 —— 基于实际 PI 活跃工具进行增强，从不假设不可见工具
3. 主动强制执行 —— tool_call 拦截、input 挫败检测、turn_end 循环检测、session_before_compact 状态保存
4. 子代理治理 —— 胶囊注入确保子代理继承 PUA 约束

关系：替代，而非叠加。两个扩展无法共存（命令/钩子冲突）。

安装

所有安装方式、配置说明、命令参考、基线插件和故障排查，请参见 INSTALL.md。

README 中不再重复安装步骤，避免文档双轨维护导致信息不一致。

命令

命令	说明
/pua-on	启用 PUA（写入 always_on=true，立即生效）
/pua-off	禁用 PUA（写入 always_on=false）
/pua-status	显示状态、失败计数、压力等级、风味、能力
/pua-reset	将失败计数器重置为零
/pua-model list	列出被排除 PUA 的模型模式
/pua-model disable <pattern>	禁用指定模型的 PUA（如 anthropic/claude-opus*）
/pua-model restore <pattern>	恢复指定模型的 PUA（移出禁用列表）
/pua-x-sync-skills	同步 skill 模块的上游 tanweai/pua references（flavors、methodology 等）。本扩展是 hooks 模块，不捆绑 skill —— 见本 README 顶部的**「两个模块」**高亮说明。

模型兼容性

PUA 的生效依赖「话语施压 + 确定性 hook 强制」。新一代前沿模型被明确训练为抵抗情感操纵——而这恰恰就是 PUA 式施压的本质：

• Anthropic 从 Opus 4.5 / 4.6+ 起专门训练模型抵抗谄媚与情感操纵（系统提示明文要求 "Be direct; avoid ungrounded or sycophantic flattery"）。官方自动化审计显示其谄媚率比 Opus 4.1 低 70–85%，并设有专门的「妄想性谄媚」评估——要求模型在对话中途主动纠偏，而非仅在一开始拒绝。
• Anthropic 还训练了指令层级（系统提示 > 用户输入）与提示注入防御：施压语言被视为「待评估的内容」而非「必须服从的权威」。Opus 4.8 甚至出现过度防御——anthropics/claude-code #67606 记录了它在长会话中凭空编造「提示词注入攻击」叙事。
• 上游 tanweai/pua 没有按模型的兼容性矩阵（兼容性按平台划分），但社区普遍观察到 Opus 系列上 PUA「不触发 / 不表演」——Opus 对施压式话术的顺从度更低。此外，Opus 4.8 的工具调用序列化缺陷（anthropics/claude-code #67307、#63481）会破坏本运行时依赖的确定性 hook 链路——这是工程层的失效，而不只是说服层失效。
• 高阶模型对 PUA 的依赖本身也在下降（推论，非官方表述）：高自主性（不放弃、穷尽方案、验证后才宣称完成）已是它们的默认训练行为，外部施压换不来额外行为增益，只是上下文里的噪音。

结论：在这些模型上，PUA 注入要么无效、要么有害——白白消耗 token、损耗信任，却换不来行为收益。/pua-model 让 PUA 成为按需开关：在真正能获得行为增益的模型上保持开启，对既不响应施压也不需要它的高阶模型（glob 模式，如 anthropic/claude-opus*）直接排除。被禁用的模型执行 L2 完全禁用：不注入协议、不挂任何 hook、完全静默。匹配逻辑详见 docs/DESIGN.md。

配置

~/.pua/config.json：

{
  "always_on": true,
  "flavor": "alibaba",
  "enforcement_level": "suggest",
  "integrity_guard": true,
  "frustration_detection": true,
  "loop_detection": true,
  "compact_state_save": true
}

支持的风味

alibaba（默认）、bytedance、huawei、tencent、baidu、pinduoduo、meituan、jd、xiaomi、netflix、tesla/musk、apple/jobs、amazon

文档

文档	用途
INSTALL.md	安装、命令、配置、同步、集成测试
docs/CAPABILITIES.md	PI 能力模型与可见性规则
docs/DESIGN.md	内部架构与契约
docs/UPSTREAM.md	tanweai/pua 上游同步策略
docs/RECOMMENDATIONS.md	推荐的 PI 插件组合
docs/research/model-compat.md	模型兼容性调研证据档案：为何新一代模型抵抗 PUA、为何需要按模型禁用

文件结构

pi-pua-x/
├── index.ts                 # 扩展入口
├── capabilities.js          # 能力快照 + 增强提示
├── enforcement.ts           # 4 个强制执行钩子逻辑
├── references_loader.ts     # 风味/方法论/压力加载器
├── global.d.ts              # PI 扩展 API 的类型存根
├── tsconfig.json            # TypeScript 配置（仅类型检查，不输出）
├── INSTALL.md               # 安装指南
├── bin/
│   ├── sync-pua-references.sh
│   └── sync-pua-references.ps1
├── docs/
│   ├── CAPABILITIES.md
│   ├── DESIGN.md
│   ├── RECOMMENDATIONS.md
│   ├── UPSTREAM.md
│   └── plans/
└── integration-tests/
    ├── pua.ittest.sh        # 集成测试（bash）
    ├── pua.ittest.ps1       # 集成测试（PowerShell）
    └── pua-enforcement.ittest.ps1

许可证

MIT