Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

10.7 KB
Raw Blame
#!/usr/bin/env python3
"""Build and verify Classic Cursor/Claude bundles from the reference workflow."""

import argparse
import json
import re
import shutil
from pathlib import Path
from typing import Dict


ROOT = Path(__file__).resolve().parent.parent
ROLES = (
    "architect", "code-reviewer", "developer", "knowledge-engineer",
    "leader", "solo-developer", "test-engineer",
)
HOSTS = ("cursor", "claude")


def is_runtime_artifact(relative: Path) -> bool:
    """Same rule as devflow_cli.core.is_runtime_artifact (kept stdlib-only here)."""
    parts = relative.parts
    if "__pycache__" in parts or relative.suffix in {".pyc", ".pyo"}:
        return True
    for index in range(len(parts) - 2):
        if parts[index:index + 2] == ("agent-observability", "logs"):
            return parts[-1] != ".gitkeep"
    return False


def strip_frontmatter(text: str) -> str:
    if text.startswith("---\n"):
        end = text.find("\n---\n", 4)
        if end >= 0:
            return text[end + 5:].lstrip()
    return text


def description(text: str, fallback: str) -> str:
    match = re.match(r"---\n(.*?)\n---\n", text, re.DOTALL)
    if not match:
        return fallback
    value = re.search(r'^description:\s*["\']?(.*?)["\']?\s*$', match.group(1), re.MULTILINE)
    return value.group(1) if value else fallback


def adapt(text: str, host: str) -> str:
    hidden = f".{host}"
    result = text.replace(".codebuddy", hidden).replace(".codex", hidden)
    result = result.replace("Codex", "Cursor" if host == "cursor" else "Claude Code")
    if host == "cursor":
        result = result.replace("multi_agent_v1.spawn_agent", "Task")
        result = result.replace("spawn_agent", "Task")
        result = result.replace("subagent_name=", "subagent_type=")
    else:
        result = result.replace("multi_agent_v1.spawn_agent", "Agent")
        result = result.replace("spawn_agent", "Agent")
        result = result.replace("Task(", "Agent(")
        result = result.replace("subagent_name=", "subagent_type=")
    result = result.replace("Team 模式", "独立 Subagent 模式")
    result = result.replace("team-async", "isolated-subagent")
    result = result.replace("team member", "阶段 subagent")
    result = result.replace("检查 inbox", "检查当前完整阶段提示")
    result = result.replace("保持阶段 subagent 常驻,等待下次唤醒", "结束当前执行,是否恢复由主 Agent 决定")
    result = re.sub(r',?\s*team_name="[^"]*"', "", result)
    result = re.sub(r',?\s*mode="bypassPermissions"', "", result)
    result = re.sub(r'`use_skill\("([^"]+)"\)`', r'`/\1`', result)
    tool = "Task" if host == "cursor" else "Agent"
    result = re.sub(
        r'`send_message\(recipient="?<?([a-zA-Z0-9-]+)>?"?[^`]*\)`',
        rf'`{tool}(subagent_type="devflow-\1", prompt=<完整阶段提示>)`',
        result,
    )
    result = re.sub(r'subagent_type="(?!devflow-)([a-z][a-z0-9-]+)"', r'subagent_type="devflow-\1"', result)
    return result


def command_frontmatter(source: str) -> Dict[str, str]:
    match = re.match(r"---\n(.*?)\n---\n", source, re.DOTALL)
    values = {}
    if not match:
        return values
    for key in ("description", "argument-hint"):
        found = re.search(rf'^{re.escape(key)}:\s*["\']?(.*?)["\']?\s*$', match.group(1), re.MULTILINE)
        if found:
            values[key] = found.group(1)
    return values


def render_command(source: Path, host: str) -> str:
    raw = source.read_text(encoding="utf-8")
    meta = command_frontmatter(raw)
    if source.name == "start-devflow.md":
        runtime = (ROOT / ".codex/runtime/start-workflow.md").read_text(encoding="utf-8")
        body = "# /start-devflow\n\n按以下 Classic 工作流启动用户提供的需求。\n\n" + adapt(runtime, host)
    elif source.name == "resume-devflow.md":
        body = adapt("""# /resume-devflow

读取 `artifacts/<task-slug>/workflow-state.json`,保留已有产物和 task_slug。
根据 `current_stage`、`last_event` 和 `next_target` 找到首个未完成阶段,使用宿主
Agent 工具创建该阶段对应的全新 `devflow-<role>` subagent,并把状态路径、允许输入、
必需输出和失败信息一次性放入完整提示。阶段返回后更新状态并继续路由。

不得扫描或恢复其他任务的 subagent,不得删除已有产物,不得把失败阶段标成完成。
""", host)
    elif source.name == "abort-devflow.md":
        body = """# /abort-devflow

定位指定任务的 `workflow-state.json`,将 `summary.status` 更新为 `aborted`,记录时间
和用户给出的原因,并停止继续派发新阶段。保留状态和已有产物供审计;不得删除项目
文件或其他任务数据。当前宿主仍有对应 subagent 运行时,只停止该精确任务。
"""
    else:
        body = adapt(strip_frontmatter(raw), host)
    if host == "cursor":
        return body.rstrip() + "\n"
    lines = ["---"]
    if "description" in meta:
        lines.append("description: " + json.dumps(meta["description"], ensure_ascii=False))
    if "argument-hint" in meta:
        lines.append("argument-hint: " + json.dumps(meta["argument-hint"], ensure_ascii=False))
    lines.extend(["---", "", body.rstrip(), ""])
    return "\n".join(lines)


