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

离线脚本工厂

目标

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

工作流

1. 提炼自动化契约

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

1. 判断离线可行性

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

1. 选择运行时

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

1. 生成脚手架

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

1. 为复用而实现

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

1. 自运行验证并回修

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

1. 交付结果

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

产物标准

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

<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 条示例命令。
• 依赖或环境假设。
• 实际执行过的验证命令。
• 若发生过失败修复，简要说明修过什么。
• 若原需求无法完全离线，直接说明剩余在线边界。