# 智能体质量评估与改进建议

日期：2026-06-17 · 版本基线：v1.4.2
视角：从"智能体质量"出发，对标当前主流智能体平台，评估 lambdagentpaas 的智能体实现并给出建议。
证据：本评估锚定 2026-06-14~17 期间真实运行复盘（run_id / commit 见正文），非空谈。

---

## 一、什么叫"智能体质量"（评估维度）

| 维度 | 含义 | 业界标杆 |
|---|---|---|
| 执行可靠性 | 让它干的事是否真发生：工具真执行、产物真落盘 | Claude Code / Codex 原生 harness |
| 上下文 / 收敛性 | 记得住、往前走 vs 忘了、乱跳重做 | LangGraph（state/checkpoint）、原生 harness |
| 可复现 / 隔离 | per-run 隔离、可追溯 | Dify / LangSmith |
| 可度量（eval） | 能给智能体**输出质量**打分、回归测**行为** | LangSmith / Braintrust / Ragas |
| 安全 / 约束 | 沙箱、权限、防幻觉/伪造 | 各家在补 |
| 形式化根基 | 类型 / 效果 / 成本语义、可证明保证 | **几乎无人有 —— lambdagentpaas 独有** |

---

## 二、现状打分（对标主流）

### 强项（真实差异化）
- **形式化内核**：λ 演算 + typed effects + cost 语义 + Guard/validator。Dify/Coze/LangChain/Claude Code 都没有。是 AgentOS / 论文线的资产。
- **可靠性加固的工程纪律**：6/14~6/17 针对真实故障逐个修 + 配回归——目录一致性、会话轮换/熔断、MCP 隔离、401 人话、网络重试、进度纪律、per-run 隔离。
- **两条执行车道的觉悟**（commit 6758ff8）：意识到 claude-code 应"当 agent 本身"而非套 react-over-text 封装。
- **单机 / 隐私 / 自带模型**：契合 beachhead（有经费研究室 PI）。

### 弱项（质量短板，按严重度）

**1. react-over-text 车道从根上脆（头号问题）**
让模型把工具调用当散文手写 `{"tool":...}`、平台正则抠并自己执行。并发症（均实锤）：
- run_541390a1ea49：claude-code 76 次工具调用 **0 执行 0 落盘**（`input` 裸串、`path` vs `file_path`、格式飘）。
- run_bf2405e28547：相对路径写入落错目录。
- 主流早用模型**原生 function-calling**（结构化 tool_use），qwen/openai/deepseek 都支持，可靠性高一个量级。本平台只有 claude-code 走了 native，其他模型仍困在最脆那条。

**2. 没有 eval / 质量度量**
全程模式是"跑一条 → 人肉看 trace → 发现没落盘 → 修"。有代码单测（lambdagent 594 + agentpaas 344），但**零条"智能体行为"测**：给定输入、产物是否达标。测不了 → 改不动 → 只能人肉当 eval，不可扩展、不可回归。

**3. 上下文管理原始**
手搓 `max_input_chars` / obs 截断 / history 裁剪 → 直接导致"忘了→乱跳→重做"（qwen-max 30720 溢出 commit 787126d；乱跳 commit fc93ae3）。PROGRESS.md 磁盘纪律很聪明，但本质是给弱上下文管理打补丁。主流用 summarization + 检索 + checkpoint。

**4. 可靠性是打地鼠**
dir / session / MCP / 401 / context / network 反应式逐个修。根因：react loop + 上下文是手卷的，provider 怪癖靠一个个 case 兜。LangGraph 的 loop/state/checkpoint 是被打磨过的原语。

### 横向定位
- vs Claude Code / Codex：raw agentic 可靠性**更弱**（未充分用原生能力），但多了编排 + 形式化 + 多模型 + 产品 UI。
- vs Dify / Coze / Flowise：多了形式化内核 + 单机隐私 + 科研 agent；但它们 eval/观测/生态更成熟。
- vs LangGraph / CrewAI：内核更有原则；但其操作层原语（state/checkpoint/streaming/human-in-loop）更经打磨。

---

## 三、最值得改的三件事（按投入产出排序）

### ① 全 provider 切原生 function-calling —— 最高杠杆
- **问题**：react-over-text 文本 JSON 解析是"0 执行 / 格式飘 / 相对路径落错"这一整类 bug 的总根源；6/14~17 约一半修复都在补这个模具的窟窿。
- **方案**：用各 provider 的结构化工具接口——OpenAI 兼容（qwen/deepseek/openai/moonshot/zhipu）走 `tools` + `tool_calls`；Anthropic 走 native tool_use；claude-code 保持 native 车道。react-over-text 仅留给真不支持 function-calling 的模型当兜底。
- **影响面**：`providers/openai_compat_provider`（加 tools 透传 + tool_calls 解析）、`conversation.py`（消息含 tool role）、`compiler._compile_react`（不再正则抠文本，改读结构化 tool_calls；`_extract_tool_call` 退化为兜底）。两车道架构不变，等于给 react 车道换"可靠引擎"。
- **验收**：同一批任务，工具执行成功率 / 落盘率显著上升；`input` 裸串、`path` 别名类 bug 归零。先在 qwen-plus 验证。
- **工作量**：中（provider + 解析层），但收益覆盖最大一类故障。

