fastshell 0.3.7

Lightweight Bash + Python runtime SDK for mobile AI agents
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
# fastshell

[![Crates.io](https://img.shields.io/crates/v/fastshell.svg)](https://crates.io/crates/fastshell)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

轻量级跨平台 Shell 运行时 SDK,面向移动端 AI Agent——提供 180+ Linux 兼容命令、管道、通配符展开、Python 执行、内置 SQLite。

## 解决的问题

移动平台缺少原生 Bash 环境。AI 编程 Agent 依赖 shell 命令和 Python,没有兼容的运行时就无法在手机上运行。fastshell 提供了一套自包含、可嵌入的运行时 SDK。

## 特性

- **180+ 内置命令** — `ls`、`grep`、`sed`、`awk`、`jq`、`curl`、`git`、`tar`、`sha256sum`……
- **内置 SQLite** — `sqlite3 db.sqlite "SELECT ..."`,零系统依赖(rusqlite bundled 静态链接)
- **设备能力集成** — `camera`、`clipboard`、`contacts`、`location`、`notify`、`open`、`say`、`screencapture`……通过插件 trait 接入
- **管道支持** — 真正并发执行,每个阶段独立线程,mpsc channel 流式传递
- **通配符展开** — `ls *.rs`、`cat src/**/*.rs`
- **正则表达式** — `grep` 和 `sed s///` 使用完整正则
- **Python 引擎** — 内嵌 [RustPython]https://github.com/RustPython/RustPython(MIT,纯 Rust,feature `python-rustpython`):支持 `ast`/`unittest`/冻结标准库,无 dlopen/JNI/C-TLS 崩溃面。桌面端优先使用系统 `python3`。
- **JavaScript 执行** — `node`/`js` 在宿主 App 的 WebView 引擎(Android V8 / iOS JavaScriptCore)里运行 JS,`render` 把 HTML 渲染成截图,`jscheck`/`node -c` 用 [oxc]https://github.com/oxc-project/oxc 做 JS/TS 语法静态检查(纯 Rust,可选 feature `js-oxc`)。
- **虚拟文件系统** — 沙箱隔离,防止路径逃逸
- **线程安全** — `Arc<Mutex<Runtime>>`,支持超时控制
- **跨平台** — 统一代码库编译 Android / iOS / macOS / Linux

## 真实应用

[**aacode**](https://github.com/kandada/aacode) —— 移动端 AI 编程助手,运行在 fastshell 之上:
- 整个 shell 沙箱、180+ 命令、内置 Python、设备桥接、原生 C-ABI agent 接口均由 fastshell 提供。
- 可通过 [**APK 下载**]https://github.com/kandada/aacode/raw/main/mobile_app/aacode-v1.7.24-arm64.apk 安装。Google Play 等应用市场还在上架流程中。
- 可通过  [**APK 下载**]https://github.com/kandada/aacode/raw/main/mobile_app/aacode-v1.7.24-arm64.apk 安装。Google Play等应用市场还在上架流程中。

## 安装

```toml
[dependencies]
fastshell = "0.3.4"
```

## 快速开始

### Rust

```rust
use fastshell::{Fastshell, Config};

let mut sdk = Fastshell::new();
sdk.init(Config {
    sandbox_path: "/tmp/my-sandbox".into(),
    command_timeout_ms: 30_000,
    python_enabled: true,
    allow_subprocess: true,
    network_ask_permission: false,
})?;

let result = sdk.execute("echo 你好 | wc -c");
assert_eq!(result.exit_code, 0);
println!("{}", result.stdout);

// 直接文件 API
sdk.write_file("hello.txt", "Hello, world!")?;
assert_eq!(sdk.read_file("hello.txt")?, "Hello, world!");

// Python
let r = sdk.execute_python("print(sum(range(1, 101)))");
// 5050
```

### 内嵌 RustPython(feature `python-rustpython`)

移动端内嵌 **[RustPython](https://github.com/RustPython/RustPython) 0.5.0** —— 纯 Rust 实现的
Python 3 解释器,直接编译进静态库:没有 `libpython.so`、没有 dlopen、没有磁盘
解压(CPython 纯 Python 标准库通过 `freeze-stdlib` 冻结进二进制)。

> 旧的 Chaquopy CPython 集成已移除:进程内嵌入式 CPython 在真机上崩溃
> (pthread/bionic TLS,`unittest`/`threading` 场景)。RustPython 从架构上
> 消灭了这一整类崩溃。

开箱即用:`ast` 语法检查、`unittest`、`json`、`re`、`os`、沙箱内文件读写、
大整数与正确的浮点除法语义。不支持 C 扩展(numpy 等,任何嵌入方案皆然)。

协议说明:RustPython 上游的 LGPL malachite 依赖已被净室 Apache-2.0 替身替换
(见 `num_bigint/README.md` 与 `vendor/README.md`),最终依赖树全部为宽松协议,
闭源 App 可放心静态链接。

桌面端优先使用系统 `python3`;设置 `FASTSHELL_PYTHON=rustpython` 可强制使用
内嵌引擎(用于在桌面上测试移动端代码路径)。

### Python 调用 Shell

在 fastshell 中运行的 Python 代码可以直接使用 `subprocess` 和 `asyncio` 调用 shell 命令,无需额外导入:

```python
import subprocess

# 执行 shell 命令
r = subprocess.run("ls -la", shell=True, capture_output=True, text=True)
print(r.stdout)

# 管道也支持
r = subprocess.run("cat file.txt | grep hello | wc -l", shell=True, capture_output=True, text=True)

# 异步 shell
import asyncio
async def main():
    proc = await asyncio.create_subprocess_shell("curl -s https://api.example.com", stdout=asyncio.subprocess.PIPE)
    data, _ = await proc.communicate()
    print(data.decode())
asyncio.run(main())

# os.system 也可以
import os
ret = os.system("mkdir -p /tmp/work")
```

全部 180+ 内置命令、管道、通配符展开都可以在 Python 中使用。桌面端未知命令会转发给系统 shell;移动端**默认禁用** subprocess fallthrough,所有执行保持在进程内。

### 移动端 (FFI)

```c
// Android JNI / iOS C FFI
const char* result = fastshell_init("/data/sandbox");
const char* output = fastshell_execute("ls -la");
fastshell_free_string(output);
```

## API 参考

```rust
pub struct Config {
    pub sandbox_path: String,             // 沙箱路径(必填)
    pub python_enabled: bool,             // 是否启用 Python
    pub command_timeout_ms: u64,          // 超时(毫秒),0 = 不限
    pub allow_subprocess: bool,           // 允许 subprocess fallthrough
                                          //   桌面端默认 true,移动端默认 false
    pub network_ask_permission: bool,     // 网络请求触发用户授权
                                          //   移动端默认 true,桌面端默认 false
}

impl Fastshell {
    pub fn new() -> Self;
    pub fn init(&mut self, config: Config) -> Result<(), String>;
    pub fn execute(&self, command: &str) -> CommandResult;
    pub fn execute_python(&self, code: &str) -> CommandResult;
    pub fn execute_python_script(&self, script_path: &str) -> CommandResult;
    pub fn get_cwd(&self) -> String;
    pub fn read_file(&self, path: &str) -> Result<String, String>;
    pub fn write_file(&self, path: &str, content: &str) -> Result<(), String>;
    pub fn list_dir(&self, path: &str) -> Result<Vec<FileEntry>, String>;
    pub fn exists(&self, path: &str) -> bool;
    pub fn is_dir(&self, path: &str) -> bool;
    pub fn set_env(&mut self, key: &str, value: &str);
    pub fn get_env(&self, key: &str) -> Option<String>;
    pub fn get_info(&self) -> SdkInfo;
    pub fn config(&self) -> &Config;
    pub fn vfs_root(&self) -> String;
    pub fn shutdown(&mut self);

    // 权限管理(移动端)
    pub fn set_permission(&self, resource: &str, allowed: bool);
    pub fn check_permission(&self, resource: &str) -> Option<bool>;
    pub fn clear_permissions(&self);

    // 取消正在执行的命令(超时或中断用)
    pub fn cancel_execution(&self);

    // 注册设备插件
    pub fn register_plugin(&self, plugin: Box<dyn DevicePlugin>);
}

pub struct CommandResult {
    pub stdout: String,
    pub stderr: String,
    pub exit_code: i32,
    // exit_code == 100 → 需要用户授权(见下方权限控制章节)
}
```

## 权限控制(移动端)

fastshell 不自行决定网络访问规则,而是通过**特殊退出码**将决策权交给宿主 App:

```
1. 脚本执行 "curl http://example.com"
2. fastshell 检查 "network:example.com" 是否已授权
3. 未授权 → 返回 { exit_code: 100, stderr: "PERMISSION_NEEDED:network:example.com" }
4. 宿主 App 检测 exit_code=100 → 弹出原生对话框:"允许访问 example.com?"
5. 用户点击"允许" → 宿主调用 sdk.set_permission("network:example.com", true) → 重试命令
```

**资源类型:**
| 资源 | 触发场景 |
|------|---------|
| `network:<host>` | `curl`、`wget`、`ping`、`ssh`、`nslookup` |
| `network:*` | 一次性授权所有网络访问 |

**示例流程:**
```rust
let result = sdk.execute("curl http://example.com");
if result.exit_code == 100 {
    // 解析 stderr 获取资源标识,展示原生对话框
    sdk.set_permission("network:example.com", true);
    let result = sdk.execute("curl http://example.com"); // 重试
}
```

## 设备插件

fastshell 内置 22 个**设备能力命令**(`camera`、`clipboard`、`contacts`、`location`、`notify`、`open`……)。
这些命令**默认不工作** —— 需要宿主 App 实现 `DevicePlugin` trait 并注册。

```
┌──────────────────────────────┐      ┌────────────────────────────┐
│  fastshell SDK                │      │  宿主 App (Kotlin/Swift)   │
│                                │      │                            │
│  shell: "camera" → 命令       │      │  impl DevicePlugin {       │
│  检查: 插件已注册?             │──→   │    fn take_photo(path) {   │
│  调用: plugin.take_photo()    │      │      // AVCaptureSession   │
│                                │      │      // 或 CameraX         │
│  返回结果给 AI Agent           │←──   │    }                       │
└──────────────────────────────┘      └────────────────────────────┘
```

**宿主集成示例:**
```rust
use fastshell::sdk::plugin::DevicePlugin;

struct MyPlugin;
impl DevicePlugin for MyPlugin {
    fn take_photo(&self, output_path: &str) -> Result<(), String> {
        // 调起原生相机,照片存入沙盒指定路径
    }
    fn get_clipboard(&self) -> Result<String, String> { ... }
    fn get_location(&self) -> Result<Location, String> { ... }
    // 按需实现其他方法
}

sdk.register_plugin(Box::new(MyPlugin));
```

**权限模型:** 与网络权限一致 —— 首次调用返回 `exit_code=100` 和 `PERMISSION_NEEDED:camera:photo`。
宿主 App 弹出原生授权对话框,调用 `set_permission` 后重试。

**命令兼容性:** 常用 macOS/Linux 命令名均已别名 —— `pbcopy` / `pbpaste`、
`notify-send`、`xdg-open`、`screencapture`、`say`、`arecord` —— AI Agent 无需学习新命令名。

## 移动端集成注意事项

### 单进程保障

在移动端(`allow_subprocess = false`),fastshell 是 **100% 单进程** ——
所有内置命令、管道、Python 执行都在宿主 App 进程内完成,不产生子进程。这避免了:

- **Android 12+ Phantom Process Killer** — 系统限制所有 App 总共最多 32 个 phantom process,超出直接 SIGKILL
- **iOS 禁止 fork()** — iOS 不允许创建子进程

### 管道并发

管道已改为**真正的线程并发** —— 每个 stage 独立线程,mpsc channel 流式传递数据:

```
ls -la | grep foo | wc -l
  线程1      线程2      线程3
```

### VFS 根目录建议

| 平台 | 推荐路径 |
|------|---------|
| Android | `/data/data/<包名>/files/fastshell` |
| iOS | `<app>/Documents/fastshell`(**不要**用 `Library/Caches`,可能被系统清理) |
| 桌面 | 任意可写路径 |

### 网络配置要求

| 平台 | 要求 |
|------|------|
| iOS | `Info.plist` 添加 `NSAllowsArbitraryLoads`,或通过 `NSAppTransportSecurity` 配置域名白名单 |
| Android | `AndroidManifest.xml` 添加 `android:usesCleartextTraffic="true"` |

不配置的话,`curl`/`wget` 的 HTTP 请求在移动端默认失败。

### 保活建议(Android)

宿主 App 应实现 **Foreground Service** + 常驻通知,防止系统在后台杀进程。
各厂商白名单引导步骤参考 [dontkillmyapp.com](https://dontkillmyapp.com)。

### Subprocess Fallthrough

| 平台 | 默认值 | 行为 |
|------|--------|------|
| Android / iOS | `allow_subprocess = false` | 未知命令返回 "command not found (subprocess disabled)" |
| macOS / Linux | `allow_subprocess = true` | 未知命令转发给系统 shell |

内置命令(`ls`、`grep`、`curl`、`git` 等)不受此设置影响,在所有平台都能正常运行。

## 从源码编译

需要 Rust 稳定版工具链。

```bash
# 1. 编译目标平台(可选 feature:python-rustpython = 内嵌 Python,js-oxc = JS/TS 语法检查)
cargo build --release --target aarch64-apple-darwin        # macOS ARM64
cargo build --release --target x86_64-apple-darwin          # macOS Intel
cargo build --release --target aarch64-apple-ios            # iOS(需 macOS 宿主机)
cargo build --release --target aarch64-linux-android        # Android(需 NDK;libffi 已随仓库提供,见 vendor/README.md)

# Linux x86_64 交叉编译(需要 cargo-zigbuild)
pip3 install cargo-zigbuild
cargo zigbuild --release --target x86_64-unknown-linux-gnu

# 2. 运行测试(fastshell 约 500 个;含 aacode-rs 全 workspace 共 687 个)
cargo test --features git,python-rustpython
```

**注意:** Android 目标需要 Android NDK r27c。Python 由内嵌 RustPython 提供,
无需任何外部 CPython 资产。

产物直接链接到你的项目:

```
# macOS / Linux
target/aarch64-apple-darwin/release/libfastshell.dylib

# iOS
target/aarch64-apple-ios/release/libfastshell.a

# Android
target/aarch64-linux-android/release/libfastshell.so
```

编译产物参考(按 `git,python-rustpython` 全 feature 实测;不开则更小):

| 平台 | 输出文件 | 格式 | 约大小 |
|------|---------|------|--------|
| macOS Apple Silicon | `libfastshell.dylib` | 动态库 | ~14 MB |
| iOS arm64 | `libfastshell.a` | 静态库(链接期可裁剪) | ~90 MB `.a` |
| Android arm64 | `libaacode_rs.a` → `libfastshell_jni.so` | 静态库 + NDK CMake 链接(推荐,见 `fastshell_c/`) | ~218 MB `.a` → **~48 MB `.so`** |
| Linux x86_64 | `libfastshell.so` | 动态库 (.so) | ~14 MB |

移动端推荐 **staticlib + 宿主侧 C/CMake 链接** 路线(Android 见 `fastshell_c/`):
链接期死代码消除(`--gc-sections`)可大幅缩小最终 `.so`,且单个 `.a` 同时
包含 fastshell + aacode-rs agent + RustPython + git2。

## 命令列表

### 文件操作
`ls` `cd` `pwd` `mkdir` `rm` `cp` `mv` `cat` `find` `tree` `touch` `chmod` `file` `stat` `du` `basename` `dirname` `realpath`

### 文本处理
`grep`(`egrep`/`fgrep`)`rg` `sed` `awk` `sort` `uniq` `wc` `head` `tail` `cut` `tr` `diff` `tee` `xargs` `column` `paste` `rev` `comm` `xxd` `printf` `seq` `shuf`

### 网络
`curl` `wget` `ping` `ssh`

### 压缩
`gzip` `gunzip` `tar` `zip` `unzip`

### 加密 / 编码
`base64` `sha256sum` `sha512sum` `md5sum`

### JSON
`jq`

### 系统信息
`ps` `kill` `pgrep` `pkill` `env` `printenv` `date` `sleep` `which` `uname` `hostname` `whoami` `id` `df`

### 控制流程
`true` `false` `test` `expr` `timeout`

### 数据库
`sqlite3`(内置,bundled,无系统依赖)

### JavaScript
`node` `js` `render` `jscheck`(`node -c` 只做语法检查不执行)

### 设备能力(需插件)
`camera` `screencapture` `photolib` `record` `arecord` `play` `say` `speech` `contacts` `location` `clipboard` `pbpaste` `pbcopy` `sensor` `notify` `notify-send` `share` `open` `xdg-open` `auth` `battery` `vibrate` `screen` `device`

### 版本控制
`git`

## 架构

```
fastshell/
├── src/
│   ├── vfs/       # 层1 — 虚拟沙箱文件系统
│   ├── shell/     # 层1 — 180+ 内置命令(纯 Rust 实现)
│   ├── python/    # 层1 — Python 引擎(子进程 / CPython)
│   ├── js/        # 层1 — JS/TS 语法静态检查(oxc,feature js-oxc)
│   ├── bridge/    # 层2 — 脚本执行、I/O、管道、通配符
│   └── sdk/       # 层3 — 公共 API + 平台 FFI(JNI / C)
├── docs/          # 文档(API、命令、集成、插件、安全等)
├── tests/         # 集成测试
└── vendor/        # 内嵌 CPython 3.12 库
```

## 设计理念

- **轻量** — 纯 Rust 实现,不依赖 BusyBox,无 GPL 许可证问题
- **兼容** — 命令行为与 Linux 一致,AI Agent 无需额外训练
- **安全** — VFS 沙箱隔离,路径逃逸防护,命令超时控制,移动端单进程运行
- **跨平台** — 统一 API,Android/iOS/macOS/Linux 共享同一 Rust 核心
- **权限驱动** — 网络访问需宿主 App 授权,fastshell 不自行决策

## 许可证

Apache 2.0 © xiefujin (490021684@qq.com)