P3：跨语言商品上架Agent（学习文档 · 只读不搭建）

学习理念：这是学习 Claude Agent SDK + Plan-Executor 架构的参考文档。不需要搭建运行，重点理解 Plan-Executor 的"规划→拆分→执行"模式，以及 MCP/DeepL/Playwright 的集成方式。读完能回答"Claude SDK 跟 OpenAI SDK 的核心差异是什么"即可。

海外对标：对标 WebInterpret（$30/月多语言上架工具）+ P2C（跨境翻译+SaaS）的核心功能。

本节 AI 替代率：~75% | 人工干预率：~25%

角色	能力范围
🤖 AI 擅长	生成 Plan-Executor 架构代码、翻译质量评估脚本、DeepL API 调用
👤 人类需理解	Plan-Executor 与 StateGraph 的架构差异、多语言 SEO 策略、合规检查的业务规则

---

一、Claude Agent SDK 核心知识

1.1 Claude SDK vs OpenAI SDK 核心差异

维度	OpenAI Agents SDK	Claude Agent SDK
核心抽象	Agent + Handoff + Guardrail	Harness + Tools + Permissions + Lifecycle Hooks
执行模式	Runner.run() 直执行	Plan → Executor 两步式
模型支持	100+ 模型（Responses API）	仅 Claude 系列
MCP 集成	通过 adapter	原生 200+ MCP Server 单行接入
文件系统	❌ 无	✅ FileSystem / Shell
生命周期钩子	❌ 有限	✅ 18 个 Lifecycle Hooks
Extended Thinking	❌	✅ 可见推理过程

1.2 Plan-Executor 架构模式

Plan-Executor 是 Claude Agent SDK 的核心架构模式，和 LangGraph 的 StateGraph 有本质区别：

LangGraph StateGraph：
  定义状态（State）→ 定义节点（Node）→ 定义边（Edge）→ 编译执行
  特点：开发者完全控制执行路径

Claude SDK Plan-Executor：
  Agent 自己规划执行步骤 → Agent 自己执行
  特点：Agent 自主决策，开发者只提供工具和 prompt

# Plan-Executor 模式 vs StateGraph 模式 对比

# Claude SDK Plan-Executor
from claude_agent_sdk import Agent

planner = Agent(
    name="planner",
    instructions="分析任务并输出执行计划",
)
# Agent 自主决定：先翻译 → 再 SEO → 最后合规

# LangGraph StateGraph
from langgraph.graph import StateGraph
# 开发者定义：先调用 translate_node → 再调用 seo_node

---

二、P3 项目架构拆解

2.1 整体流程

2.2 核心代码骨架

# Claude Agent SDK Plan-Executor 模式完整骨架
# 🟡 【P1 看注释就行】理解 Plan-Executor 架构比写代码更重要

from claude_agent_sdk import Agent
from claude_agent_sdk.tools import MCP, FileSystem

# Step 1: 定义工具
@claude_agent_sdk.tool
def translate_text(text: str, target_lang: str) -> str:
    """调用 DeepL API 翻译文本"""
    import deepl
    client = deepl.DeepLClient(os.getenv("DEEPL_API_KEY"))
    result = client.translate_text(text, target_lang=target_lang)
    return result.text

@claude_agent_sdk.tool
def search_keywords(product_desc: str, market: str) -> list[str]:
    """搜索目标市场的 SEO 关键词"""
    # Google Keyword Planner / SerpAPI
    return ["keyword1", "keyword2"]

@claude_agent_sdk.tool
def check_compliance(product: dict, market: str) -> dict:
    """检查产品合规要求"""
    # RAG 检索法规知识库
    return {"compliant": True, "issues": []}

# Step 2: 定义 Plan Agent（规划者）
listing_planner = Agent(
    name="listing_planner",
    model="claude-sonnet-4-6",
    instructions="""
    对于每个产品，你需要输出一个JSON执行计划：
    {
        "translations": [{"target_lang": "de", "fields": ["title", "description"]}],
        "seo_keywords": {"market": "de", "type": "long_tail"},
        "compliance": {"standards": ["CE", "RoHS"]},
        "target_platforms": ["amazon_de", "shopify"]
    }
    只需要输出JSON，不要输出其他内容。
    """,
)

# Step 3: 执行翻译
def run_listing_pipeline(product: dict, target_markets: list[str]) -> dict:
    # Plan Agent 输出计划
    plan = listing_planner.run(f"产品：{product}，目标市场：{target_markets}")
    
    # 执行翻译
    translations = {}
    for lang in target_markets:
        translated = translate_text(product["description"], lang)
        translations[lang] = translated
    
    return {"plan": plan, "translations": translations}

---

三、技术选型说明

组件	选型	原因
Agent 框架	Claude Agent SDK	Plan-Executor 模式是 Claude 独特的架构，值得了解
翻译引擎	DeepL API	专业翻译质量，非 LLM 能替代
关键词研究	Google Keyword Planner	免费，SEO 行业标准
合规知识库	RAG + 欧盟法规 PDF	自建可控
浏览器自动化	Playwright	可对接任意平台

---

四、知识点总结

知识点	重要性	理解要点
Plan-Executor 架构	🔥 核心	Agent 自主规划+执行，与 StateGraph 的手动定义形成对比
Claude SDK vs OpenAI SDK	🔥 核心	模型锁定 vs 模型中立，各自的独特能力
DeepL API	🟡 了解	专业翻译引擎，电商上架场景不可替代
Playwright 自动化	🟡 了解	跨平台自动上架的工具层
多语言 SEO	🟢 概念	关键词策略在不同市场的差异

---

五、成本参考

项目	月费
DeepL API	$8.99/月起
DeepSeek + GPT-4o	~$18/月
Langfuse 自部署	~$10/月
合计	~$37/月