pi-information-protecter 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,23 +1,54 @@
-# Changelog
+# Changelog / 更新日志
 
-## 0.1.0 — 2026-09-18
+## 0.2.0 — Machine configuration and memory cache / 机器配置与内存缓存
 
-首个公开版本：**个人敏感信息保护插件 — Sensitive Personal Information (SPI) Protecter**。
+- Derive deterministic filenames from OS machine identifiers using a product-specific hash; never fall back to random IDs.
+  使用产品专用哈希派生确定性机器配置名称，不回退随机标识。
+- Validate and union-merge legacy/previous-machine configs before durable target writes and verified old-file deletion, with locking and retry-safe cleanup.
+  校验并合并旧名称及旧机器配置，持久化验证目标后删除旧文件，支持锁与可重试清理。
+- Cache rules at startup/reload; outgoing requests and status no longer read configuration files. Loaded protection survives file edits or deletion.
+  启动和重载时缓存规则，出站请求和状态不再读配置；加载后的防护不受文件修改或删除影响。
+- Make `/protecter reload` invoke Pi reload; check file-tool target paths instead of documentation content.
+  重载命令调用 Pi 重载，文件工具改为检查目标路径而非文档正文。
+- Add migration, failure-injection, concurrency and cache regression tests, plus bilingual migration documentation.
+  增加迁移、故障注入、并发及缓存回归测试和双语迁移文档。
 
-### 新增
 
-- Pi 最终 provider 请求体的本地脱敏，覆盖系统提示、历史、工具结果及工具定义。
-- `protecter.json` 敏感词数组、字面匹配及 JavaScript 正则表达式。
-- 随机 192-bit 占位符、仅内存映射、最终回复及工具参数本地还原。
-- TUI Markdown 流式展示还原；已学习敏感值在当前实例内继续按精确值保护。
-- 配置文件 0600 权限及直接访问防护，配置异常与扫描超时的安全替代请求。
-- Worker 正则扫描与资源限制；`/protecter status` 和 `/protecter reload`。
-- 配置示例、安全边界说明及自动化测试，包括真实 Pi loader/runner 集成测试。
+- Add tag-triggered GitHub Actions npm OIDC publishing, scoped environment permissions and manual dry-run validation.
+  增加标签触发的 GitHub Actions npm OIDC 发布、限定环境权限及手动试运行验证。
+- Document trusted publisher setup and the automated release procedure in both languages.
+  以双语记录可信发布配置和自动发布流程。
 
-### 兼容性与已知限制
+## 0.1.0 — Initial release / 首个版本
 
-- Node.js 22+，Pi `@earendil-works/pi-coding-agent` 0.85.1–0.85.x；验证基线 0.85.1。
-- 初始规则为空，需用户本地配置；不会自动识别所有 SPI。
-- 暂不支持上下文压缩、带摘要的树导航及常见多模态附件。
-- RPC/JSON 流式 delta 保留占位符，最终消息还原；映射不会跨进程保存。
-- 不是沙箱；不防任意 shell 编码绕过，不覆盖独立网络调用、HTTP 认证 headers、本地会话及导出。详见 SECURITY.md。
+**Sensitive Personal Information (SPI) Protecter — 个人敏感信息保护插件。**
+
+### Added / 新增
+
+- Local masking of final Pi provider request bodies, including system prompts, history, tool results and definitions.
+  本地脱敏 Pi 最终请求体，覆盖系统提示、历史、工具结果和工具定义。
+- `protecter.json` sensitive-word arrays, literal matching and JavaScript regular expressions.
+  配置文件敏感词数组、字面匹配及 JavaScript 正则表达式。
+- Random 192-bit placeholders, memory-only mappings and local final-response/tool-argument restoration.
+  随机 192-bit 占位符、仅内存映射及最终回复和工具参数本地还原。
+- TUI Markdown streaming restoration and continued exact-value protection for learned secrets.
+  TUI Markdown 流式展示还原，以及已识别敏感值的持续精确匹配保护。
+- Unix 0600 configuration permissions, direct-access guards and safe replacement payloads on configuration errors/timeouts.
+  配置文件 Unix 0600 权限、直接访问拦截，以及配置异常和超时时的安全替代请求体。
+- Worker regex execution limits; `/protecter status` and `/protecter reload`.
+  worker 正则执行限制，以及状态和重载命令。
+- Configuration examples, security guidance, bilingual documentation/comments and automated tests including real Pi loader/runner integration.
+  配置示例、安全说明、双语文档和注释，以及包含真实 Pi 加载器／执行器集成的自动化测试。
+
+### Compatibility and limitations / 兼容性与限制
+
+- Node.js 22+ and Pi `@earendil-works/pi-coding-agent` 0.85.1–0.85.x; tested with 0.85.1.
+  要求 Node.js 22+ 和该范围的 Pi，验证基线为 0.85.1。
+- Empty initial rules require local configuration; not an automatic SPI detector.
+  初始规则为空，需本地配置，不自动识别全部个人敏感信息。
+- Compaction, summarized tree navigation and common multimodal attachments are not supported.
+  暂不支持压缩、带摘要的树导航和常见多模态附件。
+- RPC/JSON deltas keep placeholders until final restoration; mappings are not persisted across processes.
+  RPC/JSON 增量保留占位符直到最终还原，映射不跨进程保存。
+- Not a sandbox: arbitrary shell encoding can bypass protection. Independent networking, authentication headers, local sessions and exports are outside coverage. See SECURITY.md.
+  不是沙箱，任意 shell 编码可绕过防护；独立联网、认证头、本地会话和导出不在保护范围，详见安全文档。

package/README.md

@@ -1,32 +1,57 @@
 # pi-information-protecter
 
-**个人敏感信息保护插件 — Sensitive Personal Information (SPI) Protecter。**
+**Sensitive Personal Information (SPI) Protecter — 个人敏感信息保护插件。**
 
-这是一个 Pi 扩展：在本地审查即将发往 LLM 网关的请求，用随机占位符替换配置中的个人敏感信息；模型返回占位符后，在本地还原为原始内容。可用于 URL、电话号码、身份证／ID、姓名、凭证、密码等。**它是规则驱动的意外泄漏防护，不是安全沙箱、自动 PII 识别器或加密代理。**
+A Pi extension that inspects outgoing LLM request bodies locally, replaces configured sensitive values with random placeholders, and restores echoed placeholders locally. Suitable for URLs, phone numbers, identity numbers, names, credentials and passwords. **This is rule-based accidental-disclosure protection, not a sandbox, automatic PII detector or encryption proxy.**
 
-## 安装
+这是一个 Pi 扩展：在本地审查 LLM 出站请求体，用随机占位符替换配置中的敏感值，并在本地还原模型返回的占位符。适用于 URL、电话号码、身份证／ID、姓名、凭证和密码。**这是基于规则的意外泄漏防护，不是沙箱、自动 PII 检测器或加密代理。**
 
-要求 Node.js 22+、`@earendil-works/pi-coding-agent` **0.85.1–0.85.x**（验证基线 0.85.1）。旧 `@mariozechner/*` 版本不在兼容范围内。
+## Installation / 安装
+
+Requires Node.js 22+ and `@earendil-works/pi-coding-agent` **0.85.1–0.85.x**, tested against 0.85.1. Legacy `@mariozechner/*` releases are not supported.
+
+要求 Node.js 22+ 和 `@earendil-works/pi-coding-agent` **0.85.1–0.85.x**，验证基线为 0.85.1。不支持旧 `@mariozechner/*` 版本。
 
 ```bash
-# 安装首个版本（固定版本便于复现）
-pi install npm:pi-information-protecter@0.1.0
+# Install the published, pinned npm release. / 安装已发布的固定 npm 版本。
+pi install npm:pi-information-protecter@0.2.0
 
-# 或在源码仓库内本地安装；本地路径安装不会复制仓库
+# Alternatively, install from this repository without copying it. / 或从本仓库本地安装，不复制仓库。
 pi install "$PWD"
-# 或单次加载
+
+# Load for one invocation. / 单次加载。
 pi -e ./src/index.ts
 ```
 
