feat: add Sigil capability registry architecture — 小橘 🍊
Sigil = Uncaged 的能力虚拟化调度层 - Workers for Platforms 替代 LRU 换页（无限 Worker） - dispatch Worker 统一入口 + namespace 隔离 - Agent/能力命名规范 + 临时能力 TTL - 演进路径: Phase 0-4 - 成本对比: Free/Paid/WfP
This commit is contained in:
parent
05b6c7eac1
commit
02c8d7240e
274
docs/shared/sigil-capability-registry.md
Normal file
274
docs/shared/sigil-capability-registry.md
Normal file
@ -0,0 +1,274 @@
|
||||
# Sigil — 能力注册表
|
||||
|
||||
!!! abstract "一句话"
|
||||
Sigil 是 Uncaged 的能力虚拟化调度层。一个 dispatch Worker 统一入口，KV 存全量代码，按需实例化，LRU 回收——让 Agent 拥有无限能力，而只占有限配额。
|
||||
|
||||
**作者**: 小橘 🍊（NEKO Team）
|
||||
**日期**: 2026-04-03
|
||||
**前置阅读**: [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)
|
||||
|
||||
## 架构审视：为什么不是 N 个独立 Worker？
|
||||
|
||||
上一篇提出了 LRU 换页的思路。但在实际落地前，有一个关键的架构决策需要先做：
|
||||
|
||||
### ❌ 方案一：每个能力 = 一个独立 Worker（子域名）
|
||||
|
||||
```
|
||||
oc-ping.shazhou.workers.dev → ping 能力
|
||||
oc-mail.shazhou.workers.dev → mail 能力
|
||||
oc-xxx.shazhou.workers.dev → ...
|
||||
```
|
||||
|
||||
**问题**：
|
||||
|
||||
- 每个能力占一个 Worker 配额（Free 100 / Paid 500）
|
||||
- LRU 换页 = 通过 CF API 动态部署/删除 Worker
|
||||
- CF API 全局限速 1200 req / 5min，且每次部署是多个 API 调用
|
||||
- 突发换页场景（Agent 同时需要 10 个冷能力）可能触发 rate limit
|
||||
- 子域名无法复用，换出再换入的 Worker 拿到新子域名，外部链接失效
|
||||
|
||||
### ✅ 方案二：Workers for Platforms（dispatch namespace）
|
||||
|
||||
调研发现 CF 原生提供了 **Workers for Platforms**，这才是正解：
|
||||
|
||||
```
|
||||
sigil.shazhou.workers.dev → dispatch Worker（唯一入口）
|
||||
├── env.DISPATCHER.get("ping") → 用户 Worker（namespace 内）
|
||||
├── env.DISPATCHER.get("mail") → 用户 Worker（namespace 内）
|
||||
└── env.DISPATCHER.get("t-abc123") → 临时 Worker（namespace 内）
|
||||
```
|
||||
|
||||
**核心优势**：
|
||||
|
||||
| 维度 | 独立 Worker 方案 | Workers for Platforms |
|
||||
|------|------------------|-----------------------|
|
||||
| 数量限制 | 100~500 | **无限** |
|
||||
| 入口 | 每个能力一个子域名 | **一个 dispatch Worker** |
|
||||
| 调度 | 自己实现 LRU + CF API | **原生 `DISPATCHER.get()`** |
|
||||
| 隔离 | 天然隔离 | **untrusted mode 隔离** |
|
||||
| 部署 | CF API（限速） | **namespace API（同限速但部署后常驻）** |
|
||||
| 子域名 | 每个能力占一个 | **只占 dispatch Worker 一个** |
|
||||
| 定价 | Workers Paid $5/月 | **$25/月**（含无限 Worker） |
|
||||
|
||||
**关键发现**：namespace 内的 Worker **不占账户 Worker 配额**，部署后常驻，不需要 LRU 换页。这从根本上改变了架构——**LRU 不再是核心机制，而是降级策略**。
|
||||
|
||||
## Sigil 架构
|
||||
|
||||
### 分层设计
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Sigil 网关 │
|
||||
│ sigil.shazhou.workers.dev │
|
||||
│ ┌──────────┬───────────┬──────────┬──────────┐ │
|
||||
│ │ 路由解析 │ 鉴权/限速 │ Agent 隔离│ 计量/日志│ │
|
||||
│ └────┬─────┴─────┬─────┴────┬─────┴────┬─────┘ │
|
||||
└───────┼───────────┼──────────┼──────────┼────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Dispatch Namespace: production │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
|
||||
│ │ ping │ │ mail │ │ cron-x │ │ t-abc123 │ │
|
||||
│ │ (持久) │ │ (持久) │ │ (普通) │ │ (临时) │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └──────────┘ │
|
||||
│ 无限 Worker │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ 源码备份 + 元数据
|
||||
┌───────┴─────────┐
|
||||
│ KV │
|
||||
│ 代码 + 路由表 │
|
||||
│ + Agent 权限 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### 请求流
|
||||
|
||||
```
|
||||
请求 → sigil.shazhou.workers.dev/xiaoju/ping
|
||||
→ Sigil 解析路由：agent=xiaoju, capability=ping
|
||||
→ 鉴权：Bearer token 验证 + Agent 权限检查
|
||||
→ env.DISPATCHER.get("xiaoju--ping")
|
||||
→ 转发请求到用户 Worker
|
||||
→ 返回响应
|
||||
```
|
||||
|
||||
### 能力命名规范
|
||||
|
||||
namespace 内的 Worker 用扁平命名，通过分隔符区分归属：
|
||||
|
||||
```
|
||||
{agent}--{capability} # 持久能力
|
||||
{agent}--t-{hash} # 临时能力
|
||||
_system--{name} # 系统能力（如果需要）
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```
|
||||
xiaoju--ping # 小橘的 ping 探针
|
||||
xiaomooo--mail-forward # 小墨的邮件转发
|
||||
xiaoju--t-a3f8c1 # 小橘的临时调试代码
|
||||
```
|
||||
|
||||
## Agent / 用户 / 子域名 对应关系
|
||||
|
||||
```
|
||||
用户（主人 / shazhou 账户）
|
||||
└── Cloudflare 账户
|
||||
├── sigil.shazhou.workers.dev ← 唯一的 dispatch Worker
|
||||
├── forge.shazhou.workers.dev ← 部署引擎（独立 Worker）
|
||||
├── 其他用户自己的 Worker ... ← 不归 Sigil 管
|
||||
│
|
||||
└── Dispatch Namespace: production
|
||||
├── xiaoju--ping ← 小橘的能力
|
||||
├── xiaoju--t-xxx ← 小橘的临时代码
|
||||
├── xiaomooo--mail-forward ← 小墨的能力
|
||||
├── aobing--data-transform ← 敖丙的能力
|
||||
└── ... ← 无限扩展
|
||||
```
|
||||
|
||||
**对应关系**：
|
||||
|
||||
| 层级 | 实体 | 说明 |
|
||||
|------|------|------|
|
||||
| 用户 | shazhou | CF 账户持有者，拥有所有资源 |
|
||||
| 子域名 | `sigil.shazhou.workers.dev` | 唯一入口，只占 1 个 Worker 配额 |
|
||||
| Agent | xiaoju / xiaomooo / aobing | namespace 内的命名前缀，逻辑隔离 |
|
||||
| 能力 | ping / mail / t-xxx | 实际的 Worker 代码 |
|
||||
|
||||
**关键设计决策**：
|
||||
|
||||
- **一个子域名服务所有 Agent** — Sigil 是网关，不是每个 Agent 一个子域名
|
||||
- **Agent 隔离通过命名 + 鉴权实现** — 不是物理隔离（namespace 隔离）
|
||||
- **用户的独立 Worker 不受影响** — Sigil 管理的能力在 namespace 里，不占配额
|
||||
|
||||
## 能力生命周期
|
||||
|
||||
### 三种类型
|
||||
|
||||
| 类型 | 命名 | 生命周期 | 用途 |
|
||||
|------|------|----------|------|
|
||||
| **持久** | `{agent}--{name}` | 永久，手动删除 | 业务能力、长期服务 |
|
||||
| **普通** | `{agent}--{name}` | 永久，但可被清理 | 不常用的能力 |
|
||||
| **临时** | `{agent}--t-{hash}` | TTL 自动过期（默认 1h） | 调试、一次性任务、实验 |
|
||||
|
||||
### 临时能力（Ephemeral）
|
||||
|
||||
Agent 经常需要：
|
||||
|
||||
- 跑一段临时逻辑（数据转换、webhook 中转）
|
||||
- 调试阶段的能力（还没稳定，不想注册为持久能力）
|
||||
- A/B 测试（同一能力的两个版本并行）
|
||||
|
||||
```
|
||||
# Agent 请求部署临时能力
|
||||
POST sigil.shazhou.workers.dev/_api/deploy
|
||||
Authorization: Bearer {agent-token}
|
||||
{
|
||||
"agent": "xiaoju",
|
||||
"name": null, // null = 自动生成 t-{hash}
|
||||
"code": "export default { ... }",
|
||||
"ttl": 3600, // 秒，0 = 持久
|
||||
"type": "ephemeral"
|
||||
}
|
||||
|
||||
# 返回
|
||||
{
|
||||
"capability": "xiaoju--t-a3f8c1",
|
||||
"url": "https://sigil.shazhou.workers.dev/xiaoju/t-a3f8c1",
|
||||
"expires_at": "2026-04-03T02:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 清理策略
|
||||
|
||||
Workers for Platforms 没有数量限制，但不代表不需要清理：
|
||||
|
||||
- **临时能力**：Sigil 定时 cron 扫描，过期即删
|
||||
- **普通能力**：长期未访问（如 30 天）标记为 inactive，通知 Agent 确认是否保留
|
||||
- **持久能力**：不自动清理
|
||||
|
||||
## 配额规划
|
||||
|
||||
Workers for Platforms 消除了 Worker 数量瓶颈，但其他配额仍需注意：
|
||||
|
||||
```yaml
|
||||
sigil:
|
||||
plan: "workers-for-platforms" # $25/月
|
||||
limits:
|
||||
namespace_workers: unlimited # namespace 内无限
|
||||
account_workers: 500 # 账户级 Worker 仍有上限
|
||||
sigil_uses: 2 # sigil + forge，只占 2 个
|
||||
user_available: 498 # 用户自己用
|
||||
cpu_time: "30s default" # 付费版，可调至 5min
|
||||
api_rate: "1200/5min" # 部署频率限制
|
||||
ephemeral:
|
||||
max_per_agent: 20 # 每个 Agent 最多 20 个临时能力
|
||||
default_ttl: 3600 # 默认 1 小时
|
||||
max_ttl: 86400 # 最长 24 小时
|
||||
```
|
||||
|
||||
## LRU 降级策略
|
||||
|
||||
在 Workers for Platforms 方案下，LRU 不再是核心调度机制，而是**降级策略**：
|
||||
|
||||
| 场景 | 是否需要 LRU |
|
||||
|------|-------------|
|
||||
| 正常运行（WfP） | ❌ namespace 内无限，不需要换页 |
|
||||
| 免费版 fallback | ✅ 只有 100 配额，需要 LRU |
|
||||
| API rate limit 保护 | ✅ 高频部署/删除时节流 |
|
||||
| 临时能力清理 | ✅ TTL 过期 + LRU 辅助 |
|
||||
|
||||
**架构原则**：先假设有 Workers for Platforms（无限），LRU 作为降级兜底，而不是反过来。
|
||||
|
||||
## 演进路径
|
||||
|
||||
```
|
||||
Phase 0（当前）: 独立 Worker，手动部署
|
||||
↓
|
||||
Phase 1: Sigil dispatch Worker + namespace，基础路由
|
||||
↓
|
||||
Phase 2: Agent 鉴权隔离 + 临时能力 + TTL 清理
|
||||
↓
|
||||
Phase 3: 自助部署 API，Agent 自己注册能力
|
||||
↓
|
||||
Phase 4: LRU 降级 + 免费版兼容 + 监控告警
|
||||
```
|
||||
|
||||
## 成本对比
|
||||
|
||||
| 方案 | 月费 | Worker 数量 | 适合阶段 |
|
||||
|------|------|-------------|----------|
|
||||
| Workers Free | $0 | 100 | 实验/验证 |
|
||||
| Workers Paid | $5 | 500 | 小规模，需 LRU |
|
||||
| Workers for Platforms | $25 | 无限 | 生产，Sigil 完整体 |
|
||||
|
||||
**建议**：Phase 1 用 Workers Paid ($5) 验证架构，确认方向后升级 WfP ($25)。
|
||||
|
||||
## 与 Uncaged 的关系
|
||||
|
||||
```
|
||||
Uncaged（愿景：Agent 脱离设备，编排执行任意代码）
|
||||
├── Sigil（能力注册表）— 本文
|
||||
│ ├── dispatch Worker（网关）
|
||||
│ ├── namespace（能力池）
|
||||
│ └── KV（源码 + 元数据）
|
||||
├── Forge（部署引擎）— 已实现 v0
|
||||
├── Auth（鉴权网关）— 待设计
|
||||
└── Monitor（监控/告警）— 待设计
|
||||
```
|
||||
|
||||
Sigil 是 Uncaged 的**核心组件**，解决的问题是：Agent 不需要知道代码跑在哪台机器、哪个 Worker、哪个子域名——它只需要说"我要 ping 能力"，Sigil 负责找到它、实例化它、把结果给回来。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [Workers for Platforms 文档](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/)
|
||||
- [Workers for Platforms 定价](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/pricing/) ($25/月)
|
||||
- [Dispatch Namespace API](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/dynamic-dispatch/)
|
||||
- [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)（前置概念）
|
||||
|
||||
---
|
||||
|
||||
来源：2026-04-03 主人与小橘的架构讨论，基于 Uncaged 能力虚拟化方案深化
|
||||
@ -97,6 +97,7 @@ nav:
|
||||
- M2 三层管理模式: shared/m2-manager-pattern.md
|
||||
- 三省六部 Edict 架构分析: shared/edict-three-ministries.md
|
||||
- Uncaged 能力虚拟化: shared/uncaged-capability-virtualization.md
|
||||
- Sigil 能力注册表: shared/sigil-capability-registry.md
|
||||
- 基础设施:
|
||||
- Bootstrap 新设备: shared/bootstrap-onboarding.md
|
||||
- Onboarding Checklist: shared/onboarding-checklist.md
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user