feat(ssa): Implement dual-channel architecture Phase 1-3 (QPER + LLM Agent pipeline)
Completed: - Phase 1: DB schema (execution_mode + ssa_agent_executions), ModeToggle component, Session PATCH API - Phase 2: AgentPlannerService + AgentCoderService (streaming) + CodeRunnerService + R Docker /execute-code endpoint - Phase 3: AgentCodePanel (3-step confirmation UI), SSE event handling (7 agent events), streaming code display - Three-step confirmation pipeline: plan -> user confirm -> stream code -> user confirm -> execute R code -> results - R Docker sandbox /execute-code endpoint with 120s timeout + block_helpers preloaded - E2E dual-channel test script (8 tests) - Updated R engine architecture doc (v1.5) and SSA module status doc (v4.0) Technical details: - AgentCoderService uses LLM streaming (chatStream) for real-time code generation feedback - ReviewerAgent temporarily disabled, prioritizing Plan -> Code -> Execute flow - CodeRunnerService wraps user code with auto data loading (df variable injection) - Frontend handles agent_planning, agent_plan_ready, code_generating, code_generated, code_executing, code_result events - ask_user mechanism used for plan and code confirmation steps Files: 24 files (4 new services, 2 new components, 1 migration, 1 E2E test, 16 modified) Made-with: Cursor
This commit is contained in:
@@ -1,9 +1,9 @@
|
||||
# R 统计引擎架构与部署指南
|
||||
|
||||
> **版本：** v1.4
|
||||
> **更新日期：** 2026-02-26
|
||||
> **版本：** v1.5
|
||||
> **更新日期：** 2026-03-02
|
||||
> **维护者：** SSA-Pro 开发团队 / ASL 循证工具箱团队
|
||||
> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 — 新增 Meta 分析引擎）
|
||||
> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 + Agent 代码执行端点）
|
||||
|
||||
---
|
||||
|
||||
@@ -49,9 +49,10 @@ R 统计引擎是平台的**专用统计计算服务**，基于 Docker 容器化
|
||||
│ ▼ ▼ 通用能力层 │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ R 统计引擎 (Docker) │ │
|
||||
│ │ • /health 健康检查 │ │
|
||||
│ │ • /api/v1/tools 工具列表 │ │
|
||||
│ │ • /api/v1/skills 技能执行 │ │
|
||||
│ │ • /health 健康检查 │ │
|
||||
│ │ • /api/v1/tools 工具列表 │ │
|
||||
│ │ • /api/v1/skills 技能执行（QPER 管线） │ │
|
||||
│ │ • /api/v1/execute-code 代码执行（Agent 通道） │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
@@ -552,7 +553,65 @@ Content-Type: application/json
|
||||
- 根据 `suggested_tool` 自动切换到更合适的方法
|
||||
- 将 `checks` 结果展示给用户
|
||||
|
||||
### 5.5 复合工具示例：基线特征表（Phase Deploy 新增）
|
||||
### 5.5 Agent 通道：执行任意 R 代码（v1.5 双通道架构新增）
|
||||
|
||||
```http
|
||||
POST /api/v1/execute-code
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"code": "blocks <- list()\nblocks[[1]] <- make_markdown_block('Hello', title='Test')\nlist(status='success', report_blocks=blocks)",
|
||||
"session_id": "xxx-xxx",
|
||||
"timeout": 120
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `code` | string | ✅ | 要执行的 R 代码（可使用 block_helpers.R 的所有辅助函数） |
|
||||
| `session_id` | string | 否 | 会话 ID（用于日志追踪） |
|
||||
| `timeout` | number | 否 | 超时秒数，默认 120，最大 120 |
|
||||
|
||||
**成功响应：**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"result": {
|
||||
"status": "success",
|
||||
"report_blocks": [
|
||||
{"type": "markdown", "content": "Hello", "title": "Test"}
|
||||
]
|
||||
},
|
||||
"console_output": [],
|
||||
"duration_ms": 42
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error_code": "E_EXEC",
|
||||
"message": "object 'xxx' not found",
|
||||
"user_hint": "R 代码执行出错 (123ms): object 'xxx' not found",
|
||||
"duration_ms": 123
|
||||
}
|
||||
```
|
||||
|
||||
**沙箱安全机制：**
|
||||
- 代码在 `new.env(parent = globalenv())` 隔离环境中执行
|
||||
- `setTimeLimit` 强制超时（CPU + 挂钟时间 ≤ 120 秒）
|
||||
- 可访问 `block_helpers.R` 和 `data_loader.R` 中的所有辅助函数
|
||||
- 由 Node.js `CodeRunnerService` 自动注入 `input` 和 `df` 数据变量
|
||||
|
||||
**调用方：** SSA 模块 Agent 通道（`CodeRunnerService.ts`），用于执行 LLM 生成的 R 代码。
|
||||
|
||||
> **与 `/api/v1/skills/{tool_code}` 的区别：** `/skills` 端点执行**预制的统计工具**（白名单限制），`/execute-code` 端点执行**任意 R 代码**（由 LLM Agent 生成，经 ReviewerAgent 审核后执行）。
|
||||
|
||||
### 5.6 复合工具示例：基线特征表（Phase Deploy）
|
||||
|
||||
```http
|
||||
POST /api/v1/skills/ST_BASELINE_TABLE
|
||||
@@ -604,7 +663,7 @@ Content-Type: application/json
|
||||
|
||||
> **特点：** `ST_BASELINE_TABLE` 是复合工具，基于 `gtsummary::tbl_summary()` 自动判断变量类型（连续/分类）、选择统计方法（T 检验/Mann-Whitney/卡方/Fisher），输出标准三线表。`report_blocks[0].metadata.is_baseline_table = true` 触发前端特殊渲染（P 值标星、rowspan 合并行）。
|
||||
|
||||
### 5.6 Meta 分析示例（ASL 工具 5 — v1.4 新增）
|
||||
### 5.7 Meta 分析示例（ASL 工具 5 — v1.4 新增）
|
||||
|
||||
```http
|
||||
POST /api/v1/skills/ST_META_ANALYSIS
|
||||
@@ -1364,7 +1423,8 @@ r-statistics-service/
|
||||
|
||||
| 版本 | 日期 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| v1.4 | 2026-02-26 | ASL Meta 分析引擎：工具 12→13（+ST_META_ANALYSIS），Dockerfile 新增 `meta` 包，新增 §5.6 Meta 分析 API 示例、陷阱 8（对数尺度反变换）、§9.5 Meta E2E 测试（36 断言全通过），架构图更新 ASL 调用方 |
|
||||
| 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 常见问题 |
|
||||
| v1.2 | 2026-02-22 | Phase Deploy 完成：工具 7→12（+Fisher/ANOVA/Wilcoxon/线性回归/基线表）、Dockerfile 新增 gtsummary 等 5 包、Block-based 输出协议文档化（§6.4）、全工具测试脚本 |
|
||||
| v1.1 | 2026-02-20 | Phase 2A 完成：7 个统计工具、JIT 护栏、热重载说明、常见问题补充 |
|
||||
|
||||
Reference in New Issue
Block a user