Pi Agent: 安全与项目信任
最后更新：2026-08-31
Agent 能帮你执行命令，也能帮你闯祸——安全机制就是那个"刹车"。
1. 安全模型概览
Pi Agent 的安全基于三层模型：
TEXT
📖 仅展示
安全三层模型
├── 第一层：项目信任（Project Trust）—— 是否允许 Agent 访问项目
├── 第二层：工具权限（Tool Permission）—— 哪些工具可以使用
└── 第三层：执行沙箱（Execution Sandbox）—— 工具执行的安全边界
2. 项目信任
(1) 信任级别
| 级别 | 说明 | 允许的操作 |
|---|---|---|
| untrusted | 不信任 | 只能对话，不能访问文件或执行命令 |
| readonly | 只读信任 | 读取项目文件，不能修改或执行 |
| trusted | 完全信任 | 读写文件、执行命令 |
| restricted | 受限信任 | 自定义白名单操作 |
(2) 设置信任级别
BASH
# CLI 设置
pi-agent trust set ./my-project --level trusted
# 查看信任状态
pi-agent trust list
(3) 首次交互提示
首次在项目目录使用 Pi Agent 时：
TEXT
📖 仅展示
🔒 检测到新项目：/home/alice/my-project
是否信任此项目？ [y/N]
trusted - 完全访问（读写文件、执行命令）
readonly - 只读访问（只能读取文件）
untrusted - 不允许访问
选择信任级别:
(4) Python API
PYTHON
from pi_agent import Agent, TrustLevel
agent = Agent(
name="safe_agent",
project_path="./my-project",
trust_level=TrustLevel.READONLY
)
3. 工具权限
(1) 危险等级
| 等级 | 工具示例 | 默认状态 |
|---|---|---|
| 安全 | calculator, search | 默认启用 |
| 中等 | file_reader | 需要确认 |
| 危险 | file_write, shell | 需要明确授权 |
(2) 权限配置
YAML
# .pi-agent.yaml
permissions:
tools:
safe: auto # 安全工具自动允许
medium: confirm # 中等工具需确认
dangerous: deny # 危险工具默认拒绝
# 或精细控制
allow:
- calculator
- search
- file_reader
deny:
- shell
- file_write
# 交互确认
confirm_dangerous: true
confirm_file_write: true
confirm_shell: true
(3) 运行时确认
TEXT
📖 仅展示
you> 删除所有临时文件
⚠️ Agent 想要执行: rm -rf /tmp/project_*
允许？ [y/N/a(always)]
4. 执行沙箱
(1) 沙箱模式
PYTHON
from pi_agent import Agent
agent = Agent(
name="sandboxed",
sandbox=True, # 启用沙箱
sandbox_dir="/tmp/pi_sandbox", # 沙箱目录
allowed_commands=["python", "pytest"], # 允许的命令白名单
max_execution_time=30 # 最大执行时间（秒）
)
(2) 文件系统隔离
沙箱模式下，Agent 的文件操作被限制在沙箱目录内：
PYTHON
agent = Agent(
sandbox=True,
sandbox_dir="./workspace/sandbox",
allowed_paths=["./data/", "./output/"] # 额外允许的路径
)
(3) 网络限制
PYTHON
agent = Agent(
sandbox=True,
network_access=False, # 禁止网络访问
allowed_domains=["api.github.com"] # 白名单域名
)
5. 最佳安全实践
(1) API 密钥保护
BASH
# 使用环境变量，不要写进配置文件
export PI_DEEPSEEK_API_KEY="sk-xxxxxxxx"
# .gitignore 中排除
echo ".pi-agent.local.yaml" >> .gitignore
(2) 最小权限原则
PYTHON
# 只给 Agent 必要的权限
agent = Agent(
tools=["file_reader"], # 只读，不给写权限
trust_level=TrustLevel.READONLY
)
(3) 审计日志
PYTHON
agent = Agent(
audit_log=True,
audit_file="./audit.log"
)
# 审计日志记录所有工具调用
# [2026-08-28 10:30:00] TOOL_CALL: file_reader(path="main.py")
# [2026-08-28 10:30:05] TOOL_CALL: shell(cmd="python main.py")
▶ 示例 1：安全代码审查 Agent（难度⭐⭐）
PYTHON
from pi_agent import Agent, TrustLevel
agent = Agent(
name="secure_reviewer",
trust_level=TrustLevel.READONLY,
tools=["file_reader"],
sandbox=True,
audit_log=True,
system_prompt="你是安全审查专家，只审查代码，不做任何修改"
)
result = agent.run("审查 src/auth.py 的安全性")
❓ 常见问题
Q 信任了项目后可以撤销吗？
A 可以。
pi-agent trust set ./project --level untrusted 或删除 ~/.pi-agent/trust/ 下对应的文件。Q shell 工具太危险，能完全禁用吗？
A 可以。在配置中
deny: [shell] 或不将 shell 加入工具列表。这是推荐做法。Q 沙箱对性能有影响吗？
A 文件系统隔离几乎没有性能损失。网络限制可能影响需要联网的工具。
📖 小节
- 三层安全模型：项目信任 → 工具权限 → 执行沙箱
- 四个信任级别：untrusted、readonly、trusted、restricted
- 工具按危险等级分级：安全（自动）、中等（确认）、危险（拒绝）
- 沙箱隔离文件系统、限制网络、控制执行时间
- API 密钥用环境变量、最小权限原则、开启审计日志
📝 作业
- 基础题（难度⭐）：为你的项目设置 readonly 信任级别，体验受限模式下的 Agent 行为。
- 进阶题（难度⭐⭐）：配置一个沙箱 Agent，只允许读取特定目录和执行 Python 命令。
- 挑战题（难度⭐⭐⭐）：编写一个安全策略文件，定义完整的权限矩阵，并通过审计日志验证策略生效。
