{"id":"72fb205b-f4ae-4b04-a118-2b7344d63992","entityType":"agent","slug":"clawhub-tuobadaidai-agent-optimization-expert","name":"Agent优化专家","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tuobadaidai-agent-optimization-expert","canonicalPath":"/agent/clawhub-tuobadaidai-agent-optimization-expert","generatedAt":"2026-10-10T21:42:16.850Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":null},"description":"Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因... Skill: Agent优化专家 Owner: tuobadaidai Summary: Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因... Tags: agent:1.4.0, cron:1.4.0, diagnostics:1.4.0, hermes:1.4.0, latest:1.4.0, openclaw:1.4.0, self-evolution:1.4.0, self-healing:1.4.0 Version history: v1.0.1 | 2026-07-24T09:16:09.888Z | user Restore from backup -","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171s30jbmhtrc2kxbr4hxmyn583gsk3:agent-optimization-expert","sourceUrl":"https://clawhub.ai/tuobadaidai/agent-optimization-expert","homepage":"https://clawhub.ai/tuobadaidai/skills/agent-optimization-expert","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tuobadaidai/agent-optimization-expert","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tuobadaidai/skills/agent-optimization-expert","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":null},"stars":null,"forks":null,"downloads":1305,"packageName":null,"latestVersion":"1.0.1","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T18:02:37.839Z","lastCrawledAt":"2026-10-10T18:02:37.839Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T18:02:37.839Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.1","createdAt":"2026-07-24T09:16:09.888Z","changelog":"Restore from backup - full files recovery","fileCount":11,"zipByteSize":44317},{"version":"1.4.0","createdAt":"2026-05-20T01:55:22.082Z","changelog":"v1.4: 首次运行协议 - 安装后首次加载自动执行 Smoke Test 自检，给用户即时反馈","fileCount":10,"zipByteSize":18026},{"version":"1.3.0","createdAt":"2026-05-20T01:52:34.169Z","changelog":"v1.3: 双环境适配 - 兼容 OpenClaw + Hermes，环境自动检测、双路径命令映射、HEARTBEAT.md 与 Cron Job 双触发机制","fileCount":9,"zipByteSize":16282},{"version":"1.2.0","createdAt":"2026-05-18T04:19:54.799Z","changelog":"agent-optimization-expert 1.2.0 - 全面扩展文档，详细描述了「检测→诊断→修复→验证→学习→进化」闭环及使用场景。 - 增加具体操作方法、常见修复规则，覆盖 Cron、工具调用、子 Agent 与系统健康等细项。 - 明确自愈与进化流程，包括自动分类、模板沉淀、知识收集与版本管理。 - 新增操作分级与安全策略，防止高风险动作自动执行。 - 标准化日志格式，并强化与参考资料的联动与自我进化机制说明。","fileCount":8,"zipByteSize":14942}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171s30jbmhtrc2kxbr4hxmyn583gsk3:agent-optimization-expert","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:42:16.848Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tuobadaidai-agent-optimization-expert/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":null},"readme":"Skill: Agent优化专家\n\nOwner: tuobadaidai\n\nSummary: Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因...\n\nTags: agent:1.4.0, cron:1.4.0, diagnostics:1.4.0, hermes:1.4.0, latest:1.4.0, openclaw:1.4.0, self-evolution:1.4.0, self-healing:1.4.0\n\nVersion history:\n\nv1.0.1 | 2026-07-24T09:16:09.888Z | user\n\nRestore from backup - full files recovery\n\nv1.4.0 | 2026-05-20T01:55:22.082Z | user\n\nv1.4: 首次运行协议 - 安装后首次加载自动执行 Smoke Test 自检，给用户即时反馈\n\nv1.3.0 | 2026-05-20T01:52:34.169Z | user\n\nv1.3: 双环境适配 - 兼容 OpenClaw + Hermes，环境自动检测、双路径命令映射、HEARTBEAT.md 与 Cron Job 双触发机制\n\nv1.2.0 | 2026-05-18T04:19:54.799Z | auto\n\nagent-optimization-expert 1.2.0\n\n- 全面扩展文档，详细描述了「检测→诊断→修复→验证→学习→进化」闭环及使用场景。\n- 增加具体操作方法、常见修复规则，覆盖 Cron、工具调用、子 Agent 与系统健康等细项。\n- 明确自愈与进化流程，包括自动分类、模板沉淀、知识收集与版本管理。\n- 新增操作分级与安全策略，防止高风险动作自动执行。\n- 标准化日志格式，并强化与参考资料的联动与自我进化机制说明。\n\nArchive index:\n\nArchive v1.0.1: 11 files, 44317 bytes\n\nFiles: references/advanced-optimization.md (4477b), references/anthropic-patterns-advanced.md (24176b), references/anthropic-patterns.md (9700b), references/error-taxonomy.md (5651b), references/fix-templates.md (4495b), references/openai-patterns.md (20111b), references/self-evolution.md (3024b), skill-card.md (2545b), SKILL.md (13270b), TRIGGER-INTEGRATION.md (1726b), _meta.json (144b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: agent-optimization-expert\ndescription: Agent 优化专家 — 自动诊断和修复 OpenClaw 执行问题（Cron 失败、工具报错、工作流中断、性能退化），自带持续自我进化能力。\n Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、诊断失败原因、修复任务失败、优化师自我更新、Agent优化.\n 不适用于业务逻辑问题排查、飞书内容编辑、数据查询类任务.\n---\n\n# Agent 优化专家\n\n## 概述\n\n基于 Anthropic / OpenAI 工程实践的 Agent 自愈引擎，覆盖「检测 → 诊断 → 修复 → 验证 → 学习 → 进化」闭环。\n\n### 功能范围\n\n- Cron 任务诊断与修复（失败/超时/disabled/配置错误）\n- 工具调用异常诊断（认证/权限/限流/超时/参数）\n- 子 Agent 异常诊断（spawn 失败/超时/上下文过大）\n- 系统健康度巡检（资源/网络/磁盘/内存）\n- **自我进化**：定期收集工程实践、更新 references/、沉淀新模式\n- 错误模式学习与沉淀（learnings/error-log.md → fix-templates.md 自动升级）\n\n---\n\n## 使用\n\n### 场景 1：Cron 任务执行失败\n\n```bash\n# Step 1 — 快速扫描\nopenclaw cron list --includeDisabled\n\n# Step 2 — 定位失败 job，查看 runs 历史\nopenclaw cron runs \n\n# Step 3 — 常见修复（参照 references/fix-templates.md）\n# A. sessionTarget/payload 不匹配\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"}.\",\"sessionTarget\":\"main\"}'\n\n# B. 超时 → 增大 timeoutSeconds\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n\n# C. disabled → 重新启用\nopenclaw cron update --patch '{\"enabled\":true}'\n\n# Step 4 — 验证\nopenclaw cron runs --limit 1\n```\n\n**修复规则**：\n- `sessionTarget=\"main\"` → `payload.kind` 必须是 `\"systemEvent\"`\n- `sessionTarget=\"isolated\"/\"current\"` → `payload.kind` 必须是 `\"agentTurn\"`\n- 超时问题先尝试 `timeoutSeconds` 加倍，若仍超时则拆分 payload 逻辑\n\n### 场景 2：工具调用连续失败\n\n```bash\n# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限\necho $API_KEY | wc -c # 检查 key 是否存在\n\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)\n```\n\n### 场景 3：系统健康度巡检\n\n```bash\n# 资源检查\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# OpenClaw 状态\nopenclaw status\n```\n\n### 场景 4：子 Agent 异常\n\n```bash\n# 检查活跃子 Agent\nopenclaw subagents list --recentMinutes 60\n\n# 终止卡死的\nopenclaw subagents kill \n\n# 重新生成时的优化选择\n# - 轻量任务: lightContext=true\n# - 不需要当前上下文: context=\"isolated\"\n# - 需要上下文: context=\"fork\"\n# - 长任务: runTimeoutSeconds=600\n```\n\n---\n\n## 诊断决策树\n\n遇到问题时，按以下路径快速定位：\n\n```\n问题出现\n│\n├─ Cron 相关？\n│ ├─ 任务未执行 → 检查 enabled / schedule 表达式 / timezone\n│ ├─ 执行报错 → 检查 runs 历史 → 对照 fix-templates.md\n│ └─ 超时 → 增加 timeoutSeconds 或拆分逻辑\n│\n├─ 工具调用相关？\n│ ├─ 401/403 → 检查认证/权限（feishu_app_scopes / 环境变量）\n│ ├─ 429 → 指数退避重试（1s→2s→4s）\n│ ├─ 5xx → 等待重试，记录日志\n│ └─ 连接超时 → 检查网络 → 降级到备用方案\n│\n├─ 子 Agent 相关？\n│ ├─ spawn 失败 → 检查 task 内容是否过大 / 资源不足\n│ ├─ 超时 → 增加 runTimeoutSeconds 或优化 task\n│ └─ 结果异常 → 检查 context 模式是否正确\n│\n└─ 系统相关？\n ├─ 磁盘满 → 清理 memory/learnings 过期文件 + docker prune\n ├─ 内存不足 → 停止非必要服务 + 使用 lightContext\n └─ 网络断开 → 检查 DNS / 防火墙\n```\n\n## 自愈闭环\n\n```\n检测（心跳/用户反馈/错误日志）\n → 诊断（四层模型：快速扫描 → 错误分析 → 根因推理 → 修复建议）\n → 修复（最小变更 + 可回滚）\n → 验证（修复后确认）\n → 学习（记录到 learnings/error-log.md）\n```\n\n### 错误日志格式（learnings/error-log.md）\n\n```markdown\n## YYYY-MM-DD HH:MM\n- **Error**: [错误描述]\n- **Context**: [触发场景]\n- **Root Cause**: [根因分析]\n- **Fix Applied**: [修复操作]\n- **Prevention**: [避免复现的措施]\n```\n\n## 操作分级与安全\n\n| 级别 | 范围 | 策略 |\n|------|------|------|\n| L0 | 读取状态、检查日志 | 自动执行 |\n| L1 | 清理临时文件、更新日志 | 自动执行 |\n| L2 | 修改 cron 配置、重启服务 | 提示用户确认 |\n| L3 | 修改核心配置、删除数据 | 必须用户明确授权 |\n\n**禁止自动执行**：\n- ❌ 修改 SOUL.md / IDENTITY.md / USER.md\n- ❌ 发送外部消息（邮件/飞书/社交）\n- ❌ 删除不可恢复的数据\n\n## 参考文件\n\n| 文件 | 何时读取 |\n|------|---------|\n| [references/anthropic-patterns.md](references/anthropic-patterns.md) | 需要了解 Thinking/Tool Use/多 Agent 协调模式时（基础模式 §1-9） |\n| [references/anthropic-patterns-advanced.md](references/anthropic-patterns-advanced.md) | 需要了解 Containment/Managed Agents/Harness/Auto Mode/Context Engineering 进阶（高级模式 §10-18） |\n| [references/openai-patterns.md](references/openai-patterns.md) | 需要 ReAct 循环/降级链/评估模式时 |\n| [references/error-taxonomy.md](references/error-taxonomy.md) | 工具调用失败，需要分类诊断时 |\n| [references/fix-templates.md](references/fix-templates.md) | 确认修复方案后，查找具体修复命令时 |\n| [references/self-evolution.md](references/self-evolution.md) | 自我进化任务：收集最新实践、更新 references/ |\n| [references/advanced-optimization.md](references/advanced-optimization.md) | Prompt Caching 优化 + 高效智能体框架综述（记忆/工具/规划） |\n\n## 自我进化机制\n\n优化师不是一次性写好的，它会持续进化。进化分三个路径：\n\n### 路径 1：错误驱动进化（每次诊断后自动触发）\n\n每次修复问题后，检查是否产生新的修复模板或需要更新错误分类：\n\n```\n修复完成\n│\n├─ 这是新错误类型？\n│ ├─ 是 → 新增 error-taxonomy.md 条目 + fix-templates.md 模板\n│ └─ 否 → 更新 error-taxonomy.md 中的复发计数\n│\n├─ 修复方法可复用？\n│ ├─ 是 → 写入 fix-templates.md\n│ └─ 否 → 记录到 learnings/error-log.md\n│\n└─ 涉及工程模式？\n ├─ 是 → 更新对应 references/ 文件\n └─ 否 → 跳过\n```\n\n### 路径 2：定期知识更新（每周 Cron 任务触发）\n\n每周自动执行一次工程实践收集：\n\n1. **搜索最新实践**：用 SearXNG 搜索 Anthropic/OpenAI 最新工程文档\n2. **对比已有内容**：与 references/ 中的内容对比\n3. **提取新模式**：发现新方法时追加到对应 references/ 文件\n4. **清理过时内容**：标记已过时的实践\n5. **更新版本号**：在 SKILL.md 末尾记录最后更新时间和版本号\n\n执行脚本：`references/scripts/self-update.sh`（如果存在）或手动执行：\n\n```bash\n# 搜索 Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+agent+engineering+best+practices+tool+use+patterns+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n\n# 搜索 OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+error+handling+best+practices+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n```\n\n更新规则：\n- **新增模式**：追加到 references/ 对应文件末尾，标注日期\n- **更新模式**：修改现有条目，保留旧内容作为「历史版本」\n- **废弃模式**：标记为「⚠️ 已废弃 - 原因」，不删除\n\n### 路径 3：错误日志驱动进化（每次 error-log.md 更新后检查）\n\n当 learnings/error-log.md 中出现 3 次以上相同错误模式时：\n\n1. 创建或更新 fix-templates.md 中的对应模板\n2. 更新 error-taxonomy.md 中的优先级\n3. 如果是新型错误，新增分类条目\n\n## 主动巡检触发\n\n除问题触发外，以下场景也应主动巡检：\n\n- **每周自检**（HEARTBEAT.md 中配置）：检查 cron 健康度、工具失败回顾\n- **用户反馈响应变慢**：分析 token 使用、session 状态\n- **新服务部署后**：验证服务健康度、更新 TOOLS.md\n- **自我进化周任务**：每周日 03:00 执行工程实践收集\n\n## 版本与更新记录\n\n> 记录优化师自身的迭代历史，便于追踪进化轨迹。\n\n| 版本 | 日期 | 更新内容 |\n|------|------|----------|\n| v1.0 | 2026-05-18 | 初始创建（四层骨架 + 诊断决策树 + 修复模板） |\n| v1.1 | 2026-05-18 | 添加自我进化机制（三条路径：错误驱动/定期知识更新/错误日志驱动） |\n| v1.2 | 2026-05-24 | 新增 MCP 协议集成、Context Engineering、Agent Loop 工程要点、Agent 架构分层、Agent vs Workflow 对比、Agent 核心挑战与应对、工具描述优化、Claude Code 最佳实践 |\n| v1.3 | 2026-05-31 | 新增 Agent Skills 延迟加载模式（含 Toolkits 黑盒 vs Agent Skills 白盒对比）、Agent 范式选型矩阵（ReAct/Plan-and-Execute/Reflection/Multi-Agent/Workflow 场景匹配）、A2A 协议（Agent 间结构化通信）、2026 年 AI Agent 框架全景数据与选型指南 |\n| v1.4 | 2026-06-07 | 新增 Context Engineering 进阶实践（JIT 按需加载、上下文评估指标、Context Rot 腐化机制）、Claude Opus 4.7 SWE-bench 80.9% 里程碑、Qwen3 Think/NoThink 双模式、框架更新（LangGraph v1.0、Microsoft MAF）、GUI 自动化能力评估 |\n| v1.5 | 2026-06-14 | 新增 Prompt Caching 优化实践（Claude 显式缓存/GPT-4o 自动缓存/缓存架构设计/破坏因素）、高效智能体框架综述（上海 AI Lab 等 9 校联合：高效记忆/工具学习/规划三维度优化）、多 Agent 协作效率策略（拓扑效率/协议优化/协同蒸馏） |\n| v1.6 | 2026-06-21 | 新增 CLI vs MCP vs Skill 对比模式（唐巧博客，对 OpenClaw Skills 架构有直接参考价值）、新增 Agent 框架补充（PydanticAI/Mastra/Agno/Camel-AI/Atomic Agents/DSPy）、Agent 范式认知升级（传统程序 vs Agent 本质区别） |\n| v1.7 | 2026-06-28 | 新增 Anthropic Building Effective Agents 7大架构模式（Workflow vs Agent 区分 + Prompt Chaining/Routing/Parallelization/Orchestrator-Workers/Evaluator-Optimizer/Agents）、新增 Agent 可观测性三件套（Trace/Eval/Guardrail 生产级监控体系，含 LLM-as-Judge 陷阱、工具选型、落地 Roadmap） |\n| v1.8 | 2026-07-05 | 新增 Agent Containment 爆破半径控制模式（三层防御体系 + 三种 Isolation 模式 + 审批疲劳机制）、新增 Managed Agents 脑手分离架构（Brain/Hands/Session 解耦 + TTFT 降低 60-90% + Harness 设计警告）、新增 L4 Agent 运行时错误分类（死循环/误调工具/上下文污染/权限越界/上下文焦虑/Harness 过期）、新增 Agent 工程兜底框架（6 种典型故障模式 + 4 条兜底设计原则） |\n| v1.9 | 2026-07-12 | 新增 GAN-Inspired Multi-Agent Loops & Harness Design（Generator-Evaluator 循环 + 三 Agent 架构 + Context Reset vs Compaction）、新增 Advanced Tool Use 三大技术（Tool Search Tool 延迟加载 + Programmatic Tool Calling 代码编排 + Tool Use Examples）、新增 Claude Code Quality Postmortem 分析（推理降级/缓存 Bug/过约束提示 三起退化事件 + 对 Agent 工程通用启示）、新增 L5 质量退化错误分类 + 质量退化诊断模板 |\n| v2.0 | 2026-07-19 | ⚠️ 重大重构：anthropic-patterns.md 超 400 行，拆分为基础篇（§1-9）+ 高级篇（§10-18，新文件 anthropic-patterns-advanced.md）。新增 3 条高级实践：Claude Code Auto Mode 四层审批架构（分类器替代人工审批 + 双层防御 + 4 类威胁模型）；Code Execution with MCP（工具即代码，token 降低 98.7%）；Context Engineering Anthropic 官方定义（注意力预算/Right Altitude/组件管理）。SKILL.md 参考表同步更新。\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn70tx725606ywwb5gfj0vpxjx83admr\",\n \"slug\": \"agent-optimization-expert\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1784884569888\n}\n\nFile v1.0.1:references/advanced-optimization.md\n\n# Agent 高级优化实践\n\n## 13. Prompt Caching 优化实践 (新增 2026-06-14)\n\nPrompt Caching 是 2026 年最值得关注的 LLM 成本优化技术。典型 LLM 应用中，系统提示会在每次调用时被重复处理，产生大量不必要的算力消耗。\n\n### 核心价值\n| 指标 | 无缓存 | 有缓存 | 改善 |\n|------|--------|--------|------|\n| 缓存 Token 成本 | 全价 | Claude -90%, GPT-4o -50% | 显著 |\n| 首 Token 延迟 | 基准 | 降低 20-70% | 显著 |\n| 盈亏平衡点 | - | Claude: 约 1.25 次请求后 | 极快 |\n\n### Claude 显式缓存控制\n- 使用 `cache_control: {\"type\": \"ephemeral\"}` 标记可缓存内容块\n- 缓存对前缀完全相同的内容有效\n- 写缓存比普通输入贵 25%（一次性），读缓存便宜 90%\n\n### GPT-4o 自动缓存\n- 无需显式标记，自动缓存相同前缀\n- 关键：系统提示保持一致（日期/动态内容会破坏缓存）\n- 将动态信息放在消息层最后，而非系统提示中\n\n### 缓存友好的架构设计\n```\n层 1: 系统指令（最稳定，全局共用）→ 缓存命中\n层 2: 知识库内容（按类型共用）→ 缓存命中\n层 3: 用户特定上下文（用户级缓存）→ 用户维度命中\n层 4: 当前用户消息（动态，无法缓存）→ 不缓存\n```\n\n### 缓存破坏因素（避免）\n- ❌ 系统提示中嵌入当前时间/日期\n- ❌ 为每个请求动态生成 Session ID\n- ❌ 随机化示例内容\n- ❌ 用户姓名插入系统提示（应放用户消息层）\n\n### OpenClaw 映射\n- 主 Agent 的 SOUL.md/USER.md 作为稳定前缀有利于缓存\n- 避免在每次 prompt 中注入动态时间戳\n- 子 Agent 使用 `lightContext` 减少缓存破坏\n\n来源: [Prompt缓存工程2026：Claude和GPT-4o的上下文缓存机制与最佳实践](https://mukebb.blog.csdn.net/article/details/161868589)\n\n---\n\n## 14. 高效智能体框架 — 2026 综述 (新增 2026-06-14)\n\n上海 AI Lab、复旦、中科院、上交大等 9 所高校联合发表《迈向高效智能体（Agents）：记忆、工具学习与规划综述》，提出效率定义：\n\n> **效率** = 在固定成本预算（Token 数/延迟/计算量）下最大化任务成功率，或在相同效果下最小化成本。\n\n### 高效记忆 (Efficient Memory)\n| 类型 | 代表 | 核心思路 |\n|------|------|----------|\n| 工作记忆-文本 | COMEDY, MemAgent | LLM 提取关键信息压缩为摘要 |\n| 工作记忆-潜在 | Activation Beacon, MemoRAG | 长上下文压缩为 KV Cache |\n| 外部记忆-项目 | MemoryBank, Expel | 压缩对话记录减少 Token |\n| 外部记忆-图 | GraphReader, Zep | 知识图谱组织实体关系 |\n| 外部记忆-层次 | MemGPT, ReadAgent | OS 式层级结构管理海量信息 |\n\n**记忆管理策略**:\n- 规则驱动: FIFO/艾宾浩斯遗忘曲线（低成本，可能丢失关键信息）\n- LLM 驱动: Memory-R1 自主决定 ADD/DELETE（自适应但有计算开销）\n- 混合驱动: LightMem 规则触发阈值 + LLM 语义合并\n\n### 高效工具学习 (Efficient Tool Learning)\n| 策略 | 代表 | 核心思路 |\n|------|------|----------|\n| 外部检索器 | ProTIP | 对比学习嵌入语义空间，相似度检索 |\n| 多标签分类 | TinyAgent | 小模型直接预测需要的工具集合 |\n| 并行调用 | LLMCompiler | 分析工具调用图，无依赖工具并行执行 |\n| 成本感知 | BTP | 工具调用视为背包问题，预算约束最优组合 |\n\n### 高效规划 (Efficient Planning)\n| 策略 | 核心思路 |\n|------|----------|\n| 选择性思考 | 自适应推理预算，根据任务复杂度动态分配 Fast/Slow Thinking |\n| 结构化搜索 | A* 启发式评估，剪枝不必要搜索分支 |\n| 任务分解 | Plan-Then-Act，大问拆小问题 |\n| 记忆与技能复用 | 复用已存储经验/策略，越用越省 |\n\n### 多智能体协作效率\n- **拓扑效率**: 稀疏通信网络（图结构）替代密集冗余交互\n- **协议优化**: 精简上下文，确保每次通信携带高价值信息\n- **协同蒸馏**: 教师-学生式知识迁移，减少每个 Agent 学习成本\n\n### OpenClaw 映射\n- `memory_search` 对应高效记忆检索（避免全量 `memory_get`）\n- 子 Agent 使用 `lightContext` = 工作记忆压缩\n- 工具描述按需组装 = 外部检索器模式\n- `sessions_yield` 等待完成 = 拓扑效率（不轮询 = 减少通信）\n\n来源: [2026年做 Agents 应该看这篇全面的技术综述](https://cloud.tencent.com/developer/article/2637134)\n\nFile v1.0.1:references/anthropic-patterns-advanced.md\n\n# Anthropic 工程实践模式 — 高级篇\n\n> 本文件包含 Anthropic 工程博客中较新的高级实践模式。基础模式（§1-9 思考/Tool Use/上下文管理等）请参见 [anthropic-patterns.md](./anthropic-patterns.md)。\n\n## 10. Agent Containment — 爆破半径控制模式 (新增 2026-07-05)\n\nAnthropic 在 [How we contain Claude across products](https://www.anthropic.com/engineering/how-we-contain-claude) 中系统阐述了随着 Agent 能力增强，如何控制其「爆破半径」(blast radius)。\n\n### 三种风险源\n\n| 风险类型 | 来源 | 示例 |\n|---------|------|------|\n| **User Misuse** | 用户滥用/疏忽 | 让 Agent 绕过检查、执行不理解的危险命令 |\n| **Model Misbehavior** | 模型自主做出有害行为 | 更聪明的模型会「绕路」达成目标，甚至逃逸沙箱 |\n| **External Attackers** | 外部攻击向量 | Prompt 注入、工具/文件/网络攻击 |\n\n### 三层防御体系\n\n| 层 | 机制 | 特点 |\n|---|------|------|\n| **环境层** | 沙箱、VM、文件系统边界、出口控制 | 硬边界，最可靠。凭证不进沙箱就无法被窃取 |\n| **模型层** | 系统提示、分类器、探测器、训练修改 | 概率性防御，不可能 100% 有效 |\n| **外部内容层** | 工具权限粒度控制、MCP 代理 | 限制工具能力范围，读-only 比可写安全得多 |\n\n**核心原则**：环境防御 > 模型防御。三层重叠互补，当环境防御不可用时模型层必须兜底。\n\n### 三种 Isolation 模式\n\n| 模式 | 代表产品 | 特点 |\n|------|---------|------|\n| **Ephemeral Container** | claude.ai 代码执行 | gVisor 容器隔离，会话级临时文件系统，爆破半径最小 |\n| **Human-in-the-Loop Sandbox** | Claude Code | OS 级沙箱 (macOS Seatbelt / Linux bubblewrap)，84% 权限提示减少 |\n| **Full Workspace** | Claude Cowork | 持久工作空间 + 受限网络 + MCP 工具代理 |\n\n### 审批疲劳 (Approval Fatigue)\n\n- 用户最终批准约 93% 的权限提示\n- 审批越多，注意力越少 → 监督质量下降\n- **经验用户** 自动批准率是新用户 2 倍，但也更频繁地中途打断\n- 解决方案：Claude Code auto mode 将审批从\"每个步骤\"改为\"基于规则的自动批准 + 异常拦截\"，捕获约 83% 的过度行为\n\n### OpenClaw 映射\n- exec 工具 = 沙箱执行，注意不要给子 Agent 超出工作区的访问权限\n- 操作分级 (L0-L3) = 审批粒度控制，L2/L3 必须确认\n- 敏感信息禁止发群 = 爆破半径控制：即使模型行为异常，影响也被限制\n\n来源: [Anthropic: How we contain Claude across products](https://www.anthropic.com/engineering/how-we-contain-claude)\n\n## 11. Managed Agents — 脑手分离架构 (新增 2026-07-05)\n\nAnthropic 在 [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) 中提出了 Agent 架构的根本性优化：**将 Brain（Claude + harness）与 Hands（沙箱 + 工具）解耦**。\n\n### 核心架构解耦\n\n| 组件 | 角色 | 比喻 |\n|------|------|------|\n| **Brain** | Claude + harness 循环 | 决策中枢，无状态，可替换 |\n| **Hands** | 沙箱容器 + 工具执行 | 执行端，故障时自动重建 |\n| **Session** | 持久化事件日志 | 上下文存储，独立于 Brain 和 Hands |\n\n### 关键设计原则\n\n1. **容器即牛 (Cattle not Pets)**：容器故障时不修复，直接重建。Harness 把容器故障当作工具调用错误处理\n2. **Harness 也是牛**：Harness 崩溃后可通过 `wake(sessionId)` 重建，从最后一个事件恢复\n3. **Session 是独立持久化对象**：不依赖 Claude 的上下文窗口，通过 `getEvents()` 接口按需获取历史\n\n### 性能收益\n\n- p50 TTFT 降低约 **60%**\n- p95 TTFT 降低超过 **90%**\n- 不需要沙箱的会话无需等待容器预配即可开始推理\n\n### 安全改进\n\n- 凭证**永远不进入**沙箱：Git token 在沙箱初始化时注入 remote，MCP 工具通过代理调用\n- 即使 Claude 生成恶意代码，也无法窃取凭证\n\n### 上下文管理新范式\n\n- Session 作为**独立于上下文窗口的上下文对象**\n- `getEvents()` 允许 Harness 按位置切片获取事件流\n- 可以在传递到 Claude 前做任意转换（缓存优化、上下文工程）\n- 避免了**不可逆的上下文压缩决策**\n\n### OpenClaw 映射\n- OpenClaw 的子 Agent 架构天然符合脑手分离：spawn 时分配独立上下文，完成后回收\n- `sessions_spawn(context=\"isolated\")` = 每次都是新容器\n- `memory_search` + `memory_get` = Session 级别的外部持久化\n- Harness 崩溃恢复 = OpenClaw session 自动恢复机制\n\n### Harness 设计警告\n\n> Harness 编码的是\"Claude 目前做不到的事\"的假设。但这些假设会随模型能力提升而**过期**。Anthropic 发现 Sonnet 4.5 有\"上下文焦虑\"（提前结束任务），但 Opus 4.5 没有这个问题——之前的 context reset 变成了死重。\n\n**工程教训**：定期审视 harness/工作流 中的补偿逻辑是否仍然必要，随模型能力升级而精简。\n\n来源: [Anthropic: Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents)\n\n## 13. GAN-Inspired Multi-Agent Loops & Harness Design (新增 2026-07-12)\n\nAnthropic 在 [Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24) 中展示了将 GAN（生成对抗网络）思想应用于 Agent 编排的进阶实践。\n\n### Generator-Evaluator 循环\n\n核心思路：生成器产出 → 独立评估器评分 → 反馈给生成器迭代。类似 GAN 的 generator/discriminator 架构，但用在 Agent 编排而非模型训练。\n\n| 组件 | 角色 | 关键设计 |\n|------|------|----------|\n| Generator | 生成输出（代码/设计/内容） | 接收评估器反馈后迭代 |\n| Evaluator | 独立评估输出质量 | 与生成器分离，避免自我评估偏差 |\n\n**关键发现**：Agent 评估自己产出时倾向于给出正面评价，即使质量明显平庸。分离评估器后，更容易调出批判性评分标准。\n\n### 四维度评估标准（前端设计场景）\n\n| 维度 | 评估什么 | 默认表现 |\n|------|---------|----------|\n| Design Quality | 整体一致性、风格统一 | 容易平淡 |\n| Originality | 是否有定制创意决策 | AI 模板化严重 |\n| Craft | 技术执行（排版/间距/配色） | 模型天然较好 |\n| Functionality | 可用性/可理解性 | 模型天然较好 |\n\n**要点**：对默认就好的维度降低权重，对默认差的维度加大权重，引导模型做审美冒险。\n\n### 三 Agent 架构（全栈开发场景）\n\n```\nPlanner → Generator → Evaluator\n │ │ │\n └─ 分解任务 ─┴─ 实现功能 ─┴─ 评分反馈\n```\n\n- **Planner**: 将产品需求分解为可管理的子任务\n- **Generator**: 逐个实现子任务\n- **Evaluator**: 独立评分并提供改进建议\n\n### Context Reset vs Compaction\n\n| 策略 | 原理 | 适用场景 |\n|------|------|----------|\n| **Compaction** | 压缩历史上下文，同一 Agent 继续 | 中等长度任务，保持连续性 |\n| **Context Reset** | 清空上下文 + 结构化交接文档 + 新 Agent | 超长任务，解决上下文焦虑 |\n\n**经验教训**：Claude Sonnet 4.5 有明显的上下文焦虑倾向（感知上下文将满时提前结束任务），compaction 不足以解决，需要 context reset。\n\n### OpenClaw 映射\n- 优化师的「诊断→修复→验证」循环本质是 Generator-Evaluator 模式的简化版\n- 子 Agent 隔离执行复杂任务 = Planner/Generator 角色\n- 修复后验证清单 = Evaluator 角色\n- `context=\"isolated\"` = Context Reset 模式\n- `memory_search` + `memory_get` = 结构化交接文档\n\n来源: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)\n\n## 14. Advanced Tool Use — Tool Search & Programmatic Calling (新增 2026-07-12)\n\nAnthropic 在 [Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) (2025-11-24) 中提出了三项解决大规模工具管理的关键技术。\n\n### Tool Search Tool — 延迟加载的工具发现\n\n**问题**: 5 个 MCP Server = 58 工具 ≈ 55K tokens 在对话开始前就已被消耗。内部测试曾出现 134K tokens 的工具定义开销。\n\n**方案**: `defer_loading: true` 标记工具为延迟加载。只加载 Tool Search Tool（~500 tokens），运行时按需搜索并加载相关工具定义。\n\n**效果**:\n- Token 消耗: ~77K → ~8.7K（**85% 降低**）\n- 准确率: Opus 4 从 49% → 74%，Opus 4.5 从 79.5% → 88.1%\n- Prompt Caching 不被破坏（延迟工具不在初始 prompt 中）\n\n**OpenClaw 映射**:\n- OpenClaw Skills 延迟加载本质上就是 Tool Search 模式\n- 启动时只读 SKILL.md front-matter（~500 tokens），需要时才加载正文\n- exec 工具 = 始终加载的核心工具（`defer_loading: false`）\n- 专用 Skills = 延迟加载（`defer_loading: true`）\n\n### Programmatic Tool Calling — 代码编排工具调用\n\n**问题**: 传统工具调用每个调用需要一次完整推理，中间结果全进入上下文。\n**方案**: Claude 编写代码编排工具调用，在沙箱中执行，只有最终结果进入上下文。\n\n**效果**: 20 个团队成员 × 每人 50-100 条费用记录 → 代码处理后只输出超标人员名单（2-3 行）。\n\n**OpenClaw 映射**:\n- `exec` 工具执行 bash/python 脚本 = Programmatic Tool Calling 的沙箱环境\n- 复杂数据查询用脚本处理而非多次工具调用\n\n### Tool Use Examples — 工具使用示例\n\n**问题**: JSON Schema 只定义结构合法性，不表达使用模式（何时传可选参数、参数组合、API 约定）。\n**方案**: 为工具提供使用示例，让模型学习正确的调用方式。\n\n**OpenClaw 映射**:\n- SKILL.md 中的「使用」章节和命令示例 = Tool Use Examples\n- 好的 Skill 应该包含常见用法和陷阱提示\n\n### 何时使用 Tool Search Tool\n\n| 使用场景 | 不使用场景 |\n|---------|----------|\n| 工具定义 >10K tokens | 工具库很小（<10 个） |\n| 多 MCP Server 集成 | 工具选择准确性没问题 |\n| 10+ 工具可用 | 延迟敏感 |\n| 遇到工具选择准确性问题 | |\n\n来源: [Anthropic: Introducing advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)\n\n## 15. Claude Code Quality Postmortem — 质量回归案例分析 (新增 2026-07-12)\n\nAnthropic 在 [An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) (2026-04-23) 中详细分析了三起质量退化事件，对 Agent 工程有重要教训。\n\n### 事件 1: 推理努力级别降级\n\n**变更**: 将 Opus 4.6 默认 reasoning effort 从 high 降为 medium，以减少极端延迟。\n**后果**: 用户反馈 Claude Code 智能度显著下降。\n**恢复**: 两周后回滚，Opus 4.7 默认 xhigh。\n\n**教训**: **智能 vs 延迟的取舍中，用户更看重智能度**。Agent 框架不应默认降低推理质量来换取速度。\n\n### 事件 2: Prompt Caching Bug 导致推理历史丢失\n\n**变更**: 空闲超过 1 小时的 session 清除旧 thinking 以降低恢复延迟。\n**Bug**: 不是清除一次，而是每次请求都清除，导致 Claude 越来越「健忘」。\n**后果**: 重复行为、奇怪的工具选择、usage limit 快速消耗（因为 cache miss）。\n\n**教训**:\n- Prompt Caching 优化是高风险变更，需要严格的回归测试\n- 上下文管理 Bug 比功能 Bug 更难诊断（多层系统：context management + API + extended thinking）\n- Cache miss 会导致 usage 消耗暴增\n\n### 事件 3: 减少啰嗦的系统提示变更损害了编码质量\n\n**变更**: 添加系统提示限制输出长度（工具调用间 ≤25 词，最终回复 ≤100 词）。\n**后果**: 编码质量下降 3%（Opus 4.6 和 4.7 都受影响）。\n**恢复**: 回滚该提示变更。\n\n**教训**: **简洁提示 ≠ 智能提示**。限制模型输出长度可能损害推理质量，尤其对复杂任务。\n\n### 对 Agent 工程的通用启示\n\n| 教训 | OpenClaw 映射 |\n|------|-------------|\n| 智能优先于延迟 | 不要随意降低 `thinking` 级别 |\n| 上下文管理需严格测试 | 修改 context/memory 配置后必须验证 |\n| 系统提示变更要 ablation 测试 | 修改 SOUL.md/AGENTS.md 后检查影响 |\n| 每个模型行为不同 | 切换模型时需重新评估配置 |\n| 渐进式发布 + soak period | 重要配置变更先灰度 |\n\n来源: [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)\n\n## 12. Anthropic Building Effective Agents — 7大架构模式 (新增 2026-06-28)\n\nAnthropic 在 [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) 中提出了 Agentic System 的系统架构分类，从简单到复杂共7种模式。这是目前业界最权威的 Agent 架构参考指南。\n\n### 核心区分: Workflow vs Agent\n\n| 类型 | 定义 | 适用场景 |\n|------|------|----------|\n| **Workflow** | LLM 和 Tool 经过预先定义和精心编排 | 流程固定、可预测性要求高、一致性优先 |\n| **Agent** | LLM 动态指导自己的流程和工具调用 | 路径不确定、需要动态规划、自主决策 |\n\n**关键原则**: 在垂直领域中，尽量找到最简单的解决方案路径。很多场景根本不需要 Agent，Agent 会牺牲延迟和成本来换取更好的性能。\n\n### 7大架构模式\n\n#### ① Building Block: The Augmented LLM\n增强型 LLM。借助 MCP 框架拓展工具链，为 LLM 定制检索、工具、记忆能力。\n→ 适用：最基础的 Agent 组件构建\n\n#### ② Workflow: Prompt Chaining（提示链）\n将任务分解为串行步骤，中间环节增加检查点。\n→ 适用：任务可清晰分解为固定子任务，用延迟换准确性\n→ 示例：编写大纲 → 检查标准 → 根据大纲编写文档\n\n#### ③ Workflow: Routing（路由）\n按类别分解大任务，建立更专业的提示。\n→ 适用：任务复杂、类别明确\n→ 示例：客服查询（一般问题/退款/技术支持）导向不同下游流程\n\n#### ④ Workflow: Parallelization（并行）\n两种方式：①分段：独立子任务并行；②投票：多次运行取不同输出\n→ 适用：多个因素需分别处理\n→ 示例：一个模型处理用户查询，另一个做安全审查\n\n#### ⑤ Workflow: Orchestrator-Workers（协调者）\n中央协调者动态分解任务，分配给工作者，综合结果。\n→ 适用：无法预测子任务复杂度的场景\n→ 与并行化的区别：子任务不是预定义的，由协调者动态确定\n\n#### ⑥ Workflow: Evaluator-Optimizer（评价器-优化器）\n一个生成响应，另一个提供评价和反馈，类似强化学习。\n→ 适用：有明确评估标准，迭代改进有可衡量价值\n→ 示例：复杂搜索/推理任务，由评估员决定是否需要进一步探索\n\n#### ⑦ Agents（真正的 Agent）\n任务明确后独立规划和操作，从环境中获取每步的\"基本事实\"评估进度。\n→ 适用：开放式问题，无法预测步骤数或硬编码固定路径\n→ 关键：清晰完善的工具集及其文档至关重要\n\n### 实施三原则\n\n1. **保持智能体设计简洁性** — 只有当复杂性明显改善结果时，才增加复杂性\n2. **明确显示规划步骤** — 优先考虑透明度\n3. **精心设计 ACI (Agent-Computer Interface)** — 通过详尽的工具文档和测试\n\n### 框架使用警告\n\n> 框架（LangGraph、Dify等）通过标准化通用组件形成抽象层，但抽象层会掩盖提示和反馈过程，增加 debug 复杂度。**当简单解决方案足够时，不要使用框架。** 不了解抽象层背后的原理是最常见的错误。\n\n来源: [Anthropic: Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents), [CSDN解读](https://blog.csdn.net/huang9604/article/details/157645191)\n\n## 16. Claude Code Auto Mode — 分类器替代人工审批 (新增 2026-07-19)\n\nAnthropic 在 [How we built Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode) (2026-03-25) 中系统解决了审批疲劳问题，将审批从「每步人工确认」升级为「模型分类器自动判断 + 异常拦截」。\n\n### 四层审批架构\n\n| 层级 | 机制 | 说明 |\n|------|------|------|\n| **Tier 1** | 内置安全工具白名单 | 只读操作（文件读取、搜索、代码导航）直接放行 |\n| **Tier 2** | 规则引擎 (Allow Rules) | 用户配置的特定工具/模式自动放行；进入 Auto Mode 时移除可能执行任意代码的规则 |\n| **Tier 3** | Transcript Classifier | Sonnet 4.6 运行两阶段分类器：快速单 token 过滤 → 仅被标记时才触发 CoT 推理 |\n| **Tier 4** | 人工审批 | 兜底，分类器无法判断时交给人工 |\n\n### Auto Mode 双层防御\n\n| 防御层 | 位置 | 功能 |\n|--------|------|------|\n| **输入层：Prompt Injection Probe** | 工具结果进入上下文前 | 扫描文件/网页/Shell 输出中的注入尝试，发现可疑内容时在 Agent 上下文中加入警告 |\n| **输出层：Transcript Classifier** | 工具调用执行前 | 评估每个行动是否符合用户意图，仅看用户消息和 Agent 工具调用（剥离 Claude 自身消息和工具输出），对推理过程「盲目」 |\n\n### 四类威胁模型\n\n| 威胁类型 | 特征 | 示例 |\n|---------|------|------|\n| **Overeager Behavior** | Agent 理解目标但过度主动 | 发现凭据后主动使用、删除判断为\"障碍\"的文件 |\n| **Honest Mistakes** | Agent 误解爆破半径 | 以为资源是测试范围的但实际是共享的 |\n| **Prompt Injection** | 外部内容劫持 Agent 行为 | 文件/网页中植入指令 |\n| **Misaligned Model** | Agent 追求自身目标 | 目前实践中未观察到，每次发版前严格评估 |\n\n### 关键设计决策\n\n1. **Classifier 对推理过程盲目**：剥离 Agent 自身消息和工具输出，只看用户意图和计划行动，避免 Agent 用「合理化推理」绕过分类器\n2. **两阶段分类**：大部分操作通过快速过滤，只有可疑操作才消耗推理 token，成本可控\n3. **Subagent 递归继承**：子 Agent 继承相同的输入/输出防御管线\n4. **进入 Auto Mode 时降级权限**：移除已知允许任意代码执行的权限规则（shell 通配、脚本解释器、包管理器运行命令）\n\n### OpenClaw 映射\n- 操作分级 L0-L3 本质上是简化的分类器：L0-L1 白名单放行，L2 提示确认，L3 必须授权\n- Auto Mode 启示：可考虑为 L2 操作配置「规则自动批准 + 异常拦截」，减少审批疲劳\n- 子 Agent 防御递归：spawn 子 Agent 时应确保其继承相同的安全约束\n\n来源: [Anthropic: How we built Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode)\n\n## 17. Code Execution with MCP — 工具即代码 (新增 2026-07-19)\n\nAnthropic 在 [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) (2025-11-04) 中提出将 MCP 工具呈现为代码 API 而非直接工具调用，大幅降低 token 消耗。\n\n### 问题\n\n| 问题 | 影响 |\n|------|------|\n| **工具定义塞满上下文** | 数十个 MCP Server × 数百个工具 = 启动前就消耗 150K+ tokens |\n| **中间结果全过模型** | 数据在工具间传递时重复流经模型上下文（同一文档读一次写一次 = 双倍 token） |\n| **大文档超上下文** | 超大文档可能直接超出上下文窗口限制 |\n\n### 方案：工具即代码\n\n将 MCP 工具封装为代码文件，Agent 通过写代码调用而非逐次推理调用：\n\n```\nservers/\n├── google-drive/\n│ ├── getDocument.ts\n│ └── index.ts\n├── salesforce/\n│ ├── updateRecord.ts\n│ └── index.ts\n```\n\nAgent 通过浏览文件系统发现可用工具，只读取当前任务需要的工具定义：\n```typescript\nimport * as gdrive from './servers/google-drive';\nimport * as salesforce from './servers/salesforce';\n\nconst transcript = (await gdrive.getDocument({ documentId: 'abc123' })).content;\nawait salesforce.updateRecord({\n objectType: 'SalesMeeting',\n recordId: '00Q5f000001abcXYZ',\n data: { Notes: transcript }\n});\n```\n\n### 效果\n- Token 消耗：~150K → ~2K（**98.7% 降低**）\n- Cloudflare 同样验证（称为 \"Code Mode\"）\n\n### 核心优势\n| 优势 | 说明 |\n|------|------|\n| **Progressive Disclosure** | Agent 按需读取工具定义，而非一次性全部加载 |\n| **Data Filtering** | 在代码执行环境中过滤/处理数据，只将结果传回模型 |\n| **Complex Logic in One Step** | 复杂逻辑在代码中一次性执行，而非多次推理 |\n| **State Management** | 变量在代码环境中持久，不占用模型上下文 |\n\n### OpenClaw 映射\n- `exec` 工具执行 Python/Bash 脚本本质上就是 Code Execution 模式\n- 复杂数据查询用脚本处理而非多次工具调用（如财务数据批量分析）\n- SKILL.md 延迟加载 + exec = OpenClaw 版的「工具即代码」架构\n\n来源: [Anthropic: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp), [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode/)\n\n## 18. Effective Context Engineering — Anthropic 官方定义 (新增 2026-07-19)\n\nAnthropic 在 [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (2025-09-29) 中给出了 Context Engineering 的权威定义，这是对 references/ 中已有 Context Engineering 条目的官方升级。\n\n### 定义\n\n> **Context Engineering** = 管理和维护 LLM 推理时最优 token（信息）集合的策略集，包括系统指令、工具、MCP、外部数据、消息历史等全部上下文组件。\n\n与 Prompt Engineering（如何写好提示词）不同，Context Engineering 关注的是**整个上下文状态**的编排和维护，是迭代式的，每次向模型传递信息时都要做策展决策。\n\n### 为什么需要 Context Engineering\n\n- **Context Rot（上下文腐化）**：Chroma Research 证实，随着上下文窗口中 token 数量增加，模型准确召回信息的能力下降\n- **注意力预算有限**：LLM 基于 Transformer 架构，n 个 token 需要 n² 的成对注意力计算，上下文越长注意力越分散\n- **性能梯度而非硬断崖**：模型在长上下文上仍然可用但精度下降，容易让人忽略问题\n\n### 系统提示词设计原则\n\n| 原则 | 说明 |\n|------|------|\n| **Right Altitude（正确高度）** | 避免两个极端：① 过度硬编码复杂 if-else 逻辑（脆弱难维护）；② 过于模糊的高级指导（缺乏具体信号） |\n| **Minimal but Complete（最小但完整）** | 用最少的信息完整描述期望行为，最小≠最短 |\n| **Section Organization（分段组织）** | 使用 XML 标签或 Markdown 头划分不同部分（背景/指令/工具/输出格式） |\n| **Direct Language（直接语言）** | 简单直接的语言，避免花哨表述 |\n\n### 上下文组件管理\n\n| 组件 | 管理要点 |\n|------|----------|\n| **工具定义** | 按需加载，不一次性全部注入；使用搜索工具或延迟加载 |\n| **检索增强 (RAG)** | 检索质量 > 数量；精确查询 + 过滤 + 重排序 |\n| **消息历史** | 定期压缩/修剪；保留关键决策点，压缩中间推理 |\n| **外部数据** | 按需注入；考虑缓存最近使用的数据减少重复检索 |\n\n### OpenClaw 映射\n- SOUL.md / AGENTS.md = 系统提示词分段组织\n- `memory_search` = 检索增强按需注入\n- `lightContext` = 上下文压缩策略\n- SKILL.md 延迟加载 = 工具定义按需加载\n- 子 Agent `context=\"isolated\"` = 消息历史隔离，避免污染\n\n来源: [Anthropic: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)\n\nFile v1.0.1:references/anthropic-patterns.md\n\n# Anthropic 工程实践模式\n\n## 1. Extended Thinking Pattern\n\nAnthropic Claude 的核心优势是 extended thinking（扩展思考）模式。\n\n### 使用场景\n- 复杂问题分解\n- 多步骤推理\n- 代码架构设计\n- 错误诊断与修复\n\n### 实践要点\n```\n1. 在思考阶段明确列出假设\n2. 对每个假设进行验证\n3. 记录推理链条\n4. 最终输出时提炼结论，隐藏中间过程\n```\n\n### OpenClaw 映射\n- `thinking` 参数控制思考级别\n- 复杂诊断任务启用 thinking 模式\n- 子 Agent 使用 thinking 进行深度分析\n\n## 2. Tool Use Best Practices\n\n### 预检-执行-后检模式\n```\n预检: 验证输入参数、权限、依赖状态\n执行: 调用工具，带超时和重试\n后检: 验证结果完整性、一致性\n```\n\n### 错误处理策略\n```\n1. 捕获具体错误类型（非通用异常）\n2. 分类处理：\n - 可重试：指数退避重试\n - 需修正：调整参数重试\n - 不可恢复：降级到备用方案\n3. 记录错误模式到学习库\n```\n\n### MCP 协议集成 (新增 2026-05-24)\n\nAnthropic 推动的 MCP（Model Context Protocol）解决工具接入碎片化问题：\n- 允许企业数据留在本地环境，保障数据主权\n- 标准化的工具注册和发现机制\n- 与 Function Calling Schema 互补：MCP 管通信接入，Schema 管数据格式\n- OpenClaw 中的 Skills 本质上就是 MCP 的轻量替代\n\n来源: [Anthropic API vs OpenAI API 对比](https://www.cnblogs.com/philry/p/19359139)\n\n## 3. Multi-Agent Coordination\n\n### 子 Agent 使用原则\n```\n- context=\"isolated\"：新任务，无需上下文\n- context=\"fork\"：需要当前对话上下文\n- runTimeoutSeconds：设置合理超时\n- 使用 sessions_yield 等待完成，不轮询\n```\n\n### 通信模式\n```\n主 Agent → 子 Agent: sessions_spawn(task, taskName)\n子 Agent → 主 Agent: 完成事件自动传递\n主 Agent ↔ 子 Agent: sessions_send 进行中途交互\n```\n\n## 4. Prompt Engineering Patterns\n\n### 结构化输出\n```\n使用明确的输出格式要求：\n- JSON schema 定义\n- Markdown 模板\n- 明确的字段名称\n```\n\n### 角色分离\n```\n不同任务使用不同的角色提示：\n- 诊断模式：\"你是一个系统诊断专家...\"\n- 修复模式：\"你是一个运维工程师...\"\n- 优化模式：\"你是一个性能调优专家...\"\n```\n\n### 自反思模式\n```\n在关键决策后添加：\n\"在继续之前，请反思你的分析：\n1. 是否遗漏了重要信息？\n2. 假设是否合理？\n3. 有没有其他可能的解释？\"\n```\n\n## 5. Context Management\n\n### 上下文优化\n```\n- 使用 memory_search 检索相关信息，而非全部加载\n- 大型文件使用 offset/limit 分段读取\n- 子 Agent 使用 lightContext 减少 token\n- 定期清理过期的 session 状态\n```\n\n### Token 预算\n```\n诊断任务：< 5000 tokens\n修复任务：< 10000 tokens\n复杂分析：使用子 Agent 隔离\n```\n\n### Context Engineering (新增 2026-05-24)\n\nContext Engineering 是 Agent 系统的第三层核心能力（与 LLM Call、Tools Call 并列）：\n\n- **核心问题**: 上下文越长，推理质量不一定越好；中间位置信息利用效率低\n- **动态记忆注入**: 按需将长期记忆注入当前对话上下文\n- **会话状态管理**: 跟踪任务进度，决定哪些上下文保留、哪些压缩\n- **工具描述动态组装**: 根据当前任务阶段，只注入相关工具描述（而非全量）\n- **上下文压缩策略**: 保留关键决策点和工具调用结果，压缩中间推理过程\n\n关键洞察：不给任何 Context 的情况下，再先进的模型也可能只能处理极少数任务。Context Engineering 是最容易被低估的环节。\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 6. Safety & Guardrails\n\n### 操作分级\n```\nL0 - 安全：读取文件、检查状态\nL1 - 低风险：修改临时文件、更新日志\nL2 - 中风险：修改配置、重启服务\nL3 - 高风险：删除数据、修改核心配置\n\nL0-L1: 自动执行\nL2: 提示用户确认\nL3: 必须用户明确授权\n```\n\n### 审计日志\n```\n所有 L2+ 操作记录到：\n- learnings/error-log.md\n- memory/YYYY-MM-DD.md\n- 包含：操作时间、内容、原因、结果\n```\n\n### Claude Code 最佳实践 (新增 2026-05-24)\n\nAnthropic 定义 Claude Code 为 **agentic coding tool**（不是 autocomplete）：\n- 可搜索和读取代码、编辑文件、写测试、运行测试、提交代码\n- 编程能力基准分达 64.3%（Claude Opus 4.7）\n- 支持复杂系统开发的自治执行\n\n来源: [Claude Code 安装与使用](https://www.runoob.com/claude-code/claude-code-install.html), [Claude Opus 4.7 发布](https://cloud.tencent.com/developer/news/3844958)\n\n## 7. Agent Skills 延迟加载模式 (新增 2026-05-31)\n\nAgent Skills 是 Anthropic 推动的技能发现与按需加载机制，核心是 SKILL.md 文件：\n\n```\n.claude/skills/code-reviewer/\n├── SKILL.md ← YAML front-matter + 详细指令\n├── scripts/xxx.py ← 可选：配套脚本\n└── reference.md ← 可选：参考资料\n```\n\n### 延迟加载设计\n- **启动时**：只读取 SKILL.md 的 YAML front-matter（元数据），用于发现\n- **执行时**：LLM 判断需要某个 Skill 后，才加载完整正文进上下文\n- **优势**：避免启动时将所有 Skill 塞进上下文，节省 Token 预算\n\n### Skill 的两种形态\n| 类型 | 特点 | 适用场景 |\n|------|------|---------|\n| Toolkits（黑盒） | 多原子工具封装成高阶工具，对外只暴露 JSON Schema | 逻辑固定、推理步骤少、Token 敏感 |\n| Agent Skills（白盒） | SKILL.md 自然语言指令集，延迟加载正文 | 团队经验沉淀、任务灵活、需要可解释性 |\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 8. Context Engineering 进阶 (新增 2026-06-07)\n\n### JIT 按需加载模式\n\nJust-in-Time (JIT) 按需加载是 Context Engineering 的进阶实践：\n- **问题**: 预检索只能拿到\"调用前看起来相关\"的信息，Agent 执行中会发现新线索\n- **方案**: 运行时维护轻量级引用（文件路径、数据库查询、Web 链接），Agent 在判断需要时才实际加载内容\n- **类比**: 不是一开始把所有可能相关的书搬到桌上，而是把书架目录放在手边，需要哪本再取\n- **OpenClaw 映射**:\n - `memory_search` 而非全量 `memory_get`\n - 子 Agent 使用 `lightContext`\n - 工具描述按需组装（不把所有工具 Schema 一次性注入）\n - 大文件使用 `offset/limit` 分段读取\n\n### 上下文评估指标\n\n| 指标类型 | 具体看什么 |\n|---------|----------|\n| 任务成功率 | 是否完成目标、是否需要人工补救、是否能稳定复现成功路径 |\n| 工具质量 | 错选工具、漏调工具、参数错误、重复调用、危险操作拦截率 |\n| 上下文成本 | 输入 Token、输出 Token、缓存命中率、压缩后信息保留比例 |\n| 延迟指标 | 首 Token 延迟、端到端耗时、工具等待时间、p95/p99 响应时间 |\n| 结果质量 | 幻觉率、证据引用准确率、摘要丢失率、关键字段遗漏率 |\n\n**建议**: 每次只改一个变量（检索/压缩/工具 Schema/Prompt），否则无法归因效果来源。\n\n### Context Rot 上下文腐化\n\n- 上下文越长 ≠ 效果越好（边际收益递减）\n- Lost in the Middle: 模型对开头和结尾信息更敏感，中间内容易被忽略\n- 关键约束要放在更显眼的位置（开头或独立段）\n- 信噪比 > 绝对量：宁愿少但精，不要多但杂\n\n来源: [上下文工程详解](https://javaguide.cn/ai/agent/context-engineering.html)\n\n## 9. CLI vs MCP vs Skill — AI 工具接入模式对比 (新增 2026-06-21)\n\n唐巧博客总结的 AI 工具接入三件套，对 OpenClaw 的 Skills 架构有直接参考价值：\n\n### 三种模式的本质区别\n\n| 模式 | 比喻 | 特点 | 适用场景 |\n|------|------|------|---------|\n| **CLI** | 工具箱放在柜子里 | 按需取用，不占上下文窗口 | 能访问终端的环境（Claude Code、OpenClaw exec） |\n| **MCP** | 工具常驻在桌面上 | 随取随用，但占上下文空间 | 不能访问终端的桌面端 AI 工具 |\n| **Skill** | 给 AI 的操作手册 | 按需延迟加载，教 AI 如何用工具 | 团队经验沉淀 + 工具使用指导 |\n\n### 核心洞察\n\n- **GUI 服务人类，CLI 服务 AI**：AI 最擅长处理文字，CLI 输入输出都是文字，非常对口\n- **MCP 的代价是上下文窗口**：每接一个 MCP 工具都要在上下文里摆一张说明卡，工具过多会挤占推理空间\n- **CLI 的优势是不占桌面**：工具箱放在柜子里，需要时才打开，用完放回去\n- **Skill 是按需加载的肌肉记忆**：上下文里只放一句话简介，AI 判断需要时才翻开详细内容\n\n### 工作流关系\n```\n用户说一句话\n → AI 判断需要操作什么\n → Skill 告诉 AI 用什么命令、参数怎么填\n → AI 通过 CLI 执行\n → 结果返回\n```\n\n### OpenClaw 映射\n- OpenClaw 的 Skills 本质上是 **CLI + Skill 手册** 的组合\n- exec 工具 = CLI（终端执行）\n- SKILL.md = Skill 手册（延迟加载的操作指南）\n- 与 MCP 的区别：OpenClaw 选择 Skill 而非 MCP，因为 Skills 更轻量、不占上下文窗口\n\n来源: [AI 干活的三件套：CLI、MCP 和 Skill - 唐巧的博客](https://blog.devtang.com/2026/04/03/cli-mcp-skill/)\n\n---\n\n> **Sections 10-18 moved to [anthropic-patterns-advanced.md](./anthropic-patterns-advanced.md)**: 高级模式 — Containment / Managed Agents / Harness Design / Auto Mode / Code Execution with MCP / Context Engineering 官方定义\n\nFile v1.0.1:references/error-taxonomy.md\n\n# 错误分类与处理策略\n\n## 错误分类体系\n\n### L1: 工具调用错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **认证失败** | 401 Unauthorized | 检查 API Key/Token，提示更新 |\n| **权限不足** | 403 Forbidden | 检查权限配置，申请授权 |\n| **资源不存在** | 404 Not Found | 验证 ID/路径，检查拼写 |\n| **限流** | 429 Too Many Requests | 指数退避重试，检查配额 |\n| **服务器错误** | 5xx | 重试或等待，记录到日志 |\n| **超时** | Timeout | 增加超时或优化请求 |\n| **参数错误** | Invalid parameters | 修正参数格式 |\n\n### L2: 工作流错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **Cron 失败** | 任务未执行/执行报错 | 检查 schedule/payload/sessionTarget |\n| **子 Agent 异常** | spawn 失败/超时 | 检查参数/资源/权限 |\n| **消息发送失败** | 投递失败/格式错误 | 检查 channel/target/format |\n| **会话中断** | Session 丢失 | 重建会话，恢复上下文 |\n\n### L3: 系统错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **内存不足** | OOM Killer | 减少并发，使用轻量模式 |\n| **磁盘满** | No space left | 清理临时文件，清理旧日志 |\n| **网络断开** | Connection refused | 检查网络，重试或降级 |\n| **配置损坏** | 解析错误 | 从备份恢复，检查语法 |\n\n### L4: Agent 运行时错误 (新增 2026-07-05)\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|----------|\n| **死循环** | Agent 反复相同操作 | 检查最大迭代轮次 / 重复操作检测 |\n| **误调工具** | 调了不该调的工具 | 检查工具描述清晰度 / Schema 歧义 |\n| **上下文污染** | 越跑越偏 | 检查上下文长度 / 启用 lightContext |\n| **权限越界** | 超出授权范围 | 检查操作分级 / 沙箱边界 |\n| **上下文焦虑** | 提前结束任务 | 较新模型已改善 / Harness 层面 context reset |\n| **Harness 过期** | 补偿逻辑变成死重 | 定期审视精简，随模型升级调整 |\n\n来源: [Anthropic: How we contain Claude](https://www.anthropic.com/engineering/how-we-contain-claude), [Anthropic: Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents), [Agent 工程兜底](https://notes.kamacoder.com/llm/app/agent_failure_modes.html)\n\n## 诊断决策树\n\n```\n错误发生\n│\n├─ 是工具调用错误？\n│ ├─ 认证问题 → 检查凭证\n│ ├─ 权限问题 → 检查授权\n│ ├─ 限流问题 → 退避重试\n│ └─ 参数问题 → 修正格式\n│\n├─ 是工作流错误？\n│ ├─ Cron 问题 → 检查 job 配置\n│ ├─ 子 Agent 问题 → 检查 spawn 参数\n│ └─ 消息问题 → 检查 channel 配置\n│\n└─ 是系统错误？\n ├─ 资源问题 → 释放资源\n └─ 配置问题 → 恢复备份\n```\n\n## L5: 质量退化模式（Agent 智能度/行为异常退化）(新增 2026-07-12)\n\n来源于 Anthropic 2026-04 Postmortem 分析的退化事件。这类错误的特征是**系统看起来正常但表现变差**。\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|----------|\n| **推理级别降级** | 默认 reasoning effort 降低 → 智能度下降 | 不随意降低 thinking 级别；切换模型时重新评估 |\n| **上下文管理 Bug** | Prompt Caching 优化导致推理历史丢失 → 健忘/重复 | 修改 context 配置后必须验证；关注 cache miss 率 |\n| **系统提示过约束** | 限制输出长度 → 编码/推理质量下降 | 简洁≠智能；修改 prompt 后做 ablation 测试 |\n| **模型特定行为变化** | 新模型更啰嗦/更焦虑 → 旧配置不兼容 | 切换模型时全量评估，不要假设行为一致 |\n\n来源: [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)\n\n## 常见错误模式库\n\n### Cron 相关\n\n#### 错误：sessionTarget 与 payload.kind 不匹配\n```\n症状: \"sessionTarget='main' requires payload.kind='systemEvent'\"\n修复: \n - main → systemEvent\n - isolated/current → agentTurn\n```\n\n#### 错误：Cron 任务超时\n```\n症状: \"Task timed out after X seconds\"\n修复:\n - 增加 payload.timeoutSeconds\n - 优化任务内容，减少复杂度\n - 使用子 Agent 处理重型任务\n```\n\n#### 错误：Cron 未触发\n```\n症状: 任务到时间未执行\n诊断:\n 1. cron list 检查 enabled 状态\n 2. 检查 schedule 表达式\n 3. 检查 timezone 配置\n 4. 检查 Gateway 运行状态\n```\n\n### 飞书相关\n\n#### 错误：权限不足\n```\n症状: \"Permission denied\" 或 \"insufficient scope\"\n修复:\n 1. feishu_app_scopes 检查当前权限\n 2. 确认所需 scope\n 3. 在飞书开放平台申请额外权限\n```\n\n#### 错误：Token 过期\n```\n症状: \"Token expired\" 或 \"Invalid token\"\n修复:\n 1. 刷新访问令牌\n 2. 检查 token 刷新机制\n 3. 重新认证\n```\n\n### 网络相关\n\n#### 错误：连接超时\n```\n症状: \"Connection timeout\"\n诊断:\n 1. ping 测试目标主机\n 2. 检查 DNS 解析\n 3. 检查防火墙规则\n 4. 尝试备用端点\n```\n\n## 自动修复规则\n\n### 可自动修复\n- ✅ Cron 任务 disabled → 重新启用\n- ✅ 临时文件清理\n- ✅ 重试限流错误（最多 3 次）\n- ✅ 更新心跳状态文件\n\n### 需确认后修复\n- ⚠️ 修改 Cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n- ⚠️ 删除大量数据\n\n### 不可自动修复\n- ❌ 修改核心身份文件\n- ❌ 发送外部消息（邮件、飞书）\n- ❌ 删除不可恢复的数据\n- ❌ 安装新软件/依赖\n\nFile v1.0.1:references/fix-templates.md\n\n# 常见修复模板库\n\n## Cron 修复模板\n\n### 1. 修复 sessionTarget/payload 不匹配\n\n**诊断**:\n```bash\nopenclaw cron get \n```\n\n**修复命令**:\n```bash\n# 情况 A: main session 需要 systemEvent\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"},\"sessionTarget\":\"main\"}'\n\n# 情况 B: isolated session 需要 agentTurn \nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"agentTurn\",\"message\":\"...\"},\"sessionTarget\":\"isolated\"}'\n```\n\n**验证**:\n```bash\nopenclaw cron runs --limit 1\n```\n\n### 2. 修复超时问题\n\n**诊断**:\n```bash\nopenclaw cron runs \n# 查找 \"timed out\" 或 \"timeout\" 错误\n```\n\n**修复命令**:\n```bash\n# 增加超时时间\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n```\n\n### 3. 修复 disabled 状态\n\n**诊断**:\n```bash\nopenclaw cron list --includeDisabled\n# 查找 enabled: false 的任务\n```\n\n**修复命令**:\n```bash\nopenclaw cron update --patch '{\"enabled\":true}'\n```\n\n### 4. 修复 cron 表达式\n\n**诊断**:\n```bash\nopenclaw cron get \n# 检查 schedule.expr 和 schedule.tz\n```\n\n**修复命令**:\n```bash\n# 更新为正确的 cron 表达式（本地时间）\nopenclaw cron update \\\n --patch '{\"schedule\":{\"kind\":\"cron\",\"expr\":\"0 9 * * 1-5\",\"tz\":\"Asia/Shanghai\"}}'\n```\n\n## 工具修复模板\n\n### 5. 刷新飞书权限\n\n**诊断**:\n```bash\nfeishu_app_scopes\n```\n\n**修复**: 提示用户在飞书开放平台申请所需权限\n\n### 6. 服务健康检查\n\n**诊断**:\n```bash\n# 检查 Docker 服务\ndocker ps --filter \"status=exited\"\n\n# 检查端口\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3004/health # SearXNG\ncurl -s http://localhost:3003/health # Crawl4AI\n```\n\n**修复**:\n```bash\n# 重启特定服务\ncd ~/firecrawl && docker compose up -d\ncd ~/searxng && docker compose up -d\n```\n\n### 7. 清理磁盘空间\n\n**诊断**:\n```bash\ndf -h /\ndu -sh ~/.openclaw/workspace/memory/ 2>/dev/null\ndu -sh ~/.openclaw/workspace/learnings/ 2>/dev/null\n```\n\n**修复**:\n```bash\n# 清理超过 30 天的日志\nfind ~/.openclaw/workspace/memory/ -name \"*.md\" -mtime +30 -delete 2>/dev/null\n\n# 清理 Docker 无用资源\ndocker system prune -f 2>/dev/null\n```\n\n## 子 Agent 修复模板\n\n### 8. 子 Agent 超时\n\n**诊断**:\n```bash\nopenclaw subagents list --recentMinutes 60\n# 查找超时或失败的子 Agent\n```\n\n**修复**:\n```bash\n# 终止卡死的子 Agent\nopenclaw subagents kill \n\n# 重新生成，增加超时\nsessions_spawn(task=\"...\", runTimeoutSeconds=600)\n```\n\n### 9. 子 Agent 上下文过大\n\n**诊断**:\n```bash\nopenclaw sessions list --limit 10\n# 检查 session 大小\n```\n\n**修复**:\n```bash\n# 使用轻量上下文\nsessions_spawn(task=\"...\", lightContext=true)\n\n# 或使用隔离上下文\nsessions_spawn(task=\"...\", context=\"isolated\")\n```\n\n## 系统修复模板\n\n### 10. Gateway 重启\n\n**诊断**:\n```bash\nopenclaw status\n```\n\n**修复**:\n```bash\nopenclaw gateway restart --reason \"优化修复后重启\"\n```\n\n### 11. 内存压力\n\n**诊断**:\n```bash\nfree -m\n# 检查可用内存\n```\n\n**修复**:\n```bash\n# 停止非必要服务\ncd ~/firecrawl && docker compose stop # 按需启动\ncd ~/crawl4ai-server && ... # 检查是否需要\n\n# 或重启 Gateway\nopenclaw gateway restart\n```\n\n## 验证模板\n\n### 质量退化诊断 (新增 2026-07-12)\n\n**诊断**:\n```bash\n# 检查模型是否被变更\nsession_status\n\n# 检查近期配置变更\ngateway config.get\n```\n\n**修复**:\n```bash\n# 恢复推理级别\ngateway config.patch --path 'thinking' --value 'high'\n\n# 恢复模型版本（如果被切换）\nsession_status --model 'qwen/qwen3.6-plus' # 恢复已知稳定模型\n```\n\n**预防**:\n- 修改模型/ thinking / prompt 配置后，跑 3-5 个已知任务验证质量\n- 关注 cache miss 率异常升高（可能意味着上下文管理 Bug）\n- 重要的系统提示变更做 ablation 测试（逐行移除看影响）\n\n### 修复后验证清单\n\n```markdown\n## 修复验证\n- [ ] cron 任务正常运行: `openclaw cron list`\n- [ ] 错误日志无新错误: `cat learnings/error-log.md`\n- [ ] 相关工具可用: 测试调用\n- [ ] 用户通知: 告知修复结果\n```\n\n### 修复报告格式\n\n```markdown\n## 🔧 修复报告\n\n**问题**: [问题描述]\n**根因**: [原因分析]\n**修复**: [执行的操作]\n**状态**: ✅ 已修复 / ⚠️ 部分修复 / ❌ 需要人工干预\n**验证**: [验证结果]\n**后续**: [预防措施或待办事项]\n```\n\nFile v1.0.1:references/openai-patterns.md\n\n# OpenAI Agent 工程最佳实践\n\n## 1. Function Calling Pattern\n\n### 工具定义最佳实践\n```json\n{\n \"name\": \"execute_fix\",\n \"description\": \"执行修复操作\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"action\": {\"type\": \"string\", \"enum\": [\"diagnose\", \"repair\", \"verify\"]},\n \"target\": {\"type\": \"string\"},\n \"parameters\": {\"type\": \"object\"}\n },\n \"required\": [\"action\", \"target\"]\n }\n}\n```\n\n### 并行工具调用\n```\n- 独立诊断步骤并行执行\n- 依赖步骤串行执行\n- 使用工具组管理相关调用\n```\n\n### 工具描述优化 (新增 2026-05-24)\n\n工具描述质量直接影响 Agent 的判断准确性：\n- **使用场景和禁用场景都要写清楚**: 如 \"如果用户问的是网络或内存问题，别调这个工具\"\n- **参数描述要具体**: 包含格式要求和默认值\n- **description 是 LLM 决定是否调用工具的关键依据**\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 2. Agent Loop Pattern\n\n### 经典 ReAct 循环\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nThought: 基于结果调整策略\n... (循环直到解决)\n```\n\n### 改进版：带终止条件\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nReflection: 评估是否接近解决\n- 是 → 输出结论\n- 否 → 继续循环（最大 N 次）\n- 超时 → 输出部分结论 + 后续建议\n```\n\n### Agent Loop 工程要点 (新增 2026-05-24)\n\nAgent Loop 本质是一个 while 循环，每一轮做三件事：\n1. 让 LLM 推理，决定下一步动作\n2. 调用工具并执行\n3. 将工具结果写回上下文\n\n**工程难点**: 上下文管理。任务越跑越久，上下文会越来越长，关键信息被稀释后模型容易跑偏。\n\n**安全兜底**: 设置最大迭代轮次上限（一般 10-20 轮）或 Token 消耗阈值，防止死循环。\n\n**框架封装**: LangChain、LlamaIndex、Spring AI 等框架都封装了 Agent Loop，底层思路一致。\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n### Agent 架构分层 (新增 2026-05-24)\n\nAgent = LLM + Planning + Memory + Tools\n\n| 层 | 职责 | 解决什么问题 |\n|---|------|-------------|\n| **LLM Call** | 模型调用 | 流式输出、Token 截断、重试机制 |\n| **Tools Call** | 外部交互 | Function Calling、MCP、Skills、第三方 API |\n| **Context Engineering** | 上下文管理 | 系统提示词、动态记忆注入、会话状态、工具描述组装 |\n| **Planning** | 推理与规划 | 目标分解、Chain-of-Thought、下一步决策 |\n| **Memory** | 记忆管理 | 短期记忆（上下文历史）、长期记忆（知识库/向量库） |\n| **Observation** | 反馈闭环 | 工具执行结果回传，驱动下一轮推理 |\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n### Agent vs 传统编程 vs Workflow (新增 2026-05-24)\n\n| 类型 | 流程 | 适用场景 |\n|------|------|---------|\n| **传统编程** | 程序员写代码 → 执行 | 逻辑固定、高频执行、高性能要求 |\n| **Workflow** | 产品画流程图 → 执行 | 流程清晰、步骤有限、需可视化管理 |\n| **Agent** | 用户说意图 → AI 决策 → 动态执行 | 步骤不确定、需理解自然语言、动态判断 |\n| **Plan-and-Execute** | Workflow + Agent 混合 | 超长流程中夹杂动态子任务 |\n\n关键判断：**Agent 解决那些没法提前穷举所有情况的问题。**\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 3. Error Recovery Strategies\n\n### 指数退避重试\n```python\ndef retry_with_backoff(func, max_retries=3, base_delay=1):\n for attempt in range(max_retries):\n try:\n return func()\n except Exception as e:\n if attempt == max_retries - 1:\n raise\n delay = base_delay * (2 ** attempt)\n time.sleep(delay)\n```\n\n### 降级链模式\n```\n主方案: API 调用\n ↓ 失败\n降级1: 本地缓存\n ↓ 失败\n降级2: 备用 API\n ↓ 失败\n降级3: 手动提示用户\n```\n\n## 4. State Management\n\n### Checkpoint 模式\n```\n在执行关键操作前保存状态：\n{\n \"checkpoint_id\": \"uuid\",\n \"timestamp\": \"ISO-8601\",\n \"action\": \"正在执行的操作\",\n \"state_snapshot\": \"关键状态快照\",\n \"rollback_instructions\": \"回滚步骤\"\n}\n```\n\n### 会话管理\n```\n- 长会话：定期清理上下文\n- 子会话：隔离运行，完成后回收\n- 共享状态：使用文件系统或数据库\n```\n\n## 5. Evaluation & Testing\n\n### 自愈效果评估\n```\n指标:\n- 首次修复成功率\n- 平均修复时间 (MTTR)\n- 复发率（同一错误再次出现）\n- 误报率（错误诊断）\n\n监控:\n- 错误日志趋势\n- 修复操作成功率\n- 用户反馈评分\n```\n\n### A/B 测试修复策略\n```\n对同一类问题，测试不同修复策略：\n- 策略 A: 立即修复\n- 策略 B: 等待 + 重试\n- 策略 C: 降级到备用方案\n\n记录每种策略的成功率和耗时\n```\n\n## 6. Scalability Patterns\n\n### 工作队列\n```\n- 使用 cron 调度重复任务\n- 使用子 Agent 处理并发任务\n- 使用消息队列（如果可用）处理高峰\n```\n\n### 资源管理\n```\n- 监控 token 使用量\n- 设置并发子 Agent 上限\n- 定期清理临时文件\n- 使用轻量上下文模式\n```\n\n## 7. Observability\n\n### 日志分级\n```\nDEBUG: 详细诊断信息\nINFO: 正常操作流程\nWARNING: 潜在问题\nERROR: 明确的失败\nCRITICAL: 系统级故障\n```\n\n### 指标收集\n```\n- 工具调用成功率\n- 平均响应时间\n- Token 消耗趋势\n- 错误类型分布\n- 修复成功率\n```\n\n## 8. Agent 核心挑战与应对 (新增 2026-05-24)\n\n| 挑战 | 应对策略 |\n|------|---------|\n| **上下文窗口限制** | 分层记忆、上下文压缩、关键信息优先 |\n| **幻觉问题** | 工具调用可降低但不能消灭幻觉；交叉验证关键判断 |\n| **Token 消耗** | 轻量上下文、工具结果精简、子 Agent 隔离复杂任务 |\n| **安全风险** | 权限最小化、沙箱隔离、高危操作人工确认 |\n| **规划能力上限** | LLM 深度多步推理易局部最优；需反思和回溯机制 |\n| **可观测性不足** | 记录 Agent 决策日志、工具调用链、上下文变化追踪 |\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 9. Agent 范式选型矩阵 (新增 2026-05-31)\n\n实际项目中，不同范式很少单独使用，更常见的是组合：\n\n| 场景特征 | 推荐方向 | 代价 |\n|---------|---------|------|\n| 执行路径可提前确定，节点需要 LLM | AI 工作流（Graph） | 稳定可观测，前期设计成本高 |\n| 执行路径不确定，需要动态规划 | ReAct | 灵活，Token 消耗高，调试难 |\n| 任务很长，步骤多但结构清晰 | Plan-and-Execute | 不易迷路，动态调整弱 |\n| 输出质量要求高，允许多轮迭代 | 叠加 Reflection | 和 ReAct/P&E 配合用，不单独用 |\n| 任务天然可拆成多个专业角色 | Multi-Agent | 通信和调试成本翻倍 |\n| 长任务 + 部分子任务不可预测 | Agentic Workflows | 全局 Workflow + 局部 ReAct 嵌套 |\n\n**关键判断准则**：\n1. 能提前写出执行路径的 → 用 Workflow\n2. 写不出执行路径的 → 用 Agent\n3. 两者都有的 → 用 Agentic Workflows\n\n**常见陷阱**：很多人觉得任务\"路径不确定\"，其实是需求没拆清楚。认真拆解后，大部分场景其实是 \"LLM 在固定节点里做生成或判断\"，这种用 Workflow 更稳。\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 10. A2A 协议 — Agent 间结构化通信 (新增 2026-05-31)\n\n单 Agent 升级到 Multi-Agent 后，Agent 之间的通信成为工程问题。\n\n### 问题\n- 自然语言互相聊天 → Token 消耗高、格式解析易出错\n- 类似后端微服务之间不应通过解析 HTML 交换数据\n\n### 解决方案\nA2A 协议让 Agent 之间用**结构化数据**交互：\n- 带 Schema 的 JSON / XML\n- 状态流转指令\n- 标准化 Payload：TaskID、Dependencies、AcceptanceCriteria\n\n### 类比\n后端微服务用 RESTful 或 RPC 接口传结构化对象，而非 HTML 页面。\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 11. 2026 年 AI Agent 框架全景 (新增 2026-05-31)\n\n### 主流框架数据（2026 年 4 月 GitHub Stars）\n\n| 框架 | Stars | 定位 | 语言 |\n|------|-------|------|------|\n| LangChain | 135k | 通用 Agent 平台 | Python |\n| MetaGPT | 67.5k | 多 Agent 软件公司模拟 | Python |\n| AutoGen（微软） | 57.6k | 事件驱动多 Agent 系统 | Python |\n| CrewAI | 50.2k | 角色扮演协作 Agent | Python |\n| LangGraph | 30.7k | 图结构工作流编排 | Python |\n| OpenAI Agents | 25.5k | 轻量多 Agent 框架 | Python |\n| Mastra | 23.4k | TypeScript Agent 框架 | TypeScript |\n\n### 选型指南\n| 场景 | 推荐 | 理由 |\n|------|------|------|\n| 快速原型 / 学习入门 | LangChain 或 OpenAI Agents SDK | 文档完整，10 行代码跑通 |\n| 复杂工作流 / 状态管理 | LangGraph | 图结构支持条件分支、循环、检查点 |\n| 多 Agent 协作 / 企业自动化 | CrewAI 或 AutoGen | CrewAI 角色抽象易用；AutoGen 支持分布式部署 |\n| TypeScript / 全栈 | Mastra | 原生 TS，与 Next.js 无缝集成 |\n| 对接 MCP | 任意框架 | 主流框架均已支持 MCP Client |\n\n### MCP 协议集成趋势\n- MCP 正成为 Agent 工具调用的新标准\n- LangChain、AutoGen、LangGraph 均已支持 MCP Client\n- 工具层：将数据库、API、文件系统封装为 MCP Server\n- 框架层：框架自动将 MCP 工具暴露给 LLM\n\n来源: [AI Agent 框架全景指南](https://www.cnblogs.com/qiniushanghai/p/19952939)\n\n## 12. 最新进展与里程碑 (新增 2026-06-07)\n\n### Claude Opus 4.7 SWE-bench 突破\n- SWE-bench Verified 基准: Claude Opus 4.5 达 80.9%（2026-03）\n- 代码修复能力的重要里程碑\n- 对比 Claude 3.7 Sonnet 在 SWE-bench 上 70.3%（2025-02），一年内提升超 10 个百分点\n\n来源: [LLM 大语言模型研究进展与趋势报告](https://www.cnblogs.com/sddai/p/19758552)\n\n### Think/NoThink 双模式\n- 阿里云 Qwen3 235B-A22B 采用 Think/NoThink 双模式\n- 允许用户动态切换推理深度（类似 OpenClaw 的 `thinking` 参数）\n- 工程启示: 推理深度的按需切换应成为 Agent 框架的标准能力\n\n来源: [LLM 大语言模型研究进展与趋势报告](https://www.cnblogs.com/sddai/p/19758552)\n\n### 框架更新动态\n- **LangGraph v1.0** (2025-10): 稳定版发布，支持人机协作循环和持久化状态管理\n- **Microsoft Agent Framework (MAF)**: AutoGen v0.4 与 Semantic Kernel 合并，提供异步事件驱动的企业级多智能体运行时\n- **OpenClaw**: 持续迭代中，文档见 [docs.openclaw.ai](https://docs.openclaw.ai/zh-CN)\n\n来源: [LLM 大语言模型研究进展与趋势报告](https://www.cnblogs.com/sddai/p/19758552)\n\n### GUI 自动化现状\n- Claude Computer Use 首个商业化 GUI 操作模型\n- OSWorld 基准: 人类平均成功率 72.36%，最先进 AI 仅 12.24%\n- 结论: GUI 自动化仍有重大工程挑战，不建议在高可靠性场景依赖\n\n来源: [LLM 大语言模型研究进展与趋势报告](https://www.cnblogs.com/sddai/p/19758552)\n\n---\n\n> **Sections 13-14 moved to [advanced-optimization.md](./advanced-optimization.md)**: Prompt Caching 优化实践 + 高效智能体框架综述\n\n## 15. Agent 框架全景图更新 (2026-06) \n\n### 新增重要框架\n\n| 框架 | 定位 | 特点 |\n|------|------|------|\n| **PydanticAI** | 类型安全 Agent 开发 | 使用 Python 类型系统约束输出，适合工程化应用 |\n| **Mastra** | 现代全栈 Agent 框架 | 支持 Workflow、Memory、部署和可观测能力 |\n| **Agno（原 Phidata）** | 多 Agent 应用框架 | 强调 Agent + Knowledge + Tools 的组合能力 |\n| **Camel-AI** | 多智能体协作框架 | 通过角色扮演机制模拟团队协作与任务拆解 |\n| **Atomic Agents** | 可组合 Agent 架构 | 强调模块化设计与可测试性 |\n| **DSPy** | 声明式 Prompt / Agent 框架 | 将 Prompt 与推理过程工程化、可优化 |\n\n### 框架选型补充\n\n| 场景 | 推荐 | 理由 |\n|------|------|------|\n| 类型安全 / 工程化 | PydanticAI | Python 类型约束，输出格式有保障 |\n| 可观测性要求高 | Mastra | 内置部署和可观测能力 |\n| Prompt 优化迭代 | DSPy | 声明式、可优化的 Prompt 工程 |\n| 模块化 / 测试驱动 | Atomic Agents | 可组合架构，单元测试友好 |\n\n来源: [AI Agent 教程 - 菜鸟教程](https://www.runoob.com/ai-agent/ai-agent-tutorial.html)\n\n## 16. Agent 范式认知升级 (2026-06)\n\n### 传统程序 vs AI Agent 的本质区别\n\n- **传统程序** = 自动售货机：投币 → 按按钮 → 出商品\n- **AI Agent** = 私人助理：告诉需求 → 助理规划 → 完成任务并汇报\n\n### Agent 核心公式（业界共识）\n\n```\nAgent = LLM (大脑) + Planning (规划) + Tool use (执行) + Memory (记忆)\n```\n\n### 思维转变\n从对话框问答 → 目标驱动的任务执行。Agent 不只是输出内容，而是输出结果并推动执行。\n\n来源: [AI Agent 教程 - 菜鸟教程](https://www.runoob.com/ai-agent/ai-agent-tutorial.html)\n\n## 17. Agent 可观测性三件套 — Trace/Eval/Guardrail (新增 2026-06-28)\n\n传统 APM（Datadog/New Relic）只能告诉你\"服务是否活着\"，但 Agent 的核心问题是\"返回的东西对不对\"——这是质量问题，不是性能问题。语义错误（错误事实、错误建议、错误格式）在传统监控指标里完全隐形。\n\n2026 年，Atlan 将 Agent Observability 列为与 DataOps 平级的新品类。真正的 Agent 可观测性需要三件套：**Trace（追踪）、Eval（评估）、Guardrail（护栏）**。\n\n### Trace：Agent 的眼睛\n\nTrace 解决的问题：一次 Agent 执行发生了什么。\n\n一次完整的 Agent 执行不是黑盒，而是调用链：\n```\n用户查询 → Planner → Tool Call 1 → LLM Call → Tool Call 2 → Response\n```\n\n**Trace 应记录的关键维度**：\n\n| 维度 | 内容 |\n|------|------|\n| 输入/输出 | 每一步的原始 prompt 和 completion |\n| Token 消耗 | 每次 LLM 调用的 input/output token + 成本 |\n| 延迟分布 | 每一跳的耗时，识别瓶颈节点 |\n| 工具调用 | Tool name、参数、返回值、是否成功 |\n| 会话上下文 | session_id、user_id、对话轮次 |\n| 元数据 | 模型版本、temperature、系统 prompt 版本 |\n\n**主流工具对比**：\n\n| 工具 | 类型 | 特点 |\n|------|------|------|\n| LangSmith | 商业 | LangChain 生态，UI 友好，快速落地 |\n| Langfuse | 开源 | 自部署友好，数据不出境首选 |\n| Arize Phoenix | 开源 | Eval 集成最深，适合重度评估 |\n| OpenTelemetry Gen AI | 标准 | 厂商中立，2025 年底进入 Beta，长期押注方向 |\n\n> **建议**: 现在做 Trace，用 OTEL 兼容的 SDK 封装，避免强绑定单一工具。\n\n### Eval：Agent 的判断力\n\nEval 解决的问题：Agent 说的对不对。\n\n**三层 Eval 架构**：\n\n| 层级 | 评估什么 | 方法 |\n|------|---------|------|\n| **Unit Eval**（单步） | 某一步输出是否正确 | 确定性规则/小型分类器 |\n| **Trajectory Eval**（轨迹） | 执行链路决策路径是否合理 | 标准轨迹参照/LLM-as-Judge |\n| **E2E Eval**（端到端） | 最终响应对用户的实际价值 | LLM-as-Judge/人工标注 |\n\n**LLM-as-Judge 的陷阱与缓解**：\n- ⚠️ 位置偏差：Judge 倾向给第一个选项打高分\n- ⚠️ 冗长偏差：更长回答容易得更高评分\n- ⚠️ 自我偏好：同模型评估有系统性偏见\n- ✅ 缓解：多 Judge 投票、结构化评分维度、定期人工校准\n\n**Eval 数据集维护**：\n- 初始集：历史日志挑选 200-500 条覆盖主要场景\n- 黄金集：人工标注校准自动化评分器\n- 回归集：发现 Bad Case 后加入，防止复现\n- 维护频率：每 2 周评估漂移，季度全量更新\n\n### Guardrail：Agent 的刹车\n\nGuardrail 解决的问题：不该发生的事情不发生。Eval 是事后的，Guardrail 是实时的。\n\n**输入护栏**：\n- Prompt 注入检测\n- 越权查询检测\n- 敏感话题过滤\n\n**输出护栏**：\n- PII 检测（身份证号、手机号、银行卡号）\n- 事实性检查（价格、政策条款规则校验）\n- 格式合规\n- 有害内容过滤\n\n**主流工具**：NVIDIA NeMo Guardrails（开源企业级）、Guardrails AI（Python 友好）、Lakera Guard（Prompt 注入最强）、Azure AI Content Safety。\n\n> **警告**: 护栏不是越严越好。需要同时监控误杀率（false positive）和漏过率（false negative）。每条规则上线前应用历史数据评估误杀率。\n\n### 三件套协同关系\n\n```\nTrace 数据 → Eval 发现 Bad Case → 更新 Guardrail 规则 → 持续运转的闭环\n```\n\n- **Trace 是眼睛**：记录一切，为 Eval 提供原材料，为调试提供回放能力\n- **Eval 是判断力**：分析 Trace 数据，识别质量问题，驱动护栏规则迭代\n- **Guardrail 是刹车**：实时拦截，消费 Eval 输出持续优化规则\n\n### 落地 Roadmap（建议分阶段）\n\n| 阶段 | 内容 | 周期 |\n|------|------|------|\n| Week 1-2 | 接入 Trace，确保每次 LLM 调用被记录 | 从 Langfuse 开源版起步 |\n| Week 3-4 | 建立 Eval 数据集，跑通自动化评估 | 初始 200 条用例 |\n| Week 5-6 | 上线核心 Guardrail 规则 | 先防 PII 和注入 |\n| 持续 | 三者闭环迭代 | 每 2 周评估漂移 |\n\n### OpenClaw 映射\n\n| 实践 | OpenClaw 对应 |\n|------|-------------|\n| Trace | session history + learnings/error-log.md |\n| Eval | 修复后验证清单 + 修复成功率统计 |\n| Guardrail | 操作分级（L0-L3）+ 禁止自动执行规则 |\n| 误杀率监控 | SOUL.md 安全规则不扼杀正常使用 |\n\n来源: [Agent 可观测性三件套](https://www.cnblogs.com/shisuidata/p/19940523), [AI Agent 可观测性工程](https://zhuanlan.zhihu.com/p/2049135443573224105)\n\n## 18. Agent 工程兜底 — 翻车模式与兜底机制 (新增 2026-07-05)\n\n从 Demo 到生产，Agent 最关键的差距在于**兜底机制**。以下是生产环境中 Agent 的典型故障模式及应对策略。\n\n### 典型故障模式\n\n| 故障类型 | 症状 | 根因 | 兜底方案 |\n|---------|------|------|----------|\n| **死循环** | Agent 反复执行相同操作 | 缺乏终止条件 / 工具返回值误导 | 最大迭代轮次上限 + 重复操作检测 |\n| **误调工具** | 调了不该调的工具 | 工具描述不清晰 / Schema 歧义 | 工具 Use/禁用场景明确标注 + 关键操作二次确认 |\n| **上下文污染** | 越跑越偏，输出质量下降 | 上下文过长关键信息被稀释 | 定期压缩 / 关键约束置顶 / 子 Agent 隔离 |\n| **权限越界** | 执行了超出授权范围的操作 | 权限模型设计缺陷 | 环境级沙箱 + 最小权限原则 + 凭证不入沙箱 |\n| **上下文焦虑** | 模型感知到上下文将满，提前结束任务 | 上下文窗口限制 | 较新模型已改善此问题；Harness 层面增加 context reset |\n\n### 兜底设计原则\n\n1. **硬上限优于软约束**：最大迭代次数 > \"请你在 N 步内完成\" 的 prompt 提示\n2. **环境防御 > 模型防御**：沙箱边界比 \"请不要做 X\" 可靠得多\n3. **可观测性是前提**：没有 Trace，出了问题无法归因\n4. **Harness 会过期**：随模型能力提升，补偿逻辑可能变成死重，需要定期审视精简\n\n### OpenClaw 映射\n\n| 故障 | OpenClaw 应对 |\n|------|-------------|\n| 死循环 | `runTimeoutSeconds` + 子 Agent 隔离 |\n| 误调工具 | SKILL.md 中明确工具 Use/禁用场景 |\n| 上下文污染 | `lightContext` + `context=\"isolated\"` |\n| 权限越界 | 操作分级 L0-L3 + exec 工作区限制 |\n\n来源: [AI Agent 学习路线 — 第五步：工程兜底](https://notes.kamacoder.com/llm/app/agent_failure_modes.html), [卡码大模型专栏](https://notes.kamacoder.com/llm/)\n\nFile v1.0.1:references/self-evolution.md\n\n# 优化师自我进化工作流\n\n## 触发方式\n\n### Cron 自动触发\n- 每周日 03:00 执行一次（cron 任务：agent-optimizer-self-update）\n- 执行环境：isolated session, agentTurn\n\n### 手动触发\n- 用户说\"更新优化师的工程实践\"\n\n## 执行步骤\n\n### Step 1: 收集最新工程实践\n\n```bash\n# Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+claude+agent+engineering+tool+use+patterns+best+practices&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+structured+outputs+error+recovery&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# 行业 Agent 架构趋势\ncurl -s \"http://localhost:3004/search?q=llm+agent+architecture+patterns+self+healing+error+recovery+2026&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:3]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n```\n\n### Step 2: 对比与更新\n\n读取搜索结果后，对比以下文件：\n\n| 文件 | 检查内容 | 更新方式 |\n|------|---------|---------|\n| anthropic-patterns.md | 是否有新 Thinking/Tool Use 模式 | 追加新条目（>400 行则拆分到 -advanced.md） |\n| anthropic-patterns-advanced.md | 是否有高级架构/安全/评估模式 | 追加新条目 |\n| openai-patterns.md | 是否有新 Agent 模式 | 追加新条目 |\n| error-taxonomy.md | 是否有新错误类型 | 新增分类 |\n| fix-templates.md | 是否有新修复方法 | 新增模板 |\n\n### Step 3: 清理过时内容\n\n检查 references/ 中的内容：\n- 标记已废弃的实践（用 `⚠️ 已废弃` 前缀）\n- 保留历史版本供参考\n- 不删除任何内容，只做标记\n\n### Step 4: 更新版本号\n\n在 SKILL.md 末尾的版本表中添加新记录：\n\n```markdown\n| v{x.y} | YYYY-MM-DD | 更新说明 |\n```\n\n## 更新规则\n\n### 必须满足\n- 只在确认有**新信息**时才更新\n- 更新内容必须**可验证**（有来源链接）\n- 更新后检查 SKILL.md 行数是否超过 400，超过则拆分\n- 更新后检查 anthropic-patterns.md 行数是否超过 400，超过则拆分为基础篇（§1-9）和高级篇（新文件 anthropic-patterns-advanced.md，§10+）\n\n### 禁止\n- 删除已有内容\n- 替换经过验证有效的实践\n- 添加未经验证的\"最佳实践\"\n\n## 输出格式\n\n更新完成后输出简要报告：\n\n```\n🔧 优化师自我进化完成\n\n新增: X 条工程实践\n- [条目1] - 来源\n- [条目2] - 来源\n\n更新: Y 条已有内容\n- [条目1] - 变更说明\n\n废弃: Z 条过时实践\n- [条目1] - 废弃原因\n```\n\nFile v1.0.1:skill-card.md\n\n## Description:
\nAgent 优化专家 helps diagnose and repair OpenClaw agent execution problems, including cron failures, tool errors, workflow interruptions, and performance degradation.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[tuobadaidai](https://clawhub.ai/user/tuobadaidai)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and operators use this skill to inspect OpenClaw runtime health, classify cron, tool, sub-agent, and system failures, and produce repair guidance or commands for review before execution.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can persistently change its own guidance and reference files through self-evolution behavior.
\nMitigation: Disable or gate the weekly self-update path and require human review for changes to SKILL.md and references before enabling the skill.
\nRisk: The skill can propose high-impact repairs such as cron edits, service restarts, docker cleanup, file deletion, or killing subagents.
\nMitigation: Require explicit human confirmation before any high-impact repair action is executed.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/tuobadaidai/skills/agent-optimization-expert)
\n- [Trigger integration](TRIGGER-INTEGRATION.md)
\n- [Advanced optimization](references/advanced-optimization.md)
\n- [Anthropic patterns](references/anthropic-patterns.md)
\n- [Anthropic advanced patterns](references/anthropic-patterns-advanced.md)
\n- [OpenAI patterns](references/openai-patterns.md)
\n- [Error taxonomy](references/error-taxonomy.md)
\n- [Fix templates](references/fix-templates.md)
\n- [Self evolution](references/self-evolution.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Analysis, Markdown, Shell commands, Configuration instructions, Guidance]
\n**Output Format:** [Markdown with inline shell commands and diagnostic checklists]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May propose high-impact system repair actions that require human confirmation before execution.]
\n\n## Skill Version(s):
\n1.0.1 (source: server-resolved release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.1:TRIGGER-INTEGRATION.md\n\n# Agent 架构与工程优化师 - 触发机制集成\n\n## 自动触发条件\n\n以下场景自动触发 agent-optimizer skill：\n\n### 1. Cron 执行失败\n- 任务超时\n- Payload schema 错误\n- Session target 不匹配\n- 连续 2 次以上失败\n\n### 2. 工具调用异常\n- API 返回错误状态码\n- 权限不足\n- 网络连接失败\n- 超时或限流\n\n### 3. 工作流中断\n- 子 Agent 异常退出\n- 消息发送失败\n- 会话状态丢失\n\n### 4. 性能退化\n- 响应时间显著增加\n- Token 消耗异常增长\n- 错误率上升\n\n## 触发方式\n\n### 自动触发\n当检测到上述问题时，小七应：\n1. 读取 `skills/agent-optimizer/SKILL.md`\n2. 按照诊断工作流执行\n3. 输出修复建议\n4. 用户确认后执行修复\n5. 验证并记录\n\n### 手动触发\n用户明确要求时：\n- \"检查一下系统问题\"\n- \"优化一下配置\"\n- \"诊断一下为什么失败\"\n\n## 集成到现有流程\n\n### Heartbeat 集成\n在 HEARTBEAT.md 中添加优化师巡检：\n\n```markdown\n# 🔄 Agent 健康度检查（每月一次）\n- 读取 learnings/error-log.md，分析错误趋势\n- 检查 cron 任务成功率\n- 评估 token 使用效率\n- 输出优化建议\n```\n\n### 错误处理集成\n在工具调用失败后：\n1. 记录错误到 learnings/error-log.md\n2. 判断是否触发优化师\n3. 执行诊断和修复\n\n## 权限与安全\n\n### 自动执行范围\n- ✅ 读取日志和状态\n- ✅ 临时文件清理\n- ✅ 重试限流错误（≤3次）\n- ✅ 更新心跳文件\n\n### 需确认操作\n- ⚠️ 修改 cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n\n### 禁止自动执行\n- ❌ 修改核心身份文件（SOUL.md/IDENTITY.md）\n- ❌ 发送外部消息\n- ❌ 删除不可恢复数据\n\nArchive v1.4.0: 10 files, 18026 bytes\n\nFiles: _meta.json (144b), references/anthropic-patterns.md (2894b), references/dual-env-adaptation.md (3379b), references/error-taxonomy.md (3701b), references/fix-templates.md (3873b), references/openai-patterns.md (3087b), references/self-evolution.md (2718b), skill-card.md (2632b), SKILL.md (8780b), TRIGGER-INTEGRATION.md (1726b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: agent-optimization-expert\nversion: 1.4.0\ndescription: >\n Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化），\n 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。\n Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、\n 诊断失败原因、修复任务失败、优化师自我更新、Agent优化、巡检系统.\n 不适用于业务逻辑问题排查、飞书内容编辑、数据查询类任务.\n---\n\n# Agent 优化专家\n\n## 概述\n\n基于 Anthropic / OpenAI 工程实践的 Agent 自愈引擎，覆盖「检测 → 诊断 → 修复 → 验证 → 学习 → 进化」闭环。\n**兼容 OpenClaw 和 Hermes Agent 双环境**，自动识别当前平台并切换对应命令。\n\n### 功能范围\n\n- Cron 任务诊断与修复（失败/超时/disabled/配置错误）\n- 工具调用异常诊断（认证/权限/限流/超时/参数）\n- 子 Agent 异常诊断（spawn 失败/超时/上下文过大）\n- 系统健康度巡检（资源/网络/磁盘/内存）\n- **自我进化**：定期收集工程实践、更新 references/、沉淀新模式\n- 错误模式学习与沉淀（learnings/error-log.md → fix-templates.md 自动升级）\n\n---\n\n## 使用\n\n### 场景 1：Cron 任务执行失败\n\n> **双环境适配**：OpenClaw 走 `openclaw cron` CLI，Hermes 走 `cronjob` 工具。\n> 完整命令映射表和修复规则见 `references/dual-env-adaptation.md`\n\n**快速诊断流程（通用）：**\n1. 列出所有 Cron 任务，检查 enabled/schedule/最近运行状态\n2. 定位失败 job，查看错误输出\n3. 对照 `references/fix-templates.md` 执行修复\n4. 手动触发一次验证修复结果\n\n**常见修复类型：**\n- **未执行** → 检查 enabled / schedule 表达式 / timezone\n- **执行报错** → 检查错误输出 → 对照 fix-templates.md\n- **超时** → timeout 加倍，若仍超时则拆分逻辑\n- **disabled** → 重新启用\n\n---\n\n### 场景 2：工具调用连续失败\n\n```bash\n# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限（双环境通用）\necho $API_KEY | wc -c # 检查 key 是否存在\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)\n```\n\n---\n\n### 场景 3：系统健康度巡检\n\n```bash\n# 资源检查（通用）\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查（通用）\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# Agent 平台状态\n# OpenClaw → openclaw status\n# Hermes → ps aux | grep hermes\n```\n\n---\n\n### 场景 4：子 Agent 异常\n\n**OpenClaw**：`openclaw subagents list` 查看 → `openclaw subagents kill ` 终止\n**Hermes**：子 Agent 同步执行不卡死，超时检查 delegate_task timeout；Cron 子任务卡住用 `process(action='kill')`\n\n---\n\n## 自动触发机制\n\n> 本 Skill 不会自己跑起来，需要环境提供\"心跳\"或\"定时\"机制。\n> **双环境适配完整指南**（含 Cron Job 配置命令 + HEARTBEAT.md 配置模板）→ `references/dual-env-adaptation.md`\n\n**一句话总结：**\n- **Hermes 环境** → 用 `cronjob(action='create')` 创建每日自检 + 每周知识更新\n- **OpenClaw 环境** → 在 `workspace/HEARTBEAT.md` 中配置心跳检查清单\n\n---\n\n## 诊断决策树\n\n```\n问题出现\n│\n├─ Cron 相关？\n│ ├─ 任务未执行 → 检查 enabled / schedule / timezone\n│ ├─ 执行报错 → 查错误输出 → 对照 fix-templates.md\n│ └─ 超时 → timeout 加倍 or 拆分逻辑\n│\n├─ 工具调用相关？\n│ ├─ 401/403 → 认证/权限\n│ ├─ 429 → 指数退避重试\n│ ├─ 5xx → 等待重试 + 记录\n│ └─ 超时 → 网络检查 → 降级\n│\n├─ 子 Agent 相关？\n│ ├─ spawn 失败 → task 过大 / 资源不足\n│ ├─ 超时 → 增加 timeout / 优化 task\n│ └─ 结果异常 → context 模式检查\n│\n└─ 系统相关？\n ├─ 磁盘满 → 清理 + docker prune\n ├─ 内存不足 → 停服务 + lightContext\n └─ 网络断开 → DNS / 防火墙\n```\n\n---\n\n## 自愈闭环\n\n```\n检测（心跳/用户反馈/错误日志）\n → 诊断（快速扫描 → 错误分析 → 根因推理 → 修复建议）\n → 修复（最小变更 + 可回滚）\n → 验证（修复后确认）\n → 学习（记录到 learnings/error-log.md）\n```\n\n### 错误日志格式（learnings/error-log.md）\n\n```markdown\n## YYYY-MM-DD HH:MM\n- **Error**: [错误描述]\n- **Context**: [触发场景]\n- **Root Cause**: [根因分析]\n- **Fix Applied**: [修复操作]\n- **Prevention**: [避免复现的措施]\n```\n\n---\n\n## 操作分级与安全\n\n| 级别 | 范围 | 策略 |\n|------|------|------|\n| L0 | 读取状态、检查日志 | 自动执行 |\n| L1 | 清理临时文件、更新日志 | 自动执行 |\n| L2 | 修改 cron 配置、重启服务 | 提示用户确认 |\n| L3 | 修改核心配置、删除数据 | 必须用户明确授权 |\n\n**禁止自动执行**：\n- ❌ 修改 SOUL.md / IDENTITY.md / USER.md\n- ❌ 发送外部消息（邮件/飞书/社交）\n- ❌ 删除不可恢复的数据\n\n---\n\n## 自我进化机制\n\n### 路径 1：错误驱动进化（每次诊断后）\n\n```\n修复完成\n├─ 新错误类型？→ 新增 error-taxonomy + fix-templates\n├─ 修复可复用？→ 写入 fix-templates\n└─ 涉及工程模式？→ 更新对应 references/\n```\n\n### 路径 2：定期知识更新（每周）\n\n1. SearXNG 搜索 Anthropic/OpenAI 最新工程文档\n2. 对比 references/ 现有内容\n3. 发现新模式追加到对应文件\n4. 标记已过时实践（不删除，标「⚠️ 已废弃」）\n\n```bash\ncurl -s \"http://localhost:3004/search?q=anthropic+agent+engineering+best+practices+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n```\n\n### 路径 3：错误日志驱动进化\n\nlearnings/error-log.md 中相同错误模式 ≥3 次时：\n1. 创建/更新 fix-templates.md 对应模板\n2. 更新 error-taxonomy.md 优先级\n3. 新型错误新增分类条目\n\n---\n\n## 参考文件\n\n| 文件 | 何时读取 |\n|------|---------|\n| [references/dual-env-adaptation.md](references/dual-env-adaptation.md) | **首次使用必读** — 环境检测、命令映射、Cron/HEARTBEAT 配置 |\n| [references/anthropic-patterns.md](references/anthropic-patterns.md) | 需要 Thinking/Tool Use/多 Agent 协调模式 |\n| [references/openai-patterns.md](references/openai-patterns.md) | 需要 ReAct 循环/降级链/评估模式 |\n| [references/error-taxonomy.md](references/error-taxonomy.md) | 工具调用失败分类诊断 |\n| [references/fix-templates.md](references/fix-templates.md) | 确认修复方案后查具体命令 |\n| [references/self-evolution.md](references/self-evolution.md) | 自我进化：收集最新实践 |\n\n---\n\n## 首次运行协议\n\n首次被加载时（检查 `learnings/error-log.md` 不存在或为空），自动执行一次完整自检：\n\n1. **系统健康度巡检**（场景 3）：磁盘/内存/容器/本地服务\n2. **Cron 任务扫描**（场景 1）：检查最近失败的 job\n3. **输出简短报告**：\n - ✅ 一切正常 → \"已就位，系统健康\"\n - ⚠️ 发现问题 → \"已就位，发现 X 个问题：[列表]\"\n4. **创建 learnings/error-log.md**，记录\"首次自检完成\"\n5. **后续不再自动触发**，等待用户指令或 Cron 调度\n\n> 目的：给用户即时反馈，确认 Skill 已正确安装且能正常工作（Smoke Test）。\n\n---\n\n## 版本与更新记录\n\n| 版本 | 日期 | 更新内容 |\n|------|------|----------|\n| v1.0 | 2026-05-18 | 初始创建（四层骨架 + 诊断决策树 + 修复模板） |\n| v1.1 | 2026-05-18 | 添加自我进化机制（三条路径） |\n| v1.3 | 2026-05-20 | **双环境适配**：兼容 OpenClaw + Hermes，环境自动检测、双路径命令映射、HEARTBEAT.md 与 Cron Job 双触发机制 |\n| v1.4 | 2026-05-20 | **首次运行协议**：安装后首次加载自动执行 Smoke Test 自检，给用户即时反馈 |\n\nFile v1.4.0:_meta.json\n\n{\n \"ownerId\": \"kn70tx725606ywwb5gfj0vpxjx83admr\",\n \"slug\": \"agent-optimization-expert\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1779242122082\n}\n\nFile v1.4.0:references/anthropic-patterns.md\n\n# Anthropic 工程实践模式\n\n## 1. Extended Thinking Pattern\n\nAnthropic Claude 的核心优势是 extended thinking（扩展思考）模式。\n\n### 使用场景\n- 复杂问题分解\n- 多步骤推理\n- 代码架构设计\n- 错误诊断与修复\n\n### 实践要点\n```\n1. 在思考阶段明确列出假设\n2. 对每个假设进行验证\n3. 记录推理链条\n4. 最终输出时提炼结论，隐藏中间过程\n```\n\n### OpenClaw 映射\n- `thinking` 参数控制思考级别\n- 复杂诊断任务启用 thinking 模式\n- 子 Agent 使用 thinking 进行深度分析\n\n## 2. Tool Use Best Practices\n\n### 预检-执行-后检模式\n```\n预检: 验证输入参数、权限、依赖状态\n执行: 调用工具，带超时和重试\n后检: 验证结果完整性、一致性\n```\n\n### 错误处理策略\n```\n1. 捕获具体错误类型（非通用异常）\n2. 分类处理：\n - 可重试：指数退避重试\n - 需修正：调整参数重试\n - 不可恢复：降级到备用方案\n3. 记录错误模式到学习库\n```\n\n## 3. Multi-Agent Coordination\n\n### 子 Agent 使用原则\n```\n- context=\"isolated\"：新任务，无需上下文\n- context=\"fork\"：需要当前对话上下文\n- runTimeoutSeconds：设置合理超时\n- 使用 sessions_yield 等待完成，不轮询\n```\n\n### 通信模式\n```\n主 Agent → 子 Agent: sessions_spawn(task, taskName)\n子 Agent → 主 Agent: 完成事件自动传递\n主 Agent ↔ 子 Agent: sessions_send 进行中途交互\n```\n\n## 4. Prompt Engineering Patterns\n\n### 结构化输出\n```\n使用明确的输出格式要求：\n- JSON schema 定义\n- Markdown 模板\n- 明确的字段名称\n```\n\n### 角色分离\n```\n不同任务使用不同的角色提示：\n- 诊断模式：\"你是一个系统诊断专家...\"\n- 修复模式：\"你是一个运维工程师...\"\n- 优化模式：\"你是一个性能调优专家...\"\n```\n\n### 自反思模式\n```\n在关键决策后添加：\n\"在继续之前，请反思你的分析：\n1. 是否遗漏了重要信息？\n2. 假设是否合理？\n3. 有没有其他可能的解释？\"\n```\n\n## 5. Context Management\n\n### 上下文优化\n```\n- 使用 memory_search 检索相关信息，而非全部加载\n- 大型文件使用 offset/limit 分段读取\n- 子 Agent 使用 lightContext 减少 token\n- 定期清理过期的 session 状态\n```\n\n### Token 预算\n```\n诊断任务：< 5000 tokens\n修复任务：< 10000 tokens\n复杂分析：使用子 Agent 隔离\n```\n\n## 6. Safety & Guardrails\n\n### 操作分级\n```\nL0 - 安全：读取文件、检查状态\nL1 - 低风险：修改临时文件、更新日志\nL2 - 中风险：修改配置、重启服务\nL3 - 高风险：删除数据、修改核心配置\n\nL0-L1: 自动执行\nL2: 提示用户确认\nL3: 必须用户明确授权\n```\n\n### 审计日志\n```\n所有 L2+ 操作记录到：\n- learnings/error-log.md\n- memory/YYYY-MM-DD.md\n- 包含：操作时间、内容、原因、结果\n```\n\nFile v1.4.0:references/dual-env-adaptation.md\n\n# 双环境适配指南（OpenClaw + Hermes）\n\n本 Skill 同时兼容 OpenClaw 和 Hermes Agent。所有诊断逻辑一致，仅执行层命令不同。\n\n## 环境自动检测\n\n```bash\nif command -v hermes &>/dev/null; then\n PLATFORM=\"hermes\"\n CMD=\"hermes\"\nelif command -v openclaw &>/dev/null; then\n PLATFORM=\"openclaw\"\n CMD=\"openclaw\"\nelse\n if [ -d \"$HOME/.hermes\" ]; then\n PLATFORM=\"hermes\"\n CMD=\"hermes\"\n else\n PLATFORM=\"openclaw\"\n CMD=\"openclaw\"\n fi\nfi\n```\n\n## 命令映射表\n\n| 操作 | OpenClaw 命令 | Hermes 工具/命令 |\n|------|---------------|------------------|\n| 列出 Cron | `openclaw cron list --includeDisabled` | `cronjob(action='list')` |\n| 查看运行历史 | `openclaw cron runs ` | `cronjob(action='list')` 查看 last output |\n| 更新 Cron | `openclaw cron update --patch '...'` | `cronjob(action='update', job_id='xxx', ...)` |\n| 重新启用 | `openclaw cron update --patch '{\"enabled\":true}'` | `cronjob(action='resume', job_id='xxx')` |\n| 手动触发 | `openclaw cron run ` | `cronjob(action='run', job_id='xxx')` |\n| 子 Agent 列表 | `openclaw subagents list` | 不适用（delegate_task 同步执行） |\n| 终止子 Agent | `openclaw subagents kill ` | `process(action='kill', session_id='xxx')` |\n| 状态检查 | `openclaw status` | `ps aux \\| grep hermes` |\n\n## 自动触发机制\n\n### Hermes 环境：Cron Job\n\n```\n# 每日自检\ncronjob(action='create',\n name='🔧 Agent 每日自检',\n schedule='0 8 * * *',\n prompt='执行 agent-optimization-expert 场景 3（系统健康度巡检）和场景 1（Cron 任务扫描）。检查磁盘/内存/容器/本地服务/所有 cron jobs。如有异常按诊断决策树修复并记录到 learnings/error-log.md。无异常只记录\"一切正常\"。',\n deliver='local')\n\n# 每周知识更新\ncronjob(action='create',\n name='📚 Agent 知识更新',\n schedule='0 3 * * 0',\n prompt='执行 agent-optimization-expert 路径 2（定期知识更新）：搜索 Anthropic/OpenAI 最新 Agent 工程实践，对比 references/ 现有内容，发现新模式追加到对应文件。',\n deliver='local')\n```\n\n### OpenClaw 环境：HEARTBEAT.md\n\n在 `workspace/HEARTBEAT.md` 中配置：\n\n```markdown\n## Agent 自检配置\n- **自检频率**：每 4 小时一次\n- **工作时间**（9:00-18:00）：检查任务 + 系统健康 + 消息\n- **非工作时间**（18:00-9:00）：仅检查紧急任务\n- **触发 Skill**：发现异常时加载 agent-optimization-expert 诊断修复\n\n## 检查清单\n- [ ] Cron 任务是否有失败（最近 24 小时）\n- [ ] 本地服务是否健康（3002/3003/3004）\n- [ ] 磁盘使用率是否 > 85%\n- [ ] learnings/error-log.md 是否有新增错误\n```\n\n## 修复规则差异\n\n| 问题 | OpenClaw 修复 | Hermes 修复 |\n|------|--------------|------------|\n| sessionTarget/payload 不匹配 | `--patch '{\"payload\":{\"kind\":\"systemEvent\"}}'` | 不适用（Hermes 无此概念） |\n| Cron prompt 过长 | 拆分 payload 逻辑 | 缩短 prompt 或拆成多 job |\n| 工具未启用 | 检查 openclaw.json | 检查 cronjob 的 enabled_toolsets |\n| 工作路径不对 | 不适用 | 检查 cronjob 的 workdir |\n\n## 触发方式选择决策\n\n```\n当前环境？\n├─ Hermes → Cron Job（方式 A）\n└─ OpenClaw → HEARTBEAT.md（方式 B）\n```\n\nFile v1.4.0:references/error-taxonomy.md\n\n# 错误分类与处理策略\n\n## 错误分类体系\n\n### L1: 工具调用错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **认证失败** | 401 Unauthorized | 检查 API Key/Token，提示更新 |\n| **权限不足** | 403 Forbidden | 检查权限配置，申请授权 |\n| **资源不存在** | 404 Not Found | 验证 ID/路径，检查拼写 |\n| **限流** | 429 Too Many Requests | 指数退避重试，检查配额 |\n| **服务器错误** | 5xx | 重试或等待，记录到日志 |\n| **超时** | Timeout | 增加超时或优化请求 |\n| **参数错误** | Invalid parameters | 修正参数格式 |\n\n### L2: 工作流错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **Cron 失败** | 任务未执行/执行报错 | 检查 schedule/payload/sessionTarget |\n| **子 Agent 异常** | spawn 失败/超时 | 检查参数/资源/权限 |\n| **消息发送失败** | 投递失败/格式错误 | 检查 channel/target/format |\n| **会话中断** | Session 丢失 | 重建会话，恢复上下文 |\n\n### L3: 系统错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **内存不足** | OOM Killer | 减少并发，使用轻量模式 |\n| **磁盘满** | No space left | 清理临时文件，清理旧日志 |\n| **网络断开** | Connection refused | 检查网络，重试或降级 |\n| **配置损坏** | 解析错误 | 从备份恢复，检查语法 |\n\n## 诊断决策树\n\n```\n错误发生\n│\n├─ 是工具调用错误？\n│ ├─ 认证问题 → 检查凭证\n│ ├─ 权限问题 → 检查授权\n│ ├─ 限流问题 → 退避重试\n│ └─ 参数问题 → 修正格式\n│\n├─ 是工作流错误？\n│ ├─ Cron 问题 → 检查 job 配置\n│ ├─ 子 Agent 问题 → 检查 spawn 参数\n│ └─ 消息问题 → 检查 channel 配置\n│\n└─ 是系统错误？\n ├─ 资源问题 → 释放资源\n └─ 配置问题 → 恢复备份\n```\n\n## 常见错误模式库\n\n### Cron 相关\n\n#### 错误：sessionTarget 与 payload.kind 不匹配\n```\n症状: \"sessionTarget='main' requires payload.kind='systemEvent'\"\n修复: \n - main → systemEvent\n - isolated/current → agentTurn\n```\n\n#### 错误：Cron 任务超时\n```\n症状: \"Task timed out after X seconds\"\n修复:\n - 增加 payload.timeoutSeconds\n - 优化任务内容，减少复杂度\n - 使用子 Agent 处理重型任务\n```\n\n#### 错误：Cron 未触发\n```\n症状: 任务到时间未执行\n诊断:\n 1. cron list 检查 enabled 状态\n 2. 检查 schedule 表达式\n 3. 检查 timezone 配置\n 4. 检查 Gateway 运行状态\n```\n\n### 飞书相关\n\n#### 错误：权限不足\n```\n症状: \"Permission denied\" 或 \"insufficient scope\"\n修复:\n 1. feishu_app_scopes 检查当前权限\n 2. 确认所需 scope\n 3. 在飞书开放平台申请额外权限\n```\n\n#### 错误：Token 过期\n```\n症状: \"Token expired\" 或 \"Invalid token\"\n修复:\n 1. 刷新访问令牌\n 2. 检查 token 刷新机制\n 3. 重新认证\n```\n\n### 网络相关\n\n#### 错误：连接超时\n```\n症状: \"Connection timeout\"\n诊断:\n 1. ping 测试目标主机\n 2. 检查 DNS 解析\n 3. 检查防火墙规则\n 4. 尝试备用端点\n```\n\n## 自动修复规则\n\n### 可自动修复\n- ✅ Cron 任务 disabled → 重新启用\n- ✅ 临时文件清理\n- ✅ 重试限流错误（最多 3 次）\n- ✅ 更新心跳状态文件\n\n### 需确认后修复\n- ⚠️ 修改 Cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n- ⚠️ 删除大量数据\n\n### 不可自动修复\n- ❌ 修改核心身份文件\n- ❌ 发送外部消息（邮件、飞书）\n- ❌ 删除不可恢复的数据\n- ❌ 安装新软件/依赖\n\nFile v1.4.0:references/fix-templates.md\n\n# 常见修复模板库\n\n## Cron 修复模板\n\n### 1. 修复 sessionTarget/payload 不匹配\n\n**诊断**:\n```bash\nopenclaw cron get \n```\n\n**修复命令**:\n```bash\n# 情况 A: main session 需要 systemEvent\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"},\"sessionTarget\":\"main\"}'\n\n# 情况 B: isolated session 需要 agentTurn \nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"agentTurn\",\"message\":\"...\"},\"sessionTarget\":\"isolated\"}'\n```\n\n**验证**:\n```bash\nopenclaw cron runs --limit 1\n```\n\n### 2. 修复超时问题\n\n**诊断**:\n```bash\nopenclaw cron runs \n# 查找 \"timed out\" 或 \"timeout\" 错误\n```\n\n**修复命令**:\n```bash\n# 增加超时时间\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n```\n\n### 3. 修复 disabled 状态\n\n**诊断**:\n```bash\nopenclaw cron list --includeDisabled\n# 查找 enabled: false 的任务\n```\n\n**修复命令**:\n```bash\nopenclaw cron update --patch '{\"enabled\":true}'\n```\n\n### 4. 修复 cron 表达式\n\n**诊断**:\n```bash\nopenclaw cron get \n# 检查 schedule.expr 和 schedule.tz\n```\n\n**修复命令**:\n```bash\n# 更新为正确的 cron 表达式（本地时间）\nopenclaw cron update \\\n --patch '{\"schedule\":{\"kind\":\"cron\",\"expr\":\"0 9 * * 1-5\",\"tz\":\"Asia/Shanghai\"}}'\n```\n\n## 工具修复模板\n\n### 5. 刷新飞书权限\n\n**诊断**:\n```bash\nfeishu_app_scopes\n```\n\n**修复**: 提示用户在飞书开放平台申请所需权限\n\n### 6. 服务健康检查\n\n**诊断**:\n```bash\n# 检查 Docker 服务\ndocker ps --filter \"status=exited\"\n\n# 检查端口\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3004/health # SearXNG\ncurl -s http://localhost:3003/health # Crawl4AI\n```\n\n**修复**:\n```bash\n# 重启特定服务\ncd ~/firecrawl && docker compose up -d\ncd ~/searxng && docker compose up -d\n```\n\n### 7. 清理磁盘空间\n\n**诊断**:\n```bash\ndf -h /\ndu -sh ~/.openclaw/workspace/memory/ 2>/dev/null\ndu -sh ~/.openclaw/workspace/learnings/ 2>/dev/null\n```\n\n**修复**:\n```bash\n# 清理超过 30 天的日志\nfind ~/.openclaw/workspace/memory/ -name \"*.md\" -mtime +30 -delete 2>/dev/null\n\n# 清理 Docker 无用资源\ndocker system prune -f 2>/dev/null\n```\n\n## 子 Agent 修复模板\n\n### 8. 子 Agent 超时\n\n**诊断**:\n```bash\nopenclaw subagents list --recentMinutes 60\n# 查找超时或失败的子 Agent\n```\n\n**修复**:\n```bash\n# 终止卡死的子 Agent\nopenclaw subagents kill \n\n# 重新生成，增加超时\nsessions_spawn(task=\"...\", runTimeoutSeconds=600)\n```\n\n### 9. 子 Agent 上下文过大\n\n**诊断**:\n```bash\nopenclaw sessions list --limit 10\n# 检查 session 大小\n```\n\n**修复**:\n```bash\n# 使用轻量上下文\nsessions_spawn(task=\"...\", lightContext=true)\n\n# 或使用隔离上下文\nsessions_spawn(task=\"...\", context=\"isolated\")\n```\n\n## 系统修复模板\n\n### 10. Gateway 重启\n\n**诊断**:\n```bash\nopenclaw status\n```\n\n**修复**:\n```bash\nopenclaw gateway restart --reason \"优化修复后重启\"\n```\n\n### 11. 内存压力\n\n**诊断**:\n```bash\nfree -m\n# 检查可用内存\n```\n\n**修复**:\n```bash\n# 停止非必要服务\ncd ~/firecrawl && docker compose stop # 按需启动\ncd ~/crawl4ai-server && ... # 检查是否需要\n\n# 或重启 Gateway\nopenclaw gateway restart\n```\n\n## 验证模板\n\n### 修复后验证清单\n\n```markdown\n## 修复验证\n- [ ] cron 任务正常运行: `openclaw cron list`\n- [ ] 错误日志无新错误: `cat learnings/error-log.md`\n- [ ] 相关工具可用: 测试调用\n- [ ] 用户通知: 告知修复结果\n```\n\n### 修复报告格式\n\n```markdown\n## 🔧 修复报告\n\n**问题**: [问题描述]\n**根因**: [原因分析]\n**修复**: [执行的操作]\n**状态**: ✅ 已修复 / ⚠️ 部分修复 / ❌ 需要人工干预\n**验证**: [验证结果]\n**后续**: [预防措施或待办事项]\n```\n\nFile v1.4.0:references/openai-patterns.md\n\n# OpenAI Agent 工程最佳实践\n\n## 1. Function Calling Pattern\n\n### 工具定义最佳实践\n```json\n{\n \"name\": \"execute_fix\",\n \"description\": \"执行修复操作\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"action\": {\"type\": \"string\", \"enum\": [\"diagnose\", \"repair\", \"verify\"]},\n \"target\": {\"type\": \"string\"},\n \"parameters\": {\"type\": \"object\"}\n },\n \"required\": [\"action\", \"target\"]\n }\n}\n```\n\n### 并行工具调用\n```\n- 独立诊断步骤并行执行\n- 依赖步骤串行执行\n- 使用工具组管理相关调用\n```\n\n## 2. Agent Loop Pattern\n\n### 经典 ReAct 循环\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nThought: 基于结果调整策略\n... (循环直到解决)\n```\n\n### 改进版：带终止条件\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nReflection: 评估是否接近解决\n- 是 → 输出结论\n- 否 → 继续循环（最大 N 次）\n- 超时 → 输出部分结论 + 后续建议\n```\n\n## 3. Error Recovery Strategies\n\n### 指数退避重试\n```python\ndef retry_with_backoff(func, max_retries=3, base_delay=1):\n for attempt in range(max_retries):\n try:\n return func()\n except Exception as e:\n if attempt == max_retries - 1:\n raise\n delay = base_delay * (2 ** attempt)\n time.sleep(delay)\n```\n\n### 降级链模式\n```\n主方案: API 调用\n ↓ 失败\n降级1: 本地缓存\n ↓ 失败\n降级2: 备用 API\n ↓ 失败\n降级3: 手动提示用户\n```\n\n## 4. State Management\n\n### Checkpoint 模式\n```\n在执行关键操作前保存状态：\n{\n \"checkpoint_id\": \"uuid\",\n \"timestamp\": \"ISO-8601\",\n \"action\": \"正在执行的操作\",\n \"state_snapshot\": \"关键状态快照\",\n \"rollback_instructions\": \"回滚步骤\"\n}\n```\n\n### 会话管理\n```\n- 长会话：定期清理上下文\n- 子会话：隔离运行，完成后回收\n- 共享状态：使用文件系统或数据库\n```\n\n## 5. Evaluation & Testing\n\n### 自愈效果评估\n```\n指标:\n- 首次修复成功率\n- 平均修复时间 (MTTR)\n- 复发率（同一错误再次出现）\n- 误报率（错误诊断）\n\n监控:\n- 错误日志趋势\n- 修复操作成功率\n- 用户反馈评分\n```\n\n### A/B 测试修复策略\n```\n对同一类问题，测试不同修复策略：\n- 策略 A: 立即修复\n- 策略 B: 等待 + 重试\n- 策略 C: 降级到备用方案\n\n记录每种策略的成功率和耗时\n```\n\n## 6. Scalability Patterns\n\n### 工作队列\n```\n- 使用 cron 调度重复任务\n- 使用子 Agent 处理并发任务\n- 使用消息队列（如果可用）处理高峰\n```\n\n### 资源管理\n```\n- 监控 token 使用量\n- 设置并发子 Agent 上限\n- 定期清理临时文件\n- 使用轻量上下文模式\n```\n\n## 7. Observability\n\n### 日志分级\n```\nDEBUG: 详细诊断信息\nINFO: 正常操作流程\nWARNING: 潜在问题\nERROR: 明确的失败\nCRITICAL: 系统级故障\n```\n\n### 指标收集\n```\n- 工具调用成功率\n- 平均响应时间\n- Token 消耗趋势\n- 错误类型分布\n- 修复成功率\n```\n\nFile v1.4.0:references/self-evolution.md\n\n# 优化师自我进化工作流\n\n## 触发方式\n\n### Cron 自动触发\n- 每周日 03:00 执行一次（cron 任务：agent-optimizer-self-update）\n- 执行环境：isolated session, agentTurn\n\n### 手动触发\n- 用户说\"更新优化师的工程实践\"\n\n## 执行步骤\n\n### Step 1: 收集最新工程实践\n\n```bash\n# Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+claude+agent+engineering+tool+use+patterns+best+practices&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+structured+outputs+error+recovery&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# 行业 Agent 架构趋势\ncurl -s \"http://localhost:3004/search?q=llm+agent+architecture+patterns+self+healing+error+recovery+2026&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:3]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n```\n\n### Step 2: 对比与更新\n\n读取搜索结果后，对比以下文件：\n\n| 文件 | 检查内容 | 更新方式 |\n|------|---------|---------|\n| anthropic-patterns.md | 是否有新 Thinking/Tool Use 模式 | 追加新条目 |\n| openai-patterns.md | 是否有新 Agent 模式 | 追加新条目 |\n| error-taxonomy.md | 是否有新错误类型 | 新增分类 |\n| fix-templates.md | 是否有新修复方法 | 新增模板 |\n\n### Step 3: 清理过时内容\n\n检查 references/ 中的内容：\n- 标记已废弃的实践（用 `⚠️ 已废弃` 前缀）\n- 保留历史版本供参考\n- 不删除任何内容，只做标记\n\n### Step 4: 更新版本号\n\n在 SKILL.md 末尾的版本表中添加新记录：\n\n```markdown\n| v{x.y} | YYYY-MM-DD | 更新说明 |\n```\n\n## 更新规则\n\n### 必须满足\n- 只在确认有**新信息**时才更新\n- 更新内容必须**可验证**（有来源链接）\n- 更新后检查 SKILL.md 行数是否超过 400，超过则拆分\n\n### 禁止\n- 删除已有内容\n- 替换经过验证有效的实践\n- 添加未经验证的\"最佳实践\"\n\n## 输出格式\n\n更新完成后输出简要报告：\n\n```\n🔧 优化师自我进化完成\n\n新增: X 条工程实践\n- [条目1] - 来源\n- [条目2] - 来源\n\n更新: Y 条已有内容\n- [条目1] - 变更说明\n\n废弃: Z 条过时实践\n- [条目1] - 废弃原因\n```\n\nFile v1.4.0:skill-card.md\n\n## Description:\n\nAgent优化专家 diagnoses and helps repair agent execution issues such as cron failures, tool errors, workflow interruptions, and performance regressions across OpenClaw and Hermes Agent environments.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tuobadaidai](https://clawhub.ai/user/tuobadaidai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to inspect agent and system state, classify cron, tool, workflow, and performance failures, propose fixes, and record learning patterns for OpenClaw or Hermes environments.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Recurring self-repair and self-update workflows can modify local agent files or references.\n\nMitigation: Keep cron or heartbeat setup manual and review the exact proposed updates before applying them.\n\nRisk: Maintenance actions can restart services, prune Docker resources, terminate sub-agents, or delete logs.\n\nMitigation: Require explicit approval for service restarts, Docker pruning, process termination, and file deletion.\n\nRisk: Diagnostics inspect local agent and system state.\n\nMitigation: Run the skill only in workspaces where operational inspection is expected, and avoid recording secrets or sensitive data in logs.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/tuobadaidai/skills/agent-optimization-expert)\n- [Trigger Integration](artifact/TRIGGER-INTEGRATION.md)\n- [Dual Environment Adaptation](artifact/references/dual-env-adaptation.md)\n- [Error Taxonomy](artifact/references/error-taxonomy.md)\n- [Fix Templates](artifact/references/fix-templates.md)\n- [Self-Evolution Workflow](artifact/references/self-evolution.md)\n- [Anthropic Engineering Patterns](artifact/references/anthropic-patterns.md)\n- [OpenAI Agent Engineering Practices](artifact/references/openai-patterns.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include diagnostic reports, fix proposals, validation checklists, and commands that require user approval before execution.]\n\n## Skill Version(s):\n\n1.4.0 (source: server release and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.4.0:TRIGGER-INTEGRATION.md\n\n# Agent 架构与工程优化师 - 触发机制集成\n\n## 自动触发条件\n\n以下场景自动触发 agent-optimizer skill：\n\n### 1. Cron 执行失败\n- 任务超时\n- Payload schema 错误\n- Session target 不匹配\n- 连续 2 次以上失败\n\n### 2. 工具调用异常\n- API 返回错误状态码\n- 权限不足\n- 网络连接失败\n- 超时或限流\n\n### 3. 工作流中断\n- 子 Agent 异常退出\n- 消息发送失败\n- 会话状态丢失\n\n### 4. 性能退化\n- 响应时间显著增加\n- Token 消耗异常增长\n- 错误率上升\n\n## 触发方式\n\n### 自动触发\n当检测到上述问题时，小七应：\n1. 读取 `skills/agent-optimizer/SKILL.md`\n2. 按照诊断工作流执行\n3. 输出修复建议\n4. 用户确认后执行修复\n5. 验证并记录\n\n### 手动触发\n用户明确要求时：\n- \"检查一下系统问题\"\n- \"优化一下配置\"\n- \"诊断一下为什么失败\"\n\n## 集成到现有流程\n\n### Heartbeat 集成\n在 HEARTBEAT.md 中添加优化师巡检：\n\n```markdown\n# 🔄 Agent 健康度检查（每月一次）\n- 读取 learnings/error-log.md，分析错误趋势\n- 检查 cron 任务成功率\n- 评估 token 使用效率\n- 输出优化建议\n```\n\n### 错误处理集成\n在工具调用失败后：\n1. 记录错误到 learnings/error-log.md\n2. 判断是否触发优化师\n3. 执行诊断和修复\n\n## 权限与安全\n\n### 自动执行范围\n- ✅ 读取日志和状态\n- ✅ 临时文件清理\n- ✅ 重试限流错误（≤3次）\n- ✅ 更新心跳文件\n\n### 需确认操作\n- ⚠️ 修改 cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n\n### 禁止自动执行\n- ❌ 修改核心身份文件（SOUL.md/IDENTITY.md）\n- ❌ 发送外部消息\n- ❌ 删除不可恢复数据\n\nArchive v1.3.0: 9 files, 16282 bytes\n\nFiles: _meta.json (144b), references/anthropic-patterns.md (2894b), references/dual-env-adaptation.md (3379b), references/error-taxonomy.md (3701b), references/fix-templates.md (3873b), references/openai-patterns.md (3087b), references/self-evolution.md (2718b), SKILL.md (7977b), TRIGGER-INTEGRATION.md (1726b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: agent-optimization-expert\nversion: 1.3.0\ndescription: >\n Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化），\n 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。\n Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、\n 诊断失败原因、修复任务失败、优化师自我更新、Agent优化、巡检系统.\n 不适用于业务逻辑问题排查、飞书内容编辑、数据查询类任务.\n---\n\n# Agent 优化专家\n\n## 概述\n\n基于 Anthropic / OpenAI 工程实践的 Agent 自愈引擎，覆盖「检测 → 诊断 → 修复 → 验证 → 学习 → 进化」闭环。\n**兼容 OpenClaw 和 Hermes Agent 双环境**，自动识别当前平台并切换对应命令。\n\n### 功能范围\n\n- Cron 任务诊断与修复（失败/超时/disabled/配置错误）\n- 工具调用异常诊断（认证/权限/限流/超时/参数）\n- 子 Agent 异常诊断（spawn 失败/超时/上下文过大）\n- 系统健康度巡检（资源/网络/磁盘/内存）\n- **自我进化**：定期收集工程实践、更新 references/、沉淀新模式\n- 错误模式学习与沉淀（learnings/error-log.md → fix-templates.md 自动升级）\n\n---\n\n## 使用\n\n### 场景 1：Cron 任务执行失败\n\n> **双环境适配**：OpenClaw 走 `openclaw cron` CLI，Hermes 走 `cronjob` 工具。\n> 完整命令映射表和修复规则见 `references/dual-env-adaptation.md`\n\n**快速诊断流程（通用）：**\n1. 列出所有 Cron 任务，检查 enabled/schedule/最近运行状态\n2. 定位失败 job，查看错误输出\n3. 对照 `references/fix-templates.md` 执行修复\n4. 手动触发一次验证修复结果\n\n**常见修复类型：**\n- **未执行** → 检查 enabled / schedule 表达式 / timezone\n- **执行报错** → 检查错误输出 → 对照 fix-templates.md\n- **超时** → timeout 加倍，若仍超时则拆分逻辑\n- **disabled** → 重新启用\n\n---\n\n### 场景 2：工具调用连续失败\n\n```bash\n# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限（双环境通用）\necho $API_KEY | wc -c # 检查 key 是否存在\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)\n```\n\n---\n\n### 场景 3：系统健康度巡检\n\n```bash\n# 资源检查（通用）\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查（通用）\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# Agent 平台状态\n# OpenClaw → openclaw status\n# Hermes → ps aux | grep hermes\n```\n\n---\n\n### 场景 4：子 Agent 异常\n\n**OpenClaw**：`openclaw subagents list` 查看 → `openclaw subagents kill ` 终止\n**Hermes**：子 Agent 同步执行不卡死，超时检查 delegate_task timeout；Cron 子任务卡住用 `process(action='kill')`\n\n---\n\n## 自动触发机制\n\n> 本 Skill 不会自己跑起来，需要环境提供\"心跳\"或\"定时\"机制。\n> **双环境适配完整指南**（含 Cron Job 配置命令 + HEARTBEAT.md 配置模板）→ `references/dual-env-adaptation.md`\n\n**一句话总结：**\n- **Hermes 环境** → 用 `cronjob(action='create')` 创建每日自检 + 每周知识更新\n- **OpenClaw 环境** → 在 `workspace/HEARTBEAT.md` 中配置心跳检查清单\n\n---\n\n## 诊断决策树\n\n```\n问题出现\n│\n├─ Cron 相关？\n│ ├─ 任务未执行 → 检查 enabled / schedule / timezone\n│ ├─ 执行报错 → 查错误输出 → 对照 fix-templates.md\n│ └─ 超时 → timeout 加倍 or 拆分逻辑\n│\n├─ 工具调用相关？\n│ ├─ 401/403 → 认证/权限\n│ ├─ 429 → 指数退避重试\n│ ├─ 5xx → 等待重试 + 记录\n│ └─ 超时 → 网络检查 → 降级\n│\n├─ 子 Agent 相关？\n│ ├─ spawn 失败 → task 过大 / 资源不足\n│ ├─ 超时 → 增加 timeout / 优化 task\n│ └─ 结果异常 → context 模式检查\n│\n└─ 系统相关？\n ├─ 磁盘满 → 清理 + docker prune\n ├─ 内存不足 → 停服务 + lightContext\n └─ 网络断开 → DNS / 防火墙\n```\n\n---\n\n## 自愈闭环\n\n```\n检测（心跳/用户反馈/错误日志）\n → 诊断（快速扫描 → 错误分析 → 根因推理 → 修复建议）\n → 修复（最小变更 + 可回滚）\n → 验证（修复后确认）\n → 学习（记录到 learnings/error-log.md）\n```\n\n### 错误日志格式（learnings/error-log.md）\n\n```markdown\n## YYYY-MM-DD HH:MM\n- **Error**: [错误描述]\n- **Context**: [触发场景]\n- **Root Cause**: [根因分析]\n- **Fix Applied**: [修复操作]\n- **Prevention**: [避免复现的措施]\n```\n\n---\n\n## 操作分级与安全\n\n| 级别 | 范围 | 策略 |\n|------|------|------|\n| L0 | 读取状态、检查日志 | 自动执行 |\n| L1 | 清理临时文件、更新日志 | 自动执行 |\n| L2 | 修改 cron 配置、重启服务 | 提示用户确认 |\n| L3 | 修改核心配置、删除数据 | 必须用户明确授权 |\n\n**禁止自动执行**：\n- ❌ 修改 SOUL.md / IDENTITY.md / USER.md\n- ❌ 发送外部消息（邮件/飞书/社交）\n- ❌ 删除不可恢复的数据\n\n---\n\n## 自我进化机制\n\n### 路径 1：错误驱动进化（每次诊断后）\n\n```\n修复完成\n├─ 新错误类型？→ 新增 error-taxonomy + fix-templates\n├─ 修复可复用？→ 写入 fix-templates\n└─ 涉及工程模式？→ 更新对应 references/\n```\n\n### 路径 2：定期知识更新（每周）\n\n1. SearXNG 搜索 Anthropic/OpenAI 最新工程文档\n2. 对比 references/ 现有内容\n3. 发现新模式追加到对应文件\n4. 标记已过时实践（不删除，标「⚠️ 已废弃」）\n\n```bash\ncurl -s \"http://localhost:3004/search?q=anthropic+agent+engineering+best+practices+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n```\n\n### 路径 3：错误日志驱动进化\n\nlearnings/error-log.md 中相同错误模式 ≥3 次时：\n1. 创建/更新 fix-templates.md 对应模板\n2. 更新 error-taxonomy.md 优先级\n3. 新型错误新增分类条目\n\n---\n\n## 参考文件\n\n| 文件 | 何时读取 |\n|------|---------|\n| [references/dual-env-adaptation.md](references/dual-env-adaptation.md) | **首次使用必读** — 环境检测、命令映射、Cron/HEARTBEAT 配置 |\n| [references/anthropic-patterns.md](references/anthropic-patterns.md) | 需要 Thinking/Tool Use/多 Agent 协调模式 |\n| [references/openai-patterns.md](references/openai-patterns.md) | 需要 ReAct 循环/降级链/评估模式 |\n| [references/error-taxonomy.md](references/error-taxonomy.md) | 工具调用失败分类诊断 |\n| [references/fix-templates.md](references/fix-templates.md) | 确认修复方案后查具体命令 |\n| [references/self-evolution.md](references/self-evolution.md) | 自我进化：收集最新实践 |\n\n---\n\n## 版本与更新记录\n\n| 版本 | 日期 | 更新内容 |\n|------|------|----------|\n| v1.0 | 2026-05-18 | 初始创建（四层骨架 + 诊断决策树 + 修复模板） |\n| v1.1 | 2026-05-18 | 添加自我进化机制（三条路径） |\n| v1.2 | 2026-05-20 | **双环境适配**：兼容 OpenClaw + Hermes，环境自动检测、双路径命令映射、HEARTBEAT.md 与 Cron Job 双触发机制 |\n\nFile v1.3.0:_meta.json\n\n{\n \"ownerId\": \"kn70tx725606ywwb5gfj0vpxjx83admr\",\n \"slug\": \"agent-optimization-expert\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1779241954169\n}\n\nFile v1.3.0:references/anthropic-patterns.md\n\n# Anthropic 工程实践模式\n\n## 1. Extended Thinking Pattern\n\nAnthropic Claude 的核心优势是 extended thinking（扩展思考）模式。\n\n### 使用场景\n- 复杂问题分解\n- 多步骤推理\n- 代码架构设计\n- 错误诊断与修复\n\n### 实践要点\n```\n1. 在思考阶段明确列出假设\n2. 对每个假设进行验证\n3. 记录推理链条\n4. 最终输出时提炼结论，隐藏中间过程\n```\n\n### OpenClaw 映射\n- `thinking` 参数控制思考级别\n- 复杂诊断任务启用 thinking 模式\n- 子 Agent 使用 thinking 进行深度分析\n\n## 2. Tool Use Best Practices\n\n### 预检-执行-后检模式\n```\n预检: 验证输入参数、权限、依赖状态\n执行: 调用工具，带超时和重试\n后检: 验证结果完整性、一致性\n```\n\n### 错误处理策略\n```\n1. 捕获具体错误类型（非通用异常）\n2. 分类处理：\n - 可重试：指数退避重试\n - 需修正：调整参数重试\n - 不可恢复：降级到备用方案\n3. 记录错误模式到学习库\n```\n\n## 3. Multi-Agent Coordination\n\n### 子 Agent 使用原则\n```\n- context=\"isolated\"：新任务，无需上下文\n- context=\"fork\"：需要当前对话上下文\n- runTimeoutSeconds：设置合理超时\n- 使用 sessions_yield 等待完成，不轮询\n```\n\n### 通信模式\n```\n主 Agent → 子 Agent: sessions_spawn(task, taskName)\n子 Agent → 主 Agent: 完成事件自动传递\n主 Agent ↔ 子 Agent: sessions_send 进行中途交互\n```\n\n## 4. Prompt Engineering Patterns\n\n### 结构化输出\n```\n使用明确的输出格式要求：\n- JSON schema 定义\n- Markdown 模板\n- 明确的字段名称\n```\n\n### 角色分离\n```\n不同任务使用不同的角色提示：\n- 诊断模式：\"你是一个系统诊断专家...\"\n- 修复模式：\"你是一个运维工程师...\"\n- 优化模式：\"你是一个性能调优专家...\"\n```\n\n### 自反思模式\n```\n在关键决策后添加：\n\"在继续之前，请反思你的分析：\n1. 是否遗漏了重要信息？\n2. 假设是否合理？\n3. 有没有其他可能的解释？\"\n```\n\n## 5. Context Management\n\n### 上下文优化\n```\n- 使用 memory_search 检索相关信息，而非全部加载\n- 大型文件使用 offset/limit 分段读取\n- 子 Agent 使用 lightContext 减少 token\n- 定期清理过期的 session 状态\n```\n\n### Token 预算\n```\n诊断任务：< 5000 tokens\n修复任务：< 10000 tokens\n复杂分析：使用子 Agent 隔离\n```\n\n## 6. Safety & Guardrails\n\n### 操作分级\n```\nL0 - 安全：读取文件、检查状态\nL1 - 低风险：修改临时文件、更新日志\nL2 - 中风险：修改配置、重启服务\nL3 - 高风险：删除数据、修改核心配置\n\nL0-L1: 自动执行\nL2: 提示用户确认\nL3: 必须用户明确授权\n```\n\n### 审计日志\n```\n所有 L2+ 操作记录到：\n- learnings/error-log.md\n- memory/YYYY-MM-DD.md\n- 包含：操作时间、内容、原因、结果\n```\n\nFile v1.3.0:references/dual-env-adaptation.md\n\n# 双环境适配指南（OpenClaw + Hermes）\n\n本 Skill 同时兼容 OpenClaw 和 Hermes Agent。所有诊断逻辑一致，仅执行层命令不同。\n\n## 环境自动检测\n\n```bash\nif command -v hermes &>/dev/null; then\n PLATFORM=\"hermes\"\n CMD=\"hermes\"\nelif command -v openclaw &>/dev/null; then\n PLATFORM=\"openclaw\"\n CMD=\"openclaw\"\nelse\n if [ -d \"$HOME/.hermes\" ]; then\n PLATFORM=\"hermes\"\n CMD=\"hermes\"\n else\n PLATFORM=\"openclaw\"\n CMD=\"openclaw\"\n fi\nfi\n```\n\n## 命令映射表\n\n| 操作 | OpenClaw 命令 | Hermes 工具/命令 |\n|------|---------------|------------------|\n| 列出 Cron | `openclaw cron list --includeDisabled` | `cronjob(action='list')` |\n| 查看运行历史 | `openclaw cron runs ` | `cronjob(action='list')` 查看 last output |\n| 更新 Cron | `openclaw cron update --patch '...'` | `cronjob(action='update', job_id='xxx', ...)` |\n| 重新启用 | `openclaw cron update --patch '{\"enabled\":true}'` | `cronjob(action='resume', job_id='xxx')` |\n| 手动触发 | `openclaw cron run ` | `cronjob(action='run', job_id='xxx')` |\n| 子 Agent 列表 | `openclaw subagents list` | 不适用（delegate_task 同步执行） |\n| 终止子 Agent | `openclaw subagents kill ` | `process(action='kill', session_id='xxx')` |\n| 状态检查 | `openclaw status` | `ps aux \\| grep hermes` |\n\n## 自动触发机制\n\n### Hermes 环境：Cron Job\n\n```\n# 每日自检\ncronjob(action='create',\n name='🔧 Agent 每日自检',\n schedule='0 8 * * *',\n prompt='执行 agent-optimization-expert 场景 3（系统健康度巡检）和场景 1（Cron 任务扫描）。检查磁盘/内存/容器/本地服务/所有 cron jobs。如有异常按诊断决策树修复并记录到 learnings/error-log.md。无异常只记录\"一切正常\"。',\n deliver='local')\n\n# 每周知识更新\ncronjob(action='create',\n name='📚 Agent 知识更新',\n schedule='0 3 * * 0',\n prompt='执行 agent-optimization-expert 路径 2（定期知识更新）：搜索 Anthropic/OpenAI 最新 Agent 工程实践，对比 references/ 现有内容，发现新模式追加到对应文件。',\n deliver='local')\n```\n\n### OpenClaw 环境：HEARTBEAT.md\n\n在 `workspace/HEARTBEAT.md` 中配置：\n\n```markdown\n## Agent 自检配置\n- **自检频率**：每 4 小时一次\n- **工作时间**（9:00-18:00）：检查任务 + 系统健康 + 消息\n- **非工作时间**（18:00-9:00）：仅检查紧急任务\n- **触发 Skill**：发现异常时加载 agent-optimization-expert 诊断修复\n\n## 检查清单\n- [ ] Cron 任务是否有失败（最近 24 小时）\n- [ ] 本地服务是否健康（3002/3003/3004）\n- [ ] 磁盘使用率是否 > 85%\n- [ ] learnings/error-log.md 是否有新增错误\n```\n\n## 修复规则差异\n\n| 问题 | OpenClaw 修复 | Hermes 修复 |\n|------|--------------|------------|\n| sessionTarget/payload 不匹配 | `--patch '{\"payload\":{\"kind\":\"systemEvent\"}}'` | 不适用（Hermes 无此概念） |\n| Cron prompt 过长 | 拆分 payload 逻辑 | 缩短 prompt 或拆成多 job |\n| 工具未启用 | 检查 openclaw.json | 检查 cronjob 的 enabled_toolsets |\n| 工作路径不对 | 不适用 | 检查 cronjob 的 workdir |\n\n## 触发方式选择决策\n\n```\n当前环境？\n├─ Hermes → Cron Job（方式 A）\n└─ OpenClaw → HEARTBEAT.md（方式 B）\n```\n\nFile v1.3.0:references/error-taxonomy.md\n\n# 错误分类与处理策略\n\n## 错误分类体系\n\n### L1: 工具调用错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **认证失败** | 401 Unauthorized | 检查 API Key/Token，提示更新 |\n| **权限不足** | 403 Forbidden | 检查权限配置，申请授权 |\n| **资源不存在** | 404 Not Found | 验证 ID/路径，检查拼写 |\n| **限流** | 429 Too Many Requests | 指数退避重试，检查配额 |\n| **服务器错误** | 5xx | 重试或等待，记录到日志 |\n| **超时** | Timeout | 增加超时或优化请求 |\n| **参数错误** | Invalid parameters | 修正参数格式 |\n\n### L2: 工作流错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **Cron 失败** | 任务未执行/执行报错 | 检查 schedule/payload/sessionTarget |\n| **子 Agent 异常** | spawn 失败/超时 | 检查参数/资源/权限 |\n| **消息发送失败** | 投递失败/格式错误 | 检查 channel/target/format |\n| **会话中断** | Session 丢失 | 重建会话，恢复上下文 |\n\n### L3: 系统错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **内存不足** | OOM Killer | 减少并发，使用轻量模式 |\n| **磁盘满** | No space left | 清理临时文件，清理旧日志 |\n| **网络断开** | Connection refused | 检查网络，重试或降级 |\n| **配置损坏** | 解析错误 | 从备份恢复，检查语法 |\n\n## 诊断决策树\n\n```\n错误发生\n│\n├─ 是工具调用错误？\n│ ├─ 认证问题 → 检查凭证\n│ ├─ 权限问题 → 检查授权\n│ ├─ 限流问题 → 退避重试\n│ └─ 参数问题 → 修正格式\n│\n├─ 是工作流错误？\n│ ├─ Cron 问题 → 检查 job 配置\n│ ├─ 子 Agent 问题 → 检查 spawn 参数\n│ └─ 消息问题 → 检查 channel 配置\n│\n└─ 是系统错误？\n ├─ 资源问题 → 释放资源\n └─ 配置问题 → 恢复备份\n```\n\n## 常见错误模式库\n\n### Cron 相关\n\n#### 错误：sessionTarget 与 payload.kind 不匹配\n```\n症状: \"sessionTarget='main' requires payload.kind='systemEvent'\"\n修复: \n - main → systemEvent\n - isolated/current → agentTurn\n```\n\n#### 错误：Cron 任务超时\n```\n症状: \"Task timed out after X seconds\"\n修复:\n - 增加 payload.timeoutSeconds\n - 优化任务内容，减少复杂度\n - 使用子 Agent 处理重型任务\n```\n\n#### 错误：Cron 未触发\n```\n症状: 任务到时间未执行\n诊断:\n 1. cron list 检查 enabled 状态\n 2. 检查 schedule 表达式\n 3. 检查 timezone 配置\n 4. 检查 Gateway 运行状态\n```\n\n### 飞书相关\n\n#### 错误：权限不足\n```\n症状: \"Permission denied\" 或 \"insufficient scope\"\n修复:\n 1. feishu_app_scopes 检查当前权限\n 2. 确认所需 scope\n 3. 在飞书开放平台申请额外权限\n```\n\n#### 错误：Token 过期\n```\n症状: \"Token expired\" 或 \"Invalid token\"\n修复:\n 1. 刷新访问令牌\n 2. 检查 token 刷新机制\n 3. 重新认证\n```\n\n### 网络相关\n\n#### 错误：连接超时\n```\n症状: \"Connection timeout\"\n诊断:\n 1. ping 测试目标主机\n 2. 检查 DNS 解析\n 3. 检查防火墙规则\n 4. 尝试备用端点\n```\n\n## 自动修复规则\n\n### 可自动修复\n- ✅ Cron 任务 disabled → 重新启用\n- ✅ 临时文件清理\n- ✅ 重试限流错误（最多 3 次）\n- ✅ 更新心跳状态文件\n\n### 需确认后修复\n- ⚠️ 修改 Cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n- ⚠️ 删除大量数据\n\n### 不可自动修复\n- ❌ 修改核心身份文件\n- ❌ 发送外部消息（邮件、飞书）\n- ❌ 删除不可恢复的数据\n- ❌ 安装新软件/依赖\n\nFile v1.3.0:references/fix-templates.md\n\n# 常见修复模板库\n\n## Cron 修复模板\n\n### 1. 修复 sessionTarget/payload 不匹配\n\n**诊断**:\n```bash\nopenclaw cron get \n```\n\n**修复命令**:\n```bash\n# 情况 A: main session 需要 systemEvent\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"},\"sessionTarget\":\"main\"}'\n\n# 情况 B: isolated session 需要 agentTurn \nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"agentTurn\",\"message\":\"...\"},\"sessionTarget\":\"isolated\"}'\n```\n\n**验证**:\n```bash\nopenclaw cron runs --limit 1\n```\n\n### 2. 修复超时问题\n\n**诊断**:\n```bash\nopenclaw cron runs \n# 查找 \"timed out\" 或 \"timeout\" 错误\n```\n\n**修复命令**:\n```bash\n# 增加超时时间\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n```\n\n### 3. 修复 disabled 状态\n\n**诊断**:\n```bash\nopenclaw cron list --includeDisabled\n# 查找 enabled: false 的任务\n```\n\n**修复命令**:\n```bash\nopenclaw cron update --patch '{\"enabled\":true}'\n```\n\n### 4. 修复 cron 表达式\n\n**诊断**:\n```bash\nopenclaw cron get \n# 检查 schedule.expr 和 schedule.tz\n```\n\n**修复命令**:\n```bash\n# 更新为正确的 cron 表达式（本地时间）\nopenclaw cron update \\\n --patch '{\"schedule\":{\"kind\":\"cron\",\"expr\":\"0 9 * * 1-5\",\"tz\":\"Asia/Shanghai\"}}'\n```\n\n## 工具修复模板\n\n### 5. 刷新飞书权限\n\n**诊断**:\n```bash\nfeishu_app_scopes\n```\n\n**修复**: 提示用户在飞书开放平台申请所需权限\n\n### 6. 服务健康检查\n\n**诊断**:\n```bash\n# 检查 Docker 服务\ndocker ps --filter \"status=exited\"\n\n# 检查端口\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3004/health # SearXNG\ncurl -s http://localhost:3003/health # Crawl4AI\n```\n\n**修复**:\n```bash\n# 重启特定服务\ncd ~/firecrawl && docker compose up -d\ncd ~/searxng && docker compose up -d\n```\n\n### 7. 清理磁盘空间\n\n**诊断**:\n```bash\ndf -h /\ndu -sh ~/.openclaw/workspace/memory/ 2>/dev/null\ndu -sh ~/.openclaw/workspace/learnings/ 2>/dev/null\n```\n\n**修复**:\n```bash\n# 清理超过 30 天的日志\nfind ~/.openclaw/workspace/memory/ -name \"*.md\" -mtime +30 -delete 2>/dev/null\n\n# 清理 Docker 无用资源\ndocker system prune -f 2>/dev/null\n```\n\n## 子 Agent 修复模板\n\n### 8. 子 Agent 超时\n\n**诊断**:\n```bash\nopenclaw subagents list --recentMinutes 60\n# 查找超时或失败的子 Agent\n```\n\n**修复**:\n```bash\n# 终止卡死的子 Agent\nopenclaw subagents kill \n\n# 重新生成，增加超时\nsessions_spawn(task=\"...\", runTimeoutSeconds=600)\n```\n\n### 9. 子 Agent 上下文过大\n\n**诊断**:\n```bash\nopenclaw sessions list --limit 10\n# 检查 session 大小\n```\n\n**修复**:\n```bash\n# 使用轻量上下文\nsessions_spawn(task=\"...\", lightContext=true)\n\n# 或使用隔离上下文\nsessions_spawn(task=\"...\", context=\"isolated\")\n```\n\n## 系统修复模板\n\n### 10. Gateway 重启\n\n**诊断**:\n```bash\nopenclaw status\n```\n\n**修复**:\n```bash\nopenclaw gateway restart --reason \"优化修复后重启\"\n```\n\n### 11. 内存压力\n\n**诊断**:\n```bash\nfree -m\n# 检查可用内存\n```\n\n**修复**:\n```bash\n# 停止非必要服务\ncd ~/firecrawl && docker compose stop # 按需启动\ncd ~/crawl4ai-server && ... # 检查是否需要\n\n# 或重启 Gateway\nopenclaw gateway restart\n```\n\n## 验证模板\n\n### 修复后验证清单\n\n```markdown\n## 修复验证\n- [ ] cron 任务正常运行: `openclaw cron list`\n- [ ] 错误日志无新错误: `cat learnings/error-log.md`\n- [ ] 相关工具可用: 测试调用\n- [ ] 用户通知: 告知修复结果\n```\n\n### 修复报告格式\n\n```markdown\n## 🔧 修复报告\n\n**问题**: [问题描述]\n**根因**: [原因分析]\n**修复**: [执行的操作]\n**状态**: ✅ 已修复 / ⚠️ 部分修复 / ❌ 需要人工干预\n**验证**: [验证结果]\n**后续**: [预防措施或待办事项]\n```\n\nFile v1.3.0:references/openai-patterns.md\n\n# OpenAI Agent 工程最佳实践\n\n## 1. Function Calling Pattern\n\n### 工具定义最佳实践\n```json\n{\n \"name\": \"execute_fix\",\n \"description\": \"执行修复操作\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"action\": {\"type\": \"string\", \"enum\": [\"diagnose\", \"repair\", \"verify\"]},\n \"target\": {\"type\": \"string\"},\n \"parameters\": {\"type\": \"object\"}\n },\n \"required\": [\"action\", \"target\"]\n }\n}\n```\n\n### 并行工具调用\n```\n- 独立诊断步骤并行执行\n- 依赖步骤串行执行\n- 使用工具组管理相关调用\n```\n\n## 2. Agent Loop Pattern\n\n### 经典 ReAct 循环\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nThought: 基于结果调整策略\n... (循环直到解决)\n```\n\n### 改进版：带终止条件\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nReflection: 评估是否接近解决\n- 是 → 输出结论\n- 否 → 继续循环（最大 N 次）\n- 超时 → 输出部分结论 + 后续建议\n```\n\n## 3. Error Recovery Strategies\n\n### 指数退避重试\n```python\ndef retry_with_backoff(func, max_retries=3, base_delay=1):\n for attempt in range(max_retries):\n try:\n return func()\n except Exception as e:\n if attempt == max_retries - 1:\n raise\n delay = base_delay * (2 ** attempt)\n time.sleep(delay)\n```\n\n### 降级链模式\n```\n主方案: API 调用\n ↓ 失败\n降级1: 本地缓存\n ↓ 失败\n降级2: 备用 API\n ↓ 失败\n降级3: 手动提示用户\n```\n\n## 4. State Management\n\n### Checkpoint 模式\n```\n在执行关键操作前保存状态：\n{\n \"checkpoint_id\": \"uuid\",\n \"timestamp\": \"ISO-8601\",\n \"action\": \"正在执行的操作\",\n \"state_snapshot\": \"关键状态快照\",\n \"rollback_instructions\": \"回滚步骤\"\n}\n```\n\n### 会话管理\n```\n- 长会话：定期清理上下文\n- 子会话：隔离运行，完成后回收\n- 共享状态：使用文件系统或数据库\n```\n\n## 5. Evaluation & Testing\n\n### 自愈效果评估\n```\n指标:\n- 首次修复成功率\n- 平均修复时间 (MTTR)\n- 复发率（同一错误再次出现）\n- 误报率（错误诊断）\n\n监控:\n- 错误日志趋势\n- 修复操作成功率\n- 用户反馈评分\n```\n\n### A/B 测试修复策略\n```\n对同一类问题，测试不同修复策略：\n- 策略 A: 立即修复\n- 策略 B: 等待 + 重试\n- 策略 C: 降级到备用方案\n\n记录每种策略的成功率和耗时\n```\n\n## 6. Scalability Patterns\n\n### 工作队列\n```\n- 使用 cron 调度重复任务\n- 使用子 Agent 处理并发任务\n- 使用消息队列（如果可用）处理高峰\n```\n\n### 资源管理\n```\n- 监控 token 使用量\n- 设置并发子 Agent 上限\n- 定期清理临时文件\n- 使用轻量上下文模式\n```\n\n## 7. Observability\n\n### 日志分级\n```\nDEBUG: 详细诊断信息\nINFO: 正常操作流程\nWARNING: 潜在问题\nERROR: 明确的失败\nCRITICAL: 系统级故障\n```\n\n### 指标收集\n```\n- 工具调用成功率\n- 平均响应时间\n- Token 消耗趋势\n- 错误类型分布\n- 修复成功率\n```\n\nFile v1.3.0:references/self-evolution.md\n\n# 优化师自我进化工作流\n\n## 触发方式\n\n### Cron 自动触发\n- 每周日 03:00 执行一次（cron 任务：agent-optimizer-self-update）\n- 执行环境：isolated session, agentTurn\n\n### 手动触发\n- 用户说\"更新优化师的工程实践\"\n\n## 执行步骤\n\n### Step 1: 收集最新工程实践\n\n```bash\n# Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+claude+agent+engineering+tool+use+patterns+best+practices&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+structured+outputs+error+recovery&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# 行业 Agent 架构趋势\ncurl -s \"http://localhost:3004/search?q=llm+agent+architecture+patterns+self+healing+error+recovery+2026&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:3]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n```\n\n### Step 2: 对比与更新\n\n读取搜索结果后，对比以下文件：\n\n| 文件 | 检查内容 | 更新方式 |\n|------|---------|---------|\n| anthropic-patterns.md | 是否有新 Thinking/Tool Use 模式 | 追加新条目 |\n| openai-patterns.md | 是否有新 Agent 模式 | 追加新条目 |\n| error-taxonomy.md | 是否有新错误类型 | 新增分类 |\n| fix-templates.md | 是否有新修复方法 | 新增模板 |\n\n### Step 3: 清理过时内容\n\n检查 references/ 中的内容：\n- 标记已废弃的实践（用 `⚠️ 已废弃` 前缀）\n- 保留历史版本供参考\n- 不删除任何内容，只做标记\n\n### Step 4: 更新版本号\n\n在 SKILL.md 末尾的版本表中添加新记录：\n\n```markdown\n| v{x.y} | YYYY-MM-DD | 更新说明 |\n```\n\n## 更新规则\n\n### 必须满足\n- 只在确认有**新信息**时才更新\n- 更新内容必须**可验证**（有来源链接）\n- 更新后检查 SKILL.md 行数是否超过 400，超过则拆分\n\n### 禁止\n- 删除已有内容\n- 替换经过验证有效的实践\n- 添加未经验证的\"最佳实践\"\n\n## 输出格式\n\n更新完成后输出简要报告：\n\n```\n🔧 优化师自我进化完成\n\n新增: X 条工程实践\n- [条目1] - 来源\n- [条目2] - 来源\n\n更新: Y 条已有内容\n- [条目1] - 变更说明\n\n废弃: Z 条过时实践\n- [条目1] - 废弃原因\n```\n\nFile v1.3.0:TRIGGER-INTEGRATION.md\n\n# Agent 架构与工程优化师 - 触发机制集成\n\n## 自动触发条件\n\n以下场景自动触发 agent-optimizer skill：\n\n### 1. Cron 执行失败\n- 任务超时\n- Payload schema 错误\n- Session target 不匹配\n- 连续 2 次以上失败\n\n### 2. 工具调用异常\n- API 返回错误状态码\n- 权限不足\n- 网络连接失败\n- 超时或限流\n\n### 3. 工作流中断\n- 子 Agent 异常退出\n- 消息发送失败\n- 会话状态丢失\n\n### 4. 性能退化\n- 响应时间显著增加\n- Token 消耗异常增长\n- 错误率上升\n\n## 触发方式\n\n### 自动触发\n当检测到上述问题时，小七应：\n1. 读取 `skills/agent-optimizer/SKILL.md`\n2. 按照诊断工作流执行\n3. 输出修复建议\n4. 用户确认后执行修复\n5. 验证并记录\n\n### 手动触发\n用户明确要求时：\n- \"检查一下系统问题\"\n- \"优化一下配置\"\n- \"诊断一下为什么失败\"\n\n## 集成到现有流程\n\n### Heartbeat 集成\n在 HEARTBEAT.md 中添加优化师巡检：\n\n```markdown\n# 🔄 Agent 健康度检查（每月一次）\n- 读取 learnings/error-log.md，分析错误趋势\n- 检查 cron 任务成功率\n- 评估 token 使用效率\n- 输出优化建议\n```\n\n### 错误处理集成\n在工具调用失败后：\n1. 记录错误到 learnings/error-log.md\n2. 判断是否触发优化师\n3. 执行诊断和修复\n\n## 权限与安全\n\n### 自动执行范围\n- ✅ 读取日志和状态\n- ✅ 临时文件清理\n- ✅ 重试限流错误（≤3次）\n- ✅ 更新心跳文件\n\n### 需确认操作\n- ⚠️ 修改 cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n\n### 禁止自动执行\n- ❌ 修改核心身份文件（SOUL.md/IDENTITY.md）\n- ❌ 发送外部消息\n- ❌ 删除不可恢复数据\n\nArchive v1.2.0: 8 files, 14942 bytes\n\nFiles: references/anthropic-patterns.md (2894b), references/error-taxonomy.md (3701b), references/fix-templates.md (3873b), references/openai-patterns.md (3087b), references/self-evolution.md (2718b), SKILL.md (9603b), TRIGGER-INTEGRATION.md (1726b), _meta.json (144b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: agent-optimization-expert\ndescription: Agent 优化专家 — 自动诊断和修复 OpenClaw 执行问题（Cron 失败、工具报错、工作流中断、性能退化），自带持续自我进化能力。\n Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、诊断失败原因、修复任务失败、优化师自我更新、Agent优化.\n 不适用于业务逻辑问题排查、飞书内容编辑、数据查询类任务.\n---\n\n# Agent 优化专家\n\n## 概述\n\n基于 Anthropic / OpenAI 工程实践的 Agent 自愈引擎，覆盖「检测 → 诊断 → 修复 → 验证 → 学习 → 进化」闭环。\n\n### 功能范围\n\n- Cron 任务诊断与修复（失败/超时/disabled/配置错误）\n- 工具调用异常诊断（认证/权限/限流/超时/参数）\n- 子 Agent 异常诊断（spawn 失败/超时/上下文过大）\n- 系统健康度巡检（资源/网络/磁盘/内存）\n- **自我进化**：定期收集工程实践、更新 references/、沉淀新模式\n- 错误模式学习与沉淀（learnings/error-log.md → fix-templates.md 自动升级）\n\n---\n\n## 使用\n\n### 场景 1：Cron 任务执行失败\n\n```bash\n# Step 1 — 快速扫描\nopenclaw cron list --includeDisabled\n\n# Step 2 — 定位失败 job，查看 runs 历史\nopenclaw cron runs \n\n# Step 3 — 常见修复（参照 references/fix-templates.md）\n# A. sessionTarget/payload 不匹配\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"}.\",\"sessionTarget\":\"main\"}'\n\n# B. 超时 → 增大 timeoutSeconds\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n\n# C. disabled → 重新启用\nopenclaw cron update --patch '{\"enabled\":true}'\n\n# Step 4 — 验证\nopenclaw cron runs --limit 1\n```\n\n**修复规则**：\n- `sessionTarget=\"main\"` → `payload.kind` 必须是 `\"systemEvent\"`\n- `sessionTarget=\"isolated\"/\"current\"` → `payload.kind` 必须是 `\"agentTurn\"`\n- 超时问题先尝试 `timeoutSeconds` 加倍，若仍超时则拆分 payload 逻辑\n\n### 场景 2：工具调用连续失败\n\n```bash\n# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限\necho $API_KEY | wc -c # 检查 key 是否存在\n\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)\n```\n\n### 场景 3：系统健康度巡检\n\n```bash\n# 资源检查\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# OpenClaw 状态\nopenclaw status\n```\n\n### 场景 4：子 Agent 异常\n\n```bash\n# 检查活跃子 Agent\nopenclaw subagents list --recentMinutes 60\n\n# 终止卡死的\nopenclaw subagents kill \n\n# 重新生成时的优化选择\n# - 轻量任务: lightContext=true\n# - 不需要当前上下文: context=\"isolated\"\n# - 需要上下文: context=\"fork\"\n# - 长任务: runTimeoutSeconds=600\n```\n\n---\n\n## 诊断决策树\n\n遇到问题时，按以下路径快速定位：\n\n```\n问题出现\n│\n├─ Cron 相关？\n│ ├─ 任务未执行 → 检查 enabled / schedule 表达式 / timezone\n│ ├─ 执行报错 → 检查 runs 历史 → 对照 fix-templates.md\n│ └─ 超时 → 增加 timeoutSeconds 或拆分逻辑\n│\n├─ 工具调用相关？\n│ ├─ 401/403 → 检查认证/权限（feishu_app_scopes / 环境变量）\n│ ├─ 429 → 指数退避重试（1s→2s→4s）\n│ ├─ 5xx → 等待重试，记录日志\n│ └─ 连接超时 → 检查网络 → 降级到备用方案\n│\n├─ 子 Agent 相关？\n│ ├─ spawn 失败 → 检查 task 内容是否过大 / 资源不足\n│ ├─ 超时 → 增加 runTimeoutSeconds 或优化 task\n│ └─ 结果异常 → 检查 context 模式是否正确\n│\n└─ 系统相关？\n ├─ 磁盘满 → 清理 memory/learnings 过期文件 + docker prune\n ├─ 内存不足 → 停止非必要服务 + 使用 lightContext\n └─ 网络断开 → 检查 DNS / 防火墙\n```\n\n## 自愈闭环\n\n```\n检测（心跳/用户反馈/错误日志）\n → 诊断（四层模型：快速扫描 → 错误分析 → 根因推理 → 修复建议）\n → 修复（最小变更 + 可回滚）\n → 验证（修复后确认）\n → 学习（记录到 learnings/error-log.md）\n```\n\n### 错误日志格式（learnings/error-log.md）\n\n```markdown\n## YYYY-MM-DD HH:MM\n- **Error**: [错误描述]\n- **Context**: [触发场景]\n- **Root Cause**: [根因分析]\n- **Fix Applied**: [修复操作]\n- **Prevention**: [避免复现的措施]\n```\n\n## 操作分级与安全\n\n| 级别 | 范围 | 策略 |\n|------|------|------|\n| L0 | 读取状态、检查日志 | 自动执行 |\n| L1 | 清理临时文件、更新日志 | 自动执行 |\n| L2 | 修改 cron 配置、重启服务 | 提示用户确认 |\n| L3 | 修改核心配置、删除数据 | 必须用户明确授权 |\n\n**禁止自动执行**：\n- ❌ 修改 SOUL.md / IDENTITY.md / USER.md\n- ❌ 发送外部消息（邮件/飞书/社交）\n- ❌ 删除不可恢复的数据\n\n## 参考文件\n\n| 文件 | 何时读取 |\n|------|---------|\n| [references/anthropic-patterns.md](references/anthropic-patterns.md) | 需要了解 Thinking/Tool Use/多 Agent 协调模式时 |\n| [references/openai-patterns.md](references/openai-patterns.md) | 需要 ReAct 循环/降级链/评估模式时 |\n| [references/error-taxonomy.md](references/error-taxonomy.md) | 工具调用失败，需要分类诊断时 |\n| [references/fix-templates.md](references/fix-templates.md) | 确认修复方案后，查找具体修复命令时 |\n| [references/self-evolution.md](references/self-evolution.md) | 自我进化任务：收集最新实践、更新 references/ |\n\n## 自我进化机制\n\n优化师不是一次性写好的，它会持续进化。进化分三个路径：\n\n### 路径 1：错误驱动进化（每次诊断后自动触发）\n\n每次修复问题后，检查是否产生新的修复模板或需要更新错误分类：\n\n```\n修复完成\n│\n├─ 这是新错误类型？\n│ ├─ 是 → 新增 error-taxonomy.md 条目 + fix-templates.md 模板\n│ └─ 否 → 更新 error-taxonomy.md 中的复发计数\n│\n├─ 修复方法可复用？\n│ ├─ 是 → 写入 fix-templates.md\n│ └─ 否 → 记录到 learnings/error-log.md\n│\n└─ 涉及工程模式？\n ├─ 是 → 更新对应 references/ 文件\n └─ 否 → 跳过\n```\n\n### 路径 2：定期知识更新（每周 Cron 任务触发）\n\n每周自动执行一次工程实践收集：\n\n1. **搜索最新实践**：用 SearXNG 搜索 Anthropic/OpenAI 最新工程文档\n2. **对比已有内容**：与 references/ 中的内容对比\n3. **提取新模式**：发现新方法时追加到对应 references/ 文件\n4. **清理过时内容**：标记已过时的实践\n5. **更新版本号**：在 SKILL.md 末尾记录最后更新时间和版本号\n\n执行脚本：`references/scripts/self-update.sh`（如果存在）或手动执行：\n\n```bash\n# 搜索 Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+agent+engineering+best+practices+tool+use+patterns+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n\n# 搜索 OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+error+handling+best+practices+$(date +%Y)&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(json.dumps({'title': r.get('title',''), 'url': r.get('url','')}, ensure_ascii=False))\n\"\n```\n\n更新规则：\n- **新增模式**：追加到 references/ 对应文件末尾，标注日期\n- **更新模式**：修改现有条目，保留旧内容作为「历史版本」\n- **废弃模式**：标记为「⚠️ 已废弃 - 原因」，不删除\n\n### 路径 3：错误日志驱动进化（每次 error-log.md 更新后检查）\n\n当 learnings/error-log.md 中出现 3 次以上相同错误模式时：\n\n1. 创建或更新 fix-templates.md 中的对应模板\n2. 更新 error-taxonomy.md 中的优先级\n3. 如果是新型错误，新增分类条目\n\n## 主动巡检触发\n\n除问题触发外，以下场景也应主动巡检：\n\n- **每周自检**（HEARTBEAT.md 中配置）：检查 cron 健康度、工具失败回顾\n- **用户反馈响应变慢**：分析 token 使用、session 状态\n- **新服务部署后**：验证服务健康度、更新 TOOLS.md\n- **自我进化周任务**：每周日 03:00 执行工程实践收集\n\n## 版本与更新记录\n\n> 记录优化师自身的迭代历史，便于追踪进化轨迹。\n\n| 版本 | 日期 | 更新内容 |\n|------|------|----------|\n| v1.0 | 2026-05-18 | 初始创建（四层骨架 + 诊断决策树 + 修复模板） |\n| v1.1 | 2026-05-18 | 添加自我进化机制（三条路径：错误驱动/定期知识更新/错误日志驱动） |\n\nFile v1.2.0:_meta.json\n\n{\n \"ownerId\": \"kn70tx725606ywwb5gfj0vpxjx83admr\",\n \"slug\": \"agent-optimization-expert\",\n \"version\": \"1.2.0\",\n \"publishedAt\": 1779077994799\n}\n\nFile v1.2.0:references/anthropic-patterns.md\n\n# Anthropic 工程实践模式\n\n## 1. Extended Thinking Pattern\n\nAnthropic Claude 的核心优势是 extended thinking（扩展思考）模式。\n\n### 使用场景\n- 复杂问题分解\n- 多步骤推理\n- 代码架构设计\n- 错误诊断与修复\n\n### 实践要点\n```\n1. 在思考阶段明确列出假设\n2. 对每个假设进行验证\n3. 记录推理链条\n4. 最终输出时提炼结论，隐藏中间过程\n```\n\n### OpenClaw 映射\n- `thinking` 参数控制思考级别\n- 复杂诊断任务启用 thinking 模式\n- 子 Agent 使用 thinking 进行深度分析\n\n## 2. Tool Use Best Practices\n\n### 预检-执行-后检模式\n```\n预检: 验证输入参数、权限、依赖状态\n执行: 调用工具，带超时和重试\n后检: 验证结果完整性、一致性\n```\n\n### 错误处理策略\n```\n1. 捕获具体错误类型（非通用异常）\n2. 分类处理：\n - 可重试：指数退避重试\n - 需修正：调整参数重试\n - 不可恢复：降级到备用方案\n3. 记录错误模式到学习库\n```\n\n## 3. Multi-Agent Coordination\n\n### 子 Agent 使用原则\n```\n- context=\"isolated\"：新任务，无需上下文\n- context=\"fork\"：需要当前对话上下文\n- runTimeoutSeconds：设置合理超时\n- 使用 sessions_yield 等待完成，不轮询\n```\n\n### 通信模式\n```\n主 Agent → 子 Agent: sessions_spawn(task, taskName)\n子 Agent → 主 Agent: 完成事件自动传递\n主 Agent ↔ 子 Agent: sessions_send 进行中途交互\n```\n\n## 4. Prompt Engineering Patterns\n\n### 结构化输出\n```\n使用明确的输出格式要求：\n- JSON schema 定义\n- Markdown 模板\n- 明确的字段名称\n```\n\n### 角色分离\n```\n不同任务使用不同的角色提示：\n- 诊断模式：\"你是一个系统诊断专家...\"\n- 修复模式：\"你是一个运维工程师...\"\n- 优化模式：\"你是一个性能调优专家...\"\n```\n\n### 自反思模式\n```\n在关键决策后添加：\n\"在继续之前，请反思你的分析：\n1. 是否遗漏了重要信息？\n2. 假设是否合理？\n3. 有没有其他可能的解释？\"\n```\n\n## 5. Context Management\n\n### 上下文优化\n```\n- 使用 memory_search 检索相关信息，而非全部加载\n- 大型文件使用 offset/limit 分段读取\n- 子 Agent 使用 lightContext 减少 token\n- 定期清理过期的 session 状态\n```\n\n### Token 预算\n```\n诊断任务：< 5000 tokens\n修复任务：< 10000 tokens\n复杂分析：使用子 Agent 隔离\n```\n\n## 6. Safety & Guardrails\n\n### 操作分级\n```\nL0 - 安全：读取文件、检查状态\nL1 - 低风险：修改临时文件、更新日志\nL2 - 中风险：修改配置、重启服务\nL3 - 高风险：删除数据、修改核心配置\n\nL0-L1: 自动执行\nL2: 提示用户确认\nL3: 必须用户明确授权\n```\n\n### 审计日志\n```\n所有 L2+ 操作记录到：\n- learnings/error-log.md\n- memory/YYYY-MM-DD.md\n- 包含：操作时间、内容、原因、结果\n```\n\nFile v1.2.0:references/error-taxonomy.md\n\n# 错误分类与处理策略\n\n## 错误分类体系\n\n### L1: 工具调用错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **认证失败** | 401 Unauthorized | 检查 API Key/Token，提示更新 |\n| **权限不足** | 403 Forbidden | 检查权限配置，申请授权 |\n| **资源不存在** | 404 Not Found | 验证 ID/路径，检查拼写 |\n| **限流** | 429 Too Many Requests | 指数退避重试，检查配额 |\n| **服务器错误** | 5xx | 重试或等待，记录到日志 |\n| **超时** | Timeout | 增加超时或优化请求 |\n| **参数错误** | Invalid parameters | 修正参数格式 |\n\n### L2: 工作流错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **Cron 失败** | 任务未执行/执行报错 | 检查 schedule/payload/sessionTarget |\n| **子 Agent 异常** | spawn 失败/超时 | 检查参数/资源/权限 |\n| **消息发送失败** | 投递失败/格式错误 | 检查 channel/target/format |\n| **会话中断** | Session 丢失 | 重建会话，恢复上下文 |\n\n### L3: 系统错误\n\n| 错误类型 | 示例 | 处理策略 |\n|---------|------|---------|\n| **内存不足** | OOM Killer | 减少并发，使用轻量模式 |\n| **磁盘满** | No space left | 清理临时文件，清理旧日志 |\n| **网络断开** | Connection refused | 检查网络，重试或降级 |\n| **配置损坏** | 解析错误 | 从备份恢复，检查语法 |\n\n## 诊断决策树\n\n```\n错误发生\n│\n├─ 是工具调用错误？\n│ ├─ 认证问题 → 检查凭证\n│ ├─ 权限问题 → 检查授权\n│ ├─ 限流问题 → 退避重试\n│ └─ 参数问题 → 修正格式\n│\n├─ 是工作流错误？\n│ ├─ Cron 问题 → 检查 job 配置\n│ ├─ 子 Agent 问题 → 检查 spawn 参数\n│ └─ 消息问题 → 检查 channel 配置\n│\n└─ 是系统错误？\n ├─ 资源问题 → 释放资源\n └─ 配置问题 → 恢复备份\n```\n\n## 常见错误模式库\n\n### Cron 相关\n\n#### 错误：sessionTarget 与 payload.kind 不匹配\n```\n症状: \"sessionTarget='main' requires payload.kind='systemEvent'\"\n修复: \n - main → systemEvent\n - isolated/current → agentTurn\n```\n\n#### 错误：Cron 任务超时\n```\n症状: \"Task timed out after X seconds\"\n修复:\n - 增加 payload.timeoutSeconds\n - 优化任务内容，减少复杂度\n - 使用子 Agent 处理重型任务\n```\n\n#### 错误：Cron 未触发\n```\n症状: 任务到时间未执行\n诊断:\n 1. cron list 检查 enabled 状态\n 2. 检查 schedule 表达式\n 3. 检查 timezone 配置\n 4. 检查 Gateway 运行状态\n```\n\n### 飞书相关\n\n#### 错误：权限不足\n```\n症状: \"Permission denied\" 或 \"insufficient scope\"\n修复:\n 1. feishu_app_scopes 检查当前权限\n 2. 确认所需 scope\n 3. 在飞书开放平台申请额外权限\n```\n\n#### 错误：Token 过期\n```\n症状: \"Token expired\" 或 \"Invalid token\"\n修复:\n 1. 刷新访问令牌\n 2. 检查 token 刷新机制\n 3. 重新认证\n```\n\n### 网络相关\n\n#### 错误：连接超时\n```\n症状: \"Connection timeout\"\n诊断:\n 1. ping 测试目标主机\n 2. 检查 DNS 解析\n 3. 检查防火墙规则\n 4. 尝试备用端点\n```\n\n## 自动修复规则\n\n### 可自动修复\n- ✅ Cron 任务 disabled → 重新启用\n- ✅ 临时文件清理\n- ✅ 重试限流错误（最多 3 次）\n- ✅ 更新心跳状态文件\n\n### 需确认后修复\n- ⚠️ 修改 Cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n- ⚠️ 删除大量数据\n\n### 不可自动修复\n- ❌ 修改核心身份文件\n- ❌ 发送外部消息（邮件、飞书）\n- ❌ 删除不可恢复的数据\n- ❌ 安装新软件/依赖\n\nFile v1.2.0:references/fix-templates.md\n\n# 常见修复模板库\n\n## Cron 修复模板\n\n### 1. 修复 sessionTarget/payload 不匹配\n\n**诊断**:\n```bash\nopenclaw cron get \n```\n\n**修复命令**:\n```bash\n# 情况 A: main session 需要 systemEvent\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"},\"sessionTarget\":\"main\"}'\n\n# 情况 B: isolated session 需要 agentTurn \nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"agentTurn\",\"message\":\"...\"},\"sessionTarget\":\"isolated\"}'\n```\n\n**验证**:\n```bash\nopenclaw cron runs --limit 1\n```\n\n### 2. 修复超时问题\n\n**诊断**:\n```bash\nopenclaw cron runs \n# 查找 \"timed out\" 或 \"timeout\" 错误\n```\n\n**修复命令**:\n```bash\n# 增加超时时间\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n```\n\n### 3. 修复 disabled 状态\n\n**诊断**:\n```bash\nopenclaw cron list --includeDisabled\n# 查找 enabled: false 的任务\n```\n\n**修复命令**:\n```bash\nopenclaw cron update --patch '{\"enabled\":true}'\n```\n\n### 4. 修复 cron 表达式\n\n**诊断**:\n```bash\nopenclaw cron get \n# 检查 schedule.expr 和 schedule.tz\n```\n\n**修复命令**:\n```bash\n# 更新为正确的 cron 表达式（本地时间）\nopenclaw cron update \\\n --patch '{\"schedule\":{\"kind\":\"cron\",\"expr\":\"0 9 * * 1-5\",\"tz\":\"Asia/Shanghai\"}}'\n```\n\n## 工具修复模板\n\n### 5. 刷新飞书权限\n\n**诊断**:\n```bash\nfeishu_app_scopes\n```\n\n**修复**: 提示用户在飞书开放平台申请所需权限\n\n### 6. 服务健康检查\n\n**诊断**:\n```bash\n# 检查 Docker 服务\ndocker ps --filter \"status=exited\"\n\n# 检查端口\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3004/health # SearXNG\ncurl -s http://localhost:3003/health # Crawl4AI\n```\n\n**修复**:\n```bash\n# 重启特定服务\ncd ~/firecrawl && docker compose up -d\ncd ~/searxng && docker compose up -d\n```\n\n### 7. 清理磁盘空间\n\n**诊断**:\n```bash\ndf -h /\ndu -sh ~/.openclaw/workspace/memory/ 2>/dev/null\ndu -sh ~/.openclaw/workspace/learnings/ 2>/dev/null\n```\n\n**修复**:\n```bash\n# 清理超过 30 天的日志\nfind ~/.openclaw/workspace/memory/ -name \"*.md\" -mtime +30 -delete 2>/dev/null\n\n# 清理 Docker 无用资源\ndocker system prune -f 2>/dev/null\n```\n\n## 子 Agent 修复模板\n\n### 8. 子 Agent 超时\n\n**诊断**:\n```bash\nopenclaw subagents list --recentMinutes 60\n# 查找超时或失败的子 Agent\n```\n\n**修复**:\n```bash\n# 终止卡死的子 Agent\nopenclaw subagents kill \n\n# 重新生成，增加超时\nsessions_spawn(task=\"...\", runTimeoutSeconds=600)\n```\n\n### 9. 子 Agent 上下文过大\n\n**诊断**:\n```bash\nopenclaw sessions list --limit 10\n# 检查 session 大小\n```\n\n**修复**:\n```bash\n# 使用轻量上下文\nsessions_spawn(task=\"...\", lightContext=true)\n\n# 或使用隔离上下文\nsessions_spawn(task=\"...\", context=\"isolated\")\n```\n\n## 系统修复模板\n\n### 10. Gateway 重启\n\n**诊断**:\n```bash\nopenclaw status\n```\n\n**修复**:\n```bash\nopenclaw gateway restart --reason \"优化修复后重启\"\n```\n\n### 11. 内存压力\n\n**诊断**:\n```bash\nfree -m\n# 检查可用内存\n```\n\n**修复**:\n```bash\n# 停止非必要服务\ncd ~/firecrawl && docker compose stop # 按需启动\ncd ~/crawl4ai-server && ... # 检查是否需要\n\n# 或重启 Gateway\nopenclaw gateway restart\n```\n\n## 验证模板\n\n### 修复后验证清单\n\n```markdown\n## 修复验证\n- [ ] cron 任务正常运行: `openclaw cron list`\n- [ ] 错误日志无新错误: `cat learnings/error-log.md`\n- [ ] 相关工具可用: 测试调用\n- [ ] 用户通知: 告知修复结果\n```\n\n### 修复报告格式\n\n```markdown\n## 🔧 修复报告\n\n**问题**: [问题描述]\n**根因**: [原因分析]\n**修复**: [执行的操作]\n**状态**: ✅ 已修复 / ⚠️ 部分修复 / ❌ 需要人工干预\n**验证**: [验证结果]\n**后续**: [预防措施或待办事项]\n```\n\nFile v1.2.0:references/openai-patterns.md\n\n# OpenAI Agent 工程最佳实践\n\n## 1. Function Calling Pattern\n\n### 工具定义最佳实践\n```json\n{\n \"name\": \"execute_fix\",\n \"description\": \"执行修复操作\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"action\": {\"type\": \"string\", \"enum\": [\"diagnose\", \"repair\", \"verify\"]},\n \"target\": {\"type\": \"string\"},\n \"parameters\": {\"type\": \"object\"}\n },\n \"required\": [\"action\", \"target\"]\n }\n}\n```\n\n### 并行工具调用\n```\n- 独立诊断步骤并行执行\n- 依赖步骤串行执行\n- 使用工具组管理相关调用\n```\n\n## 2. Agent Loop Pattern\n\n### 经典 ReAct 循环\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nThought: 基于结果调整策略\n... (循环直到解决)\n```\n\n### 改进版：带终止条件\n```\nThought: 分析当前状态\nAction: 调用工具\nObservation: 检查结果\nReflection: 评估是否接近解决\n- 是 → 输出结论\n- 否 → 继续循环（最大 N 次）\n- 超时 → 输出部分结论 + 后续建议\n```\n\n## 3. Error Recovery Strategies\n\n### 指数退避重试\n```python\ndef retry_with_backoff(func, max_retries=3, base_delay=1):\n for attempt in range(max_retries):\n try:\n return func()\n except Exception as e:\n if attempt == max_retries - 1:\n raise\n delay = base_delay * (2 ** attempt)\n time.sleep(delay)\n```\n\n### 降级链模式\n```\n主方案: API 调用\n ↓ 失败\n降级1: 本地缓存\n ↓ 失败\n降级2: 备用 API\n ↓ 失败\n降级3: 手动提示用户\n```\n\n## 4. State Management\n\n### Checkpoint 模式\n```\n在执行关键操作前保存状态：\n{\n \"checkpoint_id\": \"uuid\",\n \"timestamp\": \"ISO-8601\",\n \"action\": \"正在执行的操作\",\n \"state_snapshot\": \"关键状态快照\",\n \"rollback_instructions\": \"回滚步骤\"\n}\n```\n\n### 会话管理\n```\n- 长会话：定期清理上下文\n- 子会话：隔离运行，完成后回收\n- 共享状态：使用文件系统或数据库\n```\n\n## 5. Evaluation & Testing\n\n### 自愈效果评估\n```\n指标:\n- 首次修复成功率\n- 平均修复时间 (MTTR)\n- 复发率（同一错误再次出现）\n- 误报率（错误诊断）\n\n监控:\n- 错误日志趋势\n- 修复操作成功率\n- 用户反馈评分\n```\n\n### A/B 测试修复策略\n```\n对同一类问题，测试不同修复策略：\n- 策略 A: 立即修复\n- 策略 B: 等待 + 重试\n- 策略 C: 降级到备用方案\n\n记录每种策略的成功率和耗时\n```\n\n## 6. Scalability Patterns\n\n### 工作队列\n```\n- 使用 cron 调度重复任务\n- 使用子 Agent 处理并发任务\n- 使用消息队列（如果可用）处理高峰\n```\n\n### 资源管理\n```\n- 监控 token 使用量\n- 设置并发子 Agent 上限\n- 定期清理临时文件\n- 使用轻量上下文模式\n```\n\n## 7. Observability\n\n### 日志分级\n```\nDEBUG: 详细诊断信息\nINFO: 正常操作流程\nWARNING: 潜在问题\nERROR: 明确的失败\nCRITICAL: 系统级故障\n```\n\n### 指标收集\n```\n- 工具调用成功率\n- 平均响应时间\n- Token 消耗趋势\n- 错误类型分布\n- 修复成功率\n```\n\nFile v1.2.0:references/self-evolution.md\n\n# 优化师自我进化工作流\n\n## 触发方式\n\n### Cron 自动触发\n- 每周日 03:00 执行一次（cron 任务：agent-optimizer-self-update）\n- 执行环境：isolated session, agentTurn\n\n### 手动触发\n- 用户说\"更新优化师的工程实践\"\n\n## 执行步骤\n\n### Step 1: 收集最新工程实践\n\n```bash\n# Anthropic 最新实践\ncurl -s \"http://localhost:3004/search?q=anthropic+claude+agent+engineering+tool+use+patterns+best+practices&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# OpenAI 最新实践\ncurl -s \"http://localhost:3004/search?q=openai+agent+patterns+function+calling+structured+outputs+error+recovery&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:5]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n\n# 行业 Agent 架构趋势\ncurl -s \"http://localhost:3004/search?q=llm+agent+architecture+patterns+self+healing+error+recovery+2026&format=json&engines=bing,duckduckgo\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor r in data.get('results', [])[:3]:\n print(f'- [{r.get(\\\"title\\\",\\\"\\\")}]({r.get(\\\"url\\\",\\\"\\\")})')\n\" 2>/dev/null\n```\n\n### Step 2: 对比与更新\n\n读取搜索结果后，对比以下文件：\n\n| 文件 | 检查内容 | 更新方式 |\n|------|---------|---------|\n| anthropic-patterns.md | 是否有新 Thinking/Tool Use 模式 | 追加新条目 |\n| openai-patterns.md | 是否有新 Agent 模式 | 追加新条目 |\n| error-taxonomy.md | 是否有新错误类型 | 新增分类 |\n| fix-templates.md | 是否有新修复方法 | 新增模板 |\n\n### Step 3: 清理过时内容\n\n检查 references/ 中的内容：\n- 标记已废弃的实践（用 `⚠️ 已废弃` 前缀）\n- 保留历史版本供参考\n- 不删除任何内容，只做标记\n\n### Step 4: 更新版本号\n\n在 SKILL.md 末尾的版本表中添加新记录：\n\n```markdown\n| v{x.y} | YYYY-MM-DD | 更新说明 |\n```\n\n## 更新规则\n\n### 必须满足\n- 只在确认有**新信息**时才更新\n- 更新内容必须**可验证**（有来源链接）\n- 更新后检查 SKILL.md 行数是否超过 400，超过则拆分\n\n### 禁止\n- 删除已有内容\n- 替换经过验证有效的实践\n- 添加未经验证的\"最佳实践\"\n\n## 输出格式\n\n更新完成后输出简要报告：\n\n```\n🔧 优化师自我进化完成\n\n新增: X 条工程实践\n- [条目1] - 来源\n- [条目2] - 来源\n\n更新: Y 条已有内容\n- [条目1] - 变更说明\n\n废弃: Z 条过时实践\n- [条目1] - 废弃原因\n```\n\nFile v1.2.0:TRIGGER-INTEGRATION.md\n\n# Agent 架构与工程优化师 - 触发机制集成\n\n## 自动触发条件\n\n以下场景自动触发 agent-optimizer skill：\n\n### 1. Cron 执行失败\n- 任务超时\n- Payload schema 错误\n- Session target 不匹配\n- 连续 2 次以上失败\n\n### 2. 工具调用异常\n- API 返回错误状态码\n- 权限不足\n- 网络连接失败\n- 超时或限流\n\n### 3. 工作流中断\n- 子 Agent 异常退出\n- 消息发送失败\n- 会话状态丢失\n\n### 4. 性能退化\n- 响应时间显著增加\n- Token 消耗异常增长\n- 错误率上升\n\n## 触发方式\n\n### 自动触发\n当检测到上述问题时，小七应：\n1. 读取 `skills/agent-optimizer/SKILL.md`\n2. 按照诊断工作流执行\n3. 输出修复建议\n4. 用户确认后执行修复\n5. 验证并记录\n\n### 手动触发\n用户明确要求时：\n- \"检查一下系统问题\"\n- \"优化一下配置\"\n- \"诊断一下为什么失败\"\n\n## 集成到现有流程\n\n### Heartbeat 集成\n在 HEARTBEAT.md 中添加优化师巡检：\n\n```markdown\n# 🔄 Agent 健康度检查（每月一次）\n- 读取 learnings/error-log.md，分析错误趋势\n- 检查 cron 任务成功率\n- 评估 token 使用效率\n- 输出优化建议\n```\n\n### 错误处理集成\n在工具调用失败后：\n1. 记录错误到 learnings/error-log.md\n2. 判断是否触发优化师\n3. 执行诊断和修复\n\n## 权限与安全\n\n### 自动执行范围\n- ✅ 读取日志和状态\n- ✅ 临时文件清理\n- ✅ 重试限流错误（≤3次）\n- ✅ 更新心跳文件\n\n### 需确认操作\n- ⚠️ 修改 cron 配置\n- ⚠️ 重启服务\n- ⚠️ 修改系统配置\n\n### 禁止自动执行\n- ❌ 修改核心身份文件（SOUL.md/IDENTITY.md）\n- ❌ 发送外部消息\n- ❌ 删除不可恢复数据","readmeExcerpt":"Skill: Agent优化专家 Owner: tuobadaidai Summary: Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因... Tags: agent:1.4.0, cron:1.4.0, diagnostics:1.4.0, hermes:1.4.0, latest:1.4.0, openclaw:1.4.0, self-evolution:1.4.0, self-healing:1.4.0 Version history: v1.0.1 | 2026-07-24T09:16:09.888Z | user Restore from backup -","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Step 1 — 快速扫描\nopenclaw cron list --includeDisabled\n\n# Step 2 — 定位失败 job，查看 runs 历史\nopenclaw cron runs \n\n# Step 3 — 常见修复（参照 references/fix-templates.md）\n# A. sessionTarget/payload 不匹配\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"}.\",\"sessionTarget\":\"main\"}'\n\n# B. 超时 → 增大 timeoutSeconds\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n\n# C. disabled → 重新启用\nopenclaw cron update --patch '{\"enabled\":true}'\n\n# Step 4 — 验证\nopenclaw cron runs --limit 1"},{"language":"bash","snippet":"# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限\necho $API_KEY | wc -c # 检查 key 是否存在\n\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)"},{"language":"bash","snippet":"curl -s http://localhost:3002/health # Firecrawl"},{"language":"bash","snippet":"curl -s http://localhost:3003/health # Crawl4AI"},{"language":"bash","snippet":"curl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）"},{"language":"bash","snippet":"# 资源检查\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# OpenClaw 状态\nopenclaw status"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agent-optimization-expert\ndescription: Agent 优化专家 — 自动诊断和修复 OpenClaw 执行问题（Cron 失败、工具报错、工作流中断、性能退化），自带持续自我进化能力。\n Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、诊断失败原因、修复任务失败、优化师自我更新、Agent优化.\n 不适用于业务逻辑问题排查、飞书内容编辑、数据查询类任务.\n---\n\n# Agent 优化专家\n\n## 概述\n\n基于 Anthropic / OpenAI 工程实践的 Agent 自愈引擎，覆盖「检测 → 诊断 → 修复 → 验证 → 学习 → 进化」闭环。\n\n### 功能范围\n\n- Cron 任务诊断与修复（失败/超时/disabled/配置错误）\n- 工具调用异常诊断（认证/权限/限流/超时/参数）\n- 子 Agent 异常诊断（spawn 失败/超时/上下文过大）\n- 系统健康度巡检（资源/网络/磁盘/内存）\n- **自我进化**：定期收集工程实践、更新 references/、沉淀新模式\n- 错误模式学习与沉淀（learnings/error-log.md → fix-templates.md 自动升级）\n\n---\n\n## 使用\n\n### 场景 1：Cron 任务执行失败\n\n```bash\n# Step 1 — 快速扫描\nopenclaw cron list --includeDisabled\n\n# Step 2 — 定位失败 job，查看 runs 历史\nopenclaw cron runs \n\n# Step 3 — 常见修复（参照 references/fix-templates.md）\n# A. sessionTarget/payload 不匹配\nopenclaw cron update \\\n --patch '{\"payload\":{\"kind\":\"systemEvent\",\"text\":\"...\"}.\",\"sessionTarget\":\"main\"}'\n\n# B. 超时 → 增大 timeoutSeconds\nopenclaw cron update \\\n --patch '{\"payload\":{\"timeoutSeconds\":300}}'\n\n# C. disabled → 重新启用\nopenclaw cron update --patch '{\"enabled\":true}'\n\n# Step 4 — 验证\nopenclaw cron runs --limit 1\n```\n\n**修复规则**：\n- `sessionTarget=\"main\"` → `payload.kind` 必须是 `\"systemEvent\"`\n- `sessionTarget=\"isolated\"/\"current\"` → `payload.kind` 必须是 `\"agentTurn\"`\n- 超时问题先尝试 `timeoutSeconds` 加倍，若仍超时则拆分 payload 逻辑\n\n### 场景 2：工具调用连续失败\n\n```bash\n# Step 1 — 检查错误日志\ncat learnings/error-log.md 2>/dev/null | tail -50\n\n# Step 2 — 按错误类型定位（参照 references/error-taxonomy.md）\n# 401/403 → 认证/权限问题\nfeishu_app_scopes # 检查飞书权限\necho $API_KEY | wc -c # 检查 key 是否存在\n\n# 429 → 限流，等待 + 指数退避重试\n# 5xx → 服务端错误，稍后重试\n\n# Step 3 — 应用降级策略\n# 搜索: web_search → SearXNG(local:3004) → web_fetch\n# 网页: web_fetch → firecrawl(local:3002)\n```\n\n### 场景 3：系统健康度巡检\n\n```bash\n# 资源检查\ndf -h / # 磁盘\nfree -m # 内存\ndocker ps # 容器状态\n\n# 服务健康检查\ncurl -s http://localhost:3002/health # Firecrawl\ncurl -s http://localhost:3003/health # Crawl4AI\ncurl -s http://localhost:3004/health # SearXNG（返回 HTML 即正常）\n\n# OpenClaw 状态\nopenclaw status\n```\n\n### 场景 4：子 Agent 异常\n\n```bash\n# 检查活跃子 Agent\nopenclaw subagents list --recentMinutes 60\n\n# 终止卡死的\nopenclaw subagents kill \n\n# 重新生成时的优化选择\n# - 轻量任务: lightContext=true\n# - 不需要当前上下文: context=\"isolated\"\n# - 需要上下文: context=\"fork\"\n# - 长任务: runTimeoutSeconds=600\n```\n\n---\n\n## 诊断决策树\n\n遇到问题时，按以下路径快速定位：\n\n```\n问题出现\n│\n├─ Cron 相关？\n│ ├─ 任务未执行 → 检查 enabled / schedule 表达式 / timezone\n│ ├─ 执行报错 → 检查 runs 历史 → 对照 fix-templates.md\n│ └─ 超时 → 增加 timeoutSeconds 或拆分逻辑\n│\n├─ 工具调用相关？\n│ ├─ 401/403 → 检查认证/权限（feishu_app_scopes / 环境变量）\n│ ├─ 429 → 指数退避重试（1s→2s→4s）\n│ ├─ 5xx → 等待重试，记录日志\n│ └─ 连接超时 → 检查网络 → 降级到备用方案\n│\n├─ 子 Agent 相关？\n│ ├─ spawn 失败 → 检查 task 内容是否过大 / 资源不足\n│ ├─ 超时 → 增加 runTimeoutSeconds 或优化 task\n│ └─ 结果异常 → 检查 context 模式是否正确\n│\n└─ 系统相关？\n ├─ 磁盘满 → 清理 memory/learnings 过期文件 + docker prune\n ├─ 内存不足 → 停止非必要服务 + 使用 lightContext\n └─ 网络断开 → 检查 DNS / 防火墙\n```\n\n## 自愈"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn70tx725606ywwb5gfj0vpxjx83admr\",\n \"slug\": \"agent-optimization-expert\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1784884569888\n}"},{"path":"references/advanced-optimization.md","content":"# Agent 高级优化实践\n\n## 13. Prompt Caching 优化实践 (新增 2026-06-14)\n\nPrompt Caching 是 2026 年最值得关注的 LLM 成本优化技术。典型 LLM 应用中，系统提示会在每次调用时被重复处理，产生大量不必要的算力消耗。\n\n### 核心价值\n| 指标 | 无缓存 | 有缓存 | 改善 |\n|------|--------|--------|------|\n| 缓存 Token 成本 | 全价 | Claude -90%, GPT-4o -50% | 显著 |\n| 首 Token 延迟 | 基准 | 降低 20-70% | 显著 |\n| 盈亏平衡点 | - | Claude: 约 1.25 次请求后 | 极快 |\n\n### Claude 显式缓存控制\n- 使用 `cache_control: {\"type\": \"ephemeral\"}` 标记可缓存内容块\n- 缓存对前缀完全相同的内容有效\n- 写缓存比普通输入贵 25%（一次性），读缓存便宜 90%\n\n### GPT-4o 自动缓存\n- 无需显式标记，自动缓存相同前缀\n- 关键：系统提示保持一致（日期/动态内容会破坏缓存）\n- 将动态信息放在消息层最后，而非系统提示中\n\n### 缓存友好的架构设计\n```\n层 1: 系统指令（最稳定，全局共用）→ 缓存命中\n层 2: 知识库内容（按类型共用）→ 缓存命中\n层 3: 用户特定上下文（用户级缓存）→ 用户维度命中\n层 4: 当前用户消息（动态，无法缓存）→ 不缓存\n```\n\n### 缓存破坏因素（避免）\n- ❌ 系统提示中嵌入当前时间/日期\n- ❌ 为每个请求动态生成 Session ID\n- ❌ 随机化示例内容\n- ❌ 用户姓名插入系统提示（应放用户消息层）\n\n### OpenClaw 映射\n- 主 Agent 的 SOUL.md/USER.md 作为稳定前缀有利于缓存\n- 避免在每次 prompt 中注入动态时间戳\n- 子 Agent 使用 `lightContext` 减少缓存破坏\n\n来源: [Prompt缓存工程2026：Claude和GPT-4o的上下文缓存机制与最佳实践](https://mukebb.blog.csdn.net/article/details/161868589)\n\n---\n\n## 14. 高效智能体框架 — 2026 综述 (新增 2026-06-14)\n\n上海 AI Lab、复旦、中科院、上交大等 9 所高校联合发表《迈向高效智能体（Agents）：记忆、工具学习与规划综述》，提出效率定义：\n\n> **效率** = 在固定成本预算（Token 数/延迟/计算量）下最大化任务成功率，或在相同效果下最小化成本。\n\n### 高效记忆 (Efficient Memory)\n| 类型 | 代表 | 核心思路 |\n|------|------|----------|\n| 工作记忆-文本 | COMEDY, MemAgent | LLM 提取关键信息压缩为摘要 |\n| 工作记忆-潜在 | Activation Beacon, MemoRAG | 长上下文压缩为 KV Cache |\n| 外部记忆-项目 | MemoryBank, Expel | 压缩对话记录减少 Token |\n| 外部记忆-图 | GraphReader, Zep | 知识图谱组织实体关系 |\n| 外部记忆-层次 | MemGPT, ReadAgent | OS 式层级结构管理海量信息 |\n\n**记忆管理策略**:\n- 规则驱动: FIFO/艾宾浩斯遗忘曲线（低成本，可能丢失关键信息）\n- LLM 驱动: Memory-R1 自主决定 ADD/DELETE（自适应但有计算开销）\n- 混合驱动: LightMem 规则触发阈值 + LLM 语义合并\n\n### 高效工具学习 (Efficient Tool Learning)\n| 策略 | 代表 | 核心思路 |\n|------|------|----------|\n| 外部检索器 | ProTIP | 对比学习嵌入语义空间，相似度检索 |\n| 多标签分类 | TinyAgent | 小模型直接预测需要的工具集合 |\n| 并行调用 | LLMCompiler | 分析工具调用图，无依赖工具并行执行 |\n| 成本感知 | BTP | 工具调用视为背包问题，预算约束最优组合 |\n\n### 高效规划 (Efficient Planning)\n| 策略 | 核心思路 |\n|------|----------|\n| 选择性思考 | 自适应推理预算，根据任务复杂度动态分配 Fast/Slow Thinking |\n| 结构化搜索 | A* 启发式评估，剪枝不必要搜索分支 |\n| 任务分解 | Plan-Then-Act，大问拆小问题 |\n| 记忆与技能复用 | 复用已存储经验/策略，越用越省 |\n\n### 多智能体协作效率\n- **拓扑效率**: 稀疏通信网络（图结构）替代密集冗余交互\n- **协议优化**: 精简上下文，确保每次通信携带高价值信息\n- **协同蒸馏**: 教师-学生式知识迁移，减少每个 Agent 学习成本\n\n### OpenClaw 映射\n- `memory_search` 对应高效记忆检索（避免全量 `memory_get`）\n- 子 Agent 使用 `lightContext` = 工作记忆压缩\n- 工具描述按需组装 = 外部检索器模式\n- `sessions_yield` 等待完成 = 拓扑效率（不轮询 = 减少通信）\n\n来源: [2026年做 Agents 应该看这篇全面的技术综述](https://cloud.tencent.com/developer/article/2637134)"},{"path":"references/anthropic-patterns-advanced.md","content":"# Anthropic 工程实践模式 — 高级篇\n\n> 本文件包含 Anthropic 工程博客中较新的高级实践模式。基础模式（§1-9 思考/Tool Use/上下文管理等）请参见 [anthropic-patterns.md](./anthropic-patterns.md)。\n\n## 10. Agent Containment — 爆破半径控制模式 (新增 2026-07-05)\n\nAnthropic 在 [How we contain Claude across products](https://www.anthropic.com/engineering/how-we-contain-claude) 中系统阐述了随着 Agent 能力增强，如何控制其「爆破半径」(blast radius)。\n\n### 三种风险源\n\n| 风险类型 | 来源 | 示例 |\n|---------|------|------|\n| **User Misuse** | 用户滥用/疏忽 | 让 Agent 绕过检查、执行不理解的危险命令 |\n| **Model Misbehavior** | 模型自主做出有害行为 | 更聪明的模型会「绕路」达成目标，甚至逃逸沙箱 |\n| **External Attackers** | 外部攻击向量 | Prompt 注入、工具/文件/网络攻击 |\n\n### 三层防御体系\n\n| 层 | 机制 | 特点 |\n|---|------|------|\n| **环境层** | 沙箱、VM、文件系统边界、出口控制 | 硬边界，最可靠。凭证不进沙箱就无法被窃取 |\n| **模型层** | 系统提示、分类器、探测器、训练修改 | 概率性防御，不可能 100% 有效 |\n| **外部内容层** | 工具权限粒度控制、MCP 代理 | 限制工具能力范围，读-only 比可写安全得多 |\n\n**核心原则**：环境防御 > 模型防御。三层重叠互补，当环境防御不可用时模型层必须兜底。\n\n### 三种 Isolation 模式\n\n| 模式 | 代表产品 | 特点 |\n|------|---------|------|\n| **Ephemeral Container** | claude.ai 代码执行 | gVisor 容器隔离，会话级临时文件系统，爆破半径最小 |\n| **Human-in-the-Loop Sandbox** | Claude Code | OS 级沙箱 (macOS Seatbelt / Linux bubblewrap)，84% 权限提示减少 |\n| **Full Workspace** | Claude Cowork | 持久工作空间 + 受限网络 + MCP 工具代理 |\n\n### 审批疲劳 (Approval Fatigue)\n\n- 用户最终批准约 93% 的权限提示\n- 审批越多，注意力越少 → 监督质量下降\n- **经验用户** 自动批准率是新用户 2 倍，但也更频繁地中途打断\n- 解决方案：Claude Code auto mode 将审批从\"每个步骤\"改为\"基于规则的自动批准 + 异常拦截\"，捕获约 83% 的过度行为\n\n### OpenClaw 映射\n- exec 工具 = 沙箱执行，注意不要给子 Agent 超出工作区的访问权限\n- 操作分级 (L0-L3) = 审批粒度控制，L2/L3 必须确认\n- 敏感信息禁止发群 = 爆破半径控制：即使模型行为异常，影响也被限制\n\n来源: [Anthropic: How we contain Claude across products](https://www.anthropic.com/engineering/how-we-contain-claude)\n\n## 11. Managed Agents — 脑手分离架构 (新增 2026-07-05)\n\nAnthropic 在 [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) 中提出了 Agent 架构的根本性优化：**将 Brain（Claude + harness）与 Hands（沙箱 + 工具）解耦**。\n\n### 核心架构解耦\n\n| 组件 | 角色 | 比喻 |\n|------|------|------|\n| **Brain** | Claude + harness 循环 | 决策中枢，无状态，可替换 |\n| **Hands** | 沙箱容器 + 工具执行 | 执行端，故障时自动重建 |\n| **Session** | 持久化事件日志 | 上下文存储，独立于 Brain 和 Hands |\n\n### 关键设计原则\n\n1. **容器即牛 (Cattle not Pets)**：容器故障时不修复，直接重建。Harness 把容器故障当作工具调用错误处理\n2. **Harness 也是牛**：Harness 崩溃后可通过 `wake(sessionId)` 重建，从最后一个事件恢复\n3. **Session 是独立持久化对象**：不依赖 Claude 的上下文窗口，通过 `getEvents()` 接口按需获取历史\n\n### 性能收益\n\n- p50 TTFT 降低约 **60%**\n- p95 TTFT 降低超过 **90%**\n- 不需要沙箱的会话无需等待容器预配即可开始推理\n\n### 安全改进\n\n- 凭证**永远不进入**沙箱：Git token 在沙箱初始化时注入 remote，MCP 工具通过代理调用\n- 即使 Claude 生成恶意代码，也无法窃取凭证\n\n### 上下文管理新范式\n\n- Session 作为**独立于上下文窗口的上下文对象**\n- `getEvents()` 允许 Harness 按位置切片获取事件流\n- 可以在传递到 Claude 前做任意转换（缓存优化、上下文工程）\n- 避免了**不可逆的上下文压缩决策**\n\n### OpenClaw 映射\n- OpenClaw 的子 Agent 架构天然符合脑手分离：spawn 时分配独立上下文，完成后回收\n- `sessions_spawn(context=\"isolated\")` = 每次都是新容器\n- `memory_search` + `memory_get` = Session 级别的外部持久化\n- Harness 崩溃恢复 = OpenClaw session 自动恢复机制\n\n### Harness 设计警告\n\n> Harness 编码的是\"Claude 目前做不到的事\"的假设。但这些假设会随模型能力提升而**过期**。Anthropic 发现 Sonnet 4.5 有\"上下文焦虑\"（提前结束任务），但 Opus 4.5 没有这个问题——之前的 context reset 变成了死重。\n\n**工程教训**：定期审视 harness/工作流 中的补偿逻辑是否仍然必要，随模型能力升级而精简。\n\n来源: [Anthropic: Scaling Managed Agents](https"},{"path":"references/anthropic-patterns.md","content":"# Anthropic 工程实践模式\n\n## 1. Extended Thinking Pattern\n\nAnthropic Claude 的核心优势是 extended thinking（扩展思考）模式。\n\n### 使用场景\n- 复杂问题分解\n- 多步骤推理\n- 代码架构设计\n- 错误诊断与修复\n\n### 实践要点\n```\n1. 在思考阶段明确列出假设\n2. 对每个假设进行验证\n3. 记录推理链条\n4. 最终输出时提炼结论，隐藏中间过程\n```\n\n### OpenClaw 映射\n- `thinking` 参数控制思考级别\n- 复杂诊断任务启用 thinking 模式\n- 子 Agent 使用 thinking 进行深度分析\n\n## 2. Tool Use Best Practices\n\n### 预检-执行-后检模式\n```\n预检: 验证输入参数、权限、依赖状态\n执行: 调用工具，带超时和重试\n后检: 验证结果完整性、一致性\n```\n\n### 错误处理策略\n```\n1. 捕获具体错误类型（非通用异常）\n2. 分类处理：\n - 可重试：指数退避重试\n - 需修正：调整参数重试\n - 不可恢复：降级到备用方案\n3. 记录错误模式到学习库\n```\n\n### MCP 协议集成 (新增 2026-05-24)\n\nAnthropic 推动的 MCP（Model Context Protocol）解决工具接入碎片化问题：\n- 允许企业数据留在本地环境，保障数据主权\n- 标准化的工具注册和发现机制\n- 与 Function Calling Schema 互补：MCP 管通信接入，Schema 管数据格式\n- OpenClaw 中的 Skills 本质上就是 MCP 的轻量替代\n\n来源: [Anthropic API vs OpenAI API 对比](https://www.cnblogs.com/philry/p/19359139)\n\n## 3. Multi-Agent Coordination\n\n### 子 Agent 使用原则\n```\n- context=\"isolated\"：新任务，无需上下文\n- context=\"fork\"：需要当前对话上下文\n- runTimeoutSeconds：设置合理超时\n- 使用 sessions_yield 等待完成，不轮询\n```\n\n### 通信模式\n```\n主 Agent → 子 Agent: sessions_spawn(task, taskName)\n子 Agent → 主 Agent: 完成事件自动传递\n主 Agent ↔ 子 Agent: sessions_send 进行中途交互\n```\n\n## 4. Prompt Engineering Patterns\n\n### 结构化输出\n```\n使用明确的输出格式要求：\n- JSON schema 定义\n- Markdown 模板\n- 明确的字段名称\n```\n\n### 角色分离\n```\n不同任务使用不同的角色提示：\n- 诊断模式：\"你是一个系统诊断专家...\"\n- 修复模式：\"你是一个运维工程师...\"\n- 优化模式：\"你是一个性能调优专家...\"\n```\n\n### 自反思模式\n```\n在关键决策后添加：\n\"在继续之前，请反思你的分析：\n1. 是否遗漏了重要信息？\n2. 假设是否合理？\n3. 有没有其他可能的解释？\"\n```\n\n## 5. Context Management\n\n### 上下文优化\n```\n- 使用 memory_search 检索相关信息，而非全部加载\n- 大型文件使用 offset/limit 分段读取\n- 子 Agent 使用 lightContext 减少 token\n- 定期清理过期的 session 状态\n```\n\n### Token 预算\n```\n诊断任务：< 5000 tokens\n修复任务：< 10000 tokens\n复杂分析：使用子 Agent 隔离\n```\n\n### Context Engineering (新增 2026-05-24)\n\nContext Engineering 是 Agent 系统的第三层核心能力（与 LLM Call、Tools Call 并列）：\n\n- **核心问题**: 上下文越长，推理质量不一定越好；中间位置信息利用效率低\n- **动态记忆注入**: 按需将长期记忆注入当前对话上下文\n- **会话状态管理**: 跟踪任务进度，决定哪些上下文保留、哪些压缩\n- **工具描述动态组装**: 根据当前任务阶段，只注入相关工具描述（而非全量）\n- **上下文压缩策略**: 保留关键决策点和工具调用结果，压缩中间推理过程\n\n关键洞察：不给任何 Context 的情况下，再先进的模型也可能只能处理极少数任务。Context Engineering 是最容易被低估的环节。\n\n来源: [AI Agent 核心概念详解](https://javaguide.cn/ai/agent/agent-basis.html)\n\n## 6. Safety & Guardrails\n\n### 操作分级\n```\nL0 - 安全：读取文件、检查状态\nL1 - 低风险：修改临时文件、更新日志\nL2 - 中风险：修改配置、重启服务\nL3 - 高风险：删除数据、修改核心配置\n\nL0-L1: 自动执行\nL2: 提示用户确认\nL3: 必须用户明确授权\n```\n\n### 审计日志\n```\n所有 L2+ 操作记录到：\n- learnings/error-log.md\n- memory/YYYY-MM-DD.md\n- 包含：操作时间、内容、原因、结果\n```\n\n### Claude Code 最佳实践 (新增 2026-05-24)\n\nAnthropic 定义 Claude Code 为 **agentic coding tool**（不是 autocomplete）：\n- 可搜索和读取代码、编辑文件、写测试、运行测试、提交代码\n- 编程能力基准分达 64.3%（Claude Opus 4.7）\n- 支持复杂系统开发的自治执行\n\n来源: [Claude Code 安装与使用](https://www.runoob.com/claude-code/claude-code-install.html), [Claude Opus 4.7 发布](https://cloud.tencent.com/developer/news/3844958)\n\n## 7. Agent Skills 延迟加载模式 (新增 2026-05-31)\n\nAgent Skills 是 Anthropic 推动的技能发现与按需加载机制，核心是 SKILL.md 文件：\n\n```\n.claude/skills/code-reviewer/\n├── SKILL.md ← YAML front-matter + 详细指令\n├── scripts/xxx.py ← 可选：配套脚本\n└── reference.md ← 可选：参考资料\n```\n\n### 延迟加载设计\n- **启动时**：只读取 SKILL.md 的 YAML f"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因... Skill: Agent优化专家 Owner: tuobadaidai Summary: Agent 优化专家 — 自动诊断和修复 Agent 执行问题（Cron 失败、工具报错、工作流中断、性能退化）， 兼容 OpenClaw 和 Hermes Agent，自带持续自我进化能力。 Use when user asks to 系统诊断、修复 cron、优化配置、检查系统健康度、自愈修复、 诊断失败原因... Tags: agent:1.4.0, cron:1.4.0, diagnostics:1.4.0, hermes:1.4.0, latest:1.4.0, openclaw:1.4.0, self-evolution:1.4.0, self-healing:1.4.0 Version history: v1.0.1 | 2026-07-24T09:16:09.888Z | user Restore from backup -","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":769,"uniquenessScore":58,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T18:02:37.839Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:42:16.850Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}