open-reflection-protocol 0.3.0__py3-none-any.whl

orp/reflect.py

@@ -0,0 +1,97 @@
+"""Reflection Analyzer — 诊断、替代策略、Challenger"""
+
+from typing import Any, Optional
+
+from orp.schema import (
+    ExperienceRecord, TimelineEvent, EventKind, ReflectionAnalysis,
+)
+from orp.storage import ORPStorage
+
+
+class ReflectionAnalyzer:
+    """反思分析 — 输出结构化候选，不直接修改 Agent"""
+
+    def analyze(self, record: ExperienceRecord) -> ReflectionAnalysis:
+        """对 ExperienceRecord 执行反思分析"""
+        diagnosis = self._diagnose(record)
+        alternatives = self._suggest_alternatives(record)
+        limitations = self._find_limitations(record)
+        return ReflectionAnalysis(
+            diagnosis=diagnosis,
+            alternatives=alternatives,
+            limitations=limitations,
+        )
+
+    def _diagnose(self, record: ExperienceRecord) -> Optional[str]:
+        """从失败的运行中生成诊断"""
+        outcome_events = [
+            e for e in record.timeline
+            if e.kind == EventKind.OUTCOME
+        ]
+        error_events = [
+            e for e in record.timeline
+            if e.kind == EventKind.OBSERVATION
+            and any(w in e.content.lower() for w in ["error", "fail", "exception", "traceback"])
+        ]
+        if outcome_events:
+            return f"Outcome: {outcome_events[-1].content}"
+        if error_events:
+            return f"Detected error: {error_events[-1].content[:200]}"
+        if record.outcome.status == "failed":
+            return "Task failed — review timeline for root cause"
+        return None
+
+    def _suggest_alternatives(self, record: ExperienceRecord) -> list[str]:
+        """基于失败的运行提出替代策略"""
+        suggestions = []
+        has_test = any(
+            "test" in e.content.lower() or "pytest" in e.content.lower()
+            for e in record.timeline
+        )
+        has_diff = any(
+            "git diff" in e.content.lower() or "diff" in e.content.lower()
+            for e in record.timeline
+        )
+        if record.outcome.status == "failed":
+            if not has_test:
+                suggestions.append("Run tests first to confirm the failure")
+            if not has_diff:
+                suggestions.append("Check git diff to understand what changed")
+        return suggestions
+
+    def _find_limitations(self, record: ExperienceRecord) -> list[str]:
+        """识别这次运行的局限性"""
+        limits = []
+        if not record.task.get("input_ref"):
+            limits.append("No input reference recorded — cannot reproduce exact input")
+        claim_count = sum(1 for e in record.timeline if e.kind == EventKind.CLAIM)
+        evidence_count = sum(len(e.evidence_refs) for e in record.timeline)
+        if claim_count > evidence_count:
+            limits.append(f"More claims ({claim_count}) than evidence refs ({evidence_count})")
+        return limits
+
+
+class Challenger:
+    """Challenger — 质疑未经证明的声明
+    
+    自动查找 ExperienceRecord 中的 claim 及其证据支持情况。
+    """
+
+    def challenge(self, record: ExperienceRecord) -> list[dict[str, Any]]:
+        """找出所有未经充分支持的声明"""
+        challenged: list[dict[str, Any]] = []
+        for evt in record.timeline:
+            if evt.kind == EventKind.CLAIM:
+                if not evt.evidence_refs:
+                    challenged.append({
+                        "event_id": evt.id,
+                        "content": evt.content[:100],
+                        "issue": "No evidence references provided",
+                    })
+                elif len(evt.evidence_refs) < 2:
+                    challenged.append({
+                        "event_id": evt.id,
+                        "content": evt.content[:100],
+                        "issue": "Only 1 evidence ref — may be insufficient",
+                    })
+        return challenged

orp/replay.py

