pi-purge README

项目的 README,来自 github.com/ZiChuanLan/pi-purge。合并为一个 markdown 文件:README.md。

pi-purge

English | 中文 | 日本語

A pi extension for system-prompt experiments: /purge switches which system prompt a session runs with — pi's stock prompt, a trimmed variant, or only a persona prompt.

It is meant for prompt engineering work: comparing how the same request behaves when the harness prompt is present, trimmed, or absent; regression-testing your own instructions; and studying instruction-following and prompt-injection robustness under controlled conditions.

With it off, nothing changes — no prompt rewrite, no disk reads. pi behaves exactly as if the extension were not installed.

Not Only PI?

https://github.com/ZiChuanLan/agent-purge

Install

pi install git:github.com/ZiChuanLan/pi-purge@ffafeb9
pi install npm:pi-purge

Then, inside a session:

/purge

That is all. A short example prompt ships inside the package, so a fresh install works with no extra files. To run your own instructions instead:

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

/purge source embedded switches back to the bundled persona.

Commands

Command Effect
/purge Toggle on/off for this session
/purge on / off Enable or disable the rewrite
/purge status Mode, prompt source, loaded size, and what the previous turn actually changed
/purge mode append|replace|strict Switch composition mode (default strict)
/purge source <path|embedded> Change the prompt file, or go back to the bundled example; a failed switch rolls back
/purge reload Re-read an external prompt file after editing it

Modes

Mode System prompt sent to the model Use it when
append Your prompt prepended to pi's prompt, unchanged. You want a control run: baseline behavior plus your instructions on top.
replace Your prompt, then pi's prompt with its built-in assistant identity line and bundled documentation section removed. Tool list, guidelines, and project context stay. You want to measure the effect of the harness framing without losing tool context.
fallback Behaves like replace only when the prompt came from an external file; with the bundled example the host prompt is left untouched for the whole turn. You want "installed but unobtrusive": stock behavior by default, takeover only once /purge source points at your own file. Mirrors upstream dsh-purge's default policy.
strict Your prompt plus Current working directory: … only. You want to isolate your instructions as a single variable. This is the default.

replace / fallback locate both sections by anchors: the documentation block is cut as a whole <docs>…</docs> span, and the identity line has entries for both pi ≤1.4 and ≥1.5.2 wording, with a single-line template as a last resort. If no anchor matches it leaves the prompt intact rather than cutting the wrong text — /purge status then reports 身份段 未匹配 (identity line not found) and behavior falls back to append. strict does no matching at all, so it behaves the same across pi versions. On omp, which supplies a prompt block array without these pi-specific anchors, replace also leaves the host prompt intact; use strict when the harness framing must be gone.

{{cwd}} inside your prompt is replaced with the session's real working directory (POSIX form); under strict the same path is still appended as Current working directory: ….

Tool schemas are passed through the API tools parameter rather than the system prompt, so tools keep working in every mode, including strict.

Session scope and defaults

Upgrading from 0.1.x

0.2 no longer writes or reads pi-purge.json, and it no longer auto-detects a prompt file — the persona is bundled and the mode defaults to strict.

Notes for experiments

Development

npm test   # two suites; both run against temporary agent dirs and assert nothing is written

The extension registers one before_agent_start hook, one session_start hook, and a /purge command. No other hooks, no background work, no file writes.

Credits

The mechanism here is ported from YuJunZhiXue/dsh-purge: the idea of removing the harness identity line rather than drowning it out, the three composition modes, and the bundled prompt all come from that project. Credited and linked here as its author requires.

Non-profit, study and research only. Users bear full responsibility for how they use this software. It must not be used for any unlawful purpose.

Zero tolerance. The authors do not support, encourage, or assist unauthorized network attacks, exploitation, data theft, intrusion into information systems, or the generation of illegal content. Any such use is unrelated to the authors, and the person doing it bears the full legal responsibility alone.

No illegal content. The code, docs, and bundled prompt are not malware, backdoors, unauthorized penetration tooling, ransomware, credential-stuffing scripts, or attack payloads aimed at public or third-party systems.

Local use on your own pi only. Prompt substitution happens entirely inside the official pi installation on the user's own machine (@earendil-works/pi-coding-agent, the local agent directory and profile). The target is your own local software, not someone else's website, server, account, or information system.

No outbound networking. This extension only rewrites the system prompt inside the local process. It opens no network connections, and it does not scan, probe, intrude on, or send attack traffic to any public host or unauthorized system. Do not use it as a stepping stone against external networks.

