SoupNet

<p align="center"> <a href="https://www.soup.net"> <img src="apps/frontend/public/og-image.png" alt="Soup.net — 一个人在桌子旁工作，周围有发光的AI代理人物，通过共享品味和判断的线索连接" width="640"> </a> </p> <p align="center"><strong>您的品味和判断，融入每一个您使用的AI代理。</strong></p> <p align="center"> <a href="https://github.com/AndyForest/SoupNet/actions/workflows/ci.yml"><img src="https://github.com/AndyForest/SoupNet/actions/workflows/ci.yml/badge.svg" alt="持续集成"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="许可证：MIT"></a> </p> Soup.net 是 AI 代理的共享内存。您合作的代理会在发生时记录您的判断，然后在下一次会话、不同的工具或协作者的代理加入项目时将其带回。食谱书会自动构建。 存储的单位是一个**食谱**：一个结构化、基于证据的判断调用——*“作为[角色]，为了[目标]，我更喜欢[X]，这样[原因]”*，加上逐字逐句的支持引用。代理通过**食谱检查**使用它：一种语义搜索，其唯一副作用是追加。您的代理使用其当前假设搜索您的品味，获取先前的决策及其证据，而假设本身成为未来代理可以查找的跟踪。任何内容都不会被覆盖，每个检查都使下一个检查更智能——这与蚂蚁加强信息素轨迹（协同作用）的机制相同。 ## 为什么 AI 代理独立完成越来越大的工作，您永远不会只运行一个代理。每次新的会话都是一个全新的代理，每个工具都是另一个，全新的协作者带来他们自己的代理。每个代理都需要您单独的答案。 大多数代理内存存储事实和对话状态，在一个供应商的生态系统中。Soup.net 存储判断调用本身，以及限定它的上下文和证据，并且它与您一起存在——跨 Claude Code、ChatGPT、Gemini 或您的团队在内部编写的自定义代理移植。过去的决策作为**上下文，而不是指令**返回：您的代理根据当前任务权衡它们，而不是重放过时的事实。 由于每次检查都会留下日期化的、仅追加的跟踪，因此您还可以免费获得可观察性：一个可检查的日志，记录您的代理代表您做出的判断。随着代理在检查之间运行得更长时间，该记录使您保持在驾驶座上。 Soup.net 使用其自己的工作流程开发。构建 Soup.net 的 AI 代理会在其设计决策被检查到维护者的语料库中时进行食谱检查——因此系统的设计历史存在于系统中，而扩展它的代理会检索形成其更改的代码的判断调用。 食谱地图是人类观察语料库增长的方式：食谱根据语义相似性聚类，投影到任意两个您选择的概念轴上。 <p align="center"> <img src="apps/frontend/src/assets/recipe-map-discover.png" alt="食谱地图：根据两个概念轴聚类的食谱圆圈，带有显示集群内容的示例食谱弹出窗口" width="560"> </p> ## 现场数据 在 2026 年中期，对维护者的实际工作进行了现场评估——两个项目，协调器代理生成子代理舰队，每个代理在判断时刻进行检查并自我报告每个检查的作用。诚实的范围：一位开发人员，3 天的反馈窗口，超过 3 个月的语料库，所有 Claude 家族代理。观察性，而不是基准测试。 - 178 次检查，跨越 64 个不同的代理会话，在一个可连接的日志中。 - 68% 的检查确认了先前的决定，因此代理继续工作而不是打断人类。 - 约 4.5% 的检查改变了代理的操作。设计上很少见——但在尾部集中了价值：最强有力的案例是代理的衡量但错误的“删除此索引”的结论受到人类的挑战，重新测试，逆转，并永久记录，以便未来没有代理重新得出它。 - 12 个审计的高影响力案例全部符合原始语料库；没有一个被驳斥。 - 成本：每次检查约 1-3 KB 的返回上下文，4-6 KB 的会话简介，0.15-0.36 秒的热检查延迟。 已知的故障模式，来自同一评估：自我报告从未说“否”（将每个百分比视为上限）；年轻的语料库返回约 10 次检查中的 1 次（这是播种，而不是失败）；而批处理结束会话检查大多检索代理自己的新鲜轨迹。在判断时刻检查，而不是在结束典礼中。还有一个诚实的空白：纯 URL 路径在 ChatGPT（网页）、Gemini 和 Claude 上测试有效——但到目前为止，每个仪器化的现场行都来自 Claude Code 中的 Claude 家族代理，因此跨供应商的有效性数字尚不存在。如果您从另一个工具运行它，您正在生成第一个真实数据。 ## 试用 - **托管** - 免费，开放新注册：[soup.net](https://www.soup.net)。该网站为您的任意代理生成一键式简介，从基于网络的聊天机器人到完整的 MCP 客户端。 基于网络的聊天机器人路径是一个一流的接口，而不是一个回退：没有 MCP 的代理通过生成的链接参与 - 食谱检查是一个 URL，代理构造或人类点击。已测试与 ChatGPT（网络）、Gemini 和 Claude 配合使用，包括免费层。 - **自我托管** - MIT 许可，有意为枯燥的堆栈（Postgres 17 + pgvector，Hono，React）。服务器上没有 LLM 运行；代理在已经运行的位置进行推理；服务器仅进行存储和矢量搜索。唯一的外部依赖是 Google 的 Gemini 嵌入 API（[AI Studio 密钥](https://aistudio.google.com/apikey) 有效；确定性存根提供程序覆盖开发和测试，零 API 调用）。快速入门如下。任一方式，您的语料库都导出为单个 JSON 文件。 使用一行将支持 MCP 的代理指向托管服务： ``` claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_KEY" ``` ## 了解更多 - [`docs/design-thinking.md`](docs/design-thinking.md) - 产品愿景，用户原型，食谱检查场景 - [`docs/architecture/overview.md`](docs/architecture/overview.md) - 系统拓扑，三个代理表面，数据模型概览 - [`docs/planning/pivot-search-as-logging.md`](docs/planning/pivot-search-as-logging.md) - 搜索即日志的枢轴（决策历史） - [`docs/engineering-principles.md`](docs/engineering-principles.md) - 13 条原则，指导每项设计选择 - [`docs/backlog.md`](docs/backlog.md) - 当前工作队列；`docs/backlog-completed.md` 中的已完成项目 - [`docs/adr/`](docs/adr/) - 带有日期和状态线的架构决策记录 - [`docs/testing-plan.md`](docs/testing-plan.md)，[`docs/workflows/security.md`](docs/workflows/security.md) - 测试和审计的工作原理 每个文档的顶部分节都说明了其目的以及与附近文档的区别。如果您添加新文档，请执行相同的操作 - 并链接到此部分。 --- ## 快速入门 ```bash cp .env.example .env # 编辑 .env：设置 JWT_SECRET（openssl rand -hex 32），DEV_USERNAME，DEV_PASSWORD。 # GEMINI_API_KEY 在本地环境中是可选的 - 在测试中使用 EMBEDDINGS_PROVIDER=stub。 docker compose up --build -d # postgres + 后端（带有进程内嵌入式工作器）+ Mailpit npm run dev:frontend # Vite SPA on :5273（独立终端） ``` 打开 `http://localhost:5273` - 登录，生成食谱检查链接，然后开始检查食谱。 --- Mailpit Web UI for 本地开发：http://localhost:8625 ## 仓库布局 这是整个仓库的定位地图。带有自己的 README（或顶级文档中说明的用途）的子目录包含详细信息；此地图链接到它们。 ``` apps/backend Hono HTTP 服务器（端口 3101）- 认证，REST API，/check 食谱页面， 远程 MCP 端点（/mcp），以及进程内 pg-boss 嵌入消费者 （src/embedding-worker/）。见 ADR-0020，ADR-0021。 apps/frontend Vite React SPA（端口 5273）- 仪表盘，食谱地图，管理员页面 apps/mcp-server 标准输入/输出 MCP 服务器（作为 soupnet.mcpb 捆绑到 Claude Desktop） packages/db Drizzle 模式 + 迁移 - 单个声明网络模式，单一真实来源 packages/domain 业务逻辑，排名规则，共享代理面对的副本（无 I/O） packages/contracts Zod 模式 + OpenAPI 注册表（大多是先前形状；新路由内联验证） packages/client-sdk REST API 客户端包装器 packages/api-client 自动生成的 React Query 钩子（从合同重新生成） packages/config 共享 tsconfig，ESLint 配置 docs/ 顶级：design-thinking.md，engineering-principles.md，testing-plan.md， backlog.md + backlog-completed.md（跨会话工作队列） docs/adr/ 架构决策记录 - 带日期和状态线 docs/architecture/ 代码的工作原理：概述，搜索算法，数据模型（生成） docs/planning/ 已验证的提案准备好（或几乎准备好）实施 docs/rough-notes/ 带日期的工作笔记，打算腐烂 - 参见其 README 了解合同 和保真度阶梯（rough-notes → 规划 → 采用的文档/ADRs） docs/workflows/ 可重复的流程（安全审计周期等） docs/connectors/ 连接器接口文档（claude.ai 目录提交材料） docs/legal/ 隐私政策 + 服务条款源材料 scripts/ 开发/运维一次性脚本：test-ci-local.mjs（规范的门户），清理， 数据模型文档生成，QA 套件 ``` --- ## MCP 设置 主要路径是**通过 Streamable HTTP 的远程 MCP**（无状态，ADR-0021）。使用 API 密钥作为 Bearer 令牌将您的代理指向后端的 `/mcp` 端点 - 无论您是在本地运行还是针对部署实例。 **1. 生成 API 密钥** - 登录 SPA，打开 **API 密钥**，创建每日或范围限定的密钥，复制原始值。 **2. 添加服务器。** 在 Claude Code 中，这是一行代码： ``` claude mcp add --transport http soupnet http://localhost:3101/mcp --header "Authorization: Bearer YOUR_KEY" ``` 任何 HTTP-MCP 客户端都使用相同的三个事实，无论其配置模式如何： ```jsonc { "mcpServers": { "soupnet": { "type": "http", "url": "http://localhost:3101/mcp", "headers": { "Authorization": "Bearer YOUR_KEY" } } } } ``` 每个客户端配置块（Codex，VS Code，Google Antigravity，Claude Desktop via `mcp-remote` 或 `apps/mcp-server/` 中的 stdio 服务器）都位于 `/docs/mcp-setup` 的指南中 - 由您自己的实例提供，或 [托管](https://mcp.soup.net/docs/mcp-setup) 并预填充您的密钥。 **3. 重启客户端** （或在 Claude Code 中运行 `/mcp`）以获取新的服务器。可用工具：`check_recipe`，`get_briefing`，`list_my_recipe_books`，`update_recipe_book_description`。 工具合同仅为只读 + 追加。没有更新或删除接口，因此混淆的代理（或提示注入的代理）可以添加跟踪，但永远不能破坏或重写记录 - 如果您评估 MCP 服务器的安全性，这一点是值得了解的。 --- ## 开发 **先决条件：** Node 24 LTS，npm ≥ 10，Docker **通过 Docker 启动所有内容：** ```bash docker compose up --build -d # postgres + 后端 + 工作器 npm run dev:frontend # Vite 开发服务器（独立终端） ``` **或在本地使用热重载运行后端：** ```bash docker compose up -d postgres # 仅数据库 npm run build:packages # 构建内部包 source .env && npm run dev:backend # Hono with tsx watch on :3101 npm run dev:frontend # Vite on :5273 ``` **数据库迁移：** ```bash cd packages/db npx drizzle-kit generate # 从模式更改中生成迁移 # 迁移在后端启动时自动应用 ``` --- ## 测试 ```bash npx vitest run # 所有测试（.env 由 vitest 配置自动加载） npx vitest watch # 监视模式 npm run test:ci # CI 的干净重现（新鲜数据库在 :5534，无 Gemini） ``` 集成测试会命中正在运行的 Docker 后端，因此请保持 `docker compose up -d` 运行。 **集成测试在实时数据库中创建测试数据** （具有 `@test.local` 电子邮件地址的用户，在他们自己的食谱书中）。测试轨迹按食谱书范围限定，不会在您的个人搜索结果中显示。要清理累积的测试数据： ```bash npx tsx scripts/cleanup-test-data.ts # 清理 npx tsx scripts/cleanup-test-data.ts --status # 仅显示计数 ``` 参见 [`docs/testing-plan.md`](docs/testing-plan.md) 了解覆盖率期望和测试类别。 --- ## 公共 vs 托管 这是开源代码库。托管版本的部署细节 - Terraform，操作手册，AWS 拓扑 - 存放在一个单独的私有配套存储库中，因为它们特定于一个操作员的基础设施选择，并且不是特别有用。 **测试属于此存储库的内容：** 自我托管者在自己的基础设施上运行此堆栈是否需要此内容？如果是，这里就有。如果它特定于特定托管部署，则不在此处。 应用程序与部署无关 - 仅限 Postgres 17 和 `.env.example` 中的环境变量。容器平台无关：本地使用 Docker Compose，生产环境中使用其他任何平台（Kubernetes，ECS，Fly，Hetzner）。 --- ## 关键规则 - 路由处理程序或 React 组件中没有业务逻辑 - 使用服务 - 绝不直接编辑数据库 - 始终使用 Drizzle 迁移 - `import type { ... }` 用于仅限类型的导入；`unknown` 而不是 `any` - 参见 [`docs/engineering-principles.md`](docs/engineering-principles.md) --- ## 这个人 Soup.net 的大部分内容 - 代码，文档，本 README 的部分内容 - 都是由 AI 代理编写的。所有内容都由一位可验证的人类指导，审查和回答：[Andy Forest](https://github.com/AndyForest)，一位拥有 30 年经验的系统架构师和开发者。最近的工作：Scratch 基金会的 AI 平台架构师；在 [Steamlabs](https://steamlabs.ca) 工作了十年，为 85 万年轻学习者提供亲身体验的 AI 教育； [*Make: AI Robots*](https://www.amazon.ca/Make-Robots-Amazing-Artificial-Intelligence/dp/1680457292) 的共同作者（O'Reilly，[译成日语](https://www.amazon.co.jp/-/en/micro-bit%E3%81%A7%E3%81%AF%E3%81%98%E3%82%81%E3%82%8BAI%E5%B7%A5%E4%BD%9C-%E2%80%95%E8%A6%AA%E5%AD%90%E3%81%A7%E4%BD%9C%E3%82%8D%E3%81%86%EF%BC%81AI%E3%81%A7%E5%8B%95%E3%81%8F%E3%83%9E%E3%83%83%E3%83%88%E3%80%81%E3%82%B2%E3%83%BC%E3%83%A0%E3%80%81%E3%81%8A%E3%82%82%E3%81%A1%E3%82%83-Reade-Richard/dp/4814400993)）； [LiteLLM](https://github.com/BerriAI/litellm) 贡献者。 Soup.net 的存在是因为他运行了很多代理，并且希望他的判断在它们之间存活下来。这个 README 中描述的责任模型 - 代理做工作，人类对它负责 - 是存储库本身构建的模型。 --- ## 许可证和商标 此存储库中的代码和文档根据 [MIT 许可证](LICENSE) 授权。 **Soup.net** 名称，徽标，商标和品牌插图资产标识托管服务 [soup.net](https://www.soup.net)，不受 MIT 许可的约束。分叉代码，自己托管，自由构建，但以自己的名称和品牌呈现自己的公共实例。