@hugo-ddt/agentglass0.8.2
A novice outcome-approval layer for supported Pi file changes.
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
AgentGlass
一个面向新手的 Pi Agent 文件变更审批扩展。
AgentGlass 面向不熟悉 shell 命令、Git diff 和文件风险的新手用户。它用易懂的语言说明 Pi 准备带来的文件结果，让用户在文件真正变化前确认这个结果。
0.8.2 · 仅支持 Windows
为什么需要 AgentGlass？
AI 助手可能提出技术上有效的文件操作，却没有让新手看清实际影响。AgentGlass 始终把这几个问题放在前面：
哪个文件会变化、会变成什么、出了问题能否恢复？
用户批准的是预期结果和影响，而不是命令、工具名称或模型的隐藏推理。
新手实际看到的流程
- 让 Pi 查看、创建或修改普通项目文件。
- 对于变更，AgentGlass 显示结果卡片：目标文件、预期结果、风险和恢复信息。
- 卡片初始焦点是停止，查看详情不会产生批准。
- 只有确认预期结果清楚后，用户才选择继续。
- AgentGlass 在使用一次性批准前再次检查已批准的操作。
- 执行后只核对卡片明确列出的文件。
普通读取在必要安全检查全部通过后，不需要审批卡片。
/agentglass 菜单还提供创建说明、润色文案、整理文本三个新手起步器。起步器只负责把草稿填入 Pi 输入框：用户可以先编辑，并且必须自行发送。由此产生的文件变更仍需明确审批，只核验卡片列出的文件；只有证据支持时才提供恢复入口。
如果上一次请求被阻止，同一菜单会给出安全的下一步，例如把请求改成更小的普通文件任务。如果已有受支持且完成独立核验的文件结果，菜单会提供“查看这份文件”或“继续调整这份文件”。这些入口不会回放旧工具调用，也不会自动发送新请求；每次新的文件变更都要重新检查并审批。
S 阶段当前任务面板
0.8.2 增加了一个有界的内存内“当前任务”面板。请求进行时，它汇总本轮请求和已经确认的文件事实，也能显示一次请求中的多个文件动作。它只是显示辅助：不会批准变更、回放 raw 工具输入、保留历史、提供整任务撤销，也不会扩大当前文件结果和单文件恢复操作。
这个面板继续遵守下文的审批、核验、恢复和清理边界。
功能
- 面向新手的说明：重点说明文件结果和影响，不要求用户理解 shell 语法或隐藏推理。
- 安全默认值：未知、不支持、敏感、链接和范围外的目标会被阻止。
- 小范围支持：仅支持已验证的 Pi 内置
read、write和edit。 - 任务起步器：通过简短表单创建说明、润色文案或整理文本，并把草稿填入 Pi 输入框。
- 结果后的处理：对已支持且独立核验的结果只读查看，或提交新的调整要求。
- 卡住后的指引：上一次请求不支持或无法安全确认时，给出具体的文件处理下一步。
- 输入框保护：输入框已有内容会保留；起步器不会覆盖、发送或授予审批。
- 恢复独立批准：
/agentglass restore需要单独批准，并且只使用有证据支持的恢复能力。 - 清理独立批准：
/agentglass cleanup只处理已验证的 AgentGlass 私有数据，不能删除项目文件。 - 安全示例：
/agentglass example提供固定的无秘密文件流程。
环境要求
当前已验证环境：
- Windows x64
- Node.js
>=22.19.0 - Pi
>=0.84.3 <=0.85.1
当前版本不支持 macOS 和 Linux。
Pi 需要先安装，并在可交互终端中启动。
注意
Pi 0.85.1 在渲染非常大的内置 edit 预览时可能因 RangeError: Maximum call stack size exceeded 退出（已在约 8 MiB 的预览中复现）。这发生在 AgentGlass 收到工具调用之前，因此 AgentGlass 无法显示审批卡或核验结果。不要把宿主崩溃当成安全阻止。在 Pi 官方修复发布前，请把非常大的修改拆成较小步骤。参见 Pi issue #8036。
快速开始
安装 0.8.2 版本
本次发布的包版本为 0.8.2。包上传完成后，在使用 Pi 的项目目录中执行：
pi install npm:@hugo-ddt/agentglass@0.8.2
在需要保护的项目目录中启动 Pi：
pi
然后输入：
/agentglass help
/agentglass example
输入 /agentglass 打开统一菜单。菜单包含欢迎/帮助、任务起步器、卡住后的处理、当前文件结果、安全示例、恢复和清理；其中部分入口只会在对应结果或数据存在时显示。
不支持的操作
AgentGlass 不批准或执行 shell 命令、依赖安装、项目启动、部署、批量删除、进程管理，以及未知/自定义/覆盖后的工具。它不宣称提供操作系统级沙箱，也不保证能防止恶意共存 Pi 扩展修改工具输入。
如果任务被阻止，应让 Pi 缩小请求或改成文件操作；不要通过禁用 AgentGlass 继续被阻止的任务。
恢复与私有数据
当执行后的证据完整时，当前会话可以为最近一次受支持的单文件变更提供单独批准的恢复。发生冲突时保留后续文件内容。
Windows 私有恢复副本位于：
%PI_CODING_AGENT_DIR%\.agentglass\snapshots
这些副本可能包含恢复所需的原始文件字节，不能保证“无秘密”。卸载不会静默删除它们或项目文件，重新安装也不会恢复旧的审批授权。
禁用或卸载
pi config
pi list
pi remove <已安装来源>
禁用后，AgentGlass 不再保护后续 Pi 调用；这不是绕过阻止的方式。移除包来源与批准清理私有恢复数据是两件独立的事。