alibaba / alibaba/ROCK

feat: add terminal settings support for create_session API

Open
#540 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
485
Forks
81
Avg merge
16h 12m
Merged PRs (30d)
8

Description

**Feature Category**
- [ ] Sandbox
- [x] Actions
- [ ] Deployments
- [x] SDK & API
- [ ] Envhub
- [ ] CLI
- [ ] Performance & Optimization
- [ ] Documentation & Examples

**Problem Statement**
`create_session` API 缺乏终端配置能力,导致依赖终端的程序无法正常工作

**Proposed Solution**
为 `CreateBashSessionRequest` 添加终端参数

**Detailed Feature Description**

1. 目标

为 `create_session` API 添加终端信息配置能力,允许用户在创建 bash session 时设置终端类型、尺寸、字符编码等参数。

2. 参数规格

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `term` | str | `"xterm-256color"` | 终端类型 (TERM 环境变量) |
| `columns` | int | `80` | 终端宽度(列数),必须 >= 1 |
| `lines` | int | `24` | 终端高度(行数),必须 >= 1 |
| `lang` | str | `"en_US.UTF-8"` | 字符编码 (LANG 环境变量) |

3. 环境变量映射

| 参数 | 环境变量 |
|------|----------|
| `term` | `TERM` |
| `columns` | `COLUMNS` |
| `lines` | `LINES` |
| `lang` | `LANG` |

4. 参数优先级

| 优先级 | 来源 |
|--------|------|
| 1 (最高) | `env` 参数中的同名变量 |
| 2 | 专用终端参数 (`term`, `columns`, `lines`, `lang`) |
| 3 | 如果 `env_enable=True`,继承宿主机环境变量 |
| 4 (最低) | 参数默认值 |

5. pexpect 配置

同时设置 pexpect 的 `dimensions` 参数,确保 `stty size` 命令返回正确值:

```python
pexpect.spawn(
command,
dimensions=(lines, columns), # (rows, cols)
...
)
```

6. 实现位置

| 文件 | 修改内容 |
|------|----------|
| `rock/actions/sandbox/request.py` | 添加终端参数到 `CreateBashSessionRequest` |
| `rock/rocklet/local_sandbox.py` | `BashSession.start()` 设置环境变量和 dimensions |

7. 测试用例

| 测试 | 描述 |
|------|------|
| `test_default_terminal_settings` | 验证默认值 TERM=xterm-256color, LANG=en_US.UTF-8 |
| `test_custom_terminal_settings` | 验证自定义值 |
| `test_terminal_size_stty` | 验证 `stty size` 输出正确 |
| `test_env_overrides_terminal_params` | 验证 env 参数优先级 |

8. 向后兼容

所有新参数都有默认值,现有代码无需修改即可正常工作。

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with rock/actions/sandbox/request.py and rock/rocklet/local_sandbox.py, focusing on CreateBashSessionRequest and BashSession.start(). Use the named tests—test_default_terminal_settings, test_custom_terminal_settings, test_terminal_size_stty, and test_env_overrides_terminal_params—to verify defaults, custom values, stty dimensions, and environment-variable precedence.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.