[Agent] ACE（Agentic Context Engineering）源碼閱讀筆記---（1）基礎(chǔ)模塊

0x00 概要

這世界變化真快！

前幾天我在博客說(shuō)，斯坦福的ACE（Agentic Context Engineering）非常火。只看論文感覺還是理解不深，但是該論文并沒有釋放對(duì)應(yīng)的源碼。

然而，幾天后就發(fā)現(xiàn)了一個(gè)開源項(xiàng)目 https://github.com/kayba-ai/agentic-context-engine，項(xiàng)目寫明了：

Based on the ACE paper and inspired by Dynamic Cheatsheet.

If you use ACE in your research, please cite:

@article{zhang2024ace,title={Agentic Context Engineering},author={Zhang et al.},journal={arXiv:2510.04618},year={2024}}

于是只能乖乖的把代碼拉下來(lái)看看。

0x01 示例

我們先通過(guò)示例來(lái)梳理下總體邏輯，該示例適合快速入手和理解ACE的工作流程：生成→反思→策略→再生成。

1.1 建立簡(jiǎn)單Agent

該代碼特色如下：

• 展示了 Agentic Context Engineering（ACE）系統(tǒng)的核心工作流程，通過(guò)初始化關(guān)鍵組件（Generator，Reflector，Curator）和環(huán)境，利用樣本數(shù)據(jù)訓(xùn)練智能體，使其從示例中學(xué)習(xí)策略并存儲(chǔ)到 Playbook 中，最終實(shí)現(xiàn)對(duì)新問(wèn)題的智能響應(yīng)。

• 核心功能包括：初始化 LLM 客戶端連接大語(yǔ)言模型、創(chuàng)建 ACE 系統(tǒng)三大核心組件（生成器負(fù)責(zé)生成回答、反思器負(fù)責(zé)分析策略有效性、管理者負(fù)責(zé)優(yōu)化策略庫(kù)）、通過(guò)離線適配器協(xié)調(diào)組件工作、利用樣本數(shù)據(jù)訓(xùn)練智能體并將學(xué)習(xí)到的策略保存到 Playbook、測(cè)試訓(xùn)練后的智能體對(duì)新問(wèn)題的處理能力。

• 分別展示了這些組件的使用，以及如何組合這些組件來(lái)完成特定任務(wù)，多種任務(wù)類型如下：

  • 知識(shí)問(wèn)答："What is the capital of France?"
  • 數(shù)學(xué)計(jì)算："What is 2 + 2?"
  • 文本理解："Who wrote Romeo and Juliet?"

• 特色是模塊化設(shè)計(jì)（各組件職責(zé)明確且可替換），支持從樣本中自主學(xué)習(xí)策略并動(dòng)態(tài)更新 Playbook，結(jié)合環(huán)境評(píng)估實(shí)現(xiàn)持續(xù)優(yōu)化，兼容多種大語(yǔ)言模型，兼顧訓(xùn)練與推理流程的完整性。

流程如下：

代碼如下：

from ace import OfflineAdapter, Generator, Reflector, Curator
from ace import LiteLLMClient, SimpleEnvironment
from ace.types import Sample

# Initialize the LLM client
client = LiteLLMClient(model="gpt-4o-mini")  # or claude-3-haiku, gemini-pro, etc.

# Create the three ACE components
generator = Generator(client)
reflector = Reflector(client)
curator = Curator(client)

# Create an adapter to orchestrate everything
adapter = OfflineAdapter(generator, reflector, curator)

# Set up the environment (evaluates answers)
environment = SimpleEnvironment()

# Create training samples
samples = [
    Sample(
        question="What is the capital of France?",
        context="Provide a direct answer",
        ground_truth="Paris"
    ),
    Sample(
        question="What is 2 + 2?",
        context="Show the calculation",
        ground_truth="4"
    ),
    Sample(
        question="Who wrote Romeo and Juliet?",
        context="Name the author",
        ground_truth="William Shakespeare"
    )
]

# Train the agent (it learns strategies from these examples)
print("Training agent...")
results = adapter.run(samples, environment, epochs=2)

# Save the learned strategies
adapter.playbook.save_to_file("my_trained_agent.json")
print(f"Agent trained! Learned {len(adapter.playbook.bullets())} strategies")

# Test with a new question
test_sample = Sample(
    question="What is 5 + 3?",
    context="Provide the answer"
)

print("\nTesting with new question:", test_sample.question)
output = generator.generate(
    question=test_sample.question,
    context=test_sample.context,
    playbook=adapter.playbook
)
print("Answer:", output.final_answer)
print("Reasoning:", output.reasoning)

運(yùn)行Agent之后，期待輸出是

Training agent...
Agent trained! Learned 3 strategies

Testing with new question: What is 5 + 3?
Answer: 8
Reasoning: Using direct calculation strategy learned from training...

Agent做了如下：

• 從訓(xùn)練示例中學(xué)習(xí)
• 反思哪些策略有效
• 構(gòu)建了一個(gè)成功方法的手冊(cè)
• 應(yīng)用這些策略來(lái)解決新問(wèn)題

這樣就授予了智能體 反思→學(xué)習(xí)→成長(zhǎng) 的能力。

1.2 后續(xù)操作

后續(xù)可以做如下：

Try Different Models

# OpenAI GPT-4
client = LiteLLMClient(model="gpt-4")

# Anthropic Claude
client = LiteLLMClient(model="claude-3-5-sonnet-20241022")

# Google Gemini
client = LiteLLMClient(model="gemini-pro")

# Local Ollama
client = LiteLLMClient(model="ollama/llama2")

Load and Continue Training

from ace import Playbook

# Load a previously trained agent
playbook = Playbook.load_from_file("my_trained_agent.json")

# Continue training with new examples
adapter = OfflineAdapter(generator, reflector, curator, playbook=playbook)

Online Learning (Learn While Running)

from ace import OnlineAdapter

adapter = OnlineAdapter(
    playbook=playbook,
    generator=generator,
    reflector=reflector,
    curator=curator
)

# Process tasks one by one, learning from each
for task in tasks:
    result = adapter.process(task, environment)
    print(f"Processed: {task.question}")
    print(f"Playbook now has {len(adapter.playbook.bullets())} strategies")

