Skip to content

Latest commit

 

History

History
574 lines (420 loc) · 27.5 KB

File metadata and controls

574 lines (420 loc) · 27.5 KB

FreeOS

FreeOS:自由的 AI 工作室,想象空间由你来打开

产品闭环:uv run freeos org loop run。详见 README.md 与 docs/asset-loop.md。

Python 3.12+ License: MIT Version 上游:Octop 组织模块:openXYOS PyPI Code Style: Ruff GitHub stars GitHub forks Discord

创立初心 · 概述 · 亮点 · 核心技术 · 功能特性 · 规划 · 快速开始· 目录

English · 简体中文简介 · 繁體中文 · 日本語 · 한국어 · Français · Español · Português · Русский · العربية

Historical vs Current. 中文产品入口是 README.zh-CN.md。权威意图见 产品契约。

Current: 见下文创立初心与 产品契约:双系统合一;组织像工作室里另一间可独立布置的房间;托管 Node / 内嵌组织页是过渡桥。

Historical: 下文大量沿自 Octop 宿主能力说明(安装脚本、控制台、CLI、亮点表)。那些能力仍在 FreeOS 宿主里,但本文 不是 Octop 官方产品页,也不再把 FreeOS 写成「只管理云端与付费增强服务」。


FreeOS 项目定位与开源来源

FreeOS 是独立的下游二次开发项目,不是 Octop 官方发行版。我们保留上游许可证、版权和 NOTICE,并在此基础上建设本地优先的组织智能化与可导出管理系统能力:

  • Octop(MIT)提供多智能体运行时、FastAPI 控制面、Dashboard、桌面打包及兼容层基础。
  • openXYOS(Apache-2.0)提供组织模型、智能体蓝图、治理契约和本机定制工作台基础。
  • FreeOS 提供集成桥接、行业模板与知识加工、治理校验、版本装配和独立代码导出。我们不宣称获得 Octop、腾讯云或其商标的认可、认证、赞助或官方支持。

完整的许可证分层、署名要求与对外表述见 NOTICE、上游归属说明、产品契约 和 集成架构。

🌱 创立初心

FreeOS 诞生于一个简单而清晰的目标:在 Octop 的自托管多智能体能力之上,让每个人都能同时拥有 Octop + openXYOS 两套系统的力量——不必在「对话与自动化」和「组织与治理」之间二选一。

我们希望模型尽量跑在本地,知识尽量留在本地;Octop 与 openXYOS 已有的能力与资产能够互通、互相增强。用户可以在此基础上开发、优化、自我定制,生长出更贴合自身场景的新 openXYOS,并导出其系统源码,以便进一步产品化与商业化。

为避免整包内嵌 openXYOS 带来的安装负担与体积膨胀,FreeOS 选择另一条路:把 openXYOS 的网页与组织能力,逐步转化为 Octop 宿主上的原生能力,从而形成新的统一系统——FreeOS。当前桌面中的托管 Node / 内嵌组织页,只是通往这一终态的过渡桥,而非终点。

在使用方式上,FreeOS 更像你自己的工作室:先在本机安顿好,注册登录、数据与会话都留在你够得着的地方;以后若需要与更广的服务或授权衔接,会以可选方式慢慢打开,不挡你起步。组织相关能力则像工作室里另一间可独立布置的房间——方便试用、演练和长出自己的组织流程;与日常对话、助手协作同在一个 FreeOS 里,又各自留白,不把两种用法捏成同一种进入方式。

一句话:FreeOS = 本地可控的 Octop 底座 + 可生长、可导出的组织能力,双系统合一,双身份分立。

权威契约:产品契约。

📌 概述

下面「亮点 / 功能特性 / 快速开始」描述的是 从 Octop 继承、仍在 FreeOS 宿主中的能力(控制台、CLI、IM、知识库等),不是把本仓库重新标成 Octop。

