ITADN
denn-gubsky/loomcycle
代码 动态 Issues2 合并请求27 版本2
denn-gubsky/loomcycle · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

loomcycle

代理运行时，以边车模式运行。
一个 Go 二进制文件与您的应用程序并行。加固的代理循环，两侧均支持 MCP，多副本高可用。Apache-2.0。

🌐 loomcycle.dev  ·  📝 工程博客  ·  📐 架构

release license go sponsor

🌳 稳定且已投入生产使用。 loomcycle 已超越 v1.0 —— 功能完备、经过加固，并具备分发就绪状态（Homebrew、多架构 Docker、一个 Claude Code 插件、TS + Python 适配器、一个 TrueNAS 应用）。经 8 小时浸泡测试验证：127 万电路，380 万代理运行，零泄漏。自 v1.0 以来的开发工作包括新原语及加固 —— 参见 REVISIONS.md 了解近期发布，以及 the releases page 了解完整历史。Apache-2.0。我们欢迎 bug 报告、安全漏洞披露、功能贡献、下游使用者及分支。参见 CONTRIBUTING.md。

它是什么

以 Sidecar 形式存在的智能体运行时。 loomcycle 是一个 Go 二进制文件，大小约 50 MB。它与你的应用程序并行运行，而非嵌入其中。你的应用程序通过 HTTP、gRPC、MCP、TypeScript 适配器或 Python 适配器调用 loomcycle。智能体循环、多提供商路由、内存和通道原语、MCP 服务器身份、OpenTelemetry 追踪以及多副本协调均包含在该二进制文件中。你的应用程序可以保持其原有的开发语言。

与众不同的形态。 当前的智能体系统市场提供三种选择。其一：在应用程序进程中嵌入 Python 或 TypeScript 库。其二：租用绑定于单一供应商 IAM 的托管云服务。其三：通过一个实际上并不运行智能体的网关代理你的模型调用。

loomcycle 是第四种选择。一个轻量级、可自托管的运行时，它既拥有循环又支持你的技术栈已在使用的所有线格式。

已发布内容

按运行时执行的功能进行组织，而非按各组件的落地时间——如需查看逐版本视图，请参阅 REVISIONS.md 以及 GitHub releases。

能力您将获得
提供商通过原生 HTTP 连接 Anthropic、OpenAI、DeepSeek、Gemini、Ollama（云端 + 本地），无需厂商 SDK，统一在 Provider 接口之后。配置驱动的 providers: 映射，按层级/努力程度路由，用户层级回退级联，PinAfterSuccess，模型别名和 model_pattern 通配符。此外，还有一个合成的 code-js 提供商（确定性，零令牌成本）和一个用于负载测试的 mock 提供商。
内置工具Read / Write / Edit / Grep / Glob / NotebookEdit / HTTP / WebFetch / WebSearch / Bash / Agent / Skill / Memory / Channel / History / Path / Document / AgentDef / SkillDef / Evaluation / Interruption / Context。
记忆单一工具上的四个维度：键值对、向量（sqlite-vec / pgvector）、SQL（每个作用域一个数据库，sqlite + postgres 层级），以及一个代理式 记忆层（后台整合，混合召回，具有分层本体论的双时态实体图）。作用域为 agent / user / tenant / run，租户隔离，能力门控。
文档与路径分块图文档（块体存储于 Memory，结构存储于 SQL Memory），支持语义搜索 —— 块体在写入时嵌入，针对散文、Mermaid 标签和图片说明 + 视觉描述采用按类型的策略。内联 [[name]] 链接成为图边，![[…]] 嵌入进行转写，外加反向链接 / 相关 / 未链接提及发现，每个块体的带差异对比的块体历史，可查询的标签和类型/状态，图片和 Mermaid 图表，以及 Markdown + JSON Canvas 导入/导出 —— 所有这些都通过类 Unix 的路径 VFS 进行寻址。
基底内容寻址（SHA-256），运行时可变，租户范围的定义在启动时推送：Agent / Skill / MCPServer / Schedule / Webhook / MemoryBackend / A2A / Team / Volume / Credential / OperatorToken。通过所有传输层编写；跨部署进行验证或分叉。
多智能体通过 Agent 工具实现的子智能体，parallel_spawn 扇出，外部批量扇出，常驻/交互式子智能体，以及状态机团队编排器。
隔离每个智能体的只读/读写文件系统卷（默认沙箱化），进程内Bashbox，以及带有开发工具链的沙箱化代码执行边车。
触发器调度器，入站Webhooks（HMAC 解析前验证），以及A2A 对等互操作。
多租户绑定到权威 (tenant, subject, scopes) 的按主体（per-principal）Bearer 令牌；按路由的 HTTP 和按 RPC 的 gRPC 门控；跨状态平面和定义平面的租户隔离。按租户的凭证、按作用域的使用/成本归因、令牌预算、数据保留 + 主体擦除界面，以及派生的目录（谁在这里，我们为他们保留了什么）。单租户保持为默认设置。
上下文一个压缩子系统（手动 / 自动 / 自管理，按代理的策略向下流经生成树），包括秘密脱敏器在内的上下文转换插件，以及 {{memory:…}} / {{tool:…}} 提示词扩展。
运维暂停 / 恢复 / 快照，支持跨实例恢复，多副本高可用（Redis 取消发布订阅、基于数据库的会话锁、单例清扫器），OTEL + Prometheus，按租户的公平性，工具使用钩子。
接口HTTP+SSE，gRPC，作为 MCP 服务器的 loomcycle（loomcycle mcp [--upstream]），MCP 客户端，TS（@loomcycle/client）和 Python 适配器，一个 n8n 包，一个 OpenAI 兼容的 LLM 网关，以及一个嵌入式 React Web UI。
分发Homebrew，多架构 Docker，一个 Claude Code 插件，嵌入式配置预设 + 代理捆绑包，以及一个 TrueNAS SCALE 应用。