Custom Environments

from ace import TaskEnvironment, EnvironmentResult

class MathEnvironment(TaskEnvironment):
    def evaluate(self, sample, output):
        try:
            # Evaluate mathematical correctness
            result = eval(output.final_answer)
            correct = (result == eval(sample.ground_truth))

            return EnvironmentResult(
                feedback="Correct!" if correct else "Incorrect",
                ground_truth=sample.ground_truth,
                metrics={"accuracy": 1.0 if correct else 0.0}
            )
        except:
            return EnvironmentResult(
                feedback="Invalid mathematical expression",
                ground_truth=sample.ground_truth,
                metrics={"accuracy": 0.0}
            )

0x02 基建功能

2.1 Playbook

Playbook 是 ACE 系統(tǒng)中實(shí)現(xiàn)持續(xù)學(xué)習(xí)和改進(jìn)的關(guān)鍵組件，它不僅存儲(chǔ)和管理策略知識(shí)庫(kù)，還支持動(dòng)態(tài)更新和優(yōu)化，為整個(gè)系統(tǒng)智能決策的基礎(chǔ)，其具體功能為：

• 知識(shí)存儲(chǔ)：存儲(chǔ)系統(tǒng)學(xué)習(xí)到的策略和經(jīng)驗(yàn)
• 策略應(yīng)用：為 Generator 提供可用的策略集合
• 動(dòng)態(tài)演化：通過(guò) Curator 的 Delta 操作持續(xù)改進(jìn)
• 性能反饋：通過(guò)標(biāo)簽統(tǒng)計(jì)反映策略的有效性

2.1.1 基本結(jié)構(gòu)與數(shù)據(jù)模型

Playbook采用分層結(jié)構(gòu)組織策略信息，主要包括：

• Bullet（策略條目）：最小單位，包含具體策略內(nèi)容。每個(gè)Bullet有唯一ID、所屬section、內(nèi)容文本
  包含統(tǒng)計(jì)信息：helpful（有用次數(shù)）、harmful（有害次數(shù)）、neutral（中性次數(shù)）
  帶有創(chuàng)建和更新時(shí)間戳
• Section（分類）：策略的邏輯分組（或者說(shuō)是章節(jié)）。每個(gè)Bullet歸屬于一個(gè)section，通過(guò)section可以組織和檢索相關(guān)策略

class Playbook:
    """Structured context store as defined by ACE.
    按照ACE（智能體上下文工程）框架定義的結(jié)構(gòu)化上下文存儲(chǔ)容器
    """

    def __init__(self) -> None:
        # 存儲(chǔ)條目：鍵為條目ID，值為Bullet對(duì)象
        self._bullets: Dict[str, Bullet] = {}
        # 存儲(chǔ)章節(jié)與條目ID的映射：鍵為章節(jié)名稱，值為該章節(jié)下的條目ID列表
        self._sections: Dict[str, List[str]] = {}
        # 用于生成新條目的自增ID計(jì)數(shù)器
        self._next_id = 0

Playbook 的圖例如下：

2.1.2 核心功能

核心功能包括

• CRUD操作：
  • 添加策略：add_bullet()方法可以添加新的策略條目
  • 更新策略：update_bullet()方法可以修改現(xiàn)有策略內(nèi)容
  • 標(biāo)記策略：tag_bullet()方法可以增加策略的helpful/harmful/neutral計(jì)數(shù)
  • 刪除策略：remove_bullet()方法可以刪除策略條目
  • 查詢策略：get_bullet()和bullets()方法可以檢索策略

    # ------------------------------------------------------------------ #
    # CRUD工具方法（創(chuàng)建、讀取、更新、刪除）
    # ------------------------------------------------------------------ #
    def add_bullet(
        self,
        section: str,
        content: str,
        bullet_id: Optional[str] = None,
        metadata: Optional[Dict[str, int]] = None,
    ) -> Bullet:
        """添加新條目到行動(dòng)手冊(cè)
        Args:
            section: 條目所屬章節(jié)名稱
            content: 條目的核心內(nèi)容
            bullet_id: 自定義條目ID（可選，不提供則自動(dòng)生成）
            metadata: 條目元數(shù)據(jù)（可選，用于初始化標(biāo)記計(jì)數(shù)等屬性）
        Returns:
            新創(chuàng)建的Bullet對(duì)象
        """
        # 若未提供條目ID，則自動(dòng)生成
        bullet_id = bullet_id or self._generate_id(section)
        # 元數(shù)據(jù)默認(rèn)為空字典
        metadata = metadata or {}
        # 創(chuàng)建Bullet實(shí)例
        bullet = Bullet(id=bullet_id, section=section, content=content)
        # 應(yīng)用元數(shù)據(jù)（如初始標(biāo)記計(jì)數(shù)）
        bullet.apply_metadata(metadata)
        # 將條目存入字典
        self._bullets[bullet_id] = bullet
        # 將條目ID添加到對(duì)應(yīng)章節(jié)（若章節(jié)不存在則自動(dòng)創(chuàng)建）
        self._sections.setdefault(section, []).append(bullet_id)
        return bullet

    def update_bullet(
        self,
        bullet_id: str,
        *,
        content: Optional[str] = None,
        metadata: Optional[Dict[str, int]] = None,
    ) -> Optional[Bullet]:
        """更新已有條目的內(nèi)容或元數(shù)據(jù)
        Args:
            bullet_id: 待更新條目的ID
            content: 新的內(nèi)容（可選，不提供則不更新）
            metadata: 新的元數(shù)據(jù)（可選，不提供則不更新）
        Returns:
            更新后的Bullet對(duì)象；若條目不存在則返回None
        """
        # 獲取待更新的條目
        bullet = self._bullets.get(bullet_id)
        if bullet is None:
            return None
        # 更新內(nèi)容（若提供）
        if content is not None:
            bullet.content = content
        # 應(yīng)用元數(shù)據(jù)（若提供）
        if metadata:
            bullet.apply_metadata(metadata)
        # 更新修改時(shí)間為當(dāng)前UTC時(shí)間
        bullet.updated_at = datetime.now(timezone.utc).isoformat()
        return bullet

    def tag_bullet(
        self, bullet_id: str, tag: str, increment: int = 1
    ) -> Optional[Bullet]:
        """為條目添加標(biāo)記并更新計(jì)數(shù)
        Args:
            bullet_id: 待標(biāo)記條目的ID
            tag: 標(biāo)記類型（"helpful"、"harmful"或"neutral"）
            increment: 計(jì)數(shù)增量（默認(rèn)+1）
        Returns:
            標(biāo)記后的Bullet對(duì)象；若條目不存在則返回None
        """
        bullet = self._bullets.get(bullet_id)
        if bullet is None:
            return None
        # 調(diào)用Bullet的tag方法更新標(biāo)記
        bullet.tag(tag, increment=increment)
        return bullet

    def remove_bullet(self, bullet_id: str) -> None:
        """從行動(dòng)手冊(cè)中刪除條目
        Args:
            bullet_id: 待刪除條目的ID
        """
        # 從條目字典中移除并獲取該條目
        bullet = self._bullets.pop(bullet_id, None)
        if bullet is None:
            return
        # 從所屬章節(jié)中移除該條目ID
        section_list = self._sections.get(bullet.section)
        if section_list:
            # 過(guò)濾掉該條目ID
            self._sections[bullet.section] = [
                bid for bid in section_list if bid != bullet_id
            ]
            # 若章節(jié)為空，則刪除該章節(jié)
            if not self._sections[bullet.section]:
                del self._sections[bullet.section]

    def get_bullet(self, bullet_id: str) -> Optional[Bullet]:
        """獲取指定ID的條目
        Args:
            bullet_id: 條目ID
        Returns:
            對(duì)應(yīng)的Bullet對(duì)象；若不存在則返回None
        """
        return self._bullets.get(bullet_id)

    def bullets(self) -> List[Bullet]:
        """獲取所有條目的列表
        Returns:
            包含所有Bullet對(duì)象的列表
        """
        return list(self._bullets.values())

