@solo-thinker/moss
v1.1.0
Published
MOSS - 微内核 + 模块化架构的 AI Agent 应用
Readme
MOSS
微内核 · 模块化 · 可扩展的 AI Agent 操作系统
[!WARNING] 尚未完全建造完成，后续破坏性变更较多，请勿用于生产环境！
简介
MOSS 是一个基于微内核 + 模组化架构的本地 AI Agent 应用，运行于 Bun 运行时之上。它以浏览器 Web UI 作为交互界面，以本地常驻服务作为核心载体，将 LLM 推理、工具执行、上下文管理、持久终端、浏览器/桌面操作、语音输入与任务调度整合为一套完整、可扩展的 Agent 运行环境，并支持局域网与公网隧道远程访问。
内核仅提供配置、事件、服务注册与日志四项基础能力，其余一切功能——从 Agent 引擎、LLM 路由到 HTTP 服务与定时任务——均以模组形式挂载，模组之间通过服务契约（ServiceRegistry）与事件总线（EventBus）解耦协作。模组由内核静态注册表按固定顺序加载（被依赖者在前），正向初始化、反向销毁。这种架构使 MOSS 既保持核心的精简稳定，又允许通过 Skill 在不触碰内核的情况下持续扩展能力边界。
核心特性
- 微内核架构 —— ConfigService / EventBus / ServiceRegistry / Logger 四大核心服务，21 个模组由内核静态注册表按固定顺序加载（被依赖者在前），正向初始化、反向销毁
- ReAct Agent 引擎 —— 流式文本与思维链输出、多轮工具调用循环、任务引导/中断、上下文自动压缩与裁剪、工具结果智能折叠
- 多 LLM Provider 路由 —— 内置 openai-chat / openai-responses / anthropic / gemini 等接口格式，支持 DeepSeek、Anthropic、OpenAI、Gemini、Qwen、GLM、Kimi 等主流模型，按模型自动解析路由，支持 thinking 推理输出
- MCP 双向支持 —— 作为客户端接入任意 Model Context Protocol 外部工具服务器；同时通过
/mcp端点与moss mcp（stdio）向外部 Agent 暴露 MOSS 工具 - 内置工具集 —— 19 个可配置内置工具（read / write / edit / delete / move / copy / glob / grep / terminal / todo / ask / web / skill / mcp / memory / context / automation / browser / computer）+
use_command斜杠命令执行，写操作与命令执行可配置逐次确认 - Skills 与自定义命令 —— 以 Markdown + YAML front-matter 定义的可复用技能与斜杠命令，支持用户自定义与热重载
- Agent 团队 —— agenteam 注册表 + 团队编排（生命周期、DAG 调度、质量门禁、临时 subagent）
- 持久终端 —— 原生 PTY 会话：人类经 WebSocket 操作，Agent 经 terminal 工具操作，二者共用同一批终端
- 浏览器控制 —— Chrome 扩展桥接（CDP）、内置 Chrome、AI 标签页归组与页面操作
- 桌面操作 —— 集成 cua-driver：后台窗口观察、UIA、截图与输入
- 语音输入 —— 本地 sherpa-onnx（zipformer / SenseVoice / Whisper）、在线服务商与浏览器 WASM 本地推理
- 远程访问 —— 局域网直连 + cloudflared 公网隧道，8 位密码鉴权与请求门卫
- 记忆 / 规则 / 钩子 —— 四层记忆栈（L0-L3）BM25 检索与异步蒸馏；用户规则条件注入；生命周期钩子引擎
- 上下文工程 —— 拼接、压缩、自愈、预算校准、文件索引与遥测
- 文件历史 —— 编辑追踪、快照、撤回与恢复
- 自动化任务 —— 基于 cron 表达式与一次性定时（once）的调度，附带完整运行历史与暂停/恢复控制
- 现代 Web UI —— React 19 + shadcn/ui + Tailwind 4，中英双语（i18next），PWA 离线可用，主题/字号/密度可调
- 安全默认 —— 默认仅绑定 127.0.0.1，支持 Bearer Token 鉴权，敏感工具独立确认开关
系统架构
┌─────────────────────────────────────────────────────────┐
│ 浏览器 (Web UI) │
│ React 19 + shadcn/ui + Tailwind 4 + i18next │
└──────────────┬──────────────────────┬───────────────────┘
│ HTTP REST (/api/*) │ WebSocket (/ws)
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Server 模组 (Bun.serve :7766) │
│ HTTP 路由 + WS 处理 + 静态资源服务 │
└──────────────┬──────────────────────────────────────────┘
│ ServiceRegistry 依赖注入
▼
┌─────────────────────────────────────────────────────────┐
│ 微内核 (Kernel) │
│ ConfigService │ EventBus │ ServiceRegistry │ Logger │
│ 静态模块注册表（固定顺序编排生命周期） │
└──────────────┬──────────────────────────────────────────┘
│ 按固定顺序加载（被依赖者在前）
▼
┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│ LLM 模组 │ Server 模组 │ Remote 模组 │ Tools 模组 │ MCP 模组 │Computer 模组 │
│ (多Provider) │ (HTTP+WS) │ (远程访问) │(工具+Skill) │ (双向 MCP) │ (桌面操作) │
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│ Browser 模组 │ Update 模组 │ Filesys 模组 │Terminal 模组 │ Safety 模组 │ Rules 模组 │
│ (浏览器控制) │ (版本检查) │ (虚拟FS) │ (持久终端) │ (权限决策) │ (用户规则) │
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│ Hooks 模组 │ Memory 模组 │ Voice 模组 │Context 模组 │ Agent 模组 │agenteam模组 │
│ (生命周期) │ (记忆引擎) │ (语音识别) │(上下文引擎) │(ReAct 引擎) │(Agent 团队) │
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
┌──────────────┬──────────────┬──────────────┐
│File-history │ Daemon 模组 │Automation模组│
│ (文件历史) │ (PID 维护) │ (定时任务) │
└──────────────┴──────────────┴──────────────┘模组一览（21 个，按内核加载顺序）：
| 模组 | 职责 | 注册的标准服务 |
|---|---|---|
| llm | 多 Provider 路由与流式调用 | llm.router |
| server | HTTP + WebSocket 服务 | server.instance |
| remote | 远程访问：局域网直连 / cloudflared 隧道 / 请求门卫 | remote.service |
| tools | 内置工具 + Skill/Command 注册表 | tool.registry、skill.registry、command.registry |
| mcp | MCP 客户端管理 + 对外 MCP Server 暴露 | mcp.manager、mcp.task.registry |
| computer | 集成 cua-driver：后台桌面观察/操作（窗口、UIA、截图、输入） | computer.service |
| browser | 浏览器扩展桥接 / 内置 Chrome / AI 标签页 / CDP 操作 | browser.service |
| update | npm registry 版本检查 | — |
| filesys | 虚拟文件系统：roots 权限 / 读缓存 / 变更事件 | file.sys |
| terminal | 持久终端 PTY 会话管理 + 输出缓冲 + 状态 | terminal.service |
| safety | 统一权限决策 + 会话规则 | safety.service |
| rules | 用户规则引擎（存储 / 加载 / 条件注入） | rules.engine |
| hooks | 生命周期钩子引擎 | hooks.engine |
| memory | 记忆引擎（存储 / 检索 / 蒸馏） | memory.engine |
| voice | 语音识别（本地 sherpa-onnx / 在线服务商 / WASM） | voice.service |
| context | 上下文引擎（拼接 / 压缩 / 自愈 / 遥测 / 文件索引） | context.engine |
| agent | ReAct 循环、会话与任务管理、事件流 | agent.engine |
| agenteam | 自定义 Agent CRUD + 团队编排 | agenteam.registry、agenteam.orchestrator |
| file-history | 文件历史（编辑追踪 / 快照 / 回滚） | file.history |
| daemon | 运行时 PID 文件维护 + 优雅退出 | — |
| automation | cron / once 定时任务调度 | automation.service |
内核自身另注册 kernel.config、kernel.logger、kernel.modules 三个基础服务。
快速开始
环境要求
| 依赖 | 版本 | 用途 | |---|---|---| | Bun | >= 1.1.0 | 后端运行时与测试 | | Node.js + npm | >= 18 | 前端依赖管理与开发工具链 |
安装
# 克隆仓库
git clone <repository-url>
cd MOSS-OS
# 安装后端依赖
npm install
# 安装前端依赖
cd webui
npm install
cd ..浏览器扩展、语音模型与 cua-driver 均为按需启用：扩展可经 Web UI「设置 → 浏览器」打开扩展目录后手动加载；语音模型在设置中下载到
~/.moss/models/asr/；桌面操作在首次使用时由 computer 模组探测/安装驱动程序。
首次配置
MOSS 首次启动会自动在 ~/.moss/config/ 下生成配置模板（api.json 模板中 providers 为空数组）。编辑 ~/.moss/config/api.json，按以下结构添加至少一个 Provider 并填入 API Key：
{
"version": 2,
"providers": [
{
"id": "provider_0001",
"name": "DeepSeek",
"format": "openai-chat",
"endpoint": "https://api.deepseek.com",
"apiKey": "<你的 API Key>",
"models": [
{
"id": "model_0001",
"name": "DeepSeek Chat",
"model": "deepseek-chat",
"thinking": { "enabled": false }
},
{
"id": "model_0002",
"name": "DeepSeek Reasoner",
"model": "deepseek-reasoner",
"thinking": { "enabled": true, "effort": "high" }
}
]
}
]
}其中 models 为对象数组，每个模型含 id（内部唯一标识）、name（显示名）、model（发送给 API 的模型名）与模型级 thinking 配置。
配置保存后无需重启，内核监听文件变更并自动热重载。
启动
# 前台运行（推荐首次使用，日志直接输出）
npm run start
# 或以守护进程方式后台运行
npm run start:daemon启动后访问 http://127.0.0.1:7766 即可使用 Web UI。
CLI 命令
moss start [--foreground] # 启动服务（--foreground 前台运行，默认守护进程）
moss stop # 停止守护进程
moss status # 查看运行状态
moss restart # 重启服务
moss mcp # 以 stdio 方式运行 MCP Server（供 Claude Desktop / Cursor 等调用）
moss update # 更新版本
moss version # 查看当前版本等价的 npm scripts 亦可使用：npm run start / stop / status / restart / update / version。
配置
所有配置与用户数据位于 ~/.moss/：
| 文件 | 职责 |
|---|---|
| ~/.moss/config/config.json | 应用配置：服务端口、守护进程、Agent 参数、工具开关、安全策略、远程访问、语音等 |
| ~/.moss/config/api.json | 模型配置：Provider 列表、API Key、模型与 thinking 参数 |
AppConfig 配置段：
| 配置段 | 职责 |
|---|---|
| server | host / port / autoPort / locale |
| daemon | 是否以守护进程方式运行 |
| logs | 日志级别、保留天数、单文件大小 |
| update | 自动检查、channel（stable/beta）、检查间隔 |
| agent | 默认模型、maxTokens、maxTurns（0 = 不限轮）、工作目录、SSE 空闲超时 |
| tools | 各内置工具开关与确认策略（由工具目录下 tool.json 自动生成 schema） |
| mcpServers / mcp / mcpServer | 外部 MCP 服务器、客户端选项、对外 MCP Server 暴露 |
| skills / commands | Skill 与自定义斜杠命令的启停 |
| security | authToken、bindLocalhostOnly |
| remote | 远程访问总开关、局域网开关、密码开关、IP 覆盖 |
| fileHistory | 文件历史备份数量、保留天数、转录开关 |
| filesys | 授权 roots、读缓存上限、终端命令快照检测 |
| safety | 默认权限模式、确认超时、危险命令拦截、规则与保护路径 |
| context | 上下文压缩/修剪/自愈/遥测参数 |
| web | 默认联网搜索服务商 |
| voice | 语音输入开关、服务商、本地模型、语言 |
支持的 Provider 接口格式：
| format | 示例 endpoint | thinking 支持 |
|---|---|---|
| openai-chat | https://api.openai.com/v1 | 否 |
| openai-responses | https://api.openai.com/v1 | 是（effort） |
| anthropic | https://api.anthropic.com/v1 | 是（effort + budgetTokens） |
| gemini | https://generativelanguage.googleapis.com/v1beta | 是（budgetTokens） |
常用配置项（config.json）示例：
{
"server": { "host": "127.0.0.1", "port": 7766 },
"agent": { "defaultModel": "deepseek-chat", "maxTokens": 8192 },
"security": { "authToken": "", "bindLocalhostOnly": true },
"remote": { "enabled": false, "lanEnabled": true },
"voice": { "enabled": false, "language": "auto" }
}security.authToken：非空时所有 HTTP 请求需携带Authorization: Bearer <token>tools.*.requireConfirmation：为write/delete/terminal等敏感工具启用逐次确认remote.enabled：开启后主服务绑定0.0.0.0并启用请求门卫（详见 架构文档）- 配置文件变更后 300ms 防抖自动重载，无需重启服务
技术栈
| 层 | 技术 | |---|---| | 后端运行时 | Bun + TypeScript | | 内核 | 自研微内核（Zod 配置校验、fs.watch 热重载、静态注册表固定顺序加载） | | LLM 接入 | openai-chat / openai-responses / anthropic / gemini 格式，流式 SSE | | 工具协议 | Model Context Protocol (MCP) SDK（客户端 + 服务端） | | 终端 | 原生 PTY + @xterm/headless（服务端）/ @xterm/xterm（前端） | | 浏览器 | Chrome DevTools Protocol、Chrome for Testing、Manifest V3 扩展 | | 桌面操作 | cua-driver（窗口 / UIA / 截图 / 输入） | | 语音 | sherpa-onnx（本地）、在线 ASR 服务商、WebAssembly 浏览器推理 | | 前端框架 | React 19 + React Router 7 | | UI 组件 | shadcn/ui + Radix UI + Tailwind CSS 4 + Lucide Icons | | 状态与数据 | Zustand + idb（IndexedDB） | | 可视化 | Three.js / React Three Fiber、Mermaid、Shiki、KaTeX | | 构建工具 | Vite 8（前端）、bun build（后端单文件打包） | | 国际化 | i18next（中文 / English） |
项目结构
MOSS/
├── webui/ # 前端（React 19 + shadcn/ui）
│ └── src/
│ ├── api/ # HTTP + WS 客户端封装
│ ├── components/ # UI 组件
│ ├── hooks/ # 业务 hooks
│ ├── store/ # 全局状态
│ ├── i18n/ # 国际化（zh/en）
│ └── types/ # 前后端共享类型
├── src/
│ ├── main.ts # 入口：CLI 解析 + 启动 Kernel
│ ├── cli/ # CLI 命令实现
│ ├── core/ # 微内核（kernel/config/event-bus/...）
│ ├── modules/ # 21 个模组（agent/agenteam/automation/browser/
│ │ # computer/context/daemon/file-history/filesys/
│ │ # hooks/llm/mcp/memory/remote/rules/safety/
│ │ # server/terminal/tools/update/voice）
│ └── utils/ # 通用工具
├── browser-extension/ # Chrome 扩展（MOSS Browser Bridge，Manifest V3）
├── agent/prompts/main/ # Agent 系统提示词（.md）
├── skills/ # Skill 定义（.md + YAML front-matter，首次启动播种到 ~/.moss/skills/）
├── config/ # 配置模板
├── docs/ # 架构与 API 文档
├── scripts/ # 构建/开发脚本（build/dev/install-webui/rebrand-icons）
└── bin/moss.js # CLI 入口开发指南
开发模式
npm run dev并行启动：
- 后端：
bun run --watch src/main.ts start --foreground --log-level debug，监听 7766 端口，文件改动自动重启 - 前端：Vite dev server，监听 3000 端口，
/api与/ws自动代理到后端
访问 http://localhost:3000 进行开发调试，Ctrl+C 优雅退出全部子进程。
构建与测试
npm run build # 构建后端（dist/server.js）+ 前端（dist/webui/）
npm run build:ui # 仅构建前端
npm run build:backend # 仅构建后端
npm run test # 运行测试（bun test，当前 41 个单元测试）
npm run test:watch # 监听模式测试
npm run typecheck # TypeScript 类型检查（tsc --noEmit）扩展体系
MOSS 提供两种扩展方式：
| 类型 | 位置 | 清单 | 上下文 | 权限 |
|---|---|---|---|---|
| 模组 (Module) | src/modules/*/ | —（内核静态 import 编排） | ModuleContext | 可注册受保护服务 |
| Skill | ~/.moss/skills/（唯一加载源；包内 skills/ 仅首次启动播种） | YAML front-matter | 工具调用 | Agent 按需加载执行 |
模组由内核静态注册表按固定顺序加载（被依赖者在前），新增模组需修改 src/core/kernel.ts 的 MODULE_FACTORIES 注册表。
文档
- 系统架构详述 —— 微内核、模组系统、Agent 工作流、远程访问、数据持久化
- 前后端 API 对接 —— REST 接口与 WebSocket 协议细节
License
本项目基于 MIT License 开源。