两种姿态，一个二进制

相同的 Go 二进制文件，相同的配置模式。操作员通过切换几个环境变量来选择姿态。

姿态配置形态用例
真正的托管沙箱LOOMCYCLE_BASH_ENABLED=0，无 volumes: 块（默认沙箱——代理没有磁盘访问权限），LOOMCYCLE_HTTP_HOST_ALLOWLIST 为空，LOOMCYCLE_HTTP_CALLER_AUTHORITATIVE=1。所有工具默认拒绝；代理只能访问调用者每次请求的 allowed_hosts 所允许的内容。处理不可信提示词的共享服务器部署。运行时能够抵御对抗性输入。
代理开发环境启用 Bash，一个指向工作区的 default 读写 volumes: 条目，宽泛的 allowed_hosts，可选的本地 Ollama 用于离线工作。本地开发。内部可信操作员。单用户研究工作站。

信任边界是 操作员 / 调用者。操作员配置是底线；调用者可以按请求缩小范围，但绝不能扩大。Bearer 令牌（LOOMCYCLE_AUTH_TOKEN）是权威。将任何持有令牌的人视为完全可信，可以驱动运行时。要在沙箱姿态中实现真正的隔离，请在容器或虚拟机中运行 loomcycle。Bash 受到限制（cwd、环境清理、输出边界、超时），但它 不是 内核级沙箱。

安装

选择适合的路径。所有四种方式都提供相同的单个静态二进制文件 以及 v0.11.1 的 init / doctor 首次运行流程。Context.help installation 详细说明了每一种方式。

# Homebrew (macOS + Linux)
brew install denn-gubsky/loomcycle/loomcycle

# Docker (v0.11.2+; pull works on amd64 + arm64 including Apple Silicon)
docker pull denngubsky/loomcycle:latest

# go install from source (skips Web UI embedding — for dev only)
go install github.com/denn-gubsky/loomcycle/cmd/loomcycle@latest

# Direct tarball (one of darwin-arm64 / darwin-amd64 / linux-arm64 / linux-amd64)
curl -L https://github.com/denn-gubsky/loomcycle/releases/latest/download/loomcycle-darwin-arm64.tar.gz | tar xz

快速开始（秒级，已认证）

loomcycle init --with-token   # writes config + mints a token to ~/.config/loomcycle/auth.env (0600)
export ANTHROPIC_API_KEY=sk-...   # (or OPENAI_API_KEY / DEEPSEEK_API_KEY) — at least one provider key
loomcycle doctor              # verify env + keys + storage + the just-minted token
loomcycle                     # starts on 127.0.0.1:8787 (auto-loads auth.env — no shell-rc edit)

