# AI Agent 规划指引：从踩过的坑到可复制的框架

> 导入 AI Agent 之前，必须明确定位与边界，否则极易沦为失控的黑箱。从 OneUp 自动发文到辩论引擎到我们的 AI 平台监控，我踩过的每一个坑都指向同一件事：模块化、可追踪、从小开始。这篇是我从实战中归纳出的五个落地原则。

- Author: Paul Kuo（郭曜郎）
- Date: 2025-10-05
- Pillar: 创造与建构 / Creation & Enterprise
- Tags: AI Agent, 自动化, 流程设计, 风险管理, 模块化, Multi-Agent
- Canonical: https://paulkuo.tw/zh-cn/articles/ai-agent-planning-guide/
- Language: Simplified Chinese (简体中文)
- Translation: AI-translated from the zh-Hant (Traditional Chinese) original
- Original (zh-Hant): https://paulkuo.tw/articles/ai-agent-planning-guide.md
- Site index for LLMs: https://paulkuo.tw/llms.txt

---

去年底，我的 OneUp 自动发文管线在凌晨两点把同一篇贴文发了八次。八个平台，每个平台八则重复内容。我早上起来看到手机通知的时候，花了四十分钟手动删文。

<div class="listen-summary" style="margin:1.25rem 0;padding:0.75rem 1rem;border:1px solid var(--border);border-radius:var(--radius);background:var(--bg-section);">
  <div style="font-size:0.9rem;font-weight:600;color:var(--text-secondary);margin-bottom:0.5rem;letter-spacing:0.02em;">▶ 听摘要</div>
  <audio preload="none" controls style="width:100%;display:block;">
    <source src="https://audio.paulkuo.tw/ai-agent-planning-guide-zh.mp3" type="audio/mpeg" />
    您的浏览器不支持音频播放，请点此 <a href="https://audio.paulkuo.tw/ai-agent-planning-guide-zh.mp3">下载音频文件</a>。
  </audio>
  <div style="font-size:0.75rem;color:var(--text-secondary);opacity:0.75;margin-top:0.4rem;">AI 合成语音・作者本人声线克隆</div>
</div>

那天我学到的教训很简单：Agent 不难做，难的是不让它失控。

过去一年我建了三套 Agent 系统。辩论引擎让 GPT-4o、Gemini、Grok 互相辩论再由 Perplexity 事实查核。OneUp 管线从 Google Sheet 读排程、用 DALL-E 生图、自动发到八个平台。我们的 AI 平台的产线监控在凌晨三点自动调参数。每一套都教了我不同的事。

这篇不是理论。是我从踩坑中归纳出的五个原则。

## 先回答三个问题再动手

在写任何一行代码之前，我现在会强迫自己回答三个问题：这个 Agent 解决什么问题？它的权限范围在哪里？我怎么知道它做对了？

听起来很基本，但我的辩论引擎第一版就是没想清楚第二个问题。我让模型可以自由决定辩论轮数，结果某次它跑了二十七轮，把 API 额度烧光。后来我加了硬性上限：最多五轮，超过就强制收敛。

定位不清楚的 Agent 就是一个失控的黑箱。先画边界，再写代码。

## API 优先，浏览器是最后手段

Agent 的价值在于调用工具完成多步骤任务。但工具整合的复杂度会指数级成长。

我在 OneUp 管线上学到最痛的一课：一开始我试过用浏览器自动化来排程发文，结果每次 UI 改版就全部坏掉。后来改走 API，稳定性直接从 60% 跳到 99%。现在我的原则很简单：API 稳定性永远优先，浏览器自动化只在没有 API 的情况下才考虑。

数据处理也一样。输入数据不干净，Agent 就会在垃圾上面做决策。我在〈[从 AI 风暴中突围](/zh-cn/articles/personal-strategy-in-ai-storm/)〉里谈过，结构设计是新的核心竞争力：Agent 的结构设计，从数据清洗那一步就开始了。

## 拆成模块，出错才能定位

一个大型 Agent 很难维护。我现在所有系统都拆成四个模块：Input 处理 → 决策逻辑 → 工具调用 → 结果后处理。每个模块独立可验证、可回滚。

辩论引擎就是这样设计的。Input 模块负责解析主题和模式（dialogue/duo/adversarial）。决策模块负责轮次控制和收敛判断。工具调用模块处理四个模型的 API 调用。后处理模块把结果存成 markdown。任何一个模块出问题，不会连带搞坏其他部分。

这也是我在记忆里记下的协作原则：复杂工程必须先拆 Phase，每个 Phase 独立可验证。一次性处理的结果，通常是中途卡住然后连前面做对的部分一起搞坏。

## 每一步都要有日志

Agent 的运作过程必须透明，否则出错时你根本不知道哪里坏了。

我的 OneUp 管线八次重复发文事件，就是因为缺少日志。API 回传了 timeout，脚本重试了八次，每次都成功排程了一则新贴文。如果我当时有记录每次 API 调用的回传状态，就能在第二次重试时发现第一次其实已经成功了。

现在我的所有 Agent 都有三层监控：操作日志（每一步做了什么）、决策路径（为什么做这个选择）、成本追踪（花了多少 API 额度）。透明不是奢侈品，是存活条件。

## 从最小场景开始

最后一个原则最简单也最常被忽略：从小开始。

我们的 AI 平台的监控系统不是一开始就做全产线的。我先让它只监控一条产线的一个参数，跑了两周确认逻辑正确，才逐步扩展。我在〈[你不是输在认知](/zh-cn/articles/overcome-fear-start-ugly/)〉里讲过「先做个垃圾出来再说」：Agent 也一样，先跑一个粗糙的 POC，在运转中优化，比花三个月规划一个完美系统然后上线就爆炸好一百倍。

Agent 的价值不在于取代人。在于扩展人的能力边界。但扩展的前提是你先驯服它：定位清楚、模块化、可追踪、从小开始。每一个原则都是用失败换来的。