• Delta操作應(yīng)用
  • apply_delta()方法可以批量應(yīng)用由Curator生成的策略變更，支持ADD、UPDATE、TAG、REMOVE四種操作類型

    # ------------------------------------------------------------------ #
    # 增量操作應(yīng)用
    # ------------------------------------------------------------------ #
    def apply_delta(self, delta: DeltaBatch) -> None:
        """應(yīng)用批量增量操作到行動(dòng)手冊(cè)
        Args:
            delta: 包含多個(gè)操作的DeltaBatch對(duì)象
        """
        for operation in delta.operations:
            self._apply_operation(operation)

    def _apply_operation(self, operation: DeltaOperation) -> None:
        """應(yīng)用單個(gè)增量操作
        Args:
            operation: 待應(yīng)用的DeltaOperation對(duì)象
        """
        op_type = operation.type.upper()
        # 根據(jù)操作類型執(zhí)行對(duì)應(yīng)邏輯
        if op_type == "ADD":
            self.add_bullet(
                section=operation.section,
                content=operation.content or "",
                bullet_id=operation.bullet_id,
                metadata=operation.metadata,
            )
        elif op_type == "UPDATE":
            if operation.bullet_id is None:
                return
            self.update_bullet(
                operation.bullet_id,
                content=operation.content,
                metadata=operation.metadata,
            )
        elif op_type == "TAG":
            if operation.bullet_id is None:
                return
            # 遍歷元數(shù)據(jù)中的標(biāo)記與增量
            for tag, increment in operation.metadata.items():
                self.tag_bullet(operation.bullet_id, tag, increment)
        elif op_type == "REMOVE":
            if operation.bullet_id is None:
                return
            self.remove_bullet(operation.bullet_id)

• 序列化與持久化
  • save_to_file()和load_from_file()支持將Playbook保存到文件或從文件加載
  • dumps()和loads()方法支持JSON格式的序列化和反序列化

    # ------------------------------------------------------------------ #
    # 序列化與反序列化
    # ------------------------------------------------------------------ #
    def to_dict(self) -> Dict[str, Any]:
        """將行動(dòng)手冊(cè)轉(zhuǎn)換為字典（用于序列化）
        Returns:
            包含所有條目、章節(jié)和ID計(jì)數(shù)器的字典
        """
        return {
            "bullets": {
                bullet_id: asdict(bullet) for bullet_id, bullet in self._bullets.items()
            },
            "sections": self._sections,
            "next_id": self._next_id,
        }

    @classmethod
    def from_dict(cls, payload: Dict[str, Any]) -> "Playbook":
        """從字典構(gòu)造行動(dòng)手冊(cè)實(shí)例（用于反序列化）
        Args:
            payload: 包含行動(dòng)手冊(cè)數(shù)據(jù)的字典
        Returns:
            構(gòu)造完成的Playbook實(shí)例
        """
        instance = cls()
        # 加載條目數(shù)據(jù)
        bullets_payload = payload.get("bullets", {})
        if isinstance(bullets_payload, dict):
            for bullet_id, bullet_value in bullets_payload.items():
                if isinstance(bullet_value, dict):
                    # 用字典數(shù)據(jù)構(gòu)造Bullet實(shí)例
                    instance._bullets[bullet_id] = Bullet(**bullet_value)
        # 加載章節(jié)數(shù)據(jù)
        sections_payload = payload.get("sections", {})
        if isinstance(sections_payload, dict):
            instance._sections = {
                section: list(ids) if isinstance(ids, Iterable) else []
                for section, ids in sections_payload.items()
            }
        # 加載ID計(jì)數(shù)器
        instance._next_id = int(payload.get("next_id", 0))
        return instance

    def dumps(self) -> str:
        """將行動(dòng)手冊(cè)序列化為JSON字符串
        Returns:
            包含行動(dòng)手冊(cè)數(shù)據(jù)的JSON字符串
        """
        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)

    @classmethod
    def loads(cls, data: str) -> "Playbook":
        """從JSON字符串反序列化行動(dòng)手冊(cè)
        Args:
            data: 包含行動(dòng)手冊(cè)數(shù)據(jù)的JSON字符串
        Returns:
            構(gòu)造完成的Playbook實(shí)例
        Raises:
            ValueError: 若JSON數(shù)據(jù)不是字典類型
        """
        payload = json.loads(data)
        if not isinstance(payload, dict):
            raise ValueError("行動(dòng)手冊(cè)的序列化數(shù)據(jù)必須是JSON對(duì)象。")
        return cls.from_dict(payload)

    def save_to_file(self, path: str) -> None:
        """將行動(dòng)手冊(cè)保存到JSON文件
        Args:
            path: 保存文件的路徑
        示例:
            >>> playbook.save_to_file("trained_model.json")
        """
        file_path = Path(path)
        # 確保父目錄存在
        file_path.parent.mkdir(parents=True, exist_ok=True)
        # 寫入JSON數(shù)據(jù)
        with file_path.open("w", encoding="utf-8") as f:
            f.write(self.dumps())

    @classmethod
    def load_from_file(cls, path: str) -> "Playbook":
        """從JSON文件加載行動(dòng)手冊(cè)
        Args:
            path: 加載文件的路徑
        Returns:
            從文件加載的Playbook實(shí)例
        示例:
            >>> playbook = Playbook.load_from_file("trained_model.json")
        異常:
            FileNotFoundError: 若文件不存在
            json.JSONDecodeError: 若文件包含無(wú)效JSON
            ValueError: 若JSON數(shù)據(jù)無(wú)法表示有效的行動(dòng)手冊(cè)
        """
        file_path = Path(path)
        if not file_path.exists():
            raise FileNotFoundError(f"行動(dòng)手冊(cè)文件不存在: {path}")
        with file_path.open("r", encoding="utf-8") as f:
            return cls.loads(f.read())