init --with-token 会打印 Web UI 的 URL（http://127.0.0.1:8787/ui）。打开它，然后在登录提示处粘贴 ~/.config/loomcycle/auth.env 中的令牌。（令牌保存在 0600 文件中，绝不会嵌入到 URL 中。一个 ?token= 链接会将 bearer 泄露到浏览器历史记录以及任何前置代理的日志中。）loomcycle 和 loomcycle doctor 都会从配置目录自动加载 auth.env；真实的 export LOOMCYCLE_AUTH_TOKEN=… 始终会覆盖它。

Bootstrap tiers

选择适合的层级。每一层都是上一层的超集。只有当配置了某些内容时，才会强制执行身份验证，因此 Tier 1 完全不需要令牌。

Tier 1: zero-config dev (open mode, localhost)

无需令牌，无需标志。这是快速体验 127.0.0.1 的最快方式。

loomcycle init               # config only — no secret written
export ANTHROPIC_API_KEY=sk-...
loomcycle                    # open mode: /v1/* + /ui pass through unauthenticated (logs a warning)
open http://127.0.0.1:8787/ui

在没有 LOOMCYCLE_AUTH_TOKEN 且没有铸造令牌的情况下，运行时在 localhost 上以开放模式运行。所有请求均被允许，whoami 返回一个合成的管理员。适用于 10 秒的冒烟测试。切勿将此暴露到 localhost 之外。

第二层：单个共享令牌（推荐的默认设置）

一个 bearer 门控所有操作。init --with-token 是简易按钮（如上所述）。等效的手动设置：

loomcycle init
export LOOMCYCLE_AUTH_TOKEN=$(openssl rand -hex 32)   # or: loomcycle init --with-token
export ANTHROPIC_API_KEY=sk-...
loomcycle
open "http://127.0.0.1:8787/ui?token=$LOOMCYCLE_AUTH_TOKEN"   # sets the cookie once

将持有该令牌的任何人都视为完全受信任，可驱动运行时。

第三层：多租户、按主体划分的令牌（RFC L，v0.17.0）

为每个开发者 / 应用铸造一个独立的 bearer，每个都绑定到一个权威的 (tenant, subject, scopes)。就地迁移第二层部署，无需停机：

# promote your existing shared token into the substrate, then mint scoped tokens
loomcycle operator-token create --copy-from-env --name ops --tenant ops --scopes substrate:admin
loomcycle operator-token create --name acme-app --tenant acme --subject alice --scopes runs:create

首位管理员 OperatorTokenDef 禁用了旧版共享令牌回退机制。按路由的 HTTP 和按 RPC 的 gRPC 作用域。Web UI 变为角色感知（超级管理员与租户）。参见 Context.help operator-tokens 以及 REVISIONS.md 中的 v0.17.0 说明。

冒烟测试任意层级：

curl http://127.0.0.1:8787/healthz
# {"ok":true}

实际调用（来自另一个终端）：

curl -N http://127.0.0.1:8787/v1/runs \
  -H "Authorization: Bearer $LOOMCYCLE_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"default","segments":[{"role":"user","content":[{"type":"trusted-text","text":"Hello"}]}]}'

从检出构建（用于开发）：

make build-all       # UI + binary in one shot; output → ./bin/loomcycle
./bin/loomcycle --config loomcycle.example.yaml

多副本集群演示（v0.12.x）。 关于通过单条命令 docker compose up 部署的集群（2 个 loomcycle 副本、Postgres、nginx LB）及其验证脚本，请参阅 examples/cluster/README.md。完整的运维手册见 docs/MULTI-REPLICA.md。

发展方向

近期发布记录见 REVISIONS.md；路线图见 docs/PLAN.md。

loomcycle 已越过功能完备里程碑（v1.0.0），此后的主线一直是基础原语与加固：内存、文档、团队、沙箱、保留策略 与擦除。当前方向是基于 agentic-memory 子系统及其构建的文档界面。

架构

三张图展示了同一运行时的不同视图：

