docs/plan/2026-05-29-shell-session-design.md
Rama main · réplica de lectura del repositorio original.
# Shell 会话系统技术方案
> Note: The `bash` tool has been removed. `shell` is now the only command execution tool. See `2026-06-03-shell-unification-design.md`.
## 一、背景与目标
### 1.1 当前实现的局限
原有 `BashTool`（已移除）采用无状态设计，每次调用都创建新进程：
```java
ProcessBuilder pb = new ProcessBuilder("bash", "-c", command);
```
这导致：
- **状态丢失**：`cd /tmp` 后再 `ls` 无法感知目录变化
- **环境隔离**：无法维持环境变量、虚拟环境等
- **交互缺失**：不支持 `top`、`python -i` 等交互式程序
- **输出截断**：超过 50000 字符直接丢弃，无法回溯
### 1.2 设计目标
将 Shell 从"一次性命令执行器"升级为"有状态的交互式子系统"：
1. **会话持久化**：每个 Agent 对话拥有独立 Shell 会话，状态持续存在
2. **双模式支持**：普通命令（同步）+ 交互式程序（PTY）
3. **输出管理**：截断预览 + 完整落盘，不丢失信息
4. **向后兼容**：原有 BashTool 调用方式已迁移至 ShellSessionTool
---
## 二、架构设计
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ AgentLoop │
│ │ │
│ ToolDispatcher │
│ │ │
│ ┌───────────────┴───────────────┐ │
│ │ │ │
│ BashTool (已移除) ShellSessionTool (当前) │
│ │ │
│ ShellSessionManager │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ShellSession ShellSession ShellSession │
│ (普通模式) (PTY模式) (...) │
│ │ │ │ │
│ Process PTY Process ... │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 核心组件
| 组件 | 职责 |
|------|------|
| `ShellSessionManager` | 会话生命周期管理，会话池 |
| `ShellSession` | 单个会话的状态封装（进程、工作目录、环境变量） |
| `ShellSessionTool` | 新的 Tool 实现，暴露给 LLM |
| `OutputManager` | 输出截断、落盘、格式化 |
| `PathSandbox` | 复用现有路径安全校验 |
---
## 三、核心组件详细设计
### 3.1 ShellSession — 会话实体
```java
public class ShellSession {
private final String sessionId; // 会话唯一标识
private final Long conversationId; // 关联的 Agent 对话 ID
private final boolean ptyMode; // 是否 PTY 模式
private final Process process; // bash 进程
private final BufferedWriter stdin; // 标准输入流
private final BufferedReader stdout; // 标准输出流
private final Path workspaceDir; // 工作目录
private final Path outputFile; // 输出落盘文件
private final Instant createdAt; // 创建时间
private Instant lastActiveAt; // 最后活跃时间
private volatile boolean alive = true; // 会话是否存活
// 状态信息
private String currentWorkdir; // 当前工作目录（通过 pwd 追踪）
private Map<String, String> envVars; // 环境变量快照
}
```
**关键设计点**：
1. **进程复用**：启动 `bash --norc --noprofile` 保持运行，通过 stdin/stdout 交互
2. **工作目录追踪**：每次命令执行后自动注入 `pwd` 获取当前目录
3. **输出落盘**：所有输出 append 到文件，返回时截断预览
### 3.2 ShellSessionManager — 会话管理器
```java
@Component
public class ShellSessionManager {
// 会话池：sessionId -> ShellSession
private final ConcurrentHashMap<String, ShellSession> sessions = new ConcurrentHashMap<>();
// 按 conversationId 分组索引
private final ConcurrentHashMap<Long, Set<String>> conversationSessions = new ConcurrentHashMap<>();
// 配置
private static final int MAX_SESSIONS_PER_CONVERSATION = 5;
private static final Duration SESSION_IDLE_TIMEOUT = Duration.ofMinutes(30);
private static final Duration SESSION_MAX_LIFETIME = Duration.ofHours(2);
/**
* 获取或创建会话
*/
public ShellSession getOrCreate(Long conversationId, String sessionId, boolean ptyMode) {
// 1. 如果 sessionId 已存在且存活，直接返回
// 2. 如果 sessionId 不存在，创建新会话
// 3. 检查会话数限制
// 4. 启动 bash 进程
}
/**
* 关闭指定会话
*/
public void close(String sessionId) {
// 1. 关闭进程
// 2. 从 sessions 移除
// 3. 从 conversationSessions 索引移除
}
/**
* 关闭某个对话的所有会话
*/
public void closeByConversation(Long conversationId) {
// 遍历 conversationSessions.get(conversationId) 逐个关闭
}
/**
* 清理过期会话（定时任务调用）
*/
@Scheduled(fixedRate = 60000)
public void cleanupExpiredSessions() {
// 遍历 sessions，关闭 idle > 30min 或 lifetime > 2h 的会话
}
}
```
### 3.3 OutputManager — 输出管理器
```java
@Component
public class OutputManager {
private static final int MAX_PREVIEW_LINES = 100;
private static final int MAX_PREVIEW_CHARS = 10000;
private static final String OUTPUT_DIR = "shellOutput";
/**
* 读取进程输出，返回截断预览 + 完整落盘
*/
public OutputResult readOutput(BufferedReader reader, Path outputFile, Duration yieldTime) {
// 1. 等待 yieldTime（默认 10s），让命令有时间产生输出
// 2. 非阻塞读取所有可用输出
// 3. 写入 outputFile（append 模式）
// 4. 如果超过阈值，只返回尾部 N 行/字符
// 5. 返回 OutputResult（preview, fullWritten, totalLines）
}
/**
* 格式化工具返回结果
*/
public String formatToolResult(int exitCode, String sessionId, long elapsedMs,
OutputResult output, String currentWorkdir) {
return String.format("""
exit_code: %d
session_id: %s
elapsed_ms: %d
current_workdir: %s
output_lines: %d
truncated: %s
---
%s""",
exitCode, sessionId, elapsedMs, currentWorkdir,
output.totalLines(), output.truncated(), output.preview());
}
}
```
### 3.4 ShellSessionTool — 新工具实现
```java
@Component
public class ShellSessionTool implements Tool {
private final ShellSessionManager sessionManager;
private final OutputManager outputManager;
private final PathSandbox pathSandbox;
private final ObjectMapper objectMapper;
@Override
public String getName() {
return "shell"; // 新工具名，与原有 bash 区分
}
@Override
public String getDescription() {
return """
Interactive shell tool with session persistence.
Actions:
- exec: Execute a command in a shell session
- write_stdin: Write input to an interactive session
- close: Close a shell session
- list: List active sessions for current conversation
""";
}
@Override
public Map<String, Object> getInputSchema() {
// 返回 JSON Schema，包含 action、session_id、command 等参数
}
@Override
public String execute(String arguments, Long sessionId, String workspace) {
JsonNode args = objectMapper.readTree(arguments);
String action = args.get("action").asText();
return switch (action) {
case "exec" -> handleExec(args, sessionId, workspace);
case "write_stdin" -> handleWriteStdin(args, sessionId, workspace);
case "close" -> handleClose(args, sessionId);
case "list" -> handleList(sessionId);
default -> errorJson("Unknown action: " + action);
};
}
private String handleExec(JsonNode args, Long conversationId, String workspace) {
// 1. 解析参数：session_id（可选）、command、workdir（可选）、pty（可选）
// 2. 获取或创建 ShellSession
// 3. 如果有 workdir，先执行 cd
// 4. 写入命令到 stdin
// 5. 读取输出（带 yieldTime）
// 6. 追踪当前工作目录（注入 pwd）
// 7. 格式化返回
}
}
```
---
## 四、交互模式设计
### 4.1 普通模式（pty=false）
适用场景：大多数命令，直接获取结果
```
Agent 调用: shell(action="exec", command="ls -la", session_id="s1")
↓
ShellSession:
stdin.write("ls -la\n")
stdin.write("pwd\n") // 自动注入，追踪目录
stdout.readWithTimeout(10s)
↓
返回: {exit_code: 0, current_workdir: "/tmp", output: "..."}
```
### 4.2 PTY 模式（pty=true）
适用场景：交互式程序（top、python -i、vim 等）
```
Agent 调用: shell(action="exec", command="python3 -i", session_id="s2", pty=true)
↓
ShellSession:
启动 PTY 进程
stdout.readWithTimeout(5s) // 读取初始输出（Python banner）
↓
返回: {session_id: "s2", output: "Python 3.11.0\n>>>"}
Agent 调用: shell(action="write_stdin", session_id="s2", input="print('hello')\n")
↓
ShellSession:
stdin.write("print('hello')\n")
stdout.readWithTimeout(5s)
↓
返回: {session_id: "s2", output: "hello\n>>>"}
```
### 4.3 命令执行流程对比
| 步骤 | BashTool (已移除) | ShellSessionTool (当前) |
|------|--------------|---------------------|
| 1. 接收命令 | `execute(command)` (已移除) | `exec(command, session_id)` |
| 2. 创建进程 | 每次新建 | 复用已有会话 |
| 3. 执行命令 | `bash -c command` | `stdin.write(command)` |
| 4. 读取输出 | `process.getInputStream()` | `stdout.readWithTimeout()` |
| 5. 返回结果 | 截断到 50000 字符 | 预览 + 落盘 |
| 6. 清理 | `process.destroy()` | 保持会话存活 |
---
## 五、输出管理设计
### 5.1 输出截断策略
```
原始输出（可能 100000+ 字符）
↓
┌───┴───┐
│ │
预览 完整输出
(返回给AI) (落盘到文件)
│
├── 尾部 100 行
└── 最多 10000 字符
```
### 5.2 文件落盘结构
```
workspace/
└── shellOutput/
├── {sessionId}_1.out # 第 1 次命令输出
├── {sessionId}_2.out # 第 2 次命令输出
└── {sessionId}_N.out # 第 N 次命令输出
```
Agent 可通过 `read_file` 工具查看完整输出：
```
read_file(path="shellOutput/s1_3.out")
```
### 5.3 返回格式
```json
{
"exit_code": 0,
"session_id": "s1",
"elapsed_ms": 156,
"current_workdir": "/tmp/project",
"output_lines": 245,
"truncated": true,
"output_file": "shellOutput/s1_3.out",
"output": "（尾部 100 行预览）..."
}
```
---
## 六、数据库设计
### 6.1 新增表：shell_session
```sql
CREATE TABLE IF NOT EXISTS `shell_session` (
`id` BIGINT PRIMARY KEY AUTO_INCREMENT,
`session_id` VARCHAR(64) NOT NULL UNIQUE COMMENT '会话唯一标识',
`conversation_id` BIGINT NOT NULL COMMENT '关联的会话 ID',
`pty_mode` TINYINT DEFAULT 0 COMMENT '是否 PTY 模式 0-否 1-是',
`pid` INT COMMENT '进程 PID',
`current_workdir` VARCHAR(512) COMMENT '当前工作目录',
`status` VARCHAR(20) DEFAULT 'ACTIVE' COMMENT 'ACTIVE/CLOSED/EXPIRED',
`command_count` INT DEFAULT 0 COMMENT '已执行命令数',
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
`last_active_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
`closed_at` DATETIME,
INDEX `idx_conversation` (`conversation_id`),
INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
### 6.2 新增表：shell_command_log
```sql
CREATE TABLE IF NOT EXISTS `shell_command_log` (
`id` BIGINT PRIMARY KEY AUTO_INCREMENT,
`session_id` VARCHAR(64) NOT NULL COMMENT '会话 ID',
`conversation_id` BIGINT NOT NULL COMMENT '会话 ID',
`command` TEXT NOT NULL COMMENT '执行的命令',
`exit_code` INT COMMENT '退出码',
`output_lines` INT COMMENT '输出行数',
`output_file` VARCHAR(512) COMMENT '输出文件路径',
`truncated` TINYINT DEFAULT 0 COMMENT '是否截断',
`elapsed_ms` INT COMMENT '执行耗时（毫秒）',
`executed_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX `idx_session` (`session_id`),
INDEX `idx_conversation` (`conversation_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
---
## 七、API 设计
### 7.1 Tool Schema（供 LLM 调用）
```json
{
"name": "shell",
"description": "Interactive shell tool with session persistence. Supports multi-step operations and interactive programs.",
"input_schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["exec", "write_stdin", "close", "list"],
"description": "Action to perform"
},
"session_id": {
"type": "string",
"description": "Session ID. Omit to create new session, or provide to reuse existing."
},
"command": {
"type": "string",
"description": "Shell command to execute (for exec action)"
},
"input": {
"type": "string",
"description": "Input to write to stdin (for write_stdin action)"
},
"workdir": {
"type": "string",
"description": "Working directory (relative to workspace)"
},
"pty": {
"type": "boolean",
"description": "Use PTY mode for interactive programs (default false)"
},
"timeout": {
"type": "integer",
"description": "Timeout in seconds (default 30)"
},
"yield_time_ms": {
"type": "integer",
"description": "Initial wait time for output (default 10000)"
}
},
"required": ["action"]
}
}
```
### 7.2 调用示例
**普通命令**：
```json
{
"action": "exec",
"command": "npm install",
"workdir": "frontend"
}
```
**交互式程序**：
```json
// 第一次调用：启动 Python
{"action": "exec", "command": "python3 -i", "pty": true}
// 后续调用：发送输入
{"action": "write_stdin", "session_id": "s1", "input": "import pandas as pd\n"}
{"action": "write_stdin", "session_id": "s1", "input": "df = pd.read_csv('data.csv')\n"}
{"action": "write_stdin", "session_id": "s1", "input": "df.head()\n"}
// 关闭会话
{"action": "close", "session_id": "s1"}
```
---
## 八、安全设计
### 8.1 路径安全
复用现有 `PathSandbox`，所有路径操作必须经过校验：
```java
Path resolvedWorkdir = pathSandbox.resolve(workdir, workspace);
```
### 8.2 命令白名单（可选）
可配置允许/禁止的命令模式：
```yaml
app:
harness:
shell:
allowed-commands:
- "npm *"
- "git *"
- "python3 *"
blocked-commands:
- "rm -rf /"
- "sudo *"
```
### 8.3 资源限制
| 资源 | 限制 |
|------|------|
| 每对话最大会话数 | 5 |
| 会话空闲超时 | 30 分钟 |
| 会话最大生命周期 | 2 小时 |
| 单命令最大输出 | 100 MB（落盘） |
| 预览输出大小 | 10000 字符 |
### 8.4 会话清理
```java
@Scheduled(fixedRate = 60000) // 每分钟检查
public void cleanupExpiredSessions() {
sessions.forEach((id, session) -> {
if (session.isExpired() || session.isIdleTimeout()) {
session.close();
sessions.remove(id);
}
});
}
```
---
## 九、与现有系统的集成
### 9.1 ToolDispatcher 路由
```java
public String dispatch(String toolName, String arguments, String executionMode,
Long sessionId, String workspace) {
// 新增 shell 工具路由
if ("shell".equals(toolName)) {
Tool tool = toolRegistry.getTool("shell");
return tool.execute(arguments, sessionId, workspace);
}
// 原有逻辑保持不变
if ("LOCAL".equals(executionMode)) {
return localToolExecutor.execute(sessionId, toolName, arguments, workspace);
}
Tool tool = toolRegistry.getTool(toolName);
return tool.execute(arguments, sessionId, workspace);
}
```
### 9.2 AgentLoop 集成
在 AgentLoop 的会话结束时清理 Shell 会话：
```java
public void execute(AgentExecutionContext context, AgentEventListener listener,
MessagePersistenceCallback persistenceCallback) {
try {
// ... 原有逻辑 ...
} finally {
// 清理该对话的所有 Shell 会话
shellSessionManager.closeByConversation(context.getSessionId());
}
}
```
### 9.3 PromptEngine 集成
在系统提示词中注入 Shell 工具使用指南：
```java
public String buildSystemPrompt(AgentExecutionContext context) {
StringBuilder sb = new StringBuilder();
// ... 原有逻辑 ...
// 如果 Agent 配置了 shell 工具，注入使用指南
if (context.getToolNames().contains("shell")) {
sb.append("\n## Shell Tool Usage\n");
sb.append(shellUsageGuide); // 从 skill 文档加载
}
return sb.toString();
}
```
---
## 十、改造清单
### 10.1 新增文件
| 文件路径 | 说明 |
|---------|------|
| `backend/.../harness/shell/ShellSession.java` | 会话实体类 |
| `backend/.../harness/shell/ShellSessionManager.java` | 会话管理器 |
| `backend/.../harness/shell/OutputManager.java` | 输出管理器 |
| `backend/.../harness/tool/impl/ShellSessionTool.java` | 新 Tool 实现 |
| `backend/.../harness/shell/ShellUsageGuide.md` | 使用指南（Skill 文档） |
| `backend/src/main/resources/db/migration/V011__shell_session.sql` | 数据库迁移 |
### 10.2 修改文件
| 文件路径 | 修改内容 |
|---------|---------|
| `backend/.../harness/tool/ToolRegistry.java` | 注册 ShellSessionTool |
| `backend/.../harness/init/ToolDataInitializer.java` | 初始化 shell 工具数据 |
| `backend/.../harness/core/AgentLoop.java` | 会话结束时清理 Shell 会话 |
| `backend/.../harness/core/PromptEngine.java` | 注入 Shell 使用指南 |
| `backend/.../harness/tool/ToolDispatcher.java` | 添加 shell 工具路由（可选） |
### 10.3 配置文件
```yaml
# application.yml 新增配置
app:
harness:
shell:
enabled: true
max-sessions-per-conversation: 30
session-idle-timeout-minutes: 30
session-max-lifetime-hours: 2
default-yield-time-ms: 10000
output:
max-preview-lines: 100
max-preview-chars: 10000
dir: shellOutput
```
---
## 十一、实施步骤
### Phase 1：基础框架（1-2 天）
1. 创建 `ShellSession` 实体类
2. 实现 `ShellSessionManager` 基础会话管理
3. 实现 `OutputManager` 输出截断和落盘
4. 编写数据库迁移脚本
### Phase 2：工具实现（2-3 天）
5. 实现 `ShellSessionTool` 的 `exec` action（普通模式）
6. 实现 `write_stdin` 和 `close` action
7. 集成到 `ToolRegistry` 和 `ToolDataInitializer`
8. 编写单元测试
### Phase 3：高级特性（2-3 天）
9. 实现 PTY 模式支持
10. 实现会话过期清理定时任务
11. 集成到 `AgentLoop` 会话生命周期
12. 编写 Skill 使用指南文档
### Phase 4：测试与优化（1-2 天）
13. 集成测试：多轮对话、会话复用、输出落盘
14. 性能测试：并发会话、长时间运行
15. 安全测试：路径逃逸、命令注入
16. 文档更新
---
## 十二、风险与注意事项
### 12.1 风险点
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 进程泄漏 | 内存/文件描述符耗尽 | 严格的超时和清理机制 |
| PTY 资源消耗 | 高并发下资源不足 | 限制每对话会话数 |
| 状态不可见 | Agent 忘记当前目录 | 每次返回 current_workdir |
| 输出过大 | 磁盘空间耗尽 | 限制单命令输出大小 |
### 12.2 向后兼容
- `BashTool` 已移除，`shell` 工具是唯一的命令执行工具
- 现有 Agent 已迁移到 `shell` 工具
### 12.3 性能考量
- 普通模式：与原有 BashTool 性能相当
- PTY 模式：每个会话占用一个 PTY 文件描述符
- 输出落盘：异步写入，不阻塞返回
---
## 十三、后续扩展
### 13.1 可能的增强
1. **命令历史**：记录会话内的命令历史，支持上下文感知
2. **环境变量管理**：支持设置/获取环境变量
3. **后台任务集成**：长时间命令自动转为后台任务
4. **会话持久化**：支持跨对话的会话恢复（需评估安全性）
5. **多用户隔离**：不同用户的会话完全隔离
### 13.2 与 LOCAL 模式的集成
ShellSessionTool 也可支持 LOCAL 模式，将命令转发到桌面客户端执行：
```
ShellSessionTool → LocalToolExecutor → WebSocket → Electron
```
这需要在桌面客户端实现对应的 Shell 会话管理逻辑。