-已运行的 Pi 请执行 `/reload`。插件注册了 worker，因此分发时需要保留完整 `src/` 目录，不能只复制 `index.ts`。
+Run `/reload` in an existing Pi session. Keep the complete `src/` directory when distributing this extension: the worker file is required, so copying only `index.ts` is insufficient.
+
+已运行的 Pi 请执行 `/reload`。分发时保留完整 `src/` 目录；插件需要 worker 文件，不能仅复制 `index.ts`。
+
+See [CHANGELOG.md](CHANGELOG.md) for version changes. Contribution and release instructions are in the repository's `CONTRIBUTING.md` and `docs/RELEASING.md`.
+
+版本变更见 [CHANGELOG.md](CHANGELOG.md)。贡献与发布流程见仓库内的 `CONTRIBUTING.md` 和 `docs/RELEASING.md`。
+
+Maintainers publish new versions by pushing matching `v*` tags. GitHub Actions validates and publishes through npm OIDC trusted publishing without a long-lived token. Manual dry runs do not publish.
+
+维护者通过推送匹配版本的 `v*` 标签发布新版本。GitHub Actions 验证后使用 npm OIDC 可信发布，不需要长期令牌；手动试运行不会发布。
+
+Initialization uses `~/.pi/agent/protecter.<machineHash>.json`, respecting `PI_CODING_AGENT_DIR`. The hash is the first 32 hex characters of SHA-256 over a product prefix and normalized OS ID: macOS `IOPlatformUUID`, Linux `/etc/machine-id`, Windows `MachineGuid`. Missing/invalid IDs fail initialization, without random fallback. The hash is a stable identifier, not a secret. Project-local configuration is not loaded.
+
+初始化使用 `~/.pi/agent/protecter.<machineHash>.json`，遵循 `PI_CODING_AGENT_DIR`。哈希由产品前缀与规范化系统标识计算 SHA-256，取前 32 位十六进制；macOS 使用 `IOPlatformUUID`、Linux 使用 `/etc/machine-id`、Windows 使用 `MachineGuid`。标识缺失或无效时拒绝初始化，不随机回退。哈希是稳定标识而非秘密，不加载项目级配置。
+
+At startup and `/reload`, recognized old configs (including legacy `protecter.json`) are validated, union-merged and deduplicated into the current target. The target is durably written and verified before unchanged old files are deleted. Invalid sources abort migration without deleting originals. Unix permissions are `0600`; unsafe links, foreign ownership and oversized files are rejected. Windows users must configure ACLs separately. See [migration details](docs/MIGRATION.md).
+
+启动和重载时，识别到的旧配置（包括原固定文件名）会先验证，再合并去重到当前目标；目标持久化写入并验证后才删除未变化的旧文件。无效来源会中止迁移而不删除原文件。Unix 权限为 `0600`，拒绝不安全链接、他人所有文件和超限文件；Windows 需自行设置 ACL。详见迁移文档。
 
-版本变更见 [CHANGELOG.md](CHANGELOG.md)。源码贡献与发布流程见仓库中的 `CONTRIBUTING.md` 和 `docs/RELEASING.md`。
+Validated configuration is cached per extension instance. Outgoing scans and status commands never reread or stat configuration files. Editing, corrupting or deleting files after loading does not alter the active snapshot. Changes take effect on `/reload` (or `/protecter reload`, which invokes Pi reload). A new instance after session replacement also initializes once. If all configs are deleted, the next initialization creates an empty config and warns; the old memory does not survive teardown.
 
-首次会话启动时创建 `~/.pi/agent/protecter.json`，遵循 Pi 的 `PI_CODING_AGENT_DIR` 覆盖设置。不会改写已有配置，不会读取项目级同名配置。Unix 文件权限收紧为 `0600`；符号链接、硬链接、多于 1 MiB 的配置和非当前用户所有的文件会被拒绝。Windows 还需用户自行配置 ACL。
+验证后的配置按扩展实例缓存。出站扫描及状态命令不重新读取或检查配置文件；加载后修改、损坏或删除文件不改变当前快照。修改在重载后生效；`/protecter reload` 会调用 Pi 重载，会话切换产生的新实例也初始化一次。若全部配置已删除，下次初始化会创建空配置并警告，旧内存不跨实例销毁保留。
 
-## 配置敏感信息
+## Configuration / 配置
 
-**请用本地编辑器编辑配置，不要让模型帮你填写真实密码，也不要把真实配置提交到 Git。** 初始数组为空，此时没有个人信息检测规则，界面会警告；插件不声称自动识别全部敏感信息。
+**Edit the configuration in a local editor. Do not ask the model to enter real passwords or commit real configuration to Git.** The initial rule array is empty and provides no personal-information detection; the UI warns about this. The extension does not automatically identify all SPI.
+
+**请用本地编辑器修改配置，不要让模型填写真实密码，也不要把真实配置提交到 Git。** 初始规则数组为空，不具备个人信息检测能力，界面会给出警告。插件不会自动识别所有 SPI。
 
 ```json
 {
@@ -40,63 +65,96 @@ pi -e ./src/index.ts
 }
 ```
 
-更多示例见 [`protecter.example.json`](protecter.example.json)，这些仅为示例规则，不会自动启用。号码示例不做真实性／校验位检查，姓名和密码通常应使用精确值规则。
+More examples are in [`protecter.example.json`](protecter.example.json); they are not automatically enabled. Number patterns do not validate authenticity or check digits. Prefer exact values for names and passwords.
+
+更多示例见 [`protecter.example.json`](protecter.example.json)，不会自动启用。号码规则不验证真实性或校验位，姓名和密码建议使用精确值。
 
-- 字符串及 `literal`：大小写敏感、全量字面匹配（不是正则）。
-- `regex`：JavaScript 正则，替换**整个匹配**；需要只匹配凭证值时可用 lookbehind。支持 `g i m s u`，自动补 `g`。不支持 `/pattern/flags` 简写。
-- 正则中的反斜杠要按 JSON 规则写为 `\\`；不能匹配空字符串。运行中遇到零宽匹配会拒绝该请求。
-- 匹配重叠时合并区间，避免只遮住短词而暴露长词后缀；同一原文在当前扩展实例中复用同一个占位符。
-- 已匹配过的原文会在当前实例内继续按精确值保护，即使正则前缀消失或规则被删除。这样可以防止本地还原后的内容在后续请求中漏出；退出／重载后清除这些内存记录。
-- 每次请求重新读取、校验配置。`/protecter`、`/protecter status` 或 `/protecter reload` 只报告规则／内存映射数量，不打印敏感值。没有把敏感值通过命令参数添加的功能。
-- 配置最多 1000 条规则，每个词／模式最多 8192 字符；扫描时间上限 2 秒，请求 JSON 上限 8 MiB。超限拒绝，不降级为明文。
+- **Literals:** strings and `literal` rules match all case-sensitive occurrences, without regex interpretation.
+  **字面规则：**字符串和 `literal` 按大小写敏感方式匹配全部出现位置，不作正则解释。
+- **Regex:** JavaScript regex replaces the entire match. Use lookbehind to match only a credential value. Flags `g i m s u` are supported; `g` is added automatically. `/pattern/flags` shorthand is not supported.
+  **正则：**JavaScript 正则替换整个匹配，可用后行断言仅匹配凭证值。支持 `g i m s u`，自动补 `g`，不支持 `/pattern/flags` 简写。
+- Escape backslashes as `\\` in JSON. Empty-string matches are invalid; runtime zero-width matches reject the request.
+  JSON 中的反斜杠写作 `\\`。不允许匹配空字符串；运行时零宽匹配会拒绝请求。
+- Overlapping matches are merged to avoid exposing a longer secret's suffix. Equal values reuse a token within the extension instance.
+  合并重叠匹配，避免暴露长敏感值的后缀；同一实例内相同原文复用占位符。
+- Learned originals remain exact-match protected within the instance even if regex context disappears or a rule is removed. Exit/reload clears these records.
+  已识别原文在当前实例内持续受到精确匹配保护，即使正则上下文消失或规则被删除；退出或重载清除记录。
+- `/protecter` and `/protecter status` report cached counts only, without disk access or sensitive values. `/protecter reload` waits for idle and invokes Pi's full reload; it is no longer a status-only command. Adding secrets through command arguments is not supported.
+  状态命令只报告缓存数量，不访问磁盘或显示敏感值。重载命令等待空闲并调用 Pi 完整重载，不再只是查询状态；不支持通过命令参数添加秘密。
+- Limits: 1000 rules, 8192 characters per literal/pattern, 2-second scan timeout and 8 MiB request JSON. Exceeding limits rejects the request rather than sending plaintext.
+  限制为 1000 条规则、每个词或模式 8192 字符、扫描 2 秒、请求 JSON 8 MiB；超限拒绝，不降级发送明文。
 
-## 工作方式
+## How it works / 工作方式
 
 ```text
-用户输入／历史／工具结果／系统提示／工具定义
-                 ↓
-Pi before_provider_request：最终 JSON payload 文本扫描
-                 ↓
-__PIP_<192-bit random hex>__ → LLM 网关
-                 ↓
-模型回复 → 本地 message_end 还原 + tool_call 参数还原
+Input / history / tools / system prompt / tool definitions
+输入／历史／工具结果／系统提示／工具定义
+                         ↓
+before_provider_request: final JSON text scan / 最终 JSON 文本扫描
+                         ↓
+__PIP_<192-bit random hex>__ → LLM gateway / LLM 网关
+                         ↓
+Local response and tool-argument restoration / 本地回复和工具参数还原
 ```
 