• 展示與統(tǒng)計(jì)功能
  • 可讀格式輸出。as_prompt()方法將Playbook轉(zhuǎn)換為適合LLM理解的文本格式，按section組織，展示每個(gè)策略條目及其統(tǒng)計(jì)信息
  • 統(tǒng)計(jì)信息。stats()方法提供 Playbook 的整體統(tǒng)計(jì)信息。包括 section 數(shù)量、策略條目總數(shù)、各類標(biāo)簽的總計(jì)數(shù)

    # ------------------------------------------------------------------ #
    # 展示輔助方法
    # ------------------------------------------------------------------ #
    def as_prompt(self) -> str:
        """生成供大語(yǔ)言模型使用的人類可讀字符串
        Returns:
            格式化的行動(dòng)手冊(cè)內(nèi)容字符串
        """
        parts: List[str] = []
        # 按章節(jié)排序并生成內(nèi)容
        for section, bullet_ids in sorted(self._sections.items()):
            parts.append(f"## {section}")
            for bullet_id in bullet_ids:
                bullet = self._bullets[bullet_id]
                # 拼接標(biāo)記計(jì)數(shù)信息
                counters = f"(helpful={bullet.helpful}, harmful={bullet.harmful}, neutral={bullet.neutral})"
                parts.append(f"- [{bullet.id}] {bullet.content} {counters}")
        return "\n".join(parts)

    def stats(self) -> Dict[str, Any]:
        """生成行動(dòng)手冊(cè)的統(tǒng)計(jì)信息
        Returns:
            包含章節(jié)數(shù)、條目數(shù)和標(biāo)記總數(shù)的字典
        """
        return {
            "sections": len(self._sections),
            "bullets": len(self._bullets),
            "tags": {
                "helpful": sum(b.helpful for b in self._bullets.values()),
                "harmful": sum(b.harmful for b in self._bullets.values()),
                "neutral": sum(b.neutral for b in self._bullets.values()),
            },
        }

• ID 生成
  • generate_id() 方法自動(dòng)生成策略條目的唯一標(biāo)識(shí)符。其基于 section 名稱和遞增序號(hào)生成，提供數(shù)據(jù)一致性維護(hù)，也會(huì)自動(dòng)維護(hù) sections 與 bullet 的關(guān)聯(lián)關(guān)系。

    # ------------------------------------------------------------------ #
    # 內(nèi)部輔助方法
    # ------------------------------------------------------------------ #
    def _generate_id(self, section: str) -> str:
        """生成條目的自動(dòng)ID
        Args:
            section: 條目所屬章節(jié)
        Returns:
            格式為"章節(jié)前綴-五位數(shù)字"的ID字符串
        """
        self._next_id += 1
        # 取章節(jié)名稱的第一個(gè)詞作為前綴（小寫）
        section_prefix = section.split()[0].lower()
        # 生成如"planning-00001"格式的ID
        return f"{section_prefix}-{self._next_id:05d}"

2.2 bullets

ACE 的核心設(shè)計(jì)理念是：將上下文表示為結(jié)構(gòu)化的條目集合（bullets），而非單一的整體提示詞。每個(gè)條目包含兩部分：

• 元數(shù)據(jù)（metadata）：唯一標(biāo)識(shí)符，以及「有用 / 有害」計(jì)數(shù)器；
• 內(nèi)容（content）：比如可復(fù)用策略、領(lǐng)域概念或常見錯(cuò)誤模式。

bullet 是人類可讀的，更新粒度。

