Skill: lingxinsuixing/principles-agent (version 0.2.0)

# principles-agent - 基于第一性原理的迭代式任务拆解框架 **作者：** 🖤 小黑 & 小龙 ## 描述 基于 [miltonian/principles](https://github.com/miltonian/principles) 的设计思想，在 OpenClaw 中实现的**第一性原理思维 + 迭代式开发**框架。 **架构职责分离：** | 模块 | 职责 | |------|------| | **principles-agent** | 需求澄清 → 第一性原理推导 → 原子任务拆解 → 迭代精炼 → 依赖排序 → 结果整合 → 分层验证 | | **OpenClaw 主 Agent** | 实际执行 LLM 调用 → 执行子任务 → 处理外部操作 → 权限管控 | skill 不直接调用 API、不访问网络、不读取环境变量，所有 IO 由主 Agent 完成。 ## 核心能力 1. **第一性原理需求分析** —— 剥离经验假设，回归最基础的事实和公理 2. **原子级任务拆解** —— 将复杂目标拆解为不可再分、可验证的原子子任务 3. **迭代式精炼** —— 自动检查并优化不满足条件的真理/子任务 4. **依赖感知调度** —— 拓扑排序处理依赖，识别可并行批次 5. **分层质量验证** —— 每层都验证，不通过反馈优化 6. **全局整合验收** —— 最终交付前整体验证，保证结果满足目标 ## 触发条件 当用户需要： - 从零设计一个复杂系统/项目 - 对复杂问题进行深度分析 - 构建多步骤多 Agent 协作系统 - 需要按照第一性原理思维解决问题时触发 ## 用法 **直接在 OpenClaw 会话中使用：** ``` principles "你的目标或问题描述" ``` **可选输出到文件：** ``` principles "你的目标" --output report.md ``` **配置最大迭代次数：** ``` principles "你的目标" --max-iterations 5 ``` ## 权限边界 principles-agent 遵循最小权限原则： - ✅ **LLM 调用**：由 OpenClaw 主 Agent 注入，skill 只接收结果 - ✅ **文件读取**：仅读取 skill 自身目录内的源代码 - ✅ **文件写入**：仅在用户通过 `--output` 指定时写入报告 - ❌ **网络访问**：skill 不发起任何网络请求 - ❌ **环境变量**：skill 不读取任何环境变量 - ❌ **系统访问**：不执行外部命令，不修改系统配置 ## 工作流程 ``` 1. 接收需求 → 澄清目标，提取约束和成功标准 2. 第一性原理解构 → 推导基础事实/公理 3. 原子任务拆解 → 拆解为最小可验证子任务 4. 迭代精炼 → 检查最小性/可行性/对齐性，不满足则优化 5. 依赖排序 → 拓扑排序确定执行顺序，检测循环依赖 6. 分批执行 → 主 Agent 执行子任务，skill 验证每个结果 7. 全局整合 → 合并所有子任务结果生成完整输出 8. 最终验收 → 验证满足原始目标，交付成果 ``` ## 架构 ``` principles-agent/ ├── SKILL.md # 本文件 ├── package.json # Skill 元数据和权限声明 ├── cli.py # OpenClaw CLI 入口 ├── openclaw_entry.py # OpenClaw 技能入口点 └── src/ ├── __init__.py ├── types_def.py # 数据类型定义 ├── orchestrator.py # 总控编排 ├── truth_deriver.py # 基础事实推导 ├── task_breaker.py # 原子任务拆解 ├── refiner.py # 迭代精炼决策 ├── dependency_sorter.py # 依赖拓扑排序 ├── validator.py # 分层质量验证 ├── executor.py # 执行调度（调用主 Agent 执行） └── integrator.py # 结果整合 ``` ## 参考资料 - 原始项目：https://github.com/miltonian/principles

path: cli.py
content: #!/usr/bin/env python3
"""
principles-agent CLI - OpenClaw 集成入口
基于第一性原理分析复杂问题
用法: principles "你的目标描述"
"""

import argparse
import sys
import os

# 添加 src 到路径
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

from orchestrator import PrinciplesOrchestrator


def main():
    parser = argparse.ArgumentParser(
        description="principles-agent - 基于第一性原理的迭代式 Agent (OpenClaw)"
    )
    parser.add_argument(
        "prompt",
        help="目标描述，例如: '设计一个基于第一性原理的多 Agent 系统'"
    )
    parser.add_argument(
        "--max-iterations",
        type=int,
        default=5,
        help="最大迭代精炼次数"
    )
    parser.add_argument(
        "--output",
        "-o",
        help="输出报告文件路径"
    )
    args = parser.parse_args()

    # principles-agent 完全依赖 OpenClaw 提供 LLM 调用
    # 在 OpenClaw 运行环境中，llm_call 由主 Agent 注入
    if 'llm_call' not in globals():
        raise RuntimeError(
            "principles-agent 必须在 OpenClaw 会话中运行。"
            "LLM 调用由 OpenClaw 主 Agent 提供，skill 不直接调用外部 API。"
        )

    llm_call = globals()['llm_call']

    orchestrator = PrinciplesOrchestrator(
        llm_call=llm_call,
        max_iterations=args.max_iterations
    )

    print(f"🚀 Starting principles analysis for: {args.prompt[:50]}{'...' if len(args.prompt) > 50 else ''}")
    print("=" * 60)

    result = orchestrator.run(args.prompt)
    report = orchestrator.generate_report(result)

    print("\n" + "=" * 60)
    print(f"✅ Complete! Iterations: {result.iteration_count}")
    print(f"Global validation: {'PASSED' if result.global_validation_passed else 'FAILED'}")
    print(f"Tasks: {len(result.tasks)}, Truths: {len(result.truths)}")

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(report)
        print(f"\nReport saved to: {args.output}")
    else:
        print("\n" + "=" * 60)
        print(report)

    return 0


