内容
# SoulOS
**为你已有的代理添加身份和记忆模块** — 验证的人格（HEXACO MSV）、情景记忆（pgvector）和混合API，让现有的LLM（包括Bedrock、OpenAI、LiteLLM）继续生成内容，而SoulOS负责管理和更新人格、记忆和MSV漂移。
给你的机器人一个 **灵魂文件**，而不是一个脆弱的系统提示。 主要路径：**`ensure_avatar → prepare → your LLM → complete`**。 完整的SSE聊天、MCP和Soul Studio仍然受支持。
<p align="center">
<a href="https://github.com/mziqudhd92/soul-os/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/mziqudhd92/soul-os/ci.yml?branch=main&label=CI" alt="CI"/></a>
<a href="https://github.com/mziqudhd92/soul-os/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License MIT"/></a>
<a href="https://mziqudhd92.github.io/soul-os/"><img src="https://img.shields.io/badge/Tutorials-online-6d28d9" alt="Tutorials"/></a>
</p>
**教程（交互式）** · [GitHub Pages](https://mziqudhd92.github.io/soul-os/) · [Python 机器人指南](docs/guides/python-bot.md) · [完整文档](docs/README.md) · [FAQ](#faq)
## 信任与采用
SoulOS 在开放环境中维护，以便您可以在依赖它之前进行检查、fork 和自我托管。
| | |
|---|---|
| **许可证** | [MIT](LICENSE) — 内核、SDK、Studio、示例 |
| **CI** | 每次推送到 `main` 的测试（[工作流](https://github.com/mziqudhd92/soul-os/actions/workflows/ci.yml)) |
| **安全** | 私密报告漏洞 — [SECURITY.md](SECURITY.md) |
| **行为准则** | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
| **贡献** | [CONTRIBUTING.md](CONTRIBUTING.md) · [SUPPORT.md](SUPPORT.md) |
| **第三方** | 上游许可证（例如 ClawSouls 人格）— [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) |
### 生产采用者
独立产品在生产环境中使用SoulOS进行 **持久化人格和情景记忆**。 完整配置文件（适用于人类、爬虫和代理）： **[docs/adopters.md](docs/adopters.md)** · JSON索引： **[docs/adopters.json](docs/adopters.json)**
| 产品 | 网站 | 他们构建的内容 | SoulOS 在生产环境中的应用 |
|---------|---------|-----------------|----------------------|
| **SignalPR** | [https://signalpr.pro/](https://signalpr.pro/) | AI 原生 PR 服务 — 媒体事件雷达、新闻jacking角度、记者向量RAG、 outreach 到 Instantly / Apollo | 混合 sidecar：记忆、人格 MSV、 [`/hybrid/prepare`](docs/reference/hybrid-api.md) / [`/complete`](docs/reference/hybrid-api.md) 与 Bedrock + pgvector |
| **Aeterna** | [https://helloaeterna.com/](https://helloaeterna.com/) | 数字遗产 — AI 生命周期访谈、加密语音存档、家庭问答、数字孪生 | 持久化叙述者人格 + 跨会话的情景记忆 |
| **Ved Travel** | [https://www.ved-travel.co.il/](https://www.ved-travel.co.il/) | 家庭克罗地亚旅行专家 — 适合儿童的行程、隐藏的海滩、岛屿、国家公园和 AI 行程规划（由 Vedrana 整理） | 持久化旅行顾问人格 + 多轮次行程规划的情景记忆 |
这些是 **独立公司**；列表描述的是实际集成，而不是相互认可。 SoulOS 是 MIT 许可的开源软件 — 在依赖它之前，请检查、fork 和自我托管。
独立团队在除非他们使用通过网关的SoulOS Cloud，否则他们会在本地托管内核。 要被列出，请打开一个PR，更新 [docs/adopters.md](docs/adopters.md) 和 [docs/adopters.json](docs/adopters.json)。
---
## 新来者？先做这个
**您需要：** [Docker](https://docs.docker.com/get-docker/) （Docker Desktop 或 Engine）。 可选：Python 3.12+ 用于仅限 Studio 的模式。
### 1. 运行堆栈
```bash
git clone https://github.com/mziqudhd92/soul-os.git
cd soul-os
docker compose up --build
```
等待内核启动（第一次构建可能需要几分钟）。
| 服务 | URL | 它做什么 |
|---------|-----|----------------|
| **内核** | http://localhost:8000 | API、聊天 SSE、MCP |
| **Soul Studio** | http://localhost:8765 | 构建灵魂、教程、测试聊天 |
| **网关** （可选） | http://localhost:8080 | 云风格 API 代理 |
### 2. 选择学习方式
| 我想… | 从这里开始 | 时间 |
|------------|------------|------|
| **将 SoulOS 添加到现有的 LLM 应用中** （推荐） | [Sidecar 集成](docs/guides/sidecar-integration.md) · [混合 API](docs/reference/hybrid-api.md) | ~20 分钟 |
| **将 SoulOS 集成到我的 Python 机器人中** | [交互式教程](https://mziqudhd92.github.io/soul-os/?tutorial=python-bot) 或 [Python 机器人指南](docs/guides/python-bot.md) | ~25 分钟 |
| **在 UI 中点击** | 打开 http://localhost:8765 → **向导** 或 **教程** | ~15 分钟 |
| **使用 curl 测试 API** （无需代码） | [快速入门路径 A](docs/getting-started/quickstart.md#path-a) | ~10 分钟 |
| **从 Cursor / Claude 使用 SoulOS** | [MCP 指南](docs/guides/mcp.md) → `http://localhost:8000/mcp/sse` | ~15 分钟 |
| **在自己的服务器上部署** | [插入 SoulOS](docs/guides/plug-in-soulos.md) · [自我托管](docs/deployment/self-hosted.md) | ~15 分钟 |
| **使用 ClawSouls 人格** | [ClawSouls 导入](docs/guides/clawsouls-import.md) · Studio **ClawSouls** 选项卡 | ~10 分钟 |
### 3. 五分钟 sidecar（混合）
```bash
docker compose -f docker-compose.sidecar.yml --profile bridge-mock up -d
npm run smoke:hybrid # ensure → doctor → prepare → print system prompt
```
或手动：
```bash
# 确保头像启动
curl -s -X POST http://localhost:8001/v1/avatars/ensure \
-H "Content-Type: application/json" \
-d '{"external_key":"demo-bot","soul":'"$(cat examples/support-bot/support-bot.soul.json)"'}'
# 准备（返回您的 LLM 的系统提示）
curl -s -X POST http://localhost:8001/hybrid/prepare \
-H "Content-Type: application/json" \
-d '{"bot_id":"<BOT_ID>","query":"What is the refund policy?"}'
```
在 SoulOS 永远不应该调用聊天模型时设置 `INFERENCE_MODE=embeddings_only`。 请参阅 [身份模型](docs/guides/identity-model.md)。
### 4. 完整聊天烟雾测试（次要路径）
```bash
# 注册示例支持机器人（JSON）
curl -s -X POST http://localhost:8000/v1/avatars \
-H "Content-Type: application/json" \
-d @examples/support-bot/support-bot.soul.json
# 保存返回的 "id" 为 BOT_ID，然后教一个事实：
curl -X POST http://localhost:8000/memory/ingest \
-H "Content-Type: application/json" \
-d '{"bot_id":"<BOT_ID>","content":"Refunds within 30 days of purchase."}'
# 流式传输回复（SSE）
curl -N -X POST http://localhost:8000/chat/generate \
-H "Content-Type: application/json" \
-d '{"bot_id":"<BOT_ID>","message":"Can I get a refund?"}'
```
您应该看到 `event: message` 块和可选的 `event: msv_update` / `event: cognitive_state` 行。
---
## 什么是 SoulOS？
SoulOS **不是** 聊天界面，也 **不是** 您LLM的替代品。 它是位于您的应用程序和模型之间的层：
- **人格** — 验证的 `.soul` / `.soul.json` 文件中的 HEXACO 心理测量指标；每轮状态漂移（`msv_update`）。
- **记忆** — Postgres/pgvector 中的情景事实；可选的 `.soul-memory/` git 账本 + 同步 API。
- **编排** — 双过程路由（快速 System 1 流 + System 2 反射，当不确定性高时）。
- **集成** — REST + SSE、Python/`@soulos/sdk`、MCP 工具在 `/mcp/sse`。
**典型用例：** 客户支持机器人、开发助手、伴侣、Cursor/Claude 代理，具有持久身份和回忆。
---
## Soul Studio
用于设计灵魂、阅读文档和运行 **交互式教程** （动画、SSE 游乐场、逐步代码）的浏览器界面。
```bash
# 包含在 docker compose 中，或单独运行（内核必须在 :8000 上）：
pip install -e packages/soulos-studio
soulos-studio
```
- 本地：http://localhost:8765
- 在线教程（无需 Docker）：https://mziqudhd92.github.io/soul-os/
Studio 可以 **导出** `.soul` 和 `.soul.json`，**部署** 到内核，并 **测试聊天** 与认知轨道。
指南： [Soul Builder](docs/getting-started/soul-builder.md)
---
## Python 集成（草图）
```python
import asyncio
from soulos.client import SoulOSClient
async def main():
soul = SoulOSClient(base_url="http://localhost:8000")
avatar = await soul.register_avatar("examples/support-bot/support-bot.soul")
avatar_id = avatar["id"]
await soul.ingest_memory(avatar_id, "Refunds within 30 days.")
parts = []
async for event in soul.send_message(avatar_id, "Can I get a refund?"):
if event["type"] == "message":
parts.append(event["text"])
if event["type"] == "cognitive_state":
print("path:", event.get("current_path"))
print("".join(parts))
asyncio.run(main())
```
完整演练： [Python 机器人集成](docs/guides/python-bot.md)
---
## TypeScript / Node
```bash
npm install @soulos/sdk # from monorepo: npm run build:sdk
```
```typescript
import { SoulOSClient } from "@soulos/sdk";
import { registerAvatarFromFile } from "@soulos/sdk/node";
const soul = new SoulOSClient({ baseUrl: "http://localhost:8000" });
const { id } = await registerAvatarFromFile(soul, "./examples/support-bot/support-bot.soul.json");
for await (const e of soul.sendMessage(id, "I need a refund")) {
if (e.type === "message") process.stdout.write(e.text);
}
```
云：`new SoulOSClient({ apiKey: process.env.SOULOS_API_KEY })`
---
## MCP（Cursor，Claude Desktop）
运行 `docker compose up`：
```text
http://localhost:8000/mcp/sse
```
工具包括 `ingest_memory`、`retrieve_memory`、`get_identity`、`register_avatar` 等。 聊天流使用 REST/SDK 而不是 MCP。
- [MCP 指南](docs/guides/mcp.md)
- [examples/mcp](examples/mcp/README.md)
---
## 架构
```mermaid
flowchart LR
subgraph app [您的应用]
Bot[Bot / IDE / UI]
end
subgraph soulos [SoulOS 内核 :8000]
API[FastAPI]
MSV[HEXACO MSV]
Mem[pgvector 内存]
end
LLM[Ollama 或推理桥]
Bot --> API
API --> MSV
API --> Mem
API --> LLM
```
| SSE 事件 | 含义 |
|-----------|---------|
| `message` | 模型令牌/块 |
| `msv_update` | 人格状态漂移（例如认知不确定性） |
| `cognitive_state` | System 1 与 System 2 路径、延迟、置信度 |
详情： [API 参考](docs/reference/api.md) · [心理测量学](docs/guides/psychometrics.md)
---
## 仓库布局
```text
packages/soulos-core/ 内核 API + MCP → :8000
packages/soulos-studio/ Soul Studio UI → :8765
packages/soulos-gateway/ 云网关 → :8080
packages/soulos-sdk/ TypeScript + Python 客户端
examples/ support-bot, dev-twin, companion
spec/soul.schema.json 灵魂文件 JSON 模式
docs/ 指南、参考、部署
```
---
## 示例
| 文件夹 | 角色 |
|--------|------|
| [examples/fastapi-hybrid](examples/fastapi-hybrid/) | FastAPI 边车：ensure → prepare → LLM → complete |
| [examples/sidecar-compose](examples/sidecar-compose/) | 编排 SoulOS 位于您的 API 旁边 |
| [examples/hybrid-orchestrator](examples/hybrid-orchestrator/) | 混合客户端模式（LiteLLM / 自定义 SSE） |
| [examples/support-bot](examples/support-bot/) | 客户支持 + `.soul-memory/` |
| [examples/dev-twin](examples/dev-twin/) | 开发助手 |
| [examples/companion](examples/companion/) | 个人伴侣 |
| [examples/clawsouls](examples/clawsouls/) | ClawSouls 导入元数据 + 帮助程序 |
| [examples/clawsouls-sidecar](examples/clawsouls-sidecar/) | 边车堆栈上的 ClawSouls 人格 |
| [examples/mcp](examples/mcp/) | Cursor MCP 工作流程 |
```bash
npm run seed # 可选的演示数据
npm run test:all # 内核 + 桥 + 网关 + studio + sdk
```
---
## 文档
| 主题 | 链接 |
|-------|------|
| 文档索引 | [docs/README.md](docs/README.md) |
| 教程索引 | [docs/tutorials/README.md](docs/tutorials/README.md) |
| 更新日志 | [CHANGELOG.md](CHANGELOG.md) |
| 测试 | [docs/testing.md](docs/testing.md) |
| 快速入门（两个头像） | [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md) |
| 灵魂文件格式 | [docs/reference/soul-standard.md](docs/reference/soul-standard.md) |
| 部署 | [docs/deployment/README.md](docs/deployment/README.md) |
| 用于 AI 代理 | [llms.txt](llms.txt) · [AGENTS.md](AGENTS.md) |
贡献： [CONTRIBUTING.md](CONTRIBUTING.md) · 行为准则： [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
---
## FAQ
<details>
<summary><strong>SoulOS 解决了什么问题？</strong></summary>
静态系统提示会忘记上下文并在语气上漂移。 SoulOS 为每个头像提供了一个持久的灵魂基线、语义记忆和可测量的状态，该状态在每次对话时都会更新。
</details>
<details>
<summary><strong>什么是 .soul 文件？</strong></summary>
统一格式： **YAML 前置 + Markdown** 正文（编译为与 `.soul.json` 相同的模式）。 定义名称、角色、HEXACO `baseline_msv`、附件样式和行为文本。 由 [spec/soul.schema.json](spec/soul.schema.json) 验证。 请参阅 [Soul 标准](docs/reference/soul-standard.md)。
</details>
<details>
<summary><strong>SoulOS 是否取代我的 LLM？</strong></summary>
不。 SoulOS 协调人格、记忆和路由。 推理使用 Ollama 本地（默认）或 [Ollama 兼容的推理桥](docs/deployment/inference.md) 用于 AWS Bedrock / GCP Vertex — 而不是原始 OpenAI `/v1` URL。
</details>
<details>
<summary><strong>自我托管 vs 云？</strong></summary>
相同的 SDK 表面。 自我托管：内核位于 `:8000`。 云：通过网关的 API 密钥。 请参阅 [部署文档](docs/deployment/README.md)。
</details>
<details>
<summary><strong>GitHub Pages 教程 vs 本地 Studio？</strong></summary>
[GitHub Pages](https://mziqudhd92.github.io/soul-os/) 托管只读教程（包括交互式 Python 机器人演练）。 启用一次：存储库 **设置 → 页面 → 分支 `gh-pages`** / 根目录。 本地 Studio 添加了灵魂构建、内核部署和实时聊天 — 运行 `docker compose up`。
</details>
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。 第三方角色内容（例如 [ClawSouls](https://clawsouls.ai) 导入）仍受上游许可证约束 — 参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器