phase-barrier 0.2.0__py3-none-any.whl

anti_shortcut/__init__.py

@@ -0,0 +1,34 @@
+"""反捷径校验 Skill：强制编码 Agent 遵循标准工程师 SOP（阶段门禁）。
+
+用法::
+
+    from anti_shortcut import AntiShortcutSkill
+
+    skill = AntiShortcutSkill(workspace=".", user_request="实现一个斐波那契函数")
+    tools = skill.install({"write_file": my_write, "execute_command": my_exec})
+    result = tools["advance_stage"](2)  # 完成 spec 后推进
+"""
+from importlib.metadata import PackageNotFoundError, version as _distribution_version
+
+from .config import STAGES, GateConfig, load_config
+from .integration import bootstrap, install_into, load_plugins, register_integration
+from .skill import AntiShortcutSkill
+from .state import StateManager
+
+try:
+    __version__ = _distribution_version("phase-barrier")
+except PackageNotFoundError:  # 直接从源码运行（未安装）时的占位版本
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "AntiShortcutSkill",
+    "StateManager",
+    "GateConfig",
+    "STAGES",
+    "load_config",
+    "bootstrap",
+    "install_into",
+    "load_plugins",
+    "register_integration",
+    "__version__",
+]

anti_shortcut/__main__.py