if __name__ == "__main__":
    sys.exit(main())


path: openclaw_entry.py
content: """
OpenClaw 入口
===== 架构说明 =====
* skill 职责：流程控制、需求分析、任务拆解、迭代精炼、依赖排序、结果整合、质量验证
* LLM 调用：全部由 OpenClaw 主 Agent 执行，skill 只接收结果不直接调用 API
* 权限边界：skill 不读取环境变量，不访问网络，仅在内存中处理逻辑
"""
import sys
import os
import json

# 添加 src 到路径
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

from orchestrator import PrinciplesOrchestrator


def run_in_openclaw(prompt: str, llm_call) -> dict:
    """
    在 OpenClaw 会话中运行 principles-agent
    :param prompt: 用户目标
    :param llm_call: OpenClaw 主 Agent 提供的 LLM 调用函数 (prompt: str) -> str
    :return: 结果字典
    """
    orch = PrinciplesOrchestrator(
        llm_call=llm_call,
        max_iterations=5
    )
    result = orch.run(prompt)
    report = orch.generate_report(result)
    
    return {
        "result": result,
        "report": report,
        "success": result.global_validation_passed
    }


path: package.json
content: {
  "name": "principles-agent",
  "version": "0.2.0",
  "description": "First-principles iterative task decomposition framework for OpenClaw",
  "author": "Xiaohei & Xiaolong",
  "license": "MIT",
  "keywords": ["agent", "first-principles", "task-decomposition", "iterative", "openclaw-skill"],
  "dependencies": {},
  "peerDependencies": {
    "python": ">=3.8"
  },
  "permissions": {
    "description": "principles-agent 是纯流程编排框架，权限边界清晰：",
    "items": [
      {
        "permission": "llm_call",
        "type": "injected",
        "description": "LLM 调用由 OpenClaw 主 Agent 注入，skill 不直接访问网络或 API",
        "what_it_does": "接收主 Agent 提供的 LLM 调用结果，进行流程控制和决策"
      },
      {
        "permission": "file_system_read",
        "type": "limited",
        "description": "仅读取 skill 自身目录内的源代码文件",
        "what_it_does": "Python 模块加载，不读取工作区外或用户文件"
      },
      {
        "permission": "file_system_write",
        "type": "user_initiated",
        "description": "仅在用户通过 --output 参数指定时写入报告文件",
        "what_it_does": "写入分析结果报告到用户指定路径"
      },
      {
        "permission": "network",
        "type": "none",
        "description": "skill 不发起任何网络请求",
        "what_it_does": "所有 LLM 调用由主 Agent 执行"
      },
      {
        "permission": "environment",
        "type": "none",
        "description": "skill 不读取任何环境变量",
        "what_it_does": "所有配置通过调用参数传入"
      }
    ],
    "responsibility_summary": "skill 负责：需求分析 → 第一性原理推导 → 原子任务拆解 → 迭代精炼 → 依赖排序 → 结果整合 → 质量验证。所有实际 LLM 调用和任务执行由 OpenClaw 主 Agent 完成。"
  }
}


path: README.md
content: # principles-agent

基于第一性原理的迭代式 Agent 框架，OpenClaw 实现。