-1. 扫描请求 JSON 的字符串、键和数字；也会解析 JSON 字符串形式的工具参数，避免转义隐藏匹配。不会修改本地用户输入或历史原文。
-2. 使用 `crypto.randomBytes(24)` 生成占位符。映射**只保存在内存**，不写配置、会话自定义条目、日志或模型提示。用户仍可在本地看到原文。
-3. 最终 assistant 文本、thinking 和工具参数还原；TUI 的 Markdown transformer 在完整占位符到达时还原流式显示，尚未到齐时可能暂时显示部分占位符。RPC/JSON 的流式 delta 仍为占位符，最终 `message_end` 还原。占位符被模型改写或截断时无法还原。
-4. 工具执行前还原参数，让合法的本地文件操作能够使用原始值；下一次请求再次脱敏。**恢复真实凭证并不是工具授权或防外传机制。**
-5. 正则匹配在可终止 worker 中运行，避免恶意／低效正则阻塞主线程。扫描失败时请求替换为 `{}` 并请求终止，不依赖会被 Pi 吞掉的 hook 异常。可能仍产生空请求或网关校验错误，但不返回原始 payload。
-
-### 配置文件访问保护
-
-以**统一出口脱敏为主，配置直接访问拦截为辅**。不全面禁用 shell：
-
-- 在 `tool_call` 拦截明确涉及 `protecter.json` 的输入，包括常见 `read`、`write`、`edit` 和 `bash cat …`。
-- 路径参数解析 `@`、`~`、相对路径、`file://`，检查符号链接及 inode 别名。阻止 `grep/find/ls` 扫描包含配置的祖先目录。
-- 如果完整原始配置意外出现在请求文本中，也尝试整体替换。
-- **这只是尽力保护**：动态 shell、base64、分段输出、目录内部 symlink、任意第三方工具、网络发送均可绕过路径检查。不能保证恶意模型永远无法获取配置。不要把任意 shell 的能力与强隔离同时视为已实现。
-
-## 当前限制（请先读）
-
-- 只保护命中规则的文本；不识别同义改写、字符拆分、任意编码。附件中无法可靠检查 SPI，因此检测到常见图片／音频／视频／文件块时拒绝整个请求；不是 OCR。
-- 为避免摘要调用的不同生命周期泄漏／残留无法恢复的占位符，暂时取消 `/compact`、自动压缩和带摘要的 `/tree`。不带摘要的树导航可用；长会话请 `/new`。
-- 映射在退出、`/reload`、会话切换时丢弃。已完成并还原的本地消息不依赖映射；崩溃前的残留占位符、旧摘要、原始 delta 无法跨重启恢复。
-- 规则过宽（例如 `.`、全部数字或常见协议词）可能改写请求协议字段、模型名、工具 schema 或 ID，导致请求失败。数值命中会转为占位符字符串。优先使用具体规则。
-- 同一占位符会暴露“值相同”的关系；文本上下文也可能推断身份。这不是形式化匿名化。
-- 请求 hook 不覆盖 HTTP headers、认证 API key、网关地址、Pi 遥测、`/share`、其他扩展自行调用 `fetch`／模型 SDK 或工具网络访问。向模型提供服务的网关仍需要收到用于认证的网关凭证。
-- **请将本插件排在其他 payload 修改扩展之后，并且只运行受信任的扩展。** 后续处理器仍可重新加入原文；其他扩展拥有本机权限，插件无法约束它们。插件加载失败时 Pi 也可能继续运行，应检查状态再输入敏感信息。
-- 本地会话、终端、导出和工具写出的文件可能包含原文；本项目不加密或清理它们。
-
-详细威胁模型见 [SECURITY.md](SECURITY.md)。
-
-## 开发与验证
+1. Scan JSON strings, keys and numbers, including decoded JSON-string tool arguments. Local user input and original history are unchanged.
+   扫描 JSON 字符串、键和数字，包括解码后的 JSON 字符串工具参数；不修改本地用户输入和历史原文。
+2. Generate tokens with `crypto.randomBytes(24)`. Mappings stay **in memory only**, never in configuration, session custom entries, logs or model prompts. Local users can still see original values.
+   使用 `crypto.randomBytes(24)` 生成占位符。映射**仅存于内存**，不写入配置、会话自定义条目、日志或模型提示；本地用户仍可看到原文。
+3. Restore finalized assistant text, thinking and tool arguments. The TUI Markdown transformer restores complete streamed tokens; partial tokens may briefly appear. RPC/JSON deltas remain masked until final `message_end`. Altered or truncated tokens cannot be restored.
+   还原最终 assistant 文本、思考内容和工具参数。TUI 在完整占位符到达后还原，片段可能短暂显示；RPC/JSON 增量仍脱敏，直到最终消息还原。被改写或截断的占位符无法还原。
+4. Restore tool arguments before execution so legitimate local operations use original values; redact them again on subsequent requests. **Restoring credentials is not tool authorization or exfiltration prevention.**
+   工具执行前还原参数，让合法本地操作使用原值；后续请求再次脱敏。**凭证还原不等于工具授权或防外传。**
+5. Execute regex scans in a terminable worker. On failure, return `{}` and request cancellation rather than relying on hook exceptions swallowed by Pi. An empty request or provider validation error may still occur, but the handler does not return the original payload.
+   正则扫描运行于可终止 worker。失败时返回 `{}` 并请求取消，不依赖被 Pi 吞掉的钩子异常；仍可能产生空请求或提供商校验错误，但处理器不返回原始请求体。
+
+### Configuration access guard / 配置访问防护
+
+**Outgoing redaction is the main defense; direct-access blocking is supplementary.** Shell is not disabled wholesale.
+
+**以出站脱敏为主，直接访问拦截为辅。** 不全面禁用 shell。
+
+- File tools check actual path arguments, not document bodies; writing documentation that mentions config filenames is allowed. In the active config directory, legacy/current hash filenames and migration artifacts are protected. Shell command fields retain best-effort filename checks, so shell mentions can still produce false positives.
+  文件工具检查实际路径参数而非正文，允许文档提及配置名称。当前配置目录内的旧名称、哈希名称及迁移文件受保护；shell 命令字段保留尽力文件名检查，因此 shell 提及名称仍可能误拦截。
+- Resolve `@`, `~`, relative paths and `file://`; check symlink/inode aliases. Block `grep/find/ls` over ancestor directories containing the configuration.
+  解析上述路径形式，检查符号链接和 inode 别名；阻止这些搜索工具扫描包含配置的祖先目录。
+- Attempt whole-text masking if the complete original configuration accidentally appears in a request.
+  完整原始配置意外出现在请求文本时，尝试整体替换。
+- **Best effort only:** dynamic shell, base64, split output, nested symlinks, arbitrary third-party tools and network sends can bypass these checks. This cannot guarantee that a malicious model never obtains configuration.
+  **仅为尽力防护：**动态 shell、编码、拆分输出、目录内链接、任意第三方工具和网络发送可绕过检查，无法保证恶意模型永远无法取得配置。
+
+## Limitations — read first / 当前限制——请先阅读
+
+- Only rule-matching text is protected, not paraphrases, split characters or arbitrary encodings. Common image/audio/video/file blocks reject the entire request because SPI cannot be reliably inspected; no OCR is provided.
+  仅保护命中规则的文本，不覆盖改写、拆字和任意编码。常见多模态附件因无法可靠审查而拒绝整个请求，不提供 OCR。
+- `/compact`, automatic compaction and summarized `/tree` navigation are cancelled pending separate lifecycle/restoration verification. Tree navigation without summaries works; use `/new` for long sessions.
+  暂时取消压缩和带摘要的树导航，等待单独验证生命周期及还原；不带摘要的导航可用，长会话请使用 `/new`。
+- Exit, reload and session switching discard mappings. Final restored local messages remain readable; crash leftovers, old summaries and raw deltas cannot recover tokens across restarts.
+  退出、重载和切换会话会丢弃映射。最终已还原消息仍可读，但崩溃残留、旧摘要和原始增量无法跨重启恢复占位符。
+- Broad rules such as `.` or all digits may alter protocol fields, model names, tool schemas or IDs and break requests. Matching numbers become token strings. Prefer precise rules.
+  过宽规则可能改写协议字段、模型名、工具结构和 ID，导致请求失败；命中数字变为占位符字符串，应优先使用精确规则。
+- Reused tokens reveal equality relationships; context may imply identity. This is not formal anonymization.
+  复用占位符会暴露值相等的关系，上下文也可能揭示身份，这不是形式化匿名化。
+- Hooks do not cover HTTP headers, authentication keys, gateway endpoints, Pi telemetry, `/share`, independent extension SDK/fetch calls or tool networking. The gateway still receives its authentication credentials.
+  钩子不覆盖认证头、API key、网关地址、遥测、分享、扩展独立网络调用和工具联网；网关仍收到其认证凭证。
+- **Load after other payload rewriters and trust every installed extension.** Later handlers can reintroduce originals. Extensions have local permissions, and Pi may continue if this extension fails to load. Check status before entering secrets.
+  **在其他请求改写扩展之后加载，并只使用可信扩展。** 后续处理器可重新加入原文；扩展有本机权限，插件加载失败时 Pi 可能继续运行，请先检查状态再输入秘密。
+- Local sessions, terminals, exports and files written by tools may contain plaintext. They are not encrypted or cleaned by this project.
+  本地会话、终端、导出和工具写出的文件可能包含明文，本项目不加密或清理它们。
+
+See [SECURITY.md](SECURITY.md) for the threat model. / 详细威胁模型见该安全文档。
+
+## Development and verification / 开发与验证
 
 ```bash
 npm ci
 npm run check
 ```
 
