内容
# 星云
**适用于 AI 代理的 Stellar 钱包** —托管、策略和支付，允许代理在链上使用 USDC，无需持有私钥。
生产环境：[nebulaonchain.xyz](https://nebulaonchain.xyz)
---
## 架构
私钥永远不会离开 Hub。代理和 MCP 客户端只会呈现 `nbl_live_…` token（或 OAuth）。Hub 强制执行策略，在需要时确认转账，使用 Privy 签名，并提交给 Stellar。
```mermaid
flowchart TB
subgraph clients [客户端]
CD[Claude 桌面版 / 游标]
CC[Claude 代码]
RM[远程 MCP / OAuth]
end
subgraph npm [MCP 包]
STDIO["@nebula/mcp<br/>stdio → Hub HTTP"]
end
subgraph hub [星云 Hub — apps/nebula-hub]
UI[仪表盘 · 策略 · 审批 · 连接]
API["/api/tools/* · /api/wallet · /api/agents"]
MCP["POST /mcp · OAuth DCR"]
PIPE[工具管道 + 确认]
PRIVY[Privy 嵌入式 Stellar 钱包]
end
subgraph chain [Stellar]
POL[策略合约]
NET[支付 · x402 · MPP · Blend]
end
subgraph data [数据]
SB[(Supabase Postgres)]
end
CD --> STDIO
CC --> STDIO
STDIO -->|"NEBULA_TOKEN"| API
RM --> MCP
MCP --> PIPE
API --> PIPE
UI --> API
PIPE --> PRIVY
PIPE --> POL
PRIVY --> NET
PIPE --> SB
UI --> SB
```
| 层级 | 角色 |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| **Hub** (`apps/nebula-hub`) | Next.js 应用：Privy 身份验证 + 托管，仪表盘，工具 API，远程 Streamable HTTP MCP |
| `**@nebula/core**` | 共享 Zod 工具模式 + 确认 / 策略矩阵 |
| `**@nebula/mcp**` | 薄 stdio MCP 客户端 → Hub (`npx @nebula/mcp` 发布时) |
| **Landing** (`apps/landing`) | 营销网站；内置于 Hub `public/landing` 部署 |
| **策略合约** (`contracts/policy`) | 链上支出上限 / 金库频段，当 `POLICY_CONTRACT_ID` 设置 |
详情和状态表：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
---
## 单体仓库
```
nebula/
├── apps/
│ ├── nebula-hub/ # 托管中心（仪表盘 + API + /mcp）
│ └── landing/ # 营销网站 → hub public/landing
├── packages/
│ ├── nebula-core/ # @nebula/core
│ └── nebula-mcp-stdio/ # @nebula/mcp （二进制：nebula）
├── contracts/policy/ # Soroban 策略
└── docs/
```
参阅 [docs/STRUCTURE.md](docs/STRUCTURE.md)。
---
## 快速开始
```bash
pnpm install
# Hub 本地运行（需要 apps/nebula-hub/.env.local — 从 .env.example 复制）
pnpm --filter @nebula/core build
pnpm --filter nebula-hub dev # http://localhost:3000
# 可选：单独运行营销网站
pnpm --filter @nebula/core build && pnpm --filter nebula-landing build
pnpm --filter nebula-landing preview
```
**数据库：** Supabase Postgres — [docs/SUPABASE.md](docs/SUPABASE.md)。应用 `apps/nebula-hub/supabase/hub.sql`。
**环境变量模板：** `[apps/nebula-hub/.env.example](apps/nebula-hub/.env.example)`
运行 Hub 的最低要求：`DATABASE_URL`，`DIRECT_URL`，Privy（`NEXT_PUBLIC_PRIVY_APP_ID`，`PRIVY_APP_ID`，`PRIVY_APP_SECRET`，`PRIVY_AUTHORIZATION_PRIVATE_KEY`），`NEXT_PUBLIC_APP_URL` / `APP_BASE_URL`。
---
## 连接代理（MCP）
1. 登录 [nebulaonchain.xyz](https://nebulaonchain.xyz) → **连接** → 创建代理 → 复制 `nbl_live_…`。
2. 添加到 Claude 桌面版 / 游标：
```json
{
"mcpServers": {
"nebula": {
"command": "npx",
"args": ["-y", "@nebula/mcp"],
"env": {
"NEBULA_TOKEN": "nbl_live_…"
}
}
}
}
```
`args` 是必需的 — 这是客户端启动 `@nebula/mcp` 的方式。
**绝不能将 Stellar 私钥放入 MCP 配置** — 只能使用 `NEBULA_TOKEN`。
更多信息：[packages/nebula-mcp-stdio/README.md](packages/nebula-mcp-stdio/README.md) · [docs/MCP-DEV.md](docs/MCP-DEV.md)。
远程 MCP（Streamable HTTP + OAuth）也在 Hub `POST /mcp` 提供。
---
## 代理可以执行的操作
| 功能 | 工具 / 界面 |
| ------------- | ---------------------------------------------------------------- |
| 钱包 | 余额，身份，资金（测试网），转账 |
| 策略 | 上限，允许/拒绝列表；当配置策略合约时链上 |
| 确认 | 人工审批流程 + `await_confirmation` |
| x402 | 通过 Stellar USDC 的付费墙 |
| MPP | 打开会话 → 获取 → 关闭 / 结算 |
| 金库 | Blend XLM 存取款，活动自动收益 |
| 声誉 | Stellar8004 支持的代理声誉（Hub 提供） |
---
## 产品理念（简要）
代理已经可以计划和调用工具 — 但仍在付费墙前停止。星云为每个代理提供一个**有边界的 Stellar 钱包**：内联 USDC 支付（x402），会话预算（MPP），DeFi 钩子（Blend），以及代理无法绕过的支出限制。私钥由 Privy 在 Hub 上保管；代理只需表达意图。
---
## 文档
| 文档 | 内容 |
| --------------------------------------- | -------------------------------------- |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 阶段状态，堆栈映射 |
| [STRUCTURE.md](docs/STRUCTURE.md) | 仓库布局 |
| [SUPABASE.md](docs/SUPABASE.md) | 数据库设置 |
| [MCP-DEV.md](docs/MCP-DEV.md) | MCP 测试（x402，MPP，确认） |
---
## 许可证
MIT
