From 24866be8a931bc2bad0685b8402bddd49846ada4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= <xiaoju@shazhou.work>
Date: Fri, 3 Apr 2026 11:17:28 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20update=20Sigil=20docs=20for=20Dynamic?=
 =?UTF-8?q?=20Workers=20LOADER=20=E2=80=94=20=E5=B0=8F=E6=A9=98=20?=
 =?UTF-8?q?=F0=9F=8D=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Agent guide: replace LRU/子Worker section with Dynamic Workers architecture
- Backend LRU doc: add evolution note, link to Dynamic Workers docs
- Zero DNS latency, single Worker, V8 Isolate sandboxing
---
 docs/shared/sigil-agent-guide.md | 29 +++++++++++++++++++++++------
 docs/shared/sigil-backend-lru.md | 20 ++++++++++++++++++++
 2 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/docs/shared/sigil-agent-guide.md b/docs/shared/sigil-agent-guide.md
index 042aecd..8478c07 100644
--- a/docs/shared/sigil-agent-guide.md
+++ b/docs/shared/sigil-agent-guide.md
@@ -210,21 +210,38 @@ secret get SIGIL_DEPLOY_TOKEN
 
 所有 Agent 共用同一个 token（用户级共享，不按 Agent 隔离）。
 
-### LRU 换页
+### 执行架构：Dynamic Workers
 
-Sigil 用 LRU 在有限的 Worker 配额内管理无限能力：
+Sigil 使用 Cloudflare **Dynamic Workers LOADER** 执行能力代码：
 
-- 活跃的能力常驻 Worker
-- 冷能力换出（只删 Worker，代码保留在 KV）
-- 被调用时自动换入（从 KV 重新部署）
-- 对调用者透明
+```
+请求 → Sigil Worker → LOADER.get(id, code) → 沙箱内执行 → 返回
+```
+
+- **零延迟**：代码在 Sigil 进程内的 V8 Isolate 沙箱中执行，不涉及 DNS 或 HTTP 转发
+- **安全隔离**：Dynamic Worker 有独立内存空间，不能访问 Sigil 的变量
+- **智能缓存**：`LOADER.get(id, callback)` 按 ID 缓存实例，同一能力多次调用复用同一实例
+- **无配额压力**：不创建独立 Worker，不占用 Worker 数量配额
+- **冷启动 ~1ms**：首次调用从 KV 读代码加载，后续命中缓存直接执行
+
+整个 Sigil 只有**一个 Worker**——自己。所有能力代码都通过 Dynamic Workers 在运行时动态加载。
+
+### LRU 调度
+
+代码永久存储在 KV，LRU 管理的是 LOADER 缓存中的"已加载"状态：
+
+- deploy 时标记为 deployed，代码存入 KV
+- 配额满时 LRU 淘汰最冷的能力（标记为 not deployed）
+- 被调用时自动从 KV 加载（冷启动，对调用者透明）
 
 ### 技术细节
 
+- **执行引擎**: Cloudflare Dynamic Workers LOADER（open beta）
 - **Embedding**: CF Workers AI `bge-base-en-v1.5`（768 维）
 - **Query 缓存**: KV 缓存 embedding，TTL 1 小时
 - **description/tags 建议用英文**: embedding 模型英文效果更好
 - **deploy cooldown**: 5 秒，防止频繁部署
+- **计费**: 每次 invoke = 2 次请求（Sigil + Dynamic Worker），包含在 Workers Standard $5/月
 
 ## Repo
 
diff --git a/docs/shared/sigil-backend-lru.md b/docs/shared/sigil-backend-lru.md
index 5bc2aa8..4250c9c 100644
--- a/docs/shared/sigil-backend-lru.md
+++ b/docs/shared/sigil-backend-lru.md
@@ -369,7 +369,27 @@ Phase 4: 预热策略 + 异步换出 + 可观测性 + 告警
 - [Uncaged 能力虚拟化](uncaged-capability-virtualization.md)（前置概念）
 - [CF Workers API](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/)（部署/删除 Worker）
 - [Workers for Platforms](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/)（$25 方案参考）
+- [Dynamic Workers](https://developers.cloudflare.com/dynamic-workers/)（实际采用方案）
 
 ---
 
 来源：2026-04-03 主人提出抽象接口 + 双实现方案，小橘基于 LRU 核心地位重新设计
+
+---
+
+## 架构演进记录（2026-04-03）
+
+!!! success "实际落地：Dynamic Workers LOADER"
+    设计阶段规划了三种方案（$5 LRU 换页 / $25 WfP / 预分配 Slot Pool），最终采用 **Cloudflare Dynamic Workers LOADER**（open beta），完全跳过了子 Worker 管理的复杂度。
+
+**Dynamic Workers 方案**：
+
+- Sigil 是唯一的 Worker，能力代码通过 `env.LOADER.get(id, callback)` 在运行时动态加载
+- 代码在 V8 Isolate 沙箱中执行，独立内存，安全隔离
+- 不创建独立 Worker，不占配额，零 DNS 延迟
+- `LOADER.get()` 按 ID 缓存实例，同一能力复用 Worker 实例
+- 计费：每次 invoke = 2 次请求（Sigil + Dynamic Worker）
+
+**LRU 的角色变化**：原设计中 LRU 管理"哪些 Worker 在线"（物理部署状态），现在 LRU 管理的是逻辑状态标记（deployed/not-deployed），LOADER 缓存自行管理内存中的实例生命周期。
+
+**本文档保留为设计参考**，实际实现以 [Agent 实战指南](sigil-agent-guide.md) 为准。