From c681155de2fd16f30a289b19d342a5f8ea09dcc1 Mon Sep 17 00:00:00 2001 From: HaHafeng Date: Sat, 7 Mar 2026 22:38:28 +0800 Subject: [PATCH] docs(r-engine): Update R statistics engine guide v1.6 with structured error handling - Update execute-code error response format with new fields: error_type, error_line, error_context, console_output - Document withCallingHandlers for warnings/messages capture in sandbox - Add error code reference table (E001-E101 + E_EXEC, 20+ pattern matching) - Document format_agent_error() structured error extraction for CoderAgent auto-repair - Fix caller description: ReviewerAgent paused, CoderAgent is the actual caller - Clarify difference between /skills (map_r_error) and /execute-code (format_agent_error) error handling - Update directory structure descriptions for plumber.R and error_codes.R Made-with: Cursor --- .../06-R统计引擎/01-R统计引擎架构与部署指南.md | 55 +++++++++++++++---- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md b/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md index 32904726..356295f0 100644 --- a/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md +++ b/docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md @@ -1,9 +1,9 @@ # R 统计引擎架构与部署指南 -> **版本：** v1.5 -> **更新日期：** 2026-03-02 +> **版本：** v1.6 +> **更新日期：** 2026-03-07 > **维护者：** SSA-Pro 开发团队 / ASL 循证工具箱团队 -> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 + Agent 代码执行端点） +> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 + Agent 代码执行端点 + 结构化错误处理） --- @@ -590,26 +590,58 @@ Content-Type: application/json } ``` -**错误响应：** +**错误响应（v1.6 结构化错误）：** ```json { "status": "error", - "error_code": "E_EXEC", - "message": "object 'xxx' not found", - "user_hint": "R 代码执行出错 (123ms): object 'xxx' not found", + "error_code": "E001", + "error_type": "business", + "message": "[E001] object 'blood_pressure' not found (约第 12 行)\n[Warnings] NAs introduced by coercion", + "user_hint": "请检查变量名是否拼写正确 | object 'blood_pressure' not found", + "error_line": 12, + "error_context": " 9| df$group <- as.factor(df$group)\n 10| \n 11| # 执行 T 检验\n>>> 12| result <- t.test(blood_pressure ~ group, data = df)\n 13| \n 14| # 构建结果", + "console_output": ["Loading required package: ggplot2", "Warning: NAs introduced by coercion"], "duration_ms": 123 } ``` +| 错误响应字段 | 类型 | 说明 | +|-------------|------|------| +| `error_code` | string | 错误分类码（`E001`-`E007` 业务错误，`E100`-`E101` 系统错误，`E_EXEC` 未分类运行时错误） | +| `error_type` | string | `business`（可由 LLM 自动修复）或 `system`（需人工介入）或 `runtime`（未分类） | +| `message` | string | 结构化友好消息，含错误码 + 原始信息 + 行号 + 警告摘要 | +| `user_hint` | string | 面向 LLM 的修复建议 + 原始错误拼接 | +| `error_line` | number? | 出错代码行号（从 R 错误信息中提取，可能为 null） | +| `error_context` | string? | 出错行前后 3 行的代码上下文，`>>>` 标记出错行（可能为 null） | +| `console_output` | string[] | R 控制台完整输出（stdout + warnings + messages 合并） | + +**错误码速查（`error_codes.R` 定义，20+ 模式匹配）：** + +| 错误码 | 类型 | 典型触发 | LLM 修复建议 | +|--------|------|---------|-------------| +| E001 | business | `object 'xxx' not found`, `undefined columns` | 检查变量名拼写 | +| E002 | business | `non-numeric argument`, `cannot coerce`, `contrasts can be applied only to factors` | 检查数据类型 | +| E003 | business | 分组变量水平数不匹配 | 检查分组变量取值 | +| E004 | business | `need at least 2 observations`, `sample size must be` | 数据量不足 | +| E005 | business | `singular matrix`, `rank deficient`, `singular gradient` | 移除共线变量 | +| E006 | business | `did not converge` | 调整模型参数 | +| E007 | business | 方差为零 | 该列值全部相同 | +| E100 | system | `subscript out of bounds`, `missing value where TRUE/FALSE needed` | 需人工排查 | +| E101 | system | `could not find function`, `no package called` | 缺少 R 包 | +| E_EXEC | runtime | 未匹配到已知模式 | 返回原始错误信息 | + **沙箱安全机制：** - 代码在 `new.env(parent = globalenv())` 隔离环境中执行 - `setTimeLimit` 强制超时（CPU + 挂钟时间 ≤ 120 秒） +- `withCallingHandlers` 捕获 warnings 和 messages（不中断执行），错误由外层 `tryCatch` 捕获 +- `console_output` 合并三种来源：`capture.output` stdout + 收集的 warnings + 收集的 messages +- 错误时调用 `format_agent_error()` 提取行号、代码上下文、错误分类和修复建议 - 可访问 `block_helpers.R` 和 `data_loader.R` 中的所有辅助函数 - 由 Node.js `CodeRunnerService` 自动注入 `input` 和 `df` 数据变量 -**调用方：** SSA 模块 Agent 通道（`CodeRunnerService.ts`），用于执行 LLM 生成的 R 代码。 +**调用方：** SSA 模块 Agent 通道（`CodeRunnerService.ts` → `ChatHandlerService.ts`），用于执行 LLM CoderAgent 生成的 R 代码。 -> **与 `/api/v1/skills/{tool_code}` 的区别：** `/skills` 端点执行**预制的统计工具**（白名单限制），`/execute-code` 端点执行**任意 R 代码**（由 LLM Agent 生成，经 ReviewerAgent 审核后执行）。 +> **与 `/api/v1/skills/{tool_code}` 的区别：** `/skills` 端点执行**预制的统计工具**（白名单限制），`/execute-code` 端点执行**任意 R 代码**（由 LLM CoderAgent 生成）。两者的错误处理也不同：`/skills` 使用 `map_r_error()` 做简单映射，`/execute-code` 使用 `format_agent_error()` 返回结构化错误（含行号和上下文），便于 CoderAgent 自动修复重试。 ### 5.6 复合工具示例：基线特征表（Phase Deploy） @@ -1382,11 +1414,11 @@ r-statistics-service/ ├── docker-compose.yml # 开发环境编排（含 volume 挂载） ├── renv.lock # R 包版本锁定（备用） ├── .Rprofile # R 启动配置（备用） -├── plumber.R # API 入口（含 JIT 护栏端点，自动发现 tools/ 目录） +├── plumber.R # API 入口（含 JIT 护栏端点，自动发现 tools/，Agent withCallingHandlers 错误处理） ├── utils/ │ ├── data_loader.R # 数据加载（支持行格式/列格式） │ ├── guardrails.R # 统计护栏 + JIT 检查（12 工具全覆盖） -│ ├── error_codes.R # 错误映射 +│ ├── error_codes.R # 错误映射（20+ 模式 + format_agent_error 结构化错误） │ ├── result_formatter.R # 结果格式化 │ └── block_helpers.R # Block-based 输出辅助函数（Phase E+ 协议） ├── tools/ # 统计工具（13 个） @@ -1423,6 +1455,7 @@ r-statistics-service/ | 版本 | 日期 | 更新内容 | |------|------|----------| +| v1.6 | 2026-03-07 | Agent 通道错误处理增强：`execute-code` 端点新增结构化错误响应（`error_type`/`error_line`/`error_context`/`console_output`），`withCallingHandlers` 捕获 warnings+messages，`format_agent_error()` 从 20+ 模式匹配中提取错误分类+行号+上下文+修复建议（§5.5），便于 CoderAgent 自动修复重试 | | v1.5 | 2026-03-02 | SSA 双通道架构：新增 `POST /api/v1/execute-code` 沙箱端点（§5.5）供 Agent 通道执行 LLM 生成的 R 代码，含超时 + 隔离环境；架构图新增 Agent 通道入口 | | v1.4 | 2026-02-26 | ASL Meta 分析引擎：工具 12→13（+ST_META_ANALYSIS），Dockerfile 新增 `meta` 包，新增 §5.7 Meta 分析 API 示例、陷阱 8（对数尺度反变换）、§9.5 Meta E2E 测试（36 断言全通过），架构图更新 ASL 调用方 | | v1.3 | 2026-02-22 | 开发者体验增强：新工具模板补全 report_blocks（§6.1）、各工具 params 速查表（§6.5）、R 语言 7 大陷阱实录（§6.6）、新增 R 包操作指南（§6.7）、新增 Q11-Q13 常见问题 |