---
name: fwh-toolbox-rules
description: FranklinWH 工具箱平台的操作规则集。当涉及以下任一场景时必须使用本技能并加载对应参考规则：(1) 通过 storage_file_* 工具读取/写入/上传文件，或向用户提供文件下载、导出、生成报告；(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` |

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

1. 调用 `storage_file_write` / `storage_file_upload` **必须**传 `userId` 和 `sessionId`，取自用户消息开头的 `[context] userId=xxx sessionId=xxx` 行。
2. 写入/上传**成功后**，**必须**在回复中独占一行输出下载标记（不要放进代码块）：
   ```
   $$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`。