小橘 e629188c9a docs: Uncaged Agent — 能力虚拟内存的第一个消费者

Tools = f(Chat History) 架构解析、虚拟内存类比、agentic loop、
上下文压缩自动卸载、CF 1042 解决方案

小橘 🍊 (NEKO Team)

2026-04-03 14:31:01 +00:00

5.2 KiB

Raw Blame History

title, description, date, authors, tags

title

description

date

authors

Uncaged Agent 🔓

Sigil-native AI Agent — 一个能自主发现、创建、使用 serverless 能力的 AI agent。

仓库：oc-xiaoju/uncaged
Bot：@scottwei_doudou_bot（豆豆）
运行环境：Cloudflare Workers

核心洞察：Tools = f(Chat History)

传统 agent 的工具列表是静态的——启动时注册 N 个 tools，运行时永远是这 N 个。Uncaged 不一样：

tools 列表是 chat history 的纯函数。

每一轮构建 LLM request 时，从 history 中提取所有 sigil_query 的返回结果和 sigil_deploy 的调用记录，将其中的 capability 动态映射为 LLM tools。

这意味着：

LLM 调 sigil_query("hash") → 返回结果出现在 history → 下一轮 cap_sha256_hash 自动成为可调用 tool
上下文压缩 → 旧的 query 结果从 history 中被压缩掉 → 对应的 tool 自动消失
再次需要时 → LLM 重新 sigil_query → tool 重新出现

不需要任何显式的 load/unload 机制。

能力虚拟内存

这套机制天然实现了虚拟内存的语义：

操作系统	Uncaged
Page fault（缺页中断）	`sigil_query` 发现能力 → tool 出现
Page eviction（页面淘汰）	上下文压缩 → tool 消失
Working set（工作集）	当前 tools 列表
Physical memory（物理内存）	Context window 大小
Disk（磁盘）	Sigil KV（永久存储所有能力）
TLB	单轮的 tools 快照

而且 tools 本身占用 context window 的 token，所以 context window 大小天然约束了 working set 上限 ——就像物理内存约束 working set 一样。

架构

Telegram
   ↓ Webhook
CF Worker (Uncaged)
   ├── Chat History (KV) ← 多轮对话持久化
   ├── LLM (DashScope/Qwen)
   │     ├── Static tools: sigil_query, sigil_deploy
   │     └── Dynamic tools: cap_* (从 history 派生)
   └── Sigil (sigil.shazhou.work)
         └── query / deploy / run / inspect

Agentic Loop

每轮处理：

从 KV 加载 chat history
检查是否需要上下文压缩（> 40 条消息）
从 history 中 动态提取 capability → 生成 cap_* tools
拼装 [static_tools + dynamic_tools] + messages → 发给 LLM
LLM 返回 tool calls → 执行 → 结果反馈 → 循环（最多 6 轮）
最终文本回复 → 保存 history → 发 Telegram

错误恢复

工具调用失败时，错误信息作为 tool result 返回给 LLM。LLM 可以：

修正参数重试
换一种策略
告诉用户需要什么信息

不会因为一次工具调用失败就整体崩溃。

上下文压缩

当 history 超过 40 条消息：

保留第一条 user message + 最近 10 条
中间的 tool call 链被丢弃
孤儿 tool result（没有对应 assistant tool_call）被清理

关键副作用：被丢弃的 sigil_query 结果中的 capability 从 tools 中消失。这不是 bug，这就是自动卸载机制。

Static vs Dynamic Tools

类型	工具	生命周期
Static	`sigil_query`	永远可用
Static	`sigil_deploy`	永远可用
Dynamic	`cap_{name}`	随 history 中的 query/deploy 结果出现/消失

Dynamic tool 的命名规则：cap_ + capability 名（- 替换为 _）。例如 capability sha256-hash → tool cap_sha256_hash。

CF Worker 间调用（Error 1042）

Uncaged 和 Sigil 都是 CF Worker。同 account 的 Worker 不能通过 .workers.dev 子域名互相 fetch()（CF error 1042，防止递归调用）。

解决方案：给 Sigil 绑定 custom domain sigil.shazhou.work。不同 zone 的请求不受此限制。

典型交互

发现已有能力并使用

用户: 帮我把 hello world 编码成 base64
豆豆: [sigil_query("base64") → 找到 encode → cap_encode({text:"hello world", format:"base64"})]
      base64 编码结果: aGVsbG8gd29ybGQ=

从零创建能力

用户: 做个 SHA-256 hash 计算的能力
豆豆: [sigil_query("sha256") → 没找到 → sigil_deploy(sha256-hash, ...) → 确认]
      🔮 已创建 sha256-hash！告诉我你想 hash 什么文本。

用户: hash一下 hello world
豆豆: [cap_sha256_hash({text:"hello world"}) → 直接调用]
      SHA-256: b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

项目文件

src/
├── index.ts        — CF Worker 入口（webhook + health check）
├── telegram.ts     — Telegram 消息处理
├── llm.ts          — 动态 tool 加载 + agentic loop
├── sigil.ts        — Sigil API 客户端
└── chat-store.ts   — KV chat history + 压缩

5.2 KiB Raw Blame History