> **注（codex 修正）**：function-calling 只消灭"格式漂移 / JSON 抠错 / 裸串 input /
> 工具名解析"这一类。**"相对路径落错目录"不在其中**——那是 workspace contract + cwd 绑定 +
> sandbox + 参数 canonicalization 的**工具层硬约束**问题（`file_tools._resolve`/`_sandbox`，
> commit 5f38a1c/3bae21d/df648aa 已部分解决）。FC 与工具层约束是两件事，别把后者算进 FC 收益。

### ② 建第一方 agent 的行为回归集 —— 让质量可度量【已建框架, commit 见下】
- **修正认知**：不是"没有 eval"。`tests/test_pipeline.py` 已有 LLM-judge gate、阈值、halt、
  成本进 term graph——**eval 基础设施长出来了一截**。真正的缺口是：**有 pipeline/gate 单测，
  没有第一方 agent 的"行为回归集"**（真实智能体质量没被覆盖）。
- **方案**：复用已有 judge 基础设施，给每个第一方 agent 配 3–5 个 golden 任务（输入 +
  期望产物特征）→ LLM-judge 打分 → 进 CI 做**行为回归**（与代码单测分离，可 nightly）。
  指标：落盘率、产物达标率、步数/成本、纪律遵守率（PROGRESS 全勾率）、**FC vs 文本路径对比**。
- **验收**：每次改 provider/prompt/纪律/车道，看分数变化而非人肉看 trace。
- **工作量**：中；基础设施已有一截，主要是补"agent 维度"的覆盖。尽早建——是后续一切优化的尺子。

### ③ 把形式化内核兑现成"可感知质量"（否则只是论文资产）
- **修正认知**：形式化**不是自动加分项**。只有当它产出下列**具体可见的东西**时,才是产品质量：
  - 挂 Skill 前的 **effect / permission diff**（这条 Skill 会多读写哪、扩哪些权限）；
  - pipeline **编译期拒绝非法组合**（类型/基数/契约不符直接报错,不到运行时才炸）；
  - **并行写冲突静态检查**（两个 stage 写同一产物 → 编译期拦）；
  - **预测成本 vs 实际成本的误差报告**（`estimate_cost` 对账,准确率作卖点）；
  - 迁移前后**契约保持 / 降级证明**（换执行后端、换模型,行为契约可证不破）；
  - **Guard 失败原因 + 可复现 trace**（为什么没过、怎么重现）。
- **影响面**：把 `engine/pipeline` 的 cost/gate/effect 接到 UI + 运行时 + Skill 挂载校验。
- **工作量**：中–大；是护城河,非救火,排 ①② 之后。但**它才是 LambdAgent 真正不可替代的层**（见 §四）。

---

## 四、定位建议（codex 加狠版）

**问题不是"react-over-text 写得不够好",而是它本来就不该当主执行引擎。**
react-over-text 这个抽象边界**不适合承担 workspace agent 的主执行路径**——这两天的失败不是
几个 bug,是用错了执行车道。代码自证：`agentruntime/action_parser.py`（free-text 抠 JSON/XML/
keyword、裸串塞 `{"query":...}` = `path/file_path/input` 飘的来源）、`openai_compat_provider.py`
（请求体无 tools/tool_choice/tool_calls）、`claude_code_native.py` 注释（react=纯文本正则抠、
native=结构化执行）、`agents.py`（注释直接写 react-over-text 实测"0 执行、丢上下文、空转"）。

### 四层执行/能力划分（目标态）
```
react-over-text   → 降级为 legacy / fallback,不再作为主车道。
native harness    → Claude Code / Codex 负责 workspace agentic 执行。
structured tool-call → Qwen / OpenAI / DeepSeek 走原生 tools/tool_calls。
formal layer      → 只管 contract / policy / migration / eval / trace / cost / effect。
```

### 胜负手（一句话）
**LambdAgent 的胜负手不是"更会干活",而是让 Skill / Agent 在不同执行后端之间
可分析、可约束、可迁移、可回归。**
- 底层执行"借"成熟后端（native harness + structured tool-call），不自己卷 agentic 可靠性——卷不过基座。
- 全部差异化压到 **formal layer**：effect/permission diff、编译期拒非法组合、成本对账、迁移契约保持、Guard 可复现 trace、行为 eval。**这是别人抄不走、PI 会掏钱的层。**

落地顺序：① 原生 function-calling + react 降级为 fallback（根治执行）→ ② 第一方 agent 行为回归集（建尺子）→ ③ formal layer 兑现成可见保证（护城河）。

---

## 五、codex 评审修正（2026-06-17）

本评估方向对、80% 准、且准在痛处（把"模型不听话"改名成"执行车道选错了"）。codex 三处修正已并入上文：
1. **"没有 eval"太绝对** → 已有 pipeline/gate judge 基础设施（test_pipeline.py），缺的是第一方 agent 行为回归集。已改 §三②。
2. **FC 不消灭所有失败** → 它治格式/解析类;路径落错是工具层硬约束(workspace contract/cwd/sandbox/canonicalization),两件事。已加 §三① 注。
3. **形式化不是自动加分** → 必须产出 effect diff / 编译期拒绝 / 冲突检查 / 成本对账 / 迁移证明 / Guard trace 才算质量。已改 §三③。
并把战略加狠：react-over-text 从"主车道"降级为 fallback；formal layer 成为唯一差异化层。