loomcycle 架构 — 顶部为客户端（应用服务器、CLI、TS/Python SDK、Claude Code & MCP 编排器、通过 OpenAI 兼容 shim 连接的 LangChain/n8n），中间为单个 Go 二进制文件（1..N 副本；五个线协议界面，包括 HTTP+SSE / gRPC / Web UI / 带 40 个元工具的 MCP 服务器 / LLM Gateway → 承载者认证 + 并发信号量 + 每用户公平性 → 36 方法的 connector.Connector → 代理循环 → 带 19 个内置工具 + MCP 客户端传输 + 子代理运行器的工具调度器 → 覆盖会话、运行、事件、内存、通道、基底表的 SQLite/Postgres 存储，以及 replicas+user_quotas+runtime_state+hooks），发出 span 的 OpenTelemetry 边车，以及底部的外部服务（包括 anthropic-oauth-dev 在内的七个 LLM 提供商、三个嵌入器、外部 MCP 服务器 cloud)

Diagram source: docs/architecture.d2 (regenerate with d2 docs/architecture.d2 docs/assets/architecture.png).

Connector detail. v0.8.15 的 Connector 抽象层（主图中间的粉色块）是所有 wire transport 分发所经过的架构锚点。详细图列出了全部 36 个方法，并展示了哪些 transport 实现了（IMPLEMENT）、消费了（CONSUME）以及镜像了（MIRROR）该接口：

connector.Connector interface with 36 methods grouped by domain (run lifecycle, agent registry, substrate tools, channel CRUD, pause/snapshot, hook registry) — HTTP server IMPLEMENTS as the canonical business logic, MCP and gRPC servers CONSUME via direct Go method dispatch, TypeScript and Python adapters MIRROR over the HTTP wire

Source: docs/architecture-connector.d2.

Multi-replica cluster mode (v0.12.x). 当为每个进程设置 LOOMCYCLE_REPLICA_ID 且使用 Postgres 后端时，loomcycle 作为集群运行在任何 HTTP 负载均衡器之后。共享的 Postgres 同时充当跨副本取消、暂停/恢复、运行状态扇出以及配额通知的 LISTEN / NOTIFY 背板。SQLite 在启动时拒绝集群模式。

多副本集群部署 — 客户端访问 HTTP 负载均衡器（nginx/Caddy/Traefik/HAProxy/ELB，支持 SSE），该负载均衡器在 N 个副本之间进行轮询，每个副本具有唯一的 LOOMCYCLE_REPLICA_ID + 30 秒心跳，所有副本共享一个 Postgres 数据库，该数据库既包含基础表（replicas、user_quotas、runs.replica_id、runtime_state，以及 v0.12.x 中新增的 hooks），也包含承载 cancel/pause/runstate/channel/quota/hook 主题的 LISTEN/NOTIFY 背板，单例清扫器通过 pg_try_advisory_lock 进行门控

来源：docs/architecture-cluster.d2。操作员运行手册：docs/MULTI-REPLICA.md。演示：examples/cluster/README.md。

完整的请求流程、抽象和并发模型：docs/ARCHITECTURE.md。

适配器

  • TypeScript。 npm install @loomcycle/client（参见 adapters/ts/）。HTTP + SSE。
  • Python。 pip install loomcycle（参见 adapters/python/）。基于 grpc.aio 的异步。

安全亮点

  • 无供应商二进制参与。纯 HTTP 调用提供商 API。无子进程认证继承。
  • 默认拒绝一切。 所有内置工具在通过环境变量配置前均处于禁用状态。在设置 tools 之前，每个代理均无任何工具。
  • 双层策略 + 按请求收窄。 操作员下限在环境变量中；代理收窄在 yaml 中；调用者按运行收窄。调用者永远无法放宽。
  • SSRF 防御。 在拨号层实施主机名白名单 + RFC1918/回环/链路本地 IP 阻止。可抵御 DNS 重绑定。
  • 恒定时间 Bearer 认证。 在 HTTP 和 gRPC 上均使用 sha256+CTC。
  • Bash 是受限的，而非隔离的。 如果需要真正的隔离，请在容器或虚拟机中运行。

完整的安全模型及双层默认拒绝详解：docs/TOOLS.md。

文档