借助飞书、钉钉、QQ、Discord、企业微信或 HTTP/SSE/WebSocket API 与任意 Agent 对话;通过专家库一键创建专业角色,通过 Connector(OAuth + MCP)接入外部服务,通过 ACP 与 IDE / 终端 AI 工具双向协作。

宿主设计目标(继承自 Octop):让每一次对话、工作区与凭据都留在你自己的机器上,同时为每个用户配备一组可按场景切换的专业 Agent。

✨ 亮点

特性 说明
👥 多用户多 Agent 专家团 一人管理,全家共用;内置专家库,按场景切换专业角色
🎭 MBTI 人格 16 种人格模板与互动测试,为每个 Agent 赋予鲜明性格
🔒 更安全 JWT 多用户隔离、工具审批、Shell 命令防护与敏感信息脱敏,数据留在本地
🔌 Connector 拓展体系 一键接入腾讯全家桶(文档 / 微博 / 新闻等),OAuth 与 MCP 网关轻松扩展
💾 可插拔后端存储 本地目录、Docker 容器、PostgreSQL 或 COS/S3,AI 在隔离边界内操作
🧠 可迁移记忆系统 基于 harness-memory,记忆随工作区迁移
📚 知识库 基于文档的 RAG 检索,让 Agent 的回答锚定你的私有知识库
🧩 插件 支持第三方插件扩展;内置插件随安装注入,按需一键启用
↔️ ACP 双向集成 octop acp 增强 IDE 与终端 AI;对话中委派 OpenCode / Claude Code 等
💻 终端 AI+ 浏览器内交互式 Shell,AI 辅助命令执行与排障
🌐 浏览器 AI+ 基于 Chromium 的无头浏览器会话,支持网页自动化、截图与远程操控
🖥️ 远程桌面 控制台内实时看屏与键鼠操控,跨 Linux / Windows / macOS;适合远程办公、GUI 软件操作,无图形 Linux 可一键搭建隔离桌面
🏠 可自托管 一条 octop run 即可运行控制台、CLI、IM 通道与定时任务,数据存于 ~/.octop/
🐾 你能用 Octop 做什么
  • 个人助理 — 让专属 Agent 帮你写周报、整理资料、定日程,记忆随工作区长期保留。
  • 家庭共享 — 一个管理员账号,全家共用;按成员分配不同 Agent 与专家角色。
  • 团队助手 — 多 Agent 并行协作,对接飞书 / 钉钉 / 企业微信,把任务自动分发到群里。
  • 开发者增效 — 通过 ACP 把编码任务委派给 OpenCode / Claude Code,或在终端用 AI 辅助排障。
  • 网页自动化 — 用浏览器 AI+ 自动填表、截图、采集公开信息。
  • 定时任务 — 用自然语言配置 Cron,让 Agent 每天按时推送或执行任务。

🧠 核心技术

层级 技术
语言 Python 3.12+
Web 框架 FastAPI + uvicorn
Agent 运行时 harness-agent
IM 桥接 harness-gateway
控制平面数据库 SQLite (WAL,默认) 或 PostgreSQL(可选)
前端 React 18 + TypeScript + Vite + Ant Design
调度 APScheduler
ACP agent-client-protocol
构建 / 质量 hatchling · ruff · mypy · pytest

Octop 基于一系列 Harness 工程实践构建——它将这些专注的运行时组合进同一个进程:

  • harness-agent — Agent 运行时:模型路由、工具、技能与对话检查点。
  • harness-gateway — 多平台 IM 通道桥接,将各类入站消息归一为统一的处理管线。
  • harness-memory — 分层记忆与全文检索,让 Agent 的记忆随工作区一同迁移。
  • harness-browser — 基于 CDP 的浏览器自动化,支持持久化配置,用于网页类任务。

Octop 不依赖外部消息队列或中间件,而是通过进程内的 HarnessProcessor 统一路由所有入口——Web UI、IM 与定时任务。最终呈现为一个可重启恢复的单进程:启动时整个状态都从控制面数据库重建(默认 ~/.octop/octop.db,亦可配置 PostgreSQL)。

