Harness实战：Plan模式——让Agent先想清楚再动手

用户: 给这个项目添加单元测试
模型: [调用 bash: ls] → [调用 read_file: main.py] → [调用 write_file: test_main.py]
     → 发现遗漏了 utils.py → [调用 read_file: utils.py] → [调用 edit_file: test_main.py]
     → 运行测试失败 → [调用 edit_file: test_main.py] → ...

用户: 给这个项目添加单元测试

模型（计划阶段，无工具）:
  1. 先读取项目结构了解有哪些模块
  2. 读取 main.py 和 utils.py 的代码
  3. 为每个模块设计测试用例
  4. 创建 test_main.py 和 test_utils.py
  5. 运行测试确保通过

用户: 好的，执行吧

模型（执行阶段，有工具）:
  按计划有条理地完成...

def plan_then_execute(messages: list):
    # ── 阶段 1：计划（不给工具，模型只能输出文本） ──
    plan_messages = messages + [{
        "role": "user",
        "content": "Before acting, outline your plan step by step. Do NOT use any tools yet."
    }]

    plan_response = client.messages.create(
        model=MODEL,
        system=SYSTEM,
        messages=plan_messages,
        # 关键：不传 tools 参数，模型无法调用工具
        max_tokens=2000,
    )

    plan_text = plan_response.content[0].text
    print(f"\n📋 Plan:\n{plan_text}\n")

    # 用户确认
    confirm = input("Execute this plan? (y/n) ")
    if confirm.lower() != "y":
        print("Plan cancelled.")
        return

    # ── 阶段 2：执行（正常 agent loop，带工具） ──
    messages.append({"role": "assistant", "content": plan_response.content})
    messages.append({"role": "user", "content": "Good plan. Now execute it step by step."})
    agent_loop(messages)  # 复用之前写的 agent_loop

SYSTEM_WITH_PLAN = f"""You are a coding agent at {WORKDIR}.

When given a task:
1. FIRST output your plan as a numbered list (text only, no tool calls)
2. THEN execute the plan using tools

Always plan before acting."""

def plan_then_execute(messages: list, task: str):
    # 阶段 1：生成计划（不传 tools）
    plan_messages = messages + [
        {"role": "user", "content": task},
        {"role": "user", "content": "Analyze the task and outline a step-by-step plan. Do NOT execute anything yet."},
    ]

    print("\n⏳ Generating plan...\n")
    plan_response = client.messages.create(
        model=MODEL,
        system=SYSTEM,
        messages=plan_messages,
        max_tokens=2000,
        # 注意：没有 tools 参数
    )

    plan_text = plan_response.content[0].text
    print(f"📋 Plan:\n{plan_text}\n")

    # 用户确认
    confirm = input("Execute? (y/n/or type feedback) ")
    if confirm.strip().lower() == "n":
        print("Cancelled.")
        return

    feedback = ""
    if confirm.strip().lower() not in ("y", "yes"):
        feedback = f" User feedback: {confirm}"

    # 阶段 2：执行（把计划作为上下文，启动正常 agent loop）
    messages.append({"role": "user", "content": task})
    messages.append({"role": "assistant", "content": plan_response.content})
    messages.append({"role": "user", "content": f"Good plan.{feedback} Now execute it step by step."})

    print("\n⚡ Executing...\n")
    agent_loop(messages)

if __name__ == "__main__":
    history = []
    while True:
        query = input("❯ ")
        if query.strip().lower() in ("q", "exit", ""):
            break

        if query.strip().startswith("/plan "):
            task = query.strip()[6:]
            plan_then_execute(history, task)
        else:
            history.append({"role": "user", "content": query})
            agent_loop(history)

❯ 当前目录有什么文件
> bash: agentic-demo.py  harness-agent-loop.md  ...

❯ /plan 给当前目录的所有 py 文件添加文件头注释

⏳ Generating plan...

📋 Plan:
1. 用 bash 列出当前目录的所有 .py 文件
2. 逐个读取每个 .py 文件的前几行，检查是否已有文件头注释
3. 对没有注释的文件，用 edit_file 在文件开头插入统一格式的注释
4. 最后用 bash 验证所有文件的头部

 Execute? (y/n/or type feedback) y

⚡ Executing...
  > bash: agentic-demo.py harness.py llm-claude.py ...
  > read_file: import json ...
  > edit_file: Edited agentic-demo.py
  ...

plan_then_execute
  ├── 第 1 次 API 调用（无 tools）→ 输出计划文本
  ├── 用户确认
  └── agent_loop（有 tools）→ 正常执行

# 计划阶段 — 没有 tools，模型被迫只输出文本
plan_response = client.messages.create(
    model=MODEL,
    system=SYSTEM,
    messages=plan_messages,
    max_tokens=2000,
    # 没有 tools=TOOLS
)

# 执行阶段 — 正常带 tools 的 agent loop
agent_loop(messages)