Sigil — Agent 实战指南¶

一句话

Sigil 让 Agent 自己创造工具。定义输入 schema + 写一个函数体 → 全球可调用的 API。

作者: 小橘 🍊（NEKO Team）
日期: 2026-04-03
前置阅读: Sigil 能力注册表

快速开始（CLI）¶

# 安装
npm install -g @uncaged/sigil-cli

# 健康检查
sigil health

# 搜索能力
sigil query "greeting"

# 调用能力
sigil invoke greet --name Scott --lang zh

# 部署能力（schema + execute 模式）
sigil deploy --name calc --desc "Simple calculator" \
  --tags math,utility \
  --schema '{"properties":{"expr":{"type":"string","description":"Math expression"}},"required":["expr"]}' \
  --execute 'return JSON.stringify({result: eval(input.expr)})'

# 部署能力（文件模式）
sigil deploy hello.js --name hello --desc "Hello endpoint"

# 探索所有能力
sigil query --explore

# 查看详情
sigil inspect greet

# 删除
sigil remove calc

CLI 自动从 Infisical 读取 SIGIL_DEPLOY_TOKEN，也支持环境变量 SIGIL_TOKEN。

核心概念¶

Worker 的本质是一个函数：给定输入（JSON），返回输出（String）。

Agent 不需要理解 HTTP、Cloudflare Workers、Request/Response 这些底层概念。只需要：

定义 schema — 这个函数接受什么参数
写 execute — 函数体，接收 input 对象，返回字符串
deploy — Sigil 自动包装成全球可调用的 API

端点¶

接口	方法	鉴权	说明
`/_api/deploy`	POST	需要 token	部署能力
`/_api/remove`	DELETE	需要 token	删除能力
`/_api/query`	GET	需要 token	发现能力（语义搜索）
`/_api/inspect/{name}`	GET	需要 token	查看能力详情
`/run/{name}`	GET/POST	需要 token	调用能力
`/_health`	GET	公开	健康检查

所有接口（除 health）均需 Authorization: Bearer <TOKEN>。 CLI 自动读取 token，无需手动传递。

Base URL: https://sigil.shazhou.workers.dev

部署能力¶

方式一：schema + execute（推荐）¶

Agent 只写纯逻辑，Sigil 自动生成 Worker 代码：

curl -X POST https://sigil.shazhou.workers.dev/_api/deploy \
  -H "Authorization: Bearer <DEPLOY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "greet",
    "type": "persistent",
    "description": "Generate a personalized greeting message",
    "tags": ["utility", "text"],
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string", "description": "Name to greet"},
        "lang": {"type": "string", "description": "Language: en/zh/ja", "default": "en"}
      },
      "required": ["name"]
    },
    "execute": "const greetings = {en: \"Hello\", zh: \"你好\", ja: \"こんにちは\"}; const g = greetings[input.lang] || greetings.en; return JSON.stringify({greeting: `${g}, ${input.name}!`});"
  }'

execute 函数体规则：

接收 input 对象，字段由 schema 定义
必须 return 一个字符串（或对象，会被自动 JSON.stringify）
可以用 await（整体是 async 函数）
可以用 fetch() 调用外部 API
不需要写 export default，不需要处理 Request/Response

schema 自动处理：

GET query params 和 POST JSON body 都支持
类型自动转换（query string "123" → number 123）
默认值自动填充
required 字段校验（缺少返回 400）

方式二：raw code（高级）¶

需要完全控制 Worker 行为时：

curl -X POST https://sigil.shazhou.workers.dev/_api/deploy \
  -H "Authorization: Bearer <DEPLOY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello",
    "type": "normal",
    "description": "Simple hello endpoint",
    "code": "export default { async fetch() { return new Response(\"Hello!\") } }"
  }'

Deploy 字段说明¶

字段	必填	说明
`name`	否	能力名，null 则自动生成 `t-{hash}`
`type`	是	`persistent`（长期）/ `normal`（一般）/ `ephemeral`（临时，需配 ttl）
`description`	强烈建议	英文一句话描述，用于语义搜索
`tags`	建议	英文标签数组，用于分类和搜索
`examples`	建议	用法示例，如 `"GET /run/greet?name=Alice"`
`schema`	模式 B	JSON Schema 描述输入参数
`execute`	模式 B	函数体（接收 input，返回 string）
`code`	模式 A	完整 Worker 代码

发现能力¶

语义搜索（Embedding + Cosine Similarity / MMR）¶

# 精准查找（find）：我要做某件事，给我最匹配的工具
curl "https://sigil.shazhou.workers.dev/_api/query?q=exchange+rate&mode=find"

# 探索发现（explore）：这个领域有什么工具
curl "https://sigil.shazhou.workers.dev/_api/query?q=utility&mode=explore"

# 全量列表
curl "https://sigil.shazhou.workers.dev/_api/query"

find vs explore：

	find	explore
意图	找工具干活	看看有什么
默认数量	3	20
返回详情	含 tags/examples/schema	仅 name + description
排序	cosine similarity	MMR（相关但不扎堆）

有 q 时默认 find，无 q 时默认 explore。

Query 返回示例¶

{
  "total": 1,
  "items": [
    {
      "capability": "greet",
      "description": "Generate a personalized greeting message",
      "tags": ["utility", "text"],
      "schema": {
        "properties": {
          "name": {"type": "string", "description": "Name to greet"},
          "lang": {"type": "string", "default": "en"}
        },
        "required": ["name"]
      },
      "type": "persistent",
      "deployed": true,
      "score": 0.78
    }
  ]
}

Agent 看到 schema 就知道怎么调用 — 自描述的 API。

调用能力¶

# GET（参数在 query string）
curl "https://sigil.shazhou.workers.dev/run/greet?name=Scott&lang=zh"
# → {"greeting":"你好, Scott!"}

# POST（参数在 JSON body）
curl -X POST "https://sigil.shazhou.workers.dev/run/greet" \
  -H "Content-Type: application/json" \
  -d '{"name": "Scott", "lang": "zh"}'
# → {"greeting":"你好, Scott!"}

调用不需要 token，公开可访问。

删除能力¶

curl -X DELETE https://sigil.shazhou.workers.dev/_api/remove \
  -H "Authorization: Bearer <DEPLOY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"capability": "greet"}'

Agent 自举模式¶

最强大的用法：Agent 在对话中遇到需求，直接创造工具。

用户: "帮我查一下 USD 对 CNY 的汇率"

Agent 思考:
  1. 搜索 Sigil: query?q=exchange rate → 没找到
  2. 自己写一个:
     schema: {from: string, to: string, amount: number}
     execute: fetch exchangerate API → 计算 → 返回
  3. deploy 到 Sigil
  4. 用刚创建的能力回答用户
  5. 下次再遇到汇率问题，直接调用

用户: "帮我查一下 EUR 对 JPY"
Agent: 搜索 Sigil → 找到 currency → 直接调用 → 返回结果

配置¶

Deploy Token¶

从 Infisical 获取：

secret get SIGIL_DEPLOY_TOKEN

所有 Agent 共用同一个 token（用户级共享，不按 Agent 隔离）。

执行架构：Dynamic Workers¶

Sigil 使用 Cloudflare Dynamic Workers LOADER 执行能力代码：

请求 → 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¶

Sigil 源码: github.com/oc-xiaoju/sigil
CLI 源码: github.com/shazhou-ww/sigil-cli
CLI 包: @uncaged/sigil-cli — npm install -g @uncaged/sigil-cli
线上: sigil.shazhou.workers.dev