仓库侧文档（此目录）：

  • docs/ARCHITECTURE.md. 请求流程、提供者抽象、代理循环、子代理、技能、存储、并发、取消。
  • docs/TOOLS.md. 两层默认拒绝模型、每个内置工具、MCP / LocalAPI 集成、按请求收窄。
  • docs/CUSTOMIZING_AGENTS.md. 向聊天代理添加技能、工具或整个 MCP 服务器：能力模型（谁可以放宽工具上限以及原因）、技能何时免费 vs 何时必须派生新代理、mcp__<server>__* 授权、动态代理的原地放宽，以及委托。
  • docs/PATH.md. Path 原语（RFC AL）：基于 Memory / Volumes / Documents 的类 Unix VFS — dirent 模型、六个操作，以及非运行时的跨传输表面（HTTP / gRPC / MCP / TS / Python）。
  • docs/DOCUMENTS.md. Document 原语（RFC AK）：分块图文档 — 内容/结构分离、13 个操作、乐观并发、原子删除，以及非运行时的跨传输表面。
  • docs/MCP_INTEGRATION.md. 端到端 MCP HTTP 管道：请求生命周期、${run.user_bearer} 替换、模型可见性边界、将 REST API 封装为 loomcycle 可消费的 MCP 服务器的配方。
  • docs/MCP_SERVER.md. 在 Claude Code / Claude Desktop 中注册 loomcycle 作为 MCP 服务器。提供 Docker / Homebrew / 直接二进制传输的复制粘贴配置片段，以及 loomcycle mcp install 辅助工具。
  • docs/CLAUDE-CODE.md. 从 Claude Code 驱动 loomcycle：推荐的 claude-code-plugin-loomcycle 插件（斜杠命令 + 技能 + 钩子）vs. 手动 loomcycle mcp install 路径。
  • docs/CONFIGURATION.md. 操作员配置指南：provider / tier / user_tier 解析规则，四种 cookbook 模式（单 / 多 provider × 单 / 多 user-tier），models: 别名映射，以及 agent .md frontmatter 字段参考。
  • docs/SEARCH.md. Web-search providers (RFC BB)：目录 + 回退电路，search_providers / search_priority 配置，按 agent 列表，operator/tenant 密钥，路由视图——以及自托管 SearXNG 部署配方（sidecar + 三个 settings.yml 旋钮 + 验证）。
  • docs/POSTGRES.md. Postgres 后端操作员指南：配置，迁移，sqlite → postgres 运行手册，并发基准测试。
  • docs/GRPC.md. gRPC 接口：启用，与 HTTP + SSE 的线格式一致性，错误映射，Python 适配器快速入门。
  • docs/PLAN.md. 公开路线图和当前方向。
  • REVISIONS.md. 最近版本的发布说明；旧版本在 releases page。
  • CONTRIBUTING.md. 贡献政策（在 v1.x 之前对外部 PR 关闭）。
  • CLAUDE.md. 在此仓库中工作的 agent 项目指南 (Claude Code)。

二进制内文档（捆绑了 Context.help 个主题；代理直接读取这些内容，操作员针对运行中的实例访问 GET /v1/_help/<topic>）：

  • installation。所有四种安装路径（Homebrew、Docker、go install、直接 tarball），包含验证 + 故障排除。
  • getting-started。首次运行指南：init → 设置环境变量 → doctor → 运行。
  • llm-gateway。直接 LLM 路由端点（v0.11.0；面向 n8n + LangChain 消费者）。
  • openai-compat。即插即用的 OpenAI SDK 垫片（v0.11.3 聊天 + v0.11.4 嵌入），附带 Python + TypeScript 示例。
  • fairness。每用户并发配额策略。
  • observability。OTEL 追踪导出设置。
  • vector-memory、voyage-embedder、sqlite-vec。向量记忆后端。
  • dynamic-mcp。在运行时注册 MCP 服务器。
  • bash-security。Bash 工具的受限而非隔离的安全姿态。

通过针对运行中的实例执行 GET /v1/_help 查看完整列表。

赞助

如果 loomcycle 对您或您的团队有用，GitHub Sponsors 有助于资助持续开发。欢迎个人支持者和企业赞助商。

无论如何，运行时保持 Apache-2.0 许可。赞助资助 v1.x 的开发周期：Helm chart、操作员手册、设置 UI，以及保持二进制小巧和底层稳定的持续工程。

当前赞助商列于 BACKERS.md（并在 loomcycle.dev/sponsors 附带标志）。

许可证

Apache-2.0。参见 LICENSE。