LoopSkill

LoopSkill

面向你已有技能的本地 CLI，以及可自托管的注册表，可从中拉取更多技能。 从 CLI 开始——它无需账号，而且执行 import/diff 时不会发起网络请求。

---

开始使用编码 Agent

将以下内容粘贴到 Claude Code、Codex、Cursor 或任何带有 shell 的编码 Agent 中：

Clone https://github.com/wisechef-ai/loopskill-api, read AGENT_SETUP.md in it,
and follow it to install the loopskill CLI and verify it with the drift demo.
Only set up the self-hosted registry (Docker) if I ask for it.
Ask me before deleting any data, stopping containers or processes, using sudo,
or writing into my real skill directories. Never paste API keys or tokens
into this chat. When it works, show me the verify output and what to do next.

Agent 将会：

• 首先检查 Python、venv 和演示目录，并在遇到需要删除或覆盖的内容时停止；
• 将 CLI 安装到项目本地的 .venv，并通过路径调用；
• 使用下面的漂移演示验证其功能（先发现漂移，再确认同步）；
• 提供用于处理你实际技能的下一条命令，并说明哪些命令会访问网络或写入文件。

---

60 秒：可重复地查看技能漂移

以下是完整且自包含的实际记录。将下面的每条命令都粘贴到干净的 shell 中——它会伪造两份“技能”安装，编辑其中一份并删除另一份以模拟漂移，然后进行差异比较。你将得到完全相同的输出；这里的任何内容都不依赖你已安装的技能。

git clone https://github.com/wisechef-ai/loopskill-api && cd loopskill-api
python3 -m venv .venv && ./.venv/bin/pip install ./cli
alias loopskill=./.venv/bin/loopskill   # or add ./.venv/bin to PATH
loopskill --version

# --- fabricate a "machine" with two skills, take a snapshot ---
mkdir -p /tmp/loopskill-demo/home/.claude/skills/agent-reach
mkdir -p /tmp/loopskill-demo/home/.claude/skills/recipes
cat > /tmp/loopskill-demo/home/.claude/skills/agent-reach/SKILL.md <<'EOF'
---
name: agent-reach
description: Give your agent eyes on the internet.
---
Body v1.
EOF
cat > /tmp/loopskill-demo/home/.claude/skills/recipes/SKILL.md <<'EOF'
---
name: recipes
description: Recipe search skill.
---
Body.
EOF
loopskill import --home /tmp/loopskill-demo/home -o /tmp/loopskill-demo/machine-a.lock.json

# --- simulate drift: edit one skill, delete the other ---
cat > /tmp/loopskill-demo/home/.claude/skills/agent-reach/SKILL.md <<'EOF'
---
name: agent-reach
description: Give your agent eyes on the internet.
---
Body v2 — updated tool list.
EOF
rm -rf /tmp/loopskill-demo/home/.claude/skills/recipes

loopskill diff /tmp/loopskill-demo/machine-a.lock.json - --home /tmp/loopskill-demo/home

loopskill 0.3.0
loopskill import: wrote /tmp/loopskill-demo/machine-a.lock.json (2 skill(s) across 1 client(s))
loopskill diff: /tmp/loopskill-demo/machine-a.lock.json  vs  <live scan>

[claude] DRIFT DETECTED
  - only in /tmp/loopskill-demo/machine-a.lock.json: recipes
  ~ changed:          agent-reach
[codex] in sync (0 skill(s))
[cursor] in sync (0 skill(s))
[hermes] in sync (0 skill(s))

DRIFT FOUND

退出代码为 1——发现漂移，适合脚本和 CI。若没有任何改动，再次运行 loopskill diff，退出代码将为 0。这就是全部要点：两份快照，一条命令，在读完这段文字的时间里就能看到漂移——针对你实际拥有的技能，而不是演示；只需去掉 --home。

import 和 diff 不会发起任何网络请求——这不是文档字符串中的承诺，而是结构上的保证：支持网络的代码仅位于一个模块（loopskill.pull）中，import/diff 从不导入该模块；并且 cli/tests/test_loopskill_cli.py::test_import_and_diff_make_zero_network_calls 会在运行这些命令期间破坏 socket.socket，以此证明这一点。

完整的 CLI 参考、锁文件格式以及 pull/apply（这两条命令会访问网络，需主动选择使用）：cli/README.md。

---

这个仓库实际包含什么

两项内容，建议从 CLI 开始：

1. cli/ — 一款基于设计而无需联网的本地工具，用于处理你已保存在磁盘上的技能。执行 import/diff 无需账号、服务或依赖 LoopSkill。对于 pull/apply，可将它指向任何提供相同已知格式的 bundle 索引的注册表，也可以完全不运行这些命令。
2. app/ — 一个可自托管的 FastAPI 注册表（本仓库）；CLI 可选择通过 pull/apply 与其交互，它还在 loopskill.io 提供可浏览的目录。注册表不是从这里开始的理由——先在自己的机器上运行 CLI，无需先创建账号。

循环：先说明两项限制

注册表还提供 10 个经过审核的循环（scripts/seed_starter_catalog.py）。 POST /api/loops/{slug}/run 是同步的，可在任何地方运行。将循环放到 机群成员 上，让它按计划触发，则是另一种路径，有两项限制值得在基于它构建前了解：

