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:
小橘 2026-04-03 01:31:31 +00:00
parent 02c8d7240e
commit bbf45f21c0

View File

@ -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 能力虚拟化方案深化