内容
# Synapse_OS
<p align="center">
<b>感知运算 V1</b><br/>
面向项目执行、流程控制、记忆连续性和评估驱动质量的智能体优先操作系统。
</p>
<p align="center">
<img src="https://img.shields.io/github/last-commit/venkata2894/Synapse_OS?style=flat-square" alt="最后提交" />
<img src="https://img.shields.io/github/stars/venkata2894/Synapse_OS?style=flat-square" alt="星标" />
<img src="https://img.shields.io/github/issues/venkata2894/Synapse_OS?style=flat-square" alt="问题" />
<img src="https://img.shields.io/badge/status-%E6%99%BA%E8%83%BD%E4%BD%93%E6%89%8B%E6%89%88%E5%B9%B3%E5%8F%B0-0f9d8a?style=flat-square" alt="状态" />
</p>
## 愿景
`Synapse_OS` 是多智能体项目的操作系统基础。
它规范了管理智能体如何协调工作智能体，保留了长期任务链的上下文，并为所有者提供了一个透明的执行质量控制室。
## 为什么存在
- 多智能体系统在长工作流程中会丢失上下文。
- 交接不一致且通常信号较弱。
- 所有者缺乏对执行质量的一致且项目级的可见性。
- 评估很少是首要且可审计的。
Synapse_OS 通过结构化工作流程、持久内存和评估驱动评分来解决这个问题。
## 当前范围
- 面向 `FastAPI` 后端 + `Next.js` 前端的生产型单体仓库。
- 具有看板、任务检查器、评估、工具控制台和专用运维控制台的智能体优先工作流程引擎。
- V1 操作规则的强策略防护。
- 具有原始和精选推广模型的内存架构。
- 面向实时本地堆栈的 OpenAI 测试智能体。
- 智能体操作文档（`AGENTS.md`、`PRIMER.md`、`NEXT.md`、`CLAUDE.md`）。
## 系统快照
```mermaid
flowchart LR
O[所有者 / 监督者] --> W[Web 控制台 + 运维控制台<br/>Next.js + Tailwind + Clerk]
W --> A[API 层<br/>FastAPI /api/v1]
A --> P[(PostgreSQL)]
A --> Q[(Qdrant)]
A --> E[评估队列]
E --> S[记分卡 + 见解]
A --> M[项目内存检索]
```
## 技术栈
| 层 | 选择 |
|---|---|
| 后端 | Python, FastAPI, SQLAlchemy, Alembic |
| 前端 | Next.js, Tailwind CSS |
| 身份验证 | Clerk |
| 关系数据库 | PostgreSQL |
| 向量数据库 | Qdrant |
| 包/工作区 | pnpm 单体仓库 |
## 单体仓库布局
```text
apps/
api/ # FastAPI 应用、模式、策略、alembic
web/ # Next.js 应用壳、仪表盘路由、身份验证中间件
tester/ # OpenAI 智能体 SDK UAT 夹持 + Playwright 浏览器工具
packages/
contracts/ # 共享 TS 合同 + OpenAPI 生成脚手架
ops/ # Docker compose + 引导/开发脚本
docs/ # 架构和 ADR
memory/ # 决策、交接、运行手册、研究、变更日志
```
## 已实现功能
- 工作流程驱动的任务生命周期：
`接收 -> 就绪 -> 已分配 -> 进行中 -> 等待交接 -> 审查中 -> 评估 -> 已完成`
- 侧状态：
`阻塞`、`重新打开`
- 智能体优先 UI：
仪表盘、项目、运维、任务、智能体、评估、工具控制台
- 项目运维控制台：
项目范围的员工分配、经理插槽分配、项目智能体附加/分离/创建、最近活动动态
- 无缝结构化日志：
在项目运维和任务检查流程中共享的快速日志编辑器
- 实时基础：
SSE 流 + 轮询回退，用于仪表盘、员工分配和工作日志活动表面
- 身份验证模式：
Clerk 用于应用用户，智能体 API 密钥用于 `/agent-tools`，本地测试身份验证用于 UAT
- 测试：
OpenAI 测试智能体模拟现实的项目负责人和工人，锻炼 API/MCP/UI 包括 `/operations`，并生成报告
## 快速入门（Windows / PowerShell）
```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .\apps\api[dev]
.\\.venv\\Scripts\\python.exe -m pip install -e .\\apps\\tester
npm install -g pnpm@10.18.0
pnpm install
pnpm dev:api
pnpm dev:web
```
对于无 Docker 的本地运行，设置：
```env
DATABASE_URL=sqlite:///./sentientops.db
```
## API 接口
命名空间：`/api/v1`
- `projects`：创建/更新/存档 + 经理指定 + 项目员工读取模型
- `agents`：注册/更新/状态 + 项目附加/分离流程
- `tasks`：创建/分配/认领/转换/状态/依赖
- `worklogs`：追加结构化条目 + 过滤的项目/任务/智能体活动读取
- `handovers`：创建 + 时间线检索
- `memory`：获取/搜索/推广
- `evaluations`：请求/提交/所有者覆盖（审计）
- `agent-tools`：面向 AI 智能体的机器导向工具调用 API
- `boards`：工作流程通道和卡片的 Kanban 读取模型
- `events`：项目活动的 SSE 事件流
- `process`：默认流程模板/引导
## 智能体优先集成
智能体身份验证（推荐）：
```http
Authorization: Bearer soa_dev_agent_key
```
发现工具：
```bash
curl http://localhost:8000/api/v1/agent-tools/manifest \
-H "Authorization: Bearer soa_dev_agent_key"
```
调用工具：
```bash
curl -X POST http://localhost:8000/api/v1/agent-tools/create_project \
-H "Authorization: Bearer soa_dev_agent_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-project-001" \
-d '{
"name": "Project Atlas",
"description": "Agent-run delivery workflow",
"objective": "Build V1 vertical slice",
"owner": "owner-1",
"status": "active",
"tags": ["agentic", "v1"]
}'
```
## MCP 兼容性
- 当启用时，MCP 服务器安装在 `/mcp` 上。
- 通过 MCP 暴露相同的后端工具（`tool_manifest`、`call_tool`）。
- 运行 stdio MCP 服务器：
```powershell
.\.venv\Scripts\python.exe -m app.mcp.server
```
## V1 防护
- 每个项目一个经理。
- 仅分配工人才能认领任务。
- 完成可以触发评估工作流程。
- 所有者覆盖允许具有不可变审计历史。
- 混合内存推广（建议 + 批准）。
- 子任务自主权允许具有可配置限制。
## 文档索引
- [产品简介](./PRIMER.md)
- [智能体操作合同](./AGENTS.md)
- [当前执行队列](./NEXT.md)
- [智能体集成架构](./docs/architecture/agent-integration.md)
- [OpenAI 测试夹持](./docs/architecture/openai-uat-harness.md)
- [公开路线图](./ROADMAP.md)
- [展示笔记](./SHOWCASE.md)
## 验证
- 后端测试：`15 passed`
- Web 构建：生产构建在本地通过
- UAT 夹持：OpenAI 测试智能体在 `reports/uat/` 下生成 Markdown + JSON 报告
## 构建笔记
- Clerk 身份验证对于应用程序路由严格（`/`、`/projects`、`/operations`、`/tasks`、`/agents`、`/evaluations`、`/tools`）。
- 必须配置 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY` 以进行运行时访问。
- 前端包括一个完整的运算符 UI：仪表盘、项目、运维、任务（Kanban + 检查器）、智能体、评估、工具控制台。
## OpenAI 测试智能体
- 新测试夹持位于 `apps/tester`，使用 OpenAI 智能体 SDK 和 Playwright 进行 UAT 模拟。
- 根命令：
- `pnpm qa:uat`
- `pnpm qa:uat:blocked`
- `pnpm qa:uat:agent`
- `pnpm qa:uat:ux`
- 报告写入 `reports/uat/`，包括 JSON 和 Markdown 输出以及可选截图。
- 本地浏览器 UAT 设计为在 `apps/web/.env.local` 中使用 `SENTIENTOPS_TESTER_AUTH_MODE=local_bypass` 运行。
## 当前关注点
- 收集新运维控制台和员工工作流程的首次测试反馈
- 加固评估队列处理器和工人自动化
- 提高浏览器-UAT 可靠性和智能体人体工程学
- 扩展 SSE 覆盖范围并加强工作流程交互润色
## 迈向 MVP 之路
参见 [`ROADMAP.md`](./ROADMAP.md)，了解从基础脚手架到完整端到端试点的计划进度。