1. 除非循环自身的提示词要求，否则循环不会报告任何信息。 遥测数据之所以存在， 只是因为循环的提示词调用了 scripts/loopskill-emit-run.sh。没有其他组件会观察触发情况——调度器不会，服务也不会。省略这一行，循环就会一直运行，而所有仪表板都显示为零。这就是 loop_runs 一年间一直为 1 的原因。
2. Cron 物化仅支持 Hermes。 app/loop_apply.py 会写入 Hermes 调度器的 ~/.hermes/cron/jobs.json，目前还没有其他组件支持这种格式。在 Codex、Claude 或 OpenCode 主机上，scripts/install-loop-apply.sh 会拒绝安装，而不是装上一个永远无法收敛的 Cron。技能路径跨供应商通用；计划循环路径则不通用。

docs/SELF_HOST.md 中提供了这两项内容的端到端说明。

自托管注册表（可选，用于针对自己的实例执行 pull/apply）

git clone https://github.com/wisechef-ai/loopskill-api
cd loopskill-api && docker compose up

零配置：SQLite、自动生成的开发密钥，以及预置的入门目录。 首次启动时会打印你的开发 API 密钥。完整指南（包括 Postgres/生产环境路径）： docs/SELF_HOST.md。

然后运行一个循环——运行器已就绪（验证模式无需大模型）：

# the zero-config Docker Compose stack always boots with this dev key
# (override via WR_API_KEY in production) — same value the boot banner prints
curl -X POST localhost:8200/api/loops/hello-world-loop/run \
  -H "x-api-key: rec_dev_wiserecipes_local_testing_key"
# → {"passed": true, "confinement": "bounded", "duration_seconds": 0.03, ...}

一个全新的注册表不仅会列出循环，还会在强制限制下执行循环的成功检查，并给出判定结果。

---

此代码库的实际规模（以及“为什么这么大”的坦诚回答）

347 个应用 Python 文件、85,076 行应用代码、119 个 Alembic 迁移、 506 个测试文件（基于干净检出的统计）、2 个 GitHub 星标、0 个分叉（2026-08-21 通过 gh repo view wisechef-ai/loopskill-api --json stargazerCount,forkCount 测得）。

这个比例确实如此，而且并不好看。Issue #68 曾就此提问；坦诚的回答——包括为什么代码库是在一款可用的食谱搜索产品经过实战检验的身份验证／Stripe／沙箱技术栈之上发展起来，而非从空白注册表开始，以及因此提交的具体精简内容——见 docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md。 每次运行时，tests/test_readme_claims.py 都会根据实时文件系统测量结果核验上述每个数字；如果本段内容像 #68 中的原始数字那样偏离实际情况，构建就会失败。

---

核心 API 一览（自托管注册表）

方法	路径	描述
GET	/api/healthz	DB 健康检查
GET	/api/skills/search	全文搜索与向量搜索混合的技能搜索
GET	/api/skills/{slug}	技能详情与版本
GET	/api/bundles/discover	浏览公开套件
GET	/api/loops	列出循环（及其安全契约）
GET	/api/loops/{slug}	循环详情——契约、运行次数、评分
POST	/api/loops	发布循环（验证契约）
POST	/api/loops/{slug}/run	运行循环验证 → 目标通过／失败判定
POST	/api/loops/{slug}/rate	为循环评分 1–5（社会认可信号）
GET	/api/personalities	列出可部署的个性

原生支持 MCP：Agent（Claude Code、Cursor，以及任何支持 MCP 的工具）可通过该协议发现并安装。也提供签名 URL 的 tarball 获取方式，可直接下载。

架构

FastAPI + SQLAlchemy。同一条 Alembic 迁移链可在 SQLite （自托管）和 Postgres（托管）上运行——不会出现 create_all 漂移；SQLite 启动时会重放真实迁移，因此自托管运行的内容与生产环境一致。完整模块布局：AGENTS.md。

认证流程

APIKeyMiddleware.dispatch()
  └─ validate_key(db, x-api-key)
       └─ request.state.auth_ctx = AuthContext(scope, user_id, tier, …)
            └─ REST routes / MCP tools / runner call authz.can_*() predicates

API 密钥以 rec_ 为前缀，并通过 x-api-key 请求头传递。大多数 读取端点（搜索、详情、发现）无需认证。免费层级的技能可以匿名安装，无需密钥（200 + tarball）；安装 付费层级的技能、发布、运行和评分都需要密钥。

---

开发

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pre-commit install                       # ruff, bandit, mypy --strict, actionlint, yamllint

pytest -q                                # fast run
pytest -n auto --cov=app --cov-fail-under=80   # the CI gate

alembic upgrade head                     # apply migrations before first start (non-SQLite)
uvicorn app.main:app --reload --port 8201

沙箱（仅限 Linux）： 内核沙箱（app/sandbox/）需要 firejail 或 bubblewrap。 如果两者都无法使用（macOS、加固型容器），循环运行器会回退到受限 模式——POSIX rlimits + 清理后的环境变量 + 隔离的工作区——循环仍可运行；响应会声明 它实现的 confinement 级别。多租户集群的运营者可设置 WR_LOOP_RUN_REQUIRE_SANDBOX=true 来拒绝受限模式执行，并要求使用真正的内核沙箱。

面向 AI Agent 的贡献者指南：AGENTS.md。

---

为什么采用开放核心模式

整个注册表都是开源产品（MPL-2.0）。可在任何地方自行托管—— docker compose up 就能获得完整体验，而非试用版，且不会向外发送任何数据。托管方案的卖点是“无需自行运行”，而不是限制功能。与 n8n / PostHog / Supabase 的做法相同。

许可证

MPL-2.0——参见 LICENSE。整个注册表都是开源的；我们只对托管服务收费。

链接

• CLI（从这里开始）： cli/README.md
• 主页： loopskill.io
• 自托管指南： docs/SELF_HOST.md
• Issue #68 答复： docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md
• 贡献（AI Agent）： AGENTS.md