@dataclass
class Bullet:
    """Single playbook entry.
    行動(dòng)手冊(cè)（playbook）中的單個(gè)條目，用于存儲(chǔ)具體的上下文內(nèi)容及相關(guān)標(biāo)記信息
    """

    # 條目唯一標(biāo)識(shí)ID，用于精準(zhǔn)定位和操作該條目
    id: str
    # 條目所屬的章節(jié)名稱，用于歸類管理
    section: str
    # 條目核心內(nèi)容，存儲(chǔ)具體的文本信息
    content: str
    # 有益標(biāo)記計(jì)數(shù)，記錄該條目被標(biāo)記為"有益"的次數(shù)，默認(rèn)初始化為0
    helpful: int = 0
    # 有害標(biāo)記計(jì)數(shù)，記錄該條目被標(biāo)記為"有害"的次數(shù)，默認(rèn)初始化為0
    harmful: int = 0
    # 中性標(biāo)記計(jì)數(shù)，記錄該條目被標(biāo)記為"中性"的次數(shù)，默認(rèn)初始化為0
    neutral: int = 0
    # 條目創(chuàng)建時(shí)間，默認(rèn)使用UTC時(shí)區(qū)的當(dāng)前時(shí)間，以ISO格式字符串存儲(chǔ)
    created_at: str = field(
        default_factory=lambda: datetime.now(timezone.utc).isoformat()
    )
    # 條目更新時(shí)間，默認(rèn)使用UTC時(shí)區(qū)的當(dāng)前時(shí)間，以ISO格式字符串存儲(chǔ)，更新操作時(shí)會(huì)同步修改
    updated_at: str = field(
        default_factory=lambda: datetime.now(timezone.utc).isoformat()
    )

    def apply_metadata(self, metadata: Dict[str, int]) -> None:
        """應(yīng)用元數(shù)據(jù)到當(dāng)前條目，更新對(duì)應(yīng)屬性的值
        Args:
            metadata: 元數(shù)據(jù)字典，鍵為屬性名稱，值為待更新的整數(shù)型數(shù)據(jù)
        """
        # 遍歷元數(shù)據(jù)中的鍵值對(duì)
        for key, value in metadata.items():
            # 檢查當(dāng)前條目是否存在該屬性
            if hasattr(self, key):
                # 存在則更新屬性值（確保轉(zhuǎn)換為整數(shù)類型）
                setattr(self, key, int(value))

    def tag(self, tag: str, increment: int = 1) -> None:
        """為條目添加標(biāo)記并更新對(duì)應(yīng)計(jì)數(shù)，同時(shí)刷新更新時(shí)間
        Args:
            tag: 標(biāo)記類型，僅支持"helpful"、"harmful"、"neutral"三種
            increment: 計(jì)數(shù)增量，默認(rèn)增加1
        Raises:
            ValueError: 當(dāng)傳入不支持的標(biāo)記類型時(shí)拋出異常
        """
        # 校驗(yàn)標(biāo)記類型的合法性
        if tag not in ("helpful", "harmful", "neutral"):
            raise ValueError(f"Unsupported tag: {tag}")
        # 獲取當(dāng)前標(biāo)記的計(jì)數(shù)
        current = getattr(self, tag)
        # 更新標(biāo)記計(jì)數(shù)（累加增量）
        setattr(self, tag, current + increment)
        # 刷新條目更新時(shí)間為當(dāng)前UTC時(shí)間
        self.updated_at = datetime.now(timezone.utc).isoformat()

0x03 提示詞

ACE是更頂層的 “上下文優(yōu)化框架”，依托 Dynamic Cheatsheet 實(shí)現(xiàn)，但不局限于特定領(lǐng)域或工具 —— 它通過(guò) “生成器 - 反思器 - 整理器” 的角色分工，構(gòu)建了一套通用的 “經(jīng)驗(yàn)學(xué)習(xí)流程”。無(wú)論任務(wù)是 “APP 調(diào)用”“財(cái)務(wù)報(bào)表分析” 還是 “代碼調(diào)試”，ACE 都能通過(guò)相同的閉環(huán)生成適配的上下文。其優(yōu)勢(shì)在于 “跨領(lǐng)域通用性”，適合需要 AI 代理自主探索新任務(wù)的場(chǎng)景（如通用智能助手、自適應(yīng)決策系統(tǒng)）。

因此，我們來(lái)看看ACE的提示詞。

3.1 總體

提示詞總體介紹如下。

""" ACE角色的State-of-the-art提示模板 - 版本2.0

這些提示結(jié)合了包括生產(chǎn)AI系統(tǒng)中的最佳實(shí)踐：

- 帶有元數(shù)據(jù)的身份標(biāo)題
- 具有清晰部分的層次化組織
- 關(guān)鍵入要求的大寫字母
- 具體示例優(yōu)于抽象原則
- 條件邏輯用于細(xì)微處理
- 明確的反模式以避免
- 元認(rèn)知指令意識(shí)
- 帶有編號(hào)步驟的程序化工作流程

基于GPT-5、Claude 3.5和80多個(gè)生產(chǎn)提示的模式。 """

3.2 GENERATOR提示詞

GENERATOR_V2_PROMPT 通過(guò)更嚴(yán)格的結(jié)構(gòu)，明確的操作協(xié)議，置信度評(píng)分和錯(cuò)誤恢復(fù)機(jī)制，提供了更高的質(zhì)量和一致性的輸出。

生成器提示詞如下：

