# star-orchestrator

一个**本地优先、可自控**的智能体编排框架：把「大模型决策」与「真实动作执行」彻底分层，
让 LLM 只负责选技能与填参数，所有副作用都经过**显式技能注册表 + 风险确认闸门**后才发生。

- 编排层用 Python 标准库 `http.server` 起服务（零框架依赖）；
- 执行层用 FastAPI/uvicorn，只接受 `skill_id + args`，**不做意图解析**；
- MCP / A2A 协议接入全部**手写 JSON-RPC over Streamable HTTP**，不引入官方 SDK；
- 内置 SSRF/越权/危险命令拦截、长期记忆、本地 LLM 故障兜底、SSE 流式与心跳。

```
用户 / 外部智能体 / Bot
        │
        ▼
┌──────────────────────────┐        ┌──────────────────────────┐
│ orchestrator  :8700      │        │ exec  :8730              │
│ 唯一对话层                │        │ 技能引擎                  │
│ · Function Calling 循环  │──────▶ │ · config 注册表驱动        │
│ · SSE 流式 + 心跳         │ skill  │ · risk=confirm 二次确认   │
│ · 参数护栏 arg_guard      │ + args │ · 危险命令/敏感路径拦截    │
│ · 长期记忆 / 本地 LLM 兜底│        │ · ResultEnvelope 统一返回  │
└──────────────────────────┘        └──────────────────────────┘
        │ mcp_ 前缀                          ▲
        ├─────────────▶ 外部 MCP Server      │
        │ a2a_ 前缀                          │
        └─────────────▶ 外部 A2A Agent       │
                                     config/super_connector.json
```

## 目录结构

```
star-orchestrator/
├── orchestrator/              编排层（8700）
│   ├── main.py               入口
│   ├── config.yaml           非敏感配置（凭据一律走环境变量）
│   ├── api/gateway_api.py    HTTP 网关 + FC 工具循环 + SSE
│   ├── adapters/             LLM / 执行层 / 可选外部大脑适配器
│   ├── router/               路由、参数护栏、tools schema、MCP、A2A
│   ├── storage/              会话记忆 + 长期记忆（SQLite）
│   ├── services/             平台化（审计/计价/健康）+ 通用查询服务
│   └── utils/                配置加载、trace
├── exec/                     执行层（8730）
│   ├── server.py             FastAPI 入口：鉴权 / 技能 / SSE
│   ├── auth.py               多用户认证（PBKDF2 + 会话 + 模块授权）
│   └── super_connector.py    技能引擎（handler 注册表 + 风险闸门）
├── config/super_connector.json   技能注册表（唯一扩展点）
├── examples/custom_skill.py      最小可运行的自定义技能示例
├── desktop/                      桌面壳源码（Swift + WKWebView / Tauri）
├── scripts/start.sh              一键启动两层
├── scripts/oss/audit_public.py   敏感信息闸门（CI 与发布前共用）
└── tests/                        176 个用例（全离线可跑）
```

## 快速开始

```bash
git clone https://github.com/<your-account>/star-orchestrator.git
cd star-orchestrator

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env      # 按需填入 DEEPSEEK_API_KEY 等凭据

./scripts/start.sh        # 同时起 8700（编排层）与 8730（执行层）
```

验证：

```bash
curl http://127.0.0.1:8730/api/health     # 执行层（loopback 免登录）
curl http://127.0.0.1:8730/api/skills     # 技能清单（由注册表派生）
curl http://127.0.0.1:8700/health         # 编排层双引擎状态
```

跑测试（无需任何外部服务与网络）：

```bash
python3 -m pytest tests/ -q        # 176 passed
python3 scripts/oss/audit_public.py  # 敏感信息闸门
```

## 端口表

| 端口 | 服务 | 说明 |
|---|---|---|
| 8700 | `orchestrator/main.py` | 唯一对话层：路由、FC 循环、SSE、记忆 |
| 8730 | `exec/server.py` | 执行层：技能清单 / 执行 / 确认闸门 / 唤醒 SSE |

所有地址与端口均可用环境变量覆盖，详见 `.env.example`。

## 内置技能

技能由 `config/super_connector.json` 单一权威源定义，`risk=read` 免确认直接执行，
`risk=confirm` 必须先经二次确认闸门。

| 分类 | 技能 |
|---|---|
| 信息获取 | `web_search`、`web_fetch`、`weather`、`news`、`stock_query` |
| 出行/消费 | `travel_query`、`train_query`、`price_compare` |
| 办公 | `send_mail`（confirm）、`calendar_query`、`task_query`、`task_create`（confirm）、`task_complete`（confirm） |
| 创作 | `img_gen`、`visual_analyze` |
| 桌面操作 | `run_command`（confirm）、`file_read_write`（confirm）、`app_launch`、`app_control`（confirm）、`screen_analyze`、`code_exec`（confirm） |
| 系统 | `sys_status` |

新增技能见 [docs/SKILLS.md](docs/SKILLS.md)，可直接照抄 `examples/custom_skill.py`。

## 协议接入

- **MCP（作为 Host/客户端）**：在 `orchestrator/config.yaml` 的 `mcp.servers` 白名单里声明外部
  MCP Server，工具会以 `mcp_<server>_<tool>` 前缀并入 Function Calling 面板。详见 [docs/MCP.md](docs/MCP.md)。
- **A2A（Agent 联邦）**：在 `a2a.servers` 声明外部 Agent，其技能以 `a2a_<agent>_<skill>` 前缀暴露；
  默认只读委托，`allow_write=false` 时写操作会被拒绝。详见 [docs/A2A.md](docs/A2A.md)。

两者均为手写 JSON-RPC over Streamable HTTP，无第三方 SDK 依赖。

## 安全模型

- **分层纪律**：执行层不接受自然语言，只接受 `skill_id + args`；意图解析归编排层。
- **风险闸门**：`risk=confirm` 技能生成一次性令牌，用户确认后才真正执行。
- **参数护栏**：`orchestrator/router/arg_guard.py` 在执行前拦截 SSRF（内网 URL）、
  家目录越权读写、非法枚举取值、空参数等。
- **命令与路径**：`exec/super_connector.py` 内置危险命令正则与敏感目录黑名单。
- **凭据**：任何 api_key / 令牌 / 口令都只从环境变量读取，`config.yaml` 全为空串占位。
- **发布闸门**：`scripts/oss/audit_public.py` 在 CI 与发布前扫描全仓，命中敏感信息即非零退出。

> ⚠️ 本框架默认提供**终端执行 / 文件读写 / 代码执行**等高权限技能。请仅在受控环境运行，
> 并遵循 [SECURITY.md](SECURITY.md) 中的部署建议。

## 文档

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 分层、数据流、扩展点
- [docs/SKILLS.md](docs/SKILLS.md) — 技能开发指南
- [docs/MCP.md](docs/MCP.md) — 作为 MCP Host 接入外部 Server
- [docs/A2A.md](docs/A2A.md) — Agent 联邦与委托语义
- [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) — 部署与进程编排
- [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南

## 许可

MIT，见 [LICENSE](LICENSE)。