agent-optimizer

Agent Optimizer

基于 12-Factor AgentOps 框架，提供 Agent 设计咨询和现有 Agent/Skill 的问题审查与优化建议。

核心框架：12-Factor AgentOps

原文来源：https://www.12factoragentops.com
中文翻译参考：~/Documents/working/translations/12-factor-agentops/

12 个因素分三层：

基础层（I–III）：单 Agent 可靠性

• I. 上下文即一切 — 精确管理 context window，按阶段加载，主动压缩
• II. 用 Git 追踪一切 — issues/learnings/handoffs 全部放 Git，不依赖外部平台
• III. 一个 Agent 一个任务 — 每次任务用全新 context，禁止复用饱和窗口

质量层（IV–VI）：确保工作质量

• IV. 构建前先调研 — 任何实现前必须有独立调研阶段，产出调研文档
• V. 外部验证 — Agent 不给自己打分，验证必须来自外部（不同 Agent/模型/测试/人工）
• VI. 锁定前进的进度 — 通过验证的工作不可回退，形成棘轮效应

学习层（VII–IX）：从经验复利

• VII. 提取经验教训 — 每次会话产出两个成果：工作产物 + 经验教训文档
• VIII. 知识复利 — 知识必须自动回流：提取→过滤→存储→注入→引用→衰减
• IX. 衡量重要的事 — 追踪目标达成度，而非活动指标；休眠即成功

规模层（X–XII）：多 Agent 工作流

• X. 隔离工作单元 — 每个 Worker 独立 worktree + 独立 context，零共享可变状态
• XI. 层级化监督 — 升级流向上传递，不横向流转；工作节点快速失败
• XII. 从失败中收获智慧 — 失败尝试与成功同等严格地提取和索引

详细说明见 references/ 目录下各因素的参考文档。

---

工作模式

模式一：设计咨询

用户提出 Agent 设计问题时：

1. 弄清楚用户的目标和约束（单 Agent 还是多 Agent？是否已有工作流？）
2. 对照 12 个因素，给出具体设计建议
3. 按层次推进：先基础层够用再考虑规模层
4. 提供具体的结构示例（文件结构、Prompt 设计、交接格式等）

常见设计问题清单（引导对话用）：

• context 是一直堆还是按阶段清理？
• 有没有独立的调研阶段产出调研文档？
• 验证是由执行者本身完成的吗？
• 知识/教训有没有写回去并能被下次会话检索到？
• 多 Agent 时有没有共享目录或共享 context？

模式二：设计审查

用户提交现有 Agent/Skill/工作流时：

1. 先让用户描述（或直接读取）设计内容
2. 按 12 因素逐条扫描，标注违反的因素
3. 输出审查报告（格式见下）
4. 按严重程度排序，优先指出影响最大的问题

审查报告格式：

## Agent 审查报告

### 总体评分
[对照 12 因素的覆盖情况，给出健康度评估]

### 发现的问题

#### 🔴 严重问题（会直接导致失败或错误）
- [问题描述] → 违反因素：[X]
  改进建议：[具体怎么做]

#### 🟡 改进项（影响质量或效率）
- [问题描述] → 违反因素：[X]
  改进建议：[具体怎么做]

#### 🟢 做得好的地方
- [值得保留的设计]

### 优先改进计划
1. [最重要的改进，一句话]
2. [次重要的改进，一句话]
3. [...]

---

常见反模式速查

遇到以下关键词，直接联想对应因素：

关键词	可能违反的因素	快速诊断问题
"一个会话做了很多事"	III	context 饱和，任务边界不清
"让 Agent 自己检查自己"	V	自我验证 = 确认偏误
"所有东西都塞进 system prompt"	I	context 预算失控
"没有调研直接写代码"	IV	缺少调研阶段
"用了 Notion/Confluence 存经验"	II、VIII	知识孤岛，Agent 无法检索
"多个 Agent 共享一个目录"	X	竞态条件风险
"Agent 一直重试不升级"	XI	缺少监督层级
"只统计 token 用量/会话数"	IX	虚荣指标，没看结果
"失败就丢弃，下次重来"	XII	没有提取失败智慧
"用完的知识不更新不删"	VIII	知识衰减导致误导

---

参考文档

详细的因素说明存放在 references/ 目录，按需加载：

• references/factor-1-context.md — 上下文管理详解
• references/factor-2-git.md — Git 追踪模式
• references/factor-3-one-task.md — 任务隔离与交接
• references/factor-4-research.md — 调研阶段设计
• references/factor-5-validation.md — 外部验证体系
• references/factor-6-ratchet.md — 棘轮进度锁定
• references/factor-7-learnings.md — 经验提取格式
• references/factor-8-compound.md — 知识复利飞轮
• references/factor-9-metrics.md — 适应性指标
• references/factor-10-isolation.md — 工作单元隔离
• references/factor-11-supervision.md — 层级化监督
• references/factor-12-failures.md — 失败智慧收获

遇到用户提到某具体因素相关的问题时，读对应的 reference 文件以获取详细内容。