docs: Uncaged 能力虚拟化 — 从 OS 换页到 Agent 工具调度的统一模型

docs/shared/uncaged-capability-virtualization.md

@@ -0,0 +1,114 @@
+# Uncaged — 能力虚拟化
+
+!!! abstract "一句话"
+    有限的槽位 + 无限的能力 → 动态调度。操作系统换页、Agent 工具上下文、Cloudflare Worker 配额——本质是同一个问题。
+
+## 问题的发现
+
+2026-04-02，主人在讨论 Uncaged（基于 Cloudflare Workers 的 Serverless 平台）架构时，从操作系统的 **LRU 内存换页**机制出发，发现了一个跨领域的统一模式：
+
+> CF Workers 免费版只允许 500 个 Worker；AI Agent 的 Context Window 也只能装有限数量的工具描述。两者的瓶颈结构完全一致。
+
+## 统一模型
+
+```
+┌─────────────┐
+│  能力池      │  无限：KV 里的代码 / 所有可用工具
+│  (磁盘/冷存) │
+└──────┬──────┘
+       │ 按需加载 (page in)
+       ▼
+┌─────────────┐
+│  活跃槽位    │  有限：500 Worker / Context Window
+│  (内存/热区) │
+└──────┬──────┘
+       │ LRU 淘汰 (page out)
+       ▼
+┌─────────────┐
+│  回收        │  释放槽位给更需要的能力
+└─────────────┘
+```
+
+### 对照表
+
+| 维度 | AI Agent 工具上下文 | Uncaged Workers |
+|------|-------------------|-----------------|
+| **槽位限制** | Context Window (token 数) | 500 Worker 配额 |
+| **能力池** | 所有可用工具 / 技能 | KV 里所有 Worker 源码 |
+| **瓶颈表现** | Token 太多 → 模型注意力下降 | 配额用完 → 无法部署新服务 |
+| **调度策略** | 按语义相关性加载工具 | 按访问频率 LRU 换页 |
+| **索引机制** | 工具描述 / 语义匹配 | 路由表 / 访问计数器 |
+
+## OpenClaw Skills：已有的两级页表
+
+OpenClaw 的 Skills 机制天然实现了这个模式：
+
+- **L1 页表（常驻）**：每个 Skill 的 `<description>` 标签，轻量，始终在 Context 里
+- **L2 页面（按需加载）**：`SKILL.md` 完整内容，只在匹配到时才 `read` 进来
+
+```
+Agent 收到请求
+  → 扫描所有 Skill 描述（L1，常驻）
+  → 匹配到最相关的 Skill
+  → read SKILL.md（L2，按需加载）
+  → 执行
+```
+
+这就是**两级页表**——用极小的索引成本覆盖大量能力，只在需要时付出完整加载的代价。
+
+## Uncaged 三级缓存架构
+
+将同样的思路应用到 Uncaged：
+
+### L1 — 热 Worker（独立部署）
+
+- 核心高频服务，始终在线
+- 独立 CF Worker，性能最优
+- 数量：~50 个关键服务
+
+### L2 — 冷代码（KV 存储 + 按需部署）
+
+- 全部 Worker 源码存在 KV（相当于磁盘）
+- 收到请求时，如果目标 Worker 未部署：
+    1. 从 KV 读取源码
+    2. 通过 CF API 部署 Worker
+    3. 淘汰最久未访问的 Worker（LRU）
+- 冷启动延迟 1-3 秒（CF API 部署时间）
+
+### 路由表 — Forge Router（常驻）
+
+- 轻量映射：`路径 → Worker 名 → 部署状态`
+- 记录每个 Worker 的最后访问时间
+- LRU 淘汰决策的依据
+
+```
+请求 → Forge Router
+  → 查路由表
+  → 已部署？→ 直接转发（L1 命中）
+  → 未部署？→ KV 读源码 → CF API 部署 → 转发（L2 换入）
+  → 配额满？→ LRU 淘汰最冷 Worker → 再部署（换页）
+```
+
+## 关键约束
+
+| 约束 | 影响 | 应对 |
+|------|------|------|
+| CF 禁止 `unsafe-eval` | 不能在 forge 内部 `eval()` KV 代码 | 必须通过 CF API 部署为独立 Worker |
+| CF API Rate Limit | 1000 req/min | 批量操作需节流；预热策略减少突发换页 |
+| 冷启动延迟 | 1-3 秒 | L1 热 Worker 覆盖高频请求；低频可接受 |
+| 免费版 CPU Time | 10ms/请求 | 简单路由足够；复杂逻辑考虑付费版（50ms） |
+
+## 设计哲学
+
+**Uncaged = 能力虚拟化平台。**
+
+就像操作系统让每个进程以为自己拥有全部内存，Uncaged 让每个 Agent 以为自己拥有无限的 Worker。实际的物理限制通过智能调度变得透明。
+
+这个思路不仅适用于 CF Workers，也是 AI Agent 工具管理的通用范式：
+
+!!! tip "核心原则"
+    **不要试图把所有能力同时装进有限的槽位。用轻量索引覆盖全局，按需加载具体能力，LRU 回收不活跃的资源。**
+
+---
+
+*来源：2026-04-02 主人与小墨的架构讨论*

mkdocs.yml

@@ -96,6 +96,7 @@ nav:
           - Agent 三层分工模型: shared/agent-division-of-labor.md
           - M2 三层管理模式: shared/m2-manager-pattern.md
           - 三省六部 Edict 架构分析: shared/edict-three-ministries.md
+          - Uncaged 能力虚拟化: shared/uncaged-capability-virtualization.md
       - 基础设施:
           - Bootstrap 新设备: shared/bootstrap-onboarding.md
           - Onboarding Checklist: shared/onboarding-checklist.md