feiskyer/codex-settings / skills/deep-research
deep-research
Verified仅在用户显式调用 `$deep-research` 时,用 Codex CLI 子任务完成多来源深度调研并综合成带出处的报告。不用于单次查证或已给定材料的总结。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| agents/openai.yaml | config | 357 B |
| references/runner.md | markdown | 2.8 KB |
| scripts/aggregate.pyexecutable | script | 3.3 KB |
| scripts/run_children.pyexecutable | script | 10.3 KB |
| tests/test_deep_research_scripts.py | script | 5.3 KB |
scripts/run_children.py
View on GitHub#!/usr/bin/env python3
"""Run manifest-defined Codex research tasks concurrently without a shell."""
import argparse
from concurrent.futures import ThreadPoolExecutor, as_completed
import json
from pathlib import Path
import re
import shlex
import shutil
import subprocess
import sys
import time
TASK_ID_RE = re.compile(r"^[A-Za-z0-9._-]+$")
def positive_int(value):
parsed = int(value)
if parsed < 1:
raise argparse.ArgumentTypeError("must be a positive integer")
return parsed
def nonnegative_int(value):
parsed = int(value)
if parsed < 0:
raise argparse.ArgumentTypeError("must be zero or greater")
return parsed
def parse_args(argv=None):
parser = argparse.ArgumentParser(
description="Run Codex research child tasks from a JSON manifest"
)
parser.add_argument("--run-dir", required=True, help="Research run directory")
parser.add_argument(
"--manifest",
default=None,
help="Manifest path (default: <run-dir>/manifest.json)",
)
parser.add_argument(
"--workspace",
default=".",
help="Workspace passed to Codex with -C (default: current directory)",
)
parser.add_argument("--parallel", type=positive_int, default=8)
parser.add_argument("--timeout", type=positive_int, default=600)
parser.add_argument("--retries", type=nonnegative_int, default=0)
parser.add_argument("--codex-bin", default="codex")
parser.add_argument(
"--network",
action="store_true",
help="Allow shell network access inside workspace-write sandboxes",
)
parser.add_argument(
"--resume-existing",
action="store_true",
help="Skip tasks whose non-empty child output already exists",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Validate and print commands without starting Codex",
)
return parser.parse_args(argv)
def resolve_within(base_dir, relative_path, label):
"""Resolve a relative path and reject traversal outside the run directory."""
candidate = (base_dir / relative_path).resolve()
try:
candidate.relative_to(base_dir)
except ValueError as exc:
raise ValueError(f"{label} must stay inside the run directory") from exc
return candidate
def load_manifest(manifest_path, run_dir):
"""Load and validate ordered task definitions."""
payload = json.loads(manifest_path.read_text(encoding="utf-8"))
raw_tasks = payload.get("tasks") if isinstance(payload, dict) else payload
if not isinstance(raw_tasks, list) or not raw_tasks:
raise ValueError("manifest must contain a non-empty tasks list")
tasks = []
seen_ids = set()
for index, raw_task in enumerate(raw_tasks):
if not isinstance(raw_task, dict):
raise ValueError(f"task {index} must be an object")
task_id = str(raw_task.get("id") or "")
if not TASK_ID_RE.fullmatch(task_id):
raise ValueError(f"invalid task id: {task_id!r}")
if task_id in seen_ids:
raise ValueError(f"duplicate task id: {task_id}")
seen_ids.add(task_id)
prompt_value = raw_task.get("prompt_file")
if not isinstance(prompt_value, str) or not prompt_value:
raise ValueError(f"task {task_id} is missing prompt_file")
prompt_path = resolve_within(run_dir, Path(prompt_value), "prompt_file")
if not prompt_path.is_file():
raise FileNotFoundError(f"prompt file not found: {prompt_path}")
tasks.append(
{
"id": task_id,
"title": str(raw_task.get("title") or task_id),
"prompt_path": prompt_path,
"output_path": resolve_within(
run_dir,
Path("child_outputs") / f"{task_id}.md",
"child output",
),
"log_path": resolve_within(
run_dir,
Path("logs") / f"{task_id}.log",
"task log",
),
}
)
return tasks
def resolve_codex(command):
"""Resolve a Codex executable name or explicit path."""
if Path(command).parent != Path("."):
path = Path(command).expanduser()
if path.is_file():
return str(path.resolve())
return None
return shutil.which(command)
def build_command(args, codex_bin, output_path, workspace):
"""Build a least-privilege Codex command for one child task."""
command = [
codex_bin,
"exec",
"--full-auto",
"--sandbox",
"workspace-write",
"--ephemeral",
"--color",
"never",
"-C",
str(workspace),
"--output-last-message",
str(output_path),
]
if args.network:
command.extend(["-c", "sandbox_workspace_write.network_access=true"])
command.append("-")
return command
def append_log(log_path, text):
log_path.parent.mkdir(parents=True, exist_ok=True)
with log_path.open("a", encoding="utf-8") as log_file:
log_file.write(text)
if not text.endswith("\n"):
log_file.write("\n")
def run_task(task, args, codex_bin, workspace):
"""Run one task with bounded retries and return a serializable result."""
output_path = task["output_path"]
log_path = task["log_path"]
output_path.parent.mkdir(parents=True, exist_ok=True)
log_path.parent.mkdir(parents=True, exist_ok=True)
if args.resume_existing and output_path.is_file() and output_path.stat().st_size:
return {"id": task["id"], "status": "skipped", "attempts": 0}
command = build_command(args, codex_bin, output_path, workspace)
prompt = task["prompt_path"].read_text(encoding="utf-8")
started = time.monotonic()
last_error = ""
log_path.write_text(
f"command: {shlex.join(command)}\n",
encoding="utf-8",
)
for attempt in range(1, args.retries + 2):
output_path.unlink(missing_ok=True)
append_log(log_path, f"\n--- attempt {attempt} ---")
try:
completed = subprocess.run(
command,
cwd=workspace,
input=prompt,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
timeout=args.timeout,
check=False,
)
append_log(log_path, completed.stdout or "")
if (
completed.returncode == 0
and output_path.is_file()
and output_path.stat().st_size > 0
):
return {
"id": task["id"],
"status": "success",
"attempts": attempt,
"duration_seconds": round(time.monotonic() - started, 3),
"output": str(output_path),
"log": str(log_path),
}
last_error = (
f"Codex exited {completed.returncode} or produced an empty output"
)
except subprocess.TimeoutExpired as exc:
timeout_output = exc.stdout or ""
if isinstance(timeout_output, bytes):
timeout_output = timeout_output.decode("utf-8", errors="replace")
append_log(log_path, timeout_output)
last_error = f"timed out after {args.timeout} seconds"
append_log(log_path, f"error: {last_error}")
return {
"id": task["id"],
"status": "failed",
"attempts": args.retries + 1,
"duration_seconds": round(time.monotonic() - started, 3),
"error": last_error,
"log": str(log_path),
}
def write_results(run_dir, results):
"""Atomically write ordered task results."""
destination = run_dir / "results.json"
temporary = destination.with_suffix(".json.tmp")
temporary.write_text(
json.dumps({"results": results}, indent=2, ensure_ascii=False) + "\n",
encoding="utf-8",
)
temporary.replace(destination)
return destination
def run(args):
"""Validate the run and execute all manifest tasks."""
run_dir = Path(args.run_dir).expanduser().resolve()
workspace = Path(args.workspace).expanduser().resolve()
if not run_dir.is_dir():
raise FileNotFoundError(f"run directory not found: {run_dir}")
if not workspace.is_dir():
raise FileNotFoundError(f"workspace not found: {workspace}")
manifest_path = (
Path(args.manifest).expanduser().resolve()
if args.manifest
else run_dir / "manifest.json"
)
tasks = load_manifest(manifest_path, run_dir)
codex_bin = args.codex_bin if args.dry_run else resolve_codex(args.codex_bin)
if not codex_bin:
raise RuntimeError(f"Codex executable not found: {args.codex_bin}")
if args.dry_run:
return [
{
"id": task["id"],
"command": build_command(
args,
codex_bin,
task["output_path"],
workspace,
),
}
for task in tasks
]
results_by_id = {}
with ThreadPoolExecutor(max_workers=min(args.parallel, len(tasks))) as executor:
futures = {
executor.submit(run_task, task, args, codex_bin, workspace): task["id"]
for task in tasks
}
for future in as_completed(futures):
task_id = futures[future]
try:
results_by_id[task_id] = future.result()
except Exception as exc:
results_by_id[task_id] = {
"id": task_id,
"status": "failed",
"attempts": 0,
"error": str(exc),
}
ordered_results = [results_by_id[task["id"]] for task in tasks]
write_results(run_dir, ordered_results)
return ordered_results
def main(argv=None):
try:
args = parse_args(argv)
results = run(args)
print(json.dumps(results, indent=2, ensure_ascii=False))
if args.dry_run:
return 0
return 0 if all(item["status"] in {"success", "skipped"} for item in results) else 1
except Exception as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |