FranklinWH-Toolbox/deploy/kiro/skills/fwh-toolbox-rules/references/python-rules.md

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 + 输出下载标记。