agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/harness/spec.py

@@ -0,0 +1,332 @@
+"""HarnessSpec v1 — Revision 编译后的引擎无关运行规范（plan §6.1）。
+
+冻结契约：本模块（及其依赖）不得 import LangGraph 或任何 Runner 专有类型，
+由 ``tests/architecture/test_harness_contract.py`` 守卫。所有资源引用必须
+固定版本；不含明文 Secret（只允许 Secret Reference）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic.alias_generators import to_camel
+
+from ksadk.harness.resource_ref import validate_resource_ref
+
+SCHEMA_VERSION = "harness.ksadk.io/v1"
+HARNESS_VERSION = "0.1.0"
+
+
+class _SpecModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class ModelFailureCategory(str, Enum):
+    """平台稳定分类，避免按厂商异常类直接决定重试与降级。"""
+
+    RATE_LIMIT = "rate_limit"
+    TIMEOUT = "timeout"
+    UNAVAILABLE = "unavailable"
+    TRANSPORT = "transport"
+
+
+class ModelProviderPolicy(_SpecModel):
+    """模型提供方失败策略。
+
+    只允许对瞬时故障配置重试/降级。鉴权、权限、请求参数、上下文超限和
+    未知错误不会被此合同静默包装为可重试故障。
+    """
+
+    max_attempts_per_model: int = Field(default=10, ge=1, le=10)
+    total_attempt_budget: int = Field(default=20, ge=1, le=40)
+    initial_backoff_ms: int = Field(default=1_000, ge=0, le=30_000)
+    max_backoff_ms: int = Field(default=60_000, ge=0, le=60_000)
+    retryable_categories: tuple[ModelFailureCategory, ...] = (
+        ModelFailureCategory.RATE_LIMIT,
+        ModelFailureCategory.TIMEOUT,
+        ModelFailureCategory.UNAVAILABLE,
+        ModelFailureCategory.TRANSPORT,
+    )
+    failover_categories: tuple[ModelFailureCategory, ...] = (
+        ModelFailureCategory.RATE_LIMIT,
+        ModelFailureCategory.TIMEOUT,
+        ModelFailureCategory.UNAVAILABLE,
+        ModelFailureCategory.TRANSPORT,
+    )
+
+    @model_validator(mode="after")
+    def validate_backoff(self) -> "ModelProviderPolicy":
+        if self.max_backoff_ms < self.initial_backoff_ms:
+            raise ValueError("max_backoff_ms 不得小于 initial_backoff_ms")
+        return self
+
+
+class ModelBinding(_SpecModel):
+    """模型绑定：profile_ref 固定版本，可选降级链。"""
+
+    profile_ref: str = Field(min_length=1, max_length=512)
+    fallback_profile_refs: tuple[str, ...] = Field(default=(), max_length=4)
+    provider_policy: ModelProviderPolicy = Field(default_factory=ModelProviderPolicy)
+    temperature: float | None = Field(default=None, ge=0.0, le=2.0)
+    max_output_tokens: int | None = Field(default=None, ge=1, le=1_000_000)
+
+    @model_validator(mode="after")
+    def validate_refs(self) -> "ModelBinding":
+        validate_resource_ref(self.profile_ref)
+        for ref in self.fallback_profile_refs:
+            validate_resource_ref(ref)
+        return self
+
+
+class PromptSpec(_SpecModel):
+    """Stable Prompt 规范：正文内联或引用，二者互斥。"""
+
+    instructions: str | None = Field(default=None, max_length=131_072)
+    instructions_ref: str | None = Field(default=None, max_length=512)
+
+    @model_validator(mode="after")
+    def validate_exactly_one(self) -> "PromptSpec":
+        if bool(self.instructions) == bool(self.instructions_ref):
+            raise ValueError("prompt 必须二选一：instructions（内联）或 instructions_ref（引用）")
+        if self.instructions_ref:
+            validate_resource_ref(self.instructions_ref)
+        return self
+
+
+class BudgetSource(str, Enum):
+    MODEL_PROFILE = "model_profile"
+    PROVIDER_MODELS = "provider_models"
+    STATIC_METADATA = "static_metadata"
+    SAFE_DEFAULT = "safe_default"
+
+
+class ContextPolicy(_SpecModel):
+    """上下文预算与压缩策略（plan §8.3/§8.4）。"""
+
+    budget_source: BudgetSource = BudgetSource.MODEL_PROFILE
+    budget_source_fallback: tuple[BudgetSource, ...] = Field(
+        default=(BudgetSource.PROVIDER_MODELS, BudgetSource.SAFE_DEFAULT), max_length=3
+    )
+    proactive_compaction_threshold: float = Field(default=0.72, ge=0.1, le=0.95)
+    emergency_retry_limit: int = Field(default=1, ge=1, le=3)
+    reserved_output_ratio: float = Field(default=0.15, ge=0.05, le=0.5)
+    safety_buffer_ratio: float = Field(default=0.05, ge=0.01, le=0.2)
+
+
+class MemoryPolicy(_SpecModel):
+    """Memory 作用域与写入策略（plan §9）。"""
+
+    enabled: bool = False
+    scopes: tuple[str, ...] = Field(default=("session",), max_length=5)
+    core_block_refs: tuple[str, ...] = Field(default=(), max_length=16)
+    max_resident_blocks: int = Field(default=8, ge=1, le=64)
+    write_requires_source: bool = True
+
+    @model_validator(mode="after")
+    def validate_refs(self) -> "MemoryPolicy":
+        for ref in self.core_block_refs:
+            validate_resource_ref(ref)
+        allowed = {"run", "session", "agent", "user", "org"}
+        unknown = set(self.scopes) - allowed
+        if unknown:
+            raise ValueError(f"未知 memory scope: {sorted(unknown)}；允许 {sorted(allowed)}")
+        return self
+
+
+class CapabilityBinding(_SpecModel):
+    """单个能力绑定（MCP/Skill），固定版本 + 加载策略。"""
+
+    capability_ref: str = Field(min_length=1, max_length=512)
+    required: bool = Field(default=True)
+    load_policy: str = Field(default="always", pattern=r"^(always|on_demand|explicit)$")
+
+    @model_validator(mode="after")
+    def validate_ref(self) -> "CapabilityBinding":
+        validate_resource_ref(self.capability_ref)
+        return self
+
+
+class CapabilityBindings(_SpecModel):
+    mcp_bindings: tuple[CapabilityBinding, ...] = Field(default=(), max_length=32)
+    skill_bindings: tuple[CapabilityBinding, ...] = Field(default=(), max_length=64)
+
+
+class SubAgentBinding(_SpecModel):
+    """子 Agent 声明（plan §14：多 Agent 是可选能力，经 Revision 编译）。"""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    name: str = Field(min_length=1, max_length=64, pattern=r"^[a-z0-9][a-z0-9_-]*$")
+    instructions: str = Field(min_length=1, max_length=32_768)
+    description: str = Field(default="", max_length=1024)
+    #: 允许使用的工具名（空 = 纯文本推理）。
+    tools: tuple[str, ...] = Field(default=(), max_length=64)
+    #: 单次委派的墙钟超时；防止子 Agent 阻塞父 Run。
+    timeout_seconds: float = Field(default=120.0, gt=0, le=3600)
+    #: 子 Agent 自己可执行的最大模型轮数，独立于父 Agent。
+    max_turns: int = Field(default=4, ge=1, le=32)
+    #: 子 Agent 模型调用的独立总 Token 上限；None 表示仅受父级/Provider 预算。
+    max_total_tokens: int | None = Field(default=None, ge=1, le=10_000_000)
+    #: 子 Agent 可创建的独立 Artifact 数量上限。
+    max_artifacts: int | None = Field(default=None, ge=0, le=10_000)
+    #: 子 Agent 最多完成的 Tool Call 数量。
+    max_tool_calls: int | None = Field(default=None, ge=0, le=100_000)
+    #: 子 Agent 最终输出的 JSON Schema；未声明时保留文本输出。
+    output_schema: dict[str, Any] | None = None
+    #: 同一委派批次内必须先完成的子 Agent 名称。
+    depends_on: tuple[str, ...] = Field(default=(), max_length=32)
+    #: ``propagate`` 将失败作为 Tool error 回流父 Agent；``return_error``
+    #: 返回结构化失败文本，适合可选审查/检索子任务。
+    failure_policy: str = Field(
+        default="propagate", pattern=r"^(propagate|return_error|retry)$"
+    )
+    max_retries: int = Field(default=0, ge=0, le=3)
+    #: Skill 属于只读知识能力，默认继承；MCP 默认不继承，避免子 Agent
+    #: 在未显式授权时扩大外部系统访问面。
+    inherit_skills: bool = True
+    inherit_mcp: bool = False
+
+    @field_validator("output_schema")
+    @classmethod
+    def validate_output_schema(cls, value: dict[str, Any] | None) -> dict[str, Any] | None:
+        if value is None:
+            return None
+        from jsonschema.validators import validator_for
+
+        try:
+            validator_for(value).check_schema(value)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f"output_schema 不是有效 JSON Schema: {exc}") from exc
+        return value
+
+
+class ExecutionStrategyKind(str, Enum):
+    SINGLE_AGENT = "single-agent"
+    PLAN_EXECUTE = "plan-execute"
+    PLAN_EXECUTE_REVIEW = "plan-execute-review"
+    CUSTOM_IMPORTED = "custom-imported"
+
+
+class ExecutionStrategySpec(_SpecModel):
+    kind: ExecutionStrategyKind = ExecutionStrategyKind.SINGLE_AGENT
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class ApprovalPolicy(_SpecModel):
+    """高风险 Tool 审批策略（plan §11）。"""
+
+    mode: str = Field(default="policy", pattern=r"^(never|policy|always)$")
+    timeout_seconds: int | None = Field(default=None, ge=1, le=2_592_000)
+    approver_roles: tuple[str, ...] = Field(default=(), max_length=16)
+
+
+class SandboxPolicy(_SpecModel):
+    read_only: bool = True
+    backend: str = Field(default="local-readonly", max_length=64)
+    network_egress: str = Field(default="deny", pattern=r"^(deny|allow|policy)$")
+
+
+class ObservabilityPolicy(_SpecModel):
+    emit_usage: bool = True
+    emit_context_trace: bool = True
+    redact_secrets: bool = True
+    record_reasoning_text: bool = False
+
+
+class HarnessSpec(_SpecModel):
+    """Revision 编译后的不可变运行规范。"""
+
+    schema_version: str = Field(default=SCHEMA_VERSION, frozen=True)
+    harness_version: str = Field(default=HARNESS_VERSION, frozen=True)
+    agent_revision_ref: str = Field(min_length=1, max_length=512)
+
+    model: ModelBinding
+    prompt: PromptSpec
+    context_policy: ContextPolicy = Field(default_factory=ContextPolicy)
+    memory_policy: MemoryPolicy = Field(default_factory=MemoryPolicy)
+    capabilities: CapabilityBindings = Field(default_factory=CapabilityBindings)
+    sub_agents: tuple[SubAgentBinding, ...] = Field(default=(), max_length=32)
+    execution_strategy: ExecutionStrategySpec = Field(default_factory=ExecutionStrategySpec)
+    approval_policy: ApprovalPolicy = Field(default_factory=ApprovalPolicy)
+    sandbox_policy: SandboxPolicy = Field(default_factory=SandboxPolicy)
+    observability_policy: ObservabilityPolicy = Field(default_factory=ObservabilityPolicy)
+
+    @model_validator(mode="after")
+    def validate_revision_ref(self) -> "HarnessSpec":
+        validate_resource_ref(self.agent_revision_ref)
+        names = {sub.name for sub in self.sub_agents}
+        for sub in self.sub_agents:
+            unknown = set(sub.depends_on) - names
+            if unknown:
+                raise ValueError(
+                    f"sub-agent {sub.name!r} has unknown dependencies: {sorted(unknown)}"
+                )
+            if sub.name in sub.depends_on:
+                raise ValueError(f"sub-agent dependency cycle: {sub.name} -> {sub.name}")
+        dependencies = {sub.name: set(sub.depends_on) for sub in self.sub_agents}
+        remaining = set(dependencies)
+        resolved: set[str] = set()
+        while remaining:
+            ready = {name for name in remaining if dependencies[name] <= resolved}
+            if not ready:
+                raise ValueError(
+                    f"sub-agent dependency cycle: {sorted(remaining)}"
+                )
+            resolved.update(ready)
+            remaining -= ready
+        return self
+
+    def content_hash(self) -> str:
+        """规范内容 Hash——同一 Spec + 版本可解释行为基线（plan §6.1）。"""
+        payload = json.dumps(
+            self.model_dump(mode="json", exclude_none=True),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+        return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def build_manifest(spec: HarnessSpec, *, engine: str = "managed-langgraph") -> dict[str, Any]:
+    """Build Manifest 最小集（plan §12.3）：不记录 Secret，只记录引用与版本。"""
+    return {
+        "revisionRef": spec.agent_revision_ref,
+        "harnessVersion": spec.harness_version,
+        "schemaVersion": spec.schema_version,
+        "engine": engine,
+        "modelProfileRef": spec.model.profile_ref,
+        "fallbackModelProfileRefs": list(spec.model.fallback_profile_refs),
+        "modelProviderPolicy": spec.model.provider_policy.model_dump(mode="json"),
+        "mcpRefs": [b.capability_ref for b in spec.capabilities.mcp_bindings],
+        "skillRefs": [b.capability_ref for b in spec.capabilities.skill_bindings],
+        "memoryPolicyRef": None,
+        "policyRefs": [],
+        "contentHash": spec.content_hash(),
+    }
+
+
+__all__ = [
+    "HARNESS_VERSION",
+    "SCHEMA_VERSION",
+    "ApprovalPolicy",
+    "BudgetSource",
+    "CapabilityBinding",
+    "CapabilityBindings",
+    "ContextPolicy",
+    "ExecutionStrategyKind",
+    "ExecutionStrategySpec",
+    "HarnessSpec",
+    "MemoryPolicy",
+    "ModelBinding",
+    "ModelFailureCategory",
+    "ModelProviderPolicy",
+    "ObservabilityPolicy",
+    "PromptSpec",
+    "SandboxPolicy",
+    "SubAgentBinding",
+    "build_manifest",
+]

ksadk/harness/state.py

@@ -0,0 +1,153 @@
+"""HarnessState v1 — Checkpoint 之外的影子运行状态（plan §6.2/§6.2.1）。
+
+引擎图 State 只存最小路由信息；本状态由 Harness Runtime 持有，持久化到
+Session/Transcript 存储。恢复时先恢复图 Checkpoint（路由位置），再从
+Transcript 重建本状态；不一致以 Transcript 为准并记录 context.recovered。
+大 Tool Result / Artifact 只存引用，正文不进 State。
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    AWAITING_APPROVAL = "awaiting_approval"
+    PAUSED = "paused"
+    COMPACTING = "compacting"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+
+class MessageRole(str, Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class Message(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    role: MessageRole
+    content: str = Field(default="", max_length=1_048_576)
+    tool_call_id: str | None = Field(default=None, max_length=128)
+    name: str | None = Field(default=None, max_length=256)
+
+
+class ToolCall(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    call_id: str = Field(min_length=1, max_length=128)
+    name: str = Field(min_length=1, max_length=256)
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    #: 大结果外置为引用（plan §6.2：Checkpoint 不无限膨胀）。
+    result_ref: str | None = Field(default=None, max_length=512)
+    result_preview: str = Field(default="", max_length=2048)
+    status: str = Field(default="pending", pattern=r"^(pending|succeeded|failed|denied)$")
+
+
+class ApprovalRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    approval_id: str = Field(min_length=1, max_length=128)
+    call_id: str = Field(min_length=1, max_length=128)
+    risk_level: str = Field(default="medium", max_length=32)
+    reason: str = Field(default="", max_length=4096)
+    requested_at: float = Field(default_factory=time.time)
+
+
+class MemoryRef(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    memory_ref: str = Field(min_length=1, max_length=512)
+    scope: str = Field(default="session", max_length=32)
+
+
+class ArtifactRef(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    artifact_ref: str = Field(min_length=1, max_length=512)
+    digest: str | None = Field(default=None, max_length=128)
+    mime_type: str | None = Field(default=None, max_length=128)
+
+
+class RetryState(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    consecutive_failures: int = Field(default=0, ge=0, le=32)
+    emergency_compaction_retries: int = Field(default=0, ge=0, le=3)
+    last_error_kind: str | None = Field(default=None, max_length=64)
+
+
+class WorkingContext(BaseModel):
+    """当前任务工作上下文（plan §8.5）：Session/Task 生命周期，非长期 Memory。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    #: 结构化 Patch 版本（长任务方案 §6.1）：每次成功 Patch +1，乐观并发控制。
+    version: int = Field(default=0, ge=0)
+    goal: str = Field(default="", max_length=8192)
+    confirmed_constraints: tuple[str, ...] = Field(default=(), max_length=64)
+    open_questions: tuple[str, ...] = Field(default=(), max_length=64)
+    plan: str = Field(default="", max_length=16384)
+    verified_facts: tuple[str, ...] = Field(default=(), max_length=256)
+    artifact_refs: tuple[ArtifactRef, ...] = Field(default=(), max_length=64)
+    recent_tool_failures: tuple[str, ...] = Field(default=(), max_length=32)
+
+
+class CapabilitySnapshot(BaseModel):
+    """本 Run 实际可见的能力清单（含降级标记）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    entries: tuple[str, ...] = Field(default=(), max_length=256)
+    degraded: tuple[str, ...] = Field(default=(), max_length=256)
+
+
+class HarnessState(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tenant_id: str = Field(min_length=1, max_length=128)
+    user_id: str = Field(min_length=1, max_length=128)
+    agent_id: str = Field(min_length=1, max_length=160)
+    session_id: str = Field(min_length=1, max_length=160)
+    run_id: str = Field(default_factory=lambda: f"hr-{uuid.uuid4().hex[:16]}")
+
+    messages: list[Message] = Field(default_factory=list)
+    working_context: WorkingContext = Field(default_factory=WorkingContext)
+    memory_refs: list[MemoryRef] = Field(default_factory=list)
+    capability_snapshot: CapabilitySnapshot = Field(default_factory=CapabilitySnapshot)
+    pending_tool_calls: list[ToolCall] = Field(default_factory=list)
+    pending_approval: ApprovalRequest | None = None
+    artifacts: list[ArtifactRef] = Field(default_factory=list)
+    retry_state: RetryState = Field(default_factory=RetryState)
+    status: RunStatus = Field(default=RunStatus.PENDING)
+    turn_count: int = Field(default=0, ge=0, le=1024)
+
+    def checkpoint_key(self) -> str:
+        """与图 Checkpoint 关联的键（plan §6.2.1 一致性规则）。"""
+        return f"{self.tenant_id}/{self.agent_id}/{self.session_id}/{self.run_id}"
+
+
+__all__ = [
+    "ApprovalRequest",
+    "ArtifactRef",
+    "CapabilitySnapshot",
+    "HarnessState",
+    "MemoryRef",
+    "Message",
+    "MessageRole",
+    "RetryState",
+    "RunStatus",
+    "ToolCall",
+    "WorkingContext",
+]

ksadk/harness/strategies.py

@@ -0,0 +1,149 @@
+"""Harness Execution Strategy Registry（plan §14）——多 Agent 是可选能力。
+
+一期策略：
+- ``single-agent``：默认（对应 engine.base.single_agent_plan）；
+- ``plan-execute``：规划与执行分离；
+- ``plan-execute-review``：增加独立审查；
+- ``custom-imported``：兼容导入路径占位。
+
+模板可推荐策略，但不把技术拓扑写成模板核心描述（§14.2）——策略由创建者
+或平台策略选择。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ksadk.harness.engine.base import ExecutionPlan, single_agent_plan
+from ksadk.harness.spec import HarnessSpec
+
+
+class StrategyRegistryError(ValueError):
+    """未知/冲突策略注册。"""
+
+
+@dataclass(frozen=True)
+class StrategyDescriptor:
+    strategy_kind: str
+    description: str
+    #: 单 Agent 模板无关性守卫：默认策略不得携带多 Agent 专属字符串。
+    is_default: bool = False
+
+
+def plan_execute_plan() -> ExecutionPlan:
+    """plan-execute：规划与执行分离（§14.1）。"""
+    return ExecutionPlan(
+        strategy_kind="plan-execute",
+        nodes=("prepare_context", "plan", "execute", "reason", "tool_calls", "final"),
+        edges=(
+            ("prepare_context", "plan"),
+            ("plan", "execute"),
+            ("execute", "reason"),
+            ("reason", "tool_calls"),
+            ("tool_calls", "reason"),
+            ("reason", "final"),
+        ),
+    )
+
+
+def plan_execute_review_plan() -> ExecutionPlan:
+    """plan-execute-review：增加独立审查节点（§14.1）。"""
+    return ExecutionPlan(
+        strategy_kind="plan-execute-review",
+        nodes=(
+            "prepare_context",
+            "plan",
+            "execute",
+            "reason",
+            "tool_calls",
+            "review",
+            "final",
+        ),
+        edges=(
+            ("prepare_context", "plan"),
+            ("plan", "execute"),
+            ("execute", "reason"),
+            ("reason", "tool_calls"),
+            ("tool_calls", "reason"),
+            ("reason", "review"),
+            ("review", "final"),
+        ),
+    )
+
+
+#: 多 Agent 专属节点名——single-agent 拓扑不得包含（§17 多 Agent 拓扑 验收）。
+_MULTI_AGENT_NODES = frozenset({"plan", "execute", "review", "manager", "reviewer"})
+
+
+class ExecutionStrategyRegistry:
+    """策略注册表：compile(spec) → ExecutionPlan（纯数据，引擎无关）。"""
+
+    def __init__(self) -> None:
+        self._strategies: dict[str, StrategyDescriptor] = {
+            "single-agent": StrategyDescriptor(
+                strategy_kind="single-agent",
+                description="默认单 Agent 循环（reason 自环 + final）",
+                is_default=True,
+            ),
+            "plan-execute": StrategyDescriptor(
+                strategy_kind="plan-execute",
+                description="规划与执行分离",
+            ),
+            "plan-execute-review": StrategyDescriptor(
+                strategy_kind="plan-execute-review",
+                description="规划-执行-独立审查",
+            ),
+            "custom-imported": StrategyDescriptor(
+                strategy_kind="custom-imported",
+                description="导入已有项目的兼容路径",
+            ),
+        }
+        self._compilers = {
+            "single-agent": single_agent_plan,
+            "plan-execute": plan_execute_plan,
+            "plan-execute-review": plan_execute_review_plan,
+        }
+
+    def register(self, descriptor: StrategyDescriptor, compiler=None) -> None:
+        if descriptor.strategy_kind in self._strategies:
+            raise StrategyRegistryError(f"strategy 重复注册: {descriptor.strategy_kind}")
+        self._strategies[descriptor.strategy_kind] = descriptor
+        if compiler is not None:
+            self._compilers[descriptor.strategy_kind] = compiler
+
+    def list_strategies(self) -> list[StrategyDescriptor]:
+        return list(self._strategies.values())
+
+    def default(self) -> str:
+        for descriptor in self._strategies.values():
+            if descriptor.is_default:
+                return descriptor.strategy_kind
+        return "single-agent"
+
+    def compile(self, spec: HarnessSpec, *, strategy: str | None = None) -> ExecutionPlan:
+        """按策略编译拓扑；未指定时使用注册表默认。"""
+        kind = strategy or self.default()
+        if kind == "custom-imported":
+            raise StrategyRegistryError("custom-imported 策略无通用拓扑：由导入的 Graph 自行提供")
+        compiler = self._compilers.get(kind)
+        if compiler is None:
+            raise StrategyRegistryError(f"unknown strategy: {kind}")
+        return compiler()
+
+    # ------------------------------------------------------------- 守卫
+
+    @staticmethod
+    def assert_single_agent_purity(plan: ExecutionPlan) -> None:
+        """验收守卫：single-agent 拓扑不包含多 Agent 专属节点。"""
+        polluted = _MULTI_AGENT_NODES & set(plan.nodes)
+        if polluted:
+            raise StrategyRegistryError(f"single-agent 拓扑混入多 Agent 节点: {sorted(polluted)}")
+
+
+__all__ = [
+    "ExecutionStrategyRegistry",
+    "StrategyDescriptor",
+    "StrategyRegistryError",
+    "plan_execute_plan",
+    "plan_execute_review_plan",
+]