docs: 智能体质量评估 + 三点最值得改(原生 function-calling / eval 闭环 / 形式化兑现)

从智能体质量维度对标主流平台,锚定 6/14~17 真实运行复盘(run_541390a1ea49 等)。
强项:形式化内核、加固纪律、两车道、单机隐私。弱项:react-over-text 文本 JSON 解析
脆(0 执行类 bug 总根源)、无 eval、上下文管理原始。三点改进按投入产出排序。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/AGENT_QUALITY_ASSESSMENT.md

@@ -0,0 +1,85 @@
+# 智能体质量评估与改进建议
+
+日期：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 + 解析层），但收益覆盖最大一类故障。
+
+### ② 建 eval 闭环 —— 让质量可度量
+- **问题**：无法回答"乱跳改好没""qwen-plus 真更好吗""native 比 react 强多少"——只能靠感觉。
+- **方案**：每个第一方 agent 配 3–5 个 golden 任务（输入 + 期望产物特征）；用 LLM-judge（复用平台 pipeline 已有的 default_judge）对产物打分；进 CI 做**行为回归**（与代码单测分离，可 nightly）。指标：落盘率、产物达标率、步数/成本、纪律遵守率（PROGRESS 全勾率）。
+- **影响面**：新增 `evals/` 目录 + 一个 runner（复用 pipeline 的 judge）；CI 加一个可选 job。
+- **验收**：每次改 provider/prompt/纪律，能看到分数变化而非人肉看 trace。
+- **工作量**：中；是后续一切优化的"尺子"，应尽早建。
+
+### ③ 把形式化内核兑现成用户可感知的保证
+- **问题**：cost 语义 / effects 优雅但运行时质量上"看不见"，目前更像论文资产。
+- **方案**：让它产出真价值——(a) **成本预测**：run 前用 `estimate_cost` 给预算并在 UI 显示，事后对账准确率作为卖点；(b) **effect 驱动安全**：把沙箱/权限从硬编码（`_sandbox`/dangerousCommandBlock）升级为由 agent 声明的 effect 推导；(c) **pipeline Guard 前置**：产物 gate 在写盘前校验（已有骨架）。
+- **影响面**：connect `engine/pipeline` 的 cost/gate 到 UI 与运行时；中长期。
+- **验收**：用户能看到"这条 run 预计 $X、effect 仅限 F 目录读写"，且事后对得上。
+- **工作量**：中–大；是差异化护城河，非救火，可排在 ①② 之后。
+
+---
+
+## 四、定位建议（一句话）
+
+**底层别硬卷，上层卷形式化与领域 eval。**
+- 底层执行尽量"借"原生能力（claude-code/codex 走 native；其他走 function-calling），不自己卷 agentic 可靠性——卷不过基座 harness。
+- 力气花在**编排的可证明性（effects/cost/Guard）+ 科研领域 agent 的 eval 质量**上——这是 PI 会掏钱、别人抄不走的护城河。
+
+落地顺序建议：① 原生 function-calling（救火 + 根治）→ ② eval 闭环（建尺子）→ ③ 形式化兑现（护城河）。