企业官网建设流程全解析

Loop Library架构内幕：Cloudflare Worker加SQLite Durable Object构建智能体循环目录

【免费下载链接】loop-libraryA library of practical AI-agent loops and an installable skill for finding, adapting, and designing repeatable agent workflows.项目地址: https://gitcode.com/gh_mirrors/lo/loop-library

Loop Library 是一个收集实用 AI 智能体循环（Agent Loop）的开源目录项目，它的后端只用一个 Cloudflare Worker 和 SQLite Durable Object，就完成了目录存储、版本控制、备份恢复、防滥用表单与投票系统的全部功能。本文带你拆解这套架构的设计思路，看看它如何用极少的基础设施撑起一个完整的智能体循环目录站点。

一、整体架构：一个 Worker，三个 Durable Object

整个后端位于 loop-library/worker/ 目录，入口是 src/index.js。它在 wrangler.jsonc 中注册了三个 Durable Object 绑定，各司其职：

这个设计的关键点：数据不是放在外部数据库里，而是直接以 SQLite 的形式嵌入 Durable Object 内部。Cloudflare 会为每个命名对象保证单实例串行处理，天然避免了并发写冲突，也不需要维护任何独立的数据库服务。

二、SQLite Durable Object：目录存储是怎么设计的

打开 src/catalog-store.js 可以看到，LoopCatalog在构造函数里直接用state.storage.sql建了三张表：

• loops：当前每个 loop 的最新状态，slug作主键，状态只能是draft、published、archived之一
• loop_revisions：追加式修订日志，每次发布、改稿、归档都留一条完整快照
• catalog_settings：存放开关类配置，比如"公开目录是否已激活"

一个 loop 的完整文档以 JSON 整块存入document_json字段，而结构校验由 src/loop-schema.js 负责。worker/examples/loop.json 给了一份完整示例：编号、slug、标题、prompt、验证标准、步骤、关键词、相关 loop……这些字段正好对应循环详情页、目录、搜索和面向智能体的各种输出格式所需的全部内容。

用修订号做乐观并发控制

写入时（upsert方法）有一个精巧的细节：调用方必须带上读取时拿到的expectedRevision，服务端发现实际修订号不一致就返回 409 冲突。这就是教科书式的乐观锁——两个管理员同时编辑同一个 loop 时，后写的人会被明确拒绝而不是静默覆盖。

三、备份与恢复：带摘要校验的安全恢复流

目录数据可以完整导出（/export），恢复过程则分三步走：/restore/start开始、/restore/chunk分块上传修订记录、/restore/finalize收尾。

这套流程值得新手学习的地方有三点：

1. 只能恢复到空的目录库——避免覆盖线上数据
2. 分块上传必须按修订 ID 严格升序，每块都做一次 SHA-256 链式摘要（chainRevisionDigest），任何乱序或篡改都会立刻报 409
3. 收尾时逐条核对每个 loop 的最新修订与当前文档一致，并回算created_at/updated_at

AGENTS.md 中明确要求：首次激活必须携带人工审核过的 bootstrap 目录摘要（BOOTSTRAP_CATALOG_DIGEST），数据库才能对外激活。宁可麻烦，也不让未经审查的内容直接上线。

四、请求路由：从 Worker 到 HTML 页面

loop-routes.js 是这个 Worker 的"前台"。一个请求进来后，它先判断路径类型：

• /api/loops：返回 JSON API，供站点前端和第三方调用
• /loops/<slug>：动态渲染出完整的循环详情页 HTML
• /catalog.json、/catalog.md、/llms.txt、/sitemap.xml、/feed.xml：同一份数据渲染成多种格式，其中 llms.txt 专门服务 AI 智能体，让没有安装 Loopy 技能的智能体也能直接读取目录
• /admin/loops/*：管理端点，用 Bearer Token 鉴权（比对时先做 SHA-256 哈希再恒时比较，防止时序攻击）

也就是说，首页、详情页、目录、RSS、sitemap 全部来自同一次数据库读取。发布一个 loop 后所有出口同时更新，不存在"页面更新了但 sitemap 没更新"的一致性问题。所有公开响应统一带Cache-Control: no-store，保证发布即时可见。

五、防滥用与投票：另外两个 Durable Object 在做什么

表单提交（提交 loop 建议、订阅周报）是公开端点，天然会被恶意刷。Worker 里为此设计了一条完整的防线：

• Honeypot 陷阱字段：机器人填写则静默返回成功
• Turnstile 人机校验：校验 action、hostname 是否匹配
• 幂等键：同一表单会话重放请求不会重复入库，内容冲突返回 409
• IP 维度限流：建议表单每小时 3 次、每天 10 次，由FormGuard用 SQLite 存储事件窗口并靠 alarm 自动清理过期数据

投票系统（vote-store.js）则简单得多：一张loop_votes表，主键是(loop_slug, voter_key)，一个 GitHub 账号对每个 loop 最多一票，可随时改票或撤票，聚合统计直接用 SQL 的SUM(CASE WHEN ...)一次算出。

六、这套架构给新手的启示 🔍

Loop Library 后端不到千行核心代码，却完整演示了一套现代 Serverless 数据应用的做法：

1. SQLite Durable Object 代替外部数据库——小团队项目的目录、配置、投票完全够用，零运维
2. 追加式修订日志 + 乐观并发控制——免费获得完整的版本历史，且天然支持精确恢复
3. 一次写入，多格式渲染——JSON、Markdown、llms.txt、sitemap 同源输出，人读智能体也读
4. 摘要校验贯穿恢复流程——数据完整性不靠信任，靠密码学证明

想继续深入，可以从 worker/test/ 的测试用例入手，再对照 README.md 中"Notes for maintainers"一节了解发布命令与部署细节。这套架构对任何想自建小型内容目录（文章库、提示词库、模板库）的项目，都是一份很值得参考的蓝图。

【免费下载链接】loop-libraryA library of practical AI-agent loops and an installable skill for finding, adapting, and designing repeatable agent workflows.项目地址: https://gitcode.com/gh_mirrors/lo/loop-library