@@ -0,0 +1,108 @@
+"""Counterfactual Replay — 隔离环境回放替代策略"""
+
+import os
+import subprocess
+import tempfile
+from typing import Any, Optional
+
+from orp.schema import CounterfactualReplay
+
+
+class CounterfactualReplayer:
+    """反事实回放 — 在隔离环境中比较原始策略与替代策略"""
+
+    def replay(self, experience_id: str, original: str, alternative: str,
+               workdir: Optional[str] = None) -> CounterfactualReplay:
+        """尝试在隔离环境中回放替代策略
+        
+        返回 CounterfactualReplay，其中 result.status 为:
+        - improved: 替代策略结果更好
+        - equivalent: 结果相当
+        - worse: 替代策略更差
+        - predicted: 无法实际回放，只能输出预测
+        """
+        isolation = self._create_isolation(workdir)
+        if not isolation:
+            # 无法创建隔离环境，只能输出预测
+            return CounterfactualReplay(
+                experience_id=experience_id,
+                original_strategy=original,
+                alternative_strategy=alternative,
+                verification_mode="predicted",
+                result={"status": "predicted", "note": "Could not create isolation environment"},
+            )
+        
+        try:
+            # 运行替代策略
+            start_cmd = alternative.split()
+            if not start_cmd:
+                return CounterfactualReplay(
+                    experience_id=experience_id,
+                    original_strategy=original,
+                    alternative_strategy=alternative,
+                    verification_mode="sandbox_replay",
+                    result={"status": "predicted", "note": "Empty alternative strategy"},
+                )
+            
+            result = subprocess.run(
+                start_cmd,
+                capture_output=True, text=True,
+                cwd=isolation, timeout=120,
+            )
+            success = result.returncode == 0
+            
+            return CounterfactualReplay(
+                experience_id=experience_id,
+                original_strategy=original,
+                alternative_strategy=alternative,
+                verification_mode="sandbox_replay",
+                result={
+                    "status": "improved" if success else "worse",
+                    "exit_code": result.returncode,
+                    "duration": "completed",
+                },
+            )
+        except subprocess.TimeoutExpired:
+            return CounterfactualReplay(
+                experience_id=experience_id,
+                original_strategy=original,
+                alternative_strategy=alternative,
+                verification_mode="sandbox_replay",
+                result={"status": "worse", "error": "timed out"},
+            )
+        except FileNotFoundError:
+            return CounterfactualReplay(
+                experience_id=experience_id,
+                original_strategy=original,
+                alternative_strategy=alternative,
+                verification_mode="predicted",
+                result={"status": "predicted", "error": "command not found"},
+            )
+        finally:
+            self._cleanup_isolation(isolation)
+
+    def _create_isolation(self, workdir: Optional[str] = None) -> Optional[str]:
+        try:
+            tmp = tempfile.mkdtemp(prefix="orp_replay_")
+            if workdir and os.path.isdir(workdir):
+                # 复制工作目录内容（浅层）
+                for item in os.listdir(workdir):
+                    src = os.path.join(workdir, item)
+                    dst = os.path.join(tmp, item)
+                    if os.path.isfile(src):
+                        try:
+                            with open(src, 'rb') as fsrc:
+                                with open(dst, 'wb') as fdst:
+                                    fdst.write(fsrc.read())
+                        except (PermissionError, OSError):
+                            pass
+            return tmp
+        except Exception:
+            return None
+
+    def _cleanup_isolation(self, path: str) -> None:
+        try:
+            import shutil
+            shutil.rmtree(path, ignore_errors=True)
+        except Exception:
+            pass

orp/rollback.py

