parallel-vibe

Files (8)

• CHANGELOG.md
• README.md
• SKILL.md
• config.yaml
• 工作区隔离机制.md · docs/
• cli_prompt_usage.md · references/
• smart-mode-protocol.md · references/
• parallel_vibe.py · scripts/

SKILL.md (first lines)

# parallel-vibe

## 目标

当用户明确要求"并行或串行启用多个 Agent"，或上游 Skill 声明需要统一执行底座时使用。`parallel-vibe` 负责 Agent 的创建、工作区隔离、调度、回收和结果汇总，覆盖 focused-agent、sequential 和 parallel 三种策略。默认使用智能模式：由宿主原生 subagent 独立分析并由主 agent 汇总；智能模式和代码模式必须使用同一套 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/{yyyy-mm-dd-hh-mm}/` 运行目录、`@main/plan.json`、thread `workspace/`、`RESULT.md` 与 `runner.log` 契约，区别只在底层执行机制；当用户要求脚本 runner、plan-file、resume、跨 CLI runner、退出码或无可用 subagent 时，切换到代码模式并调用 `scripts/parallel_vibe.py`。⚠️ 不适用：普通 shell 并发、单元测试并发、下载任务、要求强安全隔离或处理高度敏感数据。

## 流程

### 输入

输入为需要 Agent/thread 串行或并行评估、设计或执行的用户任务，或上游 Skill 交付的执行计划；可选输入包括线程数、智能/代码模式、`plan-file`、`project-id`/`resume`、runner 参数和源目录。普通 shell/测试并发、下载任务及高度敏感数据不使用本 Skill。

### 执行步骤

#### 模式选择

`parallel-vibe` 有两种模式：

- **智能模式（默认）**：使用宿主工具的原生 subagent / 独立上下文能力，让多个 thread 独立分析同一任务，主 agent 最后综合共识、分歧、推荐路线和验证步骤。
- **代码模式（保留）**：调用 `parallel-vibe/scripts/parallel_vibe.py`，由 CLI runner 在各 thread 的 `workspace/` 内执行，用于可追溯批处理、失败退出码和下游 skill 自动化。

目录管理是模式无关的。两种模式都使用同一套运行目录。默认 run id 为 `{yyyy-mm-dd-hh-mm}`，同一分钟重复运行时追加 `-02` 等后缀；代码模式显式传 `--project-id` 时可复用该值作为 run/project id：

- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/project.json`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/@main/plan.json`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/@main/plan.md`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/@main/summary.md`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/workspace/`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/workspace/RESULT.md`（优先产物）
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/RESULT.md`（汇总用副本或兜底）
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/runner.log`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/prompt.txt`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/thread.json`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/done.json`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/exit_code.txt`

路由规则：

1. 用户只是要求多个 agent 独立想方案、审查、优化、评估风险或对比路线时，使用智能模式。
2. 用户要求固定目录、`.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/`、`@main/plan.json`、`RESULT.md` 或 `runner.log` 时，仍可使用智能模式；这些是共享目录契约，不是代码模式专属触发条件。
3. 用户明确要求“代码模式”“脚本模式”“CLI runner”“plan-file”“resume”“dry-run”“退出码”、跨 `codex` / `claude` / `shell` runner，或下游 skill 需要脚本可复跑批处理时，使用代码模式。
4. 宿主没有可用 subagent 能力，或当前环境无法可靠启动独立上下文时，回退代码模式。
5. 涉及多个 agent 并行修改文件时，仍先按共享目录创建每个 thread 的 `workspace/`；如果宿主不能把 subagent 绑定到各自 `workspace/`，改用代码模式，或让智能模式只输出方案 / diff / patch 建议，由主 agent 单点落地。

`config.yaml` 中的 `defaults.mode`、`modes.smart`、`modes.code` 只表达模式口径，不要求宿主一定能以代码读取；真正执行仍以本节路由和用户意图为准。

#### 智能模式工作流

适用场景：方案探索、代码审查、风险评估、文档优化、研究假设打磨，以及“让多个独立 agent 给意见再汇总”的任务。

执行步骤：

1. 从用户消息提取任务、期望 thread 数和是否需要串行或并行；用户未指定时，按任务复杂度选择 3-5 个 thread。
2. 先创建共享运行目录。可直接按“模式选择”中的目录契约创建，也可运行代码模式脚本的 `--plan-only` 只初始化目录和 workspace，不启动 runner。
3. 为每个 thread 规划独立角色，例如保守方案、激进方案、测试边界、风险审查、用户体验审查，并写入 `@main/plan.json` / `@main/plan.md`。
4. 启动宿主原生 subagent 或等价独立上下文；每个 subagent 只读取用户任务和分配给自己的 thread prompt，不读取其他 thread 的结果。
5. 要求每个 subagent 把结论写入自己的 `<thread_id>/workspace/RESULT.md`；如果宿主无法让 subagent 直接落盘，主 agent 必须把其返回内容保存到 `<thread_id>/RESULT.md`，并在 `runner.log` 写入“由宿主 subagent 返回内容兜底落盘”的说明。
6. 每个 thread 完成后补齐 `done.json`、`exit_code.txt` 和 `runner.log`；智能模式没有真实 CLI 退出码时，成功用 `0`，失败或未完成用 `1`。
7. 主 agent 汇总共识、主要分歧、推荐路线和最小验证步骤，写入 `@main/summary.md`，再交付给用户。

智能模式与代码模式的目录管理必须一致。需要完整协议时，读取 `references/smart-mode-protocol.md`。

面向用户的输出至少包含：

- 运行模式：`智能模式`
- project 目录：`.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/`
- thread 数与串行/并行策略
- 每个 thread 的角色与一句话结论
- 综合结论：推荐路线、共识、主要分歧
- 验证步骤：可执行命令或人工检查点

重要边界：共享目录契约不等于强安全隔离。智能模式的独立性来自宿主 subagent / 独立上下文；代码模式的独立性来自 CLI runner + `cwd=workspace/`。实现型任务必须确保每个执行单元只写自己的 `workspace/`，否则让 subagent 输出方案或 patch 建议，由主 agent 选择并落地。

#### 代码模式工作流

适用场景：需要脚本 runner、`--plan-file`、`--resume`、`--dry-run`、失败日志、真实退出码、跨 `codex` / `claude` / `shell` runner，或被 `git-pr-review`、`research-idea`、`auto-draw-plot` 等下游 skill 作为稳定批处理接口调用。

输入：

- 必需：`prompt`（用户原始指令）或 `--plan-file`
- 可选：`n`（线程数，默认 5，范围 1-9；用户明确要求则以用户为准）
- 可选：每个 thread 的 `runner/model/prompt`（通过 `@main/plan.json` 或 `--plan-file` 自定义）
- 可选：`--project-id/--resume`（复用已有 run/project 目录）
- 可选：`--parallel/--max-parallel`（用户明确要求并行时使用）

输出：

- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/@main/plan.json`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/@main/summary.md`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/RESULT.md`
- `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/parallel-vibe/<run_id>/<thread_id>/runner.log`

运行脚本（在用户当前目录或系统级 skill 目录中选择可用路径）：

```bash
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
```

```bash
python3 ~/.codex/skills/parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
# 或
python3 ~/.claude/skills/parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
```

常见参数：

```bash
# 指定线程数（默认 5）
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --n 5

# 复用已有 run/project
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --project-id <run_id> --resume

# 只生成计划与工作区，便于先审查 plan
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --plan-only

# 使用自定义 plan（JSON）

From huangwb8/skills, MIT.

More from huangwb8/skills