花了3个月写3000行代码的"智能框架"，被同事用50行代码吊打。 这不是段子，是我去年真实的经历。本文用3个问题帮你识别"伪Agent"，附赠Harness工程3阶段路线图，看完你就能写出真正的Agent系统。

我的惨痛经历：3000行代码 vs 50行代码

去年我接到一个任务：给公司开发一个AI编程助手。作为资深工程师，我信心满满：

# 我的"企业级"Agent框架（节选）
class AIProgrammer:
    def __init__(self):
        self.intent_classifier = IntentClassifier()  # 500行
        self.prompt_templates = PromptTemplateManager()  # 800行
        self.workflow_engine = WorkflowEngine()  # 1200行
        
    def process(self, user_input):
        # 意图识别 -> 选择模板 -> 执行流程 -> 返回结果
        intent = self.intent_classifier.classify(user_input)  # 100行
        template = self.prompt_templates.get(intent)  # 200行
        result = self.workflow_engine.execute(template)  # 1500行
        return result

3000行代码，15个类，8个设计模式。 结果遇到"帮我重构这个函数，但要保持向后兼容，还要更新测试用例"这种需求，直接崩溃——因为它无法被归类到单一意图。

同事的方案：

# 同事的最小Agent（完整版）
def agent_loop(messages):
    while True:
        response = client.messages.create(
            model="claude-3-sonnet",
            messages=messages,
            tools=[read_file, write_file, bash],  # 只有3个原子工具
        )
        messages.append({"role": "assistant", "content": response.content})
        
        if response.stop_reason != "tool_use":
            return  # 模型说"我完成了"
        
        # 执行工具，结果反馈给模型
        results = [execute_tool(block) for block in response.content]
        messages.append({"role": "user", "content": results})

50行代码。 没有意图分类，没有工作流引擎，没有Prompt模板库。但它能处理我那个"无法归类"的需求，因为它让模型自己决定"做什么"。

核心洞察：Agent是模型，Harness是载具

我犯的错误是用确定性代码模拟不确定性智能。就像用算盘模拟计算机——外表相似，本质完全不同。

真正的Agent架构：

关键认知：

• Agent（模型）：决定"做什么"（读文件？运行测试？写代码？）
• Harness（代码）：决定"怎么做"（如何读文件？如何执行命令？）

我的3000行代码在做什么？ 我在替模型做决定——这是"伪Agent"。

同事的50行代码在做什么？ 他让模型自己做决定——这是"真Agent"。

3个问题识别"伪Agent"

维度	伪Agent（我的方案）	真Agent（同事方案）
决策方式	硬编码if-else规则（意图分类）	模型自主决策（Agent Loop）
工具设计	业务流程化（粗粒度）	原子化（细粒度可组合）
扩展方式	修改框架代码（加意图、加模板）	添加工具描述（不改循环逻辑）
代码行数	3000行，复杂到难以维护	50行，简单到一眼看懂
适应能力	遇到未预设场景直接崩溃	能处理任意复杂组合需求
代表产品	早期"智能"脚本、简单Prompt链	Claude Code、GitHub Copilot Chat

一句话区分：

• 伪Agent：代码替模型做决定（if-else编排）
• 真Agent：代码给模型提供做决定的环境（Harness）

给你的团队：Harness工程3阶段路线图

如果你要为自己的场景构建Agent系统，遵循这个路径：

阶段1：最小Harness（验证可行性，1-2天）

目标： 用50行代码验证Agent在你的领域是否work

# 最小Agent Loop（阶段1）
def minimal_harness():
    tools = [
        {"name": "read_doc", "description": "读取文档内容"},
        {"name": "search_kb", "description": "搜索知识库"},
        {"name": "send_email", "description": "发送邮件通知"}
    ]
    
    # 验证：模型能否在你的领域自主完成任务？
    agent_loop(tools=tools)

关键产出：

• 确认模型能否理解你的业务场景
• 确定需要哪些原子工具
• 验证Agent Loop是否work