🤔 功能特性

服务器与认证

  • 多用户 JWT 认证,支持管理员角色
  • 首次运行向导(octop init)
  • 交互式 API 文档:/api/docs(默认关闭 — 在 config.json 中设置 "enable_api_docs": true 开启)

Agent

  • 每位用户可创建多个 Agent;各自拥有独立工作区、供应商、通道和定时任务
  • 16 种 MBTI 人格模板 + 自定义系统提示词
  • 启动时扫描专家库(infra/agents/experts/library/)
  • 工作区后端:本地磁盘、COS、S3 及其他远程存储

通道与自动化

  • IM 通道:飞书、钉钉、QQ、Discord、企业微信等
  • 主动定时任务,支持自然语言和斜杠命令触发
  • Web UI、IM、定时任务共用同一套消息处理链路

使用入口

  • Web 控制台 — 对话、Agent 管理、连接器、通道、定时任务、设置
  • CLI — octop run、octop chat、octop acp、管理命令
  • HTTP/SSE/WebSocket API — 完整的程序化访问能力

知识库与插件

  • 知识库 — 基于文档的 RAG 检索;上传文件后,语义检索让 Agent 的回答锚定你的私有知识库
  • 插件 — 安装并管理第三方插件(octop plugin);内置插件随安装注入,按需在控制台一键启用

ACP(Agent Client Protocol)

Octop 支持两个方向的 ACP 集成:

  1. 入站 — 外部工具使用你的 Octop Agent

    octop acp --agent main   # 为 Zed、OpenCode 等提供 stdio ACP 服务
  2. 出站 — Octop 委派给外部编程 Agent

    • 控制台 → ACP(/acp):配置 Runner(按用户全局)
    • 为 Agent 启用 acp_runner 后,在对话中委派任务

内置出站 Runner 包括 OpenCode、CodeBuddy、Claude Code 和 Codex。

完整配置:docs/acp.md。

🧭 规划

以下是我们的中长期规划:

  • 资源共享池 — 构建技能 / 子智能体共享池,用户在创建专家时可直接取用,无需从零搭建。
  • 专家共享 — 支持用户将自有专家共享给其他用户使用,沉淀优秀配置、避免重复造轮子。
  • 浏览器与终端能力补全 — 增强浏览器技能录制(把操作流程录制为可复用技能),并完善终端 AI 助手能力。
  • AgentTeams — 支持协调者自主调度、编排多位专家,协同完成复杂多步骤任务。
  • 自进化能力 — 将日常对话自动沉淀为技能,让助手随使用不断成长。
  • PC / 移动端客户端 — 在 Web 控制台与 IM 通道之外,提供原生桌面与移动端应用。

规划会随社区发展动态调整,以上仅供参考。

🚀 快速开始

环境要求

  • macOS / Linux / Windows
  • 无需预先安装 Python — 安装脚本通过 uv 在 ~/.octop/ 下创建隔离的 Python 3.12 虚拟环境
  • 现代多核 CPU,并预留数 GB 内存供进程与模型/Embedding 缓存使用;磁盘需容纳数据库、Agent 工作区与文档语料

1. 安装

macOS / Linux — 一键安装(推荐):

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows(PowerShell):

irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

Windows(cmd) — 下载后运行,或从已克隆的仓库执行:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.bat -o install.bat
install.bat

安装完成后,请打开新终端,或重新加载 shell 配置:

source ~/.zshrc   # Zsh
# 或
source ~/.bashrc  # Bash

安装脚本会将 octop 加入 PATH(~/.octop/bin)。可选附加组件:

# 浏览器自动化(Playwright Chromium)
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras browser

# 飞书通道支持
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash -s -- --extras channels-feishu

完整安装选项见 scripts/README.md(--version、--from-source、--mirror 及 Windows 参数)。