def render_agent(role: str, host: str) -> str:
    source = ROOT / ".codex/agents" / f"{role}.md"
    raw = source.read_text(encoding="utf-8")
    body = adapt(strip_frontmatter(raw), host)
    desc = description((ROOT / ".codebuddy/agents" / f"{role}.md").read_text(encoding="utf-8"), role)
    fields = [
        "---",
        f"name: devflow-{role}",
        "description: " + json.dumps(desc, ensure_ascii=False),
        "model: inherit",
    ]
    if host == "cursor":
        fields.append("readonly: false")
    else:
        fields.append("permissionMode: acceptEdits")
    fields.extend(["---", "", "<!-- generated-by: build-classic-hosts.py -->", body.rstrip(), ""])
    return "\n".join(fields)


def add_tree(files: Dict[str, bytes], source: Path, target_prefix: str, host: str) -> None:
    for path in sorted(source.rglob("*")):
        if not path.is_file() or is_runtime_artifact(path.relative_to(source)):
            continue
        relative = path.relative_to(source)
        target = str(Path(target_prefix) / relative)
        data = path.read_bytes()
        if path.suffix in {".md", ".mdc", ".json", ".yaml", ".yml"}:
            try:
                data = adapt(data.decode("utf-8"), host).encode("utf-8")
            except UnicodeDecodeError:
                pass
        files[target] = data


def expected(host: str) -> Dict[str, bytes]:
    files: Dict[str, bytes] = {}
    for role in ROLES:
        files[f"agents/devflow-{role}.md"] = render_agent(role, host).encode("utf-8")
    for command in sorted((ROOT / ".codebuddy/commands").glob("*.md")):
        files[f"commands/{command.name}"] = render_command(command, host).encode("utf-8")
    add_tree(files, ROOT / ".codex/assets", "assets", host)
    add_tree(files, ROOT / ".codex/checklists", "checklists", host)
    add_tree(files, ROOT / ".codex/runtime", "runtime", host)
    add_tree(files, ROOT / ".codex/workflows", "workflows", host)
    add_tree(files, ROOT / ".codebuddy/skills", "skills", host)
    for rule in sorted((ROOT / ".codex/rules").glob("*.mdc")):
        suffix = ".mdc" if host == "cursor" else ".md"
        files[f"rules/{rule.stem}{suffix}"] = adapt(rule.read_text(encoding="utf-8"), host).encode("utf-8")
    host_name = "Cursor" if host == "cursor" else "Claude Code"
    readme = f"""# DevFlow Classic for {host_name}

本目录是由 `.codebuddy` 参考工作流和 Classic 公共契约生成的 {host_name} 宿主包。
它属于 Classic edition,不依赖 `skills/devflow` Portable edition。不要直接修改;
修改参考工作流或适配规则后运行 `python3 scripts/build-classic-hosts.py --write`。

## 常用命令

- 启动:`/start-devflow <需求>`
- 恢复:`/resume-devflow <task_slug>`
- 状态:`/status-devflow <task_slug>`
- 终止:`/abort-devflow <task_slug>`

单阶段命令见 `commands/`,状态和产物协议见 `runtime/`。
"""
    files["README.md"] = readme.encode("utf-8")
    marker = {"version": 1, "edition": "classic", "host": host, "generator": "scripts/build-classic-hosts.py"}
    files[".devflow-generated.json"] = (json.dumps(marker, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
    return files


def safe_to_replace(target: Path) -> bool:
    if not target.exists():
        return True
    if (target / ".devflow-generated.json").is_file():
        return True
    entries = {item.name for item in target.iterdir()}
    return entries.issubset({"agents", "skills"})


def write_host(host: str) -> None:
    target = ROOT / f".{host}"
    if not safe_to_replace(target):
        raise SystemExit(f"拒绝覆盖非生成目录: {target}")
    if target.exists():
        shutil.rmtree(target)
    for relative, data in expected(host).items():
        destination = target / relative
        destination.parent.mkdir(parents=True, exist_ok=True)
        destination.write_bytes(data)


def check_host(host: str) -> list:
    target = ROOT / f".{host}"
    wanted = expected(host)
    # __pycache__/*.pyc 是运行 Python 工具(比如 validate.sh 里的 py_compile)时的
    # 正常副作用,不是宿主包内容本身;add_tree() 生成期望清单时已经排除了同样的
    # 东西(见上面 134 行),这里扫描"实际有什么"必须用一样的排除规则,否则任何
    # 在 .claude/.cursor 下跑过一次 Python 语法检查就会把这些缓存文件误判成
    # "unmanaged extra"。
    actual = {
        str(path.relative_to(target)): path.read_bytes()
        for path in target.rglob("*")
        if path.is_file() and not is_runtime_artifact(path.relative_to(target))
    } if target.is_dir() else {}
    errors = []
    for name in sorted(set(wanted) | set(actual)):
        if name not in actual:
            errors.append(f".{host}/{name}: missing")
        elif name not in wanted:
            errors.append(f".{host}/{name}: unmanaged extra")
        elif actual[name] != wanted[name]:
            errors.append(f".{host}/{name}: drift")
    return errors


def main() -> int:
    parser = argparse.ArgumentParser(description="生成或检查 DevFlow Classic Cursor/Claude 宿主包")
    mode = parser.add_mutually_exclusive_group(required=True)
    mode.add_argument("--write", action="store_true")
    mode.add_argument("--check", action="store_true")
    args = parser.parse_args()
    if args.write:
        for host in HOSTS:
            write_host(host)
    errors = [error for host in HOSTS for error in check_host(host)]
    if errors:
        print("ERROR:\n- " + "\n- ".join(errors))
        return 1
    print("OK: Classic Cursor/Claude bundles match their generator")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())