阶段2：增强Harness（提升能力，1-2周）

目标： 在最小Harness基础上增加能力，但不改变核心循环

# 增强Harness（阶段2）
class EnhancedHarness:
    def __init__(self):
        self.tools = self.load_tools()  # 扩展工具集
        self.skill_loader = SkillLoader()  # 知识按需加载
        self.subagent = SubagentManager()  # 子Agent支持
    
    def run(self, task):
        # Agent Loop保持不变！
        return agent_loop(
            messages=task,
            tools=self.tools,
            # 新增能力通过参数注入，不改循环逻辑
            skill_loader=self.skill_loader,
            subagent=self.subagent
        )

关键产出：

• 工具集扩展到10-20个原子工具
• 实现知识按需加载（节省66%成本）
• 添加Subagent支持（处理复杂任务）

阶段3：生产Harness（工程化，1-2月）

目标： 让Agent从"玩具"升级为"生产系统"

# 生产级Harness（阶段3）
class ProductionHarness:
    def __init__(self):
        self.task_system = TaskSystem()  # 任务持久化
        self.context_manager = ContextManager()  # 上下文压缩
        self.team_bus = MessageBus()  # 多Agent协作
        self.worktree_manager = WorktreeManager()  # 环境隔离
    
    def run_long_task(self, project):
        # 支持跨天任务、断点续传、崩溃恢复
        # 支持多Agent并行、环境隔离
        pass

关键产出：

• 上下文压缩（支持50+轮对话）
• 任务持久化（断点续传、崩溃恢复）
• 多Agent协作（团队协议、任务分配）
• 资源隔离（Worktree/Docker）

避坑指南：别让"框架思维"害了你

❌ 坑1：过度设计

# 不要一开始就这么做
class EnterpriseAgentFramework:
    def __init__(self):
        self.plugin_manager = PluginManager()  # 插件系统
        self.config_manager = ConfigManager()  # 配置管理
        self.event_bus = EventBus()  # 事件总线

✅ 正确做法：

# 从最小开始，逐步演进
def agent_loop(messages, tools):
    while True:
        response = llm.call(messages, tools)
        if response.stop_reason != "tool_use":
            return
        results = execute_tools(response)
        messages.append(results)

❌ 坑2：混淆Agent和Harness

# 错误：在Harness层做决策
if "deploy" in user_input:
    force_run_tests()  # 强制先跑测试
    
# 正确：让模型决定要不要跑测试
# Harness只提供"run_tests"工具，模型自己决定何时调用

❌ 坑3：工具设计过于粗粒度

# 错误：业务流程化工具
{"name": "refactor_code", "description": "重构代码并更新测试"}
# 模型无法灵活组合，只能按你预设的流程执行

# 正确：原子化工具
{"name": "read_file", "description": "读取文件内容"}
{"name": "edit_file", "description": "编辑文件"}
{"name": "run_tests", "description": "运行测试"}
# 模型可以自主组合：读文件→编辑→测试→再编辑

总结：造好Harness，Agent会完成剩下的

Agent是模型。Harness是载具。

你的工作是构建一个高质量的栖居环境——让Agent能看得清楚（Observation）、想得明白（Reasoning）、动得精准（Action）、学得持续（Learning）。

不要试图用代码编写智能。智能已经在模型里了。 你只需要给它一个能发挥的世界。

造好Harness。Agent会完成剩下的。

---

🔥 互动投票：

你当前的项目中有"伪Agent"痕迹吗？

• A. 大量使用if-else编排业务流程（意图分类）
• B. 工具设计过于粗粒度（如"重构代码"作为一个工具）
• C. 新增功能需要修改框架核心代码（而非添加工具描述）
• D. 已经是Harness思维，模型自主决策（恭喜你！）

---

💡 思考题：

1. 你当前的项目中，有哪些"伪Agent"的痕迹？
2. 如果让你重构，哪些决策应该交给模型，哪些应该保留在Harness层？
3. 你的领域需要什么特殊的"感知"和"行动"能力？（特定的工具集）