besh 0.1.0__tar.gz

besh-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.pytest_cache/
+.workbuddy/
+__pycache__/
+dist/

besh-0.1.0/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026-present cqian-cs <cqian.cs@qq.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

besh-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: besh
+Version: 0.1.0
+Summary: Beacon Shell：让 Agent 把计算任务交给闲置算力（手机 Termux / 云 IDE / 云 Notebook）
+Project-URL: Documentation, https://github.com/cqian-cs/besh#readme
+Project-URL: Issues, https://github.com/cqian-cs/besh/issues
+Project-URL: Source, https://github.com/cqian-cs/besh
+Author-email: cqian-cs <cqian.cs@qq.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: agent,beacon,rclone,remote,tmux,worker
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=22.1
+Requires-Dist: aiohttp>=3.8
+Requires-Dist: orjson>=3.6
+Requires-Dist: sqless>=5.0.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Beacon Shell (besh)
+
+**把闲置算力变成 AI Agent 可远程操作的工人。**
+
+闲置算力随处可见：手机 Termux、免费的云 IDE、云 Notebook……但它们大多没有公网 IP，没法通过 SSH 远程操作。
+
+besh 用一个"信标 + 工人"的架构解决这个问题：只要闲置终端能访问外网，就能反向连接信标、领取命令、回传结果——你（或你的 AI Agent）则可以像操作 tmux 一样操作散落在各处的机器。
+
+```mermaid
+flowchart TB
+    UR["人类"]
+    AG["AI Agent"]
+    RC["本地电脑<br>besh run -t 工人ID:窗口名 命令"]
+    BE["公网服务器<br>besh serve"]
+
+    UR -- CLI --> RC
+    UR -- Web --> BE
+    AG -- CLI --> RC -- API --> BE
+    AG -- MCP --> BE
+
+    BE <-- "轮询取命令 <br> 回传屏幕 / 结果" --> W1["闲置算力<br>besh worker 工人ID"]
+    BE <-- "轮询取命令 <br> 回传屏幕 / 结果" --> W2["闲置算力<br>besh worker 工人ID"]
+
+    W1 -.->|"rclone 定时备份"| R2[("对象存储<br>Cloudflare R2")]
+    W2 -.->|"rclone 定时备份"| R2
+
+    classDef purple fill:#ede9fe,stroke:#7c3aed,color:#1e293b
+    classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e293b
+    classDef green fill:#d1fae5,stroke:#059669,color:#1e293b
+    classDef amber fill:#fef3c7,stroke:#d97706,color:#1e293b
+
+    class RC,AG,UR purple
+    class BE blue
+    class W1,W2 green
+    class R2 amber
+```
+
+## 四个角色
+
+| 角色 | 运行位置 | 职责 |
+|------|----------|------|
+| 信标 | 有公网 IP 的服务器 | 中转命令、记录状态、提供 Web 界面与 MCP 接口 |
+| 工人 | 任意闲置终端（无公网 IP） | 轮询信标领命令，在 tmux 窗口里执行，定时备份工作目录 |
+| 遥控器 | 本地电脑 | 类似 tmux 的命令行，把 session 换成工人 ID，可同时操作多台 |
+| 对象存储 | Cloudflare R2 | 备份工人工作目录（工人是临时的，随时会释放） |
+
+## 安装
+
+```bash
+pip install besh
+```
+
+要求 Python ≥ 3.10。工人机器上还需要安装 [tmux](https://github.com/tmux/tmux)。
+
+## 快速开始
+
+### 1. 启动信标（云服务器）
+
+```bash
+export besh_secret=CHANGE_TO_YOUR_PASSWORD
+besh serve
+```
+
+启动时会生成自包含的 `besh_beacon.py`（主程序）和 `www/index.html`（Web 界面），数据存放在 `./db/`。默认监听 `12242` 端口，输出类似：
+
+```
+  工人连接 : export besh_url=http://<HOST>:12242?secret=xxx
+  浏览器   : http://<HOST>:12242/?secret=xxx
+  MCP      : http://<HOST>:12242/mcp  (Authorization: Bearer xxx)
+```
+
+### 2. 接入工人（闲置终端）
+
+```bash
+export besh_url=http://BEACON-HOST:12242?secret=CHANGE_TO_YOUR_PASSWORD
+besh worker WORKER_ID
+```
+
+- 会创建 `./WORKER_ID` 作为工作目录，后续所有命令都在这个目录里执行
+- 通过 tmux 启动 `besh_worker` 会话（创建窗口、执行命令）和 `besh_sync` 会话（定时把工作目录同步到对象存储）
+
+### 3. 远程操作（本地电脑）
+
+```bash
+export besh_url=http://BEACON-HOST:12242?secret=CHANGE_TO_YOUR_PASSWORD
+
+# 列出所有工人（ls / list-sessions / list-workers 等价）
+besh ls
+
+# 列出某工人的所有窗口
+besh list-windows -t WORKER_ID
+
+# 查看窗口内容（同 tmux capture-pane）
+besh capture-pane -t WORKER_ID:WINDOW_NAME -p -S -50
+
+# 发送按键（窗口不存在会自动创建）
+besh send-keys -t WORKER_ID:WINDOW_NAME "ls -l" Enter
+
+# 发送按键，-l 按字面处理（不展开变量）
+besh send-keys -t WORKER_ID:WINDOW_NAME -l 'echo "Hello $USER"'
+
+# 执行一条命令并打印输出（体验类似 ssh host cmd）
+besh run -t WORKER_ID "uname -a"
+
+# 跑长任务：先输入不等待，稍后等它执行完（窗口回到提示符）
+besh type -t WORKER_ID:WINDOW_NAME "python train.py"
+besh wait -t WORKER_ID:WINDOW_NAME
+```
+
+## 对象存储（Cloudflare R2）
+
+信标带宽贵、网速慢，不适合备份工作目录；[Cloudflare R2](https://developers.cloudflare.com/r2/) 免费 10GB 且网速快，所以用它。工人工作目录备份在 `cf:besh/YYYY-MM-DD/WORKER_ID/*`。
+
+1. 开通 Cloudflare R2，创建存储桶 `besh`
+2. 在信标与工人机器上安装 [rclone](https://rclone.org/install/)：
+
+   ```bash
+   sudo -v ; curl https://rclone.org/install.sh | sudo bash
+   ```
+
+3. 配置 rclone 环境变量访问 R2：
+
+   ```bash
+   export RCLONE_CONFIG_CF_TYPE=s3
+   export RCLONE_CONFIG_CF_PROVIDER=Cloudflare
+   export RCLONE_CONFIG_CF_ACCESS_KEY_ID=
+   export RCLONE_CONFIG_CF_SECRET_ACCESS_KEY=
+   export RCLONE_CONFIG_CF_ENDPOINT=
+   export RCLONE_CONFIG_CF_REGION=auto
+   ```
+
+配置好后，遥控器即可管理备份：
+
+```bash
+besh backup  -t WORKER_ID              # 立刻备份（不等定时任务）
+besh restore -t WORKER_ID              # 从最新备份恢复工作目录
+besh files  -t WORKER_ID               # 列出对象存储里的备份文件
+besh download / besh upload / besh rm  # 下载 / 上传 / 删除文件
+```
+
+## Web 操作界面
+
+浏览器打开 `http://BEACON-HOST:12242?secret=xxx`：
+
+- 每个工人的实时状态（主机名、工作目录、窗口列表、在线状态）
+- 完善的 WebShell：实时屏幕、输入框、`^C` / `^D` / `Tab` / `↑` / `↓` / `Esc` 按键助手
+- 基于对象存储的文件上传 / 下载 / 直链分享
+
+## AI Agent 接入
+
+besh 为 AI Agent 提供两条通道，任选其一：
+
+**MCP**（信标内置）：
+
+```bash
+besh mcp          # 打印 MCP 客户端配置
+besh mcp --write ~/.workbuddy/mcp.json   # 直接写入客户端配置
+```
+
+**CLI 技能**（把 besh 命令教给 Agent）：
+
+```bash
+besh skill        # 打印 SKILL.md
+besh skill --install ~/.workbuddy/skills/   # 安装为 Agent 技能
+```
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `besh serve` | 在当前目录启动信标 |
+| `besh worker ID` | 以工人身份接入信标 |
+| `besh ls` | 列出所有工人 |
+| `besh list-windows -t ID` | 列出工人的窗口 |
+| `besh capture-pane -t ID:WIN` | 查看窗口内容 |
+| `besh send-keys -t ID:WIN …` | 向窗口发送按键 |
+| `besh type -t ID:WIN TEXT` | 输入文本（可选回车），Agent 友好 |
+| `besh run -t ID:WIN CMD` | 执行命令并打印输出 |
+| `besh new-window` / `kill-window` | 新建 / 关闭窗口 |
+| `besh kill-worker -t ID` | 让工人退出（tmux 会话一并关闭） |
+| `besh wait -t ID:WIN` | 等待窗口回到提示符（命令执行完毕） |
+| `besh wait CMD_ID` | 等待某条异步命令的回执 |
+| `besh history` / `besh info` | 命令历史 / 工人详情 |
+| `besh files` / `download` / `upload` / `rm` | 管理对象存储里的文件 |
+| `besh backup` / `restore` | 备份 / 恢复工作目录 |
+| `besh mcp` / `besh skill` | 生成 MCP / Agent 技能配置 |
+
+环境变量：`besh_url`（信标地址）、`besh_secret`（密钥）。也可以用 `-u` / `--secret` 参数临时指定，或 `--json` 输出 JSON。
+
+## 可靠性设计
+
+- **命令不丢**：命令入队即落盘（sqlite）。信标重启后，pending 和已投递未回执的命令都会重新排队；工人侧用执行记录去重，最坏情况重复执行一次（at-least-once）。
+- **屏幕秒回**：工人定期把各窗口屏幕快照推给信标缓存，`capture-pane` 无需等待。
+- **投递超时重排**：命令投递后 120 秒无回执，自动重新排队（工人可能已重启）。
+- **安全模型**：单一密钥认证（信标侧）；工人本身处在容器 / 虚拟机内，不提供额外的安全隔离。
+
+## 实现细节
+
+1. 信标基于 [sqless](https://github.com/cqian-cs/sqless) 框架（简易单用户认证 + sqlite 数据库 + 函数转 API + 函数转 MCP）。`besh serve` 会在当前路径通过 `sqless --app besh_beacon.py` 生成服务端代码。
+2. 工人内部跑两个 tmux 会话：`besh_worker`（窗口与命令执行）和 `besh_sync`（定时 rclone 备份）。
+3. 遥控器客户端只依赖 Python 标准库。
+
+## 开发
+
+```bash
+git clone https://github.com/cqian-cs/besh
+cd besh
+pip install -e . --no-build-isolation
+pip install -e ".[test]"
+pytest
+```
+
+测试包含 55 个单元/集成测试；`tests/fake_worker.py` 提供不依赖 tmux 的假工人，可用于本地联调。
+
+## License
+
+MIT © [cqian-cs](https://github.com/cqian-cs)

besh-0.1.0/README.md

@@ -0,0 +1,217 @@
+# Beacon Shell (besh)
+
+**把闲置算力变成 AI Agent 可远程操作的工人。**
+
+闲置算力随处可见：手机 Termux、免费的云 IDE、云 Notebook……但它们大多没有公网 IP，没法通过 SSH 远程操作。
+
+besh 用一个"信标 + 工人"的架构解决这个问题：只要闲置终端能访问外网，就能反向连接信标、领取命令、回传结果——你（或你的 AI Agent）则可以像操作 tmux 一样操作散落在各处的机器。
+
+```mermaid
+flowchart TB
+    UR["人类"]
+    AG["AI Agent"]
+    RC["本地电脑<br>besh run -t 工人ID:窗口名 命令"]
+    BE["公网服务器<br>besh serve"]
+
+    UR -- CLI --> RC
+    UR -- Web --> BE
+    AG -- CLI --> RC -- API --> BE
+    AG -- MCP --> BE
+
+    BE <-- "轮询取命令 <br> 回传屏幕 / 结果" --> W1["闲置算力<br>besh worker 工人ID"]
+    BE <-- "轮询取命令 <br> 回传屏幕 / 结果" --> W2["闲置算力<br>besh worker 工人ID"]
+
+    W1 -.->|"rclone 定时备份"| R2[("对象存储<br>Cloudflare R2")]
+    W2 -.->|"rclone 定时备份"| R2
+
+    classDef purple fill:#ede9fe,stroke:#7c3aed,color:#1e293b
+    classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e293b
+    classDef green fill:#d1fae5,stroke:#059669,color:#1e293b
+    classDef amber fill:#fef3c7,stroke:#d97706,color:#1e293b
+
+    class RC,AG,UR purple
+    class BE blue
+    class W1,W2 green
+    class R2 amber
+```
+
+## 四个角色
+
+| 角色 | 运行位置 | 职责 |
+|------|----------|------|
+| 信标 | 有公网 IP 的服务器 | 中转命令、记录状态、提供 Web 界面与 MCP 接口 |
+| 工人 | 任意闲置终端（无公网 IP） | 轮询信标领命令，在 tmux 窗口里执行，定时备份工作目录 |
+| 遥控器 | 本地电脑 | 类似 tmux 的命令行，把 session 换成工人 ID，可同时操作多台 |
+| 对象存储 | Cloudflare R2 | 备份工人工作目录（工人是临时的，随时会释放） |
+
+## 安装
+
+```bash
+pip install besh
+```
+
+要求 Python ≥ 3.10。工人机器上还需要安装 [tmux](https://github.com/tmux/tmux)。
+
+## 快速开始
+
+### 1. 启动信标（云服务器）
+
+```bash
+export besh_secret=CHANGE_TO_YOUR_PASSWORD
+besh serve
+```
+
+启动时会生成自包含的 `besh_beacon.py`（主程序）和 `www/index.html`（Web 界面），数据存放在 `./db/`。默认监听 `12242` 端口，输出类似：
+
+```
+  工人连接 : export besh_url=http://<HOST>:12242?secret=xxx
+  浏览器   : http://<HOST>:12242/?secret=xxx
+  MCP      : http://<HOST>:12242/mcp  (Authorization: Bearer xxx)
+```
+
+### 2. 接入工人（闲置终端）
+
+```bash
+export besh_url=http://BEACON-HOST:12242?secret=CHANGE_TO_YOUR_PASSWORD
+besh worker WORKER_ID
+```
+
+- 会创建 `./WORKER_ID` 作为工作目录，后续所有命令都在这个目录里执行
+- 通过 tmux 启动 `besh_worker` 会话（创建窗口、执行命令）和 `besh_sync` 会话（定时把工作目录同步到对象存储）
+
+### 3. 远程操作（本地电脑）
+
+```bash
+export besh_url=http://BEACON-HOST:12242?secret=CHANGE_TO_YOUR_PASSWORD
+
+# 列出所有工人（ls / list-sessions / list-workers 等价）
+besh ls
+
+# 列出某工人的所有窗口
+besh list-windows -t WORKER_ID
+
+# 查看窗口内容（同 tmux capture-pane）
+besh capture-pane -t WORKER_ID:WINDOW_NAME -p -S -50
+
+# 发送按键（窗口不存在会自动创建）
+besh send-keys -t WORKER_ID:WINDOW_NAME "ls -l" Enter
+
+# 发送按键，-l 按字面处理（不展开变量）
+besh send-keys -t WORKER_ID:WINDOW_NAME -l 'echo "Hello $USER"'
+
+# 执行一条命令并打印输出（体验类似 ssh host cmd）
+besh run -t WORKER_ID "uname -a"
+
+# 跑长任务：先输入不等待，稍后等它执行完（窗口回到提示符）
+besh type -t WORKER_ID:WINDOW_NAME "python train.py"
+besh wait -t WORKER_ID:WINDOW_NAME
+```
+
+## 对象存储（Cloudflare R2）
+
+信标带宽贵、网速慢，不适合备份工作目录；[Cloudflare R2](https://developers.cloudflare.com/r2/) 免费 10GB 且网速快，所以用它。工人工作目录备份在 `cf:besh/YYYY-MM-DD/WORKER_ID/*`。
+
+1. 开通 Cloudflare R2，创建存储桶 `besh`
+2. 在信标与工人机器上安装 [rclone](https://rclone.org/install/)：
+
+   ```bash
+   sudo -v ; curl https://rclone.org/install.sh | sudo bash
+   ```
+
+3. 配置 rclone 环境变量访问 R2：
+
+   ```bash
+   export RCLONE_CONFIG_CF_TYPE=s3
+   export RCLONE_CONFIG_CF_PROVIDER=Cloudflare
+   export RCLONE_CONFIG_CF_ACCESS_KEY_ID=
+   export RCLONE_CONFIG_CF_SECRET_ACCESS_KEY=
+   export RCLONE_CONFIG_CF_ENDPOINT=
+   export RCLONE_CONFIG_CF_REGION=auto
+   ```
+
+配置好后，遥控器即可管理备份：
+
+```bash
+besh backup  -t WORKER_ID              # 立刻备份（不等定时任务）
+besh restore -t WORKER_ID              # 从最新备份恢复工作目录
+besh files  -t WORKER_ID               # 列出对象存储里的备份文件
+besh download / besh upload / besh rm  # 下载 / 上传 / 删除文件
+```
+
+## Web 操作界面
+
+浏览器打开 `http://BEACON-HOST:12242?secret=xxx`：
+
+- 每个工人的实时状态（主机名、工作目录、窗口列表、在线状态）
+- 完善的 WebShell：实时屏幕、输入框、`^C` / `^D` / `Tab` / `↑` / `↓` / `Esc` 按键助手
+- 基于对象存储的文件上传 / 下载 / 直链分享
+
+## AI Agent 接入
+
+besh 为 AI Agent 提供两条通道，任选其一：
+
+**MCP**（信标内置）：
+
+```bash
+besh mcp          # 打印 MCP 客户端配置
+besh mcp --write ~/.workbuddy/mcp.json   # 直接写入客户端配置
+```
+
+**CLI 技能**（把 besh 命令教给 Agent）：
+
+```bash
+besh skill        # 打印 SKILL.md
+besh skill --install ~/.workbuddy/skills/   # 安装为 Agent 技能
+```
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `besh serve` | 在当前目录启动信标 |
+| `besh worker ID` | 以工人身份接入信标 |
+| `besh ls` | 列出所有工人 |
+| `besh list-windows -t ID` | 列出工人的窗口 |
+| `besh capture-pane -t ID:WIN` | 查看窗口内容 |
+| `besh send-keys -t ID:WIN …` | 向窗口发送按键 |
+| `besh type -t ID:WIN TEXT` | 输入文本（可选回车），Agent 友好 |
+| `besh run -t ID:WIN CMD` | 执行命令并打印输出 |
+| `besh new-window` / `kill-window` | 新建 / 关闭窗口 |
+| `besh kill-worker -t ID` | 让工人退出（tmux 会话一并关闭） |
+| `besh wait -t ID:WIN` | 等待窗口回到提示符（命令执行完毕） |
+| `besh wait CMD_ID` | 等待某条异步命令的回执 |
+| `besh history` / `besh info` | 命令历史 / 工人详情 |
+| `besh files` / `download` / `upload` / `rm` | 管理对象存储里的文件 |
+| `besh backup` / `restore` | 备份 / 恢复工作目录 |
+| `besh mcp` / `besh skill` | 生成 MCP / Agent 技能配置 |
+
+环境变量：`besh_url`（信标地址）、`besh_secret`（密钥）。也可以用 `-u` / `--secret` 参数临时指定，或 `--json` 输出 JSON。
+
+## 可靠性设计
+
+- **命令不丢**：命令入队即落盘（sqlite）。信标重启后，pending 和已投递未回执的命令都会重新排队；工人侧用执行记录去重，最坏情况重复执行一次（at-least-once）。
+- **屏幕秒回**：工人定期把各窗口屏幕快照推给信标缓存，`capture-pane` 无需等待。
+- **投递超时重排**：命令投递后 120 秒无回执，自动重新排队（工人可能已重启）。
+- **安全模型**：单一密钥认证（信标侧）；工人本身处在容器 / 虚拟机内，不提供额外的安全隔离。
+
+## 实现细节
+
+1. 信标基于 [sqless](https://github.com/cqian-cs/sqless) 框架（简易单用户认证 + sqlite 数据库 + 函数转 API + 函数转 MCP）。`besh serve` 会在当前路径通过 `sqless --app besh_beacon.py` 生成服务端代码。
+2. 工人内部跑两个 tmux 会话：`besh_worker`（窗口与命令执行）和 `besh_sync`（定时 rclone 备份）。
+3. 遥控器客户端只依赖 Python 标准库。
+
+## 开发
+
+```bash
+git clone https://github.com/cqian-cs/besh
+cd besh
+pip install -e . --no-build-isolation
+pip install -e ".[test]"
+pytest
+```
+
+测试包含 55 个单元/集成测试；`tests/fake_worker.py` 提供不依赖 tmux 的假工人，可用于本地联调。
+
+## License
+
+MIT © [cqian-cs](https://github.com/cqian-cs)

besh-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "besh"
+dynamic = ["version"]
+description = "Beacon Shell：让 Agent 把计算任务交给闲置算力（手机 Termux / 云 IDE / 云 Notebook）"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["tmux", "remote", "agent", "beacon", "worker", "rclone"]
+authors = [
+  { name = "cqian-cs", email = "cqian.cs@qq.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+dependencies = [
+  "sqless>=5.0.1",
+  "aiohttp>=3.8",
+  "aiofiles>=22.1",
+  "orjson>=3.6",
+]
+
+[project.scripts]
+besh = "besh.cli:main"
+
+[project.urls]
+Documentation = "https://github.com/cqian-cs/besh#readme"
+Issues = "https://github.com/cqian-cs/besh/issues"
+Source = "https://github.com/cqian-cs/besh"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[tool.hatch.version]
+path = "src/besh/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/besh"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/besh", "tests", "README.md"]
+core-metadata-version = "2.4"
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/besh tests}"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+source_pkgs = ["besh", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/besh/__about__.py",
+]
+
+[tool.coverage.paths]
+besh = ["src/besh", "*/besh/src/besh"]
+tests = ["tests", "*/besh/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

besh-0.1.0/src/besh/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present cqian-cs <cqian.cs@qq.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.0"

besh-0.1.0/src/besh/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026-present cqian-cs <cqian.cs@qq.com>
+#
+# SPDX-License-Identifier: MIT
+"""besh - Beacon Shell.
+
+把闲置算力（手机 Termux、免费云 IDE、云 NoteBook）变成可远程操作的工人。
+
+四个角色：
+
+* 信标（beacon）—— 有公网 IP 的服务器，中转命令、记录状态、提供 Web 界面与 MCP。
+* 工人（worker）—— 任意终端，向信标轮询命令并交给 tmux 执行。
+* 遥控器（controller）—— 本地电脑，用 tmux 风格的命令行操作多个工人。
+* 对象存储（R2）—— 备份工人的工作目录。
+"""
+
+from .__about__ import __version__
+
+__all__ = ["__version__"]

besh-0.1.0/src/besh/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026-present cqian-cs <cqian.cs@qq.com>
+#
+# SPDX-License-Identifier: MIT
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())