jakecastillo/sloppy-joe

# 🥪 Sloppy Joe **提供受治理的 AI 运维。** Sloppy Joe 是一个开源的、与模型无关的 **控制循环**，旨在清理在生产环境中运行 AI 时的糟糕状况。它位于你已运行的 LLM gateway *之上*，并将模型层的信号——成本飙升、 fallback 风暴、延迟/质量倒退、 guardrail 触发、 provider 宕机——转化为**受治理、经审计、通过 Git 审查的自动化响应**。 ## 一句话简介 一次成本 / eval / guardrail 违规会触发一项受治理的、作用域受限的、经审计的补救措施，其**策略是 Git 中的一个文件，你可以在 PR 中审查它并在 CI 中重放它**——它作为任何 gateway 都可以应用的、已签名且可逆的 intent 来执行。 ## 体验感受 ``` # 单次执行：立即通过您的规则运行一个 signal（执行操作，然后写入 audit） $ sloppy inject --now --rules examples/rules examples/signals/cost-spike.json applied route_override target=gpt-4o applied page target=gpt-4o # CI gate：重放一个 fixture 并查看会触发什么（无副作用） $ sloppy test --replay examples/fixtures/replay.jsonl --rules examples/rules replay: 4 signal(s), 6 intent(s) would fire # 防篡改 audit log $ sloppy audit tail chain: verified ✓ (3 entries) # 持续运行：HTTP ingest + TTL auto-revert + /status metrics $ sloppyd --rules examples/rules 🥪 sloppyd listening on :8723 ``` ## 状态 ✅ **v0 已实现（计划 1–4）。** 包括一个可导入的 Go 库[^lib] + `sloppy` CLI + `sloppyd` daemon。所有包的 `go test ./...` 均通过（green）；静态的 `CGO_ENABLED=0` 二进制文件。设计和计划位于 [`docs/superpowers/`](docs/superpowers/)。与设计合作伙伴的 **Phase-0 需求验证** 正在同步进行（参见 [`docs/vision.md`](docs/vision.md)）。 [^lib]: 可导入的核心是 `github.com/sloppyjoe/sloppy` 模块（`cmd/` 之外的所有内容）；请通过 `sloppyjoe "github.com/sloppyjoe/sloppy"` 来导入。早期设计文档中的 `libsloppyjoe` 名称从未作为独立工件发布。 ## 架构 Sloppy Joe 是一个**控制循环，而不是 gateway**——它位于你已运行的 LLM gateway 旁边，消费其遥测数据，并通过狭义的、已签名的、可逆的 intent 对其进行反向操作。它永远不会出现在推理请求的热路径上，也永远不会持有你的 provider 密钥。 ``` flowchart LR apps["Apps / agents"] -->|inference requests| gw subgraph GW["LLM gateway — you already run it (not built by Sloppy Joe)"] gw["LiteLLM · Bifrost · Envoy AI Gateway"] keys[("provider keys live HERE")] end gw --> prov["OpenAI · Anthropic · Ollama / vLLM"] subgraph SJ["Sloppy Joe — AI-ops control loop (off the hot path)"] auth["ee/ API-key RBAC"] subgraph ING["ingest (HTTP)"] i1["POST /v1/signals"] i2["POST /v1/usage"] i3["POST /v1/otlp/metrics"] end eng["engine: reconcile → CEL → sign → govern → idempotent"] rls[("rules/*.yaml + CEL")] subgraph ST["state.Store"] led[("cost ledger")] aud[("hash-chained audit")] rev[("pending TTL reverts")] end brk["secret broker (admin / notify tokens only)"] subgraph ACT["actuators — signed, reversible intents"] ac1["LiteLLM route_override"] ac2["GitHub issue"] ac3["Slack page"] ac4["Bifrost · Envoy"] end end gw -. OTel telemetry .-> ING auth --> ING ING --> eng rls --> eng eng <--> ST brk --> ACT eng --> ACT ac1 -. admin API .-> gw ac4 -. admin API .-> gw ac2 --> ext1["GitHub"] ac3 --> ext2["Slack"] subgraph BK["state backends"] db1[("SQLite — solo")] db2[("Redis — multi-replica")] end ST --- db1 ST --- db2 subgraph BIN["binaries"] c1["sloppy CLI — inject · test --replay · audit · doctor"] c2["sloppyd — ingest + TTL revert + /status"] end c1 --> eng c2 --> ING ``` 运行时循环——**观察 → 决策 → 执行 → 记录 → 回滚**——全部在请求热路径之外进行： ``` sequenceDiagram participant GW as Gateway (OTel) participant IN as Sloppy Joe ingest participant EN as engine participant ST as state (ledger/audit/reverts) participant AC as actuator GW-->>IN: telemetry / signal (cost burn, latency, fallback…) IN->>EN: Signal EN->>ST: read cost / policy state EN->>EN: CEL match? `for:` window held? EN->>EN: build + ed25519-sign RemediationIntent EN->>ST: idempotency check (skip if already applied) EN->>AC: Apply (reroute / open issue / page) AC-->>GW: admin API (reroute) EN->>ST: mark applied + append hash-chained audit Note over EN,ST: TTL elapses (sloppyd ticker) EN->>AC: Revert EN->>ST: mark reverted + audit ``` ## 快速开始 ``` go build -o bin/sloppy ./cmd/sloppy go build -o bin/sloppyd ./cmd/sloppyd # 通过示例规则触发一个已记录的 signal，然后读取 audit ./bin/sloppy inject --now --rules examples/rules --db /tmp/sloppy.db examples/signals/cost-spike.json ./bin/sloppy audit tail --db /tmp/sloppy.db # 根据已持久化的公钥验证每个已应用 intent 的 ed25519 签名 # (sloppy.key.pub)。如果任何签名验证失败，则以非零状态退出 —— 这是一个可作 CI gate 的检查。 ./bin/sloppy audit --verify-sigs --db /tmp/sloppy.db --key sloppy.key # 或者运行 daemon 并通过 HTTP POST signals / usage ./bin/sloppyd --rules examples/rules --db /tmp/sloppy.db & curl -XPOST localhost:8723/v1/signals -d @examples/signals/cost-spike.json curl localhost:8723/status ``` **命令：** `sloppy inject` · `sloppy rules validate` · `sloppy test --replay` · `sloppy audit tail` · `sloppy audit --verify-sigs` · `sloppy doctor` · `sloppyd` (daemon)。 - **可验证的签名：** intent 经过 ed25519 签名；应用的审计条目会持久化已签名的规范字节 + 完整签名。`sloppy audit --verify-sigs` 会重新计算每个 intent 的规范字节，并根据持久化的公钥（`sloppy.key.pub`）验证签名，如有任何失败将以非零状态退出。私钥（`sloppy.key`，模式 `0600`）是伪造可验证 intent 所必需的；仅持有公钥的用户可以验证真实性并检测篡改，但无法进行签名。有关威胁模型，请参阅 [`SECURITY.md`](SECURITY.md)。 - **状态后端：** `sloppyd --store sqlite`（默认）或 `--store redis --redis-addr host:6379`。 - **认证：** `sloppyd --auth` 配合 `SLOPPY_API_KEYS="key1=ingest:write,status:read"`。 - **Gateway：** 要接入真实的 LiteLLM admin API，请设置 `SLOPPY_LITELLM_URL` 和 `SLOPPY_TOKEN_LITELLM`。 - **`for:` 时间窗口：** 一次性的 `sloppy inject --now` 会立即触发；`sloppyd` daemon 会在实时信号流中评估 `for:` 时间窗口。 - **在 CI 中把关规则（无需基础设施）：** `sloppy rules validate ./rules` 会编译每个 CEL `when`，检查 action 类型和 `intent_budget`，并在出错时以非零状态退出——你可以将其直接放入 PR 检查中。 ## 文档 第一次来这里？通往高效产出的最快路径： 1. **运行它** —— 上面的[快速开始](#quickstart)，然后探索 [`examples/`](examples/)（CEL 规则 + 示例信号 + 重放测试夹具）。 2. **了解它为何存在** —— [`docs/vision.md`](docs/vision.md)：问题、转型与切入点。 3. **看看它是为谁准备的** —— [`docs/audience.md`](docs/audience.md)：谁*操作*它，对比谁*受益*于它。 📖 **完整文档地图 → [`docs/`](docs/README.md)** —— 每一份文档，按意图分组（*理解 · 规划 · 验证 · 贡献*）。单一索引，没有重复内容：描述都在那里，本 README 仅作指引。 ## 原则 - **与模型无关** —— 消费 OpenTelemetry GenAI + CloudEvents，通过供应商中立的已签名 intent 执行操作 - **Linux/Unix 优先** —— 单一的静态 Go 二进制文件 - **库优先** —— 一个小型核心库；CLI + daemon 只是轻量级封装 - **从独立打包到企业级均可适用**，源自同一个核心（适配器可替换） - **问题驱动 · 自动化优先** —— 且是多用途的，而非单一用途 - **绝不持有你的 provider 密钥** —— 它们保留在 gateway 中 ## 部署（本地端到端） 一个 `docker-compose.yml` 即可启动整个循环——Ollama（本地模型）、LiteLLM (gateway)、Redis（状态）和 `sloppyd`（控制循环），无需 provider 密钥： ``` docker compose up -d --build # 驱动一次成本飙升并观察其修复过程： curl -XPOST localhost:8723/v1/signals -d @examples/signals/cost-spike.json curl localhost:8723/status ``` 端到端测试针对该堆栈运行。它受 `integration` 构建标签保护，因此绝不会在常规套件中运行： ``` SLOPPY_E2E_BASE=http://localhost:8723 go test -tags integration ./test/e2e/... ``` ## 许可证 Sloppy Joe 采用 **[Apache License 2.0](LICENSE)** 授权——宽松许可， 包含明确的专利授权（这是控制平面 / 基础设施项目的信任标准）。贡献 将通过相同的许可证在[开发者原产地证明](.github/DCO)签署（`git commit -s`）下被接受；请参阅 [CONTRIBUTING](CONTRIBUTING.md)。版权所有 © The Sloppy Joe Authors。 *在开放中构建。一旦 v0 设计锁定，欢迎贡献。*

标签：EVTX分析, Go语言, LLM网关, 人工智能运维, 可审计性, 搜索引擎查询, 日志审计, 用户代理, 程序破解, 自动化响应, 请求拦截