task-director

# 任务导演 / Task Director 把复杂任务编排成电影剧本。**先看分镜，确认后再开机。** No more "run and pray". Plan first, execute with confidence. ## 核心理念 普通 Agent 的工作方式： ``` 用户：部署这个项目 Agent：冲！（5分钟后报错）啊... 从头再来... ``` 用任务导演的 Agent： ``` 用户：部署这个项目 Agent：我给你写了个分镜，你看看？ 🎬 第一幕：环境检查（预计 30s） 🎬 第二幕：安装依赖（预计 2min） 🎬 第三幕：构建部署（预计 5min） 🎭 备选：先本地测试 🎬 杀青：验证服务能访问 用户：第三幕的备选方案换成本地构建 Agent：好的，改了。开机？ 用户：开机！ Agent：🎬 Action! 第一幕... ``` ## 命令参考 DIRECTOR = python <skill_dir>/scripts/director.py ### 创建剧本 ```bash $DIRECTOR create --title "部署全栈项目" --scenes scenes.json ``` scenes.json 格式： ```json [ { "name": "环境准备", "description": "检查并配置运行环境", "estimated_time": "1 min", "shots": [ { "action": "检查 Node.js 版本", "command": "node --version" }, { "action": "安装项目依赖", "command": "npm install", "fallback": { "action": "使用 yarn 安装", "command": "yarn install" } } ] }, { "name": "构建部署", "shots": [ { "action": "执行构建", "command": "npm run build" } ] } ] ``` **Shot 的字段：** - `action` (必填): 要做什么 - `command` (可选): 具体命令 - `fallback` (可选): 失败后的备选方案 ### 查看剧本 ```bash $DIRECTOR show # 显示当前活跃的剧本 $DIRECTOR show --id movie_xxx # 按 ID 查看 ``` ### 批准剧本 ```bash $DIRECTOR approve ``` 状态从 `draft` → `approved`，可以开始执行了。 ### 开机拍摄（执行下一步） ```bash $DIRECTOR action ``` 输出下一个待执行的 shot 信息（JSON 格式），Agent 根据这个信息去实际执行。 指定某一幕某个镜头： ```bash $DIRECTOR action --scene 2 --shot 1 ``` ### 记录结果 Agent 执行完后，回报结果： ```bash # 成功 $DIRECTOR result --id movie_xxx --outcome done --output "v18.0.0" # 失败 $DIRECTOR result --id movie_xxx --outcome ng --output "npm ERR! code ERESOLVE" # 用备选方案成功 $DIRECTOR result --id movie_xxx --outcome done --fallback --output "yarn install success" ``` ### 暂停 / 继续 ```bash $DIRECTOR cut # 暂停（导演喊卡） $DIRECTOR action # 继续拍摄 ``` ### 跳过镜头 ```bash $DIRECTOR skip --scene 1 --shot 3 --reason "不需要这一步" ``` ### 杀青 ```bash $DIRECTOR wrap ``` 显示最终统计：耗时、完成率、失败数。 ### 查看所有剧本 ```bash $DIRECTOR list ``` ## Agent 工作流 ### 创建剧本（Agent 自动生成） ```python import json scenes = [ { "name": "环境检查", "estimated_time": "30s", "shots": [ {"action": "检查 Python 版本", "command": "python --version"}, {"action": "检查依赖是否安装", "command": "pip list | grep flask"}, ] }, { "name": "启动服务", "estimated_time": "10s", "shots": [ { "action": "启动 Flask 服务", "command": "python app.py", "fallback": { "action": "使用 gunicorn 启动", "command": "gunicorn app:app" } }, ] }, { "name": "验证", "estimated_time": "5s", "shots": [ {"action": "检查端口是否监听", "command": "curl http://localhost:5000/health"}, ] }, ] with open("scenes.json", "w") as f: json.dump(scenes, f, ensure_ascii=False, indent=2) ``` ### 执行循环 ``` 1. $DIRECTOR action → 获取下一个 shot 2. Agent 执行 shot 中的 command 3. $DIRECTOR result --id xxx --outcome done --output "..." → 记录结果 4. 如果有下一个，回到步骤 1 5. 全部完成后 $DIRECTOR wrap → 杀青 ``` ### 失败处理 ``` 1. $DIRECTOR action → 获取 shot 2. Agent 执行，失败了 3. $DIRECTOR result --id xxx --outcome ng --output "报错信息" 4. $DIRECTOR action → 自动识别有 fallback，返回备选方案 5. Agent 执行备选方案 6. $DIRECTOR result --id xxx --outcome done --fallback --output "..." ``` ## 状态流转 ``` draft → approved → filming → wrapped ↘ cut → filming ``` Shot 状态： ``` pending → running → done / ng → fallback (if available) → done ↘ skipped ``` ## 目录结构 ``` task-director/ ├── SKILL.md # 本文件 ├── scripts/ │ └── director.py # CLI 工具 └── templates/ └── example-scenes.json # 示例剧本 ``` ## 数据存储 剧本保存在 `~/.openclaw/memory/movies/`，每个剧本一个 JSON 文件。 ## 设计哲学 - **电影隐喻**：用直觉化的概念降低理解成本 - **先规划后执行**：让用户有掌控感 - **备选方案**：不是只有一条路 - **随时喊卡**：可以暂停、跳过、重来 - **全程可视化**：进度条 + 状态图标一目了然