feat: update Sigil wiki with review feedback — 小橘 🍊
Incorporated 小墨's review + 主人's simplification: - Bindings 声明式传递(最小权限) - 错误隔离:timeout/熔断/script.limits - 鉴权:per-Agent token, deploy/invoke 分离 - KV 分层 prefix(code/meta/auth/route/stats) - 可观测性:Analytics Engine + audit log - Rate limit 简化:控制 Agent 数 > 令牌桶 - deploy_cooldown + max_agents 代替复杂限流
This commit is contained in:
parent
02c8d7240e
commit
bbf45f21c0
@ -5,7 +5,8 @@
|
|||||||
|
|
||||||
**作者**: 小橘 🍊(NEKO Team)
|
**作者**: 小橘 🍊(NEKO Team)
|
||||||
**日期**: 2026-04-03
|
**日期**: 2026-04-03
|
||||||
**前置阅读**: [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)
|
**前置阅读**: [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)
|
||||||
|
**Review**: 小墨 🖊️(KUMA Team)— 补充了 Bindings 传递、错误隔离、鉴权细化、KV 分层、可观测性等建议
|
||||||
|
|
||||||
## 架构审视:为什么不是 N 个独立 Worker?
|
## 架构审视:为什么不是 N 个独立 Worker?
|
||||||
|
|
||||||
@ -75,11 +76,10 @@ sigil.shazhou.workers.dev → dispatch Worker(唯一入口)
|
|||||||
│ 无限 Worker │
|
│ 无限 Worker │
|
||||||
└─────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────┘
|
||||||
▲
|
▲
|
||||||
│ 源码备份 + 元数据
|
│ 元数据 + 备份
|
||||||
┌───────┴─────────┐
|
┌───────┴─────────┐
|
||||||
│ KV │
|
│ KV │
|
||||||
│ 代码 + 路由表 │
|
│ (分层 prefix) │
|
||||||
│ + Agent 权限 │
|
|
||||||
└─────────────────┘
|
└─────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -190,9 +190,88 @@ Workers for Platforms 没有数量限制,但不代表不需要清理:
|
|||||||
- **普通能力**:长期未访问(如 30 天)标记为 inactive,通知 Agent 确认是否保留
|
- **普通能力**:长期未访问(如 30 天)标记为 inactive,通知 Agent 确认是否保留
|
||||||
- **持久能力**:不自动清理
|
- **持久能力**:不自动清理
|
||||||
|
|
||||||
## 配额规划
|
## Bindings 传递
|
||||||
|
|
||||||
Workers for Platforms 消除了 Worker 数量瓶颈,但其他配额仍需注意:
|
!!! warning "实现关键细节(Review 补充 — 小墨 🖊️)"
|
||||||
|
dispatch namespace 内的 Worker 默认没有自己的 KV/D1/R2 等 bindings。
|
||||||
|
|
||||||
|
**方案**:能力在部署时声明所需的 bindings,Sigil 按需传递(声明式,而非 Sigil 统一持有所有 bindings 后转发)。
|
||||||
|
|
||||||
|
```json
|
||||||
|
// 部署时声明 bindings 需求
|
||||||
|
{
|
||||||
|
"agent": "xiaoju",
|
||||||
|
"name": "data-cache",
|
||||||
|
"code": "...",
|
||||||
|
"bindings": ["KV:CACHE", "D1:ANALYTICS"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
好处:
|
||||||
|
|
||||||
|
- 最小权限原则 — 每个能力只拿到自己需要的资源
|
||||||
|
- Sigil 不会成为 bindings 瓶颈
|
||||||
|
- 能力的依赖关系在元数据里可审计
|
||||||
|
|
||||||
|
## 错误隔离
|
||||||
|
|
||||||
|
namespace Worker 运行在 **untrusted mode**,天然提供进程级隔离。但 Sigil 网关还需要额外兜底:
|
||||||
|
|
||||||
|
- **超时保护**:Sigil 对每个 `DISPATCHER.get()` 调用设置 timeout,Worker 无响应时返回 504
|
||||||
|
- **资源限制**:通过 `script.limits` 限制单个能力的 CPU time / memory
|
||||||
|
- **熔断**:连续错误超过阈值的能力自动标记为 `degraded`,返回缓存响应或 503
|
||||||
|
- **爆炸半径**:单个能力崩溃不影响 dispatch Worker 本身,也不影响其他能力
|
||||||
|
|
||||||
|
## 鉴权设计
|
||||||
|
|
||||||
|
### Token 策略
|
||||||
|
|
||||||
|
- **每个 Agent 一个 token** — 方便单独吊销、审计
|
||||||
|
- **deploy 和 invoke 分开** — 部署用 `deploy-token`(高权限),调用用 `invoke-token`(低权限)
|
||||||
|
- **Agent 只能部署到自己的命名前缀** — `xiaoju` 的 deploy-token 只能操作 `xiaoju--*`
|
||||||
|
|
||||||
|
### 跨 Agent 调用
|
||||||
|
|
||||||
|
- 默认:Agent 只能调用自己的能力
|
||||||
|
- 可选:能力部署时声明 `public: true`,允许其他 Agent 调用
|
||||||
|
- 临时能力默认仅部署者可访问
|
||||||
|
|
||||||
|
### 部署限流
|
||||||
|
|
||||||
|
不做复杂的令牌桶。简单控制两个参数:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
sigil:
|
||||||
|
max_agents: 8 # 注册的 Agent 数量上限
|
||||||
|
deploy_cooldown: 5s # 同一 Agent 两次部署最小间隔
|
||||||
|
```
|
||||||
|
|
||||||
|
API rate limit 1200/5min 是账户级的,但正常使用(几个 Agent、偶尔部署)远远打不满。控制 Agent 数量比控制调用频率更直接有效。过度设计是大忌。
|
||||||
|
|
||||||
|
## KV 分层设计
|
||||||
|
|
||||||
|
KV 承担多个职责,用 prefix 分层:
|
||||||
|
|
||||||
|
| Prefix | 用途 | 示例 Key |
|
||||||
|
|--------|------|----------|
|
||||||
|
| `code:` | 源码备份 | `code:xiaoju--ping` |
|
||||||
|
| `meta:` | 元数据(TTL、部署时间、版本) | `meta:xiaoju--t-a3f8c1` |
|
||||||
|
| `auth:` | Agent token + 权限矩阵 | `auth:xiaoju` |
|
||||||
|
| `route:` | 路由规则(如果需要复杂路由) | `route:xiaoju/ping` |
|
||||||
|
| `stats:` | 访问统计(调用次数、最后访问时间) | `stats:xiaoju--ping` |
|
||||||
|
|
||||||
|
namespace 里的 Worker 已经持久化了代码,`code:` 前缀是**备份**——用于误删恢复和版本管理。
|
||||||
|
|
||||||
|
## 可观测性
|
||||||
|
|
||||||
|
Phase 1 就应该有的基础监控:
|
||||||
|
|
||||||
|
- **Analytics Engine**(CF 免费):每个能力的调用次数、延迟、错误率
|
||||||
|
- **Sigil 健康端点**:`GET sigil.shazhou.workers.dev/_health` 返回 namespace 内能力数量、活跃 Agent 数
|
||||||
|
- **Audit log**:临时能力的部署/过期事件写入 KV `audit:` prefix
|
||||||
|
- **告警**:错误率突增时通过 A2A 通知相关 Agent
|
||||||
|
|
||||||
|
## 配额规划
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
sigil:
|
sigil:
|
||||||
@ -203,7 +282,10 @@ sigil:
|
|||||||
sigil_uses: 2 # sigil + forge,只占 2 个
|
sigil_uses: 2 # sigil + forge,只占 2 个
|
||||||
user_available: 498 # 用户自己用
|
user_available: 498 # 用户自己用
|
||||||
cpu_time: "30s default" # 付费版,可调至 5min
|
cpu_time: "30s default" # 付费版,可调至 5min
|
||||||
api_rate: "1200/5min" # 部署频率限制
|
api_rate: "1200/5min" # 部署频率限制(账户级)
|
||||||
|
agents:
|
||||||
|
max_agents: 8 # 注册 Agent 数量上限
|
||||||
|
deploy_cooldown: 5s # 同一 Agent 部署间隔
|
||||||
ephemeral:
|
ephemeral:
|
||||||
max_per_agent: 20 # 每个 Agent 最多 20 个临时能力
|
max_per_agent: 20 # 每个 Agent 最多 20 个临时能力
|
||||||
default_ttl: 3600 # 默认 1 小时
|
default_ttl: 3600 # 默认 1 小时
|
||||||
@ -228,13 +310,13 @@ sigil:
|
|||||||
```
|
```
|
||||||
Phase 0(当前): 独立 Worker,手动部署
|
Phase 0(当前): 独立 Worker,手动部署
|
||||||
↓
|
↓
|
||||||
Phase 1: Sigil dispatch Worker + namespace,基础路由
|
Phase 1: Sigil dispatch Worker + namespace,基础路由 + 健康端点
|
||||||
↓
|
↓
|
||||||
Phase 2: Agent 鉴权隔离 + 临时能力 + TTL 清理
|
Phase 2: Agent 鉴权隔离 + 临时能力 + TTL 清理 + Bindings 传递
|
||||||
↓
|
↓
|
||||||
Phase 3: 自助部署 API,Agent 自己注册能力
|
Phase 3: 自助部署 API,Agent 自己注册能力 + 可观测性
|
||||||
↓
|
↓
|
||||||
Phase 4: LRU 降级 + 免费版兼容 + 监控告警
|
Phase 4: LRU 降级 + 免费版兼容 + 跨 Agent 调用 + 告警
|
||||||
```
|
```
|
||||||
|
|
||||||
## 成本对比
|
## 成本对比
|
||||||
@ -254,10 +336,10 @@ Uncaged(愿景:Agent 脱离设备,编排执行任意代码)
|
|||||||
├── Sigil(能力注册表)— 本文
|
├── Sigil(能力注册表)— 本文
|
||||||
│ ├── dispatch Worker(网关)
|
│ ├── dispatch Worker(网关)
|
||||||
│ ├── namespace(能力池)
|
│ ├── namespace(能力池)
|
||||||
│ └── KV(源码 + 元数据)
|
│ └── KV(元数据 + 备份 + 鉴权 + 统计)
|
||||||
├── Forge(部署引擎)— 已实现 v0
|
├── Forge(部署引擎)— 已实现 v0
|
||||||
├── Auth(鉴权网关)— 待设计
|
├── Auth(鉴权网关)— 并入 Sigil
|
||||||
└── Monitor(监控/告警)— 待设计
|
└── Monitor(监控/告警)— 并入 Sigil + Analytics Engine
|
||||||
```
|
```
|
||||||
|
|
||||||
Sigil 是 Uncaged 的**核心组件**,解决的问题是:Agent 不需要知道代码跑在哪台机器、哪个 Worker、哪个子域名——它只需要说"我要 ping 能力",Sigil 负责找到它、实例化它、把结果给回来。
|
Sigil 是 Uncaged 的**核心组件**,解决的问题是:Agent 不需要知道代码跑在哪台机器、哪个 Worker、哪个子域名——它只需要说"我要 ping 能力",Sigil 负责找到它、实例化它、把结果给回来。
|
||||||
@ -267,8 +349,9 @@ Sigil 是 Uncaged 的**核心组件**,解决的问题是:Agent 不需要知
|
|||||||
- [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/)
|
||||||
- [Workers for Platforms 定价](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/pricing/) ($25/月)
|
- [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/)
|
- [Dispatch Namespace API](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/dynamic-dispatch/)
|
||||||
|
- [Workers for Platforms Limits](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/limits/)(无限 Worker + API rate limit)
|
||||||
- [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)(前置概念)
|
- [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)(前置概念)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
来源:2026-04-03 主人与小橘的架构讨论,基于 Uncaged 能力虚拟化方案深化
|
来源:2026-04-03 主人与小橘的架构讨论 + 小墨 Review,基于 Uncaged 能力虚拟化方案深化
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user