# Python3 使用规则（沙箱内执行）

本平台的 Python3 只能通过沙箱执行器 `fwh-pyrun` 运行。`fwh-pyrun` 用 bwrap 建立强制隔离，
并施加资源限额；**沙箱是内核级强制边界**，以下约束即便脚本不遵守也会被系统拦截，但仍需遵守
以免脚本报错或产出无效结果。

## 何时使用 Python3

- 仅当 `@fwh-tools` / `@officecli` / `knowledge` 等工具**无法完成**的自定义数据处理、计算、格式转换时，才写 Python。
- 能用现成工具完成的，优先用工具，不要写 Python 重复实现。

## 唯一允许的运行方式

1. 先用 `write` 把脚本写到沙箱目录，建议放 `/tmp/fwh-toolbox-agent/scripts/<name>.py`。
2. 通过下面的命令执行（这是**唯一**被放行的方式）：
   ```
   __KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/<name>.py [参数...]
   ```
3. **禁止**以下写法（配置层 `allowedCommands` 会直接拒绝，不要尝试）：
   - 直接 `python3 xxx` / `python xxx`
   - `python3 -c "..."`（内联代码）
   - 任何命令拼接或管道：`; | &`
   - 运行沙箱目录之外、或非 `.py` 结尾的脚本

## 脚本内约束（沙箱已强制，遵守以免失败）

- **文件范围**：只能读写 `/tmp/fwh-toolbox-agent/` 下的文件。沙箱外路径（`/home`、项目目录、
  `/etc` 写入、凭据等）不可见或不可写，访问会抛 `FileNotFoundError` / `PermissionError`。
- **无网络**：沙箱内没有网络接口。不要 `import requests` / `urllib` / `socket` 发起网络请求，会失败。
  需要外部数据时，改用 MCP 数据工具（`@fwh-tools/data_*` 等）取回后再交给脚本处理。
- **仅标准库**：只用 Python 标准库。不要 `pip install`（沙箱只读且无网，必然失败）。
- **输入文件**：需要处理的远端/对象存储文件，先用 `storage_file_read_to_local` 下载到
  `/tmp/fwh-toolbox-agent/downloads/`，再在脚本里按本地路径读取。
- **输出文件**：脚本产物写到 `/tmp/fwh-toolbox-agent/` 下；若需交付用户，脚本运行后由你用
  `storage_file_upload` 上传并按 `references/file-output-rules.md` 输出 `$$FILE_DOWNLOAD:...$$` 标记
  （上传动作由工具完成，不在脚本内做）。

## 资源限制（会被强制，超限即终止）

- CPU 时间 ≤ 30 秒，虚拟内存 ≤ 1GB，单文件写入 ≤ ~128MB，总运行 ≤ 60 秒。
- 若数据量大导致超时/超内存：改为分批处理、流式读取，或改用 MCP 数据工具在数据侧聚合，
  减少 Python 侧的数据量。

## 典型流程示例

1. `write` → `/tmp/fwh-toolbox-agent/scripts/analyze.py`（只用标准库，读写沙箱内路径）。
2. 若需输入数据：先 `@fwh-tools` 查询或 `storage_file_read_to_local` 下载到沙箱。
3. 执行：`__KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/analyze.py`。
4. 读取脚本产物（沙箱内），如需交付用户再 `storage_file_upload` + 输出下载标记。