parallel-vibe
与 bensz-collect-bugs 的协作约定
- 因本 skill 设计缺陷导致的 bug，先用
bensz-collect-bugs规范记录到~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。 - 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地
gh上传新增 bug 到huangwb8/bensz-bugs；不要 pull / clone 整个仓库。
目标
把用户的一条指令，拆成多个 thread（任务视角），并在多个**独立工作区（workspace）与多个独立进程（runner 子进程）**中执行：
-
每个 thread 只运行一条终端命令（例如
codex ... exec "..."或claude ... -p "..."），确保进程级独立 -
默认串行跑 threads（省资源、减少 API 限流/轮询风险）；用户明确要求时再并行
-
最终把每个 thread 的产物与日志落盘，并在
@main/生成可追溯的计划与汇总 -
.parallel_vibe/{project_id}/{thread_id}/... -
.parallel_vibe/{project_id}/@main/summary.md（综合汇总）
输入
- 必需：
prompt（用户原始指令） - 可选：
n（线程数，默认 5，范围 1-9；用户明确要求则以用户为准） - 可选：每个 thread 的
runner/model/prompt（通过@main/plan.json或--plan-file自定义） - 可选：
--project-id/--resume（复用已有 project 目录） - 可选：
--parallel/--max-parallel（用户明确要求并行时使用）
输出
你必须向用户返回：
- 本次运行的结果目录：
.parallel_vibe/{project_id}/ - 如何查看汇总：
.parallel_vibe/{project_id}/@main/summary.md
软护栏（必须遵守的操作规范；不是安全隔离）
当你在某个 thread 的 workspace/ 内工作时：
- 只允许读写当前
workspace/及其子目录 - 禁止访问父目录（
..）与任何绝对路径写入 - 禁止读取/写入
.parallel_vibe/{project_id}下的其他 thread 目录 - 产物必须落盘到当前
workspace/（便于追溯与汇总）
说明：parallel-vibe 提供的是“工程隔离”（减少相对路径污染与文件互相覆盖），不是容器/沙箱级的强安全隔离。默认拒绝 --src-dir 中的 symlink（可用 --symlink-policy 覆盖，但存在越界风险）；不要把包含敏感文件（如 .env、SSH key）的目录作为 --src-dir。
工作流
- 从用户消息提取：
- 用户指令原文
prompt - 线程数
n：用户明确要求则照做，否则默认 5 - 是否要求并行：若未明确要求，默认串行
- 用户指令原文
- 规划 thread（启发式，必须落到“可执行命令”）：
- 每个 thread 明确：
thread_id/title/runner/model/prompt - 推荐路由（默认策略）：
claude：规划/审查/风险与边界（强推理、强约束）codex：实现/修改/测试与验证（代码落地）
- 模型选择：
- 用
profile=fast|deep|default表达”任务强度”，再由parallel-vibe/config.yaml:models映射到你本机可用的model_id - 如你已经确定具体模型，也可在计划里直接写
model=<model_id>覆盖 profile
- 用
- effort 等级选择（
low/medium/high）：- 若用户已明确指定，严格遵从用户要求
- 否则根据 thread 的实际 prompt 自主判断：
low：指令简单明确，无歧义（如格式化、重命名、简单查询）medium：中等复杂度（如功能实现、代码重构、文档生成）high：需要深度推理（如架构设计、多步骤分析、有歧义需要深度理解的任务）
- 每个 thread 可独立设置不同的 effort 等级
- 每个 thread 明确：
- 在用户当前目录运行脚本（不要手写编排逻辑）：
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
如果该 skill 已做系统级安装（推荐），脚本通常位于以下路径之一（按你当前平台选择）：
python3 ~/.codex/skills/parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
# 或
python3 ~/.claude/skills/parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>"
常见参数（按需添加）：
# 指定线程数（默认 5）
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --n 5
# 复用已有 project（便于重跑/续跑；每次运行仍会重建各 thread/workspace）
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --project-id <32位md5> --resume
# 只生成计划与工作区（不运行 threads），便于你先改 plan
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --plan-only
# 使用自定义 plan（JSON）
python3 parallel-vibe/scripts/parallel_vibe.py --plan-file /path/to/plan.json --src-dir . --out-dir .
# src_dir 存在 symlink 时的处理策略（默认 error 拒绝；skip 剔除；keep 保留为 symlink）
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --symlink-policy skip
# 用户明确要求并行时才开启（默认串行）
python3 parallel-vibe/scripts/parallel_vibe.py --prompt "<用户指令原文>" --parallel --max-parallel 3
- 打开并阅读汇总：
.parallel_vibe/{project_id}/@main/summary.md
- 向用户交付：
- 汇总结论（以
@main/summary.md为准） - 指向每个 thread 工作区的路径（用户需要时可直接查看/对比）
- 汇总结论（以
自定义 thread（可选）
如需精确控制每个 thread 的 runner/profile/model/prompt，可直接编辑运行产物：
.parallel_vibe/{project_id}/@main/plan.json
然后用同一个 --project-id + --resume 续跑。
注意：--resume 会复用 project 目录与 @main/plan.json，但每次运行仍会重建各 thread 的 workspace/（避免复用旧缓存导致不可追溯/不一致）。
⚠️ 安全提示：如计划中使用 runner.type=shell，它会执行你提供的任意命令模板（仅对受信任的 plan 使用）；并且 shell/工具本身可能读写用户全局缓存目录或访问绝对路径，因此不应将其理解为“安全沙箱”。
Runner 命令形态（给规划用）
本 skill 的关键是假设 runner 支持“一条命令 = 一次独立执行”。
常见形态（以官方文档为准；具体参数以你本机 CLI 为准）：
# OpenAI Codex CLI（非交互执行；全局参数通常放在子命令 exec 之前）
# <effort> 由 AI 根据 prompt 复杂度自主选择：low / medium / high
# 若用户已明确指定 effort，以用户要求为准
codex -m <model_id> -c 'reasoning_effort="<effort>"' exec "你的指令内容"
# Claude CLI / Claude Code（打印模式）
# <effort> 同上，AI 自主规划或遵从用户指定
claude --model <model_id> --effort <effort> -p "你的指令内容"
计划里 runner 参数约定（用于把 --help 中的参数安全落到“一条命令”）：
runner.args：全局参数（放在子命令前；适合codex -c ...、claude --effort ...）runner.sub_args：子命令参数（放在子命令后、prompt 前；适合codex exec --some-flag ...）
清理方式
在触发目录执行：
rm -rf .parallel_vibe