@@ -0,0 +1,107 @@
+"""命令行入口：外部门禁检查与阶段推进（供编排器 / 人工监督使用）。
+
+用法::
+
+    python -m anti_shortcut inspect [--workspace .] [--json]
+    python -m anti_shortcut advance --to 2 [--workspace .] [--json]
+    python -m anti_shortcut --version
+
+``advance`` 与 Agent 内部的 ``advance_stage`` 走同一套证据校验：
+通过返回退出码 0，被拒绝返回退出码 1 并打印原因。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import STAGES
+from .skill import AntiShortcutSkill
+
+
+def _build_skill(args: argparse.Namespace) -> AntiShortcutSkill:
+    return AntiShortcutSkill(
+        args.workspace,
+        config=args.config,
+        user_request=getattr(args, "user_request", "") or "",
+    )
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    skill = _build_skill(args)
+    tr = skill.state.get_evidence("last_test_run") or {}
+    payload = {
+        "workspace": str(skill.workspace),
+        "current_stage": skill.current_stage,
+        "stage_name": skill.stage_name,
+        "completed_stages": skill.state.completed_stages,
+        "complete": skill.is_complete,
+        "last_test_run": (
+            {k: tr.get(k) for k in ("exit_code", "passed", "summary")} if tr else None
+        ),
+    }
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"workspace       : {payload['workspace']}")
+        print(f"current_stage   : {payload['current_stage']}（{payload['stage_name']}）")
+        print(f"completed_stages: {payload['completed_stages']}")
+        print(f"complete        : {payload['complete']}")
+        if payload["last_test_run"]:
+            ltr = payload["last_test_run"]
+            print(
+                f"last_test_run   : exit_code={ltr['exit_code']} "
+                f"passed={ltr['passed']} summary={ltr['summary']!r}"
+            )
+    return 0
+
+
+def _cmd_advance(args: argparse.Namespace) -> int:
+    skill = _build_skill(args)
+    result = skill.advance_stage(args.to)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["success"]:
+        print(f"OK: {result['message']}")
+    else:
+        print(f"REJECTED: {result['error']}")
+    return 0 if result["success"] else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m anti_shortcut",
+        description="反捷径校验 Skill 命令行：状态检查与阶段推进",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--workspace", type=str, default=".", help="工作区根目录（默认当前目录）")
+    common.add_argument("--config", type=str, default=None, help="YAML 配置文件路径")
+    common.add_argument("--json", action="store_true", help="以 JSON 输出")
+
+    p_inspect = sub.add_parser("inspect", parents=[common], help="查看当前门禁状态")
+    p_inspect.set_defaults(func=_cmd_inspect)
+
+    p_advance = sub.add_parser("advance", parents=[common], help="推进阶段（校验当前阶段证据）")
+    p_advance.add_argument("--to", type=int, required=True, help="目标阶段（必须等于当前阶段 + 1）")
+    p_advance.add_argument("--user-request", type=str, default="", help="用户需求原文（首次初始化时记录）")
+    p_advance.set_defaults(func=_cmd_advance)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):  # pragma: no cover
+        pass
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

anti_shortcut/audit.py

@@ -0,0 +1,109 @@
+"""审计日志：结构化 JSON 日志（优先 structlog，缺省回退 stdlib）。
+
+记录内容：阶段状态变更、工具拦截事件、证据校验结果。
+日志文件位于 ``<workspace>/.agent_gate/audit.log``，每个 Skill 实例使用独立
+logger（按文件句柄），同一进程内的多个工作区互不串扰。
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+try:
+    import structlog
+
+    _HAS_STRUCTLOG = True
+except ImportError:  # pragma: no cover
+    _HAS_STRUCTLOG = False
+
+LOGGER_NAME = "anti_shortcut.audit"
+
+
+class _JsonFallbackFormatter(logging.Formatter):
+    """无 structlog 时的简易 JSON 格式化器。"""
+
+    def format(self, record: logging.LogRecord) -> str:
+        import json
+
+        payload = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
+            "level": record.levelname,
+            "event": record.getMessage(),
+        }
+        for key, value in getattr(record, "payload", {}).items():
+            payload[key] = value
+        return json.dumps(payload, ensure_ascii=False)
+
+
+class _TeeLogger:
+    """同时写入文件 logger 与控制台 logger 的简单组合。"""
+
+    def __init__(self, *loggers) -> None:
+        self._loggers = loggers
+
+    def _emit(self, level: str, event, **kwargs):
+        for lg in self._loggers:
+            getattr(lg, level)(event, **kwargs)
+
+    def info(self, event, **kwargs):
+        self._emit("info", event, **kwargs)
+
+    def warning(self, event, **kwargs):
+        self._emit("warning", event, **kwargs)
+
+    def error(self, event, **kwargs):
+        self._emit("error", event, **kwargs)
+
+    def debug(self, event, **kwargs):
+        self._emit("debug", event, **kwargs)
+
+
+def get_audit_logger(log_file: Path, *, console: bool = False, level: int = logging.INFO):
+    """创建审计 logger（独立文件句柄，进程内可安全创建多个）。
+
+    :param log_file: 审计日志文件路径
+    :param console: 是否同时输出到控制台
+    """
+    log_file = Path(log_file)
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    if _HAS_STRUCTLOG:
+        json_processors = [
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.JSONRenderer(ensure_ascii=False),
+        ]
+        file_logger = structlog.wrap_logger(
+            structlog.PrintLogger(file=open(log_file, "a", encoding="utf-8")),
+            processors=json_processors,
+            wrapper_class=structlog.make_filtering_bound_logger(level),
+            cache_logger_on_first_use=True,
+        )
+        if not console:
+            return file_logger
+        console_logger = structlog.wrap_logger(
+            structlog.PrintLogger(file=sys.stdout),
+            processors=[
+                structlog.processors.TimeStamper(fmt="iso"),
+                structlog.processors.add_log_level,
+                structlog.processors.ConsoleRenderer(colors=False),
+            ],
+            wrapper_class=structlog.make_filtering_bound_logger(level),
+            cache_logger_on_first_use=True,
+        )
+        return _TeeLogger(file_logger, console_logger)
+
+    # 回退：标准库 logging + JSON Formatter
+    std_logger = logging.getLogger(f"{LOGGER_NAME}:{log_file}")
+    std_logger.setLevel(level)
+    if not std_logger.handlers:
+        handler = logging.FileHandler(log_file, encoding="utf-8")
+        handler.setFormatter(_JsonFallbackFormatter())
+        std_logger.addHandler(handler)
+        if console:
+            std_logger.addHandler(logging.StreamHandler(sys.stdout))
+    std_logger.propagate = False
+    return std_logger

anti_shortcut/config.py