Windows 用户:下载安装包 → 安装 → 打开即用 FreeOS(Octop壳+组织能力) — 从 GitHub Releases 下载:

平台 制品
Windows FreeOS-desktop-windows-amd64-<version>.exe(64 位)/ FreeOS-desktop-windows-arm64-<version>.exe(ARM64)— NSIS 安装程序,单进程 FreeOS + 宿主内 Organization;不捆绑也不自动拉起 openXYOS Node
macOS FreeOS-desktop-darwin-arm64-<version>.dmg(Apple 芯片)/ FreeOS-desktop-darwin-amd64-<version>.dmg(Intel)
Linux FreeOS-desktop-linux-amd64-<version>.tar.gz / FreeOS-desktop-linux-arm64-<version>.tar.gz
飞牛 NAS(FnOS) Octop-fnos-docker-<version>.fpk(依赖 Docker)/ Octop-fnos-native-<version>.fpk(无需 Docker)— 通过应用中心安装

桌面客户端说明见 desktop/README.md,飞牛打包指南见 fnos/README.md。独立商业组织站见 docs/org-export.md(freeos org export-standalone,默认导出完整 openXYOS 源码树),不是默认安装器里的第二套 Node。

备选 — PyPI(若你已自行管理 Python 环境):

pip install octop
# 可选:pip install "octop[browser]"
# 可选本地 ONNX Embedding 模型缓存(设置 → 模型 → 本地):pip install "octop[local-embedding]"
# 仅下载目录模型到 ~/.octop/embedding_models;不用于对话,也不接入 Memory。

从源码用 uv 开发时:

uv sync --extra local-embedding

2. 启动

# 前台运行(API + Web 控制台)
octop run

# 自定义主机与端口
octop run --host 0.0.0.0 --port 8088

# 注册为系统服务(systemd / launchd / Windows 服务)
octop service start

打开 **http://127.0.0.1:8088**。Docker 首次初始化会自动生成随机管理员密码(写入 /data/.octop/credential.txt),除非设置了 OCTOP_DEFAULT_PASSWORD。交互式 octop init / 设置向导会让你自行设置密码(至少 8 位,且同时包含字母和数字)。向导模型步默认先选本机 Ollama;知识库默认走本机文件夹 + ONNX 向量,云厂商与 ima 是可选项。详见 docs/user-guide.md。

Docker(推荐用于生产部署)

# 构建并启动
docker compose -f docker/docker-compose.yml up -d

# 或手动构建
bash docker/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<自定义强密码,留空则自动生成随机密码>" \
  octop:latest

打开 http://localhost:8088。首次初始化会创建管理员账号,并把凭据写入容器内 /data/.octop/credential.txt。未设置 OCTOP_DEFAULT_PASSWORD 时自动生成随机强密码;自行设置的密码须 ≥8 位且同时包含字母和数字(被应用密码策略拒绝的常见弱密码会自动回退为随机密码)。可通过 OCTOP_ADMIN_USERNAME 覆盖用户名。

密码策略: 至少 8 位,且同时包含字母和数字。

变量 默认值 说明
OCTOP_PORT 8088 HTTP 监听端口
OCTOP_DEFAULT_PASSWORD (未设置) 首次运行管理员密码(Docker 引导)。未设置 = 自动生成随机密码并写入 credential.txt
OCTOP_ADMIN_USERNAME admin 首次运行管理员用户名
OCTOP_DATA ~/.octop 宿主机数据目录(compose 挂载)

完整变量列表见 .env.example。

📑 目录

📦 安装方式

方式 平台 说明
远程一键安装 macOS / Linux curl …/octop/install.sh | bash
远程一键安装 Windows irm …/octop/install.ps1 | iex 或 install.bat
本地脚本 macOS / Linux bash scripts/install.sh
本地脚本 Windows scripts\install.bat 或 install.ps1
PyPI 全平台 pip install octop 或 pip install "octop[browser]"
Docker 全平台 docker/docker-compose.yml

