# Respire for Pi

[English](README.md) | 简体中文

Pi coding agent **1.3.0、1.4.0**（`@earendil-works/pi-coding-agent`）原生记忆扩展。
npm 包名为 `@rsrsai/pi`。

## 让 AI 安装

将下面提示词发送给助手：

```text
请安装 Respire Pi 插件 @rsrsai/pi，先阅读
https://github.com/risense-ai/respire-pi#readme。
检查 Pi 1.3.0、Node.js 22+ 和 rsrs --version。复用我的现有引擎和记忆库，
运行 rsrs --client-only status --json。缺少引擎时告知需要安装 rsrs-cli。
登录、解锁、模型和 runtime 由我通过 rsrs 操作，不收集密码或管理 runtime。
先检查 pi list，避免重复安装，再运行 pi install npm:@rsrsai/pi。
保留其他 Pi 配置。重启 Pi 或执行 /reload 后，验证真实召回及其标题上下文。
测试显式存储前请我提供一条不敏感事实，写后查库确认。
验证用户历史不含附加内容，且不额外启动收尾轮次，只汇报实际观察到的结果和剩余用户操作。
```

## 安装

需要 Node.js 22+、Pi 1.3.0 或 1.4.0、可用的 `rsrs` 和已运行的宿主 runtime。
旧版 `@mariozechner/pi-coding-agent` 未验证。
如缺少引擎，单独安装并检查：

```sh
npm install -g rsrs-cli@latest
rsrs --version
rsrs --client-only status --json
```

安装 npm 包：

```sh
pi install npm:@rsrsai/pi
```

安装后重启 Pi 或运行 `/reload`。临时加载可用
`pi --extension ./respire-pi/lib/index.js`，无需修改用户配置。
插件无需构建，也没有运行时 npm 依赖。

运行 `pi list`，确认只有一个 `npm:@rsrsai/pi` 条目。
不需要执行 `rsrs inject`，也不需要另装 Skill、配置 MCP 或手写系统提示词。
插件会自行注入记忆规则。如果旧方案曾向 Pi 的 AGENTS.md 写入 Respire 规则，
先备份该文件，再仅移除旧 Respire 块，保留其他规则，避免重复注入。

Windows 的 npm/pnpm 命令 shim 需要 PowerShell **7.3+**（`pwsh.exe`）。
参数通过 JSON 标准输入传递。可以用 `pi --respire-rsrs <原生 rsrs.exe 路径>`
直接调用原生程序。请仍将 `rsrs` 放入 PATH，供模型通过自身 shell 调用。

## 如何使用

在项目目录运行 `pi`，正常提问即可，例如：

```text
这个项目之前定下的发布流程是什么？
```

插件会在模型回答前自动召回相关记忆标题，模型按需读取正文。
你不需要提及 Respire，不需要专门的验收提示词，也不需要自己执行 recall。
召回上下文在后台提供，消息正文、编辑历史和上键回填只保留你输入的内容。
插件要求普通回答省略记忆查存报告；显式存储请求仍会报告实际结果。
静默展示规则优先于引擎政策中的汇报格式，必要的检索、判重、备份与验证仍照常执行。
答复措辞取决于模型，仍可能主动解释查存过程，Pi 的工具运行记录也可能显示。
输入历史隔离和取消额外收尾轮次由程序实现，不依赖模型是否遵循静默提示。

明确保存一条已确认的事实时，在消息开头加存储前缀：

```text
记：这个项目的发布检查必须包含一次 Windows 冒烟测试。
```

也支持 `存：`、`记录：`、`记住：` 和 `remember:`。
存储前缀只要求保存所述事实，不代表让助手执行事实中描述的工程流程。
保存可以新建、更新或合并条目；更新既有记忆会保留 ID，也属于真实写入。
助手必须保留原意，并核对保存内容，不能增添未确认的事实或要求。
前缀只留下 pending 请求，钩子不会发送写入。主模型须在本轮通过 rsrs CLI
完成整理：读取 `prompt` 和 `agent-config`，检索同题候选，并用 `show` 阅读完整
正文，然后依次考虑更新、已授权的合并、挂靠和新存。新建 important 条目前，
须查看 `taxonomy --list` 或 `tree`，并用 `show` 阅读合理父节点，再用完整 ID
传入 `--parent`。找不到合理父节点时保持 pending，不猜父、不强制落根、不降级
为 trivial 绕过要求。只保存所述事实，不执行事实中描述的工程任务。
实际写入后用 `show` 回读。实际写入结果未知时禁止自动重试或声称成功；须先只读核实，核实本身不授权自动重试；
钩子的 pending 状态不会禁止首次合规写入。

