电商工单的核心痛点是：Agent 要跨系统（订单、物流、支付）操作，且面临异步等待（如查物流）、风险操作（退款）和长流程（退货审批）。以下是针对此场景的 Harness 五层架构实战设计：

 

---

 

1. 指令层（Orchestration Layer）：写死“游戏规则”

 

在项目根目录放置 .claude/AGENTS.md，强制注入电商业务边界。

 

```markdown

# 电商工单主管角色

- 权限边界：只能查询订单、查物流、发起标准退款。**禁止**直接修改库存或价格。

- 风控红线：单笔退款金额 > 500元 或 订单超时 > 7天，**禁止**自动执行，必须输出 [NEED_MANUAL_REVIEW] 标签。

- 操作优先级：处理投诉时，必须先查物流轨迹，再查订单状态，最后才能发起工单流转。

- 输出规范：所有工具调用必须包含 `ticket_id` 和 `trace_id` 用于链路追踪。

```

 

---

 

2. 工具层（Tooling Layer）：封装“标准 API 网关”

 

Agent 不直连数据库，通过 MCP (Model Context Protocol) 或标准函数封装中间层。重点在于输入校验 + 幂等性。

 

```python

# 工具定义示例（Python TypedDict）

@tool

def query_order_scope(order_id: str, user_id: str) -> OrderDetail:

    """只读工具。仅返回脱敏信息（隐藏中间4位手机号）"""

    # 强制注入租户隔离，防止Agent越权查他人订单

    return order_service.get_by_user(order_id, user_id)

 

@tool

def initiate_refund(ticket_id: str, order_id: str, amount: float, reason: str):

    """写工具。包含软删除+幂等键，防止重复发起退款"""

    if amount > 500.0:

        return {"status": "pending_approval", "msg": "已转人工审核"}

    # 使用 ticket_id 作为幂等键，防止网络重试导致重复扣款

    return payment_client.refund(idempotent_key=ticket_id, ...)

```

 

---

 

3. 状态层（State Layer）：实现“断点续传”

 

工单常跨天处理，Agent 必须持久化记忆。引入 Redis + 本地 Markdown 双写策略。

 

· 进程内状态：维护 PROGRESS.md，Agent 每完成一步强制更新。

· 持久化状态机：在 Redis 存储工单实体 State = PENDING -> LOGISTICS_CHECKED -> COMPENSATING -> RESOLVED。

· 实战策略：每次 Agent 回复前，强制读取 Redis 中的 current_step。若检测到 Agent 断点重启，自动加载上一步的 tool_outputs，避免重复查接口。

 

---

 

4. 环境层（Environment Layer）：本地“工厂化仿真”

 

生产环境不可随意测试，Harness 环境层要构建沙盒（Sandbox）。

 

· Docker Compose 编排：拉起 Mock 物流 API（延迟 200ms 模拟真实网络）、Mock 支付网关（沙盒返回固定回调）。

· 种子数据（Seed Data）：初始化 3 类典型工单（待退款、物流丢失、仅咨询），供 Agent 回归测试。

· 环境变量注入：通过 .env.harness 强制区分 DEV 和 PROD，且在 DEV 环境下，模拟第三方接口随机超时，考验 Agent 的重试容错机制。

 

---

 

5. 反馈层（Feedback Layer）：自动化“验收裁判”

 

工厂化讲究“无人值守”，反馈层通过退出码（Exit Code）和断言决定流水线是否通过。

 

· 单元测试化：将 Agent 的最终输出（JSON）喂给测试脚本。

  · 断言1：输出是否包含合法 refund_id 格式。

  · 断言2：查询高额订单（>500元），输出是否包含强制人工标签。

· 注入对抗样本：Harness 流水线中植入“脏数据”（如不存在的 order_id），检测 Agent 是否会编造信息，还是准确抛出 Tool_Error。

· 客观评分：不依赖 LLM 评分（避免幻觉），只校验工具调用次数（防止死循环）和最终工单闭合状态。

 

---

 

⚙️ 实战流水线（Workflow）串联

 

把这个 Harness 放进 CI 流程（如 GitHub Actions）：

 

1. 启动环境：docker-compose up -d（拉起 Mock 依赖）。

2. 注入指令：将 AGENTS.md 注入 Agent System Prompt。

3. 运行测试集：输入 10 个预设的工单场景（JSONL 格式）。

4. 状态重置：每个场景执行前，清空 Redis 并重写 PROGRESS.md。

5. 结果裁决：检查输出的 ticket_status 是否匹配预期，并检查日志中的 trace_id 是否完整。

6. 自愈测试：手动 Kill 掉 Mock 支付服务，看 Agent 是否能在 3 次重试后优雅降级（记录异常）。

 

---

 

💡 核心心法（区别于普通开发）

 

· 治理大于代码：你的主要精力在写 AGENTS.md 规则，而非修 Agent 模型。

· 强制幂等：所有写操作必须引入 idempotent_key，这是工厂化防呆的核心。

· 可观测性：Harness 层必须强制 Agent 每次工具调用输出 思考日志（Thought），用于回溯“为何 Agent 发起退款”。

 

这套架构落地后，你的电商工单 Agent 将不再是“黑盒聊天机器人”，而是一个可审计、可回滚、可压测的标准化数字员工。