Pi 自定义工具与权限控制教程

一、从窄工具开始

自定义工具应只完成一个清晰动作，例如读取指定目录下的文件摘要。不要直接暴露任意 shell、任意路径或任意网络请求。

TOOL_NAME = "read_project_file"
MAX_BYTES = 100_000
ALLOWED_ROOT = "/path/to/project"

上面的路径只是占位符。实际项目应使用配置目录，并在运行前确认目录权限。

二、参数必须再次校验

from pathlib import Path

def safe_path(root: str, requested: str) -> Path:
    base = Path(root).resolve()
    target = (base / requested).resolve()
    if target != base and base not in target.parents:
        raise ValueError("path outside project")
    return target

模型输出的参数不能视为可信输入。服务端或工具实现必须再次校验路径、类型、大小和允许的操作。

三、设置资源边界

• 限制单次读取字节数和返回文本长度。
• 为外部请求设置超时、域名白名单和响应大小上限。
• 为工具循环设置最大调用次数，避免意外重复操作。
• 将写入、删除、发送和部署等敏感动作设置为人工确认。

四、逐步启用和调试

1. 先只启用只读工具。
2. 用合法、缺失和越权参数分别测试。
3. 确认日志不包含 API Key、Cookie 或完整个人数据。
4. 再增加受限写入，并保留 Git 差异和回滚方案。

五、验收清单

工具名、参数 schema、权限、超时、错误结构和日志字段都应有明确约定。未知工具、非法路径、超时和重复调用必须得到可预测结果。