所有安装脚本均在 ~/.octop/venv 创建隔离环境,并通过 ~/.octop/bin/octop 包装 CLI,不会影响系统 Python。

升级

octop update 只替换 wheel / 二进制,你的 ~/.octop/ 数据库、工作区、密钥与 config.json 均会保留:

octop update          # 获取并安装最新版 Octop,若已注册系统服务则自动重启

数据库结构会在下次启动时自动迁移;仅当设置向导提示需要迁移时才运行 octop init。跨版本升级前请务必先备份(octop backup)。

⚙️ 配置

所有运行时数据存放在 ~/.octop/。可通过 CLI 管理,也可直接编辑文件。

# LLM 供应商与模型
octop models
octop provider list

# IM 通道
octop channel list
octop channel install

# Skill(按 Agent)
octop skills list --agent main

# 定时任务
octop cron list
octop cron create --help

# 用户(管理员)
octop user list

支持的 LLM 供应商

本机优先: Ollama、本机 OpenAI 兼容端点(LM Studio / llama.cpp / vLLM)、本机 ONNX Embedding。云厂商(OpenAI 兼容 API、DashScope 等)是可选项 — 在向导或控制台「模型 → 本地」先配本机,再按需加云。

支持的通道

通道 所需凭证
飞书 App ID、App Secret
钉钉 App Key、App Secret
QQ Bot AppID、Token
Discord Bot Token
企业微信 Corp ID、Agent Secret
Web 控制台 默认启用

📖 CLI 参考

命令 说明
octop init 初始化 ~/.octop/(数据库、管理员、JWT 密钥)
octop run 前台启动 Octop
octop service start 安装并启动系统服务
octop service stop 停止系统服务
octop agent 创建、列出、启停 Agent
octop channel 安装与管理 IM 通道
octop chats REPL 与会话管理
octop acp 为 IDE 提供 stdio ACP 服务
octop cron 管理定时任务
octop models 供应商预设与模型解析
octop skills 按 Agent 启用/禁用 Skill
octop plugin 安装并管理第三方插件
octop backup 导出 / 恢复备份
octop clean 清理 CLI 状态或清空 ~/.octop/
octop update 检查并安装更新

完整参考:docs/cli.md。

🖥️ Web 控制台

octop run 启动后访问 **http://127.0.0.1:8088**。

Octop Web 控制台

  • 对话 — 与 Agent 实时聊天
  • Agent — 创建 Agent,选择专家库 / MBTI 人格,配置供应商
  • Connector — OAuth 应用与 MCP 网关
  • 通道 — IM 平台配置
  • 定时任务 — 可视化 Cron 管理
  • 知识库 — 管理文档语料与语义检索
  • 插件 — 安装、启用与配置插件
  • ACP — 配置出站编程 Agent Runner
  • 设置 — 用户、安全、TLS、系统

交互式 API 文档:**http://127.0.0.1:8088/api/docs**(默认关闭 — 在 config.json 中设置 "enable_api_docs": true 开启)

📁 数据目录

~/.octop/                          ← 安装与数据根目录
├── config.json                    # 进程配置(含可选 database 段)
├── octop.db                       # 默认 SQLite 控制面(用户、Agent、通道、定时任务 …)
├── secrets/                       # JWT 密钥、通道 Token
├── agents/<agent_id>/             # 各 Agent 工作区(SOUL.md、skills …)
├── security/tool_guard/           # Shell 命令允许/拒绝规则
├── logs/                          # 运行日志
├── venv/                          # uv 管理的 Python(安装脚本布局)
└── bin/octop                      # PATH 包装脚本 → venv/bin/octop

控制面也可改用 PostgreSQL(config.json → database,或 OCTOP_DATABASE_* / 首次设置向导)。控制面为 PostgreSQL 时,Agent 记忆默认复用同一 DSN(per-agent schema);若需继续用文件记忆,在 agent 配置里设 "memory": { "backend": { "type": "sqlite" } }。详见 docs/configuration.md 与 docs/adr/002-database-backends.md。

