# 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。缺少引擎时告知需要安装 @rsrsai/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 @rsrsai/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，也属于真实写入。
助手必须保留原意，并核对保存内容，不能增添未确认的事实或要求。
以实际回执为准：

- 已存：包含记忆 ID，代表成功写入。写后回读做**全量核验**——`show` 返回的
  条目 ID、标题、完整正文（去首尾空白）须与所发一致才算 verified；前缀相同
  但尾部被改、返回了别的条目、标题不同都如实报 DIFFERENT（要求先查验再改题），
  回读失败或信封畸形则如实报 unavailable，回执保留「已存」；任何回读结果都
  不触发第二次写入。
- 待决（pending）：引擎找到候选，尚未写入；回执转述候选与引擎建议动作。
  建议动作只是「待评估的建议，不是授权」，逐条过滤凭据、限长后转达；
  助手须自行读取候选正文，再决定更新或挂靠。
- 未确认：结果未知，可能已经写入；必须先查库，不能直接重试。

显式快存仍是一次直接 `remember`：为显式保存挑选候选与 parent 依旧是模型的
责任；本版本只为该路径补上写后回读（PI-02 未标记完成——后台 worker 的
候选/parent 闭环未套用到快存）。

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

```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、切换会话及退出会取消旧任务。
失败或中止的主任务不启动收尾；显式存储成功、pending 或未确认的输入均不自动重存。
**不做全库时间抑制**：引擎 `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、模型供应商或用户数据库实测。
供应商是否实际停止网络请求取决于它是否遵守取消信号；后台任务本身到期退出并忽略迟到结果。