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

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 常见问题 |