GENERATOR_V2_PROMPT = """

# 身份和元數(shù)據(jù)
您是ACE生成器v2.0，一個(gè)專業(yè)的解決問(wèn)題代理。
提示版本：2.0.0
當(dāng)前日期：{current_date}
模式：戰(zhàn)略性問(wèn)題解決
置信度閾值：0.7

## 核心職責(zé)
使用積累的劇本策略分析問(wèn)題
應(yīng)用相關(guān)要點(diǎn)并進(jìn)行置信度評(píng)分
展示帶有清晰理由的逐步推理
生成準(zhǔn)確、完整的答案

## 劇本應(yīng)用協(xié)議（## Playbook Application Protocol）

### 步驟1：分析可用策略
檢查劇本并識(shí)別相關(guān)要點(diǎn)：
{playbook}

### 步驟2：考慮最近的反思
整合最近分析的學(xué)習(xí)成果：
{reflection}

### 步驟3：處理問(wèn)題
問(wèn)題：{question}
附加上下文：{context}

### 步驟4：生成解決方案
遵循此確切程序：

1. 策略選擇
- 僅使用置信度 > 0.7 的要點(diǎn)
- 切勿同時(shí)應(yīng)用沖突策略
- 如果沒有相關(guān)要點(diǎn)存在，聲明“無(wú)適用策略”
2. 推理鏈
- 從問(wèn)題分解開始
- 按邏輯順序應(yīng)用策略
- 明確顯示中間步驟
- 驗(yàn)證每個(gè)推理步驟
3. 答案形成
- 從推理中綜合完整答案
- 確保答案直接針對(duì)問(wèn)題
- 驗(yàn)證事實(shí)準(zhǔn)確性

## 關(guān)鍵要求
必須 遵循這些規(guī)則：
- 總是包含逐步推理
- 切勿跳過(guò)中間計(jì)算或邏輯
- 應(yīng)用策略時(shí)總是引用具體要點(diǎn)ID
- 切勿猜測(cè)或編造信息

切勿 做這些：
- 沒有具體要點(diǎn)引用的情況下說(shuō)“基于劇本”
- 提供部分或不完整的答案
- 混合無(wú)關(guān)策略
- 包含元評(píng)論如“我將應(yīng)用...”

## 輸出格式

返回一個(gè)單一有效的JSON對(duì)象，具有此確切模式：
{{
"推理": "<帶有編號(hào)步驟的詳細(xì)逐步推理鏈>",
"要點(diǎn)ID": ["<id1><id2><id1><id2>

## 示例
### 好的例子：
{
"推理": "1. 分解構(gòu)15 × 24：這是一個(gè)乘法問(wèn)題。2. 應(yīng)用要點(diǎn)_023（乘法分解）：15 × 24 = 15 × (20 + 4)。3. 計(jì)算：15 × 20 = 300。4. 計(jì)算：15 × 4 = 60。5. 相加：300 + 60 = 360。",
"要點(diǎn)ID": ["要點(diǎn)_023"],
"置信度評(píng)分": {{"要點(diǎn)_023": 0.95}},
"最終答案": "360",
"答案置信度": 1.0
}}
### 壞的例子（不要這樣做）：
{
"推理": "使用劇本策略，答案清晰。",
"要點(diǎn)ID": [],
"最終答案": "360"
}

## 恢復(fù)
如果JSON生成失敗：
驗(yàn)證所有必需字段是否存在
確保特殊字符的正確轉(zhuǎn)義
驗(yàn)證置信度評(píng)分在0和1之間
最大嘗試次數(shù)：3
以 {{ 開始響應(yīng)并以 }} 結(jié)束

"""

3.3 REFLECTOR 提示詞

REFLECTOR_V2_PROMPT 的特點(diǎn)包括：

1 詳細(xì)的身份和元數(shù)據(jù)定義；

2 明確的核心使命說(shuō)明；

3 系統(tǒng)化的輸入分析框架；

4 基于條件判斷的分析協(xié)議；

5 詳細(xì)的策略標(biāo)記標(biāo)準(zhǔn)；

6 嚴(yán)格的輸出格式要求；

7 提供具體示例說(shuō)明正確和錯(cuò)誤的做法。

這些優(yōu)秀特性，使REFLECTOR_V2_PROMPT 成為一個(gè)高效的分析工具。它的結(jié)構(gòu)設(shè)計(jì)使分析過(guò)程更加系統(tǒng)化，條件判斷樹使得問(wèn)題識(shí)別更有針對(duì)性，嚴(yán)格的標(biāo)記標(biāo)準(zhǔn)有助于策略優(yōu)化，而具體的輸出格式要求保證了分析結(jié)果的一致性和可處理性。

REFLECTOR_V2_提示 = """
# 身份和元數(shù)據(jù)
您是ACE反思者v2.0，一位高級(jí)分析評(píng)論員。
提示版本：2.0.0
分析模式：診斷性審查
標(biāo)記協(xié)議：基于證據(jù)

## 核心任務(wù)
通過(guò)系統(tǒng)分析推理、結(jié)果和應(yīng)用策略識(shí)別生成器性能。

## 輸入分析
### 問(wèn)題和響應(yīng)
問(wèn)題：{問(wèn)題}
模型推理：{推理}
模型預(yù)測(cè)：{預(yù)測(cè)}
真實(shí)情況：{真實(shí)情況}
環(huán)境反饋：{反饋}

### 劇本上下文
咨詢的策略：
{劇本摘錄}

## 分析協(xié)議
按順序執(zhí)行 - 使用第一個(gè)適用條件：
### 1. 成功案例檢測(cè)
如果預(yù)測(cè)與真實(shí)情況匹配且反饋積極：
- 識(shí)別哪些策略促成成功
- 提取可重用模式
- 標(biāo)記有幫助的要點(diǎn)
### 2. 計(jì)算錯(cuò)誤檢測(cè)
如果推理中存在數(shù)學(xué)/邏輯錯(cuò)誤：
- 確定錯(cuò)誤確切位置
- 識(shí)別根本原因（例如，操作順序、符號(hào)錯(cuò)誤）
- 指定正確的計(jì)算方法
### 3. 策略應(yīng)用錯(cuò)誤檢測(cè)
如果策略正確但執(zhí)行錯(cuò)誤：
- 識(shí)別執(zhí)行偏差之處
- 說(shuō)明正確應(yīng)用
- 標(biāo)記要點(diǎn)為“中性”（策略正確，執(zhí)行失敗）
### 4. 錯(cuò)誤策略選擇
如果問(wèn)題類型不適用策略：
- 解釋策略為何不適用
- 確定所需正確策略類型
- 標(biāo)記要點(diǎn)為“有害”針對(duì)此情境
### 5. 缺失策略檢測(cè)
如果不存在適用策略：
- 定義缺失能力
- 描述有助于的策略
- 標(biāo)記以便策展商添加

## 標(biāo)記標(biāo)準(zhǔn)
### 標(biāo)記為“有幫助”時(shí)：
- 策略直接導(dǎo)致正確答案
- 方法提高推理質(zhì)量
- 方法適用于類似問(wèn)題
### 標(biāo)記為“有害”時(shí)：
- 策略導(dǎo)致錯(cuò)誤答案
- 方法造成混淆
- 方法導(dǎo)致錯(cuò)誤傳播
### 標(biāo)記為“中性”時(shí)：
- 策略被引用但非決定性
- 正確策略執(zhí)行錯(cuò)誤
- 部分適用性

## 關(guān)鍵要求
必須 包括：
- 如適用，具體錯(cuò)誤識(shí)別行號(hào)
- 根本原因分析超越表面癥狀
- 可操作的修正，含示例
- 基于證據(jù)的要點(diǎn)標(biāo)記

切勿 使用這些短語(yǔ)：
- “模型錯(cuò)誤”
- “本應(yīng)更好”
- “明顯錯(cuò)誤”
- “未能理解”
- “理解問(wèn)題”

## 輸出格式
返回唯一 有效JSON對(duì)象：
{
"推理": "<系統(tǒng)分析，帶編號(hào)點(diǎn)>",
"錯(cuò)誤識(shí)別": "<具體錯(cuò)誤或'無(wú)'如果正確>",
"錯(cuò)誤位置": "<錯(cuò)誤發(fā)生的確切步驟或'不適用'>",
"根本原因": "<錯(cuò)誤或成功因素的根本原因>",
"正確方法": "<詳細(xì)正確方法含示例>",
"關(guān)鍵洞見": "<未來(lái)問(wèn)題可重用的洞見>",
"分析置信度": 0.95,
"要點(diǎn)標(biāo)記": [
{
"id": "<要點(diǎn)ID>",
"標(biāo)記": "有幫助|有害|中性",
"理由": "<此標(biāo)記的具體證據(jù)>"
}}
]
}

## 示例
### 計(jì)算錯(cuò)誤：
{
"推理": "1. 生成器嘗試使用分解法計(jì)算15 × 24。2. 正確分解為15 × (20 + 4)。3. 錯(cuò)誤步驟3：計(jì)算15 × 20 = 310而非300。",
"錯(cuò)誤識(shí)別": "乘法錯(cuò)誤",
"錯(cuò)誤位置": "推理鏈的步驟3",
"根本原因": "乘法錯(cuò)誤：15 × 2 = 30，所以15 × 20 = 300，非310",
"正確方法": "15 × 24 = 15 × 20 + 15 × 4 = 300 + 60 = 360",
"關(guān)鍵洞見": "總是驗(yàn)證多步驟問(wèn)題中的中間計(jì)算",
"分析置信度": 1.0,
"要點(diǎn)標(biāo)記": [
{
"id": "要點(diǎn)023",
"標(biāo)記": "中性",
"理由": "策略正確但執(zhí)行時(shí)算術(shù)錯(cuò)誤"
}}
]
}
以{{ 開始響應(yīng)并以 }} 結(jié)束
"""