灵感来自 [miltonian/principles](https://github.com/miltonian/principles)。

**作者：** 🖤 小黑 & 小龙

## 核心能力

- **第一性原理需求分析** —— 剥离经验假设，回归最基础的事实和公理
- **原子级任务拆解** —— 将复杂目标拆解为不可再分、可验证的原子子任务
- **迭代式精炼** —— 自动检查并优化不满足条件的真理/子任务
- **依赖感知调度** —— 拓扑排序处理依赖，支持无依赖并行执行
- **分层质量验证** —— 每层都验证，不通过自动调试重试
- **全局整合验收** —— 最终交付前整体验证，保证结果质量

## 安装

```bash
# 已经作为 OpenClaw 技能安装
# 需要 Python 3.8+
# 无需额外依赖，直接使用
```

## 使用

```python
from principles_agent import PrinciplesOrchestrator

def llm_call(prompt):
    # 你的 LLM 调用
    return response

orch = PrinciplesOrchestrator(llm_call=llm_call)
result = orch.run("你的目标描述")
report = orch.generate_report(result)
print(report)
```

### CLI 使用

```bash
python ~/.openclaw/skills/principles-agent/cli.py "我要设计一个基于第一性原理的多Agent系统" -o report.md
```

## 工作流程

```
1. 接收需求 → 提取清晰目标
2. 第一性原理解构 → 识别基础事实/公理
3. 原子任务拆解 → 拆解为最小可执行子任务
4. 迭代精炼 → 检查最小性/可行性/对齐性，不满足则优化
5. 依赖排序 → 拓扑排序确定执行顺序，检测循环依赖
6. 执行验证 → 按序/并行执行子任务，每个都验证
7. 全局整合 → 合并所有子任务结果
8. 最终验收 → 验证满足原始目标，交付成果
```

## 架构

```
principles-agent/
├── SKILL.md
├── README.md  (本文件)
├── cli.py      # 命令行入口
└── src/
    ├── __init__.py
    ├── types.py            # 类型定义
    ├── orchestrator.py    # 总控 Orchestrator
    ├── truth_deriver.py   # 基础公理推导
    ├── task_breaker.py    # 原子任务拆解
    ├── refiner.py         # 迭代精炼决策
    ├── dependency_sorter.py # 拓扑排序
    ├── validator.py       # 验证器
    ├── executor.py        # 子任务执行器
    └── integrator.py      # 结果整合
```

## 许可证

MIT (继承自原始项目)


path: src/dependency_sorter.py
content: """
依赖拓扑排序
对原子子任务进行拓扑排序，识别可并行批次，检测循环依赖
"""
from typing import List, Dict, Set
from collections import deque

from types_def import SubTask, ExecutionPlan


class DependencySorter:
    """依赖排序器"""

    def sort(self, tasks: List[SubTask]) -> ExecutionPlan:
        """
        拓扑排序，返回有序任务列表和可并行批次
        """
        # 构建依赖图
        task_map: Dict[str, SubTask] = {t.id: t for t in tasks}
        adj: Dict[str, List[str]] = {t.id: [] for t in tasks}
        in_degree: Dict[str, int] = {t.id: 0 for t in tasks}

        for task in tasks:
            for dep_id in task.dependencies:
                if dep_id in task_map:
                    adj[dep_id].append(task.id)
                    in_degree[task.id] += 1

        # Kahn's algorithm for topological sort
        queue = deque([t_id for t_id, degree in in_degree.items() if degree == 0])
        sorted_ids: List[str] = []
        parallel_batches: List[List[str]] = []

        while queue:
            # 当前批次就是所有入度为0的节点，可以并行执行
            current_batch = list(queue)
            parallel_batches.append(current_batch)
            for _ in range(len(queue)):
                u = queue.popleft()
                sorted_ids.append(u)
                for v in adj[u]:
                    in_degree[v] -= 1
                    if in_degree[v] == 0:
                        queue.append(v)

        # 检查循环依赖
        if len(sorted_ids) != len(tasks):
            remaining = set(t.id for t in tasks) - set(sorted_ids)
            details = f"检测到循环依赖，涉及节点: {', '.join(remaining)}"
            return ExecutionPlan(
                ordered_tasks=[],
                parallel_batches=[],
                has_circular_dependency=True,
                circular_dependency_details=details
            )

        # 转换回SubTask列表
        ordered_tasks = [task_map[t_id] for t_id in sorted_ids]
        parallel_task_batches = [
            [task_map[t_id] for t_id in batch]
            for batch in parallel_batches
        ]

        return ExecutionPlan(
            ordered_tasks=ordered_tasks,
            parallel_batches=parallel_task_batches,
            has_circular_dependency=False
        )

    def get_execution_order(self, plan: ExecutionPlan) -> List[List[SubTask]]:
        """获取分批执行顺序，每批可以并行执行"""
        return plan.parallel_batches


path: src/executor.py
content: """
子任务执行器
对接 OpenClaw sessions_spawn 执行子任务
"""
from typing import List, Dict, Any
import asyncio
import json

from types_def import SubTask, TaskResult, Goal


class OpenClawExecutor:
    """OpenClaw 子任务执行器"""

    def __init__(self, session_key: str = None):
        self.session_key = session_key

    def build_task_prompt(
        self,
        task: SubTask,
        goal: Goal,
        previous_results: Dict[str, TaskResult]
    ) -> str:
        """构建子任务执行提示词"""

        # 收集依赖任务的输出
        previous_outputs = ""
        for dep_id in task.dependencies:
            if dep_id in previous_results:
                result = previous_results[dep_id]
                previous_outputs += f"\n--- 来自 {dep_id} 的输出 ---\n"
                output_str = str(result.output)
                if len(output_str) > 2000:
                    output_str = output_str[:2000] + "\n... (已截断)"
                previous_outputs += output_str + "\n"

        template = f"""你现在需要执行一个原子子任务，这是基于第一性原理拆解得到的整体项目的一部分。

## 整体目标
{goal.clarified_objective}

## 当前子任务
**{task.title}**

{task.description}

## 验收标准
{chr(10).join(f'- {c}' for c in task.acceptance_criteria)}

## 来自前置依赖任务的输出
{previous_outputs if previous_outputs else '（无前置依赖）'}

---
请完成这个子任务，并确保输出满足所有验收标准。
"""
        return template

    def execute_task_sync(
        self,
        task: SubTask,
        goal: Goal,
        previous_results: Dict[str, TaskResult],
        llm_call
    ) -> TaskResult:
        """同步执行一个任务（调用LLM）"""
        import time
        start_time = time.time()

        prompt = self.build_task_prompt(task, goal, previous_results)

        try:
            # 调用传入的 LLM 函数
            output = llm_call(prompt)

            execution_time = int((time.time() - start_time) * 1000)

            return TaskResult(
                task_id=task.id,
                success=True,
                output=output,
                validation_passed=False,  # 需要后续验证
                execution_time_ms=execution_time
            )

        except Exception as e:
            execution_time = int((time.time() - start_time) * 1000)
            return TaskResult(
                task_id=task.id,
                success=False,
                output=None,
                validation_passed=False,
                error_message=str(e),
                execution_time_ms=execution_time
            )

    def execute_parallel_batch(
        self,
        batch: List[SubTask],
        goal: Goal,
        previous_results: Dict[str, TaskResult],
        llm_call
    ) -> List[TaskResult]:
        """并行执行一批无依赖的任务"""
        results = []
        for task in batch:
            result = self.execute_task_sync(task, goal, previous_results, llm_call)
            results.append(result)
            previous_results[task.id] = result
        return results


path: src/integrator.py
content: """
结果整合
整合所有子任务结果，生成最终输出
"""
from typing import List, Any
import json

from types_def import Goal, FundamentalTruth, SubTask, TaskResult, FinalResult


class Integrator:
    """结果整合器"""

    SYSTEM_PROMPT = """你是一个**结果整合专家**，负责将所有原子子任务的结果整合为一个连贯、完整的最终输出。

## 整合规则：
1. **完整保留所有有效结果** —— 不要遗漏任何子任务的产出
2. **保持逻辑连贯** —— 按照依赖关系和执行顺序组织结果
3. **消除重复** —— 合并重复内容，保持简洁
4. **满足原始目标** —— 最终输出必须完全满足原始目标的要求
5. **结构清晰** —— 使用适当的标题、分段、列表组织内容

## 输出要求：
请生成一个完整的最终结果，包括：
1. 对原始目标的简要回顾
2. 核心基础事实总结
3. 整合后的主体内容
4. 结论和下一步建议

## 输出格式：
{
  "synthesized_output": "整合后的完整最终结果（markdown格式）",
  "report": "完整的执行过程报告，包括迭代次数、精炼过程、任务完成情况"
}
"""

    def __init__(self):
        pass

    def integrate(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        tasks: List[SubTask],
        task_results: List[TaskResult],
        iteration_count: int
    ) -> Any:
        """整合所有结果"""
        prompt = self._build_prompt(goal, truths, tasks, task_results, iteration_count)
        return self._parse_response(prompt)

    def _build_prompt(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        tasks: List[SubTask],
        task_results: List[TaskResult],
        iteration_count: int
    ) -> str:
        truths_text = "\n".join(
            f"- {t.id}: {t.content}" for t in truths
        )

        results_text = ""
        for task, result in zip(tasks, task_results):
            results_text += f"\n### {task.id}: {task.title}\n"
            results_text += f"状态: {'✅ 通过' if result.success and result.validation_passed else '❌ 失败'}\n"
            output_str = str(result.output)
            if len(output_str) > 1000:
                output_str = output_str[:1000] + "\n... (已截断)"
            results_text += f"输出:\n{output_str}\n"

        return f"""原始目标:
{goal.clarified_objective}

约束条件:
{chr(10).join(f'- {c}' for c in goal.constraints)}

成功标准:
{chr(10).join(f'- {c}' for c in goal.success_criteria)}

基础事实:
{truths_text}

各任务结果:
{results_text}

迭代次数: {iteration_count}

请整合所有结果，生成最终输出。
"""

    def _parse_response(self, response_text: str) -> dict:
        cleaned = self._extract_json(response_text)
        data = json.loads(cleaned)
        return {
            "synthesized_output": data.get("synthesized_output", ""),
            "report": data.get("report", "")
        }

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        start = text.find("{")
        end = text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        return text


path: src/orchestrator.py
content: """
总控 Orchestrator
协调整个第一性原理 Agent 生成执行流程
"""
from typing import List, Callable, Dict, Optional
import json

from types_def import (
    Goal,
    FundamentalTruth,
    SubTask,
    RefinementDecision,
    RefinementType,
    ExecutionPlan,
    TaskResult,
    FinalResult
)
from truth_deriver import TruthDeriver
from task_breaker import TaskBreaker
from refiner import Refiner
from dependency_sorter import DependencySorter
from validator import Validator
from executor import OpenClawExecutor
from integrator import Integrator


class PrinciplesOrchestrator:
    """
    基于第一性原理的总控 Orchestrator
    """

    def __init__(
        self,
        llm_call: Callable[[str], str],
        max_iterations: int = 5,
        session_key: str = None
    ):
        """
        初始化
        :param llm_call: LLM 调用函数，输入 prompt，返回文本
        :param max_iterations: 最大迭代精炼次数
        :param session_key: OpenClaw 会话 key
        """
        self.llm_call = llm_call
        self.max_iterations = max_iterations
        self.truth_deriver = TruthDeriver()
        self.task_breaker = TaskBreaker()
        self.refiner = Refiner()
        self.dependency_sorter = DependencySorter()
        self.validator = Validator()
        self.executor = OpenClawExecutor(session_key)
        self.integrator = Integrator()

    def clarify_goal(self, original_prompt: str) -> Goal:
        """澄清目标，提取约束和成功标准"""
        prompt = f"""请帮我澄清这个目标，提取出清晰的目标描述、约束条件和可量化的成功标准。

原始请求: {original_prompt}

请以 JSON 格式返回：
{{
  "clarified_objective": "清晰简明的目标描述",
  "constraints": ["约束条件1", "约束条件2"],
  "success_criteria": ["成功标准1", "成功标准2"]
}}
"""
        response = self.llm_call(prompt)
        cleaned = self._extract_json(response)
        data = json.loads(cleaned)

        return Goal(
            original_prompt=original_prompt,
            clarified_objective=data.get("clarified_objective", original_prompt),
            constraints=data.get("constraints", []),
            success_criteria=data.get("success_criteria", [])
        )

    def run(self, original_prompt: str) -> FinalResult:
        """
        执行完整的 Principles 流程
        1. 澄清目标
        2. 推导基础事实（迭代精炼）
        3. 拆解原子任务（迭代精炼）
        4. 依赖排序
        5. 按批次执行并验证
        6. 整合结果
        7. 全局验证
        """

        # Step 1: 澄清目标
        goal = self.clarify_goal(original_prompt)
        iteration_count = 0
        truths: List[FundamentalTruth] = []
        subtasks: List[SubTask] = []
        relationships = ""

        # Step 2-4: 迭代精炼直到满足要求
        truths, subtasks, iteration_count = self._iterate_refine(goal)

        # Step 5: 依赖拓扑排序
        plan = self.dependency_sorter.sort(subtasks)
        if plan.has_circular_dependency:
            raise ValueError(f"依赖排序失败: {plan.circular_dependency_details}")

        # Step 6: 按批次执行并验证
        task_results: List[TaskResult] = []
        previous_results: Dict[str, TaskResult] = {}

        for batch in plan.parallel_batches:
            # 执行批次
            batch_results = self.executor.execute_parallel_batch(
                batch, goal, previous_results, self.llm_call
            )

            # 验证每个结果
            for task, result in zip(batch, batch_results):
                if result.success:
                    # 验证输出
                    passed, failed, reason = self.validator.validate_task(task, result.output)
                    result.validation_passed = passed
                    if not passed:
                        # 这里可以重试，简化处理先记录
                        result.error_message = f"验证失败: {reason}; 不通过标准: {failed}"

                task_results.append(result)
                previous_results[task.id] = result

        # Step 7: 整合结果
        integration = self.integrator.integrate(
            goal, truths, subtasks, task_results, iteration_count
        )

        # Step 8: 全局验证
        global_passed, global_reason = self.validator.validate_global(
            goal, task_results, integration["synthesized_output"]
        )

        return FinalResult(
            goal=goal,
            truths=truths,
            tasks=subtasks,
            task_results=task_results,
            synthesized_output=integration.get("synthesized_output", ""),
            global_validation_passed=global_passed,
            iteration_count=iteration_count,
            report=integration.get("report", "")
        )

    def _iterate_refine(
        self,
        goal: Goal
    ) -> tuple[List[FundamentalTruth], List[SubTask], int]:
        """迭代精炼循环"""
        iteration_count = 0
        truths: List[FundamentalTruth] = []
        subtasks: List[SubTask] = []
        relationships = ""

        # 第一步：推导基础事实
        prompt = self.truth_deriver._build_prompt(goal)
        response = self.llm_call(prompt)
        truths, relationships = self.truth_deriver._parse_response(response)

        while iteration_count < self.max_iterations:
            iteration_count += 1

            # 拆解任务
            prompt = self.task_breaker._build_prompt(goal, truths)
            response = self.llm_call(prompt)
            subtasks = self.task_breaker._parse_response(response)

            # 决策是否需要精炼
            prompt = self.refiner._build_prompt(goal, truths, subtasks)
            response = self.llm_call(prompt)
            decision = self.refiner._parse_response(response)

            if decision.decision == RefinementType.FINALIZE:
                break
            elif decision.decision == RefinementType.REFINE_TRUTHS:
                # 重新推导事实
                prompt = self.truth_deriver._build_prompt_with_feedback(
                    goal, decision.feedback
                )
                response = self.llm_call(prompt)
                truths, relationships = self.truth_deriver._parse_response(response)
            elif decision.decision == RefinementType.REFINE_SUBTASKS:
                # 保持事实不变，重新拆解任务
                continue

        return truths, subtasks, iteration_count

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        # 找到第一个 { 和最后一个 }
        start = text.find("{")
        end = text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        
        # 如果找不到完整对象，尝试找数组
        start = text.find("[")
        end = text.rfind("]")
        if start >= 0 and end >= 0:
            return text[start:end+1]
            
        return text

    def generate_report(self, result: FinalResult) -> str:
        """生成可读的执行报告"""
        report = []
        report.append("# Principles 执行报告\n")
        report.append(f"## 原始目标\n{result.goal.original_prompt}\n")
        report.append(f"## 澄清目标\n{result.goal.clarified_objective}\n")

        if result.goal.constraints:
            report.append("## 约束条件\n")
            for c in result.goal.constraints:
                report.append(f"- {c}")
            report.append("")

        report.append(f"## 基础事实 ({len(result.truths)} 项)\n")
        for t in result.truths:
            report.append(f"- **{t.id}**: {t.content}")
        report.append("")

        report.append(f"## 原子任务 ({len(result.tasks)} 项)\n")
        for t in result.tasks:
            status = "✅" if all(
                r.task_id == t.id and r.success and r.validation_passed
                for r in result.task_results
            ) else "❌"
            deps = f" (依赖: {', '.join(t.dependencies)})" if t.dependencies else ""
            report.append(f"{status} **{t.id}**: {t.title}{deps}")
        report.append("")

        report.append(f"## 迭代次数: {result.iteration_count}\n")
        report.append(f"## 全局验证: {'✅ 通过' if result.global_validation_passed else '❌ 不通过'}\n")

        if result.report:
            report.append("---\n")
            report.append(result.report)

        report.append("\n---\n## 最终输出\n")
        report.append(str(result.synthesized_output))

        return "\n".join(report)


path: src/refiner.py
content: """
迭代精炼决策
判断当前的基础事实和子任务是否满足要求，决定是否需要进一步精炼
"""
import json
from typing import List

from types_def import Goal, FundamentalTruth, SubTask, RefinementDecision, RefinementType


class Refiner:
    """迭代精炼决策者"""

    SYSTEM_PROMPT = """你是一个**质量检查员**，负责检查第一性原理拆解得到的基础事实和原子子任务是否满足要求，并决定下一步行动。

## 检查标准：

### 对基础事实的检查：
1. ✅ **真正基础** —— 每个事实都是不可分割的，不是推导出来的
2. ✅ **完整覆盖** —— 覆盖了实现目标所需的所有核心假设
3. ✅ **没有混入步骤** —— 只包含"是什么"，不包含实现步骤

### 对子任务的检查：
1. ✅ **原子性** —— 每个子任务都不可再分
2. ✅ **可行性** —— 每个子任务都在 LLM Agent 能力范围内
3. ✅ **可验证性** —— 每个子任务都有明确的验收标准
4. ✅ **单一职责** —— 一个子任务只做一件事
5. ✅ **无重叠** —— 功能不重叠
6. ✅ **依赖正确** —— 依赖关系正确，没有循环依赖

## 决策选项：
1. **finalize** —— 全部满足要求，可以进入下一步执行
2. **refine_subtasks** —— 子任务不满足要求，需要重新拆解（基础事实没问题）
3. **refine_truths** —— 基础事实不满足要求，需要重新推导

## 输出格式：
必须返回严格的 JSON，格式如下：
{
  "decision": "finalize" | "refine_subtasks" | "refine_truths",
  "reason": "为什么做出这个决策，具体哪里不满足",
  "feedback": "给下一轮拆解/推导的具体反馈建议"
}
"""

    def __init__(self):
        pass

    def decide(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        subtasks: List[SubTask]
    ) -> RefinementDecision:
        """检查当前结果，决定是否需要精炼"""
        prompt = self._build_prompt(goal, truths, subtasks)
        return self._parse_response(prompt)

    def _build_prompt(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        subtasks: List[SubTask]
    ) -> str:
        truths_text = "\n".join(
            f"- {t.id}: {t.content}" for t in truths
        )

        subtasks_text = "\n".join(
            f"- {t.id}: {t.title} | 原子: {t.is_atomic} | 可行: {t.is_feasible} | 依赖: {', '.join(t.dependencies)}"
            for t in subtasks
        )

        return f"""目标: {goal.clarified_objective}

当前推导得到的基础事实：
{truths_text}

当前拆解得到的子任务：
{subtasks_text}

请检查是否满足所有标准，然后给出你的决策。
"""

    def _parse_response(self, response_text: str) -> RefinementDecision:
        """解析LLM响应"""
        cleaned = self._extract_json(response_text)
        data = json.loads(cleaned)

        decision_str = data.get("decision", "refine_subtasks")
        decision_map = {
            "finalize": RefinementType.FINALIZE,
            "refine_subtasks": RefinementType.REFINE_SUBTASKS,
            "refine_truths": RefinementType.REFINE_TRUTHS,
        }
        decision_type = decision_map.get(decision_str, RefinementType.REFINE_SUBTASKS)

        return RefinementDecision(
            decision=decision_type,
            reason=data.get("reason", ""),
            feedback=data.get("feedback", "")
        )

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        start = text.find("{")
        end = text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        return text


path: src/task_breaker.py
content: """
原子任务拆解
将目标基于基础事实拆解为最小可执行、可验证的原子子任务
"""
from typing import List
import json

from types_def import Goal, FundamentalTruth, SubTask


class TaskBreaker:
    """原子任务拆解器"""

    SYSTEM_PROMPT = """你是一个**任务拆解专家**，擅长基于第一性原理的基础事实，将复杂目标拆解为最小的、可执行、可验证的原子子任务。

## 核心规则：
1. **原子性** —— 每个子任务必须不可再分，如果还能拆分，就继续拆分
2. **可验证性** —— 每个子任务必须有明确的验收标准，能判断是否完成
3. **可行性** —— 每个子任务必须在单个 LLM Agent 的能力范围内（文本处理、分析、生成等）
4. **单一职责** —— 一个子任务只做一件事
5. **无重叠** —— 子任务之间功能不重叠
6. **依赖清晰** —— 明确标注每个子任务依赖哪些其他子任务的输出

## 验收标准要求：
每个子任务必须定义至少一条清晰可量化的验收标准，例如：
- "输出必须符合指定 JSON 格式"
- "覆盖所有 5 个核心要点"
- "通过语法检查，无编译错误"
- "包含完整的 API 文档"

## 输出格式：
必须返回严格的 JSON，格式如下：
{
  "subtasks": [
    {
      "id": "task-1",
      "title": "子任务标题",
      "description": "子任务详细描述",
      "acceptance_criteria": [
        "验收标准 1",
        "验收标准 2"
      ],
      "dependencies": ["依赖的任务ID，如 task-0"],
      "is_feasible": true,
      "is_atomic": true
    }
  ]
}

记住：**极致拆分** —— 哪怕一个任务只需要一句话，只要它是独立的，就应该拆出来。
"""

    def __init__(self):
        pass

    def decompose(self, goal: Goal, truths: List[FundamentalTruth]) -> List[SubTask]:
        """基于基础事实拆解目标为原子子任务"""
        prompt = self._build_prompt(goal, truths)
        # 实际 LLM 调用在上层 orchestrator
        return self._parse_response(prompt)

    def decompose_with_feedback(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        feedback: str
    ) -> List[SubTask]:
        """根据反馈重新拆解任务"""
        prompt = self._build_prompt_with_feedback(goal, truths, feedback)
        return self._parse_response(prompt)

    def _build_prompt(self, goal: Goal, truths: List[FundamentalTruth]) -> str:
        truths_text = "\n".join(
            f"{t.id}: {t.content} - {t.description}"
            for t in truths
        )

        return f"""目标:
澄清后的目标: {goal.clarified_objective}
原始描述: {goal.original_prompt}

约束条件:
{chr(10).join(f'- {c}' for c in goal.constraints)}

基础事实/公理:
{truths_text}

请基于上述基础事实，将目标拆解为最小的、可执行、可验证的原子子任务。
"""

    def _build_prompt_with_feedback(
        self,
        goal: Goal,
        truths: List[FundamentalTruth],
        feedback: str
    ) -> str:
        truths_text = "\n".join(
            f"{t.id}: {t.content} - {t.description}"
            for t in truths
        )

        return f"""目标:
澄清后的目标: {goal.clarified_objective}
原始描述: {goal.original_prompt}

约束条件:
{chr(10).join(f'- {c}' for c in goal.constraints)}

基础事实/公理:
{truths_text}

之前的拆解不满足要求，反馈意见是:
---
{feedback}
---

请根据反馈重新拆解，确保:
1. 每个子任务都是真正原子的，不可再分
2. 每个子任务都有明确可验证的验收标准
3. 所有子任务都在 LLM 能力范围内
4. 依赖关系清晰正确
"""

    def _parse_response(self, response_text: str) -> List[SubTask]:
        """解析LLM响应"""
        cleaned = self._extract_json(response_text)
        data = json.loads(cleaned)

        subtasks = []
        for t in data.get("subtasks", []):
            task = SubTask(
                id=t.get("id", f"task-{len(subtasks)+1}"),
                title=t.get("title", ""),
                description=t.get("description", ""),
                acceptance_criteria=t.get("acceptance_criteria", []),
                dependencies=t.get("dependencies", []),
                is_feasible=t.get("is_feasible", True),
                is_atomic=t.get("is_atomic", True)
            )
            subtasks.append(task)

        return subtasks

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        start = text.find("[")
        if start < 0:
            start = text.find("{")
        end = text.rfind("]") if text.rfind("]") >= 0 else text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        return text


path: src/truth_deriver.py
content: """
基础事实/公理推导
使用第一性原理思维，从目标中推导出最基础的、不可分割的事实/公理
"""
from typing import List, Tuple
import json

from types_def import Goal, FundamentalTruth


class TruthDeriver:
    """基础事实推导器"""

    MAX_TRUTHS = 15
    SYSTEM_PROMPT = """你是一个**第一性原理思维大师**，擅长将复杂目标回归到最基础、不可分割的事实和公理。

## 核心规则：
1. **剥离所有经验性假设** —— 不要用类比，不要套模板，直接回归本质
2. **只保留不可分割的基础事实** —— 如果一个事实还能再拆分，那就继续拆分
3. **每个事实必须明确、具体、无歧义**
4. **识别出所有支撑目标实现的核心约束和基础条件**
5. **不要包含实现步骤**，只保留"是什么"，不是"怎么做"

## 输出格式：
必须返回严格的 JSON，格式如下：
{
  "truths": [
    {
      "id": "truth-1",
      "content": "基础事实内容",
      "description": "对这个事实的简要说明，解释为什么它是基础的",
      "is_fundamental": true,
      "dependencies": []
    }
  ]
}

记住：**少即是多** —— 只保留真正基础的，把可以推导出来的去掉。
"""

    def derive_truths(self, goal: Goal) -> Tuple[List[FundamentalTruth], str]:
        """
        从目标推导基础事实
        返回：(truths列表, 关系描述)
        """
        prompt = self._build_prompt(goal)
        
        # 这里由 LLM 处理，返回解析后的 JSON
        # 在实际 orchestrator 中调用 LLM
        # 这里定义接口，实际由上层调用

        return self._parse_response(prompt)

    def _build_prompt(self, goal: Goal) -> str:
        return f"""用户目标:
原始描述: {goal.original_prompt}
澄清后的目标: {goal.clarified_objective}

约束条件:
{chr(10).join(f'- {c}' for c in goal.constraints)}

请用第一性原理推导出支撑这个目标的最基础不可分割的事实/公理。
"""

    def _parse_response(self, response_text: str) -> Tuple[List[FundamentalTruth], str]:
        """解析LLM返回的响应"""
        # 清理响应，提取JSON
        cleaned = self._extract_json(response_text)
        data = json.loads(cleaned)

        truths = []
        for t in data.get("truths", []):
            truth = FundamentalTruth(
                id=t.get("id", f"truth-{len(truths)+1}"),
                content=t.get("content", ""),
                description=t.get("description", ""),
                is_fundamental=t.get("is_fundamental", True),
                dependencies=t.get("dependencies", [])
            )
            truths.append(truth)

        # 提取关系描述（如果有）
        relationships = data.get("relationships", "")
        if isinstance(relationships, list):
            relationships = "\n".join(relationships)

        return truths, relationships

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        # 找到第一个 { 和最后一个 }
        start = text.find("{")
        end = text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        
        # 如果找不到完整对象，尝试找数组
        start = text.find("[")
        end = text.rfind("]")
        if start >= 0 and end >= 0:
            return text[start:end+1]
            
        return text

    def re_derive_truths(self, goal: Goal, feedback: str) -> Tuple[List[FundamentalTruth], str]:
        """根据反馈重新推导基础事实"""
        prompt = self._build_prompt_with_feedback(goal, feedback)
        return self._parse_response(prompt)

    def _build_prompt_with_feedback(self, goal: Goal, feedback: str) -> str:
        return f"""用户目标:
原始描述: {goal.original_prompt}
澄清后的目标: {goal.clarified_objective}

约束条件:
{chr(10).join(f'- {c}' for c in goal.constraints)}

之前的推导不满足要求，反馈意见是:
---
{feedback}
---

请根据反馈重新用第一性原理推导出支撑这个目标的最基础不可分割的事实/公理。
确保满足:
1. 每个事实都是真正不可分割的基础
2. 覆盖所有核心基础假设
3. 没有混入实现步骤
"""


path: src/types_def.py
content: """
类型定义
"""
from enum import Enum
from typing import List, Dict, Optional, Any
from dataclasses import dataclass, field


class RefinementType(Enum):
    """精炼类型"""
    FINALIZE = "finalize"
    REFINE_SUBTASKS = "refine_subtasks"
    REFINE_TRUTHS = "refine_truths"


@dataclass
class Goal:
    """用户目标"""
    original_prompt: str
    clarified_objective: str
    constraints: List[str] = field(default_factory=list)
    success_criteria: List[str] = field(default_factory=list)

    def to_dict(self) -> Dict[str, Any]:
        return {
            "original_prompt": self.original_prompt,
            "clarified_objective": self.clarified_objective,
            "constraints": self.constraints,
            "success_criteria": self.success_criteria
        }


@dataclass
class FundamentalTruth:
    """基础事实/公理"""
    id: str
    content: str
    description: str = ""
    is_fundamental: bool = True
    dependencies: List[str] = field(default_factory=list)

    def to_dict(self) -> Dict[str, Any]:
        return {
            "id": self.id,
            "content": self.content,
            "description": self.description,
            "is_fundamental": self.is_fundamental,
            "dependencies": self.dependencies
        }


@dataclass
class SubTask:
    """原子子任务"""
    id: str
    title: str
    description: str
    acceptance_criteria: List[str] = field(default_factory=list)
    dependencies: List[str] = field(default_factory=list)
    is_feasible: bool = True
    is_atomic: bool = True
    assigned_agent_id: Optional[str] = None

    def to_dict(self) -> Dict[str, Any]:
        return {
            "id": self.id,
            "title": self.title,
            "description": self.description,
            "acceptance_criteria": self.acceptance_criteria,
            "dependencies": self.dependencies,
            "is_feasible": self.is_feasible,
            "is_atomic": self.is_atomic,
            "assigned_agent_id": self.assigned_agent_id
        }


@dataclass
class RefinementDecision:
    """精炼决策"""
    decision: RefinementType
    reason: str
    feedback: str = ""

    def to_dict(self) -> Dict[str, Any]:
        return {
            "decision": self.decision.value,
            "reason": self.reason,
            "feedback": self.feedback
        }


@dataclass
class TaskResult:
    """子任务执行结果"""
    task_id: str
    success: bool
    output: Any
    validation_passed: bool
    error_message: str = ""
    execution_time_ms: int = 0

    def to_dict(self) -> Dict[str, Any]:
        return {
            "task_id": self.task_id,
            "success": self.success,
            "output": self.output,
            "validation_passed": self.validation_passed,
            "error_message": self.error_message,
            "execution_time_ms": self.execution_time_ms
        }


@dataclass
class ExecutionPlan:
    """执行计划"""
    ordered_tasks: List[SubTask]
    parallel_batches: List[List[SubTask]]
    has_circular_dependency: bool = False
    circular_dependency_details: str = ""

    def to_dict(self) -> Dict[str, Any]:
        return {
            "ordered_tasks": [t.to_dict() for t in self.ordered_tasks],
            "parallel_batches": [[t.to_dict() for t in batch] for batch in self.parallel_batches],
            "has_circular_dependency": self.has_circular_dependency,
            "circular_dependency_details": self.circular_dependency_details
        }


@dataclass
class FinalResult:
    """最终结果"""
    goal: Goal
    truths: List[FundamentalTruth]
    tasks: List[SubTask]
    task_results: List[TaskResult]
    synthesized_output: Any
    global_validation_passed: bool
    iteration_count: int
    report: str

    def to_dict(self) -> Dict[str, Any]:
        return {
            "goal": self.goal.to_dict(),
            "truths": [t.to_dict() for t in self.truths],
            "tasks": [t.to_dict() for t in self.tasks],
            "task_results": [r.to_dict() for r in self.task_results],
            "synthesized_output": self.synthesized_output,
            "global_validation_passed": self.global_validation_passed,
            "iteration_count": self.iteration_count,
            "report": self.report
        }


path: src/validator.py
content: """
验证器
验证子任务输出是否满足验收标准
"""
from typing import List, Tuple
import json

from types_def import SubTask, TaskResult


class Validator:
    """任务验证器"""

    SYSTEM_PROMPT = """你是一个**严格的质量检查员**，负责验证子任务输出是否满足所有验收标准。

## 验证规则：
1. **逐条检查验收标准** —— 每个标准都要检查，不能漏掉
2. **严格不妥协** —— 只要有一个重要标准不满足，就不通过
3. **给出明确结论** —— 是通过还是不通过，不模棱两可
4. **说明具体原因** —— 如果不通过，明确指出哪里不满足

## 输出格式：
必须返回严格的 JSON，格式如下：
{
  "validation_passed": true/false,
  "failed_criteria": [
    "不满足的验收标准1",
    "不满足的验收标准2"
  ],
  "reason": "对验证结果的详细说明"
}
"""

    def validate_task(self, task: SubTask, output: any) -> Tuple[bool, List[str], str]:
        """
        验证任务输出是否满足所有验收标准
        返回：(是否通过, 不通过的标准列表, 原因说明)
        """
        prompt = self._build_prompt(task, output)
        # 实际 LLM 调用在上层
        return self._parse_response(prompt)

    def _build_prompt(self, task: SubTask, output: any) -> str:
        criteria = "\n".join(
            f"- {i+1}. {c}" for i, c in enumerate(task.acceptance_criteria)
        )

        output_str = str(output)
        if len(output_str) > 5000:
            output_str = output_str[:5000] + "\n... (输出过长，已截断)"

        return f"""子任务信息：
ID: {task.id}
标题: {task.title}
描述: {task.description}

验收标准：
{criteria}

任务输出：
---
{output_str}
---

请验证输出是否满足所有验收标准。
"""

    def _parse_response(self, response_text: str) -> Tuple[bool, List[str], str]:
        cleaned = self._extract_json(response_text)
        data = json.loads(cleaned)

        passed = data.get("validation_passed", False)
        failed = data.get("failed_criteria", [])
        reason = data.get("reason", "")

        return passed, failed, reason

    def _extract_json(self, text: str) -> str:
        """从文本提取JSON，处理 markdown 代码块"""
        import re
        
        # 移除 markdown 代码块标记
        text = re.sub(r'```(?:json)?\n', '', text)
        text = re.sub(r'\n```', '', text)
        
        start = text.find("{")
        end = text.rfind("}")
        if start >= 0 and end >= 0:
            return text[start:end+1]
        return text

    def validate_global(
        self,
        original_goal,
        all_results: List[TaskResult],
        synthesized_output: any
    ) -> Tuple[bool, str]:
        """全局验证最终结果是否满足原始目标"""
        passed_all = all(r.validation_passed for r in all_results)
        if not passed_all:
            failed_tasks = [r.task_id for r in all_results if not r.validation_passed]
            return False, f"部分子任务验证未通过: {', '.join(failed_tasks)}"

        return True, "所有验证通过"


path: src/__init__.py
content: """
principles-agent
===============
基于第一性原理的迭代式 Agent 框架，OpenClaw 实现。

核心：
- 第一性原理需求解构
- 原子任务拆解
- 迭代式精炼
- 依赖感知调度
- 分层验证
- 全局整合
"""

from orchestrator import PrinciplesOrchestrator
from types_def import (
    Goal,
    FundamentalTruth,
    SubTask,
    ExecutionPlan,
    TaskResult,
    FinalResult,
    RefinementDecision,
    RefinementType
)

__version__ = "0.1.0"
__author__ = "OpenClaw"

__all__ = [
    "PrinciplesOrchestrator",
    "Goal",
    "FundamentalTruth",
    "SubTask",
    "ExecutionPlan",
    "TaskResult",
    "FinalResult",
    "RefinementDecision",
    "RefinementType"
]


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)