@@ -0,0 +1,82 @@
+"""Rollback Manager — Lesson 降级、撤回与恢复"""
+
+from typing import Optional
+
+from orp.schema import (
+    Lesson, LessonRollback, LessonStatus,
+)
+from orp.storage import ORPStorage
+
+
+class RollbackManager:
+    """回滚管理 — 坏 Lesson 的审计撤回"""
+
+    def __init__(self, storage: Optional[ORPStorage] = None):
+        self._storage = storage or ORPStorage()
+
+    def rollback(self, lesson_id: str, reason: str,
+                 new_status: LessonStatus = LessonStatus.UNDER_REVIEW,
+                 replacement_id: Optional[str] = None) -> Optional[LessonRollback]:
+        """撤回一条 Lesson
+        
+        默认进入 under_review 而非直接 rejected，保留复审机会。
+        """
+        lesson = self._storage.get_lesson(lesson_id)
+        if not lesson:
+            return None
+        
+        previous = lesson.status
+        rollback = LessonRollback(
+            lesson_id=lesson_id,
+            reason=reason,
+            previous_status=previous,
+            new_status=new_status,
+            replacement_lesson_id=replacement_id,
+            affected_deliveries=[
+                d.delivery_id
+                for d in self._storage.get_deliveries_for_lesson(lesson_id)
+            ],
+        )
+        
+        # 更新 Lesson 状态
+        self._storage.update_lesson_status(lesson_id, new_status)
+        # 保存回滚记录
+        self._storage.save_rollback(rollback)
+        
+        # 如果是 POLICY_FILE 交付的，尝试从 AGENTS.md 移除
+        if previous == LessonStatus.ACTIVE:
+            self._cleanup_policy_file(lesson_id)
+        
+        return rollback
+
+    def restore(self, lesson_id: str) -> bool:
+        """将 under_review 的 Lesson 恢复到 active"""
+        lesson = self._storage.get_lesson(lesson_id)
+        if not lesson or lesson.status != LessonStatus.UNDER_REVIEW:
+            return False
+        self._storage.update_lesson_status(lesson_id, LessonStatus.ACTIVE)
+        return True
+
+    def _cleanup_policy_file(self, lesson_id: str) -> None:
+        """从 AGENTS.md 中移除指定 Lesson 相关的区块"""
+        import os
+        try:
+            agents_path = os.path.join(os.getcwd(), "AGENTS.md")
+            if not os.path.exists(agents_path):
+                return
+            with open(agents_path, "r") as f:
+                content = f.read()
+            start_marker = f"<!-- ORP Lesson: {lesson_id} -->"
+            end_marker = "<!-- END ORP Lesson -->"
+            start = content.find(start_marker)
+            if start == -1:
+                return
+            end = content.find(end_marker, start)
+            if end == -1:
+                return
+            end += len(end_marker)
+            new_content = content[:start] + content[end:]
+            with open(agents_path, "w") as f:
+                f.write(new_content)
+        except (IOError, PermissionError, FileNotFoundError):
+            pass

orp/schema.py