-测试使用临时目录和虚构敏感值，不读取用户真实配置，不使用真实 API key 或访问 LLM 网关。包含脱敏／还原、正则超时、配置权限、路径防护及真实 Pi 扩展加载器／事件 runner 集成测试。
+Tests use temporary directories and fictional secrets, never real user configuration, API keys or LLM gateways. Coverage includes masking/restoration, regex timeout, permissions, path guards and real Pi loader/runner integration. All Markdown, comments and new commit messages must be English + Simplified Chinese.
+
+测试仅使用临时目录和虚构敏感值，不读取真实配置、不使用真实密钥或访问 LLM 网关，覆盖脱敏还原、正则超时、权限、路径防护和真实 Pi 加载器／执行器集成。所有 Markdown、注释和新提交信息必须使用英文＋简体中文。
+
+API references: [Pi Extensions](https://pi.dev/docs/latest/extensions), local 0.85.1 documentation and runner implementation. Licensed under MIT.
 
-接口依据：[Pi Extensions](https://pi.dev/docs/latest/extensions)、本机 0.85.1 扩展文档及 runner 实现。项目遵循 MIT License。
+接口依据为 Pi 官方扩展文档、本机 0.85.1 文档及执行器实现；采用 MIT 许可证。

package/SECURITY.md

@@ -1,30 +1,50 @@
-# SPI Protecter 安全边界
-
-## 目标
-
-防止正常使用 Pi 时，已配置的个人敏感信息以原始文本意外进入 LLM 请求体。威胁模型假设 Pi 核心、provider 实现、操作系统及其他已加载扩展可信，且该扩展成功加载、最终 hook 确实被调用。
-
-## 非目标
-
-- 不是操作系统沙箱，不防御同 UID 程序、恶意扩展、任意代码执行、调试器或内存抓取。
-- 不防御对文本任意编码、拆分、翻译、截图／OCR后的重构；不提供自动隐私分类或形式化匿名化。
-- 不保护网关认证 header、网关 endpoint、工具请求、独立 SDK 请求、遥测、会话导出或 `/share`。
-- 不加密本地配置／会话／终端，也不在秘密被模型推断出来后自动阻止它外传。
-
-## 实现策略
-
-- 全 payload 文本出口扫描；随机 192-bit 占位符，只在本地内存保存反向映射。
-- 正则 worker 2 秒超时、资源及输入限制。异常不包含原始配置、规则或请求文本。
-- Pi 0.85.1 runner 会捕获 before_provider_request 异常并继续发送当前 payload，因此错误路径必须返回安全替代 `{}`，并尽力 abort。不能宣传为“一定没有 HTTP 请求”，只能保证该处理器不回退原始 payload。
-- 配置单独创建，Unix 0600，读取时拒绝链接／非普通文件／多链接／其他用户所有文件。目录和操作系统权限仍需用户维护；路径检查存在 TOCTOU，不能抵御恶意本地并发修改。
-- 直接文件访问拦截只是纵深防护。`bash` 可以绕过字符串检查；配置目录祖先保护会有误拦截。
-- 配置整体文本检测只是补充，不保证各种重新格式化后的规则定义都被掩盖。
-- 辅助压缩和树摘要保守禁用。未经验证的新 Pi 版本不应直接扩大兼容范围。
-
-## 安全部署建议
-
-1. 本地填写具体规则，确认状态与规则数量；空配置并不具备个人信息检测能力。
-2. 使用虚构样例在自己信任的测试网关抓取请求验证，绝不要用真实秘密测试。
-3. 避免同时使用上传日志／导出会话／自动遥测类扩展；确认 payload 处理顺序。
-4. 高风险环境用容器／独立用户／独立文件系统，把配置放在执行工具不可访问的位置；同时限制网络出口。单靠本扩展不能提供这层保证。
-5. 不向公共 issue 提交真实配置、映射、会话或含个人信息的抓包数据。
+# SPI Protecter security boundaries / SPI Protecter 安全边界
+
+## Goal / 目标
+
+Prevent configured personal information from accidentally entering Pi LLM request bodies as plaintext. This assumes trusted Pi core, provider implementations, OS and installed extensions, successful extension loading and invocation of the final request hook.
+
+防止已配置的个人信息意外以明文进入 Pi 的 LLM 请求体。前提是 Pi 核心、提供商实现、操作系统和已加载扩展可信，且插件成功加载、最终请求钩子确实执行。
+
+## Non-goals / 非目标
+
+- No OS sandbox or defense against same-UID programs, malicious extensions, arbitrary code execution, debuggers or memory inspection.
+  不提供操作系统沙箱，不防御同 UID 程序、恶意扩展、任意代码执行、调试器或内存检查。
+- No protection against arbitrary encoding, splitting, translation or screenshot/OCR reconstruction; no automatic privacy classification or formal anonymization.
+  不防御任意编码、拆分、翻译和截图／OCR 重构，不提供自动隐私分类或形式化匿名化。
+- No coverage for gateway authentication headers/endpoints, tool requests, independent SDK calls, telemetry, session exports or `/share`.
+  不覆盖网关认证头与地址、工具请求、独立 SDK 调用、遥测、会话导出或分享。
+- No local configuration/session/terminal encryption, nor automatic prevention of exfiltration after a model infers a secret.
+  不加密本地配置、会话和终端，也不会在模型推断出秘密后自动阻止外传。
+
+## Implementation / 实现策略
+
+- Scan outgoing payload text; use random 192-bit placeholders and memory-only reverse mappings.
+  扫描出站请求体文本，使用随机 192-bit 占位符及仅内存反向映射。
+- Limit worker regex scans to 2 seconds, with resource and input limits. Errors exclude original configuration, rules and request text.
+  worker 正则扫描限制为 2 秒，并限制资源和输入；错误不包含原始配置、规则或请求文本。
+- Pi 0.85.1 catches `before_provider_request` errors and continues with the current payload. Error paths therefore return `{}` and attempt cancellation. This does not guarantee zero HTTP requests; it prevents this handler from falling back to the original payload.
+  Pi 0.85.1 会捕获该钩子异常并继续使用当前请求体，因此错误路径返回空对象并尝试取消。这不保证没有 HTTP 请求，只保证本处理器不回退原始请求体。
+- Create configuration separately with Unix mode 0600. Reject links, non-regular files, multiple links and files owned by others. Users remain responsible for directories and OS permissions; TOCTOU races are not prevented.
+  独立创建配置，Unix 权限为 0600；拒绝链接、非普通文件、多链接及他人所有文件。用户仍需维护目录和系统权限，无法防止检查与使用之间的竞态。
+- Direct-access blocking is supplementary. File tools inspect target paths rather than document bodies. Shell can bypass string checks, and command mentions or ancestor directory checks can still cause false positives.
+  直接访问拦截只是补充；文件工具检查目标路径而非正文。shell 可绕过字符串检查，命令提及及祖先目录检查仍可能误拦截。
+- Startup/reload validates and merges machine-hash configurations before caching. Requests use memory only; file deletion does not revoke cached secrets. Reload or process exit clears the instance. Migration uses commit-before-delete and a cooperating-process lock, not a multi-file transaction or protection against hostile local writers. Stale locks require local inspection; Windows does not provide POSIX directory fsync.
+  启动或重载时校验并合并机器哈希配置后缓存，请求只使用内存；文件删除不撤销缓存秘密，重载或退出才清理实例。迁移采用先提交后删除及协作进程锁，并非多文件事务或恶意本地写入防护；残留锁需本地检查，Windows 无 POSIX 目录同步。
+- Whole-configuration text detection does not guarantee that every reformatted rule definition is masked.
+  整体配置文本检测不保证所有重新格式化的规则定义都被遮盖。
+- Compaction and tree summaries are conservatively disabled. Do not widen Pi compatibility without verification.
+  保守禁用压缩和树摘要，未经验证不扩大 Pi 兼容范围。
+
+## Deployment guidance / 安全部署建议
+
+1. Configure precise rules locally and check status/counts. Empty rules provide no SPI detection.
+   在本地配置具体规则并检查状态和数量；空规则不具备个人信息检测能力。
+2. Inspect requests using fictional data and a trusted test gateway; never test with real secrets.
+   使用虚构数据及可信测试网关检查请求，绝不用真实秘密测试。
+3. Avoid log-upload, session-export and telemetry extensions; verify payload handler ordering.
+   避免日志上传、会话导出和遥测类扩展，确认请求处理器顺序。
+4. Use containers, separate users/filesystems and network restrictions for high-risk environments. Keep configuration outside tool-accessible storage. This extension alone cannot enforce that isolation.
+   高风险环境使用容器、独立用户或文件系统及网络限制，将配置放在工具不可访问的位置；本扩展无法单独提供此隔离。
+5. Never post real configuration, mappings, sessions or personal-information packet captures in public issues.
+   不在公共问题报告中提交真实配置、映射、会话或含个人信息的抓包。

package/docs/MIGRATION.md

@@ -0,0 +1,54 @@
+# Configuration migration and cache / 配置迁移与缓存
+
+## Identity and discovery / 标识与发现
+
+The target is `protecter.<32-lowercase-hex-machine-hash>.json` in Pi's active agent directory. Normalize the OS identifier by trimming, lowercasing and removing UUID hyphens, then hash `pi-information-protecter:v1:` plus that identifier with SHA-256. Use the first 32 hex characters. IDs are never logged. OS reinstalls, cloned images and containers may change or duplicate IDs; this is not a uniqueness or access-control guarantee.
+
+目标位于 Pi 当前配置目录，名称包含 32 位小写十六进制机器哈希。系统标识去除首尾空白、转小写并移除 UUID 连字符，再加产品前缀计算 SHA-256，取前 32 位。不记录原始标识；重装、克隆和容器可能改变或重复标识，因此不保证唯一性，也不是访问控制。
+
+Only `protecter.json` and `protecter.[a-f0-9]{32}.json` in that directory are candidates. No recursion or arbitrary wildcard deletion. At most 64 candidates are accepted. Example files are ignored. UUID filenames were never shipped and are not silently imported.
+
+仅识别该目录中的旧固定名称和严格匹配的哈希名称，不递归、不任意通配删除，最多接受 64 个候选。示例文件被忽略；从未发布过 UUID 名称版本，因此不静默导入这种文件。
+
+## Validate and merge / 校验与合并
+
+Every candidate must be a current-user regular file without symlinks or hard links, at most 1 MiB, with schema version 1 and valid rules. Regex empty-match checks run in a bounded worker before any target write. Unknown fields, malformed rules and unsupported versions stop initialization. Existing files may have permissions tightened to 0600, but invalid input never causes deletion.
+
+每个候选必须为当前用户所有的普通文件，无符号或硬链接，不超过 1 MiB，版本为 1 且规则合法。正则空匹配在限时 worker 中验证后才写目标。未知字段、错误规则和不支持版本会停止初始化。已有文件权限可能收紧为 0600，但无效输入不导致删除。
+
+Current-target rules come first, then old files in filename order. Strings and equivalent explicit literals deduplicate by exact value. Regexes deduplicate by exact pattern and normalized flags, with implicit `g` included. Case, whitespace, Unicode and differing regex semantics are preserved. The merged, pretty-printed target must remain within 1000 rules and 1 MiB; no truncation is allowed.
+
+当前目标规则优先，旧文件按名称顺序合并。字符串和等价字面对象按精确值去重；正则按模式和含隐式 `g` 的规范化标志去重。大小写、空白、Unicode 和不同正则语义保留。合并并格式化后仍须满足 1000 条及 1 MiB 限制，不允许截断。
+
+## Commit and cleanup / 提交与清理
+
+1. Acquire the directory-wide `.protecter-migration.lock` using exclusive directory creation; wait up to 5 seconds for cooperating processes.
+   通过排他目录创建获取目录级迁移锁，最多等待其他协作进程 5 秒。
+2. Read and validate all candidates, retain file identity/content digests, merge and validate the result.
+   读取校验全部候选，记录身份及内容摘要，合并并校验结果。
+3. Write a same-directory, uniquely named `.protecter-migration.<uuid>.tmp` with 0600 permissions; fsync and close it.
+   在同目录排他创建唯一临时文件，设为 0600，写入、同步并关闭。
+4. Recheck candidate names, identities and content. Rename the temporary file onto the target; fsync the directory on POSIX. Reopen and verify the exact committed contents.
+   再检查候选集合、身份及内容，将临时文件重命名到目标，POSIX 上同步目录，重新打开验证精确内容。
+5. Before each old-file deletion, recheck both the committed target and the old source. Delete only unchanged sources, then sync the directory and verify the final target.
+   每次删除前同时检查目标与旧来源，仅删除未变化来源，再同步目录并验证最终目标。
+6. Activate the in-memory snapshot only after success; release the lock. Migration failure leaves the instance unready and outgoing requests safely empty.
+   成功后才启用内存快照并释放锁；失败时实例不就绪，出站请求安全清空。
+
+This is recoverable, not a multi-file atomic transaction. A failure after target commit can leave both target and old files; the next run unions them again safely. Failure during deletion leaves the committed union intact. External editors do not obey the lock and TOCTOU cannot be eliminated; avoid editing during initialization. Windows lacks POSIX directory fsync, so power-loss durability is weaker.
+
+这是一套可恢复流程，不是跨文件原子事务。目标提交后失败可能留下新旧文件，下次可安全重复合并；删除途中失败时目标已包含规则并集。外部编辑器不遵守锁，无法彻底消除竞态，请避免初始化期间编辑。Windows 缺少 POSIX 目录同步，断电持久性较弱。
+
+A hard crash may leave the lock or a private temporary file. The plugin never steals a lock or automatically deletes unknown temporary files. Stop all Pi processes and inspect the agent directory locally before manually removing a stale lock or orphaned temporary file. Never upload those files: they may contain secrets.
+
+硬崩溃可能遗留锁或私有临时文件。插件不抢占锁、不自动删除未知临时文件。先停止全部 Pi 进程，在本地检查目录后再手动移除残留锁或孤立临时文件；文件可能含秘密，绝不要上传。
+
+## Memory lifecycle / 内存生命周期
+
+Startup, `/reload` and extension-instance replacement initialize once. Outbound scans read only the cached snapshot; deleting or changing files does not affect the active instance. `/protecter status` reads only counts. `/protecter reload` requests Pi's full reload after idle. Successful reload uses disk rules; failed initialization does not fall back to plaintext. Cache and token mappings are cleared at shutdown.
+
+启动、重载及扩展实例替换时初始化一次。出站扫描仅使用缓存，删除或修改文件不影响当前实例；状态命令只读取数量，重载命令等待空闲后请求 Pi 完整重载。成功重载使用磁盘规则，失败不回退明文；关闭时清除缓存和映射。
+
+Deleting every config does not preserve rules across restart: a fresh instance creates an empty configuration and warns. Keep a secure user-managed backup if persistent recovery is required. Independent processes keep independent snapshots even if another process migrates their former file.
+
+删除全部配置不能跨重启保留规则，新实例将创建空配置并警告；需要持久恢复时由用户自行安全备份。独立进程拥有独立快照，即使其他进程迁移原文件也不受影响。

package/package.json

@@ -1,18 +1,47 @@
 {
   "name": "pi-information-protecter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sensitive Personal Information (SPI) Protecter — local reversible privacy redaction for Pi",
   "type": "module",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/taills/pi-information-protecter.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taills/pi-information-protecter.git"
+  },
   "homepage": "https://github.com/taills/pi-information-protecter#readme",
-  "bugs": { "url": "https://github.com/taills/pi-information-protecter/issues" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "keywords": ["pi-package", "pi-extension", "privacy", "redaction"],
-  "files": ["src", "README.md", "SECURITY.md", "CHANGELOG.md", "protecter.example.json", "LICENSE"],
-  "pi": { "extensions": ["./src/index.ts"] },
-  "engines": { "node": ">=22" },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": ">=0.85.1 <0.86.0" },
+  "bugs": {
+    "url": "https://github.com/taills/pi-information-protecter/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "privacy",
+    "redaction"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "docs/MIGRATION.md",
+    "protecter.example.json",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.1 <0.86.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@types/node": "^22.0.0",

package/src/config.ts

@@ -20,7 +20,7 @@ export interface Config {
 }
 export const DEFAULT_CONFIG: Config = { version: 1, sensitiveWords: [] };
 export const CONFIG_ERROR =
-  "protecter: 配置无法安全读取或格式无效；请在本地修复 protecter.json。";
+  "SPI Protecter: unsafe or invalid configuration / 配置不安全或格式无效，请在本地修复。";
 
 export function parseConfig(raw: string): Config {
   try {
@@ -60,7 +60,8 @@ export function parseConfig(raw: string): Config {
         )
           throw new Error();
         const re = new RegExp(rule.pattern, rule.flags ?? "");
-        if (re.test("")) throw new Error();
+        // Compilation only here; matching is bounded in the worker. / 此处仅编译，匹配在限时 worker 内执行。
+        void re;
       } else throw new Error();
     }
     return value;
@@ -69,7 +70,10 @@ export function parseConfig(raw: string): Config {
   }
 }
 
-/** Do not follow a symlink, accept a hard-linked file, or print parser/OS errors containing secrets. */
+/**
+ * Reject symlinks and hard links; never print parser/OS errors containing secrets.
+ * 拒绝符号链接和硬链接；不输出可能包含敏感值的解析器或系统错误。
+ */
 export function loadConfig(
   path: string,
   create = false,

package/src/engine.ts

@@ -1,6 +1,7 @@
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
-import { loadConfig } from "./config.ts";
+import { migrateConfig, type Snapshot } from "./migration.ts";
+import { getMachineHash } from "./machine.ts";
 
 export const REQUEST_ERROR =
   "protecter: 请求已清空。配置无效、扫描超时或包含不支持的附件；修复后重试。";
@@ -9,19 +10,31 @@ export class Protecter {
   private queue: Promise<unknown> = Promise.resolve();
   private readonly workers = new Set<Worker>();
   private closed = false;
+  private snapshot?: Snapshot;
   constructor(
-    readonly configPath: string,
+    private readonly configDir: string,
     private readonly timeoutMs = 2000,
+    private readonly machineId: () => string = getMachineHash,
   ) {}
 
-  initialize(): void {
-    loadConfig(this.configPath, true);
+  async initialize(): Promise<void> {
+    if (this.closed) throw new Error(REQUEST_ERROR);
+    this.snapshot = undefined;
+    const snapshot = await migrateConfig(this.configDir, this.machineId());
+    if (this.closed) throw new Error(REQUEST_ERROR);
+    this.snapshot = snapshot;
   }
+  get configPath(): string { return this.snapshot?.path ?? ""; }
+  get ruleCount(): number { return this.snapshot?.config.sensitiveWords.length ?? 0; }
+  get ready(): boolean { return !!this.snapshot && !this.closed; }
   get mappingCount(): number {
     return this.tokens.size;
   }
 
-  /** Serialise scans so two requests cannot assign different tokens to the same value. */
+  /**
+   * Serialise scans so two requests cannot assign different tokens to the same value.
+   * 串行扫描，避免两个请求为同一原文分配不同占位符。
+   */
   redact(payload: unknown): Promise<unknown> {
     const run = this.queue.then(() => this.scan(payload));
     this.queue = run.catch(() => undefined);
@@ -29,8 +42,8 @@ export class Protecter {
   }
 
   private async scan(payload: unknown): Promise<unknown> {
-    if (this.closed) throw new Error(REQUEST_ERROR);
-    const { config, raw } = loadConfig(this.configPath);
+    if (!this.ready) throw new Error(REQUEST_ERROR);
+    const { config, sourceRaws } = this.snapshot!;
     const serialized = JSON.stringify(payload);
     if (!serialized || Buffer.byteLength(serialized) > 8 * 1024 * 1024)
       throw new Error(REQUEST_ERROR);
@@ -49,8 +62,9 @@ export class Protecter {
             payload: snapshot,
             rules: config.sensitiveWords,
             entries: [...this.tokens],
-            configRaw: raw,
+            configRaws: sourceRaws,
           },
+          execArgv: [],
           resourceLimits: { maxOldGenerationSizeMb: 128 },
         },
       );
@@ -81,6 +95,7 @@ export class Protecter {
 
   restoreText(text: string): string {
     // One pass, never recursively expand text introduced by a replacement.
+    // 仅替换一遍，不递归展开替换后引入的文本。
     return text.replace(
       /__PIP_[a-f0-9]{48}__/g,
       (token) => this.tokens.get(token) ?? token,
@@ -107,6 +122,7 @@ export class Protecter {
 
   close(): void {
     this.closed = true;
+    this.snapshot = undefined;
     this.tokens.clear();
     for (const worker of this.workers) void worker.terminate();
     this.workers.clear();

package/src/guard.ts

@@ -1,6 +1,7 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { CONFIG_NAME } from "./migration.ts";
 import { fileURLToPath } from "node:url";
 
 function normalized(path: string, cwd: string): string {
@@ -34,17 +35,23 @@ function sameFile(a: string, b: string): boolean {
   }
 }
 
-/** Best-effort access guard. Arbitrary shell/third-party tools are NOT sandboxed. */
+/**
+ * Best-effort access guard. Arbitrary shell/third-party tools are NOT sandboxed.
+ * 尽力而为的访问防护，不对任意 shell 或第三方工具提供沙箱隔离。
+ */
 export function blocksConfigAccess(
   tool: string,
   input: Record<string, unknown>,
   cwd: string,
   configPath: string,
 ): boolean {
+  if (!configPath) return true;
   const target = canonical(resolve(configPath));
-  const serialized = JSON.stringify(input);
-  if (/protecter\.json/i.test(serialized) || serialized.includes(configPath))
-    return true;
+  // Inspect executable fields, not document bodies. / 检查可执行字段，不检查文档正文。
+  if (["bash", "powershell"].includes(tool)) {
+    const command = typeof input.command === "string" ? input.command : "";
+    if (/protecter(?:\.[a-f0-9]{32})?\.json|\.protecter-migration/i.test(command) || command.includes(configPath)) return true;
+  }
   const candidate = input.path ?? input.file_path ?? input.filePath;
   const recursive = ["grep", "find", "ls"].includes(tool);
   if (typeof candidate !== "string" && !recursive) return false;
@@ -55,6 +62,7 @@ export function blocksConfigAccess(
     );
     const real = canonical(path);
     return (
+      (dirname(real) === dirname(target) && (CONFIG_NAME.test(basename(real)) || basename(real).startsWith(".protecter-migration"))) ||
       real === target ||
       sameFile(path, configPath) ||
       (recursive && contains(real, target))

package/src/index.ts

@@ -3,28 +3,29 @@ import {
   VERSION,
   type ExtensionAPI,
 } from "@earendil-works/pi-coding-agent";
-import { join } from "node:path";
-import { loadConfig } from "./config.ts";
 import { Protecter, REQUEST_ERROR } from "./engine.ts";
 import { blocksConfigAccess } from "./guard.ts";
 
-/** Explicitly install this after other extensions that rewrite outgoing payloads. */
+/**
+ * Explicitly install this after other extensions that rewrite outgoing payloads.
+ * 请将本扩展放在其他改写出站请求体的扩展之后加载。
+ */
 export default function informationProtecter(pi: ExtensionAPI): void {
-  const engine = new Protecter(join(getAgentDir(), "protecter.json"));
+  const engine = new Protecter(getAgentDir());
   const compatible =
     /^0\.85\./.test(VERSION) && Number(VERSION.split(".")[2]) >= 1;
   let healthy = false;
 
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
     try {
       if (!compatible) throw new Error();
-      engine.initialize();
+      await engine.initialize();
       healthy = true;
-      const count = loadConfig(engine.configPath).config.sensitiveWords.length;
+      const count = engine.ruleCount;
       ctx.ui.setStatus("protecter", `SPI Protecter · ${count} rules`);
       if (count === 0)
         ctx.ui.notify(
-          "SPI Protecter：敏感词数组为空，请在本地编辑 protecter.json 后使用。",
+          "SPI Protecter: empty rules; edit local machine config and /reload / 规则为空，请编辑本地机器配置后重载。",
           "warning",
         );
     } catch {
@@ -41,25 +42,30 @@ export default function informationProtecter(pi: ExtensionAPI): void {
       return payload;
     } catch {
       healthy = false;
-      // Pi catches thrown hook errors and continues with the ORIGINAL payload.
-      // Always return an empty replacement first; abort/notifications are best-effort.
+      // Pi catches hook errors and continues with the ORIGINAL payload.
+      // Pi 会捕获钩子异常并继续使用原始请求体。
+      // Always return an empty replacement; abort/notifications are best-effort.
+      // 必须返回空替代请求体；终止请求和通知仅作尽力处理。
       try {
         await ctx.abort();
       } catch {
-        /* replacement below remains mandatory */
+        /* Replacement below remains mandatory. / 仍须返回下方的替代请求体。 */
       }
       try {
         ctx.ui.notify(REQUEST_ERROR, "error");
       } catch {
-        /* never fail open */
+        /* Never fail open. / 不因异常放行原文。 */
       }
-      return {}; // May produce a provider validation error, but contains NO original data.
+      // May produce a provider validation error, but contains NO original data.
+      // 可能触发提供商校验错误，但不包含任何原始数据。
+      return {};
     }
   });
 
   pi.on("message_end", (event) => {
     if (event.message.role !== "assistant") return;
     // Preserve IDs, signatures, usage and provider metadata; only restore user-facing content.
+    // 保留 ID、签名、用量与提供商元数据，仅还原面向用户的内容。
     const message = event.message;
     return {
       message: {
@@ -105,8 +111,10 @@ export default function informationProtecter(pi: ExtensionAPI): void {
     }
   });
 
-  // These auxiliary request paths have different lifecycle/response restoration semantics.
+  // These auxiliary requests have different lifecycle/response restoration semantics.
+  // 这些辅助请求具有不同的生命周期与响应还原语义。
   // Until separately verified, cancel instead of silently sending plaintext summaries.
+  // 在单独验证前取消这些请求，避免静默发送明文摘要。
   pi.on("session_before_compact", (_event, ctx) => {
     ctx.ui.notify(
       "SPI Protecter：暂不支持远程上下文压缩，请使用 /new 开始新会话。",
@@ -119,7 +127,7 @@ export default function informationProtecter(pi: ExtensionAPI): void {
   );
 
   pi.registerCommand("protecter", {
-    description: "SPI Protecter 状态与本地配置校验（不显示敏感值）",
+    description: "SPI Protecter memory status / 内存状态（不显示敏感值）",
     handler: async (args, ctx) => {
       if (args.trim() && !["status", "reload"].includes(args.trim())) {
         ctx.ui.notify(
@@ -128,18 +136,15 @@ export default function informationProtecter(pi: ExtensionAPI): void {
         );
         return;
       }
-      try {
-        if (!compatible) throw new Error();
-        const { config } = loadConfig(engine.configPath);
-        healthy = true;
-        ctx.ui.notify(
-          `SPI Protecter：${config.sensitiveWords.length} 条规则；${engine.mappingCount} 个内存映射。配置每次请求重新读取。`,
-          "info",
-        );
-      } catch {
-        healthy = false;
-        ctx.ui.notify(REQUEST_ERROR, "error");
+      if (args.trim() === "reload") {
+        await ctx.waitForIdle();
+        await ctx.reload();
+        return;
       }
+      ctx.ui.notify(
+        `SPI Protecter: ${engine.ready ? "ready / 就绪" : "not ready / 未就绪"}; ${engine.ruleCount} rules / 规则; ${engine.mappingCount} mappings / 映射. Memory snapshot; /reload to refresh / 内存快照，重载后更新。`,
+        engine.ready ? "info" : "error",
+      );
     },
   });
   pi.on("session_shutdown", () => engine.close());

package/src/machine.ts

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+export const MACHINE_ERROR = "SPI Protecter: machine ID unavailable / 无法获取机器标识。";
+
+/** Normalize OS identifiers without exposing them. / 规范化系统标识，不向外暴露。 */
+export function machineHash(id: string): string {
+  const normalized = id.trim().toLowerCase().replace(/-/g, "");
+  if (!/^[a-f0-9]{32}$/.test(normalized) || /^0+$/.test(normalized)) throw new Error(MACHINE_ERROR);
+  return createHash("sha256").update(`pi-information-protecter:v1:${normalized}`).digest("hex").slice(0, 32);
+}
+
+/** No random fallback: unavailable IDs must fail closed. / 不随机回退，标识不可用时拒绝初始化。 */
+export function getMachineHash(): string {
+  try {
+    if (process.platform === "linux") return machineHash(readFileSync("/etc/machine-id", "utf8"));
+    if (process.platform === "darwin") {
+      const text = execFileSync("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], { encoding: "utf8", timeout: 5000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+      return machineHash(text.match(/"IOPlatformUUID"\s*=\s*"([a-fA-F0-9-]+)"/)?.[1] ?? "");
+    }
+    if (process.platform === "win32") {
+      const text = execFileSync("reg.exe", ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid", "/reg:64"], { encoding: "utf8", timeout: 5000, maxBuffer: 65536, stdio: ["ignore", "pipe", "pipe"] });
+      return machineHash(text.match(/MachineGuid\s+REG_SZ\s+([a-fA-F0-9-]+)/i)?.[1] ?? "");
+    }
+  } catch { /* Do not expose command output. / 不暴露命令输出。 */ }
+  throw new Error(MACHINE_ERROR);
+}

package/src/migration.ts

@@ -0,0 +1,127 @@
+import * as fs from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { CONFIG_ERROR, DEFAULT_CONFIG, loadConfig, parseConfig, type Config, type Rule } from "./config.ts";
+
+export const CONFIG_NAME = /^protecter(?:\.[a-f0-9]{32})?\.json$/;
+export interface Snapshot { path: string; config: Config; raw: string; sourceRaws: string[]; migrated: number }
+interface Source { name: string; raw: string; config: Config; identity: string; digest: string }
+export interface MigrationOptions {
+  lockTimeoutMs?: number;
+  // Local fault injection for regression tests only. / 仅供本地回归测试注入故障。
+  checkpoint?: (stage: "beforeCommit" | "afterCommit" | "beforeDelete", path: string) => void;
+}
+
+export function validatePatterns(configs: Config[]): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const worker = new Worker(fileURLToPath(new URL("./validate-worker.mjs", import.meta.url)), { workerData: configs, execArgv: [], resourceLimits: { maxOldGenerationSizeMb: 64 } });
+    let done = false;
+    const finish = (ok: boolean) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      if (ok) resolvePromise(); else reject(new Error(CONFIG_ERROR));
+    };
+    const timer = setTimeout(() => finish(false), 2000);
+    worker.once("message", value => finish(value === true));
+    worker.once("error", () => finish(false));
+    worker.once("exit", () => finish(false));
+  });
+}
+
+export function mergeConfigs(configs: Config[]): Config {
+  const seen = new Set<string>();
+  const rules: Rule[] = [];
+  for (const config of configs) for (const rule of config.sensitiveWords) {
+    const key = typeof rule === "string" ? JSON.stringify(["literal", rule]) : rule.type === "literal" ? JSON.stringify(["literal", rule.value]) : JSON.stringify(["regex", rule.pattern, [...new Set((rule.flags ?? "") + "g")].sort().join("")]);
+    if (!seen.has(key)) { seen.add(key); rules.push(rule); }
+  }
+  const raw = JSON.stringify({ version: 1, sensitiveWords: rules });
+  if (Buffer.byteLength(raw) > 1024 * 1024) throw new Error(CONFIG_ERROR);
+  return parseConfig(raw);
+}
+
+function identity(path: string): string {
+  const s = fs.lstatSync(path, { bigint: true });
+  if (!s.isFile() || s.nlink !== 1n || (process.getuid && s.uid !== BigInt(process.getuid()))) throw new Error(CONFIG_ERROR);
+  return `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}`;
+}
+function source(dir: string, name: string): Source {
+  const path = join(dir, name), before = identity(path);
+  const loaded = loadConfig(path);
+  if (identity(path) !== before) throw new Error(CONFIG_ERROR);
+  return { name, ...loaded, identity: before, digest: createHash("sha256").update(loaded.raw).digest("hex") };
+}
+function unchanged(dir: string, previous: Source): void {
+  const now = source(dir, previous.name);
+  if (now.identity !== previous.identity || now.digest !== previous.digest) throw new Error(CONFIG_ERROR);
+}
+function names(dir: string): string[] { return fs.readdirSync(dir).filter(name => CONFIG_NAME.test(name)).sort(); }
+function syncDir(dir: string): void {
+  // Windows does not support POSIX directory fsync. / Windows 不支持 POSIX 目录同步。
+  if (process.platform === "win32") return;
+  const fd = fs.openSync(dir, fs.constants.O_RDONLY);
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+/** Commit before deleting; repeat safely after partial cleanup. / 先提交再删除，部分清理后可安全重试。 */
+export async function migrateConfig(directory: string, hash: string, options: MigrationOptions = {}): Promise<Snapshot> {
+  if (!/^[a-f0-9]{32}$/.test(hash)) throw new Error(CONFIG_ERROR);
+  const dir = resolve(directory), targetName = `protecter.${hash}.json`, path = join(dir, targetName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const lock = join(dir, ".protecter-migration.lock"), deadline = Date.now() + (options.lockTimeoutMs ?? 5000);
+  for (;;) {
+    try { fs.mkdirSync(lock, { mode: 0o700 }); break; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST" || Date.now() >= deadline) throw new Error("SPI Protecter: migration locked; check active processes / 迁移锁被占用，请检查活动进程。");
+      await new Promise(resolvePromise => setTimeout(resolvePromise, 50));
+    }
+  }
+  let temp: string | undefined;
+  try {
+    const discovered = names(dir);
+    if (discovered.length > 64) throw new Error(CONFIG_ERROR);
+    const ordered = [...discovered].sort((a, b) => a === targetName ? -1 : b === targetName ? 1 : a.localeCompare(b));
+    const sources = ordered.map(name => source(dir, name));
+    const config = mergeConfigs(sources.length ? sources.map(s => s.config) : [DEFAULT_CONFIG]);
+    await validatePatterns(sources.length ? sources.map(s => s.config) : [config]);
+    if (sources.length === 1 && sources[0].name === targetName) {
+      unchanged(dir, sources[0]);
+      if (JSON.stringify(names(dir)) !== JSON.stringify(discovered)) throw new Error(CONFIG_ERROR);
+      return { path, config: sources[0].config, raw: sources[0].raw, sourceRaws: [sources[0].raw], migrated: 0 };
+    }
+    const raw = JSON.stringify(config, null, 2) + "\n";
+    if (Buffer.byteLength(raw) > 1024 * 1024) throw new Error(CONFIG_ERROR);
+    temp = join(dir, `.protecter-migration.${randomUUID()}.tmp`);
+    const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try { fs.writeFileSync(fd, raw); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    options.checkpoint?.("beforeCommit", path);
+    if (JSON.stringify(names(dir)) !== JSON.stringify(discovered)) throw new Error(CONFIG_ERROR);
+    for (const s of sources) unchanged(dir, s);
+    fs.renameSync(temp, path);
+    temp = undefined;
+    syncDir(dir);
+    const committed = source(dir, targetName);
+    if (committed.raw !== raw) throw new Error(CONFIG_ERROR);
+    options.checkpoint?.("afterCommit", path);
+    for (const s of sources) {
+      if (s.name === targetName) continue;
+      options.checkpoint?.("beforeDelete", join(dir, s.name));
+      unchanged(dir, committed);
+      unchanged(dir, s);
+      fs.unlinkSync(join(dir, s.name));
+    }
+    syncDir(dir);
+    const expected = [targetName];
+    if (JSON.stringify(names(dir)) !== JSON.stringify(expected)) throw new Error(CONFIG_ERROR);
+    unchanged(dir, committed);
+    return { path, config, raw, sourceRaws: [...new Set([...sources.map(s => s.raw), raw])], migrated: sources.filter(s => s.name !== targetName).length };
+  } catch { throw new Error(CONFIG_ERROR); }
+  finally {
+    if (temp) { try { fs.unlinkSync(temp); } catch { /* Preserve on failure. / 失败时保留待人工检查。 */ } }
+    fs.rmdirSync(lock);
+  }
+}

package/src/scan-worker.mjs

@@ -1,9 +1,10 @@
 // A separate worker bounds user-supplied JavaScript regex execution (including ReDoS).
+// 独立 worker 限制用户正则的执行时间，包括正则拒绝服务风险。
 import { parentPort, workerData } from "node:worker_threads";
 import { randomBytes } from "node:crypto";
 
 try {
-  const { payload, rules, entries, configRaw } = workerData;
+  const { payload, rules, entries, configRaws } = workerData;
   const originalToToken = new Map(
     entries.map(([token, original]) => [original, token]),
   );
@@ -20,12 +21,15 @@ try {
     };
   });
   // A restored value may lose its original regex context (e.g. a Bearer prefix).
+  // 还原后的值可能失去原始正则上下文，例如 Bearer 前缀。
   // Keep learned originals protected for the lifetime of this extension instance.
+  // 在当前扩展实例的整个生命周期内继续保护已识别的原文。
   for (const original of originalToToken.keys())
     matchers.push({ literal: original });
   // Defense in depth for an accidentally pasted full configuration (not a sandbox).
-  const compactConfig = JSON.stringify(JSON.parse(configRaw));
-  matchers.push({ literal: configRaw }, { literal: compactConfig });
+  // 对意外粘贴的完整配置提供纵深防护，但这不是沙箱。
+  const protectedTexts = [...new Set(configRaws.flatMap(raw => [raw, JSON.stringify(JSON.parse(raw))]))];
+  for (const literal of protectedTexts) matchers.push({ literal });
   const payloadText = JSON.stringify(payload);
   let matches = 0;
   let nodes = 0;
@@ -57,7 +61,7 @@ try {
         while ((start = text.indexOf(matcher.literal, start)) !== -1) {
           spans.push([start, start + matcher.literal.length]);
           if (++matches > 100000) throw new Error();
-          start++; // Include overlapping occurrences.
+          start++; // Include overlapping occurrences. / 包含重叠匹配。
         }
       }
     }
@@ -78,6 +82,7 @@ try {
   }
   function redact(text) {
     // Only OUR tokens are exempt, not arbitrary strings with a similar prefix.
+    // 仅豁免本实例生成的占位符，不豁免具有相似前缀的任意字符串。
     let result = "",
       cursor = 0;
     for (const match of text.matchAll(/__PIP_[a-f0-9]{48}__/g)) {
@@ -90,22 +95,25 @@ try {
   function walk(value, depth = 0) {
     if (++nodes > 200000 || depth > 80) throw new Error();
     if (typeof value === "string") {
-      if (value.includes(configRaw) || value.includes(compactConfig))
+      if (protectedTexts.some(text => value.includes(text)))
         return redact(value);
       // OpenAI serializes tool arguments as JSON strings: decode escapes BEFORE matching.
+      // OpenAI 将工具参数序列化为 JSON 字符串，匹配前必须先解码转义。
       if (/^\s*[[{]/.test(value)) {
         let parsed;
         try {
           parsed = JSON.parse(value);
         } catch {
-          /* ordinary prose */
+          /* Ordinary prose. / 普通文本。 */
         }
         if (parsed && typeof parsed === "object") {
           const inner = JSON.stringify(walk(parsed, depth + 1));
           const outer = redact(inner);
           if (outer === inner) return inner;
           // A rule may span JSON syntax or match a whole JSON-shaped secret.
+          // 规则可能跨越 JSON 语法，或匹配整个 JSON 形式的敏感值。
           // Return altered JSON only if it still parses; otherwise reject the request.
+          // 仅返回仍可解析的修改后 JSON，否则拒绝请求。
           JSON.parse(outer);
           return outer;
         }
@@ -119,6 +127,7 @@ try {
     if (Array.isArray(value)) return value.map((item) => walk(item, depth + 1));
     if (value && typeof value === "object") {
       // No claim to perform OCR or redact opaque attachments. Reject rather than leak.
+      // 不提供 OCR 或不透明附件脱敏，宁可拒绝请求也不放行泄漏。
       if (
         typeof value.type === "string" &&
         /image|audio|video|document|(^|_)file($|_)/i.test(value.type)
@@ -146,5 +155,6 @@ try {
   parentPort.postMessage({ payload: walk(payload), additions });
 } catch {
   // Never serialize an exception, original payload or configuration back into diagnostics.
+  // 不将异常、原始请求体或配置序列化到诊断信息中。
   parentPort.postMessage({ failed: true });
 }

package/src/validate-worker.mjs

@@ -0,0 +1,13 @@
+import { parentPort, workerData } from "node:worker_threads";
+
+try {
+  for (const config of workerData) {
+    for (const rule of config.sensitiveWords) {
+      if (typeof rule === "object" && rule.type === "regex" && new RegExp(rule.pattern, rule.flags ?? "").test("")) throw new Error();
+    }
+  }
+  parentPort.postMessage(true);
+} catch {
+  // Return no rules or parser errors. / 不返回规则或解析错误。
+  parentPort.postMessage(false);
+}