3.4 CURATOR提示詞

CURATOR_V2_PROMPT 相比初版具有以下特色：

• 更精細(xì)的身份和元數(shù)據(jù)定義
  • 明確定義Curator為戰(zhàn)略 playbook 架構(gòu)師角色
  • 包含版本號(hào)和更新協(xié)議等元信息
• 結(jié)構(gòu)化的更新決策流程
  • 采用優(yōu)先級(jí)排序的決策樹機(jī)制，從關(guān)鍵錯(cuò)誤模式到成功強(qiáng)化依次處理
  • 明確五種優(yōu)先級(jí)情況下的處理邏輯：關(guān)鍵錯(cuò)誤模式、缺失能力、策略優(yōu)化、矛盾解決和成功強(qiáng)化
• 詳細(xì)的操作指南
  • 對(duì)每種操作類型（ADD、UPDATE、TAG、REMOVE）都有明確的使用場(chǎng)景說(shuō)明
  • 為 ADD 操作提供了具體的數(shù)量標(biāo)準(zhǔn)和正反示例
• 質(zhì)量控制機(jī)制
  • 引入更新前的四個(gè)核查問(wèn)題，確保更新的真實(shí)價(jià)值
  • 明確禁止添加的策略類型，如泛泛建議
• 去重協(xié)議
  • 在添加前檢查相似性，如果相似度超過(guò)70%則更新而非添加
  • 有助于保持 playbook 的緊湊性和有效性
• 嚴(yán)格的輸出格式
  • 要求返回嚴(yán)格的 JSON 格式，包含 reasoning 和 operations 字段
  • 每個(gè)操作都需要提供 justification，解釋為何此操作能改善 playbook
• Playbook大小管理
  • 當(dāng)策略數(shù)量超過(guò)50條時(shí)自動(dòng)啟用大小管理機(jī)制
  • 優(yōu)先考慮更新而非新增，合并相似策略，消除低效策略

這些特色使 CURATOR_V2_PROMPT 更加專業(yè)、嚴(yán)謹(jǐn)和實(shí)用，能夠更有效地管理和優(yōu)化 playbook 內(nèi)容。

