super-engineer-workflow 0.1.0

package/scripts/se-cli.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILL_DIR = REPO_ROOT / "super-engineer-workflow"
+PACKAGE_JSON = REPO_ROOT / "package.json"
+
+
+def main() -> None:
+    if len(sys.argv) == 1:
+        run_setup([])
+        return
+    if sys.argv[1] in ("init", "setup"):
+        run_setup(sys.argv[2:])
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="se",
+        description="Super Engineer workflow CLI.",
+    )
+    parser.add_argument("--version", action="store_true", help="显示版本号。")
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("init", help="交互式安装 skill 并初始化工作区。")
+    subparsers.add_parser("setup", help="init 的别名。")
+
+    install_parser = subparsers.add_parser("install", help="安装 skill 到 Codex / Claude。")
+    install_parser.add_argument("--target", choices=["codex", "claude", "both"], default="both")
+    install_parser.add_argument("--force", action="store_true", help="安装前删除旧 skill 目录。")
+
+    sync_parser = subparsers.add_parser("sync", help="重新同步 skill 到 Codex / Claude。")
+    sync_parser.add_argument("--target", choices=["codex", "claude", "both"], default="both")
+
+    doctor_parser = subparsers.add_parser("doctor", help="检查本机环境和工作区配置。")
+    doctor_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
+    doctor_parser.add_argument("--json", action="store_true", help="输出 JSON。")
+
+    migrate_parser = subparsers.add_parser("migrate", help="补齐旧工作区缺失的 workspace.yml 配置项。")
+    migrate_parser.add_argument("--workspace", default=".", help="工作区目录，默认当前目录。")
+    migrate_parser.add_argument("--dry-run", action="store_true", help="只展示计划，不写入文件。")
+
+    subparsers.add_parser("version", help="显示版本号。")
+
+    args = parser.parse_args()
+    if args.version or args.command == "version":
+        print(package_version())
+        return
+    if args.command == "install":
+        install_targets(args.target, force=args.force)
+        return
+    if args.command == "sync":
+        install_targets(args.target, force=True)
+        return
+    if args.command == "doctor":
+        exit_code = doctor(Path(args.workspace).expanduser().resolve(), output_json=args.json)
+        raise SystemExit(exit_code)
+    if args.command == "migrate":
+        exit_code = migrate(Path(args.workspace).expanduser().resolve(), dry_run=args.dry_run)
+        raise SystemExit(exit_code)
+
+    parser.print_help()
+
+
+def package_version() -> str:
+    if not PACKAGE_JSON.exists():
+        return "0.0.0"
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data.get("version", "0.0.0"))
+
+
+def run_setup(args: list[str]) -> None:
+    script = REPO_ROOT / "scripts" / "se-setup.py"
+    result = subprocess.run([sys.executable, str(script), *args], check=False)
+    raise SystemExit(result.returncode)
+
+
+def install_targets(target: str, force: bool) -> None:
+    targets = []
+    if target in ("codex", "both"):
+        targets.append(skill_target("codex"))
+    if target in ("claude", "both"):
+        targets.append(skill_target("claude"))
+    for item in targets:
+        install_skill(item, force=force)
+
+
+def skill_target(kind: str) -> Path:
+    if kind == "codex":
+        base = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    elif kind == "claude":
+        base = Path(os.environ.get("CLAUDE_HOME", "~/.claude")).expanduser()
+    else:
+        raise ValueError(kind)
+    return base / "skills" / "super-engineer-workflow"
+
+
+def install_skill(target: Path, force: bool) -> None:
+    if not SKILL_DIR.exists():
+        raise SystemExit(f"skill 目录不存在：{SKILL_DIR}")
+    if target.exists() and force:
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(
+        SKILL_DIR,
+        target,
+        dirs_exist_ok=True,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+    print(f"✓ 已同步 skill: {target}")
+
+
+def doctor(workspace: Path, output_json: bool) -> int:
+    checks: list[dict[str, str]] = []
+    add_check(checks, "python", "ok", sys.version.split()[0])
+    add_check(checks, "skill_source", "ok" if SKILL_DIR.exists() else "fail", str(SKILL_DIR))
+    add_check(checks, "codex_skill", "ok" if skill_target("codex").exists() else "warn", str(skill_target("codex")))
+    add_check(checks, "claude_skill", "ok" if skill_target("claude").exists() else "warn", str(skill_target("claude")))
+    add_check(checks, "openspec_cli", "ok" if shutil.which("openspec") else "warn", shutil.which("openspec") or "未安装")
+    add_check(checks, "workspace", "ok" if workspace.exists() else "fail", str(workspace))
+
+    workspace_yml = workspace / "workspace.yml"
+    add_check(checks, "workspace_yml", "ok" if workspace_yml.exists() else "fail", str(workspace_yml))
+    if workspace_yml.exists():
+        try:
+            config = read_workspace_yaml(workspace_yml)
+        except ValueError as exc:
+            add_check(checks, "workspace_yml.parse", "fail", str(exc))
+        else:
+            add_check(checks, "workspace_yml.parse", "ok", "解析成功")
+            validate_workspace(checks, workspace, config)
+
+    if output_json:
+        print(json.dumps({"checks": checks}, ensure_ascii=False, indent=2))
+    else:
+        print("Super Engineer doctor")
+        for check in checks:
+            mark = {"ok": "✓", "warn": "!", "fail": "✗"}[check["status"]]
+            print(f"{mark} {check['name']}: {check['message']}")
+
+    return 1 if any(item["status"] == "fail" for item in checks) else 0
+
+
+def add_check(checks: list[dict[str, str]], name: str, status: str, message: str) -> None:
+    checks.append({"name": name, "status": status, "message": message})
+
+
+def read_workspace_yaml(path: Path) -> dict[str, object]:
+    text = path.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore
+    except Exception:
+        yaml = None
+    if yaml is not None:
+        loaded = yaml.safe_load(text) or {}
+        if not isinstance(loaded, dict):
+            raise ValueError("workspace.yml 顶层必须是对象")
+        return loaded
+
+    common_path = SKILL_DIR / "scripts" / "common.py"
+    spec = importlib.util.spec_from_file_location("se_common_for_cli", common_path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"无法加载 YAML 解析器：{common_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    loaded = module.parse_simple_yaml(text)
+    if not isinstance(loaded, dict):
+        raise ValueError("workspace.yml 顶层必须是对象")
+    return loaded
+
+
+def config_get(config: dict[str, object], key: str, default: object = None) -> object:
+    current: object = config
+    for part in key.split("."):
+        if not isinstance(current, dict) or part not in current:
+            return default
+        current = current[part]
+    return current
+
+
+def config_str(config: dict[str, object], key: str, default: str = "") -> str:
+    value = config_get(config, key, default)
+    if value is None:
+        return default
+    return str(value)
+
+
+def validate_workspace(checks: list[dict[str, str]], workspace: Path, config: dict[str, object]) -> None:
+    for key in ("workflow_source", "mode", "code_path", "output_dir"):
+        value = config_str(config, key)
+        add_check(checks, f"config.{key}", "ok" if value else "fail", value or "缺失")
+
+    version = config_get(config, "version")
+    add_check(checks, "config.version", "ok" if version == 1 else "fail", str(version or "缺失"))
+
+    references = config_get(config, "reference_files")
+    add_check(checks, "config.reference_files", "ok" if isinstance(references, list) else "fail", "list" if isinstance(references, list) else "缺失或非数组")
+
+    source = config_str(config, "workflow_source")
+    if source not in ("openspec", "todo"):
+        add_check(checks, "config.workflow_source.value", "fail", source or "缺失")
+
+    mode = config_str(config, "mode")
+    if mode not in ("auto", "manual"):
+        add_check(checks, "config.mode.value", "fail", mode or "缺失")
+
+    code_path = config_str(config, "code_path")
+    if code_path:
+        resolved = resolve_workspace_path(workspace, code_path)
+        add_check(checks, "code_path.exists", "ok" if resolved.exists() else "warn", str(resolved))
+
+    demand_file = config_str(config, "demand_file")
+    if source == "openspec":
+        add_check(checks, "config.demand_file", "ok" if demand_file else "fail", demand_file or "缺失")
+        if demand_file:
+            resolved = resolve_workspace_path(workspace, expand_vars(demand_file, config))
+            add_check(checks, "demand_file.exists", "ok" if resolved.exists() else "warn", str(resolved))
+        changes_dir = config_str(config, "openspec.changes_dir", "openspec/changes")
+        resolved_changes = resolve_workspace_path(workspace, changes_dir)
+        add_check(checks, "openspec.changes_dir", "ok" if resolved_changes.exists() else "warn", str(resolved_changes))
+
+    todo_file = config_str(config, "todo_file")
+    add_check(checks, "config.todo_file", "ok" if todo_file else "fail", todo_file or "缺失")
+    if todo_file:
+        resolved = resolve_workspace_path(workspace, expand_vars(todo_file, config))
+        status = "ok" if resolved.exists() else ("warn" if source == "openspec" else "fail")
+        add_check(checks, "todo_file.exists", status, str(resolved))
+
+
+def expand_vars(value: str, config: dict[str, object]) -> str:
+    demand_name = config_str(config, "vars.demand_name")
+    return value.replace("${demand_name}", demand_name)
+
+
+def resolve_workspace_path(workspace: Path, value: str) -> Path:
+    path = Path(value).expanduser()
+    if path.is_absolute():
+        return path
+    return (workspace / path).resolve()
+
+
+def migrate(workspace: Path, dry_run: bool) -> int:
+    workspace_yml = workspace / "workspace.yml"
+    if not workspace_yml.exists():
+        print(f"✗ workspace.yml 不存在：{workspace_yml}")
+        return 1
+
+    try:
+        config = read_workspace_yaml(workspace_yml)
+    except ValueError as exc:
+        print(f"✗ workspace.yml 无法解析：{exc}")
+        return 1
+
+    additions = default_missing_lines(config)
+    if not additions:
+        print("✓ workspace.yml 已是当前版本，无需迁移。")
+        return 0
+
+    print("将补齐以下配置：")
+    for line in additions:
+        print(f"  {line}")
+
+    if dry_run:
+        return 0
+
+    with workspace_yml.open("a", encoding="utf-8") as handle:
+        handle.write("\n# Added by super-engineer migrate\n")
+        for line in additions:
+            handle.write(f"{line}\n")
+    print(f"✓ 已迁移：{workspace_yml}")
+    return 0
+
+
+def default_missing_lines(config: dict[str, object]) -> list[str]:
+    additions: list[str] = []
+    if config_get(config, "version") is None:
+        additions.append("version: 1")
+    if not config_str(config, "mode"):
+        additions.append("mode: manual")
+    if not config_str(config, "workflow_source"):
+        additions.append("workflow_source: todo")
+    if config_get(config, "reference_files") is None:
+        additions.extend(["reference_files:", "  - docs/项目介绍.md"])
+    if not config_str(config, "code_path"):
+        additions.append("code_path: ../your-project")
+    if not config_str(config, "output_dir"):
+        additions.append("output_dir: output")
+    return additions
+
+
+if __name__ == "__main__":
+    main()

package/scripts/se-setup.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILL_DIR = REPO_ROOT / "super-engineer-workflow"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="安装 super-engineer skill，并初始化业务工作区。"
+    )
+    parser.add_argument("--workspace", help="业务工作区目录，默认使用当前目录。")
+    parser.add_argument("--code-path", help="代码目录，写入 workspace.yml。默认：../code")
+    parser.add_argument("--demand-name", help="需求目录名。默认：1-your-demand")
+    parser.add_argument("--source", choices=["todo", "openspec"], help="输入模式。默认：openspec")
+    parser.add_argument("--mode", choices=["manual", "auto"], help="执行模式。默认：auto")
+    parser.add_argument(
+        "--install",
+        choices=["none", "codex", "claude", "both"],
+        help="安装 skill 到本机目录。默认：none",
+    )
+    parser.add_argument("--force-skill", action="store_true", help="安装 skill 时先删除已有目录。")
+    parser.add_argument("--openspec-init", action="store_true", help="如果安装了 openspec CLI，尝试执行 openspec init。")
+    parser.add_argument("--yes", action="store_true", help="非交互模式，全部使用参数或默认值。")
+    args = parser.parse_args()
+
+    if should_prompt(args):
+        args = prompt_args(args)
+
+    install = args.install or "none"
+    source = args.source or "openspec"
+    mode = args.mode or "auto"
+    demand_name = args.demand_name or "1-your-demand"
+    code_path = args.code_path or "../code"
+    workspace = Path(args.workspace).expanduser().resolve() if args.workspace else Path.cwd().resolve()
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    if install in ("codex", "both"):
+        install_skill(skill_target("codex"), args.force_skill)
+    if install in ("claude", "both"):
+        install_skill(skill_target("claude"), args.force_skill)
+
+    ensure_global_skill_config()
+    init_workspace(
+        workspace=workspace,
+        code_path=code_path,
+        demand_name=demand_name,
+        source=source,
+        mode=mode,
+        openspec_init=args.openspec_init,
+    )
+    print_summary(workspace, demand_name, source, mode)
+
+
+def should_prompt(args: argparse.Namespace) -> bool:
+    if args.yes:
+        return False
+    provided = any(
+        [
+            args.workspace,
+            args.code_path,
+            args.demand_name,
+            args.source,
+            args.mode,
+            args.install,
+            args.force_skill,
+            args.openspec_init,
+        ]
+    )
+    return not provided and sys.stdin.isatty()
+
+
+def prompt_args(args: argparse.Namespace) -> argparse.Namespace:
+    print("Super Engineer 初始化向导")
+    print("该向导会逐步完成：环境检查、skill 安装、工作区结构初始化、workspace.yml 生成。")
+    print("按 Enter 使用默认值。")
+    print("")
+    print("Step 1/7 环境检查")
+    print(f"  Python: {sys.executable}")
+    print(f"  Skill:  {SKILL_DIR}")
+    print(f"  OpenSpec CLI: {'已安装' if shutil.which('openspec') else '未检测到'}")
+    print("")
+    print("Step 2/7 选择本机 skill 安装目标")
+    args.install = prompt_choice(
+        "安装 skill 到哪里",
+        choices=["both", "codex", "claude", "none"],
+        default="both",
+        labels={
+            "both": "Codex 和 Claude",
+            "codex": "仅 Codex",
+            "claude": "仅 Claude",
+            "none": "暂不安装",
+        },
+    )
+    args.force_skill = prompt_bool("如果 skill 已存在，是否覆盖安装", default=False)
+    print("")
+    print("Step 3/7 选择业务工作区")
+    args.workspace = prompt_text("业务工作区目录", default=str(Path.cwd()))
+    print("")
+    print("Step 4/7 配置代码目录和当前需求")
+    args.code_path = prompt_text("代码目录 code_path", default="../code")
+    args.demand_name = prompt_text("当前需求目录名", default="1-your-demand")
+    print("")
+    print("Step 5/7 选择工作流模式")
+    args.source = prompt_choice(
+        "输入模式",
+        choices=["openspec", "todo"],
+        default="openspec",
+        labels={
+            "openspec": "OpenSpec + todo 桥接",
+            "todo": "直接读取 todo.md",
+        },
+    )
+    args.mode = prompt_choice(
+        "执行模式",
+        choices=["auto", "manual"],
+        default="auto",
+        labels={
+            "auto": "自动推进到验证",
+            "manual": "关键阶段等待人工确认",
+        },
+    )
+    print("")
+    print("Step 6/7 OpenSpec 初始化")
+    args.openspec_init = prompt_bool("是否尝试执行 openspec init", default=False)
+    print("")
+    print("Step 7/7 执行前确认")
+    print(f"  install:       {args.install}")
+    print(f"  force_skill:   {args.force_skill}")
+    print(f"  workspace:     {Path(args.workspace).expanduser()}")
+    print(f"  code_path:     {args.code_path}")
+    print(f"  demand_name:   {args.demand_name}")
+    print(f"  source:        {args.source}")
+    print(f"  mode:          {args.mode}")
+    print(f"  openspec_init: {args.openspec_init}")
+    if not prompt_bool("确认开始初始化", default=True):
+        raise SystemExit("已取消初始化。")
+    print("")
+    return args
+
+
+def prompt_text(title: str, default: str) -> str:
+    value = input(f"{title} [{default}]: ").strip()
+    return value or default
+
+
+def prompt_bool(title: str, default: bool) -> bool:
+    suffix = "Y/n" if default else "y/N"
+    value = input(f"{title} [{suffix}]: ").strip().lower()
+    if not value:
+        return default
+    return value in ("y", "yes", "true", "1", "是")
+
+
+def prompt_choice(title: str, choices: list[str], default: str, labels: dict[str, str]) -> str:
+    print(title)
+    for index, choice in enumerate(choices, start=1):
+        marker = " 默认" if choice == default else ""
+        print(f"  {index}. {labels.get(choice, choice)} ({choice}){marker}")
+    while True:
+        value = input(f"请选择 [默认 {default}]: ").strip()
+        if not value:
+            return default
+        if value in choices:
+            return value
+        if value.isdigit() and 1 <= int(value) <= len(choices):
+            return choices[int(value) - 1]
+        print("输入无效，请重新选择。")
+
+
+def skill_target(kind: str) -> Path:
+    if kind == "codex":
+        base = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    elif kind == "claude":
+        base = Path(os.environ.get("CLAUDE_HOME", "~/.claude")).expanduser()
+    else:
+        raise ValueError(kind)
+    return base / "skills" / "super-engineer-workflow"
+
+
+def install_skill(target: Path, force: bool) -> None:
+    if not SKILL_DIR.exists():
+        raise SystemExit(f"skill 目录不存在：{SKILL_DIR}")
+    if target.exists() and force:
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(SKILL_DIR, target, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    print(f"installed_skill={target}")
+
+
+def ensure_global_skill_config() -> None:
+    config_dir = Path("~/.super-engineer").expanduser()
+    config_file = config_dir / "skill-config.yml"
+    if config_file.exists():
+        print(f"skill_config=exists:{config_file}")
+        return
+    config_dir.mkdir(parents=True, exist_ok=True)
+    source = SKILL_DIR / "assets" / "config.example.yml"
+    if source.exists():
+        shutil.copyfile(source, config_file)
+    else:
+        config_file.write_text("version: 1\nnotification: {}\n", encoding="utf-8")
+    print(f"skill_config=created:{config_file}")
+
+
+def init_workspace(
+    workspace: Path,
+    code_path: str,
+    demand_name: str,
+    source: str,
+    mode: str,
+    openspec_init: bool,
+) -> None:
+    (workspace / "docs").mkdir(parents=True, exist_ok=True)
+    (workspace / "openspec" / "changes").mkdir(parents=True, exist_ok=True)
+    (workspace / "openspec" / "specs").mkdir(parents=True, exist_ok=True)
+    demand_dir = workspace / "superengineer" / demand_name
+    demand_dir.mkdir(parents=True, exist_ok=True)
+
+    demand_file = demand_dir / "需求.md"
+    if not demand_file.exists():
+        demand_file.write_text(
+            "# 需求说明\n\n"
+            "## 背景\n\n"
+            "请在这里描述业务背景。\n\n"
+            "## 目标\n\n"
+            "请在这里描述本次需求目标。\n\n"
+            "## 验收标准\n\n"
+            "- [ ] 补充验收标准。\n",
+            encoding="utf-8",
+        )
+
+    workspace_yml = workspace / "workspace.yml"
+    if not workspace_yml.exists():
+        workspace_yml.write_text(
+            build_workspace_yml(
+                code_path=code_path,
+                demand_name=demand_name,
+                source=source,
+                mode=mode,
+            ),
+            encoding="utf-8",
+        )
+        print(f"workspace_yml=created:{workspace_yml}")
+    else:
+        print(f"workspace_yml=exists:{workspace_yml}")
+
+    if openspec_init:
+        try_init_openspec(workspace)
+
+
+def build_workspace_yml(code_path: str, demand_name: str, source: str, mode: str) -> str:
+    if source == "todo":
+        return (
+            "version: 1\n"
+            f"mode: {mode}\n"
+            "workflow_source: todo\n"
+            "vars:\n"
+            f"  demand_name: {demand_name}\n"
+            "todo_file: superengineer/${demand_name}/todo.md\n"
+            "reference_files:\n"
+            "  - docs/需求分析与实现指南.md\n"
+            f"code_path: {code_path}\n"
+            "output_dir: superengineer/${demand_name}/output\n"
+        )
+    return (
+        "version: 1\n"
+        f"mode: {mode}\n"
+        "workflow_source: openspec\n"
+        "vars:\n"
+        f"  demand_name: {demand_name}\n"
+        "demand_file: superengineer/${demand_name}/需求.md\n"
+        "todo_file: superengineer/${demand_name}/todo.md\n"
+        "reference_files:\n"
+        "  - docs/需求分析与实现指南.md\n"
+        f"code_path: {code_path}\n"
+        "output_dir: superengineer/${demand_name}/output\n"
+        "openspec:\n"
+        "  changes_dir: openspec/changes\n"
+    )
+
+
+def try_init_openspec(workspace: Path) -> None:
+    if not shutil.which("openspec"):
+        print("openspec_init=skipped:openspec CLI not found")
+        return
+    config_file = workspace / "openspec" / "config.yaml"
+    if config_file.exists():
+        print("openspec_init=skipped:already initialized")
+        return
+    result = subprocess.run(
+        ["openspec", "init", ".", "--tools", "codex,claude"],
+        cwd=workspace,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    print(result.stdout.strip())
+    print(f"openspec_init={'ok' if result.returncode == 0 else 'failed'}")
+
+
+def print_summary(workspace: Path, demand_name: str, source: str, mode: str) -> None:
+    print("")
+    print("初始化完成。")
+    print(f"workspace={workspace}")
+    print(f"demand_dir={workspace / 'superengineer' / demand_name}")
+    print(f"workflow_source={source}")
+    print(f"mode={mode}")
+    print("")
+    if source == "openspec":
+        print("下一步提示词：")
+        print(f"/se:propose <change-name>")
+        print("请根据当前 workspace 的 demand_file 生成或完善 OpenSpec change。")
+        print("不要改代码。过程中请使用中文。")
+    else:
+        print("下一步提示词：")
+        print("/se:apply")
+        print("请根据当前 workspace 的 todo_file 推进交付工作流。过程中请使用中文。")
+
+
+if __name__ == "__main__":
+    main()