@@ -0,0 +1,106 @@
+"""阶段门禁配置：Pydantic 模型 + YAML 加载。
+
+配置允许项目自定义阶段划分、证据要求、文件模式、测试命令等，
+从而在“严格门禁”与“灵活性”之间取得平衡（见方案第 5 章/第 10 章）。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+# 阶段名称（与方案第 5 章保持一致）
+STAGES: dict[int, str] = {
+    0: "需求接收",
+    1: "Spec 设计",
+    2: "测试用例编写",
+    3: "实现代码",
+    4: "运行测试",
+    5: "修复与回归",
+    6: "交付",
+}
+
+DEFAULT_SPEC_SECTIONS = ["## 需求分析", "## 设计方案", "## 接口定义"]
+
+# 默认测试命令正则（匹配命令前缀），可按语言扩展
+DEFAULT_TEST_COMMANDS: list[str] = [
+    r"^\s*python3?\s+(-m\s+)?pytest\b",
+    r"^\s*pytest\b",
+    r"^\s*python3?\s+-m\s+unittest\b",
+    r"^\s*npm\s+test\b",
+    r"^\s*npx\s+(jest|vitest|mocha|playwright)\b",
+    r"^\s*(go|rust)\s+test\b",
+    r"^\s*cargo\s+test\b",
+    r"^\s*gradle\s+test\b",
+    r"^\s*mvn\s+test\b",
+    r"^\s*tox\b",
+    r"^\s*unittest\b",
+]
+
+# 默认测试文件匹配模式（fnmatch / Path.match 语义）
+DEFAULT_TEST_FILE_PATTERNS: list[str] = [
+    "test_*.py",
+    "*_test.py",
+    "tests/**/test_*.py",
+    "tests/**/*_test.py",
+]
+
+DEFAULT_SOURCE_FILE_PATTERNS: list[str] = ["*.py"]
+
+
+class GateConfig(BaseModel):
+    """反捷径校验 Skill 的可配置项。所有字段都有合理默认值，YAML 可部分覆盖。"""
+
+    workspace: Path = Path(".")
+    gate_dir_name: str = ".agent_gate"
+    state_file_name: str = "state.json"
+    audit_log_name: str = "audit.log"
+    # ---- 阶段 1：Spec ----
+    spec_file: str = "spec.md"
+    spec_sections: list[str] = Field(default_factory=lambda: list(DEFAULT_SPEC_SECTIONS))
+    spec_min_chars: int = 120
+    # ---- 阶段 2：测试用例 ----
+    test_file_patterns: list[str] = Field(default_factory=lambda: list(DEFAULT_TEST_FILE_PATTERNS))
+    min_test_functions: int = 2
+    require_assert_per_test: bool = True
+    # ---- 阶段 3：实现 ----
+    source_file_patterns: list[str] = Field(default_factory=lambda: list(DEFAULT_SOURCE_FILE_PATTERNS))
+    require_implementation: bool = True
+    # ---- 阶段 4/5：测试运行 ----
+    test_commands: list[str] = Field(default_factory=lambda: list(DEFAULT_TEST_COMMANDS))
+    max_test_output_tail: int = 4000
+    # ---- 安全 ----
+    protect_gate_dir: bool = True
+    # 允许 Agent 直接写入“其他”类型文件（如 README.md、docs），默认不限
+    allow_other_files_any_stage: bool = True
+
+    @model_validator(mode="after")
+    def _expand_workspace(self) -> "GateConfig":
+        self.workspace = Path(self.workspace).expanduser().resolve()
+        return self
+
+
+def load_config(path: str | Path | dict[str, Any] | None = None) -> GateConfig:
+    """从 YAML 文件或字典加载配置，缺失字段使用默认值。
+
+    - ``None``：纯默认配置
+    - ``dict``：字段覆盖
+    - ``Path``/``str``：读取 YAML 文件后覆盖
+    """
+    if path is None:
+        data: dict[str, Any] = {}
+    elif isinstance(path, (str, Path)):
+        p = Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"配置文件不存在: {p}")
+        with p.open("r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+        if not isinstance(data, dict):
+            raise ValueError(f"配置文件 {p} 顶层必须是映射（dict）")
+    elif isinstance(path, dict):
+        data = path
+    else:
+        raise TypeError(f"不支持的配置类型: {type(path)!r}")
+    return GateConfig(**data)

anti_shortcut/integration.py

@@ -0,0 +1,108 @@
+"""集成层：插件加载与通用 Agent 工具注册表接入。
+
+对接方式（对应方案“技术栈选型—集成与部署”）：
+
+1. **一键接入**：``bootstrap(agent_tools, workspace, ...)`` 创建 Skill、包装工具、
+   注入 ``advance_stage`` 并加载集成插件，适合 Alpha-SWE 等以“工具表 dict”暴露工具的 Agent。
+2. **进程内插件**：``register_integration(name, installer)`` 注册，``installer(agent, skill)``
+   负责把包装后的工具装回 Agent；宿主进程启动时调用 ``load_plugins(agent, skill)``。
+3. **入口点插件**：发布为独立包的插件可声明 ``anti_shortcut.integrations`` 入口点，
+   ``load_plugins`` 自动发现并执行其 ``install``。
+"""
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+from typing import Any, Callable
+
+from .skill import AntiShortcutSkill
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "bootstrap",
+    "install_into",
+    "load_plugins",
+    "register_integration",
+]
+
+ENTRY_POINT_GROUP = "anti_shortcut.integrations"
+
+# 进程内集成注册表：name -> installer(agent, skill)
+_registry: dict[str, Callable[[Any, AntiShortcutSkill], None]] = {}
+
+
+def register_integration(
+    name: str,
+    installer: Callable[[Any, AntiShortcutSkill], None],
+) -> None:
+    """进程内注册一个集成插件。
+
+    :param name: 插件名（重复注册会覆盖）
+    :param installer: ``installer(agent, skill)``，负责把 ``skill`` 包装后的工具装回 ``agent``
+    """
+    if not callable(installer):
+        raise TypeError("installer 必须可调用")
+    _registry[name] = installer
+
+
+def load_plugins(
+    agent: Any = None,
+    skill: AntiShortcutSkill | None = None,
+) -> list[str]:
+    """加载并执行所有集成插件（进程内注册表 + 已安装包的入口点）。
+
+    :param agent: 宿主 Agent 对象（原样传给 installer）
+    :param skill: 已创建的 Skill 实例
+    :return: 已加载的插件名列表
+    """
+    loaded: list[str] = []
+    for name, installer in _registry.items():
+        installer(agent, skill)
+        loaded.append(name)
+    try:
+        entry_points = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+    except (TypeError, importlib.metadata.PackageNotFoundError):  # pragma: no cover
+        entry_points = ()
+    for ep in entry_points:
+        plugin = ep.load()
+        installer = plugin if callable(plugin) else getattr(plugin, "install", None)
+        if installer is None:
+            raise TypeError(
+                f"入口点插件 {ep.name!r} 必须整体可调用，或导出 install(agent, skill)"
+            )
+        installer(agent, skill)
+        loaded.append(ep.name)
+    return loaded
+
+
+def install_into(
+    agent_tools: dict[str, Callable],
+    skill: AntiShortcutSkill,
+) -> dict[str, Callable]:
+    """把 Skill 包装后的工具写回 Agent 工具表（等价于 ``skill.install``）。"""
+    return skill.install(agent_tools)
+
+
+def bootstrap(
+    agent_tools: dict[str, Callable],
+    workspace: str | Path,
+    config: Any = None,
+    user_request: str = "",
+    *,
+    agent: Any = None,
+    load_integrations: bool = True,
+) -> AntiShortcutSkill:
+    """一步完成：创建 Skill -> 包装 Agent 工具 -> 加载集成插件。
+
+    :param agent_tools: Agent 的工具表，如 ``{"write_file": ..., "execute_command": ...}``
+    :param workspace: 工作区根目录
+    :param config: Skill 配置（YAML 路径 / dict / GateConfig / None）
+    :param user_request: 用户需求原文（阶段 0 证据）
+    :param agent: 宿主 Agent 对象（透传给集成插件）
+    :param load_integrations: 是否加载已注册的集成插件
+    """
+    skill = AntiShortcutSkill(workspace, config=config, user_request=user_request)
+    install_into(agent_tools, skill)
+    if load_integrations:
+        load_plugins(agent=agent, skill=skill)
+    return skill

anti_shortcut/interceptors.py

@@ -0,0 +1,144 @@
+"""工具拦截辅助：命令分类、门禁目录保护、shell 写路径提取、测试输出摘要。
+
+- 识别测试运行命令（可配置正则）
+- 识别试图访问/篡改门禁目录的命令
+- 从 shell 命令中提取“被写入的路径”（重定向、mv/cp 目标、sed -i、rm/touch 等），
+  从而让 ``execute_command`` 的写操作受到与 ``write_file`` 相同的阶段限制
+"""
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+
+from .config import GateConfig
+
+
+# ---------- 测试命令识别 ----------
+
+def is_test_command(command: str, config: GateConfig) -> bool:
+    """判断命令是否为测试运行命令（按 config.test_commands 正则匹配前缀）。"""
+    cmd = (command or "").strip()
+    if not cmd:
+        return False
+    for pattern in config.test_commands:
+        try:
+            if re.search(pattern, cmd, flags=re.IGNORECASE):
+                return True
+        except re.error:
+            continue
+    return False
+
+
+# ---------- 门禁目录保护 ----------
+
+def touches_gate_dir(command: str, gate_dir: Path) -> bool:
+    """判断命令是否可能访问或篡改门禁目录（.agent_gate）。"""
+    gate_dir = Path(gate_dir)
+    name = gate_dir.name
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        tokens = command.split()
+    for raw in tokens:
+        tok = raw.strip('"\'')
+        if not tok:
+            continue
+        if tok == name or tok == str(gate_dir):
+            return True
+        if tok.startswith(name + "/") or tok.startswith(name + "\\"):
+            return True
+        if tok.startswith(str(gate_dir) + "/") or tok.startswith(str(gate_dir) + "\\"):
+            return True
+    return False
+
+
+# ---------- shell 写路径提取 ----------
+
+def _looks_like_sed_expr(token: str) -> bool:
+    """粗略判断 token 是否为 sed 表达式（如 s/a/b/、/pattern/、1,5d）。"""
+    if "/" in token:
+        return True
+    return bool(re.match(r"^[0-9$!~,]*[sSdDcCpPaAiI]", token))
+
+
+def extract_written_paths(command: str) -> list[str]:
+    """从 shell 命令中提取可能被写入的路径（启发式，用于阶段门禁检查）。"""
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        tokens = command.split()
+    paths: list[str] = []
+    n = len(tokens)
+    i = 0
+    while i < n:
+        tok = tokens[i]
+        if tok in (">", ">>", "2>", "2>>", "1>", "1>>"):
+            if i + 1 < n:
+                nxt = tokens[i + 1]
+                if not nxt.startswith("&"):
+                    paths.append(nxt)
+        elif tok in ("mv", "cp", "install", "rename"):
+            dest = [t for t in tokens[i + 1:] if not t.startswith("-")]
+            if dest:
+                paths.append(dest[-1])
+        elif tok == "sed":
+            j = i + 1
+            if j < n and tokens[j].startswith("-i"):
+                j += 1  # 跳过 -i 或 -i.bak
+                while j < n and tokens[j].startswith("-"):
+                    opt = tokens[j]
+                    j += 1
+                    if opt in ("-e", "--expression", "-f", "--file") and j < n:
+                        j += 1
+                if j < n and _looks_like_sed_expr(tokens[j]):
+                    j += 1  # 跳过 sed 表达式
+                for t in tokens[j:]:
+                    if not t.startswith("-"):
+                        paths.append(t)
+        elif tok in ("rm", "touch", "tee", "truncate", "unlink", "shred"):
+            for t in tokens[i + 1:]:
+                if t == "--" or t.startswith("-"):
+                    continue
+                paths.append(t)
+        i += 1
+    return paths
+
+
+# ---------- 测试输出摘要 ----------
+
+def summarize_test_output(
+    output: str,
+    exit_code: int | None = None,
+    *,
+    max_tail: int = 4000,
+) -> dict[str, Any]:
+    """把测试命令输出规整为结构化记录：退出码、是否通过、摘要、输出尾部。"""
+    text = output or ""
+    if exit_code is None:
+        passed = bool(re.search(r"\b\d+ passed\b|tests? (passed|ok)\b|All tests? passed", text, re.IGNORECASE))
+        if re.search(r"\b\d+ failed\b|FAILED|ERRORS?\b", text, re.IGNORECASE):
+            passed = False
+    else:
+        passed = exit_code == 0
+
+    lines = [ln.rstrip() for ln in text.splitlines() if ln.strip()]
+    tail = lines[-20:]
+    tail_text = "\n".join(tail)[-max_tail:]
+
+    # 尝试提取 pytest / unittest 风格摘要行
+    summary = ""
+    for ln in reversed(tail):
+        if re.search(r"\b\d+ (passed|failed|error|skipped|warning)\b|tests? (passed|ok|failed)\b|OK|FAILED", ln, re.IGNORECASE):
+            summary = ln.strip()
+            break
+    if not summary and tail:
+        summary = tail[-1][:300]
+
+    return {
+        "exit_code": exit_code,
+        "passed": passed,
+        "summary": summary,
+        "output_tail": tail_text,
+    }