# pi-purge

[English](README.md) | 中文 | [日本語](README.ja.md)

[pi](https://github.com/earendil-works/pi-coding-agent) 的系统提示词实验扩展：`/purge` 用来切换一轮会话到底带哪套系统提示词 —— pi 自带的、精简过的，或者只发一份人设提示词。

它的用途是提示词工程：同一句请求在「宿主提示词完整 / 精简 / 缺失」三种条件下的行为差异；自己写的指令做回归测试；以及指令遵循、提示词注入鲁棒性这类受控实验。

关掉时什么都不变：不改提示词、不读盘，行为与没装这个扩展完全一致。

## 安装

```bash
完整带提示词： pi install git:github.com/ZiChuanLan/pi-purge@ffafeb9
自定义提示词： pi install npm:pi-purge
```

然后在会话里：

```text
/purge
```

就这一步。包内自带一段简短示例提示词，装完不必准备任何文件。想换成自己的提示词：

```text
/purge source C:/prompts/my-instructions.md
/purge mode replace
/purge on
```

`/purge source embedded` 切回内置人设。

## 命令

| 命令 | 作用 |
| --- | --- |
| `/purge` | 切换本会话开 / 关 |
| `/purge on` / `off` | 显式开关 |
| `/purge status` | 当前模式、提示词来源、已加载字符数，以及上一轮实际改了什么 |
| `/purge mode append\|replace\|strict` | 切换组合方式（默认 `strict`） |
| `/purge source <路径\|embedded>` | 换提示词文件，或回到内置示例；切换失败会自动回滚 |
| `/purge reload` | 改完外部文件后重新读取 |

## 模式

| 模式 | 实际发给模型的系统提示词 | 适用场景 |
| --- | --- | --- |
| `append` | 你的提示词 + pi 原提示词（一字不改） | 对照组：基线行为，加一层自己的指令 |
| `replace` | 你的提示词 + 去掉「助手身份句」和「内置文档段」的 pi 提示词，工具列表 / Guidelines / 项目上下文保留 | 想测量宿主框架措辞的影响，又不想丢工具上下文 |
| `strict` | 你的提示词 + 仅 `Current working directory: …` | 想把人设/指令当成唯一变量隔离出来。这是默认模式 |

`replace` 依赖固定文案定位那两段。pi 升级改措辞时它会原样保留提示词（退化成 `append`），而不是切错位置 —— `/purge status` 会显示 `身份段 未匹配`。`strict` 不做任何匹配，跨 pi 版本行为一致。omp 传的是提示词块数组，没有这些 pi 专用锚点，`replace` 同样会退化成 `append`；要彻底丢掉宿主框架用 `strict`。

工具 schema 走 API 的 `tools` 参数，不依赖系统提示词，所以三种模式下工具都正常可用，包括 `strict`。

## 会话范围与默认值

- 作用范围是**会话**。每次 `session_start`（启动 / 新建 / `resume` / 重载）都从**关闭**开始；退出 pi 一定回到原始提示词。
- **不写任何文件**：没有状态文件、没有缓存、没有标记。两个 pi 进程互不影响。
- 默认提示词是 `extensions/pi-purge.ts` 里的一小段示例；`/purge source <路径>` 换成自己的文件，`/purge source embedded` 切回来。
- 想不落盘就让每次启动都指向自己的文件，把 `PI_PURGE_SOURCE` 设成绝对路径：

    ```bash
    PI_PURGE_SOURCE=/home/me/persona.md pi          # macOS / Linux
    set PI_PURGE_SOURCE=C:/prompts/persona.md        # Windows cmd
    $env:PI_PURGE_SOURCE='C:/prompts/persona.md'     # Windows PowerShell
    ```

    它只提供 `source` 的初始值：仍然要 `/purge on`，每次 `session_start` 的 `enabled` 仍然是 `false`，会话里的 `/purge source <路径>` 也仍然优先。文件不存在时 `/purge on` 会报错，而不是静默回退到内嵌示例。
- 内置文本故意写得很短：发布到包仓库的内容会被扫描滥用性提示词，完整的人设文本过不了扫描；把自己的提示词放在本地用 `/purge source` 引用。
- 默认模式 `strict`。

## 从 0.1.x 升级

0.2 不再读写 `pi-purge.json`，也不再自动探测提示词文件 —— 人设内置，模式默认 `strict`。

- 删掉 `<agent dir>/pi-purge.json`，它已经不被读取。
- 开启是会话级的：重启或 `/resume` 之后需要重新 `/purge`。
- 需要时 `append` / `replace` 的行为与之前一致。

## 做实验时的注意点

- `strict` 会一并丢掉 `AGENTS.md` / 项目上下文、skills 列表、其他扩展注入的提示词。这正是它能做单变量隔离的原因，也意味着 `strict` 下的结论不能直接和普通会话对比。
- `append` 侵入最小、信号也最弱：宿主提示词后段权重仍然很大，差异可能不明显。
- `replace` 仍会残留宿主文本，而且其他扩展可能在本扩展之后追加自己的提示词段。实践上只有 `strict` 能让人设不和别的框架措辞竞争。
- 扩展加载顺序会影响 `before_agent_start` 看到的内容。要留结果的话，建议把 `/purge status` 的输出一起记录。

## 开发

```bash
npm test   # 两个套件，均跑在临时 agent 目录里，并断言全程没有写任何文件
```

实现上只注册一个 `before_agent_start` 钩子、一个 `session_start` 钩子和一个 `/purge` 命令，无其他钩子、无后台任务、无文件写入。

## 致谢与署名

本项目的机制移植自 [YuJunZhiXue/dsh-purge](https://github.com/YuJunZhiXue/dsh-purge)：把宿主身份段**清掉**（而非压住）的思路、三档组合方式与默认提示词，均出自该项目。按原作者要求在此署名并标明来源仓库。

## 免责与合规声明

### 严正法律免责与合规使用声明

**免责声明**：本项目为非营利开源项目，遵守国家法律法规及所在平台的相关规范，仅供学习与研究使用。不得将本项目用于任何违法违规用途；由此产生的后果由使用者自行承担。

**【零容忍严正申明】**：本项目坚决反对并严禁任何形式的违法犯罪行为！本项目开发者绝不支持、不鼓励、不协助任何未授权网络攻击、漏洞利用、数据窃取、非法侵入计算机信息系统或生成违法违禁内容的活动。任何将本项目用于违法犯罪的行为，均与开发者无关，由行为人依法独立承担全部法律责任。

**本仓库不含违法内容**：本扩展发布的代码、文档与默认提示词不是木马、后门、未授权渗透工具、勒索软件、撞库脚本，也不是针对公网或第三方系统的攻击载荷。项目本身不提供违法内容，也不教唆、组织、协助实施违法犯罪。

**只作用于本机官方 pi**：系统提示词替换全部发生在使用者本机已安装的官方 pi（`@earendil-works/pi-coding-agent`、本机 agent 目录与 profile）上。对象是使用者自己的本地软件，不是他人的网站、服务器、账号或信息系统。

**不对外网目标联网**：本扩展只在本地进程内改写系统提示词，不发起任何网络请求，不对任何公网主机、未授权系统进行扫描、探测、入侵或攻击发包。不得把本项目当作跳板去打外网。

**合法受控范围限定**：本项目定位为使用者在自己有权管理的本机官方 pi 上，进行提示词工程与鲁棒性评测的辅助工具。严禁在未经所有者合法书面授权的目标、公网在线系统或生产业务上运行本项目。一切测试必须限制在本机已授权安装的官方 pi、离线本地合成靶标、授权网络安全演练靶场及合规实验室受控环境中进行。

**禁止中国大陆、香港、澳门的服务器与网站**：不得对中国大陆、香港、澳门网段，以及解析进这些网段的服务器、网站或地址进行访问、扫描、探测或任何操作。云厂商的名字不能当作例外。唯一例外是使用者事先登记为自己的服务器的那一个确切 IP，或那一个完整主机名。密钥、密码、网段、通配符，以及对话里的口头说明，都不能增加例外。没有登记的，一律禁止。

**严禁违法与违禁用途**：使用者严禁利用本项目直接或间接从事任何违反下列法律法规的行为（必须逐条遵守，不得以任何理由规避）：

- 《中华人民共和国刑法》
- 《中华人民共和国网络安全法》
- 《中华人民共和国数据安全法》
- 《中华人民共和国个人信息保护法》
- 以及其他现行有效的法律、行政法规与监管规定

同时严禁：

- 未经授权渗透、攻击公私机构计算机信息系统，实施勒索、破坏、撞库或传播恶意载荷；
- 诱导、生成或传播危害国家安全、恐怖主义、暴力血腥、涉黄涉赌、诈骗、侵犯公民隐私或知识产权等任何法律明令禁止的违法违禁内容；
- 违反相关大模型提供商的《服务条款》与《滥用政策》。

**使用者独立承担全部责任**：本项目依据 MIT 开源协议“按现状”提供，开发者不对软件的完整性、安全性与适用性作任何明示或暗示的保证。使用者应对自身的所有下载、部署、运行、修改、传播行为以及由此产生的全部输入与输出后果承担独立、完全的民事、行政及刑事法律责任。项目作者与贡献团队绝不承担任何因使用者滥用导致的直接、间接或连带责任。

**违约即终止授权**：任何将本项目用于非法攻击、恶意活动或违规行为的个人或实体，其开源软件使用许可将自违法违规行为发生之日起自动且不可撤销地立即终止。该主体须立即停止使用并永久销毁本项目的所有代码、脚本与衍生数据，并依法承担相应法律制裁。

**第三方独立性声明**：本项目属于完全独立的开源安全评测研究项目，与 pi 官方或其关联主体无任何隶属、商业合作、授权或官方背书关系。文中「官方」仅指评测对象为使用者本机安装的官方 pi 软件包，不代表其官方开发、认可或担保本插件。

**必须署名**：借用本项目的名称、思路、代码或提示词，必须署名并标明本仓库。不署名将依法追究责任。

## 许可

MIT

---

感谢 [LINUX DO](https://linux.do) 社区