---
name: offline-script-factory
description: '把已经完成或已经明确的需求沉淀成可重复运行的本地脚本、CLI 或自动化 bundle，供用户以后离线直接执行。用户表达如“把这个需求做成脚本”“沉淀成离线工具”“转成可本地运行的脚本”“以后直接离线跑”“不要每次都重新问代码 agent”时使用。适合在一次性方案已经验证可行之后，将过程固化为可复用脚本。若需求仍依赖网页、云 API 或远程模型，必须只固化离线部分并明确剩余在线边界。'
---

# 离线脚本工厂

## 目标

把一次性解决方案变成以后可重复运行的本地脚本，而不是让用户反复重新提需求。

## 工作流

1. 提炼自动化契约

- 从已完成任务、执行过的命令、产出文件和目标行为里提炼脚本规格。
- 编码前先写清 5 个事实：目的、输入、输出、副作用、约束。
- 把可能变化的部分提升为参数、配置文件或环境变量。

2. 判断离线可行性

- 去掉依赖 Codex 推理、联网检索、云服务调用的部分。
- 若原需求无法完全离线化，只固化本地可执行部分，并明确剩余在线边界。
- 仍依赖网站、云 API 或远程模型时，不要把产物描述成“纯离线脚本”。

3. 选择运行时

- Windows 原生自动化优先选 PowerShell：文件、注册表、计划任务、服务、进程控制、Office 周边操作。
- 结构化数据处理优先选 Python：解析、转换、报表、标准库逻辑。
- 优先选择用户机器上已经具备且最容易复用的运行时。

4. 生成脚手架

- 从零开始时，先运行 `scripts/init_offline_bundle.py` 生成最小 bundle，再补上任务逻辑。
- 默认保持最小结构：一个可执行脚本、一个 `bundle.spec.json`，必要时再加 `config.example.json`。
- 除非目标运行时确实无法暴露帮助入口，否则不要额外生成说明文档，把用法内置进脚本本身。

5. 为复用而实现

- 默认把使用说明内置到脚本中，而不是额外生成说明文件。
- Python 脚本默认提供 `--help`。
- PowerShell 脚本默认提供 `-Help`，并补充 comment-based help 以支持 `Get-Help`。
- 默认生成 `bundle.spec.json`，把入口脚本、帮助命令、自检命令、运行时和用途说明集中写在一个地方。
- 通过参数、配置承接路径和阈值，不要把机器相关值硬编码进脚本。
- 增加输入校验、明确错误信息和非零退出码。
- 涉及文件或系统状态变更时，优先提供 `--dry-run`、`--what-if` 或等价安全开关。
- 默认让脚本可重复执行，或至少让重复执行的后果清晰可控。
- 新生成的脚本默认应提供一个安全验证入口，例如 `--self-test`、`--dry-run` 或演示模式。

6. 自运行验证并回修

- 生成脚本后，必须亲自运行至少一次，不允许“未运行就交付”。
- 先运行帮助命令，再运行安全验证命令，优先顺序如下：
  1. `--help` 或原生帮助
  2. `--self-test`、`-SelfTest`、`--dry-run`、`--what-if`
  3. 若存在安全样例输入，再运行一次贴近真实场景的命令
- 若脚本运行失败，读取具体命令、退出码、stdout、stderr，然后立即修改脚本并重新运行。
- 默认持续执行“运行 -> 观察错误 -> 修改 -> 再运行”的循环，直到通过，或遇到明确外部阻塞。
- 只有在以下情况才停止自动修复：缺少本地依赖、缺少必须输入文件、权限/策略阻止执行、或用户原需求本身无法安全本地复现。
- 如果验证只能做到部分执行，必须在最终回复里明确写出“实际运行了什么、没运行什么、为什么没运行”。

7. 交付结果

- 返回产物路径、所需运行时、示例命令和已知限制。
- 把说明写短，真正的交付物是脚本本身。

## 产物标准

除非任务明显更复杂，否则默认使用：

```text
<bundle-name>/
  <bundle-name>.py | <bundle-name>.ps1
  bundle.spec.json
  config.example.json   # 仅在确实需要稳定配置时加入
```

遵守这些默认规则：
- bundle 名称使用稳定的动宾结构。
- 入口脚本名称默认跟 bundle 名一致，避免使用 `run` 这类过于泛化的名字。
- 把用途、入口、帮助命令、自检命令集中写进 `bundle.spec.json`。
- 能用参数传递时，不要在源码里写死绝对路径。
- 依赖尽量限制在标准库或用户机器上已有工具。
- 让重复执行安全，或者至少让风险显式可见。

## 中文输出要求

- 默认使用中文说明、中文命令示例解释、中文错误总结。
- 若生成给用户看的帮助文本、终端输出、注释没有特殊约束，优先写中文。
- 若脚本面向现有英文接口或第三方参数，保留必要的英文参数名，但对外解释仍用中文。

## 通用性要求

- 将核心流程写成 agent 中立的操作，不依赖某一家模型厂商的专有能力。
- 避免把步骤表述成只有 Codex 才能完成；统一使用“agent”或“代码 agent”。
- 若运行环境支持技能/skill 机制，则直接调用本 skill；若不支持，则读取本文件并按工作流执行，效果应保持一致。
- `agents/openai.yaml` 仅用于 OpenAI/Codex 的界面元数据；核心逻辑以 `SKILL.md` 和 bundled resources 为准，其他 agent 可以忽略该文件。

## 资源使用

判断离线可行性、运行时选择、安全开关和验证闭环时，读取 `references/offline-automation-checklist.md`。

从零生成 bundle 时，运行 `scripts/init_offline_bundle.py`。生成后优先 patch 已有文件，不要反复重建目录。

当一个目录下积累了多个 bundle 时，运行 `scripts/update_bundle_index.py` 生成或刷新总索引，方便后续 agent 先查本地能力再决定是否新建。

交付前或批量整理 bundle 时，运行 `scripts/validate_bundle_metadata.py` 校验 `bundle.spec.json` 和 `bundles.index.json` 的结构是否完整。

## 最终回复

至少包含：
- 具体 bundle 路径。
- 1 到 2 条示例命令。
- 依赖或环境假设。
- 实际执行过的验证命令。
- 若发生过失败修复，简要说明修过什么。
- 若原需求无法完全离线，直接说明剩余在线边界。