@@ -0,0 +1,303 @@
+# ORP Core Schema v0.3
+# 代码即规范 — 此文件中的所有 Pydantic 模型构成 ORP 协议的官方定义
+# 
+# 设计原则:
+# 1. Evidence first: 结论必须引用证据，无证据的标记为 claim
+# 2. 区分事实与声明: observation/action 是事实，claim/decision 是声明
+# 3. 可执行: 反思优先编译为 Lesson/Eval/Guardrail
+# 4. Outcome based: 经验价值由后续任务结果决定
+# 5. 基于 OpenTelemetry: 不替代 tracing，而是扩展它
+
+from __future__ import annotations
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Optional
+from uuid import UUID, uuid4
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# ─── Helpers ─────────────────────────────────────────────────
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+def _uuid() -> UUID:
+    return uuid4()
+
+
+# ─── Enums ───────────────────────────────────────────────────
+
+class EventKind(str, Enum):
+    """TimelineEvent 类型 — 必须区分可观察事实与 Agent 声明"""
+    OBSERVATION = "observation"   # 工具/环境/外部系统产生的可观察结果
+    ACTION = "action"             # Agent 或用户执行的动作
+    CLAIM = "claim"               # Agent 对原因/状态/结果的声明
+    DECISION = "decision"         # Agent 在多个方案间做出的选择
+    FEEDBACK = "feedback"         # 人工/规则/模型/用户评价
+    OUTCOME = "outcome"           # 测试/验收/生产指标等结果
+
+
+class TrustLevel(str, Enum):
+    """可信等级 — 不使用缺乏校准的单一评分"""
+    ASSERTED = "asserted"                    # 未经外部证据支持的声明
+    OBSERVED = "observed"                    # 被工具/环境/trace 观察到
+    REPRODUCED = "reproduced"                # 独立重跑中复现
+    EXTERNALLY_VERIFIED = "externally_verified"  # 被规则/测试/系统验证
+    HUMAN_CONFIRMED = "human_confirmed"      # 被授权人工确认
+    REGRESSION_GUARDED = "regression_guarded" # 已形成持续运行的回归 Eval
+
+
+class LessonStatus(str, Enum):
+    CANDIDATE = "candidate"        # 由单次经验生成，尚未验证
+    ACTIVE = "active"              # 通过外部验证，可被检索
+    UNDER_REVIEW = "under_review"  # 发现冲突/负面效果，暂停默认交付
+    DEPRECATED = "deprecated"      # 效果不佳/冲突/过期
+    REJECTED = "rejected"          # 被证明错误
+
+
+class DeliveryStrategy(str, Enum):
+    MCP_TOOL = "mcp_tool"           # Agent 主动调用 MCP 工具
+    PROMPT_CONTEXT = "prompt_context"  # 运行时注入系统/任务上下文
+    POLICY_FILE = "policy_file"     # 写入 AGENTS.md 等策略文件
+    RUNTIME_HOOK = "runtime_hook"   # 高风险动作前条件式注入
+
+
+class FeedbackSourceType(str, Enum):
+    HUMAN = "human"
+    DETERMINISTIC = "deterministic"
+    LLM_JUDGE = "llm_judge"
+    USER = "user"
+    PRODUCTION_METRIC = "production_metric"
+
+
+class EvaluationMethod(str, Enum):
+    DESCRIPTIVE = "descriptive"              # 仅记录，不声称因果
+    MATCHED_BASELINE = "matched_baseline"    # 与相似任务基线比较
+    RANDOMIZED = "randomized"                # A/B 实验
+    CAUSAL_MODEL = "causal_model"            # 贝叶斯分层等因果方法
+
+
+class TrainingFormat(str, Enum):
+    SFT_EXAMPLE = "sft_example"
+    PREFERENCE_PAIR = "preference_pair"
+    CRITIQUE_REVISION = "critique_revision"
+    NEGATIVE_EXAMPLE = "negative_example"
+
+
+class TrainingStatus(str, Enum):
+    CANDIDATE = "candidate"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+# ─── Core Objects ────────────────────────────────────────────
+
+class EvidenceRef(BaseModel):
+    """证据引用 — 必须可定位、可校验"""
+    evidence_id: str
+    kind: str = Field(default="tool_output")
+    uri: Optional[str] = None
+    digest: Optional[str] = None
+    created_at: datetime = Field(default_factory=_now)
+    redaction: Optional[dict[str, Any]] = None
+
+
+class Feedback(BaseModel):
+    """外部评价 — 必须记录来源"""
+    target_ref: str
+    source_type: FeedbackSourceType
+    source_id: str
+    verdict: str
+    explanation: Optional[str] = None
+    evidence_refs: list[str] = Field(default_factory=list)
+
+
+class TimelineEvent(BaseModel):
+    """时间线事件 — 推理/操作/观察序列中的一个原子项"""
+    id: str = Field(default_factory=lambda: f"evt_{uuid4().hex[:8]}")
+    kind: EventKind
+    source: str = Field(default="agent")  # agent | tool | human | system
+    content: str
+    evidence_refs: list[str] = Field(default_factory=list)
+    parent_event: Optional[str] = None
+    timestamp: datetime = Field(default_factory=_now)
+
+    @field_validator("content")
+    @classmethod
+    def content_not_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Event content cannot be empty")
+        return v
+
+
+class Outcome(BaseModel):
+    """运行结果 — 基于客观信号"""
+    status: str = Field(default="unknown")  # success | failed | partial | unknown
+    objective_signals: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class ReflectionAnalysis(BaseModel):
+    """反思分析 — Agent 或 Challenger 对运行的结构化复盘"""
+    diagnosis: Optional[str] = None
+    alternatives: list[str] = Field(default_factory=list)
+    limitations: list[str] = Field(default_factory=list)
+
+
+class ExperienceRecord(BaseModel):
+    """经验记录 — 一次 Agent 运行及其复盘结果"""
+    orp_version: str = Field(default="0.3")
+    experience_id: str = Field(default_factory=lambda: f"exp_{uuid4().hex[:12]}")
+    trace_ref: Optional[str] = None
+    agent: dict[str, Any] = Field(default_factory=lambda: {"id": "unknown", "version": "", "model": ""})
+    task: dict[str, Any] = Field(default_factory=lambda: {"goal": "", "domain": "", "input_ref": ""})
+    timeline: list[TimelineEvent] = Field(default_factory=list)
+    outcome: Outcome = Field(default_factory=Outcome)
+    reflection: Optional[ReflectionAnalysis] = None
+    artifacts: dict[str, list[str]] = Field(default_factory=lambda: {"lessons": [], "evals": [], "guardrails": []})
+    feedback: list[Feedback] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=_now)
+
+    @field_validator("timeline")
+    @classmethod
+    def timeline_not_empty(cls, v: list[TimelineEvent]) -> list[TimelineEvent]:
+        if not v:
+            raise ValueError("Timeline must have at least one event")
+        return v
+
+
+class Lesson(BaseModel):
+    """课程/经验 — 可在未来任务中检索的条件化经验"""
+    lesson_id: str = Field(default_factory=lambda: f"lesson_{uuid4().hex[:12]}")
+    trigger: dict[str, Any] = Field(default_factory=lambda: {"domain": "", "conditions": []})
+    recommendation: str
+    provenance: dict[str, Any] = Field(default_factory=lambda: {"experience_ids": [], "evals": []})
+    scope: dict[str, Any] = Field(default_factory=lambda: {
+        "task_domains": [], "frameworks": [], "agent_versions": []
+    })
+    relationships: dict[str, list[str]] = Field(default_factory=lambda: {
+        "conflicts_with": [], "supersedes": [], "superseded_by": []
+    })
+    validation: dict[str, Any] = Field(default_factory=lambda: {"level": "asserted", "evidence_refs": []})
+    metrics: dict[str, Any] = Field(default_factory=lambda: {
+        "retrieved": 0, "delivered": 0, "acknowledged": 0, "applied": 0,
+        "successful_after_apply": 0, "estimated_effect": None
+    })
+    status: LessonStatus = LessonStatus.CANDIDATE
+    expires_at: Optional[datetime] = None
+    created_at: datetime = Field(default_factory=_now)
+    updated_at: datetime = Field(default_factory=_now)
+
+
+class EvalArtifact(BaseModel):
+    """评估工件 — 将失败转换为可重复执行的评估"""
+    eval_id: str = Field(default_factory=lambda: f"eval_{uuid4().hex[:12]}")
+    origin_experience: str
+    runner: str = Field(default="pytest")
+    command: str
+    expected: dict[str, Any] = Field(default_factory=lambda: {"exit_code": 0})
+    generated_by: str = Field(default="agent")
+    review: Optional[dict[str, Any]] = None
+    last_result: Optional[dict[str, Any]] = None
+    created_at: datetime = Field(default_factory=_now)
+
+
+class CounterfactualReplay(BaseModel):
+    """反事实回放 — 记录替代策略是否得到了验证"""
+    replay_id: str = Field(default_factory=lambda: f"replay_{uuid4().hex[:12]}")
+    experience_id: str
+    original_strategy: str
+    alternative_strategy: str
+    verification_mode: str = Field(default="sandbox_replay")  # predicted | sandbox_replay | production
+    result: dict[str, Any] = Field(default_factory=lambda: {
+        "status": "unknown", "objective_delta": {}
+    })
+    created_at: datetime = Field(default_factory=_now)
+
+
+class LessonDelivery(BaseModel):
+    """Lesson 交付 — 记录 Lesson 如何进入 Agent 上下文及是否被采纳"""
+    delivery_id: str = Field(default_factory=lambda: f"delivery_{uuid4().hex[:12]}")
+    lesson_id: str
+    experience_id: str
+    strategy: DeliveryStrategy
+    delivered_at: datetime = Field(default_factory=_now)
+    delivery_context: Optional[str] = None
+    acknowledged: bool = False
+    applied: bool = False
+    application_evidence_refs: list[str] = Field(default_factory=list)
+
+
+class LessonEvaluation(BaseModel):
+    """Lesson 效果评估 — 记录效果、实验设计、负面证据与处置"""
+    evaluation_id: str = Field(default_factory=lambda: f"leval_{uuid4().hex[:12]}")
+    lesson_id: str
+    method: EvaluationMethod
+    population: dict[str, Any] = Field(default_factory=dict)
+    results: dict[str, Any] = Field(default_factory=lambda: {
+        "with_lesson": {"tasks": 0, "successes": 0},
+        "baseline": {"tasks": 0, "successes": 0},
+        "estimated_effect": None,
+        "uncertainty_interval": None,
+    })
+    decision: str = Field(default="keep_active")  # keep_active | restrict_scope | review | deprecate | reject
+    evidence_refs: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=_now)
+
+
+class LessonRollback(BaseModel):
+    """Lesson 回滚 — 坏 Lesson 撤回的审计记录"""
+    rollback_id: str = Field(default_factory=lambda: f"rollback_{uuid4().hex[:12]}")
+    lesson_id: str
+    reason: str
+    previous_status: LessonStatus
+    new_status: LessonStatus
+    affected_deliveries: list[str] = Field(default_factory=list)
+    replacement_lesson_id: Optional[str] = None
+    evidence_refs: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=_now)
+
+
+class TrainingCandidate(BaseModel):
+    """训练候选 — 将经验转化为训练资产的审批通道"""
+    candidate_id: str = Field(default_factory=lambda: f"train_{uuid4().hex[:12]}")
+    source_experience_ids: list[str] = Field(default_factory=list)
+    format: TrainingFormat
+    validation: dict[str, bool] = Field(default_factory=lambda: {
+        "outcome_verified": False,
+        "human_reviewed": False,
+        "privacy_reviewed": False,
+        "license_reviewed": False,
+    })
+    status: TrainingStatus = TrainingStatus.CANDIDATE
+    artifact_ref: Optional[str] = None
+    created_at: datetime = Field(default_factory=_now)
+
+
+# ─── High-level Schema Validation ────────────────────────────
+
+def validate_lesson_scope(lesson: Lesson) -> list[str]:
+    """检查 Lesson 的作用域定义是否完整"""
+    issues = []
+    if not lesson.scope.get("task_domains"):
+        issues.append("Lesson missing task_domains in scope")
+    if not lesson.trigger.get("conditions"):
+        issues.append("Lesson missing trigger conditions")
+    return issues
+
+
+def check_lesson_conflict(a: Lesson, b: Lesson) -> bool:
+    """检查两条 Lesson 是否有冲突
+    
+    先比较 scope，再比较建议内容。
+    不同 scope 的两条建议即使语义相反也不应判定为冲突。
+    """
+    # 如果 scope 完全不重叠，不算冲突
+    a_domains = set(a.scope.get("task_domains", []))
+    b_domains = set(b.scope.get("task_domains", []))
+    if a_domains and b_domains and not a_domains & b_domains:
+        return False
+    a_versions = set(a.scope.get("agent_versions", []))
+    b_versions = set(b.scope.get("agent_versions", []))
+    if a_versions and b_versions and not a_versions & b_versions:
+        return False
+    return True