# rbot

**Repository Path**: cash_soldier_admin/rbot

## Basic Information

- **Project Name**: rbot
- **Description**: rbot 是一个受规则约束的专用 AI Agent，用 Rust 实现。区别于通用 Agent，rbot 通过配置文件（rbot.json）定义工具、规则和 LLM 配置，通过 Shell Hook 脚本在 Agent 执行每个环节进行拦截、校验和改写。
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rbot — 工业级 Agent 底座框架

[![License](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

> rbot 是**工业级 Agent 底座**，不是通用 AI Agent 框架。它以「**会话内串行 + 会话间受限并发**」（默认 4，决策 110）为架构主张，
> 只实现与业务无关的必要能力，为特定业务领域提供可嵌入、安全、可审计、数据完整记录的自动化执行通道。

## 项目定位与设计方向

1. **rbotd = 工业级 Agent 底座**：只实现必要功能、与业务无关；**数据完整性记录是底线**（对话/任务/子任务/观测全链路不丢）。动态策略（并发上限、超时等）由 **LLM 与调用者按任务自主决定**，不做底座配置项——底座只提供机制，业务决策交给上层。
2. **www = rbotd 基础配置与管理前端**：承担配置、实时交互接口、基础管理、可观察可审计数据前端；管理功能追求**方便直观**；**插件体系是底座的自扩展能力**，持续加强（分步计划，见下文）。
3. **当前状态**：rbotd + www 已实现**最基础的工业级 Agent 行为能力**——基础未扩展形态**基本可投入使用发布**。
4. **android-workspace = 安卓封装层**：以 **proot 沙箱 + 单一 APK** 封装 rbotd + www，实现安卓上便捷的安装/配置/使用；内置**宿主 MCP 桥**（127.0.0.1:9905）把宿主原生能力（公共存储文件、内置浏览器子窗口、应用控制、电量/剪贴板等系统能力、受限 shell）开放给沙箱内 rbotd，为**工业级生产节点的超级终端**夯实能力。
5. **业务定制在后**：知识库管理、资料管理、质量库管理等**工业企业最难管理的数据电子化**，将作为专项应用定制开发；当前自带的文档内容管理技能**只是示范**，不是独立产品形态。
6. **PC 级个人助手扩展**：线上 SKILLS、插件市场等扩展能力，在 www 基础上（或 rbot-work）定制开发——www 已实现协议交互等基础能力，其它前端应用在其上扩展即可，届时再从产品设计角度打磨用户体验与功能多样性。

## 产品矩阵

```
                    ┌──────────────────────────────────────────┐
                    │           rbotd（工业级 Agent 底座）       │
                    │  多会话（会话内串行/间并发）+ 任务/子任务   │
                    │  安全硬约束 · 全链路可观测 · 数据完整记录   │
                    └───────────────┬──────────────────────────┘
                                    │
              ┌─────────────────────┼───────────────────────┐
              ▼                     ▼                       ▼
   ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────────┐
   │ www 基础配置前端   │  │ android-workspace│  │ 业务定制应用（后期）     │
   │ 配置/交互/管理/    │  │ proot 沙箱+APK   │  │ 知识库/资料/质量库       │
   │ 可观察可审计前端   │  │ 宿主MCP桥增强    │  │ 数据电子化专项          │
   │ 插件=自扩展能力    │  └──────────────────┘  └────────────────────────┘
   └──────────────────┘
        │
        └── PC 个人助手扩展（rbot-work / 线上 SKILLS / 插件市场，定制开发）
```

## 架构

```
rbotd (TCP :9902)
  │
  ├── rbot (终端客户端)
  ├── rbot-feishu (内嵌 rbotd via rbot-main)
  ├── rbot-channel (多通道进程，连接外部 rbotd)
  ├── www (零构建多页面管理前端，独立子仓库 rbot-www)
  └── other apps
```

- rbot-feishu **内嵌 rbotd**（通过 `rbot-main` crate），单进程运行
- rbot-channel **连接外部 rbotd**，一条 WS 承载多种 IM 通道（当前接入飞书 / 微信 / 企业微信 / Telegram；框架见 `crates/rbot-channel-core`）
- 其他客户端通过 WebSocket 连接 rbotd，按消息携带的 `session_id` 路由/过滤对应会话（决策 72/110）
- www 前端为独立子仓库 [rbot-www](https://gitee.com/cash_soldier_admin/rbot-www.git)（git submodule；**v0.2.26+ 编译期内嵌进 rbotd 二进制**，无 `--www-dir` 即内置 Web 管理端；`--www-dir` 外部目录优先，支持安卓沙箱 `/usr/local/rbotd/www` 覆写热升级；`--no-www` 完全关闭）

## 相关仓库

rbot 采用「主仓库 + 扩展仓库」组织，扩展能力均由独立仓库承载，可单独克隆/引用：

| 仓库 | 说明 | 地址 |
|------|------|------|
| **rbot-www** | www 基础管理前端（git submodule，v0.2.26+ 内嵌进 rbotd） | https://gitee.com/cash_soldier_admin/rbot-www.git |
| **rbot-android** | 安卓扩展应用：`rbot-android-desktop`（平板 WebView 壳）+ `rbot-android-workspace`（PRoot 沙箱 + 单一 APK，宿主 MCP 桥 + 内置浏览器子窗口） | https://gitee.com/cash_soldier_admin/rbot-android.git |
| **rbot-extensions** | Web 扩展应用（rbot-desktop Electron GUI、rbot-work 工作台、rbot-obsidian、rbot-gateway 等；观测仪表盘前端已迁移至此） | https://gitee.com/cash_soldier_admin/rbot-extensions.git |
| **rbot-plugins** | 插件仓库（集中存放插件 manifest + 静态代码，供 rbotd 智能体自然语言安装） | https://gitee.com/cash_soldier_admin/rbot-plugins.git |
| **rbot-skills** | 技能仓库（集中存放技能 SKILL.md + 脚本，供 rbotd 下载拷贝使用） | https://gitee.com/cash_soldier_admin/rbot-skills.git |

> 本仓库为**底座主仓库**（核心三件套 rbot / rbotd / rbot-feishu + 支撑 crate）；其余扩展应用与分发仓库均在上表独立维护。

## 与市场流行 Agent 对比

> 说明：不与 **Agent 开发框架**（LangChain / AutoGen / Dify 等）对比——框架是给开发者搭积木的中间件，定位不同；
> 与**市场上正在被使用的 Agent 产品**对比：`opencode`（开源 AI 编程代理）、`openclaw`（开源个人/团队助理）、
> `hermes-agent`（自进化个人 AI）、`OpenMinis`（端侧私有移动 AI），以及三大厂入口产品（腾讯 WorkBuddy /
> 字节豆包工作 / 阿里千问办公，仅简要比对）。

### 与开源 Agent 产品对比

| 维度 | **rbotd（工业级 Agent 底座）** | **opencode**（AI 编程代理） | **openclaw**（个人/团队助理） | **hermes-agent**（自进化个人 AI） | **OpenMinis**（端侧私有移动 AI） |
|------|------|------|------|------|------|
| **定位** | 工业级 Agent **底座**：只做必要功能、业务无关、可嵌入 | AI **coding agent**：终端内编程会话 | 个人/团队助理：多设备多通道 | 自进化个人 AI | 端侧私有移动 AI |
| **技术栈** | **Rust 单二进制**，14 crate 分层，axum | TypeScript + **Bun**，Effect + OpenTUI | TypeScript + **Node.js**，SQLite + TypeBox | **Python** gateway daemon | **Swift / Kotlin** 原生 |
| **架构形态** | 常驻守护（TCP :9902）+ WS/HTTP + 零构建 Web 管理端 | TUI / `run` 交互进程 + 无头 `serve`，**随会话生灭、无常驻 daemon** | **常驻 Gateway daemon**（WS RPC + HTTP + Control UI）+ CLI/TUI/Web/原生 App | 常驻 gateway daemon + 多平台通道 | 移动 App + iSH/PRoot Alpine 沙箱 |
| **部署方式** | **单静态二进制 scp 即用**，交叉编译 Linux/macOS/Windows，proot 沙箱 APK 封装 | npm / brew / curl 安装，Electron 桌面版（BETA） | npm 全局，launchd/systemd/schtasks daemon，Docker | Python 环境 | App Store / 应用市场 |
| **数据与隐私** | **全本地 `~/.rbot/`**，无账号、可离线，观测脱敏写入 | XDG 本地存储；`share` 上传 **opt-in** | 本地 `~/.openclaw/`；默认仅版本检查遥测 | 本地 `~/.hermes`（SQLite+FTS5），默认不上传 | **设备端 Keychain**，iCloud 可选 |
| **自动化与定时** | **原生 cron 调度 + 用户 `/task` + SubAgent 子任务（串行/并行/中止/结果池）四通道** | **无 cron**，仅运行内后台作业 | cron 定时 + standing intents + auto-reply + boards | 后台自进化循环 | 端侧离线任务 |
| **记忆系统** | 长期记忆 memory.md + **上下文镜像 mirror.json（交互级 checkpoint）** | 会话回放（SQLite）+ git 工作区 | 明文 Markdown（USER.md/MEMORY.md/日记）+ dreaming 后台整合 | 自进化记忆 | 端侧私密存储 |
| **可观测审计** | **一等公民**：sessions/events/metrics/token_usage/messages 五表 + 审计导出 + 180 天归档 | 事件/调试 trace | 会话记录 + OTEL/Prometheus + security audit | 有限 | 有限 |
| **嵌入与扩展** | **底座可嵌入**（rbot-feishu / rbot-work / 任意上层）+ 技能 / Hook 12 节点 / 规则引擎 / 插件 / MCP | 插件 / .opencode、MCP、ACP、skill | 52 内置 skills + 插件市场 + plugin SDK，48 通道（含飞书） | 多平台通道 | 22 个原生离线处理器 |
| **安全体系** | 三层硬约束（路径沙箱 + 权限级别边界 + 规则引擎 / Hook） | agent 级权限系统 | trusted gateway 信任边界（**非对抗性多租户**） | 本地信任 | 沙箱隔离 + 细粒度权限 |
| **开源许可** | **MIT** | MIT | MIT | MIT | **GPLv3**（强 copyleft） |
| **目标用户** | 政企 / 自动化集成 / 嵌入场景 | 开发者（终端编程） | 个人 / 小团队 | 个人 | 个人（移动端） |

**一句话差异**：opencode 把「人在终端里的一次编程会话」做到极致；openclaw 把「常驻在设备与聊天里的助理」做到极致；
Hermes / OpenMinis 是面向个人的完整 AI 产品；而 rbotd 是**确定性任务驱动的长期自动化底座**——对话只是入口之一，
**调度、子任务编排、可观测审计才是本体**（以任务 DAG + 审计日志为核心，而非以会话为核心）。

### 与三大厂入口产品简要对比（隐私 / 本地优先角度）

腾讯 **WorkBuddy**（桌面 AI 工作台 / Agent 入口，配合 CodeBuddy，免部署、自动化重复任务）、字节 **豆包工作**、
阿里 **千问办公** 是「大厂 AI 入口大战」的代表——**云账号体系、功能全、开箱即用**，但数据在云端、**非本地优先**、
闭源、不可嵌入、不可自审计。rbotd 的差异化角度恰好相反：

| 维度 | 三大厂入口产品 | **rbotd** |
|------|----------------|----------|
| 形态 | 云账号 + 客户端/网页，**功能全但数据在云端** | **本地单机底座**，数据不出机 |
| 账号 | 必须注册/登录 | **无账号**，初始化即用，可离线 |
| 可嵌入 | 独立产品，不可嵌入业务系统 | **可嵌入** rbot-feishu / rbot-work / 任意上层应用 |
| 审计 | 平台侧黑盒 | **全链路可观测审计**，数据自己掌握 |
| 定制 | 闭源，不可改 | 开源 MIT，业务经 skill / 插件 / Hook 定制 |

### 结论：rbotd 的优势与为什么自研而非二开

**rbotd 相对这些产品形态的核心优势**：

1. **单二进制零依赖** — Rust 静态二进制，scp 即用、毫秒级启动、内存占用小；opencode / openclaw / Hermes 依赖 Node / Bun / Python 运行时，安装体积、内存与依赖面都大一个量级。
2. **本地优先、数据不出机** — 全本地 `~/.rbot/`、无账号、可离线；三大厂产品数据在云端，这是工业 / 政企场景的底线差异。
3. **自动化即本体** — cron 调度 + 单一任务 + SubAgent 子任务（串行 / 并行 / 中止 / 结果池镜像 / 自定义超时）四通道，无人值守能力完整；opencode 无调度，openclaw 的调度服务于「对话」而非「任务」。
4. **确定性任务编排 + 全链路审计为一等公民** — 子任务结果池镜像、父子 trace 追溯、五表观测 + 审计导出 + 180 天归档；产品型 Agent 的审计多为辅助功能而非设计底线。
5. **可嵌入、业务无关** — 底座不预设业务，经技能 / 插件 / Hook 12 节点 / MCP 扩展；产品型 Agent 自带完整产品形态与主张，嵌入 = 改造其产品。

**为什么自研独立 Agent 而非二开（fork / 二次开发）这些产品**：

- **opencode**：场景限定「终端编程会话」，无常驻、无调度、无无人值守，且迭代极快、breaking change 频繁，仓库还混有云侧商业化代码；二开 = 绑定其「编程会话」产品形态与 JS 技术栈，与底座定位相悖。
- **openclaw**：个人助理产品，Node 运行时依赖重、配置复杂度高（openclaw.json + .env + gateway 网络 / 沙箱 / 通道）、信任边界窄（非对抗性多租户）；二开 = 继承其「助理」产品主张，而底座所需的数据完整性、确定性编排、审计需推倒重构。
- **Hermes / OpenMinis**：面向个人 / 移动端的完整产品，Python / Swift / Kotlin 技术栈与个人设备部署形态，与工业嵌入、政企自托管的底座场景不匹配；OpenMinis 为 **GPLv3** 强 copyleft，作为可嵌入底座的二次开发会传染闭源下游，与 MIT 的开放嵌入定位相悖。
- **三大厂产品**：闭源云服务，无二开可能，且「数据不出机」的底线要求即不满足。

**自研的本质**：二开 = 继承别人的产品形态、技术栈与技术债务，受其架构主张约束；自研底座 = 只做必要功能、业务无关、
**数据完整性记录是底线**、稳定压倒一切——把「能嵌入任何业务系统的自动化执行通道」做到极致，而不是把某一个 Agent
产品形态做到极致。借鉴方面，opencode 的工具链 / 会话工程、openclaw 的常驻模型 / 通道接入 / cron 设计均有参考价值，
但**任务执行层独立于对话存在**——以任务 DAG + 审计日志为核心而非以会话为核心，是 rbotd 与所有产品型 Agent 最本质的架构分野。

## 消息流转

rbotd 采用**持久化多会话 + 无过滤广播**模型（模型 D + 会话级并发门控，决策 72/110）：每条消息携带 `session_id`，服务端按会话隔离历史/压缩态/取消态；所有 WebSocket 连接收到同一广播流，客户端各自按 `session_id` 过滤渲染当前会话。会话内严格串行、会话间受限并发（默认 4）。详见 [rbot-messages.md](./rbot-messages.md)。

## 当前能力状态（可发布基线）

**rbotd + www 已具备最基础的工业级 Agent 行为能力**，基础未扩展形态可投入使用：

| 维度 | 已实现 |
|---|---|
| 任务执行 | 主任务 + 定时任务（cron 调度/重叠强杀）+ 用户单一任务（/task）+ **SubAgent 子任务**（主任务内部串行/并行创建、结果回收、中止、结果池镜像、自定义超时）四通道 |
| 数据完整性 | 交互级 checkpoint（提交 LLM 前保存，崩溃最多丢一次工具执行）、上下文镜像、子任务结果池镜像、全链路观测落库 |
| 安全 | 三层硬约束（路径沙箱/权限级别边界/规则引擎 + 12 节点 Hook）、入参脱敏、越权审查 |
| 可观测 | sessions/events/metrics/token_usage/messages 五表 + 完整查询 API + 审计导出 |
| www 管理 | 对话/插件/定时/工具（技能/MCP/外部工具）/Hook/观测审计/配置 + 系统信息 + 统一交互组件（Rbot.dialogs/浮动对话窗/目标选择弹窗） |

## 宿主环境能力与限制

rbotd 是纯本地守护进程（Rust 单二进制），**本体不依赖图形界面**（www 管理端经浏览器访问，可在任意机器）。但 **LLM 经 exec 工具能做什么、Hook 脚本怎么写、系统信息多完整**，随宿主环境而变：

| 能力 | **Linux 桌面** | **macOS 桌面** | **Windows 原生 exe** | **Linux 无头服务器** | **Android proot+Alpine** |
|---|---|---|---|---|---|
| **命令生态（exec）** | ✅ 完整 bash | ✅ 完整 bash | ✅ 系统 cmd（`cmd /c`：`&&`/`|`/`>` 可用、重定向到 `NUL`；无 grep/sed/awk/head/tail/ls，需要 PowerShell 时显式 `powershell -Command "..."`） | ✅ 完整 bash | ⚠️ Alpine busybox（apk 可装包） |
| **Hook 脚本** | ✅ .sh | ✅ .sh | ⚠️ 需 .ps1/.cmd/.bat（或 Git Bash 跑 .sh） | ✅ .sh | ✅ .sh（Alpine sh） |
| **定时/子任务/观测/记忆/审计** | ✅ | ✅ | ✅ | ✅ | ✅（纯 Rust 全可用） |
| **无头浏览器（网页渲染/截图）** | ⚠️ 需自装 chromium | ⚠️ 需自装 | ⚠️ 需自装 | ⚠️ 需自装（无 DISPLAY 不可渲染验证） | ⚠️ **经宿主内置浏览器子窗口（MCP `browser_*`，需工作台前台）**：开页/执行 JS/截图/取 HTML/触摸/下载 |
| **GUI 集成（打开桌面应用/剪贴板/截图）** | ✅ | ✅ | ✅ | ❌ 无 DISPLAY | ⚠️ 经宿主 MCP：启动应用（`app_*`）、剪贴板/音量/亮度/Toast（`system_*`）；截图限浏览器子窗口 |
| **访问宿主文件系统** | ✅ | ✅ | ✅ | ✅ | ⚠️ **经宿主 MCP `file_*` 读写公共存储**（`/storage/emulated/0`，需「所有文件访问」授权）+ 数据根；沙箱内仍只见虚拟根 |
| **系统信息完整度** | ✅ | ✅ | ⚠️ 真实 cpu/mem/disk/网卡 IP（sysinfo 枚举），但内核名通用（`windows x86_64`） | ✅ | ⚠️ 沙箱 /proc 受限，但宿主 `system_status` 补电量/屏幕/内存/存储/网络 |
| **中文编码处理** | ✅ UTF-8 | ✅ UTF-8 | ⚠️ 输出 GBK/UTF-16LE，rbotd 自动识别解码，LLM 无感知 | ✅ UTF-8 | ⚠️ 视容器 locale |
| **常驻服务** | ✅ systemd | ✅ launchd | ⚠️ 需 Task Scheduler / NSSM 包装 | ✅ systemd | ⚠️ 生命周期受宿主管控 |
| **进程树清理** | ✅ 进程组 | ✅ 进程组 | ⚠️ taskkill 补杀（无精确进程组语义） | ✅ | ⚠️ 受限 |
| **推荐度** | ⭐⭐⭐ 最佳 | ⭐⭐⭐ 最佳 | ⭐⭐ 可用 | ⭐⭐ 无人值守 | ⭐⭐ 可用（宿主 MCP 增强，仍受限） |

### Android proot + Alpine 沙箱（演示/受限环境，宿主 MCP 桥增强）

workspace 应用内建**宿主 MCP 服务器**（`127.0.0.1:9905`，HTTP POST JSON-RPC，协议对齐 `crates/rbot-mcp`），沙箱与宿主共享 loopback（PRoot 不建网络命名空间），沙箱内 rbotd 以 `rbot.json` 配置 `{"transport":"http","url":"http://127.0.0.1:9905/mcp"}` 直连，把宿主原生能力以工具开放给 LLM：

- ✅ **宿主文件读写**（MCP `file_*`，9 个）：读写**公共存储** `/storage/emulated/0`（照片 DCIM/Pictures、文档 Documents/Download 等，需「所有文件访问」授权）+ **数据根**（相对路径=宿主数据根 `/storage/emulated/0/rbot/data`，与沙箱 rbotd 共享）；安全边界=限定公共存储内，禁止系统分区、防穿越
- ✅ **内置浏览器子窗口**（MCP `browser_*`，16 个）：开/关/导航/返回/前进/刷新/**执行 JS**/取 HTML/取文本/触摸/信息/截图/等待加载/Cookie 读写/下载；需**工作台（WorkActivity）在前台**（否则提示「浏览器窗口未挂载」）
- ✅ **宿主应用管理**（MCP `app_*`，5 个）：install / launch / list / info / uninstall
- ✅ **宿主系统控制**（MCP `system_*`，9 个）：status（电量/屏幕/内存/存储/网络）/ screen_on / sleep / volume / brightness / toast / clipboard
- ⚠️ **受限 shell**（MCP `shell_*`，2 个）：`shell_exec` / `shell_getprop`——宿主是无 root 普通应用，经 `Runtime.exec` 执行 app 权限内命令（sh / 只读系统属性等，「类 adb shell」形态），不可执行特权命令（写 setprop、包管理强操作）
- ⚠️ **宿主信息 + 沙箱日志**（MCP `host_*`，2 个）：`host_info`（设备/数据根/授权/MCP 状态）、`host_log`（沙箱启动日志）

沙箱内不受 MCP 桥影响的部分（仍受限）：

- ❌ **沙箱内无头浏览器不可用**：proot 沙箱无 GPU/渲染能力，chromium 等无法运行——网页抓取/截图类任务改用宿主内置浏览器子窗口（`browser_*`）
- ❌ **沙箱内不能直接访问安卓系统目录**：沙箱进程仅见虚拟根目录；`/sdcard`、应用私有数据等宿主机目录仅能经宿主 `file_*` 工具访问
- ⚠️ **命令生态为 Alpine busybox**（`apk` 可安装包），非完整 bash；hook 用 .sh 可运行
- ⚠️ **系统信息部分受限**（沙箱侧）：/proc 部分字段屏蔽（CapEff/Seccomp/NoNewPrivs 沙箱检测仍可用，www 系统信息页按容器适配）；宿主电量/网络/存储等经 `system_status` 补充
- ⚠️ **无 systemd / Docker / 硬件访问**（相机、GPS、传感器等）
- ✅ 定时任务、SubAgent 子任务、观测审计、记忆、www 管理端**全部可用**（纯 Rust，不受沙箱影响）
- 定位：**工业级生产节点的超级终端雏形**（见产品矩阵），沙箱内能力与宿主原生能力**分层叠加**——完整沙箱 bash 生态请用桌面/服务器环境

### Windows 原生 exe（详见 [README-rbotd.md](./README-rbotd.md#windows-部署原生-exe--wsl2--docker)）

- ⚠️ **exec 走系统 cmd（`cmd /c`）**：`&&`/`|`/`>` 与重定向到 `NUL` 可用，与 sh 写法接近（需 PowerShell 时显式 `powershell -Command "..."`）；但无 `grep/sed/awk/head/tail/ls`（用 `findstr`/`type`/`dir`）；同一命令字符串与 Linux 行为可能不同
- ⚠️ **Hook**：`.sh` 脚本需改写为 `.ps1`（.cmd/.bat 原生支持）；安装 Git Bash 可跑 .sh
- ⚠️ **进程树清理**：超时/取消用 `taskkill /F /T` 补杀（加 `CREATE_NO_WINDOW`，不再闪黑窗），无 unix 进程组精确语义（`cmd /c` 派生孙进程可能遗留）；另有 **Job Object 兜底**：rbotd 启动即把自身加入设了 `KILL_ON_JOB_CLOSE` 的 Job Object，rbotd 被「结束任务」/崩溃时子进程树由系统回收（见 AGENTS.md 决策 34）
- ⚠️ **系统信息**：cpu/memory/disk 真实（sysinfo），内核名/架构为通用值（`windows`/`x86_64`）
- ✅ 定时任务、SubAgent、观测审计、记忆、内嵌 www、搜索（纯 Rust）全部可用
- 💡 需要完整 bash 生态（.sh Hook、bash 语法命令）时，用 **WSL2 或 Docker** 运行（同文档三方案）

### Linux 无图形界面（无头服务器，无人值守）

- ✅ **全部守护能力完整**：定时任务、SubAgent、观测审计、HTTP/WS API、www 管理端（浏览器在任意机器访问）——适合长期无人值守
- ❌ **无 DISPLAY**：GUI 应用集成不可用（打开桌面应用、桌面截图、剪贴板等 exec 类能力）
- ⚠️ **无头浏览器**：需自装 `chromium --headless` 类方案，且无法做可视化渲染验证
- 💡 纯服务端自动化场景（定时采集、数据管道、飞书 Bot）无任何缺失——这是 rbotd 的主要目标场景

### 最佳环境

**Linux / macOS 图形界面桌面**：完整 bash 生态 + Hook .sh + GUI 集成 + 完整系统信息 + 本地浏览器管理 www，能力无缺失。

## 可观测仪表盘

rbotd 内建可观测层：每个任务入口生成服务端 trace_id（ULID），任务 / 事件 / 指标（token、Hook、安全拦截、进程健康）写入 `~/.rbot/agents/{name}/rbot.sqlite`，经 `/observability/*` 查询 API 对外暴露。观测仪表盘前端随扩展应用迁移到 `rbot-extensions` 仓库。

设计文档与全部决策见 [rbot-observability.md](./rbot-observability.md)。

## 各 APP 文档

| 应用 | 文档 | 说明 |
|------|------|------|
| **rbotd** | [README-rbotd.md](./README-rbotd.md) | 核心守护服务：部署、配置、WS 协议、HTTP API、安全体系、Hook 系统、规则引擎、定时任务、技能系统、上下文管理、可观测 API |
| **HTTP API** | [rbot-api.md](./rbot-api.md) | rbotd HTTP 接口唯一权威文档：全部端点的认证、参数、响应与错误码 |
| **rbot-feishu** | [README-feishu.md](./README-feishu.md) | 飞书 Bot 通道：嵌入式 rbotd、消息处理、错误码、限速、诊断工具（确认卡片已随决策 29 停用） |
| **rbot-channel** | [README-channel.md](./README-channel.md) | 多通道进程：连接外部 rbotd，一条 WS 按 `session.bot` demux 分发（框架 `rbot-channel-core`） |
| **rbot-wecom** | [README-wecom.md](./README-wecom.md) | 企业微信通道：智能机器人 WebSocket 长连接（BotID + Secret，无需公网回调） |
| **rbot-telegram** | [README-telegram.md](./README-telegram.md) | Telegram 通道：Bot API 长轮询（`getUpdates`，无需公网回调） |
| **rbot-weixin** | [README-weixin.md](./README-weixin.md) | 个人微信通道：iLink 长轮询（扫码登录，无需公网 IP；有账号风险，见文档） |
| **可观测设计** | [rbot-observability.md](./rbot-observability.md) | 可观测层唯一权威设计文档（crate 与内部开发） |

## 快速开始

```bash
# 编译全部
cargo build --workspace --release

# 安装到 PATH
cargo install --path apps/rbotd
cargo install --path apps/rbot

# 初始化 Agent
rbotd --init

# 编辑 ~/.rbot/agents/default/rbot.json 配置 LLM

# 启动核心服务
rbotd

# 发送消息
rbot -m "你好"
```

详见 [README-rbotd.md](./README-rbotd.md#快速开始)。

## 交叉编译

```bash
# Linux（Docker）
./scripts/macos_build_docker_linux.sh [x86_64|aarch64]

# macOS
./scripts/macos_build_macos.sh [x86_64|aarch64]

# Windows（Docker）
./scripts/macos_build_docker_windows.sh [x86_64|aarch64]
```

产物分类输出到 `target/release-{platform}/`。

## 开发命令

```bash
# 类型检查
cargo check --workspace

# Lint
cargo clippy --workspace

# 格式化
cargo fmt --workspace

# 测试
cargo test --workspace

# 带日志启动
RUST_LOG=debug cargo run --bin rbotd
```

## 设计原则

1. **层间分离** — LLM 调用、Agent Loop、工具、输入通道互不了解
2. **每环节可拦截** — Hook Pipeline 贯穿全部 14 个生命周期节点
3. **受规则约束** — 规则引擎强制行为边界，非提示词软约束
4. **配置驱动** — 所有工具、规则、LLM 配置集中在 `rbot.json`
5. **多 Agent 隔离** — 每个 rbotd 对应独立工作目录，通过 `--name` 区分
6. **安全可审计** — 路径沙箱 + 边界控制 + 规则引擎 + Hook 拦截，三层防护

## 开发方向与分步计划

按项目定位分阶段推进：**先底座必要功能与数据完整 → 再管理前端易用与插件自扩展 → 后安卓封装**，当前代码即为阶段性完成标志。
动态策略（并发/超时）一律由 LLM 与调用者自主决定，底座不引入业务配置。

### 阶段一：底座核心 + www 基础管理（✅ 已达成，可发布基线）

- [x] 多会话（持久化隔离 + 会话内串行/间并发，决策 110）+ 多任务四通道（主任务/定时/单一任务/SubAgent）
- [x] 数据完整性：交互级 checkpoint、镜像、子任务结果池、观测五表
- [x] www 全管理面（对话/插件/定时/工具/Hook/观测/配置）+ 系统信息
- [x] www 独立子仓库（安卓热升级）+ 缓存根治 + 统一交互组件（Rbot.dialogs）

### 阶段二：观测闭环 + www 插件自扩展（✅ 已达成）

**P0 — SubAgent 观测闭环**（让刚建的任务编排能力「看得见、可追溯」）✅：
- [x] `parent_trace_id` 暴露到 sessions 查询与事件 payload（父子任务审计追溯）
- [x] www 子任务列表增强：主任务发起的子任务 + 状态/耗时/结果/中止按钮

**P1 — www 插件自扩展能力加强**（✅ 已达成：见 [插件开发指南](./rbot-plugins.md)）：
- [x] 插件生命周期管理（启用=加入菜单/停用=移出、修复、删除；manifest 元数据与菜单注入已支持）
- [x] 插件四路径创建：新建向导（四模板脚手架）/ zip 导入（zip-slip 防护）/ 智能创建（plugin-dev 技能 + Agent 生成）/ 手动
- [x] 插件设置系统（manifest.settings 声明 → `PUT /api/plugins/{id}/settings` → 插件内 Rbot.plugin.getSettings；无 UI 表单，决策 128）
- [x] manifest 可视化编辑 + 校验 issues 提示 + 插件日志（`log.jsonl`，经 `GET /api/plugins/{id}/log` 读取）
- [x] 插件开发文档与脚手架（[rbot-plugins.md](./rbot-plugins.md) + 内置 plugin-dev 技能；新插件使用 DS-1 `.ui-*` + components.css）

### 阶段三：android-workspace 超级终端化

- [x] proot 沙箱固化（rbotd + www 一体化，单一 APK 安装即用）
- [x] 系统信息页适配安卓容器（沙箱探针 /proc 受限字段 + 容器化展示）
- [x] 宿主 MCP 桥（127.0.0.1:9905，HTTP JSON-RPC）：`file_*` 宿主公共存储读写 / `browser_*` 内置浏览器子窗口（替代无头浏览器）/ `app_*` 应用管理 / `system_*` 电量·屏幕·音量·剪贴板 / `shell_*` 受限命令 / `host_*` 设备与日志

### 明确不做（设计红线）

- ~~**多会话**~~（**已支持**：决策 110 落地持久化多会话 + 会话级并发门控；「高并发通用对话服务」仍为红线——并发上限 4、会话内串行）
- **底座业务配置化**（并发/超时等动态策略由 LLM 与调用者按任务自主决定；`max_concurrent_sessions` 是可运维的容量旋钮，非业务策略）
- **agent 核心工具循环并发化**（所有工具并行执行 = 文件/状态竞争风险，违背稳定优先）
- **业务逻辑进入底座**（知识库/资料/质量库等一律经 skill/插件/上层应用实现）

## FAQ

**端口被占用：**
```bash
lsof -i :9902
kill -9 $(lsof -t -i :9902)
```

**客户端找不到 rbotd：** 运行 `cargo install --path apps/rbotd`。

**清理记忆：** 编辑 `~/.rbot/agents/{name}/memory/memory.md` 或删除旧的日期文件。

各 APP 的专属 FAQ 详见对应文档。

## 参与贡献

我们欢迎任何形式的贡献——Bug 报告、功能建议、代码提交、文档改进均可。

- **问题反馈**：在 [Gitee Issues](https://gitee.com/cash_soldier_admin/rbot/issues) 提交
- **代码提交**：Fork 后提交 Pull Request，参考 [CONTRIBUTING.md](./CONTRIBUTING.md)
- **行为准则**：本项目采用 [贡献者公约](./CODE_OF_CONDUCT.md)，请所有参与者遵守

## 开源许可

本项目基于 [MIT License](./LICENSE) 开源，可自由使用、修改和分发。