Metadata-Version: 2.5
Name: claude-sandbox-sdk
Version: 0.2.0b1
Summary: Claude Sandbox SDK — 管理 Claude Agent 沙盒服务的 CLI 工具
Project-URL: Homepage, https://github.com/ai302/claude-sandbox-sdk
Project-URL: Repository, https://github.com/ai302/claude-sandbox-sdk
Project-URL: Issues, https://github.com/ai302/claude-sandbox-sdk/issues
Author: AI302
License: MIT
License-File: LICENSE
Keywords: agent,claude,sandbox,sdk,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: charset-normalizer>=3.0.0
Requires-Dist: claude-agent-sdk>=0.2.91
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: rich>=13.0
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: uvicorn[standard]>=0.23.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Claude Sandbox SDK

管理 Claude Agent 沙盒服务的 CLI 工具。

## 安装

```bash
pip install claude-sandbox-sdk
```

## 使用

### 启动服务

```bash
# 前台运行
claude-sandbox start

# 后台运行
claude-sandbox start --daemon

# 指定端口
claude-sandbox start --port 8300

# 指定地址和端口
claude-sandbox start --host 127.0.0.1 --port 8300
```

### 停止服务

```bash
claude-sandbox stop

# 强制终止
claude-sandbox stop --force
```

### 重启服务

```bash
claude-sandbox restart

# 重启并更换端口
claude-sandbox restart --port 8300

# 先同步控制中台投放的资源，再重启
claude-sandbox restart --assets-dir /path/to/bundle
```

### 更新 Agent 资源与 MCP 工具

`assets/media-studio-agent` 与 `mcp_tools.py` 不再打进 wheel，由 agent 控制中台
维护和投放。控制中台把 bundle 写进沙盒后，执行：

```bash
claude-sandbox restart --assets-dir /path/to/bundle
```

bundle 目录结构（两种形态都接受）：

```
<bundle>/
  .claude/agents/*.md
  .claude/skills/...
  CLAUDE.md
  settings.json
  mcp_tools.py          # 可选，只在 MCP 有变化时携带
```

或者把 agent 资源整体放在 `<bundle>/media-studio-agent/` 下。同步规则：

- agent 资源复制到工作目录，覆盖同名文件；
- 上次投放、本次 bundle 已不存在的文件会被清理（只清理自己投放过的文件）；
- `mcp_tools.py` 安装到 `~/.claude-sandbox/runtime/mcp_tools.py`，服务启动时
  从这里动态加载，不放进工作目录；
- 只带 `mcp_tools.py` 的 bundle 视为「仅更新 MCP」，不改动工作目录。

MCP 模块必须导出 `mcp`、`set_client_env`、`_download_file`、`_wrap_song`
（与 `server.py` 的下载接口共用）。它是进程内加载的，因此新增第三方依赖时
需要同步更新沙盒镜像。

> 首次部署时必须先投放一次 `mcp_tools.py`，否则服务会拒绝启动。

### 查看状态

```bash
claude-sandbox status
```

### 查看日志

```bash
# 查看最近 50 行
claude-sandbox logs

# 实时跟踪
claude-sandbox logs --follow

# 查看最近 100 行
claude-sandbox logs --lines 100
```

## 配置

配置优先级: CLI 参数 > 环境变量 > 默认值

| 配置项 | 环境变量 | 默认值 |
|-------|---------|-------|
| host | `CLAUDE_SANDBOX_HOST` | 0.0.0.0 |
| port | `CLAUDE_SANDBOX_PORT` | 8200 |
| log_level | `CLAUDE_SANDBOX_LOG_LEVEL` | INFO |
| workspace | `CLAUDE_SANDBOX_WORKSPACE` | /home/user/workspace |
| mcp_path | `CLAUDE_SANDBOX_MCP_PATH` | ~/.claude-sandbox/runtime/mcp_tools.py |

## 数据目录

服务运行时数据存储在 `~/.claude-sandbox/`:

- `pid` — 运行中的进程 PID
- `port` — 当前使用的端口
- `server.log` — 服务日志
- `runtime/mcp_tools.py` — 控制中台投放的 MCP 工具模块
- `deployed_assets.json` — 上次同步到工作目录的文件清单

## 开发

```bash
# 克隆仓库
git clone https://github.com/ai302/claude-sandbox-sdk.git
cd claude-sandbox-sdk

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check .
mypy app/
```

## 发布

```bash
# 构建
python -m build

# 上传到 PyPI
twine upload dist/*
```

## API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/sessions` | GET | 列出会话 |
| `/sessions/{id}` | GET | 获取会话信息 |
| `/sessions/{id}/messages` | GET | 获取会话消息 |
| `/ws/chat` | WebSocket | 聊天接口 |

## License

MIT
