📦 仓库名片 · Powered by gh-card
智能体下载（GitHub Releases） · 官网与在线文档 osbt.space · 完整 Wiki · QQ 交流群
一、BrainTentacle（触手怪 / BIT）是什么
BIT 是一个桌面 AI Agent 工具中枢：配置任意 AI 提供方（OpenAI / Gemini / Claude）即可流式对话，并让 AI 调用本机工具、自写脚本、沉淀记忆与技能。密钥等敏感信息对 AI 脱敏，全部数据保存在本机，可审计、可远程访问。
几个重要承诺：
- 永久免费：完全开源（Apache-2.0），所有功能对个人与商业用户永久免费——无内购、无订阅、无功能锁、无遥测，可随时自行编译。
- 全平台覆盖：Windows x64/ARM64、macOS Apple Silicon/Intel、Linux x64/ARM64，甚至龙芯 LoongArch64、RISC-V 64、飞腾/鲲鹏/麒麟、ChromeOS（Crostini）都有对应安装形态。
- 黑白线性设计：无边框自定义标题栏、深/浅色主题。
二、架构与原理：为什么是「Electron 托盘壳 + Rust 核心」
BIT 不是套壳网页，而是真正做了分层。整体技术栈如下：
| 层 | 技术 | 说明 |
|---|---|---|
| 前端 | React 18 + Vite 6 + Tailwind CSS 4 + react-markdown/remark-gfm | 对话页、工具页、服务页、记忆页、技能页、审计页、安全页、远程页等 |
| 桌面壳 | Electron（托盘形态）+ Tauri 2（原生形态） | 同一份核心构建两个壳 |
| 桥接 | N-API | Electron 通过桥复用同一份 Rust 核心 |
| 核心 | Rust：tokio + axum + reqwest(stream) + rhai + futures-util | 一切的发动机 bit-core |
几个关键的架构原理：
- 一份核心、两个壳、一份数据。
crates/bit-core编译为 Rust 核心库，Electron 壳通过crates/bit-napi（N-API 桥）复用它，Tauri 壳（src-tauri/）则直接链接。两个壳共用同一数据目录与bit.db数据库——你换壳不丢数据。 - 全链路流式。AI 回复走 SSE + Electron/Tauri Event 双通道流式，逐字输出；思考过程独立显示；缓存命中率实时统计。
- 工具注册中心（registry）。核心里的 registry 是所有能力的汇合点：内置工具、AI 自建脚本、本地插件、MCP 服务器、WorkWith 服务，全部注册成同构工具——AI 调用时一视同仁，每项工具带成功率 / 平均耗时统计。
- 解释器自动探测（runtime）。启动时自动探测本机 JS / Python 解释器，也支持 Perl / Julia / 编译型程序与任意可执行文件。AI 只需写一段「能通讯的脚本」即可成为工具（通讯约定见第六节），工具热更新。
- Rhai 沙箱（script_runtime）。AI 自建脚本不是直接跑在你系统里，而是经 Rhai 沙箱受限执行，带深度 / 操作数 / 墙钟预算三重限额，防失控。
- 记忆与技能（memory）。AI 通过
add_memory/skill内置工具自行总结沉淀结论，跨会话复用，无需手动触发——用得越久越懂你。 - 目标与子代理（goal / agent）。打开 Autopilot 后，待办可自动派给子代理并行推进；计划目标与待办在「记忆」页可查可删。
项目结构一览：
src/ React 前端
pages/ 对话 / 工具 / 服务(WorkWith) / 记忆 / 技能 / 审计 / 安全 / 远程 / AI 设置 / 主题
components/ Markdown、工具卡片、图标等
crates/bit-core/ Rust 核心：ai、agent、mcp、registry、runtime、script_runtime、
http_api、update、audit、session、goal、memory、plugins、workwith …
crates/bit-napi/ Electron 用的 N-API 桥
src-tauri/ Tauri 壳（原生版）
electron/ Electron 壳（托盘、preload）
packaging/ npm / flatpak / musl / exotic / Arch 等分发通道
installer/bit.iss Inno Setup 打包脚本
三、安装：全平台安装包与包管理器
3.1 安装包（Releases 下载）
| 平台 | 安装包 | 说明 |
|---|---|---|
| Windows x64 | BIT_<版本>_x64-setup.exe（NSIS） |
双击安装；骁龙 X 等 ARM64 笔记本选 aarch64 版 |
| macOS Apple Silicon | BIT_<版本>_aarch64.dmg |
M 系列芯片 |
| macOS Intel | BIT_<版本>_x64.dmg |
拖入 Applications |
| Linux x64/ARM64 | .deb / .AppImage / .rpm |
按发行版习惯选择 |
| 龙芯 3A5000/3A6000、RISC-V 64 | bit-cli_* 或 Tauri 版安装包 |
musl/exotic 通道，见下 |
| 飞腾/鲲鹏/麒麟 | aarch64 的 deb/AppImage/rpm |
与 Linux ARM64 通用 |
| 兆芯/海光 | amd64 的 deb/AppImage/rpm |
与 Linux x64 通用 |
musl（Alpine）/ 龙芯 / RISC-V / ppc64le 上仓库提供
bit-cli_*（TUI / worker / guardian 命令行形态）；需要 GUI 时直接下载 Tauri 版 BIT 安装包（bit releases），与 Electron 版共用同一份核心与数据目录。
3.2 包管理器安装
macOS（Homebrew）：
brew tap yxpil/bit
brew install --cask bit
Windows（Scoop）：
scoop bucket add bit https://github.com/yxpil/scoop-bit
scoop install bit
npm（跨平台，自动下载对应平台应用）：
npm install -g bit-agent
bit-agent # 启动 BIT
Windows（winget，审核中）：winget install yxpil.bit
Debian / Ubuntu / UOS / 麒麟（APT 源）：
echo "deb [trusted=yes] https://yxpil.github.io/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/bit.list
sudo apt update && sudo apt install bit
Fedora / RHEL / openSUSE（dnf 源）：
sudo tee /etc/yum.repos.d/bit.repo <<'EOF'
[bit]
name=BIT
baseurl=https://yxpil.github.io/dnf-repo
enabled=1
gpgcheck=0
EOF
sudo dnf install bit
Arch / Manjaro（pacman 源）：
echo "
[bit]
Server = https://yxpil.github.io/pacman-repo/\$arch
SigLevel = Never" | sudo tee /etc/pacman.d/bit.conf
# 在 /etc/pacman.conf 的 [core] 前加一行：Include = /etc/pacman.d/bit.conf
sudo pacman -Sy bit
3.3 安装疑难排查
- macOS 提示「已损坏，无法打开」：BIT 采用 ad-hoc 签名（未购买 $99/年 开发者证书），macOS 对网络下载的应用默认拦截。执行一次
xattr -cr /Applications/BIT.app即可（原理：删除 quarantine 隔离标记，签名本身完整可校验）。也可在 系统设置 → 隐私与安全性 → 点「仍要打开」。 - Windows SmartScreen：安装包未做代码签名（EV 证书同样需付费），点「更多信息」→「仍要运行」。
- Linux AppImage：
chmod +x BIT_<版本>_amd64.AppImage后运行。 - ChromeOS（Crostini）：设置 → 关于 ChromeOS → 开发者 → 启用 Linux 开发环境，然后
sudo apt install ./BIT_<版本>_amd64.deb，依赖（libwebkit2gtk-4.1、libgtk-3 等）由 Debian 12 仓库自动补齐。
四、打包与自编译
想自己编译（或给内网分发）？前置只需要 Node.js + Rust 工具链 + Tauri 系统依赖：
npm install # 安装前端依赖
npm run tauri dev # Tauri 开发模式（热更新）
npm run tauri build # 构建 Tauri release（NSIS / MSI / dmg / AppImage / deb）
- Electron 壳的构建配置在
electron-builder.yml，打包前的资源暂存逻辑在scripts/stage-pack.cjs。 - Windows 经典安装器用
installer/bit.iss（Inno Setup 脚本）。 - 分发通道集中在
packaging/目录：npm、flatpak、musl、exotic（龙芯/RISC-V/ppc64le）、Arch 等都有现成脚本；npm install -g bit-agent这个包会按平台自动下载对应应用。 - 发版流程（版本号、changelog、CI 构建）详见 Wiki 的「开发与构建」章节。
五、使用：三分钟上手到进阶
① 配一个模型：「AI 设置」页 → 添加提供方 → 选协议（OpenAI / Gemini / Claude）、填 Base URL、API Key、模型名（可点「从 API 获取」一键拉取模型列表）→ 点条目上的播放按钮激活。同一时刻只有一个提供方生效（互斥），先测试上游连通性再保存。
② 开始对话：回复流式逐字输出，工具调用以卡片展示参数与结果。审批模式三档可切：每次询问 / 自动审批（危险操作仍询问）/ 完全放行。
③ 让它干活，试试这些自然语言指令：
列出当前目录的文件并统计大小
写一个脚本，把这周的 git log 按作者汇总成表格
帮我查一下这个报错信息
把「本项目用 pnpm 不要用 npm」记下来
AI 会自己挑工具、必要时写脚本、把有用结论用 add_memory / skill 沉淀下来跨会话复用。
④ 终端模式：安装后在任意终端输入 bit 直接进入 TUI 对话——无窗口、无单实例约束、不监听端口，SSH / 无桌面环境的救星。
⑤ 长对话治理：一键压缩为摘要；会话收藏、彩色标签、多选删除；执行中的任务切走不中断，长命令自动转后台。
⑥ 系统托盘：关窗即驻留托盘不丢任务；右键任务面板可看会话回合 / 后台命令 / 子代理 / 活跃目标，状态灯白=空闲、黄=进行中、绿=成功、红=受阻。
六、MCP 插件与协同工作服务器：三层扩展体系与原理
这是 BIT 最强的地方。扩展能力分三层，从轻到重：
本地插件（声明式，最省事）→ MCP 扩展（接现成服务器）→ WorkWith（托管你自己的常驻程序）
三者最终都把能力汇入同一个工具注册中心，AI 一视同仁地调用。
6.1 本地插件：一个文件夹 + 一个 plugin.json
① 找到插件目录（固定在数据目录下的 toolhomes/plugins/）：
| 平台 | 数据目录 |
|---|---|
| Windows | %APPDATA%\com.bit.hub\toolhomes\plugins\ |
| macOS | ~/Library/Application Support/com.bit.hub/toolhomes/plugins/ |
| Linux | ${XDG_DATA_HOME:-~/.local/share}/com.bit.hub/toolhomes/plugins/ |
设了
BIT_DATA_DIR环境变量时以它为准。「工具」页 → 「本地插件」区块会直接显示当前插件目录完整路径，点一下复制即可。
② 写一个 plugin.json（除 name 外全部可选）：
{
"name": "我的插件",
"version": "0.1.0",
"description": "一句话说明这个插件干什么",
"tools": [{
"name": "disk_usage",
"description": "查看指定目录的磁盘占用",
"parameters": {
"type": "object",
"properties": { "path": { "type": "string", "description": "目录路径" } },
"required": ["path"]
},
"kind": "interpreter",
"runtime": "py",
"file": "disk_usage.py"
}],
"prompts": ["回答时优先使用中文。"],
"skills": [{ "name": "磁盘排查", "summary": "先用 disk_usage 看占用，再逐层往下钻" }],
"memories": ["本机默认工作目录是 D:/work"],
"jobs": [{
"name": "日报",
"schedule": "daily 09:00",
"runtime": "py",
"file": "daily.py"
}]
}
字段说明：
| 字段 | 说明 |
|---|---|
name / version / description |
展示信息；插件 id 取目录名 |
tools[] |
kind = interpreter（本机解释器跑）或 script（Rhai 沙盒）；interpreter 必填 runtime（py/js/ps1/…）；源码 code 内联或 file 指向插件目录内相对路径（file 优先） |
tools[].parameters |
JSON Schema 参数描述，缺省视为无参 |
prompts[] |
启用时追加到系统提示词的指令片段 |
skills[] |
注入技能列表（name + summary），与 AI 自动提炼的技能同构 |
memories[] |
作为记忆注入的内容 |
jobs[] |
定时任务；schedule 支持 every 30m / every 2h / daily 09:00；session 填会话 id 可把结果注入该会话 |
③ 工具脚本的通讯约定（原理核心）：从 stdin 读参数 JSON，把结果打印到 stdout。所以 disk_usage.py 就这么简单：
import json, sys, shutil
params = json.loads(sys.stdin.read() or '{}')
total, used, free = shutil.disk_usage(params.get("path", "."))
print(json.dumps({"total": total, "used": used, "free": free}, ensure_ascii=False))
④ 生效：「工具」页 → 「重扫插件」。每个插件有独立启停开关（存在 disabled_plugins，重扫不丢选择）；扫描失败的插件会被跳过并列出错误原因，不会静默消失。插件工具走既有执行链，自动继承安全策略与超时配置。
6.2 MCP 扩展：接入现成的 MCP 服务器
先讲原理：BIT 同时是 MCP 客户端和 MCP 服务器。作为客户端，它支持两种标准传输：
- Streamable HTTP：适合独立部署的 MCP 服务，直接 HTTP 调用 JSON-RPC；
- stdio（JSON-RPC 2.0）：每个 stdio 服务器作为独立子进程启动，通过标准输入输出通信，握手完成后工具自动并入注册表。Windows 下自动用
cmd /c包裹 npx / uvx 等 npm 命令，省去兼容性坑。
三种接入方式：
方式 A：自动扫描（最省事）——「工具」页 → 「MCP 服务器 · 自动发现」→ 指定端口范围 → 扫描 → 一键接入。BIT 会连上去做 initialize 握手，把该服务器暴露的工具自动并入。扫描还能发现局域网内其它机器的 MCP 服务器。
方式 B：粘贴端点 URL——知道 Streamable HTTP 端点（如 http://127.0.0.1:8341/）时直接填 URL 回车。
方式 C：粘贴 mcpServers 配置（stdio）——兼容 Cursor / Claude Desktop 的现成配置，粘进去就能用：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/data"]
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": { "BRAVE_API_KEY": "xxx" }
}
}
}
已接入的服务器可暂停 / 恢复 / 移除（kill 进程）/ 重新拉取并导入工具。MCP 会话治理：30 分钟空闲过期、数量上限、显式 DELETE 终止。
**去哪找 MCP 服务器？**作者维护的 TentacleTool：13 个零依赖 MCP 工具集（文件系统 fsx、Git gitx、HTTP httpx、加密 cryptox、数据库 kb、代码图谱 analyze、时间调度 stamp、数据格式 jsonx、本机搜索 find、计算 calc、聚合搜索 search、网页转 MD webview、局域网 neton），每个自带端口，扫描即可发现。社区合集见 awesome-mcp-servers / awesome-mcp-clients。
6.3 WorkWith：协同工作服务器（添加即可，自动扫描运行）
「服务」页（WorkWith）用来把本机常驻程序接进 BIT：用本机已探测的运行环境托管服务器程序（server.js、xxx.jar，或任意自定义可执行文件）。
**你只需要做一件事：新建条目、填路径、保存。**之后 BIT 自动完成剩下的全部动作：
填好条目 → 自动拉起程序（无窗口）→ 实时捕获日志 → 自动探测端口就绪
→ 自动扫描并接入为 MCP 服务器 → 该服务上的工具自动可用
停止 / 崩溃 → 自动禁用该 MCP 并同步移除其工具（不留死工具）
新建条目要填的字段：
| 字段 | 说明 |
|---|---|
| 名称 | 展示名，如「我的 MCP 服务」 |
| 运行环境 | 从已探测的解释器里选（node / java / python…），或选「自定义可执行文件」 |
| 程序路径 | 如 C:/app/server.js 或 app.jar |
| 启动参数 | 空格分隔，如 --port 3000 |
| 工作目录 / 环境变量 | 可选；环境变量每行一条 K=V |
| 服务端口 | 该程序监听的端口。填 0 = 只托管进程，不联动 MCP |
| 会话联动 | 勾上后新会话首回合自动拉起（幂等，已在运行则跳过）；不勾则手动点「启动」 |
原理细节：页面内可直接展开看运行日志（stdout / stderr，1 秒轮询，进程退出由事件刷新兜底）；条目卡片显示「运行中 · PID」「MCP 已接入」等状态；删除条目时运行中的服务会被停止，其 MCP 工具同步移除。
典型用法：让 AI 在对话前自动拉起你自己的本地 MCP 服务 / 数据库网关 / 构建脚本服务，用完即停——既省手，又不会留下常驻进程。
七、黑科技：HiddenCode 隐藏个人信息脱敏
这是 BIT 安全设计里最「聪明」的一环，专门解决一个真实痛点：你让 AI 帮你干活，免不了把 API Key、手机号、邮箱、真实姓名发给云端模型——等于把隐私交了出去。
核心原理一句话：在「发给 AI 之前」把敏感值替换成占位符或别名，工具在本机执行时才还原真实值——AI 全程看不到原文，但功能完全不受影响。
整个流程是这样的：
你的消息 ──→ [HiddenCode 引擎] ──→ 脱敏后的文本 ──→ 云端 AI（只看到 [HC:xxxxxx]）
↓ 原文留在本机的映射表
AI 决定调用工具 ──→ 本机执行时自动把占位符还原为真实值 ──→ 工具拿到真 Key 正常干活
↓
工具结果 ──→ 再次脱敏 ──→ 回传给 AI 展示
四层探测机制：
- 内置类型掩码：密钥 / 手机号 / 邮箱 / 用户名等常见敏感类型开箱即用；
- 精确值：把指定字符串（如某个具体 Key、具体人名）加入脱敏名单；
- 自定义正则：适配公司内部工号、订单号等自定义格式；
- 粘贴扫描探测：从剪贴板粘贴内容时即时扫描，发现疑似敏感信息立刻提示脱敏。
别名替换更有意思：可以把「小明」映射为「李四」——AI 看到的是李四，处理的是李四的语境，而你本机工具执行时面对的是真实的小明。适合让 AI 处理涉及真实人名的任务又不想暴露身份。
配套的第二道防线——L2 PASS 二级审核（实验功能）：工具执行前，先把调用请求交给另一个模型审核 Allow / Deny，可以覆盖「自动放行」的工具；审核模型不可达时自动回退人工审批，不打断正常使用。等于给危险操作上了双保险。
再加上这些底层加固，HiddenCode 才算完整闭环：
- 审计日志：所有工具调用与关键操作留痕，「审计」页按主体 / 动作 / 目标过滤，脱敏决策也留痕可查；
- 常数时间比较：Client Key 校验采用常数时间比较，防时序侧信道；
- 加密存储：设备密钥派生加密敏感配置，带防篡改校验；
- 沙箱与限额：AI 自建脚本经 Rhai 沙箱（深度 / 操作数 / 墙钟预算）；子进程工具带超时杀灭、输出上限与资源回收。
八、远程访问与 API：把 BIT 当本地 AI 网关
「远程」页开启后，BIT 在本机监听 HTTP API（默认 127.0.0.1:8600，可改为 0.0.0.0 供局域网访问；默认关闭，开启时自动生成密钥与访问密码）。
双重认证：
- Client Key（
bit_前缀，自动生成）：Authorization: Bearer <key>或?key=<key>，用于/v1/*与/mcp端点； - 访问密码：
/api/*管理端点额外要求X-Access-Password头（OpenAI / MCP 客户端无法携带自定义头，故豁免）。
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/chat/completions |
POST | OpenAI 兼容对话（支持 SSE 流式） |
/v1/models |
GET | 模型列表 |
/mcp |
POST / DELETE | 标准 MCP 服务器（Streamable HTTP / JSON-RPC 2.0） |
/api/* |
— | 会话 / 配置 / 审计等管理接口（需访问密码） |
/api/health |
GET | 健康检查（无需认证） |
curl http://127.0.0.1:8600/v1/chat/completions \
-H "Authorization: Bearer $BIT_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL","messages":[{"role":"user","content":"列出当前目录"}]}'
任何支持 OpenAI 接口的客户端（Cherry Studio、LobeChat、沉浸式翻译等）都可把 BIT 当本地 AI 网关接入，支持流式与图片多模态透传。手机端用 bit-mobile 扫码配对，连接策略三级回落：局域网直连 → IPv6 直连 → 云中继。
九、日常维护
- 自动更新：全平台自动检查、下载、换装，可在设置里关闭；更新走 update 模块，不影响本机数据。
- 数据本地化与备份：会话、记忆、技能、配置全部在本机应用数据目录（核心库
bit.db）；备份 = 直接复制数据目录，就这么简单。不上传任何遥测。 - 审计：「审计」页按主体 / 动作 / 目标过滤所有工具调用与关键操作，出问题先来这里回溯。
- 排查建议：
- 工具调用失败：先看对话里的工具卡片与「工具」页的「最近错误」，再到「审计」页核对调用记录；
- MCP 扫描不到：扩大端口范围或直接填 URL；stdio 配置格式错误会启动失败，「服务」页与「工具」页均有日志提示；
- 插件不生效：确认层级是
plugins/<插件名>/plugin.json（不能多层嵌套），改完点「重扫插件」； - 远程调用工具同样受工具启用开关与审批模式约束，不会绕过安全策略。
- 扩展来源可控：插件是本地声明式文件（不下载即不执行）；MCP / WorkWith 接入的每个服务器与工具都有独立启停开关，随时可断开——接入谁、跑什么，始终由你决定。
十、生态：同门项目
| 项目 | 说明 |
|---|---|
| TentacleTool | 触手怪的 MCP 工具集：13 个零依赖 MCP 服务器，扫描端口即可接入 |
| bit | 同一 Rust 核心的 Tauri 2 原生壳版本（龙芯 / RISC-V 等 GUI 首选） |
| bit-mobile | 安卓伴侣端：扫码配对，随身对话 / 工具审批 / 多路连接 |
| BITSDK | 让开发者在自己的程序里调用 BIT 的能力 |
| PANOPTES | 屏幕操作 MCP 服务器（截图 + 鼠标键盘控制） |
| Neton | 智能体操作网络系统的工具（设备发现 / 端口扫描 / 协议分析 / 抓包） |
| Firelin | 智能体网络渗透工具集 |
| ADONWORD | 智能体主动防御工具 |
| HOWCUEME | 智能体条件自唤醒程序 |
| MemoryPool | 智能体记忆池程序 |
| SECFORGE | 把上述安全卫星聚合成 29 个 MCP 工具的统一入口 |
许可：Apache License 2.0——所有功能无内购、无订阅、无功能锁，个人与商业使用均免费。