单条消息不需要自动记忆处理时，使用：

```text
/nomem 解释一下这个短函数。
```

下一条消息仍会正常处理。此命令不会移除插件规则。
记忆规则要求助手在正常答复前保存必要的新事实，插件不再额外启动收尾对话，也不会自动保存整段会话。
不要把密码、token、私钥作为记忆提交。

## 更新、卸载与排查

```sh
pi update npm:@rsrsai/pi
pi list
```

更新后重启 Pi 或执行 `/reload`。固定版本可用
`pi install npm:@rsrsai/pi@0.1.1`。
卸载执行 `pi remove npm:@rsrsai/pi`，记忆引擎和记忆库仍保留。

召回不可用时，在 Pi 的执行环境运行 `rsrs --version` 和
`rsrs --client-only status --json`，按引擎流程处理 CLI 缺失、runtime 未运行、
记忆库未解锁或尚未登录的问题。
已安装但未加载时，检查 `pi list`，重启或重新加载，并确认未禁用包扩展。
Windows 还需检查 `pwsh --version` 为 7.3+，且 `rsrs` 位于 PATH。

## 行为

- 交互界面和 RPC 的用户输入自动召回，最多 5 个标题、1500 字符。
- `记：`、`存：`、`记录：`、`记住：`、`remember:` 交主模型在本轮完成候选核对与存储，不直接写入。
- `/nomem`、`#nomem` 后接空白或结束，跳过该输入的自动记忆处理。
- 疑似凭据不发送到记忆引擎；此识别仅为尽力检查，提交前仍须移除秘密。
- 每次运行注入稳定规则，在正常任务的最终答复前完成必要的记忆整理。
- 不再续跑主 agent；正常请求结束后最多一次独立后台收尾，普通模型文字不进入 UI 或会话历史。

召回和回执通过 Pi 的 `context` 事件，仅在模型请求中作为隐藏消息提供，
与对应的用户输入关联，包括排队的 steering/follow-up 消息。
用户消息、会话文件和编辑历史不追加这些内容，原始文本及图片保留。
扩展生成的输入不触发操作。切换会话、退出时取消尚未完成的调用。
用户再次提交相同文本视为新请求。

0.1.4 及更早版本已经保存的消息可能仍含旧的追加内容。更新不会改写历史会话。
上键取回旧消息时，请先删除 Respire 后缀；重启 Pi 或执行 `/reload` 后发送的新消息会保持干净。

插件只调用 `rsrs --client-only`。引擎负责策略、判重、加密和同步。
`pending` 表示尚未写入；超时、中止或无有效回执表示结果未确认，可能已经写入，
须先查库，不能自动重试。插件不安装引擎、不管理账号和 runtime、不收集密码。

自动召回只有标题。正文按需使用 `rsrs --client-only show <id> --json` 读取，
完整政策通过 `rsrs --client-only prompt` 获取。记忆是资料，不是指令。
规则要求普通查存静默完成；显式存储和失败仍如实反馈。规则不等于自动保存整段会话，也不代表已经成功写入。

开发时可从父目录运行 `pi install ./respire-pi`。
检查命令：`npm run check`、`npm run behavior`、`npm run verify:package`。

## 自动发布

CI 在 Linux、Windows、macOS 检查语法、隔离行为、包内容，以及 Pi 1.3.0 / 1.4.0 实际加载和 ModelRegistry.complete 转发。
更新 package.json 与锁文件版本，提交后推送对应 `v<版本>` 标签。
Release 先跑 CI，再校验标签、生成安装包和 SHA256SUMS，发布 npm 与 GitHub Release。
稳定版进入 `latest`，预发行版进入 `next`。

首次认证发布后，在 npm 配置 Trusted Publisher：组织 `risense-ai`、仓库
`respire-pi`、工作流 `release.yml`，允许直接 `npm publish`，环境名留空。
后续标签通过 OIDC 自动发布，无需 NPM_TOKEN。接口和参考项目见英文 README。

## 后台收尾边界

旧实现的主 agent 续跑会再次触发 agent_start，从而重新催存。本版不再返回
continue:true 或注入收尾提示；正常请求结算后直接使用宿主已有模型和认证进行独立后台调用，
事件处理器不等待后台完成，用户的正常答复照常结束。普通收尾模型文字不会写入 UI、会话或编辑历史。