环境变量与 config.json 详见 docs/configuration.md。

🏗️ 架构

OctopServer
 ├─ DatabasePool         SQLite (WAL) 或 PostgreSQL
 ├─ SharedServices       依赖注入根 — 所有 repo 与配置
 ├─ ExpertCatalog        启动时扫描 agents/experts/library/
 ├─ UserManager
 │   └─ HarnessAgentManager(按用户)
 │       └─ AgentRuntime(按 Agent)
 │           ├─ HarnessAgent      Agent 运行时(harness-agent)
 │           ├─ HarnessProcessor  IM / UI / 定时任务入口
 │           ├─ ChannelManager    IM 连接(harness-gateway)
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)

单进程架构。重启后从控制面数据库重建状态(默认本地 SQLite;可选 PostgreSQL)。

详见 docs/architecture.md、docs/adr/001-single-process-model.md 与 docs/adr/002-database-backends.md。

产品意图(工作室比喻、Node 只是桥)见 docs/product-contract.zh-CN.md。组织模块目标架构(Dashboard 子 UI + 可导出独立站,单源双交付)见 docs/adr/003-org-ui-single-source-dual-delivery.md 与 docs/org-merge-plan.md(先读文首 Historical vs Current)。

📁 项目结构

src/octop/
  config.py    环境变量配置
  launch.py    OctopServer 启动 + uvicorn
  infra/       业务核心(agents、gateway、cron、db、users …)
  api/         HTTP 层 — FastAPI 路由、JWT、SSE
  cli/         CLI 层 — Click 命令
  dashboard/   构建后的 React SPA(wheel 产物)

dashboard/     前端源码(Vite)— 在此编辑,运行 make build-frontend

docker/        Docker Compose、入口脚本、构建与部署脚本
tests/         unit/ + integration/

🛠️ 开发

前置条件: Python 3.12+、Node 18+、uv

# 后端
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test(发布门槛)

# 前端(另开终端)
make dev-frontend     # Vite 开发服务器 :5173
make build-frontend   # 生产构建 → src/octop/dashboard/
cd dashboard && npx tsc --noEmit

单独执行:make test、make lint、make typecheck、make format。

🔒 安全与隐私

  • 本地优先:配置、对话、工作区与凭证均存储在 ~/.octop/。
  • 多用户隔离:JWT 认证,按用户隔离 Agent 与工作区。
  • 敏感信息脱敏与工具审批:离开工作区前自动脱敏敏感数据;高风险工具或 Shell 命令需依据护栏规则显式审批。
  • 工具护栏:可在 ~/.octop/security/tool_guard/ 编辑 Shell 命令规则。
  • 无厂商锁定:可自由切换 LLM 供应商、存储后端与 IM 通道。

🤝 参与贡献

欢迎贡献代码:

  1. Fork 本仓库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交前运行 make all(后端)或 make check-all(全栈)
  4. 发起 Pull Request

完整指南见 CONTRIBUTING.md。安全问题见 SECURITY.md。

模块边界与编码规范见 AGENTS.md。

📋 更新日志

详见 CHANGELOG.md。

🔗 相关项目

项目 描述
harness-agent Agent 运行时 — 模型路由、工具、Skill、检查点
harness-gateway 多平台 IM 通道桥接
harness-memory 层级召回与全文搜索
harness-browser CDP 浏览器自动化,支持 profile 持久登录

这些 harness-* 项目正在筹备开源中,仓库地址将在发布后补充。

💬 客户企业微信群

如需加入客户企业微信服务群,请扫码:

客户企业微信服务群二维码

请扫码进入工作群,如有任何疑问或需求,请直接联系群管理员对接处理。

📄 许可证

本项目采用 MIT License。

✨ 贡献者

感谢所有贡献者: