name: fwh-toolbox-rules

description: FranklinWH 工具箱平台的操作规则集。当涉及以下任一场景时必须使用本技能并加载对应参考规则：(1) 通过 storagefile* 工具读取/写入/上传文件，或向用户提供文件下载、导出、生成报告；(2) 通过 @officecli 工具批量写入 .xlsx/.docx/.pptx；(3) 使用公司 PPT 模板生成演示文稿（用户提到“公司模板/company template/用模板生成 PPT”）；(4) 需要用 Python3 运行自定义脚本做数据处理/计算/转换（只能通过沙箱执行器 fwh-pyrun 运行）。本技能规定这些操作的强制参数、输出标记、批量写入方式、模板路径与 Python3 沙箱运行方式。

FranklinWH 工具箱操作规则

本技能汇总平台在“文件输出、officecli 批量写入、PPT 模板、Python3 沙箱执行”四类操作上的强制规则。按下面的对照表，在对应操作前加载相应参考文件并严格遵循。

何时加载哪份规则

操作场景	必读参考
任何 `storage_file_write` / `storage_file_upload` / `storage_file_read*` / `storage_file_list` 调用；给用户下载/导出/生成报告	`references/file-output-rules.md`
通过 `@officecli` 批量写入 `.xlsx` / `.docx` / `.pptx`	`references/officecli-batch-rules.md`
使用公司 PPT 模板生成演示文稿	`references/ppt-template-rules.md`
需要用 Python3 做自定义数据处理/计算/转换（现成工具无法覆盖时）	`references/python-rules.md`

文件输出：两条必守硬约束（无条件遵守，无需展开也要执行）

调用 storage_file_write / storage_file_upload 必须传 userId 和 sessionId，取自用户消息开头的 [context] userId=xxx sessionId=xxx 行。
写入/上传成功后，必须在回复中独占一行输出下载标记（不要放进代码块）：
```
$$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<文件大小>}$$
```
完整的读/写策略、判断标准与示例见 references/file-output-rules.md。

officecli 批量写入：核心红线

永远不要用 --input -（stdin），MCP 环境无 stdin 管道，会永久卡住。
批量首选 batch <file> --commands '[...]' --json 一次内联完成；仅超大批量才用 --input <真实文件路径>。
详细决策顺序与转义规则见 references/officecli-batch-rules.md。

PPT 模板：要点

用户提到“公司模板 / company template / 用模板生成 PPT”时，使用 __KIRO_HOME__/templates/company-template.pptx，先拷贝到 /tmp/fwh-toolbox-agent/ppt/ 再编辑。
布局/配色/首尾页规则见 references/ppt-template-rules.md。

Python3 沙箱执行：核心红线

仅当现成工具（@fwh-tools / @officecli / knowledge）无法完成时才写 Python3。
Python3 只能通过沙箱执行器运行，命令固定为： __KIRO_HOME__/bin/fwh-pyrun /tmp/fwh-toolbox-agent/scripts/<name>.py [参数...]。
禁止直接 python3 / python -c / 命令拼接 / 管道（配置层会拒绝）。
脚本只能读写 /tmp/fwh-toolbox-agent/ 内文件、无网络、仅标准库；输入先用 storage_file_read_to_local 下载进沙箱，产物交付用户走 storage_file_upload + 下载标记。
资源限额：CPU ≤ 30s、内存 ≤ 1GB、总运行 ≤ 60s，超限即被终止。
完整规则见 references/python-rules.md。