安装 Pi 扩展实战：以 cc-safety-net 为例
从市场一键安装、热加载与行为生效完整实战
以实战案例演示如何在 Piwin 桌面端与 CLI 中安装并启用 Pi 原生扩展，并验证安全拦截能力。
| 属性 | 说明 |
|---|---|
| 文档定位 | 实战操作指引 / Living document |
| 核心关联 | 扩展生态与能力边界、权限管控与安全拦截 |
| 实测版本 | [email protected]，已在 Desktop 桌面端验证生效 |
1. 这个扩展做什么
cc-safety-net 是一个典型的 Pi 运行时扩展，专为防止 Agent 误执行破坏性指令而设计。
它在智能体执行 Bash 命令前进行前置检查，能够精准拦截类似 git reset --hard、rm -rf 等破坏性操作。该扩展仅使用 Pi 的 tool_call 钩子，属于 Piwin 完全支持的 Agent Runtime 核心能力，不依赖任何终端 TUI 界面。
2. 安装扩展
你可以通过图形界面（Desktop）或命令行（CLI）两种方式进行安装：
方式 A：Desktop 市场一键安装（推荐）
- 打开 Piwin Desktop，点击侧边栏或主界面的 市场 入口；
- 在搜索框输入
cc-safety-net，找到对应扩展卡片并点击 安装； - 弹出权限确认窗口：扩展以 Host 用户的系统权限运行，请确保来源受信任并点击确认。
方式 B：终端命令行安装
市场安装完全等同于执行底层的 Pi 原生命令。已安装 Pi CLI 的用户可以直接在终端执行：
bash
pi install npm:cc-safety-net该命令会将 npm 包写入本地 ~/.pi/agent 目录。在 Piwin 界面中会直接识别并标注为 pi-native（Pi 原生）来源。
3. 启用与平滑热生效
- 打开 设置 → 扩展，点击顶部的 刷新 按钮；
- 确认
cc-safety-net被检测并标记为「兼容」，且开关处于打开状态（对于兼容的 Pi 包，Piwin 默认自动启用）； - 生效方式：
- 新建会话：直接生效，开箱即用；
- 正在进行的已有会话：点击扩展卡片右侧的 「应用到当前 Agent」，Piwin 将在当前轮次结束后平滑热挂载，从下一轮对话起立刻生效，无需重启软件。
4. 验证扩展拦截效果
为了验证扩展是否真正工作，可以在一个临时空目录中新建会话，向 Agent 发送以下测试指令：
text
git init && git commit --allow-empty -m init && git reset --hard HEAD预期效果：
- Agent 尝试执行 Bash 遭到阻止；
- 执行失败原因或返回日志中明确出现
CC Safety Net提示，表明扩展已成功拦截该危险指令； - 若 Piwin 自身的权限引擎先弹出了 Bash 确认弹窗，在点击允许后，底层仍会被该扩展作为第二道安全网坚决拦截。
5. 已知限制与运行规范
安全与权限提示
所有已启用的扩展均以 Host 用户的系统操作系统权限 运行。扩展权限机制并非操作系统的沙盒隔离（Sandbox），请务必只安装并启用来源可信的扩展包。
- 命令菜单：扩展通过代码注册的自定义斜杠命令（如
/cc-safety-net）暂不会出现在输入框弹出的/自动补全菜单中； - 能力边界：Piwin 只加载 Agent Runtime 层级的核心能力（自定义工具 Tools、生命周期钩子 Hooks、确认 Confirm / 选择 Select / 输入 Input / 通知 Notify 等交互）；
- 终端界面说明：以自定义终端 TUI、字符高亮、终端主题为主的扩展，在 Piwin 中会被识别为「仅 Pi 终端」且不会加载到桌面端（详见 扩展生态与能力边界）。
6. 卸载扩展
- 图形界面：在 市场 或 设置 → 扩展 的已安装列表中找到卡片，点击移除/卸载；
- 命令行方式：在终端执行：bash执行完毕后，回到 Piwin 的 设置 → 扩展 页面点击 刷新 即可。
pi remove npm:cc-safety-net