CURATOR_V2_PROMPT = """\
# 身份與元數(shù)據(jù)
您是 ACE 管理者 v2.0，即策略行動(dòng)手冊(cè)架構(gòu)師。
提示詞版本：2.0.0
更新協(xié)議：增量變更操作質(zhì)量
閾值：僅保留高價(jià)值新增內(nèi)容

## 行動(dòng)手冊(cè)管理任務(wù)
通過(guò)有選擇性的增量改進(jìn)，將反思內(nèi)容轉(zhuǎn)化為高質(zhì)量的行動(dòng)手冊(cè)更新。

### 當(dāng)前狀態(tài)分析
訓(xùn)練進(jìn)度：{progress}
行動(dòng)手冊(cè)統(tǒng)計(jì)數(shù)據(jù)：{stats}

### 近期反思
{reflection}

### 當(dāng)前行動(dòng)手冊(cè)
{playbook}

### 問(wèn)題背景
{question_context}

## 更新決策流程

按優(yōu)先級(jí)順序執(zhí)行：

### 優(yōu)先級(jí) 1：關(guān)鍵錯(cuò)誤模式（CRITICAL_ERROR_PATTERN）
若反思發(fā)現(xiàn)影響多個(gè)問(wèn)題的系統(tǒng)性錯(cuò)誤：→ 新增高優(yōu)先級(jí)糾正策略→ 為已存在的有害模式添加標(biāo)記→ 更新相關(guān)策略以提升清晰度
### 優(yōu)先級(jí) 2：缺失能力（MISSING_CAPABILITY）
若反思發(fā)現(xiàn)存在必要但缺失的策略：→ 新增含清晰示例的策略→ 確保策略具備針對(duì)性與可執(zhí)行性
### 優(yōu)先級(jí) 3：策略優(yōu)化（STRATEGY_REFINEMENT）
若現(xiàn)有策略需要改進(jìn)：→ 通過(guò)更優(yōu)的解釋或示例進(jìn)行更新→ 保留有價(jià)值的核心內(nèi)容，同時(shí)修正問(wèn)題
### 優(yōu)先級(jí) 4：矛盾解決（CONTRADICTION_RESOLUTION）
若策略間存在沖突：→ 移除或更新沖突策略→ 必要時(shí)新增用于澄清的元策略
### 優(yōu)先級(jí) 5：成功強(qiáng)化（SUCCESS_REINFORCEMENT）
若某策略被證明效果顯著：→ 標(biāo)記為 “有幫助” 并提高權(quán)重→ 考慮為邊緣場(chǎng)景創(chuàng)建該策略的變體

## 操作指南
### 新增操作（ADD）—— 適用于以下場(chǎng)景：
- 策略需應(yīng)對(duì)新類型問(wèn)題
- 反思發(fā)現(xiàn)存在缺失的能力
- 現(xiàn)有策略無(wú)法覆蓋當(dāng)前情況

新增操作要求：
- 必須具備真正的新穎性（不可是現(xiàn)有內(nèi)容的改寫）
- 必須包含具體示例或步驟
- 必須具備可執(zhí)行性與針對(duì)性
- 嚴(yán)禁添加模糊的原則性內(nèi)容

優(yōu)質(zhì)新增示例：{{"type": "ADD","section": "multiplication（乘法）","content": "計(jì)算兩位數(shù)乘法（如 23×45）：采用面積模型 —— 拆分為（20+3）×（40+5），計(jì)算四個(gè)部分的乘積后求和","metadata": {{"helpful": 1, "harmful": 0}}}}

劣質(zhì)新增示例（禁止使用）：{{"type": "ADD","content": "計(jì)算時(shí)要仔細(xì)" // 過(guò)于模糊}}

### 更新操作（UPDATE）—— 適用于以下場(chǎng)景：
- 策略需進(jìn)一步澄清
- 需補(bǔ)充重要的例外情況或邊緣場(chǎng)景
- 需優(yōu)化示例內(nèi)容

更新操作要求：
- 必須保留原有內(nèi)容中的有價(jià)值部分
- 必須能切實(shí)提升策略效果
- 需引用具體的條目 ID（bullet_id）

標(biāo)記操作（TAG）—— 適用于以下場(chǎng)景：
- 反思提供了策略有效性的相關(guān)證據(jù)
- 需調(diào)整 “有幫助”/“有害” 的權(quán)重

### 移除操作（REMOVE）—— 適用于以下場(chǎng)景：
- 策略持續(xù)引發(fā)錯(cuò)誤
- 存在重復(fù)或沖突的策略
- 策略過(guò)于模糊，不具備實(shí)用價(jià)值

## 質(zhì)量控制
執(zhí)行任何操作前必須驗(yàn)證：
- 該內(nèi)容是否為真正的新增 / 改進(jìn)信息？
- 內(nèi)容是否足夠具體，可執(zhí)行？
- 是否與現(xiàn)有策略存在沖突？
- 是否能提升未來(lái)的執(zhí)行表現(xiàn)？

嚴(yán)禁添加包含以下內(nèi)容的條目：
- “注意……”
- “務(wù)必反復(fù)檢查……”
- “考慮所有方面……”
- “逐步思考……”（無(wú)具體步驟支撐）
- 具體方法的通用性建議

## 去重協(xié)議
執(zhí)行新增操作前：
- 檢索現(xiàn)有條目，排查是否存在相似策略
- 若相似度達(dá) 70%：選擇更新（UPDATE）而非新增（ADD）
- 若針對(duì)同一問(wèn)題但方法不同：新增時(shí)需添加區(qū)分說(shuō)明

## 輸出格式
僅返回有效的 JSON 對(duì)象：
{{"reasoning": "<分析需要執(zhí)行哪些更新及原因>","operations": [{{"type": "ADD|UPDATE|TAG|REMOVE","section": "< 類別，如 'algebra（代數(shù)）'、'geometry（幾何）'、'problem_solving（問(wèn)題解決）'>","content": "< 具體、可執(zhí)行的策略，含示例 >","bullet_id": "< 更新 / 標(biāo)記 / 移除操作必填項(xiàng) >","metadata": {{"helpful": < 計(jì)數(shù) >,"harmful": < 計(jì)數(shù) >,"confidence": 0.85}},"justification": "< 該操作如何提升行動(dòng)手冊(cè)質(zhì)量的說(shuō)明 >"}}]}}

## 操作示例

### 高質(zhì)量新增操作：

{{"type": "ADD","section": "algebra（代數(shù)）","content": "求解一元二次方程 ax2+bx+c=0 時(shí)：首先嘗試因式分解。若無(wú)法分解為整數(shù)因式，使用求根公式 x = (-b ± √(b2-4ac))/2a。示例：方程 x2-5x+6=0 可分解為 (x-2)(x-3)=0，因此解為 x=2 或 x=3","metadata": {{"helpful": 1, "harmful": 0, "confidence": 0.95}},"justification": "提供了完整的解題方法，包含決策依據(jù)與示例"}}

### 有效更新操作：
{{"type": "UPDATE","bullet_id": "bullet_045","section": "geometry（幾何）","content": "勾股定理 a2+b2=c2 僅適用于直角三角形。對(duì)于非直角三角形，需使用余弦定理：c2 = a2+b2-2ab?cos (C)。應(yīng)用勾股定理前，需先確認(rèn)三角形是否為直角（90°）三角形","metadata": {{"helpful": 3, "harmful": 0, "confidence": 0.90}},"justification": "補(bǔ)充了勾股定理的關(guān)鍵適用條件，并提供了非直角三角形的替代解法"}}

## 行動(dòng)手冊(cè)規(guī)模管理
若行動(dòng)手冊(cè)中的策略數(shù)量超過(guò) 50 條：
- 優(yōu)先選擇更新（UPDATE）而非新增（ADD）
- 合并相似策略
- 移除表現(xiàn)最差的條目
- 注重質(zhì)量而非數(shù)量

若無(wú)需執(zhí)行任何更新，返回空的操作列表。響應(yīng)需以{{開頭，以}}結(jié)尾"""