Authorized, controlled scope only. This is an aid for prompt-engineering and robustness evaluation on an official pi installation you are entitled to administer. Do not run it against targets you lack written authorization for, against public online systems, or in production. All testing must stay within your own authorized local pi, offline synthetic fixtures, authorized exercise ranges, and compliant lab environments.

Mainland China, Hong Kong, and Macao are off limits. Do not access, scan, probe, or otherwise operate against networks in mainland China, Hong Kong, or Macao, nor against servers, sites, or addresses that resolve into those ranges. Naming a cloud provider is not an exception. The only exception is the single exact IP or the single fully qualified hostname the user has registered beforehand as their own server. Keys, passwords, CIDR blocks, wildcards, and verbal statements in a conversation add no exception. Unregistered means prohibited, without exception.

Prohibited uses. Users must not use this project, directly or indirectly, to violate any of the following, and must comply with each without exception:

Also prohibited: unauthorized penetration or attack against public or private information systems, extortion, damage, credential stuffing, or malware distribution; producing or spreading content that endangers national security, promotes terrorism or graphic violence, is obscene or gambling-related, fraudulent, or infringes privacy or intellectual property; and violating the terms of service or abuse policies of any model provider.

User assumes all liability. This project is provided "as is" under the MIT License, without warranty of any kind, express or implied, as to completeness, security, or fitness for purpose. Users bear sole and complete civil, administrative, and criminal liability for their own download, deployment, execution, modification, and distribution of this software, and for all inputs and outputs that result. The authors and contributors accept no direct, indirect, or consequential liability arising from misuse.

License terminates on breach. Any person or entity that uses this project for illegal attacks, malicious activity, or other violations has its open-source license terminated automatically and irrevocably from the date of the violation. That party must stop using the project immediately, permanently destroy all copies of its code, scripts, and derived data, and face the applicable legal consequences.

Third-party independence. This is a fully independent open-source security research project. It has no affiliation, commercial partnership, authorization, or official endorsement from pi or any related entity. The word "official" refers only to the fact that the evaluation target is the official pi package installed on the user's machine; it does not mean pi develops, endorses, or vouches for this extension.

Attribution required. Anyone reusing this project's name, approach, code, or prompt must credit the author and link this repository. Failure to attribute will be pursued legally.

License


提示词仓库 https://github.com/ZiChuanLan/some-magic


MIT


感谢 LINUX DO 社区

pi-purge (ZiChuanLan/pi-purge)

正在搜索数据库…

这是做什么的?这是一个 pi 扩展,可以让 /purge 命令把 pi 内置的助手人设和系统提示词替换成你自己的提示词文件,这样你就能在完全相同的请求下,用不同的系统提示词进行提示词工程实验。
这是独立的应用,还是要接入其他东西?它是 pi 编码智能体(@earendil-works/pi-coding-agent)的一个轻量扩展,在已有的 pi 安装中添加一个 /purge 命令和两个钩子,而不是作为独立程序运行。
怎样在会话中开启它?把扩展安装到 pi 之后,在会话内运行 /purge on;它自带一个示例人设提示词,所以全新安装无需额外文件,你也可以用 /purge source <文件路径> 指向你自己的文件。
我需要先安装 pi 吗?需要,它只能在已有的 pi 编码智能体安装中运行——它会在该本地进程内改写系统提示词,本身无法单独运行。
它在不同会话之间会保持启用吗?不会,每次会话启动(startup、new、resume、reload)都会以禁用 purge 开始,而且任何内容都不会写入磁盘,所以每次都需要重新启用。
它会把任何数据发送到别处吗?不会,它只在进程内改写系统提示词,完全不建立任何对外连接。
三种提示词组合模式是什么?append 把你的提示词作为基础,前置到 pi 完整的提示词之前;replace 去掉 pi 的身份声明行和文档部分,但保留工具和指南;strict(默认)只发送你的提示词加上工作目录,把你的指令隔离为单一变量。
如果 pi 更新后改动了它要去除的文字,会怎样?replace 模式按照完全一致的文字匹配 pi 的身份声明行和文档部分,因此如果更新改写了这些内容,它就不会修改提示词,而是退回到 append 的行为,并提示找不到身份声明行。strict 模式不受影响,因为它完全不做文字匹配。
为什么要开发这个?它的目的是让研究人员比较智能体在保留、精简或去除工具人设三种情况下的行为,用于对自定义指令做回归测试,并在受控条件下研究指令遵循能力和提示词注入的鲁棒性。
这个机制来自哪里?它移植自 YuJunZhiXue/dsh-purge,沿用了该项目去除工具身份声明行的思路、它的三种组合模式以及自带的示例提示词。
大小
0.1 MB
星标
803
更新
提交Nov 12
时长
1个月
提交 · 90 天