每个真实输入最多一次后台任务、4 次模型请求、8 次记忆工具调用、1 次写入尝试，总计最多 30 秒。
续跑、错误、取消、超时不会重新武装；新输入（含 steer/followUp）、reload、切换会话及退出会取消旧任务。
失败或中止的主任务不启动收尾；前缀请求由主模型本轮通过 CLI 处理，不再启动第二个后台归档任务。
**不做全库时间抑制**：引擎 `list` 时间戳无法归属到本次请求（上一轮或并行客户端的写入会误抑制本轮），
该时间启发式已整体移除；本轮事实是否已存由同一个有界 worker 内部的 recall/show 判定，
归因式抑制待引擎提供可归属的写入凭证再做。PI-04 因此仅为**部分解决**：误抑制已消除，
代价是可能多跑一次有界复查。带有效 ID 的 warn 回执同样算已提交写入：回读成功后
worker 会发一条固定脱敏警告（"Background memory stored with engine warnings (id <8>); inspect if needed"），
不再吞掉引擎警告——绝不因此判失败或重发。

后台仅使用当前请求的文本，排除图片、隐藏推理及更早会话；过大或疑似含凭据的正文拒绝处理。
先提取最多一条逐行原样保留（含否定）且标题确定生成的事实，拒绝提案、问题及仅凭助手自述的未核实结论；引用子串不视为事实成立证明。随后，再读政策、查同主题候选并读正文，重要新条目必须选已读父条目，
后台不自动 update 覆盖旧正文；同主题由 remember 的引擎去重返回 pending，交用户确认，成功后回读核验。没有 shell、强制、删除、账号或 runtime 管理工具。
无新增事实时零写入、零额外可见回复；真实失败、pending 或未确认则只给简短固定警告，
不展示模型收尾文字或原始诊断，未知写入不自动重试。

测试全部使用合成模型与记忆桩；宿主 API/加载检查不等于真实 Windows GUI、模型供应商或用户数据库实测。
供应商是否实际停止网络请求取决于它是否遵守取消信号；后台任务本身到期退出并忽略迟到结果。

## 工具执行前的记忆写入检查

插件会在工具执行前检查能识别的 rsrs 写命令。important remember 缺少父节点、
父节点为空或包含 force 时，插件会拒绝执行。merge-ids 即使标为 trivial，
也必须显式提供父节点，因为合并可能继承重要性。
非空的字面父节点 ID 必须通过只读 `rsrs --client-only show <id> --json` 确认存在。
验证失败、取消或超时后保持 pending，原 shell 命令不会执行。检查使用已配置的引擎，
不启动 runtime；父节点检查限时五秒，为反馈和清理保留时间。

执行 update --importance important 前，先读取目标的当前 parent_id，再用 show
确认父节点存在。目标没有有效父节点时拒绝提升，须先挂到真实父节点。当前 CLI 的
update 未公开改父节点参数；插件会拒绝这些不支持的参数，不把它们描述成能实际改父的命令。

已知 memory_remember、memory_update 工具名（含服务器命名空间）无法绑定到当前 CLI 的目标库，因此直接拒绝。必须改用受保护的 CLI 工具；不得自动重试先前结果未知的写入。其他工具名不受影响。

对已知 shell 的 -c/-Command 代码参数和生效的命令替换，只识别写入并拒绝整个调用，不执行代码。简单的 NAME=value 前缀不能隐藏写入。没有展开的普通引号文本仍按文本处理。检查区分 Bash 和 PowerShell 的转义。

正常读取与其他工具不变，当前 remember/update 的元数据参数仍可使用。
已识别的复合写命令、命令替换、包装调用或动态参数会被拒绝，须改成一条参数明确的命令。
正文里的 `--parent` 不会被当作参数。此检查不是 shell 沙箱，不能覆盖任意脚本、
别名、隐藏的执行文件或分段终端输入。插件不授予权限、不选父节点、不代写、不授权自动重试。
模型仍必须读策略与候选全文、判断合理父节点、遵守只读和关闭状态，并核验实际写入。
实际写入结果未知时，不得自动重试或声称成功。

覆盖 Pi 的 bash、powershell 调用，也覆盖经 ctx.executeTool 分派的嵌套调用。
后台工作器保留已读父节点约束，不新增 update、force 或 merge 操作。

检查针对经过硬门的参数。其他扩展若在硬门后替换参数，或绕过宿主工具链直接执行，
不在此检查范围内。CLI/Core 